Repository navigation
Add custom sync methods #1012
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add custom sync methods #1012
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| 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()) | ||
| } | ||
| } |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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<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. | ||
|
|
@@ -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) | ||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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
Collaborator
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. |
||
| } | ||
Uh oh!
There was an error while loading. Please reload this page.