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

diff --git a/crates/chain/src/canonical.rs b/crates/chain/src/canonical.rs
index 132a388d3a08db7ef9f11b0b7c458da99b30941c..c2aecb7561af2f8181a98cd0ca139a9658efdb96 100644 (file)
--- a/crates/chain/src/canonical.rs
+++ b/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

diff --git a/crates/chain/src/canonical_task.rs b/crates/chain/src/canonical_task.rs
index 702a909dac0f78b61316ec36e2233cc8a2f585b8..0cb8ffbf4a756a05855c1a84689d7ebc4d7dfb86 100644 (file)
--- a/crates/chain/src/canonical_task.rs
+++ b/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,

diff --git a/crates/chain/src/chain_oracle.rs b/crates/chain/src/chain_oracle.rs
deleted file mode 100644 (file)
index 08e697e..0000000
--- a/crates/chain/src/chain_oracle.rs
+++ /dev/null
@@ -1,25 +0,0 @@
-use crate::BlockId;
-
-/// Represents a service that tracks the blockchain.
-///
-/// The main method is [`is_block_in_chain`] which determines whether a given block of [`BlockId`]
-/// is an ancestor of the `chain_tip`.
-///
-/// [`is_block_in_chain`]: Self::is_block_in_chain
-pub trait ChainOracle {
-    /// Error type.
-    type Error: core::fmt::Debug;
-
-    /// Determines whether `block` of [`BlockId`] exists as an ancestor of `chain_tip`.
-    ///
-    /// If `None` is returned, it means the implementation cannot determine whether `block` exists
-    /// under `chain_tip`.
-    fn is_block_in_chain(
-        &self,
-        block: BlockId,
-        chain_tip: BlockId,
-    ) -> Result<Option<bool>, Self::Error>;
-
-    /// Get the best chain's chain tip.
-    fn get_chain_tip(&self) -> Result<BlockId, Self::Error>;
-}

diff --git a/crates/chain/src/indexed_tx_graph.rs b/crates/chain/src/indexed_tx_graph.rs
index c56f7d58de60391f05c4270902036dfaf0336bc0..496367ef268e86f65ab51ceb9f40b66aa6a7d551 100644 (file)
--- a/crates/chain/src/indexed_tx_graph.rs
+++ b/crates/chain/src/indexed_tx_graph.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

diff --git a/crates/chain/src/lib.rs b/crates/chain/src/lib.rs
index 8c42473ba4eeea05ae28499d5b40d8decad0a006..41ed7cc098a7c3e89fbc933dc71ff2dbf4b15e53 100644 (file)
--- a/crates/chain/src/lib.rs
+++ b/crates/chain/src/lib.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;

diff --git a/crates/chain/src/local_chain.rs b/crates/chain/src/local_chain.rs
index 38fc30c464ff5c13b692c5ad37c5a0e39df2b1a2..ee1d67fe0de4f7b14a029192dfbcdb107d5c8d0e 100644 (file)
--- a/crates/chain/src/local_chain.rs
+++ b/crates/chain/src/local_chain.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;
                 }

diff --git a/crates/chain/tests/test_indexed_tx_graph.rs b/crates/chain/tests/test_indexed_tx_graph.rs
index d6fabbab3b1de9dfef49b05338d2a676e128abdc..96cafcb8ed517167973f2f5702b665e8eda2d27d 100644 (file)
--- a/crates/chain/tests/test_indexed_tx_graph.rs
+++ b/crates/chain/tests/test_indexed_tx_graph.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:
 ///

diff --git a/crates/chain/tests/test_tx_graph.rs b/crates/chain/tests/test_tx_graph.rs
index 3cbfe3414f1822cce6736ffdcd8e3ad9395d7b8b..621bd6706775275da642234400d4c77683e5d4ed 100644 (file)
--- a/crates/chain/tests/test_tx_graph.rs
+++ b/crates/chain/tests/test_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,
                     }
                 }