From ecc74ce4cd1ab0c51c2e9bcaa4f7d53390dd4d9b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=BF=97=E5=AE=87?= <hello@evanlinjin.me>
Date: Sat, 22 Apr 2023 23:39:49 +0800
Subject: [PATCH] [bdk_chain_redesign] Docs for `is_mature` and
 `is_confirmed_and_spendable`

Docs are updated to explain why `is_mature` and
`is_confirmed_and_spendable` may return false-negatives.
---
 crates/chain/src/chain_data.rs | 35 +++++++++++++++++++---------------
 1 file changed, 20 insertions(+), 15 deletions(-)

diff --git a/crates/chain/src/chain_data.rs b/crates/chain/src/chain_data.rs
index e585d82d..a360b304 100644
--- a/crates/chain/src/chain_data.rs
+++ b/crates/chain/src/chain_data.rs
@@ -247,23 +247,25 @@ impl<A: Anchor> FullTxOut<ObservedAs<A>> {
     /// This is the alternative version of [`is_mature`] which depends on `chain_position` being a
     /// [`ObservedAs<A>`] where `A` implements [`Anchor`].
     ///
+    /// Depending on the implementation of [`confirmation_height_upper_bound`] in [`Anchor`], this
+    /// method may return false-negatives. In other words, interpretted confirmation count may be
+    /// less than the actual value.
+    ///
     /// [`is_mature`]: Self::is_mature
+    /// [`confirmation_height_upper_bound`]: Anchor::confirmation_height_upper_bound
     pub fn is_mature(&self, tip: u32) -> bool {
-        if !self.is_on_coinbase {
-            return true;
-        }
-
-        let tx_height = match &self.chain_position {
-            ObservedAs::Confirmed(anchor) => anchor.confirmation_height_upper_bound(),
-            ObservedAs::Unconfirmed(_) => {
-                debug_assert!(false, "coinbase tx can never be unconfirmed");
+        if self.is_on_coinbase {
+            let tx_height = match &self.chain_position {
+                ObservedAs::Confirmed(anchor) => anchor.confirmation_height_upper_bound(),
+                ObservedAs::Unconfirmed(_) => {
+                    debug_assert!(false, "coinbase tx can never be unconfirmed");
+                    return false;
+                }
+            };
+            let age = tip.saturating_sub(tx_height);
+            if age + 1 < COINBASE_MATURITY {
                 return false;
             }
-        };
-
-        let age = tip.saturating_sub(tx_height);
-        if age + 1 < COINBASE_MATURITY {
-            return false;
         }
 
         true
@@ -276,7 +278,12 @@ impl<A: Anchor> FullTxOut<ObservedAs<A>> {
     /// This is the alternative version of [`is_spendable_at`] which depends on `chain_position`
     /// being a [`ObservedAs<A>`] where `A` implements [`Anchor`].
     ///
+    /// Depending on the implementation of [`confirmation_height_upper_bound`] in [`Anchor`], this
+    /// method may return false-negatives. In other words, interpretted confirmation count may be
+    /// less than the actual value.
+    ///
     /// [`is_spendable_at`]: Self::is_spendable_at
+    /// [`confirmation_height_upper_bound`]: Anchor::confirmation_height_upper_bound
     pub fn is_confirmed_and_spendable(&self, tip: u32) -> bool {
         if !self.is_mature(tip) {
             return false;
@@ -300,5 +307,3 @@ impl<A: Anchor> FullTxOut<ObservedAs<A>> {
         true
     }
 }
-
-// TODO: make test