Skip to content

Add head_v2 event and deprecate head event #590

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
chong-he wants to merge 17 commits into
base: master
Choose a base branch
from
Open

Add head_v2 event and deprecate head event #590

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
a4f263b
new_head event
chong-he Mar 18, 2026
8b3a640
update pr number
chong-he Mar 19, 2026
fde1cb3
update to head_v2
chong-he Mar 20, 2026
cddd3fa
update attester.yaml
chong-he Mar 20, 2026
0c484bd
change duty to epoch
chong-he Mar 20, 2026
cbdbe5f
update changes.md
chong-he Mar 20, 2026
55a073f
Update apis/eventstream/index.yaml
chong-he Mar 20, 2026
61ffaec
move up
chong-he Mar 20, 2026
81bb82d
revise attester and proposer.v2
chong-he Mar 26, 2026
c776a6c
revise ptc dependent root
chong-he Mar 26, 2026
1879edd
Merge branch 'master' into event-head
chong-he Mar 26, 2026
cdebb44
Add slot definition
chong-he Apr 2, 2026
4048c90
update head event
chong-he Apr 15, 2026
0268d02
revise
chong-he Apr 15, 2026
d81c30a
typo
chong-he Apr 16, 2026
cfd78f9
delete release file
chong-he Apr 21, 2026
5c3241e
Merge remote-tracking branch 'upstream/master' into event-head
chong-he Apr 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ There are likely to be descriptions etc outside of the list below, but new query
| [#568](https://github.com/ethereum/beacon-APIs/pull/568) `GET /eth/v1/node/version` deprecated | | | | | |
| [#588](https://github.com/ethereum/beacon-APIs/pull/588) `execution_payload EVENT` added | | | | | |
| [#588](https://github.com/ethereum/beacon-APIs/pull/588) `execution_payload_gossip EVENT` added | | | | | |
| [#590](https://github.com/ethereum/beacon-APIs/pull/590) `head_v2 EVENT` added | | | | | |
| [#590](https://github.com/ethereum/beacon-APIs/pull/590) `head EVENT` deprecated | | | | | |

The Following are no longer in the Standard API, removed since the latest version.

Expand Down
8 changes: 7 additions & 1 deletion apis/eventstream/index.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ get:
type: string
enum:
- head
- head_v2
- block
- block_gossip
- attestation
Expand Down Expand Up @@ -53,10 +54,15 @@ get:
description: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format
examples:
head:
description: The node has finished processing, resulting in a new head. previous_duty_dependent_root is `get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch - 1) - 1)` and current_duty_dependent_root is `get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch) - 1)`. Both dependent roots use the genesis block root in the case of underflow.
description: Deprecated, use `head_v2` instead.
value: |
event: head
data: {"slot":"10", "block":"0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf", "state":"0x600e852a08c1200654ddf11025f1ceacb3c2e74bdd5c630cde0838b2591b69f9", "epoch_transition":false, "previous_duty_dependent_root":"0x5e0043f107cb57913498fbf2f99ff55e730bf1e151f02f221e977c91a90a0e91", "current_duty_dependent_root":"0x5e0043f107cb57913498fbf2f99ff55e730bf1e151f02f221e977c91a90a0e91", "execution_optimistic": false}
head_v2:
description: The node has finished processing the beacon block, resulting in a new head with an empty `payload_status`. The node may emit a second head event for the same slot if there is an update in the `payload_status` from empty to full. `slot` is the slot of the head block. 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", "payload_status": "empty", "epoch_transition":false, "previous_epoch_dependent_root":"0x5e0043f107cb57913498fbf2f99ff55e730bf1e151f02f221e977c91a90a0e91", "current_epoch_dependent_root":"0x5e0043f107cb57913498fbf2f99ff55e730bf1e151f02f221e977c91a90a0e91", "next_epoch_dependent_root":"0x5e0043f107cb57913498fbf2f99ff55e730bf1e151f02f221e977c91a90a0e91", "execution_optimistic": false}}
Copy link
Copy Markdown
Member

@nflaig nflaig Apr 28, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

what's the purpose of having the previous_epoch_dependent_root in the head event?

Copy link
Copy Markdown
Author

@chong-he chong-he Apr 29, 2026

Choose a reason for hiding this comment

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

This is the equivalent field to the current head event field previous_duty_dependent_root, so I keep it in the response. Is it not required now?

Copy link
Copy Markdown
Author

@chong-he chong-he Apr 29, 2026

Choose a reason for hiding this comment

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

oh I think I got what you mean. The previous_duty_dependent_root in head is equivalent to the now current_epoch_dependent_root in head_v2, so we don't need to have previous_epoch_dependent_root in the event. Is that what you mean?

block:
description: The node has received a block (from P2P or API) that is successfully imported on the fork-choice `on_block` handler
value: |
Expand Down
8 changes: 3 additions & 5 deletions apis/validator/duties/attester.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,12 @@ post:

Duties should only need to be checked once per epoch,
however a chain reorganization (of > MIN_SEED_LOOKAHEAD epochs) could occur,
resulting in a change of duties. For full safety, you should monitor head events and confirm the
resulting in a change of duties. For full safety, you should monitor head_v2 events and confirm the
dependent root in this response matches:

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

- event.current_duty_dependent_root when `compute_epoch_at_slot(event.slot) + 1 == epoch`

- event.block otherwise
- event.next_epoch_dependent_root when `compute_epoch_at_slot(event.slot) + 1 == epoch`


The dependent_root value is `get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch - 1) - 1)`
Expand Down
24 changes: 5 additions & 19 deletions apis/validator/duties/proposer.v2.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,29 +8,15 @@ get:

Duties should only need to be checked once per epoch,
however a chain reorganization could occur that results in a change of duties. For full safety,
you should monitor head events and confirm the dependent root in this response matches. After Fulu,
different checks need to be performed as the dependent root changes due to deterministic proposer lookahead.
you should monitor head_v2 events and confirm the dependent root in this response matches:

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

Before Fulu:
- event.next_epoch_dependent_root when `compute_epoch_at_slot(event.slot) + 1 == epoch`

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

- event.block otherwise

- dependent_root value is `get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch) - 1)`


After Fulu:

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

- event.block otherwise

- dependent_root value is `get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch - 1) - 1)`


The dependent_root value is the genesis block root in the case of underflow."
The dependent_root value is `get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch - 1) - 1)`
or the genesis block root in the case of underflow."
parameters:
- name: epoch
in: path
Expand Down
8 changes: 3 additions & 5 deletions apis/validator/duties/ptc.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,11 @@ post:

Duties should only need to be checked once per epoch,
however a chain reorganization (of > MIN_SEED_LOOKAHEAD epochs) could occur, resulting in a change of duties. For full safety,
you should monitor head events and confirm the dependent root in this response matches:
you should monitor head_v2 events and confirm the dependent root in this response matches:

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

- event.current_duty_dependent_root when `compute_epoch_at_slot(event.slot) + 1 == epoch`

- event.block otherwise
- event.next_epoch_dependent_root when `compute_epoch_at_slot(event.slot) + 1 == epoch`


The dependent_root value is `get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch - 1) - 1)`
Expand Down