refactor(chain,core)!: replace CanonicalIter with sans-IO CanonicalTask + ChainQuery trait

[oleonardolima]

fixes #1816

Description

Replaces the iterator-based CanonicalIter with a two-phase sans-IO canonicalization pipeline, and introduces a generic ChainQuery trait in bdk_core to decouple canonicalization from chain sources.

Old API:

// Direct coupling between canonicalization logic and ChainOracle
let view = tx_graph.canonical_view(&chain, chain_tip, params)?;

New API:

// Option A: Two-phase (full control)
let canonical_txs = chain.canonicalize(tx_graph.canonical_task(tip, params));
let view = chain.canonicalize(canonical_txs.view_task(&tx_graph));

// Option B: Convenience method
let view = chain.canonical_view(&tx_graph, tip, params);

Phase 1: CanonicalTask

Determines which transactions are canonical by processing them in stages:

1. Assumed txs — transactions assumed canonical via CanonicalParams
2. Anchored txs — transactions anchored in the best chain (descending height)
3. Seen txs — unconfirmed transactions by descending last-seen time
4. Remaining txs — leftover anchored transactions not in the best chain

Produces a CanonicalTxs<A> containing each canonical transaction with its CanonicalReason.

Phase 2: CanonicalViewTask

Resolves CanonicalReasons into concrete ChainPositions (confirmed height or unconfirmed with last-seen), producing the final CanonicalView<A>.

Both phases implement the ChainQuery trait, so any chain source can drive them via the same next_query/resolve_query loop.

Key structural changes

• ChainQuery trait added to bdk_core — a generic sans-IO interface (next_query → resolve_query → finish) for any algorithm that needs to verify blocks against a chain source.
• ChainOracle trait removed — replaced by ChainQuery. LocalChain::canonicalize() now drives any ChainQuery implementor.
• Canonical<A, P> generic container — CanonicalTxs<A> (phase 1 output) and CanonicalView<A> (phase 2 output) are type aliases over Canonical<A, P>.
• Module split — canonical_view.rs split into canonical.rs (types: Canonical, CanonicalTx, CanonicalTxOut) and canonical_view_task.rs (phase 2 task). canonical_iter.rs replaced by canonical_task.rs.

Notes to the reviewers

The changes are split into multiple commits for easier review. Also depends on #2029.

Changelog notice

  ### Added
  - `bdk_core::ChainQuery` trait — generic sans-IO interface for chain verification queries
  - `bdk_core::ChainRequest` / `ChainResponse` type aliases
  - `CanonicalTask` — phase 1 sans-IO canonicalization (determines canonical txs)
  - `CanonicalViewTask` — phase 2 sans-IO canonicalization (resolves chain positions)
  - `Canonical<A, P>` generic container with `CanonicalTxs<A>` and `CanonicalView<A>` aliases
  - `LocalChain::canonicalize()` — drives any `ChainQuery` implementor
  - `LocalChain::canonical_view()` — convenience method for full two-phase canonicalization

  ### Changed
  - **Breaking:** Replace `TxGraph::canonical_iter()` / `TxGraph::canonical_view()` with `TxGraph::canonical_task()`
  - **Breaking:** Canonicalization now uses a two-phase sans-IO process via `ChainQuery`
  - **Breaking:** `ChainQuery`, `ChainRequest`, `ChainResponse` have no generics (use `BlockId` directly)
  - **Breaking:** Chain tip moved from `ChainRequest` to `ChainQuery::tip()`

  ### Removed
  - **Breaking:** `ChainOracle` trait and all implementations
  - **Breaking:** `CanonicalIter` type and `canonical_iter` module
  - **Breaking:** `TxGraph::try_canonical_view()` and `TxGraph::canonical_view()` methods
  - **Breaking:** `CanonicalView::new()` public constructor

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]

Great work.

This is my initial round of reviews.

Are you planning to introduce topological ordering in a separate PR?

[evanlinjin]

What do you think about the following naming:

• CanonicalizationTask -> CanonicalResolver.
• TxGraph::canonicalization_task -> TxGraph::resolver.
• LocalChain::canonicalize -> LocalChain::resolve.

[oleonardolima]

I've been thinking about this, I agree with the CanonicalResolver, though the TxGraph::resolver and LocalChain::resolve seems a bit off.

What do you think about (?):

• CanonicalResolver
• TxGraph::canonical_resolver
• LocalChain::canonical_resolve

[oleonardolima]

Alright, this one is a bit outdated.

As of 031de40 we have:

• CanonicalizationTask -> CanonicalTask; and also new CanonicalViewTask.
• TxGraph::canonicalization_task -> TxGraph::canonical_task.
• LocalChain::canonicalize is still the same, though we now also have LocalChain::canonical_view.

I'm fine with these names for now, though if there's no consensus on those we can discuss/change in a follow-up PR.

[evanlinjin]

Can we get rid of ChainOracle in the same PR?

Edit: Removed in 37eb136

[evanlinjin]

ACK 37eb136

[evanlinjin]

I've also updated the PR description.

[oleonardolima]

Can we get rid of ChainOracle in the same PR?

Edit: Removed in 37eb136

I'm fine with removing it in the same PR, thanks for the commit.

I've also updated the PR description.

Great, thank you!

[ValuedMammal]

You seem to be ignoring the descendant, but it may be the case that the descendant has a direct anchor, making this tx Confirmed transitively.

In case the reason is Assumed, to determine the ChainPosition you would want to:

• First look for a direct anchor of the current tx. If a direct anchor exists, the position must be Confirmed (and transitively None)
• Otherwise look at the descendant txid. If the descendant has a direct anchor, then the position is Confirmed transitively by the descendant's anchor
• If the descendant has no direct anchor, then the position is Unconfirmed. Likewise Unconfirmed if there's no anchor and no descendant

[nymius]

You seem to be ignoring the descendant, but it may be the case that the descendant has a direct anchor, making this tx Confirmed transitively.

I think this depends of the priority we give to the different CanonicalReasons. As it is expressed right now, CanonicalReason::Asumed has higher priority than the others.

In case the reason is Assumed, to determine the ChainPosition you would want to:

• First look for a direct anchor of the current tx. If a direct anchor exists, the position must be Confirmed (and transitively None)

In case we raise CanonicalReason::Anchor in the hierarchy, then is as easy as to make AssumedTxs also return a query for these txids.

• Otherwise look at the descendant txid. If the descendant has a direct anchor, then the position is Confirmed transitively by the descendant's anchor

Again, in case we raise CanonicalReason::Anchor in the hierarchy, this case is partially covered by mark_canonical when walking up the Ancestor queue:

            |_: usize, tx: Arc<Transaction>| -> Option<Txid> {
                let this_txid = tx.compute_txid();
                let this_reason = if is_starting_tx {
                    is_starting_tx = false;
                    reason.clone()
                } else {
                    // This is an ancestor being marked transitively
                    reason.to_transitive(starting_txid)
                };

                use crate::collections::hash_map::Entry;
                let canonical_entry = match self.canonical.entry(this_txid) {
                    // Already visited tx before, exit early.
                    Entry::Occupied(_) => return None, // Here we can compare and replace `CanonicalReason::Assumed` by `this_reason` if `this_reason` is `CanonicalReason::Anchor`. 
                    Entry::Vacant(entry) => entry,
                };

• If the descendant has no direct anchor, then the position is Unconfirmed. Likewise Unconfirmed if there's no anchor and no descendant

Are you proposing a different category here? Or with Unconfirmed you refer to CanonicalReason::Assumed?

[ValuedMammal]

Suggested change

	#[cfg(test)]
	#[cfg(test)]
	#[cfg_attr(coverage_nightly, coverage(off))]

[ValuedMammal]

The canonical task and the view task only differ in the stages of canonicalization they handle and the finished output. You should reduce this to a single task architecture. The rationale in 6d9a7d6 is to separate concerns, but it's really the same concern, canonicalizing the TxGraph into a consistent view. That'll prevent having the algorithm spread across multiple modules.

[nymius]

I agree with this, the canonicalization task doesn't have a meaning without the view task.

[ValuedMammal]

You could reuse the canonical view here for the remaining test assertions.