refactor(tx_graph)!: Rename {try_}list_chain_txs to {try_}canonical_transactions

The name `canonical_transactions` better describes the return
type for this method. Docs are updated to clearly define what
we mean by "canonical".

Author: ValuedMammal

crates/bdk/src/wallet/mod.rs

@@ -1103,7 +1103,7 @@ impl Wallet {
     {
         self.indexed_graph
             .graph()
-            .list_chain_txs(&self.chain, self.chain.tip().block_id())
+            .canonical_transactions(&self.chain, self.chain.tip().block_id())
     }
 
     /// Return the balance, separated into available, trusted-pending, untrusted-pending and immature

crates/chain/src/tx_graph.rs

@@ -969,18 +969,24 @@ impl<A: Anchor> TxGraph<A> {
 
     /// List graph transactions that are in `chain` with `chain_tip`.
     ///
-    /// Each transaction is represented as a [`CanonicalTx`] that contains where the transaction is
-    /// observed in-chain, and the [`TxNode`].
+    /// Each transaction is represented as a [`CanonicalTx`] that contains where the transaction
+    /// is observed in-chain and the [`TxNode`]. This means for a transaction to be considered
+    /// canonical from the point of view of [`TxGraph`], it needs to have been observed either in
+    /// the mempool or in a block confirmed in the active `chain`. However, it's also possible for
+    /// [`TxGraph`] to contain non-canonical transactions if for example a tx conflicts with a
+    /// more recent one or if it was never broadcast, in which case it can still be retrieved by
+    /// calling [`full_txs`].
     ///
-    /// # Error
+    /// # Errors
     ///
     /// If the [`ChainOracle`] implementation (`chain`) fails, an error will be returned with the
     /// returned item.
     ///
-    /// If the [`ChainOracle`] is infallible, [`list_chain_txs`] can be used instead.
+    /// If the [`ChainOracle`] is infallible, [`canonical_transactions`] can be used instead.
     ///
-    /// [`list_chain_txs`]: Self::list_chain_txs
-    pub fn try_list_chain_txs<'a, C: ChainOracle + 'a>(
+    /// [`full_txs`]: Self::full_txs
+    /// [`canonical_transactions`]: Self::canonical_transactions
+    pub fn try_canonical_transactions<'a, C: ChainOracle + 'a>(
         &'a self,
         chain: &'a C,
         chain_tip: BlockId,
@@ -1001,15 +1007,15 @@ impl<A: Anchor> TxGraph<A> {
 
     /// List graph transactions that are in `chain` with `chain_tip`.
     ///
-    /// This is the infallible version of [`try_list_chain_txs`].
+    /// This is the infallible version of [`try_canonical_transactions`].
     ///
-    /// [`try_list_chain_txs`]: Self::try_list_chain_txs
-    pub fn list_chain_txs<'a, C: ChainOracle + 'a>(
+    /// [`try_canonical_transactions`]: Self::try_canonical_transactions
+    pub fn canonical_transactions<'a, C: ChainOracle + 'a>(
         &'a self,
         chain: &'a C,
         chain_tip: BlockId,
     ) -> impl Iterator<Item = CanonicalTx<'a, Arc<Transaction>, A>> {
-        self.try_list_chain_txs(chain, chain_tip)
+        self.try_canonical_transactions(chain, chain_tip)
             .map(|r| r.expect("oracle is infallible"))
     }
 

crates/chain/tests/test_tx_graph_conflicts.rs

@@ -13,7 +13,7 @@ struct Scenario<'a> {
     name: &'a str,
     /// Transaction templates
     tx_templates: &'a [TxTemplate<'a, BlockId>],
-    /// Names of txs that must exist in the output of `list_chain_txs`
+    /// Names of txs that must exist in the output of `canonical_transactions`
     exp_chain_txs: HashSet<&'a str>,
     /// Outpoints that must exist in the output of `filter_chain_txouts`
     exp_chain_txouts: HashSet<(&'a str, u32)>,
@@ -25,7 +25,7 @@ struct Scenario<'a> {
 
 /// This test ensures that [`TxGraph`] will reliably filter out irrelevant transactions when
 /// presented with multiple conflicting transaction scenarios using the [`TxTemplate`] structure.
-/// This test also checks that [`TxGraph::list_chain_txs`], [`TxGraph::filter_chain_txouts`],
+/// This test also checks that [`TxGraph::canonical_transactions`], [`TxGraph::filter_chain_txouts`],
 /// [`TxGraph::filter_chain_unspents`], and [`TxGraph::balance`] return correct data.
 #[test]
 fn test_tx_conflict_handling() {
@@ -595,7 +595,7 @@ fn test_tx_conflict_handling() {
         let (tx_graph, spk_index, exp_tx_ids) = init_graph(scenario.tx_templates.iter());
 
         let txs = tx_graph
-            .list_chain_txs(&local_chain, chain_tip)
+            .canonical_transactions(&local_chain, chain_tip)
             .map(|tx| tx.tx_node.txid)
             .collect::<BTreeSet<_>>();
         let exp_txs = scenario
@@ -605,7 +605,7 @@ fn test_tx_conflict_handling() {
             .collect::<BTreeSet<_>>();
         assert_eq!(
             txs, exp_txs,
-            "\n[{}] 'list_chain_txs' failed",
+            "\n[{}] 'canonical_transactions' failed",
             scenario.name
         );
 

example-crates/example_electrum/src/main.rs

@@ -264,7 +264,7 @@ fn main() -> anyhow::Result<()> {
             if unconfirmed {
                 let unconfirmed_txids = graph
                     .graph()
-                    .list_chain_txs(&*chain, chain_tip)
+                    .canonical_transactions(&*chain, chain_tip)
                     .filter(|canonical_tx| !canonical_tx.chain_position.is_confirmed())
                     .map(|canonical_tx| canonical_tx.tx_node.txid)
                     .collect::<Vec<Txid>>();

example-crates/example_esplora/src/main.rs

@@ -315,7 +315,7 @@ fn main() -> anyhow::Result<()> {
                     // `EsploraExt::update_tx_graph_without_keychain`.
                     let unconfirmed_txids = graph
                         .graph()
-                        .list_chain_txs(&*chain, local_tip.block_id())
+                        .canonical_transactions(&*chain, local_tip.block_id())
                         .filter(|canonical_tx| !canonical_tx.chain_position.is_confirmed())
                         .map(|canonical_tx| canonical_tx.tx_node.txid)
                         .collect::<Vec<Txid>>();