github.com/prysmaticlabs/prysm@v1.4.4/proto/eth/v1/node.proto

// Copyright 2020 Prysmatic Labs.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
syntax = "proto3";

package ethereum.eth.v1;

import "google/api/annotations.proto";
import "google/protobuf/descriptor.proto";
import "google/protobuf/empty.proto";

import "proto/eth/ext/options.proto";

option csharp_namespace = "Ethereum.Eth.v1";
option go_package = "github.com/prysmaticlabs/prysm/proto/eth/v1";
option java_multiple_files = true;
option java_outer_classname = "BeaconNodeProto";
option java_package = "org.ethereum.eth.v1";
option php_namespace = "Ethereum\\Eth\\v1";

// Beacon chain node API
//
// The beacon chain node API is a set of endpoints to query node information.
service BeaconNode {
  // GetIdentity retrieves data about the node's network presence.
  rpc GetIdentity(google.protobuf.Empty) returns (IdentityResponse) {
    option (google.api.http) = {get: "/eth/v1/node/identity"};
  }

  // ListPeers retrieves data about the node's network peers.
  rpc ListPeers(PeersRequest) returns (PeersResponse) {
    option (google.api.http) = {get: "/eth/v1/node/peers"};
  }

  // GetPeer retrieves data about the given peer.
  rpc GetPeer(PeerRequest) returns (PeerResponse) {
    option (google.api.http) = {get: "/eth/v1/node/peers/{peer_id}"};
  }

  // PeerCount retrieves number of known peers.
  rpc PeerCount(google.protobuf.Empty) returns (PeerCountResponse) {
    option (google.api.http) = {get: "/eth/v1/node/peer_count"};
  }

  // GetSyncStatus requests the beacon node to describe if it's currently syncing or not, and
  // if it is, what block it is up to.
  rpc GetSyncStatus(google.protobuf.Empty) returns (SyncingResponse) {
    option (google.api.http) = {get: "/eth/v1/node/syncing"};
  }

  // GetVersion requests that the beacon node identify information about its implementation in a
  // format similar to a HTTP User-Agent field.
  rpc GetVersion(google.protobuf.Empty) returns (VersionResponse) {
    option (google.api.http) = {get: "/eth/v1/node/version"};
  }

  // GetHealth returns node health status in http status codes. Useful for load balancers.
  // Response Usage:
  //    "200":
  //      description: Node is ready
  //    "206":
  //      description: Node is syncing but can serve incomplete data
  //    "503":
  //      description: Node not initialized or having issues
  rpc GetHealth(google.protobuf.Empty) returns (google.protobuf.Empty) {
    option (google.api.http) = {get: "/eth/v1/node/health"};
  }
}

message IdentityResponse {
  Identity data = 1;
}

message Identity {
  // The peer id of the node.
  string peer_id = 1;
  // The latest ENR of the node.
  string enr = 2;
  // All the p2p multiaddresses of the peer, specified as a full multiaddr.
  repeated string p2p_addresses = 3;
  // All the discv5 multiaddresses of the peer, specified as a full multiaddr.
  repeated string discovery_addresses = 4;
  // Additional metadata that the node would like to provide. Includes extra networking information.
  Metadata metadata = 5;
}

message Metadata {
  // Sequence number starts at 0 used to version the node's metadata. If any other field in the local MetaData changes,
  // the node MUST increment seq_number by 1.
  uint64 seq_number = 1;
  // Attnets is a bitvector representing the node's persistent attestation subnet subscriptions.
  bytes attnets = 2 [(ethereum.eth.ext.ssz_size) = "8", (ethereum.eth.ext.cast_type) = "github.com/prysmaticlabs/go-bitfield.Bitvector64"];
}

message PeerRequest {
  // Peer id of the peer requested.
  string peer_id = 1;
}

message PeersRequest {
  // Requested peer states (available values: disconnected, connecting, connected, disconnecting).
  repeated ConnectionState state = 1;
  // Requested peer directions (available values: inbound, outbound).
  repeated PeerDirection direction = 2;
}

message PeerResponse {
  Peer data = 1;
  Meta meta = 2;

  message Meta {
    uint64 count = 1;
  }
}

message PeersResponse {
  repeated Peer data = 1;
}

message PeerCountResponse {
  PeerCount data = 1;

  message PeerCount {
    // The number of disconnected peers.
    uint64 disconnected = 1;
    // The number of connecting peers.
    uint64 connecting = 2;
    // The number of connected peers.
    uint64 connected = 3;
    // The number of disconnecting peers.
    uint64 disconnecting = 4;
  }
}

// Peer provides details of a peer on the network.
message Peer {
  // The peer id of the peer.
  string peer_id = 1;
  // The latest ENR of the peer that's in the record.
  string enr = 2;
  // The address of the peer, as a full multiaddr, for example:
  // /ip4/37.221.192.134/tcp/13000/p2p/16Uiu2HAm8maLMjag1TAUM52zPfmLbVMGFdwUAWgoHu1HDQLR6e17
  string last_seen_p2p_address = 3;
  // The connection state of the peer at the moment of the request. (e.g. Connecting)
  ConnectionState state = 4;
  // The direction of the connection (inbound/outbound).
  PeerDirection direction = 5;
}

// PeerDirection states the direction of the connection to a peer.
enum PeerDirection {
  INBOUND = 0;
  OUTBOUND = 1;
}

// ConnectionState states the current status of the peer.
enum ConnectionState {
  DISCONNECTED = 0;
  CONNECTING = 1;
  CONNECTED = 2;
  DISCONNECTING = 3;
}

message VersionResponse {
  Version data = 1;
}

// Information about the node version.
message Version {
  // A string that uniquely identifies the node and its version.
  string version = 1;
}

message SyncingResponse {
  SyncInfo data = 1;
}

message SyncInfo {
  // A uint64 states the latest head slot of the current node.
  uint64 head_slot = 1 [(ethereum.eth.ext.cast_type) = "github.com/prysmaticlabs/eth2-types.Slot"];

  // A uint64 indicating how many slots are left for the beacon node sync to complete.
  uint64 sync_distance = 2 [(ethereum.eth.ext.cast_type) = "github.com/prysmaticlabs/eth2-types.Slot"];

  // A bool indicating whether the node is currently syncing or not.
  bool is_syncing = 3;
}