From: Alok <227512169+alok844937-design@users.noreply.github.com>
Date: Mon, 19 Oct 2026 11:39:53 +0000 (+1100)
Subject: feat(core): split SyncRequest consuming and read-only iterators
X-Git-Url: http://internal-gitweb-vhost/-script/src/example_cli/database/struct.KeychainStore.html?a=commitdiff_plain;h=b3a3087823a51c2dc2e87ae6fc29716a7e5c5028;p=bdk

feat(core): split SyncRequest consuming and read-only iterators

Rename the consuming iterators to `drain_*` and deprecate the `iter_*`
methods as wrappers. Add read-only `spks`, `txids` and `outpoints`.

Fixes #2220

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---

diff --git a/crates/core/src/spk_client.rs b/crates/core/src/spk_client.rs
index 64fe3dd8..76d8a4e1 100644
--- a/crates/core/src/spk_client.rs
+++ b/crates/core/src/spk_client.rs
@@ -376,21 +376,64 @@ impl<I, D> SyncRequest<I, D> {
         Some(outpoint)
     }
 
+    /// Drain and iterate over [`ScriptBuf`]s with corresponding [`Txid`] histories contained in
+    /// this request, consuming them.
+    pub fn drain_spks_with_expected_txids(
+        &mut self,
+    ) -> impl ExactSizeIterator<Item = SpkWithExpectedTxids> + '_ {
+        SyncIter::<I, D, SpkWithExpectedTxids>::new(self)
+    }
+
     /// Iterate over [`ScriptBuf`]s with corresponding [`Txid`] histories contained in this request.
+    #[deprecated(
+        note = "use `drain_spks_with_expected_txids` for consuming iteration or `spks` for read-only iteration"
+    )]
     pub fn iter_spks_with_expected_txids(
         &mut self,
     ) -> impl ExactSizeIterator<Item = SpkWithExpectedTxids> + '_ {
-        SyncIter::<I, D, SpkWithExpectedTxids>::new(self)
+        self.drain_spks_with_expected_txids()
+    }
+
+    /// Drain and iterate over [`Txid`]s contained in this request, consuming them.
+    pub fn drain_txids(&mut self) -> impl ExactSizeIterator<Item = Txid> + '_ {
+        SyncIter::<I, D, Txid>::new(self)
+    }
+
+    /// Drain and iterate over [`OutPoint`]s contained in this request, consuming them.
+    pub fn drain_outpoints(&mut self) -> impl ExactSizeIterator<Item = OutPoint> + '_ {
+        SyncIter::<I, D, OutPoint>::new(self)
     }
 
     /// Iterate over [`Txid`]s contained in this request.
+    #[deprecated(
+        note = "use `drain_txids` for consuming iteration or `txids` for read-only iteration"
+    )]
     pub fn iter_txids(&mut self) -> impl ExactSizeIterator<Item = Txid> + '_ {
-        SyncIter::<I, D, Txid>::new(self)
+        self.drain_txids()
     }
 
     /// Iterate over [`OutPoint`]s contained in this request.
+    #[deprecated(
+        note = "use `drain_outpoints` for consuming iteration or `outpoints` for read-only iteration"
+    )]
     pub fn iter_outpoints(&mut self) -> impl ExactSizeIterator<Item = OutPoint> + '_ {
-        SyncIter::<I, D, OutPoint>::new(self)
+        self.drain_outpoints()
+    }
+
+    /// Iterate over script pubkeys (with indexes) contained in this request, without
+    /// consuming them.
+    pub fn spks(&self) -> impl ExactSizeIterator<Item = &(I, ScriptBuf)> + '_ {
+        self.spks.iter()
+    }
+
+    /// Iterate over [`Txid`]s contained in this request, without consuming them.
+    pub fn txids(&self) -> impl ExactSizeIterator<Item = &Txid> + '_ {
+        self.txids.iter()
+    }
+
+    /// Iterate over [`OutPoint`]s contained in this request, without consuming them.
+    pub fn outpoints(&self) -> impl ExactSizeIterator<Item = &OutPoint> + '_ {
+        self.outpoints.iter()
     }
 
     fn _call_inspect(&mut self, item: SyncItem<I>) {
diff --git a/crates/electrum/src/bdk_electrum_client.rs b/crates/electrum/src/bdk_electrum_client.rs
index 8efc86cc..70f181b2 100644
--- a/crates/electrum/src/bdk_electrum_client.rs
+++ b/crates/electrum/src/bdk_electrum_client.rs
@@ -235,7 +235,7 @@ impl<E: ElectrumApi> BdkElectrumClient<E> {
             start_time,
             &mut tx_update,
             request
-                .iter_spks_with_expected_txids()
+                .drain_spks_with_expected_txids()
                 .enumerate()
                 .map(|(i, spk)| (i as u32, spk)),
             usize::MAX,
@@ -246,13 +246,13 @@ impl<E: ElectrumApi> BdkElectrumClient<E> {
         self.populate_with_txids(
             start_time,
             &mut tx_update,
-            request.iter_txids(),
+            request.drain_txids(),
             &mut pending_anchors,
         )?;
         self.populate_with_outpoints(
             start_time,
             &mut tx_update,
-            request.iter_outpoints(),
+            request.drain_outpoints(),
             &mut pending_anchors,
         )?;
 
diff --git a/crates/esplora/src/async_ext.rs b/crates/esplora/src/async_ext.rs
index 80fa0253..5dd4f031 100644
--- a/crates/esplora/src/async_ext.rs
+++ b/crates/esplora/src/async_ext.rs
@@ -136,7 +136,7 @@ where
                 self,
                 start_time,
                 &mut inserted_txs,
-                request.iter_spks_with_expected_txids(),
+                request.drain_spks_with_expected_txids(),
                 parallel_requests,
             )
             .await?,
@@ -146,7 +146,7 @@ where
                 self,
                 start_time,
                 &mut inserted_txs,
-                request.iter_txids(),
+                request.drain_txids(),
                 parallel_requests,
             )
             .await?,
@@ -156,7 +156,7 @@ where
                 self,
                 start_time,
                 &mut inserted_txs,
-                request.iter_outpoints(),
+                request.drain_outpoints(),
                 parallel_requests,
             )
             .await?,
diff --git a/crates/esplora/src/blocking_ext.rs b/crates/esplora/src/blocking_ext.rs
index 2bd9722e..779c6729 100644
--- a/crates/esplora/src/blocking_ext.rs
+++ b/crates/esplora/src/blocking_ext.rs
@@ -127,21 +127,21 @@ impl EsploraExt for esplora_client::BlockingClient {
             self,
             start_time,
             &mut inserted_txs,
-            request.iter_spks_with_expected_txids(),
+            request.drain_spks_with_expected_txids(),
             parallel_requests,
         )?);
         tx_update.extend(fetch_txs_with_txids(
             self,
             start_time,
             &mut inserted_txs,
-            request.iter_txids(),
+            request.drain_txids(),
             parallel_requests,
         )?);
         tx_update.extend(fetch_txs_with_outpoints(
             self,
             start_time,
             &mut inserted_txs,
-            request.iter_outpoints(),
+            request.drain_outpoints(),
             parallel_requests,
         )?);