A0-4333: Performance score API

consensus/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "aleph-bft"
-version = "0.37.2"
+version = "0.38.0"
 edition = "2021"
 authors = ["Cardinal Cryptography"]
 categories = ["algorithms", "data-structures", "cryptography", "database"]
@@ -13,8 +13,8 @@ readme = "../README.md"
 description = "AlephBFT is an asynchronous and Byzantine fault tolerant consensus protocol aimed at ordering arbitrary messages (transactions). It has been designed to continuously operate even in the harshest conditions: with no bounds on message-delivery delays and in the presence of malicious actors. This makes it an excellent fit for blockchain-related applications."
 
 [dependencies]
-aleph-bft-rmc = { path = "../rmc", version = "0.13" }
-aleph-bft-types = { path = "../types", version = "0.14" }
+aleph-bft-rmc = { path = "../rmc", version = "0.14" }
+aleph-bft-types = { path = "../types", version = "0.15" }
 anyhow = "1.0"
 async-trait = "0.1"
 codec = { package = "parity-scale-codec", version = "3.0", default-features = false, features = ["derive"] }

consensus/src/extension/mod.rs

@@ -33,7 +33,7 @@ impl<MK: MultiKeychain, UFH: UnitFinalizationHandler> Ordering<MK, UFH> {
     pub fn add_unit(&mut self, unit: DagUnit<UFH::Hasher, UFH::Data, MK>) {
         for batch in self.extender.add_unit(unit) {
             self.finalization_handler
-                .batch_finalized(batch.into_iter().map(|unit| unit.into()).collect());
+                .batch_finalized(batch.into_iter().map(|unit| unit.into()).collect(), vec![]);
         }
     }
 }

consensus/src/member.rs

@@ -11,7 +11,9 @@ use crate::{
     Config, Data, DataProvider, Hasher, MultiKeychain, Network, NodeIndex, Receiver, Recipient,
     Round, Sender, Signature, SpawnHandle, Terminator, UncheckedSigned,
 };
-use aleph_bft_types::{FinalizationHandler, NodeMap, OrderedUnit, UnitFinalizationHandler};
+use aleph_bft_types::{
+    FinalizationHandler, NodeMap, OrderedUnit, PerformancePenalties, UnitFinalizationHandler,
+};
 use codec::{Decode, Encode};
 use futures::{channel::mpsc, pin_mut, AsyncRead, AsyncWrite, FutureExt, StreamExt};
 use futures_timer::Delay;
@@ -127,12 +129,17 @@ impl<D: Data, H: Hasher, FH: FinalizationHandler<D>> UnitFinalizationHandler
     type Data = D;
     type Hasher = H;
 
-    fn batch_finalized(&mut self, batch: Vec<OrderedUnit<Self::Data, Self::Hasher>>) {
+    fn batch_finalized(
+        &mut self,
+        batch: Vec<OrderedUnit<Self::Data, Self::Hasher>>,
+        penalties: PerformancePenalties,
+    ) {
         for unit in batch {
             if let Some(data) = unit.data {
                 self.finalization_handler.data_finalized(data)
             }
         }
+        self.finalization_handler.performance_reported(penalties);
     }
 }
 

consensus/src/testing/dag.rs

@@ -12,7 +12,7 @@ use crate::{
     NodeCount, NodeIndex, NodeMap, NodeSubset, Round, Signed,
 };
 use aleph_bft_mock::{Data, Hash64, Hasher64, Keychain};
-use aleph_bft_types::{OrderedUnit, UnitFinalizationHandler};
+use aleph_bft_types::{OrderedUnit, PerformancePenalties, UnitFinalizationHandler};
 use log::debug;
 use parking_lot::Mutex;
 use rand::{distributions::Open01, prelude::*};
@@ -222,7 +222,11 @@ impl UnitFinalizationHandler for RecordingHandler {
     type Data = Data;
     type Hasher = Hasher64;
 
-    fn batch_finalized(&mut self, batch: Vec<OrderedUnit<Self::Data, Self::Hasher>>) {
+    fn batch_finalized(
+        &mut self,
+        batch: Vec<OrderedUnit<Self::Data, Self::Hasher>>,
+        _penalties: PerformancePenalties,
+    ) {
         let mut batch_of_data = batch.into_iter().filter_map(|unit| unit.data).collect();
         self.finalized.lock().append(&mut batch_of_data)
     }

examples/ordering/src/dataio.rs

@@ -1,5 +1,6 @@
 use aleph_bft_types::{
     DataProvider as DataProviderT, FinalizationHandler as FinalizationHandlerT, NodeIndex,
+    PerformancePenalties,
 };
 use async_trait::async_trait;
 use codec::{Decode, Encode};
@@ -63,6 +64,8 @@ impl FinalizationHandlerT<Data> for FinalizationHandler {
             error!(target: "finalization-handler", "Error when sending data from FinalizationHandler {:?}.", e);
         }
     }
+
+    fn performance_reported(&mut self, _penalties: PerformancePenalties) {}
 }
 
 impl FinalizationHandler {

mock/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "aleph-bft-mock"
-version = "0.15.0"
+version = "0.16.0"
 edition = "2021"
 authors = ["Cardinal Cryptography"]
 documentation = "https://docs.rs/?"
@@ -11,7 +11,7 @@ readme = "./README.md"
 description = "Mock implementations of traits required by the aleph-bft package. Do NOT use outside of testing!"
 
 [dependencies]
-aleph-bft-types = { path = "../types", version = "0.14" }
+aleph-bft-types = { path = "../types", version = "0.15" }
 async-trait = "0.1"
 codec = { package = "parity-scale-codec", version = "3.0", default-features = false, features = ["derive"] }
 futures = "0.3"

mock/src/dataio.rs

@@ -1,4 +1,7 @@
-use aleph_bft_types::{DataProvider as DataProviderT, FinalizationHandler as FinalizationHandlerT};
+use aleph_bft_types::{
+    DataProvider as DataProviderT, FinalizationHandler as FinalizationHandlerT,
+    PerformancePenalties,
+};
 use async_trait::async_trait;
 use codec::{Decode, Encode};
 use futures::{channel::mpsc::unbounded, future::pending, AsyncWrite};
@@ -82,6 +85,8 @@ impl FinalizationHandlerT<Data> for FinalizationHandler {
             error!(target: "finalization-handler", "Error when sending data from FinalizationHandler {:?}.", e);
         }
     }
+
+    fn performance_reported(&mut self, _penalties: PerformancePenalties) {}
 }
 
 impl FinalizationHandler {

rmc/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "aleph-bft-rmc"
-version = "0.13.0"
+version = "0.14.0"
 edition = "2021"
 authors = ["Cardinal Cryptography"]
 categories = ["algorithms", "cryptography"]
@@ -14,7 +14,7 @@ description = "Reliable MultiCast - a primitive for Reliable Broadcast protocol.
 
 [dependencies]
 aleph-bft-crypto = { path = "../crypto", version = "0.9" }
-aleph-bft-types = { path = "../types", version = "0.14" }
+aleph-bft-types = { path = "../types", version = "0.15" }
 async-trait = "0.1"
 codec = { package = "parity-scale-codec", version = "3.0", default-features = false, features = ["derive"] }
 futures = "0.3"

types/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "aleph-bft-types"
-version = "0.14.0"
+version = "0.15.0"
 edition = "2021"
 authors = ["Cardinal Cryptography"]
 documentation = "https://docs.rs/?"

types/src/dataio.rs

@@ -26,6 +26,11 @@ pub trait FinalizationHandler<D: Data>: Sync + Send + 'static {
     /// Data, provided by [DataProvider::get_data], has been finalized.
     /// The calls to this function follow the order of finalization.
     fn data_finalized(&mut self, data: D);
+
+    /// Called periodically when a new performance vector was calculated.
+    /// The scores are deterministic across all the committee members,
+    /// and the performance is reported at the same time, ordering-wise.
+    fn performance_reported(&mut self, penalties: PerformancePenalties);
 }
 
 /// Represents state of the main internal data structure of AlephBFT (i.e. direct acyclic graph) used for
@@ -42,6 +47,13 @@ pub struct OrderedUnit<D: Data, H: Hasher> {
     pub round: Round,
 }
 
+/// A vector of performance penalties reported whenever a batch of units has been finalized.
+/// For each committee member we calculate a penalty based on their performance while processing
+/// the latest batch. In normal conditions, we expect to get a vector of zeros.
+/// Penalties are ordered according to the ordering of the committee.
+/// Less is better.
+pub type PerformancePenalties = Vec<u32>;
+
 /// The source of finalization of the units that consensus produces.
 ///
 /// The [`UnitFinalizationHandler::batch_finalized`] method is called whenever a batch of units
@@ -52,5 +64,9 @@ pub trait UnitFinalizationHandler: Sync + Send + 'static {
 
     /// A batch of units, that contains data provided by [DataProvider::get_data], has been finalized.
     /// The calls to this function follow the order of finalization.
-    fn batch_finalized(&mut self, batch: Vec<OrderedUnit<Self::Data, Self::Hasher>>);
+    fn batch_finalized(
+        &mut self,
+        batch: Vec<OrderedUnit<Self::Data, Self::Hasher>>,
+        penalties: PerformancePenalties,
+    );
 }

types/src/lib.rs

@@ -9,7 +9,9 @@ pub use aleph_bft_crypto::{
     NodeIndex, NodeMap, NodeSubset, PartialMultisignature, PartiallyMultisigned, Signable,
     Signature, SignatureError, SignatureSet, Signed, UncheckedSigned,
 };
-pub use dataio::{DataProvider, FinalizationHandler, OrderedUnit, UnitFinalizationHandler};
+pub use dataio::{
+    DataProvider, FinalizationHandler, OrderedUnit, PerformancePenalties, UnitFinalizationHandler,
+};
 pub use network::{Network, Recipient};
 pub use tasks::{SpawnHandle, TaskHandle};