doc: Improve TxGraph & co docs

crates/chain/src/chain_data.rs

@@ -147,6 +147,9 @@ impl From<(&u32, &BlockHash)> for BlockId {
 
 /// An [`Anchor`] implementation that also records the exact confirmation height of the transaction.
 ///
+/// Note that the confirmation block and the anchor block can be different here. If you
+/// know they're always going to be the same, you can use the [`BlockId`] anchor instead.
+///
 /// Refer to [`Anchor`] for more details.
 #[derive(Debug, Default, Clone, PartialEq, Eq, Copy, PartialOrd, Ord, core::hash::Hash)]
 #[cfg_attr(
@@ -186,6 +189,9 @@ impl AnchorFromBlockPosition for ConfirmationHeightAnchor {
 /// An [`Anchor`] implementation that also records the exact confirmation time and height of the
 /// transaction.
 ///
+/// Note that the confirmation block and the anchor block can be different here. If you
+/// know they're always going to be the same, you can use the [`BlockId`] anchor instead.
+///
 /// Refer to [`Anchor`] for more details.
 #[derive(Debug, Default, Clone, PartialEq, Eq, Copy, PartialOrd, Ord, core::hash::Hash)]
 #[cfg_attr(

crates/chain/src/chain_oracle.rs

@@ -3,7 +3,7 @@ use crate::BlockId;
 /// Represents a service that tracks the blockchain.
 ///
 /// The main method is [`is_block_in_chain`] which determines whether a given block of [`BlockId`]
-/// is an ancestor of another "static block".
+/// is an ancestor of the `chain_tip`.
 ///
 /// [`is_block_in_chain`]: Self::is_block_in_chain
 pub trait ChainOracle {

crates/chain/src/indexed_tx_graph.rs

@@ -1,6 +1,8 @@
-//! Contains the [`IndexedTxGraph`] structure and associated types.
+//! Contains the [`Indexer`] trait, the [`IndexedTxGraph`] structure,
+//! and the associated [`ChangeSet`].
 //!
-//! This is essentially a [`TxGraph`] combined with an indexer.
+//! The [`IndexedTxGraph`] is essentially a [`TxGraph`] combined with
+//! an implementation of the [`Indexer`] trait.
 
 use alloc::vec::Vec;
 use bitcoin::{Block, OutPoint, Transaction, TxOut, Txid};

crates/chain/src/lib.rs

@@ -12,9 +12,8 @@
 //!    you do it synchronously or asynchronously. If you know a fact about the blockchain, you can just
 //!    tell `bdk_chain`'s APIs about it, and that information will be integrated, if it can be done
 //!    consistently.
-//! 2. Error-free APIs.
-//! 3. Data persistence agnostic -- `bdk_chain` does not care where you cache on-chain data, what you
-//!    cache or how you fetch it.
+//! 2. Data persistence agnostic -- `bdk_chain` does not care where you cache on-chain data, what you
+//!    cache or how you retrieve it from persistence.
 //!
 //! [Bitcoin Dev Kit]: https://bitcoindevkit.org/
 

crates/chain/src/tx_data_traits.rs

@@ -5,21 +5,20 @@ use alloc::vec::Vec;
 
 /// Trait that "anchors" blockchain data to a specific block of height and hash.
 ///
-/// [`Anchor`] implementations must be [`Ord`] by the anchor block's [`BlockId`] first.
-///
-/// I.e. If transaction A is anchored in block B, then if block B is in the best chain, we can
+/// If transaction A is anchored in block B, then if block B is in the best chain, we can
 /// assume that transaction A is also confirmed in the best chain. This does not necessarily mean
 /// that transaction A is confirmed in block B. It could also mean transaction A is confirmed in a
 /// parent block of B.
 ///
+/// [`Anchor`] implementations must implement [`Ord`] by the anchor block's [`BlockId`] first.
+///
 /// ```
 /// # use bdk_chain::local_chain::LocalChain;
 /// # use bdk_chain::tx_graph::TxGraph;
 /// # use bdk_chain::BlockId;
 /// # use bdk_chain::ConfirmationHeightAnchor;
 /// # use bdk_chain::example_utils::*;
 /// # use bitcoin::hashes::Hash;
-///
 /// // Initialize the local chain with two blocks.
 /// let chain = LocalChain::from_blocks(
 ///     [

crates/chain/src/tx_graph.rs

@@ -1,12 +1,25 @@
 //! Module for structures that store and traverse transactions.
 //!
-//! [`TxGraph`] is a monotone structure that inserts transactions and indexes the spends. The
-//! [`ChangeSet`] structure reports changes of [`TxGraph`] but can also be applied to a
-//! [`TxGraph`] as well. Lastly, [`TxDescendants`] is an [`Iterator`] that traverses descendants of
-//! a given transaction.
+//! [`TxGraph`] is a monotone structure that contains transactions and indexes the spends. It can
+//! contain either full transactions, or partial transactions (transactions for which we have only
+//! certain outputs, which we usually call "floating outputs").
+//!
+//! The graph contains transactions in the form of [`TxNode`] structures. Each node contains the
+//! txid, the transaction (whole or partial), the blocks it's anchored in (see the [`Anchor`]
+//! documentation for more details), and the timestamp of the last time we saw
+//! the transaction as unconfirmed.
 //!
 //! Conflicting transactions are allowed to coexist within a [`TxGraph`]. This is useful for
-//! identifying and traversing conflicts and descendants of a given transaction.
+//! identifying and traversing conflicts and descendants of a given transaction. Some [`TxGraph`]
+//! methods only consider "canonical" (i.e., in the best chain or in mempool) transactions,
+//! we decide which transactions are canonical based on anchors `last_seen_unconfirmed`;
+//! see the [`try_get_chain_position`] documentation for more details.
+//!
+//! The [`ChangeSet`] structure reports changes of [`TxGraph`]; it can be used to either save to persistance,
+//! or to be applied to another [`TxGraph`].
+//!
+//! Lastly, you can use [`TxAncestors`]/[`TxDescendants`] to traverse ancestors and descendants of
+//! a given transaction.
 //!
 //! # Applying changes
 //!
@@ -49,6 +62,7 @@
 //! let changeset = graph.apply_update(update);
 //! assert!(changeset.is_empty());
 //! ```
+//! [`try_get_chain_position`]: TxGraph::try_get_chain_position
 
 use crate::{
     collections::*, keychain::Balance, local_chain::LocalChain, Anchor, Append, BlockId,
@@ -90,7 +104,7 @@ impl<A> Default for TxGraph<A> {
     }
 }
 
-/// An outward-facing view of a (transaction) node in the [`TxGraph`].
+/// A transaction node in the [`TxGraph`].
 #[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
 pub struct TxNode<'a, T, A> {
     /// Txid of the transaction.
@@ -127,7 +141,7 @@ impl Default for TxNodeInternal {
     }
 }
 
-/// An outwards-facing view of a transaction that is part of the *best chain*'s history.
+/// A transaction that is included in a certain chain.
 #[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
 pub struct CanonicalTx<'a, T, A> {
     /// How the transaction is observed as (confirmed or unconfirmed).
@@ -687,8 +701,20 @@ impl<A: Anchor> TxGraph<A> {
 
     /// Get the position of the transaction in `chain` with tip `chain_tip`.
     ///
-    /// If the given transaction of `txid` does not exist in the chain of `chain_tip`, `None` is
-    /// returned.
+    /// If the given `txid` does not exist in the chain of `chain_tip`, and
+    /// we believe that the transaction is not in mempool anymore, `None` is returned.
+    ///
+    /// We determine whether the transaction `tx` is in the mempool or not by looking at
+    /// tx's conflicting transactions, and tx's ancestors' conflicting transactions;
+    /// if in these transactions we find one which is anchored to a block in the best chain,
+    /// then `tx` can't be in mempool.
+    ///
+    /// Otherwise, we decide which transactions are in mempool based on their
+    /// `last_seen_unconfirmed`. We first of all calculate `tx`'s `max_last_seen_unconfirmed`,
+    /// which is the max `last_seen_unconfirmed` between `tx` and all its descendants.
+    /// We then look at all the conflicts of `tx`, and if all of them have
+    /// `last_seen_unconfirmed` < `max_last_seen_unconfirmed`, then we consider `tx` to be still
+    /// in mempool.
     ///
     /// # Error
     ///
@@ -714,7 +740,7 @@ impl<A: Anchor> TxGraph<A> {
             }
         }
 
-        // The tx is not anchored to a block which is in the best chain, which means that it
+        // The tx is not anchored to a block in the best chain, which means that it
         // might be in mempool, or it might have been dropped already.
         // Let's check conflicts to find out!
         let tx = match tx_node {
@@ -911,7 +937,8 @@ impl<A: Anchor> TxGraph<A> {
     /// (`OI`) for convenience. If `OI` is not necessary, the caller can use `()`, or
     /// [`Iterator::enumerate`] over a list of [`OutPoint`]s.
     ///
-    /// Floating outputs are ignored.
+    /// Floating outputs (i.e., outputs for which we don't have the full transaction in the graph)
+    /// are ignored.
     ///
     /// # Error
     ///