docs(code): Document the three consensus modes and how to pick a `Val…

…ue` type accordingly (#804)

* doc(code): Document the three consensus modes and how to pick a `Value` type accordingly

* Apply suggestions from code review

Co-authored-by: Daniel <[email protected]>
Signed-off-by: Romain Ruetschi <[email protected]>

---------

Signed-off-by: Romain Ruetschi <[email protected]>
Co-authored-by: Daniel <[email protected]>

code/crates/core-consensus/src/params.rs

@@ -1,9 +1,8 @@
 use derive_where::derive_where;
-use malachitebft_core_types::Context;
 
-pub use malachitebft_core_driver::ThresholdParams;
+use malachitebft_core_types::{Context, ValuePayload};
 
-use crate::ValuePayload;
+pub use malachitebft_core_driver::ThresholdParams;
 
 /// Consensus parameters.
 #[derive_where(Clone, Debug)]

code/crates/core-consensus/src/types.rs

@@ -5,6 +5,8 @@ use malachitebft_core_types::{
     Vote,
 };
 
+pub use malachitebft_core_types::ValuePayload;
+
 pub use malachitebft_peer::PeerId;
 pub use multiaddr::Multiaddr;
 
@@ -75,35 +77,3 @@ pub struct ProposedValue<Ctx: Context> {
     pub validity: Validity,
     pub extension: Option<SignedExtension<Ctx>>,
 }
-
-/// The possible messages used to deliver proposals
-#[derive(Clone, Copy, Debug, PartialEq, Eq)]
-pub enum ValuePayload {
-    PartsOnly,
-    ProposalOnly,
-    ProposalAndParts,
-}
-
-impl ValuePayload {
-    pub fn include_proposal(self) -> bool {
-        matches!(
-            self,
-            ValuePayload::ProposalOnly | ValuePayload::ProposalAndParts
-        )
-    }
-
-    pub fn include_parts(self) -> bool {
-        matches!(
-            self,
-            ValuePayload::PartsOnly | ValuePayload::ProposalAndParts
-        )
-    }
-
-    pub fn parts_only(self) -> bool {
-        matches!(self, ValuePayload::PartsOnly)
-    }
-
-    pub fn proposal_only(&self) -> bool {
-        matches!(self, ValuePayload::ProposalOnly)
-    }
-}

code/crates/core-types/src/context.rs

@@ -28,7 +28,8 @@ where
     /// The interface provided by the validator set type.
     type ValidatorSet: ValidatorSet<Self>;
 
-    /// The type of values that can be proposed.
+    /// The `Value` type denotes the value `v` carried by the `Proposal`
+    /// consensus message that is gossiped to other nodes by the proposer.
     type Value: Value;
 
     /// The type of votes that can be cast.

code/crates/core-types/src/lib.rs

@@ -63,6 +63,6 @@ pub use signing::{SigningProvider, SigningProviderExt, SigningScheme};
 pub use threshold::{Threshold, ThresholdParam, ThresholdParams};
 pub use timeout::{Timeout, TimeoutKind};
 pub use validator_set::{Address, Validator, ValidatorSet, VotingPower};
-pub use value::{NilOrVal, Value, ValueOrigin};
+pub use value::{NilOrVal, Value, ValueOrigin, ValuePayload};
 pub use vote::{Extension, Vote, VoteType};
 pub use vote_set::VoteSet;

code/crates/core-types/src/value.rs

@@ -54,24 +54,69 @@ impl<Value> NilOrVal<Value> {
     }
 }
 
-/// Defines the requirements for the type of value to decide on.
+/// The `Value` type denotes the value `v` carried by the `Proposal`
+/// consensus message broadcast by the proposer of a round of consensus.
+///
+/// How to instantiate `Value` with a concrete type depends on which mode consensus
+/// is parametrized to run in. See the documentation for the [`ValuePayload`]
+/// type for more information.
 pub trait Value
 where
     Self: Clone + Debug + PartialEq + Eq + PartialOrd + Ord + Send + Sync,
 {
-    /// The type of the ID for this value.
-    /// Typically, a representation of the value with a lower memory footprint.
-    type Id: Clone + Debug + Display + PartialEq + Eq + PartialOrd + Ord + Send + Sync;
+    /// A unique representation of the `Value` with a lower memory footprint, denoted `id(v)`.
+    /// It is carried by votes and herefore is typically set to be a hash of the value `v`.
+    type Id: Clone + Debug + Display + Eq + Ord + Send + Sync;
 
     /// The ID of the value.
     fn id(&self) -> Self::Id;
 }
 
+/// The possible messages used to deliver proposals
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum ValuePayload {
+    /// The proposer broadcasts a `Proposal` consensus message carrying the full proposed value `v`. There is no proposal part streaming.
+    /// Better suited for small proposed values when there are no benefits of gossiping proposal parts.
+    /// In this case `Value` is typically set to be the block and `Id` is its hash.
+    ProposalOnly,
+
+    /// The proposer does not broadcast a `Proposal` consensus message at all. The proposer only streams the proposed value as proposal parts.
+    /// In this case `Value` is typically set to the same type as `Id`.
+    PartsOnly,
+
+    /// The proposer broadcasts a `Proposal` message carrying `id(v)` and streams the full proposed value `v` as proposal parts.
+    /// In this case `Value` is typically set to the same type as `Id`.
+    ProposalAndParts,
+}
+
+impl ValuePayload {
+    /// Whether the proposer must publish the proposed value as a `Proposal` message.
+    pub fn include_proposal(self) -> bool {
+        matches!(self, Self::ProposalOnly | Self::ProposalAndParts)
+    }
+
+    /// Whether the proposer must publish the proposed value as parts.
+    pub fn include_parts(self) -> bool {
+        matches!(self, Self::PartsOnly | Self::ProposalAndParts)
+    }
+
+    /// Whether the proposal must only publish proposal parts, no `Proposal` message.
+    pub fn parts_only(self) -> bool {
+        matches!(self, Self::PartsOnly)
+    }
+
+    /// Whether the proposer must only publish a `Proposal` message, no proposal parts.
+    pub fn proposal_only(&self) -> bool {
+        matches!(self, Self::ProposalOnly)
+    }
+}
+
 /// Protocols that diseminate `Value`
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
 pub enum ValueOrigin {
     /// Synchronization protocol
     Sync,
+
     /// Consensus protocol
     Consensus,
 }