Our API documentation website is undergoing maintenance
One of the required components of nodes in the Ethereum 2.0 network is to expose an API server for outside interaction. This API is critical for running validators on eth2, 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 eth2 API schema is maintained in its unique repository: github.com/prysmaticlabs/ethereumapis and is implemented by Prysm beacon nodes here. Note, this API is only used by Prysm.
Prysm implements its API by using the popular gRPC project created by Google, providing highly advanced functionality for eth2. 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
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:
All our service definitions are explained below:
|eth||BeaconChain||v1alpha1||This service is used to retrieve critical data relevant to the Ethereum 2.0 phase 0 beacon chain, including the most recent head block, current pending deposits, the chain state and more.|
|eth||Node||v1alpha1||The Node service returns information about the Ethereum node itself, including versioning and general information as well as network sync status and a list of services currently implemented on the node.|
|eth||Validator||v1alpha1||This API provides the information a validator needs to retrieve throughout its life cycle, including recieved assignments from the network, its current index in the state as well as the rewards and penalties that have been applied to it.|
Thanks for wanting to contribute to our eth2 API! Go and Java libraries may be generated from the ethereumapis repository 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:
- A modern, UNIX operating system
- The latest release of Bazel 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. First, make sure the functionality you wish to add is not already covered by one of our endpoints on https://api.prylabs.network. Also, 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 eth2. If you are confident in your desired changes, you can proceed by modifying the protobuf schema:
After making your changes, you can regenerate the Go libraries from the schema by running:
Then, open a pull request with your changes on https://github.com/prysmaticlabs/ethereumapis. Next, you'll be ready to implement your new changes in Prysm itself.
Implementing Your Changes in Prysm
Ensure you have read our contribution guidelines first. Then, once your changes to the API schema are merged into the master branch of ethereumapis, you can update Prysm's dependency on ethereumapis to its latest version with the command:
Prysm also utilizes generated mocks for testing gRPC requests/responses, so you will also need to regenerate the required mocks by running:
Now, you will be able to implement your required changes in Prysm.
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.
This enables an HTTP REST to gRPC mapping, as shown below:
The majority of field primitive types for Ethereum are either
uint64. The canonical JSON mapping for those fields are a Base64 encoded string for
bytes, or a string representation of
For more details on JSON mapping for other types, view the relevant section in the proto3 language guide.