Sitelet https://github.com/Galoretka/sp1/commit/c6ddc2e941c5fa17e0e3b703eb9a274f5bfdae0b
Skip to content

Commit c6ddc2e

Browse files
ratankalianiratankaliani
authored
chore: book + tracing (succinctlabs#1932)
1 parent 43b82ce commit c6ddc2e

10 files changed

Lines changed: 126 additions & 75 deletions

File tree

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,3 +52,9 @@ examples/fibonacci/fibonacci-plonk.bin
5252

5353
# C++
5454
.vscode/c_cpp_properties.json
55+
56+
**/.yarn
57+
**/yarn.lock
58+
book/.pnp.cjs
59+
book/.pnp.loader.mjs
60+
book/.yarnrc.yml

‎book/docs/developers/common-issues.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
If you are using a library that has an MSRV specified, you may encounter an error like this when building your program.
66

77
```txt
8-
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`
8+
package `alloy cannot be built because it requires rustc 1.83 or newer, while the currently active rustc version is 1.81.0`
99
```
1010

1111
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.
@@ -18,9 +18,9 @@ You can check the version of your local Succinct Rust toolchain by running `carg
1818
cargo 1.81.0-dev (2dbb1af80 2024-08-20)
1919
```
2020

21-
A Succinct Rust toolchain with version **1.81** should work for all crates that have an MSRV of **1.81** or lower.
21+
A Succinct Rust toolchain with version **1.82** should work for all crates that have an MSRV of **1.82** or lower.
2222

23-
If the MSRV of your crate is higher than **1.81**, try the following:
23+
If the MSRV of your crate is higher than **1.82**, try the following:
2424

2525
- If using `cargo prove build` directly, pass the `--ignore-rust-version` flag:
2626

‎book/docs/verification/off-chain-verification.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ import ProgramScript from "@site/static/examples_groth16_script_src_main.rs.mdx"
77

88
You can verify SP1 Groth16 and Plonk proofs in `no_std` environments with [`sp1-verifier`](https://docs.rs/sp1-verifier/latest/sp1_verifier/).
99

10-
`sp1-verifier` is also patched to verify Groth16 and Plonk proofs within the SP1 ZKVM, using
10+
`sp1-verifier` is also patched to verify Groth16 and Plonk proofs within the SP1 zkVM, using
1111
[bn254](https://blog.succinct.xyz/succinctshipsprecompiles/) precompiles. For an example of this, see
1212
the [Groth16 Example](https://github.com/succinctlabs/sp1/tree/main/examples/groth16/).
1313

‎book/docs/writing-programs/compiling.mdx‎

Lines changed: 24 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -6,17 +6,21 @@ Once you have written an SP1 program, you must compile it to an ELF file that ca
66

77
## Development Builds
88

9-
> WARNING: This may not generate a reproducible ELF which is necessary for verifying that your binary corresponds to given source code.
9+
> WARNING: Running `cargo prove build` may not generate a reproducible ELF which is necessary for verifying that your binary corresponds to given source code.
1010
>
11-
> Use the [reproducible build system](#production-builds) for production builds.
11+
> Use SP1's [reproducible build system](#production-builds) for production builds.
1212
1313
To build a program while developing, simply run the following command in the crate that contains your SP1 program:
1414

1515
```bash
16+
# Enter the directory containing your SP1 program.
17+
cd path/to/your/program
18+
19+
# Build the program.
1620
cargo prove build
1721
```
1822

19-
This will compile the ELF that can be executed in the zkVM. The output from the command will look something like this:
23+
This will compile the ELF that can be executed in the zkVM. The output from the command will look similar to this:
2024

2125
```bash
2226
[sp1] Compiling version_check v0.9.4
@@ -34,17 +38,27 @@ Under the hood, this CLI command calls `cargo build` with the `riscv32im-succinc
3438

3539
### Advanced Build Options
3640

37-
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.
41+
The `cargo prove build` command supports several configuration options to customize the build process for your program:
42+
43+
- `--features`: Enable specific features
44+
- `--output-directory`: Specify a custom output location for the ELF
45+
- `--elf-name`: Set a custom name for the output ELF file
46+
- `--no-default-features`: Disable default features
47+
- `--locked`: Ensure Cargo.lock remains unchanged
48+
- `--packages`: Build only specified packages
49+
- `--binaries`: Build only specified binaries
50+
51+
Run `cargo prove build --help` to see the complete list of options. Some options mirror those available in the standard `cargo build` command.
3852

3953
## Production Builds
4054

41-
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:
55+
For production builds, use Docker to generate a **reproducible ELF** that will be identical across all platforms. Simply add the `--docker` flag to your build command. You can also specify a release version using `--tag`, otherwise the tag defaults to the latest release. For example:
4256

4357
```bash
44-
cargo prove build --docker --tag v1.0.1
58+
cargo prove build --docker --tag v4.0.0
4559
```
4660

47-
To verify that your build is reproducible, you can compute the SHA-512 hash of the ELF on different platforms and systems with:
61+
To verify that your build is truly reproducible across different platforms and systems, compute the SHA-512 hash of the generated ELF file. The hash should be identical regardless of where you build it:
4862

4963
```bash
5064
$ shasum -a 512 elf/riscv32im-succinct-zkvm-elf
@@ -82,19 +96,17 @@ The above output was generated by running `RUST_LOG=info cargo run --release -vv
8296

8397
To configure the build process when using the `sp1-build` crate, you can pass a [`BuildArgs`](https://docs.rs/sp1-build/latest/sp1_build/struct.BuildArgs.html) struct to to the [`build_program_with_args`](https://docs.rs/sp1-build/latest/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.
8498

85-
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:
99+
As an example, you could use the following code to build the Fibonacci example with the `docker` flag set to `true` and a custom name for the generated ELF. This will generate a reproducible ELF file (with Docker) with the name `fibonacci-elf`:
86100

87101
```rust
88102
use sp1_build::{build_program_with_args, BuildArgs};
89103

90104
fn main() {
91105
let args = BuildArgs {
92106
docker: true,
93-
output_directory: "./fibonacci-program".to_string(),
107+
elf_name: "fibonacci-elf".to_string(),
94108
..Default::default()
95109
};
96110
build_program_with_args("../program", &args);
97111
}
98-
```
99-
100-
**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.
112+
```

‎book/docs/writing-programs/cycle-tracking.mdx‎

Lines changed: 53 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -4,59 +4,75 @@ import Example from "@site/static/examples_cycle-tracking_program_bin_normal.rs.
44

55
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.
66

7-
## Tracking Cycles with Annotations
7+
## Tracking Cycles
88

9-
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:
9+
### Using Print Annotations
10+
For simple debugging, use these annotations to log cycle counts to stdout:
1011

11-
<Example />
12+
```rust
13+
#![no_main]
14+
sp1_zkvm::entrypoint!(main);
1215

13-
Note that to use the macro, you must add the `sp1-derive` crate to your dependencies for your program.
16+
fn main() {
17+
let mut nums = vec![1, 1];
1418

15-
```toml
16-
[dependencies]
17-
sp1-derive = "4.0.0"
18-
```
19+
// Compute the sum of the numbers.
20+
println!("cycle-tracker-start: compute");
21+
let sum: u64 = nums.iter().sum();
22+
println!("cycle-tracker-end: compute");
23+
}
24+
```
1925

20-
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:
26+
With this code, you will see output like the following in your logs:
2127

2228
```
23-
$ RUST_LOG=info cargo run --release
24-
Finished release [optimized] target(s) in 0.21s
25-
Running `target/release/cycle-tracking-script`
26-
2024-03-13T02:03:40.567500Z INFO execute: loading memory image
27-
2024-03-13T02:03:40.567751Z INFO execute: starting execution
28-
2024-03-13T02:03:40.567760Z INFO execute: clk = 0 pc = 0x2013b8
29-
2024-03-13T02:03:40.567822Z INFO execute: ┌╴setup
30-
2024-03-13T02:03:40.568095Z INFO execute: └╴4,398 cycles
31-
2024-03-13T02:03:40.568122Z INFO execute: ┌╴main-body
32-
2024-03-13T02:03:40.568149Z INFO execute: │ ┌╴expensive_function
33-
2024-03-13T02:03:40.568250Z INFO execute: │ └╴1,368 cycles
34-
stdout: result: 5561
35-
2024-03-13T02:03:40.568373Z INFO execute: │ ┌╴expensive_function
36-
2024-03-13T02:03:40.568470Z INFO execute: │ └╴1,368 cycles
37-
stdout: result: 2940
38-
2024-03-13T02:03:40.568556Z INFO execute: └╴5,766 cycles
39-
2024-03-13T02:03:40.568566Z INFO execute: finished execution clk = 11127 pc = 0x0
40-
2024-03-13T02:03:40.569251Z INFO execute: close time.busy=1.78ms time.idle=21.1µs
29+
[INFO] compute: 1234 cycles
4130
```
4231

43-
Note that we elegantly handle nested cycle tracking, as you can see above.
44-
45-
### Get Tracked Cycle Counts
46-
47-
To include tracked cycle counts in the `ExecutionReport` when using `ProverClient::execute`, use the following annotations:
32+
### Using Report Annotations
33+
To store cycle counts across multiple invocations in the `ExecutionReport`, use the report annotations:
4834

4935
```rust
36+
#![no_main]
37+
sp1_zkvm::entrypoint!(main);
38+
5039
fn main() {
51-
println!("cycle-tracker-report-start: block name");
52-
// ...
53-
println!("cycle-tracker-report-end: block name");
40+
// Track cycles across multiple computations
41+
for i in 0..10 {
42+
println!("cycle-tracker-report-start: compute");
43+
expensive_computation(i);
44+
println!("cycle-tracker-report-end: compute");
45+
}
5446
}
47+
5548
```
5649

57-
This will log the cycle count for `block name` and include it in the `ExecutionReport` in the `cycle_tracker` map.
50+
Access total cycles from all invocations
51+
```rust
52+
let report = client.execute(ELF, &stdin).run().unwrap();
53+
let total_compute_cycles = report.cycle_tracker.get("compute").unwrap();
54+
```
55+
56+
### Using the Cycle Tracker Macro
57+
Add `sp1-derive` to your dependencies:
58+
```toml
59+
sp1-derive = "4.0.0"
60+
```
61+
62+
Then annotate your functions:
63+
```rust
64+
#[sp1_derive::cycle_tracker]
65+
pub fn expensive_function(x: usize) -> usize {
66+
let mut y = 1;
67+
for _ in 0..100 {
68+
y *= x;
69+
y %= 7919;
70+
}
71+
y
72+
}
73+
```
5874

59-
### Profiling a ZKVM program
75+
## Profiling a zkVM program
6076

6177
Profiling a zkVM program produces a useful visualization ([example profile](https://share.firefox.dev/3Om1pzz)) which makes it easy to examine program performance and see exactly where VM cycles are being spent without needing to modify the program at all.
6278

‎book/docs/writing-programs/patched-crates.md‎

Lines changed: 26 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -28,17 +28,27 @@ To use the patched libraries, you can use corresponding patch entries in your pr
2828

2929
```toml
3030
[patch.crates-io]
31+
# SHA2
32+
sha2-v0-9-9 = { git = "https://github.com/sp1-patches/RustCrypto-hashes", package = "sha2", tag = "patch-sha2-0.9.9-sp1-4.0.0" }
3133
sha2-v0-10-6 = { git = "https://github.com/sp1-patches/RustCrypto-hashes", package = "sha2", tag = "patch-sha2-0.10.6-sp1-4.0.0" }
3234
sha2-v0-10-8 = { git = "https://github.com/sp1-patches/RustCrypto-hashes", package = "sha2", tag = "patch-sha2-0.10.8-sp1-4.0.0" }
35+
# SHA3
3336
sha3-v0-10-8 = { git = "https://github.com/sp1-patches/RustCrypto-hashes", package = "sha3", tag = "patch-sha3-0.10.8-sp1-4.0.0" }
37+
# BigInt
3438
crypto-bigint = { git = "https://github.com/sp1-patches/RustCrypto-bigint", tag = "patch-0.5.5-sp1-4.0.0" }
35-
tiny-keccak = { git = "https://github.com/sp1-patches/tiny-keccak", tag = "patch-2.0.2-sp1-4.0.0 }
39+
# Keccak
40+
tiny-keccak = { git = "https://github.com/sp1-patches/tiny-keccak", tag = "patch-2.0.2-sp1-4.0.0" }
41+
# Ed25519
3642
curve25519-dalek = { git = "https://github.com/sp1-patches/curve25519-dalek", tag = "patch-4.1.3-sp1-4.0.0" }
3743
curve25519-dalek-ng = { git = "https://github.com/sp1-patches/curve25519-dalek-ng", tag = "patch-4.1.1-sp1-4.0.0" }
44+
# ECDSA
3845
ecdsa-core = { git = "https://github.com/sp1-patches/signatures", package = "ecdsa", tag = "patch-0.16.9-sp1-4.0.0" }
3946
secp256k1 = { git = "https://github.com/sp1-patches/rust-secp256k1", tag = "patch-0.29.1-sp1-4.0.0" }
47+
# BN254
4048
substrate-bn = { git = "https://github.com/sp1-patches/bn", tag = "patch-0.6.0-sp1-4.0.0" }
49+
# BLS12-381
4150
bls12_381 = { git = "https://github.com/sp1-patches/bls12_381", tag = "patch-0.8.0-sp1-4.0.0", features = ["groups"] }
51+
# RSA
4252
rsa = { git = "https://github.com/sp1-patches/RustCrypto-RSA/", tag = "patch-0.9.6-sp1-4.0.0" }
4353
```
4454

@@ -47,33 +57,35 @@ repository in the patch section. For example:
4757

4858
```toml
4959
[patch."https://github.com/RustCrypto/hashes"]
50-
sha3 = { git = "https://github.com/sp1-patches/RustCrypto-hashes", package = "sha3", tag = "sha3-v0.10.8-patch-v1" }
60+
sha3 = { git = "https://github.com/sp1-patches/RustCrypto-hashes", package = "sha3", tag = "patch-sha3-0.10.8-sp1-4.0.0" }
5161
```
5262

53-
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).
63+
An example of using patched crates is available in [SP1 Blobstream](https://github.com/succinctlabs/sp1-blobstream/blob/89e058052c0b691898c5b56a62a6fa0270b31627/Cargo.toml#L40-L43).
5464

5565
## Ed25519 Acceleration
5666

5767
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.
5868

59-
Generally, `ed25519-consensus` has better performance than `ed25519-dalek` by a factor of 2.
69+
Generally, `ed25519-consensus` has better performance for Ed25519 operations than `ed25519-dalek` by a factor of 2.
6070

6171
### Patches
6272

6373
Apply the following patches based on what crates are in your dependencies.
6474

6575
- `ed25519-consensus`
6676

77+
If using `ed25519-consensus`, you should patch `curve25519-dalek-ng` to accelerate ed25519 operations:
78+
6779
```toml
6880
curve25519-dalek-ng = { git = "https://github.com/sp1-patches/curve25519-dalek-ng", tag = "patch-4.1.1-sp1-4.0.0" }
6981
```
7082

7183
- `ed25519-dalek`
7284

73-
If using `ed25519-dalek` version `2.1`, you can patch it with the following:
85+
If using `ed25519-dalek` version `2.1`, you should patch `curve25519-dalek` to accelerate ed25519 operations:
7486

7587
```toml
76-
curve25519-dalek = { git = "https://github.com/sp1-patches/curve25519-dalek", tag = "curve25519_dalek-v4.1.3-patch-v1" }
88+
curve25519-dalek = { git = "https://github.com/sp1-patches/curve25519-dalek", tag = "patch-4.1.3-sp1-4.0.0" }
7789
```
7890

7991
## Secp256k1 Acceleration
@@ -89,16 +101,16 @@ Apply the following patches based on what crates are in your dependencies.
89101
- `k256`
90102

91103
```toml
92-
ecdsa-core = { git = "https://github.com/sp1-patches/signatures", package = "ecdsa", tag = "ecdsa-v0.16.9-patch-v1" }
104+
ecdsa-core = { git = "https://github.com/sp1-patches/signatures", package = "ecdsa", tag = "patch-0.16.9-sp1-4.0.0" }
93105
```
94106

95107
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.
96108

97109
- `secp256k1`
98110

99111
```toml
100-
secp256k1 = { git = "https://github.com/sp1-patches/rust-secp256k1", tag = "secp256k1-v0.29.0-patch-v1" }
101-
ecdsa-core = { git = "https://github.com/sp1-patches/signatures", package = "ecdsa", tag = "patch-0.16.9-sp1-4.0.0 }
112+
secp256k1 = { git = "https://github.com/sp1-patches/rust-secp256k1", tag = "patch-0.29.1-sp1-4.0.0" }
113+
ecdsa-core = { git = "https://github.com/sp1-patches/signatures", package = "ecdsa", tag = "patch-0.16.9-sp1-4.0.0" }
102114
```
103115

104116
While `secp256k1` doesnt usually rely on `ecdsa-core` the patched version does, so you must patch it as well.
@@ -112,7 +124,7 @@ To accelerate BN254 (Also known as BN128 and Alt-BN128), you will need to patch
112124
Apply the patch by adding the following to your list of dependencies:
113125

114126
```rust
115-
substrate-bn = { git = "https://github.com/sp1-patches/bn", tag = "substrate_bn-v0.6.0-patch-v1" }
127+
substrate-bn = { git = "https://github.com/sp1-patches/bn", tag = "patch-0.6.0-sp1-4.0.0" }
116128
```
117129

118130
### Performance Benchmarks for Patched `substrate-bn` in `revm`
@@ -128,15 +140,15 @@ Note: The operations `run-add`, `run-mul`, and `run-pair` are from the `revm` cr
128140
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`:
129141

130142
```toml
131-
bn = { git = "https://github.com/sp1-patches/bn", package = "substrate-bn", tag = "substrate_bn-v0.6.0-patch-v1" }
143+
bn = { git = "https://github.com/sp1-patches/bn", package = "substrate-bn", tag = "patch-0.6.0-sp1-4.0.0" }
132144
```
133145

134146
## BLS12-381 Acceleration
135147

136148
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:
137149

138150
```toml
139-
bls12_381 = { git = "https://github.com/sp1-patches/bls12_381", tag = "bls12_381-v0.8.0-patch-v1" }
151+
bls12_381 = { git = "https://github.com/sp1-patches/bls12_381", tag = "patch-0.8.0-sp1-4.0.0" }
140152
```
141153

142154
This patch significantly improves the performance of BLS12-381 operations, making it essential for applications that rely heavily on these cryptographic primitives.
@@ -158,15 +170,15 @@ This patch significantly improves the performance of BLS12-381 operations, makin
158170
You can check if the patch was applied by using cargo's tree command to print the dependencies of the crate you patched.
159171

160172
```bash
161-
cargo tree -p sha2@0.9.8
173+
cargo tree -p sha2@0.10.8
162174
```
163175

164176
Next to the package name, it should have a link to the Github repository that you patched with.
165177

166178
Ex.
167179

168180
```text
169-
sha2 v0.9.8 (https://github.com/sp1-patches/RustCrypto-hashes?branch=patch-sha2-v0.9.8#afdbfb09)
181+
sha2 v0.10.8 (https://github.com/sp1-patches/RustCrypto-hashes?tag=patch-sha2-0.10.8-sp1-4.0.0)
170182
├── ...
171183
```
172184

0 commit comments

Comments
 (0)