feat: introduce the circuit verification key registry - #3513
Open
jpraynaud wants to merge 5 commits into
Open
Conversation
Add 'requires_certified_circuit_verification_keys' on AggregateSignatureType, true for the SNARK proof systems and false for concatenation.
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
There was a problem hiding this comment.
🟡 Changes recommended
There are operational/runtime concerns in the new registry plumbing (cache freshness under clock rollback and blocking file I/O in an async retriever) that should be addressed before relying on this for revocation safety.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR introduces the foundation for a genesis-signed circuit verification key (VK) registry and certification flow, enabling runtime whitelisting and retroactive revocation of SNARK circuit VKs over epoch ranges (to be enforced in follow-up PRs).
Changes:
- Add
CircuitVerificationKeyDigest(Poseidon hash of canonical VK bytes) inmithril-stm, plus accessors to expose digests from ancillary verifier data. - Introduce registry types in
mithril-common(whitelist + revocation-wins semantics) and a signed “raw JSON bytes” container with domain-separated genesis signature verification. - Add registry retrieval + certification traits and implementations, including a cached certifier with TTL and version rollback protection.
File summaries
| File | Description |
|---|---|
| mithril-stm/src/protocol/aggregate_signature/signature.rs | Adds requires_certified_circuit_verification_keys() plus a golden test pinning semantics per aggregate signature type. |
| mithril-stm/src/protocol/aggregate_signature/ancillary_data.rs | Exposes stable-order circuit VK digests from ancillary verifier data and tests the ordering/consistency. |
| mithril-stm/src/lib.rs | Re-exports circuit VK digest types/constants behind future_snark. |
| mithril-stm/src/circuits/verification_key_digest.rs | New digest type + serde/hex round-trips and golden tests pinning digests. |
| mithril-stm/src/circuits/mod.rs | Wires the new digest module and re-exports it from circuits. |
| mithril-common/src/test/double/mod.rs | Adds a future_snark-gated test double module export for registry retrieval. |
| mithril-common/src/test/double/circuit_key_registry_retriever.rs | Implements a fake registry retriever for tests. |
| mithril-common/src/crypto_helper/mod.rs | Adds future_snark-gated circuit key registry module wiring and re-exports. |
| mithril-common/src/crypto_helper/circuit_key_registry/retriever.rs | Adds retriever trait + file-based implementation + tests. |
| mithril-common/src/crypto_helper/circuit_key_registry/registry.rs | Implements registry data model, check semantics (revocation wins), and signed raw-JSON container with signature verification. |
| mithril-common/src/crypto_helper/circuit_key_registry/mod.rs | New module root re-exporting registry/retriever/certifier pieces. |
| mithril-common/src/crypto_helper/circuit_key_registry/certifier.rs | Adds certifier trait, Mithril certifier implementation, and cached certifier (TTL + rollback protection) with tests. |
| mithril-common/Cargo.toml | Enables serde_json raw_value feature needed to preserve exact signed JSON bytes. |
Review details
- Files reviewed: 13/13 changed files
- Comments generated: 2
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
jpraynaud
force-pushed
the
jpraynaud/3148-introduce-circuit-key-registry
branch
2 times, most recently
from
September 2, 2026 13:55
d971416 to
36ef087
Compare
…ifier data Add CircuitVerificationKeyDigest (Poseidon hash of the canonical key bytes, hex-serialized) and a digests accessor covering both SNARK variants.
Add the genesis-signed registry (whitelist entries with epoch ranges and revocation-wins semantics) under crypto_helper/circuit_key_registry.
Add the retriever trait returning the unverified signed registry, a file based implementation and a fake test double.
Lazily retrieve the signed registry, verify its genesis signature, network and minimum version, cache it, then check digests fail-closed.
jpraynaud
force-pushed
the
jpraynaud/3148-introduce-circuit-key-registry
branch
from
September 2, 2026 14:33
36ef087 to
d71b4d5
Compare
9 tasks
jpraynaud
marked this pull request as ready for review
September 2, 2026 14:36
jpraynaud
requested review from
Alenar,
curiecrypt,
damrobi,
hjeljeli32 and
turmelclem
as code owners
September 2, 2026 14:36
damrobi
reviewed
Sep 4, 2026
| /// revoked entry covers the epoch, and with | ||
| /// [NotWhitelisted](CircuitVerificationKeyRegistryError::NotWhitelisted) when no allowed | ||
| /// entry covers it. | ||
| pub fn check( |
Collaborator
There was a problem hiding this comment.
We only return the first digest that is not allowed. Could it be interesting to get the list of all rejected digests that fails?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Content
This PR includes the machinery of the genesis signed circuit verification key registry, a whitelist with epoch ranges and retroactive revocations for the circuit verification keys trusted by SNARK certificates:
CircuitVerificationKeyDigest(Poseidon hash of the canonical verification key bytes) and arequires_certified_circuit_verification_keyspredicate onAggregateSignatureTypeinmithril-stm, with golden tests pinning the digestsmithril-common, signed over the exact registry JSON bytes with a domain-separation prefix so the schema stays evolvable after publicationPre-submit checklist
Comments
The enforcement in the certificate verifier, the client and the aggregator, along with the genesis tooling and the runbook, comes in a follow-up PR stacked on this one.
Issue(s)
Relates to #3148