wip

Author: oleonardolima

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,10 @@ 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>>) {
+    ) -> Self {
         let anchors = tx_graph.all_anchors();
         let unprocessed_assumed_txs = Box::new(
             params
@@ -80,7 +74,6 @@ impl<'g, A: Anchor> CanonicalizationTask<'g, A> {
 
         let mut task = Self {
             tx_graph,
-            chain_tip,
 
             unprocessed_assumed_txs,
             unprocessed_anchored_txs,
@@ -96,22 +89,18 @@ 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.
     pub fn next_query(&mut self) -> Option<CanonicalizationRequest<A>> {
         // Check if we have pending anchor checks
         if let Some((_, _, anchors)) = self.pending_anchor_checks.front() {
             return Some(CanonicalizationRequest {
-                anchors: anchors.clone(),
-                chain_tip: self.chain_tip,
+                anchors: anchors.clone()
             });
         }
 
@@ -152,7 +141,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 +221,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 +415,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).unwrap();
 
         // Should have one canonical transaction
         assert_eq!(canonical_view.txs().len(), 1);

crates/chain/src/canonical_view.rs

@@ -31,8 +31,11 @@ use bdk_core::BlockId;
 use bitcoin::{Amount, OutPoint, ScriptBuf, Transaction, Txid};
 
 use crate::{
-    local_chain::LocalChain, spk_txout::SpkTxOutIndex, Anchor, Balance, CanonicalizationParams,
-    CanonicalizationTask, ChainOracle, ChainPosition, FullTxOut, TxGraph,
+    canonical_iter::{CanonicalIter, CanonicalReason, ObservedIn},
+    spk_txout::SpkTxOutIndex,
+    tx_graph::TxNode,
+    Anchor, Balance, CanonicalizationParams, ChainOracle, ChainPosition,
+    FullTxOut, TxGraph,
 };
 
 /// A single canonical transaction with its chain position.
@@ -76,9 +79,10 @@ pub struct CanonicalView<A> {
 }
 
 impl<A: Anchor> CanonicalView<A> {
+    // TODO: @(oleonardolima) update the documentation
     /// Creates a CanonicalView from its constituent parts.
     /// This is used by CanonicalizationTask to build the view.
-    pub(crate) fn from_parts(
+    pub(crate) fn new(
         tip: BlockId,
         order: Vec<Txid>,
         txs: HashMap<Txid, (Arc<Transaction>, ChainPosition<A>)>,
@@ -92,84 +96,6 @@ impl<A: Anchor> CanonicalView<A> {
         }
     }
 
-    /// Create a new canonical view from a transaction graph.
-    ///
-    /// This constructor analyzes the given [`TxGraph`] and creates a canonical view of all
-    /// transactions, resolving conflicts and ordering them according to their chain position.
-    ///
-    /// # Returns
-    ///
-    /// Returns `Ok(CanonicalView)` on success, or an error if the chain oracle fails.
-    pub fn new<'g, C>(
-        tx_graph: &'g TxGraph<A>,
-        chain: &'g C,
-        chain_tip: BlockId,
-        params: CanonicalizationParams,
-    ) -> Result<Self, C::Error>
-    where
-        C: ChainOracle,
-    {
-        let (mut task, initial_request) = CanonicalizationTask::new(tx_graph, chain_tip, params);
-
-        // Process the initial request if present
-        if let Some(request) = initial_request {
-            // Check each anchor and return the first confirmed one
-            let mut best_anchor = None;
-            for anchor in &request.anchors {
-                if chain.is_block_in_chain(anchor.anchor_block(), request.chain_tip)? == Some(true)
-                {
-                    best_anchor = Some(anchor.clone());
-                    break;
-                }
-            }
-            task.resolve_query(best_anchor);
-        }
-
-        // Process all subsequent requests
-        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 {
-                if chain.is_block_in_chain(anchor.anchor_block(), request.chain_tip)? == Some(true)
-                {
-                    best_anchor = Some(anchor.clone());
-                    break;
-                }
-            }
-            task.resolve_query(best_anchor);
-        }
-
-        // Return the finished canonical view
-        Ok(task.finish())
-    }
-
-    /// Create a new canonical view from a transaction graph using a LocalChain.
-    ///
-    /// This is a convenience method for working with [`LocalChain`] specifically.
-    pub fn new_with_local_chain<'g>(
-        tx_graph: &'g TxGraph<A>,
-        chain: &'g LocalChain,
-        chain_tip: BlockId,
-        params: CanonicalizationParams,
-    ) -> Result<Self, Infallible> {
-        let (mut task, initial_request) = CanonicalizationTask::new(tx_graph, chain_tip, params);
-
-        // Process the initial request if present
-        if let Some(request) = initial_request {
-            let response = chain.handle_canonicalization_request(&request)?;
-            task.resolve_query(response);
-        }
-
-        // Process all subsequent requests
-        while let Some(request) = task.next_query() {
-            let response = chain.handle_canonicalization_request(&request)?;
-            task.resolve_query(response);
-        }
-
-        // Return the finished canonical view
-        Ok(task.finish())
-    }
-
     /// Get a single canonical transaction by its transaction ID.
     ///
     /// Returns `Some(CanonicalTx)` if the transaction exists in the canonical view,

crates/chain/src/indexed_tx_graph.rs

@@ -423,33 +423,6 @@ where
     }
 }
 
-impl<A, X> IndexedTxGraph<A, X>
-where
-    A: Anchor,
-{
-    /// Returns a [`CanonicalView`].
-    pub fn try_canonical_view<'a, C: ChainOracle>(
-        &'a self,
-        chain: &'a C,
-        chain_tip: BlockId,
-        params: CanonicalizationParams,
-    ) -> Result<CanonicalView<A>, C::Error> {
-        self.graph.try_canonical_view(chain, chain_tip, params)
-    }
-
-    /// Returns a [`CanonicalView`].
-    ///
-    /// This is the infallible version of [`try_canonical_view`](Self::try_canonical_view).
-    pub fn canonical_view<'a, C: ChainOracle<Error = Infallible>>(
-        &'a self,
-        chain: &'a C,
-        chain_tip: BlockId,
-        params: CanonicalizationParams,
-    ) -> CanonicalView<A> {
-        self.graph.canonical_view(chain, chain_tip, params)
-    }
-}
-
 impl<A, I> AsRef<TxGraph<A>> for IndexedTxGraph<A, I> {
     fn as_ref(&self) -> &TxGraph<A> {
         &self.graph

crates/chain/src/local_chain.rs

@@ -4,9 +4,9 @@ use core::convert::Infallible;
 use core::fmt;
 use core::ops::RangeBounds;
 
-use crate::canonical_task::{CanonicalizationRequest, CanonicalizationResponse};
+use crate::canonical_task::CanonicalizationTask;
 use crate::collections::BTreeMap;
-use crate::{Anchor, BlockId, ChainOracle, Merge};
+use crate::{Anchor, BlockId, CanonicalView, ChainOracle, Merge};
 use bdk_core::ToBlockHash;
 pub use bdk_core::{CheckPoint, CheckPointIter};
 use bitcoin::block::Header;
@@ -70,50 +70,75 @@ impl<D> PartialEq for LocalChain<D> {
     }
 }
 
-impl<D> ChainOracle for LocalChain<D> {
-    type Error = Infallible;
-
-    fn is_block_in_chain(
-        &self,
-        block: BlockId,
-        chain_tip: BlockId,
-    ) -> Result<Option<bool>, Self::Error> {
+// Methods for `LocalChain<BlockHash>`
+impl LocalChain<BlockHash> {
+    /// Check if a block is in the chain.
+    ///
+    /// # Arguments
+    /// * `block` - The block to check
+    /// * `chain_tip` - The chain tip to check against
+    ///
+    /// # Returns
+    /// * `Some(true)` if the block is in the chain
+    /// * `Some(false)` if the block is not in the chain
+    /// * `None` if it cannot be determined
+    pub fn is_block_in_chain(&self, block: BlockId, chain_tip: BlockId) -> Option<bool> {
         let chain_tip_cp = match self.tip.get(chain_tip.height) {
             // we can only determine whether `block` is in chain of `chain_tip` if `chain_tip` can
             // be identified in chain
             Some(cp) if cp.hash() == chain_tip.hash => cp,
-            _ => return Ok(None),
+            _ => return None,
         };
-        match chain_tip_cp.get(block.height) {
-            Some(cp) => Ok(Some(cp.hash() == block.hash)),
-            None => Ok(None),
-        }
+        chain_tip_cp
+            .get(block.height)
+            .map(|cp| cp.hash() == block.hash)
     }
 
-    fn get_chain_tip(&self) -> Result<BlockId, Self::Error> {
-        Ok(self.tip.block_id())
+    /// Get the chain tip.
+    ///
+    /// # Returns
+    /// The [`BlockId`] of the chain tip.
+    pub fn chain_tip(&self) -> BlockId {
+        self.tip.block_id()
     }
-}
 
-// Methods for `LocalChain<BlockHash>`
-impl LocalChain<BlockHash> {
-    /// Handle a canonicalization request.
+    /// Canonicalize a transaction graph using this chain.
+    ///
+    /// This method processes a [`CanonicalizationTask`], handling all its requests
+    /// to determine which transactions are canonical, and returns a [`CanonicalView`].
     ///
-    /// This method processes requests from [`CanonicalizationTask`] to check if blocks
-    /// are in the chain.
+    /// # Example
     ///
-    /// [`CanonicalizationTask`]: crate::canonical_task::CanonicalizationTask
-    pub fn handle_canonicalization_request<A: Anchor>(
+    /// ```
+    /// # use bdk_chain::{CanonicalizationTask, CanonicalizationParams, TxGraph, local_chain::LocalChain};
+    /// # use bdk_core::BlockId;
+    /// # 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, chain.tip().block_id(), CanonicalizationParams::default());
+    /// let view = chain.canonicalize(task).unwrap();
+    /// ```
+    pub fn canonicalize<A: Anchor>(
         &self,
-        request: &CanonicalizationRequest<A>,
-    ) -> Result<CanonicalizationResponse<A>, Infallible> {
-        // Check each anchor and return the first confirmed one
-        for anchor in &request.anchors {
-            if self.is_block_in_chain(anchor.anchor_block(), request.chain_tip)? == Some(true) {
-                return Ok(Some(anchor.clone()));
+        mut task: CanonicalizationTask<'_, A>,
+    ) -> Result<CanonicalView<A>, Infallible> {
+        // Process all requests from the task
+        let chain_tip = self.chain_tip();
+
+        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 {
+                if self.is_block_in_chain(anchor.anchor_block(), chain_tip) == Some(true) {
+                    best_anchor = Some(anchor.clone());
+                    break;
+                }
             }
+            task.resolve_query(best_anchor);
         }
-        Ok(None)
+
+        // Return the finished canonical view
+        Ok(task.finish(chain_tip))
     }
 
     /// Update the chain with a given [`Header`] at `height` which you claim is connected to a