core(stm/snark): integrate certificate circuit prototype as it is (future_snark)

[hjeljeli32]

Content

This PR integrates the Halo2 certificate circuit prototype into mithril-stm, behind the existing future_snark feature flag.

Concretely, it:

• Introduces the circuits/halo2 module structure and wires it into mithril-stm
• Moves and adapts the existing certificate circuit prototype into this module
• Adds off-circuit helpers (Merkle tree utilities, unique signature logic, helpers)
• Exposes a minimal setup binary for experimentation (setup.rs, feature-gated)

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
• Documentation
  • Update README file (if relevant)
  • Update documentation website (if relevant)
  • Add dev blog post (if relevant)
  • Add ADR blog post or Dev ADR entry (if relevant)
  • No new TODOs introduced

Comments

This PR fixes purely mechanical issues surfaced by CI and Clippy (unused imports, iterator patterns, borrows, dependency ordering). Logic is preserved relative to the prototype; differences are structural only

Issue(s)

Closes #2911

[github-actions]

Test Results

    5 files  ± 0    172 suites  ±0   29m 43s ⏱️ + 4m 16s
2 404 tests +12  2 404 ✅ +12  0 💤 ±0  0 ❌ ±0 
7 516 runs  +13  7 516 ✅ +13  0 💤 ±0  0 ❌ ±0 

Results for commit 70b2cc9. ± Comparison against base commit bef7ca4.

♻️ This comment has been updated with latest results.

[Copilot]

Pull request overview

This PR integrates a Halo2-based certificate circuit prototype into the mithril-stm crate behind the future_snark feature flag. The integration is purely structural and preserves the original prototype logic while adapting it to the mithril-stm module organization.

Changes:

• Adds a new circuits/halo2 module structure with circuit implementation, off-circuit utilities, and supporting infrastructure
• Introduces Merkle tree utilities, unique signature scheme, and cryptographic helpers for circuit witness generation
• Adds a feature-gated binary (setup) for generating KZG parameters for experimentation

Reviewed changes

Copilot reviewed 17 out of 19 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
mithril-stm/src/lib.rs	Adds feature-gated circuits module to public API
mithril-stm/src/circuits/mod.rs	Top-level circuits module documentation
mithril-stm/src/circuits/halo2/mod.rs	Halo2 prototype module structure
mithril-stm/src/circuits/halo2/types.rs	Type aliases and reexports for Jubjub curve types
mithril-stm/src/circuits/halo2/constants.rs	Domain separation tags and curve constants
mithril-stm/src/circuits/halo2/hash.rs	Hash function type aliases and CPU interfaces
mithril-stm/src/circuits/halo2/off_circuit/mod.rs	Off-circuit helpers module structure
mithril-stm/src/circuits/halo2/off_circuit/error.rs	Error types for signature and Merkle tree operations
mithril-stm/src/circuits/halo2/off_circuit/utils.rs	Utility functions for field arithmetic and conversions
mithril-stm/src/circuits/halo2/off_circuit/unique_signature.rs	Unique Schnorr signature implementation and verification
mithril-stm/src/circuits/halo2/off_circuit/merkle_tree.rs	Merkle tree implementation for certificate commitments
mithril-stm/src/circuits/halo2/circuit/mod.rs	In-circuit relations module structure
mithril-stm/src/circuits/halo2/circuit/gadgets.rs	Circuit gadgets for Merkle paths, signatures, and lottery verification
mithril-stm/src/circuits/halo2/circuit/certificate.rs	Main certificate circuit relation and proof tests
mithril-stm/src/circuits/halo2/tests/mod.rs	Test module placeholder
mithril-stm/src/circuits/halo2/bin/setup.rs	Binary tool for generating KZG parameters
mithril-stm/Cargo.toml	Adds feature-gated dependencies and binary configuration
mithril-stm/.gitignore	Ignores generated Halo2 assets directory
Cargo.lock	Locks new dependency versions

Comments suppressed due to low confidence (1)

mithril-stm/Cargo.toml:76

• Dependency conflict: num-bigint is declared as a non-optional dependency on line 58, but also as an optional dependency on line 76 for non-WASM/Windows/musl targets. This creates an ambiguous dependency specification. Since line 58 makes it always available, the optional declaration on line 76 is redundant and should likely be removed, or the unconditional dependency on line 58 should be reconsidered.

num-bigint = "0.4.6"
num-integer = { version = "0.1", optional = true }
num-traits = { version = "0.2.19", optional = true }
rand = { version = "0.9.2", optional = true }
rand_core = { version = "0.6", features = ["std"] }
rayon = { workspace = true }
serde = { workspace = true }
sha2 = "0.10.9"
subtle = { version = "2.5.0", optional = true }
thiserror = { workspace = true }

[target.'cfg(any(target_family = "wasm", target_env = "musl", windows))'.dependencies]
# WASM and Windows don't support rug backend, fallback to num-integer only
num-bigint = { version = "0.4.6" }
num-rational = { version = "0.4.2" }
num-traits = { version = "0.2.19" }

[target.'cfg(not(any(target_family = "wasm", target_env = "musl", windows)))'.dependencies]
num-bigint = { version = "0.4.6", optional = true }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jpraynaud]

During the upcoming refactoring we will probably want to get the circuit sub-modules directly under the halo2 module (and get rid of bin and off_circuit).

[hjeljeli32]

During the upcoming refactoring we will probably want to get the circuit sub-modules directly under the halo2 module (and get rid of bin and off_circuit).

@jpraynaud
Agree.
In the upcoming refactor we will completely get rid of off_circuit/.
For the setup tool (KZG/SRS param generation), do you have a preference for its long-term home (keep as a feature-gated bin/ in mithril-stm vs move to a dedicated tooling crate)?

[hjeljeli32]

Thanks @jpraynaud for the review.
All your suggestions make sense. I updated the code accordingly.

[jpraynaud]

LGTM 👍

[damrobi]

LGTM 👍

[curiecrypt]

LGTM 👍 with some comments:

• I agree with @jpraynaud about

During the upcoming refactoring we will probably want to get the circuit sub-modules directly under the halo2 module (and get rid of bin and off_circuit).

• Instead of having circuits/halo2/tools/setup.rs, would it be possible to move this functionality to a module like circuits/test_utils/setup.rs? A test_utils module could serve as a common base for setup-related functions and utilities that we may need in the future. I don’t think placing this setup functionality under a tools submodule inside the halo2 module accurately reflects its purpose or scope.
• With the upcoming refactoring, we might consider gathering types, hash, and constants under a sub-module, such as helpers, maybe.

[hjeljeli32]

LGTM 👍 with some comments:

• I agree with @jpraynaud about

During the upcoming refactoring we will probably want to get the circuit sub-modules directly under the halo2 module (and get rid of bin and off_circuit).

• Instead of having circuits/halo2/tools/setup.rs, would it be possible to move this functionality to a module like circuits/test_utils/setup.rs? A test_utils module could serve as a common base for setup-related functions and utilities that we may need in the future. I don’t think placing this setup functionality under a tools submodule inside the halo2 module accurately reflects its purpose or scope.
• With the upcoming refactoring, we might consider gathering types, hash, and constants under a sub-module, such as helpers, maybe.

Thanks @curiecrypt ! Agreed. I’ll move the KZG params setup helpersnto a shared circuits/test_utils module (gated to cfg(test) + future_snark).
Grouping types/hash/constants under a helpers submodule sounds good; I agree we should do that as part of the upcoming Halo2 refactor/off_circuit removal.