refactor(chain)!: migrate from CanonicalIter to CanonicalizationTask

- Replace `CanonicalView::new()` constructor with internal `CanonicalView::new()` for use by `CanonicalizationTask`
- Remove `TxGraph::try_canonical_view()` and `TxGraph::canonical_view()` methods
- Add `TxGraph::canonicalization_task()` method to create canonicalization tasks
- Add `LocalChain::canonicalize()` method to process tasks and return `CanonicalView`'s
- Update `IndexedTxGraph` to delegate canonicalization to underlying `TxGraph`

The new API separates canonicalization logic from I/O operations:
- Create canonicalization task: `graph.canonicalization_task(params)`
- Execute canonicalization: `chain.canonicalize(task, chain_tip)`

BREAKING CHANGE: Remove `CanonicalView::new()` and `TxGraph::canonical_view()` methods in favor of task-based approach

Author: oleonardolima

crates/bitcoind_rpc/examples/filter_iter.rs

@@ -69,7 +69,8 @@ fn main() -> anyhow::Result<()> {
     println!("\ntook: {}s", start.elapsed().as_secs());
     println!("Local tip: {}", chain.tip().height());
 
-    let canonical_view = graph.canonical_view(&chain, chain.tip().block_id(), Default::default());
+    let task = graph.canonicalization_task(Default::default());
+    let canonical_view = chain.canonicalize(task, Some(chain.tip().block_id()));
 
     let unspent: Vec<_> = canonical_view
         .filter_unspent_outpoints(graph.index.outpoints().clone())

crates/bitcoind_rpc/tests/test_emitter.rs

@@ -310,8 +310,11 @@ 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
-        .canonical_view(recv_chain, chain_tip, CanonicalizationParams::default())
+    let task = recv_graph
+        .graph()
+        .canonicalization_task(CanonicalizationParams::default());
+    let balance = recv_chain
+        .canonicalize(task, Some(chain_tip))
         .balance(outpoints, |_, _| true, 0);
     Ok(balance)
 }
@@ -616,8 +619,9 @@ fn test_expect_tx_evicted() -> anyhow::Result<()> {
     let _txid_2 = core.send_raw_transaction(&tx1b)?;
 
     // Retrieve the expected unconfirmed txids and spks from the graph.
-    let exp_spk_txids = graph
-        .canonical_view(&chain, chain_tip, Default::default())
+    let task = graph.canonicalization_task(Default::default());
+    let exp_spk_txids = chain
+        .canonicalize(task, Some(chain_tip))
         .list_expected_spk_txids(&graph.index, ..)
         .collect::<Vec<_>>();
     assert_eq!(exp_spk_txids, vec![(spk, txid_1)]);
@@ -632,8 +636,11 @@ fn test_expect_tx_evicted() -> anyhow::Result<()> {
     // Update graph with evicted tx.
     let _ = graph.batch_insert_relevant_evicted_at(mempool_event.evicted);
 
-    let canonical_txids = graph
-        .canonical_view(&chain, chain_tip, CanonicalizationParams::default())
+    let task = graph
+        .graph()
+        .canonicalization_task(CanonicalizationParams::default());
+    let canonical_txids = chain
+        .canonicalize(task, Some(chain_tip))
         .txs()
         .map(|tx| tx.txid)
         .collect::<Vec<_>>();

crates/chain/benches/canonicalization.rs

@@ -95,31 +95,28 @@ 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 view = tx_graph.canonical_view(
-        chain,
-        chain.tip().block_id(),
-        CanonicalizationParams::default(),
-    );
+    let task = tx_graph
+        .graph()
+        .canonicalization_task(CanonicalizationParams::default());
+    let view = chain.canonicalize(task, Some(chain.tip().block_id()));
     let txs = view.txs();
     assert_eq!(txs.count(), exp_txs);
 }
 
 fn run_filter_chain_txouts(tx_graph: &KeychainTxGraph, chain: &LocalChain, exp_txos: usize) {
-    let view = tx_graph.canonical_view(
-        chain,
-        chain.tip().block_id(),
-        CanonicalizationParams::default(),
-    );
+    let task = tx_graph
+        .graph()
+        .canonicalization_task(CanonicalizationParams::default());
+    let view = chain.canonicalize(task, Some(chain.tip().block_id()));
     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 view = tx_graph.canonical_view(
-        chain,
-        chain.tip().block_id(),
-        CanonicalizationParams::default(),
-    );
+    let task = tx_graph
+        .graph()
+        .canonicalization_task(CanonicalizationParams::default());
+    let view = chain.canonicalize(task, Some(chain.tip().block_id()));
     let utxos = view.filter_unspent_outpoints(tx_graph.index.outpoints().clone());
     assert_eq!(utxos.count(), exp_utxos);
 }

crates/chain/benches/indexer.rs

@@ -84,8 +84,11 @@ 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
-        .canonical_view(chain, chain_tip, CanonicalizationParams::default())
+    let task = graph
+        .graph()
+        .canonicalization_task(CanonicalizationParams::default());
+    let bal = chain
+        .canonicalize(task, Some(chain_tip))
         .balance(op, |_, _| false, 1);
     assert_eq!(bal.total(), AMOUNT * TX_CT as u64);
 }

crates/chain/src/canonical_task.rs

@@ -14,8 +14,6 @@ use bitcoin::{Transaction, Txid};
 pub struct CanonicalizationRequest<A> {
     /// The anchors to check.
     pub anchors: Vec<A>,
-    /// The chain tip to check against.
-    pub chain_tip: BlockId,
 }
 
 /// Response containing the best confirmed anchor, if any.
@@ -30,7 +28,6 @@ type NotCanonicalSet = HashSet<Txid>;
 /// Manages the canonicalization process without direct I/O operations.
 pub struct CanonicalizationTask<'g, A> {
     tx_graph: &'g TxGraph<A>,
-    chain_tip: BlockId,
 
     unprocessed_assumed_txs: Box<dyn Iterator<Item = (Txid, Arc<Transaction>)> + 'g>,
     unprocessed_anchored_txs:
@@ -52,13 +49,7 @@ pub struct CanonicalizationTask<'g, A> {
 
 impl<'g, A: Anchor> CanonicalizationTask<'g, A> {
     /// Creates a new canonicalization task.
-    ///
-    /// Returns the task and an optional initial request.
-    pub fn new(
-        tx_graph: &'g TxGraph<A>,
-        chain_tip: BlockId,
-        params: CanonicalizationParams,
-    ) -> (Self, Option<CanonicalizationRequest<A>>) {
+    pub fn new(tx_graph: &'g TxGraph<A>, params: CanonicalizationParams) -> Self {
         let anchors = tx_graph.all_anchors();
         let unprocessed_assumed_txs = Box::new(
             params
@@ -80,7 +71,6 @@ impl<'g, A: Anchor> CanonicalizationTask<'g, A> {
 
         let mut task = Self {
             tx_graph,
-            chain_tip,
 
             unprocessed_assumed_txs,
             unprocessed_anchored_txs,
@@ -96,13 +86,10 @@ impl<'g, A: Anchor> CanonicalizationTask<'g, A> {
             confirmed_anchors: HashMap::new(),
         };
 
-        // Process assumed transactions first (they don't need queries)
+        // process assumed transactions first (they don't need queries)
         task.process_assumed_txs();
 
-        // Process anchored transactions and get the first request if needed
-        let initial_request = task.process_anchored_txs();
-
-        (task, initial_request)
+        task
     }
 
     /// Returns the next query needed, if any.
@@ -111,7 +98,6 @@ impl<'g, A: Anchor> CanonicalizationTask<'g, A> {
         if let Some((_, _, anchors)) = self.pending_anchor_checks.front() {
             return Some(CanonicalizationRequest {
                 anchors: anchors.clone(),
-                chain_tip: self.chain_tip,
             });
         }
 
@@ -152,7 +138,7 @@ impl<'g, A: Anchor> CanonicalizationTask<'g, A> {
     }
 
     /// Completes the canonicalization and returns a CanonicalView.
-    pub fn finish(mut self) -> CanonicalView<A> {
+    pub fn finish(mut self, chain_tip: BlockId) -> CanonicalView<A> {
         // Process remaining transactions (seen and leftover)
         self.process_seen_txs();
         self.process_leftover_txs();
@@ -232,7 +218,7 @@ impl<'g, A: Anchor> CanonicalizationTask<'g, A> {
             }
         }
 
-        CanonicalView::from_parts(self.chain_tip, view_order, view_txs, view_spends)
+        CanonicalView::new(chain_tip, view_order, view_txs, view_spends)
     }
 
     fn is_canonicalized(&self, txid: Txid) -> bool {
@@ -426,23 +412,10 @@ mod tests {
         };
         let _ = tx_graph.insert_anchor(txid, anchor);
 
-        // Create canonicalization task
+        // Create canonicalization task and canonicalize using the chain
         let params = CanonicalizationParams::default();
-        let (mut task, initial_request) = CanonicalizationTask::new(&tx_graph, chain_tip, params);
-
-        // Process requests
-        if let Some(request) = initial_request {
-            let response = chain.handle_canonicalization_request(&request).unwrap();
-            task.resolve_query(response);
-        }
-
-        while let Some(request) = task.next_query() {
-            let response = chain.handle_canonicalization_request(&request).unwrap();
-            task.resolve_query(response);
-        }
-
-        // Get canonical view
-        let canonical_view = task.finish();
+        let task = CanonicalizationTask::new(&tx_graph, params);
+        let canonical_view = chain.canonicalize(task, Some(chain_tip));
 
         // Should have one canonical transaction
         assert_eq!(canonical_view.txs().len(), 1);