Skip to content

Network Messages in Ergo's P2P Protocol#

This document provides a detailed overview of the network messages in Ergo's P2P protocol. Understanding these messages is crucial for interacting with the Ergo network at a low level. Each message in the protocol has a specific format and serves a unique purpose in the communication between nodes.

Message Format#

Every message in the P2P protocol has the following format:

Data type Field name Details
byte[4] Magic bytes For the mainnet, the magic bytes are {1, 0, 2, 4}. For testnet, {2, 0, 0, 1}.
unsigned byte Message code One byte describing message type
int Message body length No VLQ or ZigZag encoding is used for the message length (for historical reasons); bytes are coming in big-endian order.
byte[4] Handshake body checksum First four bytes of blake2b256(message body)
byte[bodyLength] Message body Message body

For more detailed implementation, you can check out the Ergo Node View Synchronizer in the Ergo repository.

Records#

Records are structured data types used in the P2P protocol. They include Peer, Feature, Modifier, and Header records.

Peer#

Data type Field name Details
unsigned byte Length of next field
UTF-8 String Agent name
byte[3] Version For example, {4, 0, 25}
unsigned byte Length of next field
UTF-8 String Peer name
boolean Whether public address exists
(unsigned byte) Length of the IP plus 4 When decoding, subtract the value with 4 to get the actual length
(byte[ipLength - 4]) The public IP address
(VLQ unsigned int) Port
unsigned byte Count of peer features
Feature[featureCount] Features

Feature#

Data type Field name
unsigned byte Feature code
VLQ unsigned short Body length
byte[bodyLength] Body

Modifier (Record)#

Data type Field name
byte[32] Modifier ID
VLQ unsigned int Length of object
byte[objectLength] Object
Data type Field name
VLQ unsigned short Length of bytes
byte[length] Bytes

For a deeper understanding of how records are serialized, check out the Ergo Serialization Documentation.

Messages#

Messages are the primary means of communication between nodes in the P2P network. They include Get Peers, Peers, Sync Info, Inv, Request Modifier, and Modifier messages.

Get Peers#

Code = 1

The body is empty.

Peers#

Code = 2

Sent in response to Get Peers. Contains all the peers that are currently connected to. Used for node discovery.

Data type Field name
VLQ ZZ int Count of peers
Peer[] Peers

For the Java implementation of the GetPeers message, refer to Ergonnection.

Sync Info#

Code = 65

New (Added in 4.0.16)

It is sent only to nodes that report a version of 4.0.16 or higher. For older nodes, the Sync Info (old) is sent.

Requests an Inv message that provides modifier IDs required by the sender to synchronize their blockchain with the recipient. It allows a peer which has been disconnected or started for the first time to get the data it needs to request the blocks it hasn't seen.

Data type Field name
VLQ unsigned short The constant value 0
byte The constant value -1
unsigned byte Count of headers
Header[headerCount] Headers

Sync Info (old)#

Code = 65

The old (before 4.0.16) version of the Sync Info message.

Data type Field name
VLQ unsigned short Count of last header IDs
byte[32][lastHeaderIdCount] Last header IDs (ID byte arrays)

Inv#

Code = 55

Transmits one or more inventories of objects known to the transmitting peer.

It can be sent unsolicited to announce new transactions or blocks, or it can be sent in reply to a Sync Info message.

Data type Field name
unsigned byte Type ID
VLQ unsigned int Count of elements
byte[32][elementCount] Elements (ID byte arrays)

For an example of how INV messages are handled, see InvSpec.scala.

Request Modifier#

Code = 22

Requests one or more modifiers from another node. The objects are requested by an inventory, which the requesting node typically received previously with an Inv message.

This message cannot be used to request arbitrary data, such as historic transactions no longer in the memory pool. Full nodes may not even be able to provide older blocks if they've pruned old transactions from their block database.

For this reason, this message should usually only be used to request data from a node that previously advertised it had that data by sending an Inv message.

Data type Field name
unsigned byte Modifier type ID
VLQ unsigned int Count of elements
byte[32][elementCount] Elements (ID byte arrays)

Modifier#

Code = 33

Sent in response to Request Modifier.

Data type Field name
unsigned byte Type ID
VLQ unsigned int Count of modifiers
Modifier[modifierCount] Modifiers

Pull Requests (PRs) & Tests#

The NiPoPoW powered bootstrapping PR #1365 is a relevant enhancement that introduces a method to bootstrap nodes using Non-Interactive Proofs of Proof-of-Work (NiPoPoWs).

Tests for parsing networking messages against test vectors are discussed in PR #1264, which includes:

  • Enhanced validation with require() for non-elidable checks.
  • Simplified test vectors for invalid PoW solution validation and handshake parsing.
  • Introduced SyncInfo networking message parsing test (can be used as a simple spec).

These tests ensure robust handling of network messages in Ergo’s P2P protocol.

Demo Applications#

Demo applications are available for practical implementation, such as:

These demos provide examples of how to generate addresses and print transactions using the Ergo wallet functionalities.

Resources#

  • A simple implementation of VLQ and ZigZag encoding can be found here.
  • A complete implementation of the P2P protocol written in Java can be found in Ergonnection.