From 1fe5ff8c4609370367c39e1defca12e7baf7f347 Mon Sep 17 00:00:00 2001 From: Shannon Appelcline Date: Thu, 19 Feb 2026 08:39:26 -1000 Subject: [PATCH] Update 03_4_Understanding_the_Descriptor.md --- 03_4_Understanding_the_Descriptor.md | 38 +++++++++++++--------------- 1 file changed, 18 insertions(+), 20 deletions(-) diff --git a/03_4_Understanding_the_Descriptor.md b/03_4_Understanding_the_Descriptor.md index 3718a83..c6075a7 100644 --- a/03_4_Understanding_the_Descriptor.md +++ b/03_4_Understanding_the_Descriptor.md @@ -4,7 +4,7 @@ You've got your wallet set up, but before we go further we're going to take a mo ## Know about HD Wallets -Private keys are what make the Bitcoin world go round. They're used to generate public keys, which are the foundation of addresses, and they're also used to control those addresses. One private key creates one public key which creates one address. Once upon a time, the Bitcoin Core wallet managed this by holding on to a "bag of keys". A new, unrelated private key would be created every time a new address was desired. But a bag of keys can be big, inefficient, and prone to loss. That's where the HD wallet came in. +Private keys are what make the Bitcoin world go round. They're used to generate public keys, which are the foundation of addresses, and they're also used to control those addresses. One private key creates one public key which creates one address. Once upon a time, the Bitcoin Core wallet managed this by holding on to a "bag of keys". A new, unrelated private key would be created every time a new address was desired. But a bags of keys are big, inefficient, and prone to loss. That's where the HD wallet came in. The HD wallet, which is short for the Hierarchical Deterministic Wallet, was defined in [BIP-32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki). It's a hierarchical design where a single "seed" generates an extended private key, which includes not just the private key but also a "chain code" that can be used to create descendents of that key. The key and chain code can be used to deterministically generate chains of keys (and therefore addresses) for a variety of purposes. A Bitcoin HD wallet will typically have individual chains of keys (and addresses) for a variety of different address types. But, they can all be restored from that seed (or from that master extended private key) because of their determinism: the addresses are always created in the same way provided that you have the same starting points (your master extended private key and a specific index [0,1,...,n] for a specific type of address). @@ -12,24 +12,24 @@ The HD wallet, which is short for the Hierarchical Deterministic Wallet, was def ## Know about Descriptor Wallets -Most of this course presumes that you're working entirely from a single node where you manage your own wallet, sending and receiving payments with the addresses created by that wallet. However, that's not necessarily how the larger Bitcoin ecosystem works. There, you're more likely to be moving addresses between wallets and even setting up wallets to watch over funds controlled by different wallets. +Most of this course presumes that you're working entirely from a single node where you manage your own wallet, sending and receiving payments with the addresses created by that wallet. However, that's not necessarily how the larger Bitcoin ecosystem works. There, you're more likely to be moving addresses between wallets (often on different devices) and even setting up wallets to watch over funds controlled by different wallets. -HD wallets offered a big step forward for managing this sort of interoperability, because they allowed you to load a single seed (or master extended private key) into a new wallet rather than having to move over a whole bag of keys. Seed phrases and the `xpub` and `xprv` formats were introduced to define these master secrets. But they quickly proved inadequate. The `xprv` (and `xpub`) defined the root of an HD tree, but they were very specific to a certain type of address. When a new address type was created, a new format was needed, resulting in the `yprv` and `ypub` formats. Then a third address type resulted in the creation of `zprv` and `zpub`. The system was quickly growing unmanageable. A new system was needed that described not just the extended keys, but also which address types they would be used to create. Because if you didn't have that, a new wallet would have to test a master extended public key against _every possible type of address_ and that was going to be very inefficient and time-consuming and still introduced the likelihood of losing funds. +HD wallets offered a big step forward for managing this sort of interoperability, because they allowed you to load a single seed (or master extended private key) into a new wallet rather than having to move over a whole bag of keys. A few formats have been introduced to make it easy to move HD wallets, starting with seed phrases and the `xpub` and `xprv` formats. But they quickly proved inadequate. Seed phrases only defined the seed, not what it was used for. The `xprv` (and `xpub`) improved on that by defining the root of an HD tree, but they were very specific to a certain type of address. When a new address type was created, a new format was needed, resulting in the `yprv` and `ypub` formats. Then a third address type resulted in the creation of `zprv` and `zpub`. The system was quickly growing unmanageable. A new format was needed that described not just the extended keys, but also which address types they would be used to create. Because if you didn't have that, a new wallet would have to test a master extended public key against _every possible type of address_ and that was going to be very inefficient and time-consuming and still introduced the likelihood of losing funds. -> :book: **What is a seed phase?** A collection of words that define a seed. The seed is in turn used to generate an extended private key. Seed phrases are not currently used by Bitcoin Core, but they are in wide use in the larger Bitcoin ecosystem. +> :book: **What is a seed phase?** A collection of mnemonic words can define a seed. That seed is then used to generate an extended private key. Seed phrases are not currently used by Bitcoin Core, but they are in wide use in the larger Bitcoin ecosystem. -> :book: ***What is xprv?*** An extended private key. This is the combination of a private key and a chain code. It's a private key that a whole sequence of children private keys can be derived from. +> :book: ***What is xprv?*** Xprv stands for extended private key. This is the combination of a private key and a chain code. It's a private key that a whole sequence of children private keys can be derived from. -> :book: ***What is xpub?*** An extended public key. This is the combination of a public key and a chain code. It's a public key that a whole sequence of children public keys can be derived from. +> :book: ***What is xpub?*** Xpub stands for extended public key. This is the combination of a public key and a chain code. It's a public key that a whole sequence of children public keys can be derived from. -Enter, at last, the descriptor wallet. A descriptor wallet collects together "output descriptors" (sometimes called "wallet descriptors") which each either define one address or for a special "ranged descriptor" a whole array of addresses, each at a separate index. They do so through the specification of a specific format that includes: a function (which defines how to unlock the Bitcoin at the address), a derivation path (which defines the purpose of an address, which mostly links it to a specific standard), either the master extended public key or the master extended private key, and a checksum to make sure that nothing has been corrupted. +Enter, at last, the descriptor wallet. A descriptor wallet collects together "output descriptors" (sometimes called "wallet descriptors") which each either define one address or for a special "ranged descriptor" a whole array of addresses, each at a separate index. They do so through the specification of a format that includes: a function (which defines how to unlock the Bitcoin at the address), a derivation path (which defines the purpose of an address, which mostly links it to a specific standard), either the master extended public key or the master extended private key, and a checksum to make sure that nothing has been corrupted. -> :book: ***What is a Derivation Path?*** When you have hierarchical keys, you need to be able to define individual keys as descendents of the master key. For example `[0]` is the 0th key of the master key, `[0/1]` is the first son of the 0th key, `[0/1/1]` is the first grandson of the first son of the 0th key. Some keys also contain a `'` or `h` after the number, to show they're hardened, which protects them from a specific attack that could otherwise be used to derive a private key from a public key. You don't need to worry about the specifics, other than the fact that a derivation path like `[0/1/1/0/0]` depicts a path down through a hierarchy tree and that descriptor wallets run specific calculations to deterministically determine the right address for a specific position in a tree. A derivation path defines a key, which means that a key represents a derivation path. They're equivalent. +> :book: ***What is a Derivation Path?*** When you have hierarchical keys, you need to be able to define individual keys as descendents of the master key. For example `[0]` is the 0th key of the master key, `[0/1]` is the first son of the 0th key, `[0/1/1]` is the first grandson of the first son of the 0th key. Some keys also contain a `'` or `h` after the number, to show they're hardened, which protects them from a specific attack that could otherwise be used to derive a private key from a public key. You don't need to worry about the specifics, other than the fact that a derivation path like `[0/1/1/0/0]` describes a path down through a hierarchical tree and that descriptor wallets run specific calculations to deterministically determine the right address for a specific position in a tree. A derivation path defines a key, which means that a key represents a derivation path. They're equivalent. -The derivation path allows you to calculate the right key from the master extended key, but it's the introduction of functions into descriptors that makes them particularly powerful, because it allows descriptors to serve a number of different types of past, present, and future addresses (which we'll meet in the next chapter). +The derivation path allows you to calculate the right key from the master extended key, but it's the introduction of functions into descriptors that makes them particularly powerful, because they allows descriptors to serve a number of different types of past, present, and future addresses (which we'll meet in [§3.5](03_5_Understanding_the_Address.md)). > :warning: **VERSION WARNING:** Modern Bitcoin wallets use descriptor wallets stored in SQLite. Older, "classic" wallets were instead bags of keys, stored in BDB (Berkeley Database) format. The classic files can currently still be opened by `bitcoin-cli` but you wouldn't want to create something new in that format. -> + ## Examine Your Wallet's Descriptors You can look at all of the descriptors contained in your wallet with `bitcoin-cli listdescriptors`: @@ -137,7 +137,7 @@ $ bitcoin-cli listdescriptors ] } ``` -Wow, that's a lot! But it's really just a listing of eight descriptors (`desc`) with a bunch of additional information on each. As it happens, that's descriptors for four different types of addresses (which we'll meet in chapter 4), with both an external address (for receiving funds from other wallets) and an internal address (for sending change back to this wallet). (And we'll talk about change in chapter 4 too!) +Wow, that's a lot! But it's really just a listing of eight descriptors (`desc`) with a bunch of additional information on each. As it happens, that's descriptors for four different types of addresses (which we'll meet in the next section), with both an external address (for receiving funds from other wallets) and an internal address (for sending change back to this wallet, which we'll talk about in chapter 4). With that understood, we can look more closely at one of the descriptors: ``` @@ -158,17 +158,17 @@ This contains: * **`desc`:** The descriptor. * **`timestamp`:** When the descriptor was created. * **`active`:** Is the descriptor still in use for creating new addresses? (It could have been superseded by a new master extended key, for example when encrypting the wallet.) -* **`internal`:** Is this a descriptor for internal addresses (for change). +* **`internal`:** Is this a descriptor for internal addresses (for change)? * **`range`:** For ranged descriptors, what's the range? * **`next`, `next_index`:** What is the next address to create for this descriptor? In this example, the next one is `3` because we already created three addresses from this descriptor (`0`, `1`, and `2`) in [§3.3](3_3_Setting_Up_Your_Wallet.md). As for the descriptor itself, let's break that down further: * **Function: `wpkh`.** The function that is used to create an address from that key. In this cases it's `wpkh`. That stands for "Witness Public Key Hash," which is one of the methods used to unlock a Bech32 address. -* **Fingerprint: `e18dae20`.** This is a fingerprint of the master extended public key. It tells you which secret was used to generate this address. The fingerprint is *not* necessary to generate the keys and addresses for a derivation, it's just helpful for you need to go back and find the secret that generated your extended keys. -* **Derivation Path: `/84h/1h/0h`.** This describes what part of an HD wallet is being exported. This is the 0th child key of the 1st child of the 84th child in the HD tree. The various levels in the derivation path have very specific meanings as defined in [BIP-44](https://en.bitcoin.it/wiki/BIP_0044): `/purpose/ coin_type/ account/`. The purpose of this derivation path is "84", which means that it follows [BIP-84](https://github.com/bitcoin/bips/blob/master/bip-0084.mediawiki), which describes WPKH derivation. The coin type is "1", which means that it's a testnet or signet coin. (A mainnet coin could would be "0") The account is "0", as it's the only account in our wallet. -* **Key: `tpubDC4ujMbsd9REzpGk3gnTjkrfJFw1NnvCpx6QBbLj3CHBzcLmVzssTVP8meRAM1WW4pZnK6SCCPGyzi9eMfzSXoeFMNprqtgxG71VRXTmetu`.** This is the signet or testnet extended master public key that was used to generate this derived key. (A private key could be here instead. A public key would demonstrate how to watch this series of addresses, while a private key would show to control them) -* **Range: `/0/*`.** These are actually the final two parts of the derivation path, which are defined as `change / address_index`. The "0" says it's an external address. (An internal or change address would be "1".) The `*` says it's a ranged address, which means that it's defining a whole set of WPKH addresses that could be created. +* **Fingerprint: `e18dae20`.** This is a fingerprint of the master extended public key. It tells you which secret was used to generate this address. The fingerprint is *not* necessary to generate the keys and addresses for a derivation, it's just helpful if you need to go back and find the secret that generated your extended keys. +* **Derivation Path: `/84h/1h/0h`.** This describes what part of an HD wallet is being exported. This is the 0th child key of the 1st child of the 84th child in the HD tree. The various levels in the derivation path have very specific meanings as defined in [BIP-44](https://en.bitcoin.it/wiki/BIP_0044): `/purpose/ coin_type/ account/`. The purpose of this derivation path is "84", which means that it follows [BIP-84](https://github.com/bitcoin/bips/blob/master/bip-0084.mediawiki), which describes WPKH derivation. The coin type is "1", which means that it's a testnet or signet coin. (A mainnet coin could would be "0".) The account is "0", as it's the only account in our wallet. +* **Key: `tpubDC4ujMbsd9REzpGk3gnTjkrfJFw1NnvCpx6QBbLj3CHBzcLmVzssTVP8meRAM1WW4pZnK6SCCPGyzi9eMfzSXoeFMNprqtgxG71VRXTmetu`.** This is the signet or testnet extended master public key that was used to generate this derived key. (A private key could be here instead. A public key would demonstrate how to watch this series of addresses, while a private key would show to control them.) +* **Range: `/0/*`.** These are actually the final two parts of the derivation path, which are defined by BIP-44 as `change / address_index`. The "0" says it's an external address. (An internal or change address would be "1".) The `*` says it's a ranged address, which means that it's defining a whole set of WPKH addresses that could be created. * **`#3658f8sn"`.** This is a checksum showing the descriptor isn't corrupted. So that's what everything means in a descriptor. Though they might seem somewhat complex, keep in mind that a descriptor takes the place of a potentially infinite number of addresses. With this one descriptor, or these eight descriptors as the case might be, you can regenerate every key and addresse that you might have used for these four address types. That's a huge boon for backups (when you want to protect your funds) and for moving control of your funds from one wallet-app to another. @@ -211,12 +211,10 @@ Which you can compare to the ranged descriptor we just looked at: ``` "desc": "wpkh([e18dae20/84h/1h/0h]tpubDC4ujMbsd9REzpGk3gnTjkrfJFw1NnvCpx6QBbLj3CHBzcLmVzssTVP8meRAM1WW4pZnK6SCCPGyzi9eMfzSXoeFMNprqtgxG71VRXTmetu/0/*)#3658f8sn", ``` -They're in slightly different formats as the non-ranged address has the derivation path all together. But other than that, there are just two changes: +They're in slightly different formats as the non-ranged address has the derivation path all together rather than it being split in two. But other than that, there are just two changes: * The wallet has a ranged of addresses `0/*`, while the address is one specific index in that range `0/2`. * The checksums are different, as you'd expect due to the differences in the index number. -That's the only difference between a descriptor in the wallet and a descriptor for a specific address! - You will see descriptors throughout Bitcoin commands. They're a vital element of not just the wallet, but of each address that is used to transfer funds and therefore of each transaction. ## Examine Descriptors Again @@ -300,4 +298,4 @@ Descriptors let you pass public keys and private keys among wallets, but more th ## What's Next? -Continue "Understanding Your Bitcoin Setup" with [§3.5: Receiving a Transaction](03_5_Receiving_a_Transaction.md). +Continue "Understanding Your Bitcoin Setup" with [§3.5: Undestanding the Address](03_5_Understanding_the_Address.md).