From 126f68984bbb33772c9d2942ec9ae39d95c4e310 Mon Sep 17 00:00:00 2001 From: thunderbiscuit Date: Tue, 26 May 2026 14:20:08 -0400 Subject: [PATCH 1/2] feat: add sync method for specific spks --- bdk-ffi/src/error.rs | 22 +++++++++++ bdk-ffi/src/wallet.rs | 87 ++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 107 insertions(+), 2 deletions(-) diff --git a/bdk-ffi/src/error.rs b/bdk-ffi/src/error.rs index 8911852f..945c8ee7 100644 --- a/bdk-ffi/src/error.rs +++ b/bdk-ffi/src/error.rs @@ -1,3 +1,4 @@ +use crate::types::KeychainKind; use crate::OutPoint; use bdk_electrum::electrum_client::Error as BdkElectrumError; @@ -784,6 +785,27 @@ pub enum RequestBuilderError { RequestAlreadyConsumed, } +/// Errors returned when selecting the derivation indices of a keychain to sync. +#[derive(Debug, thiserror::Error, uniffi::Error)] +#[uniffi::export(Debug, Display)] +pub enum SpkIndexError { + #[error("index {index} of the {keychain:?} keychain has not been revealed, the last revealed index is {last_revealed}")] + NotRevealed { + keychain: KeychainKind, + index: u32, + last_revealed: u32, + }, + + #[error("no index of the {keychain:?} keychain has been revealed")] + NoneRevealed { keychain: KeychainKind }, + + #[error("this wallet has no {keychain:?} keychain")] + KeychainNotFound { keychain: KeychainKind }, + + #[error("no spk was requested, the sync request would be empty")] + NoSpksRequested, +} + #[derive(Debug, thiserror::Error, uniffi::Error)] #[uniffi::export(Debug, Display)] pub enum SighashParseError { diff --git a/bdk-ffi/src/wallet.rs b/bdk-ffi/src/wallet.rs index 9a15cab1..699c12d9 100644 --- a/bdk-ffi/src/wallet.rs +++ b/bdk-ffi/src/wallet.rs @@ -4,7 +4,7 @@ use crate::bitcoin::{ use crate::descriptor::Descriptor; use crate::error::{ CalculateFeeError, CannotConnectError, CreateWithPersistError, DescriptorError, - LoadWithPersistError, PersistenceError, SignerError, TxidParseError, + LoadWithPersistError, PersistenceError, SignerError, SpkIndexError, TxidParseError, }; use crate::signer::SignersContainer; use crate::store::{PersistenceType, Persister}; @@ -14,7 +14,9 @@ use crate::types::{ SyncRequestBuilder, UnconfirmedTx, Update, WalletEvent, WalletKeychain, }; -use bdk_wallet::bitcoin::Network; +use bdk_wallet::bitcoin::{Network, ScriptBuf}; +use bdk_wallet::chain::spk_client::SyncRequest as BdkSyncRequest; +use bdk_wallet::chain::spk_client::SyncRequestBuilder as BdkSyncRequestBuilder; use bdk_wallet::keys::KeyMap; #[allow(deprecated)] use bdk_wallet::signer::SignOptions as BdkSignOptions; @@ -940,6 +942,62 @@ impl Wallet { Arc::new(SyncRequestBuilder(Mutex::new(Some(builder)))) } + /// Create a partial [`SyncRequest`] for a specific set of derivation indices. + /// + /// Only the spks at the given indices are included. Every index must have been revealed on + /// its keychain, otherwise a [`SpkIndexError`] is returned and no request is built. + /// + /// A keychain can be left out of the request entirely by passing an empty list (the default) + /// for its indices, which is also what makes this usable on a wallet without an internal + /// keychain. Leaving out both keychains is refused with a [`SpkIndexError`], since the + /// resulting request would carry no spk at all. + #[uniffi::method(default(external_indices = [], internal_indices = []))] + pub fn start_sync_with_spk_indices( + &self, + external_indices: Vec, + internal_indices: Vec, + ) -> Result, SpkIndexError> { + let wallet = self.get_wallet(); + let spk_index = wallet.spk_index(); + + if external_indices.is_empty() && internal_indices.is_empty() { + return Err(SpkIndexError::NoSpksRequested); + } + + let mut spks = Vec::with_capacity(external_indices.len() + internal_indices.len()); + for (keychain, indices) in [ + (KeychainKind::External, external_indices), + (KeychainKind::Internal, internal_indices), + ] { + if indices.is_empty() { + continue; + } + if spk_index.get_descriptor(keychain).is_none() { + return Err(SpkIndexError::KeychainNotFound { keychain }); + } + let last_revealed = spk_index + .last_revealed_index(keychain) + .ok_or(SpkIndexError::NoneRevealed { keychain })?; + + for index in indices { + if index > last_revealed { + return Err(SpkIndexError::NotRevealed { + keychain, + index, + last_revealed, + }); + } + let spk = spk_index + .spk_at_index(keychain, index) + .expect("revealed index must have an spk"); + spks.push(((keychain, index), spk)); + } + } + + let builder = partial_sync_request_builder(&wallet, spks); + Ok(Arc::new(SyncRequestBuilder(Mutex::new(Some(builder))))) + } + /// Persist staged changes of wallet into persister. /// /// Returns whether any new changes were persisted. @@ -1004,3 +1062,28 @@ impl Wallet { self.inner_mutex.lock().expect("wallet") } } + +/// Build a partial [`SyncRequest`] over `spks` for a wallet. +/// +/// Besides the spks themselves, the request carries the wallet's chain tip (so the chain source +/// can produce a chain update which the wallet can connect to its local chain) and the txids the +/// wallet expects to see under its spks (so that a transaction which has been evicted from the +/// mempool, or replaced, can be detected as missing). Expected txids are looked up per spk by the +/// chain source, so entries for spks which are not part of `spks` are simply ignored. +fn partial_sync_request_builder( + wallet: &BdkWallet, + spks: impl IntoIterator, +) -> BdkSyncRequestBuilder<(KeychainKind, u32)> { + let chain_tip = wallet.local_chain().tip(); + let expected_spk_txids = wallet.tx_graph().list_expected_spk_txids( + wallet.local_chain(), + chain_tip.block_id(), + wallet.spk_index(), + .., + ); + + BdkSyncRequest::builder() + .chain_tip(chain_tip) + .spks_with_indexes(spks) + .expected_spk_txids(expected_spk_txids) +} From f0d493552ea39253206e32c15171da658ad926e4 Mon Sep 17 00:00:00 2001 From: thunderbiscuit Date: Tue, 13 Oct 2026 15:56:26 -0400 Subject: [PATCH 2/2] test: add kotlin and swift tests for custom sync --- .../org/bitcoindevkit/CustomSyncTest.kt | 186 ++++++++++++++++++ .../BitcoinDevKitTests/CustomSyncTests.swift | 134 +++++++++++++ 2 files changed, 320 insertions(+) create mode 100644 bdk-android/lib/src/androidTest/kotlin/org/bitcoindevkit/CustomSyncTest.kt create mode 100644 bdk-swift/Tests/BitcoinDevKitTests/CustomSyncTests.swift diff --git a/bdk-android/lib/src/androidTest/kotlin/org/bitcoindevkit/CustomSyncTest.kt b/bdk-android/lib/src/androidTest/kotlin/org/bitcoindevkit/CustomSyncTest.kt new file mode 100644 index 00000000..a8456f8e --- /dev/null +++ b/bdk-android/lib/src/androidTest/kotlin/org/bitcoindevkit/CustomSyncTest.kt @@ -0,0 +1,186 @@ +package org.bitcoindevkit + +import androidx.test.ext.junit.runners.AndroidJUnit4 +import org.junit.runner.RunWith +import kotlin.test.Test +import kotlin.test.assertEquals +import kotlin.test.assertFailsWith + +private fun ByteArray.toHex(): String = joinToString("") { "%02x".format(it) } + +@RunWith(AndroidJUnit4::class) +class CustomSyncTest { + // Records the scripts a sync request actually carries (as hex, since `Script` has no value + // equality), and remembers the total it reports. + private class SpkRecorder : SyncScriptInspector { + val scripts = mutableListOf() + var lastTotal: ULong = 0u + + override fun inspect(script: Script, total: ULong) { + scripts.add(script.toBytes().toHex()) + lastTotal = total + } + } + + // The hex scripts the wallet derives at the given indices of a keychain. + private fun Wallet.scriptsAt(keychain: KeychainKind, indices: List): List = + indices.map { peekAddress(keychain, it).address.scriptPubkey().toBytes().toHex() } + + private fun walletWithRevealedAddresses(upTo: UInt): Wallet { + val wallet = Wallet( + descriptor = BIP84_DESCRIPTOR, + changeDescriptor = BIP84_CHANGE_DESCRIPTOR, + network = Network.REGTEST, + persister = Persister.newInMemory() + ) + wallet.revealAddressesTo(KeychainKind.EXTERNAL, upTo) + wallet.revealAddressesTo(KeychainKind.INTERNAL, upTo) + return wallet + } + + // A sync request built from a specific set of indices carries only those scripts, rather than + // every revealed script of the wallet. + @Test + fun syncWithSpecificIndices() { + val wallet = walletWithRevealedAddresses(upTo = 20u) + val recorder = SpkRecorder() + val externalIndices = listOf(0u, 5u, 20u) + val internalIndices = listOf(3u) + + val syncRequest: SyncRequest = wallet + .startSyncWithSpkIndices( + externalIndices = externalIndices, + internalIndices = internalIndices + ) + .inspectSpks(recorder) + .build() + + ElectrumClient(ELECTRUM_REGTEST_URL).sync( + request = syncRequest, + batchSize = 10u, + fetchPrevTxouts = true + ) + + // 4 scripts requested, against the 42 a full `startSyncWithRevealedSpks()` would have used. + assertEquals(4, recorder.scripts.size, "Only the 4 requested scripts should be synced") + assertEquals(4uL, recorder.lastTotal, "The request should report a total of 4 scripts") + assertEquals( + expected = (wallet.scriptsAt(KeychainKind.EXTERNAL, externalIndices) + + wallet.scriptsAt(KeychainKind.INTERNAL, internalIndices)).toSet(), + actual = recorder.scripts.toSet(), + message = "The synced scripts should be exactly those at the requested indices" + ) + } + + // A keychain left out of the call contributes nothing to the request, so a sync can cover the + // internal keychain alone. + @Test + fun syncWithInternalIndicesOnly() { + val wallet = walletWithRevealedAddresses(upTo = 20u) + val recorder = SpkRecorder() + val internalIndices = listOf(0u, 1u) + + val syncRequest: SyncRequest = wallet + .startSyncWithSpkIndices(internalIndices = internalIndices) + .inspectSpks(recorder) + .build() + + ElectrumClient(ELECTRUM_REGTEST_URL).sync( + request = syncRequest, + batchSize = 10u, + fetchPrevTxouts = true + ) + + assertEquals(2, recorder.scripts.size, "Only the 2 requested internal scripts should be synced") + assertEquals( + expected = wallet.scriptsAt(KeychainKind.INTERNAL, internalIndices).toSet(), + actual = recorder.scripts.toSet(), + message = "The synced scripts should be exactly the requested internal ones" + ) + } + + // An index past the last revealed one is refused: the wallet's indexer does not track it, so + // any transaction found there would not be recognized as the wallet's own. + @Test + fun syncWithUnrevealedIndexFails() { + val wallet = walletWithRevealedAddresses(upTo = 5u) + + val exception = assertFailsWith { + wallet.startSyncWithSpkIndices(externalIndices = listOf(0u, 6u)) + } + + assertEquals( + expected = "index 6 of the External keychain has not been revealed, the last revealed index is 5", + actual = exception.toString() + ) + assertEquals(expected = KeychainKind.EXTERNAL, actual = exception.keychain) + assertEquals(expected = 6u, actual = exception.index) + assertEquals(expected = 5u, actual = exception.lastRevealed) + } + + // A wallet which has not revealed anything yet has no index to sync. + @Test + fun syncOnWalletWithoutRevealedAddressesFails() { + val wallet = Wallet( + descriptor = BIP84_DESCRIPTOR, + changeDescriptor = BIP84_CHANGE_DESCRIPTOR, + network = Network.REGTEST, + persister = Persister.newInMemory() + ) + + val exception = assertFailsWith { + wallet.startSyncWithSpkIndices(externalIndices = listOf(0u)) + } + + assertEquals( + expected = "no index of the External keychain has been revealed", + actual = exception.toString() + ) + } + + // A request which would carry no script at all is refused rather than quietly turning into a + // sync that only refreshes the chain tip. + @Test + fun syncWithoutAnySpkFails() { + val wallet = walletWithRevealedAddresses(upTo = 5u) + + val exception = assertFailsWith { + wallet.startSyncWithSpkIndices() + } + assertEquals( + expected = "no spk was requested, the sync request would be empty", + actual = exception.toString() + ) + + assertFailsWith { + wallet.startSyncWithSpkIndices(externalIndices = emptyList(), internalIndices = emptyList()) + } + } + + // A single-descriptor wallet has no internal keychain, so asking for internal indices fails + // rather than quietly syncing external scripts. + @Test + fun syncInternalIndicesOnSingleDescriptorWalletFails() { + val wallet = Wallet.createSingle( + descriptor = BIP84_DESCRIPTOR, + network = Network.REGTEST, + persister = Persister.newInMemory() + ) + wallet.revealAddressesTo(KeychainKind.EXTERNAL, 5u) + + val indicesException = assertFailsWith { + wallet.startSyncWithSpkIndices( + externalIndices = listOf(0u), + internalIndices = listOf(0u) + ) + } + assertEquals( + expected = "this wallet has no Internal keychain", + actual = indicesException.toString() + ) + + // Leaving the missing keychain out of the request is fine, as is passing it an empty list. + wallet.startSyncWithSpkIndices(externalIndices = listOf(0u)) + wallet.startSyncWithSpkIndices(externalIndices = listOf(0u), internalIndices = emptyList()) + } +} diff --git a/bdk-swift/Tests/BitcoinDevKitTests/CustomSyncTests.swift b/bdk-swift/Tests/BitcoinDevKitTests/CustomSyncTests.swift new file mode 100644 index 00000000..782f073a --- /dev/null +++ b/bdk-swift/Tests/BitcoinDevKitTests/CustomSyncTests.swift @@ -0,0 +1,134 @@ +import XCTest +@testable import BitcoinDevKit + +final class CustomSyncTests: XCTestCase { + private let descriptor = try! Descriptor( + descriptor: "wpkh(tprv8ZgxMBicQKsPf2qfrEygW6fdYseJDDrVnDv26PH5BHdvSuG6ecCbHqLVof9yZcMoM31z9ur3tTYbSnr1WBqbGX97CbXcmp5H6qeMpyvx35B/84h/1h/1h/0/*)", + networkKind: NetworkKind.test + ) + private let changeDescriptor = try! Descriptor( + descriptor: "wpkh(tprv8ZgxMBicQKsPf2qfrEygW6fdYseJDDrVnDv26PH5BHdvSuG6ecCbHqLVof9yZcMoM31z9ur3tTYbSnr1WBqbGX97CbXcmp5H6qeMpyvx35B/84h/1h/1h/1/*)", + networkKind: NetworkKind.test + ) + + private func walletWithRevealedAddresses(upTo index: UInt32) throws -> Wallet { + let wallet = try Wallet( + descriptor: descriptor, + changeDescriptor: changeDescriptor, + network: .signet, + persister: try Persister.newInMemory() + ) + _ = wallet.revealAddressesTo(keychain: KeychainKind.external, index: index) + _ = wallet.revealAddressesTo(keychain: KeychainKind.`internal`, index: index) + return wallet + } + + // A request can be built from a specific set of revealed indices on either keychain, instead of + // every revealed script of the wallet. The request is then passed to a client as usual. + func testSyncRequestFromSpkIndices() throws { + let wallet = try walletWithRevealedAddresses(upTo: 20) + + let request: SyncRequest = try wallet + .startSyncWithSpkIndices(externalIndices: [0, 5, 20], internalIndices: [3]) + .build() + + XCTAssertNotNil(request) + } + + // A keychain left out of the call contributes nothing to the request, so a request can cover + // the internal keychain alone. + func testSyncRequestFromInternalIndicesOnly() throws { + let wallet = try walletWithRevealedAddresses(upTo: 20) + + let request: SyncRequest = try wallet + .startSyncWithSpkIndices(internalIndices: [0, 1]) + .build() + + XCTAssertNotNil(request) + } + + // An index past the last revealed one is refused: the wallet's indexer does not track it, so + // any transaction found there would not be recognized as the wallet's own. + func testSyncWithUnrevealedIndexThrows() throws { + let wallet = try walletWithRevealedAddresses(upTo: 5) + + XCTAssertThrowsError( + try wallet.startSyncWithSpkIndices(externalIndices: [0, 6]) + ) { error in + guard case let SpkIndexError.NotRevealed(keychain, index, lastRevealed) = error else { + return XCTFail("Expected a NotRevealed error, got \(error)") + } + XCTAssertEqual(keychain, KeychainKind.external) + XCTAssertEqual(index, 6) + XCTAssertEqual(lastRevealed, 5) + XCTAssertEqual( + (error as! SpkIndexError).description, + "index 6 of the External keychain has not been revealed, the last revealed index is 5" + ) + } + } + + // A wallet which has not revealed anything yet has no index to sync. + func testSyncOnWalletWithoutRevealedAddressesThrows() throws { + let wallet = try Wallet( + descriptor: descriptor, + changeDescriptor: changeDescriptor, + network: .signet, + persister: try Persister.newInMemory() + ) + + XCTAssertThrowsError( + try wallet.startSyncWithSpkIndices(externalIndices: [0]) + ) { error in + guard case let SpkIndexError.NoneRevealed(keychain) = error else { + return XCTFail("Expected a NoneRevealed error, got \(error)") + } + XCTAssertEqual(keychain, KeychainKind.external) + } + } + + // A request which would carry no script at all is refused rather than quietly turning into a + // sync that only refreshes the chain tip. + func testSyncWithoutAnySpkThrows() throws { + let wallet = try walletWithRevealedAddresses(upTo: 5) + + XCTAssertThrowsError(try wallet.startSyncWithSpkIndices()) { error in + guard case SpkIndexError.NoSpksRequested = error else { + return XCTFail("Expected a NoSpksRequested error, got \(error)") + } + XCTAssertEqual( + (error as! SpkIndexError).description, + "no spk was requested, the sync request would be empty" + ) + } + + XCTAssertThrowsError( + try wallet.startSyncWithSpkIndices(externalIndices: [], internalIndices: []) + ) + } + + // A single-descriptor wallet has no internal keychain, so asking for internal scripts fails + // rather than quietly syncing external ones. + func testSyncInternalIndicesOnSingleDescriptorWalletThrows() throws { + let wallet = try Wallet.createSingle( + descriptor: descriptor, + network: .signet, + persister: try Persister.newInMemory() + ) + _ = wallet.revealAddressesTo(keychain: KeychainKind.external, index: 5) + + XCTAssertThrowsError( + try wallet.startSyncWithSpkIndices(externalIndices: [0], internalIndices: [0]) + ) { error in + guard case let SpkIndexError.KeychainNotFound(keychain) = error else { + return XCTFail("Expected a KeychainNotFound error, got \(error)") + } + XCTAssertEqual(keychain, KeychainKind.`internal`) + } + + // Asking for nothing on the missing keychain is fine. + XCTAssertNoThrow( + try wallet.startSyncWithSpkIndices(externalIndices: [0]) + ) + } +}