documentation comments

Author: QuantumExplorer

dash/src/sml/llmq_type/rotation.rs

@@ -13,7 +13,6 @@ pub enum LLMQQuarterReconstructionType<'a: 'b, 'b> {
     Snapshot,
     New {
         previous_quarters: [&'b Vec<Vec<&'a QualifiedMasternodeListEntry>>; 3],
-        skip_removed_masternodes: bool,
     }
 }
 

dash/src/sml/masternode_list/apply_diff.rs

@@ -1,11 +1,33 @@
 use crate::network::message_sml::MnListDiff;
 use crate::prelude::CoreBlockHeight;
 use crate::sml::error::SmlError;
-use crate::sml::llmq_entry_verification::{LLMQEntryVerificationSkipStatus, LLMQEntryVerificationStatus};
 use crate::sml::masternode_list::MasternodeList;
-use crate::sml::quorum_entry::qualified_quorum_entry::QualifiedQuorumEntry;
 
 impl MasternodeList {
+    /// Applies an `MnListDiff` to update the current masternode list.
+    ///
+    /// This function processes a masternode list diff (`MnListDiff`) and applies
+    /// the changes to the existing masternode list. It performs the following operations:
+    /// - Ensures the base block hash matches the expected value.
+    /// - Removes deleted masternodes from the list.
+    /// - Adds or updates new masternodes.
+    /// - Removes deleted quorums.
+    /// - Adds or updates new quorums.
+    ///
+    /// # Parameters
+    ///
+    /// - `diff`: The `MnListDiff` containing the changes to apply.
+    /// - `diff_end_height`: The block height at which the diff ends.
+    ///
+    /// # Returns
+    ///
+    /// - `Ok(MasternodeList)`: A new `MasternodeList` reflecting the applied changes.
+    /// - `Err(SmlError)`: An error if the base block hash does not match the expected value.
+    ///
+    /// # Errors
+    ///
+    /// - Returns `SmlError::BaseBlockHashMismatch` if the `base_block_hash` of the `diff`
+    ///   does not match the expected block hash of the current masternode list.
     pub fn apply_diff(
         &self,
         diff: MnListDiff,

dash/src/sml/masternode_list/is_lock_methods.rs

@@ -5,6 +5,19 @@ use crate::sml::masternode_list::MasternodeList;
 use crate::sml::quorum_entry::qualified_quorum_entry::QualifiedQuorumEntry;
 
 impl MasternodeList {
+    /// Retrieves a list of qualified quorum entries ordered for InstantSend locks.
+    ///
+    /// This function fetches all quorums for the given `quorum_type`, computes an ordering
+    /// hash based on the provided `request_id`, and sorts them in descending order.
+    ///
+    /// # Parameters
+    ///
+    /// - `quorum_type`: The type of quorum to retrieve.
+    /// - `request_id`: A 32-byte identifier used to order the quorums.
+    ///
+    /// # Returns
+    ///
+    /// - A vector of `QualifiedQuorumEntry` instances ordered based on the computed hash.
     pub fn ordered_quorums_for_is_lock(&self, quorum_type: LLMQType, request_id: [u8; 32]) -> Vec<QualifiedQuorumEntry> {
         use std::cmp::Ordering;
         let quorums_for_is = self.quorums
@@ -30,6 +43,20 @@ impl MasternodeList {
         ordered_quorums.into_iter().map(|(entry, _)| entry).collect()
     }
 
+    /// Retrieves the first valid quorum entry for a given InstantSend lock request.
+    ///
+    /// This function finds the most suitable quorum entry for a given `request_id` and `llmq_type`
+    /// by selecting the quorum with the lowest computed ordering hash.
+    ///
+    /// # Parameters
+    ///
+    /// - `request_id`: A 32-byte identifier used to determine the quorum ordering.
+    /// - `llmq_type`: The type of quorum to retrieve.
+    ///
+    /// # Returns
+    ///
+    /// - `Some(QualifiedQuorumEntry)`: The most suitable quorum entry.
+    /// - `None`: If no quorum is found.
     pub fn lock_llmq_request_id(
         &self,
         request_id: [u8; 32],
@@ -39,6 +66,21 @@ impl MasternodeList {
             .cloned()
     }
 
+    /// Retrieves a reference to the best matching quorum entry for a given InstantSend lock request.
+    ///
+    /// This function iterates through all available quorums of the given `llmq_type`, calculates
+    /// an ordering hash for each quorum based on the `request_id`, and returns a reference to the
+    /// quorum with the lowest ordering hash value.
+    ///
+    /// # Parameters
+    ///
+    /// - `request_id`: A 32-byte identifier used for quorum selection.
+    /// - `llmq_type`: The type of quorum to search for.
+    ///
+    /// # Returns
+    ///
+    /// - `Some(&QualifiedQuorumEntry)`: A reference to the best-matching quorum entry.
+    /// - `None`: If no quorum matches the criteria.
     pub fn quorum_entry_for_lock_request_id(
         &self,
         request_id: [u8; 32],
@@ -57,5 +99,4 @@ impl MasternodeList {
         });
         first_quorum
     }
-
 }

dash/src/sml/masternode_list/merkle_roots.rs

@@ -4,6 +4,20 @@ use crate::sml::masternode_list::MasternodeList;
 use crate::Transaction;
 use crate::transaction::special_transaction::TransactionPayload;
 
+/// Computes the Merkle root from a list of hashes.
+///
+/// This function constructs a Merkle tree from the provided vector of 32-byte hashes.
+/// If the vector is empty, it returns `None`. Otherwise, it iteratively hashes pairs
+/// of nodes until a single root hash is obtained.
+///
+/// # Parameters
+///
+/// - `hashes`: A vector of 32-byte hashes representing the leaves of the Merkle tree.
+///
+/// # Returns
+///
+/// - `Some([u8; 32])`: The computed Merkle root if at least one hash is provided.
+/// - `None`: If the input vector is empty.
 #[inline]
 pub fn merkle_root_from_hashes(hashes: Vec<[u8; 32]>) -> Option<[u8; 32]> {
     let length = hashes.len();
@@ -28,6 +42,19 @@ pub fn merkle_root_from_hashes(hashes: Vec<[u8; 32]>) -> Option<[u8; 32]> {
 }
 
 impl MasternodeList {
+    /// Validates whether the stored masternode list Merkle root matches the one in the coinbase transaction.
+    ///
+    /// This function compares the calculated masternode Merkle root with the one provided
+    /// in the coinbase transaction payload to verify the integrity of the masternode list.
+    ///
+    /// # Parameters
+    ///
+    /// - `coinbase_transaction`: The coinbase transaction containing the expected Merkle root.
+    ///
+    /// # Returns
+    ///
+    /// - `true` if the Merkle root matches.
+    /// - `false` otherwise.
     pub fn has_valid_mn_list_root(&self, coinbase_transaction: &Transaction) -> bool {
         let Some(TransactionPayload::CoinbasePayloadType(coinbase_payload)) = &coinbase_transaction.special_transaction_payload else {
             return false;
@@ -42,6 +69,19 @@ impl MasternodeList {
         }
     }
 
+    /// Validates whether the stored LLMQ list Merkle root matches the one in the coinbase transaction.
+    ///
+    /// This function compares the calculated quorum Merkle root with the one provided
+    /// in the coinbase transaction payload to verify the integrity of the quorum list.
+    ///
+    /// # Parameters
+    ///
+    /// - `coinbase_transaction`: The coinbase transaction containing the expected Merkle root.
+    ///
+    /// # Returns
+    ///
+    /// - `true` if the Merkle root matches.
+    /// - `false` otherwise.
     pub fn has_valid_llmq_list_root(&self, coinbase_transaction: &Transaction) -> bool {
         let Some(TransactionPayload::CoinbasePayloadType(coinbase_payload)) = &coinbase_transaction.special_transaction_payload else {
             return false;
@@ -61,23 +101,50 @@ impl MasternodeList {
         has_valid_quorum_list_root
     }
 
+    /// Computes the Merkle root for the masternode list at a given block height.
+    ///
+    /// This function generates a Merkle root for the masternode list based on the
+    /// masternode entries at the specified block height.
+    ///
+    /// # Parameters
+    ///
+    /// - `block_height`: The block height at which to compute the Merkle root.
+    ///
+    /// # Returns
+    ///
+    /// - `Some(MerkleRootMasternodeList)`: The calculated Merkle root.
+    /// - `None`: If no hashes are available for the given block height.
     pub fn calculate_masternodes_merkle_root(&self, block_height: u32) -> Option<MerkleRootMasternodeList> {
         self.hashes_for_merkle_root(block_height)
             .and_then(merkle_root_from_hashes).map(|hash| MerkleRootMasternodeList::from_byte_array(hash))
     }
-    // pub fn calculate_masternodes_merkle_root_with_block_height_lookup<BL: Fn(*const std::os::raw::c_void, [u8; 32]) -> u32>(
-    //     &self,
-    //     context: *const std::os::raw::c_void,
-    //     block_height_lookup: BL
-    // ) -> Option<[u8; 32]> {
-    //     self.hashes_for_merkle_root_with_block_height_lookup(context, block_height_lookup)
-    //         .and_then(merkle_root_from_hashes)
-    // }
 
+    /// Computes the Merkle root for the LLMQ (Long-Living Masternode Quorum) list.
+    ///
+    /// This function constructs a Merkle tree using the commitment hashes of all known LLMQs
+    /// and returns the root hash.
+    ///
+    /// # Returns
+    ///
+    /// - `Some(MerkleRootQuorums)`: The calculated Merkle root.
+    /// - `None`: If no quorum commitment hashes are available.
     pub fn calculate_llmq_merkle_root(&self) -> Option<MerkleRootQuorums> {
         merkle_root_from_hashes(self.hashes_for_quorum_merkle_root()).map(|hash| MerkleRootQuorums::from_byte_array(hash))
     }
 
+    /// Retrieves the list of hashes required to compute the masternode list Merkle root.
+    ///
+    /// This function sorts the masternode list by pro-reg transaction hash and extracts
+    /// the entry hashes for the given block height.
+    ///
+    /// # Parameters
+    ///
+    /// - `block_height`: The block height for which to retrieve the hashes.
+    ///
+    /// # Returns
+    ///
+    /// - `Some(Vec<[u8; 32]>)`: A sorted list of masternode entry hashes.
+    /// - `None`: If the block height is invalid (`u32::MAX`).
     pub fn hashes_for_merkle_root(&self, block_height: u32) -> Option<Vec<[u8; 32]>> {
         (block_height != u32::MAX).then_some({
             let mut pro_tx_hashes = self.reversed_pro_reg_tx_hashes();
@@ -94,23 +161,14 @@ impl MasternodeList {
         })
     }
 
-    // pub fn hashes_for_merkle_root_with_block_height_lookup<BL: Fn(*const std::os::raw::c_void, [u8; 32]) -> u32>(
-    //     &self,
-    //     context: *const std::os::raw::c_void,
-    //     block_height_lookup: BL
-    // ) -> Option<Vec<[u8; 32]>> {
-    //     let pro_tx_hashes = self.provider_tx_ordered_hashes();
-    //     let block_height = block_height_lookup(context, self.block_hash);
-    //     if block_height == u32::MAX {
-    //         println!("Block height lookup queried an unknown block {}", self.block_hash);
-    //         return None; //this should never happen
-    //     }
-    //     Some(pro_tx_hashes
-    //         .into_iter()
-    //         .map(|hash| (&self.masternodes[&hash]).entry_hash_at(block_height))
-    //         .collect::<Vec<_>>())
-    // }
-
+    /// Retrieves the list of hashes required to compute the quorum Merkle root.
+    ///
+    /// This function collects and sorts the entry hashes of all known quorums
+    /// to construct a Merkle tree.
+    ///
+    /// # Returns
+    ///
+    /// - `Vec<[u8; 32]>`: A sorted list of quorum commitment hashes.
     pub fn hashes_for_quorum_merkle_root(&self) -> Vec<[u8; 32]> {
         let mut llmq_commitment_hashes = self.quorums
             .values()

dash/src/sml/masternode_list/mod.rs

@@ -8,8 +8,6 @@ mod peer_addresses;
 pub mod from_diff;
 mod apply_diff;
 mod scores_for_quorum;
-mod rotation;
-mod valid_members_in_rotated_quorum;
 
 use std::collections::BTreeMap;
 #[cfg(feature = "bincode")]

dash/src/sml/masternode_list/peer_addresses.rs

@@ -6,6 +6,26 @@ use crate::sml::masternode_list::MasternodeList;
 
 impl MasternodeList {
 
+    /// Retrieves a list of peer addresses from the masternode list, sorted using a nonce for deterministic ordering.
+    ///
+    /// This function generates a sorted list of masternode addresses based on their registration transaction hashes,
+    /// using a provided nonce to create a deterministic but unpredictable order. The resulting list is truncated
+    /// to the specified maximum count.
+    ///
+    /// # Parameters
+    ///
+    /// - `nonce`: A 64-bit unsigned integer used to influence the sorting order.
+    /// - `max_count`: The maximum number of peer addresses to return.
+    ///
+    /// # Returns
+    ///
+    /// - `Vec<SocketAddr>`: A list of masternode service addresses, sorted using the nonce and limited to `max_count`.
+    ///
+    /// # Notes
+    ///
+    /// - The sorting process appends the nonce to each masternode’s transaction hash and applies a BLAKE3 hash
+    ///   to determine the order.
+    /// - Only valid masternodes (i.e., those marked as valid in the masternode list) are included in the output.
     pub fn peer_addresses_with_connectivity_nonce(&self, nonce: u64, max_count: usize) -> Vec<SocketAddr> {
         let registration_transaction_hashes: Vec<_> = self.masternodes.keys().cloned().collect();
         let mut sorted_hashes = registration_transaction_hashes.clone();