feat(consensus): integrate kona as an in-process consensus engine#686
feat(consensus): integrate kona as an in-process consensus engine#6860xOsiris wants to merge 54 commits into
Conversation
Add a new `world-chain-kona` crate that integrates the Kona OP Stack consensus/derivation node into World Chain as a single binary with reth. Key components: - `InProcessEngineClient`: Implements Kona's `EngineClient` trait (which extends `OpEngineApi`) by dispatching Engine API calls directly to reth's `ConsensusEngineHandle` and reading chain data from reth's provider. This eliminates HTTP/IPC overhead for all engine interactions. - `KonaServiceHandle`: Manages Kona's actor lifecycle (L1 watcher, derivation pipeline, engine actor, network) under the same tokio runtime as reth, with cancellation token for graceful shutdown. - `KonaConfig`: Bridges World Chain's configuration to Kona's builder requirements (L1 RPC, beacon URL, P2P settings, rollup config). The crate is excluded from the default workspace build due to a known op-alloy version mismatch (kona uses 0.22.x, world-chain uses 0.23.x). Engine API method implementations are stubbed with descriptive TODOs documenting the exact conversion steps needed. Architecture: world-chain binary ├── Kona Node (consensus/derivation) ──► Rust fn calls └── Reth Engine (execution) ◄── (no HTTP/IPC) Ref: https://github.com/anton-rs/kona (rev 2586fc56)
…d via Node Builder api
0xOsiris
requested review from
0xForerunner,
Dzejkop,
Kemperino,
alessandromazza98,
cichaczem,
karankurbur,
kilianglas,
murph and
piohei
as code owners
|
Warning Review the following alerts detected in dependencies. According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.
|
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 2 potential issues.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 54a3f03. Configure here.
Benchmark ResultsCompared on the same runner in the same workflow run.
|
alessandromazza98
left a comment
alessandromazza98
left a comment
There was a problem hiding this comment.
left some non-blocking comments
| // synced node the finalized L1 block already trails the safe head's origin by far more than | ||
| // this, so the clamp is a no-op; it only engages while the node replays history behind the | ||
| // finalized point (e.g. a restart bootstrapping derivation from L1 with no unsafe-block | ||
| // gossip), which is exactly the window where the unclamped feed crashes the node. |
There was a problem hiding this comment.
I find this comment a bit hard to understand. I understand it now but I'd suggest to add a small example that explains it very fast. Something like:
// Example:
//
// safe head L2 = #1000
// safe head origin = L1 block 100
//
// The node is replaying history and receives:
//
// finalized L1 = 150
//
// Kona will try to finalize the highest L2 block derived from finalized L1 data.
// That block may be beyond the current safe head:
//
// safe head = L2 #1000
// finalize target= L2 #1200 <-- Critical error
//
// To avoid this, we cap the finalized L1 block to strictly before the safe head's
// L1 origin:
//
// finalized L1 = min(150, 100 - 1) = 99
//
// Why "100 - 1" instead of "100"?
//
// Multiple L2 blocks can share the same L1 origin:
//
// L1 origin 100
// ├─ L2 #1000 (safe head)
// ├─ L2 #1001
// └─ L2 #1002
//
// The safe head only guarantees that L2 #1000 is safe. Later L2 blocks from the same
// epoch may still be unsafe. By clamping to origin 99, we only finalize epochs that
// are completely before the safe head's epoch, guaranteeing the derived finalize
// target can never be ahead of the current safe head.
| } | ||
|
|
||
| #[cfg(test)] | ||
| mod tests { |
There was a problem hiding this comment.
can you move this in the end of the file? Otherwise it may seem that from here forward everything is for tests, but right now this is not true
|
/deploy-alphanet |
|
🛠️ Building |
|
/deploy-alphanet |
|
Building |
|
/deploy-alphanet |
|
Building |
|
Built |
|
/deploy-alphanet |
1 similar comment
|
/deploy-alphanet |
|
Building |
1 similar comment
|
Building |
|
Built |
4 participants
Note
High Risk
Touches consensus/sequencing, engine forkchoice/payload handling, and HA devnet wiring; misconfiguration or engine/IPC integration bugs could stall or fork the chain.
Overview
This PR makes the world-chain binary a monolithic execution + consensus client: when
--kona.enabledis set, the Optimism Kona stack runs in-process instead of a separate op-node, and Engine API work on the hot path goes throughWorldChainKonaEngineClientinto reth’sConsensusEngineHandle/PayloadStore(no HTTP/JWT for FCU,newPayload,getPayload).A new
world-chain-konacrate wiresKonaService, config, and CLI (KonaArgs, P2P, sequencer, L1/beacon, conductor, node RPC). WorkspaceCargo.lockpulls inkona-*fromethereum-optimism/optimism(op-reth/v2.2.0) plus libp2p and related networking deps. Node add-ons spawn Kona after launch and require reth IPC for slower L2 reads.The full-stack devnet drops containerized op-nodes: native sequencers start with in-process Kona (P2P bootstore, conductor RPC, admin sequencer bootstrap). op-conductor and HA flows now talk to each sequencer’s kona RPC (
optimism_syncStatus,admin_startSequencer, etc.).Reviewed by Cursor Bugbot for commit 54a3f03. Configure here.