SNARK-friendly STM: Re-organize modules

mithril-stm/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.6.2 (11-27-2025)
+
+### Changed
+
+- Stm library re-organized for SNARK-friendliness.
+
 ## 0.6.1 (11-27-2025)
 
 ### Added

mithril-stm/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mithril-stm"
-version = "0.6.1"
+version = "0.6.2"
 edition = { workspace = true }
 authors = { workspace = true }
 homepage = { workspace = true }

mithril-stm/src/lib.rs

@@ -111,37 +111,21 @@
 //! # }
 //! ```
 
-mod aggregate_signature;
-mod bls_multi_signature;
-mod eligibility_check;
-mod error;
-mod key_registration;
-mod merkle_tree;
-mod parameters;
-mod participant;
-#[cfg(feature = "future_snark")]
-mod schnorr_signature;
-mod single_signature;
+mod membership_commitment;
+mod proof_system;
+mod protocol;
+mod signature_scheme;
 
-pub use aggregate_signature::{
-    AggregateSignature, AggregateSignatureType, AggregateVerificationKey, BasicVerifier, Clerk,
-};
-pub use error::{
-    AggregateSignatureError, AggregationError, MultiSignatureError, RegisterError, SignatureError,
-};
-pub use key_registration::{ClosedKeyRegistration, KeyRegistration};
-pub use parameters::Parameters;
-pub use participant::{Initializer, Signer, VerificationKey, VerificationKeyProofOfPossession};
-pub use single_signature::{SingleSignature, SingleSignatureWithRegisteredParty};
+pub use protocol::*;
 
 #[cfg(feature = "benchmark-internals")]
-pub use bls_multi_signature::{
+pub use signature_scheme::{
     BlsProofOfPossession, BlsSignature, BlsSigningKey, BlsVerificationKey,
     BlsVerificationKeyProofOfPossession,
 };
 
-#[cfg(feature = "future_snark")]
-pub use schnorr_signature::{SchnorrSignature, SchnorrSigningKey, SchnorrVerificationKey};
+#[cfg(all(feature = "benchmark-internals", feature = "future_snark"))]
+pub use signature_scheme::{SchnorrSignature, SchnorrSigningKey, SchnorrVerificationKey};
 
 /// The quantity of stake held by a party, represented as a `u64`.
 pub type Stake = u64;
@@ -155,49 +139,3 @@ pub type StmError = anyhow::Error;
 
 /// Mithril-stm result type
 pub type StmResult<T> = anyhow::Result<T, StmError>;
-
-// Aliases
-#[deprecated(since = "0.5.0", note = "Use `AggregateSignature` instead")]
-pub use aggregate_signature::AggregateSignature as StmAggrSig;
-
-#[deprecated(since = "0.5.0", note = "Use `AggregateVerificationKey` instead")]
-pub use aggregate_signature::AggregateVerificationKey as StmAggrVerificationKey;
-
-#[deprecated(since = "0.5.0", note = "Use `Clerk` instead")]
-pub use aggregate_signature::Clerk as StmClerk;
-
-#[deprecated(since = "0.5.0", note = "Use `ClosedKeyRegistration` instead")]
-pub use key_registration::ClosedKeyRegistration as ClosedKeyReg;
-
-#[deprecated(since = "0.5.0", note = "Use `KeyRegistration` instead")]
-pub use key_registration::KeyRegistration as KeyReg;
-
-#[deprecated(since = "0.5.0", note = "Use `Parameters` instead")]
-pub use parameters::Parameters as StmParameters;
-
-#[deprecated(since = "0.5.0", note = "Use `Initializer` instead")]
-pub use participant::Initializer as StmInitializer;
-
-#[deprecated(since = "0.5.0", note = "Use `Signer` instead")]
-pub use participant::Signer as StmSigner;
-
-#[deprecated(since = "0.5.0", note = "Use `VerificationKey` instead")]
-pub use participant::VerificationKey as StmVerificationKey;
-
-#[deprecated(
-    since = "0.5.0",
-    note = "Use `VerificationKeyProofOfPossession` instead"
-)]
-pub use participant::VerificationKeyProofOfPossession as StmVerificationKeyPoP;
-
-#[deprecated(since = "0.5.0", note = "Use `SingleSignature` instead")]
-pub use single_signature::SingleSignature as StmSig;
-
-#[deprecated(since = "0.5.0", note = "Use `BasicVerifier` instead")]
-pub use aggregate_signature::BasicVerifier as CoreVerifier;
-
-#[deprecated(
-    since = "0.5.0",
-    note = "Use `SingleSignatureWithRegisteredParty` instead"
-)]
-pub use single_signature::SingleSignatureWithRegisteredParty as StmSigRegParty;

mithril-stm/src/merkle_tree/commitment.rs → mithril-stm/src/membership_commitment/merkle_tree/commitment.rs

@@ -1,12 +1,11 @@
-use std::marker::PhantomData;
-
+use anyhow::{Context, anyhow};
 use blake2::digest::{Digest, FixedOutput};
 use serde::{Deserialize, Serialize};
+use std::marker::PhantomData;
+
+use super::{MerkleBatchPath, MerklePath, MerkleTreeLeaf, parent, sibling};
+use crate::{MerkleTreeError, StmResult};
 
-use crate::StmResult;
-use crate::error::MerkleTreeError;
-use crate::merkle_tree::{MerkleBatchPath, MerklePath, MerkleTreeLeaf, parent, sibling};
-use anyhow::{Context, anyhow};
 /// `MerkleTree` commitment.
 /// This structure differs from `MerkleTree` in that it does not contain all elements, which are not always necessary.
 /// Instead, it only contains the root of the tree.

mithril-stm/src/merkle_tree/leaf.rs → mithril-stm/src/membership_commitment/merkle_tree/leaf.rs

@@ -1,11 +1,10 @@
+use serde::{Deserialize, Serialize};
 use std::cmp::Ordering;
 
-use serde::{Deserialize, Serialize};
+use crate::{
+    MerkleTreeError, Stake, StmResult, VerificationKey, signature_scheme::BlsVerificationKey,
+};
 
-use crate::StmResult;
-use crate::bls_multi_signature::BlsVerificationKey;
-use crate::error::MerkleTreeError;
-use crate::{Stake, VerificationKey};
 /// The values that are committed in the Merkle Tree.
 /// Namely, a verified `VerificationKey` and its corresponding stake.
 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize, Hash)]

mithril-stm/src/merkle_tree/path.rs → mithril-stm/src/membership_commitment/merkle_tree/path.rs

@@ -1,9 +1,8 @@
-use std::marker::PhantomData;
-
-use crate::StmResult;
-use crate::error::MerkleTreeError;
 use blake2::digest::{Digest, FixedOutput};
 use serde::{Deserialize, Serialize};
+use std::marker::PhantomData;
+
+use crate::{MerkleTreeError, StmResult};
 
 /// Path of hashes from root to leaf in a Merkle Tree.
 /// Contains all hashes on the path, and the index of the leaf.

mithril-stm/src/merkle_tree/tree.rs → mithril-stm/src/membership_commitment/merkle_tree/tree.rs

@@ -1,14 +1,12 @@
-use std::marker::PhantomData;
-
 use blake2::digest::{Digest, FixedOutput};
 use serde::{Deserialize, Serialize};
+use std::marker::PhantomData;
 
-use crate::StmResult;
-use crate::error::MerkleTreeError;
-use crate::merkle_tree::{
+use super::{
     MerkleBatchPath, MerklePath, MerkleTreeBatchCommitment, MerkleTreeCommitment, MerkleTreeLeaf,
     left_child, parent, right_child, sibling,
 };
+use crate::{MerkleTreeError, StmResult};
 
 /// Tree of hashes, providing a commitment of data and its ordering.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
@@ -269,13 +267,14 @@ impl<D: Digest + FixedOutput> MerkleTree<D> {
 
 #[cfg(test)]
 mod tests {
-    use super::*;
-    use crate::bls_multi_signature::BlsVerificationKey;
     use blake2::{Blake2b, digest::consts::U32};
-    use proptest::collection::vec;
-    use proptest::prelude::*;
+    use proptest::{collection::vec, prelude::*};
     use rand::{rng, seq::IteratorRandom};
 
+    use crate::signature_scheme::BlsVerificationKey;
+
+    use super::*;
+
     fn pow2_plus1(h: usize) -> usize {
         1 + 2_usize.pow(h as u32)
     }

mithril-stm/src/membership_commitment/mod.rs

@@ -0,0 +1,3 @@
+mod merkle_tree;
+
+pub use merkle_tree::*;

mithril-stm/src/aggregate_signature/proof/concatenation.rs → mithril-stm/src/proof_system/concatenation.rs

@@ -1,15 +1,12 @@
 use anyhow::Context;
 use blake2::digest::{Digest, FixedOutput};
-
 use serde::{Deserialize, Serialize};
 
-use crate::aggregate_signature::clerk::Clerk;
-use crate::bls_multi_signature::{BlsSignature, BlsVerificationKey};
-use crate::key_registration::RegisteredParty;
-use crate::merkle_tree::MerkleBatchPath;
 use crate::{
-    AggregateSignatureError, AggregateVerificationKey, BasicVerifier, Parameters, SingleSignature,
-    SingleSignatureWithRegisteredParty, StmResult,
+    AggregateSignatureError, AggregateVerificationKey, BasicVerifier, Clerk, Parameters,
+    RegisteredParty, SingleSignature, SingleSignatureWithRegisteredParty, StmResult,
+    membership_commitment::MerkleBatchPath,
+    signature_scheme::{BlsSignature, BlsVerificationKey},
 };
 
 /// `ConcatenationProof` uses the "concatenation" proving system (as described in Section 4.3 of the original paper.)

mithril-stm/src/aggregate_signature/aggregate_key.rs → mithril-stm/src/protocol/aggregate_signature/aggregate_key.rs

@@ -1,8 +1,10 @@
 use blake2::digest::{Digest, FixedOutput};
 use serde::{Deserialize, Serialize};
 
-use crate::merkle_tree::{MerkleBatchPath, MerkleTreeBatchCommitment};
-use crate::{ClosedKeyRegistration, Stake};
+use crate::{
+    ClosedKeyRegistration, Stake,
+    membership_commitment::{MerkleBatchPath, MerkleTreeBatchCommitment},
+};
 
 /// Stm aggregate key (batch compatible), which contains the merkle tree commitment and the total stake of the system.
 /// Batch Compat Merkle tree commitment includes the number of leaves in the tree in order to obtain batch path.

mithril-stm/src/aggregate_signature/basic_verifier.rs → mithril-stm/src/protocol/aggregate_signature/basic_verifier.rs

@@ -1,12 +1,11 @@
 use anyhow::{Context, anyhow};
 use std::collections::{BTreeMap, HashMap, HashSet};
 
-use crate::bls_multi_signature::{BlsSignature, BlsVerificationKey};
-use crate::key_registration::RegisteredParty;
-use crate::merkle_tree::MerkleTreeLeaf;
 use crate::{
-    AggregationError, Index, Parameters, SingleSignature, SingleSignatureWithRegisteredParty,
-    Stake, StmResult,
+    AggregationError, Index, Parameters, RegisteredParty, SingleSignature,
+    SingleSignatureWithRegisteredParty, Stake, StmResult,
+    membership_commitment::MerkleTreeLeaf,
+    signature_scheme::{BlsSignature, BlsVerificationKey},
 };
 
 /// Full node verifier including the list of eligible signers and the total stake of the system.

mithril-stm/src/aggregate_signature/clerk.rs → mithril-stm/src/protocol/aggregate_signature/clerk.rs

@@ -1,8 +1,3 @@
-use crate::{
-    AggregateSignature, AggregateSignatureType, AggregateVerificationKey, ClosedKeyRegistration,
-    Index, Parameters, Signer, SingleSignature, Stake, StmResult, VerificationKey,
-    aggregate_signature::ConcatenationProof,
-};
 use anyhow::Context;
 use blake2::digest::{Digest, FixedOutput};
 
@@ -12,6 +7,12 @@ use anyhow::anyhow;
 #[cfg(feature = "future_proof_system")]
 use crate::AggregationError;
 
+use super::{AggregateSignature, AggregateSignatureType, AggregateVerificationKey};
+use crate::{
+    ClosedKeyRegistration, Index, Parameters, Signer, SingleSignature, Stake, StmResult,
+    VerificationKey, proof_system::ConcatenationProof,
+};
+
 /// `Clerk` can verify and aggregate `SingleSignature`s and verify `AggregateSignature`s.
 /// Clerks can only be generated with the registration closed.
 /// This avoids that a Merkle Tree is computed before all parties have registered.

mithril-stm/src/aggregate_signature/mod.rs → mithril-stm/src/protocol/aggregate_signature/mod.rs

@@ -1,19 +1,15 @@
 mod aggregate_key;
 mod basic_verifier;
 mod clerk;
-mod proof;
 mod signature;
 
 pub use aggregate_key::*;
 pub use basic_verifier::*;
 pub use clerk::*;
-pub use proof::*;
 pub use signature::*;
 
 #[cfg(test)]
 mod tests {
-    use std::collections::{HashMap, HashSet};
-
     use blake2::{Blake2b, digest::consts::U32};
     use proptest::{
         collection::{hash_map, vec},
@@ -22,13 +18,14 @@ mod tests {
     };
     use rand_chacha::ChaCha20Rng;
     use rand_core::{RngCore, SeedableRng};
+    use std::collections::{HashMap, HashSet};
 
+    use super::{AggregateSignature, AggregateSignatureType, BasicVerifier, Clerk};
     use crate::{
-        AggregateSignature, AggregateSignatureType, AggregationError, BasicVerifier, Clerk,
-        Initializer, KeyRegistration, Parameters, Signer, SingleSignature,
-        SingleSignatureWithRegisteredParty, Stake, bls_multi_signature::BlsVerificationKey,
+        AggregationError, Initializer, KeyRegistration, Parameters, Signer, SingleSignature,
+        SingleSignatureWithRegisteredParty, Stake, StmResult,
+        membership_commitment::MerkleBatchPath, signature_scheme::BlsVerificationKey,
     };
-    use crate::{StmResult, merkle_tree::MerkleBatchPath};
 
     type Sig = AggregateSignature<D>;
     type D = Blake2b<U32>;

mithril-stm/src/aggregate_signature/signature.rs → mithril-stm/src/protocol/aggregate_signature/signature.rs

@@ -1,16 +1,13 @@
-use std::collections::HashMap;
-use std::fmt::Display;
-use std::hash::Hash;
-
 use anyhow::anyhow;
 use blake2::digest::{Digest, FixedOutput};
 use serde::{Deserialize, Serialize};
+use std::{collections::HashMap, fmt::Display, hash::Hash};
 
-use crate::error::AggregateSignatureError;
-use crate::merkle_tree::MerkleBatchPath;
-use crate::{AggregateVerificationKey, Parameters, StmResult};
-
-use super::ConcatenationProof;
+use super::AggregateVerificationKey;
+use crate::{
+    AggregateSignatureError, Parameters, StmResult, membership_commitment::MerkleBatchPath,
+    proof_system::ConcatenationProof,
+};
 
 /// The type of STM aggregate signature.
 #[derive(Default, Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
@@ -211,10 +208,10 @@ mod tests {
         use rand_chacha::ChaCha20Rng;
         use rand_core::SeedableRng;
 
-        use crate::bls_multi_signature::{BlsSigningKey, BlsVerificationKeyProofOfPossession};
+        use super::{AggregateSignature, AggregateSignatureType};
         use crate::{
-            AggregateSignature, AggregateSignatureType, Clerk, ClosedKeyRegistration,
-            KeyRegistration, Parameters, Signer,
+            Clerk, ClosedKeyRegistration, KeyRegistration, Parameters, Signer,
+            signature_scheme::{BlsSigningKey, BlsVerificationKeyProofOfPossession},
         };
 
         type D = Blake2b<U32>;

mithril-stm/src/error.rs → mithril-stm/src/protocol/error.rs

@@ -2,10 +2,9 @@
 use anyhow::anyhow;
 use blst::BLST_ERROR;
 
-use crate::StmResult;
-use crate::aggregate_signature::AggregateSignatureType;
-use crate::bls_multi_signature::{
-    BlsSignature, BlsVerificationKey, BlsVerificationKeyProofOfPossession,
+use crate::{
+    AggregateSignatureType, StmResult,
+    signature_scheme::{BlsSignature, BlsVerificationKey, BlsVerificationKeyProofOfPossession},
 };
 
 /// Error types for multi signatures.
@@ -123,7 +122,7 @@ pub enum RegisterError {
     UnregisteredInitializer,
 }
 
-pub(crate) fn blst_error_to_stm_error(
+pub fn blst_error_to_stm_error(
     e: BLST_ERROR,
     sig: Option<BlsSignature>,
     key: Option<BlsVerificationKey>,