Enforced 1-sentence per line for existing pages.

All pages except BIPs are conform to 1-sentence per line.
This commit is contained in:
Josh Green
2019-12-22 17:37:40 -05:00
committed by bitcoin
parent 0d0a122c8f
commit 48f022edfa
10 changed files with 162 additions and 63 deletions
+18 -8
View File
@@ -1,22 +1,32 @@
# Block # Block
A block is a collection of transactions that have been committed to the blockchain as a bundle. The transactions do not necessarily have to be related to one another and, generally, are only associated by virtue of when they were submitted to the Bitcoin Cash network. A block is a collection of transactions that have been committed to the blockchain as a bundle.
The transactions do not necessarily have to be related to one another and, generally, are only associated by virtue of when they were submitted to the Bitcoin Cash network.
Every block contains one coinbase transaction, followed by zero or more additional transactions. The coinbase transaction is created by the miner of the block and provides an opportunity for them to receive the block reward for successfully mining a block, along with any fees collected from the transactions in the block. For more information, see [Mining](/protocol/mining). Every block contains one coinbase transaction, followed by zero or more additional transactions.
The coinbase transaction is created by the miner of the block and provides an opportunity for them to receive the block reward for successfully mining a block, along with any fees collected from the transactions in the block.
For more information, see [Mining](/protocol/mining).
## Block Headers ## Block Headers
Block are identified by the SHA-256 hash of their header. Since the block header contains the root of a [merkle tree](/protocol/blockchain/merkle-tree) of the transactions in the block, this means the hash is ultimately dependent on both the meta-information about the block as well as the full contents of all of its component transactions. For more information see [Block Header](/protocol/blockchain/block/block-header). Block are identified by the SHA-256 hash of their header.
Since the block header contains the root of a [Merkle Tree](/protocol/blockchain/merkle-tree) of the transactions in the block, this means the hash is ultimately dependent on both the meta-information about the block as well as the full contents of all of its component transactions.
For more information see [Block Header](/protocol/blockchain/block/block-header).
## Coinbase Transaction ## Coinbase Transaction
The coinbase transaction provides a mechanism for miners to: The coinbase transaction provides a mechanism for miners to:
- Receive payment for mining - Receive payment for mining.
- Include a message, known as the "coinbase message," or simply "coinbase," within the block - Include a message, known as the "coinbase message," or simply "coinbase," within the block.
To accomplish this, the coinbase transaction is required to have a single input. However, unlike other transactions, this input is not expected to provide the satoshis that appear in the outputs. Instead, the satoshis that appear in the outputs of the coinbase transaction are collected from two places: the block reward and transactions fees. To accomplish this, the coinbase transaction is required to have a single input.
However, unlike other transactions, this input is not expected to provide the satoshis that appear in the outputs.
Instead, the satoshis that appear in the outputs of the coinbase transaction are collected from two places: the block reward and transactions fees.
The block reward is provided automatically to the block and represents a continually decreasing incentive for miners. The block reward started at 5,000,000,000 satoshis (50 BCH) and decreases by half every 210,000 blocks. The block reward is provided automatically to the block and represents a continually decreasing incentive for miners.
The block reward started at 5,000,000,000 satoshis (50 BCH) and decreases by half every 210,000 blocks.
Transaction fees are often required by the network for transactions to be relayed across the network. Satoshis provided as inputs to a transaction, but not consumed by its outputs, are collected by the coinbase transaction as implicit inputs. Transaction fees are often required by the network for transactions to be relayed across the network.
Satoshis provided as inputs to a transaction, but not consumed by its outputs, are collected by the coinbase transaction as implicit inputs.
+13 -9
View File
@@ -1,12 +1,14 @@
# Block Header # Block Header
Block headers serve an important intermediary role in the creation and transmission of blocks. They are a fixed-width (80-byte) representation of the entire block. With a block header, you can: Block headers serve an important intermediary role in the creation and transmission of blocks.
They are a fixed-width (80-byte) representation of the entire block.
With a block header, you can:
1. Calculate the hash of the block 1. Calculate the hash of the block.
- The double SHA-256 hash of the block header - The double SHA-256 hash of the block header.
2. Confirm the proof of work was executed correctly 2. Confirm the proof of work was executed correctly.
- See [Difficulty Adjustment Algorithm](/protocol/blockchain/proof-of-work/difficulty-adjustment-algorithm) for more details - See [Difficulty Adjustment Algorithm](/protocol/blockchain/proof-of-work/difficulty-adjustment-algorithm) for more details.
3. Determine the relative location of the block in the blockchain 3. Determine the relative location of the block in the blockchain.
- Using the previous block hash contained in the header - Using the previous block hash contained in the header
Since validation of all the transactions in the block can be expensive, the ability to perform these checks on the block before downloading and validating its transactions helps make denial-of-service attacks on the network significantly more expensive for attackers. Since validation of all the transactions in the block can be expensive, the ability to perform these checks on the block before downloading and validating its transactions helps make denial-of-service attacks on the network significantly more expensive for attackers.
@@ -24,11 +26,13 @@ Since validation of all the transactions in the block can be expensive, the abil
### Difficulty Target Encoding ### Difficulty Target Encoding
Within the block header, the difficulty target uses a special floating-point representation that helps keep the size of the block header small. While the [Difficulty Adjustment Algorithm](/protocol/blockchain/proof-of-work/difficulty-adjustment-algorithm) attempts to calculate the ideal target (i.e. the value the block hash must be "less than"), it undergoes a lossy conversion when put in the block header: Within the block header, the difficulty target uses a special floating-point representation that helps keep the size of the block header small.
While the [Difficulty Adjustment Algorithm](/protocol/blockchain/proof-of-work/difficulty-adjustment-algorithm) attempts to calculate the ideal target (i.e. the value the block hash must be "less than"), it undergoes a lossy conversion when put in the block header:
| Field | Length | Format | Description | | Field | Length | Format | Description |
|--|--|--|--| |--|--|--|--|
| exponent | 1 byte | byte | Used to calculate the offset for the signficand. The actual exponent is <code>8 * (exponent - 3)</code>. | | exponent | 1 byte | byte | Used to calculate the offset for the signficand. The actual exponent is `8 * (exponent - 3)`. |
| significand | 3 byte | bytes | The significand, or mantissa, of the value. | | significand | 3 byte | bytes | The significand, or mantissa, of the value. |
Ultimately, the difficulty target is equal to: <code>significand * 2<sup>(8 * (exponent - 3))</sup></code> Ultimately, the difficulty target is equal to:
<pre>significand * 2<sup>(8 * (exponent - 3))</sup></pre>
+9 -4
View File
@@ -1,9 +1,14 @@
# Merkle Tree # Merkle Tree
A [merkle tree](https://en.wikipedia.org/wiki/Merkle_tree) is a data structure designed to build a hash of many separate pieces of data and allowing efficient recalculation of the hash when items are added, removed, or changed. A [Merkle Tree](https://en.wikipedia.org/wiki/Merkle_tree) is a data structure designed to build a hash of many separate pieces of data and allowing efficient recalculation of the hash when items are added, removed, or changed.
In Bitcoin Cash, the transactions in a [block](/protocol/blockchain/block) are built into a merkle tree. The root of this tree, or **merkle root**, is a hash representing a compound, indirect hash of all of the items added to the merkle tree (i.e. transactions) and is included in the [block header](/protocol/blockchain/block/block-header), ensuring the block hash is dependent (indirectly) on all of the transactions that are included in the block. In Bitcoin Cash, the transactions in a [Block](/protocol/blockchain/block) are built into a Merkle Tree.
The root of this tree, or *Merkle Root*, is a hash representing a compound, indirect hash of all of the items added to the Merkle Tree (i.e. transactions) and is included in the [Block Header](/protocol/blockchain/block/block-header), ensuring the block hash is dependent (indirectly) on all of the transactions that are included in the block.
Using a merkle tree to manage hashing the transactions in a block enables efficient addition of newly submitted transactions to a block being mined. Rather than re-hashing the entirety of the data of the transactions to be included in the block, the new transaction can be hash and then a small number of hashes can be recalculated, leading up to the merkle root. For large blocks this can heavily reduce the amount of data to be (re-)hashed. Using a Merkle Tree to manage hashing the transactions in a Block enables efficient addition of newly submitted Transactions to a Block being mined.
Rather than re-hashing the entirety of the data of the Transactions to be included in the Block, the new Transaction can be hashed and then a small number of hashes can be recalculated, leading up to the Merkle Root.
For large Blocks this can heavily reduce the amount of data to be (re-)hashed.
Using merkle trees also allows for transferring only a subset of a block while still providing confidence that the data provided in fact appeared in the block in question. For more information, see [Merkle Block](/protocol/network/messages/merkleblock). Using Merkle Trees also allows for transferring only a subset of a Block while still providing confidence that the data provided in fact appeared in the Block in question.
For more information, see [Merkle Block](/protocol/network/messages/merkleblock).
@@ -1,11 +1,19 @@
# Transaction Ordering # Transaction Ordering
Transactions in a block are inherently ordered by virtue of their inclusion in the [merkle tree](/protocol/blockchain/block/merkle-tree). Furthermore, the [coinbase transaction](/protocol/blockchain/block#coinbase-transaction) is required to be first in the block. After that, the order of any remaining transactions in the block is dependent on when that block was mined. For new blocks, the [canonical transaction ordering](#canonical-transaction-ordering) rule is in effect. For old blocks, see [topological transaction ordering](#legacy-transaction-ordering). Transactions in a Block are inherently ordered by virtue of their inclusion in the [Merkle Tree](/protocol/blockchain/block/merkle-tree).
Furthermore, the [Coinbase Transaction](/protocol/blockchain/block#coinbase-transaction) is required to be the first Transaction in the Block.
After that, the order of any remaining Transactions in the block is dependent on when that Block was mined. For new blocks, the [Canonical Transaction Ordering](#canonical-transaction-ordering) rule is in effect.
For historic blocks, see [Topological Transaction Ordering](#legacy-transaction-ordering).
## Canonical Transaction Ordering ## Canonical Transaction Ordering
With canonical transaction ordering, or CTOR, the transactions after the coinbase transaction are required to be sorted in lexicographical order by transaction hash. New blocks will not be accepted by the network unless they follow this constraint. CTOR went into effect at 1542300000 unix time (November 15, 2018 4:40:00 PM GMT). See [HF20181115](/protocol/forks/HF20181115) for more information on this change. With canonical transaction ordering (CTOR), the Transactions after the Coinbase Transaction are required to be sorted in lexicographical order by Transaction Hash.
New Blocks will not be accepted by the network unless they follow this constraint.
CTOR went into effect at 1542300000 unix time (November 15, 2018 4:40:00 PM GMT).
See [HF20181115](/protocol/forks/HF20181115) for more information on this change.
## Topological Transaction Ordering ## Topological Transaction Ordering
With topological transaction ordering, transactions after the coinbase transaction were required to abide by the following constraint: if a transaction B spends outputs created by transaction A, transaction B must appear after transaction A in the block. Otherwise, transactions could appear in any order. With topological transaction ordering, Transactions after the Coinbase Transaction were required to abide by the following constraint: if a transaction B spends outputs created by transaction A, transaction B must appear after transaction A in the block.
Otherwise, transactions could appear in any order.
+10 -2
View File
@@ -1,7 +1,15 @@
# Script # Script
Bitcoin Cash transactions make use of a scripting language to authorize and secure transfers. While, colloquially, there is a tendency to refer to transactions as "sending" Bitcoin Cash to "an address", that is merely an abstraction. In fact, the only thing that permits the spending of existing [UTXOs](/protocol/blockchain/transaction#transaction-outputs) is the successful execution of a script. The only thing preventing the spending of newly created UTXOs is the difficulty of producing a successfully executing script. Through the use of cryptographic signatures and hash functions, such scripts are often designed specifically to be difficult to produce unless you are the intended spender of a given UTXO, though that need not necessarily be the case. For more information on how transactions are commonly secured, see [Locking Script](/protocol/blockchain/transaction/locking-script). For the purposes of this page, we will be focusing more on how the scripts are run, what they are capable of, and what limitations they have. Bitcoin Cash transactions make use of a scripting language to authorize and secure transfers.
While, colloquially, there is a tendency to refer to transactions as "sending" Bitcoin Cash to "an address", that is merely an abstraction.
In fact, the only thing that permits the spending of existing [UTXOs](/protocol/blockchain/transaction#transaction-outputs) is the successful execution of a script.
The only thing preventing the spending of newly created UTXOs is the difficulty of producing a successfully executing script.
Through the use of cryptographic signatures and hash functions, such scripts are often designed specifically to be difficult to produce unless you are the intended spender of a given UTXO, though that need not necessarily be the case.
For more information on how Transactions are commonly secured, see [Locking Script](/protocol/blockchain/transaction/locking-script).
This page will focus on how the scripts are run, what they are capable of, and what limitations they have.
## Script Execution ## Script Execution
Scripts are executed using a stack-based memory model Scripts are executed using a stack-based memory model.
@@ -1,14 +1,21 @@
# Locking Script # Locking Script
A locking script is a [Script](/protocol/blockchain/script) that is used dictate how funds can be spent in the future. Locking scripts do this by defining a set of operations that must end in a successful script execution. The rest of the script execution is to be provided in an [unlocking script](/protocol/blockchain/transaction/unlocking-script) in a future transaction's input. Every locking script is executed after the unlocking script. If the unlocking script were run second, it could end by removing any values currently on the stack and replacing it with a success value. For more information about how script execution works, see [Script](/protocol/blockchain/script). A locking script is a [Script](/protocol/blockchain/script) that is used dictate how funds can be spent in the future.
Locking scripts do this by defining a set of operations that must end in a successful script execution.
The rest of the script execution is to be provided in an [unlocking script](/protocol/blockchain/transaction/unlocking-script) in a future transaction's input.
Every locking script is executed after the unlocking script.
If the unlocking script were run second, it could end by removing any values currently on the stack and replacing it with a success value.
For more information about how script execution works, see [Script](/protocol/blockchain/script).
## Standard Scripts ## Standard Scripts
The below locking script formats are regarded as "standard" on the Bitcoin Cash network and, as a result, are the three forms of transactions that will be relayed among nodes for mining. It is possible to have transactions without these standard locking script formats mined into a block, but such transactions are at a disadvantage due since they will not be as widely propagated. The below locking script formats are regarded as "standard" on the Bitcoin Cash network and, as a result, are the three forms of transactions that will be relayed among nodes for mining.
It is possible to have transactions without these standard locking script formats mined into a block, but such transactions are at a disadvantage due since they will not be as widely propagated.
### Pay to Public Key (P2PK) <img src="/_static_/images/warning.png" /> ### Pay to Public Key (P2PK) <img src="/_static_/images/warning.png" />
The P2PK locking script expects the unlocking script to push a signature to the stack. If the signature is valid for the specified public key in the locking script, the output is allowed to be spent. The P2PK locking script expects the unlocking script to push a signature to the stack.
If the signature is valid for the specified public key in the locking script, the output is allowed to be spent.
| Operation | Description | | Operation | Description |
|--|--| |--|--|
@@ -18,12 +25,16 @@ The P2PK locking script expects the unlocking script to push a signature to the
<img src="/_static_/images/warning.png" /> **NOTE:** Pay to Public Key is a largely obsolete type of locking script due to its property of leaking the public key of the recipient before the output is unlocked, resulting in: <img src="/_static_/images/warning.png" /> **NOTE:** Pay to Public Key is a largely obsolete type of locking script due to its property of leaking the public key of the recipient before the output is unlocked, resulting in:
1. More data to be transferred to request funds, since a public key is larger than the addresses used in other standard scripts. 1. More data to be transferred to request funds, since a public key is larger than the addresses used in other standard scripts.
2. Decreased security in the event of a break in the ECDSA signature algorithm. That is, if it ever becomes possible to create a signature using a public key (not currently known to be possible), the public key is readily available. 2. Decreased security in the event of a break in the ECDSA signature algorithm.
That is, if it ever becomes possible to create a signature using a public key (not currently known to be possible), the public key is readily available.
3. Decreased privacy for the recipient, since anyone aware of who owns the public key knows that they can spend the locked funds. 3. Decreased privacy for the recipient, since anyone aware of who owns the public key knows that they can spend the locked funds.
### Pay to Public Key Hash (P2PKH) ### Pay to Public Key Hash (P2PKH)
Pay to Public Key Hash is a widely used standard locking script format, that works similarly to P2PK but instead of pushing the public key, it pushes a hash of the public key, commonly referred to as an address. This heavily reduces the risks associated with a plain P2PK script as the hashing algorithms used provide a considerable barrier to determining the public key a priori. To spend an output locked with this type of script, the unlocking script is expected to push a signature and then the public key corresponding to the private key that created the signature. If that public key hashes to the expected address, and the signature is valid, the output is allowed to be spent. Pay to Public Key Hash is a widely used standard locking script format, that works similarly to P2PK but instead of pushing the public key, it pushes a hash of the public key, commonly referred to as an address.
This heavily reduces the risks associated with a plain P2PK script as the hashing algorithms used provide a considerable barrier to determining the public key a priori.
To spend an output locked with this type of script, the unlocking script is expected to push a signature and then the public key corresponding to the private key that created the signature.
If that public key hashes to the expected address, and the signature is valid, the output is allowed to be spent.
| Operation | Description | | Operation | Description |
|--|--| |--|--|
@@ -35,7 +46,10 @@ Pay to Public Key Hash is a widely used standard locking script format, that wor
### Pay to Script Hash (P2SH) ### Pay to Script Hash (P2SH)
Pay to Script Hash is used to require the spender of an output to include a specific set of operations in their unlocking script. To achieve this, the unlocking script is expected to end by pushing data to the stack that is the expected script to be executed. Once this data is verified to match the expected script hash, this internal script, commonly referred to as the redeem script, is executed on the pre-locking-script-execution stack. If this redeem script finishes execution successfully, the output is allowed to be spent. Pay to Script Hash is used to require the spender of an output to include a specific set of operations in their unlocking script.
To achieve this, the unlocking script is expected to end by pushing data to the stack that is the expected script to be executed.
Once this data is verified to match the expected script hash, this internal script, commonly referred to as the redeem script, is executed on the pre-locking-script-execution stack.
If this redeem script finishes execution successfully, the output is allowed to be spent.
| Operation | Description | | Operation | Description |
|--|--| |--|--|
@@ -45,15 +59,27 @@ Pay to Script Hash is used to require the spender of an output to include a spec
Due to the nature of this type of locking script, the following steps must be performed by a node executing this script: Due to the nature of this type of locking script, the following steps must be performed by a node executing this script:
1. After executing the unlocking scripts, create a copy of the stack for later use. Since the value at the top of the stack (the redeem script) will be consumed by the locking script, we want to return to this state after verifying that the hash is correct. 1. After executing the unlocking scripts, create a copy of the stack for later use.
2. Execute the locking script, and ensure that the result of the OP_EQUAL is TRUE. If not, fail the script execution and treat the transaction as invalid. Since the value at the top of the stack (the redeem script) will be consumed by the locking script, the stack state is restored after verifying that the hash is correct.
3. Return the stack to the pre-locking-script-execution state. Remove the (now verified) redeem script and interpret it as a new set of operations to be executed. 2. Execute the locking script, and ensure that the result of the OP_EQUAL is TRUE.
If not, fail the script execution and treat the transaction as invalid.
3. Return the stack to the pre-locking-script-execution state.
Remove the (now verified) redeem script and interpret it as a new set of operations to be executed.
4. Execute the redeem script against the new state of the stack (with any values places on the stack by the unlocking script *except* the redeem script). 4. Execute the redeem script against the new state of the stack (with any values places on the stack by the unlocking script *except* the redeem script).
5. Evaluate the success of the script as usual (a single non-zero value left on the stack). 5. Evaluate the success of the script as usual (a single non-zero value left on the stack).
The P2SH form places all interesting constraints in the redeem script, whereas previously these constraints were placed in the locking script. It is arguably better to place constraints in the redeem script for several reasons: The P2SH form places all interesting constraints in the redeem script, whereas previously these constraints were placed in the locking script.
It is arguably better to place constraints in the redeem script for several reasons:
1. Simple Addresses: P2SH allows the recipient to have funds sent to any constraint script, by providing the sender with an address. Previously, a new address form had to be created for every new script type, or in theory the entire constraint script could be sent from recipient to sender (no protocol to do this has been specced or implemented). 1. Simple Addresses: P2SH allows the recipient to have funds sent to any constraint script, by providing the sender with an address.
2. Recipient-Centric Redemption: In P2PKH scripts, the sender requires that the funds are redeemed using a signature. In the event that the recipient wants to place different requirements on spending the funds, they would have to provide their ideal locking script to the sender and have the sender potentially incur additional fees due to the increased transaction size. Instead, P2SH allows the recipient to create an address based on their desired spending criteria. When the recipient attempts to spend the funds, they them provide the script, revealing the spending requirements and paying the transaction fees themselves. Previously, a new address form had to be created for every new script type, or in theory the entire constraint script could be sent from recipient to sender (no protocol to do this has been specced or implemented).
3. Node Space Efficiency: P2SH defers providing the redeem script until it is used, replacing it with a 20 byte hash. For non-trivial scripts, this will make the UTXO set smaller, since the locking scripts will be smaller. 2. Recipient-Centric Redemption: In P2PKH scripts, the sender requires that the funds are redeemed using a signature.
4. Privacy: P2SH does not reveal the script contents until it is spent. One drawback of this is that it is not possible to determine whether certain instructions are in use or not. This makes retirement of opcodes impossible. However, it's also possible for people to create transactions and not commit them to the blockchain, so the viability of opcode retirement is questionable anyway. In the event that the recipient wants to place different requirements on spending the funds, they would have to provide their ideal locking script to the sender and have the sender potentially incur additional fees due to the increased transaction size.
Instead, P2SH allows the recipient to create an address based on their desired spending criteria.
When the recipient attempts to spend the funds, they them provide the script, revealing the spending requirements and paying the transaction fees themselves.
3. Node Space Efficiency: P2SH defers providing the redeem script until it is used, replacing it with a 20 byte hash.
For non-trivial scripts, this will make the UTXO set smaller, since the locking scripts will be smaller.
4. Privacy: P2SH does not reveal the script contents until it is spent.
One drawback of this is that it is not possible to determine whether certain instructions are in use or not.
This makes retirement of opcodes impossible.
However, it's also possible for people to create transactions and not commit them to the blockchain, so the viability of opcode retirement is questionable anyway.
@@ -1,3 +1,8 @@
# Unlocking Script # Unlocking Script
An unlocking script is a [Script](/protocol/blockchain/script) that is used to prove that a transaction is permitted to spend a given UTXO. This is accomplished by first executing the unlocking script and then executing the locking script for the UTXO referenced by the transaction input. If this execution triggers no failures and leaves a single non-zero (TRUE) value on the stack, the UTXO has been successfully unlocked. One way to look at this is that the unlocking script provides an initial state that acts as an inverse to the previously published locking script. For more information about how script execution works, see [Script](/protocol/blockchain/script). An unlocking script is a [Script](/protocol/blockchain/script) that is used to prove that a transaction is permitted to spend a given UTXO.
This is accomplished by first executing the unlocking script and then executing the locking script for the UTXO referenced by the transaction input.
If this execution triggers no failures and leaves a single non-zero (TRUE) value on the stack, the UTXO has been successfully unlocked.
One way to look at this is that the unlocking script provides an initial state that acts as an inverse to the previously published locking script.
For more information about how script execution works, see [Script](/protocol/blockchain/script).
+23 -8
View File
@@ -1,8 +1,11 @@
# P2P Network Message # P2P Network Message
The Bitcoin Cash Peer-to-Peer (P2P) Network protocol is a binary protocol used by Full Nodes and [SPV](/protocol/simple-payment-verification) Nodes, transmitted via TCP. The P2P network is similar to a gossip network, where nodes listen for messages and then relays that message to its other peers if it believes that message's content is valid. The Bitcoin Cash Peer-to-Peer (P2P) Network protocol is a binary protocol used by Full Nodes and [SPV](/protocol/simple-payment-verification) Nodes, transmitted via TCP.
The P2P network is similar to a gossip network, where nodes listen for messages and then relays that message to its other peers if it believes that message's content is valid.
P2P network messages do not necessarily have a reply and there is no way to unambiguously connect a sent message to a reply, although many communications are often request/response pairs. Nodes may handle incoming messages in parallel, so a message reply order cannot be assumed. Messages that cannot be fulfilled are sometimes dropped with no reply, and sometimes replied to via a `reject` message. P2P network messages do not necessarily have a reply and there is no way to unambiguously connect a sent message to a reply, although many communications are often request/response pairs.
Nodes may handle incoming messages in parallel, so a message reply order cannot be assumed.
Messages that cannot be fulfilled are sometimes dropped with no reply, and sometimes replied to via a `reject` message.
These design decisions were made with consideration to communication with untrusted/uncooperative partners. These design decisions were made with consideration to communication with untrusted/uncooperative partners.
@@ -10,7 +13,8 @@ These design decisions were made with consideration to communication with untrus
## Message Format ## Message Format
The P2P network has a variety of message types. All P2P messages follow a binary format with the following structure: The P2P network has a variety of message types.
All P2P messages follow a binary format with the following structure:
| Field | Length | Format | | Field | Length | Format |
@@ -23,13 +27,21 @@ The P2P network has a variety of message types. All P2P messages follow a binar
### Net Magic ### Net Magic
The network identifier is used to separate blockchains and test networks. This reduces unnecessary load on peers, allowing them to rapidly ban nodes rather then forcing the peer to do a blockchain analysis before banning or disconnecting. For Bitcoin Cash main net, the `net magic` field is always `E3E1F3E8`. Any message received that does not begin with the `net magic` is invalid. The network identifier is used to separate blockchains and test networks.
This reduces unnecessary load on peers, allowing them to rapidly ban nodes rather then forcing the peer to do a blockchain analysis before banning or disconnecting.
For Bitcoin Cash main net, the `net magic` field is always `E3E1F3E8`.
Any message received that does not begin with the `net magic` is invalid.
The `net magic` is designed to be unlikely to occur in normal data--the characters are rarely used upper ASCII, are not valid as UTF-8, and produce a large 32-bit integer with any alignment. `E3E1F3E8` is the ASCII string, "cash", with each byte's highest bit set. The `net magic` is designed to be unlikely to occur in normal data--the characters are rarely used upper ASCII, are not valid as UTF-8, and produce a large 32-bit integer with any alignment.
`E3E1F3E8` is the ASCII string, "cash", with each byte's highest bit set.
### Command String ### Command String
The `command string` is a fixed-length 12 byte ASCII string. Commands may not be longer than 12 bytes. Commands that are shorter than 12-bytes are right-padded with null bytes (`0x00`). The command string is used to determine the type of message being transmitted. Messages with an unrecognized `command string` are ignored. The `command string` is a fixed-length 12 byte ASCII string.
Commands may not be longer than 12 bytes.
Commands that are shorter than 12-bytes are right-padded with null bytes (`0x00`).
The command string is used to determine the type of message being transmitted.
Messages with an unrecognized `command string` are ignored.
The following messages are considered standard by all node implementations. The following messages are considered standard by all node implementations.
@@ -81,11 +93,14 @@ The following messages are well known, but not implemented by all node implement
### Payload Byte Count ### Payload Byte Count
The payload byte count is the size of the payload, encoded as a [little-endian](/protocol/misc/endian/little) 4-byte integer. The total max size of any message is `268,435,456` bytes (256 MiB), and the header for a message is always 24 bytes, therefore the max value of the payload byte count is `268,435,432` bytes. The payload byte count may be zero, but must not be negative. The payload byte count is the size of the payload, encoded as a [little-endian](/protocol/misc/endian/little) 4-byte integer.
The total max size of any message is `268,435,456` bytes (256 MiB), and the header for a message is always 24 bytes, therefore the max value of the payload byte count is `268,435,432` bytes.
The payload byte count may be zero, but must not be negative.
### Payload Checksum ### Payload Checksum
The message checksum is the first 4 bytes of a double-sha256 hash of the payload. The checksum is transmitted as a byte array, and is encoded as [big-endian](/protocol/misc/endian/big). The message checksum is the first 4 bytes of a double-sha256 hash of the payload.
The checksum is transmitted as a byte array, and is encoded as [big-endian](/protocol/misc/endian/big).
### Payload ### Payload
+2 -1
View File
@@ -1,6 +1,7 @@
# Handshake: Acknowledge ("verack") # Handshake: Acknowledge ("verack")
The `verack` message is sent in reply to a [version](/protocol/network/messages/version) message. Sending a `verack` in response to a `version` message indicates to the remote that its connection and version has been accepted. The `verack` message is sent in reply to a [version](/protocol/network/messages/version) message.
Sending a `verack` in response to a `version` message indicates to the remote that its connection and version has been accepted.
There is no version negotiation functionality between nodes; therefore if the node does not accept the version supplied by the remote then the node disconnects instead of responding with a `verack`. There is no version negotiation functionality between nodes; therefore if the node does not accept the version supplied by the remote then the node disconnects instead of responding with a `verack`.
+30 -13
View File
@@ -3,7 +3,7 @@
The version message is a part of the node connection [handshake](/protocol/network/node-handshake) and indicates various connection settings, networking information, and the services provided by the sending node (see Services Bitmask [below](#services-bitmask)). The version message is a part of the node connection [handshake](/protocol/network/node-handshake) and indicates various connection settings, networking information, and the services provided by the sending node (see Services Bitmask [below](#services-bitmask)).
The node connection is not considered established until both nodes have sent and received both a <code>version</code> and [verack](/protocol/network/messages/verack) message. The node connection is not considered established until both nodes have sent and received both a `version` and [verack](/protocol/network/messages/verack) message.
## Message Format ## Message Format
@@ -19,18 +19,25 @@ The node connection is not considered established until both nodes have sent and
| block height | 4 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | The height of the block with the highest height known to the sending node. | | block height | 4 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | The height of the block with the highest height known to the sending node. |
| relay flag | 1 byte | boolean | Indicates whether the sending node would like all broadcasted transactions relayed to it. See [BIP-37](/protocol/forks/bip-0037). This flag is sometimes referred to as "fRelay". | | relay flag | 1 byte | boolean | Indicates whether the sending node would like all broadcasted transactions relayed to it. See [BIP-37](/protocol/forks/bip-0037). This flag is sometimes referred to as "fRelay". |
Note: appending extra data after the `relay flag` is ignored. Historically, extra data after the `relay flag` would sometimes result in the connection being banned, although this is no longer standard behavior. Note: appending extra data after the `relay flag` is ignored.
Historically, extra data after the `relay flag` would sometimes result in the connection being banned, although this is no longer standard behavior.
## Version Number ## Version Number
The most recent version of the network protocol is `70015`. The `version` value often correlates to new behavior, parsing formats, and available services; for more details review the network protocol's [version history](/history/protocol-version). Nodes should use `version` and the `services` bitmask to determine if the node should accept the incoming connection. Related: [node connection handshake](/protocol/network/node-handshake). The most recent version of the network protocol is `70015`.
The `version` value often correlates to new behavior, parsing formats, and available services; for more details review the network protocol's [version history](/history/protocol-version).
Nodes should use `version` and the `services` bitmask to determine if the node should accept the incoming connection.
Related: [node connection handshake](/protocol/network/node-handshake).
## Services Bitmask ## Services Bitmask
The services field is an 8 byte little-endian-serialized bitfield that described peer capabilities. The following capabilities are defined, by bit position: The services field is an 8 byte little-endian-serialized bitfield that described peer capabilities.
The following capabilities are defined, by bit position:
### Standard Services ### Standard Services
* 0: NODE_NETWORK * 0: NODE_NETWORK
The node is capable of serving the complete block chain. It is currently set by all full nodes, and is unset by SPV clients or other peers that just want network services but don't provide them. The node is capable of serving the complete block chain.
It is currently set by all full nodes, and is unset by SPV clients or other peers that just want network services but don't provide them.
* 2: NODE_BLOOM * 2: NODE_BLOOM
The node is capable and willing to handle bloom-filtered connections. The node is capable and willing to handle bloom-filtered connections.
@@ -40,10 +47,13 @@ The services field is an 8 byte little-endian-serialized bitfield that described
*Bitcoin Cash nodes do not have witness data so this flag should be ignored on receipt and set to 0 when sent* *Bitcoin Cash nodes do not have witness data so this flag should be ignored on receipt and set to 0 when sent*
* 5: NODE_BITCOIN_CASH * 5: NODE_BITCOIN_CASH
The node supports the BCH chain. This is intended to be just a temporary service bit until the BTC/BCH fork actually happens. The node supports the BCH chain.
This is intended to be just a temporary service bit until the BTC/BCH fork actually happens.
* 24-31: Reserved for experimental changes * 24-31: Reserved for experimental changes
These bits are reserved for temporary experiments. Just pick a bit that isn't getting used, or one not being used much, and notify the community. Remember that service bits are just unauthenticated advertisements, so your code must be robust against collisions and other cases where nodes may be advertising a service they do not actually support. These bits are reserved for temporary experiments.
Just pick a bit that isn't getting used, or one not being used much, and notify the community.
Remember that service bits are just unauthenticated advertisements, so implementations must be robust against collisions and other cases where nodes may be advertising a service they do not actually support.
## Example Serialized Data ## Example Serialized Data
@@ -92,7 +102,8 @@ Node Features
#### Bitcoin ABC #### Bitcoin ABC
* 10: NODE_NETWORK_LIMITED <img src="/_static_/images/warning.png" /> * 10: NODE_NETWORK_LIMITED <img src="/_static_/images/warning.png" />
This means the same as NODE_NETWORK with the limitation of only serving a small subset of the blockchain. See [BIP159](/protocol/forks/bip-0159) for details on how this is implemented. This means the same as NODE_NETWORK with the limitation of only serving a small subset of the blockchain.
See [BIP159](/protocol/forks/bip-0159) for details on how this is implemented.
#### Bitcoin Unlimited #### Bitcoin Unlimited
@@ -100,10 +111,12 @@ Node Features
The node supports Xtreme Thinblocks The node supports Xtreme Thinblocks
* 6: NODE_GRAPHENE <img src="/_static_/images/warning.png" /> * 6: NODE_GRAPHENE <img src="/_static_/images/warning.png" />
The node supports Graphene blocks. If this is turned off then the node will not service graphene requests nor make graphene requests. The node supports Graphene blocks.
If this is turned off then the node will not service graphene requests nor make graphene requests.
* 10: NODE_NETWORK_LIMITED <img src="/_static_/images/warning.png" /> * 10: NODE_NETWORK_LIMITED <img src="/_static_/images/warning.png" />
This means the same as NODE_NETWORK with the limitation of only serving a small subset of the blockchain. See [BIP159](/protocol/forks/bip-0159) for details on how this is implemented. This means the same as NODE_NETWORK with the limitation of only serving a small subset of the blockchain.
See [BIP159](/protocol/forks/bip-0159) for details on how this is implemented.
#### Bitcoin Verde #### Bitcoin Verde
@@ -116,7 +129,9 @@ Node Features
#### Other Proposed/Previously Used Service Flags #### Other Proposed/Previously Used Service Flags
* 1: NODE_GETUTXO <img src="/_static_/images/warning.png" /> * 1: NODE_GETUTXO <img src="/_static_/images/warning.png" />
The node is capable of responding to the getutxo protocol request. See [BIP 64](/protocol/forks/bip-0064) for details on how this is implemented. _Was previously supported by Bitcoin XT only._ The node is capable of responding to the getutxo protocol request.
See [BIP 64](/protocol/forks/bip-0064) for details on how this is implemented.
_Was previously supported by Bitcoin XT only._
* 7: NODE_WEAKBLOCKS <img src="/_static_/images/warning.png" /> * 7: NODE_WEAKBLOCKS <img src="/_static_/images/warning.png" />
The node supports Storm weak block (currently no node supports these in production, so this is a placeholder). The node supports Storm weak block (currently no node supports these in production, so this is a placeholder).
@@ -126,11 +141,13 @@ The node is capable of responding to the getutxo protocol request. See [BIP 64](
## Node-Specific Behavior ## Node-Specific Behavior
Generally, though node implementations may be aware of services they do not provide, they generally ignore those they don't supported. Any notable deviations from that behavior are documented below. Generally, though node implementations may be aware of services they do not provide, they generally ignore those they don't supported.
Any notable deviations from that behavior are documented below.
### Bitcoin ABC ### Bitcoin ABC
Bitcoin ABC nodes may, once they have reached their maximum number of peers, selectively disconnect from nodes that do not supported "desired services", though it appears currently this just <code>NODE_NETWORK</code> and/or <code>NODE_NETWORK_LIMITED</code>. That is, it may prefer nodes that store and serve blocks. Bitcoin ABC nodes may, once they have reached their maximum number of peers, selectively disconnect from nodes that do not supported "desired services", though it appears currently this just `NODE_NETWORK` and/or `NODE_NETWORK_LIMITED`.
That is, it may prefer nodes that store and serve blocks.
### Bitcoin Verde ### Bitcoin Verde