[SPEC-01] Champion the Gloas block-event extension in Beacon APIs

[krisoshea-eth]

Why

The API-02 implementation proved that the standard block event plus getBlockV2 is sufficient for correctness, but an external Builder must retrieve every imported post-Gloas block merely to learn whether its bid was selected. Beacon API issue #599 and discussion with Nico established a preferred interoperability improvement: extend the existing block event from Gloas onward with builder_index and block_hash.

This issue champions that change through a working design draft, Lodestar proof-of-concept evidence, a Beacon APIs specification PR, and cross-client review. It does not block or replace the existing API-02 fallback.

Planning

• Lane: BN/API
• Target: Weeks 10-11
• Effort: M, approximately 3-5 ideal engineering days
• Owner: Kris
• Reviewer: Nico plus representatives from other consensus clients
• Parent: BN-01
• Primary upstream issue: ethereum/beacon-APIs#599
• Coordination: Marco's Lodestar PoC supplies implementation evidence
• Current decision: one master issue is sufficient; create sub-issues only if later implementation or cross-client work becomes independently reviewable

Agreed direction

• Extend the existing block event instead of adding a thin bid_included event.
• Keep the pre-Gloas event unchanged.
• From Gloas onward, always include builder_index and block_hash.
• Source both fields from signed_execution_payload_bid.message.
• For self-builds, encode builder_index as BUILDER_INDEX_SELF_BUILD.
• Keep block plus getBlockV2 as the compatibility and complete-verification fallback.
• Do not add block_v2 solely for these two fields.
• A future full-bid event would need the complete versioned SignedExecutionPayloadBid, but that is not the current proposal.

Tasks

• Maintain a clearly labelled working design draft in the Builder docs repository.
• Record the current event contract, intended post-Gloas schema, field sources, self-build behavior, and JSON encodings.
• Document compatibility expectations for pre-Gloas producers and consumers that receive additional JSON fields.
• Collect Marco's Lodestar PoC issue, branch or PR, implementation notes, event samples, and tests.
• Confirm external-Builder, self-build, pre-Gloas, and imported non-head block behavior from the PoC.
• Audit Beacon APIs master and open PRs for overlapping event changes and record the exact base revision.
• Audit the current Lodestar, Lighthouse, Nimbus, Prysm, Teku, and Grandine event construction seams.
• Repeat the Beacon APIs master and open-PR audit immediately before opening the upstream draft.
• Draft the narrow Beacon APIs change in apis/eventstream/index.yaml and CHANGES.md.
• Link the specification PR to #599, API-02 evidence, the working draft, and the Lodestar PoC.
• Run redocly lint beacon-node-oapi.yaml.
• Ask Nico where to circulate the proposal and request feedback from Lighthouse, Lodestar, Nimbus, Prysm, Teku, and any additional active client teams.
• Track client feedback and revise the contract until the interoperability decision is clear.
• Record the final decision and implementation-support status in the Builder docs and project board.

Cross-client questions

• Can each client source both fields at the existing post-import block emission point?
• Do existing event serializers and consumers tolerate additional JSON fields?
• Do clients agree that the fields are required post-Gloas and absent pre-Gloas?
• Do clients agree on the self-build sentinel and quoted-decimal JSON encoding?
• Do the field names and meanings match existing Gloas and execution_payload event conventions?
• Are there spec-test or client-test limitations caused by the event stream's example-based schema?

Done when

A Beacon APIs PR linked to #599 has completed cross-client review and either:

1. merges with documented Lodestar implementation evidence and client support, or
2. reaches a recorded upstream decision with the chosen alternative and follow-up ownership.

API-02 remains valid throughout because block plus getBlockV2 is the bounded fallback.

Evidence

• Working draft: docs: draft Gloas block event extension lodestar-eip-7732-builder-docs#14
• Beacon APIs issue: ethereum/beacon-APIs#599
• Beacon APIs PR:
• Lodestar PoC:
• API-02 implementation: feat(builder): observe beacon node blocks #48
• Cross-client feedback:
• Reviewer:

[linear-code]

LOD-48