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 64fe3dd8cbbcec2b39b01754ded35e8265db0bf6..76d8a4e1a06615104fc228c3bc0f32f3ba855c9a 100644 (file)
--- 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 8efc86cc42f3d01582aecc87cab460eea5aab674..70f181b2c0361032b1c5de18bedec0ef5afbe300 100644 (file)
--- 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 80fa025330c760930ac483e1efc5691080fb63b7..5dd4f0311eda76c8e6fca4521ac13d8b7fc3f1fd 100644 (file)
--- 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 2bd9722e4e2150b967686c57d1696b8621a30ca9..779c6729e020bdf7bc1968d3253bb6b5f98c2f70 100644 (file)
--- 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,
         )?);