Upgrade Guides
6.10.0
Use the SP1 6.10.0 release with its published patch set.
These steps cover upgrades from earlier V6 releases. If you are upgrading from V5, also apply the V6 API migration below, using 6.10.0 for the dependency versions.
Upgrade Steps
- Install the matching CLI and toolchain with
sp1up -v 6.10.0. - Update the SP1 crates used by your host and guest workspaces to
6.10.0. Includesp1-sdk,sp1-build,sp1-zkvm,sp1-lib, andsp1-verifierwhere present. - Update the patches your guest uses to the matching published tags. That page also lists the BN, BLS, and KZG registry versions and compatibility variants.
- Update and inspect each workspace's
Cargo.lock. Confirm that Cargo selected the intended versions and sources, including transitive dependencies. - Rebuild your guest ELF from the updated dependencies.
For Docker builds, use builder image
ghcr.io/succinctlabs/sp1:v6.10.0. - Generate and verify proofs using the proof modes your application uses. Compute the new program verification key from the rebuilt ELF.
- If the program key changes, update the application's accepted key when switching to the new ELF. Retire the old accepted key when the transition is complete.
The application program key identifies the guest program.
It is separate from the Groth16 or Plonk circuit verification key.
SP1 6.10.0 still uses circuit version v6.1.0.
Keep the circuit version separate from SDK, CLI, and builder versions.
Verification Exit Codes
SP1 6.10.0 rejects proofs with nonzero exit codes by default.
In the SDK, None selects the success status code.
Verification is synchronous, including when you use the async prover API:
use sp1_sdk::{Prover, StatusCode};
client.verify(&proof, &vk, None).unwrap();
client.verify(&proof, &vk, Some(StatusCode::SUCCESS)).unwrap();
Applications that intentionally verify nonzero exit codes must enable the sp1-sdk/experimental feature and select the expected status.
For standalone Groth16 or Plonk verification, sp1-verifier/experimental is a separate feature.
See offchain verification for that API.
If your proving or verification path uses the Gnark Docker image, use a current image too. To select the release image explicitly:
docker pull ghcr.io/succinctlabs/sp1-gnark:v6.10.0
export SP1_GNARK_IMAGE=ghcr.io/succinctlabs/sp1-gnark:v6.10.0
The SDK otherwise selects the image by circuit version. An older locally cached image can lack options required by the updated SDK.
Tonic Compatibility
The SDK network dependencies now use Tonic 0.14.6. If your application passes Tonic types directly to SDK interfaces, update those dependencies and compile the integration again.
6.0.0
The V6 upgrade introduces the Hypercube multilinear proof system, bringing significant performance improvements and architectural changes. This is a major release with breaking API changes.
First, run sp1up to install the latest compiler for the zkVM.
After upgrading the SP1 dependencies to 6.0.0, ensure you delete ALL target directories in your project, as the V6 upgrade includes a new sp1-zkvm version that is not compatible with previous versions.
rm -rf **/**/target/
Async/Await Migration (Breaking Change)
Execution, setup, and proving use async APIs with Tokio. Verification remains synchronous.
Before (V5):
use sp1_sdk::{ProverClient, SP1Stdin};
fn main() {
let client = ProverClient::builder().cpu().build();
let (pk, vk) = client.setup(elf);
let proof = client.prove(&pk, &stdin).compressed().run().unwrap();
client.verify(&proof, &vk).unwrap();
}
After (V6):
use sp1_sdk::{ProveRequest, Prover, ProverClient, ProvingKey, SP1Stdin};
#[tokio::main]
async fn main() {
let client = ProverClient::builder().cpu().build().await;
let pk = client.setup(elf).await.unwrap();
let proof = client.prove(&pk, stdin).compressed().await.unwrap();
client.verify(&proof, pk.verifying_key(), None).unwrap();
}
Key changes:
- Add
#[tokio::main]attribute to your main function - Add
asynckeyword to your main function - Await
build(),setup(), and the proof request. - Call
verify()synchronously with the expected status code. - Add
tokioas a dependency:tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
Builder API Changes
Use .mock() for mock testing.
In V6, .build() is async:
// V5
let client = ProverClient::builder().mock().build();
// V6
let client = ProverClient::builder().mock().build().await;
Use .cpu().build().await to generate proofs on the local CPU.
Verification API Changes
The current SDK requires a third status_code argument.
Pass None to require success:
client.verify(&proof, &vk, None).unwrap();
See the 6.10.0 exit-code policy before verifying nonzero exit codes.
Import Changes
Some types have moved to new locations:
// V5
use sp1_sdk::network::proto::types::ProofMode;
// V6
use sp1_prover_types::network_base_types::ProofMode;
Patches
All patches must be upgraded for V6 compatibility. You can find the up-to-date list of patches here.
The following patches are required to be upgraded:
- P256
- K256
- BLS12_381
- Dalek(-ng)
- Secp256k1
- BN
- RSA
Network Changes
If you're using the Succinct Prover Network:
- Metrics: The network now uses "Proving Gas Units" (PGUs) instead of cycles for pricing and metrics
- Version string: Use
sp1-v6.1.0when specifying the circuit version - SDK version: Requires
sp1-sdk >= v6.1.0
5.0.0
The V5 upgrade includes important security fixes and performance improvements, it is strongly recommended to upgrade to this version as soon as possible.
First you should run sp1up, this will install the lastest compiler for the zkVM.
After upgrading the SP1 dependencies to 5.0.0, ensure you delete ALL target directories in your project,
as the V5 upgrade includes a new sp1-zkvm version that is not compatible with previous versions.
If you're using a separate workspace for your program, you must ensure that target directory is deleted.
From the root of your project, you can run rm -rf **/**/target/ to delete all target directories.
Patches
In order to upgrade to V5, some patches must be upgraded, you can find the up to date list of patches here and any caveats associated with them.
The following patches are required to be upgraded:
- P256
- K256
- BLS12_381
- Dalek(-ng)
- Secp256k1
- BN
- RSA
Common Issues
RustCrypto Provider
The current version of the sp1-sdk relies on an RPC client that defaults to enabling the ring TLS feature on Rustls,
which means any dependcies that enable the aws-lc-tls feature will cause the TLS provider to become ambigious to Rustls.
Unfortunately, the only way to solve this at the moment is to install RustCrypto::Provider
at runtime in your main function.
This problem most commonly occurs when using any aws-sdk-* crates, as they enable the aws-lc-tls feature by default.
For example, to install the aws-lc-tls provider, you can add the following to your main.rs:
fn main() {
rustls::crypto::aws_lc_rs::default_provider().install_default()
.expect("Failed to set default crypto provider");
...
}
You are using reserved file descriptor X ...
This message occurs for a few reasons:
- You are using old patches
- Ensure you are using the latest patches for your dependencies, as listed in the precompiles documentation.
- You are using an old ELF by accident, and not a newly built one.
- Ensure your build system is functioning correctly and that you are not using an old ELF file.
- You are using an old
sp1-zkvmorsp1-libversion.- Ensure, when in the
programsworkspace, thatcargo tree | grep sp1shows all >=5.0.0 crates.
- Ensure, when in the