BitcoinCash/specification
1
Fork 0
Code Issues Pull Requests Releases Activity

Added remaining widely implemented messages.

Browse Source 
Includes various style/consistency changes to various pages.
This commit is contained in:
Andrew Groot
2020-09-23 16:58:50 -04:00
committed by bitcoin
parent 6a1511bca6
commit ae2a746a71
12 changed files with 135 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files
home.md
+10 -10
View File
@@ -5,17 +5,17 @@
[Style Guide](/style-guide) — [Contributors](/contributors) — [Target Audience](/target-audience) — [Project History](/project-history)
### Basics
[Blockchain basics](/protocol/blockchain) — [Protocol hashing algorithms](/protocol/blockchain/hash) — Memory Pool
[Blockchain Basics](/protocol/blockchain) — [Protocol Hashing Algorithms](/protocol/blockchain/hash) — Memory Pool
### Transactions
[Bitcoin Transaction](/protocol/blockchain/transaction) — [Unlocking Script](/protocol/blockchain/transaction/unlocking-script)— [Locking Script](/protocol/blockchain/transaction/locking-script)
### Blocks
[Bitcoin blocks](/protocol/blockchain/block) —
[Block header](/protocol/blockchain/block/block-header) — [Merkle Tree](/protocol/blockchain/block/merkle-tree) — [Transaction Ordering](/protocol/blockchain/block/transaction-ordering)
[Bitcoin Blocks](/protocol/blockchain/block) —
[Block Header](/protocol/blockchain/block/block-header) — [Merkle Tree](/protocol/blockchain/block/merkle-tree) — [Transaction Ordering](/protocol/blockchain/block/transaction-ordering)
### Script (Bitcoin transaction language)
[Script](/protocol/blockchain/script) — [Operation codes (opcodes)](/protocol/blockchain/script#operation-codes-opcodes)
[Script](/protocol/blockchain/script) — [Operation Codes (opcodes)](/protocol/blockchain/script#operation-codes-opcodes)
### Transaction validation
[Transaction Validation](/protocol/blockchain/transaction-validation) —
@@ -25,10 +25,10 @@
[Proof of Work](/protocol/blockchain/proof-of-work) — [Difficulty Adjustment Algorithm](/protocol/blockchain/proof-of-work/difficulty-adjustment-algorithm) — [Mining](/protocol/blockchain/proof-of-work/mining) — Stratum Protocol — Mining Pools
### Addresses
Pay To Public Key (P2PK) — Pay To Public Key Hash (P2PKH) — Pay To Script Hash (P2SH) — [Base58Check encoding (legacy)](/protocol/blockchain/encoding/base58check) — [Cashaddr encoding](/protocol/blockchain/encoding/cashaddr)
Pay To Public Key (P2PK) — Pay To Public Key Hash (P2PKH) — Pay To Script Hash (P2SH) — [Base58Check encoding (legacy)](/protocol/blockchain/encoding/base58check) — [Cashaddr Encoding](/protocol/blockchain/encoding/cashaddr)
### Cryptography
Secp256k1 — Public Key — Private Key — ECDSA signatures — Schnorr signatures — [Multisignature (M-of-N multisig)](/protocol/blockchain/cryptography/multisignature.md)
Secp256k1 — Public Key — Private Key — ECDSA Signatures — Schnorr Signatures — [Multisignature (M-of-N multisig)](/protocol/blockchain/cryptography/multisignature.md)
### Network upgrades
[Bip-16](/protocol/forks/bip-0016) — [Bip-34](/protocol/forks/bip-0034) — [Bip-37](/protocol/forks/bip-0037) — [Bip-64](/protocol/forks/bip-0064) — [Bip-65](/protocol/forks/bip-0065) — [Bip-66](/protocol/forks/bip-0066) — [Bip-68](/protocol/forks/bip-0068) — [Bip-112](/protocol/forks/bip-0112) — [Bip-113](/protocol/forks/bip-0113) — [Bip-157](/protocol/forks/bip-0157) — [Bip-158](/protocol/forks/bip-0158) — [Bip-159](/protocol/forks/bip-0159) — BCH-UAHF (BUIP-55) — [HF-20171113](/protocol/forks/hf-20171113) — HF-20180515 — HF-20181115 — HF-20190515 — HF-20191115
@@ -43,13 +43,13 @@ Secp256k1 — Public Key — Private Key — ECDSA signatures — Schnorr signat
#### Request messages
feefilter — getaddr — [getblocks](/protocol/network/messages/getblocks) — [getdata](/protocol/network/messages/getdata) — [getheaders](/protocol/network/messages/getheaders) — [ping](/protocol/network/messages/ping) —
sendheaders — [version](/protocol/network/messages/version)
[feefilter](/protocol/network/messages/feefilter) — [getaddr](/protocol/network/messages/getaddr) — [getblocks](/protocol/network/messages/getblocks) — [getdata](/protocol/network/messages/getdata) — [getheaders](/protocol/network/messages/getheaders) — [ping](/protocol/network/messages/ping) —
[sendheaders](/protocol/network/messages/sendheaders) — [version](/protocol/network/messages/version)
#### Response messages
[addr](/protocol/network/messages/addr) — block — headers — notfound — [merkleblock](/protocol/network/messages/merkleblock) — [pong](/protocol/network/messages/pong) —
[reject](/protocol/network/messages/reject) — tx — [verack](/protocol/network/messages/verack)
[addr](/protocol/network/messages/addr) — [block](/protocol/network/messages/block) — [headers](/protocol/network/messages/headers) — [notfound](/protocol/network/messages/notfound) — [merkleblock](/protocol/network/messages/merkleblock) — [pong](/protocol/network/messages/pong) —
[reject](/protocol/network/messages/reject) — [tx](/protocol/network/messages/tx) — [verack](/protocol/network/messages/verack)
#### Other messages (extensions)
protocol/blockchain/transaction.md
+2 -2
View File
@@ -15,9 +15,9 @@ Verification of a transaction ensures that:
|--|--|--|--|
| version | 4 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | The version of the transaction format. Currently `0x02000000`. |
| input count | variable | [variable length integer](/protocol/formats/variable-length-integer) | The number of inputs in the transaction. |
| transaction inputs | variable | `input count` [transaction inputs](#transaction-inputs) | Each of the transaction's inputs serialized in order. |
| transaction inputs | variable | `input_count` [transaction inputs](#transaction-inputs) | Each of the transaction's inputs serialized in order. |
| output count | variable | [variable length integer](/protocol/formats/variable-length-integer) | The number of output in the transaction. |
| transaction outputs | variable | `output count` [transaction outputs](#transaction-outputs) | Each of the transaction's outputs serialized in order. |
| transaction outputs | variable | `output_count` [transaction outputs](#transaction-outputs) | Each of the transaction's outputs serialized in order. |
| lock-time | 4 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | The block height or timestamp after which this transaction is allowed to be included in a block. If less than `500,000,000`, this is interpreted as a block height. If equal or greater than `500,000,000`, this is interpreted as a unix timestamp in seconds. If less than zero, this is interpreted as an error. Ignored, including less than zero case, if all of the transaction input sequence numbers are `0xFFFFFFFF`.<br/><br/>Note that at 10 minutes per block, it will take over 9,500 years to reach block height 500,000,000. Also note that when Bitcoin was created the unix timestamp was well over 1,000,000,000.<br/><br/>Additionally, since [BIP-113](/protocol/forks/bip-0113), when the lock-time is intepreted as a time, it is compared to the [median-time-past](#median-time-past) of a block, not it's timestamp. |
### Median-Time-Past
protocol/network/messages.md
+24 -23
View File
@@ -45,44 +45,45 @@ The command string is used to determine the type of message being transmitted.
Messages with an unrecognized `command string` are ignored by most implementations but may result in a ban by implementations that diverge from the Satoshi-client defacto standard.
The following messages are considered standard by all node implementations.
(TODO: the protocol is versioned, commands are introduced at certain versions, the previous line is ignoring this
(TODO: the protocol is versioned, commands are introduced at certain versions, the previous line is ignoring this.
TODO: saying something is "standard" doesn't mean much in terms of spec. Is there an obligation to implement them?)
#### Announcements
| Command String | Synopsis | Supported Implementations
| -- | -- | -- |
| [filteradd](/protocol/p2p/filteradd) | *Adds a single item into an installed filter* | all
| [filterclear](/protocol/p2p/filterclear) | *Removes an installed filter* | all
| [filterload](/protocol/p2p/filterload) | *Inserts a transaction and merkle block filter into the peer* | all
| [inv](/protocol/p2p/inv) | *Notifies peers about the existence of some information (generally a block or transaction)* | all
| [xupdate](/protocol/p2p/xupdate) | *Communicates a change in peer capabilities* | BCHUnlimited
| [filteradd](/protocol/network/messages/filteradd) | *Adds a single item into an installed filter* | all
| [filterclear](/protocol/network/messages/filterclear) | *Removes an installed filter* | all
| [filterload](/protocol/network/messages/filterload) | *Inserts a transaction and merkle block filter into the peer* | all
| [inv](/protocol/network/messages/inv) | *Notifies peers about the existence of some information (generally a block or transaction)* | all
| [xupdate](/protocol/network/messages/xupdate) | *Communicates a change in peer capabilities* | BCHUnlimited
#### Requests
| Command String | Synopsis | Supported Implementations
| -- | -- | -- |
| feefilter | |
| getaddr | |
| [getblocks](/protocol/p2p/getblocks) | *Requests block hash identifiers* | all |
| [getdata](/protocol/p2p/getdata) | *Requests information from a peer* | all |
| [getheaders](/protocol/p2p/getheaders) | *Requests block headers from a peer* | all |
| ping | [Ping](/protocol/network/messages/ping) | all |
| sendheaders | |
| [feefilter](/protocol/network/messages/feefilter) | *Requests that transactions without sufficient fees are not relayed* | all
| [getaddr](/protocol/network/messages/getaddr) | *Requests a list of active peers* | all
| [getblocks](/protocol/network/messages/getblocks) | *Requests block hash identifiers* | all |
| [getdata](/protocol/network/messages/getdata) | *Requests information from a peer* | all |
| [getheaders](/protocol/network/messages/getheaders) | *Requests block headers from a peer* | all |
| [ping](/protocol/network/messages/ping) | *Requests a confirmation (pong) that the peer is still active* | all |
| [sendheaders](/protocol/network/messages/sendheaders) | *Requests that new blocks are sent as headers instead of hashes* | all
| [version](/protocol/network/messages/version) | *Describes peer capabilities* | all
| [xversion](/protocol/p2p/xversion) | *Describes peer capabilities in an extensible manner* | BCHUnlimited
| [xversion](/protocol/network/messages/xversion) | *Describes peer capabilities in an extensible manner* | BCHUnlimited
#### Responses
| Command String | Synopsis | Supported Implementations
| -- | -- | -- |
| [addr](/protocol/p2p/addr) | *Provides a peer with the addresses of other peers* | all
| block | |
| [headers](/protocol/p2p/headers) | *Provides a set of block headers (unsolicited or GETHEADERS response)* | all |
| notfound | |
| [merkleblock](protocol/p2p/merkleblock) | *Provides a provable subset of a block's transactions, as filtered by FILTERADD* | all |
| [Pong](/protocol/network/messages/pong) | *Reply to a ping message* | all |
| [reject](/protocol/p2p/reject) | *Response by well-behaved clients if a message cannot be handled* | all
| [TX](/protocol/p2p/tx) | *Provide a transaction* | all
| [verack](/protocol/network/messages/verack) | *Respond to an [xversion](/protocol/p2p/xversion) message* | all
| [addr](/protocol/network/messages/addr) | *Provides a peer with the addresses of other peers* | all
| [block](/protocol/network/messages/block) | *Provides the contents of a block* | all
| [headers](/protocol/network/messages/headers) | *Provides a set of block headers (unsolicited or GETHEADERS response)* | all |
| [notfound](/protocol/network/messages/notfound) | *Indicates that a requested resource could not be relayed* | all
| [merkleblock](/protocol/network/messages/merkleblock) | *Provides a provable subset of a block's transactions, as filtered by FILTERADD* | all |
| [pong](/protocol/network/messages/pong) | *Reply to a ping message* | all |
| [reject](/protocol/network/messages/reject) | *Response by well-behaved clients if a message cannot be handled* | all
| [tx](/protocol/network/messages/tx) | *Provides a transaction* | all
| [verack](/protocol/network/messages/verack) | *Response to a [version](/protocol/network/messages/version) message* | all
| [xverack](/protocol/network/messages/xverack) | *Response to an [xversion](/protocol/network/messages/xversion) message* | BCHUnlimited
The following messages are well known, but not implemented by all node implementations.
protocol/network/messages/addr.md
+2 -2
View File
@@ -3,9 +3,9 @@
"related":["/protocol","/protocol/network/messages/getaddr"]
}</div>
# Response: Addr ("addr")
# Response: Addresses ("addr")
Provide information about other prospective P2P protocol peers. Peers SHOULD not send this message unsolicited, and nodes that receive an unsolicited ADDR message MUST ignore it. This behavior helps prevent eclipse and partitioning attacks by not allowing an attacker to aggressively seed peer connection tables with its own nodes.
Provide information about other prospective P2P protocol peers. Peers SHOULD not send this message unsolicited (see [getaddr](/protocol/network/messages/getaddr)), and nodes that receive an unsolicited ADDR message MUST ignore it. This behavior helps prevent eclipse and partitioning attacks by not allowing an attacker to aggressively seed peer connection tables with its own nodes.
## Message Format
protocol/network/messages/block.md
+17
View File
@@ -0,0 +1,17 @@
# Response: Block (“block”)
Provides the contents of a block.
## Message Format
| Field | Length | Format | Description |
|--|--|--|--|
| version number | 4 bytes | signed integer | The block format version number. |
| previous block hash | 32 bytes | bytes | The hash of the block preceding this one in the blockchain. |
| merkle root | 32 bytes | bytes | The root hash of the merkle tree comprised of the block's transactions. |
| timestamp | 8 bytes | unix timestamp<sup>[(LE)](/protocol/misc/endian/little)</sup> | The time the block was generated. |
| hash target | 4 bytes | [compressed target](/protocol/blockchain/block/block-header#compressed-target-format) | The target that the hash of this block is expected to satisfy. See [Target](/protocol/blockchain/proof-of-work#target). |
| nonce | 4 bytes | bytes | Nonce used to update the block hash during mining. See [Proof of Work](/protocol/blockchain/proof-of-work). |
| transaction count | variable | [variable length integer](/protocol/formats/variable-length-integer) | The number of transactions in the block (and therefore following in this message). |
| transactions | variable | &lt;transaction_count&gt; [transactions](/protocol/network/messages/tx#message-format) | The transactions contained within this block, formatted the same way they are in a [tx](/protocol/network/messages/tx) message. |
protocol/network/messages/feefilter.md
+11
View File
@@ -0,0 +1,11 @@
# Request: Filter Fee (“filterfee”)
Requests that the recipient withhold transactions that provide less than the given threshold of fees, in satoshis per byte.
The recipient node may, but is not required to, begin to perform this filtering and send only transactions that have fees at or above this threshold to the sender.
## Message Format
| Field | Length | Format | Description |
|--|--|--|--|
| minimum fee per byte | 8 bytes | unsigned 64 bit integer<sup>[(LE)](/protocol/misc/endian/little.md)</sup> | The minimum number of satoshis per byte in fees desired by the sender.
protocol/network/messages/getaddr.md
+6
View File
@@ -0,0 +1,6 @@
# Request: Get Addresses (“getaddr”)
Request the information about active peers on the network. The recipient may reply with peer IP addresses using an [addr](/protocol/network/messages/addr) message.
## Message Format
This message has no contents.
protocol/network/messages/headers.md
+16 -7
View File
@@ -3,15 +3,24 @@
"related":["/protocol","/protocol/p2p/getheaders"]
}</div>
*Provides a contiguous set of block headers*
# Response: Headers ("headers")
## HEADERS Message Format
Provides a contiguous set of block headers.
|Size in bytes|Description|Data type|
|-------------|-----------|---------|
|1+ | Number of headers | varint|
|(81 + (1+)) * count |[Block headers](/protocol/blockchain/block/block-header/) and number of txs in the block|Blockheader + varint|
## Message Format
| Field | Length | Format | Description |
|--|--|--|--|
| block header count | variable | [variable length integer](/protocol/formats/variable-length-integer) | The number of block headers in this message. |
| block headers | variable | `block_header_count` [block headers with transaction count](#block-header-with-transaction-count-format) | The set of block headers being transmitted, with the block's transaction count. |
No more than 2000 block headers may be sent at one time. Block headers in this array MUST be sequential, ordered by height and without range gaps.
The number of txs in header is **DEPRECATED** and should be ignored. Nodes are allowed to send 0 regardless of the actual number of transactions in the block.
#### Block Header With Transaction Count Format
| Field | Length | Format | Description |
|--|--|--|--|
| block header | 80 bytes | [block header](/protocol/blockchain/block/block-header#block-header-format) | The contents of the block's header. |
| transaction count* | variable | [variable length integer](/protocol/formats/variable-length-integer) | The number of transactions contained within the block with the preceding header. |
\* The transaction count above is **DEPRECATED** and should be ignored. Nodes are allowed to send 0 regardless of the actual number of transactions in the block.
protocol/network/messages/inv.md
+21 -11
View File
@@ -3,18 +3,31 @@
"related":["/protocol","/protocol/network/messages/getdata.md","/protocol/network/messages/filterload.md","/protocol/network/messages/filterclear.md"]
}</div>
*Notifies peers about the existence of some information (block or transaction)*
Based on selected services in the [VERSION](/protocol/network/messages/version.md) message, INV messages may not be sent.
# Announcement: Inventory ("inv")
If a bloom filter has been sent to this node via [FILTERLOAD](/protocol/network/messages/filterload.md), transaction INVs will only be sent if they match the bloom filter.
Notifies peers about the existence of some information (block or transaction).
| compact int | 4 bytes | 32 bytes |... | 4 bytes | 32 bytes |
|----------|---------|----------|---|---------|----------|
|[vector](/protocol/p2p/vector.md) size N of| type 1 | hash 1 | | type N | hash N
Based on selected services in the [version](/protocol/network/messages/version) message, inventory messages may not be sent.
NOTE: Since a block header is a relatively small data structure, and block propagation speed is an important network metric, a peer may send HEADER messages in place of INV messages when a block arrives.
If a bloom filter has been sent to this node via [filterload](/protocol/network/messages/filterload), a transaction inventory will only be sent for transactions that match the bloom filter.
##### Type
## Message Format
| Field | Length | Format | Description |
|--|--|--|--|
| inventory count | variable | [variable length integer](/protocol/formats/variable-length-integer) | The number of inventory items in this message. |
| inventory items | `inventory_count` * 36 bytes | `inventory_count` [inventory items](#inventory-item-format) | The set of inventory items being transmitted. |
NOTE: Since a block header is a relatively small data structure, and block propagation speed is an important network metric, a peer may send [headers](/protocol/network/messages/headers) messages in place of inventory messages when a block arrives. This behavior can be requested using the [sendheaders](/protocol/network/messages/sendheaders) message.
#### Inventory Item Format
| Field | Length | Format | Description |
|--|--|--|--|
| type | 4 bytes | [inventory type](#inventory-types) | Indicates what the following hash represents. |
| item hash | 32 bytes | bytes | The [hash](/protocol/blockchain/hash) that identifies the item. |
#### Inventory Types
The type of the object that is available.
| Type | Value|
@@ -27,6 +40,3 @@ The type of the object that is available.
| 6 | Graphene Block (Bitcoin Unlimited)
Implementations: [C++](https://github.com/BitcoinUnlimited/BitcoinUnlimited/blob/eb264e627e231f7219e60eef41b4e37cc52d6d9d/src/protocol.h#L477)
##### Hash
The [hash identifier](/glossary/hash__identifier.md) of the available object.
protocol/network/messages/notfound.md
+10
View File
@@ -0,0 +1,10 @@
# Response: Not Found ("notfound")
Indicates that a requested item is not able to be relayed to the requester.
## Message Format
| Field | Length | Format | Description |
|--|--|--|--|
| inventory count | variable | [variable length integer](/protocol/formats/variable-length-integer) | The number of inventory items in this message. |
| inventory items | &lt;inventory_count&gt; * 36 bytes | &lt;inventory_count&gt; [inventory items](/protocol/network/messages/inv#inventory-item-format) | The set of inventory items that cannot be relayed. |
protocol/network/messages/sendheaders.md
+6
View File
@@ -0,0 +1,6 @@
# Request: Send Headers (“sendheaders”)
Requests that new blocks are sent to the sender as a [header](/protocol/network/messages/headers) message instead of as a block hash [inv](/protocol/network/messages/inv) message.
## Message Format
This message has no contents.
protocol/network/messages/tx.md
+9
View File
@@ -0,0 +1,9 @@
# Response: Transaction (“tx”)
Provides the contents of a transaction.
## Message Format
| Field | Length | Format | Description |
|--|--|--|--|
| transaction data | variable | [Transaction](/protocol/blockchain/transaction#format) | The full serialized transaction. |