Merge #2007: docs(chain): add doctest for min confirmation balance filtering

657a044 docs(chain): add doctest for min confirmation balance filtering (Wei Chen)

Pull request description:

  Implements #1942.

  ### Description

  This PR adds a new doctest demonstrating how to simulate a minimum confirmation threshold for confirmed balance calculations by adjusting the `chain_tip` height passed to `TxGraph::balance`.

  ### Changelog notice

  - Added a doctest illustrating how to filter confirmed balance results by simulating a minimum confirmation threshold via `chain_tip` height.

  ### Checklists

  #### All Submissions:

  * [x] I followed the [contribution guidelines](https://github.com/bitcoindevkit/bdk/blob/master/CONTRIBUTING.md)

  #### New Features:

  * [x] I've added tests for the new feature
  * [x] I've added docs for the new feature

  #### Bugfixes:

  * [ ] This pull request breaks the existing API
  * [ ] I've added tests to reproduce the issue which are now passing
  * [x] I'm linking the issue being fixed by this PR

ACKs for top commit:
  oleonardolima:
    ACK 657a044
  evanlinjin:
    ACK 657a044

Tree-SHA512: 1c9514ee6cbf92df196b8e9295c81938cac4b822a7bc9703e93fabf79afaffd93d9d262bfdb74856774f1603d75b07a26cbfaefacc5a1336c8b214951458e2e1

Author: oleonardolima

crates/chain/src/tx_graph.rs

@@ -1315,6 +1315,69 @@ impl<A: Anchor> TxGraph<A> {
     ///
     /// This is the infallible version of [`try_balance`].
     ///
+    /// ### Minimum confirmations
+    ///
+    /// To filter for transactions with at least `N` confirmations, pass a `chain_tip` that is
+    /// `N - 1` blocks below the actual tip. This ensures that only transactions with at least `N`
+    /// confirmations are counted as confirmed in the returned [`Balance`].
+    ///
+    /// ```
+    /// # use bdk_chain::tx_graph::TxGraph;
+    /// # use bdk_chain::{local_chain::LocalChain, CanonicalizationParams, ConfirmationBlockTime};
+    /// # use bdk_testenv::{hash, utils::new_tx};
+    /// # use bitcoin::{Amount, OutPoint, ScriptBuf, Transaction, TxIn, TxOut};
+    ///
+    /// # let spk = ScriptBuf::from_hex("0014c692ecf13534982a9a2834565cbd37add8027140").unwrap();
+    /// # let chain =
+    /// #     LocalChain::from_blocks((0..=15).map(|i| (i as u32, hash!("h"))).collect()).unwrap();
+    /// # let mut graph: TxGraph = TxGraph::default();
+    /// # 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)
+    /// # };
+    /// # 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 minimum_confirmations = 6;
+    /// let target_tip = chain
+    ///     .tip()
+    ///     .floor_below(minimum_confirmations - 1)
+    ///     .expect("checkpoint from local chain must have genesis");
+    /// let balance = graph.balance(
+    ///     &chain,
+    ///     target_tip.block_id(),
+    ///     CanonicalizationParams::default(),
+    ///     std::iter::once(((), OutPoint::new(txid, 0))),
+    ///     |_: &(), _| true,
+    /// );
+    /// assert_eq!(balance.confirmed, Amount::from_sat(42_000));
+    /// ```
+    ///
     /// [`try_balance`]: Self::try_balance
     pub fn balance<C: ChainOracle<Error = Infallible>, OI: Clone>(
         &self,

crates/core/src/checkpoint.rs

@@ -192,6 +192,30 @@ impl CheckPoint {
             })
     }
 
+    /// Returns the checkpoint at `height` if one exists, otherwise the nearest checkpoint at a
+    /// lower height.
+    ///
+    /// This is equivalent to taking the "floor" of `height` over this checkpoint chain.
+    ///
+    /// Returns `None` if no checkpoint exists at or below the given height.
+    pub fn floor_at(&self, height: u32) -> Option<Self> {
+        self.range(..=height).next()
+    }
+
+    /// Returns the checkpoint located a number of heights below this one.
+    ///
+    /// This is a convenience wrapper for [`CheckPoint::floor_at`], subtracting `to_subtract` from
+    /// the current height.
+    ///
+    /// - If a checkpoint exists exactly `offset` heights below, it is returned.
+    /// - Otherwise, the nearest checkpoint *below that target height* is returned.
+    ///
+    /// Returns `None` if `to_subtract` is greater than the current height, or if there is no
+    /// checkpoint at or below the target height.
+    pub fn floor_below(&self, offset: u32) -> Option<Self> {
+        self.floor_at(self.height().checked_sub(offset)?)
+    }
+
     /// Inserts `block_id` at its height within the chain.
     ///
     /// The effect of `insert` depends on whether a height already exists. If it doesn't the