From f444a8de391abb673b11ebd03e1a9b1cce570602 Mon Sep 17 00:00:00 2001
From: =?utf8?q?=E5=BF=97=E5=AE=87?= <hello@evanlinjin.me>
Date: Fri, 12 Sep 2025 06:11:28 +0000
Subject: [PATCH] refactor(chain)!: Rename `CanonicalViewTx` to `CanonicalTx`

Also update submodule-level docs for `tx_graph`'s Canonicalization
section.
---
 crates/chain/src/canonical_view.rs | 12 +++++-------
 crates/chain/src/tx_graph.rs       | 17 ++++++++---------
 2 files changed, 13 insertions(+), 16 deletions(-)

diff --git a/crates/chain/src/canonical_view.rs b/crates/chain/src/canonical_view.rs
index 83dfd421..c6b985e6 100644
--- a/crates/chain/src/canonical_view.rs
+++ b/crates/chain/src/canonical_view.rs
@@ -41,7 +41,7 @@ use crate::{
 /// conflicted). It includes the transaction itself along with its position in the chain (confirmed
 /// or unconfirmed).
 #[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
-pub struct CanonicalViewTx<A> {
+pub struct CanonicalTx<A> {
     /// The position of this transaction in the chain.
     ///
     /// This indicates whether the transaction is confirmed (and at what height) or
@@ -228,11 +228,11 @@ impl<A: Anchor> CanonicalView<A> {
     ///     println!("Found tx {} at position {:?}", canonical_tx.txid, canonical_tx.pos);
     /// }
     /// ```
-    pub fn tx(&self, txid: Txid) -> Option<CanonicalViewTx<A>> {
+    pub fn tx(&self, txid: Txid) -> Option<CanonicalTx<A>> {
         self.txs
             .get(&txid)
             .cloned()
-            .map(|(tx, pos)| CanonicalViewTx { pos, txid, tx })
+            .map(|(tx, pos)| CanonicalTx { pos, txid, tx })
     }
 
     /// Get a single canonical transaction output.
@@ -302,12 +302,10 @@ impl<A: Anchor> CanonicalView<A> {
     /// // Get the total number of canonical transactions
     /// println!("Total canonical transactions: {}", view.txs().len());
     /// ```
-    pub fn txs(
-        &self,
-    ) -> impl ExactSizeIterator<Item = CanonicalViewTx<A>> + DoubleEndedIterator + '_ {
+    pub fn txs(&self) -> impl ExactSizeIterator<Item = CanonicalTx<A>> + DoubleEndedIterator + '_ {
         self.order.iter().map(|&txid| {
             let (tx, pos) = self.txs[&txid].clone();
-            CanonicalViewTx { pos, txid, tx }
+            CanonicalTx { pos, txid, tx }
         })
     }
 
diff --git a/crates/chain/src/tx_graph.rs b/crates/chain/src/tx_graph.rs
index 01281029..97d4ecc0 100644
--- a/crates/chain/src/tx_graph.rs
+++ b/crates/chain/src/tx_graph.rs
@@ -21,15 +21,14 @@
 //! Conflicting transactions are allowed to coexist within a [`TxGraph`]. A process called
 //! canonicalization is required to get a conflict-free view of transactions.
 //!
-//! * [`list_canonical_txs`](TxGraph::list_canonical_txs) lists canonical transactions.
-//! * [`filter_chain_txouts`](TxGraph::filter_chain_txouts) filters out canonical outputs from a
-//!   list of outpoints.
-//! * [`filter_chain_unspents`](TxGraph::filter_chain_unspents) filters out canonical unspent
-//!   outputs from a list of outpoints.
-//! * [`balance`](TxGraph::balance) gets the total sum of unspent outputs filtered from a list of
-//!   outpoints.
-//! * [`canonical_iter`](TxGraph::canonical_iter) returns the [`CanonicalIter`] which contains all
-//!   of the canonicalization logic.
+//! * [`canonical_iter`](TxGraph::canonical_iter) returns a [`CanonicalIter`] which performs
+//!   incremental canonicalization. This is useful when you only need to check specific transactions
+//!   (e.g., verifying whether a few unconfirmed transactions are canonical) without computing the
+//!   entire canonical view.
+//! * [`canonical_view`](TxGraph::canonical_view) returns a [`CanonicalView`] which provides a
+//!   complete canonical view of the graph. This is required for typical wallet operations like
+//!   querying balances, listing outputs, transactions, and UTXOs. You must construct this first
+//!   before performing these operations.
 //!
 //! All these methods require a `chain` and `chain_tip` argument. The `chain` must be a
 //! [`ChainOracle`] implementation (such as [`LocalChain`](crate::local_chain::LocalChain)) which
-- 
2.49.0