refactor(chain)!: generalize ChainQuery trait with generic type

Make `ChainRequest`/`ChainResponse` generic over block identifier types to enable
reuse beyond BlockId. Move `chain_tip` into `ChainRequest` for better encapsulation
and simpler API.

- Make `ChainRequest` and `ChainResponse` generic types with `BlockId` as default
- Add `chain_tip` field to `ChainRequest` to make it self-contained
- Change `ChainQuery` trait to use generic parameter `B` for block identifier type
- Remove `chain_tip` parameter from `LocalChain::canonicalize()` method
- Rename `ChainQuery::Result` to `ChainQuery::Output` for clarity

BREAKING CHANGE:
- `ChainRequest` now has a `chain_tip` field and is generic over block identifier type
- `ChainResponse` is now generic with default type parameter `BlockId`
- `ChainQuery` trait now takes a generic parameter `B = BlockId`
- `LocalChain::canonicalize()` no longer takes a `chain_tip` parameter

Co-authored-by: Claude <[email protected]>

Author: oleonardolima

crates/bitcoind_rpc/examples/filter_iter.rs

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

crates/bitcoind_rpc/tests/test_emitter.rs

@@ -312,9 +312,9 @@ fn get_balance(
     let outpoints = recv_graph.index.outpoints().clone();
     let task = recv_graph
         .graph()
-        .canonicalization_task(CanonicalizationParams::default());
+        .canonicalization_task(chain_tip, CanonicalizationParams::default());
     let balance = recv_chain
-        .canonicalize(task, Some(chain_tip))
+        .canonicalize(task)
         .balance(outpoints, |_, _| true, 0);
     Ok(balance)
 }
@@ -619,9 +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 task = graph.canonicalization_task(Default::default());
+    let task = graph.canonicalization_task(chain_tip, Default::default());
     let exp_spk_txids = chain
-        .canonicalize(task, Some(chain_tip))
+        .canonicalize(task)
         .list_expected_spk_txids(&graph.index, ..)
         .collect::<Vec<_>>();
     assert_eq!(exp_spk_txids, vec![(spk, txid_1)]);
@@ -638,9 +638,9 @@ fn test_expect_tx_evicted() -> anyhow::Result<()> {
 
     let task = graph
         .graph()
-        .canonicalization_task(CanonicalizationParams::default());
+        .canonicalization_task(chain_tip, CanonicalizationParams::default());
     let canonical_txids = chain
-        .canonicalize(task, Some(chain_tip))
+        .canonicalize(task)
         .txs()
         .map(|tx| tx.txid)
         .collect::<Vec<_>>();

crates/chain/benches/canonicalization.rs

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

crates/chain/benches/indexer.rs

@@ -86,10 +86,8 @@ fn do_bench(indexed_tx_graph: &KeychainTxGraph, chain: &LocalChain) {
     let op = graph.index.outpoints().clone();
     let task = graph
         .graph()
-        .canonicalization_task(CanonicalizationParams::default());
-    let bal = chain
-        .canonicalize(task, Some(chain_tip))
-        .balance(op, |_, _| false, 1);
+        .canonicalization_task(chain_tip, CanonicalizationParams::default());
+    let bal = chain.canonicalize(task).balance(op, |_, _| false, 1);
     assert_eq!(bal.total(), AMOUNT * TX_CT as u64);
 }
 

crates/chain/src/canonical_task.rs

@@ -5,7 +5,7 @@ use alloc::boxed::Box;
 use alloc::collections::BTreeSet;
 use alloc::sync::Arc;
 use alloc::vec::Vec;
-use bdk_core::{BlockId, ChainQuery};
+use bdk_core::{BlockId, ChainQuery, ChainRequest, ChainResponse};
 use bitcoin::{Transaction, Txid};
 
 type CanonicalMap<A> = HashMap<Txid, (Arc<Transaction>, CanonicalReason<A>)>;
@@ -21,19 +21,10 @@ pub struct CanonicalizationParams {
     pub assume_canonical: Vec<Txid>,
 }
 
-/// A request to check which anchors are confirmed in the chain.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct CanonicalizationRequest<A> {
-    /// The anchors to check.
-    pub anchors: Vec<A>,
-}
-
-/// Response containing the best confirmed anchor, if any.
-pub type CanonicalizationResponse<A> = Option<A>;
-
 /// 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:
@@ -54,26 +45,34 @@ pub struct CanonicalizationTask<'g, A> {
 }
 
 impl<'g, A: Anchor> ChainQuery for CanonicalizationTask<'g, A> {
-    type Request = CanonicalizationRequest<A>;
-    type Response = CanonicalizationResponse<A>;
-    type Context = BlockId;
-    type Result = CanonicalView<A>;
+    type Output = CanonicalView<A>;
 
-    fn next_query(&mut self) -> Option<Self::Request> {
+    fn next_query(&mut self) -> Option<ChainRequest> {
         // Check if we have pending anchor checks
         if let Some((_, _, anchors)) = self.pending_anchor_checks.front() {
-            return Some(CanonicalizationRequest {
-                anchors: anchors.clone(),
+            // Convert anchors to BlockIds for the ChainRequest
+            let block_ids = anchors.iter().map(|anchor| anchor.anchor_block()).collect();
+            return Some(ChainRequest {
+                chain_tip: self.chain_tip,
+                block_ids,
             });
         }
 
         // Process more anchored transactions if available
         self.process_anchored_txs()
     }
 
-    fn resolve_query(&mut self, response: Self::Response) {
+    fn resolve_query(&mut self, response: ChainResponse) {
         if let Some((txid, tx, anchors)) = self.pending_anchor_checks.pop_front() {
-            match response {
+            // Find the anchor that matches the confirmed BlockId
+            let best_anchor = response.and_then(|block_id| {
+                anchors
+                    .iter()
+                    .find(|anchor| anchor.anchor_block() == block_id)
+                    .cloned()
+            });
+
+            match best_anchor {
                 Some(best_anchor) => {
                     self.confirmed_anchors.insert(txid, best_anchor.clone());
                     if !self.is_canonicalized(txid) {
@@ -101,7 +100,7 @@ impl<'g, A: Anchor> ChainQuery for CanonicalizationTask<'g, A> {
         self.pending_anchor_checks.is_empty() && self.unprocessed_anchored_txs.size_hint().0 == 0
     }
 
-    fn finish(mut self, context: Self::Context) -> Self::Result {
+    fn finish(mut self) -> Self::Output {
         // Process remaining transactions (seen and leftover)
         self.process_seen_txs();
         self.process_leftover_txs();
@@ -181,13 +180,17 @@ impl<'g, A: Anchor> ChainQuery for CanonicalizationTask<'g, A> {
             }
         }
 
-        CanonicalView::new(context, view_order, view_txs, view_spends)
+        CanonicalView::new(self.chain_tip, view_order, view_txs, view_spends)
     }
 }
 
 impl<'g, A: Anchor> CanonicalizationTask<'g, A> {
     /// Creates a new canonicalization task.
-    pub fn new(tx_graph: &'g TxGraph<A>, params: CanonicalizationParams) -> Self {
+    pub fn new(
+        tx_graph: &'g TxGraph<A>,
+        chain_tip: BlockId,
+        params: CanonicalizationParams,
+    ) -> Self {
         let anchors = tx_graph.all_anchors();
         let unprocessed_assumed_txs = Box::new(
             params
@@ -209,6 +212,7 @@ impl<'g, A: Anchor> CanonicalizationTask<'g, A> {
 
         let mut task = Self {
             tx_graph,
+            chain_tip,
 
             unprocessed_assumed_txs,
             unprocessed_anchored_txs,
@@ -242,7 +246,7 @@ impl<'g, A: Anchor> CanonicalizationTask<'g, A> {
         }
     }
 
-    fn process_anchored_txs(&mut self) -> Option<CanonicalizationRequest<A>> {
+    fn process_anchored_txs(&mut self) -> Option<ChainRequest> {
         while let Some((txid, tx, anchors)) = self.unprocessed_anchored_txs.next() {
             if !self.is_canonicalized(txid) {
                 self.pending_anchor_checks
@@ -512,8 +516,8 @@ mod tests {
 
         // Create canonicalization task and canonicalize using the chain
         let params = CanonicalizationParams::default();
-        let task = CanonicalizationTask::new(&tx_graph, params);
-        let canonical_view = chain.canonicalize(task, Some(chain_tip));
+        let task = CanonicalizationTask::new(&tx_graph, chain_tip, params);
+        let canonical_view = chain.canonicalize(task);
 
         // Should have one canonical transaction
         assert_eq!(canonical_view.txs().len(), 1);

crates/chain/src/canonical_view.rs

@@ -11,9 +11,10 @@
 //! # use bitcoin::hashes::Hash;
 //! # let tx_graph = TxGraph::<BlockId>::default();
 //! # let chain = LocalChain::from_blocks([(0, bitcoin::BlockHash::all_zeros())].into_iter().collect()).unwrap();
+//! let chain_tip = chain.tip().block_id();
 //! let params = CanonicalizationParams::default();
-//! let task = CanonicalizationTask::new(&tx_graph, params);
-//! let view = chain.canonicalize(task, Some(chain.tip().block_id()));
+//! let task = CanonicalizationTask::new(&tx_graph, chain_tip, params);
+//! let view = chain.canonicalize(task);
 //!
 //! // Iterate over canonical transactions
 //! for tx in view.txs() {
@@ -143,8 +144,9 @@ impl<A: Anchor> CanonicalView<A> {
     /// # use bitcoin::hashes::Hash;
     /// # let tx_graph = TxGraph::<BlockId>::default();
     /// # let chain = LocalChain::from_blocks([(0, bitcoin::BlockHash::all_zeros())].into_iter().collect()).unwrap();
-    /// # let task = CanonicalizationTask::new(&tx_graph, Default::default());
-    /// # let view = chain.canonicalize(task, Some(chain.tip().block_id()));
+    /// # let chain_tip = chain.tip().block_id();
+    /// # let task = CanonicalizationTask::new(&tx_graph, chain_tip, Default::default());
+    /// # let view = chain.canonicalize(task);
     /// // Iterate over all canonical transactions
     /// for tx in view.txs() {
     ///     println!("TX {}: {:?}", tx.txid, tx.pos);
@@ -177,8 +179,9 @@ impl<A: Anchor> CanonicalView<A> {
     /// # use bitcoin::hashes::Hash;
     /// # let tx_graph = TxGraph::<BlockId>::default();
     /// # let chain = LocalChain::from_blocks([(0, bitcoin::BlockHash::all_zeros())].into_iter().collect()).unwrap();
-    /// # let task = CanonicalizationTask::new(&tx_graph, Default::default());
-    /// # let view = chain.canonicalize(task, Some(chain.tip().block_id()));
+    /// # let chain_tip = chain.tip().block_id();
+    /// # let task = CanonicalizationTask::new(&tx_graph, chain_tip, Default::default());
+    /// # let view = chain.canonicalize(task);
     /// # let indexer = KeychainTxOutIndex::<&str>::default();
     /// // Get all outputs from an indexer
     /// for (keychain, txout) in view.filter_outpoints(indexer.outpoints().clone()) {
@@ -207,8 +210,9 @@ impl<A: Anchor> CanonicalView<A> {
     /// # use bitcoin::hashes::Hash;
     /// # let tx_graph = TxGraph::<BlockId>::default();
     /// # let chain = LocalChain::from_blocks([(0, bitcoin::BlockHash::all_zeros())].into_iter().collect()).unwrap();
-    /// # let task = CanonicalizationTask::new(&tx_graph, Default::default());
-    /// # let view = chain.canonicalize(task, Some(chain.tip().block_id()));
+    /// # let chain_tip = chain.tip().block_id();
+    /// # let task = CanonicalizationTask::new(&tx_graph, chain_tip, Default::default());
+    /// # let view = chain.canonicalize(task);
     /// # let indexer = KeychainTxOutIndex::<&str>::default();
     /// // Get unspent outputs (UTXOs) from an indexer
     /// for (keychain, utxo) in view.filter_unspent_outpoints(indexer.outpoints().clone()) {
@@ -254,8 +258,9 @@ impl<A: Anchor> CanonicalView<A> {
     /// # use bitcoin::hashes::Hash;
     /// # let tx_graph = TxGraph::<BlockId>::default();
     /// # let chain = LocalChain::from_blocks([(0, bitcoin::BlockHash::all_zeros())].into_iter().collect()).unwrap();
-    /// # let task = CanonicalizationTask::new(&tx_graph, Default::default());
-    /// # let view = chain.canonicalize(task, Some(chain.tip().block_id()));
+    /// # let chain_tip = chain.tip().block_id();
+    /// # let task = CanonicalizationTask::new(&tx_graph, chain_tip, Default::default());
+    /// # let view = chain.canonicalize(task);
     /// # let indexer = KeychainTxOutIndex::<&str>::default();
     /// // Calculate balance with 6 confirmations, trusting all outputs
     /// let balance = view.balance(

crates/chain/src/indexed_tx_graph.rs

@@ -441,9 +441,10 @@ where
     /// for anchor verification requests.
     pub fn canonicalization_task(
         &'_ self,
+        chain_tip: BlockId,
         params: CanonicalizationParams,
     ) -> CanonicalizationTask<'_, A> {
-        self.graph.canonicalization_task(params)
+        self.graph.canonicalization_task(chain_tip, params)
     }
 }
 

crates/chain/src/local_chain.rs

@@ -140,38 +140,35 @@ impl LocalChain<BlockHash> {
     /// # use bitcoin::hashes::Hash;
     /// # let tx_graph: TxGraph<BlockId> = TxGraph::default();
     /// # let chain = LocalChain::from_blocks([(0, bitcoin::BlockHash::all_zeros())].into_iter().collect()).unwrap();
-    /// let task = CanonicalizationTask::new(&tx_graph, CanonicalizationParams::default());
-    /// let view = chain.canonicalize(task, Some(chain.tip().block_id()));
+    /// let chain_tip = chain.tip().block_id();
+    /// let task = CanonicalizationTask::new(&tx_graph, chain_tip, CanonicalizationParams::default());
+    /// let view = chain.canonicalize(task);
     /// ```
     pub fn canonicalize<A: Anchor>(
         &self,
         mut task: CanonicalizationTask<'_, A>,
-        chain_tip: Option<BlockId>,
     ) -> CanonicalView<A> {
-        let chain_tip = match chain_tip {
-            Some(chain_tip) => chain_tip,
-            None => self.get_chain_tip().expect("infallible"),
-        };
-
         // Process all requests from the task
         while let Some(request) = task.next_query() {
-            // Check each anchor and return the first confirmed one
-            let mut best_anchor = None;
-            for anchor in &request.anchors {
+            let chain_tip = request.chain_tip;
+
+            // Check each block ID and return the first confirmed one
+            let mut best_block_id = None;
+            for block_id in &request.block_ids {
                 if self
-                    .is_block_in_chain(anchor.anchor_block(), chain_tip)
+                    .is_block_in_chain(*block_id, chain_tip)
                     .expect("infallible")
                     == Some(true)
                 {
-                    best_anchor = Some(anchor.clone());
+                    best_block_id = Some(*block_id);
                     break;
                 }
             }
-            task.resolve_query(best_anchor);
+            task.resolve_query(best_block_id);
         }
 
         // Return the finished canonical view
-        task.finish(chain_tip)
+        task.finish()
     }
 
     /// Update the chain with a given [`Header`] at `height` which you claim is connected to a

crates/chain/src/tx_graph.rs

@@ -29,7 +29,7 @@
 //!    encapsulates the canonicalization logic without performing any I/O operations.
 //!
 //! 2. **Execute the task** with a chain oracle to obtain a [`CanonicalView`]: ```ignore let view =
-//!    chain.canonicalize(task, Some(chain_tip)); ``` The chain oracle (such as
+//!    chain.canonicalize(task); ``` The chain oracle (such as
 //!    [`LocalChain`](crate::local_chain::LocalChain)) handles all anchor verification queries from
 //!    the task.
 //!
@@ -129,7 +129,7 @@
 use crate::collections::*;
 use crate::CanonicalizationParams;
 use crate::CanonicalizationTask;
-use crate::{Anchor, Merge};
+use crate::{Anchor, BlockId, Merge};
 use alloc::collections::vec_deque::VecDeque;
 use alloc::sync::Arc;
 use alloc::vec::Vec;
@@ -964,9 +964,10 @@ impl<A: Anchor> TxGraph<A> {
     /// for anchor verification requests.
     pub fn canonicalization_task(
         &'_ self,
+        chain_tip: BlockId,
         params: CanonicalizationParams,
     ) -> CanonicalizationTask<'_, A> {
-        CanonicalizationTask::new(self, params)
+        CanonicalizationTask::new(self, chain_tip, params)
     }
 }