----------------------------------------------------------
  BIP:     BIP-0039
  Title:   Mnemonic code for generating deterministic keys
  Authors: Marek Palatinus <slush@satoshilabs.com>
           Pavol Rusnak <stick@satoshilabs.com>
           ThomasV <thomasv@bitcointalk.org>
           Aaron Voisine <voisine@gmail.com>
           Sean Bowe <ewillbefull@gmail.com>
  Status:  Draft
  Type:    Standards Track
  Created: 2013-09-10
----------------------------------------------------------

[[abstract]]
Abstract
~~~~~~~~

This BIP describes the implementation of a mnemonic code or mnemonic
sentence -- a group of easy to remember words -- for the generation of
deterministic wallets.

It consists of two parts: generating the mnenomic, and converting it
into a binary seed. This seed can be later used to generate
deterministic wallets using BIP-0032 or similar methods.

[[motivation]]
Motivation
~~~~~~~~~~

A mnenomic code or sentence is superior for human interaction compared
to the handling of raw binary or hexidecimal representations of a wallet
seed. The sentence could be written on paper or spoken over the
telephone.

This guide meant to be as a way to transport computer-generated
randomnes over human readable transcription. It's not a way how to
process user-created sentences (also known as brainwallet) to wallet
seed.

[[generating-the-mnemonic]]
Generating the mnemonic
~~~~~~~~~~~~~~~~~~~~~~~

The mnemonic must encode entropy in any multiple of 32 bits. With larger
entropy security is improved but the sentence length increases. We can
refer to the initial entropy length as ENT. The recommended size of ENT
is 128-256 bits.

First, an initial entropy of ENT bits is generated. A checksum is
generated by taking the first

--------
ENT / 32
--------

bits of its SHA256 hash. This checksum is appended to the end of the
initial entropy. Next, these concatenated bits are are split into groups
of 11 bits, each encoding a number from 0-2047, serving as an index to a
wordlist. Later, we will convert these numbers into words and use the
joined words as a mnemonic sentence.

The following table describes the relation between the initial entropy
length (ENT), the checksum length (CS) and 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  |
------------------------------

[[wordlist]]
Wordlist
~~~~~~~~

An ideal wordlist has the following characteristics:

\a) smart selection of words

`  - wordlist is created in such way that it's enough to type the first four` +
`    letters to unambiguously identify the word`

\b) similar words avoided

`  - word pairs like "build" and "built", "woman" and "women", or "quick" and "quickly"` +
`    not only make remembering the sentence difficult, but are also more error` +
`    prone and more difficult to guess`

\c) sorted wordlists

`  - wordlist is sorted which allows for more efficient lookup of the code words` +
`    (i.e. implementation can use binary search instead of linear search)` +
`  - this also allows trie (prefix tree) to be used, e.g. for better compression`

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

[[from-mnemonic-to-seed]]
From mnemonic to seed
~~~~~~~~~~~~~~~~~~~~~

A user may decide to protect their mnemonic by passphrase. If a
passphrase is not present, an empty string "" is used instead.

To create a binary seed from the mnemonic, we use PBKDF2 function with a
mnemonic sentence (in UTF-8 NFKD) used as a password and string
"mnemonic" + passphrase (again in UTF-8 NFKD) used as a salt. Iteration
count is set to 2048 and HMAC-SHA512 is used as a pseudo-random
function. Desired length of the derived key is 512 bits (= 64 bytes).

This seed can be later used to generate deterministic wallets using
BIP-0032 or similar methods.

The conversion of the mnemonic sentence to binary seed is completely
independent from generating the sentence. This results in rather simple
code; there are no constraints on sentence structure and clients are
free to implement their own wordlists or even whole sentence generators,
allowing for flexibility in wordlists for typo detection or other
purposes.

Although using mnemonic not generated by algorithm described in
"Generating the mnemonic" section is possible, this is not advised and
software must compute checksum of the mnemonic sentence using wordlist
and issue a warning if it is invalid.

Described method also provides plausible deniability, because every
passphrase generates a valid seed (and thus deterministic wallet) but
only the correct one will make the desired wallet available.

[[wordlists]]
Wordlists
~~~~~~~~~

* link:bip-0039/english.txt[English]

[[test-vectors]]
Test vectors
~~~~~~~~~~~~

See https://github.com/trezor/python-mnemonic/blob/master/vectors.json

[[reference-implementation]]
Reference Implementation
~~~~~~~~~~~~~~~~~~~~~~~~

Reference implementation including wordlists is available from

http://github.com/trezor/python-mnemonic

[[other-implementations]]
Other Implementations
~~~~~~~~~~~~~~~~~~~~~

Objective-C - https://github.com/nybex/NYMnemonic
