P2P Protocol

P2P Messages

WARNING: This document is still in progress and has not yet been reviewed by any of the core Grin developers.

Message Types

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.

Message structure

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 be 11 + the payload size.
?	Payload	uint8[]	The actual data.

TODO: Provide example

Common structures

TODO: Populate common structures

Variable-length strings are encoded in UTF8, and are preceded with a uint64 indicating their lengths.

SocketAddress

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.

Messages

Error

Size	Name	Data Type	Description/Comments
4	Code	uint32	Error Code. TODO: Determine possible values.
?	Message	String	Slightly more user-friendly message

Hand

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.
32	Hash	uint8[32]	Genesis block of the current chain. Testnet1/2/3 and mainnet all have a different genesis.
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	String	Name and version of the software. Example: "MW/Grin 0.1.2"

Shake

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.
32	Hash	uint8[32]	Genesis block of the current chain. Testnet1/2/3 and mainnet all have a different genesis.
8	TotalDifficulty	uint64	Total difficulty accumulated by the sender. Used to check whether sync may be needed.
?	UserAgent	String	Name and version of the software. Example: "MW/Grin 0.1.2"

Ping

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

Pong

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

GetPeerAddrs

PeerAddrs

GetHeaders

Header

Headers

GetBlock

Block

GetCompactBlock

CompactBlock

StemTransaction

Transaction

TxHashSetRequest

TxHashSetArchive

BanReason