support BIP39 mnemonic in descriptors

jonasschnelli commented at 6:39 am on June 3, 2020: contributor

Supporting BIP39 mnemonic in descriptors would allow less painful imports and scans of third party wallet seeds.

I think it could be used almost identical as the existing xpriv key.

Example: pkh(bip39(room,cross,cube,glance,infant,setup,renew,more,lion,glimpse,retreat,tone,chief,vanish,brisk,destroy,destroy,bounce,knee,analyst,autumn,meadow,divorce,since)/44'/0'/0'/0/0) (or slightly different to support the “passphrase”)

jonasschnelli added the label Feature on Jun 3, 2020

yancyribbens commented at 5:32 am on June 23, 2020: contributor

Wouldn’t this require at least partial implementation of BIP39 (generating the seed from the mnemonic)? It seems like there’s a long history about why parts of BIP39 have not been included in the wallet to date.

RobinLinus commented at 0:12 am on July 19, 2020: none

Wouldn’t this require at least partial implementation of BIP39 (generating the seed from the mnemonic)? It seems like there’s a long history about why parts of BIP39 have not been included in the wallet to date.

Whether we like it or not, BIP39 is the de facto standard for seed backups. At this point, not including it in core only forces people to use less secure wallet software…

andronoob commented at 3:42 am on August 13, 2020: none

BIP39 is the de facto standard for seed backups

In fact any wallet app should also take care of ambiguity brought by seed formats like Electrum2.0 and aezeed etc…

I don’t think BIP39 is ideal either, I just think the attempts to “fix” this problem usually make the situation even worse in the end.

RobinLinus commented at 8:48 am on August 26, 2020: none

How would you support the passphrase? What do you think about

pkh(bip39([room,cross,cube,glance,infant,setup,renew,more,lion,glimpse,retreat,tone,chief,vanish,brisk,destroy,destroy,bounce,knee,analyst,autumn,meadow,divorce,since],passphrase)/44'/0'/0'/0/0)

?

junderw commented at 1:18 am on February 17, 2021: contributor

Support for bip39 is impossible unless we restrict it to English only, or only languages that use characters within the input character set for descriptors.

bip39 supports the entirety of the unicode set, normalized with NFKD and decoded into UTF-8 bytes.

afaik, descriptors have a limited set of input characters for the checksum, and therefore can not support BIP39

“Support for a subset of possible BIP39 phrases (English only)” would be more correct.

maletor commented at 5:22 pm on March 3, 2021: none

BIP39 is already english only with its dictionary, I’m pretty sure…

junderw commented at 10:08 pm on March 3, 2021: contributor

BIP39 is already english only with its dictionary, I’m pretty sure…

https://github.com/bitcoin/bips/blob/333fc69ab9e6ba6d7ced5236db25f599cd6041b3/bip-0039.mediawiki#wordlist

From the BIP:

The wordlist can contain native characters, but they must be encoded in UTF-8 using Normalization Form Compatibility Decomposition (NFKD).

Therefore English-only support is technically only supporting a subset of possible BIP39 phrases.

ghost commented at 3:01 am on March 4, 2021: none

According to this answer on a website which is considered for lot of issues and PRs in bitcoin core: https://bitcoin.stackexchange.com/a/88244/

BIP 39 is not secure.

Has anything changed? Or using it in descriptors is secure?

Cc: @achow101

Sjors commented at 12:24 pm on April 9, 2021: member

I think the context of that Stack Overflow answer is about the wallet Bitcoin Core generates itself. I don’t see any objection to importing such wallets.

junderw commented at 1:05 pm on April 9, 2021: contributor

@Sjors the implementation comments still stand though.

Core currently doesn’t support 512 bit hashes or PBKDF2 hashing, and adding those just to restore external wallets that we never plan to implement in the core’s wallet module… is unnecessary bloat.

Sjors commented at 3:15 pm on April 9, 2021: member

The wallet seed is stored as (coerced into) a CKey which is constrained to 32 bytes. With descriptor wallets it’s probably more doable to add a new seed storage mechanism.

I do think there’s a use case for migrating funds from a mnemonic backup to a Bitcoin Core wallet (with or without a sweep). BIP39 mnemonics are abundant and there’s probably plenty of people who no longer have - or trust - the original wallet that generated it. Right now the only practical way to do that is to import the mnemonic in an arbitrary other (hardware) wallet and then send the coins.

But it’s a non trivial change. Perhaps it’s better left to when we have an additional use case for a different seed storage.

That still leaves the possibility of a watch-only import. Arguably this is dangerous and users should instead import an account level xpub if they need a watch-only wallet.

As far hashing, we do have HMAC-SHA-512: https://github.com/bitcoin/bitcoin/blob/master/src/crypto/hmac_sha512.h

Assuming this earlier attempt by @mateusz is correct, implementing PBKDF2 pretty short: https://github.com/bitcoin/bitcoin/pull/20361/commits/7e6ba0a3278ff0938c617a234ff07be8a20b06ed#diff-72f3c3f065865085863d0a6577e18effa07a22f3fc2df6e77b5f7089159bc031

Sjors commented at 9:28 am on April 19, 2023: member

Briefly looked at this again. Importing with private key functionality seems doable (not just watch-only).

We need to store the extended private key of the root node (easier after #26728): internally our wallet does this by storing the full extended public key and a regular CKey for the private key.
We don’t have to store the mnemonic. But if we wanted to, we have to make sure it gets encrypted along with other private key material.
Both seed and passphrase would (initially) be constrained to English, more precisely, these characters (see descriptors.cpp):

00123456789()[],'/*abcdefgh@:$%{}
1IJKLMNOPQRSTUVWXYZ&+-.;<=>?!^_|~
2ijklmnopqrstuvwxyzABCDEFGH`#"\

That restriction just needs clear documentation “You can’t import […]”.

The mnemonic (not the password) should be restricted to valid BIP39 (lower case, matching checksum)
Add a warning if the length is unusual (not 12 or 24 words)
The regular descriptor wallet creation process already uses BIP44/etc derivations. Users can add custom derivations if needed (perhaps by expanding createwalletdescriptor after #25907).
PBKDF2 can use existing HMAC-SHA-512 (see comment above)
It needs a BIP (in the BIP-380 series)
Restoring a wallet should be very quick on an unpruned node with -blockfilterindex=1 and even quicker after #26951

Sjors commented at 5:01 pm on March 21, 2025: member

#32115 may be useful

Sjors commented at 10:24 am on March 24, 2025: member

Every attempt to do this has been met with concept NACKs or lack of review. Maybe we should just decide to not do this and close?

sipa commented at 12:15 pm on March 24, 2025: member

I really don’t see a problem with, or difficulty implementing, support for bip39 in descriptor parsing. Internally it would be mapped to an xpub instead, so listdescriptors etc wouldn’t be able to echo the words back to you, but functionality-wise, that is no different from what #32115 achieved.

support BIP39 mnemonic in descriptors #19151