github.com/MetalBlockchain/metalgo@v1.11.9/proto/p2p/p2p.proto

syntax = "proto3";

package p2p;

// Reference: https://developers.google.com/protocol-buffers/docs/proto3
option go_package = "github.com/ava-labs/avalanchego/proto/pb/p2p";

// Represents peer-to-peer messages.
// Only one type can be non-null.
message Message {
  reserved 1; // Until E upgrade is activated.
  reserved 36; // Next unused field number.
  // NOTES
  // Use "oneof" for each message type and set rest to null if not used.
  // That is because when the compression is enabled, we don't want to include uncompressed fields.
  oneof message {
    // zstd-compressed bytes of a "p2p.Message" whose "oneof" "message" field is
    // NOT compressed_* BUT one of the message types (e.g. ping, pong, etc.).
    // This field is only set if the message type supports compression.
    bytes compressed_zstd = 2;

    // Fields lower than 10 are reserved for other compression algorithms.
    // TODO: support COMPRESS_SNAPPY

    // Network messages:
    Ping ping = 11;
    Pong pong = 12;
    Handshake handshake = 13;
    GetPeerList get_peer_list = 35;
    PeerList peer_list = 14;

    // State-sync messages:
    GetStateSummaryFrontier get_state_summary_frontier = 15;
    StateSummaryFrontier state_summary_frontier = 16;
    GetAcceptedStateSummary get_accepted_state_summary = 17;
    AcceptedStateSummary accepted_state_summary = 18;

    // Bootstrapping messages:
    GetAcceptedFrontier get_accepted_frontier = 19;
    AcceptedFrontier accepted_frontier = 20;
    GetAccepted get_accepted = 21;
    Accepted accepted = 22;
    GetAncestors get_ancestors = 23;
    Ancestors ancestors = 24;

    // Consensus messages:
    Get get = 25;
    Put put = 26;
    PushQuery push_query = 27;
    PullQuery pull_query = 28;
    Chits chits = 29;

    // App messages:
    AppRequest app_request = 30;
    AppResponse app_response = 31;
    AppGossip app_gossip = 32;
    AppError app_error = 34;
  }
}

// Ping reports a peer's perceived uptime percentage.
//
// Peers should respond to Ping with a Pong.
message Ping {
  // Uptime percentage on the primary network [0, 100]
  uint32 uptime = 1;
  // Uptime percentage on subnets
  repeated SubnetUptime subnet_uptimes = 2;
}

// SubnetUptime is a descriptor for a peer's perceived uptime on a subnet.
message SubnetUptime {
  // Subnet the peer is validating
  bytes subnet_id = 1;
  // Uptime percentage on the subnet [0, 100]
  uint32 uptime = 2;
}

// Pong is sent in response to a Ping.
message Pong {
  reserved 1, 2; // Until E upgrade is activated.
}

// Handshake is the first outbound message sent to a peer when a connection is
// established to start the p2p handshake.
//
// Peers must respond to a Handshake message with a PeerList message to allow the
// peer to connect to other peers in the network.
//
// Peers should drop connections to peers with incompatible versions.
message Handshake {
  reserved 5; // Until E upgrade is activated.
  // Network the peer is running on (e.g local, testnet, mainnet)
  uint32 network_id = 1;
  // Unix timestamp when this Handshake message was created
  uint64 my_time = 2;
  // IP address of the peer
  bytes ip_addr = 3;
  // IP port of the peer
  uint32 ip_port = 4;
  // Timestamp of the IP
  uint64 ip_signing_time = 6;
  // Signature of the peer IP port pair at a provided timestamp with the TLS
  // key.
  bytes ip_node_id_sig = 7;
  // Subnets the peer is tracking
  repeated bytes tracked_subnets = 8;
  Client client = 9;
  repeated uint32 supported_acps = 10;
  repeated uint32 objected_acps = 11;
  BloomFilter known_peers = 12;
  // Signature of the peer IP port pair at a provided timestamp with the BLS
  // key.
  bytes ip_bls_sig = 13;
}

// Metadata about a peer's P2P client used to determine compatibility
message Client {
  // Client name (e.g avalanchego)
  string name = 1;
  // Client semantic version
  uint32 major = 2;
  uint32 minor = 3;
  uint32 patch = 4;
}

// BloomFilter with a random salt to prevent consistent hash collisions
message BloomFilter {
  bytes filter = 1;
  bytes salt = 2;
}

// ClaimedIpPort contains metadata needed to connect to a peer
message ClaimedIpPort {
  // X509 certificate of the peer
  bytes x509_certificate = 1;
  // IP address of the peer
  bytes ip_addr = 2;
  // IP port of the peer
  uint32 ip_port = 3;
  // Timestamp of the IP address + port pair
  uint64 timestamp = 4;
  // Signature of the IP port pair at a provided timestamp
  bytes signature = 5;
  // P-Chain transaction that added this peer to the validator set
  bytes tx_id = 6;
}

// GetPeerList contains a bloom filter of the currently known validator IPs.
//
// GetPeerList must not be responded to until finishing the handshake. After the
// handshake is completed, GetPeerlist messages should be responded to with a
// Peerlist message containing validators that are not present in the bloom
// filter.
message GetPeerList {
  BloomFilter known_peers = 1;
}

// PeerList contains network-level metadata for a set of validators.
//
// PeerList must be sent in response to an inbound Handshake message from a
// remote peer a peer wants to connect to. Once a PeerList is received after
// a Handshake message, the p2p handshake is complete and the connection is
// established.
//
// PeerList should be sent in response to a GetPeerlist message if the handshake
// has been completed.
message PeerList {
  repeated ClaimedIpPort claimed_ip_ports = 1;
}

// GetStateSummaryFrontier requests a peer's most recently accepted state
// summary
message GetStateSummaryFrontier {
  // Chain being requested from
  bytes chain_id = 1;
  // Unique identifier for this request
  uint32 request_id = 2;
  // Timeout (ns) for this request
  uint64 deadline = 3;
}

// StateSummaryFrontier is sent in response to a GetStateSummaryFrontier request
message StateSummaryFrontier {
  // Chain being responded from
  bytes chain_id = 1;
  // Request id of the original GetStateSummaryFrontier request
  uint32 request_id = 2;
  // The requested state summary
  bytes summary = 3;
}

// GetAcceptedStateSummary requests a set of state summaries at a set of
// block heights
message GetAcceptedStateSummary {
  // Chain bein requested from
  bytes chain_id = 1;
  // Unique identifier for this request
  uint32 request_id = 2;
  // Timeout (ns) for this request
  uint64 deadline = 3;
  // Heights being requested
  repeated uint64 heights = 4;
}

// AcceptedStateSummary is sent in response to GetAcceptedStateSummary
message AcceptedStateSummary {
  // Chain being responded from
  bytes chain_id = 1;
  // Request id of the original GetAcceptedStateSummary request
  uint32 request_id = 2;
  // State summary ids
  repeated bytes summary_ids = 3;
}

// The consensus engine that should be used when handling a consensus request.
enum EngineType {
  ENGINE_TYPE_UNSPECIFIED = 0;
  // Only the X-Chain uses avalanche consensus
  ENGINE_TYPE_AVALANCHE = 1;
  ENGINE_TYPE_SNOWMAN = 2;
}

// GetAcceptedFrontier requests the accepted frontier from a peer.
//
// Peers should respond to GetAcceptedFrontier with AcceptedFrontier.
message GetAcceptedFrontier {
  reserved 4;
  // Chain being requested from
  bytes chain_id = 1;
  // Unique identifier for this request
  uint32 request_id = 2;
  // Timeout (ns) for this request
  uint64 deadline = 3;
}

// AcceptedFrontier contains the remote peer's last accepted frontier.
//
// AcceptedFrontier is sent in response to GetAcceptedFrontier.
message AcceptedFrontier {
  // Chain being responded from
  bytes chain_id = 1;
  // Request id of the original GetAcceptedFrontier request
  uint32 request_id = 2;
  // The id of the last accepted frontier
  bytes container_id = 3;
}

// GetAccepted sends a request with the sender's accepted frontier to a remote
// peer.
//
// Peers should respond to GetAccepted with an Accepted message.
message GetAccepted {
  reserved 5;
  // Chain being requested from
  bytes chain_id = 1;
  // Unique identifier for this message
  uint32 request_id = 2;
  // Timeout (ns) for this request
  uint64 deadline = 3;
  // The sender's accepted frontier
  repeated bytes container_ids = 4;
}

// Accepted is sent in response to GetAccepted. The sending peer responds with
// a subset of container ids from the GetAccepted request that the sending peer
// has accepted.
message Accepted {
  // Chain being responded from
  bytes chain_id = 1;
  // Request id of the original GetAccepted request
  uint32 request_id = 2;
  // Subset of container ids from the GetAccepted request that the sender has
  // accepted
  repeated bytes container_ids = 3;
}

// GetAncestors requests the ancestors for a given container.
//
// The remote peer should respond with an Ancestors message.
message GetAncestors {
  // Chain being requested from
  bytes chain_id = 1;
  // Unique identifier for this request
  uint32 request_id = 2;
  // Timeout (ns) for this request
  uint64 deadline = 3;
  // Container for which ancestors are being requested
  bytes container_id = 4;
  // Consensus type to handle this message
  EngineType engine_type = 5;
}

// Ancestors is sent in response to GetAncestors.
//
// Ancestors contains a contiguous ancestry of containers for the requested
// container in order of increasing block height.
message Ancestors {
  // Chain being responded from
  bytes chain_id = 1;
  // Request id of the original GetAncestors request
  uint32 request_id = 2;
  // Ancestry for the requested container
  repeated bytes containers = 3;
}

// Get requests a container from a remote peer.
//
// Remote peers should respond with a Put message if they have the container.
message Get {
  reserved 5;
  // Chain being requested from
  bytes chain_id = 1;
  // Unique identifier for this request
  uint32 request_id = 2;
  // Timeout (ns) for this request
  uint64 deadline = 3;
  // Container being requested
  bytes container_id = 4;
}

// Put is sent in response to Get with the requested block.
message Put {
  // Chain being responded from
  bytes chain_id = 1;
  // Request id of the original Get request
  uint32 request_id = 2;
  // Requested container
  bytes container = 3;
}

// PushQuery requests the preferences of a remote peer given a container.
//
// Remote peers should respond to a PushQuery with a Chits message
message PushQuery {
  reserved 5;
  // Chain being requested from
  bytes chain_id = 1;
  // Unique identifier for this request
  uint32 request_id = 2;
  // Timeout (ns) for this request
  uint64 deadline = 3;
  // Container being gossiped
  bytes container = 4;
  // Requesting peer's last accepted height
  uint64 requested_height = 6;
}

// PullQuery requests the preferences of a remote peer given a container id.
//
// Remote peers should respond to a PullQuery with a Chits message
message PullQuery {
  reserved 5;
  // Chain being requested from
  bytes chain_id = 1;
  // Unique identifier for this request
  uint32 request_id = 2;
  // Timeout (ns) for this request
  uint64 deadline = 3;
  // Container id being gossiped
  bytes container_id = 4;
  // Requesting peer's last accepted height
  uint64 requested_height = 6;
}

// Chits contains the preferences of a peer in response to a PushQuery or
// PullQuery message.
message Chits {
  // Chain being responded from
  bytes chain_id = 1;
  // Request id of the original PushQuery/PullQuery request
  uint32 request_id = 2;
  // Currently preferred block
  bytes preferred_id = 3;
  // Last accepted block
  bytes accepted_id = 4;
  // Currently preferred block at the requested height
  bytes preferred_id_at_height = 5;
}

// AppRequest is a VM-defined request.
//
// Remote peers must respond to AppRequest with a corresponding AppResponse or
// AppError
message AppRequest {
  // Chain being requested from
  bytes chain_id = 1;
  // Unique identifier for this request
  uint32 request_id = 2;
  // Timeout (ns) for this request
  uint64 deadline = 3;
  // Request body
  bytes app_bytes = 4;
}

// AppResponse is a VM-defined response sent in response to AppRequest
message AppResponse {
  // Chain being responded from
  bytes chain_id = 1;
  // Request id of the original AppRequest
  uint32 request_id = 2;
  // Response body
  bytes app_bytes = 3;
}

// AppError is a VM-defined error sent in response to AppRequest
message AppError {
  // Chain the message is for
  bytes chain_id = 1;
  // Request id of the original AppRequest
  uint32 request_id = 2;
  // VM defined error code. VMs may define error codes > 0.
  sint32 error_code = 3;
  // VM defined error message
  string error_message = 4;
}

// AppGossip is a VM-defined message
message AppGossip {
  // Chain the message is for
  bytes chain_id = 1;
  // Message body
  bytes app_bytes = 2;
}