Skip to content

contrib: add wallet-tools/import-pruned.py - #134

Open
Sjors wants to merge 1 commit into
masterfrom
2026/11/import-pruned
Open

Sjors wants to merge 1 commit into
masterfrom
2026/11/import-pruned

Conversation

@Sjors

@Sjors Sjors commented Nov 9, 2026 •

Copy link
Copy Markdown
Owner

A pruned node can't rescan blocks it has already deleted, so a descriptor imported into a fresh wallet with an old timestamp ends up with no history. This adds contrib/wallet-tools/import-pruned.py, which rebuilds it through importprunedfunds, the one wallet RPC that works without block data: it only needs the raw transaction and a merkle proof against a header the node still has.

The first mode, --utxo, restores the wallet's coins from the node's own UTXO set:

  1. scantxoutset with the wallet's descriptors, plus a configurable --lookahead beyond the keypool
  2. getblockfrompeer from a NODE_NETWORK peer for each block that was pruned
  3. gettxoutproof and getrawtransaction as soon as the block arrives, since it may be pruned again
  4. importprunedfunds, in derivation order so the keypool tops up as it would during a rescan

Usage:

bitcoin-cli createwallet restored
bitcoin-cli -rpcwallet=restored importdescriptors '[{"desc": "wpkh(...)", "timestamp": "now", "active": true}, ...]'
contrib/wallet-tools/import-pruned.py --wallet restored --utxo

Pass --cli "bitcoin-cli -signet" or similar to reach a non-default node, and --dry-run to only list what would be imported.

Only currently unspent coins are restored, so the balance is correct but spent history is not. Other modes, e.g. starting from a list of txids or from a script history index, can be added later.

A functional test funds a wallet on a -prune=1 -fastprune node, prunes those blocks, imports the descriptors into a blank wallet and checks that the tool restores the balance.

Restore the coins of a descriptor wallet on a pruned node, where a rescan
is no longer possible. The --utxo mode finds the wallet's unspent outputs
with scantxoutset, fetches pruned blocks from a NODE_NETWORK peer with
getblockfrompeer, builds a proof with gettxoutproof and imports each
transaction with importprunedfunds.

The functional test funds a wallet on a pruned node in blocks that are
then pruned, imports its descriptors into a fresh wallet without rescan
and checks that the tool restores the balance, including an output beyond
the initial keypool that is only found on a rerun with lookahead.
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.

1 participant