From c58a10394cd3c0cba8aafbae52ca9964542c0649 Mon Sep 17 00:00:00 2001 From: "Andreas M. Antonopoulos" Date: Wed, 4 May 2016 13:31:44 -0500 Subject: [PATCH 1/3] intro to wallets and mnemonic word diagrams --- ch05.asciidoc | 26 ++++++++++----------- images/Mnemonic_Words.png | Bin 0 -> 46199 bytes images/Mnemonic_to_seed.png | Bin 0 -> 54071 bytes images/{msbt_0408.png => msbt_new0501.png} | Bin 4 files changed, 12 insertions(+), 14 deletions(-) create mode 100644 images/Mnemonic_Words.png create mode 100644 images/Mnemonic_to_seed.png rename images/{msbt_0408.png => msbt_new0501.png} (100%) diff --git a/ch05.asciidoc b/ch05.asciidoc index 8d1d1e4b..7423a67c 100644 --- a/ch05.asciidoc +++ b/ch05.asciidoc @@ -1,30 +1,28 @@ [[ch05_wallets]] == Introduction -We will see how bitcoin wallets store collections of keys controlling many bitcoin addresses. +The term _wallet_ is used differently by bitcoin developers than it is used by the general public. Broadly, a bitcoin wallet can mean any application used to interface with bitcoin, encompassing both key management and transaction signing. Among bitcoin developers, however, the term wallet has been used more narrowly to describe the data structure that holds keys. In this chapter, we will look at wallets in the context of key management. The next chapter will focus on transaction creation and signing. === Wallets -((("wallets", id="ix_ch04-asciidoc23", range="startofrange")))Wallets are containers for private keys, usually implemented as structured files or simple databases. -Another method for making keys is((("deterministic key generation"))) _deterministic key generation_. Here you derive each new private key, using a one-way hash function from a previous private key, linking them in a sequence. As long as you can re-create that sequence, you only need the first key (known as a _seed_ or _master_ key) to generate them all. In this section we will examine the different methods of key generation and the wallet structures that are built around them. +Bitcoin wallets contain keys, not coins. Wallets are really keychains containing pairs of private/public keys (see <>). -[TIP] -==== -Bitcoin wallets contain keys, not coins. Each user has a wallet containing keys. Wallets are really keychains containing pairs of private/public keys (see <>). Users sign transactions with the keys, thereby proving they own the transaction outputs (their coins). The coins are stored on the blockchain in the form of transaction-ouputs (often noted as vout or txout).((("txout notation")))((("vout notation"))) -==== +There are two main types of wallets: deterministic and nondeterministic. Nondeterministic wallets consist of a collection of random keys, independently generated and unrelated to each other. Deterministic wallets, by comparison have a single _master key_ or _seed_ and derive all keys from that. Most modern wallets are deterministic. If you are implementing a wallet you should implement a deterministic wallet. Nondeterministic wallets are considered obsolete and are difficult to use, especially for non-technical users. + +In this section we will examine the different methods of key generation and the wallet structures that are built around them. [[random_wallet]] ==== Nondeterministic (Random) Wallets -((("nondeterministic wallets")))((("random wallets")))((("Type-0 nondeterministic wallet")))((("wallets","nondeterministic")))((("wallets","random")))In the first bitcoin clients, wallets were simply collections of randomly generated private keys. This type of wallet is called a _Type-0 nondeterministic wallet_. For example, the((("Just a Bunch Of Keys (JBOK) wallets"))) Bitcoin Core client pregenerates 100 random private keys when first started and generates more keys as needed, using each key only once. This type of wallet is nicknamed "Just a Bunch Of Keys," or JBOK, and such wallets are being replaced with deterministic wallets because they are cumbersome to manage, back up, and import. ((("backups","of random wallets")))((("random wallets","backing up")))The disadvantage of random keys is that if you generate many of them you must keep copies of all of them, meaning that the wallet must be backed up frequently. Each key must be backed up, or the funds it controls are irrevocably lost if the wallet becomes inaccessible. This conflicts directly with the principle of avoiding address re-use, by using each bitcoin address for only one transaction. Address re-use reduces privacy by associating multiple transactions and addresses with each other. A Type-0 nondeterministic wallet is a poor choice of wallet, especially if you want to avoid address re-use because that means managing many keys, which creates the need for frequent backups. Although the Bitcoin Core client includes a Type-0 wallet, using this wallet is discouraged by developers of Bitcoin Core. <> shows a nondeterministic wallet, containing a loose collection of random keys. +((("nondeterministic wallets")))((("random wallets")))((("Type-0 nondeterministic wallet")))((("wallets","nondeterministic")))((("wallets","random")))In the first bitcoin clients, wallets were simply collections of randomly generated private keys. This type of wallet is called a _nondeterministic wallet_. For example, the((("Just a Bunch Of Keys (JBOK) wallets"))) Bitcoin Core client generates 100 random private keys when first started and generates more keys as needed, using each key only once. This type of wallet is nicknamed "Just a Bunch Of Keys," or JBOK, and such wallets are being replaced with deterministic wallets because they are cumbersome to manage, back up, and import. ((("backups","of random wallets")))((("random wallets","backing up")))The disadvantage of random keys is that if you generate many of them you must keep copies of all of them, meaning that the wallet must be backed up frequently. Each key must be backed up, or the funds it controls are irrevocably lost if the wallet becomes inaccessible. This conflicts directly with the principle of avoiding address re-use. Address re-use reduces privacy by associating multiple transactions and addresses with each other. A nondeterministic wallet is a poor choice of wallet, especially if you want to avoid address re-use because that means managing many keys, which then creates the need for frequent backups. The Bitcoin Core client includes a nondeterministic wallet, primarily for testing and reference purposes. Most Core developers discourage the use of this wallet in production systems. <> shows a nondeterministic wallet, containing a loose collection of random keys. -[[Type0_wallet]] -.Type-0 nondeterministic (random) wallet: a collection of randomly generated keys -image::images/msbt_0408.png["non-deterministic wallet"] +[[jbok_wallet]] +.Nondeterministic (random) wallet: a collection of randomly generated keys +image::images/msbt_new0501.png["nondeterministic wallet"] ==== Deterministic (Seeded) Wallets -((("deterministic wallets")))((("seeded wallets")))((("wallets","deterministic")))((("wallets","seeded")))Deterministic, or "seeded" wallets are wallets that contain private keys that are all derived from a common seed, through the use of a one-way hash function. The seed is a randomly generated number that is combined with other data, such as an index number or "chain code" (see <>) to derive the private keys. In a deterministic wallet, the seed is sufficient to recover all the derived keys, and therefore a single backup at creation time is sufficient. The seed is also sufficient for a wallet export or import, allowing for easy migration of all the user's keys between different wallet implementations. +((("deterministic wallets")))((("seeded wallets")))((("wallets","deterministic")))((("wallets","seeded")))Deterministic, or "seeded" wallets contain private keys that are all derived from a common seed, through the use of a one-way hash function. The seed is a randomly generated number that is combined with other data, such as an index number or "chain code" (see <>) to derive the private keys. In a deterministic wallet, the seed is sufficient to recreate all the derived keys, and therefore a single backup at creation time is sufficient. The seed is also sufficient to export the keys to a new wallet, allowing for easy migration of all the user's keys between different wallet implementations. [[mnemonic_code_words]] ==== Mnemonic Code Words @@ -81,7 +79,7 @@ fce540af281bf7cdeade0dd2c1c795bd02f1e4049e205a0158906c343 [[hd_wallets]] ==== Hierarchical Deterministic Wallets (BIP0032/BIP0044) -((("deterministic wallets","hierarchical", id="ix_ch04-asciidoc24", range="startofrange")))((("hierarchical deterministic wallets (HD wallets)", id="ix_ch04-asciidoc25", range="startofrange")))((("BIP0032", id="ix_ch04-asciidoc25a", range="startofrange")))((("BIP0044", id="ix_ch04-asciidoc25b", range="startofrange")))Deterministic wallets were developed to make it easy to derive many keys from a single "seed." The most advanced form of deterministic wallets is the _hierarchical deterministic wallet_ or _HD wallet_ defined by the BIP0032 standard. Hierarchical deterministic wallets contain keys derived in a tree structure, such that a parent key can derive a sequence of children keys, each of which can derive a sequence of grandchildren keys, and so on, to an infinite depth. This tree structure is illustrated in <>.((("hierarchical deterministic wallets (HD wallets)","tree structure for"))) +((("deterministic wallets","hierarchical", id="ix_ch05-asciidoc24", range="startofrange")))((("hierarchical deterministic wallets (HD wallets)", id="ix_ch05-asciidoc25", range="startofrange")))((("BIP0032", id="ix_ch05-asciidoc25a", range="startofrange")))((("BIP0044", id="ix_ch05-asciidoc25b", range="startofrange")))Deterministic wallets were developed to make it easy to derive many keys from a single "seed." The most advanced form of deterministic wallets is the _hierarchical deterministic wallet_ or _HD wallet_ defined by the BIP0032 standard. Hierarchical deterministic wallets contain keys derived in a tree structure, such that a parent key can derive a sequence of children keys, each of which can derive a sequence of grandchildren keys, and so on, to an infinite depth. This tree structure is illustrated in <>.((("hierarchical deterministic wallets (HD wallets)","tree structure for"))) [[Type2_wallet]] .Type-2 hierarchical deterministic wallet: a tree of keys generated from a single seed @@ -256,7 +254,7 @@ BIP0044 specifies the structure as consisting of five predefined tree levels: ===== Experimenting with HD wallets using Bitcoin Explorer -((("hierarchical deterministic wallets (HD wallets)","Bitcoin Explorer and")))((("Bitcoin Explorer","HD wallets and")))Using the Bitcoin Explorer command-line tool introduced in <>, you can experiment with generating and extending BIP0032 deterministic keys, as well as displaying them in different formats((("Bitcoin Explorer","seed command")))((("seed command (bx)")))((("Bitcoin Explorer","hd-seed command")))((("hd-seed command (bx)")))((("Bitcoin Explorer","hd-public command")))((("hd-public command (bx)")))((("Bitcoin Explorer","hd-private command")))((("hd-private command (bx)")))((("Bitcoin Explorer","hd-to-address command")))((("hd-to-address command (bx)")))((("Bitcoin Explorer","hd-to-wif command")))((("hd-to-wif command (bx)"))): (((range="endofrange", startref="ix_ch04-asciidoc25b")))(((range="endofrange", startref="ix_ch04-asciidoc25a")))(((range="endofrange", startref="ix_ch04-asciidoc25")))(((range="endofrange", startref="ix_ch04-asciidoc24")))(((range="endofrange", startref="ix_ch04-asciidoc23"))) +((("hierarchical deterministic wallets (HD wallets)","Bitcoin Explorer and")))((("Bitcoin Explorer","HD wallets and")))Using the Bitcoin Explorer command-line tool introduced in <>, you can experiment with generating and extending BIP0032 deterministic keys, as well as displaying them in different formats((("Bitcoin Explorer","seed command")))((("seed command (bx)")))((("Bitcoin Explorer","hd-seed command")))((("hd-seed command (bx)")))((("Bitcoin Explorer","hd-public command")))((("hd-public command (bx)")))((("Bitcoin Explorer","hd-private command")))((("hd-private command (bx)")))((("Bitcoin Explorer","hd-to-address command")))((("hd-to-address command (bx)")))((("Bitcoin Explorer","hd-to-wif command")))((("hd-to-wif command (bx)"))): (((range="endofrange", startref="ix_ch05-asciidoc25b")))(((range="endofrange", startref="ix_ch05-asciidoc25a")))(((range="endofrange", startref="ix_ch05-asciidoc25")))(((range="endofrange", startref="ix_ch05-asciidoc24")))(((range="endofrange", startref="ix_ch05-asciidoc23"))) ==== [source, bash] diff --git a/images/Mnemonic_Words.png b/images/Mnemonic_Words.png new file mode 100644 index 0000000000000000000000000000000000000000..e781f4ac215dedea05d16ea7ee4c0c00108bb763 GIT binary patch literal 46199 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 literal 0 HcmV?d00001 diff --git a/images/Mnemonic_to_seed.png b/images/Mnemonic_to_seed.png new file mode 100644 index 0000000000000000000000000000000000000000..19071f2fdba1a731de0090b2d6b7f1c902297cd4 GIT binary patch literal 54071 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 VKgKr}asl|$RMl0fQhM?B{{fUu{QLj_ literal 0 HcmV?d00001 diff --git a/images/msbt_0408.png b/images/msbt_new0501.png similarity index 100% rename from images/msbt_0408.png rename to images/msbt_new0501.png From e0650cb992d4338ea26a2c4e20e0a3a1b52354f3 Mon Sep 17 00:00:00 2001 From: "Andreas M. Antonopoulos" Date: Tue, 4 Oct 2016 15:32:27 +0200 Subject: [PATCH 2/3] wallet chapter reorg and intro rewrite --- ch05.asciidoc | 171 ++++++++++++++++++++++++++++++-------------------- 1 file changed, 102 insertions(+), 69 deletions(-) diff --git a/ch05.asciidoc b/ch05.asciidoc index 7423a67c..b2863913 100644 --- a/ch05.asciidoc +++ b/ch05.asciidoc @@ -1,85 +1,49 @@ [[ch05_wallets]] == Introduction -The term _wallet_ is used differently by bitcoin developers than it is used by the general public. Broadly, a bitcoin wallet can mean any application used to interface with bitcoin, encompassing both key management and transaction signing. Among bitcoin developers, however, the term wallet has been used more narrowly to describe the data structure that holds keys. In this chapter, we will look at wallets in the context of key management. The next chapter will focus on transaction creation and signing. +The word "wallet" is used to describe a few different things in bitcoin. At a high-level, a wallet is an application that severs as the primary user interface. The wallet controls access to a user's money, managing keys and addresses, tracking the balance, and creating and signing transactions. + +More narrowly, from a programmer's perspective, the word "wallet" refers to the data structure used to store and manage a user's keys. + +In this chapter we will look at the second meaning, where ((("wallets", id="ix_ch04-asciidoc23", range="startofrange")))wallets are containers for private keys, usually implemented as structured files or simple databases. === Wallets +A common misconception about bitcoin is that bitcoin wallets contain bitcoin. In fact, the wallet contains only keys. The "coins" are recorded in the blockchain on the bitcoin network. Users control the coins on the network by signing transactions with the keys in their wallets. In a sense, a bitcoin wallet is a _keychain_. + +[TIP] +==== Bitcoin wallets contain keys, not coins. Wallets are really keychains containing pairs of private/public keys (see <>). +==== -There are two main types of wallets: deterministic and nondeterministic. Nondeterministic wallets consist of a collection of random keys, independently generated and unrelated to each other. Deterministic wallets, by comparison have a single _master key_ or _seed_ and derive all keys from that. Most modern wallets are deterministic. If you are implementing a wallet you should implement a deterministic wallet. Nondeterministic wallets are considered obsolete and are difficult to use, especially for non-technical users. +There are two primary types of wallets, distinguished by whether the keys they contain are related to each other or not. -In this section we will examine the different methods of key generation and the wallet structures that are built around them. +The first type is _non-deterministic wallets_, where each key is independently generated from a random number. The keys are not related to each other. ((("Just a Bunch Of Keys (JBOK) wallets")))This type of wallet is also known as a JBOK wallet from the phrase "Just a Bunch Of Keys." + +((("deterministic key generation")))The second type of wallet is a _deterministic wallet_, where all the keys are derived from a single master key, known as the _seed_. All the keys in this type of wallet are related to each other and can be generated again if one has the original seed. There are a number of different _key derivation_ methods used in deterministic wallets. The most commonly used derivation method uses a tree-like structure and is known as a _hierarchical deterministic_ or _HD_ wallet. [[random_wallet]] ==== Nondeterministic (Random) Wallets -((("nondeterministic wallets")))((("random wallets")))((("Type-0 nondeterministic wallet")))((("wallets","nondeterministic")))((("wallets","random")))In the first bitcoin clients, wallets were simply collections of randomly generated private keys. This type of wallet is called a _nondeterministic wallet_. For example, the((("Just a Bunch Of Keys (JBOK) wallets"))) Bitcoin Core client generates 100 random private keys when first started and generates more keys as needed, using each key only once. This type of wallet is nicknamed "Just a Bunch Of Keys," or JBOK, and such wallets are being replaced with deterministic wallets because they are cumbersome to manage, back up, and import. ((("backups","of random wallets")))((("random wallets","backing up")))The disadvantage of random keys is that if you generate many of them you must keep copies of all of them, meaning that the wallet must be backed up frequently. Each key must be backed up, or the funds it controls are irrevocably lost if the wallet becomes inaccessible. This conflicts directly with the principle of avoiding address re-use. Address re-use reduces privacy by associating multiple transactions and addresses with each other. A nondeterministic wallet is a poor choice of wallet, especially if you want to avoid address re-use because that means managing many keys, which then creates the need for frequent backups. The Bitcoin Core client includes a nondeterministic wallet, primarily for testing and reference purposes. Most Core developers discourage the use of this wallet in production systems. <> shows a nondeterministic wallet, containing a loose collection of random keys. +In the first bitcoin clients, wallets were collections of randomly generated private keys. For example, the original Bitcoin Core client pregenerates 100 random private keys when first started and generates more keys as needed, using each key only once. Such wallets are being replaced with deterministic wallets because they are cumbersome to manage, back up, and import. ((("backups","of random wallets")))((("random wallets","backing up")))The disadvantage of random keys is that if you generate many of them you must keep copies of all of them, meaning that the wallet must be backed up frequently. Each key must be backed up, or the funds it controls are irrevocably lost if the wallet becomes inaccessible. This conflicts directly with the principle of avoiding address re-use, by using each bitcoin address for only one transaction. Address re-use reduces privacy by associating multiple transactions and addresses with each other. A Type-0 nondeterministic wallet is a poor choice of wallet, especially if you want to avoid address re-use because that means managing many keys, which creates the need for frequent backups. Although the Bitcoin Core client includes a Type-0 wallet, using this wallet is discouraged by developers of Bitcoin Core. <> shows a nondeterministic wallet, containing a loose collection of random keys. -[[jbok_wallet]] -.Nondeterministic (random) wallet: a collection of randomly generated keys -image::images/msbt_new0501.png["nondeterministic wallet"] +[TIP] +==== +The use of non-deterministic wallets is discouraged for anything other than simple tests. They are simply to cumbersome to backup and use. Instead, use an industry standard based _hierarchical deterministic wallet_ with a _mnemonic_ backup. +==== + +[[Type0_wallet]] +.Type-0 nondeterministic (random) wallet: a collection of randomly generated keys +image::images/msbt_0408.png["non-deterministic wallet"] ==== Deterministic (Seeded) Wallets -((("deterministic wallets")))((("seeded wallets")))((("wallets","deterministic")))((("wallets","seeded")))Deterministic, or "seeded" wallets contain private keys that are all derived from a common seed, through the use of a one-way hash function. The seed is a randomly generated number that is combined with other data, such as an index number or "chain code" (see <>) to derive the private keys. In a deterministic wallet, the seed is sufficient to recreate all the derived keys, and therefore a single backup at creation time is sufficient. The seed is also sufficient to export the keys to a new wallet, allowing for easy migration of all the user's keys between different wallet implementations. - -[[mnemonic_code_words]] -==== Mnemonic Code Words - -((("deterministic wallets","mnemonic code words")))((("mnemonic code words")))((("seeded wallets","mnemonic code words")))Mnemonic codes are English word sequences that represent (encode) a random number used as a seed to derive a deterministic wallet. The sequence of words is sufficient to re-create the seed and from there re-create the wallet and all the derived keys. A wallet application that implements deterministic wallets with mnemonic code will show the user a sequence of 12 to 24 words when first creating a wallet. That sequence of words is the wallet backup and can be used to recover and re-create all the keys in the same or any compatible wallet application. Mnemonic code words make it easier for users to back up wallets because they are easy to read and correctly transcribe, as compared to a random sequence of numbers. - -Mnemonic codes are defined in((("BIP0039"))) Bitcoin Improvement Proposal 39 (see <>), currently in Draft status. Note that BIP0039 is one implementation of a mnemonic code standard. Specifically, there is a different standard, with a different set of words, used by the((("Electrum wallet")))((("mnemonic code words","Electrum wallet and"))) Electrum wallet and predating BIP0039. BIP0039 was introduced by the((("mnemonic code words","Trezor wallet and")))((("Trezor wallet"))) Trezor wallet and is incompatible with Electrum's implementation. However, BIP0039 has now achieved broad industry support across dozens of interoperable implementations and should be considered the de-facto industry standard. - -BIP0039 defines the creation of a mnemonic code and seed as a follows: - -1. Create a random sequence (entropy) of 128 to 256 bits. -2. Create a checksum of the random sequence by taking the first few bits of its SHA256 hash. -3. Add the checksum to the end of the random sequence. -4. Divide the sequence into sections of 11 bits, using those to index a dictionary of 2048 predefined words. -5. Produce 12 to 24 words representing the mnemonic code. - -<> shows the relationship between the size of entropy data and the length of mnemonic codes in words. - -[[table_4-5]] -.Mnemonic codes: entropy and word length -[options="header"] -|======= -|Entropy (bits) | Checksum (bits) | Entropy+checksum | Word length -| 128 | 4 | 132 | 12 -| 160 | 5 | 165 | 15 -| 192 | 6 | 198 | 18 -| 224 | 7 | 231 | 21 -| 256 | 8 | 264 | 24 -|======= - -The mnemonic code represents 128 to 256 bits, which are used to derive a longer (512-bit) seed through the use of the key-stretching function PBKDF2. The resulting seed is used to create a deterministic wallet and all of its derived keys. - -Tables pass:[#table_4-6] and pass:[#table_4-7] show some examples of mnemonic codes and the seeds they produce. - -[[table_4-6]] -.128-bit entropy mnemonic code and resulting seed -|======= -| *Entropy input (128 bits)*| 0c1e24e5917779d297e14d45f14e1a1a -| *Mnemonic (12 words)* | army van defense carry jealous true garbage claim echo media make crunch -| *Seed (512 bits)* | 3338a6d2ee71c7f28eb5b882159634cd46a898463e9d2d0980f8e80dfbba5b0fa0291e5fb88 -8a599b44b93187be6ee3ab5fd3ead7dd646341b2cdb8d08d13bf7 -|======= - -[[table_4-7]] -.256-bit entropy mnemonic code and resulting seed -|======= -| *Entropy input (256 bits)* | 2041546864449caff939d32d574753fe684d3c947c3346713dd8423e74abcf8c -| *Mnemonic (24 words)* | cake apple borrow silk endorse fitness top denial coil riot stay wolf -luggage oxygen faint major edit measure invite love trap field dilemma oblige -| *Seed (512 bits)* | 3972e432e99040f75ebe13a660110c3e29d131a2c808c7ee5f1631d0a977fcf473bee22 -fce540af281bf7cdeade0dd2c1c795bd02f1e4049e205a0158906c343 -|======= +((("deterministic wallets")))((("seeded wallets")))((("wallets","deterministic")))((("wallets","seeded")))Deterministic, or "seeded" wallets are wallets that contain private keys that are all derived from a common seed, through the use of a one-way hash function. The seed is a randomly generated number that is combined with other data, such as an index number or "chain code" (see <>) to derive the private keys. In a deterministic wallet, the seed is sufficient to recover all the derived keys, and therefore a single backup at creation time is sufficient. The seed is also sufficient for a wallet export or import, allowing for easy migration of all the user's keys between different wallet implementations. [[hd_wallets]] ==== Hierarchical Deterministic Wallets (BIP0032/BIP0044) -((("deterministic wallets","hierarchical", id="ix_ch05-asciidoc24", range="startofrange")))((("hierarchical deterministic wallets (HD wallets)", id="ix_ch05-asciidoc25", range="startofrange")))((("BIP0032", id="ix_ch05-asciidoc25a", range="startofrange")))((("BIP0044", id="ix_ch05-asciidoc25b", range="startofrange")))Deterministic wallets were developed to make it easy to derive many keys from a single "seed." The most advanced form of deterministic wallets is the _hierarchical deterministic wallet_ or _HD wallet_ defined by the BIP0032 standard. Hierarchical deterministic wallets contain keys derived in a tree structure, such that a parent key can derive a sequence of children keys, each of which can derive a sequence of grandchildren keys, and so on, to an infinite depth. This tree structure is illustrated in <>.((("hierarchical deterministic wallets (HD wallets)","tree structure for"))) +((("deterministic wallets","hierarchical", id="ix_ch04-asciidoc24", range="startofrange")))((("hierarchical deterministic wallets (HD wallets)", id="ix_ch04-asciidoc25", range="startofrange")))((("BIP0032", id="ix_ch04-asciidoc25a", range="startofrange")))((("BIP0044", id="ix_ch04-asciidoc25b", range="startofrange")))Deterministic wallets were developed to make it easy to derive many keys from a single "seed." The most advanced form of deterministic wallets is the _hierarchical deterministic wallet_ or _HD wallet_ defined by the BIP0032 standard. Hierarchical deterministic wallets contain keys derived in a tree structure, such that a parent key can derive a sequence of children keys, each of which can derive a sequence of grandchildren keys, and so on, to an infinite depth. This tree structure is illustrated in <>.((("hierarchical deterministic wallets (HD wallets)","tree structure for"))) [[Type2_wallet]] .Type-2 hierarchical deterministic wallet: a tree of keys generated from a single seed @@ -96,7 +60,7 @@ The second advantage of HD wallets is that users can create a sequence of public ===== HD wallet creation from a seed -((("hierarchical deterministic wallets (HD wallets)","creation from seeds")))((("seeded wallets","HD wallets")))HD wallets are created from a single((("root seeds"))) _root seed_, which is a 128-, 256-, or 512-bit random number. Everything else in the HD wallet is deterministically derived from this root seed, which makes it possible to re-create the entire HD wallet from that seed in any compatible HD wallet. This makes it easy to back up, restore, export, and import HD wallets containing thousands or even millions of keys by simply transferring only the root seed. The root seed is most often represented by a _mnemonic word sequence_, as described in the previous section <>, to make it easier for people to transcribe and store it. +((("hierarchical deterministic wallets (HD wallets)","creation from seeds")))((("seeded wallets","HD wallets")))HD wallets are created from a single((("root seeds"))) _root seed_, which is a 128-, 256-, or 512-bit random number. Everything else in the HD wallet is deterministically derived from this root seed, which makes it possible to re-create the entire HD wallet from that seed in any compatible HD wallet. This makes it easy to back up, restore, export, and import HD wallets containing thousands or even millions of keys by simply transferring only the root seed. The process of creating the master keys and master chain code for an HD wallet is shown in <>. @@ -126,28 +90,28 @@ The parent public key, chain code, and the index number are combined and hashed .Extending a parent private key to create a child private key image::images/msbt_0411.png["ChildPrivateDerivation"] -Changing the index allows us to extend the parent and create the other children in the sequence, e.g., Child 0, Child 1, Child 2, etc. Each parent key can have 2 billion children keys. +Changing the index allows us to extend the parent and create the other children in the sequence, e.g., Child 0, Child 1, Child 2, etc. Each parent key can have 2,147,483,647 (2^31^) children (2^31^ is half of the entire 2^32^ range available because the other half is reserved for a special type of derivation we will talk about later in this chapter) Repeating the process one level down the tree, each child can in turn become a parent and create its own children, in an infinite number of generations. ===== Using derived child keys -((("child key derivation (CKD) function","using")))((("child private keys","using")))((("security","child private keys and")))Child private keys are indistinguishable from nondeterministic (random) keys. Because the derivation function is a one-way function, the child key cannot be used to find the parent key. The child key also cannot be used to find any siblings. If you have the n~th~ child, you cannot find its siblings, such as the n–1 child or the n+1 child, or any other children that are part of the sequence. Only the parent key and chain code can derive all the children. Without the child chain code, the child key cannot be used to derive any grandchildren either. You need both the child private key and the child chain code to start a new branch and derive grandchildren. +((("child key derivation (CKD) function","using")))((("child private keys","using")))((("security","child private keys and")))Child private keys are indistinguishable from nondeterministic (random) keys. Because the derivation function is a one-way function, the child key cannot be used to find the parent key. The child key also cannot be used to find any siblings. If you have the n~th~ child, you cannot find its siblings, such as the n-1 child or the n+1 child, or any other children that are part of the sequence. Only the parent key and chain code can derive all the children. Without the child chain code, the child key cannot be used to derive any grandchildren either. You need both the child private key and the child chain code to start a new branch and derive grandchildren. So what can the child private key be used for on its own? It can be used to make a public key and a bitcoin address. Then, it can be used to sign transactions to spend anything paid to that address. [TIP] ==== -A child private key, the corresponding public key, and the bitcoin address are all indistinguishable from keys and addresses created randomly. The fact that they are part of a sequence is not visible, outside of the HD wallet function that created them. Once created, they operate exactly as "normal" keys. +A child private key, the corresponding public key, and the bitcoin address are all indistinguishable from keys and addresses created randomly. The fact that they are part of a sequence is not visible outside of the HD wallet function that created them. Once created, they operate exactly as "normal" keys. ==== ===== Extended keys ((("extended keys")))((("hierarchical deterministic wallets (HD wallets)","extended keys")))((("keys","extended")))As we saw earlier, the key derivation function can be used to create children at any level of the tree, based on the three inputs: a key, a chain code, and the index of the desired child. The two essential ingredients are the key and chain code, and combined these are called an _extended key_. The term "extended key" could also be thought of as "extensible key" because such a key can be used to derive children. -Extended keys are stored and represented simply as the concatenation of the 256-bit key and 256-bit chain code into a 512-bit sequence. There are two types of extended keys. An extended private key is the combination of a private key and chain code and can be used to derive child private keys (and from them, child public keys). An extended public key is a public key and chain code, which can be used to create child public keys, as described in <>. +Extended keys are stored and represented simply as the concatenation of the 256-bit key and 256-bit chain code into a 512-bit sequence. There are two types of extended keys. An extended private key is the combination of a private key and chain code and can be used to derive child private keys (and from them, child public keys). An extended public key is a public key and chain code, which can be used to create child public keys (*public only*), as described in <>. -Think of an extended key as the root of a branch in the tree structure of the HD wallet. With the root of the branch, you can derive the rest of the branch. The extended private key can create a complete branch, whereas the extended public key can only create a branch of public keys. +Think of an extended key as the root of a branch in the tree structure of the HD wallet. With the root of the branch, you can derive the rest of the branch. The extended private key can create a complete branch, whereas the extended public key can *only* create a branch of public keys. [TIP] ==== @@ -202,7 +166,7 @@ In simple terms, if you want to use the convenience of an extended public key to ===== Index numbers for normal and hardened derivation -((("hardened child key derivation","indexes for")))((("public child key derivation","indexes for")))The index number used in the derivation function is a 32-bit integer. To easily distinguish between keys derived through the normal derivation function versus keys derived through hardened derivation, this index number is split into two ranges. ((("child private keys","index numbers for")))Index numbers between 0 and 2^31^–1 (0x0 to 0x7FFFFFFF) are used _only_ for normal derivation. Index numbers between 2^31^ and 2^32^–1 (0x80000000 to 0xFFFFFFFF) are used _only_ for hardened derivation. Therefore, if the index number is less than 2^31^, that means the child is normal, whereas if the index number is equal or above 2^31^, the child is hardened. +((("hardened child key derivation","indexes for")))((("public child key derivation","indexes for")))The index number used in the derivation function is a 32-bit integer. To easily distinguish between keys derived through the normal derivation function versus keys derived through hardened derivation, this index number is split into two ranges. ((("child private keys","index numbers for")))Index numbers between 0 and 2^31^-1 (0x0 to 0x7FFFFFFF) are used _only_ for normal derivation. Index numbers between 2^31^ and 2^32^-1 (0x80000000 to 0xFFFFFFFF) are used _only_ for hardened derivation. Therefore, if the index number is less than 2^31^, that means the child is normal, whereas if the index number is equal or above 2^31^, the child is hardened. To make the index number easier to read and display, the index number for hardened children is displayed starting from zero, but with a prime symbol. The first normal child key is therefore displayed as 0, whereas the first hardened child (index 0x80000000) is displayed as pass:[0']. In sequence then, the second hardened key would have index 0x80000001 and would be displayed as 1', and so on. When you see an HD wallet index i', that means 2^31^+i. @@ -252,9 +216,78 @@ BIP0044 specifies the structure as consisting of five predefined tree levels: | m/44'/2'/0'/0/1 | The second private key in the Litecoin main account, for signing transactions |======= + +[[mnemonic_code_words]] +==== HD Seeds and Mnemonic Code Words + +Hierarchical deterministic wallets are a very powerful model for managing many keys and addresses. They also offer a single standard that is flexible enough to support many different applications such as: + +* Multi-currency wallets +* Multi-signature wallets +* Identity management systems +* Password management systems + +All these different applications can be build on different branches of a tree, while still being recoverable from a single common seed. + +The _HD wallet_ invention and standard was later augmented by another very important invention: a standardized way of creating seeds from a sequence of english words that are easy to transcribe, export and import across wallets. This is known as a _mnemonic_ and the standard is defined by BIP0039. Today, most bitcoin wallets (as well as wallets for other crypto-currencies) use this standard and can import and export seeds for backup and recovery using interoperable mnemonics. + +((("deterministic wallets","mnemonic code words")))((("mnemonic code words")))((("seeded wallets","mnemonic code words")))Mnemonics are word sequences that represent (encode) a random number used as a seed to derive a deterministic wallet. The sequence of words is sufficient to re-create the seed and from there re-create the wallet and all the derived keys. A wallet application that implements deterministic wallets with mnemonic words will show the user a sequence of 12 to 24 words when first creating a wallet. That sequence of words is the wallet backup and can be used to recover and re-create all the keys in the same or any compatible wallet application. Mnemonic words make it easier for users to back up wallets because they are easy to read and correctly transcribe, as compared to a random sequence of numbers. + +[TIP] +==== +Mnemonic words are often confused with "brainwallets". They are not the same. The primary difference is that a brainwallet consists of words chosen by the user, whereas menmonic words are created randomly by the wallet and presented to the user. This important difference makes mnemonic words much more secure, because humans are very poor sources of randomness. +==== + +Mnemonic codes are defined in((("BIP0039"))) Bitcoin Improvement Proposal 39 (see <>). Note that BIP0039 is one implementation of a mnemonic code standard. Specifically, there is a different standard, with a different set of words, used by the((("Electrum wallet")))((("mnemonic code words","Electrum wallet and"))) Electrum wallet and predating BIP0039. BIP0039 was introduced by the((("mnemonic code words","Trezor wallet and")))((("Trezor wallet"))) Trezor wallet and is incompatible with Electrum's implementation. However, BIP0039 has now achieved broad industry support across dozens of interoperable implementations and should be considered the de-facto industry standard. + +BIP0039 defines the creation of a mnemonic code and seed as a follows: + +1. Create a random sequence (entropy) of 128 to 256 bits. +2. Create a checksum of the random sequence by taking the first few bits of its SHA256 hash. +3. Add the checksum to the end of the random sequence. +4. Divide the sequence into sections of 11 bits, using those to index a dictionary of 2048 predefined words. +5. Produce 12 to 24 words representing the mnemonic code. + +<> shows the relationship between the size of entropy data and the length of mnemonic codes in words. + +[[table_4-5]] +.Mnemonic codes: entropy and word length +[options="header"] +|======= +|Entropy (bits) | Checksum (bits) | Entropy+checksum | Word length +| 128 | 4 | 132 | 12 +| 160 | 5 | 165 | 15 +| 192 | 6 | 198 | 18 +| 224 | 7 | 231 | 21 +| 256 | 8 | 264 | 24 +|======= + +The mnemonic words represent 128 to 256 bits, which are used to derive a longer (512-bit) seed through the use of the key-stretching function PBKDF2. The resulting seed is used to create a deterministic wallet and all of its derived keys. + +Tables pass:[#table_4-6] and pass:[#table_4-7] show some examples of mnemonic codes and the seeds they produce. + +[[table_4-6]] +.128-bit entropy mnemonic code and resulting seed +|======= +| *Entropy input (128 bits)*| 0c1e24e5917779d297e14d45f14e1a1a +| *Mnemonic (12 words)* | army van defense carry jealous true garbage claim echo media make crunch +| *Seed (512 bits)* | 3338a6d2ee71c7f28eb5b882159634cd46a898463e9d2d0980f8e80dfbba5b0fa0291e5fb88 +8a599b44b93187be6ee3ab5fd3ead7dd646341b2cdb8d08d13bf7 +|======= + +[[table_4-7]] +.256-bit entropy mnemonic code and resulting seed +|======= +| *Entropy input (256 bits)* | 2041546864449caff939d32d574753fe684d3c947c3346713dd8423e74abcf8c +| *Mnemonic (24 words)* | cake apple borrow silk endorse fitness top denial coil riot stay wolf +luggage oxygen faint major edit measure invite love trap field dilemma oblige +| *Seed (512 bits)* | 3972e432e99040f75ebe13a660110c3e29d131a2c808c7ee5f1631d0a977fcf473bee22 +fce540af281bf7cdeade0dd2c1c795bd02f1e4049e205a0158906c343 +|======= + ===== Experimenting with HD wallets using Bitcoin Explorer -((("hierarchical deterministic wallets (HD wallets)","Bitcoin Explorer and")))((("Bitcoin Explorer","HD wallets and")))Using the Bitcoin Explorer command-line tool introduced in <>, you can experiment with generating and extending BIP0032 deterministic keys, as well as displaying them in different formats((("Bitcoin Explorer","seed command")))((("seed command (bx)")))((("Bitcoin Explorer","hd-seed command")))((("hd-seed command (bx)")))((("Bitcoin Explorer","hd-public command")))((("hd-public command (bx)")))((("Bitcoin Explorer","hd-private command")))((("hd-private command (bx)")))((("Bitcoin Explorer","hd-to-address command")))((("hd-to-address command (bx)")))((("Bitcoin Explorer","hd-to-wif command")))((("hd-to-wif command (bx)"))): (((range="endofrange", startref="ix_ch05-asciidoc25b")))(((range="endofrange", startref="ix_ch05-asciidoc25a")))(((range="endofrange", startref="ix_ch05-asciidoc25")))(((range="endofrange", startref="ix_ch05-asciidoc24")))(((range="endofrange", startref="ix_ch05-asciidoc23"))) +((("hierarchical deterministic wallets (HD wallets)","Bitcoin Explorer and")))((("Bitcoin Explorer","HD wallets and")))Using the Bitcoin Explorer command-line tool introduced in <>, you can experiment with generating and extending BIP0032 deterministic keys, as well as displaying them in different formats((("Bitcoin Explorer","seed command")))((("seed command (bx)")))((("Bitcoin Explorer","hd-seed command")))((("hd-seed command (bx)")))((("Bitcoin Explorer","hd-public command")))((("hd-public command (bx)")))((("Bitcoin Explorer","hd-private command")))((("hd-private command (bx)")))((("Bitcoin Explorer","hd-to-address command")))((("hd-to-address command (bx)")))((("Bitcoin Explorer","hd-to-wif command")))((("hd-to-wif command (bx)"))): (((range="endofrange", startref="ix_ch04-asciidoc25b")))(((range="endofrange", startref="ix_ch04-asciidoc25a")))(((range="endofrange", startref="ix_ch04-asciidoc25")))(((range="endofrange", startref="ix_ch04-asciidoc24")))(((range="endofrange", startref="ix_ch04-asciidoc23"))) ==== [source, bash] From d6231e29dcb1e424db0f932325987c9d17e1ce4e Mon Sep 17 00:00:00 2001 From: "Andreas M. Antonopoulos" Date: Wed, 5 Oct 2016 13:30:27 +0200 Subject: [PATCH 3/3] memonic intro with example --- ch05.asciidoc | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/ch05.asciidoc b/ch05.asciidoc index b2863913..0f8b0b33 100644 --- a/ch05.asciidoc +++ b/ch05.asciidoc @@ -231,7 +231,31 @@ All these different applications can be build on different branches of a tree, w The _HD wallet_ invention and standard was later augmented by another very important invention: a standardized way of creating seeds from a sequence of english words that are easy to transcribe, export and import across wallets. This is known as a _mnemonic_ and the standard is defined by BIP0039. Today, most bitcoin wallets (as well as wallets for other crypto-currencies) use this standard and can import and export seeds for backup and recovery using interoperable mnemonics. -((("deterministic wallets","mnemonic code words")))((("mnemonic code words")))((("seeded wallets","mnemonic code words")))Mnemonics are word sequences that represent (encode) a random number used as a seed to derive a deterministic wallet. The sequence of words is sufficient to re-create the seed and from there re-create the wallet and all the derived keys. A wallet application that implements deterministic wallets with mnemonic words will show the user a sequence of 12 to 24 words when first creating a wallet. That sequence of words is the wallet backup and can be used to recover and re-create all the keys in the same or any compatible wallet application. Mnemonic words make it easier for users to back up wallets because they are easy to read and correctly transcribe, as compared to a random sequence of numbers. +Let's look at this from a practical perspective. Which of the following seeds is easier to transcribe, record on paper, read without error, export and import into another wallet? + +.A seed for an HD wallet, in hex +---- +0C1E24E5917779D297E14D45F14E1A1A +---- + +.A seed for an HD wallet, from a 12-word mnemonic +---- +army van defense carry jealous true +garbage claim echo media make crunch +---- + +.The mnemonic seed above, recorded in a numbered table, as a backup +|=== +|1. army |7. van +|2. defense |8. carry +|3. jealous |9. true +|4. garbage |10. claim +|5. echo |11. media +|6. make |12. crunch +|=== + + +((("deterministic wallets","mnemonic code words")))((("mnemonic code words")))((("seeded wallets","mnemonic code words")))Mnemonic code words are word sequences that represent (encode) a random number used as a seed to derive a deterministic wallet. The sequence of words is sufficient to re-create the seed and from there re-create the wallet and all the derived keys. A wallet application that implements deterministic wallets with mnemonic words will show the user a sequence of 12 to 24 words when first creating a wallet. That sequence of words is the wallet backup and can be used to recover and re-create all the keys in the same or any compatible wallet application. Mnemonic words make it easier for users to back up wallets because they are easy to read and correctly transcribe, as compared to a random sequence of numbers. [TIP] ====