Migration Guide

Guide for migrating between major versions of RISC Zero

Overview

This guide helps you migrate your RISC Zero zkVM applications between major versions. Breaking changes are documented with migration paths for each version transition.

Always review the CHANGELOG for comprehensive release notes.

Version Support

Current Stable Versions

• Latest: v1.2.1 (2025-01-15)
• Previous: v1.2.0 (2024-12-04)
• Legacy: v1.1.x, v1.0.x

Receipts generated by different major versions may not be compatible. Always ensure your prover and verifier use matching versions.

Migrating to v1.2.x

From v1.1.x to v1.2.0+

Breaking Changes

risc0-bigint2 replaces risc0-circuit-bigint

Change: The risc0-circuit-bigint crate has been dropped in favor of risc0-bigint2.

Migration:

Update your Cargo.toml:

[dependencies]
# Old
# risc0-circuit-bigint = "1.1"

# New
risc0-bigint2 = "1.2"

Update imports in your code:

// Old
// use risc0_circuit_bigint::*;

// New
use risc0_bigint2::*;

The new risc0-bigint2 crate provides significant performance improvements for RSA and other big integer operations.

New Features

Keccak and secp256r1 precompiles

New capabilities:

• Keccak hash function precompile
• secp256r1 (P-256) curve precompile

Usage:

These precompiles are automatically used when you use standard libraries:

// Keccak
use sha3::{Keccak256, Digest};
let hash = Keccak256::digest(b"hello");

// P-256
use p256::ecdsa::{SigningKey, Signature, signature::Signer};

For more information, see the Precompiles documentation.

Memory metrics in guest

New feature: The bump allocator now exposes used() and free() methods.

Usage:

use risc0_zkvm::guest::env;

let used = env::memory_used();
let free = env::memory_free();
env::log(&format!("Memory: {} used, {} free", used, free));

Profiling with RISC0_INFO

New feature: Set RISC0_INFO=1 environment variable to get profiling information.

Usage:

RISC0_INFO=1 cargo run --release

This replaces some use cases of the risc0_core::scope! macro.

Migrating to v1.1.x

From v1.0.x to v1.1.0+

Breaking Changes

Control ID changes for zero-knowledge improvements

Impact: Receipts from zkVM 1.0.x cannot be verified by verifiers from 1.1.x.

Reason: Zero-knowledge properties were strengthened by increasing cryptographic noise, resulting in new control IDs.

Migration:

1. Regenerate all receipts with zkVM 1.1.x
2. Update verifier version to match prover version
3. For Bonsai users: Ensure local verifier matches Bonsai version

Version mismatches between prover and verifier will cause verification failures.

Environment syscalls disabled by default

Change: sys_getenv, sys_argc, and sys_argv are now disabled by default.

Reason: Environment variables and arguments are trusted on the host but not in the guest, which can lead to security issues.

Migration:

If you must use environment variables in the guest:

[dependencies]
risc0-zkvm-platform = { version = "1.1", features = ["RISC0_GUEST_LOGENV"] }

Enabling environment variables in the guest can introduce security vulnerabilities. Use with caution.

New Features

Light builds for faster development

New feature: Light builds provide faster compilation for development.

Usage: Light builds are enabled automatically during development. For explicit control, see the cargo-risczero documentation.

Light builds are not production-ready. Always use standard builds for production.

Optional embedded allocator

New feature: An embedded allocator that deallocates memory is now available.

Usage:

Enable in your guest Cargo.toml:

[dependencies]
risc0-zkvm = { version = "1.1", features = ["embedded-alloc"] }

Useful for long-running guest programs that need memory deallocation.

Experimental sys_fork for unconstrained execution

New feature: Execute unconstrained code within the zkVM using sys_fork.

Usage:

use risc0_zkvm::guest::env;

// Code here is unconstrained and not part of the proof
env::sys_fork();

This is an experimental API marked with stability::unstable. Use for hints and advice only.

Migrating to v1.0.x

From v0.21.0 to v1.0.0

Breaking Changes

Prover::prove() returns ProveInfo

Change: The prove() function now returns a ProveInfo struct instead of a Receipt directly.

Migration:

// Old (v0.21.0)
// let receipt = prover.prove(env, GUEST_ELF).unwrap();

// New (v1.0.0+)
let prove_info = prover.prove(env, GUEST_ELF).unwrap();
let receipt = prove_info.receipt;
let stats = prove_info.stats;

// Access cycle information
println!("Total cycles: {}", stats.total_cycles);
println!("User cycles: {}", stats.user_cycles);
println!("Segments: {}", stats.segments);

sys_cycle_count returns u64

Change: sys_cycle_count now returns u64 instead of u32.

Migration:

// Old
// let cycles: u32 = env::get_cycle_count();

// New
let cycles: u64 = env::get_cycle_count();

ReceiptKind field added to ProverOpts

Change: ProverOpts has a new ReceiptKind field to select compression level.

Migration:

use risc0_zkvm::{ProverOpts, ReceiptKind};

let opts = ProverOpts {
    receipt_kind: ReceiptKind::Succinct, // or Composite, Compact
};

Receipt kinds:

• Composite: Vector of segment receipts (fastest)
• Succinct: Compressed into single receipt via recursion
• Compact: SNARK receipt for on-chain verification (smallest)

From v0.20.x to v0.21.0

Breaking Changes

Poseidon2 replaces Poseidon for recursive proofs

Change: Poseidon2 hash function replaces Poseidon for recursive proofs.

Impact: Receipts using the old Poseidon hash are not compatible with Bonsai or proof composition.

Migration: Regenerate all receipts with v0.21.0+ to use Poseidon2.

General Migration Best Practices

Testing Your Migration

1. Update all dependencies to the same version:

   cargo update
   

2. Regenerate guest methods:

   cargo risczero build --manifest-path methods/guest/Cargo.toml
   

3. Run tests:

   cargo test -F prove
   

4. Verify receipts: Ensure receipts generated by the new version can be verified:

   cargo test --test verify_receipt
   

Version Pinning

To ensure consistent builds, pin your RISC Zero version in Cargo.toml:

[dependencies]
risc0-zkvm = { version = "=1.2.1" }  # Pin to exact version

Rollback Strategy

If you encounter issues:

1. Revert Cargo.toml to previous version
2. Run cargo clean:
   cargo clean
   
3. Reinstall matching toolchain:
   cargo install cargo-risczero --version 1.1.3
   rzup install
   

Getting Help

CHANGELOG

Detailed release notes for every version

Discord

Get migration assistance from the community

GitHub Issues

Report migration problems

Documentation

zkVM documentation for current version