feat: introduce the circuit verification key registry by jpraynaud · Pull Request #3513 · IntersectMBO/mithril

jpraynaud · 2026-09-02T13:10:57Z

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:

Add CircuitVerificationKeyDigest (Poseidon hash of the transcript representation bytes) and a requires_certified_circuit_verification_keys predicate on AggregateSignatureType in mithril-stm, with golden tests pinning the digests
Add the registry types with revocation check semantics in mithril-common, signed over the exact registry JSON bytes with a domain-separation prefix so the schema stays evolvable after publication
Add the registry retriever trait with a file implementation and test doubles
Add the certifier trait with a caching decorator

Pre-submit checklist

Branch
- Tests are provided (if possible)
- Crates versions are updated (if relevant)
- CHANGELOG file is updated (if relevant)
- Commit sequence broadly makes sense
- Key commits have useful messages
PR
- All check jobs of the CI have succeeded
- Self-reviewed the diff
- Useful pull request description
- Reviewer requested

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 #3514 stacked on this one.

Issue(s)

Relates to #3148

Copilot

🟡 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) in mithril-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.

github-actions · 2026-09-02T13:33:22Z

Test Results

5 files ± 0 221 suites ±0 31m 2s ⏱️ - 27m 21s
3 581 tests +39 3 581 ✅ +39 0 💤 ±0 0 ❌ ±0
11 709 runs +48 11 709 ✅ +48 0 💤 ±0 0 ❌ ±0

Results for commit 4330db7. ± Comparison against base commit b76d033.

♻️ This comment has been updated with latest results.

damrobi

LGTM 👍

hjeljeli32

Looks good but I left a couple of suggestions.

damrobi

LGTM 👍

hjeljeli32

LGTM 👍

turmelclem

LGTM 👍

Alenar

LGTM

Add 'requires_certified_circuit_verification_keys' on AggregateSignatureType, true for the SNARK proof systems and false for concatenation.

…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.

… Poseidon The Poseidon hasher must absorb field elements, so the canonical key bytes are pre-hashed with SHA-256 as elsewhere in the crate.

…n keys The serialized key bytes omit the recursive circuit constraint system, so the digest covers the transcript representation that binds the gates.

Prepend a dedicated Poseidon domain separation tag (CVKD_DST) to the transcript representation, following the existing tag convention.

…oof tests Use the aggregate signature accessor instead, which also compiles cleanly without the future_snark feature.

The registry check collects all rejections with their reason in a single error variant instead of stopping at the first rejected digest.

* mithril-common from `0.7.20` to `0.7.21` * mithril-stm from `0.12.15` to `0.12.16`

jpraynaud self-assigned this Sep 2, 2026

jpraynaud requested a lite review from Copilot September 2, 2026 13:11

Copilot started reviewing on behalf of jpraynaud September 2, 2026 13:12 View session

github-advanced-security Bot found potential problems Sep 2, 2026

View reviewed changes

Copilot AI reviewed Sep 2, 2026

View reviewed changes

Comment thread mithril-common/src/crypto_helper/circuit_key_registry/certifier.rs

Comment thread mithril-common/src/crypto_helper/circuit_key_registry/retriever.rs Outdated

jpraynaud force-pushed the jpraynaud/3148-introduce-circuit-key-registry branch 2 times, most recently from d971416 to 36ef087 Compare September 2, 2026 13:55

jpraynaud deployed to testing-preview September 2, 2026 14:19 — with GitHub Actions Active

jpraynaud deployed to testing-2-preview September 2, 2026 14:19 — with GitHub Actions Active

jpraynaud force-pushed the jpraynaud/3148-introduce-circuit-key-registry branch from 36ef087 to d71b4d5 Compare September 2, 2026 14:33

jpraynaud mentioned this pull request Sep 2, 2026

feat: enforce the circuit verification key registry #3514

Draft

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

jpraynaud deployed to testing-preview September 2, 2026 14:56 — with GitHub Actions Active

jpraynaud deployed to testing-2-preview September 2, 2026 14:56 — with GitHub Actions Active

damrobi reviewed Sep 4, 2026

View reviewed changes

Comment thread mithril-common/src/crypto_helper/circuit_key_registry/registry.rs

damrobi approved these changes Sep 4, 2026

View reviewed changes

hjeljeli32 reviewed Sep 7, 2026

View reviewed changes

Comment thread mithril-stm/src/circuits/verification_key_digest.rs Outdated

Comment thread mithril-stm/src/circuits/verification_key_digest.rs Outdated

jpraynaud force-pushed the jpraynaud/3148-introduce-circuit-key-registry branch from d71b4d5 to 6aa6ed4 Compare September 8, 2026 13:45

jpraynaud deployed to testing-2-preview September 8, 2026 14:31 — with GitHub Actions Active

jpraynaud deployed to testing-preview September 8, 2026 14:31 — with GitHub Actions Active

jpraynaud force-pushed the jpraynaud/3148-introduce-circuit-key-registry branch from 6aa6ed4 to b3586ac Compare September 8, 2026 14:42

jpraynaud deployed to testing-preview September 8, 2026 15:06 — with GitHub Actions Active

jpraynaud deployed to testing-2-preview September 8, 2026 15:06 — with GitHub Actions Active

jpraynaud force-pushed the jpraynaud/3148-introduce-circuit-key-registry branch from b3586ac to 475496e Compare September 8, 2026 16:12

jpraynaud requested review from damrobi and hjeljeli32 September 8, 2026 16:14

jpraynaud deployed to testing-preview September 8, 2026 16:36 — with GitHub Actions Active

jpraynaud deployed to testing-2-preview September 8, 2026 16:36 — with GitHub Actions Active

damrobi approved these changes Sep 9, 2026

View reviewed changes

hjeljeli32 approved these changes Sep 9, 2026

View reviewed changes

turmelclem approved these changes Sep 9, 2026

View reviewed changes

Alenar approved these changes Sep 9, 2026

View reviewed changes

Comment thread mithril-common/Cargo.toml Outdated

jpraynaud added 12 commits September 9, 2026 17:33

feat(stm): add predicate for certified circuit verification keys

6763def

Add 'requires_certified_circuit_verification_keys' on AggregateSignatureType, true for the SNARK proof systems and false for concatenation.

feat(stm): expose circuit verification key digests from ancillary ver…

380e73c

…ifier data Add CircuitVerificationKeyDigest (Poseidon hash of the canonical key bytes, hex-serialized) and a digests accessor covering both SNARK variants.

feat(common): add circuit verification key registry types

95efa99

Add the genesis-signed registry (whitelist entries with epoch ranges and revocation-wins semantics) under crypto_helper/circuit_key_registry.

feat(common): add circuit verification key registry retriever

feca547

Add the retriever trait returning the unverified signed registry, a file based implementation and a fake test double.

feat(common): add circuit verification key certifier

57f5cd9

Lazily retrieve the signed registry, verify its genesis signature, network and minimum version, cache it, then check digests fail-closed.

fix(stm): hash the circuit verification key bytes with SHA-256 before…

272af8d

… Poseidon The Poseidon hasher must absorb field elements, so the canonical key bytes are pre-hashed with SHA-256 as elsewhere in the crate.

fix(stm): digest the transcript representation of circuit verificatio…

78bfa08

…n keys The serialized key bytes omit the recursive circuit constraint system, so the digest covers the transcript representation that binds the gates.

fix(stm): domain separate the circuit verification key digest

ab585f3

Prepend a dedicated Poseidon domain separation tag (CVKD_DST) to the transcript representation, following the existing tag convention.

fix(stm): remove infallible destructuring matches in concatenation pr…

29906fc

…oof tests Use the aggregate signature accessor instead, which also compiles cleanly without the future_snark feature.

fix(common): report every rejected circuit verification key digest

ff16cd1

The registry check collects all rejections with their reason in a single error variant instead of stopping at the first rejected digest.

chore: update CHANGELOG

f739595

chore: upgrade crate versions

4330db7

* mithril-common from `0.7.20` to `0.7.21` * mithril-stm from `0.12.15` to `0.12.16`

jpraynaud force-pushed the jpraynaud/3148-introduce-circuit-key-registry branch from 475496e to 4330db7 Compare September 9, 2026 15:40

jpraynaud deployed to testing-preview September 9, 2026 16:07 — with GitHub Actions Active

jpraynaud deployed to testing-2-preview September 9, 2026 16:07 — with GitHub Actions Active

jpraynaud merged commit cccb650 into main Sep 9, 2026
51 checks passed

jpraynaud deleted the jpraynaud/3148-introduce-circuit-key-registry branch September 9, 2026 16:10

hjeljeli32 mentioned this pull request Sep 9, 2026

Add property-based tests for the IVC pure helpers #3469

Open

13 tasks

Uh oh!

Conversation

jpraynaud commented Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Content

Pre-submit checklist

Comments

Issue(s)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Results

Uh oh!

Uh oh!

damrobi left a comment

Choose a reason for hiding this comment

Uh oh!

hjeljeli32 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

damrobi left a comment

Choose a reason for hiding this comment

Uh oh!

hjeljeli32 left a comment

Choose a reason for hiding this comment

Uh oh!

turmelclem left a comment

Choose a reason for hiding this comment

Uh oh!

Alenar left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

jpraynaud commented Sep 2, 2026 •

edited

Loading

github-actions Bot commented Sep 2, 2026 •

edited

Loading