commonware_broadcast/
lib.rs

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

commonware_broadcast/
lib.rs
