Skip to content

btcwallet: add ImportAccountRescan#1184

Open
losh11 wants to merge 2 commits into
btcsuite:masterfrom
ltcsuite:btcwallet
Open

btcwallet: add ImportAccountRescan#1184
losh11 wants to merge 2 commits into
btcsuite:masterfrom
ltcsuite:btcwallet

Conversation

@losh11

@losh11 losh11 commented Mar 4, 2026

Copy link
Copy Markdown

Change Description

Adds account-aware recovery code to support rescanning historical transactions for imported watch-only accounts. Used by LND WalletKit's ImportAccount.

Currently, ImportAccount creates a watch-only account from an extended public key but cannot detect transactions that occurred before the import. The existing recovery system (used for seed restore) performs gap-limit-based address discovery via FilterBlocks, but is hardcoded to DefaultAccountNum. This PR makes the recovery system account-parameterized so it can be used for any account, and adds ImportAccountWithRescan which imports an account and launches a background recovery scan from a caller-specified birthday height.

This is backend-agnostic — it uses chain.Interface.FilterBlocks() which is implemented by all backends (neutrino, btcd, bitcoind).

A companion PR to lnd will wire these new methods into the ImportAccount RPC by adding birthday_height and recovery_window request fields, allowing users to trigger a historical rescan when importing an account.

Example usage:

$ lncli wallet accounts import --address_type=p2wkh --recovery_window=250 --birthday_height=500000 zpub...

Steps to Test

  1. Set up a regtest environment with btcd or bitcoind.
  2. Create wallet A, derive addresses from a BIP-84 account, fund them with transactions at various block heights.
  3. Export the account's extended public key (zpub).
  4. Create wallet B with a separate seed.
  5. Call ImportAccountWithRescan on wallet B with the zpub and a birthdayHeight at or before the first funded block.
  6. Verify that wallet B discovers the historical transactions and the correct balance is reflected.
  7. Verify that spending one of the discovered UTXOs from wallet A is detected by wallet B (outpoint spend monitoring).
  8. Test with birthdayHeight set after the funded blocks — verify those transactions are not discovered (as expected).
  9. Test gap limit behavior: fund address at index 0 and index 100, import with recoveryWindow=50 (should miss index 100) vs recoveryWindow=150 (should find both).

Pull Request Checklist

Testing

  • Your PR passes all CI checks.
  • Tests covering the positive and negative (error paths) are included.
  • Bug fixes contain tests triggering the bug to prevent regressions.

Code Style and Documentation

@yyforyongyu

Copy link
Copy Markdown
Collaborator

Thanks for the PR - just FYI the repo is undergoing a major change, including the rescanning and all the public APIs due to sqlization of the db, for more info check the milestone.

@Roasbeef Roasbeef changed the title Btcwallet btcwallet: add ImportAccountRescan Mar 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants