Mnemonics

In HD Keys we saw that a wallet can derive its whole tree of keys from a single seed of between 16 and 64 bytes. That makes the seed the one thing a user has to back up. But people are rather bad at copying 64 bytes of hex onto a piece of paper, and worse at copying it back without a mistake.

Mnemonics, also known as seed phrases or recovery phrases, solve this. The BIP39 specification describes how a wallet turns random entropy into a short list of ordinary words, and how it later turns those words into the seed. In this section we will walk through both steps, and then follow the seed all the way to the wallet’s first key.

From entropy to words

Everything starts with entropy: a random number of 128 to 256 bits, from a secure random number generator. Figure 1 shows how a wallet turns 128 bits of entropy into twelve words. To keep the numbers easy to follow, the example uses entropy of all zeros, which is the first BIP39 test vector.

Figure 1: Turning 128 bits of entropy into a twelve-word mnemonic

Referring to Figure 1, we notice a few interesting things:

1. The entropy is hashed with SHA-256, and the first few bits of the hash are kept as a checksum: one bit for every 32 bits of entropy, so 4 bits here.
2. The checksum is appended to the entropy, giving us 132 bits.
3. The 132 bits are split into twelve groups of 11 bits. Each group is a number from 0 to 2047.
4. Each number is an index into the BIP39 word list of 2048 words. Index 0 is abandon, and index 3 is about.

All but the last of the twelve words carry nothing but entropy. The last word carries the final 7 bits of entropy together with the 4 bits of checksum, which is why, for our all-zero entropy, the last word is about and not abandon.

The more entropy we start with, the more words we end up with:

Entropy	Checksum	Words
128 bits	4 bits	12
160 bits	5 bits	15
192 bits	6 bits	18
224 bits	7 bits	21
256 bits	8 bits	24

The English word list has been chosen so that the first four letters of every word are enough to tell it apart from all the others. A wallet can complete a word as soon as the user has typed four letters, and a word that is misspelled near its end is still recognised. There are word lists for other languages too, but a mnemonic only works with the list it was made from.

When a user types their words back in, the wallet looks up each word’s index, joins the 11-bit groups back together, recomputes the checksum and compares it. A mistyped word that happens to be in the list will almost always fail this check. With only 4 bits of checksum there is a 1 in 16 chance that a wrong word slips through, which is why a wallet also checks that the restored wallet holds what the user expects.

Never choose the words yourself

The all-zero entropy in Figure 1 is a test vector, and every wallet in the world knows its words. A mnemonic is only as strong as the entropy behind it. Words picked by a person, or entropy from anything other than a secure random number generator, can be guessed, and any coins locked behind them can be taken.

From words to a seed

The words are not the seed. To get the seed, BIP39 runs the words through a key-stretching function, as in Figure 2. This figure also follows the seed through the steps described in HD Keys, down to the wallet’s first receiving key. The values are real ones, for the same twelve words and no passphrase.

Figure 2: From the mnemonic sentence to the wallet’s first key

Referring to Figure 2:

1. The mnemonic sentence, the words joined by single spaces, is used as the password for PBKDF2, a function built to be slow on purpose. It runs HMAC-SHA512 2048 times over, so that anyone trying to guess a mnemonic has to pay for 2048 rounds of hashing per guess.
2. The salt is the word mnemonic, followed by the user’s passphrase, if they chose one.
3. The result is a 64-byte seed.
4. From here on we are back in HD Keys. The seed goes through HMAC-SHA512 with the key Bitcoin seed to give the master extended key.
5. Deriving along the BIP44 path m/44'/236'/0'/0/0 gives the wallet’s first receiving key, and with it the wallet’s first Address.

Every step in this chain is deterministic. The same words, with the same passphrase, always give the same seed, the same master key, and the same keys all the way down the tree. This is what makes the mnemonic a backup.

Do note that the words are hashed as text, not as their 11-bit indexes. Before hashing, both the sentence and the passphrase are normalised to Unicode NFKD form, so that the same words typed on different keyboards give the same bytes. It also means that PBKDF2 itself never checks the checksum. Any sentence at all gives a seed, which is why a wallet checks the words against the word list and the checksum first.

The passphrase

The optional passphrase, sometimes called the “25th word”, changes the salt, and so it changes the seed completely. The same twelve words with the passphrase TREZOR give a seed starting c55257c3 in place of 5eb00bbd, and an entirely different tree of keys.

There is no such thing as a wrong passphrase. Every passphrase gives a valid seed, and a valid wallet that simply holds no coins. This can be used to keep a second wallet behind the same words, and it means that someone who finds the words alone can’t reach the wallet behind the passphrase.

A forgotten passphrase cannot be recovered

The passphrase is not stored anywhere, and the wallet can’t tell a mistyped passphrase from a different one. If the passphrase is lost, or written down wrongly, the coins in the wallet behind it are lost too, even with the words in hand.

Mnemonics in our applications

A mnemonic recovers everything that can be derived from its seed. In the applications we describe in Application Architecture, that is no longer all there is to a wallet. Keys derived with BRC-42 depend on a counterparty as well as on the seed, and a full-history wallet keeps Transactions and merkle proofs that no seed can bring back. We explain this in Wallets that keep their own history. The mnemonic remains the root of the wallet’s keys, but a complete backup has to carry the wallet’s history too.

Both of our libraries implement BIP39. You can see how to generate and validate a mnemonic, and turn it into HD keys, in DartSV and Bitcoin4J.

For the technical details of the specification, read the original BIP specification here.