From 42f2861fec21503be0feb5fa3b838d414d25ba1c Mon Sep 17 00:00:00 2001
From: Sosthene <contact@sosthene.net>
Date: Mon, 23 Feb 2026 17:24:56 +0800
Subject: [PATCH 1/3] refactor: extract shared logic for SpScanner in logic mod

---
 spdk-wallet/src/scanner/logic.rs   | 186 +++++++++++++++++++++++++++++
 spdk-wallet/src/scanner/mod.rs     |   1 +
 spdk-wallet/src/scanner/scanner.rs | 148 ++---------------------
 3 files changed, 197 insertions(+), 138 deletions(-)
 create mode 100644 spdk-wallet/src/scanner/logic.rs

diff --git a/spdk-wallet/src/scanner/logic.rs b/spdk-wallet/src/scanner/logic.rs
new file mode 100644
index 0000000..58f62ae
--- /dev/null
+++ b/spdk-wallet/src/scanner/logic.rs
@@ -0,0 +1,186 @@
+use std::collections::{HashMap, HashSet};
+
+use anyhow::{Error, Result};
+use bitcoin::{
+    BlockHash, OutPoint, Txid, XOnlyPublicKey, absolute::Height, bip158::BlockFilter, hashes::{Hash, sha256}, hex::DisplayHex, secp256k1::{PublicKey, Scalar}
+};
+use silentpayments::receiving::{Label, Receiver};
+
+use crate::{
+    client::{OutputSpendStatus, OwnedOutput},
+};
+
+use spdk_core::chain::UtxoData;
+
+/// Check if a block's created-UTXO filter matches any of our candidate scriptpubkeys.
+pub(crate) fn check_block_outputs(
+    created_utxo_filter: BlockFilter,
+    blkhash: BlockHash,
+    candidate_spks: Vec<&[u8; 34]>,
+) -> Result<bool> {
+    let output_keys: Vec<_> = candidate_spks
+        .into_iter()
+        .map(|spk| spk[2..].as_ref())
+        .collect();
+
+    // note: match will always return true for an empty query!
+    if !output_keys.is_empty() {
+        Ok(created_utxo_filter.match_any(&blkhash, &mut output_keys.into_iter())?)
+    } else {
+        Ok(false)
+    }
+}
+
+/// Compute 8-byte input hashes for our owned outpoints against a given block hash.
+pub(crate) fn get_input_hashes(
+    owned_outpoints: &HashSet<OutPoint>,
+    blkhash: BlockHash,
+) -> Result<HashMap<[u8; 8], OutPoint>> {
+    let mut map: HashMap<[u8; 8], OutPoint> = HashMap::new();
+
+    for outpoint in owned_outpoints {
+        let mut arr = [0u8; 68];
+        arr[..32].copy_from_slice(&outpoint.txid.to_raw_hash().to_byte_array());
+        arr[32..36].copy_from_slice(&outpoint.vout.to_le_bytes());
+        arr[36..].copy_from_slice(&blkhash.to_byte_array());
+        let hash = sha256::Hash::hash(&arr);
+
+        let mut res = [0u8; 8];
+        res.copy_from_slice(&hash[..8]);
+
+        map.insert(res, *outpoint);
+    }
+
+    Ok(map)
+}
+
+/// Check if a block's spent filter matches any of our input hashes.
+pub(crate) fn check_block_inputs(
+    spent_filter: BlockFilter,
+    blkhash: BlockHash,
+    input_hashes: Vec<[u8; 8]>,
+) -> Result<bool> {
+    // note: match will always return true for an empty query!
+    if !input_hashes.is_empty() {
+        Ok(spent_filter.match_any(&blkhash, &mut input_hashes.into_iter())?)
+    } else {
+        Ok(false)
+    }
+}
+
+/// Given fetched UTXOs and a secret map, find which ones belong to us.
+pub(crate) fn find_owned_in_utxos(
+    sp_receiver: &Receiver,
+    utxos: Vec<UtxoData>,
+    secrets_map: &HashMap<[u8; 34], PublicKey>,
+) -> Result<Vec<(Option<Label>, UtxoData, Scalar)>> {
+    let mut res: Vec<(Option<Label>, UtxoData, Scalar)> = vec![];
+
+    // group utxos by the txid
+    let mut txmap: HashMap<Txid, Vec<UtxoData>> = HashMap::new();
+    for utxo in utxos {
+        txmap.entry(utxo.txid).or_default().push(utxo);
+    }
+
+    for utxos in txmap.into_values() {
+        // check if we know the secret to any of the spks
+        let mut secret = None;
+        for utxo in utxos.iter() {
+            let spk = utxo.scriptpubkey.as_bytes();
+            if let Some(s) = secrets_map.get(spk) {
+                secret = Some(s);
+                break;
+            }
+        }
+
+        // skip this tx if no secret is found
+        let secret = match secret {
+            Some(secret) => secret,
+            None => continue,
+        };
+
+        let output_keys: Result<Vec<XOnlyPublicKey>> = utxos
+            .iter()
+            .filter_map(|x| {
+                if x.scriptpubkey.is_p2tr() {
+                    Some(
+                        XOnlyPublicKey::from_slice(&x.scriptpubkey.as_bytes()[2..])
+                            .map_err(Error::new),
+                    )
+                } else {
+                    None
+                }
+            })
+            .collect();
+
+        let ours = sp_receiver.scan_transaction(secret, output_keys?)?;
+
+        for utxo in utxos {
+            if !utxo.scriptpubkey.is_p2tr() || utxo.spent {
+                continue;
+            }
+
+            match XOnlyPublicKey::from_slice(&utxo.scriptpubkey.as_bytes()[2..]) {
+                Ok(xonly) => {
+                    for (label, map) in ours.iter() {
+                        if let Some(scalar) = map.get(&xonly) {
+                            res.push((label.clone(), utxo, *scalar));
+                            break;
+                        }
+                    }
+                }
+                Err(_) => {
+                    // This should never happen, but we log it just in case
+                    log::error!("Failed to parse XOnlyPublicKey from utxo.scriptpubkey: {}", utxo.scriptpubkey.as_bytes().as_hex());
+                },
+            }
+        }
+    }
+
+    Ok(res)
+}
+
+/// Convert found (label, utxo, tweak) tuples into a map of outpoints to owned outputs.
+pub(crate) fn collect_found_outputs(
+    blkheight: Height,
+    found: Vec<(Option<Label>, UtxoData, Scalar)>,
+) -> HashMap<OutPoint, OwnedOutput> {
+    let mut res = HashMap::new();
+
+    for (label, utxo, tweak) in found {
+        let outpoint = OutPoint {
+            txid: utxo.txid,
+            vout: utxo.vout,
+        };
+
+        let out = OwnedOutput {
+            blockheight: blkheight,
+            tweak: tweak.to_be_bytes(),
+            amount: utxo.value,
+            script: utxo.scriptpubkey,
+            label,
+            spend_status: OutputSpendStatus::Unspent,
+        };
+
+        res.insert(outpoint, out);
+    }
+
+    res
+}
+
+/// Match spent index data against our input hashes to find spent outpoints.
+pub(crate) fn collect_spent_outpoints(
+    spent_data: Vec<Vec<u8>>,
+    input_hashes_map: &HashMap<[u8; 8], OutPoint>,
+) -> HashSet<OutPoint> {
+    let mut res = HashSet::new();
+
+    for spent in spent_data {
+        let hex: &[u8] = spent.as_ref();
+        if let Some(outpoint) = input_hashes_map.get(hex) {
+            res.insert(*outpoint);
+        }
+    }
+
+    res
+}
diff --git a/spdk-wallet/src/scanner/mod.rs b/spdk-wallet/src/scanner/mod.rs
index 2d6bea2..fa3570f 100644
--- a/spdk-wallet/src/scanner/mod.rs
+++ b/spdk-wallet/src/scanner/mod.rs
@@ -1,3 +1,4 @@
 mod scanner;
+pub(crate) mod logic;
 
 pub use scanner::SpScanner;
diff --git a/spdk-wallet/src/scanner/scanner.rs b/spdk-wallet/src/scanner/scanner.rs
index 5f87324..8f2ea33 100644
--- a/spdk-wallet/src/scanner/scanner.rs
+++ b/spdk-wallet/src/scanner/scanner.rs
@@ -4,22 +4,20 @@ use std::{
     time::{Duration, Instant},
 };
 
-use anyhow::{Error, Result, bail};
+use anyhow::{Result, bail};
 use bitcoin::{
-    Amount, BlockHash, OutPoint, Txid, XOnlyPublicKey,
+    Amount, OutPoint,
     absolute::Height,
     bip158::BlockFilter,
-    hashes::{Hash, sha256},
-    secp256k1::{PublicKey, Scalar},
+    secp256k1::PublicKey,
 };
 use futures::{Stream, StreamExt, pin_mut};
 use log::info;
-use silentpayments::receiving::Label;
 
-use spdk_core::chain::{BlockData, ChainBackend, FilterData, UtxoData};
+use spdk_core::chain::{BlockData, ChainBackend, FilterData};
 use spdk_core::updater::{SimplifiedOutput, Updater};
 
-use crate::client::SpClient;
+use crate::{client::SpClient, scanner::logic::{check_block_inputs, check_block_outputs, find_owned_in_utxos, get_input_hashes}};
 
 pub struct SpScanner<'a> {
     updater: Box<dyn Updater + Sync + Send>,
@@ -177,12 +175,13 @@ impl<'a> SpScanner<'a> {
             let blkfilter = BlockFilter::new(&new_utxo_filter.data);
             let blkhash = new_utxo_filter.block_hash;
 
-            let matched_outputs = Self::check_block_outputs(blkfilter, blkhash, candidate_spks)?;
+            let matched_outputs = check_block_outputs(blkfilter, blkhash, candidate_spks)?;
 
             //if match: fetch and scan utxos
             if matched_outputs {
                 info!("matched outputs on: {}", blkheight);
-                let found = self.scan_utxos(blkheight, secrets_map).await?;
+                let utxos = self.backend.utxos(blkheight).await?;
+                let found = find_owned_in_utxos(&self.client.sp_receiver, utxos, &secrets_map)?;
 
                 if !found.is_empty() {
                     for (label, utxo, tweak) in found {
@@ -216,11 +215,11 @@ impl<'a> SpScanner<'a> {
         let blkhash = spent_filter.block_hash;
 
         // first get the 8-byte hashes used to construct the input filter
-        let input_hashes_map = self.get_input_hashes(blkhash)?;
+        let input_hashes_map = get_input_hashes(&self.owned_outpoints, blkhash)?;
 
         // check against filter
         let blkfilter = BlockFilter::new(&spent_filter.data);
-        let matched_inputs = self.check_block_inputs(
+        let matched_inputs = check_block_inputs(
             blkfilter,
             blkhash,
             input_hashes_map.keys().cloned().collect(),
@@ -242,133 +241,6 @@ impl<'a> SpScanner<'a> {
         Ok(res)
     }
 
-    async fn scan_utxos(
-        &self,
-        blkheight: Height,
-        secrets_map: HashMap<[u8; 34], PublicKey>,
-    ) -> Result<Vec<(Option<Label>, UtxoData, Scalar)>> {
-        let utxos = self.backend.utxos(blkheight).await?;
-
-        let mut res: Vec<(Option<Label>, UtxoData, Scalar)> = vec![];
-
-        // group utxos by the txid
-        let mut txmap: HashMap<Txid, Vec<UtxoData>> = HashMap::new();
-        for utxo in utxos {
-            txmap.entry(utxo.txid).or_default().push(utxo);
-        }
-
-        for utxos in txmap.into_values() {
-            // check if we know the secret to any of the spks
-            let mut secret = None;
-            for utxo in utxos.iter() {
-                let spk = utxo.scriptpubkey.as_bytes();
-                if let Some(s) = secrets_map.get(spk) {
-                    secret = Some(s);
-                    break;
-                }
-            }
-
-            // skip this tx if no secret is found
-            let secret = match secret {
-                Some(secret) => secret,
-                None => continue,
-            };
-
-            let output_keys: Result<Vec<XOnlyPublicKey>> = utxos
-                .iter()
-                .filter_map(|x| {
-                    if x.scriptpubkey.is_p2tr() {
-                        Some(
-                            XOnlyPublicKey::from_slice(&x.scriptpubkey.as_bytes()[2..])
-                                .map_err(Error::new),
-                        )
-                    } else {
-                        None
-                    }
-                })
-                .collect();
-
-            let ours = self
-                .client
-                .sp_receiver
-                .scan_transaction(secret, output_keys?)?;
-
-            for utxo in utxos {
-                if !utxo.scriptpubkey.is_p2tr() || utxo.spent {
-                    continue;
-                }
-
-                match XOnlyPublicKey::from_slice(&utxo.scriptpubkey.as_bytes()[2..]) {
-                    Ok(xonly) => {
-                        for (label, map) in ours.iter() {
-                            if let Some(scalar) = map.get(&xonly) {
-                                res.push((label.clone(), utxo, *scalar));
-                                break;
-                            }
-                        }
-                    }
-                    Err(_) => todo!(),
-                }
-            }
-        }
-
-        Ok(res)
-    }
-
-    // Check if this block contains relevant transactions
-    fn check_block_outputs(
-        created_utxo_filter: BlockFilter,
-        blkhash: BlockHash,
-        candidate_spks: Vec<&[u8; 34]>,
-    ) -> Result<bool> {
-        // check output scripts
-        let output_keys: Vec<_> = candidate_spks
-            .into_iter()
-            .map(|spk| spk[2..].as_ref())
-            .collect();
-
-        // note: match will always return true for an empty query!
-        if !output_keys.is_empty() {
-            Ok(created_utxo_filter.match_any(&blkhash, &mut output_keys.into_iter())?)
-        } else {
-            Ok(false)
-        }
-    }
-
-    fn get_input_hashes(&self, blkhash: BlockHash) -> Result<HashMap<[u8; 8], OutPoint>> {
-        let mut map: HashMap<[u8; 8], OutPoint> = HashMap::new();
-
-        for outpoint in &self.owned_outpoints {
-            let mut arr = [0u8; 68];
-            arr[..32].copy_from_slice(&outpoint.txid.to_raw_hash().to_byte_array());
-            arr[32..36].copy_from_slice(&outpoint.vout.to_le_bytes());
-            arr[36..].copy_from_slice(&blkhash.to_byte_array());
-            let hash = sha256::Hash::hash(&arr);
-
-            let mut res = [0u8; 8];
-            res.copy_from_slice(&hash[..8]);
-
-            map.insert(res, *outpoint);
-        }
-
-        Ok(map)
-    }
-
-    // Check if this block contains relevant transactions
-    fn check_block_inputs(
-        &self,
-        spent_filter: BlockFilter,
-        blkhash: BlockHash,
-        input_hashes: Vec<[u8; 8]>,
-    ) -> Result<bool> {
-        // note: match will always return true for an empty query!
-        if !input_hashes.is_empty() {
-            Ok(spent_filter.match_any(&blkhash, &mut input_hashes.into_iter())?)
-        } else {
-            Ok(false)
-        }
-    }
-
     fn interrupt_requested(&self) -> bool {
         !self
             .keep_scanning

From 041ca3965ab7aad0d17d80f73b629623df5684f9 Mon Sep 17 00:00:00 2001
From: Sosthene <contact@sosthene.net>
Date: Mon, 23 Feb 2026 17:40:48 +0800
Subject: [PATCH 2/3] feat: add mutually exclusive sync/async features

---
 backend-blindbit-v1/src/lib.rs          |  20 +++
 spdk-core/Cargo.toml                    |   9 +-
 spdk-core/src/chain/mod.rs              |   7 +
 spdk-core/src/chain/sync_trait.rs       |  21 +++
 spdk-core/src/lib.rs                    |   6 +
 spdk-wallet/src/scanner/mod.rs          |   9 +-
 spdk-wallet/src/scanner/sync_scanner.rs | 210 ++++++++++++++++++++++++
 7 files changed, 279 insertions(+), 3 deletions(-)
 create mode 100644 spdk-core/src/chain/sync_trait.rs
 create mode 100644 spdk-wallet/src/scanner/sync_scanner.rs

diff --git a/backend-blindbit-v1/src/lib.rs b/backend-blindbit-v1/src/lib.rs
index dac46e7..c6ab4b9 100644
--- a/backend-blindbit-v1/src/lib.rs
+++ b/backend-blindbit-v1/src/lib.rs
@@ -1,6 +1,26 @@
+#[cfg(all(feature = "async", feature = "sync"))]
+compile_error!(
+    "Features `async` and `sync` are mutually exclusive. Use `--no-default-features --features sync` for a sync build."
+);
+
+#[cfg(not(any(feature = "async", feature = "sync")))]
+compile_error!("Either feature `async` or `sync` must be enabled.");
+
 pub mod api_structs;
+
+#[cfg(feature = "async")]
 mod backend;
+#[cfg(feature = "async")]
 mod client;
 
+#[cfg(feature = "sync")]
+mod sync_backend;
+#[cfg(feature = "async")]
 pub use backend::BlindbitBackend;
+#[cfg(feature = "async")]
 pub use client::BlindbitClient;
+
+#[cfg(feature = "sync")]
+pub use sync_backend::SyncBlindbitBackend;
+#[cfg(feature = "sync")]
+pub use sync_client::SyncBlindbitClient;
diff --git a/spdk-core/Cargo.toml b/spdk-core/Cargo.toml
index e6f4e83..9436197 100644
--- a/spdk-core/Cargo.toml
+++ b/spdk-core/Cargo.toml
@@ -7,10 +7,15 @@ repository.workspace = true
 [lib]
 crate-type = ["lib", "staticlib", "cdylib"]
 
+[features]
+default = ["async"]
+async = ["dep:async-trait", "dep:futures"]
+sync = []
+
 [dependencies]
 anyhow.workspace = true
-async-trait.workspace = true
+async-trait = { workspace = true, optional = true }
 bitcoin.workspace = true
-futures.workspace = true
+futures = { workspace = true, optional = true }
 serde.workspace = true
 silentpayments.workspace = true
diff --git a/spdk-core/src/chain/mod.rs b/spdk-core/src/chain/mod.rs
index afbb7db..cbaa3c4 100644
--- a/spdk-core/src/chain/mod.rs
+++ b/spdk-core/src/chain/mod.rs
@@ -1,5 +1,12 @@
 mod structs;
+
+#[cfg(feature = "sync")]
+mod sync_trait;
+#[cfg(feature = "async")]
 mod r#trait;
 
+#[cfg(feature = "async")]
 pub use r#trait::ChainBackend;
 pub use structs::*;
+#[cfg(feature = "sync")]
+pub use sync_trait::SyncChainBackend;
diff --git a/spdk-core/src/chain/sync_trait.rs b/spdk-core/src/chain/sync_trait.rs
new file mode 100644
index 0000000..6522093
--- /dev/null
+++ b/spdk-core/src/chain/sync_trait.rs
@@ -0,0 +1,21 @@
+use std::ops::RangeInclusive;
+
+use anyhow::Result;
+use bitcoin::{absolute::Height, Amount};
+
+use super::structs::{BlockData, SpentIndexData, UtxoData};
+
+pub trait SyncChainBackend {
+    fn get_block_data_for_range(
+        &self,
+        range: RangeInclusive<u32>,
+        dust_limit: Amount,
+        with_cutthrough: bool,
+    ) -> Box<dyn Iterator<Item = Result<BlockData>> + Send>;
+
+    fn spent_index(&self, block_height: Height) -> Result<SpentIndexData>;
+
+    fn utxos(&self, block_height: Height) -> Result<Vec<UtxoData>>;
+
+    fn block_height(&self) -> Result<Height>;
+}
diff --git a/spdk-core/src/lib.rs b/spdk-core/src/lib.rs
index 3b7392c..03df7cf 100644
--- a/spdk-core/src/lib.rs
+++ b/spdk-core/src/lib.rs
@@ -1,3 +1,9 @@
+#[cfg(all(feature = "async", feature = "sync"))]
+compile_error!("Features `async` and `sync` are mutually exclusive. Use `--no-default-features --features sync` for a sync build.");
+
+#[cfg(not(any(feature = "async", feature = "sync")))]
+compile_error!("Either feature `async` or `sync` must be enabled.");
+
 pub mod chain;
 pub mod constants;
 pub mod updater;
diff --git a/spdk-wallet/src/scanner/mod.rs b/spdk-wallet/src/scanner/mod.rs
index fa3570f..6f6ede6 100644
--- a/spdk-wallet/src/scanner/mod.rs
+++ b/spdk-wallet/src/scanner/mod.rs
@@ -1,4 +1,11 @@
-mod scanner;
 pub(crate) mod logic;
 
+#[cfg(feature = "async")]
+mod scanner;
+#[cfg(feature = "sync")]
+mod sync_scanner;
+
+#[cfg(feature = "async")]
 pub use scanner::SpScanner;
+#[cfg(feature = "sync")]
+pub use sync_scanner::SpScanner;
diff --git a/spdk-wallet/src/scanner/sync_scanner.rs b/spdk-wallet/src/scanner/sync_scanner.rs
new file mode 100644
index 0000000..8565662
--- /dev/null
+++ b/spdk-wallet/src/scanner/sync_scanner.rs
@@ -0,0 +1,210 @@
+use std::{
+    collections::{HashMap, HashSet},
+    sync::atomic::AtomicBool,
+    time::{Duration, Instant},
+};
+
+use anyhow::{bail, Result};
+use bitcoin::{absolute::Height, bip158::BlockFilter, secp256k1::PublicKey, Amount, OutPoint};
+use log::info;
+
+use spdk_core::chain::{BlockData, FilterData, SyncChainBackend};
+use spdk_core::updater::Updater;
+
+use crate::client::{OwnedOutput, SpClient};
+
+use super::logic;
+
+pub struct SpScanner<'a> {
+    updater: Box<dyn Updater + Sync + Send>,
+    backend: Box<dyn SyncChainBackend + Sync + Send>,
+    client: SpClient,
+    keep_scanning: &'a AtomicBool,
+    owned_outpoints: HashSet<OutPoint>,
+}
+
+impl<'a> SpScanner<'a> {
+    pub fn new(
+        client: SpClient,
+        updater: Box<dyn Updater + Sync + Send>,
+        backend: Box<dyn SyncChainBackend + Sync + Send>,
+        owned_outpoints: HashSet<OutPoint>,
+        keep_scanning: &'a AtomicBool,
+    ) -> Self {
+        Self {
+            client,
+            updater,
+            backend,
+            owned_outpoints,
+            keep_scanning,
+        }
+    }
+
+    pub fn scan_blocks(
+        &mut self,
+        start: Height,
+        end: Height,
+        dust_limit: Amount,
+        with_cutthrough: bool,
+    ) -> Result<()> {
+        if start > end {
+            bail!("bigger start than end: {} > {}", start, end);
+        }
+
+        info!("start: {} end: {}", start, end);
+        let start_time: Instant = Instant::now();
+
+        // get block data iterator
+        let range = start.to_consensus_u32()..=end.to_consensus_u32();
+        let block_data_iter =
+            self.backend
+                .get_block_data_for_range(range, dust_limit, with_cutthrough);
+
+        // process blocks using block data iterator
+        self.process_blocks(start, end, block_data_iter)?;
+
+        // time elapsed for the scan
+        info!(
+            "Blindbit scan complete in {} seconds",
+            start_time.elapsed().as_secs()
+        );
+
+        Ok(())
+    }
+
+    fn process_blocks(
+        &mut self,
+        start: Height,
+        end: Height,
+        block_data_iter: impl Iterator<Item = Result<BlockData>>,
+    ) -> Result<()> {
+        let mut update_time: Instant = Instant::now();
+
+        for blockdata in block_data_iter {
+            let blockdata = blockdata?;
+            let blkheight = blockdata.blkheight;
+            let blkhash = blockdata.blkhash;
+
+            // stop scanning and return if interrupted
+            if self.interrupt_requested() {
+                self.updater.save_to_persistent_storage()?;
+                return Ok(());
+            }
+
+            let mut save_to_storage = false;
+
+            // always save on last block or after 30 seconds since last save
+            if blkheight == end || update_time.elapsed() > Duration::from_secs(30) {
+                save_to_storage = true;
+            }
+
+            let (found_outputs, found_inputs) = self.process_block(blockdata)?;
+
+            if !found_outputs.is_empty() {
+                save_to_storage = true;
+                self.updater
+                    .record_block_outputs(blkheight, blkhash, found_outputs)?;
+            }
+
+            if !found_inputs.is_empty() {
+                save_to_storage = true;
+                self.updater
+                    .record_block_inputs(blkheight, blkhash, found_inputs)?;
+            }
+
+            // tell the updater we scanned this block
+            self.updater.record_scan_progress(start, blkheight, end)?;
+
+            if save_to_storage {
+                self.updater.save_to_persistent_storage()?;
+                update_time = Instant::now();
+            }
+        }
+
+        Ok(())
+    }
+
+    fn process_block(
+        &mut self,
+        blockdata: BlockData,
+    ) -> Result<(HashMap<OutPoint, OwnedOutput>, HashSet<OutPoint>)> {
+        let BlockData {
+            blkheight,
+            tweaks,
+            new_utxo_filter,
+            spent_filter,
+            ..
+        } = blockdata;
+
+        let outs = self.process_block_outputs(blkheight, tweaks, new_utxo_filter)?;
+
+        // after processing outputs, we add the found outputs to our list
+        self.owned_outpoints.extend(outs.keys());
+
+        let ins = self.process_block_inputs(blkheight, spent_filter)?;
+
+        // after processing inputs, we remove the found inputs
+        self.owned_outpoints.retain(|item| !ins.contains(item));
+
+        Ok((outs, ins))
+    }
+
+    fn process_block_outputs(
+        &self,
+        blkheight: Height,
+        tweaks: Vec<PublicKey>,
+        new_utxo_filter: FilterData,
+    ) -> Result<HashMap<OutPoint, OwnedOutput>> {
+        if tweaks.is_empty() {
+            return Ok(HashMap::new());
+        }
+
+        let secrets_map = self.client.get_script_to_secret_map(tweaks)?;
+        let candidate_spks: Vec<&[u8; 34]> = secrets_map.keys().collect();
+
+        let blkfilter = BlockFilter::new(&new_utxo_filter.data);
+        let blkhash = new_utxo_filter.block_hash;
+
+        if !logic::check_block_outputs(blkfilter, blkhash, candidate_spks)? {
+            return Ok(HashMap::new());
+        }
+
+        info!("matched outputs on: {}", blkheight);
+        let utxos = self.backend.utxos(blkheight)?;
+        let found = logic::find_owned_in_utxos(&self.client.sp_receiver, utxos, &secrets_map)?;
+
+        Ok(logic::collect_found_outputs(blkheight, found))
+    }
+
+    fn process_block_inputs(
+        &self,
+        blkheight: Height,
+        spent_filter: FilterData,
+    ) -> Result<HashSet<OutPoint>> {
+        let blkhash = spent_filter.block_hash;
+
+        let input_hashes_map = logic::get_input_hashes(&self.owned_outpoints, blkhash)?;
+
+        let blkfilter = BlockFilter::new(&spent_filter.data);
+        let matched_inputs = logic::check_block_inputs(
+            blkfilter,
+            blkhash,
+            input_hashes_map.keys().cloned().collect(),
+        )?;
+
+        if !matched_inputs {
+            return Ok(HashSet::new());
+        }
+
+        info!("matched inputs on: {}", blkheight);
+        let spent = self.backend.spent_index(blkheight)?.data;
+
+        Ok(logic::collect_spent_outpoints(spent, &input_hashes_map))
+    }
+
+    fn interrupt_requested(&self) -> bool {
+        !self
+            .keep_scanning
+            .load(std::sync::atomic::Ordering::Relaxed)
+    }
+}

From 64bf8f6ff4aeca3605acfa4b1f568dfb05853614 Mon Sep 17 00:00:00 2001
From: Sosthene <contact@sosthene.net>
Date: Mon, 16 Feb 2026 17:19:13 +0100
Subject: [PATCH 3/3] feat: add `sync` support with `ureq` in
 backend-blindbit-v1

---
 backend-blindbit-v1/Cargo.toml          |  15 ++--
 backend-blindbit-v1/src/lib.rs          |   3 +
 backend-blindbit-v1/src/sync_backend.rs |  73 ++++++++++++++++
 backend-blindbit-v1/src/sync_client.rs  | 105 ++++++++++++++++++++++++
 4 files changed, 191 insertions(+), 5 deletions(-)
 create mode 100644 backend-blindbit-v1/src/sync_backend.rs
 create mode 100644 backend-blindbit-v1/src/sync_client.rs

diff --git a/backend-blindbit-v1/Cargo.toml b/backend-blindbit-v1/Cargo.toml
index f3813be..427b64d 100644
--- a/backend-blindbit-v1/Cargo.toml
+++ b/backend-blindbit-v1/Cargo.toml
@@ -7,14 +7,19 @@ repository.workspace = true
 [lib]
 crate-type = ["lib", "staticlib", "cdylib"]
 
+[features]
+default = ["async"]
+async = ["spdk-core/async", "dep:async-trait", "dep:futures", "dep:reqwest"]
+sync = ["spdk-core/sync", "dep:ureq"]
+
 [dependencies]
-spdk-core.workspace = true
+spdk-core = { workspace = true, default-features = false }
 
 anyhow.workspace = true
-async-trait.workspace = true
-bitcoin.workspace = true
-futures.workspace = true
+async-trait = { workspace = true, optional = true }
+futures = { workspace = true, optional = true }
 serde.workspace = true
 serde_json.workspace = true
-reqwest.workspace = true
+reqwest = { workspace = true, optional = true }
+ureq = { version = "2", features = ["json", "gzip", "tls"], optional = true }
 hex.workspace = true
diff --git a/backend-blindbit-v1/src/lib.rs b/backend-blindbit-v1/src/lib.rs
index c6ab4b9..81eeaee 100644
--- a/backend-blindbit-v1/src/lib.rs
+++ b/backend-blindbit-v1/src/lib.rs
@@ -15,6 +15,9 @@ mod client;
 
 #[cfg(feature = "sync")]
 mod sync_backend;
+#[cfg(feature = "sync")]
+mod sync_client;
+
 #[cfg(feature = "async")]
 pub use backend::BlindbitBackend;
 #[cfg(feature = "async")]
diff --git a/backend-blindbit-v1/src/sync_backend.rs b/backend-blindbit-v1/src/sync_backend.rs
new file mode 100644
index 0000000..ec9bf0e
--- /dev/null
+++ b/backend-blindbit-v1/src/sync_backend.rs
@@ -0,0 +1,73 @@
+use std::ops::RangeInclusive;
+
+use spdk_core::bitcoin::{Amount, absolute::Height};
+
+use anyhow::Result;
+use spdk_core::{BlockData, SpentIndexData, SyncChainBackend, UtxoData};
+
+use crate::SyncBlindbitClient;
+
+#[derive(Debug)]
+pub struct SyncBlindbitBackend {
+    client: SyncBlindbitClient,
+}
+
+impl SyncBlindbitBackend {
+    pub fn new(blindbit_url: String) -> Result<Self> {
+        Ok(Self {
+            client: SyncBlindbitClient::new(blindbit_url)?,
+        })
+    }
+}
+
+impl SyncChainBackend for SyncBlindbitBackend {
+    /// High-level function to get block data for a range of blocks.
+    /// Block data includes all the information needed to determine if a block is relevant for scanning,
+    /// but does not include utxos, or spent index.
+    /// These need to be fetched separately afterwards, if it is determined this block is relevant.
+    fn get_block_data_for_range(
+        &self,
+        range: RangeInclusive<u32>,
+        dust_limit: Amount,
+        with_cutthrough: bool,
+    ) -> Box<dyn Iterator<Item = Result<BlockData>> + Send> {
+        let client = self.client.clone();
+
+        let iter = range.map(move |n| {
+            let blkheight = Height::from_consensus(n)?;
+            let tweaks = match with_cutthrough {
+                true => client.tweaks(blkheight, dust_limit)?,
+                false => client.tweak_index(blkheight, dust_limit)?,
+            };
+            let new_utxo_filter = client.filter_new_utxos(blkheight)?;
+            let spent_filter = client.filter_spent(blkheight)?;
+            let blkhash = new_utxo_filter.block_hash;
+            Ok(BlockData {
+                blkheight,
+                blkhash,
+                tweaks,
+                new_utxo_filter: new_utxo_filter.into(),
+                spent_filter: spent_filter.into(),
+            })
+        });
+
+        Box::new(iter)
+    }
+
+    fn spent_index(&self, block_height: Height) -> Result<SpentIndexData> {
+        self.client.spent_index(block_height).map(Into::into)
+    }
+
+    fn utxos(&self, block_height: Height) -> Result<Vec<UtxoData>> {
+        Ok(self
+            .client
+            .utxos(block_height)?
+            .into_iter()
+            .map(Into::into)
+            .collect())
+    }
+
+    fn block_height(&self) -> Result<Height> {
+        self.client.block_height()
+    }
+}
diff --git a/backend-blindbit-v1/src/sync_client.rs b/backend-blindbit-v1/src/sync_client.rs
new file mode 100644
index 0000000..e87f6bf
--- /dev/null
+++ b/backend-blindbit-v1/src/sync_client.rs
@@ -0,0 +1,105 @@
+use std::time::Duration;
+
+use spdk_core::bitcoin::{Amount, Txid, absolute::Height, secp256k1::PublicKey};
+use ureq::Agent;
+
+use anyhow::Result;
+
+use super::api_structs::{
+    BlockHeightResponse, FilterResponse, ForwardTxRequest, InfoResponse, SpentIndexResponse,
+    UtxoResponse,
+};
+
+#[derive(Clone, Debug)]
+pub struct SyncBlindbitClient {
+    agent: Agent,
+    host_url: String,
+}
+
+impl SyncBlindbitClient {
+    pub fn new(host_url: String) -> Result<Self> {
+        let agent = ureq::AgentBuilder::new()
+            .timeout_connect(Duration::from_secs(5))
+            .timeout_read(Duration::from_secs(30))
+            .build();
+
+        // we need a trailing slash, if not present we append it
+        let host_url = if host_url.ends_with('/') {
+            host_url
+        } else {
+            format!("{}/", host_url)
+        };
+
+        Ok(SyncBlindbitClient { agent, host_url })
+    }
+
+    pub fn block_height(&self) -> Result<Height> {
+        let url = format!("{}block-height", self.host_url);
+        let body = self.agent.get(&url).call()?.into_string()?;
+        let blkheight: BlockHeightResponse = serde_json::from_str(&body)?;
+        Ok(blkheight.block_height)
+    }
+
+    pub fn tweaks(&self, block_height: Height, dust_limit: Amount) -> Result<Vec<PublicKey>> {
+        let url = format!("{}tweaks/{}", self.host_url, block_height);
+        let body = self
+            .agent
+            .get(&url)
+            .query("dustLimit", &dust_limit.to_sat().to_string())
+            .call()?
+            .into_string()?;
+        Ok(serde_json::from_str(&body)?)
+    }
+
+    pub fn tweak_index(&self, block_height: Height, dust_limit: Amount) -> Result<Vec<PublicKey>> {
+        let url = format!("{}tweak-index/{}", self.host_url, block_height);
+        let body = self
+            .agent
+            .get(&url)
+            .query("dustLimit", &dust_limit.to_sat().to_string())
+            .call()?
+            .into_string()?;
+        Ok(serde_json::from_str(&body)?)
+    }
+
+    pub fn utxos(&self, block_height: Height) -> Result<Vec<UtxoResponse>> {
+        let url = format!("{}utxos/{}", self.host_url, block_height);
+        let body = self.agent.get(&url).call()?.into_string()?;
+        Ok(serde_json::from_str(&body)?)
+    }
+
+    pub fn spent_index(&self, block_height: Height) -> Result<SpentIndexResponse> {
+        let url = format!("{}spent-index/{}", self.host_url, block_height);
+        let body = self.agent.get(&url).call()?.into_string()?;
+        Ok(serde_json::from_str(&body)?)
+    }
+
+    pub fn filter_new_utxos(&self, block_height: Height) -> Result<FilterResponse> {
+        let url = format!("{}filter/new-utxos/{}", self.host_url, block_height);
+        let body = self.agent.get(&url).call()?.into_string()?;
+        Ok(serde_json::from_str(&body)?)
+    }
+
+    pub fn filter_spent(&self, block_height: Height) -> Result<FilterResponse> {
+        let url = format!("{}filter/spent/{}", self.host_url, block_height);
+        let body = self.agent.get(&url).call()?.into_string()?;
+        Ok(serde_json::from_str(&body)?)
+    }
+
+    pub fn forward_tx(&self, tx_hex: String) -> Result<Txid> {
+        let url = format!("{}forward-tx", self.host_url);
+        let body = ForwardTxRequest::new(tx_hex);
+        let resp = self
+            .agent
+            .post(&url)
+            .send_json(serde_json::to_value(&body)?)?
+            .into_string()?;
+        Ok(serde_json::from_str(&resp)?)
+    }
+
+    pub fn info(&self) -> Result<InfoResponse> {
+        let url = format!("{}info", self.host_url);
+        let body = self.agent.get(&url).call()?.into_string()?;
+        Ok(serde_json::from_str(&body)?)
+    }
+}