agentleFS
ProvableHQProvableHQ/snarkVM/AGENTS.md

snarkVM

AGENTS.md1.2k starsChanged 21 days agoApache-2.0View on GitHub

snarkVM is a virtual machine for zero-knowledge proof execution on the Aleo blockchain. Crate dependencies: - snarkvm-utilities - no deps, macros and parallel primitives - snarkvm-fields - depends on utilities, finite field arithmetic - snarkvm-curves - depends on fields, elliptic curve implementations - snarkvm-algorithms - depends on curves/fields, cryptographic primitives (Poseidon, Marlin, Polycommit) - snarkvm-console - depends on algorithms, plaintext VM types (Address, Field, Group, Scalar, programs) - snarkvm-circuit - depends on console, circuit/constraint equivalents of console types - snarkvm-ledger…

Trending

More talk lately.about the whole repository

Dec 2025: 2 mentionsJan 2026: 2 mentionsFeb 2026: 1 mentionMar 2026: 1 mentionApr 2026: 1 mentionMay 2026: 3 mentionsJun 2026: 4 mentionsJul 2026: 3 mentionsAug 2026: 7 mentionsSep 2026: 7 mentionsOct 2026: 8 mentionsNov 2026: 0 mentions
Dec 2025Jun 2026Nov 2026
Mentions a month of the ProvableHQ/snarkVM repository that our weekly crawl found. There is no adoption data for this file yet.

Who's talking about ProvableHQ/snarkVM

The biggest 5 of 50 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 50

Talked about on GitHub (50 times).

On GitHub · 50

45 more on GitHub
  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository5 other files it gives its agents.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

18 rules. About 0 are common, 13 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈13

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Search for existing implementations.

    line 4
  2. Distinctive:

    Read the target module and match its patterns exactly.

    line 5
  3. Distinctive:

    When modifying one, check the other.

    line 27
  4. Distinctive:

    Test circuit equivalence by comparing constraint counts.

    line 28
  5. Distinctive:

    All changes must be backwards compatible — no consensus forks.

    line 31
  6. Distinctive:

    Test-driven development: write failing tests first.

    line 39
  7. Very specific:

    Prefer zip_eq over zip when lengths must match.

    line 41
  8. Very specific:

    Prefer into_iter() over iter().cloned().

    line 43
  9. Very specific:

    Use iterators; avoid intermediate .collect() when a single pass follows.

    line 44
  10. Very specific:

    Use --features test,dev-print for integration tests.

    line 70
  11. Distinctive:

    Never commit unless explicitly asked.

    line 95
  12. Very specific:

    Run cargo +nightly-2026-04-02 fmt --all before staging.

    line 97
  13. Distinctive:

    Write the PR README in Simplified Technical English.

    line 101
  14. Distinctive:

    Keep the pull request description succinct and DRY.

    line 102
  15. Distinctive:

    Start from program input.

    line 144
  16. Distinctive:

    Follow through console types -> circuit synthesis -> proof generation.

    line 145
  17. Distinctive:

    Verify output matches expected proof/execution result.

    line 147
  18. Distinctive:

    All randomness is derived from cryptographically secure sources.

    line 160

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

snarkVM

Before Writing Code

  • Search for existing implementations.
  • Read the target module and match its patterns exactly.
  • Scope out necessary tests ahead of time.
  • If uncertain, ask.
  • Think very hard in your planning process.
  • New files, crates, dependencies, abstractions, traits, or error types require approval.

Architecture

snarkVM is a virtual machine for zero-knowledge proof execution on the Aleo blockchain.

Crate dependencies:

  • snarkvm-utilities - no deps, macros and parallel primitives
  • snarkvm-fields - depends on utilities, finite field arithmetic
  • snarkvm-curves - depends on fields, elliptic curve implementations
  • snarkvm-algorithms - depends on curves/fields, cryptographic primitives (Poseidon, Marlin, Polycommit)
  • snarkvm-console - depends on algorithms, plaintext VM types (Address, Field, Group, Scalar, programs)
  • snarkvm-circuit - depends on console, circuit/constraint equivalents of console types
  • snarkvm-ledger - depends on synthesizer, blockchain state (blocks, transactions, storage)
  • snarkvm-synthesizer - depends on console/circuit/algorithms, program execution and proof generation

console / circuit sync requirement:

  • These crate families must stay in sync. Same structure, same API.
  • When modifying one, check the other.
  • Test circuit equivalence by comparing constraint counts.

Rules

  • All changes must be backwards compatible — no consensus forks.
  • New files, crates, dependencies, abstractions, or traits require approval.
  • unwraps must have a comment justifying why they can't panic.

Forking Risk

There are deployed versions of this software in the wild. Changes that alter consensus behavior (same inputs producing different outputs) will fork the network. All changes must either be backwards compatible or gated behind a consensus version so they can be rolled in at the appropriate time. Not all code has been released publicly, so if you are unsure whether a change is safe on a PR, ask before proceeding.

Code and Patterns

  • Test-driven development: write failing tests first.
  • unwraps must be commented with justification.
  • Prefer zip_eq over zip when lengths must match.
  • Pre-allocate with with_capacity when final size is known.
  • Prefer into_iter() over iter().cloned(). Prefer references over .clone().
  • Use iterators; avoid intermediate .collect() when a single pass follows.
  • Trait impls (ToBits, FromBits, ToField, FromField) should follow existing patterns in the same file.

See @CONTRIBUTING.md for detailed memory and performance guidelines.

Code comments

Comments must describe the state of the code today -- not a previous state or an alternative state.

Exception: Comments may describe an alternative possible state of the code, if they are documenting a hazard that a future developer may otherwise walk into.

Comments must not describe the rationale for a change.

Rationale may appear in: the commit message and the pull request. You may self-comment on your own github pull request at select positions in the code to aide reviewers.

Comments must help someone who has never heard of this change you are making.

Comments must not state the obvious. Comments that explain what attributes do or how language constructs work are unhelpful.

Testing

Synthesizer tests are slow — run only the specific test function. Use --features test,dev-print for integration tests.

cargo test -p <crate>                                           # Run crate tests
cargo test -p <crate> -- test_name                              # Run specific test
cargo test -p snarkvm-synthesizer --features test,dev-print     # Integration tests

Validation

Run in order:

cargo check -p <crate>
cargo clippy -p <crate> -- -D warnings
cargo +nightly-2026-04-02 fmt --check
cargo test -p <crate>

Clippy warnings are errors. Formatting requires the nightly .github/workflows/ci.yml pins as FMT_TOOLCHAIN (cargo +nightly-2026-04-02 fmt --all to fix) -- .rustfmt.toml uses nightly-only options, and plain cargo fmt drops them silently rather than refusing.

Pre-commit hook runs workspace-wide: cargo clippy --workspace --all-targets --all-features -- -D warnings && cargo +nightly-2026-04-02 fmt --all -- --check

Git

  • Never commit unless explicitly asked.
  • Stage with git add only if requested.
  • Run cargo +nightly-2026-04-02 fmt --all before staging.

Pull requests

  • Follow .github/PULL_REQUEST_TEMPLATE.md.
  • Write the PR README in Simplified Technical English. Use short sentences, the active voice, and one idea per sentence.
  • Keep the pull request description succinct and DRY.
  • Explain each commit in one line.

Style

  • One blank line between functions.
  • No trailing whitespace.
  • Imports: std first, external crates second, crate-local third.
  • Match existing file patterns exactly — if the file uses Self::, you use Self::.
  • Comments must be concise, complete, punctuated sentences.
  • #![forbid(unsafe_code)] in all crates unless approved.
  • License header required (enforced by tests/sources.rs).

Review Checklist

Correctness

  • Logic traced step-by-step.
  • Boundary conditions handled: zero, empty, max, off-by-one.
  • Error handling correct; no panics in production paths.
  • Serialization/deserialization roundtrips verified.

Crypto-Specific

  • Field operations use checked arithmetic where needed.
  • Randomness sources are cryptographically secure.
  • No consensus-breaking changes (same inputs must produce same outputs).
  • Circuit constraints match console logic exactly.
  • Proof verification logic is sound.

Memory & Performance

  • No unnecessary allocations in hot paths.
  • Pre-allocation with with_capacity where size known.
  • No unnecessary .clone() — prefer references.
  • Iterators used efficiently; no intermediate collections.
  • Parallel execution with rayon where appropriate.

Security

  • Input validation at trust boundaries.
  • No information leakage in error messages.
  • Fail-closed (reject on uncertainty).

Deep Analysis Techniques

Trace Execution

  1. Start from program input.
  2. Follow through console types -> circuit synthesis -> proof generation.
  3. Track field element transformations.
  4. Verify output matches expected proof/execution result.

Enumerate Failure Modes

For each operation, ask:

  • What if input is zero/empty/max?
  • What if field elements overflow?
  • What if serialization format changes?
  • What if circuit constraints don't match console logic?

Check Invariants

  • Console and circuit types produce identical outputs for identical inputs.
  • Serialization is deterministic and backwards compatible.
  • Proof verification succeeds for valid proofs and fails for invalid ones.
  • All randomness is derived from cryptographically secure sources.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.