Skip to content

Commit 4152e7d

Browse files
committed
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.
1 parent 0a21ac7 commit 4152e7d

1 file changed

Lines changed: 16 additions & 7 deletions

File tree

docs/node/validator-architecture.md

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ Despite the file carrying the full Genesis schema (allocations, gas limit, times
3636
| Derived value | Source in `config` | Use during validation |
3737
| ----------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3838
| Chain ID | `chainId` | Drives the EVM `CHAINID` opcode and EIP-155 transaction-signature checks. |
39-
| Hardfork schedule | `<fork>Block` and `<fork>Time` fields | Activates Ethereum (Cancun, Shanghai, ...), OP-Stack (Ecotone, Granite, Holocene, Isthmus, ...), and MegaETH (MiniRex, MiniRex1-2, Rex, Rex1-5) at their pre-declared block numbers or timestamps. |
39+
| Hardfork schedule | `<fork>Block` and `<fork>Time` fields | Activates Ethereum (Cancun, Shanghai, ...), OP-Stack (Ecotone, Granite, Holocene, Isthmus, ...), and MegaETH (MiniRex, MiniRex1, MiniRex2, Rex, Rex1, Rex2, Rex3, Rex4) at their pre-declared block numbers or timestamps. |
4040

4141
The genesis `alloc`, `gasLimit`, `baseFeePerGas`, and other initial-state fields are **not** consumed — initial state arrives via the witness, not from genesis.
4242

@@ -152,13 +152,23 @@ Account entries in the witness carry the `codehash`, not the bytecode itself.
152152
This is intentional — bytecode is large, changes infrequently, and is content-addressed, so the witness only references it.
153153

154154
Maintain a local cache keyed by `codehash`.
155-
On a miss, fetch via `eth_getCodeByHash` (or fall back to `eth_getCode` for a known holder address) and **verify** that `keccak256(code) == codehash` before installing it.
155+
On a miss, fetch via `eth_getCodeByHash` — a MegaETH RPC extension that takes a code hash and returns the bytecode whose `keccak256` equals that hash — and **verify** that `keccak256(code) == codehash` before installing it.
156+
If the endpoint does not support `eth_getCodeByHash`, fall back to `eth_getCode` against a known holder address and apply the same verification.
156157
A miss that cannot be resolved is a fatal error for the block being validated.
157158

158159
{% endstep %}
159160

160161
{% step %}
161162

163+
### Apply pre-execution system updates
164+
165+
Before the first transaction, apply OP-Stack pre-block hooks (e.g. L1-attributes deposit).
166+
The exact set is fixed by the active hardfork; mirror the reference client's `replay_block` to stay aligned.
167+
168+
{% endstep %}
169+
170+
{% step %}
171+
162172
### Replay the block's transactions
163173

164174
Execute every transaction with the chain's hardfork rules and accumulate state changes, receipts, and the cumulative gas counter.
@@ -175,11 +185,10 @@ There is no separate "ancestor headers" field in the witness.
175185

176186
{% step %}
177187

178-
### Apply pre- and post-execution system updates
188+
### Apply post-execution system updates
179189

180-
Before the first transaction, apply OP-Stack pre-block hooks (e.g. L1-attributes deposit).
181-
After the last transaction, apply post-block hooks (withdrawals processing on the L1 message-passer, beacon-root updates, etc.).
182-
The exact set is fixed by the active hardfork; mirror the reference client's `replay_block` to stay aligned.
190+
After the last transaction, apply OP-Stack post-block hooks: withdrawals processing on the L1 message-passer contract, beacon-root updates, and any hardfork-specific finalization.
191+
As with pre-execution, the exact set is fixed by the active hardfork.
183192

184193
{% endstep %}
185194

@@ -277,7 +286,7 @@ Everything downstream is verified:
277286
- The post-state is verified by recomputing every header commitment.
278287

279288
The validator does **not** decide which fork is canonical.
280-
For a fully trust-minimized setup, pair it with `op-node` and a MegaETH replica that derive the canonical chain from L1 — see [Stateless Validation > Trust model](stateless-validation.md#trust-model).
289+
To derive canonicality from L1 instead of trusting the upstream RPC, pair it with `op-node` and a MegaETH replica — see [Stateless Validation > Trust model](stateless-validation.md#trust-model).
281290

282291
Reorgs are detected when a freshly validated block's `parent_hash` does not match the local tip.
283292
The chain advancer truncates back to the divergence height and re-validates the new branch from there; the canonical-chain row cap (`canonical-chain-max-length`) bounds how far back this can reach.

0 commit comments

Comments
 (0)