From 82256a4e49dc7cf666f503840113aeb02e8d3293 Mon Sep 17 00:00:00 2001 From: tushar-1728 Date: Fri, 6 Nov 2020 23:29:48 +0530 Subject: [PATCH 1/5] Fixed sphinx build warnings --- devguide/block_chain.rst | 32 +++++++++++++------------- devguide/contracts.rst | 4 ++-- devguide/p2p_network.rst | 6 ++--- devguide/payment_processing.rst | 6 ++--- devguide/transactions.rst | 40 ++++++++++++++++----------------- devguide/wallets.rst | 20 ++++++++--------- examples/testing.rst | 2 +- index.rst | 2 +- reference/block_chain.rst | 6 ++--- reference/p2p_networking.rst | 6 ++--- reference/transactions.rst | 8 +++---- 11 files changed, 66 insertions(+), 66 deletions(-) diff --git a/devguide/block_chain.rst b/devguide/block_chain.rst index 2f61466..4bbfbb3 100644 --- a/devguide/block_chain.rst +++ b/devguide/block_chain.rst @@ -6,14 +6,14 @@ 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 <../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. .. 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. @@ -26,11 +26,11 @@ Transactions are also chained together. Bitcoin wallet software gives the impres A single transaction can create multiple outputs, as would be the case when sending to multiple addresses, but each output of a particular transaction can only be used as an input once in the block chain. Any subsequent reference is a forbidden double spend—an attempt to spend the same satoshis twice. -Outputs are tied to :term:`transaction identifiers (TXIDs) `, which are the hashes of signed transactions. +Outputs are tied to :term:`transaction identifiers (TXIDs) `, which are the hashes of signed transactions. -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. +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 ------------- @@ -39,13 +39,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. +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 <../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). - 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. @@ -60,18 +60,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 :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.) 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. @@ -88,7 +88,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. @@ -119,14 +119,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 @@ -135,9 +135,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 `__. diff --git a/devguide/contracts.rst b/devguide/contracts.rst index d44a446..77832b4 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 77a03a5..66896cd 100644 --- a/devguide/p2p_network.rst +++ b/devguide/p2p_network.rst @@ -15,7 +15,7 @@ To provide practical examples of the Bitcoin `peer-to-peer network <../devguide/ Peer Discovery -------------- -When started for the first time, programs don’t know the IP addresses of any active full nodes. In order to discover some IP addresses, they query one or more DNS names (called :term:`DNS seeds `) hardcoded into Bitcoin Core and `BitcoinJ `__. The response to the lookup should include one or more `DNS A records `__ with the IP addresses of full nodes that may accept new incoming connections. For example, using the `Unix ``dig`` command `__: +When started for the first time, programs don’t know the IP addresses of any active full nodes. In order to discover some IP addresses, they query one or more DNS names (called :term:`DNS seeds `) hardcoded into Bitcoin Core and `BitcoinJ `__. The response to the lookup should include one or more `DNS A records `__ with the IP addresses of full nodes that may accept new incoming connections. For example, using the `Unix ``dig`` command `__: :: @@ -155,7 +155,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 @@ -230,7 +230,7 @@ When a miner discovers a new block, it broadcasts the new block to its peers usi The miner replies to each request accordingly by sending the block in a `“block” message <../reference/p2p_networking.html#block>`__, one or more headers in a `“headers” message <../reference/p2p_networking.html#headers>`__, or the merkle block and transactions relative to the SPV client’s bloom filter in a `“merkleblock” message <../reference/p2p_networking.html#merkleblock>`__ followed by zero or more `“tx” messages <../reference/p2p_networking.html#tx>`__. -- :term:`Direct Headers Announcement `\ **:** a relay node may skip the round trip overhead of an `“inv” message <../reference/p2p_networking.html#inv>`__ followed by ``getheaders`` by instead immediately sending a `“headers” message <../reference/p2p_networking.html#headers>`__ containing the full header of the new block. A HF peer receiving this message will partially validate the block header as it would during headers-first IBD, then request the full block contents with a `“getdata” message <../reference/p2p_networking.html#getdata>`__ if the header is valid. The relay node then responds to the ``getdata`` request with the full or filtered block data in a ``block`` or `“merkleblock” message <../reference/p2p_networking.html#merkleblock>`__, respectively. A HF node may signal that it prefers to receive ``headers`` instead of ``inv`` announcements by sending a special `“sendheaders” message <../reference/p2p_networking.html#sendheaders>`__ during the connection handshake. +- :term:`Direct Headers Announcement `\ **:** a relay node may skip the round trip overhead of an `“inv” message <../reference/p2p_networking.html#inv>`__ followed by ``getheaders`` by instead immediately sending a `“headers” message <../reference/p2p_networking.html#headers>`__ containing the full header of the new block. A HF peer receiving this message will partially validate the block header as it would during headers-first IBD, then request the full block contents with a `“getdata” message <../reference/p2p_networking.html#getdata>`__ if the header is valid. The relay node then responds to the ``getdata`` request with the full or filtered block data in a ``block`` or `“merkleblock” message <../reference/p2p_networking.html#merkleblock>`__, respectively. A HF node may signal that it prefers to receive ``headers`` instead of ``inv`` announcements by sending a special `“sendheaders” message <../reference/p2p_networking.html#sendheaders>`__ during the connection handshake. This protocol for block broadcasting was proposed in BIP 130 and has been implemented in Bitcoin Core since version 0.12. diff --git a/devguide/payment_processing.rst b/devguide/payment_processing.rst index 3ed9b21..8b75923 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,9 +217,9 @@ 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. -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. +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. diff --git a/devguide/transactions.rst b/devguide/transactions.rst index 99d6f0b..8f30f5f 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. @@ -28,24 +28,24 @@ An output has an implied index number based on its location in the transaction An input uses a transaction identifier (txid) and an :ref:`output index ` number (often called “vout” for output vector) to identify a particular output to be spent. It also has a signature script which allows it to provide data parameters that satisfy the conditionals in the pubkey script. (The sequence number and locktime are related and will be covered together in a later subsection.) -The figures below help illustrate how these features are used by showing the workflow Alice uses to send Bob a transaction and which Bob later uses to spend that transaction. Both Alice and Bob will use the most common form of the standard Pay-To-Public-Key-Hash (P2PKH) transaction type. :term:`P2PKH ` lets Alice spend satoshis to a typical Bitcoin address, and then lets Bob further spend those satoshis using a simple cryptographic :ref:`key pair `. +The figures below help illustrate how these features are used by showing the workflow Alice uses to send Bob a transaction and which Bob later uses to spend that transaction. Both Alice and Bob will use the most common form of the standard Pay-To-Public-Key-Hash (P2PKH) transaction type. :term:`P2PKH ` lets Alice spend satoshis to a typical Bitcoin address, and then lets Bob further spend those satoshis using a simple cryptographic :ref:`key pair `. .. figure:: /img/dev/en-creating-p2pkh-output.svg :alt: Creating A P2PKH Public Key Hash To Receive Payment 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 :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. 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 `. +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 <../devguide/p2p_network.html>`__ 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. @@ -218,7 +218,7 @@ Pubkey outputs are a simplified form of the P2PKH pubkey script, but they aren Null Data ~~~~~~~~~ -:term:`Null data ` transaction type relayed and mined by default in `Bitcoin Core 0.9.0 `__ and later that adds arbitrary data to a provably unspendable pubkey script that full nodes don’t have to store in their UTXO database. It is preferable to use null data transactions over transactions that bloat the UTXO database because they cannot be automatically pruned; however, it is usually even more preferable to store data outside transactions if possible. +:term:`Null data ` transaction type relayed and mined by default in `Bitcoin Core 0.9.0 `__ and later that adds arbitrary data to a provably unspendable pubkey script that full nodes don’t have to store in their UTXO database. It is preferable to use null data transactions over transactions that bloat the UTXO database because they cannot be automatically pruned; however, it is usually even more preferable to store data outside transactions if possible. Consensus rules allow null data outputs up to the maximum allowed pubkey script size of 10,000 bytes provided they follow all other consensus rules, such as not having any data pushes larger than 520 bytes. @@ -263,15 +263,15 @@ 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. +- :term:`“SIGHASH_ALL” `, the default, signs all the inputs and outputs, protecting everything except the signature scripts against modification. -- :term:`“SIGHASH_NONE” ` signs all of the inputs but none of the outputs, allowing anyone to change where the satoshis are going unless other signatures using other signature hash flags protect the outputs. +- :term:`“SIGHASH_NONE” ` signs all of the inputs but none of the outputs, allowing anyone to change where the satoshis are going unless other signatures using other signature hash flags protect the outputs. -- :term:`“SIGHASH_SINGLE” ` the only output signed is the one corresponding to this input (the output with the same :ref:`output index ` number as this input), ensuring nobody can change your part of the transaction but allowing other signers to change their part of the transaction. The corresponding output must exist or the value “1” will be signed, breaking the security scheme. This input, as well as other inputs, are included in the signature. The sequence numbers of other inputs are not included in the signature, and can be updated. +- :term:`“SIGHASH_SINGLE” ` the only output signed is the one corresponding to this input (the output with the same :ref:`output index ` number as this input), ensuring nobody can change your part of the transaction but allowing other signers to change their part of the transaction. The corresponding output must exist or the value “1” will be signed, breaking the security scheme. This input, as well as other inputs, are included in the signature. The sequence numbers of other inputs are not included in the signature, and can be updated. -The base types can be modified with the :term:`“SIGHASH_ANYONECANPAY” ` (anyone can pay) flag, creating three new combined types: +The base types can be modified with the :term:`“SIGHASH_ANYONECANPAY” ` (anyone can pay) flag, creating three new combined types: - ``SIGHASH_ALL|SIGHASH_ANYONECANPAY`` signs all of the outputs but only this one input, and it also allows anyone to add or remove other inputs, so anyone can contribute additional satoshis but they cannot change how many satoshis are sent nor where they go. @@ -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. @@ -292,7 +292,7 @@ If any of the signers change their mind, they can create a new non-locktime tran Care must be taken near the expiry time of a time lock. The `peer-to-peer network <../devguide/p2p_network.html>`__ allows block time to be up to two hours ahead of real time, so a locktime transaction can be added to the block chain up to two hours before its time lock officially expires. Also, blocks are not created at guaranteed intervals, so any attempt to cancel a valuable transaction should be made a few hours before the time lock expires. -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. +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. @@ -307,15 +307,15 @@ Transaction Fees And Change Transactions pay fees based on the total byte size of the signed transaction. Fees per byte are calculated based on current demand for space in mined blocks with fees rising as demand increases. The transaction fee is given to the Bitcoin miner, as explained in the `block chain section <../devguide/block_chain.html>`__, and so it is ultimately up to each miner to choose the minimum transaction fee they will accept. -There is also a concept of so-called “:term:`high-priority transactions `” which spend satoshis that have not moved for a long time. +There is also a concept of so-called “:term:`high-priority transactions `” which spend satoshis that have not moved for a long time. In the past, these “priority” transaction were often exempt from the normal fee requirements. Before Bitcoin Core 0.12, 50 KB of each block would be reserved for these high-priority transactions, however this is now set to 0 KB by default. After the priority area, all transactions are prioritized based on their fee per byte, with higher-paying transactions being added in sequence until all of the available space is filled. -As of Bitcoin Core 0.9, a :term:`minimum fee ` (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 <../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. 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. -:term:`Change outputs ` are regular outputs which spend the surplus satoshis from the UTXOs back to the spender. They can reuse the same P2PKH pubkey hash or P2SH script hash as was used in the UTXO, but for the reasons described in the `next subsection <../devguide/transactions.html#avoiding-key-reuse>`__, it is highly recommended that change outputs be sent to a new P2PKH or P2SH address. +:term:`Change outputs ` are regular outputs which spend the surplus satoshis from the UTXOs back to the spender. They can reuse the same P2PKH pubkey hash or P2SH script hash as was used in the UTXO, but for the reasons described in the `next subsection <../devguide/transactions.html#avoiding-key-reuse>`__, it is highly recommended that change outputs be sent to a new P2PKH or P2SH address. Avoiding Key Reuse ------------------ @@ -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`\ {:.term}{:#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 `\ {:.term}{:#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 c8d8e58..273deeb 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): @@ -213,13 +213,13 @@ The HD protocol takes advantage of the `ECDSA ` works, it’s possible to create a :term:`child public key ` by combining an existing :term:`(parent) public key ` with another public key created from any integer (*i*) value. This child public key is the same public key which would be created by the :ref:`“point()” ` function if you added the *i* value to the original (parent) private key and then found the remainder of that sum divided by a global constant used by all Bitcoin software (*p*): +Because of the way :ref:`“point()” ` works, it’s possible to create a :term:`child public key ` by combining an existing :term:`(parent) public key ` with another public key created from any integer (*i*) value. This child public key is the same public key which would be created by the :ref:`“point()” ` function if you added the *i* value to the original (parent) private key and then found the remainder of that sum divided by a global constant used by all Bitcoin software (*p*): :: 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,9 +238,9 @@ 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 *parent public key* are regular uncompressed 256-bit `ECDSA `__ keys. -- The :term:`parent chain code ` is 256 bits of seemingly-random data. +- The :term:`parent chain code ` is 256 bits of seemingly-random data. - The :ref:`index ` number is a 32-bit integer specified by the program. @@ -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 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. @@ -292,7 +292,7 @@ The normal key derivation formula, described in the section above, combines toge The hardened formula, illustrated above, combines together the index number, the parent chain code, and the parent private key to create the data used to generate the child chain code and child private key. This formula makes it impossible to create child public keys without knowing the parent private key. In other words, parent extended public keys can’t create hardened child public keys. -Because of that, a :term:`hardened extended private key ` is much less useful than a normal extended private key—however, hardened extended private keys create a firewall through which multi-level key derivation compromises cannot happen. Because hardened child extended public keys cannot generate grandchild chain codes on their own, the compromise of a parent extended public key cannot be combined with the compromise of a grandchild private key to create great-grandchild extended private keys. +Because of that, a :term:`hardened extended private key ` is much less useful than a normal extended private key—however, hardened extended private keys create a firewall through which multi-level key derivation compromises cannot happen. Because hardened child extended public keys cannot generate grandchild chain codes on their own, the compromise of a parent extended public key cannot be combined with the compromise of a grandchild private key to create great-grandchild extended private keys. The HD protocol uses different index numbers to indicate whether a normal or hardened key should be generated. Index numbers from 0x00 to 0x7fffffff (0 to 231-1) will generate a normal key; index numbers from 0x80000000 to 0xffffffff will generate a hardened key. To make descriptions easy, many developers use the `prime symbol `__ to indicate hardened keys, so the first normal key (0x00) is 0 and the first hardened key (0x80000000) is 0´. diff --git a/examples/testing.rst b/examples/testing.rst index 430b7d4..a02076c 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 <../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. 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/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 diff --git a/reference/block_chain.rst b/reference/block_chain.rst index f7bc5a3..0a7b7e4 100644 --- a/reference/block_chain.rst +++ b/reference/block_chain.rst @@ -11,7 +11,7 @@ Block headers are serialized in the 80-byte format described below and then hash +-------+------------------------------------------------------------------------------------------+-----------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Bytes | Name | Data Type | Description | +=======+==========================================================================================+===========+=================================================================================================================================================================================================================================================================================================================================================+ -| 4 | version | int32_t | The :term:`block version ` number indicates which set of block validation rules to follow. See the list of block versions below. | +| 4 | version | int32_t | The :term:`block version ` number indicates which set of block validation rules to follow. See the list of block versions below. | +-------+------------------------------------------------------------------------------------------+-----------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 32 | :ref:`previous block header hash ` | char[32] | A SHA256(SHA256()) hash in internal byte order of the previous block’s header. This ensures no previous block can be changed without also changing this block’s header. | +-------+------------------------------------------------------------------------------------------+-----------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -133,8 +133,8 @@ Under current consensus rules, a block is not valid unless its serialized size i | *Varies* | txns | raw transaction | Every transaction in this block, one after another, in raw transaction format. Transactions must appear in the data stream in the same order their TXIDs appeared in the first row of the merkle tree. See the `merkle tree section <../reference/block_chain.html#merkle-trees>`__ for details. | +----------+--------------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -The first transaction in a block must be a :term:`coinbase transaction` which should collect and spend any transaction fees paid by transactions included in this block. +The first transaction in a block must be a :term:`coinbase transaction ` which should collect and spend any transaction fees paid by transactions included in this block. All blocks with a block height less than 6,930,000 are entitled to receive a block subsidy of newly created bitcoin value, which also should be spent in the coinbase transaction. (The block subsidy started at 50 bitcoins and is being halved every 210,000 blocks—approximately once every four years. As of November 2017, it’s 12.5 bitcoins.) -Together, the transaction fees and block subsidy are called the :term:`block reward`. A coinbase transaction is invalid if it tries to spend more value than is available from the block reward. +Together, the transaction fees and block subsidy are called the :term:`block reward `. A coinbase transaction is invalid if it tries to spend more value than is available from the block reward. diff --git a/reference/p2p_networking.rst b/reference/p2p_networking.rst index 8d06722..488ba3a 100644 --- a/reference/p2p_networking.rst +++ b/reference/p2p_networking.rst @@ -1,7 +1,7 @@ P2P Network ----------- -This section describes the Bitcoin P2P `network <../devguide/p2p_network.html>`__ protocol (but it is `not a specification <../reference/intro.html#not-a-specification>`__). It does not describe the discontinued direct `IP-to-IP payment protocol `__, the :term:`deprecated BIP70 payment protocol `, the `GetBlockTemplate mining protocol <../devguide/mining.html#getblocktemplate-rpc>`__, or any `network <../devguide/p2p_network.html>`__ protocol never implemented in an official version of Bitcoin Core. +This section describes the Bitcoin P2P `network <../devguide/p2p_network.html>`__ protocol (but it is `not a specification <../reference/intro.html#not-a-specification>`__). It does not describe the discontinued direct `IP-to-IP payment protocol `__, the :term:`deprecated BIP70 payment protocol `, the `GetBlockTemplate mining protocol <../devguide/mining.html#getblocktemplate-rpc>`__, or any `network <../devguide/p2p_network.html>`__ protocol never implemented in an official version of Bitcoin Core. All `peer-to-peer <../devguide/p2p_network.html>`__ communication occurs entirely over TCP. @@ -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 | +--------------------------------------------+--------------+------------------------------------------+------------+ @@ -107,7 +107,7 @@ The following `network <../devguide/p2p_network.html>`__ messages all request or Overview Of P2P Protocol Data Request And Reply Messages -Many of the data messages use :term:`inventories ` as unique identifiers for transactions and blocks. Inventories have a simple 36-byte structure: +Many of the data messages use :term:`inventories ` as unique identifiers for transactions and blocks. Inventories have a simple 36-byte structure: +-------+-----------------+-----------+--------------------------------------------------------------------------+ | Bytes | Name | Data Type | Description | diff --git a/reference/transactions.rst b/reference/transactions.rst index 99a0bb4..379d1d6 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 @@ -131,7 +131,7 @@ To convert addresses back into hashes, reverse the base58 encoding, extract the Raw Transaction Format ^^^^^^^^^^^^^^^^^^^^^^ -Bitcoin transactions are broadcast between peers in a serialized byte format, called :term:`raw format `. It is this form of a transaction which is SHA256(SHA256()) hashed to create the TXID and, ultimately, the merkle root of a block containing the transaction—making the transaction format part of the consensus rules. +Bitcoin transactions are broadcast between peers in a serialized byte format, called :term:`raw format `. It is this form of a transaction which is SHA256(SHA256()) hashed to create the TXID and, ultimately, the merkle root of a block containing the transaction—making the transaction format part of the consensus rules. Bitcoin Core and many other tools print and accept raw transactions encoded as hex. @@ -272,9 +272,9 @@ The first transaction in a block, called the coinbase transaction, must have exa +--------------+--------------------+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | *Varies* | script bytes | compactSize uint | The number of bytes in the coinbase script, up to a maximum of 100 bytes. | +--------------+--------------------+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| *Varies* (4) | height | script | The :term:`block height ` of this block as required by `BIP34 `__. Uses script language: starts with a data-pushing opcode that indicates how many bytes to push to the stack followed by the block height as a little-endian unsigned integer. This script must be as short as possible, otherwise it may be rejected. The data-pushing opcode will be 0x03 and the total size four bytes until block 16,777,216 about 300 years from now. | +| *Varies* (4) | height | script | The :term:`block height ` of this block as required by `BIP34 `__. Uses script language: starts with a data-pushing opcode that indicates how many bytes to push to the stack followed by the block height as a little-endian unsigned integer. This script must be as short as possible, otherwise it may be rejected. The data-pushing opcode will be 0x03 and the total size four bytes until block 16,777,216 about 300 years from now. | +--------------+--------------------+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| *Varies* | coinbase script | *None* | The :term:`coinbase field `: Arbitrary data not exceeding 100 bytes minus the (4) height bytes. Miners commonly place an extra nonce in this field to update the block header merkle root during hashing. | +| *Varies* | coinbase script | *None* | The :term:`coinbase field `: Arbitrary data not exceeding 100 bytes minus the (4) height bytes. Miners commonly place an extra nonce in this field to update the block header merkle root during hashing. | +--------------+--------------------+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 4 | sequence | uint32_t | Sequence number. | +--------------+--------------------+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ From e4def0830597b6af26c2f78b4872696aaf6e3ebe Mon Sep 17 00:00:00 2001 From: tushar-1728 Date: Fri, 18 Dec 2020 20:15:31 +0530 Subject: [PATCH 2/5] Added definition for terms in terms.rst All the definitions have been added from test.md file. --- terms.rst | 99 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 50 insertions(+), 49 deletions(-) diff --git a/terms.rst b/terms.rst index 820a43f..209e7e7 100644 --- a/terms.rst +++ b/terms.rst @@ -11,51 +11,51 @@ signature_script_modification_warning (developer-reference) (`original target `__) +term-bitcoin-uri (payment-processing-guide) (`original target `__): A URI which allows receivers to encode payment details so spenders don't have to manually enter addresses and other details. .. _term-certificate-chain: -term-certificate-chain (developer-examples) (`original target `__) +term-certificate-chain (developer-examples) (`original target `__): A chain of certificates connecting a individual's leaf certificate to the certificate authority's root certificate. .. _term-coinbase-block-height: -term-coinbase-block-height (developer-reference) (`original target `__) +term-coinbase-block-height (developer-reference) (`original target `__): The current block's height encoded into the first bytes of the coinbase field. .. _term-fiat: -term-fiat (payment-processing-guide) (`original target `__) +term-fiat (payment-processing-guide) (`original target `__): National currencies such as the dollar or euro. .. _term-intermediate-certificate: -term-intermediate-certificate (developer-examples) (`original target `__) +term-intermediate-certificate (developer-examples) (`original target `__): A intermediate certificate authority certificate which helps connect a leaf (receiver) certificate to a root certificate authority. .. _term-key-index: -term-key-index (wallets-guide) (`original target `__) +term-key-index (wallets-guide) (`original target `__): An index number used in the HD wallet formula to generate child keys from a parent key. .. _term-key-pair: -term-key-pair (transactions-guide) (`original target `__) +term-key-pair (transactions-guide) (`original target `__): A private key and its derived public key. .. _term-label: -term-label (payment-processing-guide) (`original target `__) +term-label (payment-processing-guide) (`original target `__): The label parameter of a bitcoin: URI which provides the spender with the receiver's name (unauthenticated). .. _term-leaf-certificate: -term-leaf-certificate (developer-examples) (`original target `__) +term-leaf-certificate (developer-examples) (`original target `__): The end-node in a certificate chain; in the payment protocol, it is the certificate belonging to the receiver of satoshis. .. _term-merge: -term-merge (payment-processing-guide) (`original target `__) +term-merge (payment-processing-guide) (`original target `__): Spending, in the same transaction, multiple outputs which can be traced back to different previous spenders, leaking information about how many satoshis you control. .. _term-merge-avoidance: -term-merge-avoidance (payment-processing-guide) (`original target `__) +term-merge-avoidance (payment-processing-guide) (`original target `__): A strategy for selecting which outputs to spend that avoids merging outputs with different histories that could leak private information. .. _term-message: -term-message (payment-processing-guide) (`original target `__) +term-message (payment-processing-guide) (`original target `__): A parameter of bitcoin: URIs which allows the receiver to optionally specify a message to the spender. .. _term-micropayment-channel: @@ -63,151 +63,152 @@ term-micropayment-channel (contracts-guide) (`original target `__) +term-msg_block (developer-reference) (`original target `__): The block header hash data type identifier of an inventory on the P2P network. .. _term-msg_cmpct_block: -term-msg_cmpct_block (developer-reference) (`original target `__) +term-msg_cmpct_block (developer-reference) (`original target `__): 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: -term-msg_filtered_witness_block (developer-reference) (`original target `__) +term-msg_filtered_witness_block (developer-reference) (`original target `__): 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: -term-msg_tx (developer-reference) (`original target `__) +term-msg_tx (developer-reference) (`original target `__): The TXID data type identifier of an inventory on the P2P network. .. _term-msg_witness_block: -term-msg_witness_block (developer-reference) (`original target `__) +term-msg_witness_block (developer-reference) (`original target `__): 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: -term-msg_witness_tx (developer-reference) (`original target `__) +term-msg_witness_tx (developer-reference) (`original target `__): 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. .. _term-op-checkmultisig: -term-op-checkmultisig (developer-reference) (`original target `__) +term-op-checkmultisig (developer-reference) (`original target `__): 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: -term-op-checksig (developer-reference) (`original target `__) +term-op-checksig (developer-reference) (`original target `__): Opcode which returns true if a signature signs the correct parts of a transaction and matches a provided public key. .. _term-op-dup: -term-op-dup (developer-reference) (`original target `__) +term-op-dup (developer-reference) (`original target `__): Operation which duplicates the entry below it on the stack. .. _term-op-equal: -term-op-equal (developer-reference) (`original target `__) +term-op-equal (developer-reference) (`original target `__): Operation which returns true if the two entries below it on the stack are equivalent. .. _term-op-equalverify: -term-op-equalverify (developer-reference) (`original target `__) +term-op-equalverify (developer-reference) (`original target `__): Operation which terminates the script in failure unless the two entries below it on the stack are equivalent. .. _term-op-hash160: -term-op-hash160 (developer-reference) (`original target `__) +term-op-hash160 (developer-reference) (`original target `__): Operation which converts the entry below it on the stack into a RIPEMD(SHA256()) hashed version of itself. .. _term-op-return: -term-op-return (developer-reference) (`original target `__) +term-op-return (developer-reference) (`original target `__): Operation which terminates the script in failure. .. _term-op-verify: -term-op-verify (developer-reference) (`original target `__) +term-op-verify (developer-reference) (`original target `__): Operation which terminates the script if the entry below it on the stack is non-true (zero). .. _term-output-index: -term-output-index (transactions-guide) (`original target `__) +term-output-index (transactions-guide) (`original target `__): The sequentially-numbered index of outputs in a single transaction starting from 0. .. _term-paymentdetails: -term-paymentdetails (developer-examples) (`original target `__) +term-paymentdetails (developer-examples) (`original target `__): The PaymentDetails of the payment protocol which allows the receiver to specify the payment details to the spender. .. _term-paymentrequest: -term-paymentrequest (developer-examples) (`original target `__) +term-paymentrequest (developer-examples) (`original target `__): The PaymentRequest of the payment protocol which contains and allows signing of the PaymentDetails. .. _term-pki: -term-pki (developer-examples) (`original target `__) +term-pki (developer-examples) (`original target `__): Public Key Infrastructure; usually meant to indicate the X.509 certificate system used for HTTP Secure (https). .. _term-point-function: -term-point-function (wallets-guide) (`original target `__) +term-point-function (wallets-guide) (`original target `__): The ECDSA function used to create a public key from a private key. .. _term-pp-amount: -term-pp-amount (developer-examples) (`original target `__) +term-pp-amount (developer-examples) (`original target `__): 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. .. _term-pp-expires: -term-pp-expires (developer-examples) (`original target `__) +term-pp-expires (developer-examples) (`original target `__): The expires field of a PaymentDetails where the receiver tells the spender when the PaymentDetails expires. .. _term-pp-memo: -term-pp-memo (developer-examples) (`original target `__) +term-pp-memo (developer-examples) (`original target `__): The memo fields of PaymentDetails, Payment, and PaymentACK which allow spenders and receivers to send each other memos. .. _term-pp-merchant-data: -term-pp-merchant-data (developer-examples) (`original target `__) +term-pp-merchant-data (developer-examples) (`original target `__): 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. .. _term-pp-pki-data: -term-pp-pki-data (developer-examples) (`original target `__) +term-pp-pki-data (developer-examples) (`original target `__): The pki_data field of a PaymentRequest which provides details such as certificates necessary to validate the request. .. _term-pp-pki-type: -term-pp-pki-type (developer-examples) (`original target `__) +term-pp-pki-type (developer-examples) (`original target `__): The PKI field of a PaymentRequest which tells spenders how to validate this request as being from a specific recipient. .. _term-pp-script: -term-pp-script (developer-examples) (`original target `__) +term-pp-script (developer-examples) (`original target `__): The script field of a PaymentDetails where the receiver tells the spender what pubkey scripts to pay. .. _term-previous-block-header-hash: -term-previous-block-header-hash (developer-reference) (`original target `__) +term-previous-block-header-hash (developer-reference) (`original target `__): A field in the block header which contains the SHA256(SHA256()) hash of the previous block's header. .. _term-r-parameter: -term-r-parameter (payment-processing-guide) (`original target `__) +term-r-parameter (payment-processing-guide) (`original target `__): The payment request parameter in a bitcoin: URI. .. _term-receipt: -term-receipt (payment-processing-guide) (`original target `__) +term-receipt (payment-processing-guide) (`original target `__): A cryptographically-verifiable receipt created using parts of a payment request and a confirmed transaction. .. _term-root-certificate: -term-root-certificate (developer-examples) (`original target `__) +term-root-certificate (developer-examples) (`original target `__): +A certificate belonging to a certificate authority (CA). .. _term-ssl-signature: -term-ssl-signature (developer-examples) (`original target `__) +term-ssl-signature (developer-examples) (`original target `__): Signatures created and recognized by major SSL implementations such as OpenSSL. .. _term-standard-block-relay: -term-standard-block-relay (p2p-network-guide) (`original target `__) +term-standard-block-relay (p2p-network-guide) (`original target `__): The regular block relay method: announcing a block with an inv message and waiting for a response. .. _term-transaction-version-number: -term-transaction-version-number (transactions-guide) (`original target `__) +term-transaction-version-number (transactions-guide) (`original target `__): A version number prefixed to transactions to allow upgrading. .. _term-unique-address: -term-unique-address (transactions-guide) (`original target `__) +term-unique-address (transactions-guide) (`original target `__): Address which are only used once to protect privacy and increase security. .. _term-unsolicited-block-push: -term-unsolicited-block-push (p2p-network-guide) (`original target `__) +term-unsolicited-block-push (p2p-network-guide) (`original target `__): When a miner sends a block message without sending an inv message first. .. _term-uri-qr-code: -term-uri-qr-code (payment-processing-guide) (`original target `__) +term-uri-qr-code (payment-processing-guide) (`original target `__): A QR code containing a bitcoin: URI. .. _term-v2-block: -term-v2-block (developer-reference) (`original target `__) +term-v2-block (developer-reference) (`original target `__): The current version of Bitcoin blocks. .. _term-x509certificates: From b8607ee1978177c8b882d426a84d963aeb54664d Mon Sep 17 00:00:00 2001 From: tushar-1728 Date: Fri, 18 Dec 2020 20:19:35 +0530 Subject: [PATCH 3/5] Modified .gitignore and performed grammatical corrections in test.md --- .gitignore | 3 +- test.md | 102 ++++++++++++++++++++++++++--------------------------- 2 files changed, 53 insertions(+), 52 deletions(-) diff --git a/.gitignore b/.gitignore index e35d885..3f52b55 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ -_build +_build/ +.vscode diff --git a/test.md b/test.md index 3793610..300e92c 100644 --- a/test.md +++ b/test.md @@ -25,66 +25,66 @@ definition of the term will be displayed in a tooltip. -[bitcoin URI]: /en/developer-guide#term-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]: /en/developer-examples#term-certificate-chain "A chain of certificates connecting a individual's leaf certificate to the certificate authority's root certificate" -[coinbase block height]: /en/developer-reference#term-coinbase-block-height "The current block's height encoded into the first bytes of the coinbase field" -[data-pushing opcode]: https://en.bitcoin.it/wiki/Script#Constants "Any opcode from 0x01 to 0x4e which pushes data on to the script evaluation stack" -[fiat]: /en/developer-guide#term-fiat "National currencies such as the dollar or euro" -[intermediate certificate]: /en/developer-examples#term-intermediate-certificate "A intermediate certificate authority certificate which helps connect a leaf (receiver) certificate to a root certificate authority" -[key index]: /en/developer-guide#term-key-index "An index number used in the HD wallet formula to generate child keys from a parent key" -[key pair]: /en/developer-guide#term-key-pair "A private key and its derived public key" -[label]: /en/developer-guide#term-label "The label parameter of a bitcoin: URI which provides the spender with the receiver's name (unauthenticated)" -[leaf certificate]: /en/developer-examples#term-leaf-certificate "The end-node in a certificate chain; in the payment protocol, it is the certificate belonging to the receiver of satoshis" -[merge]: /en/developer-guide#term-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]: /en/developer-guide#term-merge-avoidance "A strategy for selecting which outputs to spend that avoids merging outputs with different histories that could leak private information" -[message]: /en/developer-guide#term-message "A parameter of bitcoin: URIs which allows the receiver to optionally specify a message to the spender" -[msg_tx]: /en/developer-reference#term-msg_tx "The TXID data type identifier of an inventory on the P2P network" -[msg_block]: /en/developer-reference#term-msg_block "The block header hash data type identifier of an inventory on the P2P network" -[msg_filtered_block]: /en/developer-reference#term-msg_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_cmpct_block]: /en/developer-reference#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" -[msg_witness_block]: /en/developer-reference#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" -[msg_witness_tx]: /en/developer-reference#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" +[bitcoin URI]: /en/developer-guide#term-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]: /en/developer-examples#term-certificate-chain "A chain of certificates connecting a individual's leaf certificate to the certificate authority's root certificate." +[coinbase block height]: /en/developer-reference#term-coinbase-block-height "The current block's height encoded into the first bytes of the coinbase field." +[data-pushing opcode]: https://en.bitcoin.it/wiki/Script#Constants "Any opcode from 0x01 to 0x4e which pushes data on to the script evaluation stack." +[fiat]: /en/developer-guide#term-fiat "National currencies such as the dollar or euro." +[intermediate certificate]: /en/developer-examples#term-intermediate-certificate "A intermediate certificate authority certificate which helps connect a leaf (receiver) certificate to a root certificate authority." +[key index]: /en/developer-guide#term-key-index "An index number used in the HD wallet formula to generate child keys from a parent key." +[key pair]: /en/developer-guide#term-key-pair "A private key and its derived public key." +[label]: /en/developer-guide#term-label "The label parameter of a bitcoin: URI which provides the spender with the receiver's name (unauthenticated)." +[leaf certificate]: /en/developer-examples#term-leaf-certificate "The end-node in a certificate chain; in the payment protocol, it is the certificate belonging to the receiver of satoshis." +[merge]: /en/developer-guide#term-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]: /en/developer-guide#term-merge-avoidance "A strategy for selecting which outputs to spend that avoids merging outputs with different histories that could leak private information." +[message]: /en/developer-guide#term-message "A parameter of bitcoin: URIs which allows the receiver to optionally specify a message to the spender." +[msg_tx]: /en/developer-reference#term-msg_tx "The TXID data type identifier of an inventory on the P2P network." +[msg_block]: /en/developer-reference#term-msg_block "The block header hash data type identifier of an inventory on the P2P network." +[msg_filtered_block]: /en/developer-reference#term-msg_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_cmpct_block]: /en/developer-reference#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." +[msg_witness_block]: /en/developer-reference#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." +[msg_witness_tx]: /en/developer-reference#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." [msg_filtered_witness_block]: /en/developer-reference#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." [network]: /en/developer-guide#term-network "The Bitcoin P2P network which broadcasts transactions and blocks" -[op_checkmultisig]: /en/developer-reference#term-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]: /en/developer-reference#term-op-checksig "Opcode which returns true if a signature signs the correct parts of a transaction and matches a provided public key" -[op_dup]: /en/developer-reference#term-op-dup "Operation which duplicates the entry below it on the stack" -[op_equal]: /en/developer-reference#term-op-equal "Operation which returns true if the two entries below it on the stack are equivalent" -[op_equalverify]: /en/developer-reference#term-op-equalverify "Operation which terminates the script in failure unless the two entries below it on the stack are equivalent" -[op_hash160]: /en/developer-reference#term-op-hash160 "Operation which converts the entry below it on the stack into a RIPEMD(SHA256()) hashed version of itself" -[op_return]: /en/developer-reference#term-op-return "Operation which terminates the script in failure" -[op_verify]: /en/developer-reference#term-op-verify "Operation which terminates the script if the entry below it on the stack is non-true (zero)" -[output index]: /en/developer-guide#term-output-index "The sequentially-numbered index of outputs in a single transaction starting from 0" -[PaymentDetails]: /en/developer-examples#term-paymentdetails "The PaymentDetails of the payment protocol which allows the receiver to specify the payment details to the spender" -[PaymentRequest]: /en/developer-examples#term-paymentrequest "The PaymentRequest of the payment protocol which contains and allows signing of the PaymentDetails" -[PaymentRequests]: /en/developer-examples#term-paymentrequest "The PaymentRequest of the payment protocol which contains and allows signing of the PaymentDetails" +[op_checkmultisig]: /en/developer-reference#term-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]: /en/developer-reference#term-op-checksig "Opcode which returns true if a signature signs the correct parts of a transaction and matches a provided public key." +[op_dup]: /en/developer-reference#term-op-dup "Operation which duplicates the entry below it on the stack." +[op_equal]: /en/developer-reference#term-op-equal "Operation which returns true if the two entries below it on the stack are equivalent." +[op_equalverify]: /en/developer-reference#term-op-equalverify "Operation which terminates the script in failure unless the two entries below it on the stack are equivalent." +[op_hash160]: /en/developer-reference#term-op-hash160 "Operation which converts the entry below it on the stack into a RIPEMD(SHA256()) hashed version of itself." +[op_return]: /en/developer-reference#term-op-return "Operation which terminates the script in failure." +[op_verify]: /en/developer-reference#term-op-verify "Operation which terminates the script if the entry below it on the stack is non-true (zero)." +[output index]: /en/developer-guide#term-output-index "The sequentially-numbered index of outputs in a single transaction starting from 0." +[PaymentDetails]: /en/developer-examples#term-paymentdetails "The PaymentDetails of the payment protocol which allows the receiver to specify the payment details to the spender." +[PaymentRequest]: /en/developer-examples#term-paymentrequest "The PaymentRequest of the payment protocol which contains and allows signing of the PaymentDetails." +[PaymentRequests]: /en/developer-examples#term-paymentrequest "The PaymentRequest of the payment protocol which contains and allows signing of the PaymentDetails." [PKI]: /en/developer-examples#term-pki "Public Key Infrastructure; usually meant to indicate the X.509 certificate system used for HTTP Secure (https)." -[point function]: /en/developer-guide#term-point-function "The ECDSA function used to create a public key from a private key" -[pp amount]: /en/developer-examples#term-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]: /en/developer-examples#term-pp-expires "The expires field of a PaymentDetails where the receiver tells the spender when the PaymentDetails expires" -[pp memo]: /en/developer-examples#term-pp-memo "The memo fields of PaymentDetails, Payment, and PaymentACK which allow spenders and receivers to send each other memos" -[pp merchant data]: /en/developer-examples#term-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]: /en/developer-examples#term-pp-pki-data "The pki_data field of a PaymentRequest which provides details such as certificates necessary to validate the request" -[pp pki type]: /en/developer-examples#term-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]: /en/developer-examples#term-pp-script "The script field of a PaymentDetails where the receiver tells the spender what pubkey scripts to pay" -[previous block header hash]: /en/developer-reference#term-previous-block-header-hash "A field in the block header which contains the SHA256(SHA256()) hash of the previous block's header" -[proper money handling]: /en/developer-reference#term-proper-money-handling "Bitcoin amounts need to be correctly processed without introducing rounding errors that could cause monetary loss" -[r]: /en/developer-guide#term-r-parameter "The payment request parameter in a bitcoin: URI" -[receipt]: /en/developer-guide#term-receipt "A cryptographically-verifiable receipt created using parts of a payment request and a confirmed transaction" +[point function]: /en/developer-guide#term-point-function "The ECDSA function used to create a public key from a private key." +[pp amount]: /en/developer-examples#term-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]: /en/developer-examples#term-pp-expires "The expires field of a PaymentDetails where the receiver tells the spender when the PaymentDetails expires." +[pp memo]: /en/developer-examples#term-pp-memo "The memo fields of PaymentDetails, Payment, and PaymentACK which allow spenders and receivers to send each other memos." +[pp merchant data]: /en/developer-examples#term-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]: /en/developer-examples#term-pp-pki-data "The pki_data field of a PaymentRequest which provides details such as certificates necessary to validate the request." +[pp pki type]: /en/developer-examples#term-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]: /en/developer-examples#term-pp-script "The script field of a PaymentDetails where the receiver tells the spender what pubkey scripts to pay." +[previous block header hash]: /en/developer-reference#term-previous-block-header-hash "A field in the block header which contains the SHA256(SHA256()) hash of the previous block's header." +[proper money handling]: /en/developer-reference#term-proper-money-handling "Bitcoin amounts need to be correctly processed without introducing rounding errors that could cause monetary loss." +[r]: /en/developer-guide#term-r-parameter "The payment request parameter in a bitcoin: URI." +[receipt]: /en/developer-guide#term-receipt "A cryptographically-verifiable receipt created using parts of a payment request and a confirmed transaction." [recurrent rebilling]: /en/developer-guide#rebilling-recurring-payments "Billing a spender on a regular schedule" [refund]: /en/developer-guide#issuing-refunds "A transaction which refunds some or all satoshis received in a previous transaction" -[root certificate]: /en/developer-examples#term-root-certificate "A certificate belonging to a certificate authority (CA)" -[ssl signature]: /en/developer-examples#term-ssl-signature "Signatures created and recognized by major SSL implementations such as OpenSSL" -[standard block relay]: /en/developer-guide#term-standard-block-relay "The regular block relay method: announcing a block with an inv message and waiting for a response" +[root certificate]: /en/developer-examples#term-root-certificate "A certificate belonging to a certificate authority (CA)." +[ssl signature]: /en/developer-examples#term-ssl-signature "Signatures created and recognized by major SSL implementations such as OpenSSL." +[standard block relay]: /en/developer-guide#term-standard-block-relay "The regular block relay method: announcing a block with an inv message and waiting for a response." [transaction]: /en/developer-guide#transactions "A transaction spending satoshis" -[transaction version number]: /en/developer-guide#term-transaction-version-number "A version number prefixed to transactions to allow upgrading"" +[transaction version number]: /en/developer-guide#term-transaction-version-number "A version number prefixed to transactions to allow upgrading." [transactions]: /en/developer-guide#transactions "A transaction spending satoshis" [unencrypted wallet]: /en/developer-reference#encryptwallet "A wallet that has not been encrypted with the encryptwallet RPC" -[unique addresses]: /en/developer-guide#term-unique-address "Address which are only used once to protect privacy and increase security" +[unique addresses]: /en/developer-guide#term-unique-address "Address which are only used once to protect privacy and increase security." [unlocked wallet]: /en/developer-reference#walletpassphrase "An encrypted wallet that has been unlocked with the walletpassphrase RPC" -[unsolicited block push]: /en/developer-guide#term-unsolicited-block-push "When a miner sends a block message without sending an inv message first" -[URI QR Code]: /en/developer-guide#term-uri-qr-code "A QR code containing a bitcoin: URI" -[v2 block]: /en/developer-reference#term-v2-block "The current version of Bitcoin blocks" +[unsolicited block push]: /en/developer-guide#term-unsolicited-block-push "When a miner sends a block message without sending an inv message first." +[URI QR Code]: /en/developer-guide#term-uri-qr-code "A QR code containing a bitcoin: URI." +[v2 block]: /en/developer-reference#term-v2-block "The current version of Bitcoin blocks." [verified payments]: /en/developer-guide#verifying-payment "Payments which the receiver believes won't be double spent" [wallet support]: /en/developer-reference#term-wallet-support "A Bitcoin Core ./configure option that enables (default) or disables the wallet" [prefilledtransaction]: /en/developer-reference#cmpctblock "A P2P Networking data structure used to represent a vector of a few transactions" From 46afe760ebc767483eb0fb2824e6660093bc2207 Mon Sep 17 00:00:00 2001 From: tushar-1728 Date: Fri, 18 Dec 2020 21:08:03 +0530 Subject: [PATCH 4/5] 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 c4e799cd839a0bd7fbf13e130cecb5951723010d Mon Sep 17 00:00:00 2001 From: tushar-1728 Date: Tue, 19 Jan 2021 12:14:06 +0530 Subject: [PATCH 5/5] Removed the extraneous part '\ {:.term}{:#term-transaction-malleability}' --- devguide/transactions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/devguide/transactions.rst b/devguide/transactions.rst index 8f30f5f..b743325 100644 --- a/devguide/transactions.rst +++ b/devguide/transactions.rst @@ -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 `\ {:.term}{:#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.