Skip to main content
Version: 2.1.0

Prysm public API

This API is only used by Prysm

For a standard API that all Ethereum beacon nodes implement, see here. Over the next few quarters, we plan on deprecating this API and replacing it with the standard API.

One of the required components of nodes in the Ethereum beacon chain network is to expose an API server for outside interaction. This API is critical for running validators on Ethereum, as validator clients can connect to nodes and query their API to figure out their assigned duties, to submit block proposals, and more. Prysm's Ethereum consensus API schema is maintained in Prysm itself here: github.com/prysmaticlabs/prysm/proto and is implemented by Prysm beacon nodes and validators.

gRPC

Prysm implements its API by using the popular gRPC project created by Google, providing highly advanced functionality for Ethereum consensus. Interacting with the API requires the use of protocol buffers, also known as protobuf. These protocol buffer. For information on the functionality of gRPC and protocol buffers more generally, see the gRPC guide.

Calling the API on your local beacon node#

Do not publicly expose the API

The API's purpose is a means of communication between your beacon node and your validator client. Because of this it is not protected against external malicious users. Some endpoints are vulnerable to Denial-of-Service attacks, while others may disclose information about your beacon node. The communication between the beacon node and the validator client should be done privately, either on the same machine or through an SSH connection.

By default, the beacon node exposes a gRPC API on host 127.0.0.1:4000, which is accessed by the validator client. This is not an HTTP endpoint, so you will not be able to perform API queries via HTTP on that port. However, we also expose a JSON-HTTP endpoint on 127.0.0.1:3500 by default for your needs. If you want to query information such as the chainhead from your local beacon node, you can call:

http://127.0.0.1:3500/eth/v1alpha1/beacon/chainhead

Disabling the API#

By default the beacon node runs with all available set of APIs enabled. You might want to disable one or more APIs, for example for security reasons. The --http-modules flags allows fine-grained control over which APIs are available on your node.

Contributing#

Thanks for wanting to contribute to our Ethereum consensus API! Go and Java libraries may be generated from Prysm using Bazel, making it easy to make changes to the schemas needed and generate Go files or Java packages from them. Here's what you need to get started:

Dependencies#

  • A modern, UNIX operating system
  • The latest release of Bazel installed
  • The cmake package installed
  • The git package installed

Making API Schema Changes#

Say you want to add a new endpoint to the BeaconChain gRPC service in our API schema to retrieve orphaned blocks. Keep in mind making strict changes to the API schema can often times be difficult without a significant reason as this API is used by many different developers building on Ethereum consensus. If you are confident in your desired changes, you can proceed by modifying the protobuf schema:

service BeaconChain {    // Retrieve orphaned blocks from the Ethereum consensus chain.    rpc GetOrphanedBlocks(OrphanedBlocksRequest) returns (OrphanedBlocksResponse) {        option (google.api.http) = {            get: "/eth/v1alpha1/beacon/blocks/orphaned"        };    }    ...}
message OrphanedBlocksRequest {    uint64 slot = 1;}
message OrphanedBlocksResponse {    repeated BeaconBlock blocks = 1;}

After making your changes, you can regenerate the Go libraries from the schema by running:

$ ./hack/update-go-pbs.sh

Then, open a pull request with your changes on https://github.com/prysmaticlabs/prysm. Next, you'll be ready to implement your new changes in Prysm itself.

RESTful endpoints (gRPC Transcoding)#

All of the gRPC services should define JSON over HTTP endpoints by specifying HTTPRules. Developers may choose to bundle a REST service of gRPC with their client implementation binaries, or alternatively, they may use a JSON encoding proxy such as Envoy Proxy, grpc-gateway, etc.

For more information on gRPC transcoding, see the examples found here.

Code sample:

service Messaging {    rpc GetMessage(GetMessageRequest) returns (Message) {        option (google.api.http) = {            get: "/v1/{name=messages/*}"        };    }}message GetMessageRequest {    string name = 1; // Mapped to URL Path.}message Message {    string text = 1; // The resource content.}

This enables an HTTP REST to gRPC mapping, as shown below:

HTTPgRPC
GET /v1/messages/123456GetMessage(name: "messages/123456")

JSON mapping#

The majority of field primitive types for Ethereum are either bytes or uint64. The canonical JSON mapping for those fields are a Base64 encoded string for bytes, or a string representation of uint64. Since JavaScript loses precision for values over MAX_SAFE_INTEGER, uint64 must be a JSON string in order to accommodate those values. If the field value not changed and is still set to protobuf's default, this field will be omitted from the JSON encoding entirely.

For more details on JSON mapping for other types, view the relevant section in the proto3 language guide.

gRPC tooling and resources#