feat(chain)!: Introduce CanonicalView and migrate API

- Add `CanonicalView` structure with canonical transaction methods
- Move methods from `TxGraph` to `CanonicalView` (txs, filter_outpoints, balance, etc.)
- Add canonical view methods to `IndexedTxGraph`
- Update all tests and examples to use new API
- Optimize examples to reuse canonical view instances

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: 2 people

crates/bitcoind_rpc/examples/filter_iter.rs

@@ -69,13 +69,8 @@ fn main() -> anyhow::Result<()> {
     println!("\ntook: {}s", start.elapsed().as_secs());
     println!("Local tip: {}", chain.tip().height());
     let unspent: Vec<_> = graph
-        .graph()
-        .filter_chain_unspents(
-            &chain,
-            chain.tip().block_id(),
-            Default::default(),
-            graph.index.outpoints().clone(),
-        )
+        .canonical_view(&chain, chain.tip().block_id(), Default::default())
+        .filter_unspent_outpoints(graph.index.outpoints().clone())
         .collect();
     if !unspent.is_empty() {
         println!("\nUnspent");
@@ -85,16 +80,16 @@ fn main() -> anyhow::Result<()> {
         }
     }
 
-    for canon_tx in graph.graph().list_canonical_txs(
-        &chain,
-        chain.tip().block_id(),
-        bdk_chain::CanonicalizationParams::default(),
-    ) {
-        if !canon_tx.chain_position.is_confirmed() {
-            eprintln!(
-                "ERROR: canonical tx should be confirmed {}",
-                canon_tx.tx_node.txid
-            );
+    for canon_tx in graph
+        .canonical_view(
+            &chain,
+            chain.tip().block_id(),
+            bdk_chain::CanonicalizationParams::default(),
+        )
+        .txs()
+    {
+        if !canon_tx.pos.is_confirmed() {
+            eprintln!("ERROR: canonical tx should be confirmed {}", canon_tx.txid);
         }
     }
 

crates/bitcoind_rpc/tests/test_emitter.rs

@@ -310,13 +310,9 @@ fn get_balance(
 ) -> anyhow::Result<Balance> {
     let chain_tip = recv_chain.tip().block_id();
     let outpoints = recv_graph.index.outpoints().clone();
-    let balance = recv_graph.graph().balance(
-        recv_chain,
-        chain_tip,
-        CanonicalizationParams::default(),
-        outpoints,
-        |_, _| true,
-    );
+    let balance = recv_graph
+        .canonical_view(recv_chain, chain_tip, CanonicalizationParams::default())
+        .balance(outpoints, |_, _| true);
     Ok(balance)
 }
 
@@ -621,7 +617,8 @@ fn test_expect_tx_evicted() -> anyhow::Result<()> {
 
     // Retrieve the expected unconfirmed txids and spks from the graph.
     let exp_spk_txids = graph
-        .list_expected_spk_txids(&chain, chain_tip, ..)
+        .canonical_view(&chain, chain_tip, Default::default())
+        .list_expected_spk_txids(&graph.index, ..)
         .collect::<Vec<_>>();
     assert_eq!(exp_spk_txids, vec![(spk, txid_1)]);
 
@@ -636,9 +633,9 @@ fn test_expect_tx_evicted() -> anyhow::Result<()> {
     let _ = graph.batch_insert_relevant_evicted_at(mempool_event.evicted);
 
     let canonical_txids = graph
-        .graph()
-        .list_canonical_txs(&chain, chain_tip, CanonicalizationParams::default())
-        .map(|tx| tx.tx_node.compute_txid())
+        .canonical_view(&chain, chain_tip, CanonicalizationParams::default())
+        .txs()
+        .map(|tx| tx.txid)
         .collect::<Vec<_>>();
     // tx1 should no longer be canonical.
     assert!(!canonical_txids.contains(&txid_1));

crates/chain/benches/canonicalization.rs

@@ -95,31 +95,32 @@ fn setup<F: Fn(&mut KeychainTxGraph, &LocalChain)>(f: F) -> (KeychainTxGraph, Lo
 }
 
 fn run_list_canonical_txs(tx_graph: &KeychainTxGraph, chain: &LocalChain, exp_txs: usize) {
-    let txs = tx_graph.graph().list_canonical_txs(
+    let view = tx_graph.canonical_view(
         chain,
         chain.tip().block_id(),
         CanonicalizationParams::default(),
     );
+    let txs = view.txs();
     assert_eq!(txs.count(), exp_txs);
 }
 
 fn run_filter_chain_txouts(tx_graph: &KeychainTxGraph, chain: &LocalChain, exp_txos: usize) {
-    let utxos = tx_graph.graph().filter_chain_txouts(
+    let view = tx_graph.canonical_view(
         chain,
         chain.tip().block_id(),
         CanonicalizationParams::default(),
-        tx_graph.index.outpoints().clone(),
     );
+    let utxos = view.filter_outpoints(tx_graph.index.outpoints().clone());
     assert_eq!(utxos.count(), exp_txos);
 }
 
 fn run_filter_chain_unspents(tx_graph: &KeychainTxGraph, chain: &LocalChain, exp_utxos: usize) {
-    let utxos = tx_graph.graph().filter_chain_unspents(
+    let view = tx_graph.canonical_view(
         chain,
         chain.tip().block_id(),
         CanonicalizationParams::default(),
-        tx_graph.index.outpoints().clone(),
     );
+    let utxos = view.filter_unspent_outpoints(tx_graph.index.outpoints().clone());
     assert_eq!(utxos.count(), exp_utxos);
 }
 

crates/chain/benches/indexer.rs

@@ -84,13 +84,9 @@ fn do_bench(indexed_tx_graph: &KeychainTxGraph, chain: &LocalChain) {
     // Check balance
     let chain_tip = chain.tip().block_id();
     let op = graph.index.outpoints().clone();
-    let bal = graph.graph().balance(
-        chain,
-        chain_tip,
-        CanonicalizationParams::default(),
-        op,
-        |_, _| false,
-    );
+    let bal = graph
+        .canonical_view(chain, chain_tip, CanonicalizationParams::default())
+        .balance(op, |_, _| false);
     assert_eq!(bal.total(), AMOUNT * TX_CT as u64);
 }