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(error) => assert!(
103//!         matches!(
104//!             error.downcast_ref::<AggregationError>(),
105//!             Some(AggregationError::NotEnoughSignatures { .. })
106//!         ),
107//!         "Unexpected error: {error}"
108//!     ),
109//! }
110//! # Ok(())
111//! # }
112//! ```
113
114mod membership_commitment;
115mod proof_system;
116mod protocol;
117mod signature_scheme;
118
119pub use protocol::*;
120
121#[cfg(feature = "benchmark-internals")]
122pub use signature_scheme::{
123    BlsProofOfPossession, BlsSignature, BlsSigningKey, BlsVerificationKey,
124    BlsVerificationKeyProofOfPossession,
125};
126
127#[cfg(all(feature = "benchmark-internals", feature = "future_snark"))]
128pub use signature_scheme::{SchnorrSignature, SchnorrSigningKey, SchnorrVerificationKey};
129
130/// The quantity of stake held by a party, represented as a `u64`.
131pub type Stake = u64;
132
133/// Quorum index for signatures.
134/// An aggregate signature (`StmMultiSig`) must have at least `k` unique indices.
135pub type Index = u64;
136
137/// Mithril-stm error type
138pub type StmError = anyhow::Error;
139
140/// Mithril-stm result type
141pub type StmResult<T> = anyhow::Result<T, StmError>;
mithril_stm/lib.rs

mithril_stm/
lib.rs
