Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Contributing to crucible-prover

Thanks for contributing to the Crucible proof engine.

Code of conduct

All contributors must follow the Code of Conduct.

Repository map

  • interfaces/ — the stable contracts (ProofProvider, Verifier, request/response types). This crate must stay dependency-light; every other crate builds on it.
  • crates/ — the Rust engine: witness management, proof types, artifact integrity, prover orchestration, backends (Noir, UltraHonk), verification.
  • adapters/ — bridges to external systems (simulator, Soroban, testnet).
  • circuits/ — the Noir workspace (shared library, production circuits, measurement gadgets). Noir is a separate toolchain from Cargo.
  • schemas/, test-vectors/ — cross-language fixtures.
  • cli/ — orchestration only. No proving logic lives here.
  • docs/ — architecture and design documents.

Development setup

Install the pinned toolchains:

# Rust (pinned in rust-toolchain.toml)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Noir (see scripts/setup-noir.sh)
curl -L https://raw.githubusercontent.com/noir-lang/noirup/main/install | bash
export PATH="$HOME/.noirup/bin:$PATH"
noirup

Scoping your change

crucible-scenarios compiles this repository at a revision pinned in its own manifest. That means a change here cannot break it — it builds the pinned revision, not your branch — but a change to a published contract under interfaces/ blocks its next pin bump until it adapts. Scope that as two issues: the change here, and a separate follow-up that bumps the pin and adapts the consumer. Never one PR spanning repositories; it cannot be reviewed or reverted as a unit.

The pinned set is recorded in crucible-scenarios/docs/cross-repo-pinning.md.

Do not require the Noir toolchain unless the issue is about it

nargo and bb are heavy, version-gated dependencies, and the real backend refuses to run without them (BackendUnavailable). Everything else builds and tests with only Rust installed: cargo test --workspace passes without either toolchain present, which is the surface most work should stay on. If an issue does require them, say so explicitly in the issue so a contributor can judge the setup cost before applying.

Before opening a PR

  1. cargo fmt --all -- --check
  2. cargo clippy --workspace --all-targets -- -D warnings
  3. cargo test --workspace
  4. If you touched circuits: scripts/check-circuits.sh
  5. If you touched serialization or proof formats: extend the matching JSON schema in schemas/ and regenerate affected test vectors.

Tests that touch private witness material must assert the material never surfaces in Debug/Display output, errors, or logs (see the witness leakage suites under tests/).

Commit conventions

  • One logical improvement per commit; do not bundle unrelated changes.
  • Detailed commit messages explaining the what and the why.
  • Reference the security implications of your change in the message when the change touches witness handling, verification, or artifacts.

Where to start

See docs/architecture.md and the issue templates under .github/ISSUE_TEMPLATE/. Good first issues are tagged good first issue; circuit and test-vector work does not require deep Rust knowledge, while prover-core and witness work requires care with the privacy boundary.