Merge #2029: CanonicalView

1311a2e refactor(chain)!: Change trust_predicate to accept FullTxOut (志宇)
3f9eec5 refactor(example): Reuse `CanonicalView` in filter iter example (志宇)
40790d0 docs(chain): Tighten `CanonicalView` documentation (志宇)
f444a8d refactor(chain)!: Rename `CanonicalViewTx` to `CanonicalTx` (志宇)
8ad138d docs(chain): Improve CanonicalView documentation (志宇)
beb16a1 feat(chain)!: Remove `CanonicalTx` (志宇)
54409bc test(chain): Add comprehensive tests for min_confirmations parameter (志宇)
4524945 feat(chain): Add min_confirmations parameter to CanonicalView::balance (志宇)
0a55710 feat(chain)!: Introduce `CanonicalView` and migrate API (志宇)

Pull request description:

  ### Description

  `CanonicalView` allows us to canonicalize upfront, reducing our API surface and improving performance by reducing canonicalizations we need to do.

  This is also the first step to achieving many of our goals.

  * Event notifications.
  * Intent tracker.
  * Getting rid of `CanonicalUnspents` structure in `bdk_tx`.

  ### Changelog notice

  ```md
  Added
  - Introduce `CanonicalView` which allows us to canonicalize once upfront.
  - Added `TxGraph::canonical_view` which constructs a `CanonicalView`.

  Changed
  - `TxGraph` methods which require canonicalization now have `CanonicalView` equivalents.

  Removed
  - `TxGraph` methods which take in a fallible `ChainOracle` implementations are now removed.

  ```

  ### 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:
    self-ACK 1311a2e
  ValuedMammal:
    ACK 1311a2e
  oleonardolima:
    ACK 1311a2e

Tree-SHA512: 520879ac5aba37ae53d6fa0465ee5920d65108208f82e9092fc6d391f9ce5741198c474fe49462e3bf6ed9f65f94f6019be0c0e02a0b19bcdb8398eb1c7ea3e0

Author: oleonardolima

crates/bitcoind_rpc/examples/filter_iter.rs

@@ -68,14 +68,11 @@ fn main() -> anyhow::Result<()> {
 
     println!("\ntook: {}s", start.elapsed().as_secs());
     println!("Local tip: {}", chain.tip().height());
-    let unspent: Vec<_> = graph
-        .graph()
-        .filter_chain_unspents(
-            &chain,
-            chain.tip().block_id(),
-            Default::default(),
-            graph.index.outpoints().clone(),
-        )
+
+    let canonical_view = graph.canonical_view(&chain, chain.tip().block_id(), Default::default());
+
+    let unspent: Vec<_> = canonical_view
+        .filter_unspent_outpoints(graph.index.outpoints().clone())
         .collect();
     if !unspent.is_empty() {
         println!("\nUnspent");
@@ -85,16 +82,9 @@ fn main() -> anyhow::Result<()> {
         }
     }
 
-    for canon_tx in graph.graph().list_canonical_txs(
-        &chain,
-        chain.tip().block_id(),
-        bdk_chain::CanonicalizationParams::default(),
-    ) {
-        if !canon_tx.chain_position.is_confirmed() {
-            eprintln!(
-                "ERROR: canonical tx should be confirmed {}",
-                canon_tx.tx_node.txid
-            );
+    for canon_tx in canonical_view.txs() {
+        if !canon_tx.pos.is_confirmed() {
+            eprintln!("ERROR: canonical tx should be confirmed {}", canon_tx.txid);
         }
     }
 

crates/bitcoind_rpc/tests/test_emitter.rs

@@ -310,13 +310,9 @@ fn get_balance(
 ) -> anyhow::Result<Balance> {
     let chain_tip = recv_chain.tip().block_id();
     let outpoints = recv_graph.index.outpoints().clone();
-    let balance = recv_graph.graph().balance(
-        recv_chain,
-        chain_tip,
-        CanonicalizationParams::default(),
-        outpoints,
-        |_, _| true,
-    );
+    let balance = recv_graph
+        .canonical_view(recv_chain, chain_tip, CanonicalizationParams::default())
+        .balance(outpoints, |_, _| true, 1);
     Ok(balance)
 }
 
@@ -621,7 +617,8 @@ fn test_expect_tx_evicted() -> anyhow::Result<()> {
 
     // Retrieve the expected unconfirmed txids and spks from the graph.
     let exp_spk_txids = graph
-        .list_expected_spk_txids(&chain, chain_tip, ..)
+        .canonical_view(&chain, chain_tip, Default::default())
+        .list_expected_spk_txids(&graph.index, ..)
         .collect::<Vec<_>>();
     assert_eq!(exp_spk_txids, vec![(spk, txid_1)]);
 
@@ -636,9 +633,9 @@ fn test_expect_tx_evicted() -> anyhow::Result<()> {
     let _ = graph.batch_insert_relevant_evicted_at(mempool_event.evicted);
 
     let canonical_txids = graph
-        .graph()
-        .list_canonical_txs(&chain, chain_tip, CanonicalizationParams::default())
-        .map(|tx| tx.tx_node.compute_txid())
+        .canonical_view(&chain, chain_tip, CanonicalizationParams::default())
+        .txs()
+        .map(|tx| tx.txid)
         .collect::<Vec<_>>();
     // tx1 should no longer be canonical.
     assert!(!canonical_txids.contains(&txid_1));

crates/chain/benches/canonicalization.rs

@@ -95,31 +95,32 @@ 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 txs = tx_graph.graph().list_canonical_txs(
+    let view = tx_graph.canonical_view(
         chain,
         chain.tip().block_id(),
         CanonicalizationParams::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 utxos = tx_graph.graph().filter_chain_txouts(
+    let view = tx_graph.canonical_view(
         chain,
         chain.tip().block_id(),
         CanonicalizationParams::default(),
-        tx_graph.index.outpoints().clone(),
     );
+    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 utxos = tx_graph.graph().filter_chain_unspents(
+    let view = tx_graph.canonical_view(
         chain,
         chain.tip().block_id(),
         CanonicalizationParams::default(),
-        tx_graph.index.outpoints().clone(),
     );
+    let utxos = view.filter_unspent_outpoints(tx_graph.index.outpoints().clone());
     assert_eq!(utxos.count(), exp_utxos);
 }
 

crates/chain/benches/indexer.rs

@@ -84,13 +84,9 @@ fn do_bench(indexed_tx_graph: &KeychainTxGraph, chain: &LocalChain) {
     // Check balance
     let chain_tip = chain.tip().block_id();
     let op = graph.index.outpoints().clone();
-    let bal = graph.graph().balance(
-        chain,
-        chain_tip,
-        CanonicalizationParams::default(),
-        op,
-        |_, _| false,
-    );
+    let bal = graph
+        .canonical_view(chain, chain_tip, CanonicalizationParams::default())
+        .balance(op, |_, _| false, 1);
     assert_eq!(bal.total(), AMOUNT * TX_CT as u64);
 }