# nexus-xyz/nexus-zkvm architecture

> Architecture diagram of the GitHub repository nexus-xyz/nexus-zkvm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nexus-xyz/nexus-zkvm
- Repository: https://github.com/nexus-xyz/nexus-zkvm

## Overview

##### Project type and purpose
- This is a multi-crate Rust workspace implementing the Nexus zero-knowledge virtual machine (zkVM). It provides:
- A command-line interface (cli) for building and proving zkVM programs
- A runtime and macro system to compile guest code into RISC-V binaries with precompiles
- A VM emulator (vm) to execute or trace these binaries
- One or more provers (prover and prover2) that take execution traces and produce zk-SNARK/STARK proofs
- An SDK for Rust developers to integrate with and extend the VM
- Precompile crates that let you insert host functions (e.g., cryptographic primitives)
- Benchmarks, examples, tests, and common shared libraries

##### File structure
- Top-level Cargo.toml and workspace: orchestrates all sub-crates.
- “cli”: cargo-nexus plugin, progress bar, commands.
- “runtime”: macros + build.rs + RISC-V linker scripts—turns guest Rust programs into RISC-V binaries with embedded precompiles.
- “vm”: RISC-V emulator, memory layers, syscall interface, instruction definitions.
- “precompiles”: host/guest interface code for built-in functions (keccak, dummy DIV, etc.), plus macro generation.
- “prover” & “prover2”: two prover implementations (original and AIR-based), with chips/components, column generators, trace builders, AIR constraints, STARK proving and verification.
- “sdk”: Rust APIs, compiler integration, macros (profilers, pprof), examples.
- “common” & “common-testing”: shared CPU/memory traits, constants, emulator utilities.
- “examples”, “tests”, “benchmarks”: demonstration programs, integration tests, performance benchmarks.

##### README
- Emphasizes modularity, extensibility, performance, and open-science ethos.
- Mentions Stwo/​StarkWare for the underlying proving technology.
- Points to a formal specification (zkvm-spec-3.0.pdf).

##### Diagramming the architecture
a. Main components:
- User/CLI Layer (“cli” crate)
- Developer SDK (“sdk” crate + macros)
- Build & Link Layer (“runtime” crate + linker-scripts + macros)
- Guest Code + Precompiles (compiled to RISC-V via “runtime” + “precompiles”)
- VM Emulator & Trace Generator (“vm” crate + “common-testing”)
- Prover(s) (two flavors: “prover” and “prover2” crates)
- Shared Libraries (“common”, “core”)
- External Services: Stwo/STARK proving backend
b. Relationships & data flows:
1. Developer writes Rust “guest code” + uses SDK macros
2. CLI invokes “runtime” to compile & link guest code into a RISC-V binary, embedding precompiles
3. CLI or user invokes VM emulator to execute or generate a trace of that binary
4. Trace output flows into a Prover (prover2 AIR-based or original prover)
5. Prover interacts with external STARK backend (Stwo) to create a zk proof
6. Proof is returned to CLI, then output to user or on-chain consumer
7. SDK also exposes APIs for writing host clients, embedding proofs, verifying, and instrumentation
c. Important architectural patterns:
- Modular multi-crate workspace—each subsystem in its own crate
- Clear separation between compile/link (runtime) vs. execution (vm) vs. proving (prover*)
- Use of code-generation macros for precompiles & profiling
- Pluggable prover backends (original vs. AIR-based)
d. Key technologies/frameworks:
- Rust and Cargo workspaces
- RISC-V toolchain (linker scripts, build.rs)
- STARK proving via Stwo
- serde, anyhow, tracing (likely common crates)
- CLI uses clap or similar (inferred from command structure)

##### Detailed capture
- Flow from “guest Rust code” → “RISC-V binary” → “Trace” → “Proof”
- Data artifacts: binary (.elf), trace file, proof object
- That tests and benchmarks sit alongside but do not alter the core flow

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User & SDK Layer
    CLI["CLI (cli)"]:::user
    SDK["SDK (sdk)"]:::user

    %% Build & Compile Layer
    subgraph "Build & Compile"
        direction TB
        Runtime["Runtime (runtime)"]:::build
        Precompiles["Precompiles (precompiles)"]:::build
    end

    %% Execution & Trace Layer
    subgraph "Execution & Trace"
        direction TB
        VM["VM Emulator (vm)"]:::exec
        Core["Core Libraries (core)"]:::exec
        CommonTest["Common Testing (common-testing)"]:::exec
    end

    %% Shared Utilities
    Common["Common Libraries (common)"]:::util

    %% Proving Layer
    subgraph "Proving"
        direction TB
        ProverV1["Prover v1 (prover)"]:::prov
        ProverV2["Prover v2 (prover2)"]:::prov
        STARK["External STARK Service (Stwo)"]:::prov
    end

    %% Artifacts & Extras
    Benchmarks["Benchmarks"]:::util
    Examples["Examples"]:::util
    Tests["Integration & Testing"]:::util
    Spec["Specification (zkvm-spec-3.0.pdf)"]:::util

    %% Data Flow
    CLI -->|"uses SDK macros"| SDK
    CLI -->|"compile & link"| Runtime
    SDK -->|"provides macros & APIs"| Runtime
    Runtime -->|"embeds precompiles"| Precompiles
    Runtime -->|"outputs RISC-V binary"| VM
    Precompiles -.->|trait & macro code| Runtime
    Common -->|shared traits & constants| Runtime
    Common -->|shared traits & constants| VM
    Core -->|core APIs| VM
    CommonTest -->|testing utilities| VM
    VM -->|"executes & generates trace"| ProverV1
    VM -->|"executes & generates trace"| ProverV2
    ProverV1 -->|"proving request"| STARK
    ProverV2 -->|"proving request"| STARK
    STARK -->|"returns proof"| ProverV1
    STARK -->|"returns proof"| ProverV2
    ProverV1 -->|"proof output"| CLI
    ProverV2 -->|"proof output"| CLI

    %% Auxiliary components
    CLI --> Benchmarks
    CLI --> Examples
    CLI --> Tests
    CLI --> Spec

    %% Click Events
    click CLI "https://github.com/nexus-xyz/nexus-zkvm/tree/main/cli/"
    click SDK "https://github.com/nexus-xyz/nexus-zkvm/tree/main/sdk/"
    click Runtime "https://github.com/nexus-xyz/nexus-zkvm/tree/main/runtime/"
    click Precompiles "https://github.com/nexus-xyz/nexus-zkvm/tree/main/precompiles/"
    click VM "https://github.com/nexus-xyz/nexus-zkvm/tree/main/vm/"
    click Core "https://github.com/nexus-xyz/nexus-zkvm/tree/main/core/"
    click Common "https://github.com/nexus-xyz/nexus-zkvm/tree/main/common/"
    click CommonTest "https://github.com/nexus-xyz/nexus-zkvm/tree/main/common-testing/"
    click ProverV1 "https://github.com/nexus-xyz/nexus-zkvm/tree/main/prover/"
    click ProverV2 "https://github.com/nexus-xyz/nexus-zkvm/tree/main/prover2/"
    click Benchmarks "https://github.com/nexus-xyz/nexus-zkvm/tree/main/benchmarks/"
    click Examples "https://github.com/nexus-xyz/nexus-zkvm/tree/main/examples/"
    click Tests "https://github.com/nexus-xyz/nexus-zkvm/tree/main/tests/"
    click Spec "https://github.com/nexus-xyz/nexus-zkvm/blob/main/specification/zkvm-spec-3.0.pdf"

    %% Styles
    classDef user fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef build fill:#98FB98,stroke:#333,stroke-width:1px
    classDef exec fill:#FFA500,stroke:#333,stroke-width:1px
    classDef prov fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef util fill:#EEEEEE,stroke:#666,stroke-width:1px,stroke-dasharray: 2 2
```
