# brevis-network/pico architecture

> Architecture diagram of the GitHub repository brevis-network/pico, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brevis-network/pico
- Repository: https://github.com/brevis-network/pico

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI/SDK Layer
    subgraph "CLI/SDK Layer"
        direction TB
        pico_cli["pico-cli"]:::blue
        client_sdk["Client API Library"]:::blue
    end

    %% Core zkVM Engine
    subgraph "Core zkVM Engine"
        direction TB
        Compiler["Compiler"]:::green
        Emulator["Emulator"]:::green
        ChipsGadgets["Chips & Gadgets"]:::green
        MachineBuilder["Machine Builder"]:::green
        ProverChain["ProverChain"]:::green
        Instances["Circuit Instances"]:::green
    end

    %% Proving Backends
    subgraph "Proving Backends"
        direction TB
        KoalaBear["KoalaBear STARK"]:::orange
        KoalaBearVerifier["KoalaBear Verifier"]:::orange
        BabyBear["BabyBear STARK"]:::orange
        BabyBearVerifier["BabyBear Verifier"]:::orange
        FieldFFI["Rust FFI Glue"]:::orange
    end

    %% Onchain/EVM Verifier
    subgraph "Onchain/EVM Verifier"
        direction TB
        OnchainVerifier["EVM Verifier"]:::purple
    end

    %% Auxiliary
    subgraph "Auxiliary"
        direction TB
        Derive["derive Crate"]:::grey
        Examples["Examples"]:::grey
        Perf["Performance Benchmarks"]:::grey
        Scripts["Orchestration Scripts"]:::grey
    end

    %% Connections
    pico_cli -->|invokes| client_sdk
    client_sdk -->|submits ELF| Compiler
    Compiler -->|generates AIR trace| Emulator
    Emulator -->|records trace| ProverChain
    ProverChain -->|uses circuits| Instances
    ProverChain -->|calls via FFI| FieldFFI
    FieldFFI -->|invokes| KoalaBear
    FieldFFI -->|invokes| BabyBear
    KoalaBear -->|returns proof| ProverChain
    BabyBear -->|returns proof| ProverChain
    ProverChain -->|outputs proof| OnchainVerifier
    Derive -->|generates circuit code| Instances
    Examples -->|use crates| Compiler
    Perf -->|benchmarks| ProverChain
    Scripts -->|orchestrates| ProverChain

    %% Click Events
    click pico_cli "https://github.com/brevis-network/pico/tree/main/sdk/cli/"
    click client_sdk "https://github.com/brevis-network/pico/tree/main/sdk/sdk/"
    click Compiler "https://github.com/brevis-network/pico/tree/main/vm/src/compiler/"
    click Emulator "https://github.com/brevis-network/pico/tree/main/vm/src/emulator/"
    click MachineBuilder "https://github.com/brevis-network/pico/tree/main/vm/src/machine/builder/"
    click ProverChain "https://github.com/brevis-network/pico/tree/main/vm/src/proverchain/"
    click ChipsGadgets "https://github.com/brevis-network/pico/tree/main/vm/src/chips/"
    click KoalaBear "https://github.com/brevis-network/pico/tree/main/gnark/koalabear/"
    click KoalaBearVerifier "https://github.com/brevis-network/pico/tree/main/gnark/koalabear_verifier/"
    click BabyBear "https://github.com/brevis-network/pico/tree/main/gnark/babybear/"
    click BabyBearVerifier "https://github.com/brevis-network/pico/tree/main/gnark/babybear_verifier/"
    click FieldFFI "https://github.com/brevis-network/pico/tree/main/gnark/field-ffi/src/"
    click Derive "https://github.com/brevis-network/pico/blob/main/derive/src/lib.rs"
    click Examples "https://github.com/brevis-network/pico/tree/main/examples/"
    click Perf "https://github.com/brevis-network/pico/tree/main/perf/"
    click Scripts "https://github.com/brevis-network/pico/tree/main/scripts/"
    click Instances "https://github.com/brevis-network/pico/tree/main/vm/src/instances/compiler/onchain_circuit/"

    %% Styles
    classDef blue fill:#BEE3F8,stroke:#4299E1,stroke-width:2px
    classDef green fill:#C6F6D5,stroke:#38A169,stroke-width:2px
    classDef orange fill:#FEEBC8,stroke:#DD6B20,stroke-width:2px
    classDef purple fill:#E9D8FD,stroke:#805AD5,stroke-width:2px
    classDef grey fill:#EDF2F7,stroke:#A0AEC0,stroke-width:2px
```
