refactor!(bdk): Update wallet start_sync, start_scan to return new Sy…

…ncRequest, ScanRequest structs

Update esplora async_ext sync and scan to use new SyncRequest and ScanRequest

crates/bdk/src/wallet/mod.rs

@@ -40,6 +40,7 @@ use core::fmt;
 use core::ops::Deref;
 use miniscript::psbt::{PsbtExt, PsbtInputExt, PsbtInputSatisfier};
 
+use bdk_chain::request::{ScanRequest, SyncRequest};
 use bdk_chain::tx_graph::CalculateFeeError;
 #[allow(unused_imports)]
 use log::{debug, error, info, trace};
@@ -113,9 +114,20 @@ pub struct Update {
  pub chain: Option<local_chain::Update>,
 }
 
-impl From<(BTreeMap<KeychainKind, u32>, TxGraph<ConfirmationTimeAnchor>, local_chain::Update)> for Update
+impl
+ From<(
+ BTreeMap<KeychainKind, u32>,
+ TxGraph<ConfirmationTimeAnchor>,
+ local_chain::Update,
+ )> for Update
 {
- fn from((last_active_indices, graph, chain): (BTreeMap<KeychainKind, u32>, TxGraph<ConfirmationTimeAnchor>, local_chain::Update)) -> Self {
+ fn from(
+ (last_active_indices, graph, chain): (
+ BTreeMap<KeychainKind, u32>,
+ TxGraph<ConfirmationTimeAnchor>,
+ local_chain::Update,
+ ),
+ ) -> Self {
  Self {
  last_active_indices,
  graph,
@@ -124,8 +136,7 @@ impl From<(BTreeMap<KeychainKind, u32>, TxGraph<ConfirmationTimeAnchor>, local_c
  }
 }
 
-impl From<(TxGraph<ConfirmationTimeAnchor>, local_chain::Update)> for Update
-{
+impl From<(TxGraph<ConfirmationTimeAnchor>, local_chain::Update)> for Update {
  fn from((graph, chain): (TxGraph<ConfirmationTimeAnchor>, local_chain::Update)) -> Self {
  Self {
  graph,
@@ -2013,54 +2024,59 @@ impl<D> Wallet<D> {
  ///
  /// Collect the wallet keychain script pub keys, local chain, and previous chain tip data needed
  /// to start a blockchain scan.
- pub fn start_scan(&self) -> (BTreeMap<KeychainKind, impl Iterator<Item = (u32, ScriptBuf)> + Clone>,
- &LocalChain, Option<CheckPoint>) {
-
- let keychain_spks = self.spks_of_all_keychains();
- let local_chain = self.local_chain();
- let prev_tip = self.latest_checkpoint();
+ pub fn start_scan(
+ &self,
+ ) -> ScanRequest<KeychainKind, impl Iterator<Item = (u32, ScriptBuf)> + Clone> {
+ let spks_by_keychain = self.spks_of_all_keychains();
+ let checkpoint = self.latest_checkpoint();
 
- (keychain_spks, local_chain, prev_tip)
+ ScanRequest {
+ spks_by_keychain,
+ checkpoint,
+ }
  }
 
  /// Get data needed to start a wallet sync
  ///
  /// Collect the wallet keychain script pub keys, local chain, previous chain tip, UTXOs, and
  /// unconfirmed transaction id data needed to start a blockchain sync.
- pub fn start_sync(&self, unused_spks_only: bool) -> (Vec<ScriptBuf>, &LocalChain, Option<CheckPoint>, Vec<OutPoint>, Vec<Txid>) {
-
- let local_chain = self.local_chain();
- let prev_tip = self.latest_checkpoint();
+ pub fn start_sync(&self, unused_spks_only: bool) -> SyncRequest {
+ let checkpoint = self.latest_checkpoint();
 
  // Sync only unused SPKs
  let spks = if unused_spks_only {
-  self.spk_index()
-  .unused_spks(..)
-  .map(|((_keychain, _index), script)| ScriptBuf::from(script))
-  .collect::<Vec<ScriptBuf>>()
-  }
-  // Sync all SPKs
-  else {
-  self.spk_index()
-  .all_spks()
-  .into_iter()
-  .map(|((_keychain, _index), script)| (*script).clone())
-  .collect::<Vec<ScriptBuf>>()
-  };
+ self.spk_index()
+ .unused_spks(..)
+ .map(|((_keychain, _index), script)| ScriptBuf::from(script))
+ .collect::<Vec<ScriptBuf>>()
+ }
+ // Sync all SPKs
+ else {
+ self.spk_index()
+ .all_spks()
+ .into_iter()
+ .map(|((_keychain, _index), script)| (*script).clone())
+ .collect::<Vec<ScriptBuf>>()
+ };
 
-  // Sync UTXOs
-  // We want to search for whether our UTXOs are spent, and spent by which transaction.
-  let outpoints: Vec<OutPoint> = self.list_unspent().map(|utxo| utxo.outpoint).collect();
+ // Sync UTXOs
+ // We want to search for whether our UTXOs are spent, and spent by which transaction.
+ let outpoints: Vec<OutPoint> = self.list_unspent().map(|utxo| utxo.outpoint).collect();
 
-  // Sync unconfirmed TX
-  // We want to search for whether our unconfirmed transactions are now confirmed.
-  let txids: Vec<Txid> = self
-  .transactions()
-  .filter(|canonical_tx| !canonical_tx.chain_position.is_confirmed())
-  .map(|canonical_tx| canonical_tx.tx_node.txid)
-  .collect();
+ // Sync unconfirmed TX
+ // We want to search for whether our unconfirmed transactions are now confirmed.
+ let txids: Vec<Txid> = self
+ .transactions()
+ .filter(|canonical_tx| !canonical_tx.chain_position.is_confirmed())
+ .map(|canonical_tx| canonical_tx.tx_node.txid)
+ .collect();
 
- (spks, local_chain, prev_tip, outpoints, txids)
+ SyncRequest {
+ spks,
+ txids,
+ outpoints,
+ checkpoint,
+ }
  }
 }
 

crates/chain/src/lib.rs

@@ -53,6 +53,9 @@ mod spk_iter;
 #[cfg(feature = "miniscript")]
 pub use spk_iter::*;
 
+/// Structures for requesting data needed to sync or scan the blockchain for chain related data.
+pub mod request;
+
 #[allow(unused_imports)]
 #[macro_use]
 extern crate alloc;

crates/chain/src/request.rs

@@ -0,0 +1,24 @@
+use crate::local_chain::CheckPoint;
+use alloc::vec::Vec;
+use bitcoin::{OutPoint, ScriptBuf, Txid};
+use std::collections::BTreeMap;
+
+/// A list of blockchain entities for which we want to receive any related transaction data.
+pub struct SyncRequest {
+ /// transactions that spend from or two these script pubkeys
+ pub spks: Vec<ScriptBuf>,
+ /// Transactions with these txids
+ pub txids: Vec<Txid>,
+ /// Transactions with these outpoints or spend from these outpoints
+ pub outpoints: Vec<OutPoint>,
+ /// The local chain checkpoint. The sync process will return a new chain that extends this one.
+ pub checkpoint: Option<CheckPoint>,
+}
+
+/// Script pubkeys indexed by their keychain.
+pub struct ScanRequest<K, I> {
+ /// Iterators of script pubkeys indexed by the keychain index
+ pub spks_by_keychain: BTreeMap<K, I>,
+ /// The local chain checkpoint. The scan process will return a new chain that extends this one.
+ pub checkpoint: Option<CheckPoint>,
+}

crates/esplora/src/async_ext.rs

@@ -1,5 +1,7 @@
 use async_trait::async_trait;
 use bdk_chain::collections::btree_map;
+use bdk_chain::local_chain::LocalChain;
+use bdk_chain::request::{ScanRequest, SyncRequest};
 use bdk_chain::{
  bitcoin::{BlockHash, OutPoint, ScriptBuf, Txid},
  collections::{BTreeMap, BTreeSet},
@@ -8,7 +10,6 @@ use bdk_chain::{
 };
 use esplora_client::{Error, TxStatus};
 use futures::{stream::FuturesOrdered, TryStreamExt};
-use bdk_chain::local_chain::LocalChain;
 
 use crate::{anchor_from_status, ASSUME_FINAL_DEPTH};
 
@@ -33,29 +34,37 @@ pub trait EsploraAsyncExt {
  /// which is used to update a wallets [`KeychainTxOutIndex`].
  /// * graph_update, contains an update to a wallet's internal [`TxGraph`].
  /// * chain_update, contains an update to a wallet's internal [`LocalChain`].
- async fn scan<K: Clone + Ord + Send>(
+ async fn scan<K: Clone + Ord + Send, I: Iterator<Item = (u32, ScriptBuf)> + Send>(
  &self,
- start_scan: (BTreeMap<K, impl IntoIterator<IntoIter = impl Iterator<Item = (u32, ScriptBuf)> + Send> + Send,>,
- &LocalChain,
- Option<CheckPoint>),
+ scan_request: ScanRequest<K, I>,
  stop_gap: usize,
  parallel_requests: usize,
- ) -> Result<(BTreeMap<K, u32>, TxGraph<ConfirmationTimeAnchor>, local_chain::Update), Error> {
- let (keychain_spks, local_chain, local_tip) = start_scan;
+ ) -> Result<
+ (
+ BTreeMap<K, u32>,
+ TxGraph<ConfirmationTimeAnchor>,
+ local_chain::Update,
+ ),
+ Error,
+ > {
  let (graph_update, last_active_indices) = self
  .scan_txs_with_keychains(
- keychain_spks,
+ scan_request.spks_by_keychain,
  core::iter::empty(),
  core::iter::empty(),
  stop_gap,
  parallel_requests,
  )
  .await?;
 
- let missing_heights = graph_update.missing_heights(local_chain);
+ let local_chain = scan_request
+ .checkpoint
+ .map(|cp| LocalChain::from_tip(cp))
+ .unwrap_or_default();
+ let missing_heights = graph_update.missing_heights(&local_chain);
 
  let chain_update = self
- .update_local_chain(local_tip, missing_heights)
+ .update_local_chain(local_chain.tip(), missing_heights)
  .await?;
 
  Ok((last_active_indices, graph_update, chain_update))
@@ -69,16 +78,23 @@ pub trait EsploraAsyncExt {
  /// * chain_update, contains an update to a wallet's internal [`LocalChain`].
  async fn sync(
  &self,
- start_sync: (Vec<ScriptBuf>, &LocalChain, Option<CheckPoint>, Vec<OutPoint>, Vec<Txid>),
+ sync_request: SyncRequest,
  parallel_requests: usize,
  ) -> Result<(TxGraph<ConfirmationTimeAnchor>, local_chain::Update), Error> {
- let (spks, local_chain, local_tip, outpoints, txids) = start_sync;
  let graph_update = self
- .scan_txs(spks.into_iter(), txids.into_iter(), outpoints.into_iter(), parallel_requests)
+ .scan_txs(
+ sync_request.spks.into_iter(),
+ sync_request.txids.into_iter(),
+ sync_request.outpoints.into_iter(),
+ parallel_requests,
+ )
  .await?;
 
- let missing_heights = graph_update.missing_heights(local_chain);
- let chain_update = self.update_local_chain(local_tip, missing_heights).await?;
+ let local_chain = LocalChain::from_tip(sync_request.checkpoint.unwrap());
+ let missing_heights = graph_update.missing_heights(&local_chain);
+ let chain_update = self
+ .update_local_chain(local_chain.tip(), missing_heights)
+ .await?;
 
  Ok((graph_update, chain_update))
  }

example-crates/wallet_esplora_async/src/main.rs

@@ -42,8 +42,10 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
  // wallet restoration. It is a special case. Applications should use "sync" style updates
  // after an initial scan.
  if prompt("Scan wallet") {
- let start_scan = wallet.start_scan();
- let wallet_update = client.scan(start_scan, STOP_GAP, PARALLEL_REQUESTS).await?;
+ let scan_request = wallet.start_scan();
+ let wallet_update = client
+ .scan(scan_request, STOP_GAP, PARALLEL_REQUESTS)
+ .await?;
  wallet.apply_update(wallet_update.into())?;
  wallet.commit()?;
  println!("Scan completed.");
@@ -52,8 +54,8 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
  // status or fetch missing transactions.
  else {
  let unused_spks_only = prompt("Sync only unused SPKs");
- let start_sync = wallet.start_sync(unused_spks_only);
- let wallet_update = client.sync(start_sync, PARALLEL_REQUESTS).await?;
+ let sync_request = wallet.start_sync(unused_spks_only);
+ let wallet_update = client.sync(sync_request, PARALLEL_REQUESTS).await?;
  wallet.apply_update(wallet_update.into())?;
  wallet.commit()?;
  println!("Sync completed.");