Skip to content

Conversation

@rustaceanrob
Copy link
Contributor

@rustaceanrob rustaceanrob commented Dec 2, 2025

There has been discussion offline on how to improve the experience for recovering wallets using block-by-block scanning methods. A birthday has come up multiple times, so I introduce one here in CreateParams.

I believe the expect may only be hit when attempting to over-write the genesis block. If we want to return the error, it would require a break in the error type. IMO this seems unnecessary, as a birthday should not attempt to replace genesis.

This may be used immediately in Wallet::latest_checkpoint or similar.

Changelog notice

  • Added birthday parameter to CreateParams

Checklists

All Submissions:

New Features:

  • I've added tests for the new feature
  • I've added docs for the new feature

Bugfixes:

  • This pull request breaks the existing API
  • I've added tests to reproduce the issue which are now passing
  • I'm linking the issue being fixed by this PR

There has been discussion offline on how to improve the experience for
recovering wallets using block-by-block scanning methods. A birthday has
come up multiple times, so I introduce one here in `CreateParams`.

I believe the `expect` may only be hit when attempting to over-write the
genesis block. If we want to return the error, it would require a break
in the error type. IMO this seems unnecessary, as a birthday should not
attempt to replace genesis.

This may be used immediately in `Wallet::latest_checkpoint` or similar.
@codecov
Copy link

codecov bot commented Dec 2, 2025

Codecov Report

❌ Patch coverage is 46.15385% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.93%. Comparing base (6e94275) to head (b9357a6).

Files with missing lines Patch % Lines
src/wallet/params.rs 42.85% 4 Missing ⚠️
src/wallet/mod.rs 50.00% 3 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##           master     #348      +/-   ##
==========================================
- Coverage   84.99%   84.93%   -0.07%     
==========================================
  Files          23       23              
  Lines        8237     8249      +12     
==========================================
+ Hits         7001     7006       +5     
- Misses       1236     1243       +7     
Flag Coverage Δ
rust 84.93% <46.15%> (-0.07%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

.unwrap_or(genesis_block(network).block_hash());
let (chain, chain_changeset) = LocalChain::from_genesis_hash(genesis_hash);
let (mut chain, chain_changeset) = LocalChain::from_genesis_hash(genesis_hash);
if let Some(birthday) = params.birthday {
Copy link
Contributor

Choose a reason for hiding this comment

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

How will this interact with Esplora or Electrum syncing? I do wonder if we could at least limit how far we go back in full-scan syncing.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I believe this should have no effect. Both sources are based on script pub keys and I am under the impression the different between sync and full scan should only be a matter of how many scripts are queried. I may be wrong but perhaps @oleonardolima knows more precisely.

/// Begin wallet scanning from the specified birthday. Particularly useful for block-based
/// scanning sources.
pub fn birthday(mut self, birthday: BlockId) -> Self {
self.birthday = Some(birthday);
Copy link
Contributor

Choose a reason for hiding this comment

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

Hmm, it's kind of odd to having to always having to remember the birthday outside of the wallet and setting it on CreateParams. Shouldn't the wallet itself also remember its birthday, and would it need to be persisted as part of the ChangeSet?

Copy link
Contributor

Choose a reason for hiding this comment

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

I agree that it's a better idea to persist the birthday in the ChangeSet, but that'd make it a breaking change.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

One can either immediately persist the change using take_staged, in which case they would use LoadParams next time they interact with the wallet, or they can wait for a sync result, in which case they persist and would also use LoadParams. The birthday is no longer required as long as the persistence succeeds.

@notmandatory notmandatory moved this to In Progress in BDK Wallet Dec 2, 2025
@notmandatory notmandatory added this to the Wallet 3.0.0 milestone Dec 2, 2025
@luisschwab luisschwab self-requested a review December 2, 2025 14:53
@luisschwab
Copy link
Member

I was thinking that it should be possible for a chain source's result to automatically set the wallet birthday, instead of having to set it manually based on a result. Not sure if this would require going the ChangeSet route though. cc @oleonardolima

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: In Progress

Development

Successfully merging this pull request may close these issues.

5 participants