[SPEC-01] Champion the Gloas Builder-selection event decision in Beacon APIs

[krisoshea-eth]

Why

API-02 proves that standard block plus getBlockV2 is sufficient for correctness. An enriched event could avoid a block fetch for unrelated post-Gloas imports and improve interoperability. Beacon APIs #599 owns that independent wire-contract decision.

Planning

• Lane: BN/API
• Status: In Progress
• Owner: Kris
• Reviewer: Nico plus cross-client representatives
• Parent: BN-01
• Coordination: Marco's Lodestar PoCs provide implementation evidence
• Artifact boundary: beacon-APIs #638 is separate payload-attributes work and does not settle this issue

Current live candidates

1. Extend block with builder_index and block_hash, based on Lodestar #9854.
2. Add a lightweight external-Builder-only event carrying enough identity to locate retained payload material, likely slot, block_root, block_hash, and builder_index, with bid_root still an open alternative.

The full-SignedExecutionPayloadBid variants #9875 and #9876, plus block_v2 #9896, remain comparison evidence but currently lack a demonstrated consumer advantage.

Nico's implementation review of ChainSafe#9854 described fork-conditional mutation of the existing block event as implicit and error-prone, and raised whether block_gossip would also require the same fields. Therefore neither live candidate is presumed preferred until the Lodestar and cross-client discussion resolves the contract.

Open contract questions

• Choose additive block fields or a dedicated event.
• Decide whether a lightweight event needs execution_optimistic.
• Confirm imported non-head block semantics.
• Decide whether a bid root is useful or redundant when the Builder retains payloads by execution block hash.
• If block is extended, decide whether fields are required for self-builds with BUILDER_INDEX_SELF_BUILD or omitted as an external-Builder signal.
• If a dedicated event is chosen, settle its name and external-Builder-only behavior.
• Confirm rollout fallback and cross-client review venue.

Invariants

• Keep block plus getBlockV2 as the compatibility and complete-verification fallback.
• Do not make the event responsible for payload construction, reveal policy, replay, SSE IDs, or reconnect recovery.
• Preserve imported-block semantics unless the specification explicitly chooses another trigger.
• Do not confuse payload-attributes beacon-APIs #638 with selection notification beacon-APIs #599.

Tasks

• Maintain a working comparison in the Builder docs repository.
• Collect API-02 evidence, Marco's four PoCs, and Nico's direct-Engine consumer evidence.
• Audit current Beacon APIs and client implementation seams.
• Narrow the live comparison after NC's lightweight-event feedback.
• Obtain Lodestar-team direction on the remaining contract questions.
• Recheck Beacon APIs master and overlapping PRs immediately before drafting.
• Draft the chosen narrow apis/eventstream/index.yaml and CHANGES.md change.
• Link beacon-APIs #599, API-02, the working document, and implementation PoCs.
• Run redocly lint beacon-node-oapi.yaml.
• Gather and resolve cross-client feedback.

Done when

A Beacon APIs PR completes cross-client review and either merges with documented implementation support or reaches a recorded upstream decision with follow-up ownership.

Evidence

• Working document: Builder docs
• Upstream issue: ethereum/beacon-APIs #599
• Compatibility fallback: Lodestar #9931
• PoCs: #9854, #9875, #9876, #9896, and nflaig/lodestar #4
• Beacon APIs PR:
• Cross-client feedback:
• Reviewer:

[linear-code]

LOD-48