Bitcoin mnemonic phrase in Elixir

How to backup and recover a Bitcoin wallet using Elixir?

This article is a follow-up of the previous one about creating a wallet and calculating Bitcoin address in Elixir. If you are interested, you can read it here:

You should already know that a wallet in general is used to store your keys, and its public address is derived from a private key.

A wallet does NOT store any coins but it queries the blockchain to search for unspent transaction outputs ( UTXO ) for its own address, and display their balance. They are the only coins that can be transferred using the private key.

What if I lose my wallet?

If you lose your wallet (you lose your private key), you also lose the access to your coins. You are not able to spend UTXO anymore.

In this article, you will learn how to backup and recover your private key, and get your money back. I will also explain more details about different kinds of wallets as this is the continuation of the Blockchain series on this blog.

N on-Deterministic wallets

These kind of wallets are used to not only store private keys but also to create them. They generate private keys along with corresponding public addresses. The new keys are generated randomly, with no correlation to one another, and without any predictable algorithm — hence the name “non-deterministic”.

You’ve probably figured out by now that you must do frequent backups of these private keys regularly.

Deterministic wallets

They use from 12 to 24 ordered mnemonic words (which are supposed to be easy to memorize) to create a seed used to restore master private key and recreate the wallet.

A mnemonic phrase is a list of words which stores all the information needed to recover a Bitcoin wallet. Wallet software will typically generate a mnemonic backup phrase and instruct the user to write it down on paper. If the user’s computer breaks or their hard drive becomes corrupted, they can download the same wallet software again and use the paper backup to get their bitcoins back.

Using mnemonic words always creates the same seed hence the name “deterministic”. You should store them as safely as your keys.

Anybody else who discovers the phrase can steal the coins, so it must be kept safe like cash. For example, it must not be typed into any website.

Bitcoin Improvement Proposal (BIP)

There’s a list of design documents for introducing features in Bitcoin:

BIP-39

This BIP describes the implementation of a mnemonic sentence. It consists of two parts: generating the mnemonic, and converting it into a binary seed.

The English-language wordlist for the BIP39 standard has 2048 words, so if the phrase contained only 12 random words, the number of possible combinations would be 2048¹² = 2¹³² and the phrase would have 132 security bits. However, some of the data in a BIP39 phrase is not random, so the actual security of a 12 -word BIP39 mnemonic phrase is only 128 bits. This is approximately the same strength as all Bitcoin private keys, so most experts consider it to be sufficiently secure.

It is not safe to invent your own mnemonic phrase because we are bad at generating randomness. The best way is to allow the wallet software to generate the phrase which you write down.

Implementation

Ok, enough theory. Once you are familiar with all of that, you can jump into the practice.

The wallet software has an ordered and indexed wordlist taken from a dictionary. The mnemonic phrase can be converted to a number which is used as a seed to a deterministic wallet that generates all the keys.

The following table describes the relation between the initial entropy length ( ENT ), the checksum length ( CS ), and the length of the generated mnemonic sentence ( MS ) in words.

CS = ENT / 32

MS = (ENT + CS) / 11 | ENT | CS | ENT+CS | MS |

+-------+----+--------+------+

| 128 | 4 | 132 | 12 |

| 160 | 5 | 165 | 15 |

| 192 | 6 | 198 | 18 |

| 224 | 7 | 231 | 21 |

| 256 | 8 | 264 | 24 |

It can be represented programatically as:

Generating random bytes

Firstly, we can generate random bytes with the given strength. To do that, we leverage :crypto.strong_rand_bytes/1 function directly from erlang .

The mnemonic must encode entropy in a multiple of 32 bits. With more entropy, security is improved but the sentence length increases. The allowed size of the initial entropy length ( ENT ) is 128–256 bits. We will use the strongest one to generate 24 words.

Convert the initial entropy length to the number bytes and generate random ones.

Binary number

We will be working on a binary number stored as a string and derived from our entropy.

Don’t confuse these two:

binary number is a number expressed in the base-2 numeral system, which uses only two symbols: typically 0 and 1 .

is a number expressed in the numeral system, which uses only two symbols: typically and . binary is a sequence of bytes organized in any way, which you can define using <<>> .

Firstly, we convert the given sequence of bytes to a list of single bytes. Then, we cast every byte to a string representing base-2 number. Next, we ensure each of them has 8 characters by prepending it with 0 in case of being shorter. Finally, we join all separate strings into a single one.

Checksum

Once we have our entropy ENT , we calculate a checksum by taking the first 32 bits from the binary number of its sha256 hash. This checksum is appended to the end of the initial entropy.

From the previous article, you already know how sha256 is calculated:

and how checksum is appended:

So let’s focus now on the actual checksum subtraction. Do you remember how to calculate checksum length?

Just take entropy bytes, calculate its bit size and divide by 32 . It’s that simple.

Then, we create range from 0 to length-1 (i.e. of size length ) and take a substring of that range from the binary number.

And we are done with our checksum calculated and appended. Now is the time to finally generate mnemonic words.

Mnemonic

To get the mnemonic phrase, the result is split into groups of 11 bits (each encoding a number from 0 to 2047 ) serving as an index into a wordlist.

Finally, we convert these numbers into words and use the joined words as a mnemonic sentence.

Subscribe to get the latest content immediately

https://tinyletter.com/KamilLelonek

Summary

MetaMask secure identity vault providing a user interface to sign blockchain transactions.

Uff, that was a long journey… Hence, I don’t want to bother you with the opposite conversion. However, if you are interested in the complete code, it’s available right here:

You will find there useful examples and the corresponding test suite.

With what we did here, you are now able to create a mnemonic seed which can store all the information needed to recover your Bitcoin wallet. To ensure maximum security, write it down and don’t store it anywhere on your electronic devices.