commonware_consensus/lib.rs
1//! Order opaque messages in a Byzantine environment.
2//!
3//! # Status
4//!
5//! `commonware-consensus` is **ALPHA** software and is not yet recommended for production use. Developers should
6//! expect breaking changes and occasional instability.
7
8use commonware_codec::Codec;
9use commonware_cryptography::{Committable, Digestible};
10
11pub mod aggregation;
12pub mod ordered_broadcast;
13pub mod simplex;
14pub mod threshold_simplex;
15
16/// Viewable is a trait that provides access to the view (round) number.
17/// Any consensus message or object that is associated with a specific view should implement this.
18pub trait Viewable {
19 /// View is the type used to indicate the in-progress consensus decision.
20 type View;
21
22 /// Returns the view associated with this object.
23 fn view(&self) -> Self::View;
24}
25
26/// Block is the interface for a block in the blockchain.
27///
28/// Blocks are used to track the progress of the consensus engine.
29pub trait Block: Codec + Digestible + Committable + Send + Sync + 'static {
30 /// Get the height of the block.
31 fn height(&self) -> u64;
32
33 /// Get the parent block's digest.
34 fn parent(&self) -> Self::Commitment;
35}
36
37cfg_if::cfg_if! {
38 if #[cfg(not(target_arch = "wasm32"))] {
39 use commonware_cryptography::{Digest, PublicKey};
40 use futures::channel::{oneshot, mpsc};
41 use std::future::Future;
42
43 pub mod marshal;
44 mod reporter;
45 pub use reporter::*;
46
47 /// Histogram buckets for measuring consensus latency.
48 const LATENCY: [f64; 36] = [
49 0.05, 0.1, 0.125, 0.15, 0.16, 0.17, 0.18, 0.19, 0.2, 0.21, 0.22, 0.23, 0.24, 0.25, 0.26, 0.27, 0.28, 0.29, 0.3, 0.31, 0.32, 0.33, 0.34, 0.35,
50 0.36, 0.37, 0.38, 0.39, 0.4, 0.45, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0,
51 ];
52
53 /// Automaton is the interface responsible for driving the consensus forward by proposing new payloads
54 /// and verifying payloads proposed by other participants.
55 pub trait Automaton: Clone + Send + 'static {
56 /// Context is metadata provided by the consensus engine associated with a given payload.
57 ///
58 /// This often includes things like the proposer, view number, the height, or the epoch.
59 type Context;
60
61 /// Hash of an arbitrary payload.
62 type Digest: Digest;
63
64 /// Payload used to initialize the consensus engine.
65 fn genesis(&mut self) -> impl Future<Output = Self::Digest> + Send;
66
67 /// Generate a new payload for the given context.
68 ///
69 /// If it is possible to generate a payload, the Digest should be returned over the provided
70 /// channel. If it is not possible to generate a payload, the channel can be dropped. If construction
71 /// takes too long, the consensus engine may drop the provided proposal.
72 fn propose(
73 &mut self,
74 context: Self::Context,
75 ) -> impl Future<Output = oneshot::Receiver<Self::Digest>> + Send;
76
77 /// Verify the payload is valid.
78 ///
79 /// If it is possible to verify the payload, a boolean should be returned indicating whether
80 /// the payload is valid. If it is not possible to verify the payload, the channel can be dropped.
81 fn verify(
82 &mut self,
83 context: Self::Context,
84 payload: Self::Digest,
85 ) -> impl Future<Output = oneshot::Receiver<bool>> + Send;
86 }
87
88 /// Relay is the interface responsible for broadcasting payloads to the network.
89 ///
90 /// The consensus engine is only aware of a payload's digest, not its contents. It is up
91 /// to the relay to efficiently broadcast the full payload to other participants.
92 pub trait Relay: Clone + Send + 'static {
93 /// Hash of an arbitrary payload.
94 type Digest: Digest;
95
96 /// Called once consensus begins working towards a proposal provided by `Automaton` (i.e.
97 /// it isn't dropped).
98 ///
99 /// Other participants may not begin voting on a proposal until they have the full contents,
100 /// so timely delivery often yields better performance.
101 fn broadcast(&mut self, payload: Self::Digest) -> impl Future<Output = ()> + Send;
102 }
103
104 /// Reporter is the interface responsible for reporting activity to some external actor.
105 pub trait Reporter: Clone + Send + 'static {
106 /// Activity is specified by the underlying consensus implementation and can be interpreted if desired.
107 ///
108 /// Examples of activity would be "vote", "finalize", or "fault". Various consensus implementations may
109 /// want to reward (or penalize) participation in different ways and in different places. For example,
110 /// validators could be required to send multiple types of messages (i.e. vote and finalize) and rewarding
111 /// both equally may better align incentives with desired behavior.
112 type Activity;
113
114 /// Report some activity observed by the consensus implementation.
115 fn report(&mut self, activity: Self::Activity) -> impl Future<Output = ()> + Send;
116 }
117
118 /// Supervisor is the interface responsible for managing which participants are active at a given time.
119 ///
120 /// ## Synchronization
121 ///
122 /// It is up to the user to ensure changes in this list are synchronized across nodes in the network
123 /// at a given `Index`. If care is not taken to do this, consensus could halt (as different participants
124 /// may have a different view of who is active at a given time).
125 ///
126 /// The simplest way to avoid this complexity is to use a consensus implementation that reaches finalization
127 /// on application data before transitioning to a new `Index` (i.e. [Tendermint](https://arxiv.org/abs/1807.04938)).
128 ///
129 /// Implementations that do not work this way (like `simplex`) must introduce some synchrony bound for changes
130 /// (where it is assumed all participants have finalized some previous set change by some point) or "sync points"
131 /// (i.e. epochs) where participants agree that some finalization occurred at some point in the past.
132 pub trait Supervisor: Clone + Send + Sync + 'static {
133 /// Index is the type used to indicate the in-progress consensus decision.
134 type Index;
135
136 /// Public key used to identify participants.
137 type PublicKey: PublicKey;
138
139 /// Return the leader at a given index for the provided seed.
140 fn leader(&self, index: Self::Index) -> Option<Self::PublicKey>;
141
142 /// Get the **sorted** participants for the given view. This is called when entering a new view before
143 /// listening for proposals or votes. If nothing is returned, the view will not be entered.
144 fn participants(&self, index: Self::Index) -> Option<&Vec<Self::PublicKey>>;
145
146 // Indicate whether some candidate is a participant at the given view.
147 fn is_participant(&self, index: Self::Index, candidate: &Self::PublicKey) -> Option<u32>;
148 }
149
150 /// ThresholdSupervisor is the interface responsible for managing which `polynomial` (typically a polynomial with
151 /// a fixed constant `identity`) and `share` for a participant is active at a given time.
152 ///
153 /// ## Synchronization
154 ///
155 /// The same considerations for [crate::Supervisor] apply here.
156 pub trait ThresholdSupervisor: Supervisor {
157 /// Identity is the type against which threshold signatures are verified.
158 type Identity;
159
160 /// Seed is some random value used to bias the leader selection process.
161 type Seed;
162
163 /// Polynomial is the group polynomial over which partial signatures are verified.
164 type Polynomial;
165
166 /// Share is the type used to generate a partial signature that can be verified
167 /// against `Identity`.
168 type Share;
169
170 /// Returns the static identity of the shared secret (typically the constant term
171 /// of a polynomial).
172 fn identity(&self) -> &Self::Identity;
173
174 /// Return the leader at a given index over the provided seed.
175 fn leader(&self, index: Self::Index, seed: Self::Seed) -> Option<Self::PublicKey>;
176
177 /// Returns the polynomial over which partial signatures are verified at a given index.
178 fn polynomial(&self, index: Self::Index) -> Option<&Self::Polynomial>;
179
180 /// Returns share to sign with at a given index. After resharing, the share
181 /// may change (and old shares may be deleted).
182 ///
183 /// This can be used to generate a partial signature that can be verified
184 /// against `polynomial`.
185 fn share(&self, index: Self::Index) -> Option<&Self::Share>;
186 }
187
188 /// Monitor is the interface an external actor can use to observe the progress of a consensus implementation.
189 ///
190 /// Monitor is used to implement mechanisms that share the same set of active participants as consensus and/or
191 /// perform some activity that requires some synchronization with the progress of consensus.
192 ///
193 /// Monitor can be implemented using [crate::Reporter] to avoid introducing complexity
194 /// into any particular consensus implementation.
195 pub trait Monitor: Clone + Send + 'static {
196 /// Index is the type used to indicate the in-progress consensus decision.
197 type Index;
198
199 /// Create a channel that will receive updates when the latest index (also provided) changes.
200 fn subscribe(&mut self) -> impl Future<Output = (Self::Index, mpsc::Receiver<Self::Index>)> + Send;
201 }
202 }
203}