System Architecture

Technical architecture of the RISC Zero zkVM and its components

System Architecture

The RISC Zero zkVM implements a sophisticated multi-layer proof system built on RISC-V instruction set emulation and zero-knowledge cryptography. This page explores the architecture from compilation through verification.

High-Level Architecture

The zkVM architecture consists of several distinct layers:

┌─────────────────────────────────────────────┐
│          User Code (Rust/C/C++)            │
└─────────────────────┬───────────────────────┘
                      │ Compile
                      ▼
┌─────────────────────────────────────────────┐
│        RISC-V ELF Binary (Method)          │
└─────────────────────┬───────────────────────┘
                      │ Execute & Prove
                      ▼
┌─────────────────────────────────────────────┐
│              RISC-V Prover                 │
│         (Segment-level STARK)              │
└─────────────────────┬───────────────────────┘
                      │ Aggregate
                      ▼
┌─────────────────────────────────────────────┐
│            Recursion Prover                │
│     (Proof composition & aggregation)      │
└─────────────────────┬───────────────────────┘
                      │ Compress
                      ▼
┌─────────────────────────────────────────────┐
│         STARK-to-SNARK Prover              │
│            (Groth16 proof)                 │
└─────────────────────┬───────────────────────┘
                      │
                      ▼
              Receipt (Proof)

Compilation Layer

cargo risczero Tool

The cargo risczero tool compiles user-written code into RISC-V ELF binaries deterministically. This ensures:

• Reproducible builds across different machines
• Consistent Image IDs for the same source code
• Compatibility with the zkVM execution environment

Memory Image

The compiled binary is loaded into a MemoryImage structure (defined in risc0_binfmt::MemoryImage) that represents:

• Program code and data
• Initial memory state
• Entry point for execution

use risc0_binfmt::{MemoryImage, compute_image_id};

// Compute the Image ID from an ELF binary
let image_id = compute_image_id(elf_bytes)?;

The Image ID is computed using the compute_image_id function from the risc0_binfmt crate, which creates a cryptographic digest of the memory image.

Execution Layer

Executor Environment

The ExecutorEnv configures the guest execution environment, including:

• Input data streams
• Environment variables
• File descriptors (stdin, stdout, stderr)
• Segment limits
• Trace callbacks for debugging

use risc0_zkvm::ExecutorEnv;

let env = ExecutorEnv::builder()
    .write(&input_a)?
    .write(&input_b)?
    .env_vars([("LOG_LEVEL".to_string(), "debug".to_string())])
    .build()?;

Key fields from risc0/zkvm/src/host/client/env.rs:

pub struct ExecutorEnv<'a> {
    pub(crate) env_vars: HashMap<String, String>,
    pub(crate) args: Vec<String>,
    pub(crate) segment_limit_po2: Option<u32>,
    pub(crate) posix_io: Rc<RefCell<PosixIo<'a>>>,
    pub(crate) input: Vec<u8>,
    pub(crate) trace: Vec<Rc<RefCell<dyn TraceCallback + 'a>>>,
    // ... additional fields
}

Session and Segments

Execution is divided into segments to manage memory and enable parallelization:

• Session: Complete execution from start to finish
• Segment: A portion of execution (typically 2^20 to 2^24 cycles)
• SegmentRef: Reference to segment data for proof generation

Segmentation provides:

• Memory efficiency: Prove large computations without loading all state
• Parallelization: Generate proofs for segments concurrently
• Incremental proving: Pause and resume execution

The segment size can be tuned with segment_limit_po2() to balance memory usage and proving performance.

Proving Layers

Layer 1: RISC-V Prover

The RISC-V Prover generates STARK proofs for individual execution segments. It proves:

• Correct execution of RISC-V instructions
• Valid state transitions
• Proper memory access patterns
• Adherence to the RISC-V ISA specification

Cryptographic properties:

• Based on zk-STARK protocol
• 96 bits of security
• Quantum-safe (relies on hash functions, not elliptic curves)
• Targets perfect zero-knowledge

From the codebase (risc0/zkvm/src/lib.rs:100-118):

#[cfg(feature = "prove")]
pub use self::host::{
    client::prove::{local::LocalProver, local_executor},
    server::prove::{
        HalPair, ProverServer,
        get_prover_server,
    },
    server::session::{
        Segment, Session, SessionEvents,
    },
};

Layer 2: Recursion Prover

The Recursion Prover aggregates and composes proofs from the RISC-V Prover:

• Lift: Convert RISC-V segment proofs to recursion circuit format
• Join: Combine multiple proofs into a single proof
• Resolve: Handle proof composition with assumptions

This layer enables:

• Constant-size proofs regardless of execution length
• Proof composition (verifying proofs within the zkVM)
• Hiding execution length information

Control IDs: Each recursion program (lift, join, resolve) has a control ID that identifies it. The ALLOWED_CONTROL_ROOT aggregates all allowed control IDs.

The Recursion Prover achieves 99 bits of security and is also quantum-safe.

Layer 3: STARK-to-SNARK Prover

The STARK-to-SNARK Prover compresses STARK proofs into Groth16 SNARKs for efficient on-chain verification:

• Verifies STARK proofs from the Recursion Prover
• Produces a Groth16 proof over the BN254 curve
• Optimized for Ethereum and EVM-compatible chains

Cryptographic properties:

• 99+ bits of security
• Not quantum-safe (relies on elliptic curve cryptography)
• Requires trusted setup ceremony (performed once)

The Groth16Receipt structure (from risc0/zkvm/src/receipt/groth16.rs):

pub struct Groth16Receipt {
    pub inner: InnerReceipt,
    pub journal: Journal,
    pub metadata: ReceiptMetadata,
}

Receipt Structure

A Receipt is the final output of the proving process:

pub struct Receipt {
    /// The polymorphic InnerReceipt
    pub inner: InnerReceipt,
    
    /// The public commitment written by the guest
    pub journal: Journal,
    
    /// Metadata about the receipt
    pub metadata: ReceiptMetadata,
}

The InnerReceipt enum supports multiple receipt types:

• SegmentReceipt: Proof of a single segment
• SuccinctReceipt: Recursively composed proof
• CompositeReceipt: Collection of receipts with assumptions
• Groth16Receipt: SNARK proof for on-chain verification
• FakeReceipt: Development mode placeholder (no actual proof)

Verification Architecture

VerifierContext

The VerifierContext controls verification parameters:

use risc0_zkvm::VerifierContext;

let ctx = VerifierContext::default();
receipt.verify_with_context(&ctx, image_id)?;

Verification checks:

1. Seal integrity: Cryptographic proof is valid
2. Image ID match: Correct code was executed
3. Exit code: Guest exited successfully (code 0)
4. Journal integrity: Output matches committed data

Hash Suites

The zkVM supports multiple hash functions for different use cases:

• SHA-256: Standard hash for general use
• Poseidon2: STARK-friendly hash for circuits
• BLAKE2b: High-performance alternative

From risc0/zkvm/src/receipt.rs:

use risc0_zkp::core::hash::{
    blake2b::Blake2bCpuHashSuite,
    poseidon2::Poseidon2HashSuite,
    sha::Sha256HashSuite,
};

Feature Flags

The zkVM supports several feature flags that control functionality:

Feature	Description
client	Enables client API (executor, prover interfaces)
prove	Enables the prover (incompatible with guest)
cuda	CUDA GPU acceleration for proving
metal	Metal GPU acceleration (macOS)
std	Rust standard library support
disable-dev-mode	Prevents fake proofs in production

Guest code must disable default features: default-features = false in Cargo.toml.

Performance Considerations

GPU Acceleration

The prover can leverage GPU acceleration:

• CUDA: For NVIDIA GPUs
• Metal: For Apple Silicon (enabled by default on M-series chips)

Memory Management

Memory usage scales with:

• Segment size (controlled by segment_limit_po2)
• Execution length
• Proof type (STARK vs SNARK)

Lowering segment size by 1 power of 2 roughly halves memory consumption.

Parallel Proving

Segments can be proven in parallel, leveraging multiple CPU cores or GPUs for improved throughput.

Next Steps

• Guest and Host Programs - Learn the programming model
• Receipts and Verification - Understand proof verification
• Security Model - Explore cryptographic guarantees