refactor(stm): update PoP, protocol parameters and decoding functions

[damrobi]

Content

This PR includes an update to the handling of the proof of possession of BLS keys, a modification of the checks done on the protocol parameters and a modification to the decoding function of the merkle tree path and concatenation proof.

Changes

• Add checked arithmetic to legacy byte decoders (Merkle tree, batch commitment, ConcatenationProof, SingleSignature)
• Validate phi_f is within (0, 1] before use in lottery/eligibility computations
• Restrict KeyRegistration::register_by_entry to pub(crate) so external registration must go through register(), which always verifies proof of possession
• Make ClosedKeyRegistration fields private with a pub(crate) constructor
• Narrow RegistrationEntry/ClosedRegistrationEntry (types, constructors, methods) to pub(crate) and dropped RegistrationEntry's unused Serialize/Deserialize
• Fix resulting lint warnings: #[allow(private_interfaces)] where a public error intentionally carries a now-private type, #[allow(dead_code)] on Merkle tree byte (de)serialization helpers that are test-only for now

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

Issue(s)

[github-actions]

Test Results

     5 files  ± 0     209 suites  ±0   1h 27m 2s ⏱️ - 28m 24s
 3 342 tests  - 31   3 342 ✅  - 31  0 💤 ±0  0 ❌ ±0 
11 080 runs   - 28  11 080 ✅  - 28  0 💤 ±0  0 ❌ ±0 

Results for commit 36b7b29. ± Comparison against base commit 8bbdf2d.

♻️ This comment has been updated with latest results.

[hjeljeli32]

LGTM so far.

[hjeljeli32]

Added 2 additional comments.

[hjeljeli32]

Are these methods really test-only? MerkleTree is public, so gating to_bytes and from_bytes removes an existing API for downstream users. It also means the hardened legacy decoder is not included in production.

[damrobi]

Those methods are never called within the code apart from test functions that only tests those functions so I used the flag as a temporary fix. I think it's worth considering whether or not we need/want those functions. We can also add a dead_code for now to leave them available to the public API

[hjeljeli32]

IMO we can avoid this. For the error, we could store the public verification key instead; for SingleSignatureWithRegisteredParty, either keep ClosedRegistrationEntry public with restricted constructors, or make the field private and expose public accessors.

[damrobi]

Regarding the registration error, it's an error that should go away during the next refactor of the function when we have a way to deduplicate without returning an error. Otherwise, we might need to split the error in two to handle both a duplication of the BLS and Schnorr key.
For the SingleSignatureWithRegisteredParty, I tried passing the ClosedRegistrationEntry in pub(crate) to fix the warning

[Copilot]

Pull request overview

This PR refactors parts of mithril-stm around registration/PoP enforcement and protocol parameter validation, and hardens several legacy byte decoders by switching to checked arithmetic to avoid panics/overflows during deserialization.

Changes:

• Added checked offset arithmetic in multiple legacy decoders (Merkle tree / commitments, concatenation proof, single signature).
• Validated phi_f is within (0, 1] and propagated errors through lottery/eligibility paths.
• Tightened key-registration APIs to ensure external callers must go through PoP-verifying registration paths (plus associated visibility/documentation updates).

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
mithril-stm/tests/test_extensions/protocol_phase.rs	Update test registration flow to use KeyRegistration::register() (PoP-verifying).
mithril-stm/src/protocol/single_signature/signature.rs	Harden single-signature legacy decoding with checked offsets; adjust tests for new encapsulation.
mithril-stm/src/protocol/single_signature/signature_registered_party.rs	Restrict access to registered-party payload inside signature wrapper; update tests accordingly.
mithril-stm/src/protocol/participant/initializer.rs	Use ClosedKeyRegistration accessor instead of direct field access.
mithril-stm/src/protocol/mod.rs	Stop publicly re-exporting RegistrationEntry; keep it crate-visible where needed.
mithril-stm/src/protocol/key_registration/registration_entry.rs	Make RegistrationEntry crate-private and remove serde derives to prevent unverified external construction.
mithril-stm/src/protocol/key_registration/register.rs	Make register_by_entry crate-private; encapsulate ClosedKeyRegistration fields and provide crate accessor(s).
mithril-stm/src/protocol/key_registration/mod.rs	Narrow RegistrationEntry re-export to pub(crate).
mithril-stm/src/protocol/key_registration/closed_registration_entry.rs	Make ClosedRegistrationEntry::new private to ensure construction flows through verified paths.
mithril-stm/src/protocol/error.rs	Silence private_interfaces warning on a public error carrying a now-private type.
mithril-stm/src/proof_system/halo2_snark/mod.rs	Update call sites to use ClosedKeyRegistration accessor.
mithril-stm/src/proof_system/halo2_snark/eligibility.rs	Add (0, 1] validation for phi_f and tests for invalid values.
mithril-stm/src/proof_system/halo2_snark/aggregate_key.rs	Use ClosedKeyRegistration accessor for total stake.
mithril-stm/src/proof_system/concatenation/single_signature.rs	Propagate phi_f validation errors from lottery checks.
mithril-stm/src/proof_system/concatenation/signer.rs	Make lottery check fallible (StmResult) and propagate errors.
mithril-stm/src/proof_system/concatenation/proof.rs	Harden concatenation-proof legacy decoding with checked offsets.
mithril-stm/src/proof_system/concatenation/eligibility.rs	Validate phi_f and make is_lottery_won fallible; add tests for invalid values.
mithril-stm/src/proof_system/concatenation/aggregate_key.rs	Use ClosedKeyRegistration accessor for total stake.
mithril-stm/src/membership_commitment/merkle_tree/tree.rs	Harden MerkleTree legacy decoding with checked arithmetic; adjust lint-handling around (de)serialization helpers.
mithril-stm/src/membership_commitment/merkle_tree/commitment.rs	Harden batch commitment verification arithmetic with checked ops.
mithril-stm/src/lib.rs	Update public docs/imports to reflect new registration API (no public RegistrationEntry).
mithril-stm/README.md	Update README example to use KeyRegistration::register().
mithril-stm/examples/key_registration.rs	Update example to use KeyRegistration::register().
mithril-stm/CHANGELOG.md	Add a new release entry describing the refactor/validation/decoder hardening.
mithril-stm/benches/stm.rs	Update benches to use KeyRegistration::register().
mithril-stm/benches/size_benches.rs	Update benches to use KeyRegistration::register().