How brevis-network/pico works
Project type and purpose
• Pico is an open-source, Rust-based zero-knowledge virtual machine (zkVM) library and CLI tool.
• It implements a “Glue-and-Coprocessor” architecture, with interchangeable proving backends (KoalaBear, BabyBear, Mersenne31) across multiple proof phases (RISCV, Convert/Recursion, Combine/Recursion, Compress/Recursion, Onchain/EVM).
• The workspace contains:
• Core zkVM engine (“vm” crate) – chips, gadgets, emulator, compiler, machine builder, proverchain
• SDK crates (“sdk/cli”, “sdk/sdk”, “sdk/patch-libs”) – client libraries and CLI front-end
• Proving backend glue (“gnark” folder) – Go code + Rust FFI
• Macro derivation support (“derive” crate)
• Examples (“examples”), performance benchmarks (“perf”), and orchestration scripts (“scripts”).
File structure
• Top-level Cargo workspace: Cargo.toml, member crates: derive, sdk, vm, perf, scripts, gnark, plus examples.
• “vm/src”: modular subpackages:
• chips & gadgets: arithmetic & crypto constraints
• emulator: RISC-V interpreter for proof trace recording
• compiler: RISC-V → Air trace translator, recursion IR
• machine: proof builder, prover & verifier, witness generation
• proverchain: orchestrates multi-phase proofs (convert/combine/compress/embed)
• instances: configuration & type-specialized circuit builders
• “sdk/cli”: CLI commands (cargo-pico), build/prove/new
• “sdk/sdk”: on-chain client library, RISC-V ecalls, IO, heap, math, verify
• “gnark”: Go modules for KoalaBear & BabyBear proving backends, plus FFI glue (“field-ffi” Rust crate).
• “perf”: benchmarking harness & ELF test apps.
• “derive”: Rust procedural macros for generating circuit code.
README for additional insights
• Emphasizes modular proving backends, four proof phases, and extendibility via circuit/coprocessor modules.
• Points to “docs/layout.md” for repo structure and “docs/requirements.md” for dependencies.
a. Main components:
[CLI / SDK Layer]
• pico-cli (sdk/cli)
• client API library (sdk/sdk)
[Core zkVM Engine]
• Compiler (riscv, recursion IR)
• Emulator (trace recorder)
• Machine builder & ProverChain
• Chips & Gadgets modules (arithmetic, crypto)
[Proving Backends]
• KoalaBear STARK (Go + field-ffi)
• BabyBear STARK (Go + field-ffi)
• (Future) Mersenne31 CircleSTARK
[Onchain/EVM Verifier]
• EVM-compatible verifier code
[Auxiliary]
• derive macros crate
• examples & perf bench apps
• orchestration scripts
b. Relationships & data flow:
1. User invokes pico-cli → calls SDK client API →
2. SDK submits ELF binary to zkVM Engine →
3. Compiler generates AIR trace; Emulator records execution trace →
4. Machine builder and ProverChain orchestrate proof phases:
• RISCV phase → trace → invoke proving backend via FFI → proof
• Recursion phases (Convert, Combine, Compress) → subsequent proofs
• Onchain phase → final proof artifact for EVM
5. Proving backend (Go) returns proofs over FFI → SDK or CLI outputs proof files.
6. Onchain proofs can be deployed/verified by EVM verifier.
7. derive crate generates Rust code for circuits/instances; examples and perf use these crates.
c. Architectural patterns & principles:
• Layered architecture: CLI/SDK → Core Engine → Backends → Onchain
• Plugin/back-end swap: abstract proving backend interface, inject KoalaBear or BabyBear
• Modular circuit design: chips & gadgets grouped by function, instances for config
• Multi-phase pipeline: sequential proof generation (RISCV → recursion → onchain)
d. Key technologies/frameworks:
• Rust Cargo workspace, procedural macros (derive)
• Go modules (gnark backends) + Rust FFI (field-ffi)
• Rayon for parallel iteration in vm/src/iter
• RISC-V emulator, STARK protocols