From 02106a1147931b8d92e1d0f027fac26c5ba57170 Mon Sep 17 00:00:00 2001 From: "David A. Harding" Date: Thu, 24 Aug 2023 10:47:54 +0200 Subject: [PATCH] All: harding edits for first complete readthrough --- ch01.asciidoc | 23 ++++++++------- ch02.asciidoc | 58 ++++++++++++++++++-------------------- ch03.asciidoc | 21 ++++++++------ ch04.asciidoc | 28 +++++++++--------- ch05.asciidoc | 51 +++++++++++++++++---------------- ch10.asciidoc | 2 +- ch12.asciidoc | 2 +- chapters/fees.adoc | 2 +- chapters/transactions.adoc | 19 ++++++------- glossary.asciidoc | 2 ++ tools/discouraged.sh | 3 +- 11 files changed, 109 insertions(+), 102 deletions(-) diff --git a/ch01.asciidoc b/ch01.asciidoc index a71c7c0a..5d0c8046 100644 --- a/ch01.asciidoc +++ b/ch01.asciidoc @@ -111,7 +111,7 @@ of transactions. ((("Proof-of-Work algorithm")))((("decentralized systems", "consensus in")))((("mining and consensus", "Proof-of-Work algorithm")))A key innovation was to use a distributed computation system (called a "Proof-of-Work" algorithm) to conduct a global -"election" every 10 minutes, allowing the decentralized network to +lottery every 10 minutes on average, allowing the decentralized network to arrive at _consensus_ about the state of transactions. ((("double-spend problem")))((("spending bitcoin", "double-spend problem")))This elegantly solves the issue of double-spend where a single currency unit @@ -214,9 +214,8 @@ computer resources--about the same as watching an hour-long streaming video for each day of Bitcoin transactions--but the full node offers complete autonomy to its users. -Lightweight client:: ((("lightweight -clients"))) -client, also known as a simplified-payment-verification (SPV) client, +Lightweight client:: ((("lightweight clients"))) +A lightweight client, also known as a simplified-payment-verification (SPV) client, connects to a full node or other remote server for receiving and sending Bitcoin transaction information, but stores the user wallet locally, partially validates the transactions it receives, and independently @@ -251,8 +250,8 @@ 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 control, then your bitcoin is managed by a third-party who ultimately controls your funds on your behalf. Key management software falls into two -important categories based on control: _wallets_ where you -control the keys and the funds and accounts with custodians where some +important categories based on control: _wallets_, where you +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: @@ -281,7 +280,7 @@ startref="Wselect01"))) id="GSquick01")))((("wallets", "quick start example", 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 +Joe. While at a party, Joe is enthusiastically explaining Bitcoin to everyone around him and is offering a demonstration. Intrigued, Alice asks how she can get started with Bitcoin. Joe says that a mobile wallet is best for new users and he recommends a few of his favorite @@ -396,13 +395,13 @@ payment. ==== Receiving bitcoin -Alice uses the _Receive_ button, which displays a QR code along with a Bitcoin address, shown in <>. +Alice uses the _Receive_ button, which displays a QR code, shown in <>. [[wallet_receive]] .Alice uses the Receive screen on her mobile Bitcoin wallet, and displays her address in a QR code format image::images/receive.png["Wallet receive screen with QR code displayed. Image derived from Bitcoin Design Guide CC-BY"] -The QR code is the square with a pattern of black and white dots, serving as a form of barcode that contains the same information in a format that can be scanned by Joe's smartphone camera. Near the wallet's QR code is the Bitcoin address it encodes, and Alice may choose to manually send her address to Joe by copying it onto her clipboard with a tap. +The QR code is the square with a pattern of black and white dots, serving as a form of barcode that contains the same information in a format that can be scanned by Joe's smartphone camera. [WARNING] ==== @@ -419,7 +418,7 @@ bitcoin-accepting charity. Bitcoin transactions are irreversible. Most electronic payment networks such as credit cards, debit cards, PayPal, and bank account transfers are reversible. For someone selling bitcoin, this difference introduces a very high risk that the buyer will reverse the electronic payment after they have received bitcoin, in effect defrauding the seller. To mitigate this risk, companies accepting traditional electronic payments in return for bitcoin usually require buyers to undergo identity verification and credit-worthiness checks, which may take several days or weeks. As a new user, this means you cannot buy bitcoin instantly with a credit card. With a bit of patience and creative thinking, however, you won't need to. [role="pagebreak-before"] -Here are some methods for getting bitcoin as a new user: +Here are some methods for acquiring 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]. * 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. @@ -443,11 +442,11 @@ identity and banking information. Users should be aware that once a Bitcoin address is attached to an identity, other associated bitcoin transactions may also become easy to identify and track--including transactions made earlier. This is one reason -many users choose to maintain dedicated exchange accounts unlinked to +many users choose to maintain dedicated exchange accounts independent from their wallets. ==== -Alice was introduced to bitcoin by a friend so she has an easy way to acquire her first bitcoin. Next, we will look at how she buys bitcoin from her friend Joe and how Joe sends the bitcoin to her wallet. +Alice was introduced to Bitcoin by a friend so she has an easy way to acquire her first bitcoin. Next, we will look at how she buys bitcoin from her friend Joe and how Joe sends the bitcoin to her wallet. [[bitcoin_price]] ==== Finding the Current Price of Bitcoin diff --git a/ch02.asciidoc b/ch02.asciidoc index 24d83aa4..c39033e7 100644 --- a/ch02.asciidoc +++ b/ch02.asciidoc @@ -240,8 +240,8 @@ image::images/transaction-chain.png["Transaction chain"] [TIP] ==== -Serialized Bitcoin transactions---the data format that software uses for -sending transactions---encodes the value to transfer using an integer +Serialized Bitcoin transactions--the data format that software uses for +sending transactions--encodes the value to transfer using an integer of the smallest defined onchain unit of value. When Bitcoin was first created, this unit didn't have a name and some developers simply called it the _base unit._ Later many users began calling this unit a @@ -312,14 +312,14 @@ transaction has one input and two outputs and is shown in .Most common transaction image::images/mbc2_0205.png["Common Transaction"] -Another common form of transaction is a _consolidation transaction_ one that spends several inputs +Another common form of transaction is a _consolidation transaction_ that spends several inputs into a single output (<>). This represents the real-world equivalent of exchanging a pile of coins and currency notes for a single larger note. Transactions like these are sometimes generated by wallets and businesses to clean up lots of smaller amounts. [[transaction-consolidating]] -.Transaction aggregating funds +.Consolidation transaction aggregating funds image::images/mbc2_0206.png["Aggregating Transaction"] Finally, another transaction form that is seen often on the bitcoin @@ -330,7 +330,7 @@ distribute funds, such as when processing payroll payments to multiple employees.((("", startref="Tover02"))) [[transaction-distributing]] -.Transaction distributing funds +.Batch transaction distributing funds image::images/mbc2_0207.png["Distributing Transaction"] === Constructing a Transaction @@ -358,8 +358,8 @@ which was created in exchange for cash (see <>). A bitcoin wallet application that runs on a full node actually contains a copy of every confirmed transaction's unspent outputs, called _Unspent Transaction Outputs_ (UTXOs). -However, because full nodes use more resources, most -user wallets run "lightweight" clients that track only the user's own +However, because full nodes use more resources, many +user wallets run lightweight clients that track only the user's own UTXOs. In this case, this single @@ -374,14 +374,12 @@ wallet application creates the transaction outputs (payments). ==== Creating the Outputs ((("outputs and inputs", "creating outputs")))A transaction output is -created in the form of a script that creates an encumbrance on the value -and can only be redeemed by the introduction of a solution to the -script. In simpler terms, Alice's transaction output will contain a -script that says something like, "This output is payable to whoever can +created with a +script that says something like, "This output is paid to whoever can present a signature from the key corresponding to Bob's public address." Because only Bob has the wallet with the keys corresponding to that -address, only Bob's wallet can present such a signature to redeem this -output. Alice will therefore "encumber" the output value with a demand +address, only Bob's wallet can present such a signature to later spend this +output. Alice will therefore _encumber_ the output value with a demand for a signature from Bob. This transaction will also include a second output, because Alice's @@ -436,7 +434,7 @@ being the nodes (dots). For that reason, Bitcoin peers are commonly called "full verification nodes", or _full nodes_ for short. Alice's wallet application can send the new -transaction to any Bitcoin node it is connected to over any type of +transaction to any Bitcoin node over any type of connection: wired, WiFi, mobile, etc. It can also send the transaction to another program (such as a block explorer) that will relay it to a node. Her bitcoin wallet does not have @@ -472,7 +470,7 @@ included in a block by a process called _mining_ and that block has been validated by full nodes. See <> for a detailed explanation. -The Bitcoin system of counterfeit protection is based on computation. +Bitcoin's system of counterfeit protection is based on computation. Transactions are bundled into _blocks_. Blocks have a very small header that must be formed in a very specific way, requiring an enormous amount of computation to get right--but only a small amount of @@ -484,20 +482,20 @@ by")))((("consensus", see="mining and consensus")))Miners can only receive honest income from creating blocks that follow all of Bitcoin's _consensus rules_. Therefore, miners are normally incentivized to only include valid transactions in their blocks and the blocks they -build upon. This allows users to optionally trust that any transaction -in a block is a valid transaction. +build upon. This allows users to optionally make a trust-based +assumption that any transaction in a block is a valid transaction. -* Mining currently creates new bitcoin in each block, almost like a central bank +* Mining currently creates new bitcoin's in each block, almost like a central bank printing new money. The amount of bitcoin created per block is limited and diminishes with time, following a fixed issuance schedule. Mining achieves a fine balance between cost and reward. Mining uses electricity to solve a computational problem. A successful miner will -collect a _reward_ in the form of new bitcoin and transaction fees. +collect a _reward_ in the form of new bitcoins and transaction fees. However, the reward will only be collected if the miner has correctly validated all the transactions, to the satisfaction of the rules of -_consensus_. This delicate balance provides security for bitcoin without +_consensus_. This delicate balance provides security for Bitcoin without a central authority. Mining is designed to be a decentralized lottery. Each miner can create @@ -548,8 +546,8 @@ on a single silicon chip. ((("mining pools", "defined")))Jing's company also participates in a _mining pool_, which much like a lottery pool allows several participants to share their efforts and rewards. Jing's company now runs a warehouse containing thousands of ASIC miners to -mine for bitcoin 24 hours a day. The company pays its electricity costs -by selling the bitcoin it is able to generate from mining, creating some +mine for bitcoins 24 hours a day. The company pays its electricity costs +by selling the bitcoins it is able to generate from mining, creating some income from the profits. [[confirmation_score]] @@ -559,7 +557,7 @@ income from the profits. flowing into the network from user wallets and other applications. As these are seen by the Bitcoin network nodes, they get added to a temporary pool of unverified transactions maintained by each node. As -miners construct a new candidate block, they add unverified transactions from this +miners construct a new _candidate block_, they add unverified transactions from this pool to the candidate block and then attempt to prove the validity of that candidate block, with the mining algorithm (Proof-of-Work). The process of mining is explained in detail in <>. @@ -567,15 +565,15 @@ is explained in detail in <>. Transactions are added to the new block, prioritized by the highest fee rate transactions first and a few other criteria. Each miner starts the process of mining a new candidate block of transactions as soon as he receives the -previous block from the network, knowing he has lost that previous round -of competition. He immediately creates a new candidate block, fills it with -transactions and the fingerprint of the previous block, and starts +previous block from the network, knowing that some other miner won that +iteration of the lottery. He immediately creates a new candidate block +with a commitment to the previous block, fills it with transactions, and starts calculating the Proof-of-Work for the candidate block. Each miner includes a special transaction in his candidate block, one that pays his own Bitcoin address the block reward plus the sum of transaction fees from all the transactions included in the candidate block. If he -finds a solution that makes the candidate into a valid block, he "wins" this reward -because his successful block is added to the global blockchain and the +finds a solution that makes the candidate into a valid block, he receives this reward +after his successful block is added to the global blockchain and the reward transaction he included becomes spendable. ((("mining pools", "operation of")))Jing, who participates in a mining pool, has set up his software to create candidate blocks that assign the reward to a pool address. @@ -597,7 +595,7 @@ block. Jing's winning block containing Alice's transaction became part of the blockchain. The block containing Alice's transaction is counted as one -"confirmation" of that transaction. After the block containing Alice's +_confirmation_ of that transaction. After the block containing Alice's transaction has propagated through the network, creating an alternative block with a different version of Alice's transaction (such as a transaction that doesn't pay Bob) would require performing the same @@ -609,7 +607,7 @@ accept an alternative block, an additional new block would need to be mined on top of the alternative. That means miners have a choice. They can work with Alice on an -alternative version of the transaction where she pays Bob, perhaps with +alternative to the transaction where she pays Bob, perhaps with Alice paying miners a share of the money she previously paid Bob. This dishonest behavior will require they expend the effort required to create two new blocks. Instead, miners who behave honestly can create a diff --git a/ch03.asciidoc b/ch03.asciidoc index 4b09d0fa..6ad0b8a8 100644 --- a/ch03.asciidoc +++ b/ch03.asciidoc @@ -4,7 +4,7 @@ People only accept money in exchange for their valuable goods and services if they believe that they'll be able to spend that money later. Money that is counterfeit or unexpectedly debased may not be spendable -later, so every person accepting bitcoin has a strong incentive to +later, so every person accepting bitcoins has a strong incentive to verify the integrity of the bitcoins they receive. The Bitcoin system was designed so that it's possible for software running entirely on your local computer to perfectly prevent counterfeiting, debasement, and @@ -38,8 +38,8 @@ contribute to the code—including you! ((("bitcoin whitepaper")))((("Satoshi client")))((("reference implementation", see="Bitcoin Core")))((("Bitcoin Core", "reference implementation")))When Bitcoin was created by Satoshi Nakamoto, the -software was mostly completed before the whitepaper reproduced in -<> was published. Satoshi wanted to make sure the +software was mostly completed before publication of the whitepaper reproduced in +<>. Satoshi wanted to make sure the implementation worked before publishing a paper about it. That first implementation, then simply known as "Bitcoin", has been heavily modified and improved. It has evolved into what is known as _Bitcoin Core_, to @@ -59,7 +59,7 @@ image::images/mbc2_0301.png["Bitcoin Core Architecture"] Although Bitcoin Core serves as a reference implementation for many major parts of the system, the Bitcoin whitepaper describes several -early parts of the system and most major parts of the system since 2011 +early parts of the system. Most major parts of the system since 2011 have been documented in a set of https://github.com/bitcoin/bips/tree/master[Bitcoin Improvement Proposals] (BIPs). Throughout this book, we refer to BIP specifications @@ -83,7 +83,7 @@ next chapter, which is less technical. id="BCsource03")))((("Bitcoin Core", "compiling from source code", "downloading")))((("code examples, obtaining and using")))Bitcoin Core's source code can be downloaded as an archive or by cloning the -authoritative source repository from GitHub. ((("Bitcoin Core +source repository from GitHub. ((("Bitcoin Core downloads")))On the https://bitcoincore.org/bin/[Bitcoin Core download page], select the most recent version and download the compressed archive of the source code. ((("GitHub @@ -380,7 +380,7 @@ example, if you close Bitcoin Core for ten days, you will need to download approximately 4 GB the next time you start it. Depending on whether you choose to index all transactions and keep a -full copy of the blockchain, you may also need a lot of disk space---at +full copy of the blockchain, you may also need a lot of disk space--at least 1 TB if you plan to run Bitcoin Core for several years. By default, Bitcoin nodes also transmit transactions and blocks to other nodes (called "peers"), consuming upload internet bandwidth. If your @@ -574,7 +574,7 @@ maxmempool=150 ---- ==== -Once you've edited the configuration file and set the options that best +After you've edited the configuration file and set the options that best represent your needs, you can test +bitcoind+ with this configuration. Run Bitcoin Core with the option +printtoconsole+ to run in the foreground with output to the console: @@ -920,7 +920,7 @@ $ bitcoin-cli getblockhash 123456 ++++ -Now that we know the _header hash_ for our chosen block, we can +Now that we know the header hash for our chosen block, we can query that block. We use the +getblock+ command with the block hash as the parameter: @@ -1025,7 +1025,10 @@ any higher level Bitcoin Core RPC wrappers), as seen in <>. $ cat .bitcoin/.cookie __cookie__:17c9b71cef21b893e1a019f4bc071950c7942f49796ed061b274031b17b19cd0 -$ curl --user __cookie__:17c9b71cef21b893e1a019f4bc071950c7942f49796ed061b274031b17b19cd0 --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getblockchaininfo", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/ +$ curl \ + --user __cookie__:17c9b71cef21b893e1a019f4bc071950c7942f49796ed061b274031b17b19cd0\ + --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getblockchaininfo", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/ + {"result":{"chain":"main","blocks":799278,"headers":799278,"bestblockhash":"000000000000000000018387c50988ec705a95d6f765b206b6629971e6978879","difficulty":53911173001054.59,"time":1689703111,"mediantime":1689701260,"verificationprogress":0.9999979206082515,"initialblockdownload":false,"chainwork":"00000000000000000000000000000000000000004f3e111bf32bcb47f9dfad5b","size_on_disk":563894577967,"pruned":false,"warnings":""},"error":null,"id":"curltest"} ---- ==== diff --git a/ch04.asciidoc b/ch04.asciidoc index fa3363a9..2ca0043f 100644 --- a/ch04.asciidoc +++ b/ch04.asciidoc @@ -99,7 +99,7 @@ associated with the corresponding Bitcoin public key. The private key is used to create signatures that are used to spend bitcoin by proving control of funds used in a transaction. The private key must remain secret at all times, because revealing it to third parties is equivalent -to giving them control over the bitcoin secured by that key. The private +to giving them control over the bitcoins secured by that key. The private key must also be backed up and protected from accidental loss, because if it's lost it cannot be recovered and the funds secured by it are forever lost, too. @@ -173,7 +173,7 @@ expressed by addition and multiplication on the points of an elliptic curve. <> is an example of an elliptic curve, similar to that used -by bitcoin. +by Bitcoin. [[ecc-curve]] [role="smallerthirty"] @@ -649,7 +649,8 @@ shows the full base58 alphabet. ==== To add extra security against typos or transcription errors, base58check -uses the base58 alphabet to also include a _checksum_. The checksum is an additional four bytes +includes a _checksum_ encoded in the base58 alphabet. The checksum is an +additional four bytes added to the end of the data that is being encoded. The checksum is derived from the hash of the encoded data and can therefore be used to detect transcription and typing errors. When presented with @@ -668,10 +669,11 @@ a legacy P2PKH output script. A list of common version prefixes is shown in <>. Next, we compute the "double-SHA" checksum, meaning we apply the SHA256 -hash-algorithm twice on the previous result (prefix and data): +hash-algorithm twice on the previous result (the prefix concatenated +with the data): ---- -checksum = SHA256(SHA256(prefix+data)) +checksum = SHA256(SHA256(prefix||data)) ---- From the resulting 32-byte hash (hash-of-a-hash), we take only the first @@ -687,7 +689,7 @@ encoding process. .Base58Check encoding: a base58, versioned, and checksummed format for unambiguously encoding bitcoin data image::images/mbc2_0406.png["Base58CheckEncoding"] -In Bitcoin, other data besides public key commitmens are presented to the user in +In Bitcoin, other data besides public key commitments are presented to the user in base58check encoding to make that data compact, easy to read, and easy to detect errors. The version prefix in base58check encoding is used to create easily distinguishable formats, which when encoded in base58 contain @@ -843,7 +845,7 @@ in the output script she uses to pay him, Bob needs to communicate those constraints to her. This is similar to the problem of Bob needing to communicate his public key to her. Like that problem, where public keys can be fairly large, the constraints Bob uses can also be -quite large---potentially thousands of bytes. That's not only thousands +quite large--potentially thousands of bytes. That's not only thousands of bytes which need to be communicated to Alice, but thousands of bytes for which she needs to pay transaction fees every time she wants to spend money to Bob. However, the solution of using hash functions to create @@ -851,7 +853,7 @@ small commitments to large amounts of data also applies here. The BIP16 upgrade to the Bitcoin protocol in 2012 allows an output script to commit to a _redemption script_ (_redeem script_). When -Bob spends his bitcoins, his input script need to provide a redeem script +Bob spends his bitcoins, his input script needs to provide a redeem script that matches the commitment and also any data necessary to satisfy the redeem script (such as signatures). Let's start by imagining Bob wants to require two signatures to spend his bitcoins, one signature from his @@ -969,7 +971,7 @@ special knowledge on the part of wallet developers is to simply use a stronger hash function. Later upgrades to Bitcoin made that possible and newer Bitcoin addresses provide at least 128 bits of collision resistance. To perform 2^128^ hash operations would require all current -Bitcoin miners about 32 billion years to perform. +Bitcoin miners about 32 billion years. Although we do not believe there is any immediate threat to anyone creating new P2SH addresses, we recommend all new wallets use newer @@ -1286,7 +1288,7 @@ library for Python to quickly generate those addresses, and then take a deeper look at what's happening: ---- -wget https://raw.githubusercontent.com/sipa/bech32/master/ref/python/segwit_addr.py +$ wget https://raw.githubusercontent.com/sipa/bech32/master/ref/python/segwit_addr.py 2023-01-30 11:59:10 (46.3 MB/s) - ‘segwit_addr.py’ saved [5022/5022] $ python @@ -1317,7 +1319,7 @@ BECH32_CONSTANT = 1 BECH32M_CONSTANT = 0x2bc830a3 ---- -Next we notice the code produce the checksum. In the final step of the +Next we notice the code that produces the checksum. In the final step of the checksum, the appropriate constant is merged into the value using an xor operation. That single value is the only difference between bech32 and bech32m. @@ -1439,8 +1441,8 @@ definition, not be raw binary data. [[comp_priv]] ===== Compressed private keys -((("public and private keys", "compressed private keys")))Ironically, -the term "compressed private key" is a misnomer, because when a private +((("public and private keys", "compressed private keys"))) +the commonly used term "compressed private key" is a misnomer, because when a private key is exported as WIF-compressed it is actually one byte _longer_ than an "uncompressed" private key. That is because the private key has an added one-byte suffix (shown as 01 in hex in <>), which diff --git a/ch05.asciidoc b/ch05.asciidoc index e2621103..ae31def3 100644 --- a/ch05.asciidoc +++ b/ch05.asciidoc @@ -39,7 +39,7 @@ hardware signing devices or other wallets in a multi-signature scheme. It's possible for a wallet application to independently generate each of the wallet keys it later plans to use, as illustrated in <>. All early Bitcoin wallet applications did -this, but this required users back up the wallet database each time they +this, but it required users to back up the wallet database each time they generated and distributed new keys, which could be as often as each time they generated a new address to receive a new payment. Failure to back up the wallet database on time would lead to the user losing access to @@ -121,14 +121,15 @@ image::images/mbc2_0502.png["Deterministic Wallet"] In <>, we learned how to create a public key from a private key using Elliptic Curve Cryptography (ECC). Although operations on an elliptic curve are not intuitive, they are analogous to the addition, -subtraction, and multiplication operations we use in regular +subtraction, and multiplication operations used in regular arithmetic. In other words, it's possible to add or subtract from a -public key, or to multiply it. Consider the equation we used for +public key, or to multiply it. Consider the operation we used in +<> for generating a public key (K) from a private key (k) using the generator -point (G): +point (G). ---- -K == k * G +K = k * G ---- It's possible to create a derived keypair, called a child keypair, by @@ -138,6 +139,15 @@ simply adding the same value to both sides of the equation: K + (123 * G) == (k + 123) * G ---- +[[TIP]] +==== +In equations throughout this book, we use a single equal sign for +operations such as +K = k * G+ where the value of a variable is +calculated. We use a double equal sign to show both sides of an +equation are equivalent, or that an operation should return false (not +true) if the two sides aren't equivalent. +==== + An interesting consequence of this is that adding `123` to the public key can be done using entirely public information. For example, Alice generates public key K and gives it to Bob. Bob doesn't know the @@ -285,7 +295,7 @@ Electrum v2:: Aezeed:: Used in the LND wallet, this is another word-based recovery code that offers improvements over BIP39. It includes two version numbers: one - is internal to eliminates several issues with upgrading wallet + is internal and eliminates several issues with upgrading wallet applications (like Electrum v2's version number); the other version number is external, which can be incremented to change the underlying cryptographic properties of the recovery code. @@ -512,7 +522,7 @@ paths_. |=== The second solution is to back up the path information with the recovery -code, making it clear with path is used with which scripts. We call +code, making it clear which path is used with which scripts. We call this _explicit paths_. The advantage of implicit paths is that users don't need to keep a record @@ -533,7 +543,7 @@ For implicit path recovery codes that don't include a version number, such as BIP39 and SLIP39, a new version of a wallet application that drops support for an older path can't warn users during the restore process that some of their funds may not be found. The same problem happens in reverse if -a user enters their recovery code into older software, it won't find +a user enters their recovery code into older software: it won't find newer paths to which the user may have received funds. Recovery codes that include version information, such as Electrum v2 and Aezeed, can detect that a user is entering an older or newer recovery code and @@ -745,7 +755,7 @@ key-stretching adds some security by slowing down how fast an attacker can check different recovery code combinations. BIP39's parameters were considered weak by modern standards even when it was first published almost a decade ago, although that's likely a consequence of being -design for compatibility with hardware signing devices with low-powered +designed for compatibility with hardware signing devices with low-powered CPUs. Some alternatives to BIP39 use stronger key-stretching parameters, such as Aezeed's 32,768 rounds of hashing using the more complex Scrypt algorithm, although they may not be as convenient to run @@ -944,7 +954,7 @@ function to derive child keys from parent keys. The child key derivation functions are based on a one-way hash function that combines: -* A parent private or public key (ECDSA uncompressed key) +* A parent private or public key (uncompressed key) * A seed called a chain code (256 bits) * An index number (32 bits) @@ -1032,13 +1042,6 @@ of the branch. The extended private key can create a complete branch, whereas the extended public key can _only_ create a branch of public keys. -[TIP] -==== -An extended key consists of a private or public key and chain code. An -extended key can create children, generating its own branch in the tree -structure. Sharing an extended key gives access to the entire branch. -==== - Extended keys are encoded using Base58Check, to easily export and import between different BIP32-compatible wallets. The Base58Check coding for extended keys uses a special version number that results in @@ -1101,7 +1104,7 @@ However, it would also take a wallet application an unreasonable amount of time to generate all four billion keys and scan the blockchain for transactions involving those keys. For that reason, most wallets only generate a few keys at a time, scan for payments involving those keys, -and generate additional keys in the sequence as previous keys are used. +and generate additional keys in the sequence as the previous keys are used. For example, Alice's wallet generates 100 keys. When it sees a payment to the first key, it generates the 101st key. @@ -1195,7 +1198,8 @@ Using the HD wallet allows Gabriel to spend the funds from his personal wallet application, but the xpub loaded on the website can only generate addresses and receive funds. This feature of HD wallets is a great security feature. Gabriel's website does not contain any private -keys and therefore does not need high levels of security. +keys and therefore any hack of it can only steal the funds Gabriel would +have received in the future, not any funds he received in the past. To export the xpub from his Trezor hardware signing device, Gabriel uses the web-based Trezor wallet application. The Trezor device must be plugged in @@ -1243,7 +1247,7 @@ When the hardened private derivation function is used, the resulting child private key and chain code are completely different from what would result from the normal derivation function. The resulting "branch" of keys can be used to produce extended public keys that are not -vulnerable, because the chain code they contain cannot be exploited to +vulnerable because the chain code they contain cannot be exploited to reveal any private keys for their siblings or parents. Hardened derivation is therefore used to create a "gap" in the tree above the level where extended public keys are used. @@ -1270,7 +1274,7 @@ To make the index number easier to read and display, the index number for hardened children is displayed starting from zero, but with a prime symbol. The first normal child key is therefore displayed as 0, whereas the first hardened child (index 0x80000000) is displayed as 0++'++. -In sequence then, the second hardened key would have index 0x80000001 +In a sequence then, the second hardened key would have index 0x80000001 and would be displayed as 1++'++, and so on. When you see an HD wallet index i++'++, that means 2^31^+i. In regular ASCII text, the prime symbol is substituted with either a single apostrophe or the @@ -1341,9 +1345,8 @@ m / purpose' / coin_type' / account' / change / address_index The first-level "purpose" is always set to +44'+. The second-level "coin_type" specifies the type of cryptocurrency coin, allowing for multicurrency HD wallets where each currency has its own subtree under -the second level. There are three currencies defined for now: Bitcoin is -m/44'/0', Bitcoin Testnet is m/44++'++/1++'++, and Litecoin is -m/44++'++/2++'++. +the second level. Bitcoin is +m/44'/0' and Bitcoin Testnet is m/44++'++/1++'++. The third level of the tree is "account," which allows users to subdivide their wallets into separate logical subaccounts, for diff --git a/ch10.asciidoc b/ch10.asciidoc index 87f8487c..e2fcd508 100644 --- a/ch10.asciidoc +++ b/ch10.asciidoc @@ -298,7 +298,7 @@ criteria: - For each input, if the referenced output transaction is a coinbase output, it must have at least +COINBASE_MATURITY+ (100) confirmations. - Any absolute or relative locktime must also be satisified. Nodes may + Any absolute or relative lock time must also be satisified. Nodes may relay transactions a block before they mature since they will be mature if included in the next block. diff --git a/ch12.asciidoc b/ch12.asciidoc index 51189ead..f5fc514a 100644 --- a/ch12.asciidoc +++ b/ch12.asciidoc @@ -677,7 +677,7 @@ send her any of his signatures on the commitment transactions. That means only Fabian has both signatures for a commitment transaction, so only he can broadcast one of those commitments. When Emma finishes streaming video, Fabian will always prefer to broadcast the transaction -that pays him the most---which will be the latest state. This +that pays him the most--which will be the latest state. This construction in called a Spillman-style payment channel, which was first described and implemented in 2013, although they are only safe to use with witness (segwit) transactions, which didn't become available until diff --git a/chapters/fees.adoc b/chapters/fees.adoc index 7f6bc568..f0472f0f 100644 --- a/chapters/fees.adoc +++ b/chapters/fees.adoc @@ -44,7 +44,7 @@ specifically designed to accommodate this by providing a mechanism that allows a transaction to give money to the miner who includes that transaction in a block. We call that mechanism _transaction fees_, although it's not a fee in the usual sense of that word. It's not an -amount set by the protocol or by any particular miner---it's much more +amount set by the protocol or by any particular miner--it's much more like a bid in an auction. The good being purchased is the portion of limited space in a block that a transaction will consume. Miners choose the set of transactions whose bids will allow them to earn the greatest diff --git a/chapters/transactions.adoc b/chapters/transactions.adoc index f73fd2d6..c59f9faf 100644 --- a/chapters/transactions.adoc +++ b/chapters/transactions.adoc @@ -20,7 +20,7 @@ bitcoins. Alice pays Bob by convincing full nodes to update their database to say that some of Alice's bitcoins are now controlled by Bob. The data that Alice uses to convince full nodes to update their databases is called a _transaction_. This is done without directly -using either Alice's or Bob's identities, as well see in +using either Alice's or Bob's identities, as we'll see in <>. In this chapter we'll deconstruct a Bitcoin transaction and examine each @@ -256,8 +256,8 @@ This txid is in Bitcoin's internal byte order for hashes, see Because transactions may contain multiple outputs, Alice also needs to identify which particular output from that transaction to use, called -its _output index_. Output indices are four-byte unsigned -integers indexed from zero. +its _output index_. Output indexes are four-byte unsigned +integers starting from zero. When a full node encounters an outpoint, it uses that information to try to find the referenced output. Full nodes are only required to look at earlier @@ -440,7 +440,7 @@ alternative scenarios: it's Alice's version of the transaction that will get confirmed. This type of protocol is what we now call a _payment channel_. -Bitcoin's creator, in an email attributed to him, described these as +Bitcoin's creator, in an email attributed to him, called these high-frequency transactions and described a number of features added to the protocol to support them. We'll learn about several of those other features later and also discover how modern versions of payment channels @@ -611,7 +611,7 @@ uneconomical UTXO to ever spend it, potentially making it a perpetual burden on operators of full nodes. Because Bitcoin's decentralization depends on many people being willing to run full nodes, several full node implementations such as Bitcoin Core discourage the creation of -uneconomical outputs using policies for the relay and mining of +uneconomical outputs using policies that affect the relay and mining of unconfirmed transactions. The policies against relaying or mining transactions creating new @@ -659,7 +659,7 @@ satoshis aren't being destroyed. The output amount is followed by a compactSize integer indicating the length of the _output script_, the script that contains the conditions which will need to be fulfilled in order to spend the -bitcoins, the _spending authorization_. According to Bitcoin's +bitcoins. According to Bitcoin's consensus rules, the minimum size of an output script is zero. The consensus maximum allowed size of an outputs script varies depending on @@ -735,7 +735,7 @@ keep secret. They're able to reference that secret data using a public identifier. That public identifier is called a _public key_ and a solution to the equation is called a _signature_. -The following script contains a public key and an opcode which requires +The following script contains a public key and an opcode that requires a corresponding signature commit to the data in the spending transaction. Like the number _2_ in our simple example, the signature is our witness. @@ -755,7 +755,7 @@ problems with placing witnesses in the input script field. ==== Circular Dependencies Many contract protocols for Bitcoin involve a series of transactions -which are signed out of order. For example, Alice and Bob want to +that are signed out of order. For example, Alice and Bob want to deposit funds into a script that can only be spent with signatures from both of them, but they each also want to get their money back if the other person becomes unresponsive. A simple solution is to sign @@ -925,8 +925,7 @@ and followed by 2 to 40 bytes of data is defined as a segwit output script template. The number indicates its version (e.g. 0 is segwit version 0, or _segwit v0_). The data is called a _witness program_. It's also possible to wrap the segwit template in a P2SH -commitment, but we won't deal with that -here. +commitment, but we won't deal with that in this chapter. From the perspective of old nodes, these output script templates can be spent with an empty input script. From the perspective of a new node which diff --git a/glossary.asciidoc b/glossary.asciidoc index 3a7d4512..f608a99b 100644 --- a/glossary.asciidoc +++ b/glossary.asciidoc @@ -1,6 +1,8 @@ [preface] == Quick Glossary +//FIXME:include this? + This quick glossary contains many of the terms used in relation to bitcoin. These terms are used throughout the book, so bookmark this for a quick reference. address:: diff --git a/tools/discouraged.sh b/tools/discouraged.sh index a7081a19..ac713139 100755 --- a/tools/discouraged.sh +++ b/tools/discouraged.sh @@ -1,7 +1,7 @@ #!/bin/bash -u ## Main discouraged words -for f in $( git ls-files | grep -v "$0" ) ; do +for f in $( git ls-files -i -c -x '*.adoc' -x '*.asciidoc' | grep -v "$0" ) ; do # 1. Find discouraged words # 2. Ignore things that look like json or code (Bitcoin Core RPCs use many discouraged words) egrep -if <( sed "1,/[S]TART DISCOURAGED WORDS/d" "$0" ) "$f" \ @@ -43,3 +43,4 @@ n-of-n k-of-n blockchain.info blockchain.com +[a-zA-Z]---[a-zA-Z]