Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
549 lines (438 sloc) 18.1 KB
// Copyright 2019 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.v1alpha1;
import "google/api/annotations.proto";
import "google/protobuf/empty.proto";
import "eth/v1alpha1/attestation.proto";
import "eth/v1alpha1/beacon_block.proto";
import "eth/v1alpha1/validator.proto";
option csharp_namespace = "Ethereum.Eth.v1alpha1";
option go_package = "github.com/prysmaticlabs/ethereumapis/eth/v1alpha1;eth";
option java_multiple_files = true;
option java_outer_classname = "BeaconChainProto";
option java_package = "org.ethereum.eth.v1alpha1";
option php_namespace = "Ethereum\\Eth\\v1alpha1";
// 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.
//
// 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.
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 (ValidatorParticipation) {
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;
}
// Information about the head of the beacon chain.
message ChainHead {
// 32 byte merkle tree root of the canonical head block in the beacon node.
bytes head_block_root = 1;
// 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;
// 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;
// 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;
}
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 Validators to return in the response.
// This field is optional.
int32 page_size = 3;
// A pagination token returned from a previous call to `GetValidators`
// 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;
// Validator indices to filter validators for the given epoch.
repeated uint64 indices = 4;
// The maximum number of Validators to return in the response.
// This field is optional.
int32 page_size = 5;
// A pagination token returned from a previous call to `GetValidators`
// 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;
// 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 to `GetListValidatorBalances`
// that indicates from where listing should continue.
string next_page_token = 3;
// Total count of items 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 Validators to return in the response.
// This field is optional.
int32 page_size = 4;
// A pagination token returned from a previous call to `GetValidators`
// 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 to `GetValidators`
// 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;
// 48 byte validator public keys that have been voluntarily exited in this
// epoch.
repeated bytes exited_public_keys = 3;
// 48 byte validator public keys that have been slashed in this epoch.
repeated bytes slashed_public_keys = 4;
// 48 byte validator public keys that have been involuntarily ejected in this epoch.
repeated bytes ejected_public_keys = 5;
}
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;
// Ordered list of public keys awaiting exit. 0th index is the next key to
// be processed.
repeated bytes exit_public_keys = 3;
}
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;
// Validator indicies to filter assignments for the given epoch.
repeated uint64 indices = 4;
// The maximum number of ValidatorAssignments to return in the response.
// This field is optional.
int32 page_size = 5;
// A pagination token returned from a previous call to `ListValidatorAssignments`
// 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;
// Committee index represents the committee of validator that's in.
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;
}
// 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 to `ListValidatorAssignmentsRequest`
// that indicates where this listing should continue from.
// This field is optional.
string next_page_token = 3;
// Total count of CommitteeAssignments 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 validator participation metrics.
ValidatorParticipation participation = 3;
}
message AttestationPoolResponse {
repeated Attestation attestations = 1;
}
You can’t perform that action at this time.