Skip to content

Commit b0b06ab

Browse files
flyqTroublor
flyq
and
Troublor
authored
docs(node): add stateless validator architecture guide (#46)
* add validator arch * docs(node): document what the validator reads from genesis 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. * docs(node): address PR #46 review comments - 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. * Update validator-architecture.md * fix review - 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. * docs: tighten precompiles row, defer details to spec page * docs(node): correct pre/post-execution hooks, wrap reference-impl in info boxes * fix fmt * fix review * docs(node): address PR #46 round 5 nits - 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). * fix review 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. * fix review The '— MegaETH is iterating quickly, ...' clause is removed; the bolded imperative carries the message on its own. * fix the code line * add eth_getCodeByHash * fix review --------- Co-authored-by: William Aaron Cheung <git@troublor.xyz>
1 parent 305b9d6 commit b0b06ab

3 files changed

Lines changed: 390 additions & 14 deletions

File tree

‎docs/AGENTS.md‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -59,20 +59,20 @@ When in doubt: top-level pages prioritize readability, layer pages prioritize de
5959

6060
Use these exact forms consistently. Do not alternate between variants.
6161

62-
| Term | Correct | Incorrect |
63-
| --------------------- | ------------------------------------ | ----------------------------------------------------------- |
64-
| Project name | MegaETH | megaETH, Mega ETH, megaeth, MEGAETH |
65-
| EVM implementation | MegaEVM | MegaEvm, mega-evm, Mega EVM |
66-
| Mainnet (proper noun) | MegaETH Mainnet | MegaETH mainnet, main net, main-net |
67-
| Testnet (proper noun) | MegaETH Testnet | MegaETH testnet, test net, test-net |
68-
| Currency ticker | ETH | eth, Eth |
69-
| Currency name | ether | Ether, ETH (when referring to the currency, not the ticker) |
70-
| Block type | mini-block | miniblock, mini block, MiniBlock |
71-
| Onchain / offchain | onchain, offchain | on-chain, off-chain, on chain |
72-
| Smart contract | smart contract | Smart Contract, smartcontract |
73-
| Gas dimensions | compute gas, storage gas | Compute Gas, Storage Gas, Compute gas |
74-
| Spec names | MiniRex, Rex, Rex1, Rex2, Rex3, Rex4 | minirex, MINIREX, mini-rex, rex-3 |
75-
| State trie | SALT | Salt, salt |
62+
| Term | Correct | Incorrect |
63+
| --------------------- | -------------------------------------------------------- | ----------------------------------------------------------- |
64+
| Project name | MegaETH | megaETH, Mega ETH, megaeth, MEGAETH |
65+
| EVM implementation | MegaEVM | MegaEvm, mega-evm, Mega EVM |
66+
| Mainnet (proper noun) | MegaETH Mainnet | MegaETH mainnet, main net, main-net |
67+
| Testnet (proper noun) | MegaETH Testnet | MegaETH testnet, test net, test-net |
68+
| Currency ticker | ETH | eth, Eth |
69+
| Currency name | ether | Ether, ETH (when referring to the currency, not the ticker) |
70+
| Block type | mini-block | miniblock, mini block, MiniBlock |
71+
| Onchain / offchain | onchain, offchain | on-chain, off-chain, on chain |
72+
| Smart contract | smart contract | Smart Contract, smartcontract |
73+
| Gas dimensions | compute gas, storage gas | Compute Gas, Storage Gas, Compute gas |
74+
| Spec names | MiniRex, MiniRex1, MiniRex2, Rex, Rex1, Rex2, Rex3, Rex4 | minirex, MINIREX, mini-rex, rex-3 |
75+
| State trie | SALT | Salt, salt |
7676

7777
**Capitalization rules:**
7878

‎docs/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,4 +44,5 @@
4444
## Node Operation
4545

4646
- [Stateless Validation](node/stateless-validation.md)
47+
- [Validator Architecture](node/validator-architecture.md)
4748
- [Get Block Witness](node/witness.md)

0 commit comments

Comments
 (0)