Overview

SP1 V4 is the latest release of SP1 with security enhancements, significant performance improvements, and new precompiles for RSA and secp256r1. We recommend everyone to migrate as soon as possible.

Migration Steps

1. Update dependency versions.

   # In program/Cargo.toml
   [dependencies]
   sp1-zkvm = "4.0.1"
   
   # In script/Cargo.toml
   [dependencies]
   sp1-sdk = "4.0.1"
   [build-dependencies]
   sp1-build = "4.0.1"
   

2. sp1_sdk has been refactored slightly for better type safety and new prover network features.

   1. ProverClient::new() has been renamed to ProverClient::from_env(). It returns EnvProver, which switches between provers based on the value of the SP1_PROVER env var, which is one of cpu/cuda/network/mock.
      • Expand
   2. Provers with prover-specific functionality can be created using ProverClient::builder() with .network(), .cuda(), or .mock() and then .build().
      1. For example, CpuProver.prove() has .cycle_limit().
   3. NetworkProver.prove() returns a builder with network-specific options and build functions run, run_async, request, request_async which replace NetworkProver.request_proof.
      • Expand
   4. If you’re using dedicated proving capacity, use the network-specific NetworkProver and select FulfillmentStrategy::Reserved when proving.
      • Expand
   5. SP1ProofWithPublicValues no longer contains stdin.

3. Environment variables have been renamed for better organization.

   Old Variable	Renamed Variable
   SP1_PRIVATE_KEY	NETWORK_PRIVATE_KEY
   PROVER_NETWORK_RPC	NETWORK_RPC_URL=https://rpc.production.succinct.xyz
   SP1_PROVER=local	SP1_PROVER=cpu
   SKIP_SIMULATION	Use NetworkProver.prove().skip_simulation()

4. ELFs are no longer copied to elf/ by default.

   We recommend using include_elf! rather than include_bytes! in script/src/main.rs to include ELF bytes. You must use sp1_build::build_program in your script/build.rs in order to use this.

   // In script/src/main.rs
   // Old
   pub const FIBONACCI_ELF: &[u8] = include_bytes!("../../../elf/riscv32im-succinct-zkvm-elf");
   
   // New
   pub const FIBONACCI_ELF: &[u8] = include_elf!("fibonacci-program");
   
   // In script/build.rs
   use sp1_build::build_program;
   
   fn main() {
       build_program("../program")
   }
   

   • sp1_build::build_program automatically sets an env var at build time which is used by include_elf to load the ELF.
   • Instead of being copied to elf/, ELFs is left in target/elf-compilation/riscv32im-succinct-zkvm-elf/release/<bin name> of the program’s target directory. We no longer recommend committing the ELF in version control.
   • If you’d like, you can still copy it out manually or by providing BuildOpts with output_directory set when building. elf_name can be set to rename the file.
     • Example

5. Program verification keys are not backwards compatible across versions so they should be recomputed for V4.

   1. Additionally, the cargo prove vkey tool is no longer supported and will not return a correct value for V4. Instead, you should use vk.bytes32() which requires the import sp1_sdk::HashableKey.

      use sp1_sdk::HashableKey;
      let (pk, vk) = client.setup(ELF);
      println!("vkey hash: {}", vk.bytes32().to_string());
      

6. All patched and accelerated crates using old patch tags no longer will work. You must use the V4 specific patches.

   1. Update any patched crate entries in your program/Cargo.toml based on: https://docs.succinct.xyz/docs/writing-programs/patched-crates

7. Proof Explorer now lives at https://network.succinct.xyz with a fresh design and new functionality.

   1. If you were whitelisted on the V1 Prover Network, you should already have 10B cycles of credits on the new Prover Network!