-
Notifications
You must be signed in to change notification settings - Fork 393
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
66 changed files
with
21,439 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,20 @@ | ||
# Dependencies | ||
/node_modules | ||
|
||
# Production | ||
/build | ||
|
||
# Generated files | ||
.docusaurus | ||
.cache-loader | ||
|
||
# Misc | ||
.DS_Store | ||
.env.local | ||
.env.development.local | ||
.env.test.local | ||
.env.production.local | ||
|
||
npm-debug.log* | ||
yarn-debug.log* | ||
yarn-error.log* |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,41 @@ | ||
# Website | ||
|
||
This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator. | ||
|
||
### Installation | ||
|
||
``` | ||
$ yarn | ||
``` | ||
|
||
### Local Development | ||
|
||
``` | ||
$ yarn start | ||
``` | ||
|
||
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. | ||
|
||
### Build | ||
|
||
``` | ||
$ yarn build | ||
``` | ||
|
||
This command generates static content into the `build` directory and can be served using any static contents hosting service. | ||
|
||
### Deployment | ||
|
||
Using SSH: | ||
|
||
``` | ||
$ USE_SSH=true yarn deploy | ||
``` | ||
|
||
Not using SSH: | ||
|
||
``` | ||
$ GIT_USER=<Your GitHub username> yarn deploy | ||
``` | ||
|
||
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,45 @@ | ||
#!/bin/bash | ||
|
||
# Define an array of file paths | ||
paths=( | ||
"../examples/fibonacci/script/bin/execute.rs" | ||
"../examples/fibonacci/script/src/main.rs" | ||
"../examples/fibonacci/script/bin/groth16_bn254.rs" | ||
"../examples/fibonacci/script/build.rs" | ||
"../examples/fibonacci/script/src/main.rs" | ||
"../examples/groth16/program/src/main.rs" | ||
"../examples/groth16/script/src/main.rs" | ||
"../examples/io/program/src/main.rs" | ||
"../examples/cycle-tracking/program/bin/normal.rs" | ||
"../crates/zkvm/lib/src/lib.rs" | ||
"../examples/fibonacci/script/bin/compressed.rs" | ||
"../examples/fibonacci/program/src/main.rs" | ||
) | ||
|
||
# Ensure the ./static directory exists | ||
mkdir -p ./static | ||
|
||
# Loop over the paths and process each file | ||
for file in "${paths[@]}"; do | ||
if [[ -f "$file" ]]; then | ||
# Get the full path and strip everything before 'sp1/' | ||
stripped_path=$(readlink -f "$file" | sed -e 's|.*sp1/||') | ||
|
||
# Replace slashes with underscores for the target file name | ||
target_name=$(echo "$stripped_path" | tr '/' '_') | ||
|
||
# Define the target markdown file path | ||
target="./static/${target_name}.mdx" | ||
|
||
# Write the content into the markdown file | ||
{ | ||
echo "\`\`\`rust" | ||
cat "$file" | ||
echo "\`\`\`" | ||
} > "$target" | ||
|
||
echo "Processed $file -> $target" | ||
else | ||
echo "File not found: $file" | ||
fi | ||
done |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,147 @@ | ||
# Common Issues | ||
|
||
## Rust Version Errors | ||
|
||
If you are using a library that has an MSRV specified, you may encounter an error like this when building your program. | ||
|
||
```txt | ||
package `alloy v0.1.1 cannot be built because it requires rustc 1.76 or newer, while the currently active rustc version is 1.75.0-nightly` | ||
``` | ||
|
||
This is due to the fact that your current Succinct Rust toolchain has been built with a lower version than the MSRV of the crates you are using. | ||
|
||
You can check the version of your local Succinct Rust toolchain by running `cargo +succinct --version`. The latest release of the Succinct Rust toolchain is **1.81**. You can update to the latest version by running [`sp1up`](../getting-started/install.md). | ||
|
||
```shell | ||
% sp1up | ||
% cargo +succinct --version | ||
cargo 1.81.0-dev (2dbb1af80 2024-08-20) | ||
``` | ||
|
||
A Succinct Rust toolchain with version **1.81** should work for all crates that have an MSRV of **1.81** or lower. | ||
|
||
If the MSRV of your crate is higher than **1.81**, try the following: | ||
|
||
- If using `cargo prove build` directly, pass the `--ignore-rust-version` flag: | ||
|
||
```bash | ||
cargo prove build --ignore-rust-version | ||
``` | ||
|
||
- If using `build_program` in an `build.rs` file with the `sp1-build` crate, set `ignore_rust_version` to true inside the `BuildArgs` struct and use | ||
`build_program_with_args`: | ||
|
||
```rust | ||
let args = BuildArgs { | ||
ignore_rust_version: true, | ||
..Default::default() | ||
}; | ||
build_program_with_args("path/to/program", args); | ||
``` | ||
|
||
## `alloy_sol_types` Errors | ||
|
||
If you are using a library that depends on `alloy_sol_types`, and encounter an error like this: | ||
|
||
```txt | ||
perhaps two different versions of crate `alloy_sol_types` are being used? | ||
``` | ||
|
||
This is likely due to two different versions of `alloy_sol_types` being used. To fix this, you can set `default-features` to `false` for the `sp1-sdk` dependency in your `Cargo.toml`. | ||
|
||
```toml | ||
[dependencies] | ||
sp1-sdk = { version = "2.0.0", default-features = false } | ||
``` | ||
|
||
This will configure out the `network` feature which will remove the dependency on `alloy_sol_types` and configure out the `NetworkProver`. | ||
|
||
## Stack Overflow Errors + Bus Errors | ||
|
||
If you encounter any of the following errors in a script using `sp1-sdk`: | ||
|
||
```shell | ||
# Stack Overflow Error | ||
thread 'main' has overflowed its stack | ||
fatal runtime error: stack overflow | ||
|
||
# Bus Error | ||
zsh: bus error | ||
|
||
# Segmentation Fault | ||
Segmentation fault (core dumped) | ||
``` | ||
|
||
Run your script with the `--release` flag. SP1 currently only supports release builds. This is because | ||
the `sp1-core` library and `sp1-recursion` require being compiled with the `release` profile. | ||
|
||
## C Binding Errors | ||
|
||
If you are building a program that uses C bindings or has dependencies that use C bindings, you may encounter the following errors: | ||
|
||
```txt | ||
cc did not execute successfully | ||
``` | ||
|
||
```txt | ||
Failed to find tool. Is `riscv32-unknown-elf-gcc` installed? | ||
``` | ||
|
||
To resolve this, re-install sp1 with the `--c-toolchain` flag: | ||
|
||
```bash | ||
sp1up --c-toolchain | ||
``` | ||
|
||
This will install the C++ toolchain for RISC-V and set the `CC_riscv32im_succinct_zkvm_elf` environment | ||
variable to the path of the installed `riscv32-unknown-elf-gcc` binary. You can also use your own | ||
C++ toolchain be setting this variable manually: | ||
|
||
```bash | ||
export CC_riscv32im_succinct_zkvm_elf=/path/to/toolchain | ||
``` | ||
|
||
## Compilation Errors with [`sp1-lib::syscall_verify_sp1_proof`](https://docs.rs/sp1-lib/latest/sp1_lib/fn.syscall_verify_sp1_proof.html) | ||
|
||
If you are using the [`sp1-lib::syscall_verify_sp1_proof`](https://docs.rs/sp1-lib/latest/sp1_lib/fn.syscall_verify_sp1_proof.html) function, you may encounter compilation errors when building your program. | ||
|
||
```bash | ||
[sp1] = note: rust-lld: error: undefined symbol: syscall_verify_sp1_proof | ||
[sp1] >>> referenced by sp1_lib.b593533d149f0f6e-cgu.0 | ||
[sp1] >>> sp1_lib-8f5deb4c47d01871.sp1_lib.b593533d149f0f6e-cgu.0.rcgu.o:(sp1_lib::verify::verify_sp1_proof::h5c1bb38f11b3fe71) in ... | ||
[sp1] | ||
[sp1] | ||
[sp1] error: could not compile `package-name` (bin "package-name") due to 1 previous error | ||
``` | ||
|
||
To resolve this, ensure that you're importing both `sp1-lib` and `sp1-zkvm` with the verify feature enabled. | ||
|
||
```toml | ||
[dependencies] | ||
sp1-lib = { version = "<VERSION>", features = ["verify"] } | ||
sp1-zkvm = { version = "<VERSION>", features = ["verify"] } | ||
``` | ||
|
||
## `sp1-sdk` `rc` Version Semver Errors | ||
|
||
When using release candidate (RC) versions of `sp1-sdk` (such as `3.0.0-rc1`), you might face compilation errors if you upgrade to a newer RC version (like `3.0.0-rc4`) and then try to downgrade back to an earlier RC version (such as `3.0.0-rc1`). | ||
|
||
This issue arises because some RC releases introduce breaking changes that aren't reflected in their version numbers according to Semantic Versioning (SemVer) rules. To fix this, you need to explicitly downgrade all related crates in your `Cargo.lock` file to match the desired RC version. | ||
|
||
To start, verify that the `sp1-sdk` version in your `Cargo.lock` file differs from the version specified in your `Cargo.toml` file: | ||
|
||
```shell | ||
% cargo tree -i sp1-sdk | ||
sp1-sdk v3.0.0-rc4 (/Users/sp1/crates/sdk) | ||
├── sp1-cli v3.0.0-rc4 (/Users/sp1/crates/cli) | ||
├── sp1-eval v3.0.0-rc4 (/Users/sp1/crates/eval) | ||
└── sp1-perf v3.0.0-rc4 (/Users/sp1/crates/perf) | ||
``` | ||
|
||
After confirming the version of `sp1-sdk` in your lockfile, you can downgrade to a specific RC version using the following command. Replace `3.0.0-rc1` with the desired version number: | ||
|
||
```shell | ||
% cargo update -p sp1-build -p sp1-sdk -p sp1-recursion-derive -p sp1-recursion-gnark-ffi -p sp1-zkvm --precise 3.0.0-rc1 | ||
``` | ||
|
||
This command will update the `Cargo.lock` file to specify the lower RC version, resolving any version conflicts and allowing you to continue development. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,68 @@ | ||
import Compressed from "../../static/examples_fibonacci_script_bin_compressed.rs.mdx"; | ||
import Execute from "../../static/examples_fibonacci_script_bin_execute.rs.mdx"; | ||
|
||
# Advanced Usage | ||
|
||
## Execution Only | ||
|
||
We recommend that during the development of large programs (> 1 million cycles) you do not generate proofs each time. | ||
Instead, you should have your script only execute the program with the RISC-V runtime and read `public_values`. Here is an example: | ||
|
||
<Execute /> | ||
|
||
If the execution of your program succeeds, then proof generation should succeed as well! (Unless there is a bug in our zkVM implementation.) | ||
|
||
## Compressed Proofs | ||
|
||
With the `ProverClient`, the default `prove` function generates a proof that is succinct, but can have size that scales with the number of cycles of the program. To generate a compressed proof of constant size, you can use the `prove_compressed` function instead. This will use STARK recursion to generate a proof that is constant size (around 7Kb), but will be slower than just calling `prove`, as it will use recursion to combine the core SP1 proof into a single constant-sized proof. | ||
|
||
<Compressed /> | ||
|
||
You can run the above script with `RUST_LOG=info cargo run --bin compressed --release` from `examples/fibonacci/script`. | ||
|
||
## Logging and Tracing Information | ||
|
||
You can use `utils::setup_logger()` to enable logging information respectively. You should only use one or the other of these functions. | ||
|
||
**Logging:** | ||
|
||
```rust | ||
utils::setup_logger(); | ||
``` | ||
|
||
You must run your command with: | ||
|
||
```bash | ||
RUST_LOG=info cargo run --release | ||
``` | ||
|
||
## CPU Acceleration | ||
|
||
To enable CPU acceleration, you can use the `RUSTFLAGS` environment variable to enable the `target-cpu=native` flag when running your script. This will enable the compiler to generate code that is optimized for your CPU. | ||
|
||
```bash | ||
RUSTFLAGS='-C target-cpu=native' cargo run --release | ||
``` | ||
|
||
Currently there is support for AVX512 and NEON SIMD instructions. For NEON, you must also enable the `sp1-sdk` feature `neon` in your script crate's `Cargo.toml` file. | ||
|
||
```toml | ||
sp1-sdk = { version = "2.0.0", features = ["neon"] } | ||
``` | ||
|
||
## Performance | ||
|
||
For maximal performance, you should run proof generation with the following command and vary your `shard_size` depending on your program's number of cycles. | ||
|
||
```rust | ||
SHARD_SIZE=4194304 RUST_LOG=info RUSTFLAGS='-C target-cpu=native' cargo run --release | ||
``` | ||
|
||
## Memory Usage | ||
|
||
To reduce memory usage, set the `SHARD_BATCH_SIZE` environment variable depending on how much RAM | ||
your machine has. A higher number will use more memory, but will be faster. | ||
|
||
```rust | ||
SHARD_BATCH_SIZE=1 SHARD_SIZE=2097152 RUST_LOG=info RUSTFLAGS='-C target-cpu=native' cargo run --release | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
import Example from "../../static/examples_fibonacci_script_src_main.rs.mdx"; | ||
|
||
# Basics | ||
|
||
All the methods you'll need for generating proofs are included in the `sp1_sdk` crate. Most importantly, you'll need to use the `ProverClient` to setup a proving key and verifying key for your program and then use the `execute`, `prove` and `verify` methods to execute your program, and generate and verify proofs. | ||
|
||
To make this more concrete, let's walk through a simple example of generating a proof for a Fibonacci program inside the zkVM. | ||
|
||
## Example: Fibonacci | ||
|
||
<Example /> | ||
|
||
You can run the above script in the `script` directory with `RUST_LOG=info cargo run --release`. Note that running the above script will generate a proof locally. | ||
|
||
<div class="warning"> | ||
WARNING: Local proving often is much slower than the prover network and for certain proof types (e.g. Groth16, PLONK) require a significant amount of RAM and will likely not work on a laptop. | ||
</div> | ||
|
||
We recommend using the [prover network](./prover-network.md) to generate proofs. Read more about the [recommended workflow](./recommended-workflow.md) for developing with SP1. |
Oops, something went wrong.