Files
specification/protocol/network/messages.md
T

91 lines
4.3 KiB
Markdown
Raw Normal View History

2019-12-17 17:16:21 -05:00
# P2P Network Message
2019-12-12 16:07:58 -05:00
2019-12-12 16:29:39 -05:00
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.
2019-12-12 17:11:33 -05:00
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.
2019-12-12 16:29:39 -05:00
These design decisions were made with consideration to communication with untrusted/uncooperative partners.
2019-12-12 17:11:33 -05:00
*Developer Notes: A common message strategy is to wait for any message that provides the required data (with a timeout), and then separately issue the request in a retry loop to multiple peers.*
2019-12-12 16:07:58 -05:00
## Message Format
The P2P network has a variety of message types. All P2P messages follow a binary format with the following structure:
| Field | Length | Format |
2019-12-17 16:38:53 -05:00
|--|--|--|
2019-12-18 13:53:44 -05:00
| 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> |
2019-12-12 16:07:58 -05:00
| payload byte count | 4 bytes | integer<sup>[(LE)](/protocol/misc/endian/little)</sup> |
2019-12-18 13:53:44 -05:00
| payload checksum | 4 bytes | byte array<sup>[(BE)](/protocol/misc/endian/big)</sup> |
2019-12-12 16:07:58 -05:00
| payload | variable | |
### Net Magic
2019-12-18 15:07:17 -05:00
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.
2019-12-12 16:07:58 -05:00
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
2019-12-18 15:17:50 -05:00
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.
2019-12-12 16:07:58 -05:00
The following messages are considered standard by all node implementations.
2019-12-12 16:13:05 -05:00
| Command String | Name |
2019-12-12 16:07:58 -05:00
| -- | -- |
| version | [Handshake: Version](/protocol/network/messages/version) |
| verack | [Handshake: Acknowledge Version](/protocol/network/messages/verack) |
| ping | [Ping](/protocol/network/messages/ping) |
| pong | [Pong](/protocol/network/messages/pong) |
| addr | |
| getblocks | |
| inv | |
| mempool | |
| getheaders | |
| headers | |
| getdata | |
| block | |
| tx | |
| merkleblock | |
| notfound | |
| reject | |
| sendheaders | |
| feefilter | |
| getaddr | |
| filterload | |
| filteradd | |
| filterclear | |
The following messages are well known, but not implemented by all node implementations.
2019-12-12 16:13:05 -05:00
| Command String | Name | Supported Implementations |
2019-12-12 16:07:58 -05:00
| -- | -- | -- |
| sendcmpct | | |
| get_xthin | | |
| xthinblock | | |
| thinblock | | |
| get_xblocktx | | |
2019-12-12 17:18:18 -05:00
| xblocktx | | |
### Payload Byte Count
2019-12-18 13:53:44 -05:00
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.
2019-12-18 13:26:26 -05:00
2019-12-12 17:18:18 -05:00
### Payload Checksum
2019-12-18 13:53:44 -05:00
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).
2019-12-18 13:26:26 -05:00
2019-12-18 13:53:44 -05:00
### Payload
The message payload is defined by the message type.
# Node Specific Behavior
2019-12-18 15:29:59 -05:00
## Bitcoin Unlimited
2019-12-18 13:53:44 -05:00
### Payload Checksum
Bitcoin ABC does not validate the message checksum since messages are sent via TCP which has its own checksum paradigm.