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

555f774 fix(chain): position resolution for assumed txs (Leonardo Lima)
4f10cde chore(chain,example)!: remove `ChainOracle`, update docs (志宇)
a3c73e4 refactor(chain)!: split `canonical_view` into `canonical`,`canonical_view_task` (志宇)
22b04c3 refactor(chain)!: split canonicalization into two tasks with generic `Canonical<A, P>` (志宇)
a9f5ca4 refactor(chain)!: remove `CanonicalIter` APIs (Leonardo Lima)
bb83da8 chore(workspace): use new `LocalChain::canonical_view` API (Leonardo Lima)
987da73 feat(core,chain): introduce `CanonicalizationTask` and `ChainQuery` (Leonardo Lima)

Pull request description:

  fixes bitcoindevkit#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:**
  ```rust
  // Direct coupling between canonicalization logic and ChainOracle
  let view = tx_graph.canonical_view(&chain, chain_tip, params)?;
  ```

  **New API:**
  ```rust
  // 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 `CanonicalReason`s into concrete `ChainPosition`s (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 bitcoindevkit#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:

  * [x] I followed the [contribution guidelines](https://github.com/bitcoindevkit/bdk/blob/master/CONTRIBUTING.md)

  #### New Features:

  * [x] I've added tests for the new feature
  * [x] I've added docs for the new feature

ACKs for top commit:
  evanlinjin:
    ACK 555f774

Tree-SHA512: ce466a623a1f8df20dedd3e4e68460892bd369567db44e6ba391c3d9ae1d10bca6204ebdcdb7b1376a9c97f3155b89e991846af4122e200d1fa15d998deb7830

Author: oleonardolima

crates/bitcoind_rpc/examples/filter_iter.rs

@@ -69,7 +69,8 @@ fn main() -> anyhow::Result<()> {
     println!("\ntook: {}s", start.elapsed().as_secs());
     println!("Local tip: {}", chain.tip().height());
 
-    let canonical_view = graph.canonical_view(&chain, chain.tip().block_id(), Default::default());
+    let canonical_view =
+        chain.canonical_view(graph.graph(), chain.tip().block_id(), Default::default());
 
     let unspent: Vec<_> = canonical_view
         .filter_unspent_outpoints(graph.index.outpoints().clone())

crates/bitcoind_rpc/tests/test_emitter.rs

@@ -5,7 +5,7 @@ use bdk_chain::{
     bitcoin::{Address, Amount, Txid},
     local_chain::{CheckPoint, LocalChain},
     spk_txout::SpkTxOutIndex,
-    Balance, BlockId, CanonicalizationParams, IndexedTxGraph, Merge,
+    Balance, BlockId, IndexedTxGraph, Merge,
 };
 use bdk_testenv::{
     anyhow,
@@ -318,11 +318,14 @@ fn get_balance(
     recv_chain: &LocalChain,
     recv_graph: &IndexedTxGraph<BlockId, SpkTxOutIndex<()>>,
 ) -> anyhow::Result<Balance> {
-    let chain_tip = recv_chain.tip().block_id();
     let outpoints = recv_graph.index.outpoints().clone();
-    let balance = recv_graph
-        .canonical_view(recv_chain, chain_tip, CanonicalizationParams::default())
-        .balance(outpoints, |_, _| true, 1);
+    let balance = recv_chain
+        .canonical_view(
+            recv_graph.graph(),
+            recv_chain.tip().block_id(),
+            Default::default(),
+        )
+        .balance(outpoints, |_, _| true, 0);
     Ok(balance)
 }
 
@@ -631,8 +634,8 @@ fn test_expect_tx_evicted() -> anyhow::Result<()> {
     let _txid_2 = core.send_raw_transaction(&tx1b)?;
 
     // Retrieve the expected unconfirmed txids and spks from the graph.
-    let exp_spk_txids = graph
-        .canonical_view(&chain, chain_tip, Default::default())
+    let exp_spk_txids = chain
+        .canonical_view(graph.graph(), chain_tip, Default::default())
         .list_expected_spk_txids(&graph.index, ..)
         .collect::<Vec<_>>();
     assert_eq!(exp_spk_txids, vec![(spk, txid_1)]);
@@ -647,8 +650,8 @@ fn test_expect_tx_evicted() -> anyhow::Result<()> {
     // Update graph with evicted tx.
     let _ = graph.batch_insert_relevant_evicted_at(mempool_event.evicted);
 
-    let canonical_txids = graph
-        .canonical_view(&chain, chain_tip, CanonicalizationParams::default())
+    let canonical_txids = chain
+        .canonical_view(graph.graph(), chain_tip, Default::default())
         .txs()
         .map(|tx| tx.txid)
         .collect::<Vec<_>>();

crates/chain/benches/canonicalization.rs

@@ -1,4 +1,3 @@
-use bdk_chain::CanonicalizationParams;
 use bdk_chain::{keychain_txout::KeychainTxOutIndex, local_chain::LocalChain, IndexedTxGraph};
 use bdk_core::{BlockId, CheckPoint};
 use bdk_core::{ConfirmationBlockTime, TxUpdate};
@@ -95,31 +94,19 @@ fn setup<F: Fn(&mut KeychainTxGraph, &LocalChain)>(f: F) -> (KeychainTxGraph, Lo
 }
 
 fn run_list_canonical_txs(tx_graph: &KeychainTxGraph, chain: &LocalChain, exp_txs: usize) {
-    let view = tx_graph.canonical_view(
-        chain,
-        chain.tip().block_id(),
-        CanonicalizationParams::default(),
-    );
+    let view = chain.canonical_view(tx_graph.graph(), chain.tip().block_id(), Default::default());
     let txs = view.txs();
     assert_eq!(txs.count(), exp_txs);
 }
 
 fn run_filter_chain_txouts(tx_graph: &KeychainTxGraph, chain: &LocalChain, exp_txos: usize) {
-    let view = tx_graph.canonical_view(
-        chain,
-        chain.tip().block_id(),
-        CanonicalizationParams::default(),
-    );
+    let view = chain.canonical_view(tx_graph.graph(), chain.tip().block_id(), Default::default());
     let utxos = view.filter_outpoints(tx_graph.index.outpoints().clone());
     assert_eq!(utxos.count(), exp_txos);
 }
 
 fn run_filter_chain_unspents(tx_graph: &KeychainTxGraph, chain: &LocalChain, exp_utxos: usize) {
-    let view = tx_graph.canonical_view(
-        chain,
-        chain.tip().block_id(),
-        CanonicalizationParams::default(),
-    );
+    let view = chain.canonical_view(tx_graph.graph(), chain.tip().block_id(), Default::default());
     let utxos = view.filter_unspent_outpoints(tx_graph.index.outpoints().clone());
     assert_eq!(utxos.count(), exp_utxos);
 }

crates/chain/benches/indexer.rs

@@ -1,7 +1,7 @@
 use bdk_chain::{
     keychain_txout::{InsertDescriptorError, KeychainTxOutIndex},
     local_chain::LocalChain,
-    CanonicalizationParams, IndexedTxGraph,
+    IndexedTxGraph,
 };
 use bdk_core::{BlockId, CheckPoint, ConfirmationBlockTime, TxUpdate};
 use bitcoin::{
@@ -82,10 +82,9 @@ fn do_bench(indexed_tx_graph: &KeychainTxGraph, chain: &LocalChain) {
         .unwrap();
 
     // Check balance
-    let chain_tip = chain.tip().block_id();
     let op = graph.index.outpoints().clone();
-    let bal = graph
-        .canonical_view(chain, chain_tip, CanonicalizationParams::default())
+    let bal = chain
+        .canonical_view(graph.graph(), chain.tip().block_id(), Default::default())
         .balance(op, |_, _| false, 1);
     assert_eq!(bal.total(), AMOUNT * TX_CT as u64);
 }