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

wiki commit

Browse Source
This commit is contained in:
AndrewStone
2020-11-04 13:23:02 -05:00
committed by buwiki
parent 7cb8fa7a00
commit f1fb956302
46 changed files with 611 additions and 350 deletions
Download Patch File Download Diff File Expand all files Collapse all files
protocol/network/messages.md
+57 -64
View File
@@ -1,18 +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 over TCP/IP.
Individual nodes on the Bitcoin Cash network connect and create a mesh network where each node is indirectly connected to many others via just a couple of hops.
In the original Satoshi implementation of the P2P protocol the design of INV and getdata have been used for propagating transaction data using the rules of the gossip protocol values: forwarding validated transactions to a few peer-nodes who send it to others until the entire network has the transaction.
This emergent behavior of the P2P layer allows fast propagation without undue strain on any individual node.
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 P2P protocol is designed around messages.
Each message is separate and self-contained.
Nodes should be tolerant of message-types they do not understand.
It is best to simply ignore those.
Generally speaking, each message is an event that the node can choose to respond to.
Events can be notifications of new data (transactions/blocks/etc), requests for such data to be sent, or the sending of the data itself.
In some specific cases a message can indicate the rejection of another message, though this is optional and should not be relied upon.
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.
@@ -23,24 +16,24 @@ These design decisions were made with consideration to communication with untrus
The P2P network has a variety of message types.
All P2P messages follow a binary format with the following structure:
| Field | Length | Format | Description |
|--|--|--|--|
| net magic | 4 bytes | byte array<sup>[(BE)](/protocol/misc/endian/big)</sup> | See [net magic](#net-magic). |
| command string | 12 bytes | string<sup>[(BE)](/protocol/misc/endian/big)</sup> | See [command string](#command-string).
| payload byte count | 4 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | The size of the payload. 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, while the min value is zero (indicating no additional payload). |
| payload checksum | 4 bytes | byte array<sup>[(BE)](/protocol/misc/endian/big)</sup> | The message checksum is the first 4 bytes of a double-sha256 hash of the payload. |
| payload | variable | message-specific | See [message types](#message-types) for links to message-specific page, which describe the payload for each message. |
See [Example Message](#example-message) for a concrete example of this with a message that does not contain an extended payload.
| Field | Length | Format |
|--|--|--|
| net magic | 4 bytes | byte array<sup>[(BE)](/protocol/misc/endian/big)</sup> |
| command string | 12 bytes | string<sup>[(BE)](/protocol/misc/endian/big)</sup> |
| payload byte count | 4 bytes | integer<sup>[(LE)](/protocol/misc/endian/little)</sup> |
| payload checksum | 4 bytes | byte array<sup>[(BE)](/protocol/misc/endian/big)</sup> |
| payload | variable | |
### 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 `0xE3E1F3E8` (the ASCII string, "cash", with each byte's highest bit set).
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.
### Command String
@@ -50,43 +43,45 @@ 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 by most implementations but may result in a ban by implementations that diverge from the Satoshi-client defacto standard.
### Message Types
The following messages are considered standard by all node implementations.
#### Announcements
| Command String | Synopsis |
| -- | -- |
| [filteradd](/protocol/network/messages/filteradd) | *Adds a single item into an installed filter* |
| [filterclear](/protocol/network/messages/filterclear) | *Removes an installed filter* |
| [filterload](/protocol/network/messages/filterload) | *Inserts a transaction and merkle block filter into the peer* |
| [inv](/protocol/network/messages/inv) | *Notifies peers about the existence of some information (generally a block or transaction)* |
| 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
#### Requests
| Command String | Synopsis |
| -- | -- |
| [feefilter](/protocol/network/messages/feefilter) | *Requests that transactions without sufficient fees are not relayed* |
| [getaddr](/protocol/network/messages/getaddr) | *Requests a list of active peers* |
| [getblocks](/protocol/network/messages/getblocks) | *Requests block hash identifiers* |
| [getdata](/protocol/network/messages/getdata) | *Requests information from a peer* |
| [getheaders](/protocol/network/messages/getheaders) | *Requests block headers from a peer* |
| [ping](/protocol/network/messages/ping) | *Requests a confirmation (pong) that the peer is still active* |
| [sendheaders](/protocol/network/messages/sendheaders) | *Requests that new blocks are sent as headers instead of hashes* |
| [version](/protocol/network/messages/version) | *Describes peer capabilities* |
| 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 | |
| [version](/protocol/network/messages/version) | *Describes peer capabilities* | all
| [xversion](/protocol/p2p/xversion) | *Describes peer capabilities in an extensible manner* | BCHUnlimited
#### Responses
| Command String | Synopsis |
| -- | -- |
| [addr](/protocol/network/messages/addr) | *Provides a peer with the addresses of other peers* |
| [block](/protocol/network/messages/block) | *Provides the contents of a block* |
| [headers](/protocol/network/messages/headers) | *Provides a set of block headers (unsolicited or GETHEADERS response)* |
| [notfound](/protocol/network/messages/notfound) | *Indicates that a requested resource could not be relayed* |
| [merkleblock](/protocol/network/messages/merkleblock) | *Provides a provable subset of a block's transactions, as filtered by FILTERADD* |
| [pong](/protocol/network/messages/pong) | *Reply to a ping message* |
| [reject](/protocol/network/messages/reject) | *Response by well-behaved clients if a message cannot be handled* |
| [tx](/protocol/network/messages/tx) | *Provides a transaction* |
| [verack](/protocol/network/messages/verack) | *Response to a [version](/protocol/network/messages/version) message* |
| 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
#### Other Message Types (Extensions)
The following messages are well known, but not implemented by all node implementations.
| Command String | Synopsis | Supported Implementations
| -- | -- | -- |
@@ -97,24 +92,22 @@ Messages with an unrecognized `command string` are ignored by most implementatio
| thinblock | | |
| xblocktx | | |
| xthinblock | | |
| [xupdate](/protocol/network/messages/xupdate) | *Communicates a change in peer capabilities* | BCHUnlimited
| [xversion](/protocol/network/messages/xversion) | *Describes peer capabilities in an extensible manner* | BCHUnlimited
| [xverack](/protocol/network/messages/xverack) | *Response to an [xversion](/protocol/network/messages/xversion) message* | BCHUnlimited
## Example message
### Payload Byte Count
The below segments, when concatenated in order, create a sample [verack](/protocol/network/messages/verack) message.
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.
| Label | Sample Value (Hexadecimal Representation) |
|-------|------|
| Net Magic<sup>[(BE)](/protocol/misc/endian/little)</sup> | `E3E1F3E8` |
| Command String ("verack")<sup>[(BE)](/protocol/misc/endian/big)</sup> | `76657261636B000000000000` |
| Payload Byte Count<sup>[(LE)](/protocol/misc/endian/little)</sup> | `00000000` |
| Payload Checksum<sup>[(LE)](/protocol/misc/endian/little)</sup> | `5DF6E0E2` |
### Payload Checksum
Below is the full, concatenated sample message (in hexadecimal):
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).
`E3E1F3E876657261636B000000000000000000005DF6E0E2`
### Payload
The message payload is defined by the message type.
# Node Specific Behavior
@@ -122,4 +115,4 @@ Below is the full, concatenated sample message (in hexadecimal):
### Payload Checksum
Bitcoin Unlimited does not validate the message checksum since messages are sent via TCP which has its own checksum paradigm.
Bitcoin Unlimited does not validate the message checksum since messages are sent via TCP which has its own checksum paradigm.
protocol/network/messages/addr.md
+17 -4
View File
@@ -3,14 +3,27 @@
"related":["/protocol","/protocol/network/messages/getaddr"]
}</div>
# Response: Addresses ("addr")
# Response: Addr ("addr")
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.
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.
## Message Format
| Field | Length | Format | Description |
|--|--|--|--|
| peer count | variable | [variable length integer](/protocol/formats/variable-length-integer) | The number of peers whose connection information is being sent in this message. |
| peer network addresses | `peer_count` * 30 | `peer_count` [network addresses](/protocol/formats/network-address) | The peer information for each of the peers being transmitted. |
| vector length N | variable | [compact int](/protocol/p2p/compact__int.md) | The following fields are repeated N times |
| time 0 | 4 bytes | unsigned int<sup>[(LE)](/protocol/misc/endian/little)</sup> | last known alive time |
| services 0 | 8 bytes | unsigned int<sup>[(LE)](/protocol/misc/endian/little)</sup> bit field | the services this node supports |
| IP address 0 | 16 bytes | bytes | connect using this IP address
| port 0 | 2 bytes | unsigned integer<sup>[(BE)](/protocol/misc/endian/little)</sup> | connect using this IP port
| ... |
| time N, etc
*services* is a bit field describing supported functionality, that is also used in the [version](/protocol/p2p/version) message. See [services field](/protocol/p2p/services__field) for bit definitions.
*time* is a 4 byte unsigned little-endian integer denoting the last time in epoch seconds that this node was known to be "live".
*IP address* is the IPv4 or IPv6 address of the prospective node.
*port* is the IP port of the prospective node, serialized as an unsigned 2 byte big-endian value.
protocol/network/messages/filteradd.md
+3 -4
View File
@@ -9,9 +9,8 @@ Add an entry into the installed bloom filter.
## Message Format
| Field | Length | Format | Description |
|--|--|--|--|
| data length | variable | [variable length integer](/protocol/formats/variable-length-integer) | The size of the piece of the data to be added to the bloom filter. |
| data | `data_length` bytes | bytes | The raw data of the object to the be added. |
| compact int | N bytes |
|-------------|---------|
|[vector](/protocol/p2p/vector) size N of| data
*data* is inserted into the bloom filter, exactly as if the [insert](https://github.com/BitcoinUnlimited/BitcoinUnlimited/blob/eb264e627e231f7219e60eef41b4e37cc52d6d9d/src/bloom.cpp#L116) operation had been called locally before sending the filter.
protocol/network/messages/filterload.md
+6 -7
View File
@@ -9,7 +9,7 @@ Inserts a transaction and merkle block filter into the peer, overwriting any exi
### Effect on Transactions
This message installs a bloom filter into the peer. Subsequent [inv](/protocol/network/messages/inv) and [merkleblock](/protocol/network/messages/merkleblock) messages only provide transactions that in match this bloom filter in some manner. The following items in a transaction are checked against the bloom filter:
This message installs a bloom filter into the peer. Subsequent INV notifications and MERKLEBLOCK messages only provide transactions that in match this bloom filter in some manner. The following items in a transaction are checked against the bloom filter:
- The transaction hash
- Each data field in every [output script](/glossary/output__script.md) in the transaction
@@ -22,17 +22,16 @@ See [CBloomFilter::MatchAndInsertOutputs](https://github.com/BitcoinUnlimited/Bi
### Effect on Merkle Blocks
If a [filtered block](https://github.com/BitcoinUnlimited/BitcoinUnlimited/blob/bucash1.7.0.0/src/protocol.h#L483) is requested via an inventory message, the installed bloom filter is used to choose which transactions are included in the response using the same matching algorithm as described above for transaction inventories.
If a [filtered block](https://github.com/BitcoinUnlimited/BitcoinUnlimited/blob/bucash1.7.0.0/src/protocol.h#L483) is requested via in [INV](/protocol/network/messages/inv.md) message, the installed bloom filter is used to choose which transactions are included in the response using the same matching algorithm as described above for transaction INVs.
## Message Format
| Field | Length | Format | Description |
|--|--|--|--|
| bloom filter size | variable | [variable length integer](/protocol/formats/variable-length-integer) | The size of the bloom filter to be used. |
| bloom filter data | variable | `bloom_filter_size` bytes | Raw bloom filter data (up to 36,000 bytes). |
| number of hash functions | 4 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | The number of hash functions used when generating this filter (max 50). |
| tweak | 4 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | Arbitrary number that helps randomize this bloom filter. |
| flags | 1 byte | bit field | See [bloom filter flags](#bloom-filter-flags). |
| [vector](/protocol/p2p/vector.md) of bytes | up to 36000 bytes | bit vector | bloom filter data |
| num hash funcs | 4 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | number of hash functions used when generating this filter (max 50) |
| tweak | 4 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | arbitrary number that uniquifies this bloom filter |
flags | 1 byte | bit field | bloom filter flags
### Bloom Filter Flags
protocol/network/messages/getdata.md
+17 -4
View File
@@ -5,15 +5,28 @@
# Request: Get Data (“getdata”)
Requests information (generally previously announced via an [inv](/protocol/network/messages/inv) message) from a peer.
As such, a getdata request carries the same general format as an inventory message and is used to request any items that the node was previously unaware.
Requests information (generally previously announced via an INV) from a peer.
A GETDATA request is a [vector](/protocol/p2p/vector.md) of INV-formatted data.
## Message Format
| Field | Length | Format | Description |
|--|--|--|--|
| inventory count | variable | [variable length integer](/protocol/formats/variable-length-integer) | The number of inventory items being requested in this message. |
| inventory items | `inventory_count` * 36 bytes | `inventory_count` [inventory items](/protocol/network/messages/inv#inventory-item-format) | The set of inventory items being requested. |
| vector length N | variable | compact int | number of items |
| item 0 type | 4 bytes | unsigned int<sup>[(LE)](/protocol/misc/endian/little)</sup> | type of the requested object |
| item 0 hash | 32 bytes | bytes | hash of the requested object |
| ... | | | |
| item N-1 type |
| item N-1 hash
### Type
The type of the desired object. See [INV](/protocol/network/messages/inv.md) for specific values
### Hash
The [hash identifier](glossary/hash__identifier) of the desired object.
## Server Implementations
protocol/network/messages/headers.md
+7 -16
View File
@@ -3,24 +3,15 @@
"related":["/protocol","/protocol/p2p/getheaders"]
}</div>
# Response: Headers ("headers")
*Provides a contiguous set of block headers*
Provides a contiguous set of block headers.
## HEADERS Message Format
## 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. |
|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|
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.
#### 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.
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.
protocol/network/messages/inv.md
+11 -21
View File
@@ -3,31 +3,18 @@
"related":["/protocol","/protocol/network/messages/getdata.md","/protocol/network/messages/filterload.md","/protocol/network/messages/filterclear.md"]
}</div>
# Announcement: Inventory ("inv")
*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.
Notifies peers about the existence of some information (block or transaction).
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.
Based on selected services in the [version](/protocol/network/messages/version) message, inventory messages may not be sent.
| 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
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.
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.
## 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)<sup>[(LE)](/protocol/misc/endian/little)</sup> | Indicates what the following hash represents. |
| item hash | 32 bytes | bytes<sup>[(LE)](/protocol/misc/endian/little)</sup> | The [hash](/protocol/blockchain/hash) that identifies the item. |
#### Inventory Types
##### Type
The type of the object that is available.
| Type | Value|
@@ -40,3 +27,6 @@ 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/merkleblock.md
+6 -18
View File
@@ -5,26 +5,14 @@
# Response: Merkle Block ("merkleblock")
Provides a block header and partial merkle proof tree to show that the selected transaction [hashes](/protocol/blockchain/hash) exist in the block.
*Provides a block header and partial merkle proof tree to show that selected transaction ids exist in the block.*
Transactions are selected by honest servers if they match the bloom filter installed by the client. However, note that servers can omit transactions and this cannot be detected except by receiving a merkleblock message from an honest server.
Transactions are selected by honest servers if they match the bloom filter installed by the client. However, note that servers can omit transactions and this cannot be detected except by receiving a MERKLEBLOCK message from an honest server.
All selected transactions are subsequently sent as separate [tx](/protocol/network/messages/tx) messages. Due to multi-threading on the server, clients should not assume that these transaction messages directly follow the merkleblock message.
All selected transactions are subsequently sent as separate TX messages. Due to multi-threading on the server, clients should not assume that these TX messages directly follow the MERKLEBLOCK message.
## Message Format
| Field | Length | Format | Description |
|--|--|--|--|
| block header | 80 bytes | [block header](/protocol/blockchain/block/block-header#block-header-format) | The header of the block. |
| transaction count | 4 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | The number of transactions in the block. |
| filtered transaction count | variable | [variable length integer](/protocol/formats/variable-length-integer) | The number of transactions matching the client's bloom filter. |
| transaction hashes | `transaction_count` * 32 bytes | bytes<sup>[(LE)](/protocol/misc/endian/little)</sup> | The hashes of the full set of transactions in the block, in the the order they appear in the block (i.e. depth-first order with respect to the merkle tree). |
| flag byte count | variable | [variable length integer](/protocol/formats/variable-length-integer) | The number of flags bytes to follow. |
| flag bits | `flag_count` bytes | bytes | Flag bits, collected into bytes (zero-padded to a full byte as necessary) indicating inclusion information with respect to traversal of the partial merkle tree of matches. See [partial merkle tree flag bits](#partial-merkle-tree-flag-bits). |
#### Partial Merkle Tree Flag Bits
The partial merkle tree flag bits effectively create a variable-width bitfield, indicating which transaction hashes from the block the merkleblock message pertains to actually matched the client's bloom filter.
If you picture the merkle tree root at the top, the flag bits represent a top-down yes/no approach to whether the a given branch (or leaf node) of the tree includes any matching transactions.
For full details, see [BIP-37: Partial Merkle Branch Format](/protocol/forks/bip-0037#partial-merkle-branch-format).
| ... | 4 bytes | ... | ...|
|----|---------------|-----------|------------|
| [block header](/protocol/blockchain/block/block-header.md)| # tx in block | [vector](/protocol/p2p/vector) of 32 byte hashes | [vector](/protocol/p2p/vector) of bytes that define the merkle block traversal
protocol/network/messages/reject.md
+17 -17
View File
@@ -3,29 +3,29 @@
"related":["/protocol"]
}</div>
# Response: Reject ("reject")
*Notifies peer that a message is invalid*
Notifies peer that a received message is invalid.
## Message Format
| [compact int](/protocol/p2p/compact__int.md) N (max 12) | N bytes | 1 byte | [compact int](/protocol/p2p/compact__int.md) M (max 111) | M bytes |
|----------------|---------|-------------|---------------|---------|
| command length | command | error code | reason length | reason string |
| Field | Length | Format | Description |
|--|--|--|--|
| rejected message type | variable | [variable length string](/protocol/formats/variable-length-string) | The [command string](/protocol/network/messages#command-string) of the message that is being rejected (e.g. "tx"). |
| rejection code | 1 byte | [rejection code](#rejection-codes) | A code indicating why the message was rejected. |
| rejection reason* | variable | [variable length string](/protocol/formats/variable-length-string) | A description of why the message was rejected. |
*command length* and *command* form a [vector](/protocol/p2p/vector.md) of bytes that identify the type of the problem message. These bytes (less padded nulls) match the *command* field in the protocol [message envelope](/protocol.md).
\* *rejection reason* is a string providing a human language explanation of the reason the message was rejected. This string is subject to change so client software **SHOULD NOT** use it programmatically.
*reason length* and *reason string* form a [vector](/protocol/p2p/vector.md) of bytes that is a string providing a human language explanation of the reason the message was rejected. This string is subject to change so client software **SHOULD NOT** use it programatically.
#### Rejection Codes
*error code* provides a succinct machine-interpretable reason why the message was rejected.
| Name | Value | Response To | Description |
### Reject Error Codes
| Name | Value | Response To | Description
|-------------|-------|---------------|-----------|
| REJECT_MALFORMED | 0x01 | any | Message cannot be deserialized. |
| REJECT_INVALID | 0x10 | BLOCK, TX, FILTERSIZEXTHIN | Block or transaction is invalid, or xthin filter size is too small |
| REJECT_MALFORMED | 0x01 | any | message cannot be deserialized |
| REJECT_INVALID | 0x10 | BLOCK, TX, FILTERSIZEXTHIN | block or transaction is invalid, or xthin filter size is too small |
| REJECT_OBSOLETE | 0x11 | VERSION | This node no longer supports your client protocol version |
| REJECT_DUPLICATE | 0x12 | unused | |
| REJECT_NONSTANDARD | 0x40 | TX | Transaction is [non-standard](/protocol/blockchain/transaction-validation/network-level-validation-rules#standard-transactions), or not final as per [BIP68](/protocol/forks/bip-0068). |
| REJECT_DUST | 0x41 | TX | Transaction has an output that is too small. |
| REJECT_INSUFFICIENTFEE | 0x42 | TX | Transaction does not pay enough in fees to be relayed. |
| REJECT_CHECKPOINT | 0x43 | unused | |
| REJECT_NONSTANDARD | 0x40 | TX | Transaction is [non-standard](/standard__transactions.md), or [not final](/final__transactions.md) as per BIP68 |
| REJECT_DUST | 0x41 | TX | Transaction has an output that is too small |
| REJECT_INSUFFICIENTFEE | 0x42 | TX | Transaction does not pay enough to be relayed |
| REJECT_CHECKPOINT | 0x43 | unused | |
| REJECT_WAITING | 0x44 | TX | This transaction is [not final](/final__transactions.md) |
protocol/network/messages/verack.md
+13 -3
View File
@@ -1,4 +1,4 @@
# Handshake: Version Acknowledgement ("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.
@@ -7,6 +7,16 @@ There is no version negotiation functionality between nodes; therefore if the no
This `verack` message consists of only a message header; the command string is "verack".
## Message Format
## Example Serialized Data
This message has no contents.
Net Magic<sup>[(BE)](/protocol/misc/endian/little)</sup>
`E3E1F3E8`
Command String ("verack")<sup>[(BE)](/protocol/misc/endian/big)</sup>
`76657261636B000000000000`
Payload Byte Count<sup>[(LE)](/protocol/misc/endian/little)</sup>
`00000000`
Payload Checksum<sup>[(LE)](/protocol/network/messages/message-checksum)</sup>
`5DF6E0E2`
protocol/network/messages/version.md
+4 -4
View File
@@ -1,7 +1,7 @@
# Handshake: Version (“version”)
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 Bitfield [below](#services-bitfield)).
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.
@@ -10,7 +10,7 @@ The node connection is not considered established until both nodes have sent and
| Field | Length | Format | Description |
|--|--|--|--|
| version number | 4 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | The version number supported by the sending node. |
| services | 8 bytes | bitfield<sup>[(LE)](/protocol/misc/endian/little)</sup> | An indication of the services supported by the sending node. See Services Bitfield section below. |
| services | 8 bytes | bitmask<sup>[(LE)](/protocol/misc/endian/little)</sup> | An indication of the services supported by the sending node. See Services Bitmask section below. |
| timestamp | 8 bytes | unix timestamp<sup>[(LE)](/protocol/misc/endian/little)</sup> | The time the message was generated on the sending node. |
| remote address | 26 bytes | [network address](/protocol/formats/network-address) | The network address of the remote node. <p>_NOTE: this does not contain the timestamp normally included with network addresses._</p> |
| local address | 26 bytes | [network address](/protocol/formats/network-address) | The network address of the sending node. <p>_NOTE: this does not contain the timestamp normally included with network addresses._</p> |
@@ -30,11 +30,11 @@ Modern Nodes ignore extra data after the `relay flag`.
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` bitfield to determine if the node should accept the incoming connection.
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 Bitfield
## 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: