Update `head` event in backwards compatible way

[michaelsproul]

Since the dependent root changes in Fulu, the head event's dependent roots are misleadingly named.

The current pre-Fulu definitions are:

• previous_duty_dependent_root = get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch - 1) - 1)
• current_duty_dependent_root = get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch) - 1)

These are the correct proposer dependent roots prior to Fulu, i.e. the dependent root for epoch N, is the last block of epoch N - 1.

With Fulu, these dependent roots are completely wrong. The proposer dependent root for epoch N is now the block at the end of epoch N - 2. The spec's extant dependent roots are also unrelated to the attestation dependent roots, which follow the same cadence as the new proposer dependent roots (i.e. epoch N is determined at the end of N - 2).

The correct post-Fulu definitions are:

• previous_epoch_dependent_root = get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch - 2) - 1)
• current_epoch_dependent_root = get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch - 1) - 1)
• next_epoch_dependent_root = get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch) - 1)

Note that we can now offer lookahead for the next epoch for both proposer and attester duties.

Proposed Fixes

There are several ways to fix this without breaking the current events endpoint.

Option 1: New /eth/v2/events endpoint

Perhaps the most drastic: we add a new /eth/v2/events endpoint with a new head event that is versioned (similar to #587), and we take the opportunity to internally version all other events for future proofing. If we introduce this endpoint before Gloas, we can remove /eth/v1/events at the Heze fork boundary.

Option 2: New event type under v1

If we don't want to add a whole new /eth/v2/events endpoint, we could add a new event type under the existing event stream, with the Fulu changes, and a future-proof versioned structure. There are several things we could name this new event without conflict with existing events. Some ideas:

• new_head: a double meaning on "new" – new in the sense of being newly made head, and new in the sense of replacing the old head event
• head_updated: kind of fine
• head_block
• head_v2: ugly IMO
• etc

Option 3: New fields on existing head event

Probably the least elegant option would be to add new fields on the existing head event, and hope that they are simply not parsed by legacy implementations. The new fields could be named according to the corrected definitions above: previous_epoch_dependent_root, current_epoch_dependent_root, next_epoch_dependent_root.

[michaelsproul]

CC @nflaig @rolfyone @chong-he

[rolfyone]

honestly v2 events would be disruptive but maybe its best...

if we went v1 and wanted new events, could just adopt a new standard and use a . prefix or something, so
head -> .head and replace the ones we need - its potentially a little less disruptive, i could go either way

[michaelsproul]

I think the .head thing would be a bit strange personally, but e.g. new_head would be fine. The question is whether we have plausible new names for any of the other events we might want to update

[chong-he]

I think the .head thing would be a bit strange personally, but e.g. new_head would be fine. The question is whether we have plausible new names for any of the other events we might want to update

There are some new events being added in #588 which seems to be require version too (from the comment). Looking at this together it may make more sense to go with Option 1 to use v2 events?

[rolfyone]

There are some new events being added in #588 which seems to be require version too (from the comment). Looking at this together it may make more sense to go with Option 1 to use v2 events?

yep agree, all new gloas events if we're staying in v1 should still have version - the question still probably remains if its a good time to go clean slate i think...

[nflaig]

I am not in favor of option 1, at least not in gloas, there are enough changes already that api consumers have to worry about. We also had this discussion in electra already (#461, #459) and talking to a lot of consumers back then nobody even had a huge problem with changing the event format across forks (even without the version container) and that's what we did in case of the attestation event.

Regarding option 3., I generally don't mind adding new fields to events, consumers need to be able to handle this but in this case it's confusing as these fields are meant to supersede existing fields, so not in favor.

From option 2., I feel like adding a new_head event would be fine.

#589 (comment) I am not convinced to use {"version": "fork_name", "data": { ... }} everywhere, that is, if they don't emit data based on spec containers, or not fork specific, it feels a bit unnecessary. Although since we change the head event now, we never know. It's just not consistent with format of existing events. When we go with v2 at some point, then yes, maybe it makes sense to wrap all events in the version container.

[michaelsproul]

The advantage of a new event (option 2) over changing the existing one at Gloas is that implementations can add their impl and people can start using it ahead of Gloas. I think maybe option 2 is the consensus?

[chong-he]

We (Lighthouse) will work on a PR to update the head event, going with Option 2

[eth2353]

I personally dislike the new_head event name.

Two reasons:

1. The current events (head, block, attestation ...) also inform about "new" things happening and aren't called new_block / new_attestation
2. This name doesn't help us future-proof changes like this. If we ever need another version of this event, will we call it new_new_head? To me this naming direction without a standard leads to the meme where documents end up being called latest_doc_v23_final_3.docx

I'd much prefer something like head_v2. Is it pretty? Not particularly but I don't view it as ugly either. It perfectly conveys this is a newer version of the head event without the downsides above. And in the future we can apply the same logic to other events if needed.

I don't like going with .head as a new standard either since it is again quite unintuitive and if we continue down this road we'll end up with events called ............head.

[rolfyone]

i do agree new should be banned basically anywhere - v2 maybe, but not new

[michaelsproul]

Ok cool. I am happy with head_v2

[nflaig]

Having a versioning scheme on the events that's more broadly applicable might be useful in the future too, and not in a sense of {"version": "fork_name", "data": { ... }} which maps more to the Eth-consensus-version we have on endpoints but one that maps to /eth/v1/... --> /eth/v2/... and also allows for an easy migration path as we usually have a whole fork where both versions coexist (servers emit both events).

It would also be good if we can deprecate the old head event in that case, there doesn't seem to be a clean syntax to do this for how we currently define events. Maybe just adding it as text is sufficient, eg. Deprecated: use head_v2 instead.

[chong-he]

Thanks for all the inputs, I will update the PR