Sui gRPC 指南：端点、流式传输与 JSON-RPC 迁移

Sui gRPC：为什么它是默认集成路径

Sui gRPC 是 Sui 全节点暴露的基于协议的 RPC 接口。它使用基于 HTTP/2 的 Protocol Buffers（proto）实现类型安全、紧凑的双向通信。对于生产应用，gRPC 是推荐路径，因为它减少了负载大小、支持服务器流式传输，并直接映射到 Sui 的对象和检查点模型。

OnFinality 为主网和测试网提供托管的 Sui gRPC 和 RPC 基础设施。确切的端点和访问详情发布在 Sui 网络页面（/networks/sui）。团队应将 gRPC 视为基础设施：在迁移持续流量之前验证支持的服务、请求可见性和故障转移。

如果您从 JSON-RPC 迁移过来，应围绕工作流而不是逐一复制方法来规划迁移。链状态相同，但 gRPC 将操作分组到 LedgerService 和 TransactionExecutionService 等服务中。

使用 grpcurl 和授权占位符进行安全端点设置

要在没有生成客户端的情况下进行实验，请使用 grpcurl。除非您有明确许可并了解速率限制，否则不要粘贴第三方公共端点。对于 OnFinality 托管的端点，请使用占位符 GRPC_ENDPOINT 并通过 -rpc-header 传递身份验证元数据。确切的主机和令牌格式可从您的提供商仪表板或 /networks/sui 页面获得。

一个最小的 grpcurl 列表如下所示：

• 对于托管服务使用 TLS（端口 443）；明文 localhost 仅用于自托管全节点。
• 将授权令牌保存在环境变量或密钥管理器中；切勿提交。
• 使用 grpcurl $GRPC_ENDPOINT list 验证服务列表，然后使用 grpcurl $GRPC_ENDPOINT describe <service> 描述服务。

核心 Sui gRPC 服务及其职责

Sui gRPC API 被分组到 proto 文件中定义的服务中。对构建者最相关的四个服务是 LedgerService、StateService、TransactionExecutionService 和 SubscriptionService。还可能存在用于包元数据或签名验证的其他服务；请参阅您客户端生成的存根或提供商的服务列表。

读取对象和检查点

Sui 以对象为中心的模型意味着读取状态通常从对象 ID 或所有者地址开始。StateService 处理对象读取和相关查询。您可以使用生成客户端中针对这些工作流的方法检索单个对象、列出某个地址拥有的对象以及检查动态字段。由于 gRPC 方法是类型化的，您可以使用对象引用和受支持的字段掩码，而不是自由格式的 JSON 参数。

检查点检索由 LedgerService 提供。检查点是一组经过认证的交易，它界定了 Sui 最终性。使用 LedgerService 方法获取最新的检查点序列号，按序列或摘要获取检查点，并在检查点内分页查看交易列表。这是需要一致、有序数据的索引器的基础模式。

• 在处理检查点时始终捕获序列号、摘要和时间戳，以便可恢复。
• 对于对象读取，优先使用字段掩码来控制响应大小。
• 将对象版本视为重要信息：状态查询可能包含对象版本以推断更新。

使用 TransactionExecutionService 执行和模拟交易

TransactionExecutionService 是签名交易执行和模拟的所在。在发送交易前使用 SimulateTransaction 进行验证。模拟接受交易负载并返回效果而不提交状态，这使其对于估算 gas、检查 Move 错误和预览余额变化非常有用。

使用 ExecuteTransaction 提交完全签名的交易以包含。精确的请求字段在 proto schema 和生成的客户端包装器中定义；不要手动重建它们。调用 ExecuteTransaction 后，通过客户端或订阅信息流跟踪检查点包含情况或等待效果以确认最终性。

如果生成的客户端使用了略有不同的包装器名称，请遵循暴露 ExecuteTransaction 工作流的生成方法。

• 先模拟，后执行。
• 保持签名交易字节不变；签名后不要修改。
• 对重试使用幂等性或交易摘要检查。

使用 SubscribeCheckpoints、SubscribeTransactions 和 SubscribeEvents 进行流式传输

SubscriptionService 提供服务器流式 RPC，用于实时链活动。SubscribeCheckpoints 在检查点被认证时推送最终检查点。SubscribeTransactions 流式传输已执行的交易，SubscribeEvents 流式传输发出的 Move 事件。这些方法减少了轮询，使索引器、浏览器和警报系统能够以低延迟做出反应。

每个流在 proto 定义的地方支持服务器端过滤和字段掩码。重新连接时，使用最后处理的检查点序列或交易摘要来无缺口恢复。对于公共或托管端点，请注意流超时和重连策略；使用长时间运行的客户端进行测试。

• SubscribeCheckpoints：用于有序链状态和索引。
• SubscribeTransactions：用于交易信息流和内存池观察。
• SubscribeEvents：用于监听发出的 Move 事件类型。

实用的 JSON-RPC 到 gRPC 迁移映射

迁移是工作流映射，而不是一一对应的方法替换。诸如 suix_getObject、suix_getBalance、suix_executeTransactionBlock 和 suix_subscribeEvent 之类的遗留 JSON-RPC 方法在概念上映射到 StateService、LedgerService、TransactionExecutionService 和 SubscriptionService。但是，请求和响应结构不同，因为 gRPC 使用 protobuf 消息，而不是 SuiJSON。

首先梳理代码库中的 JSON-RPC 调用。将它们分为读取（对象、余额）、检查点、交易执行/模拟和订阅。然后使用您所用语言的生成 gRPC 客户端实现每个组。保留解析效果的相同应用逻辑；调整为原生 protobuf 类型。

不要根据 JSON-RPC 名称发明 protobuf 字段。从官方 Sui proto 定义或提供商文档化的客户端库生成存根，然后使用生成的方法。

主网和测试网注意事项

为主网和测试网使用单独的端点。测试网用于开发和测试，而不是生产。官方 Sui 测试网水龙头是 https://faucet.sui.io；在请求代币之前请验证当前水龙头政策和限制。测试网数据和端点不是永久的，可能会重置或更改。

主网端点需要仔细的容量规划和生产监控。OnFinality 的 Sui 网络页面（/networks/sui）列出了当前主网和测试网的详细信息。有关测试网特定的设置，请参阅 /rpc-assistant/sui-testnet-rpc。

• 切勿在测试网上重复使用主网代币或密钥。
• 在部署流程中保持测试网和主网配置分离。
• 将测试网流视为短暂的；从检查点构建可恢复性。

选择 OnFinality Sui gRPC 方案和运维检查

从共享基础设施迁移到专用基础设施时，请检查以下事项：该方案是否暴露所需的 gRPC 服务？是否允许订阅流，其超时/保留限制是什么？是否有请求和错误可见性？是否需要专用节点来实现隔离或可预测的容量？

OnFinality 的 Sui RPC 提供商指南（/rpc-assistant/sui-rpc-providers）和 Sui RPC 节点页面（/rpc-assistant/sui-rpc-node）解释了这些选项。使用 Sui 网络页面（/networks/sui）获取端点事实。

常见问题