Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Introducing Pico

Welcome to Pico—the open-source zero-knowledge virtual machine (zkVM) that transforms how developers build secure, scalable, and high-performance decentralized applications. Drawing on the innovative “glue-and-coprocessor” architecture, Pico fuses the efficiency of specialized circuits with the adaptability of a general-purpose zkVM. This unique design empowers you to craft tailored proof systems that meet the diverse needs of modern cryptographic applications.

Pico’s STARK proofs have 128 bits of provable soundness; the on-chain Groth16 proof has BN254’s security level.

Pico’s design is rooted in the need for adaptable, high-performance ZK systems that can keep pace with the rapidly evolving landscape of cryptographic research. Rather than relying on a one-size-fits-all solution, Pico’s modular architecture lets you:

  • Leverage Interchangeable Proving Backends: Select from multiple proving backends to achieve the best performance and efficiency.
  • Integrate App-Specific Circuits: Seamlessly incorporate specialized circuits/coprocessors to accelerate domain-specific computations.
  • Customize Proving Workflows: Assemble and fine-tune proof generation pipelines tailored to your application’s specific requirements.

Why Choose Pico?

Pico is built upon four fundamental strengths that set it apart:

  • Modularity: Pico’s architecture is composed of independent, interchangeable components. This design allows you to configure and reassemble the system to align with your application’s requirements precisely.
  • Flexibility: Pico supports various proving backends and custom proving pipelines, enabling you to fine-tune every aspect of the proof generation process. Adjust parameters effortlessly to meet specific performance demands.
  • Extensibility: Designed for seamless integration, Pico allows you to incorporate app-specific circuits and custom acceleration modules. This extensibility ensures you can add bespoke coprocessors or precompiles, enhancing the system’s capabilities without disrupting its core functionality.
  • Performance: Engineered for efficiency, Pico achieves industry-leading proof generation speeds on standard hardware. Its optimized workflows and specialized circuits deliver exceptional throughput and low latency, even in high-demand scenarios.

Pico provides a robust, future-ready foundation that meets today’s challenges and evolves with the advancing field of zero-knowledge technology. Whether you’re a developer eager to explore the potential of ZK proofs or a researcher pushing the boundaries of cryptographic innovation, Pico is the ideal platform to build upon.

Migrating to 3.x

Pico 3.0 replaced the proof system: it proves over the KoalaBear field with an MLE proof system (LogUp-GKR, ZeroCheck and WHIR), and the host-side API moved to a new crate. Pico 3.1 raises its proofs to 128 bits of provable soundness.

No proof, key, whitelist or verifier contract carries over from 2.x or 3.0. Rebuild every guest (every program id changes), run a new Groth16 setup and redeploy the verifier contracts.

This page lists the changes most projects hit. The full guide is Migrating from 2.x to 3.0, and the 3.0 and 3.1 release notes summarize each release.

Toolchain

  • The Rust toolchain moved from nightly-2025-08-04 to nightly-2026-09-27. Reinstall the CLI with it (see Installation), then run cargo pico install again for the matching guest toolchain.
  • Set the project’s own rust-toolchain file to nightly-2026-09-27: the host crate builds pico-prover, which uses nightly-only features.
  • The guest target is still riscv64im-pico-zkvm-elf.
  • The guest depends on pico-sdk = { git = "https://github.com/brevis-network/pico", tag = "v3.1.1" }.

Fields and phases

  • KoalaBear is the only field. BabyBear and Mersenne31 are removed with no replacement: the bb and m31 features of pico-sdk are gone, and kb is kept as a no-op so existing guests still build.
  • The chain is RISCV → CONVERT → COMBINE → COMPRESS → EMBED → WRAP; see ProverChain.

CLI

2.x3.0
cargo pico prove --fastcargo pico prove --phase riscv. The RISC-V phase is full-security; --fast now fails with this hint
cargo pico prove --fieldremoved; KoalaBear is the only field, and the flag fails with an error
--elf optional--elf required
--input "0x…" or a file path, oncerepeatable and typed: --input u64:100, --input 0x…, --input file:<path>
output in <target>/pico_outoutput in pico_out under the current directory (--output to change)
prove stops after EMBEDprove stops after COMBINE by default; --phase chooses
--evm with a fixed Docker image--evm with gnark from $PICO_GNARK_BIN or $PICO_GNARK_IMAGE, in whitelist mode only, with keys from --keys DIR or $PICO_GROTH16_KEYS. See the gnark README

New subcommands: cargo pico execute (emulate without proving) and cargo pico aot (generate AOT crates). See the CLI section of the migration guide.

Host SDK: pico-sdk client → pico-prover

The prover clients left pico-sdk. The host program depends on the new crate pico-prover:

pico-prover = { git = "https://github.com/brevis-network/pico", tag = "v3.1.1" }
2.x (pico_sdk::client)3.0 (pico_prover)
DefaultProverClient::new(&elf) (and the other *ProverClients)Prover::new(&elf)?, or Prover::builder(&elf)…build()? for options
client.new_stdin_builder() + writeStdin::new() + write / write_bytes, or Stdin::from(&value)
prove_fast(stdin)prove_to(stdin, Phase::Riscv)
prove(stdin) → (riscv_proof, embed_proof)prove(stdin) → one Proof at COMBINE, already verified
verify(..)no separate call: every returned Proof is verified. A proof read from a file goes through ProofArtifact::read and Prover::verify_artifact
emulate(stdin)execute(stdin); its output is not proof-authenticated
prove_evm(stdin, need_setup, out, field)prove_evm(stdin) → EvmBundle, whitelist mode only. Groth16 itself runs outside the library (cargo pico prove --evm)
write_onchain_data(..)Proof::write_wrap_artifacts or EvmBundle::write_to
proof.pv_streamproof.committed().as_bytes()

See Proving for the new API.

Guest SDK

  • pico_sdk::poseidon2_hash is deprecated: its single-element output is not collision-resistant. Use pico_sdk::poseidon2::hash (fixed-length input).
  • syscall_poseidon2_permute now takes *const Poseidon2State, *mut Poseidon2State.

Output files

  • constraints.json and groth16_witness.json are now wrap_constraints.json and wrap_groth16_witness.json.
  • RISC-V and COMBINE proofs are written as proof-riscv.pico and proof-combine.pico.
  • inputs.json gains a committedValuesDigest field.

On-chain verifier

verifyPicoProof now takes a twelve-word proof:

function verifyPicoProof(bytes32 riscvVkey, bytes calldata publicValues, uint256[12] calldata proof) external view;

In 2.x it took uint256[8]. The extra four words are the Pedersen commitment and its proof of knowledge that the 3.0 wrap circuit carries. Redeploy the verifier contracts; see the gnark README.

Installation

Requirements:

Install

Option 1: Cargo install

  1. Install pico-cli from the GitHub repository
cargo +nightly-2026-09-27 install --git https://github.com/brevis-network/pico --tag v3.1.1 --locked pico-cli
  1. Check the version
cargo pico --version

Option 2: Local install

  1. Git clone Pico-VM repository
git clone --branch v3.1.1 https://github.com/brevis-network/pico
  1. cargo install from the local path
cd pico/sdk/cli
cargo install --locked --force --path .

Rust toolchain

Pico uses the rust-specific rust toolchain version(nightly-2026-09-27) to build the program. The specific toolchain version can be found in the rust-toolchain file in the repository root.

rustup install nightly-2026-09-27
rustup component add rust-src --toolchain nightly-2026-09-27

Install RISC-V64 target toolchain

Pico requires a RISC-V64 target toolchain to compile programs. After installing cargo pico, run:

cargo pico install

Then verify the installation:

rustup toolchain list | grep pico

You should see pico in the list.

Quick start

This page shows you how to create and prove a Fibonacci program.

Start with the Fibonacci template

  1. Create project
cargo pico new --template basic Fibonacci

This creates a directory Fibonacci with the basic template, which contains a fibonacci program.

  1. Build program
# Build program in app folder
cd app
cargo pico build    

This will use the Pico compiler to generate a RISC-V ELF that can be executed by the Pico ZKVM.

  1. Prove program with Pico (Default Path)
# Prove in prover folder
cd ../prover
RUST_LOG=info cargo run --release -- prove fib.pico

The prover subdirectory contains a Rust program that will load an input for the ELF that was just compiled, execute it, and generate a proof. This project has the entire functionality of the Pico SDK at its disposal, and can be customized however you want.

If you simply wish to use the default provided proving clients and options, you can prove using the Pico CLI via

RUST_LOG=info cargo pico prove --input "0x6400000000000000" --phase riscv --elf /path/to/elf # input n = 100

The input to the fibonacci program is a single u64 specifying which number to compute, so we can directly pass the input with the --input option, supplying little endian bytes. --phase riscv simply tells the prover to skip any recursion steps and terminate after finishing the RISC-V proof.

  1. Prove program with AOT (Experimental)

AOT is an alternative execution path: the emulator thread can be driven by AOT-compiled chunks generated from the specific guest ELF you are proving, instead of the interpreter. This trades a one-time codegen step for reduced per-proof execution cost.

  • Generate AOT chunks

The generated chunks are tied to the PC ranges of a specific ELF. You must re-generate whenever app/src/ changes.

From the project root, after cargo pico build:

cargo pico aot --elf app/elf/riscv64im-pico-zkvm-elf --out aot-generated

cargo pico aot wires pico-aot-runtime as a git dep in the generated chunk crates, pinned to the CLI’s release tag, so aot-generated/ works at the template root without requiring a local Pico checkout. Set PICO_SOURCE to a Pico checkout to build against it instead.

  • Prove with --aot

Enable the template’s aot feature:

cd prover
RUST_LOG=info cargo run --release --features aot -- prove fib.pico

Project Layout

Fibonacci
|—— app
     |—— elf
          |—— riscv64im-pico-zkvm-elf
     |—— src
          |—— main.rs
     |—— Cargo.toml
|—— lib
     |—— src
          |—— lib.rs
     |—— Cargo.toml
|—— prover
     |—— src
           |—— main.rs
     |—— Cargo.toml
|—— Cargo.toml
|—— Cargo.lock
|—— rust-toolchain     

The template project includes 3 workspace members: app, lib and prover

app: contains the program source code, which will be compiled to RiscV

app/elf: contains ELF with RISC-V instructions.

lib: contains components or utilities shared in multiple modules.

prover: contains the scripts to prepare program input data and execute the proving process.

Start with the EVM template

Minimum memory requirement: 32GB

  1. Create and build the EVM Example Project

    cargo pico new evm-example --template evm
    cd evm-example/app/
    cargo pico build
    

    This uses the evm template, which will set up a proving script that will generate a Groth16 proof suitable for verification via smart contract on an ETH compatible chain.

  2. Prove program to EVM

    cd ../prover
    RUST_LOG=info cargo run --release -- prove fib.pico
    

    This proves the program in dev mode and writes fib.pico, a RISC-V proof that verifies from the ELF but is not one a contract can check. The EVM proof comes from cargo pico prove --evm in whitelist mode, with a gnark prover and a Groth16 key set; the template’s README, “The on-chain proof”, lists the exact commands.

  3. Test EVM Proof

    cd ../contracts
    forge test
    

    The Foundry tests verify the proof in test_data/inputs.json with the Groth16 verifier in test/dev. To test your own EVM proof, copy its inputs.json and key files in, as the template’s README shows. With all tests passing, the EVM quick start is successful.

Programs

Pico entrypoint

The program is executed and proved with the zkVM platform. Pico links the programs by the main function annotated with the entrypoint macro_rules. The program needs to be declared with no_main.

// declare no_main
#![no_main]

// point out the main function in your program.
pico_sdk::entrypoint!(main);

pub fn main() {
    //todo: write your program logic here
}

Raw system calls are available by using pico_sdk::riscv_ecalls::* but it is recommended to use the integrated patch libraries to avoid disrupting the standard development workflow. The program can then be compiled to RiscV without creating conditional compilation-related hoops aside from the entry point. A few light wrappers for elliptic curve types can also be found in the pico-patch-libs crate.

Be very careful with using heap memory. The currently implemented allocator does not free any memory, so cloning a medium-sized Vec a few too many times will cause your program to go OOM. You must write your own allocator if a more managed memory solution is required.

Inputs and outputs

pico_sdk::io::read_as Read a serialized input data type into the program and deserialize it into specific types, such as u32, u64, and bytes. Pico prove CLI provides two ways to pass the inputs: hex string (0x…) and file path (file:<path>). When your specific input is a file path, the file content will be read as bytes in the program.

cargo pico prove --elf elf/riscv64im-pico-zkvm-elf --input "0x..." # hex, or file:<path>

pico_sdk::io::commit Commit serializable data to the public stream. The public inputs will be compressed using a SHA256 hash and exported to the on-chain.

pico_sdk::io:commit_bytes Write the public values in a byte buffer.

Setup programs

  1. Create an instant program
cargo pico new --template basic basic-example

The project contains the program (app), a shared library (lib) and a prover (prover). You can test and debug your RISC-V program quickly using the basic template.

  1. Create a program with EVM
cargo pico new --template evm evm-example

The created project with the evm template will contain an extra Contracts folder for app and verification contracts .

Use the pre-prepared pico EVM proof and Groth16 verifier in the repo to run contract tests.

cd contracts
forge test

Proving

Overview

Pico provides CLI and SDK tools to recursively prove the program to the developers.

Pico CLI provides a complete toolchain for compiling the RISC-V program and using Pico to complete end-to-end proof. Refer to the installation page to install the CLI toolchain. Pico 3.1 proves over the KoalaBear field, with 128 bits of provable soundness.

Like the CLI, the pico-prover crate includes lower-level APIs that can prove the program directly. The prover package of the template project repository provides an example of how to import and initialize the SDK and quickly generate a RISC-V proof using the Pico SDK. In the Proving Steps Section, you can read more about VM e2e proving and the Gnark EVM proof generation for On-chain verification

Let’s quickly go through the Pico SDK usage and generate a Fibonacci RISC-V proof.

  1. Import pico-sdk and pico-prover
# Cargo.toml
pico-sdk = { git = "https://github.com/brevis-network/pico", tag = "v3.1.1" }
pico-prover = { git = "https://github.com/brevis-network/pico", tag = "v3.1.1" }
  1. Execute the proving process and generate RISC-V proof.
// prover/src/main.rs
fn main() {
    // Initialize logger
    init_logger();

    // Load the ELF file
    let elf = load_elf("../app/elf/riscv64im-pico-zkvm-elf");

    // Initialize the prover
    let mut prover = Prover::new(&elf).expect("Failed to initialize the prover");
    // Initialize new stdin
    let mut stdin = Stdin::new();

    // Set up input and generate proof
    let n = 100u64;
    stdin.write(&n);

    // Generate proof
    let proof = prover.prove_to(stdin, Phase::Riscv).expect("Failed to generate proof");

    // Decodes public values from the proof's committed values.
    let public_values: FibonacciData = proof.committed().read().expect("Failed to decode public values");

    // Verify the public values
    verify_public_values(n, &public_values);
}

/// Verifies that the computed Fibonacci values match the public values.
fn verify_public_values(n: u64, public_values: &FibonacciData) {
    println!(
        "Public value n: {:?}, a: {:?}, b: {:?}",
        public_values.n, public_values.a, public_values.b
    );

    // Compute Fibonacci values locally
    let (result_a, result_b) = fibonacci(0, 1, n);

    // Assert that the computed values match the public values
    assert_eq!(result_a, public_values.a, "Mismatch in value 'a'");
    assert_eq!(result_b, public_values.b, "Mismatch in value 'b'");
}

Pico EmulatorStdin

Stdin Writer

  1. Pico SDK supports writing the serializable object and bytes to Pico.
#![allow(unused)]
fn main() {
/// Write a serializable struct to the buffer.
pub fn write<T: Serialize>(&mut self, data: &T);
/// Write a slice of bytes to the buffer.
pub fn write_bytes(&mut self, bytes: &[u8]);
}

Examples:

use std::vec;
use pico_prover::Stdin;
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
pub struct FibonacciInputs {
    pub a: u64,
    pub b: u64,
    pub n: u64,
}

fn main() {
    // Initialize new stdin
    let mut stdin = Stdin::new();
    // example 1: write a u64 to the VM
    let n = 100u64;
    stdin.write(&n);

    // example 2: write a struct
    let inputs = FibonacciInputs { a: 0, b: 1, n };
    stdin.write(&inputs);

    // example 3: write a byte array
    let bytes = vec![1, 2, 3, 4];
    stdin.write_bytes(&bytes);
}
  1. CLI input option

The prove command --input option can take a hex string or a file path. the hex string must be match the length of the read type. For example, the input n = 100u64; the hex string should be 0x6400000000000000 in little-endian format.

RUST_LOG=info cargo pico prove --elf elf/riscv64im-pico-zkvm-elf --input "0x6400000000000000" --phase riscv

Read

Corresponding to the writer functions, there are read_as and read_vec tools for io reading the serializable object or bytes into the program.

SDK examples:


use pico_sdk::io::{read_as, read_vec};

#[derive(Serialize, Deserialize)]
pub struct FibonacciInputs {
    pub a: u64,
    pub b: u64,
    pub n: u64,
}

fn main() {
    // example 1: read the u64 input `n`
    let n: u64 = read_as();
    
    // example 2: read FibonacciInputs struct  
    let inputs = read_as::<FibonacciInputs>();
    
    // example 3: read a byte array
    let bytes: Vec<u8> = read_vec();
}

End-to-end Proving

This section introduces more advanced CLI options and SDK APIs to complete the end-to-end proving process. The Proving process consists of multiple stages, including RISCV, RECURSION, and EVM Phases.

RISCV-Phase

Prove RISC-V programs and generate an uncompressed proof with the --phase riscv option. The command is mainly used to test and debug the program.

CLI:

RUST_LOG=info cargo pico prove --elf elf/riscv64im-pico-zkvm-elf --phase riscv

For example, the input n in the Fibonacci is a u64 read through pico_sdk::io::read_as, so it must be in little-endian format and filled to 8 bytes.

RUST_LOG=info cargo pico prove --elf elf/riscv64im-pico-zkvm-elf --input "0x6400000000000000" --phase riscv

SDK:

#![allow(unused)]
fn main() {
// Initialize the prover.
let mut prover = Prover::new(&elf).expect("Failed to initialize the prover");

// Initialize new stdin and write the inputs.
let mut stdin = Stdin::new();

// Set up input
let n = 100u64;
stdin.write(&n);

let riscv_proof = prover.prove_to(stdin, Phase::Riscv).expect("Failed to generate proof");
}

RECURSION-Phase

CLI:

RUST_LOG=info cargo pico prove --elf elf/riscv64im-pico-zkvm-elf --phase wrap

Proving with --phase wrap will execute the prover up to and including the EMBED-Phase and write the inputs of the Gnark proof verification circuit. A contract accepts them only from whitelist mode. Without --phase, prove stops after the COMBINE phase.

options:

--output

You can specify the output path to generate the files prepared for the Gnark verification and default is pico_out in the current directory

RUST_LOG=info cargo pico prove --elf elf/riscv64im-pico-zkvm-elf --phase wrap --output outputs

SDK:

#![allow(unused)]
fn main() {
// Initialize the prover.
let mut prover = Prover::new(&elf).expect("Failed to initialize the prover");
// ... write to stdin as previously described
let proof = prover.prove_to(stdin, Phase::Wrap).expect("Failed to generate proof");
let output_dir = PathBuf::from_str(&"./outputs").expect("the output dir is invalid");

proof
    .write_wrap_artifacts(
        output_dir.join("wrap_constraints.json"),
        output_dir.join("wrap_groth16_witness.json"),
    )
    .expect("Failed to write the outputs");
}

Outputs

  • wrap_constraints.json: The schema of the stark proof constraints is used to transform to Gnark circuit constraints.
  • wrap_groth16_witness.json: input witnessness of Gnark circuit.

Dev mode and whitelist mode

Pico proves in one of two modes:

  • Dev mode, the default: each recursion step uses a circuit fitted to the run. Its COMBINE proof verifies only in the process that made it, and no contract accepts it.
  • Whitelist mode: every recursion step uses one of a fixed set of circuits, prepared ahead of time and shipped with Pico. Their verifying keys form the whitelist, identified by its root. A COMBINE proof then verifies in any process with the same whitelist, and the on-chain verifier has the root built in, so EVM proofs need this mode.

The two modes give the same program different program ids; a contract pins the whitelist-mode one. To prove in whitelist mode, set VK_VERIFICATION=true, MLE_VK_MAP and MLE_VK_ROOT for the CLI (see EVM-Phase), or build the SDK prover with shipped_whitelist().

EVM-Phase

The Pico CLI provides an EVM option to generate the program Groth16 proof and verifier contracts. It proves in whitelist mode only and runs gnark in a Docker image. From the root of a project made with the evm template:

CLI:

# Once: build the gnark image. The tag is your CLI's version.
docker build -t pico-gnark -f gnark/Dockerfile https://github.com/brevis-network/pico.git#v3.1.1

# Whitelist mode, with the whitelist in the template's whitelist/.
export VK_VERIFICATION=true
export MLE_VK_MAP=whitelist/mle_vk_map_kb.bin
export MLE_VK_ROOT="$(sed -n 's/^MLE_VK_ROOT=//p' whitelist/mle_vk_root.txt | tr -d '"')"
export PICO_GNARK_IMAGE=pico-gnark

# Set up the Groth16 PK/VK the first time, or after a version update.
cargo pico prove --elf app/elf/riscv64im-pico-zkvm-elf --input u32:10 --evm --setup --keys keys
# Generate the Groth16 proof with the existing keys.
cargo pico prove --elf app/elf/riscv64im-pico-zkvm-elf --input u32:10 --evm --keys keys

The EVM template runs the full flow, including the contract tests, and notes the machine it needs.

SDK:

#![allow(unused)]
fn main() {
// Initialize the prover in whitelist mode, which EVM proofs require.
let mut prover = Prover::builder(&elf)
    .shipped_whitelist()
    .build()
    .expect("Failed to initialize the prover");
let output_dir = PathBuf::from_str(&"./outputs").expect("the output dir is invalid");
// Writes the inputs of the Gnark circuit; the Groth16 proof itself is made by `cargo pico prove --evm`.
let bundle = prover.prove_evm(stdin).expect("Failed to generate evm proof");
bundle.write_to(output_dir).expect("Failed to write the outputs");
}

The outputs:

proof.data: Groth16 proof generated by the Gnark Verifier Circuit.

inputs.json: what the verifier contract is called with, including the public values.

With --setup, the Gnark Groth16 ProvingKey/VerificationKey is also generated at this step, into the --keys directory. The --setup only needs to be executed once; its keys are for testing only, since whoever runs the setup knows its randomness.

EVM Verification

The generated inputs.json format is as follows:

{
  "riscvVKey": "bytes32",
  "publicValues": "bytes",
  "committedValuesDigest": "bytes32",
  "proof": "uint256[12]"
}

After parsing the input data, you can call the PicoVerifier.sol as shown below:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

/// @title Pico Verifier Interface
/// @author Brevis Network
/// @notice This contract is the interface for the Pico Verifier.
interface IPicoVerifier {
    /// @notice Verifies a proof with given public values and riscv verification key.
    /// @param riscvVkey The verification key for the RISC-V program.
    /// @param publicValues The public values encoded as bytes.
    /// @param proof The proof of the riscv program execution in the Pico.
    function verifyPicoProof(
        bytes32 riscvVkey,
        bytes calldata publicValues,
        uint256[12] calldata proof
    ) external view;
}

The verifyPicoProof function in PicoVerifier.sol takes a RISC-V verification key, public values, and a Pico proof, using the Groth16 verifier to validate the proof and public inputs via the pairing algorithm. For the full implementation of the PicoVerifier, please refer to the repository here.

In production, you need to verify riscvVKey and parse the public values verified by PicoVerifier. You can refer to the Fibonacci.sol example in the repository here.

Features

Logging

Pico leverages Rust’s standard logging utilities to provide detailed runtime information, particularly about performance and program statistics. You can control the verbosity of the logs via the RUST_LOG environment variable:

  • Info Level: Set RUST_LOG=info to output overall performance data and high-level progress information.
  • Debug Level: Set RUST_LOG=debug to display detailed logs, including statistics of chunks and records as they are generated and processed.

For scenarios where you want to save logs to a file without color codes (which may be embedded by default), you can pipe the output through a tool like ansi2txt. This conversion ensures that the log file remains clean and free of terminal-specific formatting, as the tracing framework does not automatically adjust colors based on environment variables.

Debugging

In the rare event that proving fails on a correctly executing binary, Pico provides additional debug capabilities to assist in pinpointing issues:

  • Enhanced Debugging Features: Enable the debug and debug-lookups features when running the prover. These features provide extra context by outputting detailed information on individual constraints and lookup operations within each processing batch.
  • Minimal Memory Impact: Since debug information is generated from data already in memory for the current batch of proofs, enabling debugging does not incur a significant additional memory cost. The debug data can be discarded once the batch is processed and debugged.
  • Accessing Debug Data: Combine the debugging features with RUST_LOG=debug to capture detailed logs.

Guest VM Cycle Tracking

Please see VM Cycle Tracking for a detailed explanation of this feature.

Proving Options

Pico offers several configurable parameters to optimize the proving process for your system’s resources and performance requirements. cargo pico reads them from environment variables; with pico-prover, set them on ProverBuilder:

  • CHUNK_SIZE (chunk_size): the number of instructions executed per chunk. Defaults to 2^23.
  • PROVE_CONCURRENCY (concurrency): the number of RISC-V chunks proved at once. Defaults to 4. Each one holds a full proving working set, so lower it on a machine with less memory.

These options allow you to balance performance and resource utilization, making it possible to optimize Pico for a wide range of environments—from resource-constrained setups to high-performance systems.

Features

pico-vm comes enabled with several features by default. These being strict, rayon, and multi-field-transcript. strict is a compile time option for #![deny(warnings)] on the entire pico-vm module. rayon enables the usage of rayon’s ParallelIterator and related traits to use multithreading to speed up the proving process. This feature should be left on unless you wish to compile a single threaded prover for profiling reasons, as rayon tends to pollute the stack trace when running flamegraph. multi-field-transcript enables the EMBED and WRAP phases, which the EVM path needs.

To build pico-vm without default features, simply set default-features = false in your Cargo.toml or run cargo build -p pico-vm --no-default-features for your local build environment, maybe adding --example if you want to build a specific example in addition to the Rust library.

Single threaded profiling

As mentioned in the previous section, we support single threaded builds in order to generate neater flamegraphs for profiling purposes. For example, to build test_mle_e2e for profiling, run

cargo build -p pico-vm --no-default-features --profile profiling --example test_mle_e2e

to build the binary and then run

sudo flamegraph -o flamegraph.svg -- ./target/profiling/examples/test_mle_e2e --elf fib --n 10 --step riscv

with cargo flamegraph to produce a flamegraph that you can use to explore cost centers.

Advanced

Pico offers several advanced components that let you go beyond its default configuration. In this section, you’ll explore:

  • VM Instances: The fundamental building blocks for creating custom virtual machines.
  • ProverChains: Tools that enable you to compose tailored proving workflows.

Together, these powerful features empower you to build a customized VM that perfectly fits your application’s unique requirements.

Instances

Pico is architected as a chain of modular components, each tailored to perform a specific role in the overall ZK proof generation process. These components—known as machine instances—are instantiations of a virtual machine and comprise several submodules, including chips, compilers, emulators, and proving backends. This modular design not only simplifies the internal workflow but also provides developers with the flexibility to customize and extend the system to meet diverse application needs.

Built-in Machine Instances

The current release of Pico includes several built-in machine instances, each designed for a distinct phase of the proof generation pipeline:

RISCV

The RISCV instance is responsible for executing RISCV programs and generating the initial STARK proofs. It achieves this by:

  • Execution & Chunking: Running the program and dividing it into smaller, manageable chunks.
  • Parallel Proof Generation: Proving these chunks concurrently to generate a series of proofs, with the total number of proofs equaling the number of chunks.

CONVERT

Acting as the first step in the recursion process, the CONVERT instance transforms each STARK proof produced by the RISCV instance into a recursion-compatible STARK proof. This conversion is crucial for setting the stage for recursive proof composition.

COMBINE

The COMBINE instance aggregates m of recursion proofs generated from the same machine instance into a single STARK proof. By default, m is set to 2 in Pico, though it can be configured to a larger value. This instance is applied recursively to collapse a large collection of proofs into one final proof, forming a recursion tree. For example, if you start with n proofs, the first layer uses n/m COMBINE calls to produce n/m proofs; these are then aggregated in subsequent layers (n/m², n/m³, etc.) until only one proof remains. This consolidation streamlines subsequent processing and reduces overall complexity.

COMPRESS

Aiming to optimize efficiency in later recursive stage, the COMPRESS instance compresses a recursion STARK proof into a smaller-sized proof.

EMBED

As the final stage in generating a STARK proof, the EMBED instance embeds the STARK proof into the BN254 field. This prepares the proof for later conversion into an on-chain-verifiable SNARK.

Modularity and Internal Extensibility

Pico’s machine instances are designed with a strong emphasis on modularity and internal extensibility:

  • Purpose-Driven Specialization: Each machine instance is engineered to execute a specific phase of the proof generation process. This targeted design enhances performance and simplifies debugging, as each instance handles a distinct, well-defined task.
  • Isolated Upgradability: The self-contained nature of each machine instance allows developers to update, optimize, or replace individual components independently. This isolation promotes rapid iteration and integration of cutting-edge cryptographic techniques without disrupting the overall system.
  • Flexible Submodule Architecture: Within each instance, core functionalities are implemented via interchangeable submodules (e.g., chips, compilers, emulators, proving backends). This design enables targeted enhancements, such as swapping out a proving backend to leverage a more efficient prime field, without modifying the instance’s primary function.
  • Seamless Future Integration: By compartmentalizing functionalities into discrete units, Pico is primed for the adoption of new technologies. As innovative proving systems and cryptographic primitives emerge, they can be integrated into the framework without a complete overhaul, ensuring the platform evolves alongside technological advancements.

ProverChain

Pico empowers developers with the ProverChain—a feature that enables you to seamlessly chain together machine instances to create a complete, end-to-end ZK proof generation workflow. Leveraging Pico’s modular architecture, ProverChain allows you to design workflows tailored precisely to the needs of your application.

Proving Phases

Pico’s proving process is structured into distinct phases:

  • RISCV-Phase: The RISCV instance executes a RISCV program, generating a series of initial proofs.
  • RECURSION-Phase: The CONVERT, COMBINE, COMPRESS, and EMBED instances work together recursively to consolidate these proofs into a single STARK proof.
  • EVM-Phase: This final STARK proof is then fed into a Gnark prover to generate a on-chain-verifiable SNARK that is ready for deployment on EVM-based blockchains.

Default Proving Workflow

By default, Pico constructs a proving workflow by chaining the following machine instances:

RISCV → CONVERT → COMBINE → COMPRESS → EMBED → ONCHAIN (optional)

In this sequence:

  • RISCV- and the RECURSION-Phase handle the initial execution and recursive proof generation. It takes a RISCV program and input and generates an embedded STARK proof.
  • ONCHAIN—an optional instance—works at EVM-Phase and converts the embedded STARK proof into an EVM-verifiable SNARK.

Customizing Your Workflow

While the default workflow is designed for uniform efficiency, ProverChain offers exceptional flexibility, enabling developers to tailor the proving process to their specific requirements:

  • Chain Modification: Easily add, adjust, or remove machine instances. For example, if on-chain verification is not required, you can simply omit the ONCHAIN step.
  • Performance Optimization: Experiment with different configurations to achieve the optimal balance between proof size and proving efficiency. In some scenarios, accepting a slightly larger proof can lead to faster overall performance.
  • Intermediate Access: The ProverChain module exposes the intermediate steps—formatted as a sequence (e.g., stdin -> proof -> proof -> ... -> final proof)—allowing you to fine-tune internal parameters at each stage of the workflow.

VM Cycle Tracking

The Pico emulator supports the standard VM cycle tracking protocol, but we explicitly state its operation here.

To request the VM to track cycles for you, the emulator must be started with the appropriate option set to true. You can use EmulatorOpts::with_cycle_tracker, which produces an EmulatorOpts with the appropriate field set, or by setting the cycle_tracker field within EmulatorOpts. The naming of the field is subject to change, but the function should be somewhat stable for now.

The emulator will then maintain a mapping between Request ⇒ Clock Cycle and Request ⇒ Vec<# Clock Cycle>. Every time a cycle-tracker-start: Request is encountered, the current clock is stored into the Request ⇒ Clock Cycle map, overwriting any pre-existing value. Every time a cycle-tracker-end: Request is encountered, the start clock is retrieved from the Request ⇒ Clock Cycle map, inserting the current clock if it does not exist. The difference between the current clock and the retrieved clock is added to the Request ⇒ Vec<# Clock Cycle> mapping.

Put shortly, cycle-tracker-start stores the current clock, and cycle-tracker-end will report the number of elapsed cycles since the last observed cycle-tracker-start, using itself as a fallback. It is important to know that these requests must be terminated by a newline. If a guest program writes something along the lines of println!("cycle-tracker-start: {}", req), this may result in three write syscalls. One to write the prefix, one to write the formatted req, and one to write the final newline. In order to accurately capture the entire string after cycle-tracker-start: , a newline must be received before Pico will service the request. The request is the entire string after cycle-tracker-start: or cycle-tracker-end: and before the next newline character. Note that there is exactly one space after the colon (:).

This information can then be processed on the host side by iterating through the cycle_tracker field of the returned EmulationReport. These reports are batched per chunk in the sense that you only receive the results of cycle-tracker-end for the current batch, but they will still correctly track the cycle-tracker-start from a previous batch.

Cost Estimation

ProverBuilder::estimate_cost(stdin) (also on Prover) runs the program without proving and returns a CostEstimate: how much proving the run would take, and its cycle count. It covers the RISC-V phase only.

Function-level

Function-level coprocessors—commonly known as precompiles—are specialized circuits within Pico designed to optimize and streamline specific cryptographic operations and computational tasks. These precompiles handle operations such as elliptic curve arithmetic, hash functions, and signature verifications. In a general-purpose environment, these operations can be resource-intensive, but by offloading them to dedicated circuits, Pico significantly reduces computational costs, improves performance, and enhances scalability during proof generation and verification. Packaging these core operations into efficient, well-tested modules not only accelerates development cycles but also establishes a secure foundation for a wide range of zk-applications, including privacy-preserving transactions, rollups, and layer-2 scaling solutions.

Work Flow

Below is an example workflow of Keccak256 hash permutation precompile in Pico.

The Pico precompiles workflow involves several steps to efficiently execute and verify cryptographic operations. To illstrate how it works, we use Keccak-256 precompile as an example:

  1. Developer Preparation: Developers begin by writing and preparing the necessary code, including the tiny-keccak patch for cryptographic hashing functions. This library provides the core primitives needed for SHA2, SHA3, and Keccak-based operations.
  2. Tiny-Keccak Patch: Pico uses a forked and zero-knowledge-compatible version of tiny-keccak (sourced from the public debris repository). This patch optimizes hashing operations—particularly Keccak-256—to run efficiently within Pico.
  3. Keccak256 Precompile: When a Keccak-256 hashing function is invoked, Pico’s Keccak256 precompile is triggered to handle the specific permutation operations. This specialized circuit, known internally as the keccak256_permute_syscall, is optimized for performance, minimizing overhead and improving provability.
  4. Rust Toolchain & ELF Generation: The Rust toolchain compiles your code, including the tiny-keccak patch, into an Executable and Linkable Format (ELF) file, which is the RISC0’s support for zkVM executables.

By following this workflow, developers can perform cryptographic operations more efficiently and securely, taking full advantage of Pico’s precompile features to reduce proof overhead and streamline the development of ZK apps.

List of Syscalls

Pico is currently supporting these syscalls.

List of patches

Pico is currently supporting the following patches:

Patch NameGithub linkbranch
tiny-keccakhttps://github.com/brevis-network/tiny-keccakpatch-v1.0.0-rv64
sha2https://github.com/brevis-network/hashessha2-0.10.9-rv64
sha3https://github.com/brevis-network/hashessha3-0.10.8-v1.0.0-rv64
bls12381https://github.com/brevis-network/bls12_381patch-v1.0.1-rv64
k256https://github.com/brevis-network/elliptic-curvesk256-0.13.4-rv64
p256https://github.com/brevis-network/elliptic-curvesp256-0.13.2-rv64
substate-bnhttps://github.com/brevis-network/bnpatch-v1.0.1-rv64

Application-level

Application-level coprocessors extend far beyond individual function-level precompiles. Instead of optimizing a single cryptographic operation, these coprocessors integrate an array of specialized circuits that work together to tackle broader, domain-specific computational challenges. By incorporating application-level coprocessors, Pico not only enhances its performance but also serves as a versatile “glue” that seamlessly routes data between high-efficiency modules. This design enables Pico to be finely tuned for specific applications without sacrificing its overall flexibility and general-purpose utility—resulting in enhanced performance, improved scalability, and accelerated development cycles.

Pico can integrate a variety of exceptional coprocessors across different domains. For example:

  • On-Chain Data zkCoprocessors: Engineered to provide efficient and secure access to historical blockchain data, these coprocessors enables developers to retrieve and analyze past transaction records, state data, and other on-chain information with confidence. Brevis Coprocessor has already been successfully integrated into Pico. This solution will offer a comprehensive framework for building applications that depend on verifiable, reliable on-chain data processing. Detailed integration guidelines will be available soon.
  • zkML (Zero-Knowledge Machine Learning) Coprocessors : These coprocessors leverages ZK proofs to enable secure, privacy-preserving training and inference for machine learning models. It ensures that sensitive data and/or proprietary model information remain confidential throughout the process, opening the door to advanced, secure ML applications.

These application-level coprocessors empower Pico to support highly specialized, domain-specific tasks while preserving the generality and flexibility that make it a robust platform for a wide range of zero-knowledge applications.