feat: implement `head_v2` event by markolazic01 · Pull Request #9486 · ChainSafe/lodestar

markolazic01 · 2026-06-09T10:23:13Z

Description

Implements server-side emission of the head_v2 event as specified in ethereum/beacon-APIs#590, alongside the existing head event which is kept for backwards compatibility.

Closes #9472

Changes

Add head_v2 to EventType enum and eventTypes map in packages/api
Define HeadV2 SSZ container type and EventData shape
Emit head_v2 from importBlock alongside head
Add toApiPayloadStatus mapper from fork choice PayloadStatus enum to API string values
Add test data for head_v2

TODO

VC-side consumption of head_v2 with fallback to head
Update duty revalidation logic for attester, proposer-v2, and PTC (updated through changes in chainHeadTracker.ts)

gemini-code-assist

Code Review

This pull request introduces support for the head_v2 Server-Sent Events (SSE) event type, defining its schema, serialization logic, and emitting it upon block import. The review feedback highlights three key improvements: handling undefined payload status for pre-Bellatrix blocks in toApiPayloadStatus to prevent serialization errors, using newHead.slot instead of blockSlot to accurately determine the fork name for the event version, and simplifying the event type mapping by utilizing the existing WithVersion helper.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 142d9c5b03

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

…dStatusCache to chain

markolazic01 · 2026-06-11T17:32:32Z

Only tests left to add

markolazic01 · 2026-06-15T21:47:13Z

Now ready for review

markolazic01 · 2026-07-02T21:56:56Z

type check was failing, it should pass now (together with other checks)

nflaig

few comments from a quick pass

nflaig · 2026-07-05T11:57:19Z

+   * Cache of head block payload status at time of head_v2 emission, used to detect
+   * empty -> full transitions and emit a second head_v2 event accordingly.
+   */
+  readonly headV2PayloadStatusCache = new Map<RootHex, {status: PayloadStatus; slot: Slot}>();


not entirely clear to me why we need a cache for this, the second head event can be emitted if your head in fork choice moves from empty to full

well, I added the cache to prevent duplicate emissions between importBlock and importExecutionPayload, but after investigating further I see the importExecutionPayload emission doesn't work correctly since the head is never updated there.
Should I add a head update call after onExecutionPayload, or should both emission types come from importBlock?
Either way the cache can be removed. Let me know what works best.

I think I raised something similar in the PR itself, to me emitting head twice per slot still feels strange but that's what we are supposed to do, I would need to re-read what the decision was on the PR, if it's up to me I would probably get rid of payload_status field or report the payload status of the parent, need to take more time to think about this and re-read what we discussed on the PR

nflaig · 2026-07-05T11:58:15Z

+import {isOptimisticBlock} from "../../util/forkChoice.js";
+import {BeaconChain} from "../chain.js";
+
+export function emitHeadV2(this: BeaconChain, head: ProtoBlock, headChanged: boolean) {


I think reusing the same function in importBlock and importExecutionPayload is a bad abstraction

i will keep this in mind and address it once I handle the emissions properly

nflaig · 2026-07-05T11:59:34Z

+        previousDutyDependentRoot: currentEpochDependentRoot,
+        currentDutyDependentRoot: nextEpochDependentRoot,


maybe we refactor our head event data and add the shim to v1 event, the new semantics of head v2 are much nicer

i'm glad to make that change, but maybe it is best to do it in another PR to keep this one readable.
I did some greps and it looks like change touches a lot of places.

let me know if you agree and I will make an issue for this

feat: add head_v2 event emission

7898bad

gemini-code-assist Bot reviewed Jun 9, 2026

View reviewed changes

Comment thread packages/beacon-node/src/chain/blocks/importBlock.ts Outdated

Comment thread packages/beacon-node/src/chain/blocks/importBlock.ts Outdated

Comment thread packages/api/src/beacon/routes/events.ts Outdated

markolazic01 and others added 7 commits June 10, 2026 13:40

fix: improper input to getForkName

2ad8a52

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

accept undefined payload status

eecf451

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

refactor: simplify head v2 using withVersion()

484d8ce

Merge branch 'unstable' into feat/head-v2

9e76ba8

feat: consume head_v2 event in validator chain header tracker

471f5ef

Merge branch 'unstable' into feat/head-v2

78fbdd8

chore: remove redundant case clauses + add missing semicolon

142d9c5

markolazic01 marked this pull request as ready for review June 10, 2026 19:12

markolazic01 requested a review from a team as a code owner June 10, 2026 19:12

markolazic01 marked this pull request as draft June 10, 2026 22:31

markolazic01 marked this pull request as ready for review June 10, 2026 22:32

chatgpt-codex-connector Bot reviewed Jun 10, 2026

View reviewed changes

Comment thread packages/validator/src/services/chainHeaderTracker.ts Outdated

Comment thread packages/beacon-node/src/chain/blocks/importBlock.ts Outdated

markolazic01 added 6 commits June 11, 2026 10:27

fix: gate head_v2 subscription behind GLOAS_FORK_EPOCH config

445da6b

feat: emit head_v2 inside importExecutionPayload and add headV2Payloa…

9c42ce9

…dStatusCache to chain

chore: add metric

8a35439

fix: add missing condition on head_v2 emission in importExecutionPayload

6ae1fee

feat: drop head event post gloas + improvements

fd0b255

refactor: simplify event topic subscription based on gloas config

bb28875

markolazic01 added 4 commits June 15, 2026 15:10

test: add unit tests

656b16f

refactor: extract emitHeadV2 helper and add unit tests

ea0a5c8

fix: add missing headChanged condition + reorg unit test

314f04a

Merge branch 'unstable' into feat/head-v2

e03ab7f

markolazic01 changed the title ~~feat: implement head_v2 event~~ feat: implement head_v2 event Jun 19, 2026

markolazic01 added 3 commits June 30, 2026 14:52

Merge branch 'unstable' into feat/head-v2

49b6780

fix: resolve type errors in headV2Event test

94890ac

Merge branch 'unstable' into feat/head-v2

e9dae84

nflaig reviewed Jul 5, 2026

View reviewed changes

markolazic01 marked this pull request as draft July 5, 2026 13:40

Merge branch 'unstable' into feat/head-v2

30cfaf3

		previousDutyDependentRoot: currentEpochDependentRoot,
		currentDutyDependentRoot: nextEpochDependentRoot,

Uh oh!

Uh oh!

Conversation

markolazic01 commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

markolazic01 commented Jun 11, 2026

Uh oh!

markolazic01 commented Jun 15, 2026

Uh oh!

markolazic01 commented Jul 2, 2026

Uh oh!

nflaig left a comment

Choose a reason for hiding this comment

Uh oh!

nflaig Jul 5, 2026

Choose a reason for hiding this comment

Uh oh!

markolazic01 Jul 5, 2026

Choose a reason for hiding this comment

Uh oh!

nflaig Jul 5, 2026

Choose a reason for hiding this comment

Uh oh!

nflaig Jul 5, 2026

Choose a reason for hiding this comment

Uh oh!

markolazic01 Jul 5, 2026

Choose a reason for hiding this comment

Uh oh!

nflaig Jul 5, 2026

Choose a reason for hiding this comment

Uh oh!

markolazic01 Jul 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

markolazic01 commented Jun 9, 2026 •

edited

Loading

markolazic01 Jul 5, 2026 •

edited

Loading