checkout book and examples

succinctlabs · Nov 6, 2024 · 366d3a1 · 366d3a1
1 parent 579993c
commit 366d3a1
Show file tree

Hide file tree

Showing 42 changed files with 8,170 additions and 118 deletions.
diff --git a/book/SUMMARY.md b/book/SUMMARY.md
@@ -57,13 +57,14 @@
 
 - [FAQ](./generating-proofs/sp1-sdk-faq.md)
 
-# Onchain Verification
+# Verification
 
-- [Setup](./onchain-verification/getting-started.md)
+- [On-chain Verification](./verification/onchain/getting-started.md)
 
-- [Solidity Verifier](./onchain-verification/solidity-sdk.md)
+  - [Solidity Verifier](./verification/onchain/solidity-sdk.md)
+  - [Contract Addresses](./verification/onchain/contract-addresses.md)
 
-- [Contract Addresses](./onchain-verification/contract-addresses.md)
+- [Off-chain Verification](./verification/off-chain-verification.md)
 
 # Developers
 

diff --git a/book/developers/common-issues.md b/book/developers/common-issues.md
@@ -1,46 +1,28 @@
 # Common Issues
 
-## Bus Error
-
-If you are running a executable that uses the `sp1-sdk` crate, you may encounter a bus error like this:
-
-```txt
-zsh: bus error
-```
-
-This is fixed by running with the `--release` flag, as the `sp1-sdk` crate only supports release builds as of right now.
-
-## Alloy Errors
+## Rust Version Errors
 
-If you are using a library that depends on `alloy_sol_types`, and encounter an error like this:
+If you are using a library that has an MSRV specified, you may encounter an error like this when building your program.
 
 ```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 }
+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 will configure out the `network` feature which will remove the dependency on `alloy_sol_types` and configure out the `NetworkProver`.
-
-## Rust Version Errors
+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. 
 
-If you are using a library that has an MSRV (minimum supported rust version) of 1.76.0
-or higher, you may encounter an error like this when building your program.
+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).
 
-```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`
+```shell
+% sp1up
+% cargo +succinct --version
+cargo 1.81.0-dev (2dbb1af80 2024-08-20)
 ```
 
-This is due to the fact that the Succinct Rust toolchain might be built with a lower version than the MSRV of the crates you are using. You can check the version of the Succinct Rust toolchain by running `cargo +succinct --version`. The Succinct Rust toolchain's latest version is 1.79, and you can update to the latest version by running [`sp1up`](../getting-started/install.md).
+A Succinct Rust toolchain with version **1.81** should work for all crates that have an MSRV of **1.81** or lower.
 
-If that doesn't work (i.e. the MSRV of the crates you are using is still higher than the version of the Succinct Rust toolchain), you can try the following:
+If the MSRV of your crate is higher than **1.81**, try the following:
 
-- If you're using `cargo prove build` directly, pass the `--ignore-rust-version` flag:
+- If using `cargo prove build` directly, pass the `--ignore-rust-version` flag:
 
   ```bash
   cargo prove build --ignore-rust-version
@@ -57,22 +39,41 @@ If that doesn't work (i.e. the MSRV of the crates you are using is still higher
   build_program_with_args("path/to/program", args);
   ```
 
-## Stack Overflow Errors
+## `alloy_sol_types` Errors
 
-If you encounter the following in a script using `sp1-sdk`:
+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
-```
 
-```txt
+# Bus Error
+zsh: bus error
+
+# Segmentation Fault
 Segmentation fault (core dumped)
 ```
 
-Re-run your script with `--release`.
-
-Note that the core `sp1-core` library and `sp1-recursion` require being compiled with the `release` profile.
+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
 
@@ -120,3 +121,27 @@ To resolve this, ensure that you're importing both `sp1-lib` and `sp1-zkvm` with
 sp1-lib = { version = "<VERSION>", features = ["verify"] }
 sp1-zkvm = { version = "<VERSION>", features = ["verify"] }
 ```
+
+## `sp1-sdk` `rc` Version Semver Errors
+
+When using release candidate (RC) versions of `sp1-sdk` (such as `3.0.0-rc1`), you might face compilation errors if you upgrade to a newer RC version (like `3.0.0-rc4`) and then try to downgrade back to an earlier RC version (such as `3.0.0-rc1`).
+
+This issue arises because some RC releases introduce breaking changes that aren't reflected in their version numbers according to Semantic Versioning (SemVer) rules. To fix this, you need to explicitly downgrade all related crates in your `Cargo.lock` file to match the desired RC version.
+
+To start, verify that the `sp1-sdk` version in your `Cargo.lock` file differs from the version specified in your `Cargo.toml` file:
+
+```shell
+% cargo tree -i sp1-sdk
+sp1-sdk v3.0.0-rc4 (/Users/sp1/crates/sdk)
+├── sp1-cli v3.0.0-rc4 (/Users/sp1/crates/cli)
+├── sp1-eval v3.0.0-rc4 (/Users/sp1/crates/eval)
+└── sp1-perf v3.0.0-rc4 (/Users/sp1/crates/perf)
+```
+
+After confirming the version of `sp1-sdk` in your lockfile, you can downgrade to a specific RC version using the following command. Replace `3.0.0-rc1` with the desired version number:
+
+```shell
+%  cargo update -p sp1-build -p sp1-sdk -p sp1-recursion-derive -p sp1-recursion-gnark-ffi -p sp1-zkvm --precise 3.0.0-rc1
+```
+
+This command will update the `Cargo.lock` file to specify the lower RC version, resolving any version conflicts and allowing you to continue development.
diff --git a/book/generating-proofs/proof-types.md b/book/generating-proofs/proof-types.md
@@ -28,7 +28,7 @@ client.prove(&pk, stdin).compressed().run().unwrap();
 
 ## Groth16 (Recommended)
 
-The Groth16 prover mode generate a SNARK proof that is ~260 bytes large and can be verified onchain for around ~270k gas. 
+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.
 
@@ -39,7 +39,7 @@ client.prove(&pk, stdin).groth16().run().unwrap();
 
 ## PLONK
 
-The PLONK prover mode generate 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.
+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.
 

diff --git a/book/getting-started/quickstart.md b/book/getting-started/quickstart.md
@@ -6,10 +6,12 @@ In this section, we will show you how to create a simple Fibonacci program using
 
 ### Option 1: Cargo Prove New CLI (Recommended)
 
-You can use the `cargo prove` CLI to create a new project using the `cargo prove new <name>` command. This command will create a new folder in your current directory.
+You can use the `cargo prove` CLI to create a new project using the `cargo prove new <--bare|--evm> <name>` 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 fibonacci
+cargo prove new --evm fibonacci
 cd fibonacci
 ```
 
@@ -73,7 +75,7 @@ Note: the `build.rs` file in the `script` directory will use run the above comma
 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
+cd ../script
 RUST_LOG=info cargo run --release -- --execute
 ```
 
@@ -82,7 +84,7 @@ RUST_LOG=info cargo run --release -- --execute
 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
+cd ../script
 RUST_LOG=info cargo run --release -- --prove
 ```
 

diff --git a/book/sp1.png b/book/sp1.png
diff --git a/book/verification/off-chain-verification.md b/book/verification/off-chain-verification.md
@@ -0,0 +1,49 @@
+# 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.md#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`.
+
+```rust,noplayground
+{{#include ../../examples/groth16/program/src/main.rs}}
+```
+
+Here, the proof, public inputs, and vkey hash are read from stdin. See the following snippet to see how these values are generated.
+
+```rust,noplayground
+{{#include ../../examples/groth16/script/src/main.rs:12:34}}
+```
+
+> 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/verification/onchain/contract-addresses.md b/book/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;
+}
+```