BNB Chain BEP-675 构建者集成指南:BidBlock 端到端实现与源码级解析
BNB Chain BEP-675 构建者集成指南:BidBlock 端到端实现与源码级解析
BEP-675(Builder-Proposed Block with Validator Blind Signing)是 BNB Smart Chain 上由构建者(Builder)直接产出完整区块、验证者(Validator)仅做"盲签名"的 MEV 区块提交流程。本文以 core/types/builder/bep-675-builder-integration.md 为骨架,结合当前仓库中 core/types/builder、consensus/parlia、miner 等模块的真实实现,完整讲解构建者侧集成 BidBlock 的 API 调用链、payload 组装、签名方式、权限生命周期、错误处理与发送时序。读完本文,你将掌握如何在自己的构建者服务中实现"头部骨架 → 执行用户交易 → 生成未签名系统交易 → 组装与签名 → 权限探测与回退 → 窗口内发送"的完整闭环,并能读懂验证者侧对应的校验逻辑。
总体工作流
构建者端到端产出并提交一个 BidBlock 的流程如下:
parent header / state
→ initialize header skeleton
→ Parlia.PrepareForBidBlock
fills Coinbase / Difficulty / Time / MixDigest / Extra / Nonce
(Extra will be overwritten by the validator)
→ select and execute user txs
produces body.Transactions / receipts / updated state
→ Parlia.FinalizeAndAssembleBidBlock
executes and appends unsigned system tx
returns the complete block
→ block → builder.BidBlock
Header = block.Header()
Transactions = tx.MarshalBinary()
Sidecars = block.Sidecars()
→ Sign BidBlock.Hash()
produces builder.BidBlockArgs
→ mev_getBidBlockPermission(builder)
(cached; if !allowed, fall back to mev_sendBid)
→ mev_sendBidBlock
整个流程分为三个层次:共识层装配(Parlia 引擎补齐共识字段并追加系统交易)、payload 组装层(把 *types.Block 转换为 builder.BidBlock 并进行签名)、RPC 交互层(权限探测、发送与回退)。下文按文档结构逐节展开,并补充源码佐证。
1. 准备头部骨架(PrepareForBidBlock)
构建者首先填充本地已知的字段(ParentHash、Number、GasLimit、BaseFee),然后调用 PrepareForBidBlock 补齐 Parlia 共识字段:
header := &types.Header{
ParentHash: parent.Hash(),
Number: new(big.Int).Add(parent.Number, common.Big1),
GasLimit: gasLimit,
BaseFee: baseFee,
}
err := parliaEngine.PrepareForBidBlock(chain, header)
PrepareForBidBlock 会写入 Coinbase / Difficulty / Time / MixDigest / Extra / Nonce。关键区别:Coinbase 取自父快照的 inturnValidator(),而不是本地 p.val——因为构建者并不持有验证者密钥。
该行为在 consensus/parlia/bid_block.go 中有直接实现:
// PrepareForBidBlock is Prepare with Coinbase set to the in-turn validator instead of p.val.
func (p *Parlia) PrepareForBidBlock(chain consensus.ChainHeaderReader, header *types.Header) error {
// Coinbase must be set before prepare(): backOffTime and calcDifficulty depend on it.
number := header.Number.Uint64()
snap, err := p.snapshot(chain, number-1, header.ParentHash, nil)
if err != nil {
return err
}
header.Coinbase = snap.inturnValidator()
return p.prepare(chain, header)
}
源码注释点明了一个重要的依赖顺序:Coinbase 必须在 prepare() 之前设置,因为 backOffTime 和 calcDifficulty 的计算依赖它。另外注意 Extra 字段会被验证者在盲签名阶段覆盖,构建者在此处填写的 Extra 最终不进入链上区块。
2. 执行用户交易
交易选择与 EVM 执行完全由构建者驱动,协议规范对其不加约束。构建者在父状态上执行选中的用户交易,并维护 state / receipts / body.Transactions / sidecars 四类中间产物。这一阶段没有专用的共识层 API,构建者可自由选择自己的交易排序、gas 竞价与 bundle 组装策略。
需要留意的是,BidBlock 的 Transactions 字段中用户交易必须排在前、未签名系统交易排在后(即下文的"硬排序约束"),因此构建者在维护交易列表时需要预留尾部区域。
3. 收尾:生成未签名系统交易(FinalizeAndAssembleBidBlock)
用户交易执行完毕后,调用 FinalizeAndAssembleBidBlock 生成完整区块:
block, receipts, err := parliaEngine.FinalizeAndAssembleBidBlock(
chain, header, state, body, receipts, tracer,
)
输入
header/state/body/receipts:均为用户交易已执行完毕后的状态。
执行过程
- 内部进入
finalizeAndAssemble(..., systemTxPacking)路径。 - 按 Parlia 规则生成并执行尾随系统交易(trailing system txs):
deposit(总是执行)distributeFinalityReward(每 200 个区块执行一次,对应finalityRewardInterval)updateValidatorSetV2(仅在 breathe block 执行)
- 系统交易真实地在 EVM 上执行,因此会:
- 更新 state;
- 增加
header.GasUsed; - 追加一条 receipt;
- 影响
Root/ReceiptHash/Bloom/GasUsed这些最终字段。
- 但在
systemTxPacking模式下,这些交易不使用验证者密钥签名:追加到区块中的系统交易是未签名的(v/r/s = 0,gasPrice = 0)。 - 计算最终 state root,由
header+body+receipts装配出完整区块。
输出
- 完整区块(含未签名的尾随系统交易);
- 完整 receipts。
对应的引擎入口在 consensus/parlia/bid_block.go:
// FinalizeAndAssembleBidBlock assembles a BidBlock with unsigned system txs.
func (p *Parlia) FinalizeAndAssembleBidBlock(chain consensus.ChainHeaderReader, header *types.Header, state *state.StateDB,
body *types.Body, receipts []*types.Receipt, tracer *tracing.Hooks) (*types.Block, []*types.Receipt, error) {
block, receipts, err := p.finalizeAndAssemble(chain, header, state, body, receipts, tracer, systemTxPacking)
if err != nil {
return nil, nil, err
}
return block, receipts, nil
}
关于签名与 GasFee 的关键结论
- 签名不影响 EVM 状态迁移:无论系统交易是已签名(验证者挖矿路径)还是未签名(构建者打包路径),执行结果完全一致。验证者在 seal 阶段会为这些未签名系统交易做"绑定签名"(bind-sign),并据此重算
TxHash。验证者侧的实现见 miner/bid_block.go 的bindSignBidBlockSystemTxs:它遍历尾随系统交易,逐个调用p.SignSystemTx(tx, chainID)就地替换签名。 - GasFee 不是 BidBlock 的线上字段(wire field):验证者从尾随
deposit系统交易的value推导出 GasFee,并用它来对同一父区块的多个 BidBlock 进行排序。验证者侧的推导逻辑在 consensus/parlia/bid_block.go 的ExtractBidBlockDepositValue:它从后向前扫描未签名系统交易区,取其起始索引并返回首条deposit交易的value。
验证者侧的系统交易形状校验
构建者提交的未签名系统交易并非任意内容,验证者在准入阶段会做两层校验(consensus/parlia/bid_block.go 的 VerifyBidBlockSystemTxs):
- Stage 1(白名单):每个尾随未签名交易必须是 BEP-675 可签名白名单成员——目标为
systemcontracts.ValidatorContract、gasPrice 为 0、v/r/s 全零、且方法选择器在signableSystemTxSelectors内(deposit=0xf340fa01、distributeFinalityReward=0x300c3567、updateValidatorSetV2=0x1e4c1524,见 consensus/parlia/bid_block.go)。 - Stage 2(形状与顺序):选择器与顺序必须匹配
expectedSystemTxShape,即deposit → distributeFinalityReward(条件性)→ updateValidatorSetV2(条件性),既不能缺失也不能有多余。
因此构建者在组装尾随系统交易时必须严格遵循上述选择器与顺序约定,否则将被验证者以准入失败拒绝。
4. 组装 BidBlock Payload
将 *types.Block 转换为 builder.BidBlock:
txBytes := make([]hexutil.Bytes, len(block.Transactions()))
for i, tx := range block.Transactions() {
enc, _ := tx.MarshalBinary()
txBytes[i] = enc
}
bidBlock := &builder.BidBlock{
Header: block.Header(),
Transactions: txBytes,
Sidecars: block.Sidecars(),
}
硬排序约束:用户交易在前,未签名系统交易在后。这一约束在数据结构层面被明确注释:core/types/builder/bid.go 中 BidBlock.Transactions 的 json 标签注释写明 // user txs first, unsigned system txs last。
BidBlock 结构体定义:
// BidBlock is the builder-proposed block carried by BidBlockArgs.
type BidBlock struct {
Header *types.Header `json:"header"`
Transactions []hexutil.Bytes `json:"transactions"` // user txs first, unsigned system txs last
Sidecars types.BlobSidecars `json:"sidecars,omitempty"`
hash atomic.Value
}
值得注意的实现细节:BidBlock.Hash()(core/types/builder/bid.go)实际计算的是 Header.Hash()——头部携带 TxHash,验证者在盲签名前会用 TxHash 与 Transactions 交叉校验,确保交易列表与头部一致。同时该 Hash 被 atomic.Value 缓存,避免重复计算(每次计算还会输出 debug 日志记录 tx 与 sidecar 数量)。
5. 签名
sig, _ := crypto.Sign(bidBlock.Hash().Bytes(), builderKey)
args := &builder.BidBlockArgs{BidBlock: bidBlock, Signature: sig}
签名对象是裸的 keccak 摘要,不带 EIP-191/712 前缀,与既有 mev_sendBid 的签名约定保持一致。验证者通过 args.EcrecoverSender() 恢复构建者地址。
验证者侧的实现同样在 core/types/builder/bid.go:
// EcrecoverSender recovers the builder address from the signature over BidBlock.Hash().
func (b *BidBlockArgs) EcrecoverSender() (common.Address, error) {
pk, err := crypto.SigToPub(b.BidBlock.Hash().Bytes(), b.Signature)
if err != nil {
return common.Address{}, err
}
return crypto.PubkeyToAddress(*pk), nil
}
恢复出的构建者地址将用于后续的权限检查与配额统计。另外 BidBlockArgs.ToDecodedBidBlock(core/types/builder/bid.go)会把 RPC 载荷解码为验证者内部表示 DecodedBidBlock(含 Builder、Header、Txs、Sidecars、SystemTxStart 等字段),其中 Sidecars 为空时会规范化为空的 types.BlobSidecars{};交易发送者恢复则被推迟到 InsertChain 阶段进行。
6. 发送与回退
权限探测:mev_getBidBlockPermission
构建者轮询 mev_getBidBlockPermission,判断 BidBlock 通道在某验证者上是否对自己开放;不开放时回退到传统 mev_sendBid。
该 RPC 不会通过 JSON-RPC error 暴露权限拒绝——状态承载在结果的 allowed 字段中。当 allowed 为 false 时,reason 说明原因。当前取值:
insertchain_failed—— 该构建者最近一次被密封的 BidBlock 在验证者侧InsertChain失败(如 state root 无效、receipt hash 不匹配、KZG proof 失败)。gasprice_too_low—— 密封的 BidBlock 成功导入,但其平均 gas 价格(排除系统交易后)低于验证者配置的最小值。manual—— 管理员通过admin_setBidBlockPermission手动撤销。
mev_getBidBlockPermission 响应示例:
{
"allowed": false,
"reason": "insertchain_failed",
"blockHash": "0x...",
"blockNumber": "0x123",
"revokedAt": "2026-05-22T...", // when the revoke happened
"resetAt": "2026-05-23T00:00:00Z" // when the revoke expires (RPC returns the lockout expiry; builder may treat as informational)
}
该响应结构对应 core/types/builder/bid_block_permission.go 中的 BidBlockPermissionStatus(Allowed / Reason / BlockHash / BlockNum / RevokedAt / ResetAt)。
验证者侧权限管理器实现在 miner/bid_block_permission.go:
BidBlockPermissionManager按构建者地址维护撤销记录,撤销仅保存在内存中、在锁定期(lockout window)后惰性过期;- 默认撤销窗口
bidBlockRevokeDuration = 24 * time.Hour,用于无效 BidBlock; - gas 价格策略撤销窗口
bidBlockGasPriceLowRevokeDuration = 450 * time.Second(约一个 epoch); SetAllowed(builder, false)会写入Reason = RevokeReasonManual(即 "manual");GetStatus返回的ResetAt = RevokedAt + Duration,与 RPC 暴露的字段一致。
mev_sendBidBlock 错误映射
BidBlock 的主要失败模式都有专属 JSON-RPC 错误码,建议优先按 code 匹配;-38001 仍是参数/预检错误的兜底码,因此仍需检查 message。错误码常量定义在 core/types/builder/bid_error.go:
| Error message contains | JSON-RPC code | Builder action |
|---|---|---|
BidBlock disabled, fallback to SendBid |
-38001 | fallback to mev_sendBid |
builder BidBlock permission revoked, fallback to SendBid |
-38006 | permission not allowed; fallback to mev_sendBid |
pre-seal verify failed: ... |
-38007 | fix build logic; do NOT retry the same BidBlock |
too late, expected before ... |
-38008 | dropped; next slot |
the validator stop accepting bids ... |
-38003 | validator paused; retry later |
the validator is working on too many bids ... |
-38004 | validator busy/overloaded (admission timed out); retry later |
the validator is not in-turn ... |
-38005 | next slot or try another validator |
too many bids: exceeded limit of N bids per builder per block |
(no dedicated code; plain JSON-RPC error) | per-builder quota hit (mev_params.MaxBidsPerBuilder); retry next slot or fall back to mev_sendBid |
错误码定义与文档一一对应:
const (
InvalidBidParamError = -38001
InvalidPayBidTxError = -38002
MevNotRunningError = -38003
MevBusyError = -38004
MevNotInTurnError = -38005
BidBlockPermissionRevokedError = -38006
BidBlockPreSealVerifyError = -38007
BidBlockTooLateError = -38008
)
其中预定义错误文本(core/types/builder/bid_error.go)与文档表格中的 message 完全对应,例如 ErrMevNotRunning = "the validator stop accepting bids for now, try again later"、ErrMevNotInTurn = "the validator is not in-turn to propose currently, try again later"。
验证者侧 SendBidBlock 的调用顺序(miner/miner_mev.go)也印证了错误映射的语义:
- 若
BidBlockEnabled未开启 → 返回-38001(BidBlock disabled, fallback to SendBid); - 检查权限(在 CheckPending 之前,避免被拒绝的 BidBlock 占用配额)→ 返回
-38006; - 空交易列表检查 →
-38001; - 时间检查 → 返回
-38008(too late, expected before ...); - 解码与
preSealVerifyBidBlock→ 失败返回-38007(pre-seal verify failed: ...)。
推荐实践
- 每 5–10 秒轮询一次
mev_getBidBlockPermission,并缓存该验证者当前对该构建者的 BidBlock 权限。 - 对每个验证者周期性查询
mev_params,检查该验证者是否开启 BidBlock(BidBlockEnabled字段)。当其为 false 时,按"权限被拒"处理并回退到传统mev_sendBid。
MevParams 结构(core/types/builder/bid.go)包含 BidBlockEnabled、MaxBidsPerBuilder、GasPrice(最小平均 gas 价格)、ValidatorCommission 等字段,其中 MaxBidsPerBuilder 即上文配额上限、GasPrice 即 gasprice_too_low 判定所用的最小值。验证者 miner 侧通过 miner.bidBlockEnabled()(miner/miner_mev.go)汇总 MEV 开关与 BidBlockEnabled 配置后填充该字段。
BidBlock 发送窗口
BidBlock 路径跳过了验证者侧模拟,因此接收截止时间更晚:
BidMustBefore = parent.MilliTimestamp + BlockInterval - DelayLeftOver // 15ms
截止时间的计算实现于 common/bidutil/bidutil.go:
// BidMustBefore returns the time when the next bid must be received,
// only considering the consensus delay but not bid simulation duration.
func BidMustBefore(parentHeader *types.Header, blockPeriod uint64, delayLeftOver time.Duration) time.Time {
nextHeaderTime := time.UnixMilli(int64(parentHeader.MilliTimestamp() + blockPeriod))
nextHeaderTime = nextHeaderTime.Add(-delayLeftOver)
return nextHeaderTime
}
由于验证者在 seal 前仍需微秒级时间完成签名恢复、交易解码、预密封校验与 Extra 覆盖,恰好卡在 BidMustBefore 到达的 BidBlock 仍可能错过密封。文档建议构建者在 BidMustBefore 前预留约 100µs–1ms 的缓冲。
此外,链上传输延迟不是常量:BidBlock 中交易数量与 blob 数量都会增大 payload 体积,从而延长到达验证者的时间。更大的 BidBlock 到得更晚,因此发送窗口控制逻辑必须把传输成本纳入考虑(例如根据当前 tx/blob 数量估算线上延迟并相应提前发送时间),而不能假设相对 BidMustBefore 的固定偏移。
作为对照,传统 bid 路径因为需要预留验证者侧模拟时间,其截止时间更早——BidBetterBefore(common/bidutil/bidutil.go)在 BidMustBefore 基础上再减去 simulationLeftOver,即 BidBetterBefore 严格早于 BidMustBefore。这正是文档"BidBlock 的发送窗口比传统 mev_sendBid 更晚"这一结论的底层原因。
Summary:构建者侧实现要点
- GasFee 无需显式提供:验证者从尾随 deposit 系统交易推导。
- 验证者覆盖
Extra并在绑定签名系统交易后重算TxHash:其余头部字段按构建者提供原样使用(EVM BlockContext 相关字段如GasLimit、Coinbase、Time、Difficulty、BaseFee一旦被构建者预执行后不可再改动,否则重执行 stateRoot 会分叉导致InsertChain失败,这一点在 miner/bid_block.go 的注释中有明确警告)。 - BidBlock 发送窗口晚于传统
mev_sendBid:因为无需验证者侧模拟(见上文"BidBlock 发送窗口")。 - BidBlock 与传统 bid 共享同一每区块配额:通过
mev_params.MaxBidsPerBuilder暴露。 - 权限必须持续轮询(推荐每 5–10 秒一次);当
mev_sendBidBlock返回 "permission revoked" 时缓存也会被失效。当mev_params.BidBlockEnabled == false时按权限被拒处理。 - 构建者必须处理 BidBlock 失败路径:(1)
mev_sendBidBlock可能直接返回错误;(2) 权限可能被撤销,原因由mev_getBidBlockPermission暴露;(3) 验证者管理员或本地策略变更可能随后恢复或再次撤销权限。权限撤销的触发点在 miner/bid_block.go 的handleBidBlockResult:区块广播后立即执行InsertChain做最终验证,Root/ReceiptHash/Bloom/GasUsed等任何不匹配都视为构建者不诚实行为,触发默认 24 小时撤销窗口;导入成功后若排除系统交易的平均 gas 价格低于配置下限,则触发 450 秒的gasprice_too_low撤销。 - 尽量在接近
BidMustBefore时发送(保留前述约 100µs 缓冲)——发送越晚,留给交易选择与执行的时间越多,能打包进区块的价值就越高。