prysm-pulse/proto/beacon/rpc/v1/debug.proto

syntax = "proto3";

package ethereum.beacon.rpc.v1;

import "eth/v1alpha1/node.proto";
import "proto/beacon/p2p/v1/messages.proto";
import "google/api/annotations.proto";
import "google/protobuf/empty.proto";

// Debug service API
//
// The debug service in Prysm provides API access to various utilities
// for debugging the beacon node's functionality at runtime, such as being able
// to retrieve the beacon state by block root or state root from the node directly.
service Debug {
    // Returns a beacon state by filter criteria from the beacon node.
    rpc GetBeaconState(BeaconStateRequest) returns (SSZResponse) {
        option (google.api.http) = {
            get: "/eth/v1alpha1/debug/state"
        };
    }
    // Returns a beacon state by filter criteria from the beacon node.
    rpc GetBlock(BlockRequest) returns (SSZResponse) {
        option (google.api.http) = {
            get: "/eth/v1alpha1/debug/block"
        };
    }
    // SetLoggingLevel sets the log-level of the beacon node programmatically.
    rpc SetLoggingLevel(LoggingLevelRequest) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            post: "/eth/v1alpha1/debug/logging"
        };
    }
    // Returns a proto array fork choice object from the beacon node.
    rpc GetProtoArrayForkChoice(google.protobuf.Empty) returns (ProtoArrayForkChoiceResponse) {
        option (google.api.http) = {
            get: "/eth/v1alpha1/debug/forkchoice"
        };
    }
    // Returns all the related data for every peer tracked by the host node.
    rpc ListPeers(google.protobuf.Empty) returns (DebugPeerResponses){
        option (google.api.http) = {
            get: "/eth/v1alpha1/debug/peers"
        };
    }
    // Returns requested peer with specified peer id if it exists.
    rpc GetPeer(ethereum.eth.v1alpha1.PeerRequest) returns (DebugPeerResponse) {
        option (google.api.http) = {
            get: "/eth/v1alpha1/debug/peer"
        };
    }
}

message BeaconStateRequest {
    oneof query_filter {
        // The slot corresponding to a desired beacon state.
        uint64 slot = 1;

        // The block root corresponding to a desired beacon state.
        bytes block_root = 2;
    }
}

message BlockRequest {
    bytes block_root = 1;
}

message SSZResponse {
    // Returns an ssz-encoded byte slice as a response.
    bytes encoded = 1;
}

message LoggingLevelRequest {
    // The logging levels available in Prysm as an enum.
    enum Level {
        INFO = 0;
        DEBUG = 1;
        TRACE = 2;
    }
    Level level = 1;
}

message ProtoArrayForkChoiceResponse {
    // The prune threshold of how many nodes allowed in proto array store.
    uint64 prune_threshold = 1;
    // Latest justified epoch in proto array store.
    uint64 justified_epoch = 2;
    // Latest finalized epoch in proto array store.
    uint64 finalized_epoch = 3;
    // The list of the proto array nodes in store.
    repeated ProtoArrayNode proto_array_nodes = 4;
    // Root to indices mapping of the proto array nodes in store.
    map<string, uint64> indices = 5;
}

message ProtoArrayNode {
    // Slot of the proto array node.
    uint64 slot = 1;
    // Root of the proto array node.
    bytes root = 2;
    // Parent of the proto array node.
    uint64 parent = 3;
    // Justified epoch of the current proto array node.
    uint64 justified_epoch = 4;
    // finalized epoch of the current proto array node.
    uint64 finalized_epoch = 5;
    // Current weight of the current proto array node.
    uint64 weight = 6;
    // Best child of the current proto array node.
    uint64 best_child = 7;
    // Best descendant of the proto array node.
    uint64 best_descendant = 8;
}

message DebugPeerResponses {
 repeated DebugPeerResponse responses = 1;
}

message DebugPeerResponse {
    // Peer related metadata that is useful for debugging.
    message PeerInfo {
        // Metadata of the peer, containing their bitfield
        // and sequence number.
        ethereum.beacon.p2p.v1.MetaData metadata = 1;
        // List of protocols the peer supports.
        repeated string protocols = 2;
        // Number of times peer has been penalised.
        uint64 fault_count = 3;
        // Protocol Version peer is running.
        string protocol_version = 4;
        // Agent Version peer is running.
        string agent_version = 5;
        // Latency of responses from peer(in ms).
        uint64 peer_latency = 6;
    }
    // Listening addresses know of the peer.
    repeated string listening_addresses = 1;
    // Direction of current connection.
    ethereum.eth.v1alpha1.PeerDirection direction = 2;
    // Current connection between host and peer.
    ethereum.eth.v1alpha1.ConnectionState connection_state = 3;
    // Peer ID of peer.
    string peer_id = 4;
    // ENR of peer at the current moment.
    string enr = 5;
    // Peer Info of the peer containing all relevant metadata.
    PeerInfo peer_info = 6;
    // Peer Status of the peer.
    ethereum.beacon.p2p.v1.Status peer_status = 7;
    // Last know update time for peer status.
    uint64 last_updated = 8;
}