prysm-pulse/proto/eth/v1alpha1/beacon_chain.proto

syntax = "proto3";

package ethereum.eth.v1alpha1;

import "github.com/gogo/protobuf/gogoproto/gogo.proto";
import "google/api/annotations.proto";
import "google/protobuf/empty.proto";

import "proto/eth/v1alpha1/attestation.proto";
import "proto/eth/v1alpha1/beacon_block.proto";
import "proto/eth/v1alpha1/validator.proto";

option go_package = "github.com/prysmaticlabs/prysm/proto/eth/v1alpha1;eth";

// Beacon chain API
//
// The beacon chain API can be used to access data relevant to the Ethereum 2.0
// phase 0 beacon chain.
service BeaconChain {
    // TODO(preston): Batch requests?

    // Retrieve attestations by block root, slot, or epoch. 
    // Attestations are sorted by slot by default.
    // 
    // The server may return an empty list when no attestations match the given 
    // filter criteria. This RPC should not return NOT_FOUND. Only one filter 
    // criteria should be used.
    rpc ListAttestations(ListAttestationsRequest) returns (ListAttestationsResponse) {
        option (google.api.http) = {
            get: "/eth/v1alpha1/beacon/attestations"
        };
    }

    // Retrieve attestations from pool.
    //
    // The server returns a list of attestations that have been seen but not
    // yet processed. Pool attestations eventually expire as the slot
    // advances, so an attestation missing from this request does not imply
    // that it was included in a block. The attestation may have expired.
    // Refer to the ethereum 2.0 specification for more details on how
    // attestations are processed and when they are no longer valid.
    // https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#attestations
    rpc AttestationPool(google.protobuf.Empty) returns (AttestationPoolResponse) {
        option (google.api.http) = {
            get: "/eth/v1alpha1/beacon/attestations/pool"
        };
    }

    // Retrieve blocks by root, slot, or epoch.
    //
    // The server may return multiple blocks in the case that a slot or epoch is
    // provided as the filter criteria. The server may return an empty list when
    // no blocks in their database match the filter criteria. This RPC should
    // not return NOT_FOUND. Only one filter criteria should be used.
    rpc ListBlocks(ListBlocksRequest) returns (ListBlocksResponse) {
        option (google.api.http) = {
            get: "/eth/v1alpha1/beacon/blocks"
        };
    }

    // Retrieve information about the head of the beacon chain from the view of
    // the beacon chain node.
    //
    // This includes the head block slot and root as well as information about
    // the most recent finalized and justified slots.
    rpc GetChainHead(google.protobuf.Empty) returns (ChainHead) {
        option (google.api.http) = {
            get: "/eth/v1alpha1/beacon/chainhead"
        };
    }

    // Retrieve the beacon chain committees for a given epoch.
    //
    // If no filter criteria is specified, the response returns
    // all beacon committees for the current epoch. The results are paginated by default.
    rpc ListBeaconCommittees(ListCommitteesRequest) returns (BeaconCommittees) {
        option (google.api.http) = {
            get: "/eth/v1alpha1/beacon/committees"
        };
    }

    // Retrieve validator balances for a given set of public keys at a specific
    // epoch in time.
    rpc ListValidatorBalances(ListValidatorBalancesRequest) returns (ValidatorBalances) {
        option (google.api.http) = {
            get: "/eth/v1alpha1/validators/balances"
        };
    }

    // Retrieve the current validator registry.
    //
    // The request may include an optional historical epoch to retrieve a
    // specific validator set in time. It can also specify fetching
    // only active validators.
    rpc ListValidators(ListValidatorsRequest) returns (Validators) {
        option (google.api.http) = {
            get: "/eth/v1alpha1/validators"
        };
    }

    // Retrieve the active set changes for a given epoch.
    //
    // This data includes any activations, voluntary exits, and involuntary
    // ejections.
    rpc GetValidatorActiveSetChanges(GetValidatorActiveSetChangesRequest) returns (ActiveSetChanges) {
        option (google.api.http) = {
            get: "/eth/v1alpha1/validators/activesetchanges"
        };
    }

    // Retrieve the current validator queue information.
    rpc GetValidatorQueue(google.protobuf.Empty) returns (ValidatorQueue) {
        option (google.api.http) = {
            get: "/eth/v1alpha1/validators/queue"
        };
    }

    // Retrieve the validator assignments for a given epoch.
    //
    // This request may specify optional validator indices or public keys to
    // filter validator assignments.
    rpc ListValidatorAssignments(ListValidatorAssignmentsRequest) returns (ValidatorAssignments) {
        option (google.api.http) = {
            get: "/eth/v1alpha1/validators/assignments"
        };
    }

    // Retrieve the validator participation information for a given epoch.
    //
    // This method returns information about the global participation of
    // validator attestations.
    rpc GetValidatorParticipation(GetValidatorParticipationRequest) returns (ValidatorParticipationResponse) {
        option (google.api.http) = {
            get: "/eth/v1alpha1/validators/participation"
        };
    }
}

// Request for attestations.
message ListAttestationsRequest {
    // TODO(preston): Test oneof with gRPC gateway.

    oneof query_filter {
        // Filter attestations by a specific block root.
        bytes head_block_root = 1;

        // Filter attestations by source epoch.
        uint64 source_epoch = 2;

        // Filter attestations by target root.
        bytes source_root = 3;

        // Filter attestations by target epoch.
        uint64 target_epoch = 4;

        // Filter attestations by target root.
        bytes target_root = 5;
    }

    // The maximum number of Attestations to return in the response.
    // This field is optional.
    int32 page_size = 6;

    // A pagination token returned from a previous call to `ListAttestations`
    // that indicates where this listing should continue from.
    // This field is optional.
    string page_token = 7;
}

message ListAttestationsResponse {
    repeated Attestation attestations = 1;

    // A pagination token returned from a previous call to `ListAttestations`
    // that indicates from where listing should continue.
    // This field is optional.
    string next_page_token = 2;

    // Total count of Attestations matching the request filter.
    int32 total_size = 3;
}

message ListBlocksRequest {
    oneof query_filter {
        // Block root filter to return a single block.
        bytes root = 1;

        // Slot to lookup a block. If the slot is not yet finalized, this
        // criteria may yield multiple valid blocks if the node has seen blocks
        // from another fork.
        uint64 slot = 2;

        // Epoch to lookup blocks. This method may return multiple blocks for a
        // slot if the epoch has not been finalized and the node has seen blocks
        // from another fork.
        uint64 epoch = 3;
    }

    // Optional criteria to include any non-canonical blocks matching the
    // request.
    bool include_noncanonical = 4;

    // The maximum number of Blocks to return in the response.
    // This field is optional.
    int32 page_size = 5;

    // A pagination token returned from a previous call to `ListBlocks`
    // that indicates where this listing should continue from.
    // This field is optional.
    string page_token = 6;
}

message ListBlocksResponse {
    repeated BeaconBlockContainer blockContainers = 1;

    // A pagination token returned from a previous call to `ListBlocks`
    // that indicates from where listing should continue.
    // This field is optional.
    string next_page_token = 2;

    // Total count of Blocks matching the request filter.
    int32 total_size = 3;
}

// A container that contains both the beacon block
// and its corresponding root.
message BeaconBlockContainer {
    BeaconBlock block = 1;
    // 32 byte merkle tree root of contained beacon block.
    bytes block_root = 2;
}

message ChainHead {
    // 32 byte merkle tree root of the canonical head block in the beacon node.
    bytes head_block_root = 1 [(gogoproto.moretags) = "ssz-size:\"32\""];

    // Slot of the head block.
    uint64 head_block_slot = 2;

    // Epoch of the head block.
    uint64 head_block_epoch = 3;

    // Most recent slot that contains the finalized block.
    uint64 finalized_block_slot = 4;

    // Epoch of the finalized block.
    uint64 finalized_epoch = 5;

    // Most recent 32 byte finalized block root.
    bytes finalized_block_root = 6 [(gogoproto.moretags) = "ssz-size:\"32\""];

    // Most recent slot that contains the justified block.
    uint64 justified_block_slot = 7;

    // Epoch of the justified block.
    uint64 justified_epoch = 8;

    // Most recent 32 byte justified block root.
    bytes justified_block_root = 9 [(gogoproto.moretags) = "ssz-size:\"32\""];

    // Most recent slot that contains the previous justified block.
    uint64 previous_justified_slot = 10;

    // Epoch of the previous justified block.
    uint64 previous_justified_epoch = 11;

    // Previous 32 byte justified block root.
    bytes previous_justified_block_root = 12 [(gogoproto.moretags) = "ssz-size:\"32\""];
}

message ListCommitteesRequest {
    oneof query_filter {
        // Optional criteria to retrieve data at a specific epoch.
        uint64 epoch = 1;

        // Optional criteria to retrieve genesis data.
        bool genesis = 2;
    }

    // The maximum number of results to return in the response.
    // This field is optional.
    int32 page_size = 3;

    // A pagination token returned from a previous call
    // that indicates where this listing should continue from.
    // This field is optional.
    string page_token = 4;
}

message BeaconCommittees {
    message CommitteeItem {
        // A committee of validator indices that need to attest to beacon blocks.
        repeated uint64 committee = 1;

        // The slot at which the committee is assigned to.
        uint64 slot = 2;
    }
    // The epoch for which the committees in the response belong to.
    uint64 epoch = 1;

    // A list of committees of validators for given  epoch.
    repeated CommitteeItem committees = 2;

    // The number of active validators at the given epoch.
    uint64 active_validator_count = 3;

    // A pagination token returned from a previous call
    // that indicates from where the listing should continue.
    string next_page_token = 4;

    // Total count of committees matching the request filter.
    int32 total_size = 5;
}

message ListValidatorBalancesRequest {
    oneof query_filter {
        // Optional criteria to retrieve balances at a specific epoch.
        uint64 epoch = 1;

        // Optional criteria to retrieve the genesis list of balances.
        bool genesis = 2;
    }
    // Validator 48 byte BLS public keys to filter validators for the given
    // epoch.
    repeated bytes public_keys = 3 [(gogoproto.moretags) = "ssz-size:\"?,48\""];

    // Validator indices to filter for the given epoch.
    repeated uint64 indices = 4;

    // The maximum number of items to return in the response.
    // This field is optional.
    int32 page_size = 5;

    // A pagination token returned from a previous call
    // that indicates where this listing should continue from.
    // This field is optional.
    string page_token = 6;
}

message ValidatorBalances {
    // Epoch which the state was considered to determine the validator balances.
    uint64 epoch = 1;

    message Balance {
        // Validator's 48 byte BLS public key. 
        bytes public_key = 1 [(gogoproto.moretags) = "ssz-size:\"48\""];

        // Validator's index in the validator set.
        uint64 index = 2;

        // Validator's balance in gwei.
        uint64 balance = 3;
    }

    repeated Balance balances = 2;

    // A pagination token returned from a previous call
    // that indicates from where listing should continue.
    string next_page_token = 3;

    // Total count of results matching the request filter.
    int32 total_size = 4;
}

message ListValidatorsRequest {
    oneof query_filter {
        // Optional criteria to retrieve validators at a specific epoch. 
        // Omitting this field or setting it to zero will retrieve a response
        // with the current active validator set.
        uint64 epoch = 1;

        // Optional criteria to retrieve the genesis set of validators.
        bool genesis = 2;
    }

    // Specify whether or not you want to retrieve only active validators.
    bool active = 3;

    // The maximum number of results to return in the response.
    // This field is optional.
    int32 page_size = 4;

    // A pagination token returned from a previous call
    // that indicates where this listing should continue from.
    // This field is optional.
    string page_token = 5;
}

message Validators {
    // Epoch which the state was considered to determine the active validator 
    // set. This field is not optional. Zero value epoch indicates the validator
    // set is from the Ethereum 2.0 genesis set.
    uint64 epoch = 1;

    repeated Validator validators = 2;

    // A pagination token returned from a previous call
    // that indicates from where listing should continue.
    // This field is optional.
    string next_page_token = 3;

    // Total count of Validators matching the request filter.
    int32 total_size = 4;
}


message GetValidatorActiveSetChangesRequest {
    oneof query_filter {
        // Optional criteria to retrieve balances at a specific epoch.
        uint64 epoch = 1;

        // Optional criteria to retrieve the genesis list of balances.
        bool genesis = 2;
    }
}

message ActiveSetChanges {
    // Epoch which the state was considered to determine the active validator 
    // set. 
    uint64 epoch = 1;

    // 48 byte validator public keys that have been activated in this epoch.
    repeated bytes activated_public_keys = 2 [(gogoproto.moretags) = "ssz-size:\"?,48\""];

    // 48 byte validator public keys that have been voluntarily exited in this epoch.
    repeated bytes exited_public_keys = 3 [(gogoproto.moretags) = "ssz-size:\"?,48\""];

    // 48 byte validator public keys that have been slashed in this epoch.
    repeated bytes slashed_public_keys = 4 [(gogoproto.moretags) = "ssz-size:\"?,48\""];

    // 48 byte validator public keys that have been involuntarily ejected in this epoch.
    repeated bytes ejected_public_keys = 5 [(gogoproto.moretags) = "ssz-size:\"?,48\""];
}

message ValidatorQueue {
    // The amount of ether in gwei allowed to enter or exit the active 
    // validator set.
    uint64 churn_limit = 1;

    // Ordered list of 48 byte public keys awaiting activation. 0th index is the
    // next key to be processed.
    repeated bytes activation_public_keys = 2 [(gogoproto.moretags) = "ssz-size:\"?,48\""];

    // Ordered list of public keys awaiting exit. 0th index is the next key to
    // be processed.
    repeated bytes exit_public_keys = 3 [(gogoproto.moretags) = "ssz-size:\"?,48\""];
}

message ListValidatorAssignmentsRequest {
    oneof query_filter {
        // Epoch to validator assignments for.
        uint64 epoch = 1;

        // Whether or not to query for the genesis information.
        bool genesis = 2;
    }
    // 48 byte validator public keys to filter assignments for the given epoch.
    repeated bytes public_keys = 3 [(gogoproto.moretags) = "ssz-size:\"?,48\""];
        
    // Validator indicies to filter assignments for the given epoch.
    repeated uint64 indices = 4;

    // The maximum number of results to return in the response.
    // This field is optional.
    int32 page_size = 5;

    // A pagination token returned from a previous call
    // that indicates where this listing should continue from.
    // This field is optional.
    string page_token = 6;
}

message ValidatorAssignments {
    message CommitteeAssignment {
        // Beacon committees is responsible for crosslinking committee data back to the beacon chain,
        // they also attest and produce beacon chain blocks. This is a list of validator indices that
        // are in the same committee as requested validator, everyone in the committee is assigned to the
        // same slot and same committee.
        repeated uint64 beacon_committees = 1;
        
        // The committee index of which the validator must perform the attestation
        // or block proposal.
        uint64 committee_index = 2;

        // Beacon chain slot in which the validator must perform its assigned 
        // duty as an attester.
        uint64 attester_slot = 3;

        // Beacon chain slot in which the validator must perform its assigned
        // duty as an attester.
        uint64 proposer_slot = 4;

        // 48 byte BLS public key 
        bytes public_key = 5 [(gogoproto.moretags) = "ssz-size:\"48\""];
    }

    // The epoch for which this set of validator assignments is valid.
    uint64 epoch = 1;

    repeated CommitteeAssignment assignments = 2;

    // A pagination token returned from a previous call
    // that indicates where this listing should continue from.
    // This field is optional.
    string next_page_token = 3;

    // Total count of results matching the request filter.
    int32 total_size = 4;
}

message GetValidatorParticipationRequest {
    oneof query_filter {
        // Epoch to request participation information.
        uint64 epoch = 1;

        // Whether or not to query for the genesis information.
        bool genesis = 2;
    }
}

message ValidatorParticipationResponse {
    // Epoch which this message is applicable.
    uint64 epoch = 1;

    // Whether or not epoch has been finalized.
    bool finalized = 2;

    // The actual participation metrics.
    ValidatorParticipation participation = 3;
}

message AttestationPoolResponse {
    repeated Attestation attestations = 1;
}