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

This repository is a mirror of github.com/prysmaticlabs/prysm/proto/eth. This means changes and contributions to protobufs ARE NOT accepted in this repository and must instead be made in the source repository instead. This project is updated on every new release of Prysm.

For 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 and a member of the team or our community will be happy to assist you.

Here's what you need to get started:

• A modern, UNIX operating system
• Go installed
• The latest release of protocol buffers installed (the protoc compiler)
• The cmake package installed

To install the required dependencies for compiling the protocol buffers, run

make install

Next, to generate the Go stubs for the protocol buffers, run

make generate

Python libraries can be generated using scripts/build-py-package.py.

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 eth2. If you are confident in your desired changes, you can proceed by modifying the protobuf schema:

service BeaconChain {
    // Retrieve orphaned blocks from the eth2 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:

make generate

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:

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

Apache 2.0