Merge #1413: Introduce universal sync/full-scan structures for spk-based syncing

c0374a0 feat(chain): `SyncRequest` now uses `ExactSizeIterator`s (志宇)
0f94f24 feat(esplora)!: update to use new sync/full-scan structures (志宇)
4c52f3e feat(wallet): make wallet compatible with sync/full-scan structures (志宇)
cdfec5f feat(chain): add sync/full-scan structures for spk-based syncing (志宇)

Pull request description:

  Fixes #1153
  Replaces #1194

  ### Description

  Introduce universal structures that represent sync/full-scan requests/results.

  ### Notes to the reviewers

  This is based on #1194 but is different in the following ways:
  * The functionality to print scan/sync progress is not reduced.
  * `SyncRequest` and `FullScanRequest` is simplified and fields are exposed for more flexibility.

  ### Changelog notice

  * Add universal structures for initiating/receiving sync/full-scan requests/results for spk-based syncing.
  * Updated `bdk_esplora` chain-source to make use of new universal sync/full-scan structures.

  ### Checklists

  #### All Submissions:

  * [x] I've signed all my commits
  * [x] I followed the [contribution guidelines](https://github.com/bitcoindevkit/bdk/blob/master/CONTRIBUTING.md)
  * [x] I ran `cargo fmt` and `cargo clippy` before committing

  #### New Features:

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

ACKs for top commit:
  notmandatory:
    tACK c0374a0

Tree-SHA512: c2ad66d972a6785079bca615dfd128edcedf6b7a02670651a0ab1ce5b5174dd96f54644680eedbf55e3f1955fe5c34f632eadbd3f71d7ffde658753c6c6d42be

Author: evanlinjin

crates/bdk/src/wallet/mod.rs

@@ -26,6 +26,7 @@ use bdk_chain::{
     local_chain::{
         self, ApplyHeaderError, CannotConnectError, CheckPoint, CheckPointIter, LocalChain,
     },
+    spk_client::{FullScanRequest, FullScanResult, SyncRequest, SyncResult},
     tx_graph::{CanonicalTx, TxGraph},
     Append, BlockId, ChainPosition, ConfirmationTime, ConfirmationTimeHeightAnchor, FullTxOut,
     IndexedTxGraph,
@@ -111,6 +112,26 @@ pub struct Update {
     pub chain: Option<CheckPoint>,
 }
 
+impl From<FullScanResult<KeychainKind>> for Update {
+    fn from(value: FullScanResult<KeychainKind>) -> Self {
+        Self {
+            last_active_indices: value.last_active_indices,
+            graph: value.graph_update,
+            chain: Some(value.chain_update),
+        }
+    }
+}
+
+impl From<SyncResult> for Update {
+    fn from(value: SyncResult) -> Self {
+        Self {
+            last_active_indices: BTreeMap::new(),
+            graph: value.graph_update,
+            chain: Some(value.chain_update),
+        }
+    }
+}
+
 /// The changes made to a wallet by applying an [`Update`].
 #[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize, Default)]
 pub struct ChangeSet {
@@ -2263,7 +2284,8 @@ impl Wallet {
     /// transactions related to your wallet into it.
     ///
     /// [`commit`]: Self::commit
-    pub fn apply_update(&mut self, update: Update) -> Result<(), CannotConnectError> {
+    pub fn apply_update(&mut self, update: impl Into<Update>) -> Result<(), CannotConnectError> {
+        let update = update.into();
         let mut changeset = match update.chain {
             Some(chain_update) => ChangeSet::from(self.chain.apply_update(chain_update)?),
             None => ChangeSet::default(),
@@ -2388,6 +2410,31 @@ impl Wallet {
     }
 }
 
+/// Methods to construct sync/full-scan requests for spk-based chain sources.
+impl Wallet {
+    /// Create a partial [`SyncRequest`] for this wallet for all revealed spks.
+    ///
+    /// This is the first step when performing a spk-based wallet partial sync, the returned
+    /// [`SyncRequest`] collects all revealed script pubkeys from the wallet keychain needed to
+    /// start a blockchain sync with a spk based blockchain client.
+    pub fn start_sync_with_revealed_spks(&self) -> SyncRequest {
+        SyncRequest::from_chain_tip(self.chain.tip())
+            .populate_with_revealed_spks(&self.indexed_graph.index, ..)
+    }
+
+    /// Create a [`FullScanRequest] for this wallet.
+    ///
+    /// This is the first step when performing a spk-based wallet full scan, the returned
+    /// [`FullScanRequest] collects iterators for the wallet's keychain script pub keys needed to
+    /// start a blockchain full scan with a spk based blockchain client.
+    ///
+    /// This operation is generally only used when importing or restoring a previously used wallet
+    /// in which the list of used scripts is not known.
+    pub fn start_full_scan(&self) -> FullScanRequest<KeychainKind> {
+        FullScanRequest::from_keychain_txout_index(self.chain.tip(), &self.indexed_graph.index)
+    }
+}
+
 impl AsRef<bdk_chain::tx_graph::TxGraph<ConfirmationTimeHeightAnchor>> for Wallet {
     fn as_ref(&self) -> &bdk_chain::tx_graph::TxGraph<ConfirmationTimeHeightAnchor> {
         self.indexed_graph.graph()

crates/chain/src/lib.rs

@@ -49,6 +49,7 @@ pub use descriptor_ext::DescriptorExt;
 mod spk_iter;
 #[cfg(feature = "miniscript")]
 pub use spk_iter::*;
+pub mod spk_client;
 
 #[allow(unused_imports)]
 #[macro_use]