risc0-circuit-rv32im

RISC-V RV32IM circuit implementation for the zkVM

risc0-circuit-rv32im

The risc0-circuit-rv32im crate implements the RISC-V RV32IM constraint system circuit used by the RISC Zero zkVM to prove correct execution of guest programs.

Installation

[dependencies]
risc0-circuit-rv32im = { version = "1.3.0", features = ["prove"] }

Overview

This crate provides the core circuit that validates RV32IM (RISC-V 32-bit with integer multiplication/division) instruction execution within the zkVM. It’s a low-level component typically used indirectly through risc0-zkvm.

This is a low-level circuit implementation. Most users should use risc0-zkvm instead.

Feature Flags

prove · feature

Enables proof generation functionality.

• Implies: execute, std

execute · feature

Enables execution and witness generation.

• Implies: std

cuda · feature

Enables CUDA GPU acceleration.

• Implies: prove

std · feature

Enables standard library support.

witgen_debug · feature

Enables witness generation debugging.

block_tracker_debug · feature

Enables block tracker debugging for performance analysis.

Constants

RV32IM_SEAL_VERSION · const

Version of the seal format for rv32im circuit.

pub const RV32IM_SEAL_VERSION: u32 = 3;

MAX_INSN_ROWS · const

Maximum instruction rows for bigint programs.

pub const MAX_INSN_ROWS: usize = 25_000;

MAX_INSN_ROWS_LOWER_PO2 · const

Maximum instruction rows for smaller power-of-2 sizes (< 15).

pub const MAX_INSN_ROWS_LOWER_PO2: usize = 2_000;

Types

Claim

Claim · struct

Represents a claim about program execution.

pub struct Claim {
    pub po2: u32,
    pub pre_state: Digest,
    pub post_state: Digest,
    pub output: Option<Digest>,
    pub terminate_state: Option<TerminateState>,
    pub povw_nonce: PovwNonce,
}

Fields:

• po2: Power of 2 for segment size
• pre_state: State before execution
• post_state: State after execution
• output: Output digest (if terminated)
• terminate_state: Termination information
• povw_nonce: Proof-of-work nonce

Claim::decode · method

Decode a claim from a segment seal.

pub fn decode(seal: &[u32]) -> Result<Self>

Parameters:

• seal: Raw seal data from a segment

Returns: Decoded claim

Example:

let claim = Claim::decode(&segment_seal)?;
println!("PO2: {}", claim.po2);
println!("Pre-state: {:?}", claim.pre_state);

Claim::exit_code · method

Extract the exit code from the claim.

pub fn exit_code(&self) -> Result<ExitCode>

Returns: Exit code (Halted, Paused, or SystemSplit)

TerminateState

TerminateState · struct

State when a segment terminates.

pub struct TerminateState {
    pub a0: HighLowU16,
    pub a1: HighLowU16,
}

Fields:

• a0: Register a0 value (exit code and halt type)
• a1: Register a1 value

EcallKind

EcallKind · enum

Types of environment calls (syscalls).

pub enum EcallKind {
    BigInt,
    Poseidon2,
    Read,
    Sha2,
    Terminate,
    User,
    Write,
}

BlockType

BlockType · enum

Types of execution blocks in the circuit.

Variants: Execution blocks, memory operations, control flow, etc.

Circuit Implementation

CircuitImpl · struct

The RV32IM circuit implementation.

pub struct CircuitImpl;

Implements the constraint system for validating RV32IM execution.

Verification

verify · function

Verify a segment seal.

pub fn verify(
    seal: &[u32],
    image_id: &Digest,
) -> Result<()>

Parameters:

• seal: Segment seal to verify
• image_id: Expected program image ID

Returns: Ok(()) if verification succeeds

Trace

trace · module

Execution trace recording and callbacks.

pub trait TraceCallback: Send {
    fn trace_callback(&mut self, event: TraceEvent);
}

pub enum TraceEvent {
    InstructionStart {
        cycle: u32,
        pc: u32,
    },
    RegisterSet {
        idx: usize,
        value: u32,
    },
    MemorySet {
        addr: u32,
        value: u32,
    },
}

Execution (with execute feature)

execute Module

execute · module

Program execution and witness generation.

Provides an executor that runs RISC-V programs and generates execution traces for proving.

Proving (with prove feature)

prove Module

prove · module

Proof generation for RV32IM execution.

Implements the prover for the RV32IM circuit constraint system.

Examples

Decoding a Segment Seal

use risc0_circuit_rv32im::Claim;

fn decode_segment(seal: &[u32]) -> Result<()> {
    let claim = Claim::decode(seal)?;
    
    println!("Segment PO2: {}", claim.po2);
    println!("Pre-state: {}", claim.pre_state);
    println!("Post-state: {}", claim.post_state);
    
    if let Some(term) = claim.terminate_state {
        let exit_code = claim.exit_code()?;
        println!("Exit code: {:?}", exit_code);
    }
    
    Ok(())
}

Verifying a Segment

use risc0_circuit_rv32im::verify;
use risc0_zkp::core::digest::Digest;

fn verify_segment(
    seal: &[u32],
    image_id: &Digest,
) -> Result<()> {
    verify(seal, image_id)?;
    println!("Segment verified successfully!");
    Ok(())
}

Trace Callback

use risc0_circuit_rv32im::trace::{TraceCallback, TraceEvent};

struct MyTracer {
    instruction_count: u32,
}

impl TraceCallback for MyTracer {
    fn trace_callback(&mut self, event: TraceEvent) {
        match event {
            TraceEvent::InstructionStart { cycle, pc } => {
                self.instruction_count += 1;
                println!("Cycle {}: PC = 0x{:08x}", cycle, pc);
            }
            TraceEvent::RegisterSet { idx, value } => {
                println!("  x{} = 0x{:08x}", idx, value);
            }
            TraceEvent::MemorySet { addr, value } => {
                println!("  [0x{:08x}] = 0x{:08x}", addr, value);
            }
        }
    }
}

Proof-of-Work

decode_povw_nonce · function

Extract proof-of-work nonce from a segment seal.

pub fn decode_povw_nonce(segment_seal: &[u32]) -> Result<PovwNonce>

Example:

let nonce = decode_povw_nonce(&seal)?;
println!("PoVW nonce: {:?}", nonce);

Performance

The RV32IM circuit is optimized for:

• Throughput: Millions of cycles per second on CPU
• GPU Acceleration: 10-100x speedup with CUDA
• Memory Efficiency: Streaming witness generation

Benchmarking

# CPU benchmarks
cargo bench --features prove

# GPU benchmarks
cargo bench --features cuda

Circuit Architecture

The RV32IM circuit validates:

1. Instruction Decoding: Correct instruction fetch and decode
2. ALU Operations: Integer arithmetic and logic
3. Memory Access: Load/store operations
4. Control Flow: Branches and jumps
5. Multiply/Divide: M extension operations
6. Syscalls: Environment calls

Debugging

Enable debugging features for development:

[dependencies]
risc0-circuit-rv32im = { 
    version = "1.3.0", 
    features = ["prove", "witgen_debug", "block_tracker_debug"] 
}

Links

• docs.rs
• GitHub
• Crate
• RISC-V Spec