Ethereum 2.0 Public API

This section contains service definitions and gRPC instructions to interact with the public API.

One of the required components for staking on the Ethereum 2.0 network is the gRPC server. It is utilised by the client to query the network for a variety of different public data, from the canonical head block to versioning and assignments.

Interacting with the API requires the use of protocol buffers, also known as protobuf. These protocol buffer service definitions support both gRPC as well as JSON over HTTP. For information on the functionality of gRPC and protocol buffers more generally, see the gRPC guide.

Service definitions

Package

Service

Version

Description

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

v1alpha`

This API provides the information a validator needs to retrieve throughout its lifecycle, 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.

Generating client libraries

Client libraries may be generated using protoc, a language-neutral tool for serializing structured data. Below are instructions for performing an installation and compiling a .proto file.

Dependencies

Compiling with protoc

First, ensure you have the most recent version of protoc installed.

protoc --version

Then, to install the Go protocol buffers plugin, issue the command:

go get -u github.com/golang/protobuf/protoc-gen-go

The compiler plugin protoc-gen-go will be installed in $GOBIN, defaulting to $GOPATH/bin. It must be in your $PATH for protoc to locate it.

The compiler can now be run. Note that this command requires a few parameters; namely a source directly, a destination directory and a path to the .proto file itself.

protoc -I=$SRC_DIR --go_out=$DST_DIR $SRC_DIR/node.proto

The above command will generate a node.pb.go file in your specified destination directory.

Additional information

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:

HTTP

gRPC

GET /v1/messages/123456

GetMessage(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