chore: book deploy workflow (#1933)

Author: jtguibas

.github/workflows/book.yml

@@ -5,9 +5,9 @@ name: book
 
 on:
   push:
-    branches: [dev]
+    branches: [main]
   pull_request:
-    branches: [dev]
+    branches: [main]
     paths:
       - "book/**"
   merge_group:
@@ -17,51 +17,51 @@ defaults:
     working-directory: book
 
 jobs:
-  # build:
-  #   name: Build Docusaurus
-  #   runs-on: ubuntu-latest
-  #   steps:
-  #     - uses: actions/checkout@v4
-  #       with:
-  #         fetch-depth: 0
-  #     - uses: actions/setup-node@v4
-  #       with:
-  #         node-version: 18
-  #         cache: npm
-  #         cache-dependency-path: book/package-lock.json
+  build:
+    name: Build Docusaurus
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: npm
+          cache-dependency-path: book/package-lock.json
 
-  #     - name: Install dependencies
-  #       run: npm ci
+      - name: Install dependencies
+        run: npm ci
 
-  #     - name: Create New Code Refrences
-  #       run: chmod +x gen-code-refs.sh && ./gen-code-refs.sh 
+      - name: Create New Code Refrences
+        run: chmod +x gen-code-refs.sh && ./gen-code-refs.sh 
 
-  #     - name: Build website
-  #       run: npm run build
+      - name: Build website
+        run: npm run build
 
-  #     - name: Upload Build Artifact
-  #       uses: actions/upload-pages-artifact@v3
-  #       with:
-  #         path: book/build
+      - name: Upload Build Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: book/build
 
-  # deploy:
-  #   # Only deploy if a push to main
-  #   if: github.ref_name == 'dev' && github.event_name == 'push'
-  #   runs-on: ubuntu-latest
-  #   needs: [build]
+  deploy:
+    # Only deploy if a push to main
+    if: github.ref_name == 'dev' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+    needs: [build]
 
-  #   # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
-  #   permissions:
-  #     pages: write
-  #     id-token: write
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write
+      id-token: write
 
-  #   environment:
-  #     name: github-pages
-  #     url: ${{ steps.deployment.outputs.page_url }}
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
 
-  #   timeout-minutes: 60
+    timeout-minutes: 60
 
-  #   steps:
-  #     - name: Deploy to GitHub Pages
-  #       id: deployment
-  #       uses: actions/deploy-pages@v4
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

book/versioned_docs/version-4.0.0/developers/common-issues.md

@@ -0,0 +1,123 @@
+# Common Issues
+
+## Rust Version Errors
+
+If you are using a library that has an MSRV specified, you may encounter an error like this when building your program.
+
+```txt
+package `alloy cannot be built because it requires rustc 1.83 or newer, while the currently active rustc version is 1.81.0`
+```
+
+This is due to the fact that your current Succinct Rust toolchain has been built with a lower version than the MSRV of the crates you are using.
+
+You can check the version of your local Succinct Rust toolchain by running `cargo +succinct --version`. The latest release of the Succinct Rust toolchain is **1.81**. You can update to the latest version by running [`sp1up`](../getting-started/install.md).
+
+```shell
+% sp1up
+% cargo +succinct --version
+cargo 1.81.0-dev (2dbb1af80 2024-08-20)
+```
+
+A Succinct Rust toolchain with version **1.82** should work for all crates that have an MSRV of **1.82** or lower.
+
+If the MSRV of your crate is higher than **1.82**, try the following:
+
+- If using `cargo prove build` directly, pass the `--ignore-rust-version` flag:
+
+  ```bash
+  cargo prove build --ignore-rust-version
+  ```
+
+- If using `build_program` in an `build.rs` file with the `sp1-build` crate, set `ignore_rust_version` to true inside the `BuildArgs` struct and use
+  `build_program_with_args`:
+
+  ```rust
+  let args = BuildArgs {
+      ignore_rust_version: true,
+      ..Default::default()
+  };
+  build_program_with_args("path/to/program", args);
+  ```
+
+## `alloy_sol_types` Errors
+
+If you are using a library that depends on `alloy_sol_types`, and encounter an error like this:
+
+```txt
+perhaps two different versions of crate `alloy_sol_types` are being used?
+```
+
+This is likely due to two different versions of `alloy_sol_types` being used. To fix this, you can set `default-features` to `false` for the `sp1-sdk` dependency in your `Cargo.toml`.
+
+```toml
+[dependencies]
+sp1-sdk = { version = "4.0.0", default-features = false }
+```
+
+This will configure out the `network` feature which will remove the dependency on `alloy_sol_types` and configure out the `NetworkProver`.
+
+## Stack Overflow Errors + Bus Errors
+
+If you encounter any of the following errors in a script using `sp1-sdk`:
+
+```shell
+# Stack Overflow Error
+thread 'main' has overflowed its stack
+fatal runtime error: stack overflow
+
+# Bus Error
+zsh: bus error
+
+# Segmentation Fault
+Segmentation fault (core dumped)
+```
+
+Run your script with the `--release` flag. SP1 currently only supports release builds. This is because
+the `sp1-core` library and `sp1-recursion` require being compiled with the `release` profile.
+
+## C Binding Errors
+
+If you are building a program that uses C bindings or has dependencies that use C bindings, you may encounter the following errors:
+
+```txt
+cc did not execute successfully
+```
+
+```txt
+Failed to find tool. Is `riscv32-unknown-elf-gcc` installed?
+```
+
+To resolve this, re-install sp1 with the `--c-toolchain` flag:
+
+```bash
+sp1up --c-toolchain
+```
+
+This will install the C++ toolchain for RISC-V and set the `CC_riscv32im_succinct_zkvm_elf` environment
+variable to the path of the installed `riscv32-unknown-elf-gcc` binary. You can also use your own
+C++ toolchain be setting this variable manually:
+
+```bash
+export CC_riscv32im_succinct_zkvm_elf=/path/to/toolchain
+```
+
+## Compilation Errors with [`sp1-lib::syscall_verify_sp1_proof`](https://docs.rs/sp1-lib/latest/sp1_lib/fn.syscall_verify_sp1_proof.html)
+
+If you are using the [`sp1-lib::syscall_verify_sp1_proof`](https://docs.rs/sp1-lib/latest/sp1_lib/fn.syscall_verify_sp1_proof.html) function, you may encounter compilation errors when building your program.
+
+```bash
+  [sp1]    = note: rust-lld: error: undefined symbol: syscall_verify_sp1_proof
+  [sp1]            >>> referenced by sp1_lib.b593533d149f0f6e-cgu.0
+  [sp1]            >>>               sp1_lib-8f5deb4c47d01871.sp1_lib.b593533d149f0f6e-cgu.0.rcgu.o:(sp1_lib::verify::verify_sp1_proof::h5c1bb38f11b3fe71) in ...
+  [sp1]
+  [sp1]
+  [sp1]  error: could not compile `package-name` (bin "package-name") due to 1 previous error
+```
+
+To resolve this, ensure that you're importing both `sp1-lib` and `sp1-zkvm` with the verify feature enabled.
+
+```toml
+[dependencies]
+sp1-lib = { version = "<VERSION>", features = ["verify"] }
+sp1-zkvm = { version = "<VERSION>", features = ["verify"] }
+```

book/versioned_docs/version-4.0.0/developers/usage-in-ci.md

@@ -0,0 +1,71 @@
+# Usage in CI
+
+## Getting started
+
+You may want to use SP1 in your [Github Actions](https://docs.github.com/en/actions) CI workflow.
+
+You first need to have Rust installed, and you can use
+[actions-rs/toolchain](https://github.com/actions-rs/toolchain) for this:
+
+```yaml
+- name: Install Rust Toolchain
+  uses: actions-rs/toolchain@v1
+  with:
+    toolchain: 1.81.0
+    profile: default
+    override: true
+    default: true
+    components: llvm-tools, rustc-dev
+```
+
+And then you can install the SP1 toolchain:
+
+```yaml
+- name: Install SP1 toolchain
+  run: |
+    curl -L https://sp1.succinct.xyz | bash
+    ~/.sp1/bin/sp1up 
+    ~/.sp1/bin/cargo-prove prove --version
+```
+
+You might experience rate limiting from sp1up. Using a Github
+[Personal Access Token (PAT)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) will help.
+
+Try setting a github actions secret to your PAT, and then passing it into the `sp1up` command:
+
+```yaml
+- name: Install SP1 toolchain
+  run: |
+    curl -L https://sp1.succinct.xyz | bash
+    ~/.sp1/bin/sp1up --token "${{ secrets.GH_PAT }}"
+    ~/.sp1/bin/cargo-prove prove --version
+```
+
+## Speeding up your CI workflow
+
+### Caching
+
+To speed up your CI workflow, you can cache the Rust toolchain and Succinct toolchain. See this example
+from SP1's CI workflow, which caches the `~/.cargo` and parts of the `~/.sp1` directories.
+
+```yaml
+- name: rust-cache
+  uses: actions/cache@v3
+  with:
+    path: |
+      ~/.cargo/bin/
+      ~/.cargo/registry/index/
+      ~/.cargo/registry/cache/
+      ~/.cargo/git/db/
+      target/
+      ~/.rustup/
+      ~/.sp1/circuits/plonk/ # Cache these if you're generating plonk proofs with docker in CI.
+      ~/.sp1/circuits/groth16/ # Cache these if you're generating groth16 proofs with docker in CI.
+    key: rust-1.81.0-${{ hashFiles('**/Cargo.toml') }}
+        restore-keys: rust-1.81.0-
+```
+
+### `runs-on` for bigger instances
+
+Since SP1 is a fairly large repository, it might be useful to use [`runs-on`](https://github.com/runs-on/runs-on)
+to specify a larger instance type.

book/versioned_docs/version-4.0.0/generating-proofs/advanced.mdx

@@ -0,0 +1,74 @@
+import Compressed from "@site/static/examples_fibonacci_script_bin_compressed.rs.mdx";
+import Execute from "@site/static/examples_fibonacci_script_bin_execute.rs.mdx";
+
+# Advanced
+
+## Execution Only
+
+We recommend that during the development of large programs (> 1 million cycles) you do not generate proofs each time.
+Instead, you should have your script only execute the program with the RISC-V runtime and read `public_values`. Here is an example:
+
+<Execute />
+
+If the execution of your program succeeds, then proof generation should succeed as well! (Unless there is a bug in our zkVM implementation.)
+
+## Logging and Tracing Information
+
+You can use `utils::setup_logger()` to enable logging information respectively. You should only use one or the other of these functions.
+
+**Logging:**
+
+```rust
+utils::setup_logger();
+```
+
+You must run your command with:
+
+```bash
+RUST_LOG=info cargo run --release
+```
+
+## CPU Acceleration
+
+To enable CPU acceleration, you can use the `RUSTFLAGS` environment variable to enable the `target-cpu=native` flag when running your script. This will enable the compiler to generate code that is optimized for your CPU.
+
+```bash
+RUSTFLAGS='-C target-cpu=native' cargo run --release
+```
+
+Currently there is support for AVX512 and NEON SIMD instructions. For NEON, you must also enable the `sp1-sdk` feature `neon` in your script crate's `Cargo.toml` file.
+
+```toml
+sp1-sdk = { version = "...", features = ["neon"] }
+```
+
+## Performance
+
+For maximal performance, you should run proof generation with the following command and vary your `shard_size` depending on your program's number of cycles.
+
+```rust
+SHARD_SIZE=4194304 RUST_LOG=info RUSTFLAGS='-C target-cpu=native' cargo run --release
+```
+
+## Memory Usage
+
+To reduce memory usage, set the `SHARD_BATCH_SIZE` environment variable depending on how much RAM
+your machine has. A higher number will use more memory, but will be faster.
+
+```rust
+SHARD_BATCH_SIZE=1 SHARD_SIZE=2097152 RUST_LOG=info RUSTFLAGS='-C target-cpu=native' cargo run --release
+```
+
+## Advanced Allocator
+
+SP1 programs use a simple bump allocator by default, which just increments a pointer to allocate memory. Although this works for many cases, some programs can still run out of memory in the SP1 zkVM. To address this, you can enable the `embedded` allocator feature on the SP1 zkVM.
+
+The embedded allocator uses the [`embedded-alloc` crate](https://crates.io/crates/embedded-alloc) and offers more flexible memory management, albeit with extra cycle overhead.
+
+To enable it, add the following to your `sp1-zkvm` dependency in `Cargo.toml`:
+
+```toml
+sp1-zkvm = { version = "...", features = ["embedded"] }
+```
+
+Once enabled, the embedded allocator replaces the default bump allocator.

book/versioned_docs/version-4.0.0/generating-proofs/basics.mdx

@@ -0,0 +1,13 @@
+import Example from "@site/static/examples_fibonacci_script_src_main.rs.mdx";
+
+# Basics
+
+All the methods you'll need for generating proofs are included in the `sp1_sdk` crate. Most importantly, you'll need to use the `ProverClient` to setup a proving key and verifying key for your program and then use the `execute`, `prove` and `verify` methods to execute your program, and generate and verify proofs.
+
+To make this more concrete, let's walk through a simple example of generating a proof for a Fibonacci program inside the zkVM.
+
+## Example: Fibonacci
+
+<Example />
+
+You can run the above script in the `script` directory with `RUST_LOG=info cargo run --release`. Note that running the above script will generate a proof locally.

book/versioned_docs/version-4.0.0/generating-proofs/hardware-acceleration.md

@@ -0,0 +1,7 @@
+# Hardware Acceleration
+
+SP1 supports hardware acceleration on the following platforms:
+- [AVX256/AVX512](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions) on x86 CPUs
+- [CUDA](https://en.wikipedia.org/wiki/CUDA) on Nvidia GPUs
+
+To enable hardware acceleration, please refer to the platform specific instructions available in this section.