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/ProvableHQ/snarkOS 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.

GO — Healthy across the board

• Last commit today
• 5 active contributors
• Distributed ownership (top contributor 43% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{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 ProvableHQ/snarkOS repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ProvableHQ/snarkOS.

What it runs against: a local clone of ProvableHQ/snarkOS — 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 ProvableHQ/snarkOS | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch staging exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ProvableHQ/snarkOS. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ProvableHQ/snarkOS.git
#   cd snarkOS
#
# 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 ProvableHQ/snarkOS and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "cli/src/lib.rs" \\
  && ok "cli/src/lib.rs" \\
  || miss "missing critical file: cli/src/lib.rs"
test -f "node/bft/Cargo.toml" \\
  && ok "node/bft/Cargo.toml" \\
  || miss "missing critical file: node/bft/Cargo.toml"
test -f "account/src/lib.rs" \\
  && ok "account/src/lib.rs" \\
  || miss "missing critical file: account/src/lib.rs"
test -f "build.rs" \\
  && ok "build.rs" \\
  || miss "missing critical file: build.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 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
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/ProvableHQ/snarkOS"
  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).

snarkOS is a decentralized operating system that powers the Aleo network, using zero-knowledge proofs to verify transactions and store encrypted application state in a publicly-verifiable manner. It's a Rust-based consensus system with three node types (Validator, Client, Prover) that coordinate over P2P to maintain a distributed ledger without trusted intermediaries. Monorepo structure: Cargo workspace with domain-separated crates likely in subdirs (snarkos-node, snarkos-ledger, snarkos-account inferred from 'node types' and 'state' concepts). CI and devnet automation in .ci/ and .devnet/ directories (shell scripts, Python helpers in .ci/rest_api_helper.py for REST API testing). .resources/ holds assets and license headers. .rustfmt.toml and .rusty-hook.toml enforce code style.

Blockchain infrastructure developers and operators running Aleo nodes (validators bonded into committee, clients relaying transactions, provers solving puzzles), plus cryptography researchers implementing ZK applications on Aleo.

Production-ready with active development: 2.15M lines of Rust, 59 contributors, CircleCI + codecov integration, comprehensive test coverage visible in .ci/ scripts (devnet, sync, upgrade tests). Recent activity evident from release workflow and benchmarking infrastructure (.github/workflows/benchmarks.yml, .github/workflows/release.yml).

Core risk is cryptographic complexity—bugs in ZK proof verification could silently corrupt ledger state. Medium risk from consensus coordination (BFT syncing shown in .ci/bench_bft_sync.sh suggests tight state machine). Dependencies appear minimal and intentional (audit.toml present); however, breaking changes across validator/client/prover interop could fracture network at upgrade points (test_full_upgrade.sh, test_partial_upgrade.sh suggest this is a known concern).

Active focus on upgrades and sync stability: test_full_upgrade.sh, test_partial_upgrade.sh, test_reset_minority.sh suggest consensus safety is under active testing. Benchmarking infrastructure added (benchmarks.yml workflow) for BFT, CDN, and P2P sync performance. Release automation present (.cargo/release-version, release.yml).

git clone https://github.com/ProvableHQ/snarkOS.git
cd snarkOS
cargo build --release
./target/release/snarkos --help

For local devnet: bash .devnet/install.sh && bash .devnet/start.sh (see .devnet/README.md).

Daily commands: Development: cargo build && cargo test. Local node: ./snarkos --validator or ./snarkos --client (see README §3). Devnet: .devnet/start.sh starts multi-node testnet. Benchmarks: .ci/bench_*.sh scripts run performance tests.

• Cargo.toml — Root workspace manifest defining all dependencies, workspace members (account, cli, node, display), and build configuration for the entire snarkOS system
• cli/src/lib.rs — CLI module entry point orchestrating command dispatch, argument parsing, and user-facing interfaces for node operation
• node/bft/Cargo.toml — Byzantine Fault Tolerant consensus engine—core consensus mechanism for the decentralized operating system
• account/src/lib.rs — Account abstraction layer providing cryptographic key management and identity primitives for all network participants
• build.rs — Build-time configuration and code generation orchestrator, likely handling proof system setup and compilation flags
• .ci/test_devnet.sh — Integration test orchestrator for full devnet startup, validating the complete system initialization and consensus participation
• cli/src/commands/mod.rs — Command dispatch module exposing account, developer, and node control operations to the CLI surface

Add a New CLI Command

1. Create a new command module in cli/src/commands/ (e.g., cli/src/commands/mycommand.rs) (cli/src/commands/mycommand.rs)
2. Add the command to the dispatcher match statement in cli/src/commands/mod.rs (cli/src/commands/mod.rs)
3. Wire argument parsing in cli/src/helpers/args.rs to handle the new subcommand flags (cli/src/helpers/args.rs)
4. Implement the command struct with clap derive macros following existing patterns in cli/src/commands/start.rs (cli/src/commands/start.rs)

Add a New Developer Subcommand

1. Create new file in cli/src/commands/developer/ (e.g., cli/src/commands/developer/myop.rs) (cli/src/commands/developer/myop.rs)
2. Export and wire the command in cli/src/commands/developer/mod.rs (cli/src/commands/developer/mod.rs)
3. Add dispatch logic in cli/src/commands/developer/mod.rs to route to the new operation (cli/src/commands/developer/mod.rs)
4. Reference account operations from account/src/lib.rs for signing or key management (account/src/lib.rs)

Add a New Node Feature or Behavior

1. Extend node/bft/Cargo.toml with required dependencies if needed (node/bft/Cargo.toml)
2. Add node initialization logic in cli/src/commands/start.rs to configure the new feature (cli/src/commands/start.rs)
3. Add corresponding metrics or logging in cli/src/helpers/logger.rs (cli/src/helpers/logger.rs)
4. Update .ci/test_devnet.sh to validate the new behavior in integration tests (.ci/test_devnet.sh)

Add a New UI Dashboard Tab or Page

1. Create new page module in display/src/pages/ (e.g., display/src/pages/myrpc.rs) (display/src/pages/myrpc.rs)
2. Register the page in display/src/pages/mod.rs (display/src/pages/mod.rs)
3. Add tab definition in display/src/tabs.rs to make it selectable (display/src/tabs.rs)
4. Wire into the main display loop in display/src/lib.rs (display/src/lib.rs)

• Rust + Cargo workspace — Memory safety, zero-cost abstractions, and compile-time verification critical for cryptographic correctness in ZK proofs
• Byzantine Fault Tolerant Consensus (BFT) — Enables decentralized consensus in untrusted network with up to 1/3 malicious validators, required for PoS networks
• Account abstraction with bech32m addressing — Human-readable, standard-compliant addresses for blockchain ecosystems while maintaining cryptographic identity
• CLI as primary user interface — Decentralized OS emphasizes node operator control; CLI enables headless operation, automation, and container deployment
• Terminal UI (display module) — Real-time monitoring without external dashboards; lean footprint for constrained validator environments

• Single monolithic CLI vs separate daemon + client tools

  • Why: Simpler deployment, unified versioning, easier onboarding for node operators
  • Consequence: CLI process must handle both long-running consensus and interactive commands; potential resource contention during large transactions

• Local devnet scripts (shell) vs formal orchestration (Kubernetes)

  • Why: Lower barrier to entry, reproducible test environment without heavyweight dependencies
  • Consequence: Devnet scaling limited; production requires external deployment tooling

• Account module separate from node vs integrated

  • Why: Enables offline signing, wallet management, and account queries independent of node state
  • Consequence: Account state must be queried from the node separately; potential consistency edge cases

• BFT consensus in core node vs pluggable consensus

  • Why: Optimized, proven consensus for Aleo's PoS model; simpler architecture
  • Consequence: Hard to experiment with alternative consensus; tied to Aleo's economic model

• Does not implement smart contract VM or program execution engine (delegated to ZK program layer)
• Not a full

Consensus safety is tightly coupled: validators must be bonded; upgrading validators while maintaining quorum is non-trivial (see test_reset_minority.sh, test_partial_upgrade.sh—these exist because state corruption is possible). REST API and P2P must stay in sync (bench_rest_api.sh separate from bench_p2p_sync.sh suggests they diverge). Local devnet requires multiple ports open and clean state (.devnet/clean.sh exists for a reason). Rust compile times are long due to cryptographic dependencies—no mention of incremental builds or sccache setup.

• ProvableHQ/leo — Leo is the high-level ZK programming language that compiles to constraints run on Aleo/snarkOS; developers write apps in Leo then deploy to snarkOS nodes
• ProvableHQ/snarkvm — snarkVM is the virtual machine and cryptographic backend for Aleo; snarkOS depends on it for ZK proof verification and execution
• ProvableHQ/aleo — The official Aleo SDK and CLI tooling for developers; snarkOS is the backend network that Aleo SDK clients talk to via REST API
• ethereum/go-ethereum — Peer blockchain OS for comparison: both are decentralized consensus systems, though Ethereum is EVM-based while snarkOS is ZK-proof-based
• filecoin/lotus — Another Rust consensus system with validator/client/prover-like roles (storage miner/full node/retrieval miner); architectural patterns may be relevant

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 integration tests for devnet lifecycle management scripts

The .devnet directory contains critical shell scripts (install.sh, start.sh, stop.sh, clean.sh, etc.) that orchestrate the entire devnet environment, but there are no automated tests validating their correctness. A new contributor could create a test suite that validates: (1) install.sh properly initializes the environment, (2) start.sh launches all required services without hanging, (3) stop.sh gracefully terminates services, (4) clean.sh properly removes artifacts. This prevents silent failures in devnet setup that waste contributor time.

• [ ] Create .devnet/tests/ directory with shell-based test harness
• [ ] Add tests for install.sh idempotency and dependency checks (reference: .devnet/install.sh, .devnet/config.sh)
• [ ] Add tests for start.sh/stop.sh lifecycle (validate PID management, port availability checks)
• [ ] Add tests for clean.sh artifact removal without data loss
• [ ] Integrate into .circleci/config.yml as a pre-commit validation workflow

Add dependency audit workflow for Node.js analytics module

The .devnet/.analytics/package.json specifies axios (^1.5.1) and yargs (^17.7.2) with loose semver constraints, but there is no GitHub Actions workflow to audit these JavaScript dependencies for vulnerabilities. The repo already has .cargo/audit.toml for Rust auditing but no equivalent for Node dependencies. A new contributor could create a GitHub Action that runs npm audit and cargo audit together, catching supply chain risks.

• [ ] Create .github/workflows/dependencies-audit.yml
• [ ] Add npm audit step targeting .devnet/.analytics/package.json (fail on high/critical)
• [ ] Add cargo audit step using existing .cargo/audit.toml configuration
• [ ] Configure to run on PR and scheduled weekly basis (reference: .github/workflows/benchmarks.yml for scheduling pattern)
• [ ] Add step to generate and commit audit report to prevent regression

Add missing CI/CD workflow validation for sync benchmarks

The .ci directory contains multiple benchmark scripts (bench_bft_sync.sh, bench_cdn_sync.sh, bench_p2p_sync.sh, bench_rest_api.sh) and sync test scripts (test_devnet.sh, start_sync_test.sh), but .github/workflows/ only has benchmarks.yml and release.yml. There is no dedicated workflow that validates these sync-critical paths run without regression. A contributor could create a comprehensive sync validation workflow that runs these benchmarks on every PR to catch performance regressions early.

• [ ] Create .github/workflows/sync-validation.yml that runs on PR to main/testnet
• [ ] Add job that executes .ci/test_devnet.sh with timeout protection
• [ ] Add job that executes .ci/bench_p2p_sync.sh and .ci/bench_bft_sync.sh in isolated environment
• [ ] Configure jobs to parse output from .ci/bench_rest_api.sh and upload metrics to artifact storage
• [ ] Add step to compare baseline metrics and comment on PR if regression detected (reference: .ci/rest_api_helper.py for metrics parsing)

• Add integration test documentation: The .ci/ directory has many bash scripts (test_devnet.sh, test_full_upgrade.sh, test_partial_upgrade.sh) but no inline comments explaining what each tests or how to write new integration tests. Create a CI.md or CONTRIBUTING.md section documenting the test matrix.
• Implement metrics/monitoring helpers: .devnet/monitor.sh and .devnet/fetch-logs.sh exist but are thin wrappers. Build a structured logging or metrics collection layer (e.g., expose Prometheus metrics from the REST API in .ci/bench_rest_api.sh) to make node health inspection easier.
• Expand Prover documentation: The README lists Prover nodes (§3.3) but .devnet/ has no prover-specific setup or example. Add .devnet/prover-only.sh and document puzzle-solving configuration (likely in a prover crate's README or clap arg parsing).

The snarkOS codebase demonstrates generally good security practices with CI/CD automation and audit tooling in place. However, there are notable concerns with outdated npm dependencies in the analytics module (axios and yargs) which should be updated to latest versions. The absence of a lock file and missing test implementation in the analytics package are additional concerns. The large shell script footprint in deployment scripts requires careful credential management review. Overall security posture is moderate; most risks are manageable with dependency updates and standard DevOps security practices.

• Medium · Outdated axios dependency with known vulnerabilities — .devnet/.analytics/package.json. The analytics package.json specifies axios ^1.5.1, which may contain known security vulnerabilities. The caret (^) allows for patch and minor version updates, but axios 1.5.1 from September 2023 is significantly outdated. Multiple CVEs have been reported in axios versions prior to 1.6.0+, including prototype pollution and request handling issues. Fix: Update axios to the latest stable version (currently 1.6.x or higher). Run 'npm audit' to identify specific vulnerabilities and apply patches. Consider using 'npm ci' with a lock file to ensure reproducible builds.
• Medium · Outdated yargs dependency — .devnet/.analytics/package.json. The yargs package version ^17.7.2 is pinned to an older minor version from mid-2023. While not as critical as axios, yargs may have security patches in newer versions. Command-line argument parsing libraries can be vectors for injection attacks if not kept current. Fix: Update yargs to the latest stable version. Run 'npm audit' to check for known vulnerabilities and update accordingly.
• Low · Missing npm package lock file — .devnet/.analytics/. The .devnet/.analytics directory contains a package.json but no package-lock.json or yarn.lock file is visible in the provided file structure. This can lead to non-deterministic dependency resolution and potential supply chain risks when different environments install dependencies. Fix: Ensure package-lock.json is committed to the repository. Use 'npm ci' instead of 'npm install' in CI/CD pipelines to use locked versions.
• Low · Incomplete test coverage in analytics package — .devnet/.analytics/package.json. The analytics package.json contains a test script that only echoes an error message and exits without running any actual tests. This indicates no automated security or functionality testing for this analytics component. Fix: Implement proper test suite using frameworks like Jest or Mocha. Add security-focused tests for the analytics module, especially for data handling and network requests.
• Low · Potential credential exposure in shell scripts — .ci/, .devnet/. Multiple shell scripts in .ci and .devnet directories handle configuration and deployment. While no obvious hardcoded secrets are visible in the file list, shell scripts in deployment contexts are prone to credential exposure through environment variables, command history, or logs. Fix: Audit all shell scripts for credential handling. Use secure secret management (e.g., HashiCorp Vault, cloud provider secrets). Never commit credentials. Implement script logging with credential masking.
• Low · Audit configuration may not catch all vulnerabilities — .cargo/audit.toml. The .cargo/audit.toml file exists but its content is not provided. Cargo audit configuration might not be optimally configured to catch all known vulnerabilities in Rust dependencies. Fix: Review and ensure audit.toml is configured to check all dependency trees, deny list vulnerable crates, and integrate with CI/CD for automated vulnerability scanning on every commit.

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.