commonware_broadcast/
lib.rs

1//! Disseminate data over a wide-area network.
2
3use bytes::Bytes;
4use commonware_cryptography::Digest;
5use commonware_utils::Array;
6use futures::channel::oneshot;
7use std::future::Future;
8
9pub mod linked;
10
11/// Proof is a blob that attests to some data.
12pub type Proof = Bytes;
13
14/// Broadcaster is the interface responsible for replication of messages across a network.
15pub trait Broadcaster: Clone + Send + 'static {
16    /// Digest is an arbitrary hash digest.
17    type Digest: Digest;
18
19    /// Attempt to broadcast a digest to the network.
20    ///
21    /// Returns a future that resolves to a boolean indicating success.
22    /// The broadcast may fail for a variety of reasons such-as networking errors, the node not
23    /// being a valid sequencer, or the Broadcaster not being ready to broadcast a new payload.
24    fn broadcast(
25        &mut self,
26        payload: Self::Digest,
27    ) -> impl Future<Output = oneshot::Receiver<bool>> + Send;
28}
29
30/// Application is the interface responsible for processing messages received from the network.
31pub trait Application: Clone + Send + 'static {
32    /// Context is metadata provided by the broadcast engine to associated with a given payload.
33    /// This could include things like the public key of the sequencer.
34    type Context;
35
36    /// Digest is an arbitrary hash digest.
37    type Digest: Array;
38
39    /// Verify a proposed payload received from the network.
40    ///
41    /// Returns a future that resolves to a boolean indicating success.
42    /// Part of verification requires ensuring that the data is made available.
43    /// For example, by storing it in a database.
44    fn verify(
45        &mut self,
46        context: Self::Context,
47        payload: Self::Digest,
48    ) -> impl Future<Output = oneshot::Receiver<bool>> + Send;
49}
50
51/// Collector is the interface responsible for handling notifications of broadcasted payloads.
52pub trait Collector: Clone + Send + 'static {
53    /// Digest is an arbitrary hash digest.
54    type Digest: Digest;
55
56    /// Emit that a payload has been successfully broadcasted.
57    /// This is used to acknowledge that the payload has been "received" by the network,
58    /// for example that it has been successfully gossiped to a threshold of validators.
59    fn acknowledged(
60        &mut self,
61        proof: Proof,
62        payload: Self::Digest,
63    ) -> impl Future<Output = ()> + Send;
64}
65
66/// Coordinator is the interface responsible for managing the active set of sequencers and signers.
67///
68/// It is up to the user to ensure changes in this list are synchronized across nodes in the network
69/// at a given `Index`. Otherwise, "acknowledgement" of a payload by the network may be delayed or never occur.
70pub trait Coordinator: Clone + Send + Sync + 'static {
71    /// Index is the type used to identify a particular set of sequencers and signers.
72    type Index;
73
74    /// PublicKey is the type used to identify a sequencer or signer.
75    type PublicKey: Array;
76
77    /// Returns the current index of the coordinator.
78    fn index(&self) -> Self::Index;
79
80    /// Get the **sorted** sequencers for the given `Index`.
81    fn sequencers(&self, index: Self::Index) -> Option<&Vec<Self::PublicKey>>;
82
83    /// Returns the index of the sequencer (in the list of sorted sequencers) if the candidate is a sequencer at the given `Index`.
84    fn is_sequencer(&self, index: Self::Index, candidate: &Self::PublicKey) -> Option<u32>;
85
86    /// Get the **sorted** signers for the given `Index`.
87    fn signers(&self, index: Self::Index) -> Option<&Vec<Self::PublicKey>>;
88
89    /// Returns the index of the signer (in the list of sorted signers) if the candidate is a signer at the given `Index`.
90    fn is_signer(&self, index: Self::Index, candidate: &Self::PublicKey) -> Option<u32>;
91}
92
93/// ThresholdCoordinator is the interface responsible for managing which `identity` (typically a group polynomial with
94/// a fixed constant factor) and `share` for a signer is active at a given time.
95pub trait ThresholdCoordinator: Coordinator {
96    /// Identity is the type against which partial signatures are verified.
97    type Identity;
98
99    /// Share is the type used to generate a partial signature that can be verified
100    /// against `Identity`.
101    type Share;
102
103    /// Returns the identity (typically a group polynomial with a fixed constant factor)
104    /// at the given index. This is used to verify partial signatures from participants
105    /// enumerated in `Coordinator::signers`.
106    fn identity(&self, index: Self::Index) -> Option<&Self::Identity>;
107
108    /// Returns share to sign with at a given index. After resharing, the share
109    /// may change (and old shares may be deleted).
110    fn share(&self, index: Self::Index) -> Option<&Self::Share>;
111}
commonware_broadcast/lib.rs

commonware_broadcast/
lib.rs
