Update 03_0_Understanding_Your_Bitcoin_Setup.md

03_0_Understanding_Your_Bitcoin_Setup.md

@@ -19,7 +19,7 @@ Supporting objectives include the ability to:
    * Understand the Basic Bitcoin File Layout
    * Use Basic Informational Commands
    * Understand What a Bitcoin Address Is
-   * Understand What a Wallet Is
+   * Understand What a Descriptor Wallet Is
    * Recognize Common Types of Bitcoin Wallets
    
 ## Table of Contents
@@ -27,6 +27,8 @@ Supporting objectives include the ability to:
 * [Section One: Verifying Your Bitcoin Setup](03_1_Verifying_Your_Bitcoin_Setup.md)
 * [Section Two: Knowing Your Bitcoin Setup](03_2_Knowing_Your_Bitcoin_Setup.md)
 * [Section Three: Setting Up Your Wallet](03_3_Setting_Up_Your_Wallet.md)
-   * [Interlude: Using Command-Line Variables](03_3__Interlude_Using_Command-Line_Variables.md)
-* [Section Four: Receiving a Transaction](03_4_Receiving_a_Transaction.md)
-* [Section Five: Understanding the Descriptor](03_5_Understanding_the_Descriptor.md)
+* [Section Four: Understanding the Descriptor](03_4_Understanding_the_Descriptor.md)
+* [Section Five: Understanding the Address](03_5_Understanding_the_Address.md)
+* [Section Six: Creating QR Codes for Addresses](03_6_Creating_QR_Codes_for_Addresses.md)
+* [Section Seven: Receiving a Transaction](03_7_Receiving_a_Transaction.md)
+   * [Interlude: Using Command-Line Variables](03_7a_Interlude_Using_Command-Line_Variables.md)

03_3_Setting_Up_Your_Wallet.md

@@ -89,13 +89,13 @@ You now have a Bitcoin wallet. But you can't receive funds with a wallet. For th
 
 ## Create an Address
 
-The next thing you need to do is create an address for receiving payments. This is done with the `bitcoin-cli getnewaddress` command. Remember that if you want more information on this command, you should type `bitcoin-cli help getnewaddress`. There are a variety of types of addresses, due to Bitcoin's evolution over the years. [§4.1](04_1_Sending_Coins_The_Easy_Way.md) covers them all. For now, though we're just going to create an address of the default type, which is Bech32.
+The next thing you need to do is create an address for receiving payments. This is done with the `bitcoin-cli getnewaddress` command. Remember that if you want more information on this command, you should type `bitcoin-cli help getnewaddress`. There are a variety of types of addresses, due to Bitcoin's evolution over the years. [§3.5](03_5_Understanding_the_Address.md) covers them all. For now, though we're just going to create an address of the default type, which is a Bech32 P2WPKH address.
 
 ```
 $ bitcoin-cli getnewaddress
 tb1q05ua6g7njnjrtsjc0t9w3jc6g2leeznasf4ny9
 ```
-You can keep typing the command you'll get a different address each time:
+If you keep typing the command, you'll get a different address each time:
 ```
 $ bitcoin-cli getnewaddress
 tb1q0psqqqgy0fv5928wmk86ntu7hlax8dva7nl82p
@@ -117,15 +117,15 @@ $ bitcoin-cli getaddressesbylabel ""
   }
 }
 ```
-Note that this address begins with an "tb1", which [means](https://en.bitcoin.it/wiki/List_of_address_prefixes) that it's a Bech32 address on either signet or testnet. The discussion of different address types in §4.1 will also talk about all of their identifying prefixes.
+Note that this address begins with an "tb1", which [means](https://en.bitcoin.it/wiki/List_of_address_prefixes) that it's a Bech32-encoded address on either signet or testnet. The discussion of different address types in [§3.5](03_5_Understanding_the_Address.md) will also talk about all of their identifying prefixes.
 
 > :link: **SIGNET vs MAINNET vs TESTNET:** The equivalent mainnet address would start with a "bc1".
 
 Take careful note of the address. You'll need to give it to whomever will be sending you funds.
 
-> :book: ***What is a Bitcoin address?*** A Bitcoin address is literally where you receive money. It's like an email address, but for funds. It's based on a public key, though different address schemes adjust that in different ways. However unlike an email address, a Bitcoin address should be considered single use: use it to receive funds just _once_. When you want to receive funds from someone else or at some other time, generate a new address. This is suggested in large part to improve your privacy. The whole blockchain is immutable, which means that explorers can look at long chains of transactions over time, making it possible to statistically determine who you and your contacts are, no matter how careful you are. If you keep reusing the same address, then this becomes even easier.
+> :book: ***What is a Bitcoin address?*** A Bitcoin address is literally where you receive money. It's like an email address, but for funds. It's based on a public key, though different address schemes adjust that in different ways. Unlike an email address, a Bitcoin address should be considered single use: use it to receive funds just _once_. When you want to receive funds from someone else or at some other time, generate a new address. This is suggested in large part to improve your privacy. The whole blockchain is immutable, which means that explorers can look at long chains of transactions over time, making it possible to statistically determine who you and your contacts are, no matter how careful you are. If you keep reusing the same address, then this becomes even easier.
 
-By creating your first Bitcoin address, you've also begun to fill in your Bitcoin wallet. More precisely, you've begun to fill the `wallet.dat` file in the appropriate `~/.bitcoin/signet /wallets/` directory. With a single address in hand, you could jump straight [§3.5: Receiving a Transaction](03_5_Receiving_a_Transaction.md) and begin receiving funds. However, before we get there, we're going to briefly discuss backing up your wallet and a few optional wallet commands that you might want to use in the future.
+By creating your first Bitcoin address, you've also begun to fill in your Bitcoin wallet. More precisely, you've begun to fill the `wallet.dat` file in the appropriate `~/.bitcoin/signet /wallets/` directory. With a single address in hand, you could jump straight [§3.6: Receiving a Transaction](03_6_Receiving_a_Transaction.md) and begin receiving funds. However, before we get there, we're going to briefly discuss backing up your wallet and a few optional wallet commands that you might want to use in the future.
 
 ## Backup Your Wallet
 
@@ -136,7 +136,7 @@ $ bitcoin-cli backupwallet ~/backups/mainwallet.dat
 ```
 This will create a backup of the SQLite file that you can later restore from with the `bitcoin-cli restorewallet` command. It's probably best used if you'll be backing up your wallet to a secure (encrypted) storage area.
 
-Just having a single backup will be enough to recover your wallet, because it'll contain the seed used to generate the wallet (more on that next chapter). However, it's good to regularly backup your wallet so that you don't lose data about your transactions.
+Just having a single backup will usually be enough to recover your wallet, because it'll contain the seed used to generate the wallet (more on that next chapter). However, it's good to regularly backup your wallet so that you don't lose data about your transactions. (A few commands also force the creation of a new seed, and you'd need to backup your wallet again in those cases.)
 
 ## Optional: Encrypt Your Wallet
 
@@ -145,9 +145,9 @@ You can choose to encrypt your wallet. (It actually just encrypts the private in
 $ bitcoin-cli encryptwallet "your-great-password"
 wallet encrypted; The keypool has been flushed and a new HD seed was generated. You need to make a new backup with the backupwallet RPC.
 ```
-You should _definitely_ encrypt your wallet if you are using `bitcoin-cli` to deal with real money, but you probably shouldn't do it for this course (or any other use of test networks) because it'll just add new hoops to jump through test out funds.
+You should _definitely_ encrypt your wallet if you are using `bitcoin-cli` to deal with real money, but you probably shouldn't do it for this course (or any other use of test networks) because it'll just add new hoops to jump through test out funds. Note that this is one of those functions that generates an additional seed: make sure you backup your wallet again afterward if you run it.
 
-Once you have encrypted your wallet, you'll be required to enter a passphrase in order to do many commands:
+Once you have encrypted your wallet, you'll be required to enter a passphrase prior to running many commands:
 ```
 $ bitcoin-cli walletpassphrase "your-great-password" 3600
 ```
@@ -160,14 +160,14 @@ $ bitcoin-cli walletlock
 
 ## Optional: Reload Named Wallets
 
-If you created a no-name (`""`) wallet, it will automatically load when you restart `bitcoind`. However, if you instead created a named wallet, it will not reload, forcing you to (initially) reload it by hand when you restart.
+If you created a no-name (`""`) wallet, it will automatically load when you restart `bitcoind`. However, if you instead created a named wallet, it will not reload, forcing you to (initially) reload it by hand when you restart `bitcoind`.
 ```
 $ bitcoin-cli loadwallet mainwallet
 {
   "name": "mainwallet"
 }
 ```
-But you can also make your named wallet load on start by adding a `true` to the end of the `bitcoin-cli loadwallet` command:
+However, you can make a named wallet load on startup by adding a `true` to the end of the `bitcoin-cli loadwallet` command:
 ```
 $ bitcoin-cli loadwallet mainwallet true
 {
@@ -185,7 +185,7 @@ $ bitcoin-cli createwallet "gamingfunds"
   "name": "gamingfunds"
 }
 ```
-bitcoin-cli listwallets` will list out all of the wallets currently "loaded", which will include your newly created one(s).
+`bitcoin-cli listwallets` will list out all of the wallets currently "loaded", which will include your newly created one(s).
 ```
 $ bitcoin-cli listwallets
 [
@@ -230,14 +230,14 @@ As discussed above, named wallets will not load by default unless you use `loadw
 
 ## Optional: Prove Control
 
-In previous versions of Bitcoin Core, you were able to prove control of an address with the `bicoin-cli signmessage` command. This is generally a nice feature because it allows you to assure someone sending you funds that they're sending to a place where you will definitely be able to retrieve the funds (or at least where you can currently). Because of the advent of descriptor wallets, which we'll talk about in the next section, this is no longer possible. You still _can_ prove control of an address by deriving a WIF-format private key from the descriptor for a particular address and then using `bitcoin-cli signmessagewithprivkey` with that specific key, but that's a complex process that goes beyond the scope of this course.
+In previous versions of Bitcoin Core, you were able to prove control of an address with the `bicoin-cli signmessage` command. This is generally a nice feature because it allows you to offer assurance to someone sending you funds that you'll definitely be able to retrieve those funds (or at least that you can currently). Because of the advent of descriptor wallets, which we'll talk about in the next section, this is no longer possible. You still _can_ prove control of an address by deriving a WIF-format private key from the descriptor for a particular address and then using `bitcoin-cli signmessagewithprivkey` with that specific key, but that's a complex process that goes beyond the scope of this course.
 
 Just keep in mind for the moment that proof of control is a nice feature if you can manage it.
 
 ## Summary: Setting Up Your Wallet
 
-You need to create an address to receive funds. That address is stored in a wallet, which you can backup. But, there's more to both the wallet and the address: they're supported by an interoperable description system called descriptors. Understanding that will be the topic of the next chapter, before we finally get some funds. We'll also be seeing lots more wallet commands in the future, but they'll be things like checking your balance, which require you to have those funds!
+You need to create an address to receive funds. That address is stored in a wallet, which you can backup. But, there's more to both the wallet and the address: wallets are supported by an interoperable description system called descriptors; and addresses come in a variety of types. We'll cover those in the next two chapters before we finally get to some funds. We'll also be seeing lots more wallet commands in the future, but they'll be things like checking your balance, which require you to have those funds!
 
 ## What's Next?
 
-Step back from "Understanding Your Bitcoin Setup" with [Interlude: Using Command-Line Variables](03_3__Interlude_Using_Command-Line_Variables.md).
+Continue "Understanding Your Bitcoin Setup" with [§3.4: Undestanding the Descriptor](03_4_Understanding_the_Descriptor.md) and then [§3.5: Understanding the Address](03_5_Understanding_the_Address.md).

03_4_Understanding_the_Descriptor.md

@@ -2,34 +2,34 @@
 
 You've got your wallet set up, but before we go further we're going to take a moment to really understand it.
 
-## Know about HD Wallets
+## Understand 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).
 
 > :book: ***What is a BIP?*** A BIP is a Bitcoin Improvement Proposal. It's an in-depth suggestion for a change to the Bitcoin Core code. Often, when a BIP has been sufficiently discussed and updated, it will become an actual part of the Bitcoin Core code. BIP-32 is one of many examples.
 
-## Know about Descriptor Wallets
+## Understand 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).

03_5_Understanding_the_Address.md

@@ -0,0 +1,73 @@
+# 3.5: Understanding the Address
+
+You understand your wallet now, but there's still the question of the addresses that it generates. Because, as it turns out, there are many sorts of addresses out there, some totally deprecated, some fairly bleeding edge, and some that are the default.
+
+## Understand Addresses 
+
+As you know, each Bitcoin address is a storage area for Bitcoin funds. Funds are sent from one address to another address as a _transaction_; the transaction matches the address that it was sent from. But an address is more than just a storage area: it's a lockbox. The specifics of the address define how that lockbox is actually opened up. The default is to use a private key associated with the public key that was used to create the address, but that's not the only way that Bitcoin addresses work.
+
+Different types of Bitcoin addresses change all of this. In general they may change:
+
+* How the Bitcoin address is derived from the public key.
+* How the Bitcoin address is encoded.
+* How the address is unlocked.
+* Whether additional scripts are necessary for unlocking.
+* How transactions sent from the address must be formed.
+
+### The Segwit Address(es)
+
+The most common sort of address actively used in the modern Bitcoin world is called by two different names that both mean the same thing: the Bech32 address (which names its encoding method, and technically includes other address types that are also encoded that way) or the SegWit address (which stands for "Segregated Witness" and describes how transactions sent to it must be formed). All Bitcoin addresses also have a "Pay-to" name, and Segwit addresses are called P2WPKH, which stands for "Pay to Witness Public Key Hash," which is a mouthful that will make more sense when you've met the older address types.
+
+Segwit came out of the Blocksize War of the '10s, where Bitcoin developers and users were trying to figure out a way to speed up the Bitcoin blockchain by allowing more transactions to be sent in less time. The result was the segwit soft fork. It solved the problem by moving the signatures (which are the key you use to unlock most Bitcoin transactions) from the middle of the transaction to the end, and then making that end space into increased space to store transactions, that could also be ignored by older servers. This allowed for an increase in the space to store transactions that was phased in gradually.
+
+The specifics aren't that important. What is important is that Segwit addresses (or Bech32 addresses or P2WPKH address) are the default type of address; when you created an address in [§3.3](03_3_Setting_Up_Your_Wallet.md), this is what you created.
+
+> :book: **What is a fork?** A fork is a change to the Bitcoin protocol. This isn't just a change to how one application (like Bitcoin Core) works, it's a change to how all of the members of the Bitcoin network agree to interact with each other. A hard fork makes new transactions incompatible with old transactions. It essentially two versions of Bitcoin (and most often has been used to actually create a new cryptocurrency). A soft fork ensures that old transactions remain compatible.
+
+### The Rest of the Addresses
+
+Here's a comprehensive listing of the address types, with the ❌ addreses largely deprecated (meaning don't worry about them!) and the ✅ addresses being the current ones (meaning that they will be relevant to your use of Bitcoin).
+
+Don't be overwhelmed by this list! If it looks like too much, just scan the ✅ addresses, which will be the only one used in this course, and come back and look at some of the other varieties if they come up and you want to figure out what they do exactly.
+
+The addresseses commonly in use for Bitcoin today are:
+
+* **✅ P2WPKH (Pay to Witness Public Hash).** P2WPKH is a SegWit address that can be unlocked with a single key. This is the default address type for Bitcoin core, and what you'll mostly be using. P2WPKH deprecates P2PKH.
+* **✅ P2WSH (Pay to Witness Script Hash).** P2WSH is a SegWit address that can be unlocked a script (rather than one or more private keys doing so). Scripts are described in [Chapter 11](11_0_Introducing_Bitcoin_Scripts.md) (and afterward). P2WSH deprecates P2SH
+* **✅ P2TR.** Taproot is the newest Bitcoin address type, but it was soft forked back in 2021, so it should have wide acceptance at this point. It's considered the next iteration of SegWit. It can produce smaller transactions for multisigs, has privacy advantages, and can also combine singular signatures with scripts. It hasn't been widely adopted yet.
+
+The addresses that have been deprecated are:
+
+* **❌ P2PK (Pay to Public Key).** This address type was used in the earliest days of Bitcoin and quickly deprecated. Revealing your public key can actually be dangerous since quantum computing or other future processor improvements might be able to brute force a private key given a public key. That's why modern addresses are based on a hash of your public key, instead of the public key itself, and why P2PK was quickly phased out.
+* **❌ P2MS (Pay to Multisig).** Most Bitcoin transactions are signed by a single key, which allows a single person to decide to send the Bitcoin. Multisigs instead allow multiple people to do so. P2MS was the initial attempt to support this, but it exposed public keys (like P2PK). It was quickly replaced by P2SH scripts, and more recently by P2WSH and P2TR.
+* **❌ P2PKH (Pay to Public Key Hash).** The P2PKH address was the predominent address type prior to the introduction of SegWit, which replaced it with P2WKH. Most new addresses are now created with P2WPKH, since their transactions are cheaper, but many older P2PKH addresses still hold funds, since it was in use for roughly a decade.
+* **❌ P2SH (Pay to Script Hash).** P2SH was the first type of scripting address, before signatures got reached for SegWit, resulting in P2WSH.
+* **❌ P2SH-P2WPKH and ❌P2SH-P2WSH.** When SegWit was being deployed, people wanted to send to it even before their wallets had been upgraded. These two "Nested Segwit" or "Wrapped Address" types offered the opportunity to do so by using a classic P2SH (scripting) address to incorporate the SegWit mechanics. These are actually just P2SH addresses with specific scripts, not a proper address type, and they're no longer needed since the SegWit upgrade is long past.
+
+[Unchained Capital](https://www.unchained.com/blog/bitcoin-address-types-compared) has conducted a survey of address types that they most recently updated in 2025. Besides giving more details on all of address types, it also listed how much of the Bitcoin supply was held in each address type. Though some deprecated addresses (mainly P2PKH) still hold large amounts of Bitcoin, that's a historic artifact. Some funds may be forever lost (due to lost keys) while others may be being held for the long term.
+  
+| Type | Description | Fund % |
+|------|-------------|--------|
+| P2PK | Pay to Public Key | 9% |
+| P2MS | Pay to Multisig | 0%+ |
+| P2PKH | Pay to Public Key Hash | 43% |
+| P2SH | Pay to Script hash | 24% |
+| P2WPKH | Pay to Witness Public Key Hash | 20% |
+| P2WSH | Pay to Witness Script Hash | 4% |
+| P2TR | Pay to Taproot | 0.1% |
+
+## Understand Address Prefixes
+
+Each different type of address is formed in a different way. An address can be derived in a different way, encoded in a different way, or formatted in a different way. As a result, addresses have different lengths and look different. Part of that formatting tends to be a prefix, which helps to identify an address type at a glance. Sometimes that prefix is different for mainnet and for the various testing networks (signet, testnet, regtest) so that you don't confuse fake funds and real funds.
+
+The following chart lists out the prefixes and encoding methods for each address type:
+
+| Type | Mainnet | Testnet | Encoding |
+|------|-------------|--------|----|
+| P2PK | N/A | N/A | public key |
+| P2MS | N/A | N/A | public keys |
+| P2PKH | 1... | m...<br>n...| base58 |
+| P2SH<br>P2SH-P2WPKH<br>P2SH-P2WSH | 3... | 2... | base58 |
+| P2WPKH | bc1q... | tb1q...| bech32 |
+| P2WSH | bc1q... | tb1q...| bech32 |
+| P2TR | bc1p... | tb1p...| bech32m |

README.md

@@ -33,11 +33,12 @@ If you'd like to make your own translation, please see [Contributing](https://gi
 * [3.0: Understanding Your Bitcoin Setup](03_0_Understanding_Your_Bitcoin_Setup.md)
   * [3.1: Verifying Your Bitcoin Setup](03_1_Verifying_Your_Bitcoin_Setup.md)
   * [3.2: Knowing Your Bitcoin Setup](03_2_Knowing_Your_Bitcoin_Setup.md)
-  * [3.3: Setting Up Your Wallet](03_3_Setting_Up_Your_Wallet.md) [**TO UPDATE**]
-    * [Interlude: Using Command-Line Variables](03_3a_Interlude_Using_Command-Line_Variables.md)
-    * [Interlude: Creating QR Codes](03_3b_Interlude_Creating_QR_Codes.md) [**TO WRITE**]
-  * [3.4: Understanding the Descriptor](03_5_Understanding_the_Descriptor.md) [**TO UPDATE**]
-  * [3.5: Receiving a Transaction](03_4_Receiving_a_Transaction.md) [**TO REVISE**]
+  * [3.3: Setting Up Your Wallet](03_3_Setting_Up_Your_Wallet.md) 
+  * [3.4: Understanding the Descriptor](03_4_Understanding_the_Descriptor.md)
+  * [3.5: Understanding the Address](03_5_Understanding_the_Address.md) 
+  * [3.6: Creating QR Codes for Addresses](03_6_Creating_QR_Codes_for_Addresses.md) [**TO WRITE**]
+  * [3.7: Receiving a Transaction](03_7_Receiving_a_Transaction.md) [**TO REVISE**]
+    * [Interlude: Using Command-Line Variables](03_7a_Interlude_Using_Command-Line_Variables.md)
 * [4.0: Sending Bitcoin Transactions](04_0_Sending_Bitcoin_Transactions.md) [**TO UPDATE FOR SEGWIT**]
   * [4.1: Sending Coins the Easy Way](04_1_Sending_Coins_The_Easy_Way.md) [**TO UPDATE FOR SEGWIT**]
   * [4.2: Creating a Raw Transaction](04_2_Creating_a_Raw_Transaction.md) [**TO UPDATE FOR SEGWIT**]
@@ -46,7 +47,7 @@ If you'd like to make your own translation, please see [Contributing](https://gi
   * [4.4: Sending Coins with Raw Transactions](04_4_Sending_Coins_with_a_Raw_Transaction.md) [**TO UPDATE**]
      * [Interlude: Using Curl](04_4a_Interlude_Using_Curl.md)
   * [4.5: Sending Coins with Automated Raw Transactions](04_5_Sending_Coins_with_Automated_Raw_Transactions.md) [**TO UPDATE FOR SEGWIT**]
-  * [4.6: Creating a Segwit Transaction](04_6_Creating_a_Segwit_Transaction.md) [**TO REMOVE**]
+  * [4.6: Creating a Segwit Transaction](04_6_Creating_a_Segwit_Transaction.md) [**TO REMOVE MAYBE**]
   * [4.6: Sending Other Types of Transactions](04_6_Sending_Other_Types_of_Transactions.md) [**TO WRITE**]
 * [5.0: Controlling Bitcoin Transactions](05_0_Controlling_Bitcoin_Transactions.md)
   * [5.1 Watching for Stuck Transactions](05_1_Watching_for_Stuck_Transactions.md)

TODO.md

@@ -4,13 +4,15 @@ The following TODO items are intended for a 3.0 version of Learning Bitcoin from
 
 ## Immediate TODO (for 2/19): Segwit
 
-1. Update §3.5 to fit into new flow
-2. Write QR Code Interlude (§3.3b)
-3. Change §4.1-4.5 to use Bech32 (incorporate existing §4.6)
-4. Create a new chapter §4.6 (4.1?)
+1. <strike>Reorg of Chapter 3</strike>
+2. Edit Updated Content in §3.3+3.4
+2. Write New Chapter §3.5
+3. Write QR Code Interlude (§3.5a)
    * Lay out new table of all the address types
    * Demonstrate how to send legacy & wrapped Segwit transactions
-5. Remove legacy address references from the rest of the course
+4. Update §3.6 to fit into new flow
+5. Change §4.1-4.5 to use Bech32 (incorporate existing §4.6)
+6. Remove legacy address references from the rest of the course
 
 ## Longer-Term TODO (Small Tasks)