feat: wire masternode engine methods to MasternodeListEngine

- Add `masternode_engine()` async accessor on `DashSpvClient` that
  returns `Option<Arc<RwLock<MasternodeListEngine>>>` (clone of field)
- Implement `SpvClient::get_masternode_count()`: reads the latest
  masternode list from the engine and returns the entry count; returns
  0 when masternodes are disabled or no list received yet
- Implement `SpvClient::get_masternodes()`: iterates the latest
  masternode list and maps `MasternodeListEntry` fields to `MasternodeInfo`
  (pro_reg_tx_hash → pro_tx_hash, service_address → address,
  is_valid → "Enabled"/"PoSeBanned"); pose_penalty/last_paid_height/
  registered_height default to 0 as they are not in the SML diff
- Replace stub bridge tests with no-engine and empty-engine variants
- Add DashSpvClient-level tests for masternode_engine() accessor and
  a populated-engine scenario using a manually constructed MasternodeList

Closes #29

Co-authored-by: Kevin Rombach <xdustinface@users.noreply.github.com>

Author: github-actions[bot]

dash-spv/src/bridge/mod.rs

@@ -610,20 +610,65 @@ pub struct GovernanceProposal {
 impl SpvClient {
     /// Returns the number of masternodes in the current masternode list.
     ///
-    /// TODO: wire up to `MasternodeListEngine` once the engine is accessible
-    /// from `DashSpvClient`.
+    /// Reads the latest masternode list from the engine and returns its entry
+    /// count.  Returns `0` when masternodes are disabled or no list has been
+    /// received yet.
     pub async fn get_masternode_count(&self) -> u32 {
-        // TODO: return self.inner.masternode_list_engine()?.read().await.count()
-        0
+        let Some(engine) = self.inner.masternode_engine().await else {
+            return 0;
+        };
+        let guard = engine.read().await;
+        guard
+            .latest_masternode_list()
+            .map(|list| list.masternodes.len() as u32)
+            .unwrap_or(0)
     }
 
     /// Returns all masternodes from the current masternode list.
     ///
-    /// TODO: wire up to `MasternodeListEngine` once the engine is accessible
-    /// from `DashSpvClient`.
+    /// Iterates the latest masternode list from the engine and maps each
+    /// [`dashcore::sml::masternode_list_entry::MasternodeListEntry`] to a
+    /// [`MasternodeInfo`] record.  Returns an empty `Vec` when masternodes are
+    /// disabled or no list has been received yet.
+    ///
+    /// # Field mapping
+    ///
+    /// | `MasternodeListEntry` field | `MasternodeInfo` field |
+    /// |---|---|
+    /// | `pro_reg_tx_hash` | `pro_tx_hash` |
+    /// | `service_address` | `address` |
+    /// | `is_valid` | `status` (`"Enabled"` / `"PoSeBanned"`) |
+    /// | — | `pose_penalty` (always `0`; not in SML diff) |
+    /// | — | `last_paid_height` (always `0`; not in SML diff) |
+    /// | — | `registered_height` (always `0`; not in SML diff) |
     pub async fn get_masternodes(&self) -> Vec<MasternodeInfo> {
-        // TODO: map MasternodeListEntry fields to MasternodeInfo
-        vec![]
+        let Some(engine) = self.inner.masternode_engine().await else {
+            return vec![];
+        };
+        let guard = engine.read().await;
+        let Some(list) = guard.latest_masternode_list() else {
+            return vec![];
+        };
+        list.masternodes
+            .values()
+            .map(|entry| {
+                let mn = &entry.masternode_list_entry;
+                MasternodeInfo {
+                    pro_tx_hash: mn.pro_reg_tx_hash.to_string(),
+                    address: mn.service_address.to_string(),
+                    status: if mn.is_valid {
+                        "Enabled".to_string()
+                    } else {
+                        "PoSeBanned".to_string()
+                    },
+                    // The SML diff does not carry PoSe penalty, last-paid height, or
+                    // registered height — default to 0 until richer data sources are wired up.
+                    pose_penalty: 0,
+                    last_paid_height: 0,
+                    registered_height: 0,
+                }
+            })
+            .collect()
     }
 }
 
@@ -1237,28 +1282,68 @@ mod tests {
         assert_eq!(proposal.abstain_count, 1);
     }
 
+    /// `get_masternode_count` returns 0 when masternodes are disabled (no engine).
     #[tokio::test]
-    async fn test_get_masternode_count_stub() {
+    async fn test_get_masternode_count_no_engine() {
         let temp_dir = TempDir::new().expect("Failed to create temp dir");
         let config = ClientConfig::regtest()
             .without_filters()
             .without_masternodes()
             .with_storage_path(temp_dir.path());
 
         let client = SpvClient::new(config).await.expect("SpvClient construction must succeed");
-        assert_eq!(client.get_masternode_count().await, 0, "stub should return 0");
+        assert_eq!(
+            client.get_masternode_count().await,
+            0,
+            "should return 0 when engine is None"
+        );
     }
 
+    /// `get_masternodes` returns an empty vec when masternodes are disabled (no engine).
     #[tokio::test]
-    async fn test_get_masternodes_stub() {
+    async fn test_get_masternodes_no_engine() {
         let temp_dir = TempDir::new().expect("Failed to create temp dir");
         let config = ClientConfig::regtest()
             .without_filters()
             .without_masternodes()
             .with_storage_path(temp_dir.path());
 
         let client = SpvClient::new(config).await.expect("SpvClient construction must succeed");
-        let masternodes = client.get_masternodes().await;
-        assert!(masternodes.is_empty(), "stub should return empty vec");
+        assert!(
+            client.get_masternodes().await.is_empty(),
+            "should return empty vec when engine is None"
+        );
+    }
+
+    /// `get_masternode_count` returns 0 when masternodes are enabled but no list
+    /// has been received yet (engine is Some but empty).
+    #[tokio::test]
+    async fn test_get_masternode_count_empty_engine() {
+        let temp_dir = TempDir::new().expect("Failed to create temp dir");
+        // Default regtest config has enable_masternodes = true
+        let config =
+            ClientConfig::regtest().without_filters().with_storage_path(temp_dir.path());
+
+        let client = SpvClient::new(config).await.expect("SpvClient construction must succeed");
+        assert_eq!(
+            client.get_masternode_count().await,
+            0,
+            "should return 0 when engine has no list yet"
+        );
+    }
+
+    /// `get_masternodes` returns an empty vec when masternodes are enabled but no
+    /// list has been received yet (engine is Some but empty).
+    #[tokio::test]
+    async fn test_get_masternodes_empty_engine() {
+        let temp_dir = TempDir::new().expect("Failed to create temp dir");
+        let config =
+            ClientConfig::regtest().without_filters().with_storage_path(temp_dir.path());
+
+        let client = SpvClient::new(config).await.expect("SpvClient construction must succeed");
+        assert!(
+            client.get_masternodes().await.is_empty(),
+            "should return empty vec when engine has no list yet"
+        );
     }
 }

dash-spv/src/client/mod.rs

@@ -49,9 +49,19 @@ mod tests {
     use crate::client::config::MempoolStrategy;
     use crate::storage::DiskStorageManager;
     use crate::{test_utils::MockNetworkManager, types::UnconfirmedTransaction};
-    use dashcore::{Address, Amount, Transaction, TxOut};
+    use dashcore::sml::masternode_list::MasternodeList;
+    use dashcore::sml::masternode_list_entry::{
+        EntryMasternodeType, MasternodeListEntry,
+        qualified_masternode_list_entry::QualifiedMasternodeListEntry,
+    };
+    use dashcore::sml::masternode_list_engine::MasternodeListEngine;
+    use dashcore::{Address, Amount, BlockHash, ProTxHash, Transaction, TxOut};
+    use dashcore_hashes::Hash;
     use key_wallet::wallet::managed_wallet_info::ManagedWalletInfo;
     use key_wallet_manager::wallet_manager::WalletManager;
+    use std::collections::BTreeMap;
+    use std::net::SocketAddr;
+    use std::str::FromStr;
     use std::sync::Arc;
     use tempfile::TempDir;
     use tokio::sync::RwLock;
@@ -170,4 +180,112 @@ mod tests {
             "InstantSend balance should be 10 Dash"
         );
     }
+
+    // ============ masternode_engine() accessor tests ============
+
+    /// `masternode_engine()` returns `None` when masternodes are disabled.
+    #[tokio::test]
+    async fn test_masternode_engine_none_when_disabled() {
+        let config = ClientConfig::testnet()
+            .without_filters()
+            .without_masternodes()
+            .with_storage_path(TempDir::new().unwrap().path());
+
+        let network_manager = MockNetworkManager::new();
+        let storage = DiskStorageManager::new(&config).await.expect("storage");
+        let wallet = Arc::new(RwLock::new(WalletManager::<ManagedWalletInfo>::new(config.network)));
+
+        let client = DashSpvClient::new(config, network_manager, storage, wallet)
+            .await
+            .expect("client construction must succeed");
+
+        assert!(
+            client.masternode_engine().await.is_none(),
+            "masternode_engine() should be None when masternodes are disabled"
+        );
+    }
+
+    /// `masternode_engine()` returns `Some` when masternodes are enabled.
+    #[tokio::test]
+    async fn test_masternode_engine_some_when_enabled() {
+        let config = ClientConfig::testnet()
+            .without_filters()
+            .with_storage_path(TempDir::new().unwrap().path());
+
+        let network_manager = MockNetworkManager::new();
+        let storage = DiskStorageManager::new(&config).await.expect("storage");
+        let wallet = Arc::new(RwLock::new(WalletManager::<ManagedWalletInfo>::new(config.network)));
+
+        let client = DashSpvClient::new(config, network_manager, storage, wallet)
+            .await
+            .expect("client construction must succeed");
+
+        assert!(
+            client.masternode_engine().await.is_some(),
+            "masternode_engine() should be Some when masternodes are enabled"
+        );
+    }
+
+    /// Verifies that after manually inserting a masternode list into the engine
+    /// the count and entries are visible via the engine handle.
+    #[tokio::test]
+    async fn test_masternode_engine_populated_reflects_entries() {
+        let config = ClientConfig::testnet()
+            .without_filters()
+            .with_storage_path(TempDir::new().unwrap().path());
+        let network = config.network;
+
+        let network_manager = MockNetworkManager::new();
+        let storage = DiskStorageManager::new(&config).await.expect("storage");
+        let wallet = Arc::new(RwLock::new(WalletManager::<ManagedWalletInfo>::new(network)));
+
+        let client = DashSpvClient::new(config, network_manager, storage, wallet)
+            .await
+            .expect("client construction must succeed");
+
+        let engine_arc = client
+            .masternode_engine()
+            .await
+            .expect("engine should be Some");
+
+        // Build a minimal MasternodeListEntry for testing.
+        let pro_reg_tx_hash = ProTxHash::all_zeros();
+        let entry = MasternodeListEntry {
+            version: 1,
+            pro_reg_tx_hash,
+            confirmed_hash: None,
+            service_address: SocketAddr::from_str("1.2.3.4:9999").unwrap(),
+            operator_public_key: dashcore::bls_sig_utils::BLSPublicKey::from([0u8; 48]),
+            key_id_voting: dashcore::PubkeyHash::all_zeros(),
+            is_valid: true,
+            mn_type: EntryMasternodeType::Regular,
+        };
+        let qualified: QualifiedMasternodeListEntry = entry.into();
+
+        // Insert the entry into a MasternodeList and load it into the engine.
+        let block_hash = BlockHash::all_zeros();
+        let masternodes = BTreeMap::from([(pro_reg_tx_hash, qualified)]);
+        let list = MasternodeList::build(masternodes, BTreeMap::new(), block_hash, 100).build();
+
+        {
+            let mut engine = engine_arc.write().await;
+            engine.masternode_lists.insert(100, list);
+        }
+
+        // Now read back via the accessor.
+        let engine_arc2 = client
+            .masternode_engine()
+            .await
+            .expect("engine should still be Some");
+        let engine = engine_arc2.read().await;
+        let latest = engine.latest_masternode_list().expect("list should be present");
+
+        assert_eq!(latest.masternodes.len(), 1, "should have 1 masternode");
+        let mn = latest.masternodes.values().next().unwrap();
+        assert!(mn.masternode_list_entry.is_valid, "masternode should be valid (Enabled)");
+        assert_eq!(
+            mn.masternode_list_entry.service_address.to_string(),
+            "1.2.3.4:9999"
+        );
+    }
 }

dash-spv/src/client/queries.rs

@@ -52,6 +52,11 @@ impl<W: WalletInterface, N: NetworkManager, S: StorageManager> DashSpvClient<W,
         }
     }
 
+    /// Returns a clone of the masternode engine handle, or `None` if masternodes are disabled.
+    pub async fn masternode_engine(&self) -> Option<Arc<RwLock<MasternodeListEngine>>> {
+        self.masternode_engine.clone()
+    }
+
     /// Get a quorum entry by type and hash at a specific block height.
     /// Returns `SpvError::QuorumLookupError` if the quorum is not found.
     pub async fn get_quorum_at_height(