feat(chain): add new `list_ordered_canonical_txs` method #2027

oleonardolima · 2025-09-11T01:17:15Z

Description

It introduces a new method for topological ordering canonical transactions, list_ordered_canonical_txs. It now ensures the dependency-based transaction processing, guaranteeing that parent transactions always appears before their children transaction.

The existing list_canonical_txs and try_list_canonical_txs methods have been deprecated in favor of the new ordered version.

Notes to the reviewers

"[...] For those reviewing, and wondering why we don't have a fallible try version of this method, it's because we don't have a fallible ChainOracle implementation - we will get rid of ChainOracle trait soon anyway."

This PR is intended for a point release so that bdk_wallet 2.x users can get a topologically sorted list of transactions (we need a point release on bdk_wallet 2.x as well).

It might be useful to take a look at the new test scenarios that I've added, it shows some specific scenarios where the current implementation and output of canonical_txs didn't output the transactions in topological order.

Let me know if you think the TopologicalIter algorithm and/or API could be improved.

Changelog notice

#### Added
- New `list_ordered_canonical_txs` method to `TxGraph` that returns canonical transactions in topological order, ensuring parent transactions always appear before their children

#### Deprecated
- `list_canonical_txs` method - use `list_ordered_canonical_txs` instead for guaranteed topological ordering
- `try_list_canonical_txs` method - use `list_ordered_canonical_txs` instead for guaranteed topological ordering

Checklists

All Submissions:

I followed the contribution guidelines

New Features:

I've added tests for the new feature
I've added docs for the new feature

evanlinjin · 2025-09-11T03:09:28Z

Nice diagrams

crates/chain/src/canonical_iter.rs

evanlinjin

The internals have completely changed. I don't think a point release would make any sense (we also have already merged other breaking changes). I recommend to just break the API.

Get rid of CanonicalIter. Just have a single function that returns impl Iterator<Item = ...>.

crates/chain/src/canonical_iter.rs

oleonardolima · 2025-10-02T05:54:18Z

Looks good. Happy to ACK after we un-deprecate list_canonical_txs and update it's docs to point to list_ordered_canonical_txs.

Also, shouldn't this PR point to the chain-0.23.x branch?

Thanks, I've removed the deprecation in 9664402.

It's valid to note that before merging the release/chain-23.x branch needs to be updated and then this PR base should be updated as well. As it will be the same commit for this base, a rebase shouldn't be needed.

ValuedMammal · 2025-10-03T14:32:45Z

ACK 9c4da10

Tested locally, and I agree with the test expectations. No real opinion on deprecating list_canonical_txs. I looked for a way to rework CanonicalIter but realized it will be better to just add an extra layer of processing that does the topological sort.

ValuedMammal

Can we drop these commits which appear to have been included in #2061

0a33219 fix(example_cli): clippy warnings
377da74 fix(electrum): clippy warnings

oleonardolima · 2025-11-21T21:49:49Z

@evanlinjin I've addressed all the comments/nits, and it's ready for a final round of review. Let me know if you see anything else.

I improved the docs, commit messages, and also squashed some of them.

--

Can we drop these commits which appear to have been included in #2061

0a33219 fix(example_cli): clippy warnings

377da74 fix(electrum): clippy warnings

@ValuedMammal I fixed these through the rebase, but now I'll need to drop the new one d9a7c2c, but it depends on #2075 landing in release/chain-0.23.x

ValuedMammal

I'll give this another review.

outdated

- Add a new `test_list_ordered_canonical_txs`, to assert the topological spending order when yielding the list of canonical txs, it also adds a new helper `Scenario` structure, and `is_txs_in_topological_order`.

Adds a new `list_ordered_canonical_txs` method which uses the new `TopologicalIterator` on top of the result of `list_canonical_txs` method, yielding the canonical txs in topological spending order. The new `list_ordered_canonical_txs` guarantees that spending transactions appears after their inputs, in topological "spending order". - Introduce the new `TopologicalIterator` for level-based topological sorting, based on Kahn's Algorithm, it uses the `ChainPosition` for sorting within the same graph level, and it takes an `Iterator<Item = CanonicalTx<'a, Arc<Transaction>, A>> of canonical txs. - Introduce the new `list_ordered_canonical_txs` method to `TxGraph`. - Update the existing tests under `test_tx_graph.rs` to verify the topological ordering correctness. - Update the existing `canonicalization` benchmark to also use the new `topological_ordered_txs` method. NOTE: - I've squashed the previous commits into a single one, as they're changing the same files and applies to the same scope. - Also, I've partially used Claude to help with the Kahn's Algorithm. Co-Authored-By: Claude <noreply@anthropic.com>

outdated

ValuedMammal

ACK 12c1076

oleonardolima added this to the Wallet 3.0.0 milestone Sep 11, 2025

oleonardolima requested review from LLFourn and evanlinjin September 11, 2025 01:17

oleonardolima self-assigned this Sep 11, 2025

oleonardolima added tests module-blockchain labels Sep 11, 2025

oleonardolima added this to BDK Chain Sep 11, 2025

oleonardolima force-pushed the test/add-canonical-iter-topological-order-tests branch 2 times, most recently from 6b76092 to a28cfdf Compare September 11, 2025 03:07

oleonardolima force-pushed the test/add-canonical-iter-topological-order-tests branch 11 times, most recently from 08e4ce8 to 70ee41b Compare September 16, 2025 04:49

This comment was marked as outdated.

Sign in to view

oleonardolima force-pushed the test/add-canonical-iter-topological-order-tests branch 2 times, most recently from 6239c8f to 0aab769 Compare September 16, 2025 06:10

oleonardolima moved this to In Progress in BDK Chain Sep 16, 2025

evanlinjin reviewed Sep 18, 2025

View reviewed changes

crates/chain/src/canonical_iter.rs Outdated Show resolved Hide resolved

oleonardolima force-pushed the test/add-canonical-iter-topological-order-tests branch from d57a580 to 3b79cba Compare September 19, 2025 01:52

evanlinjin requested changes Sep 19, 2025

View reviewed changes

crates/chain/src/canonical_iter.rs Outdated Show resolved Hide resolved

crates/chain/src/canonical_iter.rs Outdated Show resolved Hide resolved

crates/chain/src/canonical_iter.rs Show resolved Hide resolved

crates/chain/src/canonical_iter.rs Outdated Show resolved Hide resolved

oleonardolima force-pushed the test/add-canonical-iter-topological-order-tests branch 2 times, most recently from 0a17091 to 71c3744 Compare September 23, 2025 04:20

ValuedMammal changed the base branch from release/chain-0.23.2 to release/chain-0.23.x October 3, 2025 23:28

ValuedMammal approved these changes Oct 3, 2025

View reviewed changes

oleonardolima requested a review from evanlinjin October 6, 2025 22:01

ValuedMammal previously requested changes Nov 6, 2025

View reviewed changes

ValuedMammal mentioned this pull request Nov 6, 2025

Release tracking chain-0.23.3 #2070

Open

3 tasks

oleonardolima force-pushed the test/add-canonical-iter-topological-order-tests branch from 9c4da10 to 6fd0de9 Compare November 21, 2025 18:59

oleonardolima mentioned this pull request Nov 21, 2025

chore(ci): pin proptest to 1.8.0 on 1.75.0 MSRV #2075

Merged

1 task

oleonardolima force-pushed the test/add-canonical-iter-topological-order-tests branch 7 times, most recently from b1294f5 to 37920a2 Compare November 21, 2025 21:37

oleonardolima requested a review from ValuedMammal November 21, 2025 21:49

ValuedMammal reviewed Nov 21, 2025

View reviewed changes

oleonardolima and others added 4 commits November 22, 2025 01:39

chore(docs): fix typo in docs

6cf720e

chore(test): rename txid_to_name to proper tx_name_to_txid

a201be0

test(chain): add test_list_ordered_canonical_txs

f34117b

- Add a new `test_list_ordered_canonical_txs`, to assert the topological spending order when yielding the list of canonical txs, it also adds a new helper `Scenario` structure, and `is_txs_in_topological_order`.

oleonardolima force-pushed the test/add-canonical-iter-topological-order-tests branch from 37920a2 to 12c1076 Compare November 22, 2025 04:40

ValuedMammal approved these changes Nov 22, 2025

View reviewed changes

ValuedMammal merged commit 1a77475 into bitcoindevkit:release/chain-0.23.x Nov 24, 2025
19 checks passed

github-project-automation bot moved this from Needs Review to Done in BDK Chain Nov 24, 2025

oleonardolima deleted the test/add-canonical-iter-topological-order-tests branch November 24, 2025 21:43

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(chain): add new `list_ordered_canonical_txs` method #2027

feat(chain): add new `list_ordered_canonical_txs` method #2027

Uh oh!

oleonardolima commented Sep 11, 2025 •

edited

Loading

Uh oh!

evanlinjin commented Sep 11, 2025

Uh oh!

This comment was marked as outdated.

Uh oh!

evanlinjin left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

oleonardolima commented Oct 2, 2025

Uh oh!

ValuedMammal commented Oct 3, 2025 •

edited

Loading

Uh oh!

ValuedMammal left a comment

Uh oh!

oleonardolima commented Nov 21, 2025

Uh oh!

ValuedMammal left a comment

Uh oh!

ValuedMammal left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat(chain): add new list_ordered_canonical_txs method #2027

feat(chain): add new list_ordered_canonical_txs method #2027

Uh oh!

Conversation

oleonardolima commented Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Notes to the reviewers

Changelog notice

Checklists

All Submissions:

New Features:

Uh oh!

evanlinjin commented Sep 11, 2025

Uh oh!

This comment was marked as outdated.

Uh oh!

evanlinjin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

oleonardolima commented Oct 2, 2025

Uh oh!

ValuedMammal commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ValuedMammal left a comment

Choose a reason for hiding this comment

Uh oh!

oleonardolima commented Nov 21, 2025

Uh oh!

ValuedMammal left a comment

Choose a reason for hiding this comment

Uh oh!

ValuedMammal left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat(chain): add new `list_ordered_canonical_txs` method #2027

feat(chain): add new `list_ordered_canonical_txs` method #2027

oleonardolima commented Sep 11, 2025 •

edited

Loading

ValuedMammal commented Oct 3, 2025 •

edited

Loading