From cb9861a4c4a10fc9f12e97ed69b60bacc0b4c390 Mon Sep 17 00:00:00 2001 From: nhtyy Date: Tue, 3 Dec 2024 16:49:21 -0800 Subject: [PATCH] chore: freeze 3.4.0 --- .gitignore | 3 +- book/docusaurus.config.ts | 4 + .../developers/building-circuit-artifacts.md | 8 + .../version-3.4.0/developers/common-issues.md | 147 +++++++++++ .../developers/rv32im-specification.md | 8 + .../version-3.4.0/developers/usage-in-ci.md | 27 ++ .../generating-proofs/advanced.mdx | 68 +++++ .../generating-proofs/basics.mdx | 19 ++ .../hardware-acceleration.md | 7 + .../hardware-acceleration/avx.md | 30 +++ .../hardware-acceleration/cuda.md | 26 ++ .../generating-proofs/proof-types.md | 49 ++++ .../generating-proofs/prover-network.md | 9 + .../prover-network/explorer.png | Bin 0 -> 167094 bytes .../prover-network/key-setup.md | 40 +++ .../generating-proofs/prover-network/key.png | Bin 0 -> 10085 bytes .../generating-proofs/prover-network/usage.md | 83 +++++++ .../prover-network/versions.md | 30 +++ .../recommended-workflow.mdx | 57 +++++ .../version-3.4.0/generating-proofs/setup.md | 38 +++ .../generating-proofs/sp1-sdk-faq.md | 15 ++ .../getting-started/hardware-requirements.md | 41 +++ .../version-3.4.0/getting-started/install.md | 115 +++++++++ .../getting-started/project-template.md | 5 + .../getting-started/quickstart.md | 124 ++++++++++ .../version-3.4.0/introduction.md | 33 +++ .../contract-addresses.md | 80 ++++++ .../onchain-verification/getting-started.mdx | 34 +++ .../onchain-verification/solidity-sdk.md | 122 +++++++++ book/versioned_docs/version-3.4.0/sp1.png | Bin 0 -> 66629 bytes .../version-3.4.0/theme/head.hbs | 6 + .../verification/off-chain-verification.md | 48 ++++ .../onchain/contract-addresses.md | 101 ++++++++ .../verification/onchain/getting-started.mdx | 33 +++ .../verification/onchain/solidity-sdk.md | 122 +++++++++ .../version-3.4.0/what-is-a-zkvm.md | 35 +++ .../version-3.4.0/why-use-sp1.md | 46 ++++ .../version-3.4.0/writing-programs/basics.mdx | 15 ++ .../writing-programs/compiling.mdx | 100 ++++++++ .../writing-programs/cycle-tracking.mdx | 124 ++++++++++ .../writing-programs/inputs-and-outputs.mdx | 67 +++++ .../writing-programs/patched-crates.md | 234 ++++++++++++++++++ .../writing-programs/precompiles.mdx | 24 ++ .../writing-programs/proof-aggregation.md | 58 +++++ .../version-3.4.0/writing-programs/setup.md | 50 ++++ .../version-3.4.0-sidebars.json | 98 ++++++++ book/versions.json | 3 + 47 files changed, 2385 insertions(+), 1 deletion(-) create mode 100644 book/versioned_docs/version-3.4.0/developers/building-circuit-artifacts.md create mode 100644 book/versioned_docs/version-3.4.0/developers/common-issues.md create mode 100644 book/versioned_docs/version-3.4.0/developers/rv32im-specification.md create mode 100644 book/versioned_docs/version-3.4.0/developers/usage-in-ci.md create mode 100644 book/versioned_docs/version-3.4.0/generating-proofs/advanced.mdx create mode 100644 book/versioned_docs/version-3.4.0/generating-proofs/basics.mdx create mode 100644 book/versioned_docs/version-3.4.0/generating-proofs/hardware-acceleration.md create mode 100644 book/versioned_docs/version-3.4.0/generating-proofs/hardware-acceleration/avx.md create mode 100644 book/versioned_docs/version-3.4.0/generating-proofs/hardware-acceleration/cuda.md create mode 100644 book/versioned_docs/version-3.4.0/generating-proofs/proof-types.md create mode 100644 book/versioned_docs/version-3.4.0/generating-proofs/prover-network.md create mode 100644 book/versioned_docs/version-3.4.0/generating-proofs/prover-network/explorer.png create mode 100644 book/versioned_docs/version-3.4.0/generating-proofs/prover-network/key-setup.md create mode 100644 book/versioned_docs/version-3.4.0/generating-proofs/prover-network/key.png create mode 100644 book/versioned_docs/version-3.4.0/generating-proofs/prover-network/usage.md create mode 100644 book/versioned_docs/version-3.4.0/generating-proofs/prover-network/versions.md create mode 100644 book/versioned_docs/version-3.4.0/generating-proofs/recommended-workflow.mdx create mode 100644 book/versioned_docs/version-3.4.0/generating-proofs/setup.md create mode 100644 book/versioned_docs/version-3.4.0/generating-proofs/sp1-sdk-faq.md create mode 100644 book/versioned_docs/version-3.4.0/getting-started/hardware-requirements.md create mode 100644 book/versioned_docs/version-3.4.0/getting-started/install.md create mode 100644 book/versioned_docs/version-3.4.0/getting-started/project-template.md create mode 100644 book/versioned_docs/version-3.4.0/getting-started/quickstart.md create mode 100644 book/versioned_docs/version-3.4.0/introduction.md create mode 100644 book/versioned_docs/version-3.4.0/onchain-verification/contract-addresses.md create mode 100644 book/versioned_docs/version-3.4.0/onchain-verification/getting-started.mdx create mode 100644 book/versioned_docs/version-3.4.0/onchain-verification/solidity-sdk.md create mode 100644 book/versioned_docs/version-3.4.0/sp1.png create mode 100644 book/versioned_docs/version-3.4.0/theme/head.hbs create mode 100644 book/versioned_docs/version-3.4.0/verification/off-chain-verification.md create mode 100644 book/versioned_docs/version-3.4.0/verification/onchain/contract-addresses.md create mode 100644 book/versioned_docs/version-3.4.0/verification/onchain/getting-started.mdx create mode 100644 book/versioned_docs/version-3.4.0/verification/onchain/solidity-sdk.md create mode 100644 book/versioned_docs/version-3.4.0/what-is-a-zkvm.md create mode 100644 book/versioned_docs/version-3.4.0/why-use-sp1.md create mode 100644 book/versioned_docs/version-3.4.0/writing-programs/basics.mdx create mode 100644 book/versioned_docs/version-3.4.0/writing-programs/compiling.mdx create mode 100644 book/versioned_docs/version-3.4.0/writing-programs/cycle-tracking.mdx create mode 100644 book/versioned_docs/version-3.4.0/writing-programs/inputs-and-outputs.mdx create mode 100644 book/versioned_docs/version-3.4.0/writing-programs/patched-crates.md create mode 100644 book/versioned_docs/version-3.4.0/writing-programs/precompiles.mdx create mode 100644 book/versioned_docs/version-3.4.0/writing-programs/proof-aggregation.md create mode 100644 book/versioned_docs/version-3.4.0/writing-programs/setup.md create mode 100644 book/versioned_sidebars/version-3.4.0-sidebars.json create mode 100644 book/versions.json diff --git a/.gitignore b/.gitignore index 8252583295..ef9ee95d3b 100644 --- a/.gitignore +++ b/.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 \ No newline at end of file +examples/fibonacci/fibonacci-plonk.bin diff --git a/book/docusaurus.config.ts b/book/docusaurus.config.ts index df730e12ca..138a7891df 100644 --- a/book/docusaurus.config.ts +++ b/book/docusaurus.config.ts @@ -66,6 +66,10 @@ const config: Config = { label: 'GitHub', position: 'right', }, + { + type: "docsVersionDropdown", + position: "right", + }, ], }, footer: { diff --git a/book/versioned_docs/version-3.4.0/developers/building-circuit-artifacts.md b/book/versioned_docs/version-3.4.0/developers/building-circuit-artifacts.md new file mode 100644 index 0000000000..9e936d3ff3 --- /dev/null +++ b/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 +``` diff --git a/book/versioned_docs/version-3.4.0/developers/common-issues.md b/book/versioned_docs/version-3.4.0/developers/common-issues.md new file mode 100644 index 0000000000..5d0a50e808 --- /dev/null +++ b/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 = "", features = ["verify"] } +sp1-zkvm = { 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. diff --git a/book/versioned_docs/version-3.4.0/developers/rv32im-specification.md b/book/versioned_docs/version-3.4.0/developers/rv32im-specification.md new file mode 100644 index 0000000000..84e8aa7584 --- /dev/null +++ b/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. diff --git a/book/versioned_docs/version-3.4.0/developers/usage-in-ci.md b/book/versioned_docs/version-3.4.0/developers/usage-in-ci.md new file mode 100644 index 0000000000..33da5e45f9 --- /dev/null +++ b/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 +``` diff --git a/book/versioned_docs/version-3.4.0/generating-proofs/advanced.mdx b/book/versioned_docs/version-3.4.0/generating-proofs/advanced.mdx new file mode 100644 index 0000000000..8cdd0b3e72 --- /dev/null +++ b/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: + + + +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. + + + +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 +``` diff --git a/book/versioned_docs/version-3.4.0/generating-proofs/basics.mdx b/book/versioned_docs/version-3.4.0/generating-proofs/basics.mdx new file mode 100644 index 0000000000..c33c525691 --- /dev/null +++ b/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 + + + +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. + +
+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. +
+ +We recommend using the [prover network](./prover-network.md) to generate proofs. Read more about the [recommended workflow](./recommended-workflow) for developing with SP1. diff --git a/book/versioned_docs/version-3.4.0/generating-proofs/hardware-acceleration.md b/book/versioned_docs/version-3.4.0/generating-proofs/hardware-acceleration.md new file mode 100644 index 0000000000..766c9db4ed --- /dev/null +++ b/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. \ No newline at end of file diff --git a/book/versioned_docs/version-3.4.0/generating-proofs/hardware-acceleration/avx.md b/book/versioned_docs/version-3.4.0/generating-proofs/hardware-acceleration/avx.md new file mode 100644 index 0000000000..e9fe8007bf --- /dev/null +++ b/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. \ No newline at end of file diff --git a/book/versioned_docs/version-3.4.0/generating-proofs/hardware-acceleration/cuda.md b/book/versioned_docs/version-3.4.0/generating-proofs/hardware-acceleration/cuda.md new file mode 100644 index 0000000000..e27d0ce9ac --- /dev/null +++ b/book/versioned_docs/version-3.4.0/generating-proofs/hardware-acceleration/cuda.md @@ -0,0 +1,26 @@ +# CUDA + +
+WARNING: CUDA proving is still an experimental feature and may be buggy. +
+ + +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. \ No newline at end of file diff --git a/book/versioned_docs/version-3.4.0/generating-proofs/proof-types.md b/book/versioned_docs/version-3.4.0/generating-proofs/proof-types.md new file mode 100644 index 0000000000..c6d713e754 --- /dev/null +++ b/book/versioned_docs/version-3.4.0/generating-proofs/proof-types.md @@ -0,0 +1,49 @@ +# Proof Types + +There are a few different types of proofs that can be generated by the SP1 zkVM. Each proof type has its own tradeoffs in terms of proof generation time, verification cost, and proof size. + +The `ProverClient` follows a "builder" pattern that allows you to configure the proof type and other options after creating a `ProverClient` and calling `prove` on it. + +For a full list of options, see the following [docs](https://docs.rs/sp1-sdk/1.2.0/sp1_sdk/action/struct.Prove.html). + +## Core (Default) + +The default prover mode generates a list of STARK proofs that in aggregate have size proportional to +the size of the execution. Use this in settings where you don't care about **verification cost / proof size**. + +```rust +let client = ProverClient::new(); +client.prove(&pk, stdin).run().unwrap(); +``` + +## Compressed + +The compressed prover mode generates STARK proofs that have constant size. Use this in settings where you +care about **verification cost / proof size**, but not onchain verification. Compressed proofs are also useful because they can be cheaply recursively verified within SP1 itself (see the [proof aggregation](../writing-programs/proof-aggregation.md) section). + +```rust +let client = ProverClient::new(); +client.prove(&pk, stdin).compressed().run().unwrap(); +``` + +## Groth16 (Recommended) + +The Groth16 prover mode generates a SNARK proof that is ~260 bytes large and can be verified onchain for around ~270k gas. + +The trusted setup for the Groth16 circuit keys uses the [Aztec Ignition ceremony](https://github.com/AztecProtocol/ignition-verification) + entropy contributions from members of the Succinct team. + +```rust +let client = ProverClient::new(); +client.prove(&pk, stdin).groth16().run().unwrap(); +``` + +## PLONK + +The PLONK prover mode generates a SNARK proof that is ~868 bytes large and can also be verified onchain for around ~300k gas. Plonk proofs take about ~1m30s longer to generate over a compressed proof. + +PLONK does not require a trusted setup. + +```rust +let client = ProverClient::new(); +client.prove(&pk, stdin).plonk().run().unwrap(); +``` diff --git a/book/versioned_docs/version-3.4.0/generating-proofs/prover-network.md b/book/versioned_docs/version-3.4.0/generating-proofs/prover-network.md new file mode 100644 index 0000000000..f5b61d2204 --- /dev/null +++ b/book/versioned_docs/version-3.4.0/generating-proofs/prover-network.md @@ -0,0 +1,9 @@ +# Prover Network Beta + +> **See [Supported Versions](./prover-network/versions.md) for the currently supported versions of SP1 on the Prover Network.** + +Succinct [has been building](https://blog.succinct.xyz/succinct-network/) the Succinct Prover Network, a distributed network of provers that can generate proofs of any size quickly and reliably. It's currently in private beta, but you can get access by following the steps below. + +To get started, **[FILL OUT THIS FORM](https://forms.gle/rTUvhstS8PFfv9B3A)** to gain access to the Succinct +Network. Completing this form requires you to complete the [key +setup](./prover-network/key-setup.md) steps below. diff --git a/book/versioned_docs/version-3.4.0/generating-proofs/prover-network/explorer.png b/book/versioned_docs/version-3.4.0/generating-proofs/prover-network/explorer.png new file mode 100644 index 0000000000000000000000000000000000000000..9241510cd8c277134e60ce1a11c46a34f9c0cf37 GIT binary patch literal 167094 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
-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 z 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 z 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 Aa{vGU literal 0 HcmV?d00001 diff --git a/book/versioned_docs/version-3.4.0/generating-proofs/prover-network/key-setup.md b/book/versioned_docs/version-3.4.0/generating-proofs/prover-network/key-setup.md new file mode 100644 index 0000000000..222fba840f --- /dev/null +++ b/book/versioned_docs/version-3.4.0/generating-proofs/prover-network/key-setup.md @@ -0,0 +1,40 @@ +# Prover Network: Key Setup + +The prover network uses Secp256k1 keypairs for authentication, similar to Ethereum wallets. You may generate a new keypair explicitly for use with the prover network, or use an existing keypair. + +> **You do not need to hold any funds in this account, it is used solely for access control.** + +### Generate a Public Key + +Prover network keypair credentials can be generated using the +[cast](https://book.getfoundry.sh/cast/) CLI tool. + +First install [Foundry](https://book.getfoundry.sh/getting-started/installation#using-foundryup): + +```sh +curl -L https://foundry.paradigm.xyz | bash +``` + +Upon running this command, you will be prompted to source your shell profile and run `foundryup`. Afterwards you should have access to the `cast` command. + +Use `cast` to generate a new keypair: + +```sh +cast wallet new +``` + +which will give you an output similar to this: + +![Screenshot from running 'cast wallet new' to generate an SP1_PRIVATE_KEY.](../prover-network/key.png) + +The "Address" what you should submit in the [form](https://forms.gle/rTUvhstS8PFfv9B3A), in the example above this is `0x552f0FC6D736ed965CE07a3D71aA639De15B627b`. The "Private key" should be kept safe and +secure. When interacting with the network, you will set your `SP1_PRIVATE_KEY` environment variable +to this value. + +### Retrieve an Existing Key + +If you already have an existing key you would like to use, you can also use `cast` retrieve your address: + +```sh +cast wallet address --private-key $PRIVATE_KEY +``` diff --git a/book/versioned_docs/version-3.4.0/generating-proofs/prover-network/key.png b/book/versioned_docs/version-3.4.0/generating-proofs/prover-network/key.png new file mode 100644 index 0000000000000000000000000000000000000000..ccbb4b8974830a141d0e20687d2b52f42af3bbf7 GIT binary patch literal 10085 zcmZ{~1zeQN7ch(nf`o*0hjc7RcXuzfh_JA9NOy{qlnY3Mbf=_9D;bV+x!bi9jk z@BRMY`|kdBXP%ikGpFX9GiRPKbyYb`G!irf1O!Y4d1)X50wOQGE{pmI{=a}eKL;<6 zEF@GU5D+S%=-0-`@MkI$d7ugcf)_mk!s{RegiCnS>kR}1R}KV(Eh7X3!6XC(LWi^l z4PkhPof$~MTtx+e8D2+4Kzx9U@DN^m0RJL{S|K3)sv{u4XM%r_VnYy6;3Y2n_cHUr zzaujd|BgiD&3yQ`jv#vvB%vv#pa3s5O`Ock?3^v_T{60!rNPOtw$cK*fK-$PP3&K> z8=Klg%-B6%IoyLF2zv;^tFO#ljHx_c+1fb^dWg{c8X*X;-!}tjsD2G`u@RvGsi;#) z**lq0@v?KUbI^#QQBhF|JDHjb0;OgDfWx0eXe?b^90UOXcXxMocP@5&Ckp_lfPesi z<2m5@b2j)0HfK*e7h?}LJ7?P8ll+}W+RWL+$;!dS%HEFZeqLjUy{n4|4bA;R|9pPq zY35<|?@D&gf5?Ip2)OS7aI$j%{%>F|R_6Z?u=}3hV87`4y`1p@SA+M>8?u$0W*KKc+ zGqJ{zrP{DLkT4$nDv%y%+V05y^N10E{0QDckd#&P?qAT?OuQm~SdsijntbjTbY4yI z)vpZ}|x6yT6uOM#_uY%6xCxr0|yKp}C53(2m#(`~x^lapg zKi573xo&Fdr@Wbm=DqiK%?HyqZ%;q9VtO^U90UX8$r*WleSO(rc^+)U4+*8FLd9VT z|1blC6e)#?H??eWUhw8pV*dwys_l~7lo{ctl~|<)tI>RcQnK%Mjk{~Sb1s@^b)TBQ ziNJnn+Io#YQmLuY-U-!YSFFZ zFKj+CAiKDt*SWn|zKID!g=ioN@OS5$P%2 z`f4JWAaAYg(|qi)|J~Js+2_gLX`71Ox_Pf{g3|k$q37(9Owco=bsm=0T{~wXsH*`c@Lb6K z+uiVqy*|(JxM0pLRp_!|dv-Os(`Z@ES8-5n&Z=PgDC72|pfme5U6x|T)$IB+t0jm!UA^7p`O4b6i8h%YHZ8;6~rmDLH~&Q8?qC*dU>) z6u8{ooJEXTgp#{O3-Y&I&F#Cn&pL*_Rj$o@FSu}bd!|%r;668Y7+~ms;~I(^3K_-R zY@lH^YFJ~?hI6>lDk7fe@3s#?45)!r&)n4uOw5ky2%TOnV$JnUL67j0#}*40ZpTG3 zR4B)oc(h)BeY2XasH|XY#=n{Se)dO^rdi+C&p<48|3ZIQ30Oc>*~}Owu$E*(W@G0w zLg^~T=H{nw?g+7tfQe!WAG{_@)H5g6s{l?AfY-7k*tfuSX;;D@DB2Z|q5ju7bQ%7` zs+2WkntIxbV`pEm{5Yo1ipd&z|6=Kd6R<&&+F~&7YWD+`Z+(gBRjv1jfv=7)>gdhK z25=95EZps>&f7K0u3l)|wV{aqTNa9v70hWj7M&Lc74`*7Z2mJ9#hX^?z zcP6Cg&~&~O!J_mIDt22>%4Hs@?{~4PKVm|7Ht$^l3VGfg{5(oZZ(~qszw}i^pU-aX z#B8_Ntz)yTfQ~1~4206Ig>w_k*f^rd62CgVE2YQb5L*lwJA2Kj^!y*Jp9B%=YV{WUadn`S6Kk8+O;P!RBthzF^E zCPSjT;mTfIbxZ4axJKaD;DG zB!tvz^HLRE2`ANICWYJEk4RZ;{_bFI397C`DB~`SIgPKlrw)gNVj$ggTTA$WUT& z;epk1)W<@%#Y>I8#fTp!)LHU=M(Ns)Hl(8U_VSGd0H!eGH1D~tP|Di87feg>QH_5w z$j~yp_RGB!3_vCc*l@G2(_Q|#JCwZs^Hb~1?k|^=ApSEeDH^py5vbPWO0FQYqLM1nfC=W zp8yX5?c?i1{K#`2B;h{|x@o`GdU1_MBX>l8O;j?V)N&i8 zOmK2lCo0XzvL*vIRL>KPL&pc z_L}O82!93FJgtNH$&#P|N~8E4I(i`()eVP2r;{d~1tSFdw$#)B)VVCtcnC<7FpKlx zEoLy@_K!(L>MM)ivinYe_@#*PW?0f#1I*B(mCt!FfL`|TE807&$9YN0QH# zsPnGE*}hNRA4?_=V@(u^w%I2-*nS$*(N|DrVe7}5e~TmWmM4NtvpzZ?8kaHo{4812 zw}CMuK zpbKX{Zw5pdVi72EmM$)9r#wf}kzpzZ+S-;}>`ecTVls&lB_h5l0h*ub1VDXOX!k<( zb{Ld5JUW}&0tD=H*r!mxdZu(AIF<)_NOOm<9y1*C=ERmCF z@6~wS*@CLKYfZtF4s8#X)UlP6$U7Yl`*C`3S>6N5%}KsBlHic%#j7!Hc`B~m`^AJ8 z)=Xzn_C8V&%SGxJ?O@APV0YF#?v|x+7Df3;xoWt*h|JWws~_6x+K2n{5|3`#N{Oki z7rpLuAv~_Q%t5HzMOPJqb#YvOY{v#hKqe%RQ4;$=f|JVj3yvJwuzaP0%;vj8AWp%> z7X_IE)kDF+++*Mb*uS}5@!>0Y@U*wDS6WJs*WL-}C&A3v;@EzM21oB+&x+F9GO>Ma zo@iznhHb8r6Rk@)mEV=s z;6WB4FVx|p91n!Kl3I}|eS?P=%%gJBw%w4pVrbo16s1jMT-)AeK}LeBHs}pxc%8?8 z3q-E}&HK9q%4fR7mm>z=yS2SN`zZ_W{=~Y2$b_#y(xsHm?}WSoaiDF&Et9T?e((=T zYQm}3U$|4)_ZOi~6rs*DrPndJD8nRC#gR=7DnZANA1YF%@0blocJ$ zxQwcpU2YzloD1 zU+zVJHEmr__YTJo<#{C9neFnPq04(Qm@pQnKoh4)Q+NwQrk-A84CP#%5!Zb%?D!xt z5P!9c)c!|lZ8s6S-xq7K^Tl^En|8Rt!g!p*bnok~H`V-|X6##=uO|nSINR+FcRg!w z@Cr*RM&+0N43@j0iH@dG=!$w6T)X1d*YKc+ZMC;#Sw9puWs$L~^TLX*V7#)VyrGYi z-2G%&&L)1?`^Uaq@|5Zy(;kcZEYJwzMag3wmozH{^l-LFRE?C>XyCDrENJ{#j8py# z>oR~_>9$nqOV$sa?W~Vv54Z1mYud@NO^@cOOuuXNrOwV(wYG%Zu(-u-h5H+634qs6 zxwGo&R>s|R0lEsgYoO~WufFJScM#x(lubYyE_!!;tnipAFXYWmZkR@-uC`^3Pca)) zdIFSu`x2XlP|>0QXXa;t>IV`CpJK#fEHhbqskMqyZ{ZQ-c`x60Ma<`#urHLBXk!zm z*OH2uueKj;2kfQxa{aR9#FxCWd)C4TSPT$%Vz%yQ`-Hdd!h>~u}W7^f-pzyKs)V#`Um3z}N z`PYW!cS5GRctRiJBwurma@pOB7mJq14~EQJ=B#W}J60%qDS~ ztUQ?6CMO=;HDP%k{-{M?ot|DbZL&~kCljK?A(rnm$y4g@!eZQxK%d6ly7zUN_1F`S zzaG+_QK%kF1_wLk#f%*e<@m1E_s~Sh&%;k=U?9OokXZe8d84U~pngj{1jf|*p0+Ws z4F;dj-KP9=e#Ze&py(1}B0Ys?UQ*H0U`u(%`F;1S63!dt8B)QngB|lo_53gyIWX$L z^pnnXC8kmn-^}^R^Sn#liFvI%$nxM>s5b>AXtsaGwmOQD{Dp3*f6=}R-*P!@dKjC? z?w%v{c@`3MPp*6*-aPhCJSfLsC->!))%K@AHe=h5In^ zE9cTei7V?pgxX17Lms^II9sLOlT+;$eB^ho7I47k{EcSyw_*t*QiT;?ocV}V5#{L70We?#-dsMwyF6ESHLTim=56p{IW&kQ$S zsJ04oTY4aTs+D_R3?WvZa)mj9pKd(O+nIG9Vsn4pxwj2ROuv-jX9(ikeezO161n2? zmhVKv<9Ox=m9_?6n|WyoaSe%E97-~bYKsc1A0lxS?@yuZEoFUA@ED5fqUlawDjJh- zOIcsn7-ZcRA#=F3=3a)*PS&?K!u{~?6Mj6WbT1=gz zO&*EqBHnd|Xf0W9H;UY>jagYj$(-absL5xOAt~HevF0pL&^z@c^`9P@5LLMVRGdCi z&l3Bym4f*#Rqi+bOYtdJAT~KySSOADX!@kD%3Sn|T5eu^*u_ZI zV!1rTv`4}B+$vB;RU7fOwunsP)e4?W{Nh>6R=Ey*S}Nr$9|f*87`x5eOVqlHCM9t% zgEFy}>M@$|%gGd3jfk;l{zX0?xJ;A&QmDveJnJOII6U2LD}t(&o9 z@m(p4W*lNjb9hr)wuqt!CsLT~u&M7MF)_$N-OZzoV`wl9uy)c(2%dcf&+`B=(q+%q z%I@McRhc^TJWM5tzm{&Rjm8Cg{|xeUeS3TKT0$d``)1Mv8gE5R5m$;#)li4a|J+yV z1m=4-_sL8VzQ9pancc@Pk8r)jN7Z8|rw8x|m)lTAPCKR*DE1;$c&Bo&qeJ3R&@Nhr zDe>{t@;g18r9IJOEAfeFx86)RfL;|7NUvExu z_h7-OdHnoR`OmHr8^Fb@#S@i|6F!XlO--C^SMU%($?5%V4Cl!QozGd0p`ireR_r25)j`OjzzO;o#Y4?cmNB}b)(En?Nb`}8cLQQ z8uR?bj6kluk6S35)KR^X+X$AjBIq7H<;~p`R<3B=6RZ?H2+YCKJtA`+;3NxbIqw7{ zm`F*6qh!DyGR8-mxGFyMi?0!>bc@X>5(OX9s1$^%dllyJ&3) zy%cAh5zV@W)K!c;Kp~?_ce2Rjy7nTNMB%^&!S&5W`D18z?Tfu3Js!$$0KJIbDT%vb!qw2xZdn} zT?D0BAWFz`LFG}6qu(9y41K5+ud~ab|6@|3cM2hKX>HR1_a=DGU66b4M=uxI*R7s& zlMfbK^YCq3j*7&_oAhkT^$Vf?1Uhza3JQ2kA(?Vjp!4{_NN8UEW?&kO_D2Dwufx+X zskP5b+l_EC?~LRRqoGb6`mbQrd9FkIIfE9Xfcc~^L?bSPo=Tls10?T>4%H!j94B?! ztChEbOtNka+W0X^KCje@KV(%697-vF&{EicIQ;?_6GTJHcrffM(;LZZOYxVUdkLibHC&*&-a{Y#`(iPD+zF) z1i30lcYPZ1D)z8$pb#RaWh?2{(gzOZ<%2>mu}Q^Vy{EW=?^VKY3o9E?ZyqrKXDLq3 ze8cUSZ-Ert2jKK8hjChHG{jJIq~V}4^EUZH=H6%S=@=c2vIxhBz zlvQqlpDzrb`4#H5^*7`Z76y(<2Z7)(h-nAuaH?7L9klJU;7r7oQ zV#|?SD*?SYbTqm0(L)6dZkL`n&VC3U;?-1Igjv<^Tx&Iw|N0cd~H7&L7V-LWPgy z^}rp_kE$72>QxV=*|bU(AUG^S9Z9E)5*;W@a+G%fY@JjhXy_!a5-aruhbK#x)&{A+ zs}HwY>4!cjIXu(kkqjBRjIIbLjR?UKyLQ+VQhd^4?;{ywGT>RQO%^wV^+Yp9)L24z zBQtQtkNO7g6Ipz(9LP&5_U?^TWN2N~C8#75uLRDjI2GeZlzBS%`sGs!fx*>waCT*# z9Nw6dU>{9LjV&tNx^=&OKHI-@8j!TMmfi|aznX=!jVCm$12MK6M02~Kr@@!H?yVh{ z-6wuKjlJ%aOJ*37RupNG}mw=o5>{)=CUbTKZcn zon5?Rp$&&hW62F*$ZATYcd2cuf918x$PG+OtBI~Ey$A``P4LoR&8tL2 z*~*;v>@z2${d11Vl7Z*BvO4vx^=;!ZXMx+4yp+~;%%OM>@Z>d8zUMt(Ww;88qdyVS zcozp|RLq_XJJLPi(rdw8Qx~PH=mzwkP86V-+DyIF$>u4@L;Uf6jNo_}?z&{inw(p|Qs_~&$zYCQb3rZ*bN`Iw zR27>SSp7Y?&XUDM_4AJAQ8m|R0#D=&ZXEp|8Y>foPqtW|*YxzyXc^HRIZdtTvL1Qs z2BGxDW{7%RCsYLs`*JdGsgo6nQ8MhxQTIJT$3)DZ#5h!62e(j{|0qrsLp_P=VN)~Q zJ$g9SRhu}biuph)^C^-~C&Osi<)u?FN}g&Q2Q`L@v?d&jhOCbNJ(A%FM|}+t$6LgrRkx9PlGAD!W6<+cxXkD>Jgbjo zn%;~B%`}EUmqW@drUYi$dfec&$}I*qz2KQk1&AiqHnlGFWx!^&&bqkn7&bOq;aL)# zAggEd07umE!6jAUo~mL>3;l-@w!NnA82a`oZ{WFP;lu0V!-z+c=98E@VQP~!9f3vok z&PYcv_p;R-g4A)_i+Dk|Wi$)DEXFxTO8ytLnTzmrq((UPJ51FZbsDN!k7Xlek*F@3 zOB!?wP!C-Q=K9tknLrV0T}RebzF z5jDPU+<)`$1Vl*T$=J!5OoH(>lLxd>LQZK4hbGt688@ZK5#1Etr6={p7{VR6q4KoM zHi9^&W4@v|xnXYxU~x>E&(LvvsaZvX9%yQ1p=biU3355ib9(eCJe;NqMjt*yk zX?~)r-jE5>asb#I;Hl+e!*90)lkd}iAgi9ClN8ymu_KZv5*6*;e&}jR_C58 zJdaSpCQ$l^`_qzCMwP_C(Ffu1lp^X8uSpk1G9>$9!{8$d#RmjQ%p$kv%XR}vobQO9 zE2_}!SkHgQ=?p}0?qH`urTZaGUzrS|?5NS=+0)3eTsme>%39M)`F($Ve~tYNr^jbT ztB|F$3tXDxG$eXuTiKBr6iF_mGk6%56QphWqfmp*#^`$EYn;WLVmzq(4WcyO3sy1g z@W&co9^-m^K_-+BvMdECXN<)xoE|QB_w(A0BlE-*!4^E0qg=;=F3c+*FGK!eqqq<% z5-YC=K2r6}+ZLnYcTc|v?m#rW^@Il!PT^OC)vD6y;IkP(^Pz^_6eiSiaVq#XXj#_aP$%yUzIatTX37@5W^)IEc}}$; zu^9ioL?J>vF5lf?>NMxaz}^nBt6zLn@Z>_!s@gjKLtO3i|45n&J1P8mXa2WFlckQZ zR|!dcSCI^MPSqAIH2GY_Pse9XGer5mvNbG$&blJ7dLQuu6l^ z{CN?9ipGc_RRZbL=M6nIHOC4u&s0{>DIq6cqLBa!dcXs6EU?wnR|@!f#gI4y!aiUL zByN2Of1pV@A(rJW+Y#C-ml8|7u6ExuFi7AVrJt_$(D=@_^${5ajf)$LBYm z)x0%v->%~PtTNdRQ8SycJQpsn9*V6y_Ke_bmMKk-OsgIRG=G$~3$AdDfgUf7PV>D0 z*5s7Z_7}q}tmwc;wePIht1YWrqCJkTt7vcy4<*H?JZIjNF0CqD9QSCJ)~LN`?F+Q8 z`A7|?|AJ%5C*U~LI=K{aqzxRYgtvN;AbW{m`!;H>` z`0(uIKz!|WvOc3-Hsfj^xG0(~j-IUqt>|SU8Y8nlwJx4y9P8Vf`Zq<_p79o7!}9tI z*tTbRX9$=-_k)c7CH`ttl$n0*H?rpACi@$!ylnPXZ9Uap+U}kA{m0XKE8FWaL(4V> zGE-!uhzzF8l)W!4GGr3;N1Hi)Unm*mJ{`1Nt9D0lLr;c`B6j~YT;Y>8M0p6jS<349Y1^oU~A?U~NuSw=+K6=l3lcoYq1hn&AdNWFDQc_{YAsc50!rgx#ucpNI?+&fR{ zQabkl@hxxD **See [Supported Versions](./versions.md) for the currently supported versions of SP1 on the Prover Network.** + +## Sending a proof request + +To use the prover network to generate a proof, you can run your script that uses `sp1_sdk::ProverClient` as you would normally but with additional environment variables set: + +```rust +// Generate the proof for the given program. +let client = ProverClient::new(); +let (pk, vk) = client.setup(ELF); +let mut proof = client.prove(&pk, stdin).run().unwrap(); +``` + +```sh +SP1_PROVER=network SP1_PRIVATE_KEY=... RUST_LOG=info cargo run --release +``` + +- `SP1_PROVER` should be set to `network` when using the prover network. + +- `SP1_PRIVATE_KEY` should be set to your [private key](../prover-network.md#key-setup). You will need + to be using a [whitelisted](../prover-network.md#get-access) key to use the network. + +When you call any of the prove functions in ProverClient now, it will first simulate your program, then wait for it to be proven through the network and finally return the proof. + +## View the status of your proof + +You can view your proof and other running proofs on the [explorer](https://explorer.succinct.xyz/). The page for your proof will show details such as the stage of your proof and the cycles used. It also shows the program hash which is the keccak256 of the program bytes. + +![Screenshot from explorer.succinct.xyz showing the details of a proof including status, stage, type, program, requester, prover, CPU cycles used, time requested, and time claimed.](./explorer.png) + +## Advanced Usage + +### Skip simulation + +To skip the simulation step and directly submit the program for proof generation, you can set the `SKIP_SIMULATION` environment variable to `true`. This will save some time if you are sure that your program is correct. If your program panics, the proof will fail and ProverClient will panic. + +### Use NetworkProver directly + +By using the `sp1_sdk::NetworkProver` struct directly, you can call async functions directly and have programmatic access to the proof ID and download proofs by ID. + +```rust +impl NetworkProver { + /// Creates a new [NetworkProver] with the private key set in `SP1_PRIVATE_KEY`. + pub fn new() -> Self; + + /// Creates a new [NetworkProver] with the given private key. + pub fn new_from_key(private_key: &str); + + /// Requests a proof from the prover network, returning the proof ID. + pub async fn request_proof( + &self, + elf: &[u8], + stdin: SP1Stdin, + mode: ProofMode, + ) -> Result; + + /// Waits for a proof to be generated and returns the proof. If a timeout is supplied, the + /// function will return an error if the proof is not generated within the timeout. + pub async fn wait_proof( + &self, + proof_id: &str, + timeout: Option, + ) -> Result; + + /// Get the status and the proof if available of a given proof request. The proof is returned + /// only if the status is Fulfilled. + pub async fn get_proof_status( + &self, + proof_id: &str, + ) -> Result<(GetProofStatusResponse, Option)>; + + /// Requests a proof from the prover network and waits for it to be generated. + pub async fn prove( + &self, + elf: &[u8], + stdin: SP1Stdin, + mode: ProofMode, + timeout: Option, + ) -> Result; +} +``` diff --git a/book/versioned_docs/version-3.4.0/generating-proofs/prover-network/versions.md b/book/versioned_docs/version-3.4.0/generating-proofs/prover-network/versions.md new file mode 100644 index 0000000000..31503adb80 --- /dev/null +++ b/book/versioned_docs/version-3.4.0/generating-proofs/prover-network/versions.md @@ -0,0 +1,30 @@ +# Supported Versions + +The prover network currently only supports specific versions of SP1: + +| Version | Description | +| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| v2.X.X | Audited, production ready version. | +| v3.X.X | Pre-release version with enhanced performance, currently being audited. **Recommended for benchmarking or testing, not recommended for production use.** | + +`X` denotes that any minor and patch version is supported (e.g. `v2.1.0`, `v2.1.1`). + +If you submit a proof request to the prover network and you are not using a supported version, you will receive an error message. + +## Changing versions + +You must switch to a supported version before submitting a proof. To do so, replace the `sp1-zkvm` version in your program's `Cargo.toml`: + +```toml +[dependencies] +sp1-zkvm = "2.0.0" +``` + +replace the `sp1-sdk` version in your script's `Cargo.toml`: + +```toml +[dependencies] +sp1-sdk = "2.0.0" +``` + +Re-build your program and script, and then try again. diff --git a/book/versioned_docs/version-3.4.0/generating-proofs/recommended-workflow.mdx b/book/versioned_docs/version-3.4.0/generating-proofs/recommended-workflow.mdx new file mode 100644 index 0000000000..d884e60d68 --- /dev/null +++ b/book/versioned_docs/version-3.4.0/generating-proofs/recommended-workflow.mdx @@ -0,0 +1,57 @@ +import Example from "../../../static/examples_fibonacci_script_bin_execute.rs.mdx"; + +# Recommended Workflow for Developing with SP1 + +We recommend the following workflow for developing with SP1. + +## Step 1: Iterate on your program with execution only + +While iterating on your SP1 program, you should **only execute** the program with the RISC-V runtime. This will allow you to verify the correctness of your program and test the `SP1Stdin` as well as the `SP1PublicValues` that are returned, without having to generate a proof (which can be slow and/or expensive). If the execution of your program succeeds, then proof generation should succeed as well! + + + +Note that printing out the total number of executed cycles and the full execution report provides helpful insight into proof generation latency and cost either for local proving or when using the prover network. + +**Crate Setup:** We recommend that your program crate that defines the `main` function (around which you wrap the `sp1_zkvm::entrypoint!` macro) should be kept minimal. Most of your business logic should be in a separate crate (in the same repo/workspace) that can be tested independently and that is not tied to the SP1 zkVM. This will allow you to unit test your program logic without having to worry about the `zkvm` compilation target. This will also allow you to efficient reuse types between your program crate and your crate that generates proofs. + +## Step 2: Generate proofs + +After you have iterated on your program and finalized that it works correctly, you can generate proofs for your program for final end to end testing or production use. + +### Generating proofs on the prover network (recommended) + +Using Succinct's prover prover network will generally be faster and cheaper than local proving, as it parallelizes proof generation amongst multiple machines and also uses SP1's GPU prover that is not yet available for local proving. Follow the [setup instructions](./prover-network.md) to get started with the prover network. Using the prover network only requires adding 1 environment variable from a regular SP1 proof generation script with the `ProverClient`. + +There are a few things to keep in mind when using the prover network. + +### Prover Network FAQ + +#### Benchmarking latency on the prover network + +The prover network currently parallelizes proof generation across multiple machines. This means the latency of proof generation does not scale linearly with the number of cycles of your program, but rather with the number of cycles of your program divided by the number of currently available machines on the prover network. + +Our prover network currently has limited capacity because it is still in beta. If you have an extremely latency sensitive use-case and you want to figure out the **minimal latency possible** for your program, you should [reach out to us](https://partner.succinct.xyz/) and we can onboard you to our reserved capacity cluster that has a dedicated instances that can significantly reduce latency. + +#### Costs on the prover network + +The cost of proof generation on the prover network scales approximately linearly with the number of cycles of your program (along with the number of `syscalls` that your program makes). For larger workloads with regular proof frequency (like rollups and light clients), we can offer discounted pricing. To figure out how much your program will cost to prove, you can get [in touch with us](https://partner.succinct.xyz/) to discuss pricing options. + +Note that **latency is not the same as cost**, because we parallelize proof generation across multiple machines, so two proofs with the same latency can be using a different number of machines, impacting the cost. + +#### Benchmarking on small vs. large programs + +In SP1, there is a fixed overhead for proving that is independent of your program's cycle count. This means that benchmarking on _small programs_ is not representative of the performance of larger programs. To get an idea of the scale of programs for real-world workloads, you can refer to our [benchmarking blog post](https://blog.succinct.xyz/sp1-production-benchmarks) and also some numbers below: + +- An average Ethereum block can be between 100-500M cycles (including merkle proof verification for storage and execution of transactions) with our `keccak` and `secp256k1` precompiles. +- For a Tendermint light client, the average cycle count can be between 10M and 50M cycles (including our ed25519 precompiles). +- We consider programs with \<2M cycles to be "small" and by default, the fixed overhead of proving will dominate the proof latency. If latency is incredibly important for your use-case, we can specialize the prover network for your program if you reach out to us. + +Note that if you generate Groth16 or PLONK proofs on the prover network, you will encounter a fixed overhead for the STARK -> SNARK wrapping step. We're actively working on reducing this overhead in future releases. + +#### On-Demand vs. Reserved Capacity + +The prover network is currently in beta and has limited capacity. For high volume use-cases, we can offer discounted pricing and a reserved capacity cluster that has a dedicated instances that can significantly reduce latency and have higher throughput and guaranteed SLAs. + +### Generating proofs locally + +If you want to generate proofs locally, you can use the `sp1_sdk` crate to generate proofs locally as outlined in the [Basics](./basics) section. By default, the `ProverClient` will generate proofs locally using your CPU. Check out the hardware requirements for locally proving [here](../getting-started/hardware-requirements.md#local-proving). diff --git a/book/versioned_docs/version-3.4.0/generating-proofs/setup.md b/book/versioned_docs/version-3.4.0/generating-proofs/setup.md new file mode 100644 index 0000000000..6e9b5483c7 --- /dev/null +++ b/book/versioned_docs/version-3.4.0/generating-proofs/setup.md @@ -0,0 +1,38 @@ +# Setup + +In this section, we will teach you how to setup a self-contained crate which can generate proofs of programs that have been compiled with the SP1 toolchain inside the SP1 zkVM, using the `sp1-sdk` crate. + +## CLI (Recommended) + +The recommended way to setup your first program to prove inside the zkVM is using the method described in [Quickstart](../getting-started/quickstart.md) which will create a script folder. + +```bash +cargo prove new +cd script +``` + +## Manual + +You can also manually setup a project. First create a new cargo project: + +```bash +cargo new script +cd script +``` + +#### Cargo Manifest + +Inside this crate, add the `sp1-sdk` crate as a dependency. Your `Cargo.toml` should look like as follows: + +```rust +[workspace] +[package] +version = "0.1.0" +name = "script" +edition = "2021" + +[dependencies] +sp1-sdk = "2.0.0" +``` + +The `sp1-sdk` crate includes the necessary utilities to generate, save, and verify proofs. diff --git a/book/versioned_docs/version-3.4.0/generating-proofs/sp1-sdk-faq.md b/book/versioned_docs/version-3.4.0/generating-proofs/sp1-sdk-faq.md new file mode 100644 index 0000000000..ca2a0a0596 --- /dev/null +++ b/book/versioned_docs/version-3.4.0/generating-proofs/sp1-sdk-faq.md @@ -0,0 +1,15 @@ +# FAQ + +## Logging and Tracing Information + +You can use `sp1_sdk::utils::setup_logger()` to enable logging information respectively. You can set the logging level with the `RUST_LOG` environment variable. + +```rust +sp1_sdk::utils::setup_logger(); +``` + +Example of setting the logging level to `info` (other options are `debug`, `trace`, and `warn`): + +```bash +RUST_LOG=info cargo run --release +``` \ No newline at end of file diff --git a/book/versioned_docs/version-3.4.0/getting-started/hardware-requirements.md b/book/versioned_docs/version-3.4.0/getting-started/hardware-requirements.md new file mode 100644 index 0000000000..828ea96080 --- /dev/null +++ b/book/versioned_docs/version-3.4.0/getting-started/hardware-requirements.md @@ -0,0 +1,41 @@ +# Proof Generation Requirements + +

+We recommend that developers who want to use SP1 for non-trivial programs generate proofs on our prover network. The prover network generates SP1 proofs across multiple machines, reducing latency and also runs SP1 on optimized hardware instances that result in faster + cheaper proof generation times. + +We recommend that for any production benchmarking, you use the prover network to estimate latency and costs of proof generation. + +
+ +## Local Proving + +If you want to generate SP1 proofs locally, this section has an overview of the hardware requirements required. These requires depend on which [types of proofs](../generating-proofs/proof-types.md) you want to generate and can also change over time as the design of the zKVM evolves. + +**The most important requirement is CPU for performance/latency and RAM to prevent running out of memory.** + +| | Mock / Network | Core / Compress | Groth16 and PLONK (EVM) | +| -------------- | ---------------------------- | ---------------------------------- | ----------------------- | +| CPU | 1+, single-core perf matters | 16+, more is better | 16+, more is better | +| Memory | 8GB+, more is better | 16GB+, more if you have more cores | 16GB+, more is better | +| Disk | 10GB+ | 10GB+ | 10GB+ | +| EVM Compatible | ✅ | ❌ | ✅ | + +### CPU + +The execution & trace generation of the zkVM is mostly CPU bound, having a high single-core +performance is recommended to accelerate these steps. The rest of the prover is mostly bound by hashing/field operations +which can be parallelized with multiple cores. + +### Memory + +Our prover requires keeping large matrices (i.e., traces) in memory to generate the proofs. Certain steps of the prover +have a minimum memory requirement, meaning that if you have less than this amount of memory, the process will OOM. + +This effect is most noticeable when using the Groth16 or PLONK provers. + +### Disk + +Disk is required to install the SP1 zkVM toolchain and to install the circuit artifacts, if you +plan to locally build the Groth16 or PLONK provers. + +Furthermore, disk is used to checkpoint the state of the program execution, which is required to generate the proofs. diff --git a/book/versioned_docs/version-3.4.0/getting-started/install.md b/book/versioned_docs/version-3.4.0/getting-started/install.md new file mode 100644 index 0000000000..e58b9a624e --- /dev/null +++ b/book/versioned_docs/version-3.4.0/getting-started/install.md @@ -0,0 +1,115 @@ +# Installation + +SP1 currently runs on Linux and macOS. You can either use prebuilt binaries through sp1up or +build the Succinct [Rust toolchain](https://rust-lang.github.io/rustup/concepts/toolchains.html) and CLI from source. + +## Requirements + +- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) +- [Rust (Nightly)](https://www.rust-lang.org/tools/install) +- [Docker](https://docs.docker.com/get-docker/) + +## Option 1: Prebuilt Binaries (Recommended) + +`sp1up` is the SP1 toolchain installer. Open your terminal and run the following command and follow the instructions: + +```bash +curl -L https://sp1.succinct.xyz | bash +``` + +Then simply follow the instructions on-screen, which will make the `sp1up` command available in your CLI. + +After following the instructions, you can run `sp1up` to install the toolchain and the `cargo prove` CLI: + +```bash +sp1up +``` + +This will install two things: + +1. The `succinct` Rust toolchain which has support for the `riscv32im-succinct-zkvm-elf` compilation target. +2. `cargo prove` CLI tool that provides convenient commands for compiling SP1 programs and other helper functionality. + +You can verify the installation of the CLI by running `cargo prove --version`: + +```bash +cargo prove --version +``` + +You can check the version of the Succinct Rust toolchain by running: + +```bash +RUSTUP_TOOLCHAIN=succinct cargo --version +``` +or equivalently: + +```bash +cargo +succinct --version +``` + +If this works, go to the [next section](./quickstart.md) to compile and prove a simple zkVM program. + +### Troubleshooting + +#### Rate-limiting + +If you experience [rate-limiting](https://docs.github.com/en/rest/using-the-rest-api/getting-started-with-the-rest-api?apiVersion=2022-11-28#rate-limiting) when using the `sp1up` command, you can resolve this by using the `--token` flag and providing your GitHub token. To create a Github token, follow the instructions [here](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic). + + + +#### Unsupported OS Architectures + +Currently our prebuilt binaries are built on Ubuntu 20.04 (22.04 on ARM) and macOS. If your OS uses an older GLIBC version, it's possible these may not work and you will need to [build the toolchain from source](#option-2-building-from-source). + +#### Conflicting `cargo-prove` installations + +If you have installed `cargo-prove` from source, it may conflict with `sp1up`'s `cargo-prove` installation or vice versa. You can remove the `cargo-prove` that was installed from source with the following command: + +```bash +rm ~/.cargo/bin/cargo-prove +``` + +Or, you can remove the `cargo-prove` that was installed through `sp1up`: + +```bash +rm ~/.sp1/bin/cargo-prove +``` + + +## Option 2: Building from Source + +
+Warning: This option will take a long time to build and is only recommended for advanced users. +
+ +Make sure you have installed the [dependencies](https://github.com/rust-lang/rust/blob/master/INSTALL.md#dependencies) needed to build the rust toolchain from source. + +Clone the `sp1` repository and navigate to the root directory. + +```bash +git clone git@github.com:succinctlabs/sp1.git +cd sp1 +cd crates +cd cli +cargo install --locked --path . +cd ~ +cargo prove build-toolchain +``` + +Building the toolchain can take a while, ranging from 30 mins to an hour depending on your machine. If you're on a machine that we have prebuilt binaries for (ARM Mac or x86 or ARM Linux), you can use the following to download a prebuilt version. + +```bash +cargo prove install-toolchain +``` + +To verify the installation of the toolchain, run and make sure you see `succinct`: + +```bash +rustup toolchain list +``` + +You can delete your existing installation of the toolchain with: + +```bash +rustup toolchain remove succinct +``` diff --git a/book/versioned_docs/version-3.4.0/getting-started/project-template.md b/book/versioned_docs/version-3.4.0/getting-started/project-template.md new file mode 100644 index 0000000000..b6cbd8d733 --- /dev/null +++ b/book/versioned_docs/version-3.4.0/getting-started/project-template.md @@ -0,0 +1,5 @@ +# Project Template + +Another option for getting started with SP1 is to use the [SP1 Project Template](https://github.com/succinctlabs/sp1-project-template/tree/main). + +You can use this as a Github template to create a new repository that has a SP1 program, a script to generate proofs, and also a contracts folder that contains a Solidity contract that can verify SP1 proofs on any EVM chain. diff --git a/book/versioned_docs/version-3.4.0/getting-started/quickstart.md b/book/versioned_docs/version-3.4.0/getting-started/quickstart.md new file mode 100644 index 0000000000..0d7f46821e --- /dev/null +++ b/book/versioned_docs/version-3.4.0/getting-started/quickstart.md @@ -0,0 +1,124 @@ +# Quickstart + +In this section, we will show you how to create a simple Fibonacci program using the SP1 zkVM. + +## Create an SP1 Project + +### Option 1: Cargo Prove New CLI (Recommended) + +You can use the `cargo prove` CLI to create a new project using the `cargo prove new <--bare|--evm> ` command. The `--bare` option sets up a basic SP1 project for standalone zkVM programs, while `--evm` adds additional components including Solidity contracts for on-chain proof verification. + +This command will create a new folder in your current directory which includes solidity smart contracts for onchain integration. + +```bash +cargo prove new --evm fibonacci +cd fibonacci +``` + +### Option 2: Project Template (Solidity Contracts for Onchain Verification) + +If you want to use SP1 to generate proofs that will eventually be verified on an EVM chain, you should use the [SP1 project template](https://github.com/succinctlabs/sp1-project-template/tree/main). This Github template is scaffolded with a SP1 program, a script to generate proofs, and also a contracts folder that contains a Solidity contract that can verify SP1 proofs on any EVM chain. + +Either fork the project template repository or clone it: + +```bash +git clone https://github.com/succinctlabs/sp1-project-template.git +``` + +### Project Overview + +Your new project will have the following structure (ignoring the `contracts` folder, if you are using the project template): + +``` +. +├── program +│   ├── Cargo.lock +│   ├── Cargo.toml +│   ├── elf +│   │   └── riscv32im-succinct-zkvm-elf +│   └── src +│   └── main.rs +├── rust-toolchain +└── script + ├── Cargo.lock + ├── Cargo.toml + ├── build.rs + └── src + └── bin + ├── prove.rs + └── vkey.rs + +6 directories, 4 files +``` + +There are 2 directories (each a crate) in the project: +- `program`: the source code that will be proven inside the zkVM. +- `script`: code that contains proof generation and verification code. + +**We recommend you install the [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer) extension.** +Note that if you use `cargo prove new` inside a monorepo, you will need to add the manifest file to `rust-analyzer.linkedProjects` to get full IDE support. + +## Build + +Before we can run the program inside the zkVM, it must be compiled to a RISC-V executable using the `succinct` Rust toolchain. This is called an [ELF (Executable and Linkable Format)](https://en.wikipedia.org/wiki/Executable_and_Linkable_Format). To compile the program, you can run the following command: + +``` +cd program && cargo prove build +``` + +which will output the compiled ELF to the file `program/elf/riscv32im-succinct-zkvm-elf`. + +Note: the `build.rs` file in the `script` directory will use run the above command automatically to build the ELF, meaning you don't have to manually run `cargo prove build` every time you make a change to the program! + +## Execute + +To test your program, you can first execute your program without generating a proof. In general this is helpful for iterating on your program and verifying that it is correct. + +```bash +cd ../script +RUST_LOG=info cargo run --release -- --execute +``` + +## Prove + +When you are ready to generate a proof, you should run the script with the `--prove` flag that will generate a proof. + +```bash +cd ../script +RUST_LOG=info cargo run --release -- --prove +``` + +The output should show something like this: +``` +n: 20 +2024-07-23T17:07:07.874856Z INFO prove_core:collect_checkpoints: clk = 0 pc = 0x2017e8 +2024-07-23T17:07:07.876264Z INFO prove_core:collect_checkpoints: close time.busy=2.00ms time.idle=1.50µs +2024-07-23T17:07:07.913304Z INFO prove_core:shard: close time.busy=32.2ms time.idle=791ns +2024-07-23T17:07:10.724280Z INFO prove_core:commit: close time.busy=2.81s time.idle=1.25µs +2024-07-23T17:07:10.725923Z INFO prove_core:prove_checkpoint: clk = 0 pc = 0x2017e8 num=0 +2024-07-23T17:07:10.729130Z INFO prove_core:prove_checkpoint: close time.busy=3.68ms time.idle=1.17µs num=0 +2024-07-23T17:07:14.648146Z INFO prove_core: execution report (totals): total_cycles=9329, total_syscall_cycles=20 +2024-07-23T17:07:14.648180Z INFO prove_core: execution report (opcode counts): +2024-07-23T17:07:14.648197Z INFO prove_core: 1948 add +... +2024-07-23T17:07:14.648277Z INFO prove_core: execution report (syscall counts): +2024-07-23T17:07:14.648408Z INFO prove_core: 8 commit +... +2024-07-23T17:07:14.648858Z INFO prove_core: summary: cycles=9329, e2e=9.193968459, khz=1014.69, proofSize=1419780 +2024-07-23T17:07:14.653193Z INFO prove_core: close time.busy=9.20s time.idle=12.2µs +Successfully generated proof! +fib(n): 10946 +``` + +The program by default is quite small, so proof generation will only take a few seconds locally. After it generates, the proof will be verified for correctness. + +**Note:** When benchmarking proof generation times locally, it is important to note that there is a fixed overhead for proving, which means that the proof generation time for programs with a small number of cycles is not representative of the performance of larger programs (which often have better performance characteristics as the overhead is amortized across many cycles). + +## Recommended Workflow + +Please see the [Recommended Workflow](../generating-proofs/recommended-workflow) section for more details on how to develop your SP1 program and generate proofs. + +We *strongly recommend* that developers who want to use SP1 for non-trivial programs generate proofs on the beta version of our [Prover Network](../generating-proofs/prover-network.md). The prover network generates SP1 proofs across multiple machines, reducing latency and also runs SP1 on optimized hardware instances that result in faster + cheaper proof generation times. + +We recommend that for any production benchmarking, you use the prover network to estimate latency and costs of proof generation. We also would love to chat with your team directly to help you get started with the prover network--please fill out this [form](https://partner.succinct.xyz/). + diff --git a/book/versioned_docs/version-3.4.0/introduction.md b/book/versioned_docs/version-3.4.0/introduction.md new file mode 100644 index 0000000000..f3a645786c --- /dev/null +++ b/book/versioned_docs/version-3.4.0/introduction.md @@ -0,0 +1,33 @@ +# Introduction + +*Documentation for SP1 users and developers*. + +[![Telegram Chat][tg-badge]][tg-url] + +![](./sp1.png) + + +SP1 is a performant, open-source zero-knowledge virtual machine (zkVM) that verifies the execution of arbitrary Rust (or any LLVM-compiled language) programs. + +[tg-badge]: https://img.shields.io/endpoint?color=neon&logo=telegram&label=chat&url=https%3A%2F%2Ftg.sumanjay.workers.dev%2Fsuccinct%5Fsp1 +[tg-url]: https://t.me/+AzG4ws-kD24yMGYx + +SP1 has undergone multiple audits from leading ZK security firms and is currently used in production by many top blockchain teams. + +## The future of ZK is writing normal code + +Zero-knowledge proofs (ZKPs) are one of the most critical technologies to blockchain scaling, interoperability and privacy. But, historically building ZKP systems was extremely complicated--requiring large teams with specialized cryptography expertise and taking years to go to production. + +SP1 provides a performant, general-purpose zkVM that enables **any developer** to use ZKPs by writing normal code (in Rust), and get cheap and fast proofs. SP1 will enable ZKPs to become mainstream, introducing a new era of verifiability for all of blockchain infrastructure and beyond. + + +## SP1 enables a diversity of use-cases + +ZKPs enable a diversity of use-cases in blockchain and beyond, including: + +* Rollups: Use SP1 to generate a ZKP for the state transition function of your rollup and connect to Ethereum, Bitcoin or other chains with full validity proofs or ZK fraud proofs. +* Interoperability: Use SP1 for fast-finality, cross rollup interoperability +* Bridges: Use SP1 to generate a ZKP for verifying consensus of L1s, including Tendermint, Ethereum’s Light Client protocol and more, for bridging between chains. +* Oracles: Use SP1 for large scale computations with onchain state, including consensus data and storage data. +* Aggregation: Use SP1 to aggregate and verify other ZKPs for reduced onchain verification costs. +* Privacy: Use SP1 for onchain privacy, including private transactions and private state. diff --git a/book/versioned_docs/version-3.4.0/onchain-verification/contract-addresses.md b/book/versioned_docs/version-3.4.0/onchain-verification/contract-addresses.md new file mode 100644 index 0000000000..3acb971edf --- /dev/null +++ b/book/versioned_docs/version-3.4.0/onchain-verification/contract-addresses.md @@ -0,0 +1,80 @@ +# Contract Addresses + +To verify SP1 proofs on-chain, we recommend using our deployed canonical verifier gateways. The +[SP1VerifierGateway](https://github.com/succinctlabs/sp1-contracts/blob/main/contracts/src/ISP1VerifierGateway.sol) +will automatically route your SP1 proof to the correct verifier based on the SP1 version used. + +## Canonical Verifier Gateways + +| Chain ID | Chain | Gateway | +| -------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | Mainnet | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://etherscan.io/address/0x3B6041173B80E77f038f3F2C0f9744f04837185e) | +| 11155111 | Sepolia | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://sepolia.etherscan.io/address/0x3B6041173B80E77f038f3F2C0f9744f04837185e) | +| 17000 | Holesky | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://holesky.etherscan.io/address/0x3B6041173B80E77f038f3F2C0f9744f04837185e) | +| 42161 | Arbitrum One | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://arbiscan.io/address/0x3B6041173B80E77f038f3F2C0f9744f04837185e) | +| 421614 | Arbitrum Sepolia | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://sepolia.arbiscan.io/address/0x3B6041173B80E77f038f3F2C0f9744f04837185e) | +| 8453 | Base | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://basescan.org/address/0x3B6041173B80E77f038f3F2C0f9744f04837185e) | +| 84532 | Base Sepolia | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://sepolia.basescan.org/address/0x3B6041173B80E77f038f3F2C0f9744f04837185e) | +| 10 | Optimism | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://optimistic.etherscan.io/address/0x3b6041173b80e77f038f3f2c0f9744f04837185e) | +| 11155420 | Optimism Sepolia | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://sepolia-optimism.etherscan.io/address/0x3B6041173B80E77f038f3F2C0f9744f04837185e) | +| 534351 | Scroll Sepolia | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://sepolia.scrollscan.com/address/0x3B6041173B80E77f038f3F2C0f9744f04837185e) | +| 534352 | Scroll | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://scrollscan.com/address/0x3B6041173B80E77f038f3F2C0f9744f04837185e) | + +The most up-to-date reference on each chain can be found in the +[deployments](https://github.com/succinctlabs/sp1-contracts/blob/main/contracts/deployments) +directory in the +SP1 contracts repository, where each chain has a dedicated JSON file with each verifier's address. + +## Versioning Policy + +Whenever a verifier for a new SP1 version is deployed, the gateway contract will be updated to +support it with +[addRoute()](https://github.com/succinctlabs/sp1-contracts/blob/main/contracts/src/ISP1VerifierGateway.sol#L65). +If a verifier for an SP1 version has an issue, the route will be frozen with +[freezeRoute()](https://github.com/succinctlabs/sp1-contracts/blob/main/contracts/src/ISP1VerifierGateway.sol#L71). + +On mainnets, only official versioned releases are deployed and added to the gateway. Testnets have +`rc` versions of the verifier deployed supported in addition to the official versions. + +## Deploying to other Chains + +In the case that you need to use a chain that is not listed above, you can deploy your own +verifier contract by following the instructions in the +[SP1 Contracts Repo](https://github.com/succinctlabs/sp1-contracts/blob/main/README.md#deployments). + +Since both the `SP1VerifierGateway` and each `SP1Verifier` implement the [ISP1Verifier +interface](https://github.com/succinctlabs/sp1-contracts/blob/main/contracts/src/ISP1Verifier.sol), you can choose to either: + +* Deploy the `SP1VerifierGateway` and add `SP1Verifier` contracts to it. Then point to the + `SP1VerifierGateway` address in your contracts. +* Deploy just the `SP1Verifier` contract that you want to use. Then point to the `SP1Verifier` + address in + your contracts. + +If you want support for a canonical verifier on your chain, contact us [here](https://t.me/+AzG4ws-kD24yMGYx). We often deploy canonical verifiers on new chains if there's enough demand. + +## ISP1Verifier Interface + +All verifiers implement the [ISP1Verifier](https://github.com/succinctlabs/sp1-contracts/blob/main/contracts/src/ISP1Verifier.sol) interface. + +```c++ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +/// @title SP1 Verifier Interface +/// @author Succinct Labs +/// @notice This contract is the interface for the SP1 Verifier. +interface ISP1Verifier { + /// @notice Verifies a proof with given public values and vkey. + /// @dev It is expected that the first 4 bytes of proofBytes must match the first 4 bytes of + /// target verifier's VERIFIER_HASH. + /// @param programVKey The verification key for the RISC-V program. + /// @param publicValues The public values encoded as bytes. + /// @param proofBytes The proof of the program execution the SP1 zkVM encoded as bytes. + function verifyProof( + bytes32 programVKey, + bytes calldata publicValues, + bytes calldata proofBytes + ) external view; +} +``` diff --git a/book/versioned_docs/version-3.4.0/onchain-verification/getting-started.mdx b/book/versioned_docs/version-3.4.0/onchain-verification/getting-started.mdx new file mode 100644 index 0000000000..6409876a00 --- /dev/null +++ b/book/versioned_docs/version-3.4.0/onchain-verification/getting-started.mdx @@ -0,0 +1,34 @@ +import Example from "../../../static/examples_fibonacci_script_bin_groth16_bn254.rs.mdx"; + + +# Onchain Verification: Setup + +The best way to get started with verifying SP1 proofs on-chain is to refer to the [SP1 Project Template](https://github.com/succinctlabs/sp1-project-template/tree/main). + +- The template [program](https://github.com/succinctlabs/sp1-project-template/blob/main/program/src/main.rs) shows how to write outputs that can be decoded in Solidity. +- The template [script](https://github.com/succinctlabs/sp1-project-template/blob/main/script/src/bin/prove.rs) shows how to generate the proof using the SDK and save it to a file. +- The template [contract](https://github.com/succinctlabs/sp1-project-template/blob/main/contracts/src/Fibonacci.sol) shows how to verify the proof onchain using Solidity. + +Refer to the section on [Contract Addresses](./contract-addresses.md#contract-addresses) for the addresses of the deployed verifiers. + +## Generating SP1 Proofs for Onchain Verification + +By default, the proofs generated by SP1 are not verifiable onchain, as they are non-constant size and STARK verification on Ethereum is very expensive. To generate a proof that can be verified onchain, we use performant STARK recursion to combine SP1 shard proofs into a single STARK proof and then wrap that in a SNARK proof. Our `ProverClient` has a prover option for this called `plonk`. Behind the scenes, this function will first generate a normal SP1 proof, then recursively combine all of them into a single proof using the STARK recursion protocol. Finally, the proof is wrapped in a SNARK proof using PLONK. + +> WARNING: The Groth16 and PLONK provers are only guaranteed to work on official releases of SP1. To +> use Groth16 or PLONK proving & verification locally, ensure that you have Docker installed and have +> at least 128GB of RAM. + +### Example + + + +You can run the above script with `RUST_LOG=info cargo run --bin groth16_bn254 --release` in `examples/fibonacci/script`. + +#### Using Groth16 and PLONK without Docker (Advanced) + +If you would like to run the Groth16 or PLONK prover directly without Docker, you must have Go 1.22 installed and enable the `native-gnark` feature in `sp1-sdk`. This path is not recommended and may require additional native dependencies. + +```toml +sp1-sdk = { version = "2.0.0", features = ["native-gnark"] } +``` diff --git a/book/versioned_docs/version-3.4.0/onchain-verification/solidity-sdk.md b/book/versioned_docs/version-3.4.0/onchain-verification/solidity-sdk.md new file mode 100644 index 0000000000..822ab620b9 --- /dev/null +++ b/book/versioned_docs/version-3.4.0/onchain-verification/solidity-sdk.md @@ -0,0 +1,122 @@ +# Solidity Verifier + +We maintain a suite of [contracts](https://github.com/succinctlabs/sp1-contracts/tree/main) used for verifying SP1 proofs onchain. We highly recommend using [Foundry](https://book.getfoundry.sh/). + +## Installation + +To install the latest release version: + +```bash +forge install succinctlabs/sp1-contracts +``` + +To install a specific version: + +```bash +forge install succinctlabs/sp1-contracts@ +``` + +Finally, add `@sp1-contracts/=lib/sp1-contracts/contracts/src/` in `remappings.txt.` + +### Usage + +Once installed, you can use the contracts in the library by importing them: + +```c++ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {ISP1Verifier} from "@sp1-contracts/ISP1Verifier.sol"; + +/// @title Fibonacci. +/// @author Succinct Labs +/// @notice This contract implements a simple example of verifying the proof of a computing a +/// fibonacci number. +contract Fibonacci { + /// @notice The address of the SP1 verifier contract. + /// @dev This can either be a specific SP1Verifier for a specific version, or the + /// SP1VerifierGateway which can be used to verify proofs for any version of SP1. + /// For the list of supported verifiers on each chain, see: + /// https://docs.succinct.xyz/onchain-verification/contract-addresses + address public verifier; + + /// @notice The verification key for the fibonacci program. + bytes32 public fibonacciProgramVKey; + + constructor(address _verifier, bytes32 _fibonacciProgramVKey) { + verifier = _verifier; + fibonacciProgramVKey = _fibonacciProgramVKey; + } + + /// @notice The entrypoint for verifying the proof of a fibonacci number. + /// @param _proofBytes The encoded proof. + /// @param _publicValues The encoded public values. + function verifyFibonacciProof(bytes calldata _publicValues, bytes calldata _proofBytes) + public + view + returns (uint32, uint32, uint32) + { + ISP1Verifier(verifier).verifyProof(fibonacciProgramVKey, _publicValues, _proofBytes); + (uint32 n, uint32 a, uint32 b) = abi.decode(_publicValues, (uint32, uint32, uint32)); + return (n, a, b); + } +} + +``` + +### Finding your program vkey + +The program vkey (`fibonacciProgramVKey` in the example above) is passed into the `ISP1Verifier` along with the public values and proof bytes. You +can find your program vkey by going through the following steps: + +1. Find what version of SP1 crates you are using. +2. Use the version from step to run this command: `sp1up --version ` +3. Use the vkey command to get the program vkey: `cargo prove vkey -elf ` + +Alternatively, you can set up a simple script to do this using the `sp1-sdk` crate: + +```rust +fn main() { + // Setup the logger. + sp1_sdk::utils::setup_logger(); + + // Setup the prover client. + let client = ProverClient::new(); + + // Setup the program. + let (_, vk) = client.setup(FIBONACCI_ELF); + + // Print the verification key. + println!("Program Verification Key: {}", vk.bytes32()); +} +``` + +### Testing + +To test the contract, we recommend setting up [Foundry +Tests](https://book.getfoundry.sh/forge/tests). We have an example of such a test in the [SP1 +Project +Template](https://github.com/succinctlabs/sp1-project-template/blob/dev/contracts/test/Fibonacci.t.sol). + +### Solidity Versions + +The officially deployed contracts are built using Solidity 0.8.20 and exist on the +[sp1-contracts main](https://github.com/succinctlabs/sp1-contracts/tree/main) branch. + +If you need to use different versions that are compatible with your contracts, there are also other +branches you can install that contain different versions. For +example for branch [main-0.8.15](https://github.com/succinctlabs/sp1-contracts/tree/main-0.8.15) +contains the contracts with: + +```c++ +pragma solidity ^0.8.15; +``` + +and you can install it with: + +```sh +forge install succinctlabs/sp1-contracts@main-0.8.15 +``` + +If there is different versions that you need but there aren't branches for them yet, please ask in +the [SP1 Telegram](https://t.me/+AzG4ws-kD24yMGYx). diff --git a/book/versioned_docs/version-3.4.0/sp1.png b/book/versioned_docs/version-3.4.0/sp1.png new file mode 100644 index 0000000000000000000000000000000000000000..78576befe311ab327f31e2fd3054f8dddcd081dd GIT binary patch literal 66629 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 Twg!hb@;){(x_Gt->KySO+>0Oy literal 0 HcmV?d00001 diff --git a/book/versioned_docs/version-3.4.0/theme/head.hbs b/book/versioned_docs/version-3.4.0/theme/head.hbs new file mode 100644 index 0000000000..2e2be7a19f --- /dev/null +++ b/book/versioned_docs/version-3.4.0/theme/head.hbs @@ -0,0 +1,6 @@ + + + + + \ No newline at end of file diff --git a/book/versioned_docs/version-3.4.0/verification/off-chain-verification.md b/book/versioned_docs/version-3.4.0/verification/off-chain-verification.md new file mode 100644 index 0000000000..dff3ee960a --- /dev/null +++ b/book/versioned_docs/version-3.4.0/verification/off-chain-verification.md @@ -0,0 +1,48 @@ +import ProgramMain from "../../../static/examples_groth16_program_src_main.rs.mdx"; +import ProgramScript from "../../../static/examples_groth16_script_src_main.rs.mdx"; + +# Offchain Verification + +## Rust `no_std` Verification + +You can verify SP1 Groth16 and Plonk proofs in `no_std` environments with [`sp1-verifier`](https://docs.rs/sp1-verifier/latest/sp1_verifier/). + +`sp1-verifier` is also patched to verify Groth16 and Plonk proofs within the SP1 ZKVM, using +[bn254](https://blog.succinct.xyz/succinctshipsprecompiles/) precompiles. For an example of this, see +the [Groth16 Example](https://github.com/succinctlabs/sp1/tree/main/examples/groth16/). + +### Installation + +Import the following dependency in your `Cargo.toml`: + +```toml +sp1-verifier = {version = "3.0.0", default-features = false} +``` + +### Usage + +`sp1-verifier`'s interface is very similar to the solidity verifier's. It exposes two public functions: +[`Groth16Verifier::verify_proof`](https://docs.rs/sp1-verifier/latest/src/sp1_verifier/groth16.rs.html) +and [`PlonkVerifier::verify_proof`](https://docs.rs/sp1-verifier/latest/src/sp1_verifier/plonk.rs.html). + +`sp1-verifier` also exposes the Groth16 and Plonk verifying keys as constants, `GROTH16_VK_BYTES` and `PLONK_VK_BYTES`. These +keys correspond to the current SP1 version's official Groth16 and Plonk verifying keys, which are used for verifying proofs generated +using docker or the prover network. + +First, generate your groth16/plonk proof with the SP1 SDK. See [here](./onchain/getting-started#generating-sp1-proofs-for-onchain-verification) +for more information -- `sp1-verifier` and the solidity verifier expect inputs in the same format. + +Next, verify the proof with `sp1-verifier`. The following snippet is from the [Groth16 example program](https://github.com/succinctlabs/sp1/tree/dev/examples/groth16/), which verifies a Groth16 proof within SP1 using `sp1-verifier`. + + + +Here, the proof, public inputs, and vkey hash are read from stdin. See the following snippet to see how these values are generated. + + + +> Note that the SP1 SDK itself is *not* `no_std` compatible. + +## Wasm Verification + +The [`example-sp1-wasm-verifier`](https://github.com/succinctlabs/example-sp1-wasm-verifier) demonstrates how to +verify SP1 proofs in wasm. For a more detailed explanation of the process, please see the [README](https://github.com/succinctlabs/example-sp1-wasm-verifier/blob/main/README.md). diff --git a/book/versioned_docs/version-3.4.0/verification/onchain/contract-addresses.md b/book/versioned_docs/version-3.4.0/verification/onchain/contract-addresses.md new file mode 100644 index 0000000000..0a23f6ab2e --- /dev/null +++ b/book/versioned_docs/version-3.4.0/verification/onchain/contract-addresses.md @@ -0,0 +1,101 @@ +# Contract Addresses + +To verify SP1 proofs on-chain, we recommend using our deployed canonical verifier gateways. The +[SP1VerifierGateway](https://github.com/succinctlabs/sp1-contracts/blob/main/contracts/src/ISP1VerifierGateway.sol) +will automatically route your SP1 proof to the correct verifier based on the SP1 version used. + +## Canonical Verifier Gateways + +There are different verifier gateway for each proof system: Groth16 and PLONK. This means that you +must use the correct verifier gateway depending on if you are verifying a Groth16 or PLONK proof. + +### Groth16 + +| Chain ID | Chain | Gateway | +| -------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | Mainnet | [0x397A5f7f3dBd538f23DE225B51f532c34448dA9B](https://etherscan.io/address/0x397A5f7f3dBd538f23DE225B51f532c34448dA9B) | +| 11155111 | Sepolia | [0x397A5f7f3dBd538f23DE225B51f532c34448dA9B](https://sepolia.etherscan.io/address/0x397A5f7f3dBd538f23DE225B51f532c34448dA9B) | +| 17000 | Holesky | [0x397A5f7f3dBd538f23DE225B51f532c34448dA9B](https://holesky.etherscan.io/address/0x397A5f7f3dBd538f23DE225B51f532c34448dA9B) | +| 42161 | Arbitrum One | [0x397A5f7f3dBd538f23DE225B51f532c34448dA9B](https://arbiscan.io/address/0x397A5f7f3dBd538f23DE225B51f532c34448dA9B) | +| 421614 | Arbitrum Sepolia | [0x397A5f7f3dBd538f23DE225B51f532c34448dA9B](https://sepolia.arbiscan.io/address/0x397A5f7f3dBd538f23DE225B51f532c34448dA9B) | +| 8453 | Base | [0x397A5f7f3dBd538f23DE225B51f532c34448dA9B](https://basescan.org/address/0x397A5f7f3dBd538f23DE225B51f532c34448dA9B) | +| 84532 | Base Sepolia | [0x397A5f7f3dBd538f23DE225B51f532c34448dA9B](https://sepolia.basescan.org/address/0x397A5f7f3dBd538f23DE225B51f532c34448dA9B) | +| 10 | Optimism | [0x397A5f7f3dBd538f23DE225B51f532c34448dA9B](https://optimistic.etherscan.io/address/0x397A5f7f3dBd538f23DE225B51f532c34448dA9B) | +| 11155420 | Optimism Sepolia | [0x397A5f7f3dBd538f23DE225B51f532c34448dA9B](https://sepolia-optimism.etherscan.io/address/0x397A5f7f3dBd538f23DE225B51f532c34448dA9B) | +| 534351 | Scroll Sepolia | [0x397A5f7f3dBd538f23DE225B51f532c34448dA9B](https://sepolia.scrollscan.com/address/0x397A5f7f3dBd538f23DE225B51f532c34448dA9B) | +| 534352 | Scroll | [0x397A5f7f3dBd538f23DE225B51f532c34448dA9B](https://scrollscan.com/address/0x397A5f7f3dBd538f23DE225B51f532c34448dA9B) | + +### PLONK + +| Chain ID | Chain | Gateway | +| -------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | Mainnet | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://etherscan.io/address/0x3B6041173B80E77f038f3F2C0f9744f04837185e) | +| 11155111 | Sepolia | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://sepolia.etherscan.io/address/0x3B6041173B80E77f038f3F2C0f9744f04837185e) | +| 17000 | Holesky | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://holesky.etherscan.io/address/0x3B6041173B80E77f038f3F2C0f9744f04837185e) | +| 42161 | Arbitrum One | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://arbiscan.io/address/0x3B6041173B80E77f038f3F2C0f9744f04837185e) | +| 421614 | Arbitrum Sepolia | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://sepolia.arbiscan.io/address/0x3B6041173B80E77f038f3F2C0f9744f04837185e) | +| 8453 | Base | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://basescan.org/address/0x3B6041173B80E77f038f3F2C0f9744f04837185e) | +| 84532 | Base Sepolia | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://sepolia.basescan.org/address/0x3B6041173B80E77f038f3F2C0f9744f04837185e) | +| 10 | Optimism | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://optimistic.etherscan.io/address/0x3b6041173b80e77f038f3f2c0f9744f04837185e) | +| 11155420 | Optimism Sepolia | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://sepolia-optimism.etherscan.io/address/0x3B6041173B80E77f038f3F2C0f9744f04837185e) | +| 534351 | Scroll Sepolia | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://sepolia.scrollscan.com/address/0x3B6041173B80E77f038f3F2C0f9744f04837185e) | +| 534352 | Scroll | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://scrollscan.com/address/0x3B6041173B80E77f038f3F2C0f9744f04837185e) | + +The most up-to-date reference on each chain can be found in the +[deployments](https://github.com/succinctlabs/sp1-contracts/blob/main/contracts/deployments) +directory in the +SP1 contracts repository, where each chain has a dedicated JSON file with each verifier's address. + +## Versioning Policy + +Whenever a verifier for a new SP1 version is deployed, the gateway contract will be updated to +support it with +[addRoute()](https://github.com/succinctlabs/sp1-contracts/blob/main/contracts/src/ISP1VerifierGateway.sol#L65). +If a verifier for an SP1 version has an issue, the route will be frozen with +[freezeRoute()](https://github.com/succinctlabs/sp1-contracts/blob/main/contracts/src/ISP1VerifierGateway.sol#L71). + +On mainnets, only official versioned releases are deployed and added to the gateway. Testnets have +`rc` versions of the verifier deployed supported in addition to the official versions. + +## Deploying to other Chains + +In the case that you need to use a chain that is not listed above, you can deploy your own +verifier contract by following the instructions in the +[SP1 Contracts Repo](https://github.com/succinctlabs/sp1-contracts/blob/main/README.md#deployments). + +Since both the `SP1VerifierGateway` and each `SP1Verifier` implement the [ISP1Verifier +interface](https://github.com/succinctlabs/sp1-contracts/blob/main/contracts/src/ISP1Verifier.sol), you can choose to either: + +* Deploy the `SP1VerifierGateway` and add `SP1Verifier` contracts to it. Then point to the + `SP1VerifierGateway` address in your contracts. +* Deploy just the `SP1Verifier` contract that you want to use. Then point to the `SP1Verifier` + address in + your contracts. + +If you want support for a canonical verifier on your chain, contact us [here](https://t.me/+AzG4ws-kD24yMGYx). We often deploy canonical verifiers on new chains if there's enough demand. + +## ISP1Verifier Interface + +All verifiers implement the [ISP1Verifier](https://github.com/succinctlabs/sp1-contracts/blob/main/contracts/src/ISP1Verifier.sol) interface. + +```c++ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +/// @title SP1 Verifier Interface +/// @author Succinct Labs +/// @notice This contract is the interface for the SP1 Verifier. +interface ISP1Verifier { + /// @notice Verifies a proof with given public values and vkey. + /// @dev It is expected that the first 4 bytes of proofBytes must match the first 4 bytes of + /// target verifier's VERIFIER_HASH. + /// @param programVKey The verification key for the RISC-V program. + /// @param publicValues The public values encoded as bytes. + /// @param proofBytes The proof of the program execution the SP1 zkVM encoded as bytes. + function verifyProof( + bytes32 programVKey, + bytes calldata publicValues, + bytes calldata proofBytes + ) external view; +} +``` diff --git a/book/versioned_docs/version-3.4.0/verification/onchain/getting-started.mdx b/book/versioned_docs/version-3.4.0/verification/onchain/getting-started.mdx new file mode 100644 index 0000000000..279d91a8bc --- /dev/null +++ b/book/versioned_docs/version-3.4.0/verification/onchain/getting-started.mdx @@ -0,0 +1,33 @@ +import Example from "../../../../static/examples_fibonacci_script_bin_groth16_bn254.rs.mdx"; + +# Onchain Verification: Setup + +The best way to get started with verifying SP1 proofs on-chain is to refer to the [SP1 Project Template](https://github.com/succinctlabs/sp1-project-template/tree/main). + +- The template [program](https://github.com/succinctlabs/sp1-project-template/blob/main/program/src/main.rs) shows how to write outputs that can be decoded in Solidity. +- The template [script](https://github.com/succinctlabs/sp1-project-template/blob/main/script/src/bin/prove.rs) shows how to generate the proof using the SDK and save it to a file. +- The template [contract](https://github.com/succinctlabs/sp1-project-template/blob/main/contracts/src/Fibonacci.sol) shows how to verify the proof onchain using Solidity. + +Refer to the section on [Contract Addresses](./contract-addresses.md#contract-addresses) for the addresses of the deployed verifiers. + +## Generating SP1 Proofs for Onchain Verification + +By default, the proofs generated by SP1 are not verifiable onchain, as they are non-constant size and STARK verification on Ethereum is very expensive. To generate a proof that can be verified onchain, we use performant STARK recursion to combine SP1 shard proofs into a single STARK proof and then wrap that in a SNARK proof. Our `ProverClient` has a prover option for this called `plonk`. Behind the scenes, this function will first generate a normal SP1 proof, then recursively combine all of them into a single proof using the STARK recursion protocol. Finally, the proof is wrapped in a SNARK proof using PLONK. + +> WARNING: The Groth16 and PLONK provers are only guaranteed to work on official releases of SP1. To +> use Groth16 or PLONK proving & verification locally, ensure that you have Docker installed and have +> at least 128GB of RAM. + +### Example + + + +You can run the above script with `RUST_LOG=info cargo run --bin groth16_bn254 --release` in `examples/fibonacci/script`. + +#### Using Groth16 and PLONK without Docker (Advanced) + +If you would like to run the Groth16 or PLONK prover directly without Docker, you must have Go 1.22 installed and enable the `native-gnark` feature in `sp1-sdk`. This path is not recommended and may require additional native dependencies. + +```toml +sp1-sdk = { version = "2.0.0", features = ["native-gnark"] } +``` diff --git a/book/versioned_docs/version-3.4.0/verification/onchain/solidity-sdk.md b/book/versioned_docs/version-3.4.0/verification/onchain/solidity-sdk.md new file mode 100644 index 0000000000..822ab620b9 --- /dev/null +++ b/book/versioned_docs/version-3.4.0/verification/onchain/solidity-sdk.md @@ -0,0 +1,122 @@ +# Solidity Verifier + +We maintain a suite of [contracts](https://github.com/succinctlabs/sp1-contracts/tree/main) used for verifying SP1 proofs onchain. We highly recommend using [Foundry](https://book.getfoundry.sh/). + +## Installation + +To install the latest release version: + +```bash +forge install succinctlabs/sp1-contracts +``` + +To install a specific version: + +```bash +forge install succinctlabs/sp1-contracts@ +``` + +Finally, add `@sp1-contracts/=lib/sp1-contracts/contracts/src/` in `remappings.txt.` + +### Usage + +Once installed, you can use the contracts in the library by importing them: + +```c++ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.20; + +import {ISP1Verifier} from "@sp1-contracts/ISP1Verifier.sol"; + +/// @title Fibonacci. +/// @author Succinct Labs +/// @notice This contract implements a simple example of verifying the proof of a computing a +/// fibonacci number. +contract Fibonacci { + /// @notice The address of the SP1 verifier contract. + /// @dev This can either be a specific SP1Verifier for a specific version, or the + /// SP1VerifierGateway which can be used to verify proofs for any version of SP1. + /// For the list of supported verifiers on each chain, see: + /// https://docs.succinct.xyz/onchain-verification/contract-addresses + address public verifier; + + /// @notice The verification key for the fibonacci program. + bytes32 public fibonacciProgramVKey; + + constructor(address _verifier, bytes32 _fibonacciProgramVKey) { + verifier = _verifier; + fibonacciProgramVKey = _fibonacciProgramVKey; + } + + /// @notice The entrypoint for verifying the proof of a fibonacci number. + /// @param _proofBytes The encoded proof. + /// @param _publicValues The encoded public values. + function verifyFibonacciProof(bytes calldata _publicValues, bytes calldata _proofBytes) + public + view + returns (uint32, uint32, uint32) + { + ISP1Verifier(verifier).verifyProof(fibonacciProgramVKey, _publicValues, _proofBytes); + (uint32 n, uint32 a, uint32 b) = abi.decode(_publicValues, (uint32, uint32, uint32)); + return (n, a, b); + } +} + +``` + +### Finding your program vkey + +The program vkey (`fibonacciProgramVKey` in the example above) is passed into the `ISP1Verifier` along with the public values and proof bytes. You +can find your program vkey by going through the following steps: + +1. Find what version of SP1 crates you are using. +2. Use the version from step to run this command: `sp1up --version ` +3. Use the vkey command to get the program vkey: `cargo prove vkey -elf ` + +Alternatively, you can set up a simple script to do this using the `sp1-sdk` crate: + +```rust +fn main() { + // Setup the logger. + sp1_sdk::utils::setup_logger(); + + // Setup the prover client. + let client = ProverClient::new(); + + // Setup the program. + let (_, vk) = client.setup(FIBONACCI_ELF); + + // Print the verification key. + println!("Program Verification Key: {}", vk.bytes32()); +} +``` + +### Testing + +To test the contract, we recommend setting up [Foundry +Tests](https://book.getfoundry.sh/forge/tests). We have an example of such a test in the [SP1 +Project +Template](https://github.com/succinctlabs/sp1-project-template/blob/dev/contracts/test/Fibonacci.t.sol). + +### Solidity Versions + +The officially deployed contracts are built using Solidity 0.8.20 and exist on the +[sp1-contracts main](https://github.com/succinctlabs/sp1-contracts/tree/main) branch. + +If you need to use different versions that are compatible with your contracts, there are also other +branches you can install that contain different versions. For +example for branch [main-0.8.15](https://github.com/succinctlabs/sp1-contracts/tree/main-0.8.15) +contains the contracts with: + +```c++ +pragma solidity ^0.8.15; +``` + +and you can install it with: + +```sh +forge install succinctlabs/sp1-contracts@main-0.8.15 +``` + +If there is different versions that you need but there aren't branches for them yet, please ask in +the [SP1 Telegram](https://t.me/+AzG4ws-kD24yMGYx). diff --git a/book/versioned_docs/version-3.4.0/what-is-a-zkvm.md b/book/versioned_docs/version-3.4.0/what-is-a-zkvm.md new file mode 100644 index 0000000000..4f91fa3213 --- /dev/null +++ b/book/versioned_docs/version-3.4.0/what-is-a-zkvm.md @@ -0,0 +1,35 @@ +# What is a zkVM? + +A zero-knowledge virtual machine (zkVM) is zero-knowledge proof system that allows developers to prove the execution of arbitrary Rust (or other LLVM-compiled language) programs. + +Conceptually, you can think of the SP1 zkVM as proving the evaluation of a function `f(x) = y` by following the steps below: + +- Define `f` using normal Rust code and compile it to an ELF (covered in the [writing programs](./writing-programs/setup.md) section). +- Setup a proving key (`pk`) and verifying key (`vk`) for the program given the ELF. +- Generate a proof `π` using the SP1 zkVM that `f(x) = y` with `prove(pk, x)`. +- Verify the proof `π` using `verify(vk, x, y, π)`. + +As a practical example, `f` could be a simple Fibonacci [program](https://github.com/succinctlabs/sp1/blob/main/examples/fibonacci/program/src/main.rs). The process of generating a proof and verifying it can be seen [here](https://github.com/succinctlabs/sp1/blob/main/examples/fibonacci/script/src/main.rs). + +For blockchain applications, the verification usually happens inside of a [smart contract](https://github.com/succinctlabs/sp1-project-template/blob/main/contracts/src/Fibonacci.sol). + +## How does SP1 Work? + +At a high level, SP1 works with the following steps: + +* Write a program in Rust that defines the logic of your computation for which you want to generate a ZKP. +* Compile the program to the RISC-V ISA (a standard Rust compilation target) using the `cargo prove` CLI tool (installation instructions [here](./getting-started/install.md)) and generate a RISC-V ELF file. +* SP1 will prove the correct execution of arbitrary RISC-V programs by generating a STARK proof of execution. +* Developers can leverage the `sp1-sdk` crate to generate proofs with their ELF and input data. Under the hood the `sp1-sdk` will either generate proofs locally or use a beta version of Succinct's prover network to generate proofs. + +SP1 leverages performant STARK recursion that allows us to prove the execution of arbitrarily long programs and also has a STARK -> SNARK "wrapping system" that allows us to generate small SNARK proofs that can be efficiently verified on EVM chains. + +## Proof System + +For more technical details, check out the SP1 technical note that explains our proof system in detail. In short, we use: + +* STARKs + FRI over the Baby Bear field +* We use performant STARK recursion that allows us to prove the execution of arbitrarily long programs +* We have a system of performant precompiles that accelerate hash functions and cryptographic signature verification that allow us to get substantial performance gains on blockchain workloads + + diff --git a/book/versioned_docs/version-3.4.0/why-use-sp1.md b/book/versioned_docs/version-3.4.0/why-use-sp1.md new file mode 100644 index 0000000000..44db0ab6bc --- /dev/null +++ b/book/versioned_docs/version-3.4.0/why-use-sp1.md @@ -0,0 +1,46 @@ +# Why use SP1? + +## Use-Cases + +Zero-knowledge proofs (ZKPs) are a powerful primitive that enable **verifiable computation**. With ZKPs, anyone can verify a cryptographic proof that a program has executed correctly, without needing to trust the prover, re-execute the program or even know the inputs to the program. + +Historically, building ZKP systems has been extremely complicated, requiring large teams with specialized cryptography expertise and taking years to go to production. SP1 is a performant, general-purpose zkVM that solves this problem and creates a future where all blockchain infrastructure, including rollups, bridges, coprocessors, and more, utilize ZKPs **via maintainable software written in Rust**. + +SP1 is especially powerful in blockchain contexts which rely on verifiable computation. Example applications include: +- [Rollups](https://ethereum.org/en/developers/docs/scaling/zk-rollups/): SP1 can be used in combination with existing node infrastructure like [Reth](https://github.com/paradigmxyz/reth) to build rollups with ZKP validity proofs or ZK fraud proofs. +- [Coprocessors](https://crypto.mirror.xyz/BFqUfBNVZrqYau3Vz9WJ-BACw5FT3W30iUX3mPlKxtA): SP1 can be used to outsource onchain computation to offchain provers to enable use cases such as large-scale computation over historical state and onchain machine learning, dramatically reducing gas costs. +- [Light Clients](https://ethereum.org/en/developers/docs/nodes-and-clients/light-clients/): SP1 can be used to build light clients that can verify the state of other chains, facilitating interoperability between different blockchains without relying on any trusted third parties. + +SP1 has already been integrated in many of these applications, including but not limited to: + +- [SP1 Tendermint](https://github.com/succinctlabs/sp1-tendermint-example): An example of a ZK Tendermint light client on Ethereum powered by SP1. +- [SP1 Reth](https://github.com/succinctlabs/rsp): A performant, type-1 zkEVM written in Rust & SP1 using Reth. +- [SP1 Contract Call](https://github.com/succinctlabs/sp1-contract-call): A lightweight library to generate ZKPs of Ethereum smart contract execution +- and many more! + +SP1 is used by protocols in production today: + +- [SP1 Blobstream](https://github.com/succinctlabs/sp1-blobstream): A bridge that verifies [Celestia](https://celestia.org/) “data roots” (a commitment to all data blobs posted in a range of Celestia blocks) on Ethereum and other EVM chains. +- [SP1 Vector](https://github.com/succinctlabs/sp1-vector): A bridge that relays [Avail's](https://www.availproject.org/) merkle root to Ethereum and also functions as a token bridge from Avail to Ethereum. + + +## 100x developer productivity + +SP1 enables teams to use ZKPs in production with minimal overhead and fast timelines. + +**Maintainable:** With SP1, you can reuse existing Rust crates, like `revm`, `reth`, `tendermint-rs`, `serde` and more, to write your ZKP logic in maintainable, Rust code. + +**Go to market faster:** By reusing existing crates and expressing ZKP logic in regular code, SP1 significantly reduces audit surface area and complexity, enabling teams to go to market with ZKPs faster. + +## Blazing Fast Performance + +SP1 is the fastest zkVM and has blazing fast performance on a variety of realistic blockchain workloads, including light clients and rollups. With SP1, ZKP proving costs are an order of magnitude less than alternative zkVMs or even circuits, making it cost-effective and fast for practical use. + +Read more about our benchmarking results [here](https://blog.succinct.xyz/sp1-benchmarks-8-6-24). + +## Open Source + +SP1 is 100% open-source (MIT / Apache 2.0) with no code obfuscation and built to be contributor friendly, with all development done in the open. Unlike existing zkVMs whose constraint logic is closed-source and impossible to audit or modify, SP1 is modularly architected and designed to be customizable from day one. This customizability (unique to SP1) allows for users to add “precompiles” to the core zkVM logic that yield substantial performance gains, making SP1’s performance not only SOTA vs. existing zkVMs, but also competitive with circuits in a variety of use-cases. + + + diff --git a/book/versioned_docs/version-3.4.0/writing-programs/basics.mdx b/book/versioned_docs/version-3.4.0/writing-programs/basics.mdx new file mode 100644 index 0000000000..7eb28e7004 --- /dev/null +++ b/book/versioned_docs/version-3.4.0/writing-programs/basics.mdx @@ -0,0 +1,15 @@ +import Example from "../../../static/examples_fibonacci_program_src_main.rs.mdx"; + +# Basics + +The easiest way to understand how to write programs for the SP1 zkVM is to look at some examples. + +## Example: Fibonacci + +This program is from the `examples` [directory](https://github.com/succinctlabs/sp1/tree/main/examples) in the SP1 repo which contains several example programs of varying complexity. + + + +As you can see, writing programs is as simple as writing normal Rust. + +After you've written your program, you must compile it to an ELF that the SP1 zkVM can prove. To read more about compiling programs, refer to the section on [Compiling Programs](./compiling). To read more about how inputs and outputs work, refer to the section on [Inputs & Outputs](./inputs-and-outputs). diff --git a/book/versioned_docs/version-3.4.0/writing-programs/compiling.mdx b/book/versioned_docs/version-3.4.0/writing-programs/compiling.mdx new file mode 100644 index 0000000000..fef91eed8e --- /dev/null +++ b/book/versioned_docs/version-3.4.0/writing-programs/compiling.mdx @@ -0,0 +1,100 @@ +import Example from "../../../static/examples_fibonacci_script_build.rs.mdx"; + +# Compiling Programs + +Once you have written an SP1 program, you must compile it to an ELF file that can be executed in the zkVM. The `cargo prove` CLI tool (downloaded during installation) provides convenient commands for compiling SP1 programs. + +## Development Builds + +> WARNING: This may not generate a reproducible ELF which is necessary for verifying that your binary corresponds to given source code. +> +> Use the [reproducible build system](#reproducible-builds-with-docker-production) for production builds. + +To build a program while developing, simply run the following command in the crate that contains your SP1 program: + +```bash +cargo prove build +``` + +This will compile the ELF that can be executed in the zkVM and put it in the file `elf/riscv32im-succinct-zkvm-elf`. The output from the command will look something like this: + +```bash +[sp1] Compiling version_check v0.9.4 +[sp1] Compiling proc-macro2 v1.0.86 +[sp1] Compiling unicode-ident v1.0.12 +[sp1] Compiling cfg-if v1.0.0 +... +[sp1] Compiling sp1-lib v1.0.1 +[sp1] Compiling sp1-zkvm v1.0.1 +[sp1] Compiling fibonacci-program v0.1.0 (/Users/username/Documents/fibonacci/program) +[sp1] Finished `release` profile [optimized] target(s) in 8.33s +``` + +Under the hood, this CLI command calls `cargo build` with the `riscv32im-succinct-zkvm-elf` target and other required environment variables and flags. The logic for this command is defined in the [sp1-build](https://github.com/succinctlabs/sp1/tree/main/build) crate. + +### Advanced Build Options + +You can pass additional arguments to the `cargo prove build` command to customize the build process, like configuring what features are enabled, customizing the output directory and more. To see all available options, run `cargo prove build --help`. Many of these options mirror the options available in the `cargo build` command. + +## Production Builds + +For production builds of programs, you can build your program inside a Docker container which will generate a **reproducible ELF** on all platforms. To do so, just use the `--docker` flag and optionally the `--tag` flag with the release version you want to use (defaults to `latest`). For example: + +```bash +cargo prove build --docker --tag v1.0.1 +``` + +To verify that your build is reproducible, you can compute the SHA-512 hash of the ELF on different platforms and systems with: + +```bash +$ shasum -a 512 elf/riscv32im-succinct-zkvm-elf +f9afb8caaef10de9a8aad484c4dd3bfa54ba7218f3fc245a20e8a03ed40b38c617e175328515968aecbd3c38c47b2ca034a99e6dbc928512894f20105b03a203 +``` + +## Build Script + +If you want your program crate to be built automatically whenever you build/run your script crate, you can add a `build.rs` file inside of `script/` (at the same level as `Cargo.toml` of your script crate) that utilizes the `sp1-build` crate: + + + +The path passed in to `build_program` should point to the directory containing the `Cargo.toml` file for your program. Make sure to also add `sp1-build` as a build dependency in `script/Cargo.toml`: + +```toml +[build-dependencies] +sp1-build = "2.0.0" +``` + +You will see output like the following from the build script if the program has changed, indicating that the program was rebuilt: + +``` +[fibonacci-script 0.1.0] cargo:rerun-if-changed=../program/src +[fibonacci-script 0.1.0] cargo:rerun-if-changed=../program/Cargo.toml +[fibonacci-script 0.1.0] cargo:rerun-if-changed=../program/Cargo.lock +[fibonacci-script 0.1.0] cargo:warning=fibonacci-program built at 2024-03-02 22:01:26 +[fibonacci-script 0.1.0] [sp1] Compiling fibonacci-program v0.1.0 (/Users/umaroy/Documents/fibonacci/program) +[fibonacci-script 0.1.0] [sp1] Finished release [optimized] target(s) in 0.15s +warning: fibonacci-script@0.1.0: fibonacci-program built at 2024-03-02 22:01:26 +``` + +The above output was generated by running `RUST_LOG=info cargo run --release -vv` for the `script` folder of the Fibonacci example. + +### Advanced Build Options + +To configure the build process when using the `sp1-build` crate, you can pass a [`BuildArgs`](https://docs.rs/sp1-build/1.2.0/sp1_build/struct.BuildArgs.html) struct to to the [`build_program_with_args`](https://docs.rs/sp1-build/1.2.0/sp1_build/fn.build_program_with_args.html) function. The build arguments are the same as the ones available from the `cargo prove build` command. + +As an example, you could use the following code to build the Fibonacci example with the `docker` flag set to `true` and a custom output directory for the generated ELF: + +```rust +use sp1_build::{build_program_with_args, BuildArgs}; + +fn main() { + let args = BuildArgs { + docker: true, + output_directory: "./fibonacci-program".to_string(), + ..Default::default() + }; + build_program_with_args("../program", &args); +} +``` + +**Note:** If you want reproducible builds with the `build.rs` approach, you should use the `docker` flag and the `build_program_with_args` function, as shown in the example above. diff --git a/book/versioned_docs/version-3.4.0/writing-programs/cycle-tracking.mdx b/book/versioned_docs/version-3.4.0/writing-programs/cycle-tracking.mdx new file mode 100644 index 0000000000..ea45fb26bd --- /dev/null +++ b/book/versioned_docs/version-3.4.0/writing-programs/cycle-tracking.mdx @@ -0,0 +1,124 @@ +import Example from "../../../static/examples_cycle-tracking_program_bin_normal.rs.mdx"; + +# Cycle Tracking + +When writing a program, it is useful to know how many RISC-V cycles a portion of the program takes to identify potential performance bottlenecks. SP1 provides a way to track the number of cycles spent in a portion of the program. + +## Tracking Cycles with Annotations + +To track the number of cycles spent in a portion of the program, you can either put `println!("cycle-tracker-start: block name")` + `println!("cycle-tracker-end: block name")` statements (block name must be same between start and end) around the portion of your program you want to profile or use the `#[sp1_derive::cycle_tracker]` macro on a function. An example is shown below: + + + +Note that to use the macro, you must add the `sp1-derive` crate to your dependencies for your program. + +```toml +[dependencies] +sp1-derive = "2.0.0" +``` + +In the script for proof generation, setup the logger with `utils::setup_logger()` and run the script with `RUST_LOG=info cargo run --release`. You should see the following output: + +``` +$ RUST_LOG=info cargo run --release + Finished release [optimized] target(s) in 0.21s + Running `target/release/cycle-tracking-script` +2024-03-13T02:03:40.567500Z INFO execute: loading memory image +2024-03-13T02:03:40.567751Z INFO execute: starting execution +2024-03-13T02:03:40.567760Z INFO execute: clk = 0 pc = 0x2013b8 +2024-03-13T02:03:40.567822Z INFO execute: ┌╴setup +2024-03-13T02:03:40.568095Z INFO execute: └╴4,398 cycles +2024-03-13T02:03:40.568122Z INFO execute: ┌╴main-body +2024-03-13T02:03:40.568149Z INFO execute: │ ┌╴expensive_function +2024-03-13T02:03:40.568250Z INFO execute: │ └╴1,368 cycles +stdout: result: 5561 +2024-03-13T02:03:40.568373Z INFO execute: │ ┌╴expensive_function +2024-03-13T02:03:40.568470Z INFO execute: │ └╴1,368 cycles +stdout: result: 2940 +2024-03-13T02:03:40.568556Z INFO execute: └╴5,766 cycles +2024-03-13T02:03:40.568566Z INFO execute: finished execution clk = 11127 pc = 0x0 +2024-03-13T02:03:40.569251Z INFO execute: close time.busy=1.78ms time.idle=21.1µs +``` + +Note that we elegantly handle nested cycle tracking, as you can see above. + +### Get Tracked Cycle Counts + +To include tracked cycle counts in the `ExecutionReport` when using `ProverClient::execute`, use the following annotations: + +```rust +fn main() { + println!("cycle-tracker-report-start: block name"); + // ... + println!("cycle-tracker-report-end: block name"); +} +``` + +This will log the cycle count for `block name` and include it in the `ExecutionReport` in the `cycle_tracker` map. + +## Tracking Cycles with Tracing + +The `cycle-tracker` annotation is a convenient way to track cycles for specific sections of code. However, sometimes it can also be useful to track what functions are taking the most cycles across the entire program, without having to annotate every function individually. + +First, we need to generate a trace file of the program counter at each cycle while the program is executing. This can be done by simply setting the `TRACE_FILE` environment variable with the path of the file you want to write the trace to. For example, you can run the following command in the `script` directory for any example program: + +```bash +TRACE_FILE=trace.log RUST_LOG=info cargo run --release +``` + +When the `TRACE_FILE` environment variable is set, as SP1's RISC-V runtime is executing, it will write a log of the program counter to the file specified by `TRACE_FILE`. + +Next, we can use the `cargo prove` CLI with the `trace` command to analyze the trace file and generate a table of instruction counts. This can be done with the following command: + +```bash +cargo prove trace --elf --trace +``` + +The `trace` command will generate a table of instruction counts, sorted by the number of cycles spent in each function. The output will look something like this: + +``` + [00:00:00] [########################################] 17053/17053 (0s) + +Total instructions in trace: 17053 + + + Instruction counts considering call graph ++----------------------------------------+-------------------+ +| Function Name | Instruction Count | +| __start | 17045 | +| main | 12492 | +| sp1_zkvm::syscalls::halt::syscall_halt | 4445 | +| sha2::sha256::compress256 | 4072 | +| sp1_lib::io::commit | 258 | +| sp1_lib::io::SyscallWriter::write | 255 | +| syscall_write | 195 | +| memcpy | 176 | +| memset | 109 | +| sp1_lib::io::read_vec | 71 | +| __rust_alloc | 29 | +| sp1_zkvm::heap::SimpleAlloc::alloc | 22 | +| syscall_hint_len | 3 | +| syscall_hint_read | 2 | ++----------------------------------------+-------------------+ + + + Instruction counts ignoring call graph ++----------------------------------------+-------------------+ +| Function Name | Instruction Count | +| main | 12075 | +| sha2::sha256::compress256 | 4073 | +| sp1_zkvm::syscalls::halt::syscall_halt | 219 | +| memcpy | 180 | +| syscall_write | 123 | +| memset | 111 | +| sp1_lib::io::commit | 88 | +| sp1_lib::io::SyscallWriter::write | 60 | +| __start | 45 | +| sp1_lib::io::read_vec | 35 | +| sp1_zkvm::heap::SimpleAlloc::alloc | 23 | +| anonymous | 7 | +| __rust_alloc | 7 | +| syscall_hint_len | 4 | +| syscall_hint_read | 3 | ++----------------------------------------+-------------------+ +``` diff --git a/book/versioned_docs/version-3.4.0/writing-programs/inputs-and-outputs.mdx b/book/versioned_docs/version-3.4.0/writing-programs/inputs-and-outputs.mdx new file mode 100644 index 0000000000..62c0e62bb5 --- /dev/null +++ b/book/versioned_docs/version-3.4.0/writing-programs/inputs-and-outputs.mdx @@ -0,0 +1,67 @@ +import Example from "../../../static/examples_io_program_src_main.rs.mdx"; + +# Inputs and Outputs + +In real world applications of zero-knowledge proofs, you almost always want to verify your proof in the context of some inputs and outputs. For example: + +- **Rollups**: Given a list of transactions, prove the new state of the blockchain. +- **Coprocessors**: Given a block header, prove the historical state of some storage slot inside a smart contract. +- **Attested Images**: Given a signed image, prove that you made a restricted set of image transformations. + +In this section, we cover how you pass inputs and outputs to the zkVM and create new types that support serialization. + +## Reading Data + +Data that is read is not public to the verifier by default. Use the `sp1_zkvm::io::read::` method: + +```rust +let a = sp1_zkvm::io::read::(); +let b = sp1_zkvm::io::read::(); +let c = sp1_zkvm::io::read::(); +``` + +Note that `T` must implement the `serde::Serialize` and `serde::Deserialize` trait. If you want to read bytes directly, you can also use the `sp1_zkvm::io::read_vec` method. + +```rust +let my_vec = sp1_zkvm::io::read_vec(); +``` + +## Committing Data + +Committing to data makes the data public to the verifier. Use the `sp1_zkvm::io::commit::` method: + +```rust +sp1_zkvm::io::commit::(&a); +sp1_zkvm::io::commit::(&b); +sp1_zkvm::io::commit::(&c); +``` + +Note that `T` must implement the `Serialize` and `Deserialize` trait. If you want to write bytes directly, you can also use `sp1_zkvm::io::commit_slice` method: + +```rust +let mut my_slice = [0_u8; 32]; +sp1_zkvm::io::commit_slice(&my_slice); +``` + +## Creating Serializable Types + +Typically, you can implement the `Serialize` and `Deserialize` traits using a simple derive macro on a struct. + +```rust +use serde::{Serialize, Deserialize}; + +#[derive(Serialize, Deserialize)] +struct MyStruct { + a: u32, + b: u64, + c: String +} +``` + +For more complex usecases, refer to the [Serde docs](https://serde.rs/). + +## Example + +Here is a basic example of using inputs and outputs with more complex types. + + diff --git a/book/versioned_docs/version-3.4.0/writing-programs/patched-crates.md b/book/versioned_docs/version-3.4.0/writing-programs/patched-crates.md new file mode 100644 index 0000000000..818190f2ee --- /dev/null +++ b/book/versioned_docs/version-3.4.0/writing-programs/patched-crates.md @@ -0,0 +1,234 @@ +# Patched Crates + +We maintain forks of commonly used libraries in blockchain infrastructure to significantly accelerate the execution of certain operations. +Under the hood, we use [precompiles](./precompiles) to achieve tremendous performance improvements in proof generation time. + +**If you know of a library or library version that you think should be patched, please open an issue or a pull request!** + +## Supported Libraries + +| Crate Name | Repository | Notes | Versions | +|---------------------|---------------------------------------------------------------------------------------|------------------|-----------------------| +| sha2 | [sp1-patches/RustCrypto-hashes](https://github.com/sp1-patches/RustCrypto-hashes) | sha256 | 0.9.8, 0.10.6, 0.10.8 | +| sha3 | [sp1-patches/RustCrypto-hashes](https://github.com/sp1-patches/RustCrypto-hashes) | keccak256 | 0.9.8, 0.10.6, 0.10.8 | +| bigint | [sp1-patches/RustCrypto-bigint](https://github.com/sp1-patches/RustCrypto-bigint) | bigint | 0.5.5 | +| tiny-keccak | [sp1-patches/tiny-keccak](https://github.com/sp1-patches/tiny-keccak) | keccak256 | 2.0.2 | +| curve25519-dalek | [sp1-patches/curve25519-dalek](https://github.com/sp1-patches/curve25519-dalek) | ed25519 verify | 4.1.3, 3.2.0 | +| curve25519-dalek-ng | [sp1-patches/curve25519-dalek-ng](https://github.com/sp1-patches/curve25519-dalek-ng) | ed25519 verify | 4.1.1 | +| ed25519-consensus | [sp1-patches/ed25519-consensus](http://github.com/sp1-patches/ed25519-consensus) | ed25519 verify | 2.1.0 | +| ed25519-dalek | [sp1-patches/ed25519-dalek](http://github.com/sp1-patches/ed25519-dalek) | ed25519 verify | 1.0.1 | +| ecdsa-core | [sp1-patches/signatures](http://github.com/sp1-patches/signatures) | secp256k1 verify | 0.16.8, 0.16.9 | +| secp256k1 | [sp1-patches/rust-secp256k1](http://github.com/sp1-patches/rust-secp256k1) | secp256k1 verify | 0.29.0, 0.29.1 | +| substrate-bn | [sp1-patches/bn](https://github.com/sp1-patches/bn) | BN254 | 0.6.0 | +| bls12_381 | [sp1-patches/bls12_381](https://github.com/sp1-patches/bls12_381) | BLS12-381 | 0.8.0 | + +## Using Patched Crates + +To use the patched libraries, you can use corresponding patch entries in your program's `Cargo.toml` such as: + +```toml +[patch.crates-io] +sha2-v0-9-8 = { git = "https://github.com/sp1-patches/RustCrypto-hashes", package = "sha2", tag = "sha2-v0.9.8-patch-v1" } +sha2-v0-10-6 = { git = "https://github.com/sp1-patches/RustCrypto-hashes", package = "sha2", tag = "sha2-v0.10.6-patch-v1" } +sha2-v0-10-8 = { git = "https://github.com/sp1-patches/RustCrypto-hashes", package = "sha2", tag = "sha2-v0.10.8-patch-v1" } +sha3-v0-9-8 = { git = "https://github.com/sp1-patches/RustCrypto-hashes", package = "sha3", tag = "sha3-v0.9.8-patch-v1" } +sha3-v0-10-6 = { git = "https://github.com/sp1-patches/RustCrypto-hashes", package = "sha3", tag = "sha3-v0.10.6-patch-v1" } +sha3-v0-10-8 = { git = "https://github.com/sp1-patches/RustCrypto-hashes", package = "sha3", tag = "sha3-v0.10.8-patch-v1" } +crypto-bigint = { git = "https://github.com/sp1-patches/RustCrypto-bigint", tag = "crypto_bigint-v0.5.5-patch-v1" } +tiny-keccak = { git = "https://github.com/sp1-patches/tiny-keccak", tag = "tiny_keccak-v2.0.2-patch-v1" } +substrate-bn = { git = "https://github.com/sp1-patches/bn", tag = "substrate_bn-v0.6.0-patch-v1" } +bls12_381 = { git = "https://github.com/sp1-patches/bls12_381", tag = "bls12_381-v0.8.0-patch-v1" } + +# For sp1 versions >= 3.4.0 +curve25519-dalek = { git = "https://github.com/sp1-patches/curve25519-dalek", tag = "patch-v4.1.3-v3.4.0" } +# For sp1 versions < 3.4.0 +curve25519-dalek = { git = "https://github.com/sp1-patches/curve25519-dalek", tag = "curve25519_dalek-v4.1.3-patch-v1" } +curve25519-dalek-ng = { git = "https://github.com/sp1-patches/curve25519-dalek-ng", tag = "curve25519_dalek_ng-v4.1.1-patch-v1" } +ed25519-consensus = { git = "https://github.com/sp1-patches/ed25519-consensus", tag = "ed25519_consensus-v2.1.0-patch-v1" } +# For sp1 versions >= 3.3.0 +ecdsa-core = { git = "https://github.com/sp1-patches/signatures", package = "ecdsa", tag = "ecdsa-v0.16.9-patch-v3.3.0" } +secp256k1 = { git = "https://github.com/sp1-patches/rust-secp256k1", tag = "secp256k1-v0.29.0-patch-v3.3.0" } +# For sp1 versions < 3.3.0 +ecdsa-core = { git = "https://github.com/sp1-patches/signatures", package = "ecdsa", tag = "ecdsa-v0.16.9-patch-v1" } +secp256k1 = { git = "https://github.com/sp1-patches/rust-secp256k1", tag = "secp256k1-v0.29.0-patch-v1" } +``` + +If you are patching a crate from Github instead of from crates.io, you need to specify the +repository in the patch section. For example: + +```toml +[patch."https://github.com/RustCrypto/hashes"] +sha3 = { git = "https://github.com/sp1-patches/RustCrypto-hashes", package = "sha3", tag = "sha3-v0.10.8-patch-v1" } +``` + +An example of using patched crates is available in our [Tendermint Example](https://github.com/succinctlabs/sp1/blob/main/examples/tendermint/program/Cargo.toml#L22-L25). + +## Ed25519 Acceleration + +To accelerate Ed25519 operations, you'll need to patch crates depending on if you're using the `ed25519-consensus` or `ed25519-dalek` library in your program or dependencies. + +Generally, `ed25519-consensus` has better performance than `ed25519-dalek` by a factor of 2. + +### Patches + +Apply the following patches based on what crates are in your dependencies. + +- `ed25519-consensus` + + ```toml + ed25519-consensus = { git = "https://github.com/sp1-patches/ed25519-consensus", tag = "ed25519_consensus-v2.1.0-patch-v1" } + ``` + + Note: The curve operations for Ed25519 occur mainly inside of `curve25519-dalek-ng`, but the crate also exposes + a `u32_backend` feature flag which accelerates signature recovery by 10% over the default `u64_backend`, which is why + `ed25519-consensus` is patched rather than `ed25519-dalek`. + +- `ed25519-dalek` + + If using `ed25519-dalek` version `2.1`, you can patch it with the following: + + ```toml + curve25519-dalek = { git = "https://github.com/sp1-patches/curve25519-dalek", tag = "curve25519_dalek-v4.1.3-patch-v1" } + ``` + + If using `ed25519-dalek` version `1.0.1`, you can patch it with the following: + + ```toml + ed25519-dalek = { git = "https://github.com/sp1-patches/ed25519-dalek", tag = "ed25519_dalek-v1.0.1-patch-v1" } + ``` + + Note: We need to patch the underlying Ed25519 curve operations in the `curve25519-dalek` crate. `ed25519-dalek` + version `2.1` uses `curve25519-dalek` version `4.1.3`, while `1.0.1` uses `3.2.0`. For version `2.1`, we patch + `curve25519-dalek` directly, while for version `1.0.1`, we patch `ed25519-dalek`. + +- `curve25519-dalek` + + ```toml + curve25519-dalek = { git = "https://github.com/sp1-patches/curve25519-dalek", tag = "curve25519_dalek-v4.1.3-patch-v1" } + ``` + +- `curve25519-dalek-ng` + + ```toml + curve25519-dalek-ng = { git = "https://github.com/sp1-patches/curve25519-dalek-ng", tag = "curve25519_dalek_ng-v4.1.1-patch-v1" } + ``` + +## Secp256k1 Acceleration + +To accelerate Secp256k1 operations, you'll need to patch `k256` or `secp256k1` depending on your usage. + +Generally, if a crate you're using (ex. `revm`) has support for using `k256` instead of `secp256k1`, you should use `k256`. + +### Patches + +Apply the following patches based on what crates are in your dependencies. + +- `k256` + + ```toml + ecdsa-core = { git = "https://github.com/sp1-patches/signatures", package = "ecdsa", tag = "ecdsa-v0.16.9-patch-v1" } + ``` + + Note: The curve operations for `k256` are inside of the `ecdsa-core` crate, so you don't need to patch `k256` itself, and just patching `ecdsa-core` is enough. + +- `secp256k1` + + ```toml + secp256k1 = { git = "https://github.com/sp1-patches/rust-secp256k1", tag = "secp256k1-v0.29.0-patch-v1" } + ``` + +## BN254 Acceleration + +To accelerate BN254 (Also known as BN128 and Alt-BN128), you will need to patch the `substrate-bn` crate. + +### Patches + +Apply the patch by adding the following to your list of dependencies: + +```rust +substrate-bn = { git = "https://github.com/sp1-patches/bn", tag = "substrate_bn-v0.6.0-patch-v1" } +``` + +### Performance Benchmarks for Patched `substrate-bn` in `revm` + +| Operation | Standard `substrate-bn` Cycles | Patched `substrate-bn` Cycles | Times Faster | +| --------- | ------------------------------ | ----------------------------- | ------------ | +| run-add | 170,298 | 111,615 | 1.52 | +| run-mul | 1,860,836 | 243,830 | 7.64 | +| run-pair | 255,627,625 | 11,528,503 | 22.15 | + +Note: The operations `run-add`, `run-mul`, and `run-pair` are from the `revm` crate, specifically from the file `crates/precompile/src/bn128.rs` on GitHub. In the patched version of the `substrate-bn` crate, these functions utilize SP1's BN254 Fp precompiles. + +To accelerate [revm](https://github.com/bluealloy/revm) in SP1 using the BN254 patched crate, replace the `substrate-bn` crate with the patched crate by adding the following to `crates/precompile/Cargo.toml`: + +```toml +bn = { git = "https://github.com/sp1-patches/bn", package = "substrate-bn", tag = "substrate_bn-v0.6.0-patch-v1" } +``` + +## BLS12-381 Acceleration + +To accelerate BLS12-381 operations, you'll need to patch the `bls12_381` crate. Apply the following patch by adding the following to your list of dependencies: + +```toml +bls12_381 = { git = "https://github.com/sp1-patches/bls12_381", tag = "bls12_381-v0.8.0-patch-v1" } +``` + +This patch significantly improves the performance of BLS12-381 operations, making it essential for applications that rely heavily on these cryptographic primitives. + +### Performance Benchmarks for Patched `bls12_381` in [`kzg-rs`](https://github.com/succinctlabs/kzg-rs) + +| Test | Unpatched Cycles | Patched Cycles | Improvement (x faster) | +| -------------------------------------- | ---------------- | -------------- | ---------------------- | +| Verify blob KZG proof | 265,322,934 | 27,166,173 | 9.77x | +| Verify blob KZG proof batch (10 blobs) | 1,228,277,089 | 196,571,578 | 6.25x | +| Evaluate polynomial in evaluation form | 90,717,711 | 59,370,556 | 1.53x | +| Compute challenge | 63,400,511 | 57,341,532 | 1.11x | +| Verify KZG proof | 212,708,597 | 9,390,640 | 22.65x | + +## Troubleshooting + +### Verifying Patch Usage: Cargo + +You can check if the patch was applied by using cargo's tree command to print the dependencies of the crate you patched. + +```bash +cargo tree -p sha2@0.9.8 +``` + +Next to the package name, it should have a link to the Github repository that you patched with. + +Ex. + +```text +sha2 v0.9.8 (https://github.com/sp1-patches/RustCrypto-hashes?branch=patch-sha2-v0.9.8#afdbfb09) +├── ... +``` + +### Verifying Patch Usage: SP1 + +To check if a precompile is used by your program, you can view SP1's ExecutionReport, which is returned when executing a program with `execute`. In `ExecutionReport` you can view the `syscall_counts` map to view if a specific syscall was used. + +For example, if you wanted to check `sha256` was used, you would look for `SHA_EXTEND` and `SHA_COMPRESS` in `syscall_counts`. + +An example of this is available in our [Patch Testing Example](https://github.com/succinctlabs/sp1/blob/dd032eb23949828d244d1ad1f1569aa78155837c/examples/patch-testing/script/src/main.rs). + +### Cargo Version Issues + +If you encounter issues with version commits on your patches, you should try updating the patched crate manually. + +```bash +cargo update -p +``` + +If you encounter issues relating to cargo / git, you can try setting `CARGO_NET_GIT_FETCH_WITH_CLI`: + +```bash +CARGO_NET_GIT_FETCH_WITH_CLI=true cargo update -p +``` + +You can permanently set this value in `~/.cargo/config`: + +```toml +[net] +git-fetch-with-cli = true +``` diff --git a/book/versioned_docs/version-3.4.0/writing-programs/precompiles.mdx b/book/versioned_docs/version-3.4.0/writing-programs/precompiles.mdx new file mode 100644 index 0000000000..a8883d478a --- /dev/null +++ b/book/versioned_docs/version-3.4.0/writing-programs/precompiles.mdx @@ -0,0 +1,24 @@ +import Example from "../../../static/crates_zkvm_lib_src_lib.rs.mdx"; +import CodeBlock from '@theme/CodeBlock'; + +# Precompiles + +Precompiles are built into the SP1 zkVM and accelerate commonly used operations such as elliptic curve arithmetic and hashing. Under the hood, precompiles are implemented as custom STARK tables dedicated to proving one or few operations. **They typically improve the performance +of executing expensive operations in SP1 by a few orders of magnitude.** + +Inside the zkVM, precompiles are exposed as system calls executed through the `ecall` RISC-V instruction. +Each precompile has a unique system call number and implements an interface for the computation. + +SP1 also has been designed specifically to make it easy for external contributors to create and extend the zkVM with their own precompiles. +To learn more about this, you can look at implementations of existing precompiles in the [precompiles](https://github.com/succinctlabs/sp1/tree/main/crates/core/executor/src/events/precompiles) folder. More documentation on this will be coming soon. + +**To use precompiles, we typically recommend you interact with them through [patches](./patched-crates.md), which are crates modified +to use these precompiles under the hood, without requiring you to call system calls directly.** + +## Specification + +If you are an advanced user you can interact with the precompiles directly using external system calls. + +Here is a list of all available system calls & precompiles. + + diff --git a/book/versioned_docs/version-3.4.0/writing-programs/proof-aggregation.md b/book/versioned_docs/version-3.4.0/writing-programs/proof-aggregation.md new file mode 100644 index 0000000000..dc13d6e42c --- /dev/null +++ b/book/versioned_docs/version-3.4.0/writing-programs/proof-aggregation.md @@ -0,0 +1,58 @@ +# Proof Aggregation + +SP1 supports proof aggregation and recursion, which allows you to verify an SP1 proof within SP1. Use cases include: + +- Reducing on-chain verification costs by aggregating multiple SP1 proofs into a single SP1 proof. +- Proving logic that is split into multiple proofs, such as proving a statement about a rollup's state transition function by proving each block individually and aggregating these proofs to produce a final proof of a range of blocks. + +**For an example of how to use proof aggregation and recursion in SP1, refer to the [aggregation example](https://github.com/succinctlabs/sp1/blob/main/examples/aggregation/script/src/main.rs).** + +Note that to verify an SP1 proof inside SP1, you must generate a "compressed" SP1 proof (see [Proof Types](../generating-proofs/proof-types.md) for more details). + +### When to use aggregation + +Note that by itself, SP1 can already prove arbitrarily large programs by chunking the program's execution into multiple "shards" (contiguous batches of cycles) and generating proofs for each shard in parallel, and then recursively aggregating the proofs. Thus, aggregation is generally **not necessary** for most use-cases, as SP1's proving for large programs is already parallelized. However, aggregation can be useful for aggregating computations that require more than the zkVM's limited (~2GB) memory or for aggregating multiple SP1 proofs from different parties into a single proof to save on onchain verification costs. + +## Verifying Proofs inside the zkVM + +To verify a proof inside the zkVM, you can use the `sp1_zkvm::lib::verify::verify_sp1_proof` function. + +```rust +sp1_zkvm::lib::verify::verify_sp1_proof(vkey, public_values_digest); +``` + +**You do not need to pass in the proof as input into the syscall, as the proof will automatically be read for the proof input stream by the prover.** + +Note that you must include the `verify` feature in your `Cargo.toml` for `sp1-zkvm` to be able to use the `verify_proof` function (like [this](https://github.com/succinctlabs/sp1/blob/main/examples/aggregation/program/Cargo.toml#L11)). + +## Generating Proofs with Aggregation + +To provide an existing proof as input to the SP1 zkVM, you can use the existing `SP1Stdin` object +which is already used for all inputs to the zkVM. + +```rust +# Generating proving key and verifying key. +let (input_pk, input_vk) = client.setup(PROOF_INPUT_ELF); +let (aggregation_pk, aggregation_vk) = client.setup(AGGREGATION_ELF); + +// Generate a proof that will be recursively verified / aggregated. Note that we use the "compressed" +// proof type, which is necessary for aggregation. +let mut stdin = SP1Stdin::new(); +let input_proof = client + .prove(&input_pk, stdin) + .compressed() + .run() + .expect("proving failed"); + +// Create a new stdin object to write the proof and the corresponding verifying key to. +let mut stdin = SP1Stdin::new(); +stdin.write_proof(input_proof, input_vk); + +// Generate a proof that will recursively verify / aggregate the input proof. +let aggregation_proof = client + .prove(&aggregation_pk, stdin) + .compressed() + .run() + .expect("proving failed"); + +``` diff --git a/book/versioned_docs/version-3.4.0/writing-programs/setup.md b/book/versioned_docs/version-3.4.0/writing-programs/setup.md new file mode 100644 index 0000000000..2cd677f4a9 --- /dev/null +++ b/book/versioned_docs/version-3.4.0/writing-programs/setup.md @@ -0,0 +1,50 @@ +# Setup + +In this section, we will teach you how to setup a self-contained crate which can be compiled as a program that can be executed inside the zkVM. + +## Create Project with CLI (Recommended) + +The recommended way to setup your first program to prove inside the zkVM is using the method described in [Quickstart](../getting-started/quickstart.md) which will create a program folder. + +```bash +cargo prove new +cd program +``` + +## Manual Project Setup + +You can also manually setup a project. First create a new Rust project using `cargo`: + +```bash +cargo new program +cd program +``` + +### Cargo Manifest + +Inside this crate, add the `sp1-zkvm` crate as a dependency. Your `Cargo.toml` should look like the following: + +```rust +[workspace] +[package] +version = "0.1.0" +name = "program" +edition = "2021" + +[dependencies] +sp1-zkvm = "2.0.0" +``` + +The `sp1-zkvm` crate includes necessary utilities for your program, including handling inputs and outputs, +precompiles, patches, and more. + +### main.rs + +Inside the `src/main.rs` file, you must make sure to include these two lines to ensure that your program properly compiles to a valid SP1 program. + +```rust +#![no_main] +sp1_zkvm::entrypoint!(main); +``` + +These two lines of code wrap your main function with some additional logic to ensure that your program compiles correctly with the RISC-V target. diff --git a/book/versioned_sidebars/version-3.4.0-sidebars.json b/book/versioned_sidebars/version-3.4.0-sidebars.json new file mode 100644 index 0000000000..0e9b005f29 --- /dev/null +++ b/book/versioned_sidebars/version-3.4.0-sidebars.json @@ -0,0 +1,98 @@ +{ + "docs": [ + "introduction", + { + "type": "category", + "label": "Getting Started", + "items": [ + "getting-started/install", + "getting-started/quickstart", + "getting-started/hardware-requirements", + "getting-started/project-template" + ], + "collapsed": false + }, + { + "type": "category", + "label": "Writing Programs", + "items": [ + "writing-programs/basics", + "writing-programs/compiling", + "writing-programs/cycle-tracking", + "writing-programs/inputs-and-outputs", + "writing-programs/patched-crates", + "writing-programs/precompiles", + "writing-programs/proof-aggregation", + "writing-programs/setup" + ], + "collapsed": true + }, + { + "type": "category", + "label": "Generating Proofs", + "items": [ + "generating-proofs/basics", + "generating-proofs/setup", + "generating-proofs/proof-types", + "generating-proofs/recommended-workflow", + "generating-proofs/sp1-sdk-faq", + { + "type": "category", + "label": "Hardware Acceleration", + "link": { + "type": "doc", + "id": "generating-proofs/hardware-acceleration" + }, + "items": [ + "generating-proofs/hardware-acceleration", + "generating-proofs/hardware-acceleration/avx", + "generating-proofs/hardware-acceleration/cuda" + ] + }, + { + "type": "category", + "label": "Prover Network", + "link": { + "type": "doc", + "id": "generating-proofs/prover-network" + }, + "items": [ + "generating-proofs/prover-network/key-setup", + "generating-proofs/prover-network/usage", + "generating-proofs/prover-network/versions" + ] + }, + "generating-proofs/advanced" + ], + "collapsed": true + }, + { + "type": "category", + "label": "Verification", + "items": [ + "verification/off-chain-verification", + { + "type": "category", + "label": "On-Chain Verification", + "items": [ + "verification/onchain/getting-started", + "verification/onchain/contract-addresses", + "verification/onchain/solidity-sdk" + ] + } + ] + }, + { + "type": "category", + "label": "Developers", + "items": [ + "developers/common-issues", + "developers/usage-in-ci", + "developers/building-circuit-artifacts", + "developers/rv32im-specification" + ] + }, + "what-is-a-zkvm", + "why-use-sp1" + ] +} diff --git a/book/versions.json b/book/versions.json new file mode 100644 index 0000000000..af427f44cc --- /dev/null +++ b/book/versions.json @@ -0,0 +1,3 @@ +[ + "3.4.0" +]