prysm-pulse/proto/eth/service/beacon_chain_service.proto
terencechain d17996f8b0
Update to V4 🚀 (#12134)
* Update V3 from V4

* Fix build v3 -> v4

* Update ssz

* Update beacon_chain.pb.go

* Fix formatter import

* Update update-mockgen.sh comment to v4

* Fix conflicts. Pass build and tests

* Fix test
2023-03-17 18:52:56 +00:00

450 lines
20 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.service;
import "google/api/annotations.proto";
import "google/protobuf/descriptor.proto";
import "google/protobuf/empty.proto";
import "proto/eth/v1/beacon_block.proto";
import "proto/eth/v1/beacon_chain.proto";
import "proto/eth/v2/beacon_block.proto";
import "proto/eth/v2/beacon_chain.proto";
import "proto/eth/v2/beacon_state.proto";
import "proto/eth/v2/ssz.proto";
import "proto/eth/v2/sync_committee.proto";
import "proto/eth/v2/withdrawals.proto";
option csharp_namespace = "Ethereum.Eth.Service";
option go_package = "github.com/prysmaticlabs/prysm/v4/proto/eth/service";
option java_multiple_files = true;
option java_outer_classname = "BeaconChainServiceProto";
option java_package = "org.ethereum.eth.service";
option php_namespace = "Ethereum\\Eth\\Service";
// 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 Ethereum consensus APIs repository (beacon-apis/apis/).
service BeaconChain {
// Beacon state API related endpoints.
// GetGenesis retrieves details of the chain's genesis which can be used to identify chain.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/getGenesis
rpc GetGenesis(google.protobuf.Empty) returns (v1.GenesisResponse) {
option (google.api.http) = { get: "/internal/eth/v1/beacon/genesis" };
}
// GetWeakSubjectivity is a new proposed endpoint to retrieve the details necessary to download
// the ssz data needed to start a beacon node - checkpoint(epoch + block_root) and state_root
// DEPRECATED: GetWeakSubjectivity endpoint will no longer be supported
rpc GetWeakSubjectivity(google.protobuf.Empty) returns (v1.WeakSubjectivityResponse) {
option deprecated = true;
option (google.api.http) = { get: "/internal/eth/v1/beacon/weak_subjectivity" };
}
// GetStateRoot calculates HashTreeRoot for state with given 'stateId'. If stateId is root, same value will be returned.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/getStateRoot
rpc GetStateRoot(v1.StateRequest) returns (v1.StateRootResponse) {
option (google.api.http) = {
get: "/internal/eth/v1/beacon/states/{state_id}/root"
};
}
// GetStateFork returns Fork object for state with given 'stateId'.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/getStateFork
rpc GetStateFork(v1.StateRequest) returns (v1.StateForkResponse) {
option (google.api.http) = {
get: "/internal/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.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/getStateFinalityCheckpoints
rpc GetFinalityCheckpoints(v1.StateRequest) returns (v1.StateFinalityCheckpointResponse) {
option (google.api.http) = {
get: "/internal/eth/v1/beacon/states/{state_id}/finality_checkpoints"
};
}
// ListValidators returns a filterable list of validators with their balance, status and index.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/getStateValidators
rpc ListValidators(v1.StateValidatorsRequest) returns (v1.StateValidatorsResponse) {
option (google.api.http) = {
get: "/internal/eth/v1/beacon/states/{state_id}/validators"
};
}
// GetValidator returns a validator specified by state and id or public key along with status and balance.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/getStateValidator
rpc GetValidator(v1.StateValidatorRequest) returns (v1.StateValidatorResponse) {
option (google.api.http) = {
get: "/internal/eth/v1/beacon/states/{state_id}/validators/{validator_id}"
};
}
// ListValidators returns a filterable list of validator balances.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/getStateValidatorBalances
rpc ListValidatorBalances(v1.ValidatorBalancesRequest) returns (v1.ValidatorBalancesResponse) {
option (google.api.http) = {
get: "/internal/eth/v1/beacon/states/{state_id}/validator_balances"
};
}
// ListCommittees retrieves the committees for the given state at the given epoch.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/getEpochCommittees
rpc ListCommittees(v1.StateCommitteesRequest) returns (v1.StateCommitteesResponse) {
option (google.api.http) = {
get: "/internal/eth/v1/beacon/states/{state_id}/committees"
};
}
// ListSyncCommittees retrieves the sync committees for the given state at the given epoch.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/getEpochSyncCommittees
rpc ListSyncCommittees(v2.StateSyncCommitteesRequest) returns (v2.StateSyncCommitteesResponse) {
option (google.api.http) = {
get: "/internal/eth/v1/beacon/states/{state_id}/sync_committees"
};
}
// GetRandao fetches the RANDAO mix for the requested epoch from the state identified by state_id.
// If an epoch is not specified then the RANDAO mix for the state's current epoch will be returned.
// By adjusting the state_id parameter you can query for any historic value of the RANDAO mix.
// Ordinarily states from the same epoch will mutate the RANDAO mix for that epoch as blocks are applied.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=dev#/Beacon/getStateRandao
rpc GetRandao(v2.RandaoRequest) returns (v2.RandaoResponse) {
option (google.api.http) = {
get: "/internal/eth/v1/beacon/states/{state_id}/randao"
};
}
// Beacon blocks API related endpoints.
// ListBlockHeaders retrieves block headers matching given query. By default it will fetch current head slot blocks.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/getBlockHeaders
rpc ListBlockHeaders(v1.BlockHeadersRequest) returns (v1.BlockHeadersResponse) {
option (google.api.http) = {
get: "/internal/eth/v1/beacon/headers"
};
}
// GetBlockHeader retrieves block header for given block id.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/getBlockHeader
rpc GetBlockHeader(v1.BlockRequest) returns (v1.BlockHeaderResponse) {
option (google.api.http) = {
get: "/internal/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).
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/publishBlock
rpc SubmitBlock(v2.SignedBeaconBlockContainer) returns (google.protobuf.Empty) {
option (google.api.http) = {
post: "/internal/eth/v1/beacon/blocks"
body: "*"
};
}
// 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).
//
// The provided block must be SSZ-serialized.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/publishBlock
rpc SubmitBlockSSZ(v2.SSZContainer) returns (google.protobuf.Empty) {
option (google.api.http) = {
post: "/internal/eth/v1/beacon/blocks/ssz"
body: "*"
};
}
// SubmitBlindedBlock instructs the beacon node to use the components of the `SignedBlindedBeaconBlock` to construct
// and publish a `SignedBeaconBlock` by swapping out the `transactions_root` for the corresponding full list of `transactions`.
// The beacon node should broadcast a newly constructed `SignedBeaconBlock` 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).
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/publishBlindedBlock
rpc SubmitBlindedBlock(v2.SignedBlindedBeaconBlockContainer) returns (google.protobuf.Empty) {
option (google.api.http) = {
post: "/internal/eth/v1/beacon/blinded_blocks"
body: "*"
};
}
// SubmitBlindedBlock instructs the beacon node to use the components of the `SignedBlindedBeaconBlock` to construct
// and publish a `SignedBeaconBlock` by swapping out the `transactions_root` for the corresponding full list of `transactions`.
// The beacon node should broadcast a newly constructed `SignedBeaconBlock` 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).
//
// The provided block must be SSZ-serialized.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/publishBlindedBlock
rpc SubmitBlindedBlockSSZ(v2.SSZContainer) returns (google.protobuf.Empty) {
option (google.api.http) = {
post: "/internal/eth/v1/beacon/blinded_blocks/ssz"
body: "*"
};
}
// GetBlockRoot retrieves hashTreeRoot of BeaconBlock/BeaconBlockHeader.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/getBlockRoot
rpc GetBlockRoot(v1.BlockRequest) returns (v1.BlockRootResponse) {
option (google.api.http) = {
get: "/internal/eth/v1/beacon/blocks/{block_id}/root"
};
}
// GetBlock retrieves block details for given block id.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/getBlock
// DEPRECATED: GetBlock is deprecated in favor of GetBlockV2
rpc GetBlock(v1.BlockRequest) returns (v1.BlockResponse) {
option deprecated = true;
option (google.api.http) = {
get: "/internal/eth/v1/beacon/blocks/{block_id}"
};
}
// GetBlockSSZ returns the SSZ-serialized version of block details for given block id.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/getBlock
// DEPRECATED: GetBlockSSZ is deprecated in favor of GetBlockV2SSZ
rpc GetBlockSSZ(v1.BlockRequest) returns (v1.BlockSSZResponse) {
option deprecated = true;
option (google.api.http) = {
get: "/internal/eth/v1/beacon/blocks/{block_id}/ssz"
};
}
// GetBlockV2 retrieves block details for given block id.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/getBlockV2
rpc GetBlockV2(v2.BlockRequestV2) returns (v2.BlockResponseV2) {
option (google.api.http) = {
get: "/internal/eth/v2/beacon/blocks/{block_id}"
};
}
// GetBlindedBlock retrieves blinded block for given block id.
//
// https://ethereum.github.io/beacon-APIs/?urls.primaryName=dev#/Beacon/getBlindedBlock
rpc GetBlindedBlock(v1.BlockRequest) returns (v2.BlindedBlockResponse) {
option (google.api.http) = {
get: "/internal/eth/v1/beacon/blinded_blocks/{block_id}"
};
}
// GetBlindedBlockSSZ returns the SSZ-serialized version of blinded block details for given block id.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=dev#/Beacon/getBlindedBlock
rpc GetBlindedBlockSSZ(v1.BlockRequest) returns (v2.SSZContainer) {
option (google.api.http) = {
get: "/internal/eth/v1/beacon/blinded_blocks/{block_id}/ssz"
};
}
// GetBlockSSZV2 returns the SSZ-serialized version of block details for given block id.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/getBlockV2
rpc GetBlockSSZV2(v2.BlockRequestV2) returns (v2.SSZContainer) {
option (google.api.http) = {
get: "/internal/eth/v2/beacon/blocks/{block_id}/ssz"
};
}
// ListBlockAttestations retrieves attestation included in requested block.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/getBlockAttestations
rpc ListBlockAttestations(v1.BlockRequest) returns (v1.BlockAttestationsResponse) {
option (google.api.http) = {
get: "/internal/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.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/getPoolAttestations
rpc ListPoolAttestations(v1.AttestationsPoolRequest) returns (v1.AttestationsPoolResponse) {
option (google.api.http) = {
get: "/internal/eth/v1/beacon/pool/attestations"
};
}
// SubmitAttestations submits Attestation objects to node. If attestation passes all validation
// constraints, node MUST publish attestation on appropriate subnet.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/submitPoolAttestations
rpc SubmitAttestations(v1.SubmitAttestationsRequest) returns (google.protobuf.Empty) {
option (google.api.http) = {
post: "/internal/eth/v1/beacon/pool/attestations"
body: "*"
};
}
// ListPoolAttesterSlashings retrieves attester slashings known by the node but
// not necessarily incorporated into any block.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/getPoolAttesterSlashings
rpc ListPoolAttesterSlashings(google.protobuf.Empty) returns (v1.AttesterSlashingsPoolResponse) {
option (google.api.http) = {
get: "/internal/eth/v1/beacon/pool/attester_slashings"
};
}
// SubmitAttesterSlashing submits AttesterSlashing object to node's pool and
// if passes validation node MUST broadcast it to network.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/submitPoolAttesterSlashings
rpc SubmitAttesterSlashing(v1.AttesterSlashing) returns (google.protobuf.Empty) {
option (google.api.http) = {
post: "/internal/eth/v1/beacon/pool/attester_slashings"
body: "*"
};
}
// ListPoolProposerSlashings retrieves proposer slashings known by the node
// but not necessarily incorporated into any block.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/getPoolProposerSlashings
rpc ListPoolProposerSlashings(google.protobuf.Empty) returns (v1.ProposerSlashingPoolResponse) {
option (google.api.http) = {
get: "/internal/eth/v1/beacon/pool/proposer_slashings"
};
}
// SubmitProposerSlashing submits AttesterSlashing object to node's pool and if
// passes validation node MUST broadcast it to network.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/submitPoolProposerSlashings
rpc SubmitProposerSlashing(v1.ProposerSlashing) returns (google.protobuf.Empty) {
option (google.api.http) = {
post: "/internal/eth/v1/beacon/pool/proposer_slashings"
body: "*"
};
}
// ListPoolVoluntaryExits retrieves voluntary exits known by the node but
// not necessarily incorporated into any block.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/getPoolVoluntaryExits
rpc ListPoolVoluntaryExits(google.protobuf.Empty) returns (v1.VoluntaryExitsPoolResponse) {
option (google.api.http) = {
get: "/internal/eth/v1/beacon/pool/voluntary_exits"
};
}
// SubmitVoluntaryExit submits SignedVoluntaryExit object to node's pool
// and if passes validation node MUST broadcast it to network.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/submitPoolVoluntaryExit
rpc SubmitVoluntaryExit(v1.SignedVoluntaryExit) returns (google.protobuf.Empty) {
option (google.api.http) = {
post: "/internal/eth/v1/beacon/pool/voluntary_exits"
body: "*"
};
}
// SubmitSignedBLSToExecutionChanges submits said object to node's pool
// and if passes validation node MUST broadcast it to network.
rpc SubmitSignedBLSToExecutionChanges(v2.SubmitBLSToExecutionChangesRequest) returns (google.protobuf.Empty) {
option (google.api.http) = {
post: "/internal/eth/v1/beacon/pool/bls_to_execution_changes"
body: "*"
};
}
// Submits sync committee signature objects to the node.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Beacon/submitPoolSyncCommitteeSignatures
rpc SubmitPoolSyncCommitteeSignatures(v2.SubmitPoolSyncCommitteeSignatures) returns (google.protobuf.Empty) {
option (google.api.http) = {
post: "/internal/eth/v1/beacon/pool/sync_committees"
body: "*"
};
}
// ListBLSToExecutionChanges retrieves BLS to execution changes known by the node but not necessarily incorporated into any block
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=dev#/Beacon/getPoolBLSToExecutionChanges
rpc ListBLSToExecutionChanges(google.protobuf.Empty) returns (v2.BLSToExecutionChangesPoolResponse) {
option (google.api.http) = {
get: "/internal/eth/v1/beacon/pool/bls_to_execution_changes"
};
}
// Beacon config API related endpoints.
// GetForkSchedule retrieve all scheduled upcoming forks this node is aware of.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Config/getForkSchedule
rpc GetForkSchedule(google.protobuf.Empty) returns (v1.ForkScheduleResponse) {
option (google.api.http) = {get: "/internal/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
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Config/getSpec
rpc GetSpec(google.protobuf.Empty) returns (v1.SpecResponse) {
option (google.api.http) = {get: "/internal/eth/v1/config/spec"};
}
// GetDepositContract retrieves deposit contract address and genesis fork version.
//
// Spec: https://ethereum.github.io/beacon-APIs/?urls.primaryName=v2.3.0#/Config/getDepositContract
rpc GetDepositContract(google.protobuf.Empty) returns (v1.DepositContractResponse) {
option (google.api.http) = {get: "/internal/eth/v1/config/deposit_contract"};
}
}