How nexus-xyz/nexus-zkvm works
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