refactor(chain)!: Rename min_confirmations to additional_confirmations

BREAKING CHANGE: `CanonicalView::balance()` now takes `additional_confirmations`
instead of `min_confirmations`. The new parameter represents confirmations
beyond the first (e.g., 5 means 6 total confirmations required).

- Rename `why` to `reason` in CanonicalView for clarity
- Update docs to clarify topological-spending order
- Simplify docs by removing redundant conflict mentions

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: evanlinjin

crates/bitcoind_rpc/tests/test_emitter.rs

@@ -312,7 +312,7 @@ fn get_balance(
     let outpoints = recv_graph.index.outpoints().clone();
     let balance = recv_graph
         .canonical_view(recv_chain, chain_tip, CanonicalizationParams::default())
-        .balance(outpoints, |_, _| true, 1);
+        .balance(outpoints, |_, _| true, 0);
     Ok(balance)
 }
 

crates/chain/src/canonical_view.rs

@@ -60,12 +60,12 @@ pub struct CanonicalTx<A> {
 /// provides methods to query transaction data, unspent outputs, and balances.
 ///
 /// The view maintains:
-/// - An ordered list of canonical transactions (WIP)
+/// - An ordered list of canonical transactions in topological-spending order
 /// - A mapping of outpoints to the transactions that spend them
 /// - The chain tip used for canonicalization
 #[derive(Debug)]
 pub struct CanonicalView<A> {
-    /// Ordered list of transaction IDs in canonical order.
+    /// Ordered list of transaction IDs in topological-spending order.
     order: Vec<Txid>,
     /// Map of transaction IDs to their transaction data and chain position.
     txs: HashMap<Txid, (Arc<Transaction>, ChainPosition<A>)>,
@@ -119,7 +119,7 @@ impl<A: Anchor> CanonicalView<A> {
         };
 
         for r in CanonicalIter::new(tx_graph, chain, chain_tip, params) {
-            let (txid, tx, why) = r?;
+            let (txid, tx, reason) = r?;
 
             let tx_node = match tx_graph.get_tx_node(txid) {
                 Some(tx_node) => tx_node,
@@ -137,7 +137,7 @@ impl<A: Anchor> CanonicalView<A> {
                     .extend(tx.input.iter().map(|txin| (txin.previous_output, txid)));
             }
 
-            let pos = match why {
+            let pos = match reason {
                 CanonicalReason::Assumed { descendant } => match descendant {
                     Some(_) => match find_direct_anchor(&tx_node, chain, chain_tip)? {
                         Some(anchor) => ChainPosition::Confirmed {
@@ -189,8 +189,8 @@ impl<A: Anchor> CanonicalView<A> {
 
     /// Get a single canonical transaction by its transaction ID.
     ///
-    /// Returns `Some(CanonicalViewTx)` if the transaction exists in the canonical view,
-    /// or `None` if the transaction doesn't exist or was excluded due to conflicts.
+    /// Returns `Some(CanonicalTx)` if the transaction exists in the canonical view,
+    /// or `None` if it doesn't exist.
     pub fn tx(&self, txid: Txid) -> Option<CanonicalTx<A>> {
         self.txs
             .get(&txid)
@@ -206,7 +206,6 @@ impl<A: Anchor> CanonicalView<A> {
     /// Returns `None` if:
     /// - The transaction doesn't exist in the canonical view
     /// - The output index is out of bounds
-    /// - The transaction was excluded due to conflicts
     pub fn txout(&self, op: OutPoint) -> Option<FullTxOut<A>> {
         let (tx, pos) = self.txs.get(&op.txid)?;
         let vout: usize = op.vout.try_into().ok()?;
@@ -226,8 +225,9 @@ impl<A: Anchor> CanonicalView<A> {
 
     /// Get an iterator over all canonical transactions in order.
     ///
-    /// Transactions are returned in canonical order, with confirmed transactions ordered by
-    /// block height and position, followed by unconfirmed transactions.
+    /// Transactions are returned in topological-spending order, where ancestors appear before
+    /// their descendants (i.e., transactions that spend outputs come after the transactions
+    /// that create those outputs).
     ///
     /// # Example
     ///
@@ -326,16 +326,14 @@ impl<A: Anchor> CanonicalView<A> {
     /// * `trust_predicate` - Function that returns `true` for trusted scripts. Trusted outputs
     ///   count toward `trusted_pending` balance, while untrusted ones count toward
     ///   `untrusted_pending`
-    /// * `min_confirmations` - Minimum confirmations required for an output to be considered
-    ///   confirmed. Outputs with fewer confirmations are treated as pending.
+    /// * `additional_confirmations` - Additional confirmations required beyond the first one.
+    ///   Outputs with fewer than (1 + additional_confirmations) are treated as pending.
     ///
-    /// # Minimum Confirmations
+    /// # Additional Confirmations
     ///
-    /// The `min_confirmations` parameter controls when outputs are considered confirmed. A
-    /// `min_confirmations` value of `0` is equivalent to `1` (require at least 1 confirmation).
-    ///
-    /// Outputs with fewer than `min_confirmations` are categorized as pending (trusted or
-    /// untrusted based on the trust predicate).
+    /// The `additional_confirmations` parameter specifies how many confirmations beyond the
+    /// first one are required. For example, `additional_confirmations = 5` means 6 total
+    /// confirmations are required (1 + 5).
     ///
     /// # Example
     ///
@@ -351,14 +349,14 @@ impl<A: Anchor> CanonicalView<A> {
     /// let balance = view.balance(
     ///     indexer.outpoints().into_iter().map(|(k, op)| (k.clone(), *op)),
     ///     |_keychain, _script| true,  // Trust all outputs
-    ///     6,  // Require 6 confirmations
+    ///     5,  // Require 6 confirmations (1 + 5)
     /// );
     /// ```
     pub fn balance<'v, O: Clone + 'v>(
         &'v self,
         outpoints: impl IntoIterator<Item = (O, OutPoint)> + 'v,
         mut trust_predicate: impl FnMut(&O, ScriptBuf) -> bool,
-        min_confirmations: u32,
+        additional_confirmations: u32,
     ) -> Balance {
         let mut immature = Amount::ZERO;
         let mut trusted_pending = Amount::ZERO;
@@ -374,9 +372,9 @@ impl<A: Anchor> CanonicalView<A> {
                         .height
                         .saturating_sub(confirmation_height)
                         .saturating_add(1);
-                    let min_confirmations = min_confirmations.max(1); // 0 and 1 behave identically
+                    let required_confirmations = 1 + additional_confirmations;
 
-                    if confirmations < min_confirmations {
+                    if confirmations < required_confirmations {
                         // Not enough confirmations, treat as trusted/untrusted pending
                         if trust_predicate(&spk_i, txout.txout.script_pubkey) {
                             trusted_pending += txout.txout.value;

crates/chain/tests/test_canonical_view.rs

@@ -2,28 +2,28 @@
 
 use bdk_chain::{local_chain::LocalChain, CanonicalizationParams, ConfirmationBlockTime, TxGraph};
 use bdk_testenv::{hash, utils::new_tx};
-use bitcoin::{Amount, OutPoint, ScriptBuf, Transaction, TxIn, TxOut};
+use bitcoin::{Amount, BlockHash, OutPoint, ScriptBuf, Transaction, TxIn, TxOut};
+use std::collections::BTreeMap;
 
 #[test]
-fn test_min_confirmations_parameter() {
+fn test_additional_confirmations_parameter() {
     // Create a local chain with several blocks
-    let chain = LocalChain::from_blocks(
-        [
-            (0, hash!("block0")),
-            (1, hash!("block1")),
-            (2, hash!("block2")),
-            (3, hash!("block3")),
-            (4, hash!("block4")),
-            (5, hash!("block5")),
-            (6, hash!("block6")),
-            (7, hash!("block7")),
-            (8, hash!("block8")),
-            (9, hash!("block9")),
-            (10, hash!("block10")),
-        ]
-        .into(),
-    )
-    .unwrap();
+    let blocks: BTreeMap<u32, BlockHash> = [
+        (0, hash!("block0")),
+        (1, hash!("block1")),
+        (2, hash!("block2")),
+        (3, hash!("block3")),
+        (4, hash!("block4")),
+        (5, hash!("block5")),
+        (6, hash!("block6")),
+        (7, hash!("block7")),
+        (8, hash!("block8")),
+        (9, hash!("block9")),
+        (10, hash!("block10")),
+    ]
+    .into_iter()
+    .collect();
+    let chain = LocalChain::from_blocks(blocks).unwrap();
 
     let mut tx_graph = TxGraph::default();
 
@@ -56,65 +56,63 @@ fn test_min_confirmations_parameter() {
     let canonical_view =
         tx_graph.canonical_view(&chain, chain_tip, CanonicalizationParams::default());
 
-    // Test min_confirmations = 1: Should be confirmed (has 6 confirmations)
+    // Test additional_confirmations = 0: Should be confirmed (has 6 confirmations, needs 1)
     let balance_1_conf = canonical_view.balance(
         [((), outpoint)],
         |_, _| true, // trust all
-        1,
+        0,
     );
 
     assert_eq!(balance_1_conf.confirmed, Amount::from_sat(50_000));
     assert_eq!(balance_1_conf.trusted_pending, Amount::ZERO);
 
-    // Test min_confirmations = 6: Should be confirmed (has exactly 6 confirmations)
+    // Test additional_confirmations = 5: Should be confirmed (has 6 confirmations, needs 6)
     let balance_6_conf = canonical_view.balance(
         [((), outpoint)],
         |_, _| true, // trust all
-        6,
+        5,
     );
     assert_eq!(balance_6_conf.confirmed, Amount::from_sat(50_000));
     assert_eq!(balance_6_conf.trusted_pending, Amount::ZERO);
 
-    // Test min_confirmations = 7: Should be trusted pending (only has 6 confirmations)
+    // Test additional_confirmations = 6: Should be trusted pending (has 6 confirmations, needs 7)
     let balance_7_conf = canonical_view.balance(
         [((), outpoint)],
         |_, _| true, // trust all
-        7,
+        6,
     );
     assert_eq!(balance_7_conf.confirmed, Amount::ZERO);
     assert_eq!(balance_7_conf.trusted_pending, Amount::from_sat(50_000));
 
-    // Test min_confirmations = 0: Should behave same as 1 (confirmed)
+    // Test additional_confirmations = 0: Should be confirmed
     let balance_0_conf = canonical_view.balance(
         [((), outpoint)],
         |_, _| true, // trust all
         0,
     );
     assert_eq!(balance_0_conf.confirmed, Amount::from_sat(50_000));
     assert_eq!(balance_0_conf.trusted_pending, Amount::ZERO);
-    assert_eq!(balance_0_conf, balance_1_conf);
 }
 
 #[test]
-fn test_min_confirmations_with_untrusted_tx() {
+fn test_additional_confirmations_with_untrusted_tx() {
     // Create a local chain
-    let chain = LocalChain::from_blocks(
-        [
-            (0, hash!("genesis")),
-            (1, hash!("b1")),
-            (2, hash!("b2")),
-            (3, hash!("b3")),
-            (4, hash!("b4")),
-            (5, hash!("b5")),
-            (6, hash!("b6")),
-            (7, hash!("b7")),
-            (8, hash!("b8")),
-            (9, hash!("b9")),
-            (10, hash!("tip")),
-        ]
-        .into(),
-    )
-    .unwrap();
+    let blocks: BTreeMap<u32, BlockHash> = [
+        (0, hash!("genesis")),
+        (1, hash!("b1")),
+        (2, hash!("b2")),
+        (3, hash!("b3")),
+        (4, hash!("b4")),
+        (5, hash!("b5")),
+        (6, hash!("b6")),
+        (7, hash!("b7")),
+        (8, hash!("b8")),
+        (9, hash!("b9")),
+        (10, hash!("tip")),
+    ]
+    .into_iter()
+    .collect();
+    let chain = LocalChain::from_blocks(blocks).unwrap();
 
     let mut tx_graph = TxGraph::default();
 
@@ -148,11 +146,11 @@ fn test_min_confirmations_with_untrusted_tx() {
         CanonicalizationParams::default(),
     );
 
-    // Test with min_confirmations = 5 and untrusted predicate
+    // Test with additional_confirmations = 4 and untrusted predicate (requires 5 total)
     let balance = canonical_view.balance(
         [((), outpoint)],
         |_, _| false, // don't trust
-        5,
+        4,
     );
 
     // Should be untrusted pending (not enough confirmations and not trusted)
@@ -162,30 +160,29 @@ fn test_min_confirmations_with_untrusted_tx() {
 }
 
 #[test]
-fn test_min_confirmations_multiple_transactions() {
+fn test_additional_confirmations_multiple_transactions() {
     // Create a local chain
-    let chain = LocalChain::from_blocks(
-        [
-            (0, hash!("genesis")),
-            (1, hash!("b1")),
-            (2, hash!("b2")),
-            (3, hash!("b3")),
-            (4, hash!("b4")),
-            (5, hash!("b5")),
-            (6, hash!("b6")),
-            (7, hash!("b7")),
-            (8, hash!("b8")),
-            (9, hash!("b9")),
-            (10, hash!("b10")),
-            (11, hash!("b11")),
-            (12, hash!("b12")),
-            (13, hash!("b13")),
-            (14, hash!("b14")),
-            (15, hash!("tip")),
-        ]
-        .into(),
-    )
-    .unwrap();
+    let blocks: BTreeMap<u32, BlockHash> = [
+        (0, hash!("genesis")),
+        (1, hash!("b1")),
+        (2, hash!("b2")),
+        (3, hash!("b3")),
+        (4, hash!("b4")),
+        (5, hash!("b5")),
+        (6, hash!("b6")),
+        (7, hash!("b7")),
+        (8, hash!("b8")),
+        (9, hash!("b9")),
+        (10, hash!("b10")),
+        (11, hash!("b11")),
+        (12, hash!("b12")),
+        (13, hash!("b13")),
+        (14, hash!("b14")),
+        (15, hash!("tip")),
+    ]
+    .into_iter()
+    .collect();
+    let chain = LocalChain::from_blocks(blocks).unwrap();
 
     let mut tx_graph = TxGraph::default();
 
@@ -270,11 +267,11 @@ fn test_min_confirmations_multiple_transactions() {
         CanonicalizationParams::default(),
     );
 
-    // Test with min_confirmations = 5
+    // Test with additional_confirmations = 4 (requires 5 total)
     // tx0: 11 confirmations -> confirmed
     // tx1: 6 confirmations -> confirmed
     // tx2: 3 confirmations -> trusted pending
-    let balance = canonical_view.balance(outpoints.clone(), |_, _| true, 5);
+    let balance = canonical_view.balance(outpoints.clone(), |_, _| true, 4);
 
     assert_eq!(
         balance.confirmed,
@@ -286,11 +283,11 @@ fn test_min_confirmations_multiple_transactions() {
     );
     assert_eq!(balance.untrusted_pending, Amount::ZERO);
 
-    // Test with min_confirmations = 10
+    // Test with additional_confirmations = 9 (requires 10 total)
     // tx0: 11 confirmations -> confirmed
     // tx1: 6 confirmations -> trusted pending
     // tx2: 3 confirmations -> trusted pending
-    let balance_high = canonical_view.balance(outpoints, |_, _| true, 10);
+    let balance_high = canonical_view.balance(outpoints, |_, _| true, 9);
 
     assert_eq!(
         balance_high.confirmed,

crates/chain/tests/test_indexed_tx_graph.rs

@@ -474,7 +474,7 @@ fn test_list_owned_txouts() {
                 .balance(
                     graph.index.outpoints().iter().cloned(),
                     |_, spk: ScriptBuf| trusted_spks.contains(&spk),
-                    1,
+                    0,
                 );
 
             let confirmed_txouts_txid = txouts

crates/electrum/tests/test_electrum.rs

@@ -42,7 +42,7 @@ fn get_balance(
     let outpoints = recv_graph.index.outpoints().clone();
     let balance = recv_graph
         .canonical_view(recv_chain, chain_tip, CanonicalizationParams::default())
-        .balance(outpoints, |_, _| true, 1);
+        .balance(outpoints, |_, _| true, 0);
     Ok(balance)
 }
 

examples/example_bitcoind_rpc_polling/src/main.rs

@@ -205,7 +205,7 @@ fn main() -> anyhow::Result<()> {
                             .balance(
                                 graph.index.outpoints().iter().cloned(),
                                 |(k, _), _| k == &Keychain::Internal,
-                                1,
+                                0,
                             )
                     };
                     println!(
@@ -365,7 +365,7 @@ fn main() -> anyhow::Result<()> {
                             .balance(
                                 graph.index.outpoints().iter().cloned(),
                                 |(k, _), _| k == &Keychain::Internal,
-                                1,
+                                0,
                             )
                     };
                     println!(