From ae52a7fc5a830864bd180043ae9c8d62b77542e2 Mon Sep 17 00:00:00 2001 From: Jesse Frush Date: Thu, 8 Apr 2021 14:25:11 -0700 Subject: [PATCH 01/14] resolved title format warning on index --- index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.rst b/index.rst index a004ea6..49dc437 100644 --- a/index.rst +++ b/index.rst @@ -1,5 +1,5 @@ Getting Started -======== +=============== The site aims to provide the information you need to understand Bitcoin and start building Bitcoin-based applications. To make the best use of From d92cd98f83b9fcc7be0c90fd98e71a08d6fbcd60 Mon Sep 17 00:00:00 2001 From: tushar-1728 Date: Fri, 18 Dec 2020 21:08:03 +0530 Subject: [PATCH 02/14] Added terms and their definitions from terms.rst to glossary.rst --- glossary.rst | 154 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 154 insertions(+) diff --git a/glossary.rst b/glossary.rst index d49ca56..3c5c281 100644 --- a/glossary.rst +++ b/glossary.rst @@ -492,4 +492,158 @@ Glossary Watch-only address An address or pubkey script stored in the wallet without the corresponding private key, allowing the wallet to watch for outputs but not spend them. + + Bitcoin URI + A URI which allows receivers to encode payment details so spenders don't have to manually enter addresses and other details. + + Certificate chain + A chain of certificates connecting a individual's leaf certificate to the certificate authority's root certificate. + + Coinbase block height + The current block's height encoded into the first bytes of the coinbase field. + + Fiat + National currencies such as the dollar or euro. + + Intermediate certificate + A intermediate certificate authority certificate which helps connect a leaf (receiver) certificate to a root certificate authority. + + Key index + An index number used in the HD wallet formula to generate child keys from a parent key. + + Key pair + A private key and its derived public key. + + Label + The label parameter of a bitcoin: URI which provides the spender with the receiver's name (unauthenticated). + + Leaf certificate + The end-node in a certificate chain; in the payment protocol, it is the certificate belonging to the receiver of satoshis. + + Merge + Spending, in the same transaction, multiple outputs which can be traced back to different previous spenders, leaking information about how many satoshis you control. + + Merge avoidance + A strategy for selecting which outputs to spend that avoids merging outputs with different histories that could leak private information. + + Message + A parameter of bitcoin: URIs which allows the receiver to optionally specify a message to the spender. + + Micropayment channel + term-micropayment-channel (contracts-guide) (`original target `__) + + .. _term-msg_block: + The block header hash data type identifier of an inventory on the P2P network. + + .. _term-msg_cmpct_block: + An alternative to the block header hash data type identifier of an inventory on the P2P network used to request a compact block. + + .. _term-msg_filtered_witness_block: + An alternative to the block header hash data type identifier of an inventory on the P2P network that is reserved for future use and unused. + + .. _term-msg_tx: + The TXID data type identifier of an inventory on the P2P network. + + .. _term-msg_witness_block: + An alternative to the block header hash data type identifier of an inventory on the P2P network used to request a block with witness serialization for SegWit. + + .. _term-msg_witness_tx: + An alternative of the transaction data type identifier of an inventory on the P2P network used to request a transaction with witness serialization for SegWit. + + OP CHECKMULTISIG + Opcode which returns true if one or more provided signatures (m) sign the correct parts of a transaction and match one or more provided public keys (n). + + .. _term-op-checksig: + Opcode which returns true if a signature signs the correct parts of a transaction and matches a provided public key. + + .. _term-op-dup: + Operation which duplicates the entry below it on the stack. + + .. _term-op-equal: + Operation which returns true if the two entries below it on the stack are equivalent. + + .. _term-op-equalverify: + Operation which terminates the script in failure unless the two entries below it on the stack are equivalent. + + .. _term-op-hash160: + Operation which converts the entry below it on the stack into a RIPEMD(SHA256()) hashed version of itself. + + .. _term-op-return: + Operation which terminates the script in failure. + + .. _term-op-verify: + Operation which terminates the script if the entry below it on the stack is non-true (zero). + + Output index + The sequentially-numbered index of outputs in a single transaction starting from 0. + + .. _term-paymentdetails: + The PaymentDetails of the payment protocol which allows the receiver to specify the payment details to the spender. + + .. _term-paymentrequest: + The PaymentRequest of the payment protocol which contains and allows signing of the PaymentDetails. + + PKI + Public Key Infrastructure; usually meant to indicate the X.509 certificate system used for HTTP Secure (https). + + Point function + The ECDSA function used to create a public key from a private key. + + PP amount + Part of the Output part of the PaymentDetails part of a payment protocol where receivers can specify the amount of satoshis they want paid to a particular pubkey script. + + PP expires + The expires field of a PaymentDetails where the receiver tells the spender when the PaymentDetails expires. + + PP memo + The memo fields of PaymentDetails, Payment, and PaymentACK which allow spenders and receivers to send each other memos. + + PP merchant data + The merchant_data part of PaymentDetails and Payment which allows the receiver to send arbitrary data to the spender in PaymentDetails and receive it back in Payments. + + PP pki data + The pki_data field of a PaymentRequest which provides details such as certificates necessary to validate the request. + + PP pki type + The PKI field of a PaymentRequest which tells spenders how to validate this request as being from a specific recipient. + + PP script + The script field of a PaymentDetails where the receiver tells the spender what pubkey scripts to pay. + + Previous block header hash + A field in the block header which contains the SHA256(SHA256()) hash of the previous block's header. + + R parameter + The payment request parameter in a bitcoin: URI. + + Receipt + A cryptographically-verifiable receipt created using parts of a payment request and a confirmed transaction. + + Root certificate + A certificate belonging to a certificate authority (CA). + + SSL signature + Signatures created and recognized by major SSL implementations such as OpenSSL. + + Stanndard block relay + The regular block relay method: announcing a block with an inv message and waiting for a response. + + Transaction version number + A version number prefixed to transactions to allow upgrading. + + Unique Address + Address which are only used once to protect privacy and increase security. + + Unsolicited block push + When a miner sends a block message without sending an inv message first. + + URI qr code + A QR code containing a bitcoin: URI. + + V2 block + The current version of Bitcoin blocks. + + x509certificates + + term-x509certificates (developer-examples) (`original target `__) From 60cc589dccb8d5bd2c8216d39797b00ed348496d Mon Sep 17 00:00:00 2001 From: Jesse Frush Date: Fri, 9 Apr 2021 11:42:22 -0700 Subject: [PATCH 03/14] fixed previous commit from tushar-1728. --- glossary.rst | 67 ++++++++++++++++++++++------------------------------ 1 file changed, 28 insertions(+), 39 deletions(-) diff --git a/glossary.rst b/glossary.rst index 3c5c281..8ab27e9 100644 --- a/glossary.rst +++ b/glossary.rst @@ -529,58 +529,55 @@ Glossary Message A parameter of bitcoin: URIs which allows the receiver to optionally specify a message to the spender. - Micropayment channel - term-micropayment-channel (contracts-guide) (`original target `__) - - .. _term-msg_block: + Msg_block The block header hash data type identifier of an inventory on the P2P network. - .. _term-msg_cmpct_block: + Msg_cmpct_block An alternative to the block header hash data type identifier of an inventory on the P2P network used to request a compact block. - .. _term-msg_filtered_witness_block: - An alternative to the block header hash data type identifier of an inventory on the P2P network that is reserved for future use and unused. + Msg_filtered_block + An alternative to the block header hash data type identifier of an inventory on the P2P network used to request a merkle block. - .. _term-msg_tx: + Msg_tx The TXID data type identifier of an inventory on the P2P network. - .. _term-msg_witness_block: + Msg_witness_block An alternative to the block header hash data type identifier of an inventory on the P2P network used to request a block with witness serialization for SegWit. - .. _term-msg_witness_tx: + Msg_witness_tx An alternative of the transaction data type identifier of an inventory on the P2P network used to request a transaction with witness serialization for SegWit. - OP CHECKMULTISIG + OP_CHECKMULTISIG Opcode which returns true if one or more provided signatures (m) sign the correct parts of a transaction and match one or more provided public keys (n). - .. _term-op-checksig: + OP_CHECKSIG Opcode which returns true if a signature signs the correct parts of a transaction and matches a provided public key. - .. _term-op-dup: + OP_DUP Operation which duplicates the entry below it on the stack. - .. _term-op-equal: + OP_EQUAL Operation which returns true if the two entries below it on the stack are equivalent. - .. _term-op-equalverify: + OP_EQUALVERIFY Operation which terminates the script in failure unless the two entries below it on the stack are equivalent. - .. _term-op-hash160: + OP_HASH160 Operation which converts the entry below it on the stack into a RIPEMD(SHA256()) hashed version of itself. - .. _term-op-return: + OP_RETURN Operation which terminates the script in failure. - .. _term-op-verify: + OP_VERIFY Operation which terminates the script if the entry below it on the stack is non-true (zero). Output index The sequentially-numbered index of outputs in a single transaction starting from 0. - .. _term-paymentdetails: + PaymentDetails The PaymentDetails of the payment protocol which allows the receiver to specify the payment details to the spender. - .. _term-paymentrequest: + PaymentRequests The PaymentRequest of the payment protocol which contains and allows signing of the PaymentDetails. PKI @@ -589,31 +586,31 @@ Glossary Point function The ECDSA function used to create a public key from a private key. - PP amount + pp amount Part of the Output part of the PaymentDetails part of a payment protocol where receivers can specify the amount of satoshis they want paid to a particular pubkey script. - PP expires + pp expires The expires field of a PaymentDetails where the receiver tells the spender when the PaymentDetails expires. - PP memo + pp memo The memo fields of PaymentDetails, Payment, and PaymentACK which allow spenders and receivers to send each other memos. - PP merchant data + pp merchant data The merchant_data part of PaymentDetails and Payment which allows the receiver to send arbitrary data to the spender in PaymentDetails and receive it back in Payments. - PP pki data + pp PKI data The pki_data field of a PaymentRequest which provides details such as certificates necessary to validate the request. - PP pki type + pp pki type The PKI field of a PaymentRequest which tells spenders how to validate this request as being from a specific recipient. - PP script + pp script The script field of a PaymentDetails where the receiver tells the spender what pubkey scripts to pay. Previous block header hash A field in the block header which contains the SHA256(SHA256()) hash of the previous block's header. - R parameter + r The payment request parameter in a bitcoin: URI. Receipt @@ -625,25 +622,17 @@ Glossary SSL signature Signatures created and recognized by major SSL implementations such as OpenSSL. - Stanndard block relay + Standard block relay The regular block relay method: announcing a block with an inv message and waiting for a response. Transaction version number A version number prefixed to transactions to allow upgrading. - Unique Address + Unique addresses Address which are only used once to protect privacy and increase security. Unsolicited block push When a miner sends a block message without sending an inv message first. - URI qr code + URI QR Code A QR code containing a bitcoin: URI. - - V2 block - The current version of Bitcoin blocks. - - x509certificates - - term-x509certificates (developer-examples) (`original target `__) - From 93df010f099793f2c3a497c034b81d5ed8419b39 Mon Sep 17 00:00:00 2001 From: Jesse Frush Date: Fri, 9 Apr 2021 12:06:38 -0700 Subject: [PATCH 04/14] moved tushar-1728's definitions into alphabetical order --- glossary.rst | 50 +++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 41 insertions(+), 9 deletions(-) diff --git a/glossary.rst b/glossary.rst index 8ab27e9..f15367a 100644 --- a/glossary.rst +++ b/glossary.rst @@ -16,6 +16,9 @@ Glossary The method used in Bitcoin for converting 160-bit hashes into P2PKH and P2SH addresses. Also used in other parts of Bitcoin, such as encoding private keys for backup in WIP format. Not the same as other base58 implementations. **Not to be confused with:** P2PKH address, P2SH address, IP address + + Bitcoin URI + A URI which allows receivers to encode payment details so spenders don't have to manually enter addresses and other details. Block One or more transactions prefaced by a block header and protected by proof of work. Blocks are the data stored on the block chain. @@ -54,6 +57,9 @@ Glossary **Not to be confused with:** Bloom filter (general computer science term, of which Bitcoin's bloom filters are a specific implementation) + Certificate chain + A chain of certificates connecting a individual's leaf certificate to the certificate authority's root certificate. + Chain code In HD wallets, 256 bits of entropy added to the public and private keys to help them generate secure child keys; the master chain code is usually derived from a seed along with the master private key @@ -75,6 +81,9 @@ Glossary **Not to be confused with:** Coinbase transaction, Coinbase.com + Coinbase block height + The current block's height encoded into the first bytes of the coinbase field. + Coinbase transaction Generation transaction The first transaction in a block. Always created by a miner, it includes a single coinbase. @@ -141,6 +150,9 @@ Glossary Private extended key In the context of HD wallets, a public key or private key extended with the chain code to allow them to derive child keys. + Fiat + National currencies such as the dollar or euro. + Fork When two or more blocks have the same block height, forking the block chain. Typically occurs when two or more miners find blocks at nearly the same time. Can also happen as part of an attack. @@ -195,6 +207,9 @@ Glossary TxIn An input in a transaction which contains three fields: an outpoint, a signature script, and a sequence number. The outpoint references a previous output and the signature script allows spending it. + Intermediate certificate + A intermediate certificate authority certificate which helps connect a leaf (receiver) certificate to a root certificate authority. + Internal byte order The standard order in which hash digests are displayed as strings---the same format used in serialized blocks and transactions. @@ -205,6 +220,18 @@ Glossary **Not to be confused with:** Inv message (one of the P2P messages that transmits inventories) + Key index + An index number used in the HD wallet formula to generate child keys from a parent key. + + Key pair + A private key and its derived public key. + + Label + The label parameter of a bitcoin: URI which provides the spender with the receiver's name (unauthenticated). + + Leaf certificate + The end-node in a certificate chain; in the payment protocol, it is the certificate belonging to the receiver of satoshis. + Locktime nLockTime Part of a transaction which indicates the earliest time or earliest block when that transaction may be added to the block chain. @@ -230,6 +257,12 @@ Glossary Master private key In HD wallets, the master chain code and master private key are the two pieces of data derived from the root seed. + Merge + Spending, in the same transaction, multiple outputs which can be traced back to different previous spenders, leaking information about how many satoshis you control. + + Merge avoidance + A strategy for selecting which outputs to spend that avoids merging outputs with different histories that could leak private information. + Merkle block A partial merkle tree connecting transactions matching a bloom filter to the merkle root of a block. @@ -245,6 +278,14 @@ Glossary **Not to be confused with:** Partial merkle branch (a branch connecting one or more leaves to the root), Merkle block (a partial merkle branch connecting one or more transactions from a single block to the block merkle root) + Micropayment channel + A two-party multisignature bitcoin address that is funded by one or both participants. A refund transaction is exchanged, but not immediately broadcasted, which can be replaced as needed to represent fund transfer without paying transaction fees. For more information, refer to the `lightning network's summary `_ + + **Not to be confused with:** Micropayment (a single transaction within a micropayment channel) + + Message + A parameter of bitcoin: URIs which allows the receiver to optionally specify a message to the spender. + Message header The four header fields prefixed to all messages on the Bitcoin P2P network. @@ -492,15 +533,6 @@ Glossary Watch-only address An address or pubkey script stored in the wallet without the corresponding private key, allowing the wallet to watch for outputs but not spend them. - - Bitcoin URI - A URI which allows receivers to encode payment details so spenders don't have to manually enter addresses and other details. - - Certificate chain - A chain of certificates connecting a individual's leaf certificate to the certificate authority's root certificate. - - Coinbase block height - The current block's height encoded into the first bytes of the coinbase field. Fiat National currencies such as the dollar or euro. From 45478bae2571ab3264a0337dfa8e8362b82d6314 Mon Sep 17 00:00:00 2001 From: Jesse Frush Date: Fri, 9 Apr 2021 12:18:38 -0700 Subject: [PATCH 05/14] improved some definitions in the glossary --- glossary.rst | 251 +++++++++++++++++++++++---------------------------- 1 file changed, 112 insertions(+), 139 deletions(-) diff --git a/glossary.rst b/glossary.rst index f15367a..dca8860 100644 --- a/glossary.rst +++ b/glossary.rst @@ -16,7 +16,7 @@ Glossary The method used in Bitcoin for converting 160-bit hashes into P2PKH and P2SH addresses. Also used in other parts of Bitcoin, such as encoding private keys for backup in WIP format. Not the same as other base58 implementations. **Not to be confused with:** P2PKH address, P2SH address, IP address - + Bitcoin URI A URI which allows receivers to encode payment details so spenders don't have to manually enter addresses and other details. @@ -151,7 +151,7 @@ Glossary In the context of HD wallets, a public key or private key extended with the chain code to allow them to derive child keys. Fiat - National currencies such as the dollar or euro. + National government-issued currencies that are not backed by a physical commodity like gold or silver. Examples include the U.S. dollar, the euro, and many other major currencies. Fork When two or more blocks have the same block height, forking the block chain. Typically occurs when two or more miners find blocks at nearly the same time. Can also happen as part of an attack. @@ -227,7 +227,7 @@ Glossary A private key and its derived public key. Label - The label parameter of a bitcoin: URI which provides the spender with the receiver's name (unauthenticated). + The optional 'label' parameter of a 'bitcoin:' URI which provides the spender with the receiver's name (unauthenticated). Leaf certificate The end-node in a certificate chain; in the payment protocol, it is the certificate belonging to the receiver of satoshis. @@ -284,7 +284,25 @@ Glossary **Not to be confused with:** Micropayment (a single transaction within a micropayment channel) Message - A parameter of bitcoin: URIs which allows the receiver to optionally specify a message to the spender. + The optional 'message' parameter of 'bitcoin:' URIs which allows the receiver to specify a message to the spender. + + Msg_block + The block header hash data type identifier of an inventory on the P2P network. + + Msg_cmpct_block + An alternative to the block header hash data type identifier of an inventory on the P2P network used to request a compact block. + + Msg_filtered_block + An alternative to the block header hash data type identifier of an inventory on the P2P network used to request a merkle block. + + Msg_tx + The TXID data type identifier of an inventory on the P2P network. + + Msg_witness_block + An alternative to the block header hash data type identifier of an inventory on the P2P network used to request a block with witness serialization for SegWit. + + Msg_witness_tx + An alternative of the transaction data type identifier of an inventory on the P2P network used to request a transaction with witness serialization for SegWit. Message header The four header fields prefixed to all messages on the Bitcoin P2P network. @@ -327,6 +345,33 @@ Glossary **Not to be confused with:** OP_RETURN (an opcode used in one of the outputs in an OP_RETURN transaction) + OP_CHECKMULTISIG + Opcode which returns true if one or more provided signatures (m) sign the correct parts of a transaction and match one or more provided public keys (n). + + OP_CHECKSIG + Opcode which returns true if a signature signs the correct parts of a transaction and matches a provided public key. + + OP_DUP + Operation which duplicates the entry below it on the stack. + + OP_EQUAL + Operation which returns true if the two entries below it on the stack are equivalent. + + OP_EQUALVERIFY + Operation which terminates the script in failure unless the two entries below it on the stack are equivalent. + + OP_HASH160 + Operation which converts the entry below it on the stack into a RIPEMD(SHA256()) hashed version of itself. + + OP_RETURN + Operation which terminates the script in failure. + + OP_VERIFY + Operation which terminates the script if the entry below it on the stack is non-true (zero). + + Output index + The sequentially-numbered index of outputs in a single transaction starting from 0. + Opcode Data-pushing opcode Non-data-pushing opcode @@ -372,17 +417,53 @@ Glossary **Not to be confused with:** Public key (derived from a private key, not a parent key) + PaymentDetails + The PaymentDetails of the payment protocol which allows the receiver to specify the payment details to the spender. + Payment protocol Payment request The deprecated protocol defined in BIP70 (and other BIPs) which lets spenders get signed payment details from receivers. **Not to be confused with:** IP-to-IP payment protocol (an insecure, discontinued protocol included in early versions of Bitcoin) + PaymentRequests + The PaymentRequest of the payment protocol which contains and allows signing of the PaymentDetails. + + PKI + Public Key Infrastructure; usually meant to indicate the X.509 certificate system used for HTTP Secure (https). + + Point function + The ECDSA function used to create a public key from a private key. + + Previous block header hash + A field in the block header which contains the SHA256(SHA256()) hash of the previous block's header. + Private key The private portion of a keypair which can create signatures that other people can verify using the public key. **Not to be confused with:** Public key (data derived from the private key), Parent key (a key used to create child keys, not necessarily a private key) + pp amount + Part of the Output part of the PaymentDetails part of a payment protocol where receivers can specify the amount of satoshis they want paid to a particular pubkey script. + + pp expires + The expires field of a PaymentDetails where the receiver tells the spender when the PaymentDetails expires. + + pp memo + The memo fields of PaymentDetails, Payment, and PaymentACK which allow spenders and receivers to send each other memos. + + pp merchant data + The merchant_data part of PaymentDetails and Payment which allows the receiver to send arbitrary data to the spender in PaymentDetails and receive it back in Payments. + + pp PKI data + The pki_data field of a PaymentRequest which provides details such as certificates necessary to validate the request. + + pp pki type + The PKI field of a PaymentRequest which tells spenders how to validate this request as being from a specific recipient. + + pp script + The script field of a PaymentDetails where the receiver tells the spender what pubkey scripts to pay. + Proof of work POW A hash below a target value which can only be obtained, on average, by performing a certain amount of brute force work---therefore demonstrating proof of work. @@ -398,6 +479,12 @@ Glossary **Not to be confused with:** Private key (data from which the public key is derived), Parent key (a key used to create child keys, not necessarily a public key) + r + The payment request parameter in a 'bitcoin:' URI. + + Receipt + A cryptographically-verifiable receipt created using parts of a payment request and a confirmed transaction. + Replace by fee RBF Opt-in replace by fee @@ -417,6 +504,9 @@ Glossary **Not to be confused with:** Testnet (a global testing environment which mostly mimics mainnet) + Root certificate + A certificate belonging to a certificate authority (CA). + RPC byte order A hash digest displayed with the byte order reversed; used in Bitcoin Core RPCs, many block explorers, and other software. @@ -476,11 +566,17 @@ Glossary **Not to be confused with:** Fork (a regular fork where all nodes follow the same consensus rules, so the fork is resolved once one chain has more proof of work than another), Hard fork (a permanent divergence in the block chain caused by non-upgraded nodes not following new consensus rules), Software fork (when one or more developers permanently develops a codebase separately from other developers), Git fork (when one or more developers temporarily develops a codebase separately from other developers + SSL signature + Signatures created and recognized by major SSL implementations such as OpenSSL. + Stale block Blocks which were successfully mined but which aren't included on the current best block chain, likely because some other block at the same height had its chain extended first. **Not to be confused with:** Orphan block (a block whose previous (parent) hash field points to an unknown block, meaning the orphan can't be validated) + Standard block relay + The regular block relay method: announcing a block with an inv message and waiting for a response. + Standard Transaction A transaction that passes Bitcoin Core's IsStandard() and IsStandardTx() tests. Only standard transactions are mined or broadcast by peers running the default Bitcoin Core software. @@ -504,6 +600,9 @@ Glossary **Not to be confused with:** Minimum relay fee (the lowest fee a transaction must pay to be accepted into the memory pool and relayed by Bitcoin Core nodes) + Transaction version number + A version number prefixed to transactions to allow upgrading. + Txid An identifier used to uniquely identify a particular transaction; specifically, the sha256d hash of the transaction. @@ -515,6 +614,15 @@ Glossary **Not to be confused with:** Miner Activated Soft Fork (a soft fork activated through miner signalling), Fork (a regular fork where all nodes follow the same consensus rules, so the fork is resolved once one chain has more proof of work than another), Hard fork (a permanent divergence in the block chain caused by non-upgraded nodes not following new consensus rules), Soft fork (a temporary divergence in the block chain caused by non-upgraded nodes not following new consensus rules), Software fork (when one or more developers permanently develops a codebase separately from other developers), Git fork (when one or more developers temporarily develops a codebase separately from other developers + Unique addresses + Address which are only used once to protect privacy and increase security. + + Unsolicited block push + When a miner sends a block message without sending an inv message first. + + URI QR Code + A QR code containing a 'bitcoin:' URI. + UTXO An Unspent Transaction Output (UTXO) that can be spent as an input in a new transaction. @@ -533,138 +641,3 @@ Glossary Watch-only address An address or pubkey script stored in the wallet without the corresponding private key, allowing the wallet to watch for outputs but not spend them. - - Fiat - National currencies such as the dollar or euro. - - Intermediate certificate - A intermediate certificate authority certificate which helps connect a leaf (receiver) certificate to a root certificate authority. - - Key index - An index number used in the HD wallet formula to generate child keys from a parent key. - - Key pair - A private key and its derived public key. - - Label - The label parameter of a bitcoin: URI which provides the spender with the receiver's name (unauthenticated). - - Leaf certificate - The end-node in a certificate chain; in the payment protocol, it is the certificate belonging to the receiver of satoshis. - - Merge - Spending, in the same transaction, multiple outputs which can be traced back to different previous spenders, leaking information about how many satoshis you control. - - Merge avoidance - A strategy for selecting which outputs to spend that avoids merging outputs with different histories that could leak private information. - - Message - A parameter of bitcoin: URIs which allows the receiver to optionally specify a message to the spender. - - Msg_block - The block header hash data type identifier of an inventory on the P2P network. - - Msg_cmpct_block - An alternative to the block header hash data type identifier of an inventory on the P2P network used to request a compact block. - - Msg_filtered_block - An alternative to the block header hash data type identifier of an inventory on the P2P network used to request a merkle block. - - Msg_tx - The TXID data type identifier of an inventory on the P2P network. - - Msg_witness_block - An alternative to the block header hash data type identifier of an inventory on the P2P network used to request a block with witness serialization for SegWit. - - Msg_witness_tx - An alternative of the transaction data type identifier of an inventory on the P2P network used to request a transaction with witness serialization for SegWit. - - OP_CHECKMULTISIG - Opcode which returns true if one or more provided signatures (m) sign the correct parts of a transaction and match one or more provided public keys (n). - - OP_CHECKSIG - Opcode which returns true if a signature signs the correct parts of a transaction and matches a provided public key. - - OP_DUP - Operation which duplicates the entry below it on the stack. - - OP_EQUAL - Operation which returns true if the two entries below it on the stack are equivalent. - - OP_EQUALVERIFY - Operation which terminates the script in failure unless the two entries below it on the stack are equivalent. - - OP_HASH160 - Operation which converts the entry below it on the stack into a RIPEMD(SHA256()) hashed version of itself. - - OP_RETURN - Operation which terminates the script in failure. - - OP_VERIFY - Operation which terminates the script if the entry below it on the stack is non-true (zero). - - Output index - The sequentially-numbered index of outputs in a single transaction starting from 0. - - PaymentDetails - The PaymentDetails of the payment protocol which allows the receiver to specify the payment details to the spender. - - PaymentRequests - The PaymentRequest of the payment protocol which contains and allows signing of the PaymentDetails. - - PKI - Public Key Infrastructure; usually meant to indicate the X.509 certificate system used for HTTP Secure (https). - - Point function - The ECDSA function used to create a public key from a private key. - - pp amount - Part of the Output part of the PaymentDetails part of a payment protocol where receivers can specify the amount of satoshis they want paid to a particular pubkey script. - - pp expires - The expires field of a PaymentDetails where the receiver tells the spender when the PaymentDetails expires. - - pp memo - The memo fields of PaymentDetails, Payment, and PaymentACK which allow spenders and receivers to send each other memos. - - pp merchant data - The merchant_data part of PaymentDetails and Payment which allows the receiver to send arbitrary data to the spender in PaymentDetails and receive it back in Payments. - - pp PKI data - The pki_data field of a PaymentRequest which provides details such as certificates necessary to validate the request. - - pp pki type - The PKI field of a PaymentRequest which tells spenders how to validate this request as being from a specific recipient. - - pp script - The script field of a PaymentDetails where the receiver tells the spender what pubkey scripts to pay. - - Previous block header hash - A field in the block header which contains the SHA256(SHA256()) hash of the previous block's header. - - r - The payment request parameter in a bitcoin: URI. - - Receipt - A cryptographically-verifiable receipt created using parts of a payment request and a confirmed transaction. - - Root certificate - A certificate belonging to a certificate authority (CA). - - SSL signature - Signatures created and recognized by major SSL implementations such as OpenSSL. - - Standard block relay - The regular block relay method: announcing a block with an inv message and waiting for a response. - - Transaction version number - A version number prefixed to transactions to allow upgrading. - - Unique addresses - Address which are only used once to protect privacy and increase security. - - Unsolicited block push - When a miner sends a block message without sending an inv message first. - - URI QR Code - A QR code containing a bitcoin: URI. From c11ccc703a51e3c078b9c2f983c2cb43e80731ec Mon Sep 17 00:00:00 2001 From: Jesse Frush Date: Fri, 9 Apr 2021 13:48:06 -0700 Subject: [PATCH 06/14] improved the definitions of some terms in the glossary and replaced all of the newly-added 'pp ____' terms with corrected term names. --- glossary.rst | 55 ++++++++++++++++++++++++++-------------------------- 1 file changed, 27 insertions(+), 28 deletions(-) diff --git a/glossary.rst b/glossary.rst index dca8860..e90ebf0 100644 --- a/glossary.rst +++ b/glossary.rst @@ -12,6 +12,9 @@ Glossary **Not to be confused with:** IP address + Amount + An optional 'amount' parameter of the :term:`PaymentRequest` where receivers can specify the amount of satoshis they want paid to a particular pubkey script. + Base58check The method used in Bitcoin for converting 160-bit hashes into P2PKH and P2SH addresses. Also used in other parts of Bitcoin, such as encoding private keys for backup in WIP format. Not the same as other base58 implementations. @@ -150,6 +153,9 @@ Glossary Private extended key In the context of HD wallets, a public key or private key extended with the chain code to allow them to derive child keys. + Expires + An optional 'expires' parameter of the :term:`PaymentRequest` which allow for control of the period in which a payment request is valid. + Fiat National government-issued currencies that are not backed by a physical commodity like gold or silver. Examples include the U.S. dollar, the euro, and many other major currencies. @@ -231,7 +237,7 @@ Glossary Leaf certificate The end-node in a certificate chain; in the payment protocol, it is the certificate belonging to the receiver of satoshis. - + Locktime nLockTime Part of a transaction which indicates the earliest time or earliest block when that transaction may be added to the block chain. @@ -283,6 +289,9 @@ Glossary **Not to be confused with:** Micropayment (a single transaction within a micropayment channel) + Memo + An optional 'memo' parameter of the :term:`PaymentDetails` which provides plaintext metadata and can be used as cryptographic proof of payment. + Message The optional 'message' parameter of 'bitcoin:' URIs which allows the receiver to specify a message to the spender. @@ -304,6 +313,9 @@ Glossary Msg_witness_tx An alternative of the transaction data type identifier of an inventory on the P2P network used to request a transaction with witness serialization for SegWit. + Merchant data + An optional 'merchant_data' parameter of :term:`PaymentDetails` which provides additional metadata for payment tracking and reference purposes. + Message header The four header fields prefixed to all messages on the Bitcoin P2P network. @@ -358,7 +370,7 @@ Glossary Operation which returns true if the two entries below it on the stack are equivalent. OP_EQUALVERIFY - Operation which terminates the script in failure unless the two entries below it on the stack are equivalent. + Operation which terminates the script in failure unless the two entries below it on the stack are equivalent. This is equivalent to OP_EQUAL followed by OP_VERIFY. OP_HASH160 Operation which converts the entry below it on the stack into a RIPEMD(SHA256()) hashed version of itself. @@ -418,20 +430,25 @@ Glossary **Not to be confused with:** Public key (derived from a private key, not a parent key) PaymentDetails - The PaymentDetails of the payment protocol which allows the receiver to specify the payment details to the spender. + Part of the payment protocol which allows the receiver to specify the payment details to the spender. Payment protocol - Payment request The deprecated protocol defined in BIP70 (and other BIPs) which lets spenders get signed payment details from receivers. - **Not to be confused with:** IP-to-IP payment protocol (an insecure, discontinued protocol included in early versions of Bitcoin) + **Not to be confused with:** IP-to-IP payment protocol (an insecure, discontinued protocol included in early versions of Bitcoin). - PaymentRequests - The PaymentRequest of the payment protocol which contains and allows signing of the PaymentDetails. + PaymentRequest + Part of the payment protocol which contain several parameters configured by the receiver as well as a nested :term:`PaymentDetails`. PKI Public Key Infrastructure; usually meant to indicate the X.509 certificate system used for HTTP Secure (https). + PKI data + A required 'pki_data' parameter of a :term:`PaymentRequest` which provides certificate information necessary to validate the request. + + PKI type + An optional 'pki_type' parameter of a :term:`PaymentRequest` which tells spenders how to validate this request as being from a specific recipient. + Point function The ECDSA function used to create a public key from a private key. @@ -443,27 +460,6 @@ Glossary **Not to be confused with:** Public key (data derived from the private key), Parent key (a key used to create child keys, not necessarily a private key) - pp amount - Part of the Output part of the PaymentDetails part of a payment protocol where receivers can specify the amount of satoshis they want paid to a particular pubkey script. - - pp expires - The expires field of a PaymentDetails where the receiver tells the spender when the PaymentDetails expires. - - pp memo - The memo fields of PaymentDetails, Payment, and PaymentACK which allow spenders and receivers to send each other memos. - - pp merchant data - The merchant_data part of PaymentDetails and Payment which allows the receiver to send arbitrary data to the spender in PaymentDetails and receive it back in Payments. - - pp PKI data - The pki_data field of a PaymentRequest which provides details such as certificates necessary to validate the request. - - pp pki type - The PKI field of a PaymentRequest which tells spenders how to validate this request as being from a specific recipient. - - pp script - The script field of a PaymentDetails where the receiver tells the spender what pubkey scripts to pay. - Proof of work POW A hash below a target value which can only be obtained, on average, by performing a certain amount of brute force work---therefore demonstrating proof of work. @@ -512,6 +508,9 @@ Glossary **Not to be confused with:** Internal byte order (hash digests displayed in their typical order; used in serialized blocks and serialized transactions) + Script + The 'script' parameter of a :term:`PaymentDetails` where the receiver tells the spender what pubkey scripts to pay. + Sequence number Part of all transactions. A number intended to allow unconfirmed time-locked transactions to be updated before being finalized; not currently used except to disable locktime in a transaction From 3e7b9d41f9272c0cd035cc2c397cd4b3e8204a18 Mon Sep 17 00:00:00 2001 From: Jesse Frush Date: Fri, 9 Apr 2021 14:11:45 -0700 Subject: [PATCH 07/14] added 'network' reference alias to a new rst_epilog field in the conf. this pattern allows for site-wide replace and reference resolution to specific pages, titles, or other named ReST items --- conf.py | 10 ++++++++++ devguide/block_chain.rst | 12 +++++++----- devguide/mining.rst | 14 +++++++------- devguide/operating_modes.rst | 8 ++++---- devguide/p2p_network.rst | 18 ++++++++++-------- devguide/payment_processing.rst | 12 ++++++------ devguide/transactions.rst | 16 ++++++++-------- devguide/wallets.rst | 6 +++--- examples/intro.rst | 2 +- examples/p2p_networking.rst | 8 ++++---- examples/payment_processing.rst | 2 +- examples/testing.rst | 2 +- examples/transactions.rst | 2 +- 13 files changed, 63 insertions(+), 49 deletions(-) diff --git a/conf.py b/conf.py index ae8f159..ab83a4d 100644 --- a/conf.py +++ b/conf.py @@ -185,3 +185,13 @@ # A list of files that should not be packed into the epub file. epub_exclude_files = ['search.html'] + +# These ReST entries are included in every doc and are used to build +# aliases to commonly-referenced items. For example, the use of +# :ref:`p2p-network-header` would produce the link text "P2P Network" +# despite general use in documentation being "network". These aliases +# improve readability and prevent unexpected content changes. +#rst_prolog = '' +rst_epilog = """ +.. |network| replace:: :ref:`network` +""" diff --git a/devguide/block_chain.rst b/devguide/block_chain.rst index 2f61466..019266b 100644 --- a/devguide/block_chain.rst +++ b/devguide/block_chain.rst @@ -1,3 +1,5 @@ +.. _block-chain-header: + Block Chain =========== @@ -6,7 +8,7 @@ The block chain provides Bitcoin's public ledger, an ordered and timestamped rec Introduction ------------ -Each full node in the Bitcoin `network <../devguide/p2p_network.html>`__ independently stores a block chain containing only blocks validated by that node. When several nodes all have the same blocks in their block chain, they are considered to be in :term:`consensus`. The validation rules these nodes follow to maintain consensus are called :term:`consensus rules`. This section describes many of the consensus rules used by Bitcoin Core. +Each full node in the Bitcoin |network| independently stores a block chain containing only blocks validated by that node. When several nodes all have the same blocks in their block chain, they are considered to be in :term:`consensus`. The validation rules these nodes follow to maintain consensus are called :term:`consensus rules`. This section describes many of the consensus rules used by Bitcoin Core. .. figure:: /img/dev/en-blockchain-overview.svg :alt: Block Chain Overview @@ -35,7 +37,7 @@ Ignoring coinbase transactions (described later), if the value of a transaction Proof Of Work ------------- -The block chain is collaboratively maintained by anonymous peers on the `network <../devguide/p2p_network.html>`__, so Bitcoin requires that each block prove a significant amount of work was invested in its creation to ensure that untrustworthy peers who want to modify past blocks have to work harder than honest peers who only want to add new blocks to the block chain. +The block chain is collaboratively maintained by anonymous peers on the |network|, so Bitcoin requires that each block prove a significant amount of work was invested in its creation to ensure that untrustworthy peers who want to modify past blocks have to work harder than honest peers who only want to add new blocks to the block chain. Chaining blocks together makes it impossible to modify transactions included in any block without modifying all subsequent blocks. As a result, the cost to modify a particular block increases with every new block added to the block chain, magnifying the effect of the proof of work. @@ -45,7 +47,7 @@ To prove you did some extra work to create a block, you must create a hash of th In the example given above, you will produce a successful hash on average every other try. You can even estimate the probability that a given hash attempt will generate a number below the :term:`target ` threshold. Bitcoin assumes a linear probability that the lower it makes the target threshold, the more hash attempts (on average) will need to be tried. -New blocks will only be added to the block chain if their hash is at least as challenging as a :term:`difficulty` value expected by the consensus protocol. Every 2,016 blocks, the `network <../devguide/p2p_network.html>`__ uses timestamps stored in each block header to calculate the number of seconds elapsed between generation of the first and last of those last 2,016 blocks. The ideal value is 1,209,600 seconds (two weeks). +New blocks will only be added to the block chain if their hash is at least as challenging as a :term:`difficulty` value expected by the consensus protocol. Every 2,016 blocks, the |network| uses timestamps stored in each block header to calculate the number of seconds elapsed between generation of the first and last of those last 2,016 blocks. The ideal value is 1,209,600 seconds (two weeks). - If it took fewer than two weeks to generate the 2,016 blocks, the expected difficulty value is increased proportionally (by as much as 300%) so that the next 2,016 blocks should take exactly two weeks to generate if hashes are checked at the same rate. @@ -53,7 +55,7 @@ New blocks will only be added to the block chain if their hash is at least as ch (Note: an off-by-one error in the Bitcoin Core implementation causes the difficulty to be updated every 2,01\ *6* blocks using timestamps from only 2,01\ *5* blocks, creating a slight skew.) -Because each block header must hash to a value below the target threshold, and because each block is linked to the block that preceded it, it requires (on average) as much hashing power to propagate a modified block as the entire Bitcoin `network <../devguide/p2p_network.html>`__ expended between the time the original block was created and the present time. Only if you acquired a majority of the `network’s <../devguide/p2p_network.html>`__ hashing power could you reliably execute such a :term:`51 percent attack` against transaction history (although, it should be noted, that even less than 50% of the hashing power still has a good chance of performing such attacks). +Because each block header must hash to a value below the target threshold, and because each block is linked to the block that preceded it, it requires (on average) as much hashing power to propagate a modified block as the entire Bitcoin |network| expended between the time the original block was created and the present time. Only if you acquired a majority of the |network|’s hashing power could you reliably execute such a :term:`51 percent attack` against transaction history (although, it should be noted, that even less than 50% of the hashing power still has a good chance of performing such attacks). The block header provides several easy-to-modify fields, such as a dedicated nonce field, so obtaining new hashes doesn’t require waiting for new transactions. Also, only the 80-byte block header is hashed for proof-of-work, so including a large volume of transaction data in a block does not slow down hashing with extra I/O, and adding additional transaction data only requires the recalculation of the ancestor hashes in the merkle tree. @@ -113,7 +115,7 @@ Note: If identical txids are found within the same block, there is a possibility Consensus Rule Changes ---------------------- -To maintain consensus, all full nodes validate blocks using the same consensus rules. However, sometimes the consensus rules are changed to introduce new features or prevent `network <../devguide/p2p_network.html>`__ abuse. When the new rules are implemented, there will likely be a period of time when non-upgraded nodes follow the old rules and upgraded nodes follow the new rules, creating two possible ways consensus can break: +To maintain consensus, all full nodes validate blocks using the same consensus rules. However, sometimes the consensus rules are changed to introduce new features or prevent |network| abuse. When the new rules are implemented, there will likely be a period of time when non-upgraded nodes follow the old rules and upgraded nodes follow the new rules, creating two possible ways consensus can break: 1. A block following the new consensus rules is accepted by upgraded nodes but rejected by non-upgraded nodes. For example, a new transaction feature is used within a block: upgraded nodes understand the feature and accept it, but non-upgraded nodes reject it because it violates the old rules. diff --git a/devguide/mining.rst b/devguide/mining.rst index b28fa47..24e577c 100644 --- a/devguide/mining.rst +++ b/devguide/mining.rst @@ -15,7 +15,7 @@ Mining today takes on two forms: Solo Mining ----------- -As illustrated below, solo miners typically use ``bitcoind`` to get new transactions from the `network <../devguide/p2p_network.html>`__. Their mining software periodically polls ``bitcoind`` for new transactions using the `“getblocktemplate” RPC <../reference/rpc/getblocktemplate.html>`__, which provides the list of new transactions plus the public key to which the coinbase transaction should be sent. +As illustrated below, solo miners typically use ``bitcoind`` to get new transactions from the |network|. Their mining software periodically polls ``bitcoind`` for new transactions using the `“getblocktemplate” RPC <../reference/rpc/getblocktemplate.html>`__, which provides the list of new transactions plus the public key to which the coinbase transaction should be sent. .. figure:: /img/dev/en-solo-mining-overview.svg :alt: Solo Bitcoin Mining @@ -26,25 +26,25 @@ The mining software constructs a block using the template (described below) and If none of the hashes are below the threshold, the mining hardware gets an updated block header with a new merkle root from the mining software; this new block header is created by adding extra nonce data to the coinbase field of the coinbase transaction. -On the other hand, if a hash is found below the target threshold, the mining hardware returns the block header with the successful nonce to the mining software. The mining software combines the header with the block and sends the completed block to ``bitcoind`` to be broadcast to the `network <../devguide/p2p_network.html>`__ for addition to the block chain. +On the other hand, if a hash is found below the target threshold, the mining hardware returns the block header with the successful nonce to the mining software. The mining software combines the header with the block and sends the completed block to ``bitcoind`` to be broadcast to the |network| for addition to the block chain. Pool Mining ----------- -Pool miners follow a similar workflow, illustrated below, which allows mining pool operators to pay miners based on their share of the work done. The mining pool gets new transactions from the `network <../devguide/p2p_network.html>`__ using ``bitcoind``. Using one of the methods discussed later, each miner’s mining software connects to the pool and requests the information it needs to construct block headers. +Pool miners follow a similar workflow, illustrated below, which allows mining pool operators to pay miners based on their share of the work done. The mining pool gets new transactions from the |network| using ``bitcoind``. Using one of the methods discussed later, each miner’s mining software connects to the pool and requests the information it needs to construct block headers. .. figure:: /img/dev/en-pooled-mining-overview.svg :alt: Pooled Bitcoin Mining Pooled Bitcoin Mining -In pooled mining, the mining pool sets the target threshold a few orders of magnitude higher (less difficult) than the `network <../devguide/p2p_network.html>`__ difficulty. This causes the mining hardware to return many block headers which don’t hash to a value eligible for inclusion on the block chain but which do hash below the pool’s target, proving (on average) that the miner checked a percentage of the possible hash values. +In pooled mining, the mining pool sets the target threshold a few orders of magnitude higher (less difficult) than the |network| difficulty. This causes the mining hardware to return many block headers which don’t hash to a value eligible for inclusion on the block chain but which do hash below the pool’s target, proving (on average) that the miner checked a percentage of the possible hash values. The miner then sends to the pool a copy of the information the pool needs to validate that the header will hash below the target and that the block of transactions referred to by the header merkle root field is valid for the pool’s purposes. (This usually means that the coinbase transaction must pay the pool.) -The information the miner sends to the pool is called a share because it proves the miner did a share of the work. By chance, some shares the pool receives will also be below the `network <../devguide/p2p_network.html>`__ target—the mining pool sends these to the `network <../devguide/p2p_network.html>`__ to be added to the block chain. +The information the miner sends to the pool is called a share because it proves the miner did a share of the work. By chance, some shares the pool receives will also be below the |network| target—the mining pool sends these to the |network| to be added to the block chain. -The block reward and transaction fees that come from mining that block are paid to the mining pool. The mining pool pays out a portion of these proceeds to individual miners based on how many shares they generated. For example, if the mining pool’s target threshold is 100 times lower than the `network <../devguide/p2p_network.html>`__ target threshold, 100 shares will need to be generated on average to create a successful block, so the mining pool can pay 1/100th of its payout for each share received. Different mining pools use different reward distribution systems based on this basic share system. +The block reward and transaction fees that come from mining that block are paid to the mining pool. The mining pool pays out a portion of these proceeds to individual miners based on how many shares they generated. For example, if the mining pool’s target threshold is 100 times lower than the |network| target threshold, 100 shares will need to be generated on average to create a successful block, so the mining pool can pay 1/100th of its payout for each share received. Different mining pools use different reward distribution systems based on this basic share system. Block Prototypes ---------------- @@ -67,7 +67,7 @@ An improved method is the Bitcoin Core `“getblocktemplate” RPC <../reference 3. Other information necessary to construct a block header for the next block: the block version, previous block hash, and bits (target). -4. The mining pool’s current target threshold for accepting shares. (For solo miners, this is the `network <../devguide/p2p_network.html>`__ target.) +4. The mining pool’s current target threshold for accepting shares. (For solo miners, this is the |network| target.) Using the transactions received, the mining software adds a nonce to the coinbase extra nonce field and then converts all the transactions into a merkle tree to derive a merkle root it can use in a block header. Whenever the extra nonce field needs to be changed, the mining software rebuilds the necessary parts of the merkle tree and updates the time and merkle root fields in the block header. diff --git a/devguide/operating_modes.rst b/devguide/operating_modes.rst index ec6eb3f..00c325b 100644 --- a/devguide/operating_modes.rst +++ b/devguide/operating_modes.rst @@ -11,9 +11,9 @@ Currently there are two primary methods of validating the block chain as a clien Full Node --------- -The first and most secure model is the one followed by Bitcoin Core, also known as a “thick” or “full chain” client. This security model assures the validity of the block chain by downloading and validating blocks from the genesis block all the way to the most recently discovered block. This is known as using the *height* of a particular block to verify the client’s view of the `network <../devguide/p2p_network.html>`__. +The first and most secure model is the one followed by Bitcoin Core, also known as a “thick” or “full chain” client. This security model assures the validity of the block chain by downloading and validating blocks from the genesis block all the way to the most recently discovered block. This is known as using the *height* of a particular block to verify the client’s view of the |network|. -For a client to be fooled, an adversary would need to give a complete alternative block chain history that is of greater difficulty than the current “true” chain, which is computationally expensive (if not impossible) due to the fact that the chain with the most cumulative proof of work is by definition the “true” chain. Due to the computational difficulty required to generate a new block at the tip of the chain, the ability to fool a full node becomes very expensive after 6 confirmations. This form of verification is highly resistent to sybil attacks—only a single honest `network <../devguide/p2p_network.html>`__ peer is required in order to receive and verify the complete state of the “true” block chain. +For a client to be fooled, an adversary would need to give a complete alternative block chain history that is of greater difficulty than the current “true” chain, which is computationally expensive (if not impossible) due to the fact that the chain with the most cumulative proof of work is by definition the “true” chain. Due to the computational difficulty required to generate a new block at the tip of the chain, the ability to fool a full node becomes very expensive after 6 confirmations. This form of verification is highly resistent to sybil attacks—only a single honest |network| peer is required in order to receive and verify the complete state of the “true” block chain. .. figure:: /img/dev/en-block-height-vs-depth.svg :alt: Block Height Compared To Block Depth @@ -34,7 +34,7 @@ Potential SPV Weaknesses If implemented naively, an SPV client has a few important weaknesses. -First, while the SPV client can not be easily fooled into thinking a transaction is in a block when it is not, the reverse is not true. A full node can simply lie by omission, leading an SPV client to believe a transaction has not occurred. This can be considered a form of Denial of Service. One mitigation strategy is to connect to a number of full nodes, and send the requests to each node. However this can be defeated by `network <../devguide/p2p_network.html>`__ partitioning or Sybil attacks, since identities are essentially free, and can be bandwidth intensive. Care must be taken to ensure the client is not cut off from honest nodes. +First, while the SPV client can not be easily fooled into thinking a transaction is in a block when it is not, the reverse is not true. A full node can simply lie by omission, leading an SPV client to believe a transaction has not occurred. This can be considered a form of Denial of Service. One mitigation strategy is to connect to a number of full nodes, and send the requests to each node. However this can be defeated by |network| partitioning or Sybil attacks, since identities are essentially free, and can be bandwidth intensive. Care must be taken to ensure the client is not cut off from honest nodes. Second, the SPV client only requests transactions from full nodes corresponding to keys it owns. If the SPV client downloads all blocks and then discards unneeded ones, this can be extremely bandwidth intensive. If they simply ask full nodes for blocks with specific transactions, this allows full nodes a complete view of the public addresses that correspond to the user. This is a large privacy leak, and allows for tactics such as denial of service for clients, users, or addresses that are disfavored by those running full nodes, as well as trivial linking of funds. A client could simply spam many fake transaction requests, but this creates a large strain on the SPV client, and can end up defeating the purpose of thin clients altogether. @@ -69,7 +69,7 @@ Bloom filters were standardized for use via `BIP37 `__. +There are future proposals such as Unspent Transaction Output (UTXO) commitments in the block chain to find a more satisfactory middle-ground for clients between needing a complete copy of the block chain, or trusting that a majority of your connected peers are not lying. UTXO commitments would enable a very secure client using a finite amount of storage using a data structure that is authenticated in the block chain. These type of proposals are, however, in very early stages, and will require soft forks in the |network|. Until these types of operating modes are implemented, modes should be chosen based on the likely threat model, computing and bandwidth constraints, and liability in bitcoin value. diff --git a/devguide/p2p_network.rst b/devguide/p2p_network.rst index 77a03a5..6a9796a 100644 --- a/devguide/p2p_network.rst +++ b/devguide/p2p_network.rst @@ -1,3 +1,5 @@ +.. _p2p-network-header: + P2P Network =========== @@ -6,7 +8,7 @@ The Bitcoin network protocol allows full nodes (peers) to collaboratively mainta Introduction ------------ -Full nodes download and verify every block and transaction prior to relaying them to other nodes. Archival nodes are full nodes which store the entire blockchain and can serve historical blocks to other nodes. Pruned nodes are full nodes which do not store the entire blockchain. Many SPV clients also use the Bitcoin `network <../devguide/p2p_network.html>`__ protocol to connect to full nodes. +Full nodes download and verify every block and transaction prior to relaying them to other nodes. Archival nodes are full nodes which store the entire blockchain and can serve historical blocks to other nodes. Pruned nodes are full nodes which do not store the entire blockchain. Many SPV clients also use the Bitcoin |network| protocol to connect to full nodes. Consensus rules do not cover networking, so Bitcoin programs may use alternative networks and protocols, such as the `high-speed block relay network `__ used by some miners and the `dedicated transaction information servers `__ used by some wallets that provide SPV-level security. @@ -28,13 +30,13 @@ When started for the first time, programs don’t know the IP addresses of any a seed.bitcoin.sipa.be. 60 IN A 203.0.113.183 [...] -The DNS seeds are maintained by Bitcoin community members: some of them provide dynamic DNS seed servers which automatically get IP addresses of active nodes by scanning the `network <../devguide/p2p_network.html>`__; others provide static DNS seeds that are updated manually and are more likely to provide IP addresses for inactive nodes. In either case, nodes are added to the DNS seed if they run on the default Bitcoin ports of 8333 for mainnet or 18333 for testnet. +The DNS seeds are maintained by Bitcoin community members: some of them provide dynamic DNS seed servers which automatically get IP addresses of active nodes by scanning the |network|; others provide static DNS seeds that are updated manually and are more likely to provide IP addresses for inactive nodes. In either case, nodes are added to the DNS seed if they run on the default Bitcoin ports of 8333 for mainnet or 18333 for testnet. -DNS seed results are not authenticated and a malicious seed operator or `network <../devguide/p2p_network.html>`__ `man-in-the-middle `__ attacker can return only IP addresses of nodes controlled by the attacker, isolating a program on the attacker’s own `network <../devguide/p2p_network.html>`__ and allowing the attacker to feed it bogus transactions and blocks. For this reason, programs should not rely on DNS seeds exclusively. +DNS seed results are not authenticated and a malicious seed operator or |network| `man-in-the-middle `__ attacker can return only IP addresses of nodes controlled by the attacker, isolating a program on the attacker’s own |network| and allowing the attacker to feed it bogus transactions and blocks. For this reason, programs should not rely on DNS seeds exclusively. -Once a program has connected to the `network <../devguide/p2p_network.html>`__, its peers can begin to send it ``addr`` (address) messages with the IP addresses and port numbers of other peers on the `network <../devguide/p2p_network.html>`__, providing a fully decentralized method of peer discovery. Bitcoin Core keeps a record of known peers in a persistent on-disk database which usually allows it to connect directly to those peers on subsequent startups without having to use DNS seeds. +Once a program has connected to the |network|, its peers can begin to send it ``addr`` (address) messages with the IP addresses and port numbers of other peers on the |network|, providing a fully decentralized method of peer discovery. Bitcoin Core keeps a record of known peers in a persistent on-disk database which usually allows it to connect directly to those peers on subsequent startups without having to use DNS seeds. -However, peers often leave the `network <../devguide/p2p_network.html>`__ or change IP addresses, so programs may need to make several different connection attempts at startup before a successful connection is made. This can add a significant delay to the amount of time it takes to connect to the `network <../devguide/p2p_network.html>`__, forcing a user to wait before sending a transaction or checking the status of payment. +However, peers often leave the |network| or change IP addresses, so programs may need to make several different connection attempts at startup before a successful connection is made. This can add a significant delay to the amount of time it takes to connect to the |network|, forcing a user to wait before sending a transaction or checking the status of payment. To avoid this possible delay, `BitcoinJ `__ always uses dynamic DNS seeds to get IP addresses for nodes believed to be currently active. Bitcoin Core also tries to strike a balance between minimizing delays and avoiding unnecessary DNS seed use: if Bitcoin Core has entries in its peer database, it spends up to 11 seconds attempting to connect to at least one of them before falling back to seeds; if a connection is made within that time, it does not query any seeds. @@ -88,7 +90,7 @@ Upon :ref:`receipt ` of the `“getblocks” message <../reference First Inv Message Sent During IBD -Inventories are unique identifiers for information on the `network <../devguide/p2p_network.html>`__. Each inventory contains a type field and the unique identifier for an instance of the object. For blocks, the unique identifier is a hash of the block’s header. +Inventories are unique identifiers for information on the |network|. Each inventory contains a type field and the unique identifier for an instance of the object. For blocks, the unique identifier is a hash of the block’s header. The block inventories appear in the `“inv” message <../reference/p2p_networking.html#inv>`__ in the same order they appear in the block chain, so this first `“inv” message <../reference/p2p_networking.html#inv>`__ contains inventories for blocks 1 through 501. (For example, the hash of block 1 is 4860…0000 as seen in the illustration above.) @@ -282,7 +284,7 @@ Memory Pool Full peers may keep track of unconfirmed transactions which are eligible to be included in the next block. This is essential for miners who will actually mine some or all of those transactions, but it’s also useful for any peer who wants to keep track of unconfirmed transactions, such as peers serving unconfirmed transaction information to SPV clients. -Because unconfirmed transactions have no permanent status in Bitcoin, Bitcoin Core stores them in non-persistent memory, calling them a memory pool or mempool. When a peer shuts down, its memory pool is lost except for any transactions stored by its wallet. This means that never-mined unconfirmed transactions tend to slowly disappear from the `network <../devguide/p2p_network.html>`__ as peers restart or as they purge some transactions to make room in memory for others. +Because unconfirmed transactions have no permanent status in Bitcoin, Bitcoin Core stores them in non-persistent memory, calling them a memory pool or mempool. When a peer shuts down, its memory pool is lost except for any transactions stored by its wallet. This means that never-mined unconfirmed transactions tend to slowly disappear from the |network| as peers restart or as they purge some transactions to make room in memory for others. Transactions which are mined into blocks that later become stale blocks may be added back into the memory pool. These re-added transactions may be re-removed from the pool almost immediately if the replacement blocks include them. This is the case in Bitcoin Core, which removes stale blocks from the chain one by one, starting with the tip (highest block). As each block is removed, its transactions are added back to the memory pool. After all of the stale blocks are removed, the replacement blocks are added to the chain one by one, ending with the new tip. As each block is added, any transactions it confirms are removed from the memory pool. @@ -298,4 +300,4 @@ Alerts *Removed in*\ `Bitcoin Core 0.13.0 `__ -Earlier versions of Bitcoin Core allowed developers and trusted community members to issue `Bitcoin alerts `__ to notify users of critical `network <../devguide/p2p_network.html>`__-wide issues. This messaging system `was retired `__ in Bitcoin Core v0.13.0; however, internal alerts, partition detection warnings and the ``-alertnotify`` option features remain. +Earlier versions of Bitcoin Core allowed developers and trusted community members to issue `Bitcoin alerts `__ to notify users of critical |network|-wide issues. This messaging system `was retired `__ in Bitcoin Core v0.13.0; however, internal alerts, partition detection warnings and the ``-alertnotify`` option features remain. diff --git a/devguide/payment_processing.rst b/devguide/payment_processing.rst index 3ed9b21..3ccfefa 100644 --- a/devguide/payment_processing.rst +++ b/devguide/payment_processing.rst @@ -192,7 +192,7 @@ That :ref:`PaymentDetails ` message is put inside a :ref:`P Bitcoin Core Showing Validated Payment Request -Charlie’s wallet receives the :ref:`PaymentRequest ` message, checks its signature, and then displays the details from the :ref:`PaymentDetails ` message to Charlie. Charlie agrees to pay, so the wallet constructs a payment to the pubkey script Bob’s server provided. Unlike a traditional Bitcoin payment, Charlie’s wallet doesn’t necessarily automatically broadcast this payment to the `network <../devguide/p2p_network.html>`__. Instead, the wallet constructs a Payment message and sends it to the URL provided in the :ref:`PaymentDetails ` message as an HTTP POST. Among other things, the Payment message contains: +Charlie’s wallet receives the :ref:`PaymentRequest ` message, checks its signature, and then displays the details from the :ref:`PaymentDetails ` message to Charlie. Charlie agrees to pay, so the wallet constructs a payment to the pubkey script Bob’s server provided. Unlike a traditional Bitcoin payment, Charlie’s wallet doesn’t necessarily automatically broadcast this payment to the |network|. Instead, the wallet constructs a Payment message and sends it to the URL provided in the :ref:`PaymentDetails ` message as an HTTP POST. Among other things, the Payment message contains: - The signed transaction in which Charlie pays Bob. @@ -200,7 +200,7 @@ Charlie’s wallet receives the :ref:`PaymentRequest ` mess - A `refund <../devguide/payment_processing.html#issuing-refunds>`__ address (pubkey script) which Bob can pay if he needs to return some or all of Charlie’s satoshis. -Bob’s server receives the Payment message, verifies the transaction pays the requested amount to the address provided, and then broadcasts the transaction to the `network <../devguide/p2p_network.html>`__. It also replies to the HTTP POSTed Payment message with a PaymentACK message, which includes an optional memo from Bob’s server thanking Charlie for his patronage and providing other information about the order, such as the expected arrival date. +Bob’s server receives the Payment message, verifies the transaction pays the requested amount to the address provided, and then broadcasts the transaction to the |network|. It also replies to the HTTP POSTed Payment message with a PaymentACK message, which includes an optional memo from Bob’s server thanking Charlie for his patronage and providing other information about the order, such as the expected arrival date. Charlie’s wallet sees the PaymentACK and tells Charlie that the payment has been sent. The PaymentACK doesn’t mean that Bob has verified Charlie’s payment—see the Verifying Payment subsection below—but it does mean that Charlie can go do something else while the transaction gets confirmed. After Bob’s server verifies from the block chain that Charlie’s transaction has been suitably confirmed, it authorizes shipping Charlie’s order. @@ -215,19 +215,19 @@ If a `refund <../devguide/payment_processing.html#issuing-refunds>`__ needs to b Verifying Payment ----------------- -As explained in the `Transactions <../devguide/transactions.html>`__ and `Block Chain <../devguide/block_chain.html>`__ sections, broadcasting a transaction to the `network <../devguide/p2p_network.html>`__ doesn’t ensure that the receiver gets paid. A malicious spender can create one transaction that pays the receiver and a second one that pays the same input back to himself. Only one of these transactions will be added to the block chain, and nobody can say for sure which one it will be. +As explained in the `Transactions <../devguide/transactions.html>`__ and `Block Chain <../devguide/block_chain.html>`__ sections, broadcasting a transaction to the |network| doesn’t ensure that the receiver gets paid. A malicious spender can create one transaction that pays the receiver and a second one that pays the same input back to himself. Only one of these transactions will be added to the block chain, and nobody can say for sure which one it will be. Two or more transactions spending the same input are commonly referred to as a :term:`double spend`. Once the transaction is included in a block, double spends are impossible without modifying block chain history to replace the transaction, which is quite difficult. Using this system, the Bitcoin protocol can give each of your transactions an updating confidence score based on the number of blocks which would need to be modified to replace a transaction. For each block, the transaction gains one :term:`confirmation `. Since modifying blocks is quite difficult, higher confirmation scores indicate greater protection. -**0 confirmations**: The transaction has been broadcast but is still not included in any block. Zero confirmation transactions (unconfirmed transactions) should generally not be trusted without risk analysis. Although miners usually confirm the first transaction they receive, fraudsters may be able to manipulate the `network <../devguide/p2p_network.html>`__ into including their version of a transaction. +**0 confirmations**: The transaction has been broadcast but is still not included in any block. Zero confirmation transactions (unconfirmed transactions) should generally not be trusted without risk analysis. Although miners usually confirm the first transaction they receive, fraudsters may be able to manipulate the |network| into including their version of a transaction. **1 confirmation**: The transaction is included in the latest block and double-spend risk decreases dramatically. Transactions which pay sufficient transaction fees need 10 minutes on average to receive one confirmation. However, the most recent block gets replaced fairly often by accident, so a double spend is still a real possibility. **2 confirmations**: The most recent block was chained to the block which includes the transaction. As of March 2014, two block replacements were exceedingly rare, and a two block replacement attack was impractical without expensive mining equipment. -**6 confirmations**: The `network <../devguide/p2p_network.html>`__ has spent about an hour working to protect the transaction against double spends and the transaction is buried under six blocks. Even a reasonably lucky attacker would require a large percentage of the total `network <../devguide/p2p_network.html>`__ hashing power to replace six blocks. Although this number is somewhat arbitrary, software handling high-value transactions, or otherwise at risk for fraud, should wait for at least six confirmations before treating a payment as accepted. +**6 confirmations**: The |network| has spent about an hour working to protect the transaction against double spends and the transaction is buried under six blocks. Even a reasonably lucky attacker would require a large percentage of the total |network| hashing power to replace six blocks. Although this number is somewhat arbitrary, software handling high-value transactions, or otherwise at risk for fraud, should wait for at least six confirmations before treating a payment as accepted. Bitcoin Core provides several `RPCs <../reference/rpc/index.html>`__ which can provide your program with the confirmation score for transactions in your wallet or arbitrary transactions. For example, the `“listunspent” RPC <../reference/rpc/listunspent.html>`__ provides an array of every satoshi you can spend along with its confirmation score. @@ -314,7 +314,7 @@ LIFO should not be used when the primary transaction recipient’s reputation mi First In, First Out (FIFO) ~~~~~~~~~~~~~~~~~~~~~~~~~~ -The oldest outputs are the most reliable, as the longer it’s been since they were received, the more blocks would need to be modified to double spend them. However, after just a few blocks, a point of rapidly diminishing returns is reached. The `original Bitcoin paper `__ predicts the chance of an attacker being able to modify old blocks, assuming the attacker has 30% of the total `network <../devguide/p2p_network.html>`__ hashing power: +The oldest outputs are the most reliable, as the longer it’s been since they were received, the more blocks would need to be modified to double spend them. However, after just a few blocks, a point of rapidly diminishing returns is reached. The `original Bitcoin paper `__ predicts the chance of an attacker being able to modify old blocks, assuming the attacker has 30% of the total |network| hashing power: ====== ================================= Blocks Chance of successful modification diff --git a/devguide/transactions.rst b/devguide/transactions.rst index 99d6f0b..b852beb 100644 --- a/devguide/transactions.rst +++ b/devguide/transactions.rst @@ -43,7 +43,7 @@ Bob provides the pubkey hash to Alice. Pubkey hashes are almost always sent enco Once Alice has the address and decodes it back into a standard hash, she can create the first transaction. She creates a standard P2PKH transaction output containing instructions which allow anyone to spend that output if they can prove they control the private key corresponding to Bob’s hashed public key. These instructions are called the :term:`pubkey script` or scriptPubKey. -Alice broadcasts the transaction and it is added to the block chain. The `network <../devguide/p2p_network.html>`__ categorizes it as an Unspent Transaction Output (UTXO), and Bob’s wallet software displays it as a spendable balance. +Alice broadcasts the transaction and it is added to the block chain. The |network| categorizes it as an Unspent Transaction Output (UTXO), and Bob’s wallet software displays it as a spendable balance. When, some time later, Bob decides to spend the UTXO, he must create an input which references the transaction Alice created by its hash, called a Transaction Identifier (txid), and the specific output she used by its index number (:ref:`output index `). He must then create a :term:`signature script`—a collection of data parameters which satisfy the conditions Alice placed in the previous output’s pubkey script. Signature scripts are also called scriptSigs. @@ -139,7 +139,7 @@ The hash of the redeem script has the same properties as a pubkey hash—so it c Standard Transactions --------------------- -After the discovery of several dangerous bugs in early versions of Bitcoin, a test was added which only accepted transactions from the `network <../devguide/p2p_network.html>`__ if their pubkey scripts and signature scripts matched a small set of believed-to-be-safe templates, and if the rest of the transaction didn’t violate another small set of rules enforcing good `network <../devguide/p2p_network.html>`__ behavior. This is the ``IsStandard()`` test, and transactions which pass it are called standard transactions. +After the discovery of several dangerous bugs in early versions of Bitcoin, a test was added which only accepted transactions from the |network| if their pubkey scripts and signature scripts matched a small set of believed-to-be-safe templates, and if the rest of the transaction didn’t violate another small set of rules enforcing good |network| behavior. This is the ``IsStandard()`` test, and transactions which pass it are called standard transactions. Non-standard transactions—those that fail the test—may be accepted by nodes not using the default Bitcoin Core settings. If they are included in blocks, they will also avoid the IsStandard test and be processed. @@ -240,9 +240,9 @@ Non-Standard Transactions If you use anything besides a standard pubkey script in an output, peers and miners using the default Bitcoin Core settings will neither accept, broadcast, nor mine your transaction. When you try to broadcast your transaction to a peer running the default settings, you will receive an error. -If you create a redeem script, hash it, and use the hash in a P2SH output, the `network <../devguide/p2p_network.html>`__ sees only the hash, so it will accept the output as valid no matter what the redeem script says. This allows payment to non-standard scripts, and as of Bitcoin Core 0.11, almost all valid redeem scripts can be spent. The exception is scripts that use unassigned `NOP opcodes `__; these opcodes are reserved for future soft forks and can only be relayed or mined by nodes that don’t follow the standard mempool policy. +If you create a redeem script, hash it, and use the hash in a P2SH output, the |network| sees only the hash, so it will accept the output as valid no matter what the redeem script says. This allows payment to non-standard scripts, and as of Bitcoin Core 0.11, almost all valid redeem scripts can be spent. The exception is scripts that use unassigned `NOP opcodes `__; these opcodes are reserved for future soft forks and can only be relayed or mined by nodes that don’t follow the standard mempool policy. -Note: standard transactions are designed to protect and help the `network <../devguide/p2p_network.html>`__, not prevent you from making mistakes. It’s easy to create standard transactions which make the satoshis sent to them unspendable. +Note: standard transactions are designed to protect and help the |network|, not prevent you from making mistakes. It’s easy to create standard transactions which make the satoshis sent to them unspendable. As of `Bitcoin Core 0.9.3 `__, standard transactions must also meet the following conditions: @@ -294,7 +294,7 @@ Care must be taken near the expiry time of a time lock. The `peer-to-peer networ Previous versions of Bitcoin Core provided a feature which prevented transaction signers from using the method described above to cancel a time-locked transaction, but a necessary part of this feature was disabled to prevent denial of service attacks. A legacy of this system are four-byte :term:`sequence numbers ` in every input. Sequence numbers were meant to allow multiple signers to agree to update a transaction; when they finished updating the transaction, they could agree to set every input’s sequence number to the four-byte unsigned maximum (0xffffffff), allowing the transaction to be added to a block even if its time lock had not expired. -Even today, setting all sequence numbers to 0xffffffff (the default in Bitcoin Core) can still disable the time lock, so if you want to use locktime, at least one input must have a sequence number below the maximum. Since sequence numbers are not used by the `network <../devguide/p2p_network.html>`__ for any other purpose, setting any sequence number to zero is sufficient to enable locktime. +Even today, setting all sequence numbers to 0xffffffff (the default in Bitcoin Core) can still disable the time lock, so if you want to use locktime, at least one input must have a sequence number below the maximum. Since sequence numbers are not used by the |network| for any other purpose, setting any sequence number to zero is sufficient to enable locktime. Locktime itself is an unsigned 4-byte integer which can be parsed two ways: @@ -311,7 +311,7 @@ There is also a concept of so-called “:term:`high-priority transactions ` (currently 1,000 satoshis) has been required to broadcast a transaction across the `network <../devguide/p2p_network.html>`__. Any transaction paying only the minimum fee should be prepared to wait a long time before there’s enough spare space in a block to include it. Please see the `verifying payment section <../devguide/payment_processing.html#verifying-payment>`__ for why this could be important. +As of Bitcoin Core 0.9, a :term:`minimum fee ` (currently 1,000 satoshis) has been required to broadcast a transaction across the |network|. Any transaction paying only the minimum fee should be prepared to wait a long time before there’s enough spare space in a block to include it. Please see the `verifying payment section <../devguide/payment_processing.html#verifying-payment>`__ for why this could be important. Since each transaction spends Unspent Transaction Outputs (UTXOs) and because a UTXO can only be spent once, the full value of the included UTXOs must be spent or given to a miner as a transaction fee. Few people will have UTXOs that exactly match the amount they want to pay, so most transactions include a change output. @@ -347,8 +347,8 @@ This isn’t a problem for most Bitcoin transactions which are designed to be ad Bitcoin developers have been working to reduce transaction malleability among standard transaction types, one outcome of those efforts is `BIP 141: Segregated Witness `__, which is supported by Bitcoin Core and was activated in August 2017. When SegWit is not being used, new transactions should not depend on previous transactions which have not been added to the block chain yet, especially if large amounts of satoshis are at stake. -Transaction malleability also affects payment tracking. Bitcoin Core’s `RPC <../reference/rpc/index.html>`__ interface lets you track transactions by their txid—but if that txid changes because the transaction was modified, it may appear that the transaction has disappeared from the `network <../devguide/p2p_network.html>`__. +Transaction malleability also affects payment tracking. Bitcoin Core’s `RPC <../reference/rpc/index.html>`__ interface lets you track transactions by their txid—but if that txid changes because the transaction was modified, it may appear that the transaction has disappeared from the |network|. Current best practices for transaction tracking dictate that a transaction should be tracked by the transaction outputs (UTXOs) it spends as inputs, as they cannot be changed without invalidating the transaction. -Best practices further dictate that if a transaction does seem to disappear from the `network <../devguide/p2p_network.html>`__ and needs to be reissued, that it be reissued in a way that invalidates the lost transaction. One method which will always work is to ensure the reissued payment spends all of the same outputs that the lost transaction used as inputs. +Best practices further dictate that if a transaction does seem to disappear from the |network| and needs to be reissued, that it be reissued in a way that invalidates the lost transaction. One method which will always work is to ensure the reissued payment spends all of the same outputs that the lost transaction used as inputs. diff --git a/devguide/wallets.rst b/devguide/wallets.rst index c8d8e58..8c5d360 100644 --- a/devguide/wallets.rst +++ b/devguide/wallets.rst @@ -68,9 +68,9 @@ Offline Wallets Several full-service wallets programs will also operate as two separate wallets: one program instance acting as a signing-only wallet (often called an “offline wallet”) and the other program instance acting as the networked wallet (often called an “online wallet” or “watching-only wallet”). -The offline wallet is so named because it is intended to be run on a device which does not connect to any `network <../devguide/p2p_network.html>`__, greatly reducing the number of attack vectors. If this is the case, it is usually up to the user to handle all data transfer using removable media such as USB drives. The user’s workflow is something like: +The offline wallet is so named because it is intended to be run on a device which does not connect to any |network|, greatly reducing the number of attack vectors. If this is the case, it is usually up to the user to handle all data transfer using removable media such as USB drives. The user’s workflow is something like: -1. (Offline) Disable all `network <../devguide/p2p_network.html>`__ connections on a device and install the wallet software. Start the wallet software in offline mode to create the parent private and public keys. Copy the parent public key to removable media. +1. (Offline) Disable all |network| connections on a device and install the wallet software. Start the wallet software in offline mode to create the parent private and public keys. Copy the parent public key to removable media. 2. (Online) Install the wallet software on another device, this one connected to the Internet, and import the parent public key from the removable media. As you would with a full-service wallet, distribute public keys to receive payment. When ready to spend satoshis, fill in the output details and save the unsigned transaction generated by the wallet to removable media. @@ -93,7 +93,7 @@ Hardware wallets are devices dedicated to running a signing-only wallet. Their d 3. (Hardware) Review the transaction details on the hardware wallet’s screen. Some hardware wallets may prompt for a passphrase or PIN number. The hardware wallet signs the transaction and uploads it to the networked wallet. -4. (Networked) The networked wallet receives the signed transaction from the hardware wallet and broadcasts it to the `network <../devguide/p2p_network.html>`__. +4. (Networked) The networked wallet receives the signed transaction from the hardware wallet and broadcasts it to the |network|. The primary advantage of hardware wallets is their possibility for greatly improved security over full-service wallets with much less hassle than offline wallets. diff --git a/examples/intro.rst b/examples/intro.rst index 0e7c8ba..eb16752 100644 --- a/examples/intro.rst +++ b/examples/intro.rst @@ -31,7 +31,7 @@ You should also make the ``bitcoin.conf`` file only readable to its owner. On Li chmod 0600 bitcoin.conf -For development, it’s safer and cheaper to use Bitcoin’s test `network <../devguide/p2p_network.html>`__ (testnet) or regression test mode (regtest) described below. +For development, it’s safer and cheaper to use Bitcoin’s test |network| (testnet) or regression test mode (regtest) described below. Questions about Bitcoin use are best sent to the `BitcoinTalk forum `__ and `IRC channels `__. Errors or suggestions related to documentation on Bitcoin.org can be `submitted as an issue `__ or posted to the `bitcoin-documentation mailing list `__. diff --git a/examples/p2p_networking.rst b/examples/p2p_networking.rst index 481bb4e..aa4e791 100644 --- a/examples/p2p_networking.rst +++ b/examples/p2p_networking.rst @@ -203,7 +203,7 @@ Testing the filter against an arbitrary element, we get the failure output below Retrieving A MerkleBlock ~~~~~~~~~~~~~~~~~~~~~~~~ -For the `“merkleblock” message <../reference/p2p_networking.html#merkleblock>`__ documentation on the reference page, an actual merkle block was retrieved from the `network <../devguide/p2p_network.html>`__ and manually processed. This section walks through each step of the process, demonstrating basic `network <../devguide/p2p_network.html>`__ communication and merkle block processing. +For the `“merkleblock” message <../reference/p2p_networking.html#merkleblock>`__ documentation on the reference page, an actual merkle block was retrieved from the |network| and manually processed. This section walks through each step of the process, demonstrating basic |network| communication and merkle block processing. .. highlight:: python @@ -238,7 +238,7 @@ For the `“merkleblock” message <../reference/p2p_networking.html#merkleblock ) sys.stdout.flush() -To connect to the P2P `network <../devguide/p2p_network.html>`__, the trivial Python function above was developed to compute message headers and send payloads decoded from hex. +To connect to the P2P |network|, the trivial Python function above was developed to compute message headers and send payloads decoded from hex. .. highlight:: python @@ -261,7 +261,7 @@ To connect to the P2P `network <../devguide/p2p_network.html>`__, the trivial Py + "00" # .............................. Relay transactions: false ) -Peers on the `network <../devguide/p2p_network.html>`__ will not accept any requests until you send them a `“version” message <../reference/p2p_networking.html#version>`__. The receiving node will reply with their `“version” message <../reference/p2p_networking.html#version>`__ and a `“verack” message <../reference/p2p_networking.html#verack>`__. +Peers on the |network| will not accept any requests until you send them a `“version” message <../reference/p2p_networking.html#version>`__. The receiving node will reply with their `“version” message <../reference/p2p_networking.html#version>`__ and a `“verack” message <../reference/p2p_networking.html#verack>`__. .. highlight:: python @@ -313,7 +313,7 @@ Part of the response is shown in the section below. Parsing A MerkleBlock ~~~~~~~~~~~~~~~~~~~~~ -In the section above, we retrieved a merkle block from the `network <../devguide/p2p_network.html>`__; now we will parse it. Most of the block header has been omitted. For a more complete hexdump, see the example in the ```merkleblock`` message section <../reference/p2p_networking.html#merkleblock>`__. +In the section above, we retrieved a merkle block from the |network|; now we will parse it. Most of the block header has been omitted. For a more complete hexdump, see the example in the ```merkleblock`` message section <../reference/p2p_networking.html#merkleblock>`__. .. highlight:: text diff --git a/examples/payment_processing.rst b/examples/payment_processing.rst index 48d3e13..0c5d806 100644 --- a/examples/payment_processing.rst +++ b/examples/payment_processing.rst @@ -112,7 +112,7 @@ Each wallet program may choose which certificate authorities to trust, but it’ details.[network][network] = "test" ## Default: main -``network``: (optional) tell the spender’s wallet program what Bitcoin `network <../devguide/p2p_network.html>`__ you’re using; `BIP70 `__ defines “main” for mainnet (actual payments) and “test” for testnet (like mainnet, but fake satoshis are used). If the wallet program doesn’t run on the `network <../devguide/p2p_network.html>`__ you indicate, it will reject the :ref:`PaymentRequest `. +``network``: (optional) tell the spender’s wallet program what Bitcoin |network| you’re using; `BIP70 `__ defines “main” for mainnet (actual payments) and “test” for testnet (like mainnet, but fake satoshis are used). If the wallet program doesn’t run on the |network| you indicate, it will reject the :ref:`PaymentRequest `. .. highlight:: python diff --git a/examples/testing.rst b/examples/testing.rst index 430b7d4..4437ffa 100644 --- a/examples/testing.rst +++ b/examples/testing.rst @@ -6,7 +6,7 @@ Bitcoin Core provides testing tools designed to let developers test their applic Testnet ~~~~~~~ -When run with no arguments, all Bitcoin Core programs default to Bitcoin’s main `network <../devguide/p2p_network.html>`__ (:term:`mainnet`). However, for development, it’s safer and cheaper to use Bitcoin’s test `network <../devguide/p2p_network.html>`__ (testnet) where the satoshis spent have no real-world value. Testnet also relaxes some restrictions (such as standard transaction checks) so you can test functions which might currently be disabled by default on mainnet. +When run with no arguments, all Bitcoin Core programs default to Bitcoin’s main |network| (:term:`mainnet`). However, for development, it’s safer and cheaper to use Bitcoin’s test |network| (testnet) where the satoshis spent have no real-world value. Testnet also relaxes some restrictions (such as standard transaction checks) so you can test functions which might currently be disabled by default on mainnet. To use testnet, use the argument ``-testnet`` with ``bitcoin-cli``, ``bitcoind`` or ``bitcoin-qt`` or add ``testnet=1`` to your ``bitcoin.conf`` file as `described earlier <../examples/index.html>`__. To get free satoshis for testing, use `Piotr Piasecki’s testnet faucet `__. Testnet is a public resource provided for free by members of the community, so please don’t abuse it. diff --git a/examples/transactions.rst b/examples/transactions.rst index 3a8b40b..6d7723a 100644 --- a/examples/transactions.rst +++ b/examples/transactions.rst @@ -288,7 +288,7 @@ Use the `“decoderawtransaction” RPC <../reference/rpc/decoderawtransaction.h Use the ``signrawtransaction`` `RPC <../reference/rpc/index.html>`__ to sign the transaction created by `“createrawtransaction” <../reference/rpc/createrawtransaction.html>`__ and save the returned “hex” raw format signed transaction to a shell variable. -Even though the transaction is now complete, the Bitcoin Core node we’re connected to doesn’t know anything about the transaction, nor does any other part of the `network <../devguide/p2p_network.html>`__. We’ve created a spend, but we haven’t actually spent anything because we could simply unset the ``$SIGNED_RAW_TX`` variable to eliminate the transaction. +Even though the transaction is now complete, the Bitcoin Core node we’re connected to doesn’t know anything about the transaction, nor does any other part of the |network|. We’ve created a spend, but we haven’t actually spent anything because we could simply unset the ``$SIGNED_RAW_TX`` variable to eliminate the transaction. .. highlight:: bash From c5f9bf8af8ae9fca0ae2d6e451c92d546a30d0a3 Mon Sep 17 00:00:00 2001 From: Jesse Frush Date: Mon, 12 Apr 2021 09:30:24 -0700 Subject: [PATCH 08/14] removed reduntant term links --- devguide/block_chain.rst | 32 ++++++++++++++++++-------------- devguide/contracts.rst | 4 ++-- devguide/p2p_network.rst | 2 +- devguide/payment_processing.rst | 4 ++-- devguide/transactions.rst | 20 ++++++++++---------- devguide/wallets.rst | 14 +++++++------- examples/testing.rst | 2 +- reference/p2p_networking.rst | 4 ++-- reference/transactions.rst | 2 +- 9 files changed, 44 insertions(+), 40 deletions(-) diff --git a/devguide/block_chain.rst b/devguide/block_chain.rst index cf7b62a..472b7df 100644 --- a/devguide/block_chain.rst +++ b/devguide/block_chain.rst @@ -8,14 +8,14 @@ The block chain provides Bitcoin's public ledger, an ordered and timestamped rec Introduction ------------ -Each full node in the Bitcoin |network| independently stores a block chain containing only blocks validated by that node. When several nodes all have the same blocks in their block chain, they are considered to be in :term:`consensus`. The validation rules these nodes follow to maintain consensus are called :term:`consensus rules `. This section describes many of the consensus rules used by Bitcoin Core. +Each full node in the Bitcoin |network| independently stores a block chain containing only blocks validated by that node. When several nodes all have the same blocks in their block chain, they are considered to be in :term:`consensus`. The validation rules these nodes follow to maintain consensus are called :term:`consensus rules`. This section describes many of the consensus rules used by Bitcoin Core. .. figure:: /img/dev/en-blockchain-overview.svg :alt: Block Chain Overview Block Chain Overview -The illustration above shows a simplified version of a block chain. A :term:`block ` of one or more new transactions is collected into the transaction data part of a block. Copies of each transaction are hashed, and the hashes are then paired, hashed, paired again, and hashed again until a single hash remains, the :term:`merkle root ` of a merkle tree. +The illustration above shows a simplified version of a block chain. A :term:`block` of one or more new transactions is collected into the transaction data part of a block. Copies of each transaction are hashed, and the hashes are then paired, hashed, paired again, and hashed again until a single hash remains, the :term:`merkle root` of a merkle tree. The merkle root is stored in the block header. Each block also stores the hash of the previous block’s header, chaining the blocks together. This ensures a transaction cannot be modified without modifying the block that records it and all following blocks. @@ -32,7 +32,7 @@ Outputs are tied to :term:`transaction identifiers (TXIDs) `, which are th Because each output of a particular transaction can only be spent once, the outputs of all transactions included in the block chain can be categorized as either :term:`Unspent Transaction Outputs (UTXOs) ` or spent transaction outputs. For a payment to be valid, it must only use UTXOs as inputs. -Ignoring coinbase transactions (described later), if the value of a transaction’s outputs exceed its inputs, the transaction will be rejected—but if the inputs exceed the value of the outputs, any difference in value may be claimed as a :term:`transaction fee ` by the Bitcoin :term:`miner ` who creates the block containing that transaction. For example, in the illustration above, each transaction spends 10,000 satoshis fewer than it receives from its combined inputs, effectively paying a 10,000 satoshi transaction fee. +Ignoring coinbase transactions (described later), if the value of a transaction’s outputs exceed its inputs, the transaction will be rejected—but if the inputs exceed the value of the outputs, any difference in value may be claimed as a :term:`transaction fee` by the Bitcoin :term:`miner` who creates the block containing that transaction. For example, in the illustration above, each transaction spends 10,000 satoshis fewer than it receives from its combined inputs, effectively paying a 10,000 satoshi transaction fee. Proof Of Work ------------- @@ -41,13 +41,13 @@ The block chain is collaboratively maintained by anonymous peers on the |network Chaining blocks together makes it impossible to modify transactions included in any block without modifying all subsequent blocks. As a result, the cost to modify a particular block increases with every new block added to the block chain, magnifying the effect of the proof of work. -The :term:`proof of work ` used in Bitcoin takes advantage of the apparently random nature of cryptographic hashes. A good cryptographic hash algorithm converts arbitrary data into a seemingly random number. If the data is modified in any way and the hash re-run, a new seemingly random number is produced, so there is no way to modify the data to make the hash number predictable. +The :term:`proof of work` used in Bitcoin takes advantage of the apparently random nature of cryptographic hashes. A good cryptographic hash algorithm converts arbitrary data into a seemingly random number. If the data is modified in any way and the hash re-run, a new seemingly random number is produced, so there is no way to modify the data to make the hash number predictable. To prove you did some extra work to create a block, you must create a hash of the block header which does not exceed a certain value. For example, if the maximum possible hash value is 2256 − 1, you can prove that you tried up to two combinations by producing a hash value less than 2255. In the example given above, you will produce a successful hash on average every other try. You can even estimate the probability that a given hash attempt will generate a number below the :term:`target ` threshold. Bitcoin assumes a linear probability that the lower it makes the target threshold, the more hash attempts (on average) will need to be tried. -New blocks will only be added to the block chain if their hash is at least as challenging as a :term:`difficulty ` value expected by the consensus protocol. Every 2,016 blocks, the |network| uses timestamps stored in each block header to calculate the number of seconds elapsed between generation of the first and last of those last 2,016 blocks. The ideal value is 1,209,600 seconds (two weeks). +New blocks will only be added to the block chain if their hash is at least as challenging as a :term:`difficulty` value expected by the consensus protocol. Every 2,016 blocks, the |network| uses timestamps stored in each block header to calculate the number of seconds elapsed between generation of the first and last of those last 2,016 blocks. The ideal value is 1,209,600 seconds (two weeks). - If it took fewer than two weeks to generate the 2,016 blocks, the expected difficulty value is increased proportionally (by as much as 300%) so that the next 2,016 blocks should take exactly two weeks to generate if hashes are checked at the same rate. @@ -62,18 +62,18 @@ The block header provides several easy-to-modify fields, such as a dedicated non Block Height And Forking ------------------------ -Any Bitcoin miner who successfully hashes a block header to a value below the target threshold can add the entire block to the block chain (assuming the block is otherwise valid). These blocks are commonly addressed by their :term:`block height `—the number of blocks between them and the first Bitcoin block (block 0, most commonly known as the :term:`genesis block `). For example, block 2016 is where difficulty could have first been adjusted. +Any Bitcoin miner who successfully hashes a block header to a value below the target threshold can add the entire block to the block chain (assuming the block is otherwise valid). These blocks are commonly addressed by their :term:`block height`—the number of blocks between them and the first Bitcoin block (block 0, most commonly known as the :term:`genesis block`). For example, block 2016 is where difficulty could have first been adjusted. .. figure:: /img/dev/en-blockchain-fork.svg :alt: Common And Uncommon Block Chain Forks Common And Uncommon Block Chain Forks -Multiple blocks can all have the same block height, as is common when two or more miners each produce a block at roughly the same time. This creates an apparent :term:`fork ` in the block chain, as shown in the illustration above. +Multiple blocks can all have the same block height, as is common when two or more miners each produce a block at roughly the same time. This creates an apparent :term:`fork` in the block chain, as shown in the illustration above. When miners produce simultaneous blocks at the end of the block chain, each node individually chooses which block to accept. In the absence of other considerations, discussed below, nodes usually use the first block they see. -Eventually a miner produces another block which attaches to only one of the competing simultaneously-mined blocks. This makes that side of the fork stronger than the other side. Assuming a fork only contains valid blocks, normal peers always follow the most difficult chain to recreate and throw away :term:`stale blocks ` belonging to shorter forks. (Stale blocks are also sometimes called orphans or orphan blocks, but those terms are also used for true orphan blocks without a known parent block.) +Eventually a miner produces another block which attaches to only one of the competing simultaneously-mined blocks. This makes that side of the fork stronger than the other side. Assuming a fork only contains valid blocks, normal peers always follow the most difficult chain to recreate and throw away |stale blocks| belonging to shorter forks. (|stale blocks| are also sometimes called orphans or |orphan blocks|, but those terms are also used for true |orphan blocks| without a known parent block.) Long-term forks are possible if different miners work at cross-purposes, such as some miners diligently working to extend the block chain at the same time other miners are attempting a 51 percent attack to revise transaction history. @@ -90,7 +90,7 @@ Blocks are not required to include any non-coinbase transactions, but miners alm All transactions, including the coinbase transaction, are encoded into blocks in binary raw transaction format. -The raw transaction format is hashed to create the transaction identifier (txid). From these txids, the :term:`merkle tree ` is constructed by pairing each txid with one other txid and then hashing them together. If there are an odd number of txids, the txid without a partner is hashed with a copy of itself. +The raw transaction format is hashed to create the transaction identifier (txid). From these txids, the :term:`merkle tree` is constructed by pairing each txid with one other txid and then hashing them together. If there are an odd number of txids, the txid without a partner is hashed with a copy of itself. The resulting hashes themselves are each paired with one other hash and hashed together. Any hash without a partner is hashed with itself. The process repeats until only one hash remains, the merkle root. @@ -121,14 +121,14 @@ To maintain consensus, all full nodes validate blocks using the same consensus r 2. A block violating the new consensus rules is rejected by upgraded nodes but accepted by non-upgraded nodes. For example, an abusive transaction feature is used within a block: upgraded nodes reject it because it violates the new rules, but non-upgraded nodes accept it because it follows the old rules. -In the first case, rejection by non-upgraded nodes, mining software which gets block chain data from those non-upgraded nodes refuses to build on the same chain as mining software getting data from upgraded nodes. This creates permanently divergent chains—one for non-upgraded nodes and one for upgraded nodes—called a :term:`hard fork `. +In the first case, rejection by non-upgraded nodes, mining software which gets block chain data from those non-upgraded nodes refuses to build on the same chain as mining software getting data from upgraded nodes. This creates permanently divergent chains—one for non-upgraded nodes and one for upgraded nodes—called a :term:`hard fork`. .. figure:: /img/dev/en-hard-fork.svg :alt: Hard Fork Hard Fork -In the second case, rejection by upgraded nodes, it’s possible to keep the block chain from permanently diverging if upgraded nodes control a majority of the hash rate. That’s because, in this case, non-upgraded nodes will accept as valid all the same blocks as upgraded nodes, so the upgraded nodes can build a stronger chain that the non-upgraded nodes will accept as the best valid block chain. This is called a :term:`soft fork `. +In the second case, rejection by upgraded nodes, it’s possible to keep the block chain from permanently diverging if upgraded nodes control a majority of the hash rate. That’s because, in this case, non-upgraded nodes will accept as valid all the same blocks as upgraded nodes, so the upgraded nodes can build a stronger chain that the non-upgraded nodes will accept as the best valid block chain. This is called a :term:`soft fork`. .. figure:: /img/dev/en-soft-fork.svg :alt: Soft Fork @@ -137,9 +137,9 @@ In the second case, rejection by upgraded nodes, it’s possible to keep the blo Although a fork is an actual divergence in block chains, changes to the consensus rules are often described by their potential to create either a hard or soft fork. For example, “increasing the block size above 1 MB requires a hard fork.” In this example, an actual block chain fork is not required—but it is a possible outcome. -Consensus rule changes may be activated in various ways. During Bitcoin’s first two years, Satoshi Nakamoto performed several soft forks by just releasing the backwards-compatible change in a client that began immediately enforcing the new rule. Multiple soft forks such as `BIP30 `__ have been activated via a flag day where the new rule began to be enforced at a preset time or block height. Such forks activated via a flag day are known as :term:`User Activated Soft Forks ` (UASF) as they are dependent on having sufficient users (nodes) to enforce the new rules after the flag day. +Consensus rule changes may be activated in various ways. During Bitcoin’s first two years, Satoshi Nakamoto performed several soft forks by just releasing the backwards-compatible change in a client that began immediately enforcing the new rule. Multiple soft forks such as `BIP30 `__ have been activated via a flag day where the new rule began to be enforced at a preset time or block height. Such forks activated via a flag day are known as :term:`User-Activated Soft Forks ` (UASF) as they are dependent on having sufficient users (nodes) to enforce the new rules after the flag day. -Later soft forks waited for a majority of hash rate (typically 75% or 95%) to signal their readiness for enforcing the new consensus rules. Once the signalling threshold has been passed, all nodes will begin enforcing the new rules. Such forks are known as :term:`Miner Activated Soft Forks ` (MASF) as they are dependent on miners for activation. +Later soft forks waited for a majority of hash rate (typically 75% or 95%) to signal their readiness for enforcing the new consensus rules. Once the signalling threshold has been passed, all nodes will begin enforcing the new rules. Such forks are known as :term:`Miner-Activated Soft Forks ` (MASF) as they are dependent on miners for activation. **Resources:** `BIP16 `__, `BIP30 `__, and `BIP34 `__ were implemented as changes which might have lead to soft forks. `BIP50 `__ describes both an accidental hard fork, resolved by temporary downgrading the capabilities of upgraded nodes, and an intentional hard fork when the temporary downgrade was removed. A document from Gavin Andresen outlines `how future rule changes may be implemented `__. @@ -154,6 +154,10 @@ Full nodes can also check block and transaction version numbers. If the block or In either case, block and transaction data should not be relied upon if it comes from a node that apparently isn’t using the current consensus rules. -SPV clients which connect to full nodes can detect a likely hard fork by connecting to several full nodes and ensuring that they’re all on the same chain with the same block height, plus or minus several blocks to account for transmission delays and stale blocks. If there’s a divergence, the client can disconnect from nodes with weaker chains. +SPV clients which connect to full nodes can detect a likely hard fork by connecting to several full nodes and ensuring that they’re all on the same chain with the same block height, plus or minus several blocks to account for transmission delays and |stale blocks| +. If there’s a divergence, the client can disconnect from nodes with weaker chains. SPV clients should also monitor for block and :ref:`transaction version number ` increases to ensure they process received transactions and create new transactions using the current consensus rules. + +.. |stale blocks| replace:: :term:`stale blocks ` +.. |orphan blocks| replace:: :term:`orphan blocks ` \ No newline at end of file diff --git a/devguide/contracts.rst b/devguide/contracts.rst index 77832b4..9af6ff4 100644 --- a/devguide/contracts.rst +++ b/devguide/contracts.rst @@ -17,9 +17,9 @@ Charlie-the-customer wants to buy a product from Bob-the-businessman, but neithe A simple contract could say that Charlie will spend satoshis to an output which can only be spent if Charlie and Bob both sign the input spending it. That means Bob won’t get paid unless Charlie gets his merchandise, but Charlie can’t get the merchandise and keep his payment. -This simple contract isn’t much help if there’s a dispute, so Bob and Charlie enlist the help of Alice-the-arbitrator to create an :term:`escrow contract `. Charlie spends his satoshis to an output which can only be spent if two of the three people sign the input. Now Charlie can pay Bob if everything is ok, Bob can `refund <../devguide/payment_processing.html#issuing-refunds>`__ Charlie’s money if there’s a problem, or Alice can arbitrate and decide who should get the satoshis if there’s a dispute. +This simple contract isn’t much help if there’s a dispute, so Bob and Charlie enlist the help of Alice-the-arbitrator to create an :term:`escrow contract`. Charlie spends his satoshis to an output which can only be spent if two of the three people sign the input. Now Charlie can pay Bob if everything is ok, Bob can `refund <../devguide/payment_processing.html#issuing-refunds>`__ Charlie’s money if there’s a problem, or Alice can arbitrate and decide who should get the satoshis if there’s a dispute. -To create a multiple-signature (:term:`multisig `) output, they each give the others a public key. Then Bob creates the following :term:`P2SH multisig ` redeem script: +To create a multiple-signature (:term:`multisig`) output, they each give the others a public key. Then Bob creates the following :term:`P2SH multisig` redeem script: :: diff --git a/devguide/p2p_network.rst b/devguide/p2p_network.rst index 1bfe39e..430cc25 100644 --- a/devguide/p2p_network.rst +++ b/devguide/p2p_network.rst @@ -157,7 +157,7 @@ All of these problems are addressed in part or in full by the headers-first IBD Headers-First ~~~~~~~~~~~~~ -`Bitcoin Core 0.10.0 `__ uses an initial block download (IBD) method called *headers-first*. The goal is to download the headers for the best :term:`header chain
`, partially validate them as best as possible, and then download the corresponding blocks in parallel. This solves several problems with the older blocks-first IBD method. +`Bitcoin Core 0.10.0 `__ uses an initial block download (IBD) method called *headers-first*. The goal is to download the headers for the best :term:`header chain`, partially validate them as best as possible, and then download the corresponding blocks in parallel. This solves several problems with the older blocks-first IBD method. .. figure:: /img/dev/en-headers-first-flowchart.svg :alt: Overview Of Headers-First Method diff --git a/devguide/payment_processing.rst b/devguide/payment_processing.rst index 7a1e5e1..77b1ff6 100644 --- a/devguide/payment_processing.rst +++ b/devguide/payment_processing.rst @@ -126,7 +126,7 @@ Payment Protocol |Warning icon| **Warning:** The payment protocol is considered to be deprecated and will be removed in a later version of Bitcoin Core. The protocol has multiple security design flaws and implementation flaws in some wallets. Users will begin receiving deprecation warnings in Bitcoin Core version 0.18 when using `BIP70 `__ URI’s. Merchants should transition away from `BIP70 `__ to more secure options such as `BIP21 `__. Merchants should never require `BIP70 `__ payments and should provide `BIP21 `__ fallbacks. -Bitcoin Core 0.9 supports the new :term:`payment protocol `. The payment protocol adds many important features to payment requests: +Bitcoin Core 0.9 supports the new :term:`payment protocol`. The payment protocol adds many important features to payment requests: - Supports `X.509 `__ certificates and SSL encryption to verify receivers’ identity and help prevent `man-in-the-middle `__ attacks. @@ -217,7 +217,7 @@ Verifying Payment As explained in the `Transactions <../devguide/transactions.html>`__ and `Block Chain <../devguide/block_chain.html>`__ sections, broadcasting a transaction to the |network| doesn’t ensure that the receiver gets paid. A malicious spender can create one transaction that pays the receiver and a second one that pays the same input back to himself. Only one of these transactions will be added to the block chain, and nobody can say for sure which one it will be. -Two or more transactions spending the same input are commonly referred to as a :term:`double spend `. +Two or more transactions spending the same input are commonly referred to as a :term:`double spend`. Once the transaction is included in a block, double spends are impossible without modifying block chain history to replace the transaction, which is quite difficult. Using this system, the Bitcoin protocol can give each of your transactions an updating confidence score based on the number of blocks which would need to be modified to replace a transaction. For each block, the transaction gains one :term:`confirmation `. Since modifying blocks is quite difficult, higher confirmation scores indicate greater protection. diff --git a/devguide/transactions.rst b/devguide/transactions.rst index c3a94bf..e310aff 100644 --- a/devguide/transactions.rst +++ b/devguide/transactions.rst @@ -15,7 +15,7 @@ To keep things simple, this section pretends coinbase transactions do not exist. The Parts Of A Transaction -The figure above shows the main parts of a Bitcoin transaction. Each transaction has at least one input and one output. Each :term:`input ` spends the satoshis paid to a previous output. Each :term:`output ` then waits as an Unspent Transaction Output (UTXO) until a later input spends it. When your Bitcoin wallet tells you that you have a 10,000 satoshi balance, it really means that you have 10,000 satoshis waiting in one or more UTXOs. +The figure above shows the main parts of a Bitcoin transaction. Each transaction has at least one input and one output. Each :term:`input` spends the satoshis paid to a previous output. Each :term:`output` then waits as an Unspent Transaction Output (UTXO) until a later input spends it. When your Bitcoin wallet tells you that you have a 10,000 satoshi balance, it really means that you have 10,000 satoshis waiting in one or more UTXOs. Each transaction is prefixed by a four-byte :ref:`transaction version number ` which tells Bitcoin peers and miners which set of rules to use to validate it. This lets developers create new rules for future transactions without invalidating previous transactions. @@ -35,17 +35,17 @@ The figures below help illustrate how these features are used by showing the wor Creating A P2PKH Public Key Hash To Receive Payment -Bob must first generate a private/public :ref:`key pair ` before Alice can create the first transaction. Bitcoin uses the Elliptic Curve Digital Signature Algorithm (`ECDSA `__) with the `secp256k1 `__ curve; `secp256k1 `__ :term:`private keys ` are 256 bits of random data. A copy of that data is deterministically transformed into an `secp256k1 `__ :term:`public key `. Because the transformation can be reliably repeated later, the public key does not need to be stored. +Bob must first generate a private/public :term:`key pair` before Alice can create the first transaction. Bitcoin uses the Elliptic Curve Digital Signature Algorithm (`ECDSA `__) with the `secp256k1 `__ curve; a `secp256k1 `__ :term:`private key` is 256 bits of random data. A copy of that data is deterministically transformed into an `secp256k1 `__ :term:`public key `. Because the transformation can be reliably repeated later, the public key does not need to be stored. The public key (pubkey) is then cryptographically hashed. This pubkey hash can also be reliably repeated later, so it also does not need to be stored. The hash shortens and obfuscates the public key, making manual transcription easier and providing security against unanticipated problems which might allow reconstruction of private keys from public key data at some later point. Bob provides the pubkey hash to Alice. Pubkey hashes are almost always sent encoded as Bitcoin :term:`addresses
`, which are base58-encoded strings containing an address version number, the hash, and an error-detection checksum to catch typos. The address can be transmitted through any medium, including one-way mediums which prevent the spender from communicating with the receiver, and it can be further encoded into another format, such as a QR code containing a :ref:`“bitcoin:” URI `. -Once Alice has the address and decodes it back into a standard hash, she can create the first transaction. She creates a standard P2PKH transaction output containing instructions which allow anyone to spend that output if they can prove they control the private key corresponding to Bob’s hashed public key. These instructions are called the :term:`pubkey script ` or scriptPubKey. +Once Alice has the address and decodes it back into a standard hash, she can create the first transaction. She creates a standard P2PKH transaction output containing instructions which allow anyone to spend that output if they can prove they control the private key corresponding to Bob’s hashed public key. These instructions are called the :term:`pubkey script` or scriptPubKey. Alice broadcasts the transaction and it is added to the block chain. The |network| categorizes it as an Unspent Transaction Output (UTXO), and Bob’s wallet software displays it as a spendable balance. -When, some time later, Bob decides to spend the UTXO, he must create an input which references the transaction Alice created by its hash, called a Transaction Identifier (txid), and the specific output she used by its index number (:ref:`output index `). He must then create a :term:`signature script `—a collection of data parameters which satisfy the conditions Alice placed in the previous output’s pubkey script. Signature scripts are also called scriptSigs. +When, some time later, Bob decides to spend the UTXO, he must create an input which references the transaction Alice created by its hash, called a Transaction Identifier (txid), and the specific output she used by its index number (:ref:`output index `). He must then create a :term:`signature script` —a collection of data parameters which satisfy the conditions Alice placed in the previous output’s pubkey script. Signature scripts are also called scriptSigs. Pubkey scripts and signature scripts combine `secp256k1 `__ pubkeys and signatures with conditional logic, creating a programmable authorization mechanism. @@ -58,7 +58,7 @@ For a P2PKH-style output, Bob’s signature script will contain the following tw 1. His full (unhashed) public key, so the pubkey script can check that it hashes to the same value as the pubkey hash provided by Alice. -2. An `secp256k1 `__ :term:`signature ` made by using the `ECDSA `__ cryptographic formula to combine certain transaction data (described below) with Bob’s private key. This lets the pubkey script verify that Bob owns the private key which created the public key. +2. An `secp256k1 `__ :term:`signature` made by using the `ECDSA `__ cryptographic formula to combine certain transaction data (described below) with Bob’s private key. This lets the pubkey script verify that Bob owns the private key which created the public key. Bob’s `secp256k1 `__ signature doesn’t just prove Bob controls his private key; it also makes the non-signature-script parts of his transaction tamper-proof so Bob can safely broadcast them over the `peer-to-peer network <../devguide/p2p_network.html>`__. @@ -118,7 +118,7 @@ P2SH Scripts Pubkey scripts are created by spenders who have little interest what that script does. Receivers do care about the script conditions and, if they want, they can ask spenders to use a particular pubkey script. Unfortunately, custom pubkey scripts are less convenient than short Bitcoin addresses and there was no standard way to communicate them between programs prior to widespread implementation of the now deprecated `BIP70 `__ Payment Protocol discussed later. -To solve these problems, pay-to-script-hash (:term:`P2SH `) transactions were created in 2012 to let a spender create a pubkey script containing a hash of a second script, the :term:`redeem script `. +To solve these problems, pay-to-script-hash (:term:`P2SH `) transactions were created in 2012 to let a spender create a pubkey script containing a hash of a second script, the :term:`redeem script`. The basic P2SH workflow, illustrated below, looks almost identical to the P2PKH workflow. Bob creates a redeem script with whatever script he wants, hashes the redeem script, and provides the redeem script hash to Alice. Alice creates a P2SH-style output containing Bob’s redeem script hash. @@ -263,7 +263,7 @@ Signature Hash Types :ref:`“OP_CHECKSIG” ` extracts a non-stack argument from each signature it evaluates, allowing the signer to decide which parts of the transaction to sign. Since the signature protects those parts of the transaction from modification, this lets signers selectively choose to let other people modify their transactions. -The various options for what to sign are called :term:`signature hash ` types. There are three base SIGHASH types currently available: +The various options for what to sign are called :term:`signature hash` types. There are three base SIGHASH types currently available: - :term:`“SIGHASH_ALL” `, the default, signs all the inputs and outputs, protecting everything except the signature scripts against modification. @@ -284,7 +284,7 @@ Because each input is signed, a transaction with multiple inputs can have multip Locktime And Sequence Number ---------------------------- -One thing all signature hash types sign is the transaction’s :term:`locktime `. (Called nLockTime in the Bitcoin Core source code.) The locktime indicates the earliest time a transaction can be added to the block chain. +One thing all signature hash types sign is the transaction’s :term:`locktime`. (Called nLockTime in the Bitcoin Core source code.) The locktime indicates the earliest time a transaction can be added to the block chain. Locktime allows signers to create time-locked transactions which will only become valid in the future, giving the signers a chance to change their minds. @@ -311,7 +311,7 @@ There is also a concept of so-called “:term:`high-priority transactions ` (currently 1,000 satoshis) has been required to broadcast a transaction across the |network|. Any transaction paying only the minimum fee should be prepared to wait a long time before there’s enough spare space in a block to include it. Please see the `verifying payment section <../devguide/payment_processing.html#verifying-payment>`__ for why this could be important. +As of Bitcoin Core 0.9, a :term:`minimum relay fee` (currently 1,000 satoshis) has been required to broadcast a transaction across the |network|. Any transaction paying only the minimum fee should be prepared to wait a long time before there’s enough spare space in a block to include it. Please see the `verifying payment section <../devguide/payment_processing.html#verifying-payment>`__ for why this could be important. Since each transaction spends Unspent Transaction Outputs (UTXOs) and because a UTXO can only be spent once, the full value of the included UTXOs must be spent or given to a miner as a transaction fee. Few people will have UTXOs that exactly match the amount they want to pay, so most transactions include a change output. @@ -339,7 +339,7 @@ So, for both privacy and security, we encourage you to build your applications t Transaction Malleability ------------------------ -None of Bitcoin’s signature hash types protect the signature script, leaving the door open for a limited denial of service attack called :term:`transaction malleability `. The signature script contains the `secp256k1 `__ signature, which can’t sign itself, allowing attackers to make non-functional modifications to a transaction without rendering it invalid. For example, an attacker can add some data to the signature script which will be dropped before the previous pubkey script is processed. +None of Bitcoin’s signature hash types protect the signature script, leaving the door open for a limited denial of service attack called :term:`transaction malleability`. The signature script contains the `secp256k1 `__ signature, which can’t sign itself, allowing attackers to make non-functional modifications to a transaction without rendering it invalid. For example, an attacker can add some data to the signature script which will be dropped before the previous pubkey script is processed. Although the modifications are non-functional—so they do not change what inputs the transaction uses nor what outputs it pays—they do change the computed hash of the transaction. Since each transaction links to previous transactions using hashes as a transaction identifier (txid), a modified transaction will not have the txid its creator expected. diff --git a/devguide/wallets.rst b/devguide/wallets.rst index bad272f..28dde71 100644 --- a/devguide/wallets.rst +++ b/devguide/wallets.rst @@ -132,7 +132,7 @@ Private keys are what are used to unlock satoshis from a particular address. In Wallet Import Format (WIF) ^^^^^^^^^^^^^^^^^^^^^^^^^^ -In order to make copying of private keys less prone to error, :term:`Wallet Import Format ` may be utilized. WIF uses base58Check encoding on a private key, greatly decreasing the chance of copying error, much like standard Bitcoin addresses. +In order to make copying of private keys less prone to error, :term:`Wallet Import Format` may be utilized. WIF uses base58Check encoding on a private key, greatly decreasing the chance of copying error, much like standard Bitcoin addresses. 1. Take a private key. @@ -205,7 +205,7 @@ Hierarchical Deterministic Key Creation [normal|hardened|] [master|parent|child|grandchild] [extended|non-extended|] [private|public|chain] [key|code] --> -The hierarchical deterministic key creation and transfer protocol (:term:`HD protocol `) greatly simplifies wallet backups, eliminates the need for repeated communication between multiple programs using the same wallet, permits creation of child accounts which can operate independently, gives each parent account the ability to monitor or control its children even if the child account is compromised, and divides each account into full-access and restricted-access parts so untrusted users or programs can be allowed to receive or monitor payments without being able to spend them. +The hierarchical deterministic key creation and transfer protocol (:term:`HD protocol`) greatly simplifies wallet backups, eliminates the need for repeated communication between multiple programs using the same wallet, permits creation of child accounts which can operate independently, gives each parent account the ability to monitor or control its children even if the child account is compromised, and divides each account into full-access and restricted-access parts so untrusted users or programs can be allowed to receive or monitor payments without being able to spend them. The HD protocol takes advantage of the `ECDSA `__ public key creation function, :ref:`“point()” `, which takes a large integer (the private key) and turns it into a graph point (the public key): @@ -219,7 +219,7 @@ Because of the way :ref:`“point()” ` works, it’s poss point( (parent_private_key + i) % p ) == parent_public_key + point(i) -This means that two or more independent programs which agree on a sequence of integers can create a series of unique :term:`child key ` pairs from a single :term:`parent key ` pair without any further communication. Moreover, the program which distributes new public keys for receiving payment can do so without any access to the private keys, allowing the public key distribution program to run on a possibly-insecure platform such as a public web server. +This means that two or more independent programs which agree on a sequence of integers can create a series of unique :term:`child key` pairs from a single :term:`parent key` pair without any further communication. Moreover, the program which distributes new public keys for receiving payment can do so without any access to the private keys, allowing the public key distribution program to run on a possibly-insecure platform such as a public web server. Child public keys can also create their own child public keys (grandchild public keys) by repeating the child key derivation operations: @@ -229,7 +229,7 @@ Child public keys can also create their own child public keys (grandchild public Whether creating child public keys or further-descended public keys, a predictable sequence of integer values would be no better than using a single public key for all transactions, as anyone who knew one child public key could find all of the other child public keys created from the same parent public key. Instead, a random seed can be used to deterministically generate the sequence of integer values so that the relationship between the child public keys is invisible to anyone without that seed. -The HD protocol uses a single root seed to create a hierarchy of child, grandchild, and other descended keys with unlinkable deterministically-generated integer values. Each child key also gets a deterministically-generated seed from its parent, called a :term:`chain code `, so the compromising of one chain code doesn’t necessarily compromise the integer sequence for the whole hierarchy, allowing the :term:`master chain code ` to continue being useful even if, for example, a web-based public key distribution program gets hacked. +The HD protocol uses a single root seed to create a hierarchy of child, grandchild, and other descended keys with unlinkable deterministically-generated integer values. Each child key also gets a deterministically-generated seed from its parent, called a :term:`chain code`, so the compromising of one chain code doesn’t necessarily compromise the integer sequence for the whole hierarchy, allowing the :term:`master chain code` to continue being useful even if, for example, a web-based public key distribution program gets hacked. .. figure:: /img/dev/en-hd-overview.svg :alt: Overview Of Hierarchical Deterministic Key Derivation @@ -238,7 +238,7 @@ The HD protocol uses a single root seed to create a hierarchy of child, grandchi As illustrated above, HD key derivation takes four inputs: -- The :term:`parent private key ` and *parent public key* are regular uncompressed 256-bit `ECDSA `__ keys. +- The :term:`parent private key` and :term:`parent public key` are regular uncompressed 256-bit `ECDSA `__ keys. - The :term:`parent chain code ` is 256 bits of seemingly-random data. @@ -254,14 +254,14 @@ In the normal form shown in the above illustration, the parent chain code, the p Specifying different index numbers will create different unlinkable child keys from the same parent keys. Repeating the procedure for the child keys using the child chain code will create unlinkable grandchild keys. -Because creating child keys requires both a key and a chain code, the key and chain code together are called the :term:`extended key `. An :term:`extended private key ` and its corresponding :term:`extended public key ` have the same chain code. The (top-level parent) :term:`master private key ` and master chain code are derived from random data, as illustrated below. +Because creating child keys requires both a key and a chain code, the key and chain code together are called the :term:`extended key`. An :term:`extended private key ` and its corresponding :term:`extended public key ` have the same chain code. The (top-level parent) :term:`master private key` and :term:`master chain code` are derived from random data, as illustrated below. .. figure:: /img/dev/en-hd-root-keys.svg :alt: Creating A Root Extended Key Pair Creating A Root Extended Key Pair -A :term:`root seed ` is created from either 128 bits, 256 bits, or 512 bits of random data. This root seed of as little as 128 bits is the only data the user needs to backup in order to derive every key created by a particular wallet program using particular settings. +A :term:`root seed` is created from either 128 bits, 256 bits, or 512 bits of random data. This root seed of as little as 128 bits is the only data the user needs to backup in order to derive every key created by a particular wallet program using particular settings. |Warning icon| **Warning:** As of this writing, HD wallet programs are not expected to be fully compatible, so users must only use the same HD wallet program with the same HD-related settings for a particular root seed. diff --git a/examples/testing.rst b/examples/testing.rst index a39a4ec..4437ffa 100644 --- a/examples/testing.rst +++ b/examples/testing.rst @@ -6,7 +6,7 @@ Bitcoin Core provides testing tools designed to let developers test their applic Testnet ~~~~~~~ -When run with no arguments, all Bitcoin Core programs default to Bitcoin’s main |network| (:term:`mainnet `). However, for development, it’s safer and cheaper to use Bitcoin’s test |network| (testnet) where the satoshis spent have no real-world value. Testnet also relaxes some restrictions (such as standard transaction checks) so you can test functions which might currently be disabled by default on mainnet. +When run with no arguments, all Bitcoin Core programs default to Bitcoin’s main |network| (:term:`mainnet`). However, for development, it’s safer and cheaper to use Bitcoin’s test |network| (testnet) where the satoshis spent have no real-world value. Testnet also relaxes some restrictions (such as standard transaction checks) so you can test functions which might currently be disabled by default on mainnet. To use testnet, use the argument ``-testnet`` with ``bitcoin-cli``, ``bitcoind`` or ``bitcoin-qt`` or add ``testnet=1`` to your ``bitcoin.conf`` file as `described earlier <../examples/index.html>`__. To get free satoshis for testing, use `Piotr Piasecki’s testnet faucet `__. Testnet is a public resource provided for free by members of the community, so please don’t abuse it. diff --git a/reference/p2p_networking.rst b/reference/p2p_networking.rst index 488ba3a..f8eb62f 100644 --- a/reference/p2p_networking.rst +++ b/reference/p2p_networking.rst @@ -13,7 +13,7 @@ Constants And Defaults The following constants and defaults are taken from Bitcoin Core’s `chainparams.cpp `__ source code file. +--------------------------------------------+--------------+------------------------------------------+------------+ -| `Network <../devguide/p2p_network.html>`__ | Default Port | :term:`Start String ` | Max nBits | +| `Network <../devguide/p2p_network.html>`__ | Default Port | :term:`Start String` | Max nBits | +============================================+==============+==========================================+============+ | Mainnet | 8333 | 0xf9beb4d9 | 0x1d00ffff | +--------------------------------------------+--------------+------------------------------------------+------------+ @@ -692,7 +692,7 @@ Alert *Added in*\ `protocol version 311 <../reference/p2p_networking.html#protocol-versions>`__\ *.* *Removed in*\ `protocol version 70013 <../reference/p2p_networking.html#protocol-versions>`__\ *and released in*\ `Bitcoin Core 0.13.0 `__ -The legacy p2p `network <../devguide/p2p_network.html>`__ alert messaging system has been retired; however, internal alerts, partition detection warnings and the ``-alertnotify`` option features remain. See `Alert System Retirement `__ for details. +The legacy :ref:p2p-network-header alert messaging system has been retired; however, internal alerts, partition detection warnings and the ``-alertnotify`` option features remain. See `Alert System Retirement `__ for details. FeeFilter ^^^^^^^^^ diff --git a/reference/transactions.rst b/reference/transactions.rst index 379d1d6..cc5072f 100644 --- a/reference/transactions.rst +++ b/reference/transactions.rst @@ -100,7 +100,7 @@ First, get your hash. For P2PKH, you RIPEMD-160(SHA256()) hash a `ECDSA ` may not match other implementations. Tier Nolan provided the following example encoding algorithm to the Bitcoin Wiki `Base58Check encoding `__ page under the `Creative Commons Attribution 3.0 license `__: +Bitcoin’s base58 encoding, called :term:`Base58Check` may not match other implementations. Tier Nolan provided the following example encoding algorithm to the Bitcoin Wiki `Base58Check encoding `__ page under the `Creative Commons Attribution 3.0 license `__: .. highlight:: c From f340d88122309c4a900cd7dd127ecc690d737e6a Mon Sep 17 00:00:00 2001 From: Jesse Frush Date: Mon, 12 Apr 2021 11:38:31 -0700 Subject: [PATCH 09/14] added many common references and terms to rst_eplog and ran some sed substitutions to replace these as well as to replace broken :ref: links to missing terms from site conversion" --- conf.py | 19 +++++++++ devguide/block_chain.rst | 2 +- devguide/contracts.rst | 14 +++---- devguide/p2p_network.rst | 14 +++---- devguide/payment_processing.rst | 74 ++++++++++++++++++--------------- devguide/transactions.rst | 38 ++++++++--------- devguide/wallets.rst | 23 +++++----- glossary.rst | 16 +++---- reference/block_chain.rst | 2 +- reference/intro.rst | 4 +- reference/p2p_networking.rst | 32 +++++++------- reference/transactions.rst | 32 +++++++------- 12 files changed, 148 insertions(+), 122 deletions(-) diff --git a/conf.py b/conf.py index ab83a4d..723287f 100644 --- a/conf.py +++ b/conf.py @@ -193,5 +193,24 @@ # improve readability and prevent unexpected content changes. #rst_prolog = '' rst_epilog = """ +.. reference aliases .. |network| replace:: :ref:`network` + +.. frequently-used terms with links +.. |ECDSA| replace:: `ECDSA ` +.. |secp256k1| replace:: `secp256k1 ` + +.. OP codes +.. |OP_CHECKMULTISIG| replace:: :term:`“OP_CHECKMULTISIG” ` +.. |OP_CHECKSIG| replace:: :term:`“OP_CHECKSIG” ` +.. |OP_DUP| replace:: :term:`“OP_DUP” ` +.. |OP_EQUAL| replace:: :term:`OP_EQUAL ` +.. |OP_EQUALVERIFY| replace:: :term:`“OP_EQUALVERIFY” ` +.. |OP_HASH160| replace:: :term:`“OP_HASH160” ` +.. |OP_RETURN| replace:: :term:`“OP_RETURN” ` +.. |OP_VERIFY| replace:: :term:`“OP_VERIFY” ` + +.. other +.. |PaymentDetails| replace:: :term:`PaymentDetails` +.. |PaymentRequest| replace:: :term:`PaymentRequest` """ diff --git a/devguide/block_chain.rst b/devguide/block_chain.rst index 472b7df..16831b5 100644 --- a/devguide/block_chain.rst +++ b/devguide/block_chain.rst @@ -157,7 +157,7 @@ In either case, block and transaction data should not be relied upon if it comes SPV clients which connect to full nodes can detect a likely hard fork by connecting to several full nodes and ensuring that they’re all on the same chain with the same block height, plus or minus several blocks to account for transmission delays and |stale blocks| . If there’s a divergence, the client can disconnect from nodes with weaker chains. -SPV clients should also monitor for block and :ref:`transaction version number ` increases to ensure they process received transactions and create new transactions using the current consensus rules. +SPV clients should also monitor for block and :term:`transaction version number` increases to ensure they process received transactions and create new transactions using the current consensus rules. .. |stale blocks| replace:: :term:`stale blocks ` .. |orphan blocks| replace:: :term:`orphan blocks ` \ No newline at end of file diff --git a/devguide/contracts.rst b/devguide/contracts.rst index 9af6ff4..ac07e34 100644 --- a/devguide/contracts.rst +++ b/devguide/contracts.rst @@ -41,9 +41,9 @@ In the signature script Alice puts her signature and a copy of the unhashed seri OP_0 [A's signature] [B's or C's signature] [serialized redeem script] -(Opcodes to push the signatures and redeem script onto the stack are not shown. ``OP_0`` is a workaround for an off-by-one error in the original implementation which must be preserved for compatibility. Note that the signature script must provide signatures in the same order as the corresponding public keys appear in the redeem script. See the description in :ref:`“OP_CHECKMULTISIG” ` for details.) +(Opcodes to push the signatures and redeem script onto the stack are not shown. ``OP_0`` is a workaround for an off-by-one error in the original implementation which must be preserved for compatibility. Note that the signature script must provide signatures in the same order as the corresponding public keys appear in the redeem script. See the description in |OP_CHECKMULTISIG| for details.) -When the transaction is broadcast to the `network <../devguide/p2p_network.html>`__, each peer checks the signature script against the P2SH output Charlie previously paid, ensuring that the redeem script matches the redeem script hash previously provided. Then the redeem script is evaluated, with the two signatures being used as input data. Assuming the redeem script validates, the two transaction outputs show up in Bob’s and Charlie’s wallets as spendable balances. +When the transaction is broadcast to the |network|, each peer checks the signature script against the P2SH output Charlie previously paid, ensuring that the redeem script matches the redeem script hash previously provided. Then the redeem script is evaluated, with the two signatures being used as input data. Assuming the redeem script validates, the two transaction outputs show up in Bob’s and Charlie’s wallets as spendable balances. However, if Alice created and signed a transaction neither of them would agree to, such as spending all the satoshis to herself, Bob and Charlie can find a new arbitrator and sign a transaction spending the satoshis to another 2-of-3 multisig redeem script hash, this one including a public key from that second arbitrator. This means that Bob and Charlie never need to worry about their arbitrator stealing their money. @@ -52,7 +52,7 @@ However, if Alice created and signed a transaction neither of them would agree t Micropayment Channel -------------------- -Alice also works part time moderating forum posts for Bob. Every time someone posts to Bob’s busy forum, Alice skims the post to make sure it isn’t offensive or spam. Alas, Bob often forgets to pay her, so Alice demands to be paid immediately after each post she approves or rejects. Bob says he can’t do that because hundreds of small payments will cost him thousands of satoshis in transaction fees, so Alice suggests they use a :ref:`micropayment channel `. +Alice also works part time moderating forum posts for Bob. Every time someone posts to Bob’s busy forum, Alice skims the post to make sure it isn’t offensive or spam. Alas, Bob often forgets to pay her, so Alice demands to be paid immediately after each post she approves or rejects. Bob says he can’t do that because hundreds of small payments will cost him thousands of satoshis in transaction fees, so Alice suggests they use a :term:`micropayment channel`. Bob asks Alice for her public key and then creates two transactions. The first transaction pays 100 millibitcoins to a P2SH output whose 2-of-2 multisig redeem script requires signatures from both Alice and Bob. This is the bond transaction. Broadcasting this transaction would let Alice hold the millibitcoins hostage, so Bob keeps this transaction private for now and creates a second transaction. @@ -63,15 +63,15 @@ The second transaction spends all of the first transaction’s millibitcoins (mi Micropayment Channel Example -Alice checks that the `refund <../devguide/payment_processing.html#issuing-refunds>`__ transaction’s locktime is 24 hours in the future, signs it, and gives a copy of it back to Bob. She then asks Bob for the bond transaction and checks that the `refund <../devguide/payment_processing.html#issuing-refunds>`__ transaction spends the output of the bond transaction. She can now broadcast the bond transaction to the `network <../devguide/p2p_network.html>`__ to ensure Bob has to wait for the time lock to expire before further spending his millibitcoins. Bob hasn’t actually spent anything so far, except possibly a small transaction fee, and he’ll be able to broadcast the `refund <../devguide/payment_processing.html#issuing-refunds>`__ transaction in 24 hours for a full `refund <../devguide/payment_processing.html#issuing-refunds>`__. +Alice checks that the `refund <../devguide/payment_processing.html#issuing-refunds>`__ transaction’s locktime is 24 hours in the future, signs it, and gives a copy of it back to Bob. She then asks Bob for the bond transaction and checks that the `refund <../devguide/payment_processing.html#issuing-refunds>`__ transaction spends the output of the bond transaction. She can now broadcast the bond transaction to the |network| to ensure Bob has to wait for the time lock to expire before further spending his millibitcoins. Bob hasn’t actually spent anything so far, except possibly a small transaction fee, and he’ll be able to broadcast the `refund <../devguide/payment_processing.html#issuing-refunds>`__ transaction in 24 hours for a full `refund <../devguide/payment_processing.html#issuing-refunds>`__. Now, when Alice does some work worth 1 millibitcoin, she asks Bob to create and sign a new version of the `refund <../devguide/payment_processing.html#issuing-refunds>`__ transaction. Version two of the transaction spends 1 millibitcoin to Alice and the other 99 back to Bob; it does not have a locktime, so Alice can sign it and spend it whenever she wants. (But she doesn’t do that immediately.) -Alice and Bob repeat these work-and-pay steps until Alice finishes for the day, or until the time lock is about to expire. Alice signs the final version of the `refund <../devguide/payment_processing.html#issuing-refunds>`__ transaction and broadcasts it, paying herself and refunding any remaining balance to Bob. The next day, when Alice starts work, they create a new :ref:`micropayment channel `. +Alice and Bob repeat these work-and-pay steps until Alice finishes for the day, or until the time lock is about to expire. Alice signs the final version of the `refund <../devguide/payment_processing.html#issuing-refunds>`__ transaction and broadcasts it, paying herself and refunding any remaining balance to Bob. The next day, when Alice starts work, they create a new :term:`micropayment channel`. -If Alice fails to broadcast a version of the `refund <../devguide/payment_processing.html#issuing-refunds>`__ transaction before its time lock expires, Bob can broadcast the first version and receive a full `refund <../devguide/payment_processing.html#issuing-refunds>`__. This is one reason :ref:`micropayment channels ` are best suited to small payments—if Alice’s Internet service goes out for a few hours near the time lock expiry, she could be cheated out of her payment. +If Alice fails to broadcast a version of the `refund <../devguide/payment_processing.html#issuing-refunds>`__ transaction before its time lock expires, Bob can broadcast the first version and receive a full `refund <../devguide/payment_processing.html#issuing-refunds>`__. This is one reason :term:`micropayment channels ` are best suited to small payments—if Alice’s Internet service goes out for a few hours near the time lock expiry, she could be cheated out of her payment. -Transaction malleability, discussed above in the Transactions section, is another reason to limit the value of :ref:`micropayment channels `. If someone uses transaction malleability to break the link between the two transactions, Alice could hold Bob’s 100 millibitcoins hostage even if she hadn’t done any work. +Transaction malleability, discussed above in the Transactions section, is another reason to limit the value of :term:`micropayment channels `. If someone uses transaction malleability to break the link between the two transactions, Alice could hold Bob’s 100 millibitcoins hostage even if she hadn’t done any work. For larger payments, Bitcoin transaction fees are very low as a percentage of the total transaction value, so it makes more sense to protect payments with immediately-broadcast separate transactions. diff --git a/devguide/p2p_network.rst b/devguide/p2p_network.rst index 430cc25..6e2462e 100644 --- a/devguide/p2p_network.rst +++ b/devguide/p2p_network.rst @@ -83,7 +83,7 @@ The first time a node is started, it only has a single block in its local best b In the header hashes field of the `“getblocks” message <../reference/p2p_networking.html#getblocks>`__, this new node sends the header hash of the only block it has, the genesis block (6fe2…0000 in internal byte order). It also sets the stop hash field to all zeroes to request a maximum-size response. -Upon :ref:`receipt ` of the `“getblocks” message <../reference/p2p_networking.html#getblocks>`__, the sync node takes the first (and only) header hash and searches its local best block chain for a block with that header hash. It finds that block 0 matches, so it replies with 500 block inventories (the maximum response to a `“getblocks” message <../reference/p2p_networking.html#getblocks>`__) starting from block 1. It sends these inventories in the `“inv” message <../reference/p2p_networking.html#inv>`__ illustrated below. +Upon :term:`receipt` of the `“getblocks” message <../reference/p2p_networking.html#getblocks>`__, the sync node takes the first (and only) header hash and searches its local best block chain for a block with that header hash. It finds that block 0 matches, so it replies with 500 block inventories (the maximum response to a `“getblocks” message <../reference/p2p_networking.html#getblocks>`__) starting from block 1. It sends these inventories in the `“inv” message <../reference/p2p_networking.html#inv>`__ illustrated below. .. figure:: /img/dev/en-ibd-inv.svg :alt: First Inv Message Sent During IBD @@ -103,7 +103,7 @@ The IBD node uses the received inventories to request 128 blocks from the sync n It’s important to blocks-first nodes that the blocks be requested and sent in order because each block header references the header hash of the preceding block. That means the IBD node can’t fully validate a block until its parent block has been received. Blocks that can’t be validated because their parents haven’t been received are called orphan blocks; a subsection below describes them in more detail. -Upon :ref:`receipt ` of the `“getdata” message <../reference/p2p_networking.html#getdata>`__, the sync node replies with each of the blocks requested. Each block is put into serialized block format and sent in a separate `“block” message <../reference/p2p_networking.html#block>`__. The first `“block” message <../reference/p2p_networking.html#block>`__ sent (for block 1) is illustrated below. +Upon :term:`receipt` of the `“getdata” message <../reference/p2p_networking.html#getdata>`__, the sync node replies with each of the blocks requested. Each block is put into serialized block format and sent in a separate `“block” message <../reference/p2p_networking.html#block>`__. The first `“block” message <../reference/p2p_networking.html#block>`__ sent (for block 1) is illustrated below. .. figure:: /img/dev/en-ibd-block.svg :alt: First Block Message Sent During IBD @@ -117,7 +117,7 @@ The IBD node downloads each block, validates it, and then requests the next bloc Second GetBlocks Message Sent During IBD -Upon :ref:`receipt ` of the second `“getblocks” message <../reference/p2p_networking.html#getblocks>`__, the sync node searches its local best block chain for a block that matches one of the header hashes in the message, trying each hash in the order they were received. If it finds a matching hash, it replies with 500 block inventories starting with the next block from that point. But if there is no matching hash (besides the stopping hash), it assumes the only block the two nodes have in common is block 0 and so it sends an ``inv`` starting with block 1 (the same `“inv” message <../reference/p2p_networking.html#inv>`__ seen several illustrations above). +Upon :term:`receipt` of the second `“getblocks” message <../reference/p2p_networking.html#getblocks>`__, the sync node searches its local best block chain for a block that matches one of the header hashes in the message, trying each hash in the order they were received. If it finds a matching hash, it replies with 500 block inventories starting with the next block from that point. But if there is no matching hash (besides the stopping hash), it assumes the only block the two nodes have in common is block 0 and so it sends an ``inv`` starting with block 1 (the same `“inv” message <../reference/p2p_networking.html#inv>`__ seen several illustrations above). This repeated search allows the sync node to send useful inventories even if the IBD node’s local block chain forked from the sync node’s local block chain. This fork detection becomes increasingly useful the closer the IBD node gets to the tip of the block chain. @@ -173,7 +173,7 @@ The first time a node is started, it only has a single block in its local best b In the header hashes field of the `“getheaders” message <../reference/p2p_networking.html#getheaders>`__, the new node sends the header hash of the only block it has, the genesis block (6fe2…0000 in internal byte order). It also sets the stop hash field to all zeroes to request a maximum-size response. -Upon :ref:`receipt ` of the `“getheaders” message <../reference/p2p_networking.html#getheaders>`__, the sync node takes the first (and only) header hash and searches its local best block chain for a block with that header hash. It finds that block 0 matches, so it replies with 2,000 header (the maximum response) starting from block 1. It sends these header hashes in the `“headers” message <../reference/p2p_networking.html#headers>`__ illustrated below. +Upon :term:`receipt` of the `“getheaders” message <../reference/p2p_networking.html#getheaders>`__, the sync node takes the first (and only) header hash and searches its local best block chain for a block with that header hash. It finds that block 0 matches, so it replies with 2,000 header (the maximum response) starting from block 1. It sends these header hashes in the `“headers” message <../reference/p2p_networking.html#headers>`__ illustrated below. .. figure:: /img/dev/en-ibd-headers.svg :alt: First headers message @@ -236,9 +236,9 @@ When a miner discovers a new block, it broadcasts the new block to its peers usi This protocol for block broadcasting was proposed in BIP 130 and has been implemented in Bitcoin Core since version 0.12. -By default, Bitcoin Core broadcasts blocks using direct headers announcement to any peers that have signalled with `“sendheaders” <../reference/p2p_networking.html#sendheaders>`__ and uses :ref:`standard block relay ` for all peers that have not. Bitcoin Core will accept blocks sent using any of the methods described above. +By default, Bitcoin Core broadcasts blocks using direct headers announcement to any peers that have signalled with `“sendheaders” <../reference/p2p_networking.html#sendheaders>`__ and uses :term:`standard block relay` for all peers that have not. Bitcoin Core will accept blocks sent using any of the methods described above. -Full nodes validate the received block and then advertise it to their peers using the :ref:`standard block relay ` method described above. The condensed table below highlights the operation of the messages described above (Relay, BF, HF, and SPV refer to the relay node, a blocks-first node, a headers-first node, and an SPV client; *any* refers to a node using any block retrieval method.) +Full nodes validate the received block and then advertise it to their peers using the :term:`standard block relay` method described above. The condensed table below highlights the operation of the messages described above (Relay, BF, HF, and SPV refer to the relay node, a blocks-first node, a headers-first node, and an SPV client; *any* refers to a node using any block retrieval method.) +------------------------------------------------------------------+---------------+------------------------------------------------------------------------------------------+ | Message | From→To | Payload | @@ -261,7 +261,7 @@ Full nodes validate the received block and then advertise it to their peers usin Orphan Blocks ~~~~~~~~~~~~~ -Blocks-first nodes may download orphan blocks—blocks whose :ref:`previous block header hash ` field refers to a block header this node hasn’t seen yet. In other words, orphan blocks have no known parent (unlike stale blocks, which have known parents but which aren’t part of the best block chain). +Blocks-first nodes may download orphan blocks—blocks whose :term:`previous block header hash` field refers to a block header this node hasn’t seen yet. In other words, orphan blocks have no known parent (unlike stale blocks, which have known parents but which aren’t part of the best block chain). .. figure:: /img/dev/en-orphan-stale-definition.svg :alt: Difference Between Orphan And Stale Blocks diff --git a/devguide/payment_processing.rst b/devguide/payment_processing.rst index 77b1ff6..8deea27 100644 --- a/devguide/payment_processing.rst +++ b/devguide/payment_processing.rst @@ -20,7 +20,7 @@ It is worth mentioning that each of these steps can be outsourced by using third Pricing Orders -------------- -Because of exchange rate variability between satoshis and national currencies (:ref:`fiat `), many Bitcoin orders are priced in :ref:`fiat ` but paid in satoshis, necessitating a price conversion. +Because of exchange rate variability between satoshis and national currencies (:term:`fiat`), many Bitcoin orders are priced in :term:`fiat` but paid in satoshis, necessitating a price conversion. Exchange rate data is widely available through HTTP-based APIs provided by currency exchanges. Several organizations also aggregate data from multiple exchanges to create index prices, which are also available using HTTP-based APIs. @@ -30,9 +30,9 @@ To minimize problems, your applications may want to collect data from at least t You may also want to program your applications to enter a safe mode if exchange rates are rapidly increasing or decreasing, indicating a possible problem in the Bitcoin market which could make it difficult to spend any satoshis received today. -Exchange rates lie outside the control of Bitcoin and related technologies, so there are no new or planned technologies which will make it significantly easier for your program to correctly convert order totals from :ref:`fiat ` into satoshis. +Exchange rates lie outside the control of Bitcoin and related technologies, so there are no new or planned technologies which will make it significantly easier for your program to correctly convert order totals from :term:`fiat` into satoshis. -Because the exchange rate fluctuates over time, order totals pegged to :ref:`fiat ` must expire to prevent spenders from delaying payment in the hope that satoshis will drop in price. Most widely-used payment processing systems currently expire their invoices after 10 to 20 minutes. +Because the exchange rate fluctuates over time, order totals pegged to :term:`fiat` must expire to prevent spenders from delaying payment in the hope that satoshis will drop in price. Most widely-used payment processing systems currently expire their invoices after 10 to 20 minutes. Shorter expiration periods increase the chance the invoice will expire before payment is received, possibly necessitating manual intervention to request an additional payment or to issue a `refund <../devguide/payment_processing.html#issuing-refunds>`__. Longer expiration periods increase the chance that the exchange rate will fluctuate a significant amount before payment is received. @@ -47,9 +47,9 @@ The next subsections will describe in detail the following four compatible ways 1. All wallet software lets its users paste in or manually enter an address and amount into a payment screen. This is, of course, inconvenient—but it makes an effective fallback option. -2. Almost all desktop wallets can associate with :ref:`“bitcoin:” URIs `, so spenders can click a link to pre-fill the payment screen. This also works with many mobile wallets, but it generally does not work with web-based wallets unless the spender installs a browser extension or manually configures a URI handler. +2. Almost all desktop wallets can associate with |Bitcoin URIs|, so spenders can click a link to pre-fill the payment screen. This also works with many mobile wallets, but it generally does not work with web-based wallets unless the spender installs a browser extension or manually configures a URI handler. -3. Most mobile wallets support scanning :ref:`“bitcoin:” URIs ` encoded in a QR code, and almost all wallets can display them for accepting payment. While also handy for online orders, QR Codes are especially useful for in-person purchases. +3. Most mobile wallets support scanning |Bitcoin URIs| encoded in a QR code, and almost all wallets can display them for accepting payment. While also handy for online orders, QR Codes are especially useful for in-person purchases. 4. Recent wallet updates add support for the new payment protocol providing increased security, authentication of a receiver’s identity using `X.509 `__ certificates, and other important features such as `refunds <../devguide/payment_processing.html#issuing-refunds>`__. @@ -84,7 +84,7 @@ Bitcoins Unit (Abbreviation) bitcoin: URI ~~~~~~~~~~~~ -The :ref:`“bitcoin:” URI ` scheme defined in `BIP21 `__ eliminates denomination confusion and saves the spender from copying and pasting two separate values. It also lets the payment request provide some additional information to the spender. An example: +The |Bitcoin URI| scheme defined in `BIP21 `__ eliminates denomination confusion and saves the spender from copying and pasting two separate values. It also lets the payment request provide some additional information to the spender. An example: :: @@ -92,7 +92,7 @@ The :ref:`“bitcoin:” URI ` scheme defined in `BIP21 ` parameter is generally used to provide wallet software with the recipient’s name. The :ref:`“message” ` parameter is generally used to describe the payment request to the spender. Both the label and the message are commonly stored by the spender’s wallet software—but they are never added to the actual transaction, so other Bitcoin users cannot see them. Both the label and the message must be `URI encoded `__. +Two other parameters are widely supported. The :term:`“label”