From a87fbfb693577a26e9d092a79aa95dfd3f36229b Mon Sep 17 00:00:00 2001 From: krupawan5618 Date: Sun, 28 Mar 2021 15:56:46 -0400 Subject: [PATCH 1/5] Update ch05.asciidoc Addressing the gap limit --- ch05.asciidoc | 61 ++++++++++++++++++++++++++++++++------------------- 1 file changed, 39 insertions(+), 22 deletions(-) diff --git a/ch05.asciidoc b/ch05.asciidoc index 465bab36..939a58cd 100644 --- a/ch05.asciidoc +++ b/ch05.asciidoc @@ -390,28 +390,6 @@ One common application of this solution is to install an extended public key on .Extending a parent public key to create a child public key image::images/mbc2_0511.png["ChildPublicDerivation"] -==== Using an Extended Public Key on a Web Store - -((("wallets", "technology of", "using extended public keys on web stores")))Let's see how HD wallets are used by continuing our story with Gabriel's web store.((("use cases", "web store", id="gabrielfivetwo"))) - -Gabriel first set up his web store as a hobby, based on a simple hosted Wordpress page. His store was quite basic with only a few pages and an order form with a single bitcoin address. - -Gabriel used the first bitcoin address generated by his Trezor device as the main bitcoin address for his store. This way, all incoming payments would be paid to an address controlled by his Trezor hardware wallet. - -Customers would submit an order using the form and send payment to Gabriel's published bitcoin address, triggering an email with the order details for Gabriel to process. With just a few orders each week, this system worked well enough. - -However, the little web store became quite successful and attracted many orders from the local community. Soon, Gabriel was overwhelmed. With all the orders paying the same address, it became difficult to correctly match orders and transactions, especially when multiple orders for the same amount came in close together. - -Gabriel's HD wallet offers a much better solution through the ability to derive public child keys without knowing the private keys. Gabriel can load an extended public key (xpub) on his website, which can be used to derive a unique address for every customer order. Gabriel can spend the funds from his Trezor, but the xpub loaded on the website can only generate addresses and receive funds. This feature of HD wallets is a great security feature. Gabriel's website does not contain any private keys and therefore does not need high levels of security. - -To export the xpub, Gabriel uses the web-based software in conjunction with the Trezor hardware wallet. The Trezor device must be plugged in for the public keys to be exported. Note that hardware wallets will never export private keys—those always remain on the device. <> shows the web interface Gabriel uses to export the xpub. - -[[export_xpub]] -.Exporting an xpub from a Trezor hardware wallet -image::images/mbc2_0512.png["Exporting the xpub from the Trezor"] - -Gabriel copies the xpub to his web store's bitcoin shop software. He uses _BTCPay Server_, which is an open source web-store for a variety of web hosting and content platforms. BTCPay Server uses the xpub to generate a unique address for every purchase. ((("", startref="gabrielfivetwo"))) - ===== Hardened child key derivation ((("public and private keys", "hardened child key derivation")))((("hardened derivation")))The ability to derive a branch of public keys from an xpub is very useful, but it comes with a potential risk. Access to an xpub does not give access to child private keys. However, because the xpub contains the chain code, if a child private key is known, or somehow leaked, it can be used with the chain code to derive all the other child private keys. A single leaked child private key, together with a parent chain code, reveals all the private keys of all the children. Worse, the child private key together with a parent chain code can be used to deduce the parent private key. @@ -480,3 +458,42 @@ The third level of the tree is "account," which allows users to subdivide their | M/44++'++/0++'++/3++'++/1/14 | The fifteenth change-address public key for the fourth bitcoin account | m/44++'++/2++'++/0++'++/0/1 | The second private key in the Litecoin main account, for signing transactions |======= + +==== Using an Extended Public Key on a Web Store + +((("wallets", "technology of", "using extended public keys on web stores")))Let's see how HD wallets are used by continuing our story with Gabriel's web store.((("use cases", "web store", id="gabrielfivetwo"))) + +Gabriel first set up his web store as a hobby, based on a simple hosted Wordpress page. His store was quite basic with only a few pages and an order form with a single bitcoin address. + +Gabriel used the first bitcoin address generated by his Trezor device as the main bitcoin address for his store. This way, all incoming payments would be paid to an address controlled by his Trezor hardware wallet. + +Customers would submit an order using the form and send payment to Gabriel's published bitcoin address, triggering an email with the order details for Gabriel to process. With just a few orders each week, this system worked well enough. + +However, the little web store became quite successful and attracted many orders from the local community. Soon, Gabriel was overwhelmed. With all the orders paying the same address, it became difficult to correctly match orders and transactions, especially when multiple orders for the same amount came in close together. + +Gabriel's HD wallet offers a much better solution through the ability to derive public child keys without knowing the private keys. Gabriel can load an extended public key (xpub) on his website, which can be used to derive a unique address for every customer order. Gabriel can spend the funds from his Trezor, but the xpub loaded on the website can only generate addresses and receive funds. This feature of HD wallets is a great security feature. Gabriel's website does not contain any private keys and therefore does not need high levels of security. + +To export the xpub, Gabriel uses the web-based software in conjunction with the Trezor hardware wallet. The Trezor device must be plugged in for the public keys to be exported. Note that hardware wallets will never export private keys—those always remain on the device. <> shows the web interface Gabriel uses to export the xpub. + +[[export_xpub]] +.Exporting an xpub from a Trezor hardware wallet +image::images/mbc2_0512.png["Exporting the xpub from the Trezor"] + +Gabriel copies the xpub to his web store's bitcoin shop software. He uses _BTCPay Server_, which is an open source web-store for a variety of web hosting and content platforms. BTCPay Server uses the xpub to generate a unique address for every purchase. ((("", startref="gabrielfivetwo"))) + +===== Account Discovery and Management + +Gabriel's business is flourishing. He has provided his extended public key (xpub) to BTCPay Server, which is generating unique addresses for customers to his website. Every time a customer to Gabriel's website clicks on the "Checkout" button with a specified payment modality (in this case, bitcoin), BTCPay Server generates a new address for that customer. More specifically, BTCPay Server iterates on the _address_index_ tree to create a new address to display to the customer, as defined by BIP-44. If the customer decides to switch payment methods or abandon the transaction entirely, this bitcoin address goes unused and will not be used for another customer right away. At a single moment in time, Gabriel's website may have a large volume of outstanding addresses for customers making purhcases, some of which may go unused and eventually expire. Once these addresses expire, BTCPay Server will go back to reuse these addresses to fill the gap in _address_index_, but it becomes clear how there can be gaps between these leaves of where the money is actually located. + + +Let's say that Gabriel is and he is interested in viewing his total amount of bitcoin earned on a watch-only wallet (a wallet that allows you to view transaction history, but not spend funds) device that is separate from BTCPay Server but also conforms to the BIP-44 standard. How should this separate wallet go about searching for funds in this vast heirarchial tree, and when should it stop looking? Most wallets will typically follow the process that is described in [[bip-44]]https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki[BIP-44]: + + + +[TIP] +==== +Gap limits explain the phenomenon whereby the the importing of a wallet may show an incorrect or zero balance. Many wallets allow this default gap limit to be changed, and Gabriel may need to increase this limit to allow his wallet to fully import his transaction history. +==== + + + From 3c1f4f2e8b0016e3d0de8fbc9de7dfd05ecf6fe9 Mon Sep 17 00:00:00 2001 From: krupawan5618 Date: Sun, 28 Mar 2021 16:04:40 -0400 Subject: [PATCH 2/5] ch05 - Address the Gap Limit and Account discovery Detailed how BTCPay server manages generation of public keys using the xpub and how the gap limit is used to import a wallet, as detailed in BIP-44. --- ch05.asciidoc | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/ch05.asciidoc b/ch05.asciidoc index 939a58cd..f6206eb9 100644 --- a/ch05.asciidoc +++ b/ch05.asciidoc @@ -485,15 +485,9 @@ Gabriel copies the xpub to his web store's bitcoin shop software. He uses _BTCPa Gabriel's business is flourishing. He has provided his extended public key (xpub) to BTCPay Server, which is generating unique addresses for customers to his website. Every time a customer to Gabriel's website clicks on the "Checkout" button with a specified payment modality (in this case, bitcoin), BTCPay Server generates a new address for that customer. More specifically, BTCPay Server iterates on the _address_index_ tree to create a new address to display to the customer, as defined by BIP-44. If the customer decides to switch payment methods or abandon the transaction entirely, this bitcoin address goes unused and will not be used for another customer right away. At a single moment in time, Gabriel's website may have a large volume of outstanding addresses for customers making purhcases, some of which may go unused and eventually expire. Once these addresses expire, BTCPay Server will go back to reuse these addresses to fill the gap in _address_index_, but it becomes clear how there can be gaps between these leaves of where the money is actually located. - -Let's say that Gabriel is and he is interested in viewing his total amount of bitcoin earned on a watch-only wallet (a wallet that allows you to view transaction history, but not spend funds) device that is separate from BTCPay Server but also conforms to the BIP-44 standard. How should this separate wallet go about searching for funds in this vast heirarchial tree, and when should it stop looking? Most wallets will typically follow the process that is described in [[bip-44]]https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki[BIP-44]: - - +Let's say that Gabriel is and he is interested in viewing his total amount of bitcoin earned on a watch-only wallet (one that allows you to view transaction history, but not spend funds) that is separate from BTCPay Server but also conforms to the BIP-44 standard. How should this separate wallet go about searching for funds in this vast heirarchial tree, and when should it stop looking? Most wallets will typically follow an iterative process that utilizes the _gap limit_, a predefined limit whereby if there are no used addresses in a row beyond this limit number the wallet will stop searching the address chain. The default gap limit is typically set to 20. This is detailed in [[bip-44]]https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki[BIP-44]. [TIP] ==== Gap limits explain the phenomenon whereby the the importing of a wallet may show an incorrect or zero balance. Many wallets allow this default gap limit to be changed, and Gabriel may need to increase this limit to allow his wallet to fully import his transaction history. ==== - - - From fc37c08bd0e9ca702e2f3e0b10095744d3e7619d Mon Sep 17 00:00:00 2001 From: krupawan5618 Date: Sun, 28 Mar 2021 16:06:22 -0400 Subject: [PATCH 3/5] Update ch05.asciidoc --- ch05.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ch05.asciidoc b/ch05.asciidoc index f6206eb9..67eb681d 100644 --- a/ch05.asciidoc +++ b/ch05.asciidoc @@ -483,7 +483,7 @@ Gabriel copies the xpub to his web store's bitcoin shop software. He uses _BTCPa ===== Account Discovery and Management -Gabriel's business is flourishing. He has provided his extended public key (xpub) to BTCPay Server, which is generating unique addresses for customers to his website. Every time a customer to Gabriel's website clicks on the "Checkout" button with a specified payment modality (in this case, bitcoin), BTCPay Server generates a new address for that customer. More specifically, BTCPay Server iterates on the _address_index_ tree to create a new address to display to the customer, as defined by BIP-44. If the customer decides to switch payment methods or abandon the transaction entirely, this bitcoin address goes unused and will not be used for another customer right away. At a single moment in time, Gabriel's website may have a large volume of outstanding addresses for customers making purhcases, some of which may go unused and eventually expire. Once these addresses expire, BTCPay Server will go back to reuse these addresses to fill the gap in _address_index_, but it becomes clear how there can be gaps between these leaves of where the money is actually located. +Gabriel's business is flourishing. He has provided his extended public key (xpub) to _BTCPay Server_, which is generating unique addresses for customers to his website. Every time a customer to Gabriel's website clicks on the "Checkout" button with a specified payment modality (in this case, bitcoin), _BTCPay Server_ generates a new address for that customer. More specifically, _BTCPay Server_ iterates on the _address_index_ tree to create a new address to display to the customer, as defined by BIP-44. If the customer decides to switch payment methods or abandon the transaction entirely, this bitcoin address goes unused and will not be used for another customer right away. At a single moment in time, Gabriel's website may have a large volume of outstanding addresses for customers making purhcases, some of which may go unused and eventually expire. Once these addresses expire, _BTCPay Server_ will go back to reuse these addresses to fill the gap in _address_index_, but it becomes clear how there can be gaps between the leaves of where the money is actually located. Let's say that Gabriel is and he is interested in viewing his total amount of bitcoin earned on a watch-only wallet (one that allows you to view transaction history, but not spend funds) that is separate from BTCPay Server but also conforms to the BIP-44 standard. How should this separate wallet go about searching for funds in this vast heirarchial tree, and when should it stop looking? Most wallets will typically follow an iterative process that utilizes the _gap limit_, a predefined limit whereby if there are no used addresses in a row beyond this limit number the wallet will stop searching the address chain. The default gap limit is typically set to 20. This is detailed in [[bip-44]]https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki[BIP-44]. From f3b15fa715c988686b5017d775e7412c4f812988 Mon Sep 17 00:00:00 2001 From: krupawan5618 Date: Sun, 28 Mar 2021 16:25:55 -0400 Subject: [PATCH 4/5] Update ch05.asciidoc --- ch05.asciidoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/ch05.asciidoc b/ch05.asciidoc index 67eb681d..8541b9f3 100644 --- a/ch05.asciidoc +++ b/ch05.asciidoc @@ -483,11 +483,13 @@ Gabriel copies the xpub to his web store's bitcoin shop software. He uses _BTCPa ===== Account Discovery and Management -Gabriel's business is flourishing. He has provided his extended public key (xpub) to _BTCPay Server_, which is generating unique addresses for customers to his website. Every time a customer to Gabriel's website clicks on the "Checkout" button with a specified payment modality (in this case, bitcoin), _BTCPay Server_ generates a new address for that customer. More specifically, _BTCPay Server_ iterates on the _address_index_ tree to create a new address to display to the customer, as defined by BIP-44. If the customer decides to switch payment methods or abandon the transaction entirely, this bitcoin address goes unused and will not be used for another customer right away. At a single moment in time, Gabriel's website may have a large volume of outstanding addresses for customers making purhcases, some of which may go unused and eventually expire. Once these addresses expire, _BTCPay Server_ will go back to reuse these addresses to fill the gap in _address_index_, but it becomes clear how there can be gaps between the leaves of where the money is actually located. +Gabriel's business is flourishing. He has provided his extended public key (xpub) to _BTCPay Server_, which is generating unique addresses for customers to his website. Every time a customer to Gabriel's website clicks on the "Checkout" button with a specified payment modality (in this case, bitcoin), _BTCPay Server_ generates a new address for that customer. More specifically, _BTCPay Server_ iterates on the _address_index_ tree to create a new address to display to the customer, as defined by BIP-44. If the customer decides to switch payment methods or abandon the transaction entirely, this bitcoin address goes unused and will not be used for another customer right away. + +At a single moment in time, Gabriel's website may have a large volume of outstanding addresses for customers making purchases, some of which may go unused and eventually expire. Once these addresses expire, _BTCPay Server_ will go back to reuse these addresses to fill the gap in _address_index_, but it becomes clear how there can be gaps between the leaves of where the money is actually located. Let's say that Gabriel is and he is interested in viewing his total amount of bitcoin earned on a watch-only wallet (one that allows you to view transaction history, but not spend funds) that is separate from BTCPay Server but also conforms to the BIP-44 standard. How should this separate wallet go about searching for funds in this vast heirarchial tree, and when should it stop looking? Most wallets will typically follow an iterative process that utilizes the _gap limit_, a predefined limit whereby if there are no used addresses in a row beyond this limit number the wallet will stop searching the address chain. The default gap limit is typically set to 20. This is detailed in [[bip-44]]https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki[BIP-44]. [TIP] ==== -Gap limits explain the phenomenon whereby the the importing of a wallet may show an incorrect or zero balance. Many wallets allow this default gap limit to be changed, and Gabriel may need to increase this limit to allow his wallet to fully import his transaction history. +Gap limits explain the phenomenon whereby the the importing of a wallet may show an incorrect or zero balance. The funds are not lost, but rather, the wallet importing function has not traversed enough leaves to fully detect funds. Many wallets allow this default gap limit to be changed, and Gabriel may need to increase this limit to allow his wallet to fully import his transaction history. ==== From a196ec0170fa9fb92b0e5495d668dd54645aca70 Mon Sep 17 00:00:00 2001 From: krupawan5618 Date: Mon, 29 Mar 2021 10:40:04 -0400 Subject: [PATCH 5/5] Update ch05.asciidoc --- ch05.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ch05.asciidoc b/ch05.asciidoc index 8541b9f3..4859d365 100644 --- a/ch05.asciidoc +++ b/ch05.asciidoc @@ -485,9 +485,9 @@ Gabriel copies the xpub to his web store's bitcoin shop software. He uses _BTCPa Gabriel's business is flourishing. He has provided his extended public key (xpub) to _BTCPay Server_, which is generating unique addresses for customers to his website. Every time a customer to Gabriel's website clicks on the "Checkout" button with a specified payment modality (in this case, bitcoin), _BTCPay Server_ generates a new address for that customer. More specifically, _BTCPay Server_ iterates on the _address_index_ tree to create a new address to display to the customer, as defined by BIP-44. If the customer decides to switch payment methods or abandon the transaction entirely, this bitcoin address goes unused and will not be used for another customer right away. -At a single moment in time, Gabriel's website may have a large volume of outstanding addresses for customers making purchases, some of which may go unused and eventually expire. Once these addresses expire, _BTCPay Server_ will go back to reuse these addresses to fill the gap in _address_index_, but it becomes clear how there can be gaps between the leaves of where the money is actually located. +At a single moment in time, Gabriel's website may have a large volume of outstanding addresses for customers making purchases, some of which may go unused and eventually expire. Once these addresses expire, _BTCPay Server_ will go back to reuse these addresses to fill the gap in _address_index_, but it becomes clear how there can be gaps between the _address_index_ leaves of the hierarchical deterministic tree where the money is actually located. -Let's say that Gabriel is and he is interested in viewing his total amount of bitcoin earned on a watch-only wallet (one that allows you to view transaction history, but not spend funds) that is separate from BTCPay Server but also conforms to the BIP-44 standard. How should this separate wallet go about searching for funds in this vast heirarchial tree, and when should it stop looking? Most wallets will typically follow an iterative process that utilizes the _gap limit_, a predefined limit whereby if there are no used addresses in a row beyond this limit number the wallet will stop searching the address chain. The default gap limit is typically set to 20. This is detailed in [[bip-44]]https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki[BIP-44]. +Let's say that Gabriel is interested in viewing his total amount of bitcoin earned on a watch-only wallet (one that allows you to view transaction history, but not spend funds) that is separate from BTCPay Server but also conforms to the BIP-44 standard. How should this separate wallet go about searching for funds in this vast heirarchial tree, and when should it stop looking? Most wallets will typically follow an iterative process that utilizes the _gap limit_, a predefined limit whereby if there are no used addresses in a row beyond this limit number the wallet will stop searching the address chain. The default gap limit is typically set to 20. This is detailed in [[bip-44]]https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki[BIP-44]. [TIP] ====