Mock consensus layer (Engine-API driver) for frozen-milestone snap-sync + replay#36
Merged
Merged
Conversation
…nap-sync + replay Post-merge EL clients only snap-sync or execute blocks when a CL drives their Engine API. Frozen milestone snapshots (the bloated states in #21) have no live CL, so lighthouse can't drive them. This adds a minimal Engine-API mock CL with the two CL roles #21 needs: - PivotDriver: repeated engine_forkchoiceUpdatedV3 to a fixed frozen pivot hash -> the EL snap-syncs to that milestone state (snap-sync metrics). - ReplayDriver: engine_newPayloadV{1..4} + engine_forkchoiceUpdated over recorded payloads -> drives execution under live head + per-block latency (block-processing p50/p95/p99, gas/s metrics). EngineClient hand-rolls HS256 JWT (no new deps) and auto-picks newPayload/FCU versions across Paris..Prague. Wired into the orchestrator via consensus_mode: lighthouse|mock|none (back-compat: legacy consensus bool still works). Generalizes the throwaway geth FCU/replay scripts. Nethermind targets can use --Sync.StaticSnapPivot (nethermind#11943) as the native pivot alternative.
dmitriy-b
approved these changes
Jun 16, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on top of #34 (base:
feat/add-locust-framework).Why
Post-merge EL clients (Geth, Besu, Reth, Erigon, Nethermind) only snap-sync or execute blocks when a consensus client drives their Engine API. The benchmark framework in #34 starts a real
lighthouse-<client>CL for that — but the frozen milestone snapshots this project benchmarks (#21: x1, 1.5×…10× bloated states) have no live chain, so a real CL can't drive them. This adds a minimal Engine-API mock CL that provides the two CL roles #21 needs, generalizing the throwawaygeth_*_fcu.py/ replay scripts into a tested, version-controlled module.What
src/mock_cl/— stdlib +requestsonly (hand-rolled HS256 JWT, no new deps):PivotDriver(snap-sync mode) — repeatedly sendsengine_forkchoiceUpdatedV3withhead=safe=finalizedset to a fixed frozen pivot hash, so the target EL snap-syncs to that milestone state. Optional status polling stops the loop once the target reports synced.ReplayDriver(execution mode) — feeds recorded payloads throughengine_newPayloadV{1..4}+engine_forkchoiceUpdated, advancing the head and recording per-block latency (newPayload/FCU ms, p50/p95) to CSV.EngineClient— JWT-authed Engine-API client; auto-selects newPayload/FCU versions across Paris→Prague from payload shape.__main__CLI:pivot,replay,recordsubcommands.#21 metric coverage
pivotreplayOrchestrator integration (backward compatible)
nodes.consensus_mode: lighthouse | mock | none(+ amock_cl:config block). If unset it falls back to the legacyconsensus:boolean (true→lighthouse,false→none), so existing configs are unchanged.CONSENSUS_MODEin env/.envoverrides.mockmode the runner launches the pivot driver in the background for the sync phase and tears it down on stop.build_mock_cl_command()is a pure, unit-tested helper.Nethermind note
NM targets can use
--Sync.StaticSnapPivot(NethermindEth/nethermind#11943) as the native pivot alternative (no external driver) — setconsensus_mode: nonein that case. Documented in the README.Limitation
record(pulling payloads frometh_getBlockByNumber) is best-effort and cannot recover blob versioned-hashes orparentBeaconBlockRoot, so Cancun+ replay needs a true CL-recorded payload source. Pre-Cancun (V1/V2) replay works directly fromrecordoutput. Logged + documented.Tests
uv run pytest -m 'not integration'→ 62 passed (+21 new mock_cl tests; all existing runner/aggregator tests still green). Covers JWT structure/signature, secret loading, version auto-pick, FCU/newPayload param shapes, JSONL payload parsing, ReplayDriver ordering + mid-INVALID raise + CSV, PivotDriver FCU shape, andbuild_mock_cl_command.