Skip to content

Commit 2c25127

Browse files
xt0xxt0x
authored
Merge pull request #1 from xt0x/feat/foundation-assets-wordlist
Add BIP39 foundation assets, constants, and wordlist
2 parents 0c497c0 + 4b2e787 commit 2c25127

25 files changed

Lines changed: 4385 additions & 5 deletions

‎assets/README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Spec Assets
2+
3+
This directory pins the BIP39 specification assets for the English profile only.
4+
Do not reorder or edit the contents of these files.

‎assets/bip-0039.mediawiki‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
<pre>
2+
BIP: 39
3+
Layer: Applications
4+
Title: Mnemonic code for generating deterministic keys
5+
Authors: Marek Palatinus <slush@satoshilabs.com>
6+
Pavol Rusnak <stick@satoshilabs.com>
7+
Aaron Voisine <voisine@gmail.com>
8+
Sean Bowe <ewillbefull@gmail.com>
9+
Comments-Summary: Unanimously Discourage for implementation
10+
Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0039
11+
Status: Deployed
12+
Type: Specification
13+
Assigned: 2013-09-10
14+
License: MIT
15+
</pre>
16+
17+
==Abstract==
18+
19+
This BIP describes the implementation of a mnemonic code or mnemonic sentence --
20+
a group of easy to remember words -- for the generation of deterministic wallets.
21+
22+
It consists of two parts: generating the mnemonic and converting it into a
23+
binary seed. This seed can be later used to generate deterministic wallets using
24+
BIP-0032 or similar methods.
25+
26+
==Copyright==
27+
28+
This BIP falls under the MIT License.
29+
30+
==Motivation==
31+
32+
A mnemonic code or sentence is superior for human interaction compared to the
33+
handling of raw binary or hexadecimal representations of a wallet seed. The
34+
sentence could be written on paper or spoken over the telephone.
35+
36+
This guide is meant to be a way to transport computer-generated randomness with
37+
a human-readable transcription. It's not a way to process user-created
38+
sentences (also known as brainwallets) into a wallet seed.
39+
40+
==Generating the mnemonic==
41+
42+
The mnemonic must encode entropy in a multiple of 32 bits. With more entropy
43+
security is improved but the sentence length increases. We refer to the
44+
initial entropy length as ENT. The allowed size of ENT is 128-256 bits.
45+
46+
First, an initial entropy of ENT bits is generated. A checksum is generated by
47+
taking the first <code>ENT / 32</code> bits of its SHA256 hash. This checksum is
48+
appended to the end of the initial entropy. Next, these concatenated bits
49+
are split into groups of 11 bits, each encoding a number from 0-2047, serving
50+
as an index into a wordlist. Finally, we convert these numbers into words and
51+
use the joined words as a mnemonic sentence.
52+
53+
The following table describes the relation between the initial entropy
54+
length (ENT), the checksum length (CS), and the length of the generated mnemonic
55+
sentence (MS) in words.
56+
57+
<pre>
58+
CS = ENT / 32
59+
MS = (ENT + CS) / 11
60+
61+
| ENT | CS | ENT+CS | MS |
62+
+-------+----+--------+------+
63+
| 128 | 4 | 132 | 12 |
64+
| 160 | 5 | 165 | 15 |
65+
| 192 | 6 | 198 | 18 |
66+
| 224 | 7 | 231 | 21 |
67+
| 256 | 8 | 264 | 24 |
68+
</pre>
69+
70+
==Wordlist==
71+
72+
An ideal wordlist has the following characteristics:
73+
74+
a) smart selection of words
75+
- the wordlist is created in such a way that it's enough to type the first four
76+
letters to unambiguously identify the word
77+
78+
b) similar words avoided
79+
- word pairs like "build" and "built", "woman" and "women", or "quick" and "quickly"
80+
not only make remembering the sentence difficult but are also more error
81+
prone and more difficult to guess
82+
83+
c) sorted wordlists
84+
- the wordlist is sorted which allows for more efficient lookup of the code words
85+
(i.e. implementations can use binary search instead of linear search)
86+
- this also allows trie (a prefix tree) to be used, e.g. for better compression
87+
88+
The wordlist can contain native characters, but they must be encoded in UTF-8
89+
using Normalization Form Compatibility Decomposition (NFKD).
90+
91+
==From mnemonic to seed==
92+
93+
A user may decide to protect their mnemonic with a passphrase. If a passphrase is not
94+
present, an empty string "" is used instead.
95+
96+
To create a binary seed from the mnemonic, we use the PBKDF2 function with a mnemonic
97+
sentence (in UTF-8 NFKD) used as the password and the string "mnemonic" + passphrase (again
98+
in UTF-8 NFKD) used as the salt. The iteration count is set to 2048 and HMAC-SHA512 is used as
99+
the pseudo-random function. The length of the derived key is 512 bits (= 64 bytes).
100+
101+
This seed can be later used to generate deterministic wallets using BIP-0032 or
102+
similar methods.
103+
104+
The conversion of the mnemonic sentence to a binary seed is completely independent
105+
from generating the sentence. This results in a rather simple code; there are no
106+
constraints on sentence structure and clients are free to implement their own
107+
wordlists or even whole sentence generators, allowing for flexibility in wordlists
108+
for typo detection or other purposes.
109+
110+
Although using a mnemonic not generated by the algorithm described in "Generating the
111+
mnemonic" section is possible, this is not advised and software must compute a
112+
checksum for the mnemonic sentence using a wordlist and issue a warning if it is
113+
invalid.
114+
115+
The described method also provides plausible deniability, because every passphrase
116+
generates a valid seed (and thus a deterministic wallet) but only the correct one
117+
will make the desired wallet available.
118+
119+
==Wordlists==
120+
121+
Since the vast majority of BIP39 wallets supports only the English wordlist,
122+
it is '''strongly discouraged''' to use non-English wordlists for generating
123+
the mnemonic sentences.
124+
125+
If you still feel your application really needs to use a localized wordlist,
126+
use one of the following instead of inventing your own.
127+
128+
* [[bip-0039/bip-0039-wordlists.md|Wordlists]]
129+
130+
==Test vectors==
131+
132+
The test vectors include input entropy, mnemonic and seed. The
133+
passphrase "TREZOR" is used for all vectors.
134+
135+
https://github.com/trezor/python-mnemonic/blob/master/vectors.json
136+
137+
Also see https://github.com/bip32JP/bip32JP.github.io/blob/master/test_JP_BIP39.json
138+
139+
(Japanese wordlist test with heavily normalized symbols as passphrase)
140+
141+
==Reference Implementation==
142+
143+
Reference implementation including wordlists is available from
144+
145+
http://github.com/trezor/python-mnemonic

0 commit comments

Comments
 (0)