ChainSafe / ChainSafe/lodestar

Adopt head_v2 event semantics across head-event consumers

Open
#9,659 1 comment 0 reactions 0 assignees View on GitHub
spec-gloas
Dominant language
TypeScript
Stars
1.4k
Forks
483
Avg merge
1d 16h
Merged PRs (30d)
150

Description

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 #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 #9486 discussion with @nflaig).

Origin/dependency:
- Originating review discussion: https://github.com/ChainSafe/lodestar/pull/9486#discussion_r3582898083
- Depends on / follows from PR #9486: https://github.com/ChainSafe/lodestar/pull/9486

Contributor guide

Open the contributing guide

Research direction

Start with PR #9486 and its review discussion, then audit the validator-side and beacon-node-side consumers and producers of the legacy head event shape. Trace current revalidation behavior and existing client subscriptions before deciding the v1/v2 compatibility approach. Done means consistent internal semantics, preserved external compatibility, updated v1/v2 and revalidation tests, and a validator subscription path that can move to head_v2.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
backend-api-design, blockchain
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.