doc/p2p/p2p_protocol.md
There are currently 19 different types of P2P Messages:
| Id | Message Type | Description |
|---|---|---|
| 0 | Error | Sent when an issue is found during communication with a peer. Usually followed by closing the connection. |
| 1 | Hand | First part of a handshake, sender advertises its version and characteristics. |
| 2 | Shake | Second part of a handshake, receiver of the first part replies with its own version and characteristics. |
| 3 | Ping | Sent to confirm that the connection is still valid, and used to advertise the node's total_difficulty to confirm whether sync is needed. |
| 4 | Pong | The response to a ping message. |
| 5 | GetPeerAddrs | Used to request addresses of new peers to connect to. |
| 6 | PeerAddrs | Peer addresses sent in response to a GetPeerAddrs message. |
| 7 | GetHeaders | Used to request block headers from a peer. |
| 8 | Header | A single block header received from a peer. |
| 9 | Headers | Multiple block headers received from a peer in response to a GetHeaders message. |
| 10 | GetBlock | Used to request a block from a peer. |
| 11 | Block | A single block received from a peer. |
| 12 | GetCompactBlock | Used to request a compact block from a peer. |
| 13 | CompactBlock | A single compact block received from a peer. |
| 14 | StemTransaction | A stem transaction received from a peer. |
| 15 | Transaction | A transaction received from a peer. |
| 16 | TxHashSetRequest | Used to request the transaction hashset from a peer. |
| 17 | TxHashSetArchive | The transaction hashset in response to the TxHashSetRequest message. |
| 18 | BanReason | Contains the reason your node was banned by a peer. |
All P2P messages follow a generic message structure as follows.
| Size | Name | Data Type | Description/Comments |
|---|---|---|---|
| 2 | Magic | uint8[2] | Magic number used to identify Grin packets. Always hard-coded as {0x1E, 0xC5}. |
| 1 | Type | MessageTypeEnum | Identifier of the packet content. |
| 8 | Length | uint64 | The total length of the message. This will not include the header size (11 bytes). |
| ? | Payload | uint8[] | The actual data. |
TODO: Provide example
| Size | Name | Data Type | Description/Comments |
|---|---|---|---|
| 1 | IPAddressFamily | uint8 | Identifies the IP address family. 0 = IPv4, 1 = IPv6. |
| 4/16 | IPAddress | uint8[4]/uint16[8] | The IP address. 4 octets for IPv4 or 8 hexadecets for IPv6. |
| 2 | Port | uint16 | The TCP/IP port number. |
| Value | Name | Description |
|---|---|---|
| 0x00 | Unknown | We don't know (yet) what the peer can do. |
| 0x01 | Full History | Full archival node, has the whole history without any pruning. |
| 0x02 | TxHashSet History | Can provide block headers and the TxHashSet for some recent-enough height. |
| 0x04 | Peer List | Can provide a list of healthy peers. |
| 0x06 | Fast Sync Node | Both "TxHashSet History" and "Peer List" |
| 0x07 | Full Node | "Full History", "TxHashSet History", and "Peer List" |
| Size | Name | Data Type | Description/Comments |
|---|---|---|---|
| ? | Inputs | TxInput[] | List of inputs spent by the transaction. |
| ? | Outputs | TxOutput[] | List of outputs the transaction produces. |
| ? | Kernels | TxKernel[] | List of kernels that make up this transaction (usually a single kernel). |
| Size | Name | Data Type | Description/Comments |
|---|---|---|---|
| ? | FullOutputs | TxOutput[] | List of full outputs - specifically the coinbase output(s). |
| ? | FullKernels | TxKernel[] | List of full kernels - specifically the coinbase kernel(s). |
| ? | KernelIds | ShortId[] | List of transaction kernels, excluding those in the full list. Each ShortId is 6 bytes. |
| Size | Name | Data Type | Description/Comments |
|---|---|---|---|
| 8 | TotalDifficulty | uint64 | Total accumulated difficulty since genesis block. |
| 4 | ScalingDifficulty | uint32 | Difficulty scaling factor between the different proofs of work. |
| 8 | Nonce | uint64 | Nonce increment used to mine the block. |
| 1 | EdgeBits | uint8 | Power of 2 used for the size of the cuckoo graph. |
| 336 | ProofNonces | uint64[42] | The cuckoo proof nonces. |
| Size | Name | Data Type | Description/Comments |
|---|---|---|---|
| 4 | Code | uint32 | Error Code. TODO: Determine possible values. |
| ? | Message | VAR_STR | Slightly more user-friendly message |
| Size | Name | Data Type | Description/Comments |
|---|---|---|---|
| 4 | Version | uint32 | Protocol version of the sender. |
| 1 | Capabilities | CapabilitiesMask | Bitmask representing the capabilities of the sender. |
| 8 | Nonce | uint64 | Randomly generated for each handshake to help detect connections to yourself. |
| 8 | TotalDifficulty | uint64 | Total difficulty accumulated by the sender. Used to check whether sync may be needed. |
| 7/19 | SenderAddress | SocketAddress | Network address of the sender. 7 bytes for IPv4 or 19 bytes for IPv6. |
| 7/19 | ReceiverAddress | SocketAddress | Network address of the receiver. 7 bytes for IPv4 or 19 bytes for IPv6. |
| ? | UserAgent | VAR_STR | Name and version of the software. Example: "MW/Grin 0.1.2" |
| 32 | Hash | uint8[32] | Genesis block of the current chain. Testnet1/2/3 and mainnet all have a different genesis. |
| Size | Name | Data Type | Description/Comments |
|---|---|---|---|
| 4 | Version | uint32 | Protocol version of the sender. |
| 1 | Capabilities | CapabilitiesMask | Bitmask representing the capabilities of the sender. |
| 8 | Nonce | uint64 | Randomly generated for each handshake to help detect connections to yourself. |
| 8 | TotalDifficulty | uint64 | Total difficulty accumulated by the sender. Used to check whether sync may be needed. |
| ? | UserAgent | VAR_STR | Name and version of the software. Example: "MW/Grin 0.1.2" |
| 32 | Hash | uint8[32] | Genesis block of the current chain. Testnet1/2/3 and mainnet all have a different genesis. |
| Size | Name | Data Type | Description/Comments |
|---|---|---|---|
| 8 | TotalDifficulty | uint64 | Total difficulty accumulated by the sender. Used to check whether sync may be needed. |
| 8 | Height | uint64 | Total block height accumulated by the sender. See: https://github.com/mimblewimble/grin/issues/1779 |
| Size | Name | Data Type | Description/Comments |
|---|---|---|---|
| 8 | TotalDifficulty | uint64 | Total difficulty accumulated by the sender. Used to check whether sync may be needed. |
| 8 | Height | uint64 | Total block height accumulated by the sender. See: https://github.com/mimblewimble/grin/issues/1779 |
| Size | Name | Data Type | Description/Comments |
|---|---|---|---|
| 1 | Capabilities | CapabilitiesMask | The capabilities the peer should have. |
| Size | Name | Data Type | Description/Comments |
|---|---|---|---|
| 4 | Size | uint32_t | The number of peer addresses received. |
| ? | Peers | SocketAddress[] | Peer addresses that match the criteria from the GetPeerAddresses request. |
| Size | Name | Data Type | Description/Comments |
|---|---|---|---|
| 1 | Size | uint8_t | The number of headers being requested. |
| ? | Hashes | Hash[] | The 32-byte Blake2b hashes of the block headers being requested. |
| Size | Name | Data Type | Description/Comments |
|---|---|---|---|
| 2 | Version | uint16 | The version of the block. |
| 8 | Height | uint64 | Height of this block since the genesis block (height 0). |
| 8 | Timestamp | int64 | Timestamp at which the block was built. |
| 32 | Previous | Hash | Blake2b hash of the block previous to this in the chain. |
| 32 | PreviousRoot | Hash | Merklish root of all the commitments in the previous block's TxHashSet. |
| 32 | OutputRoot | Hash | Merklish root of all the commitments in the TxHashSet. |
| 32 | RangeProofRoot | Hash | Merklish root of all range proofs in the TxHashSet. |
| 32 | KernelRoot | Hash | Merklish root of all transaction kernels in the TxHashSet. |
| 32 | TotalKernelOffset | BlindingFactor | Total accumulated sum of kernel offsets since genesis block. |
| 8 | OutputMMRSize | uint64 | Total size of the output Merkle Mountain Range(MMR) after applying this block. |
| 8 | KernelMMRSize | uint64 | Total size of the kernel MMR after applying this block. |
| 178 | ProofOfWork | ProofOfWork | Proof of work and related. |
| Size | Name | Data Type | Description/Comments |
|---|---|---|---|
| 2 | Size | uint16_t | The number of headers received. |
| ? | Headers | BlockHeader[] | The headers matching the hashes provided in the GetBlockHeaders request. |
| Size | Name | Data Type | Description/Comments |
|---|---|---|---|
| 32 | BlockHash | Hash | The Blake2b hash of the block being requested. |
| Size | Name | Data Type | Description/Comments |
|---|---|---|---|
| 405 | Header | BlockHeader | The block header. |
| ? | Body | TransactionBody | The block transaction containing the inputs, outputs, and kernel(s). |
| Size | Name | Data Type | Description/Comments |
|---|---|---|---|
| 32 | BlockHash | Hash | The Blake2b hash of the compact block being requested. |
| Size | Name | Data Type | Description/Comments |
|---|---|---|---|
| 405 | Header | BlockHeader | The header with metadata and commitments to the rest of the data. |
| 8 | Nonce | uint64 | Nonce for connection specific short_ids. |
| ? | Body | CompactBlockBody | Container for out_full, kern_full and kern_ids in the compact block. |
| Size | Name | Data Type | Description/Comments |
|---|---|---|---|
| 32 | Offset | BlindingFactor | The kernel "offset" k2. |
| ? | Body | TransactionBody | The transaction body containing the inputs, outputs, and kernel(s). |
| Size | Name | Data Type | Description/Comments |
|---|---|---|---|
| 32 | Offset | BlindingFactor | The kernel "offset" k2. |
| ? | Body | TransactionBody | The transaction body containing the inputs, outputs, and kernel(s). |
| Size | Name | Data Type | Description/Comments |
|---|---|---|---|
| 32 | BlockHash | Hash | Blake2b hash of the block for which the TxHashSet should be provided. |
| 8 | Height | uint64 | Height of the corresponding block. |
The response to a TxHashSetRequest. Includes a zip stream of the archive after the message body.
| Size | Name | Data Type | Description/Comments |
|---|---|---|---|
| 32 | BlockHash | Hash | Blake2b hash of the block for which the txhashset are provided. |
| 8 | Height | uint64 | Height of the corresponding block. |
| 8 | Bytes | uint64 | Size in bytes of the archive. |
| Size | Name | Data Type | Description/Comments |
|---|---|---|---|
| 4 | BanReason | ReasonForBanEnum | The reason for the ban. |
Any feature that users will have the ability to disable should be implemented as a new capability (See CapabilitiesMask above). This includes things like archive mode/full history.
Any change to the p2p protocol that is not toggled by the addition of a new capability should result in an increase in protocol version (See Hand & Shake messages above). This includes any addition or removal of a field or entire message, or any backward-incompatible behavior change to an existing field or message. When interacting with peers on an older protocol version, backward compatibility must be maintained, so the newer node should follow the rules of the older protocol version.
To reduce the long-term complexity of the code, we can periodically bump the "major" protocol version. Although the protocol version is just a uint32, we can consider every increase by 1000 a new "major" protocol version. We can then gracefully phase out stubborn peers that refuse to upgrade by only supporting 1 major protocol version in the past. Here's what this would look like in practice:
Determining when to increase the "major" version is left up to the discretion of the developers. Care must be taken to ensure we are not increasing too quickly however, as any major bump could result in the inability to connect to certain older peers.