feat(chain): variable block confirmation for confirmed balances

Author: LagginTimes

crates/chain/src/canonical_iter.rs

@@ -12,17 +12,35 @@ type CanonicalMap<A> = HashMap<Txid, (Arc<Transaction>, CanonicalReason<A>)>;
 type NotCanonicalSet = HashSet<Txid>;
 
 /// Modifies the canonicalization algorithm.
-#[derive(Debug, Default, Clone)]
+#[derive(Debug, Clone)]
 pub struct CanonicalizationParams {
     /// Transactions that will supercede all other transactions.
     ///
     /// In case of conflicting transactions within `assume_canonical`, transactions that appear
     /// later in the list (have higher index) have precedence.
     pub assume_canonical: Vec<Txid>,
+
+    /// Minimum confirmations for a transaction to count as confirmed.
+    ///
+    /// A value of `Some(6)` means only transactions with 6+ confirmations will be included in the
+    /// `ChainPosition::Confirmed` bucket of the `Balance`. `None` means default to 1-confirmation
+    /// behavior.
+    pub min_confirmations: Option<u32>,
+}
+
+impl Default for CanonicalizationParams {
+    fn default() -> Self {
+        Self {
+            assume_canonical: vec![],
+            min_confirmations: Some(1),
+        }
+    }
 }
 
 /// Iterates over canonical txs.
 pub struct CanonicalIter<'g, A, C> {
+    params: CanonicalizationParams,
+
     tx_graph: &'g TxGraph<A>,
     chain: &'g C,
     chain_tip: BlockId,
@@ -50,6 +68,7 @@ impl<'g, A: Anchor, C: ChainOracle> CanonicalIter<'g, A, C> {
         let anchors = tx_graph.all_anchors();
         let unprocessed_assumed_txs = Box::new(
             params
+                .clone()
                 .assume_canonical
                 .into_iter()
                 .rev()
@@ -66,6 +85,7 @@ impl<'g, A: Anchor, C: ChainOracle> CanonicalIter<'g, A, C> {
                 .filter_map(|(last_seen, txid)| Some((txid, tx_graph.get_tx(txid)?, last_seen))),
         );
         Self {
+            params,
             tx_graph,
             chain,
             chain_tip,
@@ -96,6 +116,16 @@ impl<'g, A: Anchor, C: ChainOracle> CanonicalIter<'g, A, C> {
                 .chain
                 .is_block_in_chain(anchor.anchor_block(), self.chain_tip)?;
             if in_chain_opt == Some(true) {
+                if let Some(min_conf) = self.params.min_confirmations {
+                    let confirmed_depth = self
+                        .chain_tip
+                        .height
+                        .saturating_sub(anchor.anchor_block().height)
+                        + 1;
+                    if confirmed_depth < min_conf {
+                        return Ok(());
+                    }
+                }
                 self.mark_canonical(txid, tx, CanonicalReason::from_anchor(anchor.clone()));
                 return Ok(());
             }

crates/chain/src/tx_graph.rs

@@ -1284,13 +1284,23 @@ impl<A: Anchor> TxGraph<A> {
         let mut untrusted_pending = Amount::ZERO;
         let mut confirmed = Amount::ZERO;
 
-        for (spk_i, txout) in self.try_filter_chain_unspents(chain, chain_tip, params, outpoints)? {
+        for (spk_i, txout) in
+            self.try_filter_chain_unspents(chain, chain_tip, params.clone(), outpoints)?
+        {
             match &txout.chain_position {
-                ChainPosition::Confirmed { .. } => {
-                    if txout.is_confirmed_and_spendable(chain_tip.height) {
-                        confirmed += txout.txout.value;
-                    } else if !txout.is_mature(chain_tip.height) {
-                        immature += txout.txout.value;
+                ChainPosition::Confirmed { anchor, .. } => {
+                    let min_confs = params.min_confirmations.unwrap_or(1);
+                    let confirmed_depth = chain_tip
+                        .height
+                        .saturating_sub(anchor.anchor_block().height)
+                        + 1;
+
+                    if confirmed_depth >= min_confs {
+                        if txout.is_confirmed_and_spendable(chain_tip.height) {
+                            confirmed += txout.txout.value;
+                        } else if !txout.is_mature(chain_tip.height) {
+                            immature += txout.txout.value;
+                        }
                     }
                 }
                 ChainPosition::Unconfirmed { .. } => {

crates/chain/tests/test_indexed_tx_graph.rs

@@ -705,3 +705,93 @@ fn test_get_chain_position() {
     .into_iter()
     .for_each(|t| run(&chain, &mut graph, t));
 }
+
+#[test]
+fn test_balance_min_confirmations() {
+    use bdk_chain::spk_txout::SpkTxOutIndex;
+
+    let spk = ScriptBuf::from_hex("0014c692ecf13534982a9a2834565cbd37add8027140").unwrap();
+    let mut graph = IndexedTxGraph::new({
+        let mut index = SpkTxOutIndex::default();
+        let _ = index.insert_spk(0u32, spk.clone());
+        index
+    });
+
+    let chain =
+        LocalChain::from_blocks((0..=15).map(|i| (i as u32, hash!("h"))).collect()).unwrap();
+
+    let coinbase_tx = Transaction {
+        input: vec![TxIn {
+            previous_output: OutPoint::null(),
+            ..Default::default()
+        }],
+        output: vec![TxOut {
+            value: Amount::from_sat(70000),
+            script_pubkey: spk.clone(),
+        }],
+        ..new_tx(0)
+    };
+
+    // Create a confirmed transaction with 6 confirmations.
+    let tx = Transaction {
+        input: vec![TxIn {
+            previous_output: OutPoint::new(coinbase_tx.compute_txid(), 0),
+            ..Default::default()
+        }],
+        output: vec![TxOut {
+            value: Amount::from_sat(42_000),
+            script_pubkey: spk.clone(),
+        }],
+        ..new_tx(1)
+    };
+    let txid = tx.compute_txid();
+
+    let _ = graph.insert_tx(tx.clone());
+    let _ = graph.insert_anchor(
+        txid,
+        ConfirmationBlockTime {
+            block_id: chain.get(10).unwrap().block_id(),
+            confirmation_time: 123456,
+        },
+    );
+
+    let tip = chain.get(15).unwrap().block_id();
+    let trust_predicate = |_: &(), s: ScriptBuf| s == spk;
+
+    let balance_at_1 = graph.graph().balance(
+        &chain,
+        tip,
+        CanonicalizationParams {
+            min_confirmations: Some(1),
+            ..Default::default()
+        },
+        std::iter::once(((), OutPoint::new(txid, 0))),
+        trust_predicate,
+    );
+
+    let balance_at_6 = graph.graph().balance(
+        &chain,
+        tip,
+        CanonicalizationParams {
+            min_confirmations: Some(6),
+            ..Default::default()
+        },
+        std::iter::once(((), OutPoint::new(txid, 0))),
+        trust_predicate,
+    );
+
+    let balance_at_7 = graph.graph().balance(
+        &chain,
+        tip,
+        CanonicalizationParams {
+            min_confirmations: Some(7),
+            ..Default::default()
+        },
+        std::iter::once(((), OutPoint::new(txid, 0))),
+        trust_predicate,
+    );
+
+    assert_eq!(balance_at_1.confirmed, Amount::from_sat(42_000));
+    assert_eq!(balance_at_6.confirmed, Amount::from_sat(42_000));
+    assert_eq!(balance_at_7.confirmed, Amount::from_sat(0));
+}

crates/chain/tests/test_tx_graph.rs

@@ -1540,3 +1540,94 @@ fn test_get_first_seen_of_a_tx() {
     let first_seen = graph.get_tx_node(txid).unwrap().first_seen;
     assert_eq!(first_seen, Some(seen_at));
 }
+
+#[test]
+fn test_min_confirmations() {
+    // Create LocalChain with height 100.
+    let local_chain = LocalChain::from_blocks(
+        (0..=100)
+            .map(|ht| (ht, BlockHash::hash(format!("Block Hash {ht}").as_bytes())))
+            .collect(),
+    )
+    .expect("must have genesis hash");
+    let tip = local_chain.tip();
+
+    let mut graph = TxGraph::<ConfirmationBlockTime>::default();
+
+    // Create tx with six confirmations at height 95.
+    let tx_6conf = Transaction {
+        input: vec![],
+        output: vec![TxOut {
+            value: Amount::from_sat(10_000),
+            script_pubkey: ScriptBuf::new(),
+        }],
+        ..new_tx(0)
+    };
+    let txid_6conf = tx_6conf.compute_txid();
+    let _ = graph.insert_tx(tx_6conf.clone());
+    let _ = graph.insert_anchor(
+        txid_6conf,
+        ConfirmationBlockTime {
+            block_id: tip.get(95).unwrap().block_id(),
+            confirmation_time: 123456,
+        },
+    );
+
+    // Create tx with two confirmations at height 99.
+    let tx_2conf = Transaction {
+        input: vec![],
+        output: vec![TxOut {
+            value: Amount::from_sat(20_000),
+            script_pubkey: ScriptBuf::new(),
+        }],
+        ..new_tx(1)
+    };
+    let txid_2conf = tx_2conf.compute_txid();
+    let _ = graph.insert_tx(tx_2conf.clone());
+    let _ = graph.insert_anchor(
+        txid_2conf,
+        ConfirmationBlockTime {
+            block_id: tip.get(99).unwrap().block_id(),
+            confirmation_time: 123457,
+        },
+    );
+
+    let build_confirmed_txouts = |min_conf: Option<u32>| -> HashMap<OutPoint, Amount> {
+        graph
+            .filter_chain_txouts(
+                &local_chain,
+                tip.block_id(),
+                CanonicalizationParams {
+                    min_confirmations: min_conf,
+                    ..Default::default()
+                },
+                graph.all_txouts().map(|(op, _)| ((), op)),
+            )
+            .filter_map(|(_, full)| {
+                if full.spent_by.is_none() {
+                    Some((full.outpoint, full.txout.value))
+                } else {
+                    None
+                }
+            })
+            .collect()
+    };
+
+    // Test case 1: require the default 1 confirmation.
+    let all = build_confirmed_txouts(None);
+    assert_eq!(all.len(), 2);
+    assert_eq!(all[&OutPoint::new(txid_6conf, 0)], Amount::from_sat(10_000));
+    assert_eq!(all[&OutPoint::new(txid_2conf, 0)], Amount::from_sat(20_000));
+
+    // Test case 2: require 3 confirmations, with only tx_6conf surviving.
+    let filtered = build_confirmed_txouts(Some(3));
+    assert_eq!(filtered.len(), 1);
+    assert_eq!(
+        filtered[&OutPoint::new(txid_6conf, 0)],
+        Amount::from_sat(10_000)
+    );
+
+    // Test case 3: require 7 confirmations, with no tx surviving.
+    let none = build_confirmed_txouts(Some(7));
+    assert!(none.is_empty());
+}