prysm-pulse/proto/eth/v1/beacon_chain_service.proto
Radosław Kapka 12403d249f
[Feature] - API Middleware (#8926)
* HTTP proxy server for Eth2 APIs (#8904)

* Implement API HTTP proxy server

* cleanup + more comments

* gateway will no longer be dependent on beaconv1

* handle error during ErrorJson type assertion

* simplify handling of endpoint data

* fix mux v1 route

* use URL encoding for all requests

* comment fieldProcessor

* fix failing test

* change proxy port to not interfere with e2e

* gzl

* simplify conditional expression

* Move appending custom error header to grpcutils package

* add api-middleware-port flag

* fix documentation for processField

* modify e2e port

* change field processing error message

* better error message for field processing

* simplify base64ToHexProcessor

* fix json structs

* Run several new endpoints through API middleware (#8922)

* Implement API HTTP proxy server

* cleanup + more comments

* gateway will no longer be dependent on beaconv1

* handle error during ErrorJson type assertion

* simplify handling of endpoint data

* fix mux v1 route

* use URL encoding for all requests

* comment fieldProcessor

* fix failing test

* change proxy port to not interfere with e2e

* gzl

* simplify conditional expression

* Move appending custom error header to grpcutils package

* add api-middleware-port flag

* fix documentation for processField

* modify e2e port

* change field processing error message

* better error message for field processing

* simplify base64ToHexProcessor

* fix json structs

* /eth/v1/beacon/states/{state_id}/validators

* /eth/v1/beacon/states/{state_id}/validators/{validator_id}

* /eth/v1/beacon/states/{state_id}/validator_balances

* /eth/v1/beacon/states/{state_id}/committees

* allow skipping base64-encoding for query params

* /eth/v1/beacon/pool/attestations

* replace break with continue

* Remove unused functions (#8924)

Co-authored-by: terence tsao <terence@prysmaticlabs.com>

* Process SSZ-serialized beacon state through API middleware (#8925)

* update field names

* Process SSZ-serialized beacon state through API middleware

* revert changes to go.mod and go.sum

* Revert "Merge branch '__develop' into feature/api-middleware"

This reverts commit 7c739a8fd71e2c1e3a14be85abd29a59b57ae9b5, reversing
changes made to 2d0f8e012ecb006888ed8e826b45625a3edc2eeb.

* update ethereumapis

* update validator field name

* update deps.bzl

* update json tags (#8942)

* Run `/node/syncing` through API Middleware (#8944)

* add IsSyncing field to grpc response

* run /node/syncing through the middleware

Co-authored-by: Raul Jordan <raul@prysmaticlabs.com>

* Return HTTP status codes other than 200 and 500 from node and debug endpoints (#8937)

* error codes for node endpoints

* error codes for debug endpoints

* better comment about headers

* gzl

* review comments

* comment on return value

* update fakeChecker used for fuzz tests

* fix failing tests

* Allow to pass URL params literally, without encoding to base64 (#8938)

* Allow to pass URL params literally, without encoding to base64

* fix compile error

Co-authored-by: Raul Jordan <raul@prysmaticlabs.com>

* Process SSZ-serialized beacon state through API middleware (#8925)

* update field names

* Process SSZ-serialized beacon state through API middleware

* revert changes to go.mod and go.sum

* Revert "Merge branch '__develop' into feature/api-middleware"

This reverts commit 7c739a8fd71e2c1e3a14be85abd29a59b57ae9b5, reversing
changes made to 2d0f8e012ecb006888ed8e826b45625a3edc2eeb.

* update ethereumapis

* update validator field name

* update deps.bzl

* update json tags (#8942)

* Run `/node/syncing` through API Middleware (#8944)

* add IsSyncing field to grpc response

* run /node/syncing through the middleware

Co-authored-by: Raul Jordan <raul@prysmaticlabs.com>

* Return HTTP status codes other than 200 and 500 from node and debug endpoints (#8937)

* error codes for node endpoints

* error codes for debug endpoints

* better comment about headers

* gzl

* review comments

* comment on return value

* update fakeChecker used for fuzz tests

* fix failing tests

* Allow to pass URL params literally, without encoding to base64 (#8938)

* Allow to pass URL params literally, without encoding to base64

* fix compile error

Co-authored-by: Raul Jordan <raul@prysmaticlabs.com>

* unused import

* Return correct status codes from beacon endpoints (#8960)

* Various API Middleware fixes (#8963)

* Return correct status codes from `/states` endpoints

* better error messages in debug and node

* better error messages in state

* returning correct error codes from validator endpoints

* correct error codes for getting a block header

* gzl

* fix err variable name

* fix nil block comparison

* test fixes

* make status enum test better

* fix ineffectual assignment

* make PR unstuck

* return proper status codes

* return uppercase keys from /config/spec

* return lowercase validator status

* convert requested enum values to uppercase

* validator fixes

* Implement `/beacon/headers` endpoint (#8966)

* Refactor API Middleware into more manageable code  (#8984)

* move endpoint registration out of shared package

* divide main function into smaller components

* return early on error

* implement hooks

* implement custom handlers and add documentation

* fix test compile error

* restrict package visibility

* remove redundant error checking

* rename file

* API Middleware unit tests (#8998)

* move endpoint registration out of shared package

* divide main function into smaller components

* return early on error

* implement hooks

* implement custom handlers and add documentation

* fix test compile error

* restrict package visibility

* remove redundant error checking

* rename file

* api_middleware_processing

* endpoints

* gzl

* remove gazelle:ignore

* merge

* Implement SSZ version of `/blocks/{block_id}` (#8970)

* Implement SSZ version of `/blocks/{block_id}`

* add dependencies back

* fix indentation in deps.bzl

* parameterize ssz functions

* get block ssz

* update ethereumapis dependency

* gzl

* Do not reuse `Endpoint` structs between API calls (#9007)

* code refactor

* implement endpoint factory

* fix test

* fmt

* include pbs

* gaz

* test naming fixes

* remove unused code

* radek comments

* revert endpoint test

* bring back bytes test case

* move `signedBeaconBlock` to `migration` package

* change `fmt.Errorf` to `errors.Wrap`

* capitalize SSZ

* capitalize URL

* more review feedback

* rename `handleGetBlockSSZ` to `handleGetBeaconBlockSSZ`

* rename `IndexOutOfRangeError` to `ValidatorIndexOutOfRangeError`

* simplify parameter names

* test header

* more corrections

* properly allocate array capacity

Co-authored-by: terence tsao <terence@prysmaticlabs.com>
Co-authored-by: Raul Jordan <raul@prysmaticlabs.com>
Co-authored-by: Nishant Das <nishdas93@gmail.com>
2021-06-15 10:28:49 -05:00

493 lines
17 KiB
Protocol Buffer

// 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 "google/protobuf/timestamp.proto";
import "proto/eth/ext/options.proto";
import "proto/eth/v1/attestation.proto";
import "proto/eth/v1/beacon_block.proto";
import "proto/eth/v1/beacon_state.proto";
import "proto/eth/v1/validator.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 = "BeaconChainProto";
option java_package = "org.ethereum.eth.v1";
option php_namespace = "Ethereum\\Eth\\v1";
// Beacon Chain API
//
// The config API endpoints can be used to query the beacon chain state and information. Such as spec, current fork,
// blocks, and the validator spec.
//
// This service is defined in the upstream eth2.0-apis repository (eth2.0-APIs/apis/).
service BeaconChain {
// Beacon state API related endpoints.
// GetGenesis retrieves details of the chain's genesis which can be used to identify chain.
rpc GetGenesis(google.protobuf.Empty) returns (GenesisResponse) {
option (google.api.http) = { get: "/eth/v1/beacon/genesis" };
}
// GetStateRoot calculates HashTreeRoot for state with given 'stateId'. If stateId is root, same value will be returned.
rpc GetStateRoot(StateRequest) returns (StateRootResponse) {
option (google.api.http) = {
get: "/eth/v1/beacon/states/{state_id}/root"
};
}
// GetStateFork returns Fork object for state with given 'stateId'.
rpc GetStateFork(StateRequest) returns (StateForkResponse) {
option (google.api.http) = {
get: "/eth/v1/beacon/states/{state_id}/fork"
};
}
// GetFinalityCheckpoints returns finality checkpoints for state with given 'stateId'. In case finality is
// not yet achieved, checkpoint should return epoch 0 and ZERO_HASH as root.
rpc GetFinalityCheckpoints(StateRequest) returns (StateFinalityCheckpointResponse) {
option (google.api.http) = {
get: "/eth/v1/beacon/states/{state_id}/finality_checkpoints"
};
}
// ListValidators returns a filterable list of validators with their balance, status and index.
rpc ListValidators(StateValidatorsRequest) returns (StateValidatorsResponse) {
option (google.api.http) = {
get: "/eth/v1/beacon/states/{state_id}/validators"
};
}
// GetValidator returns a validator specified by state and id or public key along with status and balance.
rpc GetValidator(StateValidatorRequest) returns (StateValidatorResponse) {
option (google.api.http) = {
get: "/eth/v1/beacon/states/{state_id}/validators/{validator_id}"
};
}
// ListValidators returns a filterable list of validator balances.
rpc ListValidatorBalances(ValidatorBalancesRequest) returns (ValidatorBalancesResponse) {
option (google.api.http) = {
get: "/eth/v1/beacon/states/{state_id}/validator_balances"
};
}
// ListCommittees retrieves the committees for the given state at the given epoch.
rpc ListCommittees(StateCommitteesRequest) returns (StateCommitteesResponse) {
option (google.api.http) = {
get: "/eth/v1/beacon/states/{state_id}/committees"
};
}
// Beacon blocks API related endpoints.
// ListBlockHeaders retrieves block headers matching given query. By default it will fetch current head slot blocks.
rpc ListBlockHeaders(BlockHeadersRequest) returns (BlockHeadersResponse) {
option (google.api.http) = {
get: "/eth/v1/beacon/headers"
};
}
// GetBlockHeader retrieves block header for given block id.
rpc GetBlockHeader(BlockRequest) returns (BlockHeaderResponse) {
option (google.api.http) = {
get: "/eth/v1/beacon/headers/{block_id}"
};
}
// SubmitBlock instructs the beacon node to broadcast a newly signed beacon block to the beacon network, to be
// included in the beacon chain. The beacon node is not required to validate the signed BeaconBlock, and a successful
// response (20X) only indicates that the broadcast has been successful. The beacon node is expected to integrate the
// new block into its state, and therefore validate the block internally, however blocks which fail the validation are
// still broadcast but a different status code is returned (202).
rpc SubmitBlock(BeaconBlockContainer) returns (google.protobuf.Empty) {
option (google.api.http) = {
post: "/eth/v1/beacon/blocks"
body: "*"
};
}
// GetBlock retrieves block details for given block id.
rpc GetBlock(BlockRequest) returns (BlockResponse) {
option (google.api.http) = {
get: "/eth/v1/beacon/blocks/{block_id}"
};
}
// GetBlockRoot retrieves hashTreeRoot of BeaconBlock/BeaconBlockHeader.
rpc GetBlockRoot(BlockRequest) returns (BlockRootResponse) {
option (google.api.http) = {
get: "/eth/v1/beacon/blocks/{block_id}/root"
};
}
// GetBlockSSZ returns the SSZ-serialized version of block details for given block id.
rpc GetBlockSSZ(BlockRequest) returns (BlockSSZResponse) {
option (google.api.http) = {
get: "/eth/v1/beacon/blocks/{block_id}/ssz"
};
}
// ListBlockAttestations retrieves attestation included in requested block.
rpc ListBlockAttestations(BlockRequest) returns (BlockAttestationsResponse) {
option (google.api.http) = {
get: "/eth/v1/beacon/blocks/{block_id}/attestations"
};
}
// Beacon pools API related endpoints.
// ListPoolAttestations retrieves attestations known by the node but
// not necessarily incorporated into any block.
rpc ListPoolAttestations(AttestationsPoolRequest) returns (AttestationsPoolResponse) {
option (google.api.http) = {
get: "/eth/v1/beacon/pool/attestations"
};
}
// SubmitAttestations submits Attestation objects to node. If attestation passes all validation
// constraints, node MUST publish attestation on appropriate subnet.
rpc SubmitAttestations(SubmitAttestationsRequest) returns (google.protobuf.Empty) {
option (google.api.http) = {
post: "/eth/v1/beacon/pool/attestations"
body: "*"
};
}
// ListPoolAttesterSlashings retrieves attester slashings known by the node but
// not necessarily incorporated into any block.
rpc ListPoolAttesterSlashings(google.protobuf.Empty) returns (AttesterSlashingsPoolResponse) {
option (google.api.http) = {
get: "/eth/v1/beacon/pool/attester_slashings"
};
}
// SubmitAttesterSlashing submits AttesterSlashing object to node's pool and
// if passes validation node MUST broadcast it to network.
rpc SubmitAttesterSlashing(AttesterSlashing) returns (google.protobuf.Empty) {
option (google.api.http) = {
post: "/eth/v1/beacon/pool/attester_slashings"
body: "*"
};
}
// ListPoolProposerSlashings retrieves proposer slashings known by the node
// but not necessarily incorporated into any block.
rpc ListPoolProposerSlashings(google.protobuf.Empty) returns (ProposerSlashingPoolResponse) {
option (google.api.http) = {
get: "/eth/v1/beacon/pool/proposer_slashings"
};
}
// SubmitProposerSlashing submits AttesterSlashing object to node's pool and if
// passes validation node MUST broadcast it to network.
rpc SubmitProposerSlashing(ProposerSlashing) returns (google.protobuf.Empty) {
option (google.api.http) = {
post: "/eth/v1/beacon/pool/proposer_slashings"
body: "*"
};
}
// ListPoolVoluntaryExits retrieves voluntary exits known by the node but
// not necessarily incorporated into any block.
rpc ListPoolVoluntaryExits(google.protobuf.Empty) returns (VoluntaryExitsPoolResponse) {
option (google.api.http) = {
get: "/eth/v1/beacon/pool/voluntary_exits"
};
}
// SubmitVoluntaryExit submits SignedVoluntaryExit object to node's pool
// and if passes validation node MUST broadcast it to network.
rpc SubmitVoluntaryExit(SignedVoluntaryExit) returns (google.protobuf.Empty) {
option (google.api.http) = {
post: "/eth/v1/beacon/pool/voluntary_exits"
body: "*"
};
}
// Beacon config API related endpoints.
// GetForkSchedule retrieve all scheduled upcoming forks this node is aware of.
rpc GetForkSchedule(google.protobuf.Empty) returns (ForkScheduleResponse) {
option (google.api.http) = {get: "/eth/v1/config/fork_schedule"};
}
// Spec retrieves specification configuration (without Phase 1 params) used on this node. Specification params list
// Values are returned with following format:
// - any value starting with 0x in the spec is returned as a hex string
// - all other values are returned as number
rpc GetSpec(google.protobuf.Empty) returns (SpecResponse) {
option (google.api.http) = {get: "/eth/v1/config/spec"};
}
// GetDepositContract retrieves deposit contract address and genesis fork version.
rpc GetDepositContract(google.protobuf.Empty) returns (DepositContractResponse) {
option (google.api.http) = {get: "/eth/v1/config/deposit_contract"};
}
}
// Beacon State API related messages.
message GenesisResponse {
Genesis data = 1;
message Genesis {
// UTC time specified in the chain start event in the deposit contract.
google.protobuf.Timestamp genesis_time = 1;
// 32 byte hash tree root of the genesis validator set.
bytes genesis_validators_root = 2 [(ethereum.eth.ext.ssz_size) = "32"];
// 4 byte genesis fork version.
bytes genesis_fork_version = 3 [(ethereum.eth.ext.ssz_size) = "4"];
}
}
message StateRequest {
// The state id which can be any of: "head" (canonical head in node's view),
// "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.
// Uses the provided state_id for the request.
bytes state_id = 1; // TODO: Duck type handling.
}
message StateRootResponse {
StateRoot data = 1;
message StateRoot {
// SSZ encoded state root for the requested state.
bytes root = 1 [(ethereum.eth.ext.ssz_size) = "32"];
}
}
message StateForkResponse {
Fork data = 1;
}
message StateFinalityCheckpointResponse {
StateFinalityCheckpoint data = 1;
message StateFinalityCheckpoint {
Checkpoint previous_justified = 1;
Checkpoint current_justified = 2;
Checkpoint finalized = 3;
}
}
message StateValidatorsRequest {
// The state id which can be any of: "head" (canonical head in node's view),
// "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.
// Uses the provided state_id for the request.
bytes state_id = 1; // TODO: Duck type handling.
// An array of either hex encoded public keys (with 0x prefix) or validator indexes.
repeated bytes id = 2; // TODO: Duck type handling.
// The status to query validators for, can be one of: pending_initialized, pending_queued, active_ongoing,
// active_exiting, active_slashed, exited_unslashed, exited_slashed, withdrawal_possible,
// withdrawal_done, active, pending, exited, withdrawal
repeated ValidatorStatus status = 3;
}
message ValidatorBalancesRequest {
// The state id which can be any of: "head" (canonical head in node's view),
// "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.
// Uses the provided state_id for the request.
bytes state_id = 1; // TODO: Duck type handling.
// An array of either hex encoded public keys (with 0x prefix) or validator indexes.
repeated bytes id = 2; // TODO: Duck type handling.
}
message StateValidatorsResponse {
repeated ValidatorContainer data = 1;
}
message ValidatorBalancesResponse {
repeated ValidatorBalance data = 1;
}
message ValidatorBalance {
// The index of the validator the retrieved balance is for.
uint64 index = 1 [(ethereum.eth.ext.cast_type) = "github.com/prysmaticlabs/eth2-types.ValidatorIndex"];
// The balance of the requested validator.
uint64 balance = 2;
}
message StateValidatorRequest {
// The state id which can be any of: "head" (canonical head in node's view),
// "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.
// Uses the provided state_id for the request.
bytes state_id = 1; // TODO: Duck type handling.
// The public key or index for the validator to retrieve information for.
bytes validator_id = 2;
}
message StateValidatorResponse {
ValidatorContainer data = 1;
}
message StateCommitteesRequest {
// The state id which can be any of: "head" (canonical head in node's view),
// "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.
// Uses the provided state_id for the request.
bytes state_id = 1; // TODO: Duck type handling.
// The epoch to retrieve the committees of.
optional uint64 epoch = 2 [(ethereum.eth.ext.cast_type) = "github.com/prysmaticlabs/eth2-types.Epoch"];
// Committee index requested.
optional uint64 index = 3 [(ethereum.eth.ext.cast_type) = "github.com/prysmaticlabs/eth2-types.CommitteeIndex"];
// Committee slot requested.
optional uint64 slot = 4 [(ethereum.eth.ext.cast_type) = "github.com/prysmaticlabs/eth2-types.Slot"];
}
message StateCommitteesResponse {
repeated Committee data = 1;
}
// Beacon Block API related messages.
message BlockAttestationsResponse {
repeated Attestation data = 1;
}
message BlockRootContainer {
// 32 byte merkle tree root of the ssz encoded block.
bytes root = 1 [(ethereum.eth.ext.ssz_size) = "32"];
}
message BlockRootResponse {
BlockRootContainer data = 1;
}
message BlockHeadersRequest {
// Beacon chain slot of the requested block.
optional uint64 slot = 1 [(ethereum.eth.ext.cast_type) = "github.com/prysmaticlabs/eth2-types.Slot"];
// 32 byte merkle tree root of the ssz encoded parent block.
optional bytes parent_root = 2 [(ethereum.eth.ext.ssz_size) = "32"];
}
message BlockHeadersResponse {
repeated BlockHeaderContainer data = 1;
}
message BlockRequest {
// The block identifier. Can be one of: "head" (canonical head in node's view), "genesis",
// "finalized", <slot>, <hex encoded blockRoot with 0x prefix>.
bytes block_id = 1;
}
message BlockHeaderResponse {
BlockHeaderContainer data = 1;
}
message BlockHeaderContainer {
// 32 byte merkle tree root of the ssz encoded block.
bytes root = 1 [(ethereum.eth.ext.ssz_size) = "32"];
// Boolean indicating whether the block is canonical.
bool canonical = 2;
// Container for a signed beacon block header.
BeaconBlockHeaderContainer header = 3;
}
message BeaconBlockHeaderContainer {
// The unsigned beacon block header.
BeaconBlockHeader message = 1;
// 96 byte BLS signature from the validator that produced this block header.
bytes signature = 2 [(ethereum.eth.ext.ssz_size) = "96"];
}
message BlockResponse {
BeaconBlockContainer data = 1;
}
message BlockSSZResponse {
bytes data = 1;
}
message BeaconBlockContainer {
// The unsigned beacon block.
BeaconBlock message = 1;
// 96 byte BLS signature from the validator that produced this block.
bytes signature = 2 [(ethereum.eth.ext.ssz_size) = "96"];
}
// Beacon Pool related API service.
message AttestationsPoolRequest {
optional uint64 slot = 1 [(ethereum.eth.ext.cast_type) = "github.com/prysmaticlabs/eth2-types.Slot"];
optional uint64 committee_index = 2 [(ethereum.eth.ext.cast_type) = "github.com/prysmaticlabs/eth2-types.CommitteeIndex"];
}
message SubmitAttestationsRequest {
repeated Attestation data = 1;
}
message AttestationsPoolResponse {
repeated Attestation data = 1;
}
message AttesterSlashingsPoolResponse {
repeated AttesterSlashing data = 1;
}
message ProposerSlashingPoolResponse {
repeated ProposerSlashing data = 1;
}
message VoluntaryExitsPoolResponse {
repeated SignedVoluntaryExit data = 1;
}
// Beacon Config API related messages.
message ForkScheduleResponse {
// The fork data used for beacon chain versioning.
repeated Fork data = 1;
}
// Spec response is a generic flat map of key values.
// Values are returned with following format:
// - any value starting with 0x in the spec is returned as a hex string
// - all other values are returned as string-number
message SpecResponse {
map<string, string> data = 1;
}
message DepositContractResponse {
DepositContract data = 1;
}
message DepositContract {
// The chain_id of the network.
uint64 chain_id = 1;
// The address of the deployed deposit contract in use.
string address = 2;
}