refactor(chain): add CanonicalView topological ordering

crates/chain/src/canonical.rs

@@ -169,7 +169,7 @@ impl<A: Anchor> CanonicalTxOut<ChainPosition<A>> {
 
 /// Canonical set of transactions from a [`TxGraph`].
 ///
-/// `Canonical` provides a conflict-resolved list of transactions. It determines
+/// `Canonical` provides an ordered, conflict-resolved set of transactions. It determines
 /// which transactions are canonical (non-conflicted) based on the current chain state and
 /// provides methods to query transaction data, unspent outputs, and balances.
 ///
@@ -179,14 +179,14 @@ impl<A: Anchor> CanonicalTxOut<ChainPosition<A>> {
 ///   [`CanonicalTxs`])
 ///
 /// The view maintains:
-/// - A list of canonical transactions
+/// - An ordered list of canonical transactions in topological-spending order
 /// - A mapping of outpoints to the transactions that spend them
 /// - The chain tip used for canonicalization
 ///
 /// [`TxGraph`]: crate::TxGraph
 #[derive(Debug)]
 pub struct Canonical<A, P> {
-    /// List of canonical transaction IDs.
+    /// Ordered list of transaction IDs in topological-spending order.
     pub(crate) order: Vec<Txid>,
     /// Map of transaction IDs to their transaction data and position.
     pub(crate) txs: HashMap<Txid, (Arc<Transaction>, P)>,

crates/chain/src/canonical_view_task.rs

@@ -1,7 +1,7 @@
 //! Phase 2 task: resolves canonical reasons into chain positions.
 
 use crate::canonical_task::{CanonicalReason, ObservedIn};
-use crate::collections::{HashMap, VecDeque};
+use crate::collections::{HashMap, HashSet, VecDeque};
 use crate::tx_graph::TxDescendants;
 use alloc::collections::BTreeSet;
 use alloc::sync::Arc;
@@ -88,6 +88,81 @@ impl<'g, A: Anchor> CanonicalViewTask<'g, A> {
     }
 }
 
+/// Topologically sort [`Txid`]s (parents before children) using Kahn's algorithm.
+///
+/// Given a set of canonical transactions and their spending relationships,
+/// returns a new ordering where for every spending relationship A -> B
+/// (where B spends an output of A), A appears before B.
+///
+/// The algorithm works in three phases:
+///
+/// 1. **Build the dependency graph**: Using the `spends` map, derive parent->child edges. Each
+///    `(outpoint, child_txid)` entry means `outpoint.txid` (the parent) must come before
+///    `child_txid`. Only edges where both parent and child are in the canonical set are considered.
+///
+/// 2. **Find roots**: [`Txid`]s with `in_degree == 0` have no canonical parents and can appear
+///    first. These seed the processing queue.
+///
+/// 3. **BFS traversal**: Dequeue a [`Txid`], append it to the result, and decrement the `in_degree`
+///    of each of its children. Whenever a child reaches `in_degree == 0`, all its parents have been
+///    placed, so it is enqueued.
+///
+/// # Note
+///
+/// The relative order among unrelated transactions (those with no spending
+/// relationship) is not guaranteed to be deterministic across runs, since
+/// it depends on `HashMap` iteration order.
+fn sort_topologically(order: &[Txid], spends: &HashMap<OutPoint, Txid>) -> Vec<Txid> {
+    // Set of canonical txids — we only consider parent→child edges where
+    // both sides are in this set.
+    let canonical_set: HashSet<Txid> = order.iter().copied().collect();
+
+    // in_degree[txid] tracks how many canonical parents this tx spends from.
+    // A tx with in_degree 0 has no canonical parents and can appear first.
+    let mut in_degree: HashMap<Txid, usize> = order.iter().map(|&txid| (txid, 0)).collect();
+
+    // Adjacency list: maps each parent txid to the children that spend its
+    // outputs. Derived from `spends` where each entry (outpoint → child_txid)
+    // gives us an edge from outpoint.txid (parent) to child_txid.
+    let mut children: HashMap<Txid, Vec<Txid>> = HashMap::new();
+
+    for (outpoint, &child) in spends {
+        let parent = outpoint.txid;
+        // Only consider edges where the parent is also canonical — spending
+        // from a tx outside this canonical set is not a dependency.
+        if canonical_set.contains(&parent) {
+            children.entry(parent).or_default().push(child);
+            *in_degree.entry(child).or_default() += 1;
+        }
+    }
+
+    // Seed the queue with root transactions (those with no canonical parents).
+    let mut queue: VecDeque<Txid> = in_degree
+        .iter()
+        .filter(|(_, &d)| d == 0)
+        .map(|(&txid, _)| txid)
+        .collect();
+
+    // Process the queue: each time we "remove" a tx from the graph, we
+    // decrement the in_degree of its children. When a child reaches
+    // in_degree 0, all its parents have been placed so it is ready.
+    let mut sorted = Vec::with_capacity(order.len());
+    while let Some(txid) = queue.pop_front() {
+        sorted.push(txid);
+        if let Some(deps) = children.get(&txid) {
+            for &child in deps {
+                let d = in_degree.get_mut(&child).unwrap();
+                *d -= 1;
+                if *d == 0 {
+                    queue.push_back(child);
+                }
+            }
+        }
+    }
+
+    sorted
+}
+
 impl<'g, A: Anchor> ChainQuery for CanonicalViewTask<'g, A> {
     type Output = CanonicalView<A>;
 
@@ -218,6 +293,7 @@ impl<'g, A: Anchor> ChainQuery for CanonicalViewTask<'g, A> {
             }
         }
 
+        let view_order = sort_topologically(&view_order, &self.spends);
         CanonicalView::new(self.tip, view_order, view_txs, self.spends)
     }
 }