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

mithril_stm/
lib.rs
