Document Mina verifier

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,