Merge pull request #440 from input-output-hk/greg/439/signer_documentation

add code doc & factor service initialization

Author: ghubertpalo

mithril-signer/src/certificate_handler.rs

@@ -13,24 +13,31 @@ use mithril_common::{
 #[cfg(test)]
 use mockall::automock;
 
+/// Error structure for the Certificate Handler.
 #[derive(Error, Debug)]
 pub enum CertificateHandlerError {
+    /// The aggregator host has returned a technical error.
     #[error("remote server technical error: '{0}'")]
     RemoteServerTechnical(String),
 
+    /// The aggregator host responded it cannot fulfill our request.
     #[error("remote server logical error: '{0}'")]
     RemoteServerLogical(String),
 
+    /// Could not reach aggregator.
     #[error("remote server unreachable: '{0}'")]
     RemoteServerUnreachable(String),
 
+    /// Could not parse response.
     #[error("json parsing failed: '{0}'")]
     JsonParseFailed(String),
 
+    /// Mostly network errors.
     #[error("io error: {0}")]
     IOError(#[from] io::Error),
 }
 
+/// Trait for mocking and testing a `CertificateHandler`
 #[cfg_attr(test, automock)]
 #[async_trait]
 pub trait CertificateHandler: Sync + Send {
@@ -39,10 +46,10 @@ pub trait CertificateHandler: Sync + Send {
         &self,
     ) -> Result<Option<CertificatePending>, CertificateHandlerError>;
 
-    /// Registers signer with the aggregator
+    /// Registers signer with the aggregator.
     async fn register_signer(&self, signer: &Signer) -> Result<(), CertificateHandlerError>;
 
-    /// Registers single signatures with the aggregator
+    /// Registers single signatures with the aggregator.
     async fn register_signatures(
         &self,
         signatures: &SingleSignatures,
@@ -138,12 +145,16 @@ impl CertificateHandler for CertificateHandlerHTTPClient {
     }
 }
 
+/// This certificate handler is intended to be used by test services.
+/// It actually does not communicate with an aggregator host but mimics this behavior.
+/// It is driven by a Tester that controls the CertificatePending it can return and it can return its internal state for testing.
 pub struct DumbCertificateHandler {
     certificate_pending: RwLock<Option<CertificatePending>>,
     last_registered_signer: RwLock<Option<Signer>>,
 }
 
 impl DumbCertificateHandler {
+    /// Instanciate a new DumbCertificateHandler.
     pub fn new() -> Self {
         Self {
             certificate_pending: RwLock::new(None),
@@ -160,6 +171,7 @@ impl DumbCertificateHandler {
         *signer = None;
     }
 
+    /// Return the last signer that called with the `register` method.
     pub async fn get_last_registered_signer(&self) -> Option<Signer> {
         self.last_registered_signer.read().await.clone()
     }

mithril-signer/src/entities.rs

@@ -38,6 +38,7 @@ pub struct Config {
 }
 
 impl Config {
+    /// Return the CardanoNetwork value from the configuration.
     pub fn get_network(&self) -> Result<CardanoNetwork, ConfigError> {
         match self.network.to_lowercase().as_str() {
             "mainnet" => Ok(CardanoNetwork::MainNet),

mithril-signer/src/lib.rs

@@ -1,3 +1,10 @@
+#![warn(missing_docs)]
+//! Mithril Signer crate documentation
+//!
+//! This crate is used by Cardano nodes to participate to Mithril signatures.
+//! It proposes tools to communicate with Mithril aggregators and to issue Single Signatures.
+//! See the [Mithril documentation](https://mithril.network/doc/manual/developer-docs/nodes/mithril-signer) for more information on how it works.
+
 use std::error::Error as StdError;
 
 mod certificate_handler;

mithril-signer/src/main.rs

@@ -1,19 +1,13 @@
 use clap::Parser;
-use mithril_common::BeaconProviderImpl;
 use slog::{o, Drain, Level, Logger};
 use slog_scope::debug;
 use std::env;
 use std::error::Error;
 use std::sync::Arc;
 use std::time::Duration;
 
-use mithril_common::chain_observer::{CardanoCliChainObserver, CardanoCliRunner};
-use mithril_common::digesters::{CardanoImmutableDigester, ImmutableFileSystemObserver};
-use mithril_common::store::adapter::JsonFileStoreAdapter;
-use mithril_common::store::StakeStore;
 use mithril_signer::{
-    CertificateHandlerHTTPClient, Config, MithrilSingleSigner, ProtocolInitializerStore,
-    SignerRunner, SignerServices, SignerState, StateMachine,
+    Config, ProductionServiceBuilder, ServiceBuilder, SignerRunner, SignerState, StateMachine,
 };
 
 /// CLI args
@@ -69,45 +63,12 @@ async fn main() -> Result<(), Box<dyn Error>> {
         .map_err(|e| format!("configuration deserialize error: {}", e))?;
     debug!("Started"; "run_mode" => &run_mode, "config" => format!("{:?}", config));
 
-    let protocol_initializer_store = Arc::new(ProtocolInitializerStore::new(Box::new(
-        JsonFileStoreAdapter::new(config.data_stores_directory.join("protocol_initializer_db"))?,
-    )));
-    let single_signer = Arc::new(MithrilSingleSigner::new(config.party_id.clone()));
-    let certificate_handler = Arc::new(CertificateHandlerHTTPClient::new(
-        config.aggregator_endpoint.clone(),
-    ));
-    let digester = Arc::new(CardanoImmutableDigester::new(
-        config.db_directory.clone(),
-        slog_scope::logger(),
-    ));
-    let stake_store = Arc::new(StakeStore::new(Box::new(JsonFileStoreAdapter::new(
-        config.data_stores_directory.join("stake_db"),
-    )?)));
-    let chain_observer = Arc::new(CardanoCliChainObserver::new(Box::new(
-        CardanoCliRunner::new(
-            config.cardano_cli_path.clone(),
-            config.cardano_node_socket_path.clone(),
-            config.get_network()?,
-        ),
-    )));
-    let beacon_provider = Arc::new(BeaconProviderImpl::new(
-        chain_observer.clone(),
-        Arc::new(ImmutableFileSystemObserver::new(&config.db_directory)),
-        config.get_network()?.to_owned(),
-    ));
-
-    let services = SignerServices {
-        beacon_provider,
-        certificate_handler,
-        chain_observer,
-        digester,
-        single_signer,
-        stake_store,
-        protocol_initializer_store,
-    };
     let mut state_machine = StateMachine::new(
         SignerState::Unregistered,
-        Box::new(SignerRunner::new(config.clone(), services)),
+        Box::new(SignerRunner::new(
+            config.clone(),
+            ProductionServiceBuilder::new(&config).build()?,
+        )),
         Duration::from_millis(config.run_interval),
     );
     state_machine.run().await

mithril-signer/src/protocol_initializer_store.rs

@@ -15,28 +15,35 @@ pub enum ProtocolInitializerStoreError {
 }
 
 #[async_trait]
+/// Store the ProtocolInitializer used for each Epoch. This is useful because
+/// protocol parameters and stake distribution change over time.
 pub trait ProtocolInitializerStorer: Sync + Send {
+    /// Save a protocol initializer for the given Epoch.
     async fn save_protocol_initializer(
         &self,
         epoch: Epoch,
         protocol_initializer: ProtocolInitializer,
     ) -> Result<Option<ProtocolInitializer>, ProtocolInitializerStoreError>;
 
+    /// Fetch a protocol initializer if any saved for the given Epoch.
     async fn get_protocol_initializer(
         &self,
         epoch: Epoch,
     ) -> Result<Option<ProtocolInitializer>, ProtocolInitializerStoreError>;
 
+    /// Return the list of the N last saved protocol initializers if any.
     async fn get_last_protocol_initializer(
         &self,
         last: usize,
     ) -> Result<Vec<(Epoch, ProtocolInitializer)>, ProtocolInitializerStoreError>;
 }
+/// Implementation of the ProtocolInitializerStorer
 pub struct ProtocolInitializerStore {
     adapter: RwLock<Adapter>,
 }
 
 impl ProtocolInitializerStore {
+    /// Create a new ProtocolInitializerStore.
     pub fn new(adapter: Adapter) -> Self {
         Self {
             adapter: RwLock::new(adapter),

mithril-signer/src/runtime/runner.rs

@@ -20,73 +20,91 @@ use crate::{Config, MithrilProtocolInitializerBuilder};
 
 use super::signer_services::SignerServices;
 
+/// This trait is mainly intended for mocking.
 #[async_trait]
 pub trait Runner {
+    /// Fetch the current pending certificate if any.
     async fn get_pending_certificate(
         &self,
     ) -> Result<Option<CertificatePending>, Box<dyn StdError + Sync + Send>>;
 
+    /// Fetch the current beacon from the Cardano node.
     async fn get_current_beacon(&self) -> Result<Beacon, Box<dyn StdError + Sync + Send>>;
 
+    /// Register the signer verification key to the aggregator.
     async fn register_signer_to_aggregator(
         &self,
         epoch: Epoch,
         protocol_parameters: &ProtocolParameters,
     ) -> Result<(), Box<dyn StdError + Sync + Send>>;
 
+    /// Read the stake distribution and store it.
     async fn update_stake_distribution(
         &self,
         epoch: Epoch,
     ) -> Result<(), Box<dyn StdError + Sync + Send>>;
 
+    /// Check if all prerequisites for signing are met.
     async fn can_i_sign(
         &self,
         pending_certificate: &CertificatePending,
     ) -> Result<bool, Box<dyn StdError + Sync + Send>>;
 
+    /// From a list of signers, associate them with the stake read on the
+    /// Cardano node.
     async fn associate_signers_with_stake(
         &self,
         epoch: Epoch,
         signers: &[Signer],
     ) -> Result<Vec<SignerWithStake>, Box<dyn StdError + Sync + Send>>;
 
+    /// Create the message to be signed with the single signature.
     async fn compute_message(
         &self,
         beacon: &Beacon,
         next_signers: &[SignerWithStake],
     ) -> Result<ProtocolMessage, Box<dyn StdError + Sync + Send>>;
 
+    /// Create the single signature.
     async fn compute_single_signature(
         &self,
         epoch: Epoch,
         message: &ProtocolMessage,
         signers: &[SignerWithStake],
     ) -> Result<Option<SingleSignatures>, Box<dyn StdError + Sync + Send>>;
 
+    /// Send the single signature to the aggregator in order to be aggregated.
     async fn send_single_signature(
         &self,
         maybe_signature: Option<SingleSignatures>,
     ) -> Result<(), Box<dyn StdError + Sync + Send>>;
 }
 
+/// This type represents the errors thrown from the Runner.
 #[derive(Debug, Clone, PartialEq, Eq, Error)]
 pub enum RuntimeError {
+    /// Value was expected from a subsystem but None was returned.
     #[error("No value returned by the subsystem for `{0}`.")]
     NoValueError(String),
+    /// Could not associate my node with a stake.
     #[error("No stake associated with myself.")]
     NoStakeForSelf(),
+    /// Could not find the stake for one of the signers.
     #[error("No stake associated with this signer, party_id: {0}.")]
     NoStakeForSigner(PartyId),
+    /// General subsystem error
     #[error("Subsystem unavailable: {0}.")]
     SubsystemUnavailable(String),
 }
 
+/// Controller methods for the Signer's state machine.
 pub struct SignerRunner {
     config: Config,
     services: SignerServices,
 }
 
 impl SignerRunner {
+    /// Create a new Runner instance.
     pub fn new(config: Config, services: SignerServices) -> Self {
         Self { services, config }
     }