Ethereum 2.0 Public API

Our Prysm nodes define a public API exposed by their inner RPC servers to query important information about the Ethereum 2.0 network and for connected validators to submit block proposals and attestations directly to the node. You can find all our protobuf definitions for our RPC API's in our repo here.

We use the popular gRPC framework by Google to allow us to create easy API servers and clients with robust tests and definitions. We simply define our APIs in a protobuf format file as follows:

service BeaconService {
rpc WaitForChainStart(google.protobuf.Empty) returns (stream ChainStartResponse);
rpc CanonicalHead(google.protobuf.Empty) returns (ethereum.beacon.p2p.v1.BeaconBlock);
rpc PendingDeposits(google.protobuf.Empty) returns (PendingDepositsResponse);
rpc Eth1Data(google.protobuf.Empty) returns (Eth1DataResponse);
rpc ForkData(google.protobuf.Empty) returns (ethereum.beacon.p2p.v1.Fork);
}

Having a single place for API definitions such as protobufs gives clients a great way to know exactly the type of data they need to send and the data they will receive back with type annotations, instead of having to read through endless documentation if the API were pure JSON.

That said, here is our full Ethereum 2.0 public API and type definitions:

Validator Public API

service ValidatorService {
rpc WaitForActivation(ValidatorActivationRequest) returns (stream ValidatorActivationResponse);
rpc ValidatorIndex(ValidatorIndexRequest) returns (ValidatorIndexResponse);
rpc CommitteeAssignment(ValidatorEpochAssignmentsRequest) returns (CommitteeAssignmentResponse);
rpc ValidatorStatus(ValidatorIndexRequest) returns (ValidatorStatusResponse);
rpc ValidatorPerformance(ValidatorPerformanceRequest) returns (ValidatorPerformanceResponse);
}

Our validator public API contains all the important information a validator needs to know throughout its lifecycle, including assignments, its index in the state, its performance in terms of rewards and penalties applied.

Beacon Chain API

service BeaconService {
rpc WaitForChainStart(google.protobuf.Empty) returns (stream ChainStartResponse);
rpc CanonicalHead(google.protobuf.Empty) returns (ethereum.beacon.p2p.v1.BeaconBlock);
rpc PendingDeposits(google.protobuf.Empty) returns (PendingDepositsResponse);
rpc Eth1Data(google.protobuf.Empty) returns (Eth1DataResponse);
rpc ForkData(google.protobuf.Empty) returns (ethereum.beacon.p2p.v1.Fork);
}

Our beacon chain API returns important info about the canonical chain state and other data structures contained in the lifecycle of the chain, including pending deposits, the latest canonical head block, and more.

Proposer & Attester APIs

service ProposerService {
rpc ProposerIndex(ProposerIndexRequest) returns (ProposerIndexResponse);
rpc PendingAttestations(PendingAttestationsRequest) returns (PendingAttestationsResponse);
rpc ProposeBlock(ethereum.beacon.p2p.v1.BeaconBlock) returns (ProposeResponse);
rpc ComputeStateRoot(ethereum.beacon.p2p.v1.BeaconBlock) returns (StateRootResponse);
}

Our proposer API contains critical methods for validator clients to propose data to the beacon chain. As long as a validator client conforms to the message types required by the API, they would be able to effectively propose and attest to beacon blocks.

Finally, our attester API contains the only two utilities attesters need to perform their responsibility.

service AttesterService {
rpc AttestHead(ethereum.beacon.p2p.v1.Attestation) returns (AttestResponse);
rpc AttestationDataAtSlot(AttestationDataRequest) returns (AttestationDataResponse);
}

‚Äč