Skip to content

kona-engine: model EL sync status as an explicit state instead of booleans #24099

Open

Description

@einar-oplabs

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

  1. Delete need_fcu_call_backup_unsafe_reorg.
  2. 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.
  3. Rename el_sync_complete to what it tracks. Alternatively, send the derivation notification on the InitialSync → Live transition, keeping the established-finalized-head check.
  4. 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.

Activity

  1. self-assigned this
    on Nov 12, 2026
  2. joshklop commented on Nov 19, 2026

    @joshklop
    Contributor

    🤖 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions