Teku REST API完全参考：开发者必备的30个端点详解-拓冰建站

Teku REST API完全参考：开发者必备的30个端点详解

【免费下载链接】teku🚀 Open-source Ethereum consensus client written in Java项目地址: https://gitcode.com/gh_mirrors/te/teku

Teku作为一款开源的以太坊共识客户端，提供了全面且功能强大的REST API接口，让开发者能够轻松地与以太坊信标链进行交互。无论您是构建区块浏览器、监控工具，还是开发验证器管理应用，掌握Teku REST API都是不可或缺的技能。本文将为您详细解析Teku REST API的30个核心端点，帮助您快速上手并充分利用这一强大的工具。

📊 Teku REST API架构概览

Teku的REST API遵循以太坊信标链API标准，提供了完整的信标节点和验证器客户端功能。API主要分为以下几个核心模块：

信标链API(/eth/v1/beacon/*) - 处理区块、状态、证明等核心信标链数据
验证器API(/eth/v1/validator/*) - 验证器职责、证明聚合等验证器相关功能
节点API(/eth/v1/node/*) - 节点状态、同步信息、网络连接等节点管理功能
配置API(/eth/v1/config/*) - 网络配置、分叉计划等配置信息
事件API(/eth/v1/events) - 实时事件流订阅功能
调试API(/eth/v1/debug/*) - 调试和内部状态查询功能

🔍 核心端点详解

1. 网络状态与同步端点

获取节点同步状态-GET /eth/v1/node/syncing这是最常用的端点之一，用于检查节点是否正在同步以及同步进度。返回的数据包括当前头块槽位、同步距离和同步状态。

获取节点版本信息-GET /eth/v1/node/version返回Teku客户端的版本信息，包括软件版本、API版本等。

获取节点健康状态-GET /eth/v1/node/health检查节点是否正常运行，返回HTTP状态码200表示健康，503表示不健康。

获取节点身份信息-GET /eth/v1/node/identity返回节点的身份信息，包括节点ID、监听地址和发现地址。

2. 信标链数据端点

获取创世信息-GET /eth/v1/beacon/genesis返回网络的创世时间、创世验证器根和创世分叉版本。

获取区块头信息-GET /eth/v1/beacon/headers查询特定槽位或根哈希的区块头信息，支持分页查询。

获取区块数据-GET /eth/v1/beacon/blocks/{block_id}根据区块ID（槽位、根哈希或"genesis"、"head"、"finalized"等特殊值）获取完整的区块数据。

获取状态数据-GET /eth/v1/beacon/states/{state_id}获取特定状态ID的信标链状态数据，支持多种状态标识符格式。

获取状态验证器信息-GET /eth/v1/beacon/states/{state_id}/validators查询特定状态下所有验证器的详细信息，包括余额、状态和公钥。

3. 验证器管理端点

获取验证器职责-GET /eth/v1/validator/duties/proposer/{epoch}查询指定epoch中验证器的区块提议职责，验证器客户端使用此端点来确定何时需要提议区块。

获取证明数据-GET /eth/v1/validator/attestation_data为验证器生成证明数据，包括目标检查点、源检查点和信标区块根。

获取聚合证明-GET /eth/v1/validator/aggregate_attestation获取指定槽位和委员会索引的聚合证明。

提交证明-POST /eth/v1/validator/beacon_committee_subscriptions订阅信标委员会网络，用于接收证明相关的网络消息。

4. 区块操作端点

提交新区块-POST /eth/v1/beacon/blocks将新提议的区块发布到网络，这是验证器客户端在区块提议时的关键操作。

提交盲区块-POST /eth/v1/beacon/blinded_blocks提交盲区块（不包含执行负载的区块），用于MEV-Boost等构建器场景。

获取执行负载-GET /eth/v1/validator/execution_payload获取执行负载数据，用于构建包含交易数据的区块。

5. 证明与罚没端点

获取证明-GET /eth/v1/beacon/attestations/{attestation_id}查询特定证明的详细信息。

获取证明者罚没-GET /eth/v1/beacon/proposer_slashings获取待处理的证明者罚没交易。

获取证明者罚没-GET /eth/v1/beacon/attester_slashings获取待处理的证明者罚没交易。

提交证明者罚没-POST /eth/v1/beacon/proposer_slashings提交证明者罚没证据到网络。

提交证明者罚没-POST /eth/v1/beacon/attester_slashings提交证明者罚没证据到网络。

6. 自愿退出端点

获取自愿退出-GET /eth/v1/beacon/voluntary_exits获取待处理的自愿退出交易。

提交自愿退出-POST /eth/v1/beacon/voluntary_exits提交验证器的自愿退出请求。

7. 同步委员会端点

获取同步委员会信息-GET /eth/v1/beacon/sync_committees查询同步委员会的组成信息。

获取同步委员会贡献-GET /eth/v1/validator/sync_committee_contribution获取同步委员会的贡献数据。

提交同步委员会签名-POST /eth/v1/validator/sync_committee_subscriptions订阅同步委员会网络。

8. BLS到执行地址变更端点

获取BLS执行变更-GET /eth/v1/beacon/bls_to_execution_changes查询待处理的BLS到执行地址变更请求。

提交BLS执行变更-POST /eth/v1/beacon/bls_to_execution_changes提交BLS公钥到执行地址的变更请求。

9. 配置信息端点

获取网络配置-GET /eth/v1/config/spec返回网络的共识规范配置参数。

获取分叉计划-GET /eth/v1/config/fork_schedule返回网络的分叉激活时间表。

获取存款合约信息-GET /eth/v1/config/deposit_contract返回存款合约的地址和链ID信息。

10. 事件流端点

订阅事件流-GET /eth/v1/events建立服务器发送事件（SSE）连接，实时接收以下类型的事件：

head- 新区块头事件
block- 新区块事件
attestation- 新证明事件
voluntary_exit- 自愿退出事件
finalized_checkpoint- 最终化检查点事件
chain_reorg- 链重组事件

11. 调试与监控端点

获取链头信息-GET /eth/v1/debug/chain_heads返回所有链头的详细信息，用于调试分叉选择。

获取分叉选择状态-GET /eth/v1/debug/fork_choice返回分叉选择算法的内部状态。

获取状态数据-GET /eth/v1/debug/states/{state_id}获取完整的信标链状态数据（调试版本）。

12. 奖励计算端点

获取证明奖励-GET /eth/v1/rewards/attestations/{epoch}计算指定epoch的证明奖励。

获取区块奖励-GET /eth/v1/rewards/blocks/{block_id}计算特定区块的奖励。

获取同步委员会奖励-GET /eth/v1/rewards/sync_committee/{epoch}计算同步委员会的奖励。

🛠️ API使用最佳实践

1. 错误处理策略

Teku API遵循标准的HTTP状态码：

200 OK- 请求成功
400 Bad Request- 请求参数错误
404 Not Found- 资源不存在
503 Service Unavailable- 服务不可用（如节点正在同步）

2. 性能优化技巧

使用状态缓存：对于频繁查询的状态数据，考虑在客户端实现缓存机制。

批量请求：尽可能使用批量查询端点，减少网络往返次数。

连接复用：保持HTTP连接持久化，减少连接建立开销。

3. 安全性考虑

API认证：生产环境中建议启用API认证，防止未授权访问。

速率限制：合理控制请求频率，避免对节点性能造成影响。

TLS加密：在生产环境中始终使用HTTPS协议。

📈 实际应用场景

场景1：区块浏览器开发

# 获取最新区块头 curl -X GET "http://localhost:5051/eth/v1/beacon/headers" # 获取特定区块数据 curl -X GET "http://localhost:5051/eth/v1/beacon/blocks/head" # 获取验证器状态 curl -X GET "http://localhost:5051/eth/v1/beacon/states/head/validators"

场景2：验证器监控面板

# 检查节点同步状态 curl -X GET "http://localhost:5051/eth/v1/node/syncing" # 获取验证器职责 curl -X GET "http://localhost:5051/eth/v1/validator/duties/proposer/12345" # 订阅实时事件 curl -N "http://localhost:5051/eth/v1/events?topics=head,attestation"

场景3：网络分析工具

# 获取网络配置 curl -X GET "http://localhost:5051/eth/v1/config/spec" # 获取分叉计划 curl -X GET "http://localhost:5051/eth/v1/config/fork_schedule" # 获取节点连接信息 curl -X GET "http://localhost:5051/eth/v1/node/peers"

🔧 高级功能详解

1. 事件流订阅

Teku的事件流API支持服务器发送事件（SSE），允许客户端实时接收网络事件。这是构建实时监控应用的关键功能：

# 订阅所有事件类型 curl -N "http://localhost:5051/eth/v1/events" # 仅订阅区块和证明事件 curl -N "http://localhost:5051/eth/v1/events?topics=block,attestation"

支持的事件类型包括：

head- 新链头事件
block- 新区块事件
attestation- 新证明事件
voluntary_exit- 自愿退出事件
finalized_checkpoint- 最终化检查点事件
chain_reorg- 链重组事件

2. 状态标识符解析

Teku API支持多种状态标识符格式：

槽位编号："12345"
根哈希："0x1234..."
特殊值："genesis"、"head"、"finalized"、"justified"

3. 分页和过滤

许多列表端点支持分页查询：

page- 页码（从0开始）
per_page- 每页数量
status- 验证器状态过滤

🚀 性能调优建议

1. 连接管理

连接池配置：对于高并发应用，建议配置HTTP连接池：

// Java示例：使用连接池 PoolingHttpClientConnectionManager connManager = new PoolingHttpClientConnectionManager(); connManager.setMaxTotal(100); connManager.setDefaultMaxPerRoute(20);

超时设置：合理设置连接和读取超时：

连接超时：5-10秒
读取超时：30-60秒

2. 缓存策略

客户端缓存：对于不经常变化的数据（如配置信息），实现客户端缓存：

# Python示例：使用缓存装饰器 from functools import lru_cache import time @lru_cache(maxsize=128) def get_network_config(): # 缓存网络配置1小时 return api_client.get_config_spec()

3. 监控与告警

关键指标监控：

API响应时间（P95 < 500ms）
错误率（< 1%）
请求频率（监控异常峰值）

健康检查：定期调用健康检查端点：

# 健康检查脚本 while true; do response=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:5051/eth/v1/node/health) if [ "$response" != "200" ]; then echo "API服务异常: $response" # 触发告警 fi sleep 30 done