refactor(core,chain)!: redesign ChainQuery and add per-tx MTP

Rewrite `ChainQuery` from a simple request/response pair into a full
sans-IO task trait. The generic parameter `B` (defaulting to `BlockHash`)
lets tasks receive richer block data (e.g. `Header`) from the driver.
Remove the old `ChainRequest`/`ChainResponse` types.

Add `LocalChain::canonical_view_with_mtp()` and
`LocalChain::canonical_view()` convenience methods.

Author: evanlinjin

crates/chain/src/canonical.rs

@@ -6,15 +6,14 @@
 //! ## Example
 //!
 //! ```
-//! # use bdk_chain::{TxGraph, CanonicalParams, CanonicalTask, local_chain::LocalChain};
+//! # use bdk_chain::{TxGraph, CanonicalParams, local_chain::LocalChain};
 //! # use bdk_core::BlockId;
 //! # 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 = CanonicalParams::default();
-//! let task = CanonicalTask::new(&tx_graph, chain_tip, params);
-//! let view = chain.canonicalize(task);
+//! let view = chain.canonical_view(&tx_graph, chain_tip, params);
 //!
 //! // Iterate over canonical transactions
 //! for tx in view.txs() {
@@ -27,13 +26,21 @@ use alloc::sync::Arc;
 use alloc::vec::Vec;
 use core::{fmt, ops::RangeBounds};
 
-use bdk_core::BlockId;
+use bdk_core::{BlockId, BlockQueries};
 use bitcoin::{
     constants::COINBASE_MATURITY, Amount, OutPoint, ScriptBuf, Transaction, TxOut, Txid,
 };
 
 use crate::{spk_txout::SpkTxOutIndex, Anchor, Balance, CanonicalViewTask, ChainPosition, TxGraph};
 
+/// Internal per-transaction entry in [`Canonical`].
+#[derive(Clone, Debug)]
+pub(crate) struct CanonicalEntry<P> {
+    pub(crate) tx: Arc<Transaction>,
+    pub(crate) pos: P,
+    pub(crate) mtp: Option<u32>,
+}
+
 /// A single canonical transaction with its position.
 ///
 /// This struct represents a transaction that has been determined to be canonical (not
@@ -52,6 +59,11 @@ pub struct CanonicalTx<P> {
     pub txid: Txid,
     /// The full transaction.
     pub tx: Arc<Transaction>,
+    /// The median-time-past at the confirmation height, if computed.
+    ///
+    /// This is `Some` only when the transaction is confirmed and MTP computation was
+    /// enabled via [`CanonicalViewTask::with_mtp`](crate::CanonicalViewTask::with_mtp).
+    pub mtp: Option<u32>,
 }
 
 impl<P: Ord> Ord for CanonicalTx<P> {
@@ -86,6 +98,11 @@ pub struct CanonicalTxOut<P> {
     pub spent_by: Option<(P, Txid)>,
     /// Whether this output is on a coinbase transaction.
     pub is_on_coinbase: bool,
+    /// The median-time-past at the confirmation height, if computed.
+    ///
+    /// This is `Some` only when the output's transaction is confirmed and MTP computation
+    /// was enabled via [`CanonicalViewTask::with_mtp`](crate::CanonicalViewTask::with_mtp).
+    pub mtp: Option<u32>,
 }
 
 impl<P: Ord> Ord for CanonicalTxOut<P> {
@@ -186,12 +203,14 @@ impl<A: Anchor> CanonicalTxOut<ChainPosition<A>> {
 pub struct Canonical<A, P> {
     /// Ordered list of transaction IDs in topological-spending order.
     pub(crate) order: Vec<Txid>,
-    /// Map of transaction IDs to their transaction data and position.
-    pub(crate) txs: HashMap<Txid, (Arc<Transaction>, P)>,
+    /// Map of transaction IDs to their transaction data, position, and MTP.
+    pub(crate) txs: HashMap<Txid, CanonicalEntry<P>>,
     /// Map of outpoints to the transaction ID that spends them.
     pub(crate) spends: HashMap<OutPoint, Txid>,
     /// The chain tip at the time this view was created.
     pub(crate) tip: BlockId,
+    /// Median-time-past at the chain tip height.
+    pub(crate) tip_mtp: Option<u32>,
     /// Marker for the anchor type.
     pub(crate) _anchor: core::marker::PhantomData<A>,
 }
@@ -213,14 +232,16 @@ impl<A, P: Clone> Canonical<A, P> {
     pub(crate) fn new(
         tip: BlockId,
         order: Vec<Txid>,
-        txs: HashMap<Txid, (Arc<Transaction>, P)>,
+        txs: HashMap<Txid, CanonicalEntry<P>>,
         spends: HashMap<OutPoint, Txid>,
+        tip_mtp: Option<u32>,
     ) -> Self {
         Self {
             tip,
             order,
             txs,
             spends,
+            tip_mtp,
             _anchor: core::marker::PhantomData,
         }
     }
@@ -230,15 +251,25 @@ impl<A, P: Clone> Canonical<A, P> {
         self.tip
     }
 
+    /// Get the MTP at the chain tip height.
+    ///
+    /// Returns `None` if MTP was not computed.
+    pub fn tip_mtp(&self) -> Option<u32> {
+        self.tip_mtp
+    }
+
     /// Get a single canonical transaction by its transaction ID.
     ///
     /// Returns `Some(CanonicalTx)` if the transaction exists in the canonical set,
     /// or `None` if the transaction doesn't exist or was excluded due to conflicts.
     pub fn tx(&self, txid: Txid) -> Option<CanonicalTx<P>> {
-        self.txs
-            .get(&txid)
-            .cloned()
-            .map(|(tx, pos)| CanonicalTx { pos, txid, tx })
+        let entry = self.txs.get(&txid)?;
+        Some(CanonicalTx {
+            pos: entry.pos.clone(),
+            txid,
+            tx: entry.tx.clone(),
+            mtp: entry.mtp,
+        })
     }
 
     /// Get a single canonical transaction output.
@@ -251,19 +282,20 @@ impl<A, P: Clone> Canonical<A, P> {
     /// - The output index is out of bounds
     /// - The transaction was excluded due to conflicts
     pub fn txout(&self, op: OutPoint) -> Option<CanonicalTxOut<P>> {
-        let (tx, pos) = self.txs.get(&op.txid)?;
+        let entry = self.txs.get(&op.txid)?;
         let vout: usize = op.vout.try_into().ok()?;
-        let txout = tx.output.get(vout)?;
+        let txout = entry.tx.output.get(vout)?;
         let spent_by = self.spends.get(&op).map(|spent_by_txid| {
-            let (_, spent_by_pos) = &self.txs[spent_by_txid];
-            (spent_by_pos.clone(), *spent_by_txid)
+            let spent_by_entry = &self.txs[spent_by_txid];
+            (spent_by_entry.pos.clone(), *spent_by_txid)
         });
         Some(CanonicalTxOut {
-            pos: pos.clone(),
+            pos: entry.pos.clone(),
             outpoint: op,
             txout: txout.clone(),
             spent_by,
-            is_on_coinbase: tx.is_coinbase(),
+            is_on_coinbase: entry.tx.is_coinbase(),
+            mtp: entry.mtp,
         })
     }
 
@@ -275,14 +307,13 @@ impl<A, P: Clone> Canonical<A, P> {
     /// # Example
     ///
     /// ```
-    /// # use bdk_chain::{TxGraph, CanonicalTask, local_chain::LocalChain};
+    /// # use bdk_chain::{TxGraph, local_chain::LocalChain};
     /// # use bdk_core::BlockId;
     /// # 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 task = CanonicalTask::new(&tx_graph, chain_tip, Default::default());
-    /// # let view = chain.canonicalize(task);
+    /// # let view = chain.canonical_view(&tx_graph, chain_tip, Default::default());
     /// // Iterate over all canonical transactions
     /// for tx in view.txs() {
     ///     println!("TX {}: {:?}", tx.txid, tx.pos);
@@ -293,8 +324,13 @@ impl<A, P: Clone> Canonical<A, P> {
     /// ```
     pub fn txs(&self) -> impl ExactSizeIterator<Item = CanonicalTx<P>> + DoubleEndedIterator + '_ {
         self.order.iter().map(|&txid| {
-            let (tx, pos) = self.txs[&txid].clone();
-            CanonicalTx { pos, txid, tx }
+            let entry = &self.txs[&txid];
+            CanonicalTx {
+                pos: entry.pos.clone(),
+                txid,
+                tx: entry.tx.clone(),
+                mtp: entry.mtp,
+            }
         })
     }
 
@@ -310,14 +346,13 @@ impl<A, P: Clone> Canonical<A, P> {
     /// # Example
     ///
     /// ```
-    /// # use bdk_chain::{TxGraph, CanonicalTask, local_chain::LocalChain, keychain_txout::KeychainTxOutIndex};
+    /// # use bdk_chain::{TxGraph, local_chain::LocalChain, keychain_txout::KeychainTxOutIndex};
     /// # use bdk_core::BlockId;
     /// # 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 task = CanonicalTask::new(&tx_graph, chain_tip, Default::default());
-    /// # let view = chain.canonicalize(task);
+    /// # let view = chain.canonical_view(&tx_graph, chain_tip, Default::default());
     /// # let indexer = KeychainTxOutIndex::<&str>::default();
     /// // Get all outputs from an indexer
     /// for (keychain, txout) in view.filter_outpoints(indexer.outpoints().clone()) {
@@ -341,14 +376,13 @@ impl<A, P: Clone> Canonical<A, P> {
     /// # Example
     ///
     /// ```
-    /// # use bdk_chain::{TxGraph, CanonicalTask, local_chain::LocalChain, keychain_txout::KeychainTxOutIndex};
+    /// # use bdk_chain::{TxGraph, local_chain::LocalChain, keychain_txout::KeychainTxOutIndex};
     /// # use bdk_core::BlockId;
     /// # 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 task = CanonicalTask::new(&tx_graph, chain_tip, Default::default());
-    /// # let view = chain.canonicalize(task);
+    /// # let view = chain.canonical_view(&tx_graph, chain_tip, Default::default());
     /// # let indexer = KeychainTxOutIndex::<&str>::default();
     /// // Get unspent outputs (UTXOs) from an indexer
     /// for (keychain, utxo) in view.filter_unspent_outpoints(indexer.outpoints().clone()) {
@@ -488,13 +522,22 @@ impl<A: Anchor> CanonicalView<A> {
 }
 
 impl<A: Anchor> CanonicalTxs<A> {
-    /// 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
-    /// produces a [`CanonicalView`] with resolved chain positions.
-    pub fn view_task<'g>(self, tx_graph: &'g TxGraph<A>) -> CanonicalViewTask<'g, A> {
-        CanonicalViewTask::new(tx_graph, self.tip, self.order, self.txs, self.spends)
+    /// Creates a [`CanonicalViewTask`] that resolves [`CanonicalReason`]s into [`ChainPosition`]s.
+    ///
+    /// This is the second phase of the canonicalization pipeline. Blocks fetched during
+    /// phase 1 are passed through so they can be reused without redundant queries.
+    pub fn view_task<'g, B>(
+        self,
+        tx_graph: &'g TxGraph<A>,
+        queries: BlockQueries<B>,
+    ) -> CanonicalViewTask<'g, A, B> {
+        CanonicalViewTask::new(
+            tx_graph,
+            self.tip,
+            self.order,
+            self.txs,
+            self.spends,
+            queries,
+        )
     }
 }