CH01: edits for Mark (Xekyo) Erhardt feedback (thanks!)

- Provide rough block and year when 99% of all BTC will have been mined

- Remove user-stories section.  I think this section frontloaded too
  much irrelevant detail.  In new sections of this edition, I've
  exclusively used the convential Alice, Bob, Carol, etc.---without
  trying to maintain a consistent backstory.  This is simpler on the
  writer and, I think, simpler on the reader---if they jump into a
  section of the book, they don't need to worry that there's some
  important context in a previous section.

    - This also necessitated a few changes chapter 2.

- Mostly remove the phrase "custody".  Instead use the phares "control
  the key".  I think this is clearer to non-specialists and a quick grep
  shows that we don't use any version of the word "custody" elsewhere in
  the book.

- Drop localbitcoins.com.  This service was terminated after this
  chapter was updated.

- Add 'feerate' to the script for catching forbidden words.  :-( This
  required a change to a comment in an image source.

- Other minor changes and typo fixes

ch01.asciidoc

@@ -31,7 +31,7 @@ hands of each user.
 Bitcoin is a distributed, peer-to-peer system. As such, there is no
 central server or point of control. Units of bitcoin
 are created through a process called "mining," which involves repeatedly
-performing a competitive computational task that references a list of recent Bitcoin
+performing a computational task that references a list of recent Bitcoin
 transactions. Any participant in the Bitcoin network may operate as a
 miner, using their computing devices to help secure
 transactions. Every 10 minutes, on average, one Bitcoin miner can add security to
@@ -41,17 +41,26 @@ mining decentralizes the currency-issuance
 and clearing functions of a central bank and replaces the need for any
 central bank.
 
+//-- Math for following paragraph --
+//total_btc = 0
+//for i in range(0, 10_000_000):
+//  total_btc += (50 /  (2**int(i/210000)) )
+//  if total_btc / 21e6 > 0.99:
+//     print(i)
+//     break
+
 The Bitcoin protocol includes built-in algorithms that regulate the
 mining function across the network. The difficulty of the computational
 task that miners must perform is adjusted dynamically so that, on
 average, someone succeeds every 10 minutes regardless of how many miners
 (and how much processing) are competing at any moment. The protocol also
-halves the rate at which new bitcoins are created,
+periodically decreases the rate at which new bitcoins are created,
 limiting the total number of bitcoins that will be created to a fixed total
 just below 21 million coins. The result is that the number of bitcoins in
 circulation closely follows an easily predictable curve where half of
-the remaining coins are added to circulation every four years.  By the
+the remaining coins are added to circulation every four years.  At
-time the third edition of this book has been published for ten years, 99% of all bitcoins
+approximately block 1,411,200, which is expected to be produced around
+the year 2035, 99% of all bitcoins
 that will ever exist will have been issued.  Due to bitcoin's
 diminishing rate of issuance, over the long term, the Bitcoin currency
 is deflationary.  Furthermore, nobody can force you to accept
@@ -112,9 +121,10 @@ through a central clearinghouse.
 
 The Bitcoin network started in 2009, based on a reference implementation
 published by Nakamoto and since revised by many other programmers. The
-implementation of the Proof-of-Work algorithm (mining) that provides
+number and power of machines running the Proof-of-Work algorithm
-security and resilience for Bitcoin has increased in power
+(mining) that provides security and resilience for Bitcoin have
-exponentially, and now exceeds the combined number of computing operations of the
+increased exponentially, and their combined computational power now
+exceeds the combined number of computing operations of the
 world's top supercomputers.
 
 Satoshi Nakamoto withdrew from the public in April 2011, leaving the responsibility of developing the code and network to a thriving group of volunteers. The identity of the person or people behind Bitcoin is still unknown. ((("open source licenses")))However, neither Satoshi Nakamoto nor anyone else exerts individual control over the Bitcoin system, which operates based on fully transparent mathematical principles, open source code, and consensus among participants. The invention itself is groundbreaking and has already spawned new science in the fields of distributed computing, economics, and econometrics.
@@ -133,35 +143,6 @@ Proof-of-Work to achieve consensus _without a central trusted
 authority_, represents a breakthrough in distributed computing.
 ****
 
-
-[[user-stories]]
-=== Bitcoin Uses, Users, and Their Stories
-
-((("bitcoin", "use cases", id="GSuses01")))Bitcoin is an innovation in the ancient technology of money. At its core, money simply facilitates the exchange of value between people. Therefore, in order to fully understand Bitcoin and its uses, we'll examine it from the perspective of people using it. Each of the people and their stories, as listed here, illustrates one or more specific use cases. We'll be seeing them throughout the book:
-
-North American e-commerce retails::
-((("use cases", "retail sales")))Alice lives in Northern California's Bay Area. She has heard about Bitcoin from her techie friends and wants to start using it. We will follow her story as she learns about Bitcoin, acquires some, and then spends her bitcoin to buy a laptop from Bob's online store. This story will introduce us to the software, the exchanges, and basic transactions from the perspective of a retail consumer.
-
-North American high-value retail::
-Carol is an art gallery owner in San Francisco. She sells expensive paintings for bitcoin. This story will introduce the risks of a "51% attack" for retailers of high-value items.
-
-Offshore contract services::
-((("offshore contract services")))((("use cases", "offshore contract services")))Bob, the cafe owner in Palo Alto, is building a new website. He has contracted with a web developer, Gopesh, who lives in Bangalore, India. Gopesh has agreed to be paid in bitcoin. This story will examine the use of Bitcoin for outsourcing, contract services, and international wire transfers.
-
-Web store::
-((("use cases", "web store")))Gabriel is an enterprising young teenager in Rio de Janeiro, running a small web store that sells Bitcoin-branded t-shirts, coffee mugs, and stickers. Gabriel is too young to have a bank account, but his parents are encouraging his entrepreneurial spirit.
-
-Charitable donations::
-((("charitable donations")))((("use cases", "charitable donations")))Eugenia is the director of a children's charity in the Philippines. Recently she has discovered Bitcoin and wants to use it to reach a whole new group of foreign and domestic donors to fundraise for her charity. She's also investigating ways to use Bitcoin to distribute funds quickly to areas of need. This story will show the use of Bitcoin for global fundraising across currencies and borders and the use of an open ledger for transparency in charitable organizations.
-
-Import/export::
-((("use cases", "import/export")))Mohammed is an electronics importer in Dubai. He's trying to use Bitcoin to buy electronics from the United States and China for import into the UAE to accelerate the process of payments for imports. This story will show how Bitcoin can be used for large business-to-business international payments tied to physical goods.
-
-Mining for bitcoin::
-((("use cases", "mining for bitcoin")))Jing is a computer engineering student in Shanghai. He has built a "mining" rig to mine for bitcoin using his engineering skills to supplement his income. This story will examine the "industrial" base of Bitcoin: the specialized equipment used to secure the Bitcoin network and issue new currency.
-
-Each of these stories is based on the real people and real industries currently using Bitcoin to create new markets, new industries, and innovative solutions to global economic issues.((("", startref="GSuses01")))
-
 === Getting Started
 
 ((("getting started", "wallet selection",
@@ -262,17 +243,17 @@ peer, but the security of a client ultimately relies on the integrity of
 its peers.
 ====
 
-===== Custodial vs. Non-Custodial
+===== Who controls the keys
 
 A very important additional consideration is _who controls the keys_. As
 we will see in subsequent chapters, access to bitcoins is
 controlled by "private keys", which are like very long PIN numbers. If
-you are the only one to have *custody* and *control* over these private
+you are the only one to have *control* over these private
 keys, you are in control of your bitcoin. Conversely, if you do not have
-custody, then your bitcoin is managed by a third-party custodian, who
+control, then your bitcoin is managed by a third-party who
-ultimately controls your funds on your behalf. Wallets fall into two
+ultimately controls your funds on your behalf. Key management software falls into two
-important categories based on custody: _non-custodial_ wallets where you
+important categories based on control: _wallets_ where you
-control the keys and the funds and _custodial_ wallets where some
+control the keys and the funds and accounts with custodians where some
 third-party controls the keys. To emphasize this point, I (Andreas)
 coined the phrase:
 
@@ -280,14 +261,14 @@ _Your keys, your coins. Not your keys, not your coins_.
 
 Combining these categorizations, many Bitcoin wallets fall into a few
 groups, with the three most common being desktop full node
-(non-custodial), mobile lightweight wallet (non-custodial), and web
+(you control the keys), mobile lightweight wallet (you control the keys), and web-based
-third-party wallet (custodial). The lines between different categories
+accounts with third parties (you don't control the keys). The lines between different categories
-are often blurry, as many wallets run on multiple platforms and can
+are sometimes blurry, as software runs on multiple platforms and can
 interact with the network in different ways.
 
 For the purposes of this book, we will be demonstrating the use of a
-variety of downloadable Bitcoin clients, from the reference
+variety of downloadable Bitcoin software, from the reference
-implementation (Bitcoin Core) to mobile and web wallets. Some of the
+implementation (Bitcoin Core) to mobile and web software. Some of the
 examples will require the use of Bitcoin Core, which, in addition to
 being a full node, also exposes APIs to the wallet, network, and
 transaction services. If you are planning to explore the programmatic
@@ -299,7 +280,7 @@ startref="Wselect01")))
 
 ((("getting started", "quick start example",
 id="GSquick01")))((("wallets", "quick start example",
-id="Wquick01")))Alice, who we introduced in <<user-stories>>, is not a
+id="Wquick01")))Alice is not a
 technical user and only recently heard about Bitcoin from her friend
 Joe. While at a party, Joe is once again enthusiastically explaining
 Bitcoin to everyone around him and is offering a demonstration. Intrigued,
@@ -356,7 +337,7 @@ If something happens to Alice's wallet, she can download a new copy of
 her wallet software and enter this recovery code to rebuild the wallet
 database of all the onchain transactions she's ever sent or received.
 However, recovering from the recovery code will not by itself restore any additional
-data Alice entered into her wallet, such as the names she associated
+data Alice entered into her wallet, such as the labels she associated
 with particular addresses or transactions.  Although losing access to
 that metadata isn't as important as losing access to money, it can
 still be important in its own way.  Imagine you need to review an old
@@ -384,7 +365,7 @@ Although many legitimate wallets will prompt you to re-enter
 your recovery code, there are also many malware applications that mimic the
 design of a wallet, insist you enter your recovery code, and then
 relay any entered code to the malware developer so they can steal
-your funds.  This is the equivilent of phishing websites that try to
+your funds.  This is the equivalent of phishing websites that try to
 trick you into giving them your bank passphrase.  For most wallet
 applications, the only times they will ask for your recovery code are during
 the initial set up (before you have received any bitcoins) and during
@@ -395,7 +376,7 @@ ensure you aren't being phished.
 
 ==== Bitcoin addresses
 
-Alice is now ready to start using her new bitcoin wallet. ((("", startref="GSquick01")))((("", startref="Wquick01"))) Her wallet application randomly generated a private key (described in more detail in <<private_keys>>) which will be used to derive Bitcoin addresses that direct to her wallet. At this point, her Bitcoin addresses are not known to the Bitcoin network or "registered" with any part of the Bitcoin system. Her Bitcoin addresses are simply random numbers that correspond to her private key that she can use to control access to the funds. The addresses are generated independently by her wallet without reference or registration with any service.
+Alice is now ready to start using her new bitcoin wallet. ((("", startref="GSquick01")))((("", startref="Wquick01"))) Her wallet application randomly generated a private key (described in more detail in <<private_keys>>) which will be used to derive Bitcoin addresses that direct to her wallet. At this point, her Bitcoin addresses are not known to the Bitcoin network or "registered" with any part of the Bitcoin system. Her Bitcoin addresses are simply numbers that correspond to her private key that she can use to control access to the funds. The addresses are generated independently by her wallet without reference or registration with any service.
 
 [TIP]
 ====
@@ -409,7 +390,7 @@ learns one of your Bitcoin addresses can withdraw money from your wallet--you
 must initiate all spends.  However, if you give two people the same
 address, they will be able to see how much bitcoin the other person sent
 you.  If you post your address publicly, everyone will be able to see
-how much bitcoin other people sent you.  To protect your privacy, you
+how much bitcoin other people sent to that address.  To protect your privacy, you
 should generate a new invoice with a new address each time you request a
 payment.
 ====
@@ -442,7 +423,6 @@ Bitcoin transactions are irreversible. Most electronic payment networks such as
 Here are some methods for getting bitcoin as a new user:
 
 * Find a friend who has bitcoin and buy some from him or her directly. Many Bitcoin users start this way. This method is the least complicated. One way to meet people with bitcoin is to attend a local Bitcoin meetup listed at https://bitcoin.meetup.com[Meetup.com].
-* Use a classified service such as pass:[<a class="orm:hideurl" href="https://localbitcoins.com/">localbitcoins.com</a>] to find a seller in your area to buy bitcoin for cash in an in-person transaction.
 * Earn bitcoin by selling a product or service for bitcoin. If you are a programmer, sell your programming skills. If you're a hairdresser, cut hair for bitcoin.
 * ((("Coin ATM Radar")))((("ATMs, locating")))Use a bitcoin ATM in your city.  A bitcoin ATM is a machine that accepts cash and sends bitcoin to your smartphone bitcoin wallet. Find a bitcoin ATM close to you using an online map from http://coinatmradar.com[Coin ATM Radar].
 * ((("exchange rates", "listing services")))Use a bitcoin currency exchange linked to your bank account. Many countries now have currency exchanges that offer a market for buyers and sellers to swap bitcoin with local currency. Exchange-rate listing services, such as https://bitcoinaverage.com[BitcoinAverage], often show a list of bitcoin exchanges for each currency.
@@ -513,7 +493,7 @@ so, Joe enters "Alice".  Weeks or months from now, this will help Joe
 remember why he sent these 0.001 bitcoins.  Some wallets may also prompt
 Joe about fees.  Depending on the wallet and how the transaction is
 being sent, the wallet may ask Joe to either enter a transaction fee rate or
-prompt him with a suggested feerate.  The higher the transaction fee rate, the
+prompt him with a suggested fee (or fee rate).  The higher the transaction fee, the
 faster the transaction will be confirmed (see <<confirmations>>).
 
 [[wallet-send]]

ch02.asciidoc

@@ -572,9 +572,9 @@ verification process is able to probabalistically prove the work was
 done, so the data necessary to generate that proof--in this case, the
 block--is called Proof-of-Work (PoW).
 
-((("mining and consensus", "mining farms and pools")))In
+((("mining and consensus", "mining farms and pools")))
-<<user-stories>>, we introduced ((("use cases", "mining for
+((("use cases", "mining for
-bitcoin")))Jing, an entrepreneur in Shanghai. Jing runs a _mining farm_,
+bitcoin")))Jing is an entrepreneur in Shanghai. Jing runs a _mining farm_,
 which is a business that runs thousands of specialized mining computers,
 competing for the block reward. Jing's mining
 computers compete against thousands of similar systems in the global

images/supply_demand.gnuplot

@@ -96,7 +96,6 @@ plot price(x) title '' with lines lc rgb 'black' lw 4, \
 #######################
 
 set output 'fee-patience.png'
-#set title "Wait Times for Different Feerates"
 
 unset label 1
 unset label 2

tools/discouraged.sh

@@ -36,3 +36,4 @@ BIP [0-9]
 \<nValue\>
 witness field
 witness element
+feerate