diff --git a/protocol/blockchain/block.md b/protocol/blockchain/block.md index 9b74f24..29e26d2 100644 --- a/protocol/blockchain/block.md +++ b/protocol/blockchain/block.md @@ -1,22 +1,32 @@ # 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 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 The coinbase transaction provides a mechanism for miners to: - - Receive payment for mining - - Include a message, known as the "coinbase message," or simply "coinbase," within the block + - Receive payment for mining. + - 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. \ No newline at end of file +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. \ No newline at end of file diff --git a/protocol/blockchain/block/block-header.md b/protocol/blockchain/block/block-header.md index 2c46027..df0c881 100644 --- a/protocol/blockchain/block/block-header.md +++ b/protocol/blockchain/block/block-header.md @@ -1,12 +1,14 @@ # 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 - - The double SHA-256 hash of the block header - 2. Confirm the proof of work was executed correctly - - 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 + 1. Calculate the hash of the block. + - The double SHA-256 hash of the block header. + 2. Confirm the proof of work was executed correctly. + - 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. - 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. @@ -24,11 +26,13 @@ Since validation of all the transactions in the block can be expensive, the abil ### 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 | |--|--|--|--| -| exponent | 1 byte | byte | Used to calculate the offset for the signficand. The actual exponent is 8 * (exponent - 3). | +| 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. | -Ultimately, the difficulty target is equal to: significand * 2(8 * (exponent - 3)) \ No newline at end of file +Ultimately, the difficulty target is equal to: +
significand * 2(8 * (exponent - 3))
\ No newline at end of file diff --git a/protocol/blockchain/block/merkle-tree.md b/protocol/blockchain/block/merkle-tree.md index c4d1782..f861b11 100644 --- a/protocol/blockchain/block/merkle-tree.md +++ b/protocol/blockchain/block/merkle-tree.md @@ -1,9 +1,14 @@ # 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). \ No newline at end of file +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). \ No newline at end of file diff --git a/protocol/blockchain/block/transaction-ordering.md b/protocol/blockchain/block/transaction-ordering.md index 62502c6..5def7f9 100644 --- a/protocol/blockchain/block/transaction-ordering.md +++ b/protocol/blockchain/block/transaction-ordering.md @@ -1,11 +1,19 @@ # 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 -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 -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. \ No newline at end of file +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. \ No newline at end of file diff --git a/protocol/blockchain/script.md b/protocol/blockchain/script.md index d6d0bb7..48f2f64 100644 --- a/protocol/blockchain/script.md +++ b/protocol/blockchain/script.md @@ -1,7 +1,15 @@ # 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 -Scripts are executed using a stack-based memory model \ No newline at end of file +Scripts are executed using a stack-based memory model. \ No newline at end of file diff --git a/protocol/blockchain/transaction/locking-script.md b/protocol/blockchain/transaction/locking-script.md index 9db1c9a..e3e1158 100644 --- a/protocol/blockchain/transaction/locking-script.md +++ b/protocol/blockchain/transaction/locking-script.md @@ -1,14 +1,21 @@ # 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 -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) -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 | |--|--| @@ -18,12 +25,16 @@ The P2PK locking script expects the unlocking script to push a signature to the **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. -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. ### 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 | |--|--| @@ -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 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 | |--|--| @@ -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: -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. -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. +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, the stack state is restored after verifying that the hash is correct. +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). 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). -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. -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. \ No newline at end of file +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). +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. +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. \ No newline at end of file diff --git a/protocol/blockchain/transaction/unlocking-script.md b/protocol/blockchain/transaction/unlocking-script.md index 7cc116f..3ef5afb 100644 --- a/protocol/blockchain/transaction/unlocking-script.md +++ b/protocol/blockchain/transaction/unlocking-script.md @@ -1,3 +1,8 @@ # 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). \ No newline at end of file +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). \ No newline at end of file diff --git a/protocol/network/messages.md b/protocol/network/messages.md index 782f3eb..fe0f4ed 100644 --- a/protocol/network/messages.md +++ b/protocol/network/messages.md @@ -1,8 +1,11 @@ # 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. @@ -10,7 +13,8 @@ These design decisions were made with consideration to communication with untrus ## 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 | @@ -23,13 +27,21 @@ The P2P network has a variety of message types. All P2P messages follow a binar ### 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 -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. @@ -81,11 +93,14 @@ The following messages are well known, but not implemented by all node implement ### 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 -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 diff --git a/protocol/network/messages/verack.md b/protocol/network/messages/verack.md index 2a2bafa..3861cc9 100644 --- a/protocol/network/messages/verack.md +++ b/protocol/network/messages/verack.md @@ -1,6 +1,7 @@ # 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`. diff --git a/protocol/network/messages/version.md b/protocol/network/messages/version.md index b139747..24bfd62 100644 --- a/protocol/network/messages/version.md +++ b/protocol/network/messages/version.md @@ -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 node connection is not considered established until both nodes have sent and received both a version 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 @@ -19,18 +19,25 @@ The node connection is not considered established until both nodes have sent and | block height | 4 bytes | unsigned integer[(LE)](/protocol/misc/endian/little) | 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". | -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 -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 -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 * 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 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* * 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 - 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 @@ -92,7 +102,8 @@ Node Features #### Bitcoin ABC * 10: NODE_NETWORK_LIMITED - 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 @@ -100,10 +111,12 @@ Node Features The node supports Xtreme Thinblocks * 6: NODE_GRAPHENE - 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 - 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 @@ -116,7 +129,9 @@ Node Features #### Other Proposed/Previously Used Service Flags * 1: NODE_GETUTXO -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 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 -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 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 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