feat(node,rpc): wire CoinStatsListener into UtxoSet; gettxoutsetinfo surfaces muhash + total_amount + bogosize

Op: extend

Author: metaphorics

crates/node/src/apply.rs

@@ -35,6 +35,8 @@ pub struct ApplyHandles {
     pub block_tree: Arc<RwLock<BlockTree>>,
     /// Shared UTXO set.
     pub utxo: Arc<UtxoSet>,
+    /// Shared coinstats listener.
+    pub coin_stats: Arc<bitcoin_rs_coinstats::CoinStatsListener>,
     /// Shared mempool.
     pub mempool: Arc<RwLock<Mempool>>,
     /// Shared block records exposed to RPC handlers.
@@ -143,6 +145,8 @@ pub fn apply_block(
         tracing::debug!(%txid, evicted_count, "apply_block: evicted transaction from mempool");
         handles.transactions.write().insert(txid, tx.clone());
     }
+    let tx_count_delta = u64::try_from(block.txdata.len()).unwrap_or(u64::MAX);
+    handles.coin_stats.finish_block(height, tx_count_delta);
     tracing::info!(
         height,
         %block_hash,

crates/node/src/run.rs

@@ -147,6 +147,7 @@ pub fn run(mut config: Config) -> Result<()> {
         state.blocks(),
         state.transactions(),
         state.utxo(),
+        state.coin_stats(),
         state.network(),
         state.mining_template_id(),
         state.peers(),

crates/node/src/state.rs

@@ -171,6 +171,7 @@ pub struct NodeState {
     data_dir: PathBuf,
     storage: NodeStorage,
     utxo: Arc<UtxoSet>,
+    coin_stats: Arc<bitcoin_rs_coinstats::CoinStatsListener>,
     mempool: Arc<RwLock<Mempool>>,
     chain_tip: Arc<ArcSwapOption<TipSnapshot>>,
     applied_tip: Arc<ArcSwapOption<TipSnapshot>>,
@@ -202,7 +203,13 @@ impl NodeState {
         std::fs::create_dir_all(&config.data_dir)
             .with_context(|| format!("create data_dir {}", config.data_dir.display()))?;
         let storage = NodeStorage::open(&config)?;
-        let utxo = Arc::new(UtxoSet::new());
+        let mut utxo_set = bitcoin_rs_utxo::UtxoSet::new();
+        let coin_stats_listener = bitcoin_rs_coinstats::CoinStatsListener::new(
+            bitcoin_rs_coinstats::CoinStats::default(),
+        );
+        utxo_set.set_listener(Box::new(coin_stats_listener.clone()));
+        let utxo = Arc::new(utxo_set);
+        let coin_stats = Arc::new(coin_stats_listener);
         let mempool = Arc::new(RwLock::new(Mempool::new(MempoolLimits::default())));
         let block_tree = Arc::new(RwLock::new(bitcoin_rs_chain::BlockTree::new()));
         let chain_tip = block_tree.read().tip_handle();
@@ -226,6 +233,7 @@ impl NodeState {
                 applied_tip: Arc::clone(&applied_tip),
                 block_tree: Arc::clone(&block_tree),
                 utxo: Arc::clone(&utxo),
+                coin_stats: Arc::clone(&coin_stats),
                 mempool: Arc::clone(&mempool),
                 blocks: Arc::clone(&blocks),
                 transactions: Arc::clone(&transactions),
@@ -246,6 +254,7 @@ impl NodeState {
             data_dir,
             storage,
             utxo,
+            coin_stats,
             mempool,
             chain_tip,
             applied_tip,
@@ -289,6 +298,12 @@ impl NodeState {
         Arc::clone(&self.utxo)
     }
 
+    /// Returns the shared coinstats listener handle.
+    #[must_use]
+    pub fn coin_stats(&self) -> Arc<bitcoin_rs_coinstats::CoinStatsListener> {
+        Arc::clone(&self.coin_stats)
+    }
+
     /// Returns the shared mempool handle.
     #[must_use]
     pub fn mempool(&self) -> Arc<RwLock<Mempool>> {
@@ -435,6 +450,7 @@ impl NodeState {
             applied_tip: Arc::clone(&self.applied_tip),
             block_tree: Arc::clone(&self.block_tree),
             utxo: Arc::clone(&self.utxo),
+            coin_stats: Arc::clone(&self.coin_stats),
             mempool: Arc::clone(&self.mempool),
             blocks: Arc::clone(&self.blocks),
             transactions: Arc::clone(&self.transactions),
@@ -507,6 +523,21 @@ mod tests {
         Ok(())
     }
 
+    #[test]
+    fn open_constructs_coin_stats_listener() -> anyhow::Result<()> {
+        let dir = tempfile::tempdir()?;
+        let mut config = crate::Config::default_for_network(crate::Network::Regtest);
+        config.data_dir = dir.path().join("node");
+        config.p2p_listen.clear();
+        let state = NodeState::open(config)?;
+        let snapshot = state.coin_stats().snapshot();
+        assert_eq!(
+            snapshot.tx_count, 0,
+            "freshly opened coin_stats has zero txs"
+        );
+        Ok(())
+    }
+
     #[test]
     fn open_constructs_block_sync_orchestrator() -> anyhow::Result<()> {
         let dir = tempfile::tempdir()?;

crates/node/src/sync.rs

@@ -477,6 +477,9 @@ mod tests {
             applied_tip,
             block_tree,
             utxo: Arc::new(UtxoSet::new()),
+            coin_stats: Arc::new(bitcoin_rs_coinstats::CoinStatsListener::new(
+                bitcoin_rs_coinstats::CoinStats::default(),
+            )),
             mempool: Arc::new(RwLock::new(Mempool::new(MempoolLimits::default()))),
             blocks: Arc::new(RwLock::new(Vec::new())),
             transactions: Arc::new(RwLock::new(HashMap::<Txid, Transaction>::new())),

crates/node/tests/rpc_wiring.rs

@@ -28,6 +28,7 @@ fn rpc_context_shares_arc_identity_with_node_state() -> Result<()> {
     let blocks = state.blocks();
     let transactions = state.transactions();
     let utxo = Arc::new(UtxoSet::new());
+    let coin_stats = state.coin_stats();
     let network = state.network();
     let mining_template_id = state.mining_template_id();
     let peers = state.peers();
@@ -39,6 +40,7 @@ fn rpc_context_shares_arc_identity_with_node_state() -> Result<()> {
         Arc::clone(&blocks),
         Arc::clone(&transactions),
         Arc::clone(&utxo),
+        Arc::clone(&coin_stats),
         Arc::clone(&network),
         Arc::clone(&mining_template_id),
         Arc::clone(&peers),
@@ -65,6 +67,10 @@ fn rpc_context_shares_arc_identity_with_node_state() -> Result<()> {
         "transactions must share identity"
     );
     assert!(Arc::ptr_eq(&ctx.utxo, &utxo), "utxo must share identity");
+    assert!(
+        Arc::ptr_eq(&ctx.coin_stats, &coin_stats),
+        "coin_stats must share identity"
+    );
     assert!(
         Arc::ptr_eq(&ctx.network, &network),
         "network must share identity"

crates/node/tests/sync_smoke.rs

@@ -157,6 +157,9 @@ fn apply_handles(
         applied_tip,
         block_tree,
         utxo: Arc::new(UtxoSet::new()),
+        coin_stats: Arc::new(bitcoin_rs_coinstats::CoinStatsListener::new(
+            bitcoin_rs_coinstats::CoinStats::default(),
+        )),
         mempool: Arc::new(RwLock::new(Mempool::new(MempoolLimits::default()))),
         blocks: Arc::new(RwLock::new(Vec::new())),
         transactions: Arc::new(RwLock::new(HashMap::<Txid, Transaction>::new())),

crates/rpc/Cargo.toml

@@ -13,9 +13,9 @@ workspace = true
 
 [features]
 default = []
-rocksdb = ["bitcoin-rs-storage/rocksdb", "bitcoin-rs-p2p/rocksdb"]
-fjall = ["bitcoin-rs-storage/fjall", "bitcoin-rs-p2p/fjall"]
-redb = ["bitcoin-rs-storage/redb", "bitcoin-rs-p2p/redb"]
+rocksdb = ["bitcoin-rs-coinstats/rocksdb", "bitcoin-rs-storage/rocksdb", "bitcoin-rs-p2p/rocksdb"]
+fjall = ["bitcoin-rs-coinstats/fjall", "bitcoin-rs-storage/fjall", "bitcoin-rs-p2p/fjall"]
+redb = ["bitcoin-rs-coinstats/redb", "bitcoin-rs-storage/redb", "bitcoin-rs-p2p/redb"]
 mdbx = ["bitcoin-rs-storage/mdbx"]
 
 [dependencies]

crates/rpc/src/context.rs

@@ -86,6 +86,8 @@ pub struct Context {
     pub transactions: Arc<RwLock<HashMap<Txid, Transaction>>>,
     /// UTXO set snapshot handle used by chain metadata RPCs.
     pub utxo: Arc<bitcoin_rs_utxo::UtxoSet>,
+    /// Incremental UTXO-set statistics.
+    pub coin_stats: Arc<bitcoin_rs_coinstats::CoinStatsListener>,
     /// Network counters and peers.
     pub network: Arc<RwLock<NetworkState>>,
     /// Shared registry of currently-handshook peers.
@@ -132,6 +134,9 @@ impl Context {
             blocks: Arc::new(RwLock::new(Vec::new())),
             transactions: Arc::new(RwLock::new(HashMap::new())),
             utxo: Arc::new(bitcoin_rs_utxo::UtxoSet::new()),
+            coin_stats: Arc::new(bitcoin_rs_coinstats::CoinStatsListener::new(
+                bitcoin_rs_coinstats::CoinStats::default(),
+            )),
             network: Arc::new(RwLock::new(NetworkState::default())),
             peers: Arc::new(RwLock::new(Vec::new())),
             mining_template_id: Arc::new(ArcSwap::from_pointee(CompactString::new("0"))),
@@ -154,6 +159,7 @@ impl Context {
         blocks: Arc<RwLock<Vec<BlockRecord>>>,
         transactions: Arc<RwLock<HashMap<Txid, Transaction>>>,
         utxo: Arc<bitcoin_rs_utxo::UtxoSet>,
+        coin_stats: Arc<bitcoin_rs_coinstats::CoinStatsListener>,
         network: Arc<RwLock<NetworkState>>,
         mining_template_id: Arc<ArcSwap<CompactString>>,
         peers: Arc<RwLock<Vec<bitcoin_rs_p2p::PeerInfo>>>,
@@ -166,6 +172,7 @@ impl Context {
             blocks,
             transactions,
             utxo,
+            coin_stats,
             network,
             peers,
             mining_template_id,
@@ -288,13 +295,17 @@ mod tests {
         let chain_tip = Arc::new(ArcSwapOption::empty());
         let applied_tip = Arc::new(ArcSwapOption::empty());
         let utxo = Arc::new(bitcoin_rs_utxo::UtxoSet::new());
+        let coin_stats = Arc::new(bitcoin_rs_coinstats::CoinStatsListener::new(
+            bitcoin_rs_coinstats::CoinStats::default(),
+        ));
         let ctx = Context::from_handles(
             Arc::clone(&chain_tip),
             Arc::clone(&applied_tip),
             Arc::new(RwLock::new(Mempool::new(MempoolLimits::default()))),
             Arc::new(RwLock::new(Vec::new())),
             Arc::new(RwLock::new(HashMap::new())),
             Arc::clone(&utxo),
+            Arc::clone(&coin_stats),
             Arc::new(RwLock::new(NetworkState::default())),
             Arc::new(ArcSwap::from_pointee(CompactString::new("0"))),
             Arc::new(RwLock::new(Vec::new())),
@@ -311,5 +322,9 @@ mod tests {
             Arc::ptr_eq(&ctx.utxo, &utxo),
             "utxo must be shared with caller"
         );
+        assert!(
+            Arc::ptr_eq(&ctx.coin_stats, &coin_stats),
+            "coin_stats must be shared with caller"
+        );
     }
 }

crates/rpc/src/handlers/chain.rs

@@ -160,13 +160,22 @@ pub(crate) fn getblockstats(ctx: &Arc<Context>, params: &Value) -> Result<Value,
 
 pub(crate) fn gettxoutsetinfo(ctx: &Arc<Context>, params: &Value) -> Result<Value, RpcError> {
     ensure_no_params(params)?;
+    let snapshot = ctx.coin_stats.snapshot();
+    let muhash_bytes = snapshot.muhash.finalize();
+    let mut muhash_hex = String::with_capacity(muhash_bytes.len() * 2);
+    for byte in muhash_bytes {
+        use core::fmt::Write as _;
+
+        let _: core::fmt::Result = write!(&mut muhash_hex, "{byte:02x}");
+    }
+    let total_amount_btc = bitcoin::Amount::from_sat(snapshot.total_amount).to_btc();
     Ok(json!({
         "height": ctx.applied_height(),
         "bestblock": ctx.applied_hash().to_string_be(),
         "txouts": ctx.utxo.len(),
-        "bogosize": 0,
-        "hash_serialized_2": Hash256::default().to_string_be(),
-        "total_amount": 0.0,
+        "bogosize": snapshot.bogo_size,
+        "hash_serialized_2": muhash_hex,
+        "total_amount": total_amount_btc,
         "transactions": ctx.utxo.record_count(),
         "disk_size": 0
     }))

crates/rpc/tests/handler_smoke.rs

@@ -151,6 +151,14 @@ fn gettxoutsetinfo_returns_real_utxo_counts() -> Result<(), Box<dyn std::error::
 
     assert_eq!(result.get("txouts").as_u64(), Some(0));
     assert_eq!(result.get("transactions").as_u64(), Some(0));
+    assert_eq!(result.get("bogosize").as_u64(), Some(0));
+    assert_eq!(result.get("total_amount").as_f64(), Some(0.0));
+    let hash_serialized_value = result.get("hash_serialized_2");
+    let hash_serialized = hash_serialized_value
+        .as_str()
+        .ok_or("hash_serialized_2 must be a string")?;
+    assert_eq!(hash_serialized.len(), 768);
+    assert!(hash_serialized.ends_with("01"));
     Ok(())
 }
 
@@ -294,6 +302,9 @@ fn context_with_peers(peers: Arc<RwLock<Vec<PeerInfo>>>) -> Arc<Context> {
         Arc::new(RwLock::new(Vec::new())),
         Arc::new(RwLock::new(HashMap::new())),
         Arc::new(UtxoSet::new()),
+        Arc::new(bitcoin_rs_coinstats::CoinStatsListener::new(
+            bitcoin_rs_coinstats::CoinStats::default(),
+        )),
         Arc::new(RwLock::new(NetworkState::default())),
         Arc::new(ArcSwap::from_pointee(CompactString::new("0"))),
         peers,