docs(chain): note false-pending in CanonicalView::balance

An output confirmed transitively carries a descendant's anchor, so its
confirmation height may be an upper bound. An `is_settled` predicate
that requires a minimum number of confirmations may therefore make
`balance` count it as pending even though it has enough.

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

diff --git a/crates/chain/src/canonical.rs b/crates/chain/src/canonical.rs
index 98c1a4ca3a96c8a9e9ec2657605cd4ae3013d3bb..2f62b0f3e0707a56d1c75625f37ce6fd663dad4c 100644 (file)
--- a/crates/chain/src/canonical.rs
+++ b/crates/chain/src/canonical.rs
@@ -576,6 +576,14 @@ impl<A: Anchor> CanonicalView<A> {
     ///
     /// See `classify_outpoints` for `does_taint` and `is_settled` meaning.
     ///
+    /// The position of an output confirmed [`transitively`](ChainPosition::Confirmed::transitively)
+    /// carries a descendant's anchor, so its confirmation height may be an upper bound (see
+    /// [`confirmation_height_upper_bound`]). An `is_settled` that requires a minimum number of
+    /// confirmations may therefore count such an output as pending even though it actually has
+    /// enough.
+    ///
+    /// [`confirmation_height_upper_bound`]: ChainPosition::confirmation_height_upper_bound
+    ///
     /// # Example
     ///
     /// ```