Skip to main content
Version: v6 (Hypercube)

Upgrade Guides

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)​

The entire SDK API is now async-first using Tokio. All ProverClient methods now return futures and must be awaited.

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::{ProverClient, SP1Stdin};

#[tokio::main]
async fn main() {
    let client = ProverClient::builder().cpu().build().await;
    let (pk, vk) = client.setup(elf).await;
    let proof = client.prove(&pk, &stdin).compressed().run().await.unwrap();
    client.verify(&proof, &vk).await.unwrap();
}

Key changes:

  • Add #[tokio::main] attribute to your main function
  • Add async keyword to your main function
  • Add .await after build(), setup(), prove().run(), and verify()
  • Add tokio as a dependency: tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

Builder API Changes​

The .mock() builder method has been removed. Use .cpu() instead for local CPU proving:

// V5 (removed)
let client = ProverClient::builder().mock().build();

// V6
let client = ProverClient::builder().cpu().build().await;

Verification API Changes​

The verify() method now accepts an optional status_code parameter to validate the expected exit code:

// V5
client.verify(&proof, &vk).unwrap();

// V6 - without status code check
client.verify(&proof, &vk).await.unwrap();

// V6 - with status code check
use sp1_sdk::StatusCode;
client.verify(&proof, &vk, Some(StatusCode::Success)).await.unwrap();

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.0.0-beta.1 when specifying the circuit version
  • SDK version: Requires sp1-sdk >= v6.0.0-beta.1

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:

  1. You are using old patches
  2. 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.
  3. You are using an old sp1-zkvm or sp1-lib version.
    • Ensure, when in the programs workspace, that cargo tree | grep sp1 shows all >=5.0.0 crates.