Improve documentation of cardano modules and structures.

Author: iquerejeta

mithril-common/src/crypto_helper/cardano/codec.rs

@@ -1,3 +1,16 @@
+//! Module to provide functions to (de)serialise JSON data structures as used in Shelley,
+//! which have the following format:
+//! ```json
+//! {
+//!      "type": <NAME OF SERIALISED STRUCTURE>,
+//!      "description": <DESCRIPTION OF SERIALISED STRUCTURE>,
+//!      "cborHex": <CBOR HEX REPRESENTATION OF SERIALISED STRUCTURE>
+//!  }
+//! ```
+//!
+//! The trait `SerDeShelleyFileFormat` can be implemented for any structure that implements
+//! `Serialize` and `Deserialize`.
+
 use hex::FromHex;
 use kes_summed_ed25519::kes::Sum6Kes;
 use serde::de::DeserializeOwned;

mithril-common/src/crypto_helper/cardano/key_certification.rs

@@ -1,5 +1,7 @@
-//! API for mithril key certification. 
-//! Includes the wrappers for StmInitializer and KeyReg, and ProtocolRegistrationErrorWrapper. 
+//! API for mithril key certification.
+//! Includes the wrappers for StmInitializer and KeyReg, and ProtocolRegistrationErrorWrapper.
+//! These wrappers allows keeping mithril-core agnostic to Cardano, while providing some
+//! guarantees that mithril-core will not be misused in the context of Cardano.  
 
 use crate::crypto_helper::cardano::{OpCert, ParseError, SerDeShelleyFileFormat};
 use crate::crypto_helper::types::{
@@ -63,15 +65,21 @@ pub enum ProtocolRegistrationErrorWrapper {
     CoreRegister(#[from] RegisterError),
 }
 
-// Wrapper structures to reduce library misuse in the Cardano context
 /// Wrapper structure for [MithrilCore:StmInitializer](https://mithril.network/mithril-core/doc/mithril/stm/struct.StmInitializer.html).
+/// It now obtains a KES signature over the Mithril key. This allows the signers prove
+/// their correct identity with respect to a Cardano PoolID.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct StmInitializerWrapper {
     stm_initializer: StmInitializer,
     kes_signature: Option<ProtocolSignerVerificationKeySignature>, // todo: The option is ONLY for a smooth transition. We have to remove this.
 }
 
 /// Wrapper structure for [MithrilCore:KeyReg](https://mithril.network/mithril-core/doc/mithril/key_reg/struct.KeyReg.html).
+/// The wrapper not only contains a map between `Mithril vkey <-> Stake`, but also
+/// a map `PoolID <-> Stake`. This information is recovered from the node state, and
+/// is used to verify the identity of a Mithril signer. Furthermore, the `register` function
+/// of the wrapper forces the registrar to check that the KES signature over the Mithril key
+/// is valid with respect to the PoolID.
 #[derive(Debug, Clone)]
 pub struct KeyRegWrapper {
     stm_key_reg: KeyReg,

mithril-common/src/crypto_helper/cardano/opcert.rs

@@ -1,3 +1,5 @@
+//! Module to (de)serialise, OpCert using the same structure as used in Cardano.  
+
 use super::SerDeShelleyFileFormat;
 use crate::crypto_helper::cardano::ProtocolRegistrationErrorWrapper;
 use crate::crypto_helper::ProtocolPartyId;