Engine API

相关源文件

• beacon/engine/gen_ed.go
• beacon/engine/gen_epe.go
• beacon/engine/types.go
• eth/catalyst/api.go
• eth/catalyst/api_test.go
• eth/catalyst/queue.go
• eth/catalyst/simulated_beacon.go
• eth/catalyst/simulated_beacon_api.go
• eth/catalyst/simulated_beacon_test.go
• ethclient/simulated/backend.go
• miner/payload_building.go
• miner/payload_building_test.go

Engine API 是以太坊执行层 (geth) 与共识层 (信标链) 之间的接口。它通过一组 JSON-RPC 方法，使共识层能够驱动区块生产、验证信标链的区块体，并管理链的规范链。本文档涵盖了 API 实现、区块体构建系统以及用于测试的模拟信标链客户端。

有关更广泛的 RPC 系统信息，请参阅 RPC API。有关区块生产机制的详细信息，请参阅 挖矿与区块创建。

概述

Engine API 是以太坊 PoS 系统中执行层和共识层之间的桥梁。共识层通过此 API 进行以下操作：

• 请求构建新区块的区块体
• 提交新区块体以供执行和验证
• 更新分叉选择（规范链头）
• 检索已构建的区块体和交易 blobs
• 交换配置参数

来源：eth/catalyst/api.go46-56 eth/catalyst/simulated_beacon.go84-99

核心 API 结构

主要的 Engine API 是由 ConsensusAPI 结构体实现的，该结构体提供了所有标准化的引擎方法。该 API 在需要身份验证的情况下注册，并在 engine 命名空间下公开。

来源：eth/catalyst/api.go45-56 eth/catalyst/api.go115-153

关键 API 方法

Engine API 提供了版本化的方法，这些方法会随着以太坊的硬分叉计划而演进。

方法组	目的	版本
ForkchoiceUpdated	更新规范链头并请求区块体构建	V1, V2, V3
NewPayload	提交并验证新的执行区块体	V1, V2, V3, V4
GetPayload	按 ID 检索已构建的区块体	V1, V2, V3, V4
ExchangeTransitionConfiguration	验证合并参数	V1
GetBlobs	检索 blob 交易数据	V1

来源：eth/catalyst/api.go83-113

分叉选择管理

ForkchoiceUpdated 方法处理链头更新和区块体构建请求。这些方法会验证新链头，更新已最终确定的/安全的区块，并根据提供的属性选择性地启动区块体构建。

来源：eth/catalyst/api.go243-387 eth/catalyst/api.go179-241

分叉验证和链更新

分叉选择更新流程包括多个验证步骤：

1. 链头区块验证：确保请求的链头区块存在或可同步。
2. 无效祖先检查：防止在已知坏区块上构建。
3. 规范链更新：如果与当前链头不同，则设置新的链头。
4. 最终确定：更新已最终确定的和安全的区块指针。
5. 区块体构建：如果提供了属性，则开始构建新的区块体。

该 API 维护着无效区块的临时缓存，以避免重复处理已知坏链。

来源：eth/catalyst/api.go258-291 eth/catalyst/api.go313-357 eth/catalyst/api.go722-769

区块体构建和管理

区块体构建由一个复杂的系统处理，该系统能够构建空区块和完整区块，并持续优化以获得最大的交易费用收益。

来源：miner/payload_building.go36-64 miner/payload_building.go208-275 eth/catalyst/queue.go41-108

区块体生命周期

每个区块体都经历一个由 Payload 结构体管理的定义生命周期。

1. 初始化：立即创建空区块以快速响应。
2. 后台构建：持续构建包含交易的完整区块。
3. 费用优化：当构建出更高费用的版本时，更新区块体。
4. 解析：返回可用的最佳区块体（空区块或完整区块）。
5. 终止：在 12 秒后或检索到后停止构建。

该系统确保总有一个可交付的区块体，同时优化交易费用。

来源：miner/payload_building.go71-98 miner/payload_building.go100-134 miner/payload_building.go138-206

区块体执行和验证

NewPayload 方法处理来自共识层的传入执行区块体。这些方法会验证区块体，并将它们插入到区块链中，但不会更新规范链头。

来源：eth/catalyst/api.go557-668 beacon/engine/types.go216-298

区块体验证

验证过程包含多个检查：

• 参数验证：确保必需字段符合分叉要求。
• 区块构建：将 ExecutableData 转换为 types.Block。
• 父区块验证：确认父区块存在且有效。
• 无效祖先检查：防止在已知坏链上构建。
• 状态可用性：确保父区块状态可用于执行。

来源：eth/catalyst/api.go485-555 beacon/engine/types.go230-298

数据类型和结构

Engine API 使用 engine 包中定义的标准化数据结构，用于执行层和共识层之间的通信。

核心数据类型

来源：beacon/engine/types.go44-51 beacon/engine/types.go61-80 beacon/engine/types.go106-113 beacon/engine/types.go132-137

硬分叉中的类型演变

Engine API 的类型会随着以太坊硬分叉而演进，以支持新功能。

硬分叉	新增字段	方法
上海	Withdrawals (提款)	V2 方法
Cancun (坎昆)	BlobGasUsed、ExcessBlobGas、BeaconRoot	V3 方法
Prague (布拉格)	ExecutionRequests (执行请求)	V4 方法

每个版本都会验证是否存在适用于目标硬分叉的正确字段。

来源：eth/catalyst/api.go194-241 eth/catalyst/api.go514-555

模拟信标链客户端

SimulatedBeacon 提供了一个测试框架，用于模拟共识层行为，从而无需完整的信标链即可进行开发和测试。

来源： eth/catalyst/simulated_beacon.go84-141 eth/catalyst/simulated_beacon.go267-282

信标模拟功能

模拟信标支持多种运行模式

1. 周期模式：以固定间隔自动生成区块
2. 按需模式：通过显式 Commit() 调用生成区块
3. 交易驱动：交易到达时自动提交
4. 分叉模拟：支持链重组以进行测试

模拟器处理提款排队、费用接收方管理和信标根生成。

来源： eth/catalyst/simulated_beacon.go149-166 eth/catalyst/simulated_beacon.go309-350 eth/catalyst/simulated_beacon_api.go27-105

集成与使用

Engine API 集成了 geth 的核心系统，以提供共识层功能

注册和生命周期

来源： eth/catalyst/api.go45-56 eth/catalyst/api.go155-177 eth/catalyst/api.go788-833

错误处理和监控

API 包括全面的错误处理和监控

• 无效区块跟踪：防止重复处理坏区块
• 信标客户端监控：在共识客户端离线时发出警告
• 信封超时：确保及时信封交付
• 分叉验证：防止无效链状态转换

通过广泛的日志记录和指标收集，系统保持了运营可见性。

来源： eth/catalyst/api.go140-153 eth/catalyst/api.go710-769 eth/catalyst/api.go788-833