webevm 0.7.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/README.md +115 -63
  2. package/dist/derived-trie.d.ts +38 -0
  3. package/dist/derived-trie.d.ts.map +1 -0
  4. package/dist/derived-trie.js +187 -0
  5. package/dist/derived-trie.js.map +1 -0
  6. package/dist/engine.d.ts +1 -2
  7. package/dist/engine.d.ts.map +1 -1
  8. package/dist/engine.js +2 -3
  9. package/dist/engine.js.map +1 -1
  10. package/dist/index.d.ts +1 -1
  11. package/dist/index.d.ts.map +1 -1
  12. package/dist/index.js.map +1 -1
  13. package/dist/node.d.ts +45 -0
  14. package/dist/node.d.ts.map +1 -1
  15. package/dist/node.js +1108 -140
  16. package/dist/node.js.map +1 -1
  17. package/dist/revm-state-store.d.ts +5 -0
  18. package/dist/revm-state-store.d.ts.map +1 -1
  19. package/dist/revm-state-store.js +42 -13
  20. package/dist/revm-state-store.js.map +1 -1
  21. package/dist/revm.d.ts.map +1 -1
  22. package/dist/revm.js +5 -19
  23. package/dist/revm.js.map +1 -1
  24. package/dist/state-manager.d.ts +256 -18
  25. package/dist/state-manager.d.ts.map +1 -1
  26. package/dist/state-manager.js +429 -20
  27. package/dist/state-manager.js.map +1 -1
  28. package/dist/storage-keys.d.ts +8 -0
  29. package/dist/storage-keys.d.ts.map +1 -1
  30. package/dist/storage-keys.js +18 -2
  31. package/dist/storage-keys.js.map +1 -1
  32. package/dist/types.d.ts +150 -33
  33. package/dist/types.d.ts.map +1 -1
  34. package/dist/worker-client.d.ts.map +1 -1
  35. package/dist/worker-client.js +20 -12
  36. package/dist/worker-client.js.map +1 -1
  37. package/dist/worker-host.d.ts.map +1 -1
  38. package/dist/worker-host.js +17 -9
  39. package/dist/worker-host.js.map +1 -1
  40. package/dist/worker-rpc-error.d.ts +21 -0
  41. package/dist/worker-rpc-error.d.ts.map +1 -0
  42. package/dist/worker-rpc-error.js +121 -0
  43. package/dist/worker-rpc-error.js.map +1 -0
  44. package/package.json +3 -1
  45. package/src/derived-trie.ts +214 -0
  46. package/src/engine.ts +2 -3
  47. package/src/index.ts +2 -1
  48. package/src/node.ts +1318 -136
  49. package/src/revm-state-store.ts +47 -13
  50. package/src/revm.ts +11 -25
  51. package/src/state-manager.ts +515 -21
  52. package/src/storage-keys.ts +21 -2
  53. package/src/types.ts +152 -34
  54. package/src/worker-client.ts +22 -12
  55. package/src/worker-host.ts +17 -9
  56. package/src/worker-rpc-error.ts +139 -0
@@ -1,5 +1,7 @@
1
1
  /**
2
- * state-manager.ts — the node's `stateMode:'none'` state manager.
2
+ * state-manager.ts: the node's state manager, on EVERY node: a
3
+ * `computeStateRoot: true` node runs on it too and derives its trie from it
4
+ * (./derived-trie.ts, ADR 0014).
3
5
  *
4
6
  * `@ethereumjs/statemanager@10.1.2`'s `SimpleStateManager` keeps storage in ONE
5
7
  * FLAT `Map` keyed `` `${address}_${slot}` ``, and `checkpointSync()` pushes a
@@ -98,19 +100,72 @@
98
100
  * has to live in code we publish. That argument is even stronger for the layout,
99
101
  * which is a representation our own `dumpState` and revm store read directly.
100
102
  *
101
- * WHAT THIS DOES NOT FIX (and cannot, in this mode): the EIP-7610 collision guard
102
- * sitting just above that call rejects creation outright when the target account
103
- * has non-empty storage, and it reads `account.storageRoot`. `SimpleStateManager`
104
- * implements no state-root logic at all, so `storageRoot` never reflects its
105
- * storage and the guard cannot fire. `stateMode:'trie'` gets the correct,
106
- * spec-current behaviour from `MerkleStateManager` (creation fails with
107
- * `CREATE_COLLISION`); `stateMode:'none'` clears and proceeds, which is the
108
- * pre-EIP-7610 semantics and what the EVM's own call asks for. Both are far
109
- * better than silently inheriting; they are not identical to each other, and that
110
- * asymmetry is documented in the README's state-mode section.
103
+ * WHICH COLLISION RULE EVERY NODE FOLLOWS, and why this class is where it is
104
+ * decided. `@ethereumjs/evm` also carries an EIP-7610 guard, just above that
105
+ * call, that refuses a creation when the target has non-empty storage; it reads
106
+ * `account.storageRoot`, which this class never sets (`SimpleStateManager` has no
107
+ * trie), so the guard never fires. That is the INTENDED rule, not a gap: a
108
+ * creation over a zero-nonce, code-less account that holds storage SUCCEEDS and
109
+ * the storage is WIPED by the `clearStorage` above, which is what the reference
110
+ * spec specifies (EIP-684 plus the Yellow Paper, execution-specs PR #3508) and
111
+ * what revm does through this same state. A nonce or code at the target is still
112
+ * a collision on both engines. Every node follows it, with or without
113
+ * `computeStateRoot`, because every node runs on this class: a root-computing
114
+ * node derives its trie from this state rather than running on
115
+ * `MerkleStateManager` (whose real `storageRoot` used to make trie mode, as it
116
+ * was then called, refuse the creation, EIP-7610, the one
117
+ * behaviour that differed by mode). Decided with the user 2026-09-28; the
118
+ * evidence is
119
+ * `work/notes/findings/storage-only-creation-collisions-are-not-refused-by-the-reference-spec.md`
120
+ * and the record is
121
+ * `docs/adr/0014-the-trie-is-derived-from-the-flat-state-not-a-state-manager.md`.
122
+ * So a real `storageRoot` must never be written into this class's accounts: it
123
+ * would silently switch the EIP-7610 guard back on for that account.
124
+ *
125
+ * ## The per-block CHANGE SET (the open record), and why it lives HERE
126
+ *
127
+ * When switched on ({@link OverlayStorageStateManager.enableChangeSets}, an
128
+ * INTERNAL switch the node flips; no option exposes it yet), this class keeps
129
+ * the OPEN RECORD: every account, code entry and storage slot changed since the
130
+ * record was last taken, with the value each had when it was (FIRST WRITE WINS),
131
+ * plus a per-account "storage was cleared" marker. The node takes it at the end
132
+ * of each mined block, so it names what that block (and any `evm_set*` cheat
133
+ * issued before it) changed, and the value at the end of the previous block. It
134
+ * is the seam bounded state history (an undo log) and trie-from-flat-state (the
135
+ * keys to rehash) both stand on: `work/specs/tasked/bounded-state-history.md`.
136
+ *
137
+ * IT IS HERE, IN ONE PLACE, because every write reaches this class: the default
138
+ * engine's through the async `StateManagerInterface` methods overridden below,
139
+ * revm's through the SYNCHRONOUS by-key methods ({@link setAccountAt},
140
+ * {@link setCodeAt}, {@link removeAccountAt}, {@link setStorageAt},
141
+ * {@link clearStorageAt}) that `src/revm-state-store.ts` is required to call
142
+ * instead of writing the maps itself. The async writers are thin wrappers over
143
+ * the same by-key methods, so there is ONE recording path per key kind.
144
+ *
145
+ * CHECKPOINT-AWARE, the same way the storage overlays are. A record is kept PER
146
+ * CHECKPOINT LEVEL (lazily: a level with no write allocates nothing), holding the
147
+ * value each key had at the START of that level, which is its value in the level
148
+ * BELOW (frozen while this one is open, so reading it at first-write time is the
149
+ * same as reading it at checkpoint time). `commit()` merges the top record into
150
+ * the one below with the BELOW entry winning (it is older), `revert()` drops it.
151
+ * So a write inside a reverted frame, a reverted transaction's inner writes, and
152
+ * every `eth_call` / `eth_estimateGas` / state override leave no trace, by
153
+ * construction rather than by bookkeeping. Pure reads additionally SUSPEND
154
+ * recording ({@link withChangeSetsSuspended}) because their levels are always
155
+ * reverted: a cost rule, not a correctness one.
156
+ *
157
+ * THE PRIOR IS READ FROM THE LEVEL BELOW, NOT FROM THE LEVEL BEING WRITTEN, and
158
+ * that is what makes it immune to an in-place mutation inside a checkpoint
159
+ * (`@ethereumjs/vm` mutates the `Account` object it got and then `putAccount`s
160
+ * it). At the BOTTOM level there is no level below, so the prior is the map's
161
+ * current value, and {@link getAccount} hands out a COPY there so that no caller
162
+ * can mutate it before the write arrives. See {@link getAccount} for the
163
+ * decision and its measured cost.
111
164
  */
112
165
  import {SimpleStateManager} from '@ethereumjs/statemanager';
113
- import type {Address} from '@ethereumjs/util';
166
+ import type {AccountFields} from '@ethereumjs/common';
167
+ import {Account, type Address} from '@ethereumjs/util';
168
+ import {keccak_256} from '@noble/hashes/sha3.js';
114
169
  import {
115
170
  packAddressKey,
116
171
  packSlotKey,
@@ -155,9 +210,98 @@ function emptyOverlay(): StorageOverlay {
155
210
  return {written: new Map(), cleared: new Set()};
156
211
  }
157
212
 
213
+ /**
214
+ * THE PER-BLOCK CHANGE SET: for every key changed since the record was opened,
215
+ * the value it had THEN (`undefined` = absent). See the header's change-set
216
+ * section.
217
+ *
218
+ * Keys are the representation's own: accounts and code by `address.toString()`
219
+ * (the upstream stacks' key), storage by PACKED key (the overlays' key).
220
+ */
221
+ export interface ChangeSet {
222
+ /** Account (whole) before the first change, `undefined` if it was absent. */
223
+ readonly accounts: Map<string, Account | undefined>;
224
+ /** Code by address before the first change, `undefined` if there was none. */
225
+ readonly code: Map<string, Uint8Array | undefined>;
226
+ /** Slot values before the first change, `undefined` if the slot was unset. */
227
+ readonly storage: Map<
228
+ PackedAddressKey,
229
+ Map<PackedSlotKey, Uint8Array | undefined>
230
+ >;
231
+ /**
232
+ * Accounts whose storage was CLEARED (creation over storage, `SELFDESTRUCT`,
233
+ * EIP-161 removal). A clear also records every slot the account held, so this
234
+ * marker is not needed to restore a value; it tells a consumer that the
235
+ * account's WHOLE storage changed (a trie must rebuild it).
236
+ */
237
+ readonly storageCleared: Set<PackedAddressKey>;
238
+ }
239
+
240
+ function emptyChangeSet(): ChangeSet {
241
+ return {
242
+ accounts: new Map(),
243
+ code: new Map(),
244
+ storage: new Map(),
245
+ storageCleared: new Set(),
246
+ };
247
+ }
248
+
249
+ /** `true` when the change set records nothing. */
250
+ export function isEmptyChangeSet(cs: ChangeSet): boolean {
251
+ return (
252
+ cs.accounts.size === 0 &&
253
+ cs.code.size === 0 &&
254
+ cs.storage.size === 0 &&
255
+ cs.storageCleared.size === 0
256
+ );
257
+ }
258
+
259
+ /**
260
+ * Merge `newer` INTO `older`, the OLDER entry winning for a key both name: it
261
+ * holds the value from before the first of the two changes, which is what a
262
+ * change set means. `newer` is consumed (its inner storage maps may be handed to
263
+ * `older` whole), so the caller must not use it afterwards.
264
+ *
265
+ * Two callers, one rule: {@link OverlayStorageStateManager.commit} merging a
266
+ * checkpoint level's record down, and the node sealing a block under the number
267
+ * of the block it replaces (`sealBlock` in ./node.ts).
268
+ */
269
+ export function mergeChangeSetOlderWins(
270
+ older: ChangeSet,
271
+ newer: ChangeSet,
272
+ ): void {
273
+ for (const [key, value] of newer.accounts)
274
+ if (!older.accounts.has(key)) older.accounts.set(key, value);
275
+ for (const [key, value] of newer.code)
276
+ if (!older.code.has(key)) older.code.set(key, value);
277
+ for (const [addressKey, slots] of newer.storage) {
278
+ const target = older.storage.get(addressKey);
279
+ if (target === undefined) {
280
+ older.storage.set(addressKey, slots);
281
+ continue;
282
+ }
283
+ for (const [slotKey, value] of slots)
284
+ if (!target.has(slotKey)) target.set(slotKey, value);
285
+ }
286
+ for (const addressKey of newer.storageCleared)
287
+ older.storageCleared.add(addressKey);
288
+ }
289
+
290
+ /**
291
+ * A copy of an `Account` that shares no mutable state with it: the same trick
292
+ * `checkpointSync()` uses (upstream's, kept byte for byte), which copies the
293
+ * instance's own fields onto a fresh object of the same prototype. The fields are
294
+ * bigints and `Uint8Array`s that are REPLACED rather than mutated, so a shallow
295
+ * copy is independent. Exported for the node, which hands a sealed record's
296
+ * account to the engine for a historical call (`historicalEntries`).
297
+ */
298
+ export function copyAccount(account: Account): Account {
299
+ return Object.assign(Object.create(Object.getPrototypeOf(account)), account);
300
+ }
301
+
158
302
  const STORAGE_STACK_IS_GONE =
159
303
  "webevm: SimpleStateManager's flat `storageStack` is not maintained " +
160
- "by this node. `stateMode:'none'` storage is per-account with per-checkpoint " +
304
+ 'by this node. Its storage is per-account with per-checkpoint ' +
161
305
  'OVERLAYS — read it through `storageAt(addressKey, slotKey)` (one slot, ' +
162
306
  'synchronously), `liveStorage()` (every live slot, grouped by account) or the ' +
163
307
  'async `getStorage(address, key)`. This throws on purpose: an empty ' +
@@ -181,6 +325,17 @@ export class OverlayStorageStateManager extends SimpleStateManager {
181
325
  */
182
326
  declare storageOverlays: StorageOverlay[];
183
327
 
328
+ /**
329
+ * The change set PER CHECKPOINT LEVEL, parallel to `accountStack` (index 0 is
330
+ * the OPEN RECORD). `undefined` as a whole means recording is OFF, which is the
331
+ * default and costs nothing; an `undefined` entry means that level has written
332
+ * nothing yet. NO INITIALISER, for the header's field-initialiser trap: the
333
+ * base constructor's `checkpointSync()` runs before any field would.
334
+ */
335
+ declare private changeLevels: (ChangeSet | undefined)[] | undefined;
336
+ /** > 0 while a pure read runs: see {@link withChangeSetsSuspended}. */
337
+ declare private changeSetsSuspended: number | undefined;
338
+
184
339
  constructor(opts?: ConstructorParameters<typeof SimpleStateManager>[0]) {
185
340
  super(opts);
186
341
  // The base constructor assigned `this.storageStack = []`. Replace that own
@@ -220,6 +375,9 @@ export class OverlayStorageStateManager extends SimpleStateManager {
220
375
  }
221
376
  this.accountStack.push(newTopA);
222
377
  this.codeStack.push(new Map(this.topCodeStack()));
378
+ // A new level records nothing until it writes (lazy), so a frame that only
379
+ // reads allocates nothing here.
380
+ this.changeLevels?.push(undefined);
223
381
  // First call comes from the BASE constructor, before any subclass field
224
382
  // could have run. `as ... | undefined` because the declared type says it is
225
383
  // always there, and at this one instant it is not.
@@ -253,6 +411,8 @@ export class OverlayStorageStateManager extends SimpleStateManager {
253
411
  * {@link clearStorageAt}, with no checkpoint open), rather than swept later.
254
412
  */
255
413
  override async commit(): Promise<void> {
414
+ // Refused BEFORE anything moves, so a refusal leaves the stacks as they were.
415
+ this.refuseCommitIntoBottomWhileSuspended();
256
416
  this.accountStack.splice(-2, 1);
257
417
  this.codeStack.splice(-2, 1);
258
418
  const overlays = this.storageOverlays;
@@ -267,6 +427,7 @@ export class OverlayStorageStateManager extends SimpleStateManager {
267
427
  // After the `pop()` below, `below` is the bottom overlay exactly when the
268
428
  // stack is two deep now.
269
429
  const belowIsBottom = overlays.length === 2;
430
+ this.mergeChangeLevelDown();
270
431
  for (const address of top.cleared) {
271
432
  below.written.delete(address);
272
433
  if (!belowIsBottom) below.cleared.add(address);
@@ -288,6 +449,321 @@ export class OverlayStorageStateManager extends SimpleStateManager {
288
449
  this.accountStack.pop();
289
450
  this.codeStack.pop();
290
451
  this.storageOverlays.pop();
452
+ // ...and the change set it recorded goes with it: a reverted write was never
453
+ // a change.
454
+ this.changeLevels?.pop();
455
+ }
456
+
457
+ // --- the change set (the open record) -------------------------------------
458
+
459
+ /**
460
+ * Switch change-set recording ON. INTERNAL: called by the node when a feature
461
+ * that consumes change sets is on (bounded state history, trie-from-flat-state);
462
+ * no option exposes it directly. Only with no checkpoint open, so the level
463
+ * array starts parallel to the stacks.
464
+ */
465
+ enableChangeSets(): void {
466
+ if (this.accountStack.length !== 1)
467
+ throw new Error(
468
+ 'webevm: change sets can only be switched on with no checkpoint open.',
469
+ );
470
+ this.changeLevels ??= [emptyChangeSet()];
471
+ }
472
+
473
+ /** Whether {@link enableChangeSets} was called. */
474
+ get recordsChangeSets(): boolean {
475
+ return this.changeLevels !== undefined;
476
+ }
477
+
478
+ /**
479
+ * The OPEN RECORD as it stands, without taking it. `undefined` when recording
480
+ * is off. Read-only by contract: the node's test-only probe and the next
481
+ * consumers read it; nothing may mutate it.
482
+ */
483
+ peekChangeSet(): ChangeSet | undefined {
484
+ return this.changeLevels?.[0];
485
+ }
486
+
487
+ /**
488
+ * TAKE the open record and open a fresh one: the node calls this at the end of
489
+ * each mined block. `undefined` when recording is off. Refused with a
490
+ * checkpoint open, because the writes of an open level are not in the open
491
+ * record yet and would be attributed to the wrong block.
492
+ */
493
+ takeChangeSet(): ChangeSet | undefined {
494
+ const levels = this.changeLevels;
495
+ if (levels === undefined) return undefined;
496
+ if (levels.length !== 1)
497
+ throw new Error(
498
+ 'webevm: the change set was taken with a checkpoint open; its writes ' +
499
+ 'would be attributed to the wrong block.',
500
+ );
501
+ const taken = levels[0] ?? emptyChangeSet();
502
+ levels[0] = emptyChangeSet();
503
+ return taken;
504
+ }
505
+
506
+ /**
507
+ * Run a PURE READ (`eth_call`, `eth_estimateGas`, a state override) with
508
+ * recording suspended. Its levels are always reverted, so recording there is
509
+ * wasted work that the revert would throw away: a COST rule. Correctness does
510
+ * not depend on it, and it is guarded anyway: a write at the bottom level (no
511
+ * checkpoint open) is still recorded, and a commit INTO the bottom level while
512
+ * suspended throws, since that would be a suspended write becoming state.
513
+ */
514
+ async withChangeSetsSuspended<T>(read: () => Promise<T>): Promise<T> {
515
+ if (this.changeLevels === undefined) return read();
516
+ this.changeSetsSuspended = (this.changeSetsSuspended ?? 0) + 1;
517
+ try {
518
+ return await read();
519
+ } finally {
520
+ this.changeSetsSuspended = (this.changeSetsSuspended ?? 1) - 1;
521
+ }
522
+ }
523
+
524
+ /**
525
+ * The record of the CURRENT (top) level, created on first use, or `undefined`
526
+ * when nothing should be recorded: recording off, or a suspended pure read above
527
+ * the bottom level.
528
+ */
529
+ private recordingLevel(): ChangeSet | undefined {
530
+ const levels = this.changeLevels;
531
+ if (levels === undefined) return undefined;
532
+ const depth = levels.length - 1;
533
+ if (depth > 0 && (this.changeSetsSuspended ?? 0) > 0) return undefined;
534
+ let record = levels[depth];
535
+ if (record === undefined) {
536
+ record = emptyChangeSet();
537
+ levels[depth] = record;
538
+ }
539
+ return record;
540
+ }
541
+
542
+ /**
543
+ * The stack index the PRIOR of a write is read from: the level below the top
544
+ * (frozen while the top is open), or the bottom itself when no checkpoint is
545
+ * open (read before the write lands).
546
+ */
547
+ private priorIndex(): number {
548
+ return Math.max(this.accountStack.length - 2, 0);
549
+ }
550
+
551
+ private recordAccountPrior(key: string): void {
552
+ const record = this.recordingLevel();
553
+ if (record === undefined || record.accounts.has(key)) return;
554
+ const prior = this.accountStack[this.priorIndex()].get(
555
+ key as `0x${string}`,
556
+ );
557
+ // A COPY: the object may be handed to (and mutated by) somebody later, and
558
+ // the record must keep saying what it was.
559
+ record.accounts.set(key, prior && copyAccount(prior));
560
+ }
561
+
562
+ private recordCodePrior(key: string): void {
563
+ const record = this.recordingLevel();
564
+ if (record === undefined || record.code.has(key)) return;
565
+ record.code.set(
566
+ key,
567
+ this.codeStack[this.priorIndex()].get(key as `0x${string}`),
568
+ );
569
+ }
570
+
571
+ private recordSlotPrior(
572
+ addressKey: PackedAddressKey,
573
+ slotKey: PackedSlotKey,
574
+ ): void {
575
+ const record = this.recordingLevel();
576
+ if (record === undefined) return;
577
+ let inner = record.storage.get(addressKey);
578
+ if (inner?.has(slotKey)) return;
579
+ if (inner === undefined) {
580
+ inner = new Map();
581
+ record.storage.set(addressKey, inner);
582
+ }
583
+ inner.set(
584
+ slotKey,
585
+ this.storageAtDepth(addressKey, slotKey, this.priorIndex()),
586
+ );
587
+ }
588
+
589
+ /**
590
+ * A storage CLEAR: record every slot the account held (as seen from the level
591
+ * below) that is not already recorded, plus the cleared marker. O(slots of
592
+ * that account), paid only on a clear and only with recording on.
593
+ */
594
+ private recordClearPrior(addressKey: PackedAddressKey): void {
595
+ const record = this.recordingLevel();
596
+ if (record === undefined) return;
597
+ record.storageCleared.add(addressKey);
598
+ let inner = record.storage.get(addressKey);
599
+ const overlays = this.storageOverlays;
600
+ // Walk downwards exactly as `storageAt` does: a higher overlay shadows a
601
+ // lower one (the `has` check keeps the first, i.e. highest, value seen), and
602
+ // an overlay that cleared the account hides everything below it.
603
+ for (let i = this.priorIndex(); i >= 0; i--) {
604
+ const overlay = overlays[i];
605
+ const written = overlay.written.get(addressKey);
606
+ if (written !== undefined) {
607
+ for (const [slotKey, value] of written) {
608
+ if (inner === undefined) {
609
+ inner = new Map();
610
+ record.storage.set(addressKey, inner);
611
+ }
612
+ if (!inner.has(slotKey)) inner.set(slotKey, value);
613
+ }
614
+ }
615
+ if (overlay.cleared.has(addressKey)) break;
616
+ }
617
+ }
618
+
619
+ /**
620
+ * A commit INTO the bottom level while recording is suspended would turn a
621
+ * pure read's unrecorded writes into committed state behind the record, so it
622
+ * is refused. No pure read does it (each reverts the level it opened); this is
623
+ * the guard that makes the suspension a cost rule and never a correctness one.
624
+ */
625
+ private refuseCommitIntoBottomWhileSuspended(): void {
626
+ if (
627
+ this.changeLevels !== undefined &&
628
+ (this.changeSetsSuspended ?? 0) > 0 &&
629
+ this.accountStack.length === 2
630
+ )
631
+ throw new Error(
632
+ 'webevm: a checkpoint was committed into committed state while change ' +
633
+ 'sets were suspended for a pure read. A pure read must revert its ' +
634
+ 'levels; its writes were not recorded.',
635
+ );
636
+ }
637
+
638
+ /**
639
+ * `commit()`'s half for the change set: merge the top level's record into the
640
+ * one below, the BELOW entry winning (it holds the older value: the key was
641
+ * written there before the checkpoint).
642
+ */
643
+ private mergeChangeLevelDown(): void {
644
+ const levels = this.changeLevels;
645
+ if (levels === undefined) return;
646
+ const top = levels.pop();
647
+ if (top === undefined) return;
648
+ const belowIndex = levels.length - 1;
649
+ const below = levels[belowIndex];
650
+ // The top level is gone after this, so nobody else holds its maps: hand them
651
+ // down whole when the level below has recorded nothing.
652
+ if (below === undefined) {
653
+ levels[belowIndex] = top;
654
+ return;
655
+ }
656
+ mergeChangeSetOlderWins(below, top);
657
+ }
658
+
659
+ // --- accounts and code ------------------------------------------------------
660
+ // Every write to the account and code maps goes through the three by-key
661
+ // methods below, which record the prior first. The async `StateManagerInterface`
662
+ // writers are wrappers over them; `src/revm-state-store.ts` calls them directly
663
+ // (it cannot await). Upstream's writers, enumerated from
664
+ // `@ethereumjs/statemanager@10.1.2`'s `SimpleStateManager`: `putAccount`,
665
+ // `deleteAccount`, `modifyAccountFields` and `putCode` (which writes the code
666
+ // map and then the account's `codeHash`). All four are overridden.
667
+
668
+ /**
669
+ * Write one account SYNCHRONOUSLY, by key, into the TOP level: the account
670
+ * twin of {@link setStorageAt}, for revm's synchronous commit callback. The key
671
+ * is `address.toString()` (`0x`, lowercase), the upstream stack's key.
672
+ * `undefined` tombstones the account, as upstream's `putAccount` does.
673
+ */
674
+ setAccountAt(addressKey: string, account: Account | undefined): void {
675
+ this.recordAccountPrior(addressKey);
676
+ this.topAccountStack().set(addressKey as `0x${string}`, account);
677
+ }
678
+
679
+ /**
680
+ * Tombstone one account SYNCHRONOUSLY, by key. The ACCOUNT only: the storage
681
+ * half is {@link clearStorageAt}, which revm's binding sends immediately
682
+ * before (see `removeAccount` in `src/revm-state-store.ts`), and the async
683
+ * {@link deleteAccount} does both. Code is left in place, as upstream leaves it.
684
+ */
685
+ removeAccountAt(addressKey: string): void {
686
+ this.setAccountAt(addressKey, undefined);
687
+ }
688
+
689
+ /**
690
+ * Write one account's CODE SYNCHRONOUSLY, by key, into the TOP level. The code
691
+ * map only: the account's `codeHash` is the caller's to write (revm's
692
+ * `setAccount` carries it; the async {@link putCode} writes it itself).
693
+ */
694
+ setCodeAt(addressKey: string, code: Uint8Array): void {
695
+ this.recordCodePrior(addressKey);
696
+ this.topCodeStack().set(addressKey as `0x${string}`, code);
697
+ }
698
+
699
+ /**
700
+ * Read one account, handing out a COPY WHEN NO CHECKPOINT IS OPEN.
701
+ *
702
+ * THE HAZARD: upstream returns the object stored IN the top account map.
703
+ * Inside a checkpoint that is harmless, because a level holds copies and the
704
+ * change set reads a write's prior from the level below. At the BOTTOM level
705
+ * (where the `evm_set*` cheats, `refuseIfSenderCannotSend` and every RPC read
706
+ * run) there is no level below: a caller that edits the object and then calls
707
+ * `putAccount` (the node's `mutateAccount`, upstream `modifyAccountFields`,
708
+ * reached from `putCode`) has overwritten the prior before any write hook
709
+ * runs, and the record would hold the NEW value as the old one.
710
+ *
711
+ * DECISION (state-change-set-capture, 2026-09-28): close it at the seam, by
712
+ * copying at the bottom level only, and regardless of whether change sets are
713
+ * on, so aliasing semantics do not depend on an internal flag. Rejected: fixing
714
+ * `mutateAccount` alone (upstream `modifyAccountFields` does the same);
715
+ * recording the prior on the first bottom-level READ (it would put every
716
+ * `eth_getBalance`'d key in the record, a superset the history would then
717
+ * store per block); copying at every level (the default engine's hot path runs
718
+ * inside checkpoints and needs no copy). MEASURED COST: one object allocation
719
+ * per bottom-level read, which is only RPC reads and cheats, never the
720
+ * interpreter; see
721
+ * `docs/spikes/state-change-set-capture/measurements.md`.
722
+ */
723
+ override async getAccount(address: Address): Promise<Account | undefined> {
724
+ const account = this.topAccountStack().get(address.toString());
725
+ if (account === undefined || this.accountStack.length > 1) return account;
726
+ return copyAccount(account);
727
+ }
728
+
729
+ override async putAccount(
730
+ address: Address,
731
+ account?: Account | undefined,
732
+ ): Promise<void> {
733
+ this.setAccountAt(address.toString(), account);
734
+ }
735
+
736
+ /**
737
+ * Read-modify-write of named fields. Overridden rather than inherited so the
738
+ * write provably goes through {@link putAccount} and the read through
739
+ * {@link getAccount}'s bottom-level copy, instead of depending on upstream's
740
+ * `modifyAccountFields` helper keeping that shape.
741
+ */
742
+ override async modifyAccountFields(
743
+ address: Address,
744
+ accountFields: AccountFields,
745
+ ): Promise<void> {
746
+ const account = (await this.getAccount(address)) ?? new Account();
747
+ account.nonce = accountFields.nonce ?? account.nonce;
748
+ account.balance = accountFields.balance ?? account.balance;
749
+ account.storageRoot = accountFields.storageRoot ?? account.storageRoot;
750
+ account.codeHash = accountFields.codeHash ?? account.codeHash;
751
+ account.codeSize = accountFields.codeSize ?? account.codeSize;
752
+ await this.putAccount(address, account);
753
+ }
754
+
755
+ /**
756
+ * Upstream's `putCode`, restated so the code-map write goes through
757
+ * {@link setCodeAt}: the code, then an empty account if there was none, then
758
+ * the account's `codeHash`.
759
+ */
760
+ override async putCode(address: Address, value: Uint8Array): Promise<void> {
761
+ this.setCodeAt(address.toString(), value);
762
+ if ((await this.getAccount(address)) === undefined)
763
+ await this.putAccount(address, new Account());
764
+ await this.modifyAccountFields(address, {
765
+ codeHash: (this.common?.customCrypto.keccak256 ?? keccak_256)(value),
766
+ });
291
767
  }
292
768
 
293
769
  // --- storage -------------------------------------------------------------
@@ -325,9 +801,22 @@ export class OverlayStorageStateManager extends SimpleStateManager {
325
801
  storageAt(
326
802
  addressKey: PackedAddressKey,
327
803
  slotKey: PackedSlotKey,
804
+ ): Uint8Array | undefined {
805
+ return this.storageAtDepth(
806
+ addressKey,
807
+ slotKey,
808
+ this.storageOverlays.length - 1,
809
+ );
810
+ }
811
+
812
+ /** {@link storageAt} as seen from overlay `from` downwards. */
813
+ private storageAtDepth(
814
+ addressKey: PackedAddressKey,
815
+ slotKey: PackedSlotKey,
816
+ from: number,
328
817
  ): Uint8Array | undefined {
329
818
  const overlays = this.storageOverlays;
330
- for (let i = overlays.length - 1; i >= 0; i--) {
819
+ for (let i = from; i >= 0; i--) {
331
820
  const overlay = overlays[i];
332
821
  const hit = overlay.written.get(addressKey)?.get(slotKey);
333
822
  if (hit !== undefined) return hit;
@@ -357,6 +846,7 @@ export class OverlayStorageStateManager extends SimpleStateManager {
357
846
  value: Uint8Array,
358
847
  ): void {
359
848
  const top = this.topOverlay();
849
+ this.recordSlotPrior(addressKey, slotKey);
360
850
  let inner = top.written.get(addressKey);
361
851
  if (inner === undefined) {
362
852
  inner = new Map();
@@ -389,6 +879,7 @@ export class OverlayStorageStateManager extends SimpleStateManager {
389
879
  */
390
880
  clearStorageAt(addressKey: PackedAddressKey): void {
391
881
  const top = this.topOverlay();
882
+ this.recordClearPrior(addressKey);
392
883
  top.written.delete(addressKey);
393
884
  if (this.storageOverlays.length > 1) top.cleared.add(addressKey);
394
885
  }
@@ -443,15 +934,15 @@ export class OverlayStorageStateManager extends SimpleStateManager {
443
934
  * clearing) left every slot of the dead account READABLE at its address, and
444
935
  * `dumpState` kept serialising them. Measured through the node's own surface:
445
936
  * after a contract that writes slot 0 and selfdestructs in the same
446
- * transaction, `eth_getStorageAt` answered `0x2a` in `stateMode:'none'` and
447
- * `0x0` in `stateMode:'trie'`
937
+ * transaction, `eth_getStorageAt` answered `0x2a` on a node computing no root and
938
+ * `0x0` on one computing a root (which then ran on `MerkleStateManager`)
448
939
  * (`docs/spikes/revm-write-callbacks-reproduce-the-post-state/measurements.md`).
449
940
  *
450
941
  * A DELETED ACCOUNT HAS NO STORAGE, in a trie by construction: the account is
451
- * removed and its storage trie goes with it, which is why
452
- * `MerkleStateManager` needs no equivalent line and why `'trie'` was already
453
- * right. This makes `'none'` say the same thing rather than leaving the two
454
- * modes disagreeing about a destroyed contract, and it is the reason the revm
942
+ * removed and its storage trie goes with it. This makes the flat state, which
943
+ * every node now runs on, say the same thing (the derived trie of
944
+ * a `computeStateRoot` node sees this clear as a storage-cleared change), and it is
945
+ * the reason the revm
455
946
  * engine — whose host is handed `clearStorage` then `removeAccount` for exactly
456
947
  * these two cases, with revm's commit semantics already applied — now leaves
457
948
  * post-state a diff cannot tell apart from `@ethereumjs/vm`'s. See
@@ -464,7 +955,7 @@ export class OverlayStorageStateManager extends SimpleStateManager {
464
955
  * frame is reverted.
465
956
  */
466
957
  override async deleteAccount(address: Address): Promise<void> {
467
- await super.deleteAccount(address);
958
+ this.removeAccountAt(address.toString());
468
959
  this.clearStorageAt(packAddressKey(address.bytes));
469
960
  }
470
961
 
@@ -512,6 +1003,9 @@ export class OverlayStorageStateManager extends SimpleStateManager {
512
1003
  * overlay's outer map and each inner map), because the copy's overlays are not
513
1004
  * this object's: sharing an inner map would let a write on the copy land in
514
1005
  * this manager's committed state.
1006
+ *
1007
+ * CHANGE-SET RECORDING IS NOT COPIED: the copy starts with it off. A copy's
1008
+ * writes are not this node's blocks.
515
1009
  */
516
1010
  override shallowCopy(): OverlayStorageStateManager {
517
1011
  const copy = new OverlayStorageStateManager({common: this.common});
@@ -1,5 +1,5 @@
1
1
  /**
2
- * storage-keys.ts — the node's `stateMode:'none'` STORAGE KEY encoding, and the
2
+ * storage-keys.ts: the node's STORAGE KEY encoding (on every node), and the
3
3
  * ONE place either side of it is allowed to build a key.
4
4
  *
5
5
  * A storage key here is **PACKED**: two bytes per UTF-16 code unit, so an
@@ -45,7 +45,7 @@
45
45
  * to that width rather than encoding it ambiguously. Normalising is safe and
46
46
  * unreachable in practice: `@ethereumjs/evm` always hands over a 32-byte slot
47
47
  * key, every caller in `src/node.ts` pads to 32 first, and `MerkleStateManager`
48
- * (the other state mode) REFUSES a key that is not 32 bytes at all — so a short
48
+ * (which trie mode, as it was then called, ran on) REFUSES a key that is not 32 bytes at all, so a short
49
49
  * key names the slot it obviously means instead of an unreadable one.
50
50
  *
51
51
  * ## What this is NOT the key format for
@@ -135,6 +135,25 @@ export function unpackSlotKey(key: PackedSlotKey): HexKey {
135
135
  return unpack(key);
136
136
  }
137
137
 
138
+ /**
139
+ * The RAW BYTES a packed key encodes (20 for an account, 32 for a slot): the
140
+ * inverse of {@link packAddressKey} / {@link packSlotKey} without the hex
141
+ * detour. For the derived trie (`src/derived-trie.ts`), which keys its tries by
142
+ * the raw address and slot and reaches them from the change set's packed keys.
143
+ * Allocates, so it is a per-changed-key cost, never a read path.
144
+ */
145
+ export function packedKeyBytes(
146
+ key: PackedAddressKey | PackedSlotKey,
147
+ ): Uint8Array {
148
+ const out = new Uint8Array(key.length * 2);
149
+ for (let i = 0; i < key.length; i++) {
150
+ const c = key.charCodeAt(i);
151
+ out[2 * i] = c >>> 8;
152
+ out[2 * i + 1] = c & 0xff;
153
+ }
154
+ return out;
155
+ }
156
+
138
157
  /**
139
158
  * The inverse of the two encoders, for the dump path ONLY — it allocates a
140
159
  * string per key and is O(live slots) over a whole dump. Read one slot with