logoDocumentation
Standards

Avalanche Network Protocol

Overview

Avalanche network defines the core communication format between Avalanche nodes. It uses the primitive serialization format for payload packing.

"Containers" are mentioned extensively in the description. A Container is simply a generic term for blocks.

This document describes the protocol for peer-to-peer communication using Protocol Buffers (proto3). The protocol defines a set of messages exchanged between peers in a peer-to-peer network. Each message is represented by the Message proto message, which can encapsulate various types of messages, including network messages, state-sync messages, bootstrapping messages, consensus messages, and application messages.

Message

The Message proto message is the main container for all peer-to-peer communication. It uses the oneof construct to represent different message types. The supported compression algorithms include Gzip and Zstd.

message Message {
  oneof message {
    bytes compressed_gzip = 1;
    bytes compressed_zstd = 2;
    // ... (other compression algorithms can be added)
    Ping ping = 11;
    Pong pong = 12;
    Version version = 13;
    PeerList peer_list = 14;
    // ... (other message types)
  }
}

Compression

The compressed_gzip and compressed_zstd fields are used for Gzip and Zstd compression, respectively, of the encapsulated message. These fields are set only if the message type supports compression.

Network Messages

Ping

The Ping message reports a peer's perceived uptime percentage.

message Ping {
  uint32 uptime = 1;
  repeated SubnetUptime subnet_uptimes = 2;
}
  • uptime: Uptime percentage on the primary network [0, 100].
  • subnet_uptimes: Uptime percentages on Avalanche L1s.

Pong

The Pong message is sent in response to a Ping with the perceived uptime of the peer.

message Pong {
  uint32 uptime = 1; // Deprecated: uptime is now sent in Ping
  repeated SubnetUptime subnet_uptimes = 2; // Deprecated: uptime is now sent in Ping
}

Version

The Version message is the first outbound message sent to a peer during the p2p handshake.

message Version {
  uint32 network_id = 1;
  uint64 my_time = 2;
  bytes ip_addr = 3;
  uint32 ip_port = 4;
  string my_version = 5;
  uint64 my_version_time = 6;
  bytes sig = 7;
  repeated bytes tracked_subnets = 8;
}
  • network_id: Network identifier (e.g., local, testnet, Mainnet).
  • my_time: Unix timestamp when the Version message was created.
  • ip_addr: IP address of the peer.
  • ip_port: IP port of the peer.
  • my_version: Avalanche client version.
  • my_version_time: Timestamp of the IP.
  • sig: Signature of the peer IP port pair at a provided timestamp.
  • tracked_subnets: Avalanche L1s the peer is tracking.

PeerList

The PeerList message contains network-level metadata for a set of validators.

message PeerList {
  repeated ClaimedIpPort claimed_ip_ports = 1;
}
  • claimed_ip_ports: List of claimed IP and port pairs.

PeerListAck

The PeerListAck message is sent in response to PeerList to acknowledge the subset of peers that the peer will attempt to connect to.

message PeerListAck {
  reserved 1; // deprecated; used to be tx_ids
  repeated PeerAck peer_acks = 2;
}
  • peer_acks: List of acknowledged peers.

State-Sync Messages

GetStateSummaryFrontier

The GetStateSummaryFrontier message requests a peer's most recently accepted state summary.

message GetStateSummaryFrontier {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
}
  • chain_id: Chain being requested from.
  • request_id: Unique identifier for this request.
  • deadline: Timeout (ns) for this request.

StateSummaryFrontier

The StateSummaryFrontier message is sent in response to a GetStateSummaryFrontier request.

message StateSummaryFrontier {
  bytes chain_id = 1;
  uint32 request_id = 2;
  bytes summary = 3;
}
  • chain_id: Chain being responded from.
  • request_id: Request ID of the original GetStateSummaryFrontier request.
  • summary: The requested state summary.

GetAcceptedStateSummary

The GetAcceptedStateSummary message requests a set of state summaries at specified block heights.

message GetAcceptedStateSummary {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
  repeated uint64 heights = 4;
}
  • chain_id: Chain being requested from.
  • request_id: Unique identifier for this request.
  • deadline: Timeout (ns) for this request.
  • heights: Heights being requested.

AcceptedStateSummary

The AcceptedStateSummary message is sent in response to GetAcceptedStateSummary.

message AcceptedStateSummary {
  bytes chain_id = 1;
  uint32 request_id = 2;
  repeated bytes summary_ids = 3;
}
  • chain_id: Chain being responded from.
  • request_id: Request ID of the original GetAcceptedStateSummary request.
  • summary_ids: State summary IDs.

Bootstrapping Messages

GetAcceptedFrontier

The GetAcceptedFrontier message requests the accepted frontier from a peer.

message GetAcceptedFrontier {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
  EngineType engine_type = 4;
}
  • chain_id: Chain being requested from.
  • request_id: Unique identifier for this request.
  • deadline: Timeout (ns) for this request.
  • engine_type: Consensus type the remote peer should use to handle this message.

AcceptedFrontier

The AcceptedFrontier message contains the remote peer's last accepted frontier.

message AcceptedFrontier {
  reserved 4; // Until Cortina upgrade is activated
  bytes chain_id = 1;
  uint32 request_id = 2;
  bytes container_id = 3;
}
  • chain_id: Chain being responded from.
  • request_id: Request ID of the original GetAcceptedFrontier request.
  • container_id: The ID of the last accepted frontier.

GetAccepted

The GetAccepted message sends a request with the sender's accepted frontier to a remote peer.

message GetAccepted {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
  repeated bytes container_ids = 4;
  EngineType engine_type = 5;
}
  • chain_id: Chain being requested from.
  • request_id: Unique identifier for this message.
  • deadline: Timeout (ns) for this request.
  • container_ids: The

sender's accepted frontier.

  • engine_type: Consensus type to handle this message.

Accepted

The Accepted message is sent in response to GetAccepted.

message Accepted {
  reserved 4; // Until Cortina upgrade is activated
  bytes chain_id = 1;
  uint32 request_id = 2;
  repeated bytes container_ids = 3;
}
  • chain_id: Chain being responded from.
  • request_id: Request ID of the original GetAccepted request.
  • container_ids: Subset of container IDs from the GetAccepted request that the sender has accepted.

GetAncestors

The GetAncestors message requests the ancestors for a given container.

message GetAncestors {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
  bytes container_id = 4;
  EngineType engine_type = 5;
}
  • chain_id: Chain being requested from.
  • request_id: Unique identifier for this request.
  • deadline: Timeout (ns) for this request.
  • container_id: Container for which ancestors are being requested.
  • engine_type: Consensus type to handle this message.

Ancestors

The Ancestors message is sent in response to GetAncestors.

message Ancestors {
  reserved 4; // Until Cortina upgrade is activated
  bytes chain_id = 1;
  uint32 request_id = 2;
  repeated bytes containers = 3;
}
  • chain_id: Chain being responded from.
  • request_id: Request ID of the original GetAncestors request.
  • containers: Ancestry for the requested container.

Consensus Messages

Get

The Get message requests a container from a remote peer.

message Get {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
  bytes container_id = 4;
  EngineType engine_type = 5;
}
  • chain_id: Chain being requested from.
  • request_id: Unique identifier for this request.
  • deadline: Timeout (ns) for this request.
  • container_id: Container being requested.
  • engine_type: Consensus type to handle this message.

Put

The Put message is sent in response to Get with the requested block.

message Put {
  bytes chain_id = 1;
  uint32 request_id = 2;
  bytes container = 3;
  EngineType engine_type = 4;
}
  • chain_id: Chain being responded from.
  • request_id: Request ID of the original Get request.
  • container: Requested container.
  • engine_type: Consensus type to handle this message.

PushQuery

The PushQuery message requests the preferences of a remote peer given a container.

message PushQuery {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
  bytes container = 4;
  EngineType engine_type = 5;
  uint64 requested_height = 6;
}
  • chain_id: Chain being requested from.
  • request_id: Unique identifier for this request.
  • deadline: Timeout (ns) for this request.
  • container: Container being gossiped.
  • engine_type: Consensus type to handle this message.
  • requested_height: Requesting peer's last accepted height.

PullQuery

The PullQuery message requests the preferences of a remote peer given a container id.

message PullQuery {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
  bytes container_id = 4;
  EngineType engine_type = 5;
  uint64 requested_height = 6;
}
  • chain_id: Chain being requested from.
  • request_id: Unique identifier for this request.
  • deadline: Timeout (ns) for this request.
  • container_id: Container id being gossiped.
  • engine_type: Consensus type to handle this message.
  • requested_height: Requesting peer's last accepted height.

Chits

The Chits message contains the preferences of a peer in response to a PushQuery or PullQuery message.

message Chits {
  bytes chain_id = 1;
  uint32 request_id = 2;
  bytes preferred_id = 3;
  bytes accepted_id = 4;
  bytes preferred_id_at_height = 5;
}
  • chain_id: Chain being responded from.
  • request_id: Request ID of the original PushQuery/PullQuery request.
  • preferred_id: Currently preferred block.
  • accepted_id: Last accepted block.
  • preferred_id_at_height: Currently preferred block at the requested height.

Application Messages

AppRequest

The AppRequest message is a VM-defined request.

message AppRequest {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
  bytes app_bytes = 4;
}
  • chain_id: Chain being requested from.
  • request_id: Unique identifier for this request.
  • deadline: Timeout (ns) for this request.
  • app_bytes: Request body.

AppResponse

The AppResponse message is a VM-defined response sent in response to AppRequest.

message AppResponse {
  bytes chain_id = 1;
  uint32 request_id = 2;
  bytes app_bytes = 3;
}
  • chain_id: Chain being responded from.
  • request_id: Request ID of the original AppRequest.
  • app_bytes: Response body.

AppGossip

The AppGossip message is a VM-defined message.

message AppGossip {
  bytes chain_id = 1;
  bytes app_bytes = 2;
}
  • chain_id: Chain the message is for.
  • app_bytes: Message body.

Last updated on

On this page

Edit on Github