risc0-zkvm

RISC Zero zero-knowledge VM - Core library for building and verifying zkVM applications

risc0-zkvm

The risc0-zkvm crate is the primary interface for building zero-knowledge applications with RISC Zero. It provides the zkVM that executes RISC-V code and produces zero-knowledge proofs.

Installation

[dependencies]
risc0-zkvm = "5.0.0"

Overview

The RISC Zero zkVM is a RISC-V virtual machine that produces zero-knowledge proofs of code execution. By using the zkVM, a cryptographic receipt is produced which anyone can verify was produced by the zkVM’s guest code.

For guest code (code running inside the zkVM), disable default features:

risc0-zkvm = { version = "5.0.0", default-features = false }

Feature Flags

client · feature

Enables the client API for interacting with the zkVM from the host.

• Implies: std
• Target: All except rv32im

prove · feature

Enables the prover, required for generating proofs.

• Implies: client, std
• Incompatible: zkVM guest environment

cuda · feature

Enables CUDA GPU acceleration for the prover.

• Implies: prove, std
• Requirements: CUDA toolkit must be installed

bonsai · feature

Enables integration with Bonsai proving service.

• Enabled by default

std · feature

Support for Rust standard library.

getrandom · feature

Exposes a getrandom implementation using the sys_random ecall.

• Note: By default, getrandom panics in the zkVM

disable-dev-mode · feature

Disables dev mode to prevent faking proofs in production.

Core Types

Prover

Prover · trait

Main trait for proving zkVM programs.

pub trait Prover {
    fn prove(&self, env: ExecutorEnv, elf: &[u8]) 
        -> Result<Receipt>;
    
    fn prove_with_opts(
        &self,
        env: ExecutorEnv,
        elf: &[u8],
        opts: &ProverOpts,
    ) -> Result<Receipt>;
}

DefaultProver · struct

Default implementation of the Prover trait.

pub struct DefaultProver;

LocalProver · struct

Local prover implementation that generates proofs on the current machine.

BonsaiProver · struct

Prover implementation that uses the Bonsai proving service.

Requires: bonsai feature

Execution Environment

ExecutorEnv · struct

Environment configuration for zkVM execution.

let env = ExecutorEnv::builder()
    .write(&input_data)
    .unwrap()
    .build()
    .unwrap();

ExecutorEnvBuilder · struct

Builder for constructing ExecutorEnv.

Methods:

• write<T: Serialize>(&mut self, data: &T) -> Result<&mut Self>
• stdin(&mut self, reader: impl Read + 'static) -> &mut Self
• stdout(&mut self, writer: impl Write + 'static) -> &mut Self
• add_assumption(&mut self, receipt: impl Into<AssumptionReceipt>) -> &mut Self
• build(&mut self) -> Result<ExecutorEnv>

Receipt

Receipt · enum

Cryptographic proof of zkVM execution.

Variants:

• Composite(CompositeReceipt) - Multi-segment proof
• Succinct(SuccinctReceipt) - Compressed proof via recursion
• Groth16(Groth16Receipt) - SNARK proof for on-chain verification
• Fake(FakeReceipt) - Development-only fake receipt

// Verify a receipt
receipt.verify(image_id)?;

// Extract the journal
let output: OutputData = receipt.journal.decode()?;

Journal · struct

Public outputs from zkVM execution.

pub struct Journal {
    pub bytes: Vec<u8>,
}

impl Journal {
    pub fn decode<T: DeserializeOwned>(&self) -> Result<T>;
}

ProverOpts

ProverOpts · struct

Options for customizing proof generation.

let opts = ProverOpts::default()
    .with_receipt_kind(ReceiptKind::Groth16);

ReceiptKind · enum

Type of receipt to generate.

Variants:

• Composite - Standard multi-segment receipt
• Succinct - Compressed receipt
• Groth16 - SNARK receipt for blockchain verification

Guest API

When writing guest code (code that runs inside the zkVM), use these functions:

Input/Output

env::read · function

Read input data from the host.

pub fn read<T: DeserializeOwned>() -> T

Example:

let input: u32 = risc0_zkvm::guest::env::read();

env::commit · function

Commit data to the journal (public output).

pub fn commit<T: Serialize>(data: &T)

Example:

risc0_zkvm::guest::env::commit(&result);

Memory Management

PAGE_SIZE · const

Size of a zkVM memory page.

pub const PAGE_SIZE: usize = 1024;

GUEST_MAX_MEM · const

Maximum guest memory size.

Examples

Basic Host Code

use risc0_zkvm::{default_prover, ExecutorEnv};

fn main() {
    // Load the guest ELF binary
    let elf = include_bytes!("../target/riscv-guest/method");
    
    // Prepare input data
    let input = 42u32;
    let env = ExecutorEnv::builder()
        .write(&input)
        .unwrap()
        .build()
        .unwrap();
    
    // Generate proof
    let prover = default_prover();
    let receipt = prover.prove(env, elf).unwrap();
    
    // Verify the receipt
    receipt.verify(METHOD_ID).unwrap();
    
    // Extract output
    let output: u32 = receipt.journal.decode().unwrap();
    println!("Result: {}", output);
}

Basic Guest Code

#![no_main]
use risc0_zkvm::guest::env;

risc0_zkvm::guest::entry!(main);

fn main() {
    // Read input
    let input: u32 = env::read();
    
    // Compute result
    let result = input * 2;
    
    // Commit to journal
    env::commit(&result);
}

Using Bonsai

use risc0_zkvm::{ExecutorEnv, ProverOpts, ReceiptKind};
use risc0_zkvm::serde::to_vec;

fn prove_on_bonsai() -> Result<()> {
    let env = ExecutorEnv::builder()
        .write(&input_data)?
        .build()?;
    
    let receipt = bonsai_sdk::blocking::Client::from_env(risc0_zkvm::VERSION)?
        .prove(env, elf)?;
    
    receipt.verify(image_id)?;
    Ok(())
}

Links

• docs.rs
• GitHub
• Crate