Merge pull request #58 from lambdaclass/improve_mina_docs

Improve Mina verifier documentation

Author: gabrielbosio

operator/mina/lib/src/consensus_state.rs

@@ -13,12 +13,18 @@ const GRACE_PERIOD_END: u32 = 1440;
 const SUB_WINDOWS_PER_WINDOW: u32 = 11;
 const SLOTS_PER_SUB_WINDOW: u32 = 7;
 
+/// The result of the comparison of security between chains done in the `select_secure_chain`
+/// function.
 #[derive(Debug, PartialEq)]
 pub enum ChainResult {
     Bridge,
     Candidate,
 }
 
+/// Given two Mina chains, `candidate` and `tip`, returns an enum variant `ChainResult` that
+/// indicates which chain is more secure.
+/// Returns `ChainResult::Bridge` if `tip` is the most secure chain. `ChainResult::Candidate`
+/// otherwise.
 pub fn select_secure_chain(
     candidate: &MinaProtocolState,
     tip: &MinaProtocolState,

operator/mina/lib/src/lib.rs

@@ -75,6 +75,11 @@ fn inner_verify_mina_state_ffi(
     verify_mina_state(proof_bytes, pub_input_bytes)
 }
 
+/// Verifies that the Mina state included in `proof_bytes` is valid.
+/// This includes checking that:
+///
+/// - The Mina state corresponds to the tip of the most secure chain
+/// - The corresponding Pickles proof is valid
 pub fn verify_mina_state(proof_bytes: &[u8], pub_input_bytes: &[u8]) -> bool {
     let proof: MinaStateProof = match bincode::deserialize(proof_bytes) {
         Ok(proof) => proof,

operator/mina_account/lib/src/lib.rs

@@ -50,6 +50,14 @@ fn inner_verify_account_inclusion_ffi(
     verify_account_inclusion(proof_bytes, pub_input_bytes)
 }
 
+/// Verifies a Mina account inclusion.
+/// Verifies that exists a Merkle path composed of:
+///
+/// - The hash of the Mina account as the leaf
+/// - The ledger hash as the root
+/// - Some intermediate nodes
+///
+/// Returns `true` if the Mina account is included in the ledger hash. `false` otherwise.
 pub fn verify_account_inclusion(proof_bytes: &[u8], pub_input_bytes: &[u8]) -> bool {
     let MinaAccountProof {
         merkle_path,

operator/mina_account/lib/src/merkle_verifier.rs

@@ -4,6 +4,12 @@ use mina_curves::pasta::Fp;
 use mina_p2p_messages::v2::hash_with_kimchi;
 use std::fmt::Write;
 
+/// Verifies a Merkle Proof.
+/// This means that `merkle_leaf`, `merkle_path` and `merkle_root` conform one of the paths of a Merkle tree
+/// where `merkle_leaf` is the first node of the path, `merkle_root` is the last one and `merkle_path` is a
+/// vector of all the intermediate nodes.
+/// Returns `true` if the Merkle proof is valid. `false` otherwise.
+///
 /// Based on OpenMina's implementation
 /// https://github.com/openmina/openmina/blob/d790af59a8bd815893f7773f659351b79ed87648/ledger/src/account/account.rs#L1444
 pub fn verify_merkle_proof(merkle_leaf: Fp, merkle_path: Vec<MerkleNode>, merkle_root: Fp) -> bool {