wallet: add BIP39 mnemonic support to addhdkey #35857

pull mateusz-klatt wants to merge 5 commits into bitcoin:master from mateusz-klatt:wallet-bip39-import changing 11 files +2832 −4

mateusz-klatt commented at 8:34 PM on July 31, 2026: none
Allows addhdkey to derive and import a BIP 32 master key from an English BIP 39 mnemonic and an optional ASCII passphrase.

Only the derived key is stored. Creating active descriptors and rescanning remain explicit steps.

Motivation
- Enable recovery and import workflows for an existing wallet from a mnemonic without first converting the seed phrase to an xprv using an external tool.
- Reduce exposure of the mnemonic to additional software.
Changes
- Allow addhdkey to accept a mnemonic as an alternative to hdkey, together with an optional bip39_passphrase.
- Support the English word list and ASCII-only passphrases.
- Validate the word count, word-list membership, and checksum.
- Store only the derived HD key in the wallet.
- Do not create active descriptors or initiate a blockchain rescan.
Tests

The following tests were run locally:
- Unit tests: src/wallet/test/bip39_tests.cpp (build/bin/test_bitcoin --run_test=bip39_tests)
- Fuzz targets: bip39 and bip39_valid in src/wallet/test/fuzz/bip39.cpp (built and smoke-tested with empty input)
- Functional tests: test/functional/wallet_hd.py (build/test/functional/wallet_hd.py --portseed=5301)
- Full CTest suite: ctest --test-dir build --output-on-failure -j12 (completed without failures; script_assets_tests was skipped)

wallet: add BIP 39 mnemonic decoder

Implement validation for English-wordlist BIP 39 mnemonics and derive
the corresponding BIP 32 master key with PBKDF2-HMAC-SHA512.
Restrict passphrases to ASCII so normalization is unambiguous without
adding a Unicode dependency, and cleanse intermediate secret buffers.

Validate the decoder against official vectors, every supported word
count, checksum failures, whitespace normalization, and passphrase
edge cases.

e03ea149ca

wallet: support BIP 39 mnemonics in addhdkey

Allow addhdkey to derive a BIP 32 master key from an English BIP 39
mnemonic and an optional ASCII passphrase. Keep the random and xprv
flows unchanged, and store only the derived key through the unused
descriptor.

Document the import-only recovery flow and passphrase behavior. Add
functional coverage for argument validation, encrypted wallets,
descriptor creation, and recovery of a transaction that predates the
wallet import.

e0b0ee5c73

test: add BIP 39 mnemonic fuzz targets

Exercise arbitrary uncapped mnemonic inputs in a fast parser target.
Add a structured target that constructs valid mnemonics at every
supported word count, varies ASCII whitespace and passphrases, and
reaches checksum validation, PBKDF2, and BIP 32 derivation.

af39030598

DrahtBot added the label Wallet on Jul 31, 2026
DrahtBot commented at 8:34 PM on July 31, 2026: contributor



The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.



Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/35857.



Reviews

See the guideline and AI policy for information on the review process. A summary of reviews will appear here.
doc: add BIP 39 entry and release note 749ca97b66

wallet: add mnemonic examples to addhdkey help

Show the named-argument mnemonic flow next to the existing xprv
examples.

966fdf08b7

Contributors

mateusz-klatt

DrahtBot

Labels

Wallet

wallet: add BIP39 mnemonic support to addhdkey #35857

Motivation

Changes

Tests

Code Coverage & Benchmarks

Reviews