Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -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<String>()
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<UInt>): List<String> =
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<SpkIndexException.NotRevealed> {
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<SpkIndexException.NoneRevealed> {
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<SpkIndexException.NoSpksRequested> {
wallet.startSyncWithSpkIndices()
}
assertEquals(
expected = "no spk was requested, the sync request would be empty",
actual = exception.toString()
)

assertFailsWith<SpkIndexException.NoSpksRequested> {
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<SpkIndexException.KeychainNotFound> {
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())
}
}
22 changes: 22 additions & 0 deletions bdk-ffi/src/error.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
use crate::types::KeychainKind;
use crate::OutPoint;

use bdk_electrum::electrum_client::Error as BdkElectrumError;
Expand Down Expand Up @@ -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 {
Expand Down
87 changes: 85 additions & 2 deletions bdk-ffi/src/wallet.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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};
Expand All @@ -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;
Expand Down Expand Up @@ -940,6 +942,62 @@ impl Wallet {
Arc::new(SyncRequestBuilder(Mutex::new(Some(builder))))
}

/// Create a partial [`SyncRequest`] for a specific set of derivation indices.
Comment thread
thunderbiscuit marked this conversation as resolved.
Resolved
///
/// 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<u32>,
internal_indices: Vec<u32>,
) -> Result<Arc<SyncRequestBuilder>, 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.
Expand Down Expand Up @@ -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<Item = ((KeychainKind, u32), ScriptBuf)>,
) -> 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)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might want to add a rust test checking that the custom request preserves the wallets chain tip and expected transaction IDs for the selected scripts to possibly would help catch regressions in the metadata needed for eviction tracking? Non-blocking

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one at the Rust layer (which doesn't use/see regtest) requires building custom transactions and whatnot, and I propose we leave it out. Let me know if you'd rather I add it.

}
Loading
Loading