feat: add the circuit verification key registry crate and tools

[jpraynaud]

Content

This PR includes the circuit verification key registry crate and the tools to manage a registry, prepared for its enforcement in #3514:

• Move the circuit verification key registry introduced in feat: introduce the circuit verification key registry #3513 to its own mithril-circuit-key-registry internal crate, behind its future_snark feature (registry format, certifiers and retrievers), mithril-common keeping only the CircuitVerificationKeyCertifier trait used by the certificate verifier
• Remove the compiled minimum registry version: the genesis signature and the cached certifier cover the registry, a compiled floor would need a release per publication
• Keep a single entry per circuit verification key digest, either allowed over an epoch range or revoked, a revoked key being rejected for every epoch
• Add an HTTP retriever of the signed registry with a bounded downloader (timeout, retries and size cap)
• Keep the last verified registry in memory when a refresh fails or would lower the registry version, so an outage of the registry source does not stop a running node
• Add the circuit-key-registry command to the aggregator: export the circuit key digests for the network protocol parameters, whitelist a key (creating the registry of a Mithril network when missing), revoke an allowed key with its revocation epoch and comment, sign a hand-authored registry, and the test-only bootstrap, the registry being updated in place and genesis-signed
• Document the command in the aggregator CLI documentation.

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

Issue(s)

Relates to #3148

[Copilot]

🟡 Changes recommended

Critical and moderate unresolved findings remain in the downloader, registry validation, and aggregator tooling.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds a feature-gated circuit verification key registry crate with retrieval, caching, signing, and aggregator management tools.

Changes:

• Extracts registry types, certifiers, retrievers, and bounded HTTP downloading.
• Adds aggregator export, whitelist, revoke, sign, and bootstrap commands.
• Updates documentation, workspace metadata, tests, and CI/release workflows.

File summaries

File	Reviewed changes
README.md	Documents the new crate.
mithril-common/src/test/double/mod.rs	Removes the moved retriever double.
mithril-common/src/crypto_helper/mod.rs	Re-exports circuit digest types.
mithril-common/src/crypto_helper/circuit_key_registry/mod.rs	Removes the legacy registry module.
mithril-common/src/certificate_chain/mod.rs	Exposes the certifier trait.
mithril-common/src/certificate_chain/circuit_verification_key_certifier.rs	Defines the certifier interface.
mithril-aggregator/src/tools/mod.rs	Registers registry tools.
mithril-aggregator/src/tools/circuit_key_registry.rs	Implements registry operations. L203: Moderate, 3 votes — guard maximum-version increment overflow. L328: Moderate, 2 votes — apply inverted-range validation only to allowed entries.
mithril-aggregator/src/commands/mod.rs	Registers the registry command.
mithril-aggregator/src/commands/circuit_key_registry_command.rs	Implements CLI subcommands.
mithril-aggregator/Cargo.toml	Adds feature-gated crate wiring.
Makefile	Includes the new component.
internal/mithril-circuit-key-registry/src/test/mod.rs	Adds test utilities.
internal/mithril-circuit-key-registry/src/test/double/mod.rs	Exposes retriever test doubles.
internal/mithril-circuit-key-registry/src/test/double/circuit_key_registry_retriever.rs	L7: Nit, 1 vote — add the standard Dummy implementation.
internal/mithril-circuit-key-registry/src/retriever.rs	Adds file, HTTP, and unconfigured retrievers.
internal/mithril-circuit-key-registry/src/registry.rs	Defines registry format and verification. L161: Critical, 3 votes — validate duplicate digests or ensure revocation wins.
internal/mithril-circuit-key-registry/src/lib.rs	Defines crate modules and exports.
internal/mithril-circuit-key-registry/src/http_downloader.rs	Adds bounded HTTP downloading and retries. L83: Critical, 3 votes — stream bodies incrementally to enforce the size cap. L33: Moderate, 2 votes — propagate client construction errors instead of falling back to a client without the timeout.
internal/mithril-circuit-key-registry/src/certifier.rs	Adds verification and caching.
internal/mithril-circuit-key-registry/README.md	Documents the crate.
internal/mithril-circuit-key-registry/Makefile	Adds crate build and test targets.
internal/mithril-circuit-key-registry/Cargo.toml	Defines crate metadata and features.
docs/website/root/manual/develop/nodes/mithril-aggregator.md	Documents the CLI commands.
Cargo.toml	Adds the crate to the workspace.
Cargo.lock	Locks new dependencies.
.github/workflows/test-rust.yml	Tests the new crate.
.github/workflows/release.yml	Publishes the crate.
.github/workflows/pre-release.yml	Includes pre-release publishing.
.github/workflows/nightly-dispatcher.yml	Includes nightly publishing.
.github/workflows/manual-publish-crates.yml	Adds manual publication support.
.github/workflows/ci.yml	Updates publication and documentation coverage.

Review details

Suppressed comments (2)

internal/mithril-circuit-key-registry/src/registry.rs:165

• This first-match lookup silently ignores later entries with the same digest. The single-entry invariant is checked only by the aggregator tools, while SignedCircuitVerificationKeyRegistry::verify accepts a signed document with duplicates; an allowed first entry followed by a revoked entry would therefore certify the revoked key. Validate uniqueness when parsing/verifying, or retain revocation-wins behavior for malformed duplicates.
  internal/mithril-circuit-key-registry/src/test/double/circuit_key_registry_retriever.rs:10
• The moved public fake remains a test double without implementing mithril_common::test::double::Dummy, contrary to the repository's dummy test-double guideline. Add a Dummy implementation next to the type so shared tests can construct it through the standard test-double API.

• Files reviewed: 31/32 changed files
• Comments generated: 4
• 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]

Test Results

     5 files  ± 0     222 suites  +1   43m 1s ⏱️ - 1h 23m 35s
 3 721 tests  -  4   3 721 ✅  -  4  0 💤 ±0  0 ❌ ±0 
11 931 runs   - 13  11 931 ✅  - 13  0 💤 ±0  0 ❌ ±0 

Results for commit c6f2e05. ± Comparison against base commit 1352436.

This pull request removes 85 and adds 81 tests. Note that renamed tests count towards both.

mithril-common ‑ crypto_helper::circuit_key_registry::certifier::tests::cached_certifier::a_cache_refreshed_in_the_future_is_stale
mithril-common ‑ crypto_helper::circuit_key_registry::certifier::tests::cached_certifier::check_fails_closed_when_the_refresh_fails
mithril-common ‑ crypto_helper::circuit_key_registry::certifier::tests::cached_certifier::check_refreshes_the_registry_after_the_cache_time_to_live_expires
mithril-common ‑ crypto_helper::circuit_key_registry::certifier::tests::cached_certifier::check_rejects_a_refreshed_registry_with_a_lower_version
mithril-common ‑ crypto_helper::circuit_key_registry::certifier::tests::cached_certifier::check_retrieves_and_verifies_the_registry_only_once_within_the_time_to_live
mithril-common ‑ crypto_helper::circuit_key_registry::certifier::tests::mithril_certifier::check_fails_closed_when_retrieval_fails
mithril-common ‑ crypto_helper::circuit_key_registry::certifier::tests::mithril_certifier::check_propagates_registry_check_errors
mithril-common ‑ crypto_helper::circuit_key_registry::certifier::tests::mithril_certifier::check_rejects_a_registry_signed_by_another_genesis_key
mithril-common ‑ crypto_helper::circuit_key_registry::certifier::tests::mithril_certifier::check_rejects_a_registry_version_below_the_minimum
mithril-common ‑ crypto_helper::circuit_key_registry::certifier::tests::mithril_certifier::check_retrieves_and_verifies_the_registry_at_every_use
…

mithril-aggregator ‑ tools::circuit_key_registry::tests::add_entry::appends_the_entry_and_increments_the_version_of_an_existing_registry
mithril-aggregator ‑ tools::circuit_key_registry::tests::add_entry::creates_a_signed_registry_at_the_initial_version_when_missing
mithril-aggregator ‑ tools::circuit_key_registry::tests::add_entry::fails_on_a_digest_already_listed
mithril-aggregator ‑ tools::circuit_key_registry::tests::add_entry::fails_on_a_registry_version_that_cannot_be_incremented
mithril-aggregator ‑ tools::circuit_key_registry::tests::add_entry::fails_on_an_entry_with_an_inverted_epoch_range
mithril-aggregator ‑ tools::circuit_key_registry::tests::add_entry::fails_on_an_existing_registry_signed_by_another_genesis_key
mithril-aggregator ‑ tools::circuit_key_registry::tests::add_entry::preserves_the_fields_of_a_future_registry_schema
mithril-aggregator ‑ tools::circuit_key_registry::tests::bootstrap::bootstraps_a_verifiable_registry_whitelisting_the_production_circuit_keys_without_protocol_parameters
mithril-aggregator ‑ tools::circuit_key_registry::tests::bootstrap::digests_of_each_protocol_parameter_set_are_computed_from_it_and_named_after_its_k_and_m
mithril-aggregator ‑ tools::circuit_key_registry::tests::bootstrap::digests_without_protocol_parameters_are_the_production_ones
…

♻️ This comment has been updated with latest results.

[damrobi]

It looks good to me but there are a few comments worth discussing I believe