primitives - validator - document messages

Author: elpiel

primitives/src/validator.rs

@@ -308,6 +308,8 @@ pub mod messages {
         }
     }
 
+    /// Generated by the follower when a [`NewState`]
+    /// is generated by the leader and the state is signable and correct.
     #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
     #[serde(rename_all = "camelCase")]
     pub struct ApproveState {
@@ -316,6 +318,8 @@ pub mod messages {
         pub is_healthy: bool,
     }
 
+    /// Generated by the [`Channel.leader`](crate::Channel::leader)
+    /// on changed balances for the [`Channel`](crate::Channel).
     #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
     #[serde(rename_all = "camelCase")]
     pub struct NewState<S: BalancesState> {
@@ -335,6 +339,18 @@ pub mod messages {
         }
     }
 
+    /// Generated by the [`Channel.follower`] on:
+    ///
+    /// - Payout mismatch in the [`NewState`] between earner & spenders (i.e. their sum is not equal)
+    /// - Invalid [`NewState`] root hash.
+    /// - Failed verification of the expected signer ([`Channel.leader`])
+    ///   with the proposed [`NewState`] signature and state root.
+    /// - Invalid state transition (balances should always go up)
+    /// - [`NewState`] is unsignable because the health is below the [`Config.health_unsignable_promilles`]
+    ///
+    /// [`Channel.follower`]: crate::Channel::follower
+    /// [`Channel.leader`]: crate::Channel::leader
+    /// [`Config.health_unsignable_promilles`]: crate::Config::health_unsignable_promilles
     #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
     #[serde(rename_all = "camelCase")]
     pub struct RejectState<S: BalancesState> {
@@ -347,6 +363,13 @@ pub mod messages {
         pub timestamp: DateTime<Utc>,
     }
 
+    /// Heartbeat sent to each [`Channel`] validator by the
+    /// other validator of the [`Channel`].
+    ///
+    /// The Heartbeat is sent on regular intervals every [`Config.heartbeat_time`].
+    ///
+    /// [`Channel`]: crate::Channel
+    /// [`Config.heartbeat_time`]: crate::Config::heartbeat_time
     #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
     #[serde(rename_all = "camelCase")]
     pub struct Heartbeat {
@@ -365,6 +388,7 @@ pub mod messages {
         }
     }
 
+    /// The message types used by validator.
     #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
     #[serde(tag = "type")]
     pub enum MessageTypes {