feat(esplora)!: remove EsploraExt::update_local_chain

Previously, we would update the `TxGraph` and `KeychainTxOutIndex`
first, then create a second update for `LocalChain`. This required
locking the receiving structures 3 times (instead of twice, which
is optimal).

This PR eliminates this requirement by making use of the new `query`
method of `CheckPoint`.

Examples are also updated to use the new API.

crates/esplora/src/lib.rs

@@ -16,7 +16,9 @@
 //! [`TxGraph`]: bdk_chain::tx_graph::TxGraph
 //! [`example_esplora`]: https://github.com/bitcoindevkit/bdk/tree/master/example-crates/example_esplora
 
-use bdk_chain::{BlockId, ConfirmationTimeHeightAnchor};
+use std::collections::BTreeMap;
+
+use bdk_chain::{local_chain, BlockId, ConfirmationTimeHeightAnchor, TxGraph};
 use esplora_client::TxStatus;
 
 pub use esplora_client;
@@ -48,3 +50,21 @@ fn anchor_from_status(status: &TxStatus) -> Option<ConfirmationTimeHeightAnchor>
         None
     }
 }
+
+/// Update returns from a full scan.
+pub struct FullScanUpdate<K> {
+    /// The update to apply to the receiving [`LocalChain`](local_chain::LocalChain).
+    pub local_chain: local_chain::Update,
+    /// The update to apply to the receiving [`TxGraph`].
+    pub tx_graph: TxGraph<ConfirmationTimeHeightAnchor>,
+    /// Last active indices for the corresponding keychains (`K`).
+    pub last_active_indices: BTreeMap<K, u32>,
+}
+
+/// Update returned from a sync.
+pub struct SyncUpdate {
+    /// The update to apply to the receiving [`LocalChain`](local_chain::LocalChain).
+    pub local_chain: local_chain::Update,
+    /// The update to apply to the receiving [`TxGraph`].
+    pub tx_graph: TxGraph<ConfirmationTimeHeightAnchor>,
+}

crates/esplora/tests/async_ext.rs

@@ -2,7 +2,7 @@ use bdk_esplora::EsploraAsyncExt;
 use electrsd::bitcoind::anyhow;
 use electrsd::bitcoind::bitcoincore_rpc::RpcApi;
 use esplora_client::{self, Builder};
-use std::collections::{BTreeMap, HashSet};
+use std::collections::{BTreeMap, BTreeSet, HashSet};
 use std::str::FromStr;
 use std::thread::sleep;
 use std::time::Duration;
@@ -52,15 +52,37 @@ pub async fn test_update_tx_graph_without_keychain() -> anyhow::Result<()> {
         sleep(Duration::from_millis(10))
     }
 
-    let graph_update = client
+    // use a full checkpoint linked list (since this is not what we are testing)
+    let cp_tip = env.make_checkpoint_tip();
+
+    let sync_update = client
         .sync(
+            cp_tip.clone(),
             misc_spks.into_iter(),
             vec![].into_iter(),
             vec![].into_iter(),
             1,
         )
         .await?;
 
+    assert!(
+        {
+            let update_cps = sync_update
+                .local_chain
+                .tip
+                .iter()
+                .map(|cp| cp.block_id())
+                .collect::<BTreeSet<_>>();
+            let superset_cps = cp_tip
+                .iter()
+                .map(|cp| cp.block_id())
+                .collect::<BTreeSet<_>>();
+            superset_cps.is_superset(&update_cps)
+        },
+        "update should not alter original checkpoint tip since we already started with all checkpoints",
+    );
+
+    let graph_update = sync_update.tx_graph;
     // Check to see if we have the floating txouts available from our two created transactions'
     // previous outputs in order to calculate transaction fees.
     for tx in graph_update.full_txs() {
@@ -140,14 +162,24 @@ pub async fn test_async_update_tx_graph_stop_gap() -> anyhow::Result<()> {
         sleep(Duration::from_millis(10))
     }
 
+    // use a full checkpoint linked list (since this is not what we are testing)
+    let cp_tip = env.make_checkpoint_tip();
+
     // A scan with a gap limit of 3 won't find the transaction, but a scan with a gap limit of 4
     // will.
-    let (graph_update, active_indices) = client.full_scan(keychains.clone(), 3, 1).await?;
-    assert!(graph_update.full_txs().next().is_none());
-    assert!(active_indices.is_empty());
-    let (graph_update, active_indices) = client.full_scan(keychains.clone(), 4, 1).await?;
-    assert_eq!(graph_update.full_txs().next().unwrap().txid, txid_4th_addr);
-    assert_eq!(active_indices[&0], 3);
+    let full_scan_update = client
+        .full_scan(cp_tip.clone(), keychains.clone(), 3, 1)
+        .await?;
+    assert!(full_scan_update.tx_graph.full_txs().next().is_none());
+    assert!(full_scan_update.last_active_indices.is_empty());
+    let full_scan_update = client
+        .full_scan(cp_tip.clone(), keychains.clone(), 4, 1)
+        .await?;
+    assert_eq!(
+        full_scan_update.tx_graph.full_txs().next().unwrap().txid,
+        txid_4th_addr
+    );
+    assert_eq!(full_scan_update.last_active_indices[&0], 3);
 
     // Now receive a coin on the last address.
     let txid_last_addr = env.bitcoind.client.send_to_address(
@@ -167,16 +199,26 @@ pub async fn test_async_update_tx_graph_stop_gap() -> anyhow::Result<()> {
 
     // A scan with gap limit 5 won't find the second transaction, but a scan with gap limit 6 will.
     // The last active indice won't be updated in the first case but will in the second one.
-    let (graph_update, active_indices) = client.full_scan(keychains.clone(), 5, 1).await?;
-    let txs: HashSet<_> = graph_update.full_txs().map(|tx| tx.txid).collect();
+    let full_scan_update = client
+        .full_scan(cp_tip.clone(), keychains.clone(), 5, 1)
+        .await?;
+    let txs: HashSet<_> = full_scan_update
+        .tx_graph
+        .full_txs()
+        .map(|tx| tx.txid)
+        .collect();
     assert_eq!(txs.len(), 1);
     assert!(txs.contains(&txid_4th_addr));
-    assert_eq!(active_indices[&0], 3);
-    let (graph_update, active_indices) = client.full_scan(keychains, 6, 1).await?;
-    let txs: HashSet<_> = graph_update.full_txs().map(|tx| tx.txid).collect();
+    assert_eq!(full_scan_update.last_active_indices[&0], 3);
+    let full_scan_update = client.full_scan(cp_tip, keychains, 6, 1).await?;
+    let txs: HashSet<_> = full_scan_update
+        .tx_graph
+        .full_txs()
+        .map(|tx| tx.txid)
+        .collect();
     assert_eq!(txs.len(), 2);
     assert!(txs.contains(&txid_4th_addr) && txs.contains(&txid_last_addr));
-    assert_eq!(active_indices[&0], 9);
+    assert_eq!(full_scan_update.last_active_indices[&0], 9);
 
     Ok(())
 }

crates/esplora/tests/blocking_ext.rs

@@ -3,7 +3,7 @@ use bdk_chain::BlockId;
 use bdk_esplora::EsploraExt;
 use electrsd::bitcoind::anyhow;
 use electrsd::bitcoind::bitcoincore_rpc::RpcApi;
-use esplora_client::{self, Builder};
+use esplora_client::{self, BlockHash, Builder};
 use std::collections::{BTreeMap, BTreeSet, HashSet};
 use std::str::FromStr;
 use std::thread::sleep;
@@ -68,13 +68,35 @@ pub fn test_update_tx_graph_without_keychain() -> anyhow::Result<()> {
         sleep(Duration::from_millis(10))
     }
 
-    let graph_update = client.sync(
+    // use a full checkpoint linked list (since this is not what we are testing)
+    let cp_tip = env.make_checkpoint_tip();
+
+    let sync_update = client.sync(
+        cp_tip.clone(),
         misc_spks.into_iter(),
         vec![].into_iter(),
         vec![].into_iter(),
         1,
     )?;
 
+    assert!(
+        {
+            let update_cps = sync_update
+                .local_chain
+                .tip
+                .iter()
+                .map(|cp| cp.block_id())
+                .collect::<BTreeSet<_>>();
+            let superset_cps = cp_tip
+                .iter()
+                .map(|cp| cp.block_id())
+                .collect::<BTreeSet<_>>();
+            superset_cps.is_superset(&update_cps)
+        },
+        "update should not alter original checkpoint tip since we already started with all checkpoints",
+    );
+
+    let graph_update = sync_update.tx_graph;
     // Check to see if we have the floating txouts available from our two created transactions'
     // previous outputs in order to calculate transaction fees.
     for tx in graph_update.full_txs() {
@@ -155,14 +177,20 @@ pub fn test_update_tx_graph_stop_gap() -> anyhow::Result<()> {
         sleep(Duration::from_millis(10))
     }
 
+    // use a full checkpoint linked list (since this is not what we are testing)
+    let cp_tip = env.make_checkpoint_tip();
+
     // A scan with a stop_gap of 3 won't find the transaction, but a scan with a gap limit of 4
     // will.
-    let (graph_update, active_indices) = client.full_scan(keychains.clone(), 3, 1)?;
-    assert!(graph_update.full_txs().next().is_none());
-    assert!(active_indices.is_empty());
-    let (graph_update, active_indices) = client.full_scan(keychains.clone(), 4, 1)?;
-    assert_eq!(graph_update.full_txs().next().unwrap().txid, txid_4th_addr);
-    assert_eq!(active_indices[&0], 3);
+    let full_scan_update = client.full_scan(cp_tip.clone(), keychains.clone(), 3, 1)?;
+    assert!(full_scan_update.tx_graph.full_txs().next().is_none());
+    assert!(full_scan_update.last_active_indices.is_empty());
+    let full_scan_update = client.full_scan(cp_tip.clone(), keychains.clone(), 4, 1)?;
+    assert_eq!(
+        full_scan_update.tx_graph.full_txs().next().unwrap().txid,
+        txid_4th_addr
+    );
+    assert_eq!(full_scan_update.last_active_indices[&0], 3);
 
     // Now receive a coin on the last address.
     let txid_last_addr = env.bitcoind.client.send_to_address(
@@ -182,16 +210,24 @@ pub fn test_update_tx_graph_stop_gap() -> anyhow::Result<()> {
 
     // A scan with gap limit 5 won't find the second transaction, but a scan with gap limit 6 will.
     // The last active indice won't be updated in the first case but will in the second one.
-    let (graph_update, active_indices) = client.full_scan(keychains.clone(), 5, 1)?;
-    let txs: HashSet<_> = graph_update.full_txs().map(|tx| tx.txid).collect();
+    let full_scan_update = client.full_scan(cp_tip.clone(), keychains.clone(), 5, 1)?;
+    let txs: HashSet<_> = full_scan_update
+        .tx_graph
+        .full_txs()
+        .map(|tx| tx.txid)
+        .collect();
     assert_eq!(txs.len(), 1);
     assert!(txs.contains(&txid_4th_addr));
-    assert_eq!(active_indices[&0], 3);
-    let (graph_update, active_indices) = client.full_scan(keychains, 6, 1)?;
-    let txs: HashSet<_> = graph_update.full_txs().map(|tx| tx.txid).collect();
+    assert_eq!(full_scan_update.last_active_indices[&0], 3);
+    let full_scan_update = client.full_scan(cp_tip.clone(), keychains, 6, 1)?;
+    let txs: HashSet<_> = full_scan_update
+        .tx_graph
+        .full_txs()
+        .map(|tx| tx.txid)
+        .collect();
     assert_eq!(txs.len(), 2);
     assert!(txs.contains(&txid_4th_addr) && txs.contains(&txid_last_addr));
-    assert_eq!(active_indices[&0], 9);
+    assert_eq!(full_scan_update.last_active_indices[&0], 9);
 
     Ok(())
 }
@@ -317,14 +353,38 @@ fn update_local_chain() -> anyhow::Result<()> {
     for (i, t) in test_cases.into_iter().enumerate() {
         println!("Case {}: {}", i, t.name);
         let mut chain = t.chain;
+        let cp_tip = chain.tip();
 
-        let update = client
-            .update_local_chain(chain.tip(), t.request_heights.iter().copied())
-            .map_err(|err| {
-                anyhow::format_err!("[{}:{}] `update_local_chain` failed: {}", i, t.name, err)
+        let new_blocks =
+            bdk_esplora::init_chain_update_blocking(&client, &cp_tip).map_err(|err| {
+                anyhow::format_err!("[{}:{}] `init_chain_update` failed: {}", i, t.name, err)
             })?;
 
-        let update_blocks = update
+        let mock_anchors = t
+            .request_heights
+            .iter()
+            .map(|&h| {
+                let anchor_blockhash: BlockHash = bdk_chain::bitcoin::hashes::Hash::hash(
+                    &format!("hash_at_height_{}", h).into_bytes(),
+                );
+                let txid: Txid = bdk_chain::bitcoin::hashes::Hash::hash(
+                    &format!("txid_at_height_{}", h).into_bytes(),
+                );
+                let anchor = BlockId {
+                    height: h,
+                    hash: anchor_blockhash,
+                };
+                (anchor, txid)
+            })
+            .collect::<BTreeSet<_>>();
+
+        let chain_update = bdk_esplora::finalize_chain_update_blocking(
+            &client,
+            &cp_tip,
+            &mock_anchors,
+            new_blocks,
+        )?;
+        let update_blocks = chain_update
             .tip
             .iter()
             .map(|cp| cp.block_id())
@@ -346,14 +406,15 @@ fn update_local_chain() -> anyhow::Result<()> {
             )
             .collect::<BTreeSet<_>>();
 
-        assert_eq!(
-            update_blocks, exp_update_blocks,
+        assert!(
+            update_blocks.is_superset(&exp_update_blocks),
             "[{}:{}] unexpected update",
-            i, t.name
+            i,
+            t.name
         );
 
         let _ = chain
-            .apply_update(update)
+            .apply_update(chain_update)
             .unwrap_or_else(|err| panic!("[{}:{}] update failed to apply: {}", i, t.name, err));
 
         // all requested heights must exist in the final chain

crates/testenv/src/lib.rs

@@ -1,6 +1,8 @@
 use bdk_chain::{
     bitcoin::{
-        address::NetworkChecked, block::Header, hash_types::TxMerkleNode, hashes::Hash, secp256k1::rand::random, transaction, Address, Amount, Block, BlockHash, CompactTarget, ScriptBuf, ScriptHash, Transaction, TxIn, TxOut, Txid
+        address::NetworkChecked, block::Header, hash_types::TxMerkleNode, hashes::Hash,
+        secp256k1::rand::random, transaction, Address, Amount, Block, BlockHash, CompactTarget,
+        ScriptBuf, ScriptHash, Transaction, TxIn, TxOut, Txid,
     },
     local_chain::CheckPoint,
     BlockId,