chore(chain,example)!: remove ChainOracle, update docs

Author: evanlinjin

crates/chain/src/canonical.rs

@@ -490,7 +490,8 @@ impl<A: Anchor> CanonicalView<A> {
 }
 
 impl<A: Anchor> CanonicalTxs<A> {
-    /// Creates a [`CanonicalViewTask`] that resolves [`CanonicalReason`]s into [`ChainPosition`]s.
+    /// Creates a [`CanonicalViewTask`] that resolves [`CanonicalReason`](crate::CanonicalReason)s
+    /// into [`ChainPosition`]s.
     ///
     /// This is the second phase of the canonicalization pipeline. The resulting task
     /// queries the chain to verify anchors for transitively anchored transactions and

crates/chain/src/canonical_task.rs

@@ -53,9 +53,9 @@ pub struct CanonicalParams {
 ///
 /// This task implements the first phase of canonicalization: it walks the transaction
 /// graph and determines which transactions are canonical (non-conflicting) and why
-/// (via [`CanonicalReason`]). The output is a [`CanonicalTxs`] which can then be
-/// further processed by [`CanonicalViewTask`] to resolve reasons into
-/// [`ChainPosition`]s.
+/// (via [`CanonicalReason`](crate::CanonicalReason)). The output is a [`CanonicalTxs`] which can
+/// then be further processed by [`CanonicalViewTask`](crate::CanonicalViewTask) to resolve reasons
+/// into [`ChainPosition`](crate::ChainPosition)s.
 pub struct CanonicalTask<'g, A> {
     tx_graph: &'g TxGraph<A>,
     chain_tip: BlockId,

crates/chain/src/chain_oracle.rs

@@ -436,7 +436,8 @@ impl<A, X> IndexedTxGraph<A, X>
 where
     A: Anchor,
 {
-    /// Creates a [`CanonicalTask`] to determine the [`CanonicalView`] of transactions.
+    /// Creates a [`CanonicalTask`] to determine the [`CanonicalView`](crate::CanonicalView) of
+    /// transactions.
     ///
     /// This method delegates to the underlying [`TxGraph`] to create a [`CanonicalTask`]
     /// that can be used to determine which transactions are canonical based on the provided

crates/chain/src/indexed_tx_graph.rs

@@ -42,8 +42,6 @@ mod tx_data_traits;
 pub use tx_data_traits::*;
 pub mod tx_graph;
 pub use tx_graph::TxGraph;
-mod chain_oracle;
-pub use chain_oracle::*;
 mod canonical_task;
 pub use canonical_task::*;
 mod canonical;

crates/chain/src/lib.rs

@@ -1,13 +1,12 @@
-//! The [`LocalChain`] is a local implementation of [`ChainOracle`].
+//! The [`LocalChain`] is a local chain of checkpoints.
 
-use core::convert::Infallible;
 use core::fmt;
 use core::ops::RangeBounds;
 
 use crate::collections::BTreeMap;
-use crate::{Anchor, BlockId, CanonicalParams, CanonicalView, ChainOracle, Merge, TxGraph};
-use bdk_core::{ChainQuery, CheckPointEntry, ToBlockHash};
-pub use bdk_core::{CheckPoint, CheckPointIter};
+use crate::{Anchor, BlockId, CanonicalParams, CanonicalView, Merge, TxGraph};
+use bdk_core::{ChainQuery, ToBlockHash};
+pub use bdk_core::{CheckPoint, CheckPointEntry, CheckPointIter};
 use bitcoin::block::Header;
 use bitcoin::BlockHash;
 
@@ -61,7 +60,7 @@ where
     Ok(init_cp)
 }
 
-/// This is a local implementation of [`ChainOracle`].
+/// A local chain of checkpoints.
 #[derive(Debug, Clone)]
 pub struct LocalChain<D = BlockHash> {
     tip: CheckPoint<D>,
@@ -73,33 +72,38 @@ 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> {
     /// Canonicalize a transaction graph using this chain.
     ///
     /// This method processes any type implementing [`ChainQuery`], handling all its requests
@@ -125,11 +129,7 @@ impl LocalChain<BlockHash> {
         while let Some(request) = task.next_query() {
             let mut best_block_id = None;
             for block_id in &request {
-                if self
-                    .is_block_in_chain(*block_id, chain_tip)
-                    .expect("infallible")
-                    == Some(true)
-                {
+                if self.is_block_in_chain(*block_id, chain_tip) == Some(true) {
                     best_block_id = Some(*block_id);
                     break;
                 }

crates/chain/src/local_chain.rs

@@ -303,7 +303,7 @@ fn insert_relevant_txs() {
 }
 
 /// Ensure consistency IndexedTxGraph list_* and balance methods. These methods lists
-/// relevant txouts and utxos from the information fetched from a ChainOracle (here a LocalChain).
+/// relevant txouts and utxos from the information fetched from a LocalChain.
 ///
 /// Test Setup:
 ///

crates/chain/tests/test_indexed_tx_graph.rs

@@ -7,7 +7,7 @@ use bdk_chain::{
     local_chain::LocalChain,
     tx_graph::{self, CalculateFeeError},
     tx_graph::{ChangeSet, TxGraph},
-    Anchor, ChainOracle, ChainPosition, Merge,
+    Anchor, ChainPosition, Merge,
 };
 use bdk_testenv::{block_id, hash, utils::new_tx};
 use bitcoin::hex::FromHex;
@@ -758,7 +758,7 @@ fn test_walk_ancestors() {
                 let tx_node = graph.get_tx_node(tx.compute_txid())?;
                 for block in tx_node.anchors {
                     match local_chain.is_block_in_chain(block.anchor_block(), tip.block_id()) {
-                        Ok(Some(true)) => return None,
+                        Some(true) => return None,
                         _ => continue,
                     }
                 }