chore: update docs (#1032)

book/SUMMARY.md

@@ -2,6 +2,10 @@
 
 [Introduction](./introduction.md)
 
+[Why use SP1?](./why-use-sp1.md)
+
+[What is a zkVM?](./what-is-a-zkvm.md)
+
 # Getting Started
 
 - [Install](./getting-started/install.md)
@@ -10,6 +14,8 @@
 
 - [Project Template](./getting-started/project-template.md)
 
+- [Hardware Requirements](./getting-started/hardware-requirements.md)
+
 # Writing Programs
 
 - [Setup](./writing-programs/setup.md)
@@ -26,17 +32,23 @@
 
 - [Proof Aggregation](./writing-programs/proof-aggregation.md)
 
+- [Build Script](./writing-programs/build-script.md)
+
 # Generating Proofs
 
 - [Setup](./generating-proofs/setup.md)
 
 - [Basics](./generating-proofs/basics.md)
 
-- [Advanced](./generating-proofs/advanced.md)
+- [Prover Options](./generating-proofs/prover-options.md)
+
+- [Development Options](./generating-proofs/development-options.md)
+
+- [Optimizing Performance](./generating-proofs/optimizing-performance.md)
 
 # Onchain Verification
 
-- [Getting Started](./onchain-verification/getting-started.md)
+- [Setup](./onchain-verification/getting-started.md)
 
 - [Solidity SDK](./onchain-verification/solidity-sdk.md)
 
@@ -50,6 +62,6 @@
 
 # Developers
 
-- [Building Plonk Bn254 Artifacts](./developers/building-plonk-artifacts.md)
+- [Building PLONK Artifacts](./developers/building-plonk-artifacts.md)
 
 - [Common Issues](./developers/common-issues.md)

book/developers/building-plonk-artifacts.md

@@ -1,18 +1,8 @@
-# Building Plonk BN254 Artifacts
+# Building PLONK Artifacts
 
 To build the production Plonk Bn254 artifacts from scratch, you can use the `Makefile` inside the `prover` directory.
 
 ```shell,noplayground
 cd prover
 RUST_LOG=info make build-plonk-bn254
-```
-
-## Non-production builds
-
-For quickly building the plonk artifacts, you can run `cargo test` with additional flags to speed up the build process.
-
-```shell,noplayground
-SP1_DEV=true FRI_QUERIES=1 cargo test --release test_e2e_prove_plonk
-```
-
-The generated artifacts should only be used for development and testing purposes.
+```

book/generating-proofs/basics.md

@@ -1,49 +1,13 @@
 # Generating Proofs: Basics
 
-An end-to-end flow of proving `f(x) = y` with the SP1 zkVM involves the following steps:
-
-- Define `f` using normal Rust code and compile it to an ELF (covered in the [writing programs](../writing-programs/basics.md) section).
-- Setup a proving key (`pk`) and verifying key (`vk`) for the program given the ELF. The proving key contains all the information needed to generate a proof and includes some post-processing on top of the ELF, while the verifying key is a compact representation of the ELF that contains all the information needed to verify a proof and is much smaller than the ELF itself.
-- Generate a proof `π` using the SP1 zkVM that `f(x) = y` with `prove(pk, x)`.
-- Verify the proof `π` using `verify(vk, x, y, π)`.
+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 `prove` and `verify` methods to generate and verify proofs.
 
 To make this more concrete, let's walk through a simple example of generating a proof for a Fiboancci program inside the zkVM.
 
-## Fibonacci
+## Example: Fibonacci
 
 ```rust,noplayground
 {{#include ../../examples/fibonacci/script/src/main.rs}}
 ```
 
-You can run the above script in the `script` directory with `RUST_LOG=info cargo run --release`.
-
-## Build Script
-
-> WARNING: This may not generate a reproducible ELF which is necessary for verifying that your binary corresponds to given source code.
->
-> When building a ELF that will be used in production, make sure to use the [reproduction build system](../writing-programs/setup.md#build-with-docker-production).
-
-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`):
-
-```rust,noplayground
-{{#include ../../examples/fibonacci/script/build.rs}}
-```
-
-Make sure to also add `sp1-helper` as a build dependency in `script/Cargo.toml`:
-
-```toml
-[build-dependencies]
-sp1-helper = { git = "https://github.com/succinctlabs/sp1.git" }
-```
-
-If you run `RUST_LOG=info cargo run --release -vv`, you will see the following output 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```
-````
+You can run the above script in the `script` directory with `RUST_LOG=info cargo run --release`.

book/generating-proofs/development-options.md

@@ -0,0 +1,26 @@
+# Development Options
+
+## 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:
+
+```rust,noplayground
+{{#include ../../examples/fibonacci/script/bin/execute.rs}}
+```
+
+If the execution of your program succeeds, then proof generation should succeed as well! (Unless there is a bug in our zkVM implementation.)
+
+## Logging and Tracing Information
+
+You can use `sp1_sdk::utils::setup_logger()` to enable logging information respectively. You can set the logging level with the `RUST_LOG` environment variable.
+
+```rust,noplayground
+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
+```

book/generating-proofs/optimizing-performance.md

@@ -0,0 +1,23 @@
+# Optimizing Performance
+
+## CPU Acceleration
+
+SP1 supports CPU hardware acceleration using AVX256/512 and NEON SIMD instructions. To enable the acceleration, you can use the `RUSTFLAGS` environment variable to generate code that is optimized for your CPU.
+
+**AVX256 / NEON**:
+```bash
+RUSTFLAGS='-C target-cpu=native' cargo run --release
+```
+
+**AVX512**:
+```bash
+RUSTFLAGS='-C target-cpu=native -C target_feature=+avx512ifma,+avx512vl' cargo run --release
+```
+
+## Enviroment Variables (Advanced)
+
+`SHARD_SIZE`: The number of cycles that will be proven in each "shard" in the SP1 zkVM. This value
+must be set to a power of two. 
+
+`SHARD_BATCH_SIZE`: The number of shards that will be proven in parallel. This value can be tuned
+depending on how much memory your machine has to improve performance.

book/generating-proofs/prover-options.md

@@ -0,0 +1,38 @@
+# Prover Options
+
+The prover options can be configured using a "builder" pattern after creating a `ProverClient` and 
+calling `prove` on it.
+
+For a full list of options, see the [SP1 SDK](https://github.com/succinctlabs/sp1/blob/dev/sdk/src/action.rs).
+
+## 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,noplayground
+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**.
+
+```rust,noplayground
+let client = ProverClient::new();
+client.prove(&pk, stdin).compressed().run().unwrap();
+```
+
+## PLONK
+
+> WARNING: The PLONK prover requires around 128GB of RAM and is only guaranteed to work on official releases of SP1.
+
+The PLONK prover mode generates a SNARK proof with extremely small proof size and low verification cost.
+This mode is necessary for generating proofs that can be verified onchain for around ~300k gas.
+
+```rust,noplayground
+let client = ProverClient::new();
+client.prove(&pk, stdin).plonk().run().unwrap();
+```

book/getting-started/hardware-requirements.md

@@ -0,0 +1,34 @@
+# Hardware Requirements
+
+The hardware requirements for SP1 depend on what features you want to use. These requirements 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                    | PLONK (EVM)                |
+|----------------|------------------------------|------------------------------------|----------------------------|
+| CPU            | 1+, single-core perf matters | 16+, more is better                | 32+, more is better        |
+| Memory         | 8GB+, more is better         | 32GB+, more if you have more cores | 128GB+ (for PLONK)         |
+| Disk           | 20GB+                        | 20GB+                              | 100GB+ (for trusted setup) |
+| 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 PLONK prover, which requires around 128GB of RAM to generate a proof. We use PLONK to avoid
+having to perform a trusted setup, which other SNARK provers like Groth16 require. We have future optimizations planned to reduce
+the memory requirements of the PLONK prover substantially.
+
+### Disk
+
+Disk is required to install the SP1 zkVM toolchain and to install the trused setup artifacts, if you plan to locally build the PLONK prover.
+
+Furthermore, disk is used to checkpoint the state of the program execution, which is required to generate the proofs. 

book/onchain-verification/getting-started.md

@@ -1,4 +1,4 @@
-# Onchain Verification
+# 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).
 
@@ -8,11 +8,11 @@ The best way to get started with verifying SP1 proofs on-chain is to refer to th
 
 Refer to the section on [Contract Addresses](./contract-addresses.md) for the addresses of the deployed verifiers.
 
-## Generating SP1 Proof for Onchain Verification
+## 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 PLONK prover is only guaranteed to work on official releases of SP1. To use PLONK proving & verification locally, ensure that you have Docker installed.
+> 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 and have at least 128GB of RAM.
 
 ### Example
 

book/prover-network/setup.md

@@ -1,22 +1,25 @@
 # Prover Network: Setup
 
+> **Currently, the supported version of SP1 on the prover network is `v1.0.5-testnet`.**
+
 So far we've explored how to generate proofs locally, but this can actually be inconvenient on local machines due to high memory / CPU requirements, especially for very large programs.
 
-Succinct [has been building](https://blog.succinct.xyz/succinct-network/) the Succinct 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.
+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.
 
-## Get access
+## Get your key whitelisted
 
 **[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](#key-setup) steps below.
 
-### Key Setup
+## Key Setup
 
-The prover network uses secp256k1 keypairs for authentication, like Ethereum wallets. You may generate a new keypair explicitly for use with the prover network, or use an existing keypair. Currently you do not need to hold any funds in this account, it is used solely for access control.
+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 new keypair with `cast`
 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):
+First install [Foundry](https://book.getfoundry.sh/getting-started/installation#using-foundryup):
 
 ```sh
 curl -L https://foundry.paradigm.xyz | bash

book/prover-network/usage.md

@@ -1,5 +1,7 @@
 # Prover Network: Usage
 
+> **Currently, the supported version of SP1 on the prover network is `v1.0.5-testnet`.**
+
 ## 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:

book/what-is-a-zkvm.md

@@ -0,0 +1,14 @@
+# 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). 

book/why-use-sp1.md

@@ -0,0 +1,17 @@
+# Why use SP1?
+
+Zero-knowledge proofs (ZKPs) are a powerful primitive that enable developers to outsource verifiable computation to provers. But ZKP adoption has been held back because it is “moon math”, requiring specialized knowledge in obscure ZKP frameworks and hard to maintain one-off deployments. 
+
+Performant, general-purpose zkVMs, like SP1, will obsolete the current paradigm of specialized teams hand rolling their own custom ZK stack and create a future where all blockchain infrastructure, including rollups, bridges, coprocessors, and more, utilize ZKPs **via maintainable software written in Rust (or other LLVM-compiled languages)**.
+
+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 fraud proofs based on zero-knowledge 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 accessing 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 Reth](https://github.com/succinctlabs/sp1-reth): A performant, type-1 zkEVM written in Rust & SP1.
+- [SP1 Tendermint](https://github.com/succinctlabs/sp1-tendermint-example): An example of a ZK Tendermint light client on Ethereum powered by SP1.
+- and many more!
+

book/writing-programs/basics.md

@@ -1,15 +1,8 @@
 # Writing Programs: Basics 
 
-A zero-knowledge proof generally proves that some function `f` when applied to some input `x` produces some output `y` (i.e. `f(x) = y`).
-In the context of the SP1 zkVM:
+The easiest way to understand how to write programs for the SP1 zkVM is to look at some examples.
 
-- `f` is written in normal Rust code.
-- `x` are bytes that can be serialized / deserialized into objects
-- `y` are bytes that can be serialized / deserialized into objects
-
-To make this more concrete, let's walk through a simple example of writing a Fibonacci program inside the zkVM.
-
-## Fibonacci
+## 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.
 

book/writing-programs/build-script.md

@@ -0,0 +1,30 @@
+# Build Script
+
+> WARNING: This may not generate a reproducible ELF which is necessary for verifying that your binary corresponds to given source code.
+>
+> When building a ELF that will be used in production, make sure to use the [reproduction build system](../writing-programs/setup.md#build-with-docker-production).
+
+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`):
+
+```rust,noplayground
+{{#include ../../examples/fibonacci/script/build.rs}}
+```
+
+Make sure to also add `sp1-helper` as a build dependency in `script/Cargo.toml`:
+
+```toml
+[build-dependencies]
+sp1-helper = { git = "https://github.com/succinctlabs/sp1.git" }
+```
+
+If you run `RUST_LOG=info cargo run --release -vv`, you will see the following output 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```
+````