mithril_stm/
lib.rs

1#![doc = include_str!("../README.md")]
2//! Implementation of Stake-based Threshold Multisignatures
3//! Top-level API for Mithril Stake-based Threshold Multisignature scheme.
4//! See figure 6 of [the paper](https://eprint.iacr.org/2021/916) for most of the
5//! protocol.
6//!
7//! What follows is a simple example showing the usage of STM.
8//!
9//! ```rust
10//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
11//! use blake2::{Blake2b, digest::consts::U32};
12//! use rand_chacha::ChaCha20Rng;
13//! use rand_core::{RngCore, SeedableRng};
14//! use rayon::prelude::*; // We use par_iter to speed things up
15//!
16//! use mithril_stm::{
17//!    AggregateSignatureType, AggregationError, Clerk, Initializer, KeyRegistration, Parameters,
18//!    Signer, SingleSignature,
19//! };
20//!
21//! let nparties = 4; // Use a small number of parties for this example
22//! type D = Blake2b<U32>; // Setting the hash function for convenience
23//!
24//! let mut rng = ChaCha20Rng::from_seed([0u8; 32]); // create and initialize rng
25//! let mut msg = [0u8; 16]; // setting an arbitrary message
26//! rng.fill_bytes(&mut msg);
27//!
28//! // In the following, we will have 4 parties try to sign `msg`, then aggregate and
29//! // verify those signatures.
30//!
31//! //////////////////////////
32//! // initialization phase //
33//! //////////////////////////
34//!
35//! // Set low parameters for testing
36//! // XXX: not for production
37//! let params = Parameters {
38//!     m: 100, // Security parameter XXX: not for production
39//!     k: 2, // Quorum parameter XXX: not for production
40//!     phi_f: 0.2, // Lottery parameter XXX: not for production
41//! };
42//!
43//! // Generate some arbitrary stake for each party
44//! // Stake is an integer.
45//! // Total stake of all parties is total stake in the system.
46//! let stakes = (0..nparties)
47//!     .into_iter()
48//!     .map(|_| 1 + (rng.next_u64() % 9999))
49//!     .collect::<Vec<_>>();
50//!
51//! // Create a new key registry from the parties and their stake
52//! let mut key_reg = KeyRegistration::init();
53//!
54//! // For each party, crate a Initializer.
55//! // This struct can create keys for the party.
56//! let mut ps: Vec<Initializer> = Vec::with_capacity(nparties);
57//! for stake in stakes {
58//!     // Create keys for this party
59//!     let p = Initializer::new(params, stake, &mut rng);
60//!     // Register keys with the KeyRegistration service
61//!     key_reg
62//!         .register(p.stake, p.verification_key())
63//!         .unwrap();
64//!     ps.push(p);
65//! }
66//!
67//! // Close the key registration.
68//! let closed_reg = key_reg.close();
69//!
70//! // Finalize the Initializer and turn it into a Signer, which can execute the
71//! // rest of the protocol.
72//! let ps = ps
73//!     .into_par_iter()
74//!     .map(|p| p.new_signer(closed_reg.clone()).unwrap())
75//!     .collect::<Vec<Signer<D>>>();
76//!
77//! /////////////////////
78//! // operation phase //
79//! /////////////////////
80//!
81//! // Next, each party tries to sign the message for each index available.
82//! // We collect the successful signatures into a vec.
83//! let sigs = ps
84//!     .par_iter()
85//!     .filter_map(|p| {
86//!         return p.sign(&msg);
87//!     })
88//!     .collect::<Vec<SingleSignature>>();
89//!
90//! // Clerk can aggregate and verify signatures.
91//! let clerk = Clerk::from_signer(&ps[0]);
92//!
93//! // Aggregate and verify the signatures
94//! let msig = clerk.aggregate(&sigs, &msg);
95//! match msig {
96//!     Ok(aggr) => {
97//!         println!("Aggregate ok");
98//!         assert!(aggr
99//!             .verify(&msg, &clerk.compute_avk(), &params)
100//!             .is_ok());
101//!     }
102//!     Err(AggregationError::NotEnoughSignatures(n, k)) => {
103//!         println!("Not enough signatures");
104//!         assert!(n < params.k && k == params.k)
105//!     }
106//!     Err(_) => unreachable!(),
107//! }
108//! # Ok(())
109//! # }
110//! ```
111
112mod aggregate_signature;
113mod bls_multi_signature;
114mod eligibility_check;
115mod error;
116mod key_registration;
117mod merkle_tree;
118mod parameters;
119mod participant;
120mod single_signature;
121
122pub use aggregate_signature::{
123    AggregateSignature, AggregateSignatureType, AggregateVerificationKey, BasicVerifier, Clerk,
124};
125pub use error::{
126    AggregationError, CoreVerifierError, RegisterError, StmAggregateSignatureError,
127    StmSignatureError,
128};
129pub use key_registration::{ClosedKeyRegistration, KeyRegistration};
130pub use parameters::Parameters;
131pub use participant::{Initializer, Signer, VerificationKey, VerificationKeyProofOfPossession};
132pub use single_signature::{SingleSignature, SingleSignatureWithRegisteredParty};
133
134#[cfg(feature = "benchmark-internals")]
135pub use bls_multi_signature::{
136    BlsProofOfPossession, BlsSignature, BlsSigningKey, BlsVerificationKey,
137    BlsVerificationKeyProofOfPossession,
138};
139
140/// The quantity of stake held by a party, represented as a `u64`.
141pub type Stake = u64;
142
143/// Quorum index for signatures.
144/// An aggregate signature (`StmMultiSig`) must have at least `k` unique indices.
145pub type Index = u64;
146
147// Aliases
148#[deprecated(since = "0.5.0", note = "Use `AggregateSignature` instead")]
149pub use aggregate_signature::AggregateSignature as StmAggrSig;
150
151#[deprecated(since = "0.5.0", note = "Use `AggregateVerificationKey` instead")]
152pub use aggregate_signature::AggregateVerificationKey as StmAggrVerificationKey;
153
154#[deprecated(since = "0.5.0", note = "Use `Clerk` instead")]
155pub use aggregate_signature::Clerk as StmClerk;
156
157#[deprecated(since = "0.5.0", note = "Use `ClosedKeyRegistration` instead")]
158pub use key_registration::ClosedKeyRegistration as ClosedKeyReg;
159
160#[deprecated(since = "0.5.0", note = "Use `KeyRegistration` instead")]
161pub use key_registration::KeyRegistration as KeyReg;
162
163#[deprecated(since = "0.5.0", note = "Use `Parameters` instead")]
164pub use parameters::Parameters as StmParameters;
165
166#[deprecated(since = "0.5.0", note = "Use `Initializer` instead")]
167pub use participant::Initializer as StmInitializer;
168
169#[deprecated(since = "0.5.0", note = "Use `Signer` instead")]
170pub use participant::Signer as StmSigner;
171
172#[deprecated(since = "0.5.0", note = "Use `VerificationKey` instead")]
173pub use participant::VerificationKey as StmVerificationKey;
174
175#[deprecated(
176    since = "0.5.0",
177    note = "Use `VerificationKeyProofOfPossession` instead"
178)]
179pub use participant::VerificationKeyProofOfPossession as StmVerificationKeyPoP;
180
181#[deprecated(since = "0.5.0", note = "Use `SingleSignature` instead")]
182pub use single_signature::SingleSignature as StmSig;
183
184#[deprecated(since = "0.5.0", note = "Use `BasicVerifier` instead")]
185pub use aggregate_signature::BasicVerifier as CoreVerifier;
186
187#[deprecated(
188    since = "0.5.0",
189    note = "Use `SingleSignatureWithRegisteredParty` instead"
190)]
191pub use single_signature::SingleSignatureWithRegisteredParty as StmSigRegParty;
mithril_stm/lib.rs

mithril_stm/
lib.rs
