chore: adding doc to lib

.github/workflows/quality.yml

@@ -9,6 +9,25 @@ on:
   workflow_dispatch:
 
 jobs:
+
+  readme:
+    name: Readme - checking readme compatibility
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - uses: ./.github/actions/install-rust
+        with:
+          with_cache: false
+          tools: cargo-readme
+          AWS_ACCESS_KEY_ID: ${{ secrets.ROBOT_AWS_ACCESS_KEY_ID}}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.ROBOT_AWS_SECRET_ACCESS_KEY}}
+
+      - name: checking readme
+        run: ./scripts/check_readme.sh
+
+
   audit:
     name: Audit - crate security vulnerabilities
     runs-on: ubuntu-latest

crates/topos-tce-broadcast/README.md

@@ -0,0 +1,36 @@
+# topos-tce-broadcast
+
+Implementation of Topos Reliable Broadcast to be used in the Transmission Control Engine (TCE)
+
+This crate is designed to be used as a library in the TCE implementation.
+It covers the Reliable Broadcast part of the TCE, which is the core of the TCE.
+It doesn't handle how messages are sent or received, nor how the certificates are stored.
+It is designed to be used with any transport and storage implementation, relying on the
+`ProtocolEvents` and `DoubleEchoCommand` to communicate with the transport and storage.
+
+The reliable broadcast allows a set of validators to agree on a set of messages in order to
+reach agreement about the delivery of a certificate.
+
+Each certificates need to be broadcast to the network, and each validator needs to
+receive a threshold of messages from the other validators.
+The thresholds are defined by the `ReliableBroadcastParams` and correspond to the minimum number of
+validators who need to agree on one certificate in order to consider it delivered.
+
+This crate is responsible for validating and driving the broadcast of every certificates.
+
+### Input
+
+The input of the broadcast is a certificate to be broadcast. It can be received from
+the transport layer, or from the storage layer (from the pending tables).
+
+The transport layer can be anything from p2p network to API calls.
+
+Other inputs are the messages received from the transport layer, coming from other validators.
+They're `Echo` and `Ready` signed messages.
+
+### Output
+
+The outcome of the broadcast is either a certificate delivered or a failure on the delivery.
+
+The implementation is based on the paper: [Topos: A Secure, Trustless, and Decentralized Interoperability Protocol](https://arxiv.org/pdf/2206.03481.pdf)
+

crates/topos-tce-broadcast/src/lib.rs

@@ -1,11 +1,39 @@
-//! implementation of Topos Reliable Broadcast to be used in the Transmission Control Engine (TCE)
+//! Implementation of Topos Reliable Broadcast to be used in the Transmission Control Engine (TCE)
+//!
+//! This crate is designed to be used as a library in the TCE implementation.
+//! It covers the Reliable Broadcast part of the TCE, which is the core of the TCE.
+//! It doesn't handle how messages are sent or received, nor how the certificates are stored.
+//! It is designed to be used with any transport and storage implementation, relying on the
+//! `ProtocolEvents` and `DoubleEchoCommand` to communicate with the transport and storage.
+//!
+//! The reliable broadcast allows a set of validators to agree on a set of messages in order to
+//! reach agreement about the delivery of a certificate.
+//!
+//! Each certificates need to be broadcast to the network, and each validator needs to
+//! receive a threshold of messages from the other validators.
+//! The thresholds are defined by the `ReliableBroadcastParams` and correspond to the minimum number of
+//! validators who need to agree on one certificate in order to consider it delivered.
+//!
+//! This crate is responsible for validating and driving the broadcast of every certificates.
+//!
+//! ## Input
+//!
+//! The input of the broadcast is a certificate to be broadcast. It can be received from
+//! the transport layer, or from the storage layer (from the pending tables).
+//!
+//! The transport layer can be anything from p2p network to API calls.
+//!
+//! Other inputs are the messages received from the transport layer, coming from other validators.
+//! They're `Echo` and `Ready` signed messages.
+//!
+//! ## Output
+//!
+//! The outcome of the broadcast is either a certificate delivered or a failure on the delivery.
+//!
+//! The implementation is based on the paper: [Topos: A Secure, Trustless, and Decentralized Interoperability Protocol](https://arxiv.org/pdf/2206.03481.pdf)
 //!
-//! Abstracted from actual transport implementation.
-//! Abstracted from actual storage implementation.
-
 use double_echo::DoubleEcho;
 use futures::Stream;
-use sampler::SampleType;
 use std::collections::HashSet;
 use std::sync::Arc;
 use tce_transport::{ProtocolEvents, ReliableBroadcastParams};
@@ -42,7 +70,7 @@ use crate::sampler::SubscriptionsView;
 
 #[derive(Debug)]
 pub enum TaskStatus {
-    /// The task finished successfully and broadcasted the certificate + received ready
+    /// The task finished successfully and broadcast the certificate + received ready
     Success,
     /// The task did not finish successfully and stopped.
     Failure,
@@ -56,23 +84,6 @@ pub struct ReliableBroadcastConfig {
     pub message_signer: Arc<MessageSigner>,
 }
 
-#[derive(Debug)]
-pub enum SamplerCommand {
-    ValidatorChanged {
-        validators: Vec<ValidatorId>,
-    },
-    ConfirmValidator {
-        validator: ValidatorId,
-        sample_type: SampleType,
-        sender: oneshot::Sender<Result<(), ()>>,
-    },
-    ValidatorConfirmationFailed {
-        validator: ValidatorId,
-        sample_type: SampleType,
-    },
-    ForceResample,
-}
-
 #[derive(Debug, Clone)]
 pub enum DoubleEchoCommand {
     /// Entry point for new certificate to submit as initial sender
@@ -198,9 +209,6 @@ pub enum Errors {
     #[error("Error while waiting for a DoubleEchoCommand response: {0:?}")]
     DoubleEchoRecv(#[from] oneshot::error::RecvError),
 
-    #[error("Error while sending a SamplerCommand to Sampler: {0:?}")]
-    SamplerSend(#[from] mpsc::error::SendError<SamplerCommand>),
-
     #[error("Requested certificate not found")]
     CertificateNotFound,
 

crates/topos-tce-broadcast/src/sampler/mod.rs

@@ -1,19 +1,6 @@
 use std::collections::HashSet;
 use topos_core::types::ValidatorId;
 
-/// Categorize what we expect from which peer for the broadcast
-#[derive(PartialEq, Eq, Hash, Debug, Clone)]
-pub enum SampleType {
-    /// Listen Echo from this Sample
-    EchoSubscription,
-    /// Listen Ready from this Sample
-    ReadySubscription,
-    /// Send Echo to this Sample
-    EchoSubscriber,
-    /// Send Ready to this Sample
-    ReadySubscriber,
-}
-
 /// Stateful network view with whom we broadcast the Certificate
 /// The Echo and the Ready sets are initially equal to the whole network
 #[derive(Debug, Clone, Eq, PartialEq, Default)]

scripts/check_readme.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+
+set -e
+
+param=$1
+
+function check {
+  if [ "$param" == "generate" ]; then
+    cargo readme -r $1 > $1/README.md
+  else
+    diff <(cargo readme  -r $1) $1/README.md || (echo 1>&2 "Please update the $1/README with "'`'"cargo readme -r $1 > $1/README.md"'`' && exit 1 )
+  fi
+}
+
+check crates/topos-tce-broadcast