docs(node): add stateless validator architecture guide#46
Conversation
ReviewLayer boundary — the page's stated audience conflicts with where it lives. The opening line is: "It is written for engineers building a compatible validator from scratch — in another language, against a different EVM stack."
This page covers exactly that: the three-stage pipeline diagram, per-component crate references, 11-step The suggested home from the AGENTS.md is the upstream One minor issue noted inline below. |
|
|
Add a Genesis configuration section to the validator architecture guide. Spell out that the validator extracts only chain_id and the hardfork schedule (Ethereum, OP-Stack, MegaETH) from the genesis JSON, with file:line references into chain_spec.rs. Note the fields that are loaded but not consumed (alloc, gasLimit, baseFeePerGas, ...) and warn that any divergence in hardfork timestamps surfaces only as a state_root mismatch. Tighten the Trust model section to list the two startup trust inputs (genesis JSON, anchor block hash) explicitly.
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
|
Good addition overall — the content is accurate, well-sourced with upstream line references, and the stepper structure maps cleanly to the pipeline. All relative and anchor links resolve correctly (
|
- Reorder validation steps so pre-execution system updates come before transaction replay and post-execution updates come after, matching the actual execution order an implementer must follow. - Drop the Rex1-5 / MiniRex1-2 range shorthands and list each fork individually (MiniRex, MiniRex1, MiniRex2, Rex, Rex1-Rex4) per the canonical terminology table in docs/AGENTS.md. - Note that eth_getCodeByHash is a MegaETH RPC extension and call out the eth_getCode fallback path for endpoints that do not implement it. - Replace 'fully trust-minimized' (banned in docs/node/AGENTS.md) with neutral wording about deriving canonicality from L1.
ReviewThe page is well-structured and technically thorough for its target audience (re-implementers). Previous rounds of feedback on step ordering, fork names, Two threads from the previous round remain open — fix before merging:
New comment: Precompiles row (line 269) — "if any" leaves re-implementers without a definitive answer about what to build. Needs a concrete statement. |
- Fix step reference in the header-commitment table: withdrawals_root is recomputed in step 9 (Update the withdrawals MPT), not step 8. The numbering shifted when pre/post-execution system updates were split into separate steps. - Add MiniRex1 and MiniRex2 to the canonical spec-name list in docs/AGENTS.md. Both are real hardforks defined in crates/stateless-core/src/chain_spec.rs (mini_rex_1_time, mini_rex_2_time) with activation timestamps in the mainnet genesis.
|
Review update — round 2 Good progress on the previous round. Most threads are now addressed. Resolved this round:
Still open:
Everything else looks good — the 12-step pipeline is correctly ordered, the |
|
All six previous threads have been addressed. The precompiles row no longer says "if any" — it now specifies the OP-Stack Isthmus set with MegaETH gas-cost overrides and links to the spec — so I've resolved that last thread. The content is solid: step ordering is correct, MiniRex1/MiniRex2 are added to the terminology table, |
|
Good shape overall — previous round of feedback is all addressed. Two threads remain open before this is ready: 1. 2. Two sentences on one line (thread): The Everything else looks good — links resolve ( |
|
All previously open threads are now resolved — Rex5 was dropped and the two-sentence line was split per the suggestions. The content is technically thorough and well-structured. A few minor things worth a pass before merge:
Nothing blocking. The core pipeline doc is accurate and the spec links are correct. |
- Fix grammar: 'implementation of stateless validator' → 'implementation of the stateless validator' (missing article). - List the MegaETH forks that deploy no system contracts (MiniRex1, MiniRex2, Rex, Rex1, Rex3) so the per-hardfork hook list is exhaustive. Verified against mega-evm/crates/mega-evm/src/block/executor.rs (only MiniRex, Rex2, Rex4 install contracts in pre_execution_changes).
|
All nine previous threads are resolved. The document is technically solid — previous fixes confirmed:
One minor note, not a blocker: the Related pages footer labels the dual-gas-model spec page as |
The link goes to the Dual Gas Model spec page, not the spec root, so 'Specification' alone misled readers. Use 'MegaEVM specification — Dual Gas Model' on both the inline reference (re-execution section) and in Related pages, and note that the linked page is the entry point into the spec space.
The '— MegaETH is iterating quickly, ...' clause is removed; the bolded imperative carries the message on its own.
|
All previous review threads are now resolved. The three remaining formatting issues (two sentences on one line in the MiniRex bullet, anchor block hash bullet, and salt crate entry) have been addressed in the latest revision. No new issues found. LGTM. |
|
All 12 prior threads are resolved. The document reads cleanly — pipeline ordering, step references, fork-name terminology, one-sentence-per-line, and the precompiles/ LGTM. |
|
All 12 threads from the previous review round are resolved. Two minor issues remain. Line 88 — missing link in architecture table. The Line 313 — baseline understated. The Re-execution requirements section opens with "standard Cancun/Shanghai semantics", but MegaETH's floor is OP-Stack Isthmus. Isthmus adds deposit transactions, EIP-7002, and EIP-7251 — none of which are in vanilla Cancun. An implementer who stops at Cancun will silently miss those behaviors. Suggested fix: "OP-Stack Isthmus semantics (the floor for MegaETH)". Content, structure, and formatting otherwise look solid: step ordering is correct, step references in the intro match the stepper, SALT encoding table arithmetic checks out, terminology aligns with the updated AGENTS.md, and one-sentence-per-line is consistently applied. |
|
All previous threads are resolved. LGTM. Checklist against REVIEW.md:
|
3 participants
Summary
Adds an implementer-facing architecture and walkthrough for building a MegaETH-compatible stateless validator from scratch — aimed at external teams porting the validator to a different language or EVM stack.
The new page lives at
docs/node/validator-architecture.mdand slots underStateless Validation(peer toGet Block Witness).It links to the operator guide and witness wire-format reference rather than duplicating their content.
Covers:
path:linereferencesSome(value)/Some(None)/ absent) and the anti-omission ruleTest plan
{% stepper %},{% hint %}, and table blocks correctly.mdlinks resolve:witness.md,stateless-validation.md,../architecture.md,../dev/execution/volatile-data.mdhttps://docs.megaeth.com/spec/...links resolve on the published site...#L<N>) point to the cited symbols onmain