edits

07_3_Integrating_with_Hardware_Wallets.md

@@ -2,21 +2,21 @@
 
 > :information_source: **NOTE:** This is a draft in progress, so that I can get some feedback from early reviewers. It is not yet ready for learning.
 
-One of the greatest powers of PSBTs is the ability to hand transactions off to hardware devices. This will be a great development tool for you if you continue to program with Bitcoin. However, you can't test it out now if you're using one of the configurations we suggest for this course — a VM on Linode per [§2.2](https://github.com/BlockchainCommons/Learning-Bitcoin-from-the-Command-Line/blob/master/02_2_Setting_Up_a_Bitcoin-Core_VPS_with_StackScript.md) or an even more farflung option such an AWS per [§2.3](https://github.com/BlockchainCommons/Learning-Bitcoin-from-the-Command-Line/blob/master/02_3_Setting_Up_Bitcoin_Core_Other.md) — because obviously you won't have any way to hook a hardware wallet up to your remote, virtual machine.
+One of the greatest powers of PSBTs is the ability to hand transactions off to hardware wallets. This will be a great development tool for you if you continue to program with Bitcoin. However, you can't test it out now if you're using one of the configurations we suggest for this course — a VM on Linode per [§2.2](https://github.com/BlockchainCommons/Learning-Bitcoin-from-the-Command-Line/blob/master/02_2_Setting_Up_a_Bitcoin-Core_VPS_with_StackScript.md) or an even more farflung option such an AWS per [§2.3](https://github.com/BlockchainCommons/Learning-Bitcoin-from-the-Command-Line/blob/master/02_3_Setting_Up_Bitcoin_Core_Other.md) — because obviously you won't have any way to hook a hardware wallet up to your remote, virtual machine.
 
->: ***What is a Hardware Wallet?*** A hardware wallet is an electronic device that improves the security of cryptocurrency by maintaing all the private keys on the device, rather than ever putting them on a device directly connected to the internet. Hardware wallets have specific protocols for providing online interactions, usually managed by a program talking to the device through a USB port. In this chapter, we'll be managing a hardware wallet with `bitcoin-cli` and the `hwy.py` program.
+>: ***What is a Hardware Wallet?*** A hardware wallet is an electronic device that improves the security of cryptocurrency by maintaing all the private keys on the device, rather than ever putting them on a computer directly connected to the internet. Hardware wallets have specific protocols for providing online interactions, usually managed by a program talking to the device through a USB port. In this chapter, we'll be managing a hardware wallet with `bitcoin-cli` and the `hwy.py` program.
 
-You have three options for moving through this chapter on hardware wallets: (1) read along without testing the code; (2) install Bitcoin on a local machine to fully test these commands; or (3) skip straight ahead to [Chapter 8: Expanding Bitcoin Transactions in Other Ways](08_0_Expanding_Bitcoin_Transactions_Other.md). We suggest option #1, but if you really want to get your hands dirty we'll also give some support for #2 by talking about using a Macintosh (a hardware-platform supported by [Bitcoin Standup](https://github.com/BlockchainCommons/Bitcoin-Standup) for testing).
+You have three options for moving through this chapter on hardware wallets: (1) read along without testing the code; (2) install Bitcoin on a local machine to fully test these commands; or (3) skip straight ahead to [Chapter 8: Expanding Bitcoin Transactions in Other Ways](08_0_Expanding_Bitcoin_Transactions_Other.md). We suggest option #1, but if you really want to get your hands dirty we'll also give some support for #2 by talking about using a Macintosh (a hardware-platform supported by [Bitcoin Standup](https://github.com/BlockchainCommons/Bitcoin-Standup)) for testing.
 
-> :warning: **VERSION WARNING:** PSBTs are an innovation from Bitcoin Core v 0.17.0. Earlier versions of Bitcoin Core will not be able to work with the PSBT while it is in process (though they will still be able to recognize the final transaction). The HWI interface appeared in Bitcoin Core v 0.18.0, but as long as you are using our suggested setup with Bitcoin Standup, it should all be fully integrated.
+> :warning: **VERSION WARNING:** PSBTs are an innovation from Bitcoin Core v 0.17.0. Earlier versions of Bitcoin Core will not be able to work with the PSBT while it is in process (though they will still be able to recognize the final transaction). The HWI interface appeared in Bitcoin Core v 0.18.0, but as long as you are using our suggested setup with Bitcoin Standup, it should work.
-
-> :warning **FRESHNESS WARNING:** The HWI interface is very new and raw around the edges as of Bitcoin Core v 0.20.0. It may be hard to install correctly, and it may have unintuive errors. What follows is a description of a working setup, but it took several tries to get right, and your setup may vary.
 
 The methodology described in this chapter for integrating with a hardware wallet depends on the [Bitcoin Hardware Wallet Interface](https://github.com/bitcoin-core/HWI) released through Bitcoin Core and builds on the [installation](https://github.com/bitcoin-core/HWI/blob/master/README.md) and [usage](https://github.com/bitcoin-core/HWI/blob/master/docs/bitcoin-core-usage.md) instructions found there.
 
+> :warning **FRESHNESS WARNING:** The HWI interface is very new and raw around the edges as of Bitcoin Core v 0.20.0. It may be hard to install correctly, and it may have unintuive errors. What follows is a description of a working setup, but it took several tries to get it right, and your setup may vary.
+
 ## Install Bitcoin Core on a Local Machine
 
-_If you just plan to read over this section and not test out these commands until some future date when you have a local development environment set up, you can skip this subsection, which is about creating a Bitcoin Core installation on a local machine such as a Mac or UNIX machine._
+_If you just plan to read over this section and not test out these commands until some future date when you have a local development environment, you can skip this subsection, which is about creating a Bitcoin Core installation on a local machine such as a Mac or UNIX machine._
 
 There are alternate versions of the Bitcoin Standup script that you used to create your VM that will install on a MacOS or on a non-Linode UNIX machine.
 
@@ -40,7 +40,7 @@ You'll note it not only gives us the full path, but also ensures that we stay on
 
 ## Install HWI on a Local Machine
 
-_The following instructions again assume a Mac, and again are unncessary if you're just reading through this chapter._
+_The following instructions again assume a Mac, and you can again skip this subsection if you're just reading through this chapter._
 
 HWI is a Bitcoin Core program available in python that can be used to interact with hardware wallets.
 
@@ -53,12 +53,12 @@ If you don't already have the `xcode` command line tools, you'll need them:
 $ xcode-select --install
 ```
 
-If you don't already have the Homebrew package manager, you should install that too. Current instructions are available at the [Homebrew site](https://brew.sh/). As of this writing, you simple need to:
+If you don't already have the Homebrew package manager, you should install that too. Current instructions are available at the [Homebrew site](https://brew.sh/). As of this writing, you simply need to:
 ```
 $ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
 ```
 
-For a first time install, you should also make sure your `/usr/local/Frameworks` directory is created correctly:
+For a first-time installation, you should also make sure your `/usr/local/Frameworks` directory is created correctly:
 ```
 $ sudo mkdir /usr/local/Frameworks
 $ sudo chown $(whoami):admin /usr/local/Frameworks
@@ -72,7 +72,7 @@ $ brew install libusb
 
 ### Installing HWI
 
-You're now ready to install HWI, which requires cloning a GitHub repo and compiling.
+You're now ready to install HWI, which requires cloning a GitHub repo and running an install script.
 
 If you don't have `git` already installed on your Mac, you can do so just by trying to run it: `git --version`.
 
@@ -101,7 +101,7 @@ _We had to choose a hardware-wallet platform too, for this HWI demonstration. Ou
 
 If you are working with Bitcoins on your Ledger, you probably won't need to do anything. (But we don't suggest that for use with this course). 
 
-To work with Testnet, as suggested by this course, you'll need to make a few updates:
+To work with Testnet coins, as suggested by this course, you'll need to make a few updates:
 
 1. Go to Settings on your Ledger Live app (it's the gear), go to the "Experimental Features" tab, and turn on "Developer Mode".
 2. Go to the "Manager" and install "Bitcoin Test". The current version requires that you have "Bitcoin" and "Etereum" installed first.
@@ -109,12 +109,14 @@ To work with Testnet, as suggested by this course, you'll need to make a few upd
 
 ## Link to a Ledger
 
-In order for a Ledger to be accessible, you must login with your PIN and then call up the app that you want to use, in this case the "Bitcoin Test" app. Once you've done that, you can ask for HWI to access the Ledger with the `enumerate` command:
+In order for a Ledger to be accessible, you must login with your PIN and then call up the app that you want to use, in this case the "Bitcoin Test" app. You may need to repeat this from time to time if your Ledger falls asleep.
+
+Once you've done that, you can ask for HWI to access the Ledger with the `enumerate` command:
 ```
 $ hwi enumerate
 [{"type": "ledger", "model": "ledger_nano_s", "path": "IOService:/AppleACPIPlatformExpert/PCI0@0/AppleACPIPCI/XHC1@14/XHC1@14000000/HS05@14100000/Nano S@14100000/Nano S@0/IOUSBHostHIDDevice@14100000,0", "fingerprint": "9a1d520b", "needs_pin_sent": false, "needs_passphrase_sent": false}]
 ```
-If you receive information on your device, you're set! As you can see, it verifies your hardware-wallet type, provides other identifying information, and tells you how you must communicate with the device. The `fingerprint` (`9a1d520b`) is what you should pay particular attention to, because all interactions with your hardware wallet will require it.
+If you receive information on your device, you're set! As you can see, it verifies your hardware-wallet type, provides other identifying information, and tells you how to communicate with the device. The `fingerprint` (`9a1d520b`) is what you should pay particular attention to, because all interactions with your hardware wallet will require it.
 
 If you instead got `[]`, then either (1) you didn't get your Ledger device ready by entering your PIN and choosing the correct application, or (2) there's something wrong with your Python setup, probably a missing dependency: you should consider `uninstall`ing it and trying from scratch.
 
@@ -134,7 +136,7 @@ $ bitcoin-cli --named createwallet wallet_name="ledger" disable_private_keys="tr
   "warning": ""
 }
 ```
-In this case, we are creating a new wallet `ledger` without private keys (since those will be over on the Ledger device).
+In this case, you are creating a new wallet `ledger` without private keys (since those will be over on the Ledger device).
 
 > :book: ***Why Name Wallets?*** To date, this course has used the default ("") wallet in Bitcoin Core. This is fine for many purposes, but is inadequate if you have a more complex situation, such as when you're watching keys from a hardware wallet. Here, we want to be able to differentiate from the locally owned keys (which are kept in the "" wallet) and the remotely owned keys (which are kept in the "ledger" wallet).
 
@@ -150,14 +152,14 @@ Because you've created a second wallet, some commands will now require a `-rpcwa
 
 ### Importing the Keys
 
-We now have to import a list of addresses from the hardware wallet to watch. This is done with HWI's `getkeypool` command:
+You now have to import a watch-list of addresses from the hardware wallet. This is done with HWI's `getkeypool` command:
 ```
 $ hwi -f 9a1d520b getkeypool --wpkh 0 1000
 [{"desc": "wpkh([9a1d520b/84h/1h/0h]tpubDD7KTtoGzK9GuWUQcr1uTJazsAkqoXhdrwGXWVix6nPpNZmSbagZWD4QSaMsyK8YohAirGDPrWdRiEpKzTFB7DrTrqfzHCn7yi5EsqeR93S/0/*)#qttxy592", "range": [0, 1000], "timestamp": "now", "internal": false, "keypool": true, "active": true, "watchonly": true}, {"desc": "wpkh([9a1d520b/84h/1h/0h]tpubDD7KTtoGzK9GuWUQcr1uTJazsAkqoXhdrwGXWVix6nPpNZmSbagZWD4QSaMsyK8YohAirGDPrWdRiEpKzTFB7DrTrqfzHCn7yi5EsqeR93S/1/*)#3lw8ep4j", "range": [0, 1000], "timestamp": "now", "internal": true, "keypool": true, "active": true, "watchonly": true}]
 ```
 We address HWI with the `fingerprint` and ask for the first 1000 WPKH (native Segwit) addresses. In return, we receive two descriptors for the key pool: one for receiving addresses and one for change addresses.
 
-> :book: ***What is a key pool?*** A key pool is a group of pregenerated keys. Modern HD wallets create key pools by continuing to determine new hierarchical addresses based on the original seed. The idea of key pools was originally implemented to ease the backup requirements of wallets. This allowed a user to generate a keypool and then  backup the wallet immediately, rather than requiring backups after every new address was created. The concept has also proven very useful in the modern day since it allows the importing of a whole set of future addresses from one device to another.
+> :book: ***What is a key pool?*** A key pool is a group of pregenerated keys. Modern HD wallets create key pools by continuing to determine new hierarchical addresses based on the original seed. The idea of key pools was originally implemented to ease the backup requirements of wallets. This allowed a user to generate a keypool and then backup the wallet immediately, rather than requiring backups after every new address was created. The concept has also proven very useful in the modern day since it allows the importing of a whole set of future addresses from one device to another.
 
 The values returned by `getkeypool` are the same sorts of descriptors that we learned about in [§3.5: Understanding the Descriptor](03_5_Understanding_the_Descriptor.md). At the time, we said that they were most useful for moving addresses among different machines. Here's the real-life example: moving addresses from a hardware wallet to Bitcoin Core node, so that our net-connected machine will be able to watch over the keys owned by the offline hardware wallet.
 
@@ -244,9 +246,9 @@ $ bitcoin-cli -rpcwallet=ledger listunspent
 ```
 ## Create a Transaction with PSBT
 
-Watching and receiving payments is just half the battle. You may also want to make payments using accounts held by your hardware wallet. This is a one more real-world example of using PSBTs, per the process we learned in [§7.1: Creating a Partially Signed Bitcoin Transaction](7_1_Creating_a_Partially_Signed_Bitcoin_Transaction.md). 
+Watching and receiving payments is just half the battle. You may also want to make payments using accounts held by your hardware wallet. This is a the fourth real-life example for using PSBTs, per the process outlined in [§7.1: Creating a Partially Signed Bitcoin Transaction](7_1_Creating_a_Partially_Signed_Bitcoin_Transaction.md). 
 
-The commands work exactly the same. In this case, we use `walletcreatefundedpsbt` to form our PSBT because this is a situation where we don't care what UTXOs are used:
+The commands work exactly the same. In this case, use `walletcreatefundedpsbt` to form your PSBT because this is a situation where you don't care what UTXOs are used:
 ```
 $ bitcoin-cli -named -rpcwallet=ledger walletcreatefundedpsbt inputs='''[]''' outputs='''[{"tb1qcaedd724gts3aug73m78c7nfsv9d8zs9q6h2kd":0.015}]'''
 {
@@ -256,7 +258,7 @@ $ bitcoin-cli -named -rpcwallet=ledger walletcreatefundedpsbt inputs='''[]''' ou
 }
 ```
 
-We can take a look at the PSBT and verify that it looks rational:
+You can take a look at the PSBT and verify that it looks rational:
 ```
 $ psbt="cHNidP8BAJoCAAAAAri6BLjKQZGO9Y1iVIYbxlxBJ2kqsTPWnxGaH4HrSjxbAAAAAAD+////leV0hwJ0fO40RmhuFVIYtO16ktic2J4vJFLAsT5TM8cBAAAAAP7///8CYOMWAAAAAAAWABTHctb5VULhHvEejvx8emmDCtOKBU+gBwAAAAAAFgAU9Ojd5ds3CJi1fIRWbj92CYhQgX0AAAAAAAEBH0BCDwAAAAAAFgAUABk8i/Je8Fb41FcaHD9lEj5f54giBgMBaNlILisC1wJ/tKie3FStqhrfcJM09kfQobBTOCiuxRiaHVILVAAAgAEAAIAAAACAAAAAADkCAAAAAQEfQEIPAAAAAAAWABQtTxOfqohTBNFWFqFm0tUVdK9KXSIGAqATz5xLX1aJ2SUwNqPkd8+YaJYm94FMlPCScm8Rt0GrGJodUgtUAACAAQAAgAAAAIAAAAAAAAAAAAAAIgID2UK1nupSfXC81nmB65XZ+pYlJp/W6wNk5FLt5ZCSx6kYmh1SC1QAAIABAACAAAAAgAEAAAABAAAAAA=="
 
@@ -375,7 +377,7 @@ $ bitcoin-cli decodepsbt $psbt
   "fee": 0.00000209
 }
 ```
-And as usual, `analyzepsbt` will show us how far we've gotten:
+And as usual, `analyzepsbt` will show how far you've gotten:
 ```
 $ bitcoin-cli analyzepsbt $psbt
 {
@@ -407,9 +409,9 @@ $ bitcoin-cli analyzepsbt $psbt
   "next": "signer"
 }
 ```
-Because we imported that keypool, `bitcoin-cli` has all the information it needs to fill in the inputs, it just can't sign because the private keys are held on the hardware wallet.
+Because you imported that keypool, `bitcoin-cli` has all the information it needs to fill in the inputs, it just can't sign because the private keys are held on the hardware wallet.
 
-That's where HWI comes in, with the `signtx` command. We just send along our PSBT:
+That's where HWI comes in, with the `signtx` command. You just send along the PSBT:
 ```
 $ hwi -f 9a1d520b signtx $psbt
 ```