Skip to content

Adopt head_v2 event semantics across head-event consumers #9659

Description

@lodekeeper

PR #9486 introduces the head_v2 event and keeps the existing head event for compatibility. During review, Nico suggested that the new head_v2 semantics are nicer and may be worth adopting more broadly instead of continuing to pass around older head event data shapes.

This issue tracks the follow-up refactor outside of #9486's implementation scope.

Tasks:

  • Audit current consumers/producers of the existing head event data shape.
  • Decide whether Lodestar should replace internal head event usage with head_v2 semantics, or keep head_v2 as the canonical internal shape and add a compatibility shim for the legacy v1 head event.
  • Update validator-side and beacon-node-side callers consistently once feat: implement head_v2 event #9486 lands.
  • Preserve backwards compatibility for external consumers of the existing head event.
  • Add/adjust tests around v1/v2 event payload compatibility and revalidation behavior.
  • Re-subscribe the validator client from head to head_v2 once head_v2 is broadly supported across clients. Tagged for gloas for now; revisit as head_v2 adoption progresses across clients toward mainnet, and consider enabling after the gloas fork (per feat: implement head_v2 event #9486 discussion with @nflaig).

Origin/dependency:

Activity

  1. added
    spec-gloasIssues targeting the Glamsterdam spec version
    on Jul 27, 2026
  2. lodekeeper commented on Jul 27, 2026

    @lodekeeper
    ContributorAuthor

    Follow-up item to track here, from the #9486 review:

    Re-subscribe the validator client to the head_v2 event once cross-client adoption is broad enough.

    #9486 reverted the VC changes — the validator client stays on the v1 head event rather than subscribing to head_v2. Rationale (per @nflaig's review): using head_v2 early is a risk without benefit for the VC — it only needs the head root/slot and duty dependent roots, and payload availability is already delivered via execution_payload_available — and cross-client head_v2 support isn't guaranteed yet, so the v1 head event should stay supported by clients at least until after the heze fork.

    So this is gated on cross-client head_v2 adoption: revisit re-subscribing the VC to head_v2 as adoption progresses toward mainnet, and consider switching after the gloas fork once support is broad.

  3. added this to the Glamsterdam milestone on Aug 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    spec-gloasIssues targeting the Glamsterdam spec version

    Type

    No type

    Fields

    Priority

    None yet

    Projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions