以太坊 API

该存储库托管了Prysm的 Ethereum 2.0 API 服务接口定义。这些协议缓冲区服务定义支持gRPC以及基于 HTTP 的 JSON。

需要帮助？

我们官方文档的这一部分提供了对每项服务的更深入的描述。有关 gRPC 和协议缓冲区功能的更多一般信息，请参阅gRPC 指南。如果您仍有疑问，请随时访问我们的Discord或Gitter，团队成员或我们的社区将很乐意为您提供帮助。

服务定义

贡献

感谢您愿意为我们的 eth2 API 做出贡献！Go 库可以使用Bazel从ethereumapis 存储库生成，从而可以轻松更改所需的模式并从中生成 Go 文件。

可以使用生成 Python 库scripts/build-py-package.py；我们定期将这些库作为ethereumapis推送到 PyPI 。

依赖项

以下是您需要开始的内容：

• 现代的 UNIX 操作系统
• 安装了最新版本的Bazel
• 安装的cmake包
• 安装的git包

进行 API 架构更改

假设您想BeaconChain在我们的 API 模式中向 gRPC 服务添加一个新端点以检索孤立块。首先，确保您希望添加的功能尚未被我们在https://api.prylabs.network上的端点之一覆盖。此外，请记住，在没有明显原因的情况下，对 API 模式进行严格更改通常很困难，因为许多不同的开发人员在 eth2 上使用此 API。如果您对所需的更改有信心，则可以通过修改 protobuf 架构来继续：

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;
}

进行更改后，您可以通过运行从模式重新生成 Go 库：

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

然后，在https://github.com/prysmaticlabs/ethereumapis上打开一个包含您更改的拉取请求。接下来，您将准备好在 Prysm 本身中实施您的新更改。

在 Prysm 中实施您的更改

确保您首先阅读了我们的贡献指南。然后，一旦您对 API 模式的更改合并到 ethereumapis 的主分支中，您可以使用以下命令将 Prysm 对 ethereumapis 的依赖更新到其最新版本：

$ bazel run //:gazelle -- update-repos github.com/prysmaticlabs/ethereumapis

Prysm 还利用生成的模拟来测试 gRPC 请求/响应，因此您还需要通过运行重新生成所需的模拟：

$ ./scripts/update-mockgen.sh

现在，您将能够在 Prysm 中实现所需的更改。

RESTful 端点（gRPC 转码）

所有 gRPC 服务都应通过指定HTTPRules来定义基于 HTTP 端点的 JSON 。开发人员可以选择将 gRPC 的 REST 服务与其客户端实现二进制文件捆绑在一起，或者，他们可以使用 JSON 编码代理，例如Envoy Proxy、grpc-gateway等。

有关 gRPC 转码的更多信息，请参阅此处的示例。

代码示例：

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

这启用了 HTTP REST 到 gRPC 的映射，如下所示：

JSON 映射

以太坊的大多数字段原始类型是bytes或uint64。这些字段的规范 JSON 映射是 的 Base64 编码字符串bytes，或 的字符串表示uint64。由于 JavaScript 会丢失超过MAX_SAFE_INTEGER的值的精度，因此 uint64 必须是 JSON 字符串才能容纳这些值。如果该字段值未更改并且仍设置为 protobuf 的默认值，则该字段将从 JSON 编码中完全省略。

有关其他类型的 JSON 映射的更多详细信息，请查看proto3 语言指南中的相关部分。

gRPC 工具和资源

• 很棒的 gRPC
• Google 的 API 风格指南
• protoc3 的语言参考
• 协议缓冲区基础：Go
• 使用 Envoy 将 gRPC 转码为 JSON/HTTP

执照

阿帕奇 2.0