chore(chain,example)!: Remove ChainOracle and fix docs

Author: evanlinjin

crates/chain/src/canonical.rs

@@ -488,7 +488,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

@@ -432,7 +432,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,11 +1,10 @@
-//! 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 crate::{Anchor, BlockId, CanonicalParams, CanonicalView, Merge, TxGraph};
 use bdk_core::{ChainQuery, ToBlockHash};
 pub use bdk_core::{CheckPoint, CheckPointIter};
 use bitcoin::block::Header;
@@ -57,7 +56,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>,
@@ -69,62 +68,37 @@ 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> {
-    // /// 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 None,
-    //     };
-    //     chain_tip_cp
-    //         .get(block.height)
-    //         .map(|cp| cp.hash() == block.hash)
-    // }
-
-    // /// Get the chain tip.
-    // ///
-    // /// # Returns
-    // /// The [`BlockId`] of the chain tip.
-    // pub fn chain_tip(&self) -> BlockId {
-    //     self.tip.block_id()
-    // }
 
     /// Canonicalize a transaction graph using this chain.
     ///
@@ -151,11 +125,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

@@ -124,6 +124,7 @@
 //! assert!(changeset.is_empty());
 //! ```
 //! [`insert_txout`]: TxGraph::insert_txout
+//! [`CanonicalView`]: crate::CanonicalView
 
 use crate::collections::*;
 use crate::CanonicalParams;
@@ -978,6 +979,8 @@ impl<A: Anchor> TxGraph<A> {
     /// that can be used to determine which transactions are canonical based on the provided
     /// parameters. The task handles the stateless canonicalization logic and can be polled
     /// for anchor verification requests.
+    ///
+    /// [`CanonicalView`]: crate::CanonicalView
     pub fn canonical_task(
         &'_ self,
         chain_tip: BlockId,

crates/chain/src/tx_graph.rs

@@ -305,7 +305,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,
                     }
                 }

crates/chain/tests/test_tx_graph.rs

@@ -24,7 +24,7 @@ use bdk_chain::ConfirmationBlockTime;
 use bdk_chain::{
     indexer::keychain_txout::{self, KeychainTxOutIndex},
     local_chain::{self, LocalChain},
-    tx_graph, CanonicalTxOut, ChainOracle, ChainPosition, DescriptorExt, IndexedTxGraph, Merge,
+    tx_graph, CanonicalTxOut, ChainPosition, DescriptorExt, IndexedTxGraph, Merge,
 };
 use bdk_coin_select::{
     metrics::LowestFee, Candidate, ChangePolicy, CoinSelector, DrainWeights, FeeRate, Target,
@@ -390,9 +390,7 @@ pub fn create_tx(
         version: transaction::Version::TWO,
         lock_time: assets
             .absolute_timelock
-            .unwrap_or(absolute::LockTime::from_height(
-                chain.get_chain_tip()?.height,
-            )?),
+            .unwrap_or(absolute::LockTime::from_height(chain.chain_tip().height)?),
         input: selected
             .iter()
             .map(|(plan, utxo)| TxIn {
@@ -554,7 +552,7 @@ pub fn handle_commands<CS: clap::Subcommand, S: clap::Args>(
         Commands::TxOut { txout_cmd } => {
             let graph = &*graph.lock().unwrap();
             let chain = &*chain.lock().unwrap();
-            let chain_tip = chain.get_chain_tip()?;
+            let chain_tip = chain.chain_tip();
             let outpoints = graph.index.outpoints();
 
             match txout_cmd {