ethereumapis

Ethereum APIs

This repository hosts Prysm's service interface definitions for the Ethereum 2.0 API. These protocol buffer service definitions support gRPC as well as JSON over HTTP.

Need assistance?

More indepth descriptions of each service are available in this section of our official documentation. For more general information on the functionality of gRPC and protocol buffers, see the gRPC guide. If you still have questions, feel free to stop by either our Discord or Gitter and a member of the team or our community will be happy to assist you.

Services

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

• The latest release of protobuf compiler (protoc)

Compiling with protoc

1. First, ensure you have the most recent version of protoc installed by issuing the command:

protoc --version

1. 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.

1. 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. Example:

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 for such. 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 in google/api/http.proto.

An example:

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:

JSON mapping

The majority of field primative 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 relevent section in the proto3 language guide.

Helpful gRPC tooling and resources

• Awesome gRPC
• Google's API Style Guide
• Language reference for protoc3
• Protocol Buffer Basics: Go
• Transcoding gRPC to JSON/HTTP using Envoy

Contributing

We have put all of our contribution guidelines into CONTRIBUTING.md! Check it out to get started.

License

Apache 2.0