Skip to content

Enhance STM library readability - Deprecate Old Structs #2629

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 4, 2025
Merged

Enhance STM library readability - Deprecate Old Structs #2629

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5d9f1bb
deprecate old struct names
curiecrypt Jul 2, 2025
05092fc
change log and crates version
curiecrypt Jul 2, 2025
a5b7cc1
update demo md - depr StmParameters
curiecrypt Jul 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

14 changes: 7 additions & 7 deletions demo/protocol-demo/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,16 +73,16 @@ Party #1: party created with 741 stakes
Party #2: party created with 144 stakes
Party #3: party created with 734 stakes
Party #4: party created with 41 stakes
Protocol established to StmParameters { m: 100, k: 5, phi_f: 0.2 }
Protocol established to Parameters { m: 100, k: 5, phi_f: 0.2 }

>> Protocol initialize phase:
Verifier: verifier created
Verifier: protocol params updated to StmParameters { m: 100, k: 5, phi_f: 0.2 }
Party #0: protocol params updated to StmParameters { m: 100, k: 5, phi_f: 0.2 }
Party #1: protocol params updated to StmParameters { m: 100, k: 5, phi_f: 0.2 }
Party #2: protocol params updated to StmParameters { m: 100, k: 5, phi_f: 0.2 }
Party #3: protocol params updated to StmParameters { m: 100, k: 5, phi_f: 0.2 }
Party #4: protocol params updated to StmParameters { m: 100, k: 5, phi_f: 0.2 }
Verifier: protocol params updated to Parameters { m: 100, k: 5, phi_f: 0.2 }
Party #0: protocol params updated to Parameters { m: 100, k: 5, phi_f: 0.2 }
Party #1: protocol params updated to Parameters { m: 100, k: 5, phi_f: 0.2 }
Party #2: protocol params updated to Parameters { m: 100, k: 5, phi_f: 0.2 }
Party #3: protocol params updated to Parameters { m: 100, k: 5, phi_f: 0.2 }
Party #4: protocol params updated to Parameters { m: 100, k: 5, phi_f: 0.2 }
Verifier: protocol keys registration from [(0, 826), (1, 741), (2, 144), (3, 734), (4, 41)]
Party #0: protocol keys registration from [(0, 826), (1, 741), (2, 144), (3, 734), (4, 41)]
Party #1: protocol keys registration from [(0, 826), (1, 741), (2, 144), (3, 734), (4, 41)]
Expand Down
36 changes: 18 additions & 18 deletions demo/protocol-demo/src/types.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
use mithril_stm::{
KeyReg, Stake, StmAggrSig, StmClerk, StmInitializer, StmParameters, StmSig, StmSigner,
StmVerificationKeyPoP,
AggregateSignature, Clerk, Initializer, KeyRegistration, Parameters, Signer, SingleSignature,
Stake, VerificationKeyProofOfPossession,
};

use blake2::{Blake2b, digest::consts::U32};
Expand All @@ -14,26 +14,26 @@ pub type ProtocolPartyId = String;
/// Alias of [MithrilStm:Stake](type@mithril_stm::Stake).
pub type ProtocolStake = Stake;

/// Alias of [MithrilStm::StmParameters](struct@mithril_stm::StmParameters).
pub type ProtocolParameters = StmParameters;
/// Alias of [MithrilStm::Parameters](struct@mithril_stm::Parameters).
pub type ProtocolParameters = Parameters;

/// Alias of [MithrilStm:StmSigner](struct@mithril_stm::StmSigner).
pub type ProtocolSigner = StmSigner<D>;
/// Alias of [MithrilStm:Signer](struct@mithril_stm::Signer).
pub type ProtocolSigner = Signer<D>;

/// Alias of [MithrilStm:StmClerk](struct@mithril_stm::StmClerk).
pub type ProtocolClerk = StmClerk<D>;
/// Alias of [MithrilStm:Clerk](struct@mithril_stm::Clerk).
pub type ProtocolClerk = Clerk<D>;

/// Alias of [MithrilStm:StmInitializer](struct@mithril_stm::StmInitializer).
pub type ProtocolInitializerNotCertified = StmInitializer;
/// Alias of [MithrilStm:Initializer](struct@mithril_stm::Initializer).
pub type ProtocolInitializerNotCertified = Initializer;

/// Alias of [MithrilStm:KeyReg](struct@mithril_stm::KeyReg). (Test only)
pub type ProtocolKeyRegistrationNotCertified = KeyReg;
/// Alias of [MithrilStm:KeyRegistration](struct@mithril_stm::KeyRegistration). (Test only)
pub type ProtocolKeyRegistrationNotCertified = KeyRegistration;

/// Alias of [MithrilStm:StmSig](struct@mithril_stm::StmSig).
pub type ProtocolSingleSignature = StmSig;
/// Alias of [MithrilStm:SingleSignature](struct@mithril_stm::SingleSignature).
pub type ProtocolSingleSignature = SingleSignature;

/// Alias of [MithrilStm:StmAggrSig](struct@mithril_stm::StmAggrSig).
pub type ProtocolMultiSignature = StmAggrSig<D>;
/// Alias of [MithrilStm:AggregateSignature](struct@mithril_stm::AggregateSignature).
pub type ProtocolMultiSignature = AggregateSignature<D>;

/// Alias of [MithrilStm:StmVerificationKeyPoP](type@mithril_stm::StmVerificationKeyPoP).
pub type ProtocolSignerVerificationKey = StmVerificationKeyPoP;
/// Alias of [MithrilStm:VerificationKeyProofOfPossession](type@mithril_stm::VerificationKeyProofOfPossession).
pub type ProtocolSignerVerificationKey = VerificationKeyProofOfPossession;
28 changes: 14 additions & 14 deletions docs/website/root/manual/develop/protocol-simulation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,16 +130,16 @@ Party #1: party created with 741 stakes
Party #2: party created with 144 stakes
Party #3: party created with 734 stakes
Party #4: party created with 41 stakes
Protocol established to StmParameters { m: 50, k: 5, phi_f: 0.65 }
Protocol established to Parameters { m: 50, k: 5, phi_f: 0.65 }

>> Protocol initialization phase:
Verifier: verifier created
Verifier: protocol params updated to StmParameters { m: 50, k: 5, phi_f: 0.65 }
Party #0: protocol params updated to StmParameters { m: 50, k: 5, phi_f: 0.65 }
Party #1: protocol params updated to StmParameters { m: 50, k: 5, phi_f: 0.65 }
Party #2: protocol params updated to StmParameters { m: 50, k: 5, phi_f: 0.65 }
Party #3: protocol params updated to StmParameters { m: 50, k: 5, phi_f: 0.65 }
Party #4: protocol params updated to StmParameters { m: 50, k: 5, phi_f: 0.65 }
Verifier: protocol params updated to Parameters { m: 50, k: 5, phi_f: 0.65 }
Party #0: protocol params updated to Parameters { m: 50, k: 5, phi_f: 0.65 }
Party #1: protocol params updated to Parameters { m: 50, k: 5, phi_f: 0.65 }
Party #2: protocol params updated to Parameters { m: 50, k: 5, phi_f: 0.65 }
Party #3: protocol params updated to Parameters { m: 50, k: 5, phi_f: 0.65 }
Party #4: protocol params updated to Parameters { m: 50, k: 5, phi_f: 0.65 }
Verifier: protocol keys registration from [("0", 826), ("1", 741), ("2", 144), ("3", 734), ("4", 41)]
Party #0: protocol keys registration from [("0", 826), ("1", 741), ("2", 144), ("3", 734), ("4", 41)]
Party #1: protocol keys registration from [("0", 826), ("1", 741), ("2", 144), ("3", 734), ("4", 41)]
Expand Down Expand Up @@ -252,16 +252,16 @@ Party #1: party created with 741 stakes
Party #2: party created with 144 stakes
Party #3: party created with 734 stakes
Party #4: party created with 41 stakes
Protocol established to StmParameters { m: 5, k: 5, phi_f: 0.25 }
Protocol established to Parameters { m: 5, k: 5, phi_f: 0.25 }

>> Protocol initialization phase:
Verifier: verifier created
Verifier: protocol params updated to StmParameters { m: 5, k: 5, phi_f: 0.25 }
Party #0: protocol params updated to StmParameters { m: 5, k: 5, phi_f: 0.25 }
Party #1: protocol params updated to StmParameters { m: 5, k: 5, phi_f: 0.25 }
Party #2: protocol params updated to StmParameters { m: 5, k: 5, phi_f: 0.25 }
Party #3: protocol params updated to StmParameters { m: 5, k: 5, phi_f: 0.25 }
Party #4: protocol params updated to StmParameters { m: 5, k: 5, phi_f: 0.25 }
Verifier: protocol params updated to Parameters { m: 5, k: 5, phi_f: 0.25 }
Party #0: protocol params updated to Parameters { m: 5, k: 5, phi_f: 0.25 }
Party #1: protocol params updated to Parameters { m: 5, k: 5, phi_f: 0.25 }
Party #2: protocol params updated to Parameters { m: 5, k: 5, phi_f: 0.25 }
Party #3: protocol params updated to Parameters { m: 5, k: 5, phi_f: 0.25 }
Party #4: protocol params updated to Parameters { m: 5, k: 5, phi_f: 0.25 }
Verifier: protocol keys registration from [("0", 826), ("1", 741), ("2", 144), ("3", 734), ("4", 41)]
Party #0: protocol keys registration from [("0", 826), ("1", 741), ("2", 144), ("3", 734), ("4", 41)]
Party #1: protocol keys registration from [("0", 826), ("1", 741), ("2", 144), ("3", 734), ("4", 41)]
Expand Down
44 changes: 22 additions & 22 deletions mithril-common/src/crypto_helper/cardano/key_certification.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
//! API for mithril key certification.
//! Includes the wrappers for StmInitializer and KeyReg, and ProtocolRegistrationErrorWrapper.
//! Includes the wrappers for Initializer and KeyRegistration, and ProtocolRegistrationErrorWrapper.
//! These wrappers allows keeping mithril-stm agnostic to Cardano, while providing some
//! guarantees that mithril-stm will not be misused in the context of Cardano.

Expand All @@ -15,8 +15,8 @@ use serde::{Deserialize, Serialize};
use thiserror::Error;

use mithril_stm::{
ClosedKeyReg, KeyReg, RegisterError, Stake, StmInitializer, StmParameters, StmSigner,
StmVerificationKeyPoP,
ClosedKeyRegistration, Initializer, KeyRegistration, Parameters, RegisterError, Signer, Stake,
VerificationKeyProofOfPossession,
};

use crate::{
Expand Down Expand Up @@ -95,13 +95,13 @@ pub enum ProtocolInitializerErrorWrapper {
KesMismatch(KesPeriod, KesPeriod),
}

/// Wrapper structure for [MithrilStm:StmInitializer](mithril_stm::stm::StmInitializer).
/// Wrapper structure for [MithrilStm:Initializer](mithril_stm::stm::Initializer).
/// It now obtains a KES signature over the Mithril key. This allows the signers prove
/// their correct identity with respect to a Cardano PoolID.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StmInitializerWrapper {
/// The StmInitializer
stm_initializer: StmInitializer,
/// The Initializer
stm_initializer: Initializer,

/// The KES signature over the Mithril key
///
Expand All @@ -110,17 +110,17 @@ pub struct StmInitializerWrapper {
}

impl StmInitializerWrapper {
/// Builds an `StmInitializer` that is ready to register with the key registration service.
/// Builds an `Initializer` that is ready to register with the key registration service.
/// This function generates the signing and verification key with a PoP, signs the verification
/// key with a provided KES signer implementation, and initializes the structure.
pub fn setup<R: RngCore + CryptoRng>(
params: StmParameters,
params: Parameters,
kes_signer: Option<Arc<dyn KesSigner>>,
kes_period: Option<KesPeriod>,
stake: Stake,
rng: &mut R,
) -> StdResult<Self> {
let stm_initializer = StmInitializer::setup(params, stake, rng);
let stm_initializer = Initializer::setup(params, stake, rng);
let kes_signature = if let Some(kes_signer) = kes_signer {
let (signature, _op_cert) = kes_signer.sign(
&stm_initializer.verification_key().to_bytes(),
Expand All @@ -142,7 +142,7 @@ impl StmInitializerWrapper {
}

/// Extract the verification key.
pub fn verification_key(&self) -> StmVerificationKeyPoP {
pub fn verification_key(&self) -> VerificationKeyProofOfPossession {
self.stm_initializer.verification_key()
}

Expand All @@ -163,8 +163,8 @@ impl StmInitializerWrapper {

/// Build the `avk` for the given list of parties.
///
/// Note that if this StmInitializer was modified *between* the last call to `register`,
/// then the resulting `StmSigner` may not be able to produce valid signatures.
/// Note that if this Initializer was modified *between* the last call to `register`,
/// then the resulting `Signer` may not be able to produce valid signatures.
///
/// Returns a `StmSignerWrapper` specialized to
/// * this `StmSignerWrapper`'s ID and current stake
Expand All @@ -175,8 +175,8 @@ impl StmInitializerWrapper {
/// This function fails if the initializer is not registered.
pub fn new_signer(
self,
closed_reg: ClosedKeyReg<D>,
) -> Result<StmSigner<D>, ProtocolRegistrationErrorWrapper> {
closed_reg: ClosedKeyRegistration<D>,
) -> Result<Signer<D>, ProtocolRegistrationErrorWrapper> {
self.stm_initializer
.new_signer(closed_reg)
.map_err(ProtocolRegistrationErrorWrapper::CoreRegister)
Expand All @@ -201,7 +201,7 @@ impl StmInitializerWrapper {
/// The function fails if the given string of bytes is not of required size.
pub fn from_bytes(bytes: &[u8]) -> Result<Self, RegisterError> {
let stm_initializer =
StmInitializer::from_bytes(bytes.get(..256).ok_or(RegisterError::SerializationError)?)?;
Initializer::from_bytes(bytes.get(..256).ok_or(RegisterError::SerializationError)?)?;
let bytes = bytes.get(256..).ok_or(RegisterError::SerializationError)?;
let kes_signature = if bytes.is_empty() {
None
Expand All @@ -216,14 +216,14 @@ impl StmInitializerWrapper {
}

cfg_test_tools! {
/// Override the protocol parameters of the `StmInitializer` for testing purposes only.
/// Override the protocol parameters of the `Initializer` for testing purposes only.
pub fn override_protocol_parameters(&mut self, protocol_parameters: &ProtocolParameters) {
self.stm_initializer.params = protocol_parameters.to_owned();
}
}
}

/// Wrapper structure for [MithrilStm:KeyReg](mithril_stm::key_reg::KeyReg).
/// Wrapper structure for [MithrilStm:KeyRegistration](mithril_stm::key_reg::KeyRegistration).
/// The wrapper not only contains a map between `Mithril vkey <-> Stake`, but also
/// a map `PoolID <-> Stake`. This information is recovered from the node state, and
/// is used to verify the identity of a Mithril signer. Furthermore, the `register` function
Expand All @@ -232,7 +232,7 @@ impl StmInitializerWrapper {
#[derive(Debug, Clone)]
pub struct KeyRegWrapper {
kes_verifier: Arc<dyn KesVerifier>,
stm_key_reg: KeyReg,
stm_key_reg: KeyRegistration,
stake_distribution: HashMap<ProtocolPartyId, Stake>,
}

Expand All @@ -242,7 +242,7 @@ impl KeyRegWrapper {
pub fn init(stake_dist: &ProtocolStakeDistribution) -> Self {
Self {
kes_verifier: Arc::new(KesVerifierStandard),
stm_key_reg: KeyReg::init(),
stm_key_reg: KeyRegistration::init(),
stake_distribution: HashMap::from_iter(stake_dist.to_vec()),
}
}
Expand Down Expand Up @@ -293,8 +293,8 @@ impl KeyRegWrapper {
}

/// Finalize the key registration.
/// This function disables `KeyReg::register`, consumes the instance of `self`, and returns a `ClosedKeyReg`.
pub fn close<D: Digest + FixedOutput>(self) -> ClosedKeyReg<D> {
/// This function disables `ClosedKeyRegistration::register`, consumes the instance of `self`, and returns a `ClosedKeyRegistration`.
pub fn close<D: Digest + FixedOutput>(self) -> ClosedKeyRegistration<D> {
self.stm_key_reg.close()
}
}
Expand All @@ -317,7 +317,7 @@ mod test {

#[test]
fn test_vector_key_reg() {
let params = StmParameters {
let params = Parameters {
m: 5,
k: 5,
phi_f: 1.0,
Expand Down
Loading
Loading