Add `head_v2` event and deprecate `head` event by chong-he · Pull Request #590 · ethereum/beacon-APIs

chong-he · 2026-03-19T00:07:29Z

This PR adds a head_v2 event to the event stream as per discussion in #589

chong-he

Added some questions that I have

chong-he · 2026-03-20T08:57:31Z

+
+    After Fulu:
+
+     - event.previous_epoch_dependent_root when `compute_epoch_at_slot(event.slot) == epoch`


I use the term previous_epoch_dependent_root here (instead of previous_duty_dependent_root) as I thought after Fulu it is "epoch", not "duty". Is this right? If so, maybe I can also update this part in proposer.v2.yaml:

beacon-APIs/apis/validator/duties/proposer.v2.yaml

Line 26 in b4abce4

- event.previous_duty_dependent_root when `compute_epoch_at_slot(event.slot) == epoch`

Edit: Should it actually be current_epoch_dependent_root instead of previous_epoch_dependent_root for post-Fulu case?

After discussed with @michaelsproul , we revise this part to make it clearer:

Remove before Fulu / after Fulu as now the chain is at Fulu

rename to use current_epoch... instead of current_duty...

remove event.block otherwise bullet point as it serves no purpose (and could be confusing)

changes made to: attester.yaml, proposer.v2.yaml and ptc.yaml

Co-authored-by: Nico Flaig <nflaig@protonmail.com>

michaelsproul · 2026-04-02T04:08:45Z

+              description: The node has finished processing, resulting in a new head. previous_epoch_dependent_root is `get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch - 2) - 1)`, current_epoch_dependent_root is `get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch - 1) - 1)` and next_epoch_dependent_root is `get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch) - 1)`. All dependent roots use the genesis block root in the case of underflow.
+              value: |
+                event: head_v2
+                data: {"version": "gloas", "data":{"slot":"10", "block":"0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf", "state":"0x600e852a08c1200654ddf11025f1ceacb3c2e74bdd5c630cde0838b2591b69f9", "epoch_transition":false, "previous_epoch_dependent_root":"0x5e0043f107cb57913498fbf2f99ff55e730bf1e151f02f221e977c91a90a0e91", "current_epoch_dependent_root":"0x5e0043f107cb57913498fbf2f99ff55e730bf1e151f02f221e977c91a90a0e91", "next_epoch_dependent_root":"0x5e0043f107cb57913498fbf2f99ff55e730bf1e151f02f221e977c91a90a0e91", "execution_optimistic": false}}


Just thought of another field we might want to add to this event, possibly only after Gloas: the head's payload status.

With Gloas fork choice it's likely we'll get two head events every slot:

block_root: X, payload_status: pending

block_root: X, payload_status: full

If we do have versioning on head_v2, we could add the payload_status attribute just for Gloas. Or otherwise we could just default them to pending prior to Gloas (although there are arguments for pending, empty or full for pre-Gloas blocks 😅 ).

need to think more about it, but head seems unrelated to payload, what's the purpose or use case you had in mind?

regarding pending, I don't think we "leak" that anywhere currently outside of fork choice, so not sure that should be used anywhere else

if we would emit the event twice per slot, I would rather just do full / empty (if not received by ptc deadline), (I guess you would need pending for first time the event is emitted)

but maybe it should rather have payload_status as in status of the previous payload, maybe previous_payload_status

(although there are arguments for pending, empty or full for pre-Gloas blocks 😅 ).

I haven't seen a pending or empty block since the merge happened, using anything other than full for pre-gloas seems confusing to me, at least in lodestar we use full but it's a fork choice implementation detail anyways

need to think more about it, but head seems unrelated to payload, what's the purpose or use case you had in mind?

I don't think it's unrelated any more, the output of fork choice get_head now includes a payload status. I can imagine that some EL tools could be interested in knowing when certain payloads become enshrined as head. They can use the new *payload events, but I think they'll also want to know that the payload became canonical (not just that it exists).

I haven't seen a pending or empty block since the merge happened, using anything other than full for pre-gloas seems confusing to me, at least in lodestar we use full but it's a fork choice implementation detail anyways

In Lighthouse we treat pre-Gloas blocks as pending in some places (no payload applied), and empty (no payload applied) 😁 But yeah I agree it's an impl detail, conceptually full (or no status) makes the most sense.

IMO pending inevitably leaks into the state-based APIs, which have to now make the differentiation between block-states (pending) and payload-states (full).

this kinda ties into discussion here #572 which doesn't seem fully resolved, I would trust @twoeths opinion on this which from his last comment seems like we wanna be more explicit about payload status after gloas

so we probably wanna align what state_id=head returns from the state-based apis, and how the head event is emitted

in that case it might make sense to emit two head events per slot

I updated the description to have the possibility of having two head events per slot after Gloas, given the payload_status could be received after.

From my understanding, it will be something like:

First head emitted event:

data: {"version": "gloas", "data":{"slot":"10", "block":"x", "state":"y", payload_status: empty, "epoch_transition": ...}}

Second head emitted event for the same slot with full payload which changes the state:

data: {"version": "gloas", "data":{"slot":"10", "block":"x", "state":"z", payload_status: full, "epoch_transition": ...}}

If we do have the payload_status in the head_v2 event, then I think we keep the version field.

First head emitted event:

what about payload_status: pending?

Second head emitted event for the same slot with full payload which changes the state:

so we would not emit this if there was no payload for the slot? or would you just emit empty after some time in the slot, ie. if not observed after ptc deadline or maybe just if ptc voted for not available?

Actually I am confused and not sure. Should the first emitted event (after receiving the beacon/consensus part of the block), should the payload_status be pending? This is from here: https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/fork-choice.md#modified-get_head

And if it starts with pending for the first head event, then we update to either empty or full in the second emission?

I am now anti-pending, the output of get_head is always empty or full, because pending nodes always have at least one child (their empty node), so can never be returned by get_head.

rolfyone · 2026-04-15T22:57:37Z

happy to run with this if everyone else is now? @nflaig @michaelsproul ?

…into event-head

michaelsproul · 2026-05-26T00:41:20Z

Yep. LGTM.

Co-authored-by: Michael Sproul <michaelsproul@users.noreply.github.com>

rolfyone

LGTM

Co-authored-by: Nico Flaig <nflaig@protonmail.com>

nflaig

LGTM

**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 OffchainLabs#16922 **Other notes for review** ### Kurtosis config ```yaml 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: ```bash $ 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** - [x] I have read [CONTRIBUTING.md](https://github.com/prysmaticlabs/prysm/blob/develop/CONTRIBUTING.md). - [x] I have included a uniquely named [changelog fragment file](https://github.com/prysmaticlabs/prysm/blob/develop/CONTRIBUTING.md#maintaining-changelogmd). - [x] I have added a description with sufficient context for reviewers to understand this PR. - [x] I have tested that my changes work as expected and I added a testing plan to the PR description (if applicable). --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

chong-he added 2 commits March 18, 2026 12:32

new_head event

a4f263b

update pr number

8b3a640

rolfyone reviewed Mar 19, 2026

View reviewed changes

Comment thread apis/eventstream/index.yaml Outdated

rolfyone added the Gloas api's needed in Gloas fork. label Mar 19, 2026

michaelsproul approved these changes Mar 19, 2026

View reviewed changes

nflaig reviewed Mar 19, 2026

View reviewed changes

Comment thread apis/eventstream/index.yaml Outdated

chong-he added 3 commits March 20, 2026 11:35

update to head_v2

fde1cb3

update attester.yaml

cddd3fa

change duty to epoch

0c484bd

chong-he changed the title ~~Add new_head event~~ Add head_v2 event and deprecate head event Mar 20, 2026

chong-he commented Mar 20, 2026

View reviewed changes

update changes.md

cbdbe5f

nflaig reviewed Mar 20, 2026

View reviewed changes

Comment thread apis/eventstream/index.yaml Outdated

Comment thread apis/eventstream/index.yaml Outdated

chong-he and others added 2 commits March 20, 2026 19:21

Update apis/eventstream/index.yaml

55a073f

Co-authored-by: Nico Flaig <nflaig@protonmail.com>

move up

61ffaec

michaelsproul reviewed Mar 26, 2026

View reviewed changes

Comment thread apis/eventstream/index.yaml Outdated

chong-he and others added 3 commits March 26, 2026 15:43

revise attester and proposer.v2

81bb82d

revise ptc dependent root

c776a6c

Merge branch 'master' into event-head

1879edd

michaelsproul reviewed Apr 2, 2026

View reviewed changes

Add slot definition

cdebb44

michaelsproul mentioned this pull request Apr 12, 2026

Gloas: on_block is ill-defined at fork boundary ethereum/consensus-specs#5096

Open

chong-he added 2 commits April 15, 2026 10:27

update head event

4048c90

revise

0268d02

chong-he added 2 commits April 16, 2026 08:39

typo

d81c30a

delete release file

cfd78f9

nflaig reviewed Apr 28, 2026

View reviewed changes

Comment thread apis/eventstream/index.yaml Outdated

Merge remote-tracking branch 'upstream/master' into event-head

5c3241e

brech1 mentioned this pull request Apr 29, 2026

Guard get_parent_payload_status at fork boundary ethereum/consensus-specs#5125

Open

chong-he and others added 4 commits May 8, 2026 20:41

remove previous_epoch_dependent_root

aa984ea

Merge branch 'master' into event-head

9cb2419

Merge remote-tracking branch 'upstream/master' into event-head

4719332

Merge branch 'event-head' of https://github.com/chong-he/beacon-APIs …

cdf6084

…into event-head

michaelsproul mentioned this pull request May 22, 2026

the Head SSE event does not seem tro track payloads #609

Closed

michaelsproul reviewed May 26, 2026

View reviewed changes

Comment thread apis/eventstream/index.yaml Outdated

Update apis/eventstream/index.yaml

f460fbc

Co-authored-by: Michael Sproul <michaelsproul@users.noreply.github.com>

rolfyone previously approved these changes May 26, 2026

View reviewed changes

nflaig reviewed May 26, 2026

View reviewed changes

Comment thread apis/validator/duties/attester.yaml

nflaig reviewed May 27, 2026

View reviewed changes

Comment thread apis/eventstream/index.yaml Outdated

Comment thread apis/eventstream/index.yaml Outdated

Update apis/eventstream/index.yaml

0a32d28

Co-authored-by: Nico Flaig <nflaig@protonmail.com>

chong-he dismissed rolfyone’s stale review via 0a32d28 May 28, 2026 03:43

add epoch definition

ccb3f0b

nflaig approved these changes May 28, 2026

View reviewed changes

nflaig merged commit ed6b9ab into ethereum:master May 28, 2026
3 checks passed

nflaig mentioned this pull request May 28, 2026

Update head event in backwards compatible way #589

Closed

chong-he mentioned this pull request May 28, 2026

Tracking issue for Beacon-APIs sigp/lighthouse#9045

Open

20 tasks

markolazic01 mentioned this pull request Jun 6, 2026

Implement head_v2 event ChainSafe/lodestar#9472

Open

This was referenced Jun 8, 2026

Implement head_v2 event OffchainLabs/prysm#16922

Closed

Make validator client observe head_v2 event OffchainLabs/prysm#16931

Closed

Add head_v2 event OffchainLabs/prysm#16930

Merged

markolazic01 mentioned this pull request Jun 9, 2026

feat: implement head_v2 event ChainSafe/lodestar#9486

Draft

2 tasks

rolfyone added a commit to Consensys/teku that referenced this pull request Jun 23, 2026

Implemented the head_v2 event from ethereum/beacon-APIs#590. (#10776)

df3159e


		After Fulu:

		- event.previous_epoch_dependent_root when `compute_epoch_at_slot(event.slot) == epoch`

Uh oh!

Conversation

chong-he commented Mar 19, 2026 • edited by nflaig Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chong-he left a comment

Choose a reason for hiding this comment

Uh oh!

chong-he Mar 20, 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!

chong-he Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

michaelsproul Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

nflaig Apr 2, 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!

michaelsproul Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

michaelsproul Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

nflaig Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

chong-he Apr 15, 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!

nflaig May 11, 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!

chong-he May 11, 2026

Choose a reason for hiding this comment

Uh oh!

michaelsproul May 14, 2026

Choose a reason for hiding this comment

Uh oh!

rolfyone commented Apr 15, 2026

Uh oh!

Uh oh!

michaelsproul commented May 26, 2026

Uh oh!

Uh oh!

rolfyone left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nflaig left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

chong-he commented Mar 19, 2026 •

edited by nflaig

Loading

chong-he Mar 20, 2026 •

edited

Loading

nflaig Apr 2, 2026 •

edited

Loading

chong-he Apr 15, 2026 •

edited

Loading

nflaig May 11, 2026 •

edited

Loading