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
Rename EngineActor (and sibling Engine* actor-naming types) to ChainController and extend it: mediate derivation-bound signals and own reset initiation; read-only query handler (atomic local-safe-at-timestamp + L1-at-safe snapshot, sync status); depth-1 lockstep confirmation to derivation fed from local-safe (on cross-safe it deadlocks — no compile error catches this, name it in review); unsafe-descends-from-local-safe check on payload inserts (the EL's forkchoice-consistency check can't be relied on, optimism-private#577). Wire names (RPC/WS/subscriptions, e.g. dev_subscribe_engine_queue_size) unchanged. Update public docs (engine.mdx).
Opened #22595 for the bulk of this, stacked on #22586. Notes, in case they save someone else the same reasoning.
Two items were already true. "Mediate derivation-bound signals and own reset initiation" and the depth-1 lockstep confirmation fed from local-safe both landed with the earlier slices in this stack (the lagging-cross test asserting the confirmation carries local-safe rather than cross-safe is already there). Nothing to do here beyond writing them down in engine.mdx, which did not describe either.
The descends-from-local-safe check can't live in the controller. The issue puts it on the controller, but the controller only enqueues the insert; the local-safe head can advance between enqueue and execution, so a check against the state at enqueue time does not hold unsafe >= local-safe for the write that follows. It also can't be an ordinary task error: Engine::drain does not pop a task that errors, so any severity other than an explicit drop retries a permanently-wrong payload forever. It ended up as a predicate on InsertTask evaluated against the live state, with the drop at the queue boundary next to the existing drop for an INVALID payload status. Rejected, not clamped — an untrusted gossip payload is neither an advisor's opinion nor an internal write.
Worth noting where this sits relative to #22576: EngineSyncState::apply_update explicitly declines to clamp the unsafe head, on the grounds that no writer produces an unsafe head below cross-safe. That was true only because nothing checked the one writer fed from outside the node. This check is what makes the assumption hold, rather than a second clamp.
The query handler is deferred, and the reason may need a decision. "Atomic local-safe-at-timestamp + L1-at-safe snapshot" is the in-process equivalent of op-supernode's ChainContainer.OptimisticAt, which today is two reads (LocalSafeBlockAtTimestamp then safeDBAtL2) with a TOCTOU gap between them — so serving it from one state snapshot is a real improvement and worth having.
The obstacle is where the L2→L1 pairing is recorded. #22528 describes the write as happening "at local-safe promotion in the ChainController (derived_from supplies the L1 key)", but the controller cannot form that pair reliably: it forwards a ConsolidateInput carrying derived_from, and consolidation may fall back to build-and-seal and land a different block than the attributes named. Pairing "last derived_from forwarded" with "local-safe head after drain" would therefore sometimes answer with an L1 key the head was not derived from — a silent wrong answer in exactly the query interop uses to decide cross-safety, which is worse than not serving it. ConsolidateTask (and InsertTask on its derived path) are the only places that know both values at the moment the head is written, which makes this a kona-engine sync-state change — #22525's vocabulary surface — rather than a controller change.
Correction. The struck mechanism above is wrong, and the InsertTask detail with it. Read against 96fd237d:
Consolidation's build-and-seal fallback does not land a different block.ConsolidateTask::execute_build_and_seal_tasks passes attributes.clone() — the same OpAttributesWithParent, derived_from included — into build_and_seal (crates/node/engine/src/task_queue/tasks/consolidate/task.rs:92), and BuildTask::start_build builds the block those attributes name, handing them straight to the forkchoice update (.../tasks/build/task.rs:85-126). The one path that does land a genuinely different block, SealTask's Holocene deposits-only retry (.../tasks/seal/task.rs:157-178), goes through OpAttributesWithParent::as_deposits_only, which copies the origin verbatim (crates/protocol/protocol/src/attributes.rs:84). No path there yields a wrong L1 key.
InsertTask does not hold both values. It carries only is_payload_local_safe: bool (.../tasks/insert/task.rs:26), used to decide whether to write a local-safe head at all (:156). It never sees an L1 origin.
The conclusion stands, on different grounds. The controller still cannot form the pair:
Queue order is not forwarding order. The engine task queue is a BinaryHeap (.../task_queue/core.rs:49) and EngineTask::Ord returns Ordering::Equal for two Consolidate tasks (.../task_queue/tasks/task.rs:189-232). BinaryHeap is not a stable order, so among equal-priority consolidations the last derived_from forwarded is not guaranteed to be the last one executed.
A drain can end part-way through.Engine::drain peeks, executes, and only then pops (core.rs:238-252), so a task error halts the drain with that task still queued; ChainController::drain classifies the severity afterwards (actors/chain_controller/controller.rs:124-168), and Reset, Flush and Critical all leave the remaining tasks unexecuted. A drain can therefore end with local-safe written by an earlier task while later-forwarded origins were never consumed — pairing would then report an L1 key ahead of the head. ChainController::step drains at the top (controller.rs:236) and enqueues at the bottom (:263-:320, consolidations at :271), so more than one consolidation really can be in flight.
Two writers hold no L1 key at all.ConsolidateTask::reconcile_to_local_safe_head, reached on the derivation-delegation path where the input is a bare L2BlockInfo (consolidate/task.rs:99, :154-156), and Engine::reset / Engine::reset_to (core.rs:121, :175) each write a local-safe head with no origin to pair it with. derived_from is itself Option<BlockInfo> (attributes.rs:16), so even the attributes path can arrive without one. That is an absent pairing rather than a wrong one, and the read path has to represent it rather than serving a stale origin or silence.
So: recorded in kona-engine's sync state at the point where the local-safe head is written, with the absent case representable in the type so a consumer cannot mistake it for a real origin.
So: the write hook belongs in kona-engine, not the ChainController, and once it is there #22527's read query and #22528's SafeDB write are both straightforward consumers of it. That also removes what otherwise looks like a dependency cycle: #22528 depends on #22527 for the write hook, while #22527's L1-at-safe half would depend on #22528's SafeDB for anything historical. Suggest a small slice that adds the pairing to the sync state, sequenced before both.
Two smaller calls I made rather than asked about:
EngineConfig keeps its name — it configures the real Engine API connection (URL, JWT, L1 RPC), not the actor — as do DerivationEngineClient / NetworkEngineClient / SequencerEngineClient, which are named for their consumer rather than for the actor and are not Engine*-prefixed.
The engine tracing target is unchanged. It isn't a wire name, but renaming it would break operator log filters for no gain.
One incidental win: kona-engine has its own EngineClientError for Engine API transport failures, and kona-node-service had a same-named type for request-channel failures. The rename to ChainControllerClientError retires the collision.
Opened #22597 for the read-only query handler this issue asks for and #22595 deferred, stacked on #22596. Notes on what turned out to be true.
The single read was already available; #22596 is what made it mean something.EngineQueries::handle takes exactly one borrow() of the state watch, at the top (crates/node/engine/src/query.rs:77), and EngineState is Copy, so every field of the answer is computed from one value. No new synchronisation was needed. Before #22596 that single borrow would not have helped: the L1 origin was not in the state, so the second half of the answer had to come from somewhere else. The atomicity is the pairing living in the state plus that one borrow, not either alone.
The Go side's gap is structural, and its comments point the other way.ChainContainer.OptimisticAt (op-supernode/supernode/chain_container/chain_container.go:638) calls LocalSafeBlockAtTimestamp (:559) and then safeDBAtL2 (:611), and each of those calls SyncStatus (:584) for itself — so it is not two reads but four, and the L2 block and the L1 key can come from different views of the chain. The comment that names the race is at the call site (op-supernode/supernode/activity/interop/interop.go:1159), and it names OptimisticAt as the fix: "the single atomic source for both L2 block and L1 head". Relative to calling LocalSafeBlockAtTimestamp and OptimisticAt separately it is an improvement, which is presumably what was meant; internally the gap is still there. Nothing in OptimisticAt itself acknowledges it.
A live snapshot answers the timestamp query only for the head, and the answer has to say so. The state holds the L1 origin of exactly one L2 block. So there are four verdicts, not two, and the three that carry no pairing are not interchangeable:
ahead of the local-safe head: not local-safe yet, retry;
the head's own timestamp: the pairing, which may legitimately be Unpaired;
below L2 genesis: no such block, and history will not have one either.
The last one is worth keeping distinct because of how the Go consumer behaves: safeDBAtL2 maps a permanent history gap to ErrHistoryUnavailable, on which interop halts. A consumer that collapsed "out of range" into "history gap" would halt on a request that was simply wrong. Flattening any of these into one absent answer is the same class of mistake as flattening Unpaired into a defaulted BlockInfo.
Timestamps rather than a floored block number. op-node's TargetBlockNumber (op-node/rollup/types.go:237) floors an unaligned timestamp onto the preceding block, so a timestamp one second past the head returns the head. The handler here answers with the head's pairing only for the head's own timestamp, and reports ahead/behind otherwise: it will not attach the head's L1 key to a block that is not the head. Interop's timestamps are block-aligned across the dependency set, so the two agree wherever the answer matters.
While looking for the mapping: RollupConfig::block_number_from_timestamp (crates/protocol/genesis/src/rollup.rs:379) is not the Rust equivalent of TargetBlockNumber. It omits genesis.l2.number and saturates instead of erroring below the genesis time, so it is only correct for a chain whose L2 genesis block number is zero. Its one caller is bin/host/src/interop/handler.rs:233. Not touched here — flagging it because it looks like the helper for this job and is not.
One incidental fix.engine.mdx's InsertTask snippet still showed is_payload_local_safe: bool, which #22596 replaced with the origin; corrected alongside the new query's documentation.
Nothing here needs #22528, and nothing here does any part of it: no rocksdb, no historical lookup, no optimism_safeHeadAtL1Block. No new wire name either — this is an in-process query, and the controller's read side stays read-only.
This is shared-component architecture work for Lokahi, rather than a SafeDB implementation ticket: it refactors the engine actor into a ChainController responsible for derivation coordination, resets, head queries, and safety checks.
The older SafeDB plan in #22528 depended on this issue for a controller write hook. That plan has been superseded by #23473; its write-path sub-issue #23474 explicitly integrates with the current actors without waiting for #22527. This issue is therefore not a prerequisite for the current SafeDB integration. Its in-process head query is also distinct from SafeDB persistence and historical lookups, as the earlier implementation comments explain.
Moving this issue from the SafeDB feature tracker #20278 to #22520, the Lokahi phase-1 shared-component refactor tracker. It retains its prerequisite #22525 and the downstream Lokahi work that depends on it.
Acknowledged, and sorry about that. I assigned you on 2026-10-16 without you committing to this work. You've already unassigned yourself and the issue now has no assignee. I won't reassign it; it can be picked up at the next planning meeting.
Activity
claude commentedon Aug 21, 2026
Opened #22595 for the bulk of this, stacked on #22586. Notes, in case they save someone else the same reasoning.
Two items were already true. "Mediate derivation-bound signals and own reset initiation" and the depth-1 lockstep confirmation fed from local-safe both landed with the earlier slices in this stack (the lagging-cross test asserting the confirmation carries local-safe rather than cross-safe is already there). Nothing to do here beyond writing them down in
engine.mdx, which did not describe either.The descends-from-local-safe check can't live in the controller. The issue puts it on the controller, but the controller only enqueues the insert; the local-safe head can advance between enqueue and execution, so a check against the state at enqueue time does not hold
unsafe >= local-safefor the write that follows. It also can't be an ordinary task error:Engine::draindoes not pop a task that errors, so any severity other than an explicit drop retries a permanently-wrong payload forever. It ended up as a predicate onInsertTaskevaluated against the live state, with the drop at the queue boundary next to the existing drop for anINVALIDpayload status. Rejected, not clamped — an untrusted gossip payload is neither an advisor's opinion nor an internal write.Worth noting where this sits relative to #22576:
EngineSyncState::apply_updateexplicitly declines to clamp the unsafe head, on the grounds that no writer produces an unsafe head below cross-safe. That was true only because nothing checked the one writer fed from outside the node. This check is what makes the assumption hold, rather than a second clamp.The query handler is deferred, and the reason may need a decision. "Atomic local-safe-at-timestamp + L1-at-safe snapshot" is the in-process equivalent of op-supernode's
ChainContainer.OptimisticAt, which today is two reads (LocalSafeBlockAtTimestampthensafeDBAtL2) with a TOCTOU gap between them — so serving it from one state snapshot is a real improvement and worth having.The obstacle is where the L2→L1 pairing is recorded. #22528 describes the write as happening "at local-safe promotion in the ChainController (
derived_fromsupplies the L1 key)", but the controller cannot form that pair reliably:it forwards aConsolidateInputcarryingderived_from, and consolidation may fall back to build-and-seal and land a different block than the attributes named. Pairing "lastderived_fromforwarded" with "local-safe head after drain" would therefore sometimes answer with an L1 key the head was not derived from — a silent wrong answer in exactly the query interop uses to decide cross-safety, which is worse than not serving it.ConsolidateTask(andInsertTaskon its derived path) are the only places that know both values at the moment the head is written, which makes this akona-enginesync-state change — #22525's vocabulary surface — rather than a controller change.So: the write hook belongs in kona-engine, not the ChainController, and once it is there #22527's read query and #22528's SafeDB write are both straightforward consumers of it. That also removes what otherwise looks like a dependency cycle: #22528 depends on #22527 for the write hook, while #22527's L1-at-safe half would depend on #22528's SafeDB for anything historical. Suggest a small slice that adds the pairing to the sync state, sequenced before both.
Two smaller calls I made rather than asked about:
EngineConfigkeeps its name — it configures the real Engine API connection (URL, JWT, L1 RPC), not the actor — as doDerivationEngineClient/NetworkEngineClient/SequencerEngineClient, which are named for their consumer rather than for the actor and are notEngine*-prefixed.enginetracing target is unchanged. It isn't a wire name, but renaming it would break operator log filters for no gain.One incidental win: kona-engine has its own
EngineClientErrorfor Engine API transport failures, and kona-node-service had a same-named type for request-channel failures. The rename toChainControllerClientErrorretires the collision.Generated by Claude Code
claude commentedon Aug 21, 2026
Opened #22597 for the read-only query handler this issue asks for and #22595 deferred, stacked on #22596. Notes on what turned out to be true.
The single read was already available; #22596 is what made it mean something.
EngineQueries::handletakes exactly oneborrow()of the state watch, at the top (crates/node/engine/src/query.rs:77), andEngineStateisCopy, so every field of the answer is computed from one value. No new synchronisation was needed. Before #22596 that single borrow would not have helped: the L1 origin was not in the state, so the second half of the answer had to come from somewhere else. The atomicity is the pairing living in the state plus that one borrow, not either alone.The Go side's gap is structural, and its comments point the other way.
ChainContainer.OptimisticAt(op-supernode/supernode/chain_container/chain_container.go:638) callsLocalSafeBlockAtTimestamp(:559) and thensafeDBAtL2(:611), and each of those callsSyncStatus(:584) for itself — so it is not two reads but four, and the L2 block and the L1 key can come from different views of the chain. The comment that names the race is at the call site (op-supernode/supernode/activity/interop/interop.go:1159), and it namesOptimisticAtas the fix: "the single atomic source for both L2 block and L1 head". Relative to callingLocalSafeBlockAtTimestampandOptimisticAtseparately it is an improvement, which is presumably what was meant; internally the gap is still there. Nothing inOptimisticAtitself acknowledges it.A live snapshot answers the timestamp query only for the head, and the answer has to say so. The state holds the L1 origin of exactly one L2 block. So there are four verdicts, not two, and the three that carry no pairing are not interchangeable:
Unpaired;The last one is worth keeping distinct because of how the Go consumer behaves:
safeDBAtL2maps a permanent history gap toErrHistoryUnavailable, on which interop halts. A consumer that collapsed "out of range" into "history gap" would halt on a request that was simply wrong. Flattening any of these into one absent answer is the same class of mistake as flatteningUnpairedinto a defaultedBlockInfo.Timestamps rather than a floored block number. op-node's
TargetBlockNumber(op-node/rollup/types.go:237) floors an unaligned timestamp onto the preceding block, so a timestamp one second past the head returns the head. The handler here answers with the head's pairing only for the head's own timestamp, and reports ahead/behind otherwise: it will not attach the head's L1 key to a block that is not the head. Interop's timestamps are block-aligned across the dependency set, so the two agree wherever the answer matters.While looking for the mapping:
RollupConfig::block_number_from_timestamp(crates/protocol/genesis/src/rollup.rs:379) is not the Rust equivalent ofTargetBlockNumber. It omitsgenesis.l2.numberand saturates instead of erroring below the genesis time, so it is only correct for a chain whose L2 genesis block number is zero. Its one caller isbin/host/src/interop/handler.rs:233. Not touched here — flagging it because it looks like the helper for this job and is not.One incidental fix.
engine.mdx'sInsertTasksnippet still showedis_payload_local_safe: bool, which #22596 replaced with the origin; corrected alongside the new query's documentation.Nothing here needs #22528, and nothing here does any part of it: no rocksdb, no historical lookup, no
optimism_safeHeadAtL1Block. No new wire name either — this is an in-process query, and the controller's read side stays read-only.Generated by Claude Code
einar-oplabs commentedon Oct 26, 2026
This is shared-component architecture work for Lokahi, rather than a SafeDB implementation ticket: it refactors the engine actor into a ChainController responsible for derivation coordination, resets, head queries, and safety checks.
The older SafeDB plan in #22528 depended on this issue for a controller write hook. That plan has been superseded by #23473; its write-path sub-issue #23474 explicitly integrates with the current actors without waiting for #22527. This issue is therefore not a prerequisite for the current SafeDB integration. Its in-process head query is also distinct from SafeDB persistence and historical lookups, as the earlier implementation comments explain.
Moving this issue from the SafeDB feature tracker #20278 to #22520, the Lokahi phase-1 shared-component refactor tracker. It retains its prerequisite #22525 and the downstream Lokahi work that depends on it.
einar-oplabs commentedon Oct 26, 2026
@OptimismBot I did not commit to this work. Unassigning. Feel free to bring it up on the next planning meeting.
OptimismBot commentedon Oct 26, 2026
Acknowledged, and sorry about that. I assigned you on 2026-10-16 without you committing to this work. You've already unassigned yourself and the issue now has no assignee. I won't reassign it; it can be picked up at the next planning meeting.
Requested by @einar-oplabs in GitHub