If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/nexus-xyz/nexus-zkvm shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Slowing — last commit 4mo ago

• Last commit 4mo ago
• 44+ active contributors
• Distributed ownership (top contributor 27% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 4mo ago
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live nexus-xyz/nexus-zkvm repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/nexus-xyz/nexus-zkvm.

What it runs against: a local clone of nexus-xyz/nexus-zkvm — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in nexus-xyz/nexus-zkvm | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 152 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of nexus-xyz/nexus-zkvm. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/nexus-xyz/nexus-zkvm.git
#   cd nexus-zkvm
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of nexus-xyz/nexus-zkvm and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "nexus-xyz/nexus-zkvm(\\.git)?\\b" \\
  && ok "origin remote is nexus-xyz/nexus-zkvm" \\
  || miss "origin remote is not nexus-xyz/nexus-zkvm (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "common/src/lib.rs" \\
  && ok "common/src/lib.rs" \\
  || miss "missing critical file: common/src/lib.rs"
test -f "vm/src/lib.rs" \\
  && ok "vm/src/lib.rs" \\
  || miss "missing critical file: vm/src/lib.rs"
test -f "runtime/src/lib.rs" \\
  && ok "runtime/src/lib.rs" \\
  || miss "missing critical file: runtime/src/lib.rs"
test -f "prover/src/lib.rs" \\
  && ok "prover/src/lib.rs" \\
  || miss "missing critical file: prover/src/lib.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 152 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~122d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/nexus-xyz/nexus-zkvm"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Nexus zkVM is a modular, open-source zero-knowledge virtual machine written in Rust that generates proofs of computation without revealing inputs. Built on StarkWare's Stwo prover framework, it executes arbitrary programs on the zkVM and produces cryptographic proofs of correct execution, targeting performance and security with fully public specifications. 12-crate monorepo organized as: runtime/ (core VM execution), prover/ and prover2/ (Stwo integration and AIR machine definitions), vm/ (VM bytecode/state), precompiles/ (optimized cryptographic operations), core/ (primitives), sdk/ (user-facing API), cli/ (cargo-nexus toolchain), and examples/ (runnable programs). Proof generation flows through prover2/air-column and prover2/machine components.

Cryptography researchers and blockchain developers building zero-knowledge proof systems who need a transparent, extensible VM for proving program execution. Contributors include protocol engineers optimizing prover performance and zkVM language toolchain developers.

Experimental alpha stage (v0.3.6). The repo has active CI/CD (workflows in .github/workflows/), comprehensive workspace structure with 12+ crates, and StarkWare Stwo dependency integration, but README explicitly states 'not currently recommended for production use.' Actively maintained with consistent versioning and modular design indicating serious development, but not yet battle-tested.

Primary risk is external dependency on StarkWare's Stwo proving library (pinned to rev 0790eba), which could introduce breaking changes upstream. Alpha maturity means the zkVM specification and API are not stable (see specification/zkvm-spec-3.0.pdf). No obvious single-maintainer concentration visible, but small team (given experimental status). Integration of precompiles and machine-specific AIR constraints in prover2/ suggests complex proof generation that could have undiscovered edge cases.

Cannot determine exact recent commits from provided data, but the workspace includes actively-structured prover2/ directory with AIR column derivation (air-column-derive/) and machine definitions, suggesting ongoing work on proof system optimization. Benchmarking infrastructure (benchmarks/benches/integration_bench.rs) indicates performance work is in progress.

git clone https://github.com/nexus-xyz/nexus-zkvm.git
cd nexus-zkvm
cargo build --release
cargo test  # Run test suite

Daily commands: Development workflow varies by crate. For the zkVM CLI: cargo run -p cli --bin cargo-nexus -- <command>. For running proofs: reference examples/ and benchmarks/benches/integration_bench.rs as integration test templates. No explicit dev server; this is a proving system, not a service.

• Cargo.toml — Workspace root defining all member crates and shared dependencies; essential for understanding the project structure and build configuration
• common/src/lib.rs — Core abstractions for CPU, memory, RISC-V instruction handling, and error types used across the entire zkVM
• vm/src/lib.rs — Virtual machine implementation entry point; contains the main execution engine
• runtime/src/lib.rs — Runtime layer providing execution environment and program initialization
• prover/src/lib.rs — Zero-knowledge proof generation system; core proving mechanism built on Stwo
• common/src/riscv/instruction.rs — RISC-V instruction definitions and encoding; fundamental to all program execution
• README.md — Project overview, mission statement, and links to specification; required reading for context

Add a New RISC-V Instruction

1. Define the opcode in the opcode enumeration (common/src/riscv/opcode.rs)
2. Add instruction structure and encoding logic (common/src/riscv/instruction.rs)
3. Implement execution logic in the VM fetch-decode-execute cycle (vm/src/lib.rs)
4. Add test case in the VM test suite (vm/src/lib.rs)

Add a New Cryptographic Precompile

1. Review precompile interface and design patterns (precompiles/design.md)
2. Create a new precompile module under precompiles/examples or extend precompiles/src (precompiles/Cargo.toml)
3. Implement the precompile with input validation and output serialization (precompiles/examples/dummy_div/Cargo.toml)
4. Register the precompile in the VM's syscall/exception handler (vm/src/lib.rs)
5. Add example usage demonstrating the precompile (examples/src/bin/precompiles/keccak_precompile.rs)

Create a New Example Program

1. Create a new binary file in examples/src/bin/ (examples/src/bin/fib.rs)
2. Use SDK macros and the runtime environment to structure your program (sdk/src/lib.rs)
3. For I/O examples, follow the pattern in examples/src/bin/io/ (examples/src/bin/io/input_output.rs)
4. Ensure the example compiles with the examples/Cargo.toml configuration (examples/Cargo.toml)

Extend the Proving System

1. Understand the current prover interface and Stwo integration (prover/src/lib.rs)
2. Add trace column definitions using the AIR framework (prover2/air-column/src/lib.rs)
3. Extend the machine architecture with new components (prover2/machine/src/lib.rs)
4. Register the new machine in the proving pipeline and add benchmarks (benchmarks/src/runner.rs)

• Rust — Memory safety without GC, performance-critical for proving operations, strong type system for correctness guarantees
• Stwo (Starkware) — State-of-the-art STARK proving system with optimized polynomial commitments and transparent setup
• RISC-V ISA — Open, modular instruction set enabling portability and security analysis; reduces custom instruction complexity
• Workspace Monorepo (Cargo) — Enables shared dependency management and atomic versioning across VM, prover, SDK, and tooling

• Prover-optimized design over universal VM compatibility

  • Why: Nexus prioritizes zero-knowledge proof generation efficiency
  • Consequence: Some edge-case RISC-V instructions or behaviors may not be fully supported; proof sizes and performance vary with instruction complexity

• Modular precompile system instead of hardcoded cryptography

  • Why: Extensibility and custom domain support
  • Consequence: Developers must explicitly register precompiles; risk of inconsistent implementations if guidelines not followed

• Transparent STARK proofs (Stwo) over private-setup SNARKs

  • Why: Stronger security assumptions and no trusted setup ceremony
  • Consequence: Larger proof sizes and longer proving times than optimized SNARK systems like Groth16

• Single-threaded VM execution for trace determinism

  • Why: Ensures reproducible execution traces for proof verification
  • Consequence: No built-in parallelism for CPU-heavy computations; parallelization handled at proving layer only

• Does not support concurrent/multi-threaded program execution
• Not a replacement for traditional VMs; optimized for zero-knowledge proof generation, not general-purpose computing speed
• Does not include a formal language compiler; users write in Rust with SDK
• Not production-ready (alpha stage); experimental proving system still undergoing optimization
• Does not provide privacy at the hardware level; privacy guarantees derive from zero-knowledge proofs only
• Not a blockchain execution layer; requires external host for program I/O and state transitions

Stwo dependency pinning: Stwo is pinned to a specific git rev (0790eba), not a release version—this can break silently if upstream changes the API. AIR/Constraint complexity: The prover2/air-column-derive/ macro generates constraint code; modifying AIR requires understanding StarkWare's constraint framework, not just Rust. Specification coupling: The VM must exactly implement specification/zkvm-spec-3.0.pdf; deviations invalidate proofs. Profile selection: profile.ci-test vs profile.release differ significantly (thin LTO vs full); wrong choice breaks benchmarks. No obvious CONTRIBUTING.md specifics visible: check .github/pull_request_template.md and CONTRIBUTING.md for contribution workflow.

• AIR (Algebraic Intermediate Representation) — Proof generation in Nexus uses AIR to encode computation as polynomial constraints; understanding AIR is essential to extending or modifying the prover
• STARK (Scalable Transparent ARgument of Knowledge) — Nexus produces STARK proofs via Stwo; STARKs are collision-resistant without trusted setup, which is why Nexus can be fully transparent
• Zero-Knowledge Proof — The core cryptographic primitive: Nexus generates proofs that a computation executed correctly without revealing the computation's inputs or internal state
• Virtual Machine (VM) Instruction Set — The zkVM defines a bytecode instruction set (executed in runtime/); understanding the ISA is necessary for compiling programs or debugging execution
• Precompile (Cryptographic Primitive) — Nexus uses precompiles (e.g., keccak in tiny-keccak) to optimize expensive crypto operations outside the main proof loop; adding precompiles is a common extension
• Constraint Framework (Proof System) — Stwo's constraint framework (stwo-constraint-framework in Cargo.toml) encodes zkVM semantics as polynomial equations; proof generation validates constraints over finite fields
• Finite Field Arithmetic — All zkVM state transitions and proof computations occur in finite fields (not regular integers); this is why Stwo's field implementations are critical to correctness and performance

• starkware-libs/stwo — The foundational prover library that nexus-zkvm builds on top of; all proof generation ultimately delegates to Stwo's constraint solver
• facebook/winterfell — Alternative Rust-based zkVM/STARK prover with similar transparency goals; useful for comparing architectural choices
• risc0/risc0 — Competing zkVM project targeting RISC-V; helps understand the zkVM design space and performance trade-offs
• nexus-xyz/nexus-docs — Official documentation repository for Nexus zkVM; essential for understanding user-facing API and getting-started guides
• starkware-libs/cairo — Cairo language that compiles to StarkWare's prover; relevant for understanding how programs target the Nexus zkVM

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for CLI commands in cli/src/command/

The CLI module (cli/src/command/host.rs and cli/src/bin/cargo-nexus.rs) lacks visible test coverage. Given this is a user-facing interface for the zkVM, integration tests validating command parsing, execution flows, and error handling would catch regressions early and improve maintainability as the CLI evolves.

• [ ] Create tests/cli_integration_tests/ directory with test modules for each command
• [ ] Add integration tests in tests/ for cargo-nexus.rs subcommands (create, prove, verify workflows)
• [ ] Add unit tests in cli/src/command/ for argument parsing and command validation
• [ ] Update .github/workflows/ci.yml to run CLI tests with real project scenarios
• [ ] Document test setup in CONTRIBUTING.md for CLI development

Add missing benchmark suite for core RISC-V instruction execution in common/src/riscv/

The benchmarks/ directory exists but benchmarks/benches/integration_bench.rs appears to only benchmark at integration level. The RISC-V instruction set (common/src/riscv/instruction.rs, opcode.rs, encoder.rs) lacks dedicated performance benchmarks. These would help identify performance bottlenecks in the VM's core execution loop and inform optimization priorities.

• [ ] Create benchmarks/benches/riscv_instruction_bench.rs for encoding/decoding performance
• [ ] Add benchmarks for common RISC-V instruction types (load, store, arithmetic, branch)
• [ ] Create benchmarks/benches/cpu_bench.rs for register operations and PC updates (common/src/cpu/)
• [ ] Add benchmark results tracking to CI via .config/nextest.toml and GitHub Actions
• [ ] Document benchmark methodology in CONTRIBUTING.md

Add memory safety and alignment validation tests for common/src/memory/

The memory module has alignment.rs and traits.rs but no visible test suite. Memory safety is critical in a zkVM. Adding comprehensive tests for alignment requirements, bounds checking, and edge cases in memory access patterns would prevent subtle bugs and validate the correctness of memory operations across the VM.

• [ ] Add unit tests in common/src/memory/alignment.rs for all alignment variants and their validation
• [ ] Create common/src/memory/tests.rs with comprehensive memory trait implementation tests
• [ ] Add property-based tests using proptest for memory address generation and access patterns
• [ ] Add tests validating memory error conditions from common/src/error/memory.rs
• [ ] Ensure memory tests run in CI and document memory safety invariants in code comments

• Add integration tests for precompiles/: currently no visible test harness for cryptographic precompiles in the file structure; contributors could write test suites validating keccak and other precompute outputs against spec
• Document the AIR constraint framework usage: prover2/air-column-derive/ macro has no visible inline documentation; add examples showing how to define new constraint polynomials for a custom zkVM feature
• Benchmark specific opcodes: benchmarks/benches/integration_bench.rs exists but likely tests full programs; profile individual CPU opcodes (common/src/cpu/) to identify hot paths and optimization opportunities

The Nexus zkVM codebase demonstrates reasonable security practices for a cryptographic project, including workspace isolation, controlled publishing restrictions, and optimization for performance. However, several areas require attention: (1) dependency management could benefit from more rigorous verification mechanisms given the alpha status of the project, (2) no visible supply chain security infrastructure (cargo-deny/audit) is evident, and (3) the project lacks formal security documentation policies. The most significant concern is the reliance on git dependencies from external sources without additional verification mechanisms. For a zero-knowledge VM project, this maturity level is acceptable for research/development but requires security hardening before production deployment. Recommendations include implementing dependency scanning, creating a security policy document, and considering signed/auditable build configurations.

• Medium · Pinned Git Dependency Without Hash Verification — Cargo.toml - workspace.dependencies (stwo, stwo-constraint-framework). The Cargo.toml uses git dependencies (stwo and stwo-constraint-framework) pinned to a specific revision but sourced from GitHub. While a revision hash is specified (0790eba), this approach relies on GitHub's availability and doesn't protect against potential tampering if the repository is compromised. Fix: Consider using vendored dependencies or git submodules with signed commits. Implement dependency verification checks in CI/CD pipeline. Consider forking critical dependencies if not already done.
• Medium · Missing Publish Restrictions — Cargo.toml - workspace.package (publish = false). While 'publish = false' is set in workspace.package, the public nature of the repository combined with zero-knowledge cryptography code requires careful review. No evidence of crate signing or verified publisher policies. Fix: Implement crate signing for any published artifacts. Use cargo-deny or similar tools to audit supply chain. Document the publishing process and restrictions.
• Medium · Aggressive LTO and Codegen Settings in Release Profile — Cargo.toml - [profile.release]. The release profile uses 'codegen-units = 1' and 'lto = true', which optimizes for performance but may obscure binary analysis and make debugging production issues more difficult. For security-critical cryptographic code, this can complicate auditing. Fix: Consider maintaining a separate 'auditable' build profile with higher codegen-units and disabled LTO for security audits. Document the security implications of these optimizations.
• Low · No Evidence of Dependency Vulnerability Scanning — .github/workflows/ci.yml (not provided but referenced). No visible dependency vulnerability scanning configuration (e.g., cargo-deny, cargo-audit) in the provided file structure, though this doesn't mean it's absent in CI. Fix: Implement cargo-deny with vulnerability checks in CI/CD pipeline. Add 'cargo audit' as a required check. Create a documented vulnerability disclosure policy.
• Low · No Security.md or Vulnerability Disclosure Policy — Repository root (SECURITY.md missing). CONTRIBUTING.md exists but no SECURITY.md file detected in the repository. This is important for a cryptographic project where security researchers may need to report vulnerabilities responsibly. Fix: Create a SECURITY.md file outlining the vulnerability disclosure process, contact information for security issues, and responsible disclosure guidelines.
• Low · Experimental/Alpha Stage Without Clear Security Warnings — README.md. The README indicates the zkVM is in 'Alpha' stage, but the specification reference and repository structure suggest production usage patterns. Alpha-stage cryptographic software requires explicit security warnings. Fix: Add prominent security warnings about alpha status in README and documentation. Include audit status, known limitations, and recommendations for production use.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.