You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
kona-engine: model EL sync status as an explicit state instead of booleans #24099
Claude: kona-node records EL-sync progress in separate booleans, and not every combination of them is valid. joshklop proposed replacing them with explicit sync states: an EL-sync state machine and a live-sync state machine, composed by the engine actor, which switches between them on forkchoice update replies.
Current state
This is at the tip of the #24004 → #24065 stack. el_applied_last_forkchoice exists only on that stack.
Flag
Where
Set by
Meaning
el_sync_finished
EngineState
record_forkchoice_reply on the first VALID; never cleared
The EL has answered VALID at least once
el_applied_last_forkchoice
EngineState
record_forkchoice_reply: VALID sets it, SYNCING clears it
The EL applied the last forkchoice update
el_sync_complete
EngineActor
mark_el_sync_complete_and_notify_derivation_actor
Derivation has been notified. Lags el_sync_finished while a reset is pending because no finalized head is established yet
need_fcu_call_backup_unsafe_reorg
EngineState
nothing
Unused, also on develop
EngineState is only constructed with Default, and record_forkchoice_reply is the only production code that writes the two EngineState flags. So those flags reach three states:
initial sync: (false, false)
live: (true, true)
resyncing: (true, false), when the EL answered SYNCING after an earlier VALID
(false, true) cannot occur, but the types allow it.
Proposed
Delete need_fcu_call_backup_unsafe_reorg.
Replace el_sync_finished and el_applied_last_forkchoice with an enum: InitialSync, Live, Resyncing. Its transition on a ForkchoiceReply is a pure function. This is a breaking change to kona-engine, because the EngineState fields are public.
Rename el_sync_complete to what it tracks. Alternatively, send the derivation notification on the InitialSync → Live transition, keeping the established-finalized-head check.
Decide whether derivation must observe Resyncing. DerivationState has no transition back to AwaitingELSyncCompletion.
Out of scope here: splitting the engine actor into separate EL-sync and live-sync state machines. Revisit it once steps 1–3 land and ethereum-optimism/protocol-team#631 decides whether kona-node keeps a single sync model.
Testing
An rstest table over every (status, reply) pair, 3 × 2 cases, asserting the next status.
Consolidate-task and delegated-actor tests that set el_applied_last_forkchoice migrate to the enum.
No behavior change: the existing engine and actor suites pass after the migration.
Timing
After the ethereum-optimism/protocol-team#545 stack (#24004 → #24065) lands.
🤖 Claude, for @joshklop:#24006, which fixes #23931, adds EL-sync state that isn't in the table above:
ElSyncProgress in the consolidate task: the last eth_syncing reading, when it last changed, and a stall timer bounded by --l2.el-sync-stall-timeout (default 24 h).
The task queue's parked task: a consolidation that got SYNCING waits as the queue's waiting task, with a retry deadline the engine actor tracks in waiting_retry_at, and DrainScope decides whether it runs.
The new EngineTaskErrorSeverity::Wait, which is what parks it.
Taken together, this is another EL-syncing state, now tracked as a queue slot plus a timer instead of a boolean. When this issue's state machines are designed, they should absorb it, or #24006 should land in a shape that maps onto them. #24006 is being taken out of the delegated stack and will be based directly on develop.
Activity
joshklop commentedon Nov 19, 2026
🤖 Claude, for @joshklop: #24006, which fixes #23931, adds EL-sync state that isn't in the table above:
ElSyncProgressin the consolidate task: the lasteth_syncingreading, when it last changed, and a stall timer bounded by--l2.el-sync-stall-timeout(default 24 h).SYNCINGwaits as the queue'swaitingtask, with a retry deadline the engine actor tracks inwaiting_retry_at, andDrainScopedecides whether it runs.EngineTaskErrorSeverity::Wait, which is what parks it.Taken together, this is another EL-syncing state, now tracked as a queue slot plus a timer instead of a boolean. When this issue's state machines are designed, they should absorb it, or #24006 should land in a shape that maps onto them. #24006 is being taken out of the delegated stack and will be based directly on
develop.