chore: freeze 3.4.0

.gitignore

@@ -16,6 +16,7 @@ pgo-data.profdata
 **/proof-with-io.bin
 **/program.bin
 **/stdin.bin
+**/node_modules
 
 # Benchmark
 benchmark.csv
@@ -37,4 +38,4 @@ crates/prover/vk
 
 # Example fibonacci groth16 / plonk proofs
 examples/fibonacci/fibonacci-groth16.bin
-examples/fibonacci/fibonacci-plonk.bin
+examples/fibonacci/fibonacci-plonk.bin

book/docusaurus.config.ts

@@ -66,6 +66,10 @@ const config: Config = {
           label: 'GitHub',
           position: 'right',
         },
+        {
+          type: "docsVersionDropdown",
+          position: "right",
+        },
       ],
     },
     footer: {

book/versioned_docs/version-3.4.0/developers/building-circuit-artifacts.md

@@ -0,0 +1,8 @@
+# Building Circuit Artifacts
+
+To build the production Groth16 and PLONK Bn254 artifacts from scratch, you can use the `Makefile` inside the `prover` directory.
+
+```shell,noplayground
+cd prover
+RUST_LOG=info make build-circuits
+```

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

@@ -0,0 +1,147 @@
+# 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 v0.1.1 cannot be built because it requires rustc 1.76 or newer, while the currently active rustc version is 1.75.0-nightly`
+```
+
+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.81** should work for all crates that have an MSRV of **1.81** or lower.
+
+If the MSRV of your crate is higher than **1.81**, 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 = "2.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"] }
+```
+
+## `sp1-sdk` `rc` Version Semver Errors
+
+When using release candidate (RC) versions of `sp1-sdk` (such as `3.0.0-rc1`), you might face compilation errors if you upgrade to a newer RC version (like `3.0.0-rc4`) and then try to downgrade back to an earlier RC version (such as `3.0.0-rc1`).
+
+This issue arises because some RC releases introduce breaking changes that aren't reflected in their version numbers according to Semantic Versioning (SemVer) rules. To fix this, you need to explicitly downgrade all related crates in your `Cargo.lock` file to match the desired RC version.
+
+To start, verify that the `sp1-sdk` version in your `Cargo.lock` file differs from the version specified in your `Cargo.toml` file:
+
+```shell
+% cargo tree -i sp1-sdk
+sp1-sdk v3.0.0-rc4 (/Users/sp1/crates/sdk)
+├── sp1-cli v3.0.0-rc4 (/Users/sp1/crates/cli)
+├── sp1-eval v3.0.0-rc4 (/Users/sp1/crates/eval)
+└── sp1-perf v3.0.0-rc4 (/Users/sp1/crates/perf)
+```
+
+After confirming the version of `sp1-sdk` in your lockfile, you can downgrade to a specific RC version using the following command. Replace `3.0.0-rc1` with the desired version number:
+
+```shell
+%  cargo update -p sp1-build -p sp1-sdk -p sp1-recursion-derive -p sp1-recursion-gnark-ffi -p sp1-zkvm --precise 3.0.0-rc1
+```
+
+This command will update the `Cargo.lock` file to specify the lower RC version, resolving any version conflicts and allowing you to continue development.

book/versioned_docs/version-3.4.0/developers/rv32im-specification.md

@@ -0,0 +1,8 @@
+# RV32IM Specification
+
+SP1 implements the RISC-V RV32IM instruction set with some implementation details that make it more suitable for proving.
+
+- LW/SW memory access must be word aligned.
+- LH/LHU/SH memory access must be half-word aligned.
+- Memory access is only valid for addresses `0x20, 0x78000000`. Accessing addresses outside of this range will result in undefined behavior. The global heap allocator in `sp1_zkvm` will panic if memory exceeds this range.
+- The ECALL instruction is used for system calls and precompiles. Only valid syscall IDs should be called, and only using the specific convention of loading the ID into register T0 and arguments into registers A0 and A1. If the arguments are addresses, they must be word-aligned. Failure to follow this convention can result in undefined behavior. Correct usages can be found in the `sp1_zkvm` and `sp1_lib` crates.

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

@@ -0,0 +1,27 @@
+# Usage in CI
+
+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
+```

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

@@ -0,0 +1,68 @@
+import Compressed from "../../../static/examples_fibonacci_script_bin_compressed.rs.mdx";
+import Execute from "../../../static/examples_fibonacci_script_bin_execute.rs.mdx";
+
+# Advanced Usage
+
+## 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.)
+
+## Compressed Proofs
+
+With the `ProverClient`, the default `prove` function generates a proof that is succinct, but can have size that scales with the number of cycles of the program. To generate a compressed proof of constant size, you can use the `prove_compressed` function instead. This will use STARK recursion to generate a proof that is constant size (around 7Kb), but will be slower than just calling `prove`, as it will use recursion to combine the core SP1 proof into a single constant-sized proof.
+
+<Compressed />
+
+You can run the above script with `RUST_LOG=info cargo run --bin compressed --release` from `examples/fibonacci/script`.
+
+## 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 = "2.0.0", 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
+```

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

@@ -0,0 +1,19 @@
+import Example from "../../../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.
+
+<div class="warning">
+WARNING: Local proving often is much slower than the prover network and for certain proof types (e.g. Groth16, PLONK) require a significant amount of RAM and will likely not work on a laptop.
+</div>
+
+We recommend using the [prover network](./prover-network.md) to generate proofs. Read more about the [recommended workflow](./recommended-workflow) for developing with SP1.

book/versioned_docs/version-3.4.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.

book/versioned_docs/version-3.4.0/generating-proofs/hardware-acceleration/avx.md

@@ -0,0 +1,30 @@
+# AVX
+
+SP1 supports both AVX256 and AVX512 acceleration on x86 CPUs due to support in [Plonky3](https://github.com/Plonky3/Plonky3).
+Whenever possible, we recommend using AVX512 acceleration as it provides better performance.
+
+## Checking for AVX
+
+To check if your CPU supports AVX, you can run the following command:
+
+`grep avx /proc/cpuinfo`
+
+Look for the flags `avx2` and `avx512`.
+
+## Enabling AVX256
+
+To enable AVX256 acceleration, you can set the `RUSTFLAGS` environment variable to include the following flags:
+
+```bash
+RUSTFLAGS="-C target-cpu=native" cargo run --release
+```
+
+## Enabling AVX512
+
+To enable AVX512 acceleration, you can set the `RUSTFLAGS` environment variable to include the following flags:
+
+```bash
+RUSTFLAGS="-C target-cpu=native -C target-feature=+avx512f" cargo run --release
+```
+
+Note that the `+avx512f` flag is required to enable AVX512 acceleration.

book/versioned_docs/version-3.4.0/generating-proofs/hardware-acceleration/cuda.md

@@ -0,0 +1,26 @@
+# CUDA
+
+<div class="warning">
+WARNING: CUDA proving is still an experimental feature and may be buggy.
+</div>
+
+
+SP1 supports CUDA acceleration, which can provide dramatically better latency and cost performance
+compared to using the CPU prover, even with AVX acceleration.
+
+## Software Requirements
+
+Please make sure you have the following installed before using the CUDA prover:
+
+- [CUDA 12](https://developer.nvidia.com/cuda-12-0-0-download-archive?target_os=Linux&target_arch=x86_64&Distribution=Ubuntu&target_version=22.04&target_type=deb_local)
+- [CUDA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)
+
+## Hardware Requirements
+
+- **CPU**: We recommend having at least 8 CPU cores with 32GB of RAM available to fully utilize the GPU.
+- **GPU**: 24GB or more for core/compressed proofs, 40GB or more for shrink/wrap proofs
+
+## Usage
+
+To use the CUDA prover, you can compile the `sp1-sdk` crate with the `cuda` feature enabled. You
+can use the normal methods on the `ProverClient` to generate proofs.