Skip to content

Add head_v2 event - #16930

Merged
syjn99 merged 28 commits into
developfrom
feat/head-v2-event
Jun 11, 2026
Merged

Add head_v2 event#16930
syjn99 merged 28 commits into
developfrom
feat/head-v2-event

Conversation

@syjn99

@syjn99 syjn99 commented Jun 9, 2026

Copy link
Copy Markdown
Member

What type of PR is this?

Feature

What does this PR do? Why is it needed?

Implements a new head_v2 event. Ref: ethereum/beacon-APIs#590

Note that it doesn't deprecate the legacy head event. So it is expected to receive both head and head_v2 events if subscribed for them.

Which issues(s) does this PR fix?

Fixes #16922

Other notes for review

Kurtosis config

participants:
  - el_type: ethrex
    el_image: ethpandaops/ethrex:glamsterdam-devnet-4
    el_extra_params:
      - --http.api=eth,net,web3,admin
    cl_type: prysm
    cl_image: prysm-bn-custom-image:latest
    vc_image: prysm-vc-custom-image:latest
    supernode: true
    count: 3
    cl_extra_params:
      - --subscribe-all-subnets
      - --verbosity=debug
    vc_extra_params:
      - --verbosity=debug
      - --enable-beacon-rest-api

network_params:
  fulu_fork_epoch: 0
  gloas_fork_epoch: 2
  seconds_per_slot: 6
  genesis_delay: 40

additional_services:
  - dora

global_log_level: debug

Result

Command:

$ curl -X 'GET' \
  'http://<BN>/eth/v1/events?topics=head&topics=head_v2' \
  -H 'accept: text/event-stream'

so that we can subscribe both head and head_v2.

Outcome:

event: head
data: {"slot":"5","block":"0xbe03088c8d737d41de220c6758c0dcb920d3df9befdd7e75c6bc156695118611","state":"0x210c280f57344228104b410d1855a9ef720cdd64e242476ed7a304198cb8b76a","epoch_transition":false,"execution_optimistic":false,"previous_duty_dependent_root":"0x7851e4368487090b5a9170ad357563850c5e86a8162de7372bfa4c46133de197","current_duty_dependent_root":"0x7851e4368487090b5a9170ad357563850c5e86a8162de7372bfa4c46133de197"}

event: head_v2
data: {"version":"fulu","data":{"slot":"5","block":"0xbe03088c8d737d41de220c6758c0dcb920d3df9befdd7e75c6bc156695118611","state":"0x210c280f57344228104b410d1855a9ef720cdd64e242476ed7a304198cb8b76a","payload_status":"full","current_epoch_dependent_root":"0x7851e4368487090b5a9170ad357563850c5e86a8162de7372bfa4c46133de197","next_epoch_dependent_root":"0x7851e4368487090b5a9170ad357563850c5e86a8162de7372bfa4c46133de197","epoch_transition":false,"execution_optimistic":false}}

...


event: head
data: {"slot":"83","block":"0xd7507c7df5a5c28813e3c93bbedd4871b378e4f869571bf190f8675fa6293244","state":"0xa10e78912570d65272b3facb9cc9a0d50e209ba73fa3f8f9d9a8961b669fa431","epoch_transition":false,"execution_optimistic":false,"previous_duty_dependent_root":"0x8ab1f18715a944835e8c5a3b966126b31c3b6d282f237f8d20846f4db4cc4c4d","current_duty_dependent_root":"0xa078bc2d1264d2358f611549b6461983ed5c5d1ba58a6c8a6a5e8f6db35cad3b"}

event: head_v2
data: {"version":"gloas","data":{"slot":"83","block":"0xd7507c7df5a5c28813e3c93bbedd4871b378e4f869571bf190f8675fa6293244","state":"0xa10e78912570d65272b3facb9cc9a0d50e209ba73fa3f8f9d9a8961b669fa431","payload_status":"empty","current_epoch_dependent_root":"0x8ab1f18715a944835e8c5a3b966126b31c3b6d282f237f8d20846f4db4cc4c4d","next_epoch_dependent_root":"0xa078bc2d1264d2358f611549b6461983ed5c5d1ba58a6c8a6a5e8f6db35cad3b","epoch_transition":false,"execution_optimistic":false}}

event: head_v2
data: {"version":"gloas","data":{"slot":"83","block":"0xd7507c7df5a5c28813e3c93bbedd4871b378e4f869571bf190f8675fa6293244","state":"0xa10e78912570d65272b3facb9cc9a0d50e209ba73fa3f8f9d9a8961b669fa431","payload_status":"full","current_epoch_dependent_root":"0x8ab1f18715a944835e8c5a3b966126b31c3b6d282f237f8d20846f4db4cc4c4d","next_epoch_dependent_root":"0xa078bc2d1264d2358f611549b6461983ed5c5d1ba58a6c8a6a5e8f6db35cad3b","epoch_transition":false,"execution_optimistic":false}}

Notable points:

  • Data of head_v2 is properly versioned. It will give "fulu" if the current fork is fulu.
  • head_v2 is emitted two times for same block, right after the execution payload is received.
  • current_epoch_dependent_root == previous_duty_dependent_root and next_epoch_dependent_root == current_duty_dependent_root as expected.

Acknowledgements

  • I have read CONTRIBUTING.md.
  • I have included a uniquely named changelog fragment file.
  • I have added a description with sufficient context for reviewers to understand this PR.
  • I have tested that my changes work as expected and I added a testing plan to the PR description (if applicable).

syjn99 and others added 10 commits June 8, 2026 16:51
Add the NewHeadV2 state-feed event type and its HeadV2Data carrier. It
mirrors the legacy head event fields, renames the duty-dependent roots to
current/next_epoch_dependent_root per beacon-APIs#590, and adds the
execution payload status and head fork version needed to render head_v2.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add HeadEventV2 ({version, data} envelope) and HeadEventV2Data for the
head_v2 SSE event. Fields are renamed per beacon-APIs#590
(current/next_epoch_dependent_root) and add payload_status. Fields are
ordered to satisfy the maligned nogo check.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Register the head_v2 topic, route statefeed.NewHeadV2 to it, and serialize
HeadV2Data into the {version, data} HeadEventV2 envelope (version rendered
via runtime/version). The legacy head topic is unchanged. Extend the
stream test to cover head_v2.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@syjn99 syjn99 changed the title [WIP] Add head_v2 event Add head_v2 event Jun 9, 2026
@github-project-automation github-project-automation Bot moved this to Unassigned in Gloas Jun 9, 2026
@syjn99
syjn99 marked this pull request as ready for review June 9, 2026 10:33
Comment thread beacon-chain/blockchain/head.go Outdated
Comment thread beacon-chain/blockchain/receive_execution_payload_envelope.go Outdated
@syjn99
syjn99 requested a review from terencechain June 10, 2026 03:30
Comment thread beacon-chain/blockchain/receive_execution_payload_envelope.go Outdated
Comment thread beacon-chain/blockchain/receive_execution_payload_envelope.go Outdated
@syjn99
syjn99 requested a review from terencechain June 10, 2026 14:07
Comment thread changelog/syjn99_feat-head-v2-event.md
Comment thread beacon-chain/blockchain/head.go
Comment thread beacon-chain/blockchain/head.go Outdated
Comment thread beacon-chain/blockchain/head.go

@terencechain terencechain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lgtm, ill defer @james-prysm to approve since he has more comments

@syjn99
syjn99 requested a review from james-prysm June 11, 2026 04:31
@syjn99
syjn99 enabled auto-merge June 11, 2026 17:35
@syjn99
syjn99 requested a review from terencechain June 11, 2026 17:35
@syjn99
syjn99 added this pull request to the merge queue Jun 11, 2026
Merged via the queue into develop with commit ae84a5f Jun 11, 2026
22 checks passed
@syjn99
syjn99 deleted the feat/head-v2-event branch June 11, 2026 18:40
@github-project-automation github-project-automation Bot moved this from Unassigned to Done in Gloas Jun 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

Implement head_v2 event

3 participants