docs: official contracts (#1026)

Author: jtguibas

book/SUMMARY.md

@@ -34,16 +34,20 @@
 
 - [Advanced](./generating-proofs/advanced.md)
 
+# Onchain Verification
+
+- [Getting Started](./onchain-verification/getting-started.md)
+
+- [Solidity SDK](./onchain-verification/solidity-sdk.md)
+
+- [Contract Addresses](./onchain-verification/contract-addresses.md)
+
 # Prover Network
 
 - [Setup](./prover-network/setup.md)
 
 - [Usage](./prover-network/usage.md)
 
-# Verifying Proofs
-
-- [Solidity & EVM](./verifying-proofs/solidity-and-evm.md)
-
 # Developers
 
 - [Building Plonk Bn254 Artifacts](./developers/building-plonk-artifacts.md)

book/onchain-verification/contract-addresses.md

@@ -0,0 +1,43 @@
+# Contract Addresses
+
+When using SP1, we recommend using our deployed verifiers. Each contract is a [SP1VerifierGateway](https://github.com/succinctlabs/sp1-contracts/blob/main/contracts/src/ISP1VerifierGateway.sol) which can automatically routes your SP1 proof to the correct verifier based on the prover version.
+
+
+| Chain ID | Chain            | Gateway                                                                                                                         |
+|----------|------------------|---------------------------------------------------------------------------------------------------------------------------------|
+| 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)    |
+| 534351   | Scroll Sepolia   | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://sepolia.scrollscan.com/address/0x3B6041173B80E77f038f3F2C0f9744f04837185e) |
+| 534352   | Scroll           | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://scrollscan.com/address/0x3B6041173B80E77f038f3F2C0f9744f04837185e)         |
+| 8453     | Base             | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://basescan.org/address/0x3B6041173B80E77f038f3F2C0f9744f04837185e)           |
+| 84532    | Base Sepolia     | [0x3B6041173B80E77f038f3F2C0f9744f04837185e](https://sepolia.basescan.org/address/0x3B6041173B80E77f038f3F2C0f9744f04837185e)   |
+
+**Currently officially supported versions of SP1 are v1.0.7 and v1.0.8.** If you'd like official support for a verifier on a different chain, please ask in the [SP1 Telegram](https://t.me/succinct_sp1).
+
+## 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;
+}
+```

book/onchain-verification/getting-started.md

@@ -0,0 +1,33 @@
+# Onchain Verification
+
+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) for the addresses of the deployed verifiers.
+
+## Generating SP1 Proof 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 PLONK prover is only guaranteed to work on official releases of SP1. To use PLONK proving & verification locally, ensure that you have Docker installed.
+
+### Example
+
+```rust,noplayground
+{{#include ../../examples/fibonacci/script/bin/plonk_bn254.rs}}
+```
+
+You can run the above script with `RUST_LOG=info cargo run --bin plonk_bn254 --release` in `examples/fibonacci/script`.
+
+#### Using PLONK without Docker (Advanced)
+
+If you would like to run the PLONK prover directly without Docker, you must have Go 1.22 installed and enable the `native-plonk` feature in `sp1-sdk`. This path is not recommended and may require additional native dependencies.
+
+```toml
+sp1-sdk = { features = ["native-plonk"] }
+```
+
+

book/onchain-verification/solidity-sdk.md

@@ -0,0 +1,70 @@
+# Solidity SDK
+
+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@<version>
+```
+
+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://github.com/succinctlabs/sp1-contracts/tree/main/contracts/deployments
+    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 proof The encoded proof.
+    /// @param publicValues The encoded public values.
+    function verifyFibonacciProof(bytes calldata proof, bytes calldata publicValues)
+        public
+        view
+        returns (uint32, uint32, uint32)
+    {
+        ISP1Verifier(verifier).verifyProof(fibonacciProgramVkey, publicValues, proof);
+        (uint32 n, uint32 a, uint32 b) = abi.decode(publicValues, (uint32, uint32, uint32));
+        return (n, a, b);
+    }
+}
+```
+
+For more details on the contracts, refer to the [sp1-contracts](https://github.com/succinctlabs/sp1-contracts) repo.
+
+### 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).

book/verifying-proofs/solidity-and-evm.md

@@ -91,7 +91,7 @@ impl SP1PublicValues {
         }
     }
 
-    pub fn bytes(&self) -> String {
+    pub fn raw(&self) -> String {
         format!("0x{}", hex::encode(self.buffer.data.clone()))
     }
 

core/src/io.rs

@@ -16,16 +16,17 @@ fn main() {
     // Generate the proof for the given program and input.
     let client = ProverClient::new();
     let (pk, vk) = client.setup(ELF);
-    let mut proof = client.prove(&pk, stdin).plonk().run().unwrap();
+    let proof = client.prove(&pk, stdin).plonk().run().unwrap();
 
     println!("generated proof");
 
-    // Read and verify the output.
-    let _ = proof.public_values.read::<u32>();
-    let a = proof.public_values.read::<u32>();
-    let b = proof.public_values.read::<u32>();
-    println!("a: {}", a);
-    println!("b: {}", b);
+    // Get the public values as bytes.
+    let public_values = proof.public_values.raw();
+    println!("public values: {:?}", public_values);
+
+    // Get the proof as bytes.
+    let solidity_proof = proof.raw();
+    println!("proof: {:?}", solidity_proof);
 
     // Verify proof and public values
     client.verify(&proof, &vk).expect("verification failed");

examples/fibonacci/script/bin/plonk_bn254.rs

@@ -39,6 +39,14 @@ impl SP1ProofWithPublicValues {
         bincode::deserialize_from(File::open(path).expect("failed to open file"))
             .map_err(Into::into)
     }
+
+    /// Returns the raw proof as a string.
+    pub fn raw(&self) -> String {
+        match &self.proof {
+            SP1Proof::Plonk(plonk) => plonk.raw_proof.clone(),
+            _ => unimplemented!(),
+        }
+    }
 }
 
 pub type SP1CoreProofVerificationError = MachineVerificationError<CoreSC>;