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
package/src/node.ts CHANGED
@@ -4,7 +4,10 @@
4
4
  * Design: sits BETWEEN bare `EVM.runCall` (no blocks/receipts/logs) and a full
5
5
  * node (heavy). Runs on `@ethereumjs/vm` through the engine seam (see ./engine.ts)
6
6
  * + a minimal mock blockchain with `SimpleStateManager` (plain Maps, NO trie, NO
7
- * state-root) and NONE of the node / RPC / mempool / signing bloat.
7
+ * state-root) and NONE of the node / RPC / mempool / signing bloat. Every node
8
+ * runs on that one flat state; a node with `computeStateRoot: true` additionally DERIVES
9
+ * a Merkle-Patricia trie from it at the end of each block (./derived-trie.ts,
10
+ * `docs/adr/0014-the-trie-is-derived-from-the-flat-state-not-a-state-manager.md`).
8
11
  *
9
12
  * It is EXECUTION-ONLY:
10
13
  * - NO account methods (eth_sendTransaction, eth_accounts, eth_sign,
@@ -34,8 +37,19 @@
34
37
  * `docs/adr/0012-one-request-at-a-time-the-node-serialises-its-whole-public-surface.md`.
35
38
  */
36
39
  import {createVM, type VM} from '@ethereumjs/vm';
37
- import {MerkleStateManager} from '@ethereumjs/statemanager';
38
- import {OverlayStorageStateManager} from './state-manager.js';
40
+ import {DerivedStateTrie} from './derived-trie.js';
41
+ import {
42
+ OverlayStorageStateManager,
43
+ copyAccount,
44
+ mergeChangeSetOlderWins,
45
+ type ChangeSet,
46
+ } from './state-manager.js';
47
+ import {
48
+ packAddressKey,
49
+ packSlotKey,
50
+ unpackAddressKey,
51
+ unpackSlotKey,
52
+ } from './storage-keys.js';
39
53
  import {Common, Mainnet, Hardfork} from '@ethereumjs/common';
40
54
  import {createBlock, type Block} from '@ethereumjs/block';
41
55
  import {createTxFromRLP, createTx, type TypedTransaction} from '@ethereumjs/tx';
@@ -50,6 +64,7 @@ import {
50
64
  bigIntToHex,
51
65
  setLengthLeft,
52
66
  bigIntToBytes,
67
+ unpadBytes,
53
68
  } from '@ethereumjs/util';
54
69
 
55
70
  // `@ethereumjs/util`'s hexToBytes is typed to require a `0x${string}` literal.
@@ -90,6 +105,7 @@ import {
90
105
  type SerializedReceipt,
91
106
  type SerializedLog,
92
107
  type SerializedTx,
108
+ type SerializedHistoryBlock,
93
109
  } from './types.js';
94
110
 
95
111
  const ZERO_HASH = '0x' + '00'.repeat(32);
@@ -182,6 +198,96 @@ function hex(b: Uint8Array): string {
182
198
  function numHex(n: number | bigint): string {
183
199
  return bigIntToHex(BigInt(n));
184
200
  }
201
+
202
+ /**
203
+ * A change set as the dump carries it ({@link SerializedHistoryBlock}): keys in
204
+ * `0x` hex, values hex, `null` for absent. Reads `changes` and does not keep a
205
+ * reference to anything in it.
206
+ */
207
+ function serializeChangeSet(
208
+ number: number,
209
+ changes: ChangeSet,
210
+ ): SerializedHistoryBlock {
211
+ const accounts: Record<string, string | null> = {};
212
+ for (const [key, account] of changes.accounts)
213
+ accounts[key] = account === undefined ? null : hex(account.serialize());
214
+ const code: Record<string, string | null> = {};
215
+ for (const [key, value] of changes.code)
216
+ code[key] = value === undefined ? null : hex(value);
217
+ const storage: Record<string, Record<string, string | null>> = {};
218
+ for (const [addressKey, slots] of changes.storage) {
219
+ const out: Record<string, string | null> = {};
220
+ for (const [slotKey, value] of slots)
221
+ out[unpackSlotKey(slotKey)] = value === undefined ? null : hex(value);
222
+ storage[unpackAddressKey(addressKey)] = out;
223
+ }
224
+ return {
225
+ number,
226
+ accounts,
227
+ code,
228
+ storage,
229
+ storageCleared: [...changes.storageCleared].map(unpackAddressKey),
230
+ };
231
+ }
232
+
233
+ /**
234
+ * Merge serialized record `newer` INTO `older`, the OLDER entry winning for a
235
+ * key both name: the serialized twin of `mergeChangeSetOlderWins`, used by
236
+ * `dumpState` to fold the open record into the head's record (see there).
237
+ */
238
+ function mergeSerializedOlderWins(
239
+ older: SerializedHistoryBlock,
240
+ newer: SerializedHistoryBlock,
241
+ ): void {
242
+ for (const [key, value] of Object.entries(newer.accounts))
243
+ if (!(key in older.accounts)) older.accounts[key] = value;
244
+ for (const [key, value] of Object.entries(newer.code))
245
+ if (!(key in older.code)) older.code[key] = value;
246
+ for (const [address, slots] of Object.entries(newer.storage)) {
247
+ const target = (older.storage[address] ??= {});
248
+ for (const [slot, value] of Object.entries(slots))
249
+ if (!(slot in target)) target[slot] = value;
250
+ }
251
+ for (const address of newer.storageCleared)
252
+ if (!older.storageCleared.includes(address))
253
+ older.storageCleared.push(address);
254
+ }
255
+
256
+ /**
257
+ * The inverse of {@link serializeChangeSet}: keys back to the representation's
258
+ * own (`address.toString()` for accounts and code, PACKED for storage), `null`
259
+ * back to `undefined`. Addresses are lowercased, so a hand-edited checksummed
260
+ * key still names the account the maps hold.
261
+ */
262
+ function deserializeChangeSet(record: SerializedHistoryBlock): ChangeSet {
263
+ const accounts = new Map<string, Account | undefined>();
264
+ for (const [key, value] of Object.entries(record.accounts))
265
+ accounts.set(
266
+ key.toLowerCase(),
267
+ value === null ? undefined : createAccountFromRLP(hexToBytes(value)),
268
+ );
269
+ const code = new Map<string, Uint8Array | undefined>();
270
+ for (const [key, value] of Object.entries(record.code))
271
+ code.set(key.toLowerCase(), value === null ? undefined : hexToBytes(value));
272
+ const storage: ChangeSet['storage'] = new Map();
273
+ for (const [address, slots] of Object.entries(record.storage)) {
274
+ const out = new Map<string, Uint8Array | undefined>();
275
+ for (const [slot, value] of Object.entries(slots))
276
+ out.set(
277
+ packSlotKey(hexToBytes(slot)),
278
+ value === null ? undefined : hexToBytes(value),
279
+ );
280
+ storage.set(packAddressKey(hexToBytes(address)), out);
281
+ }
282
+ return {
283
+ accounts,
284
+ code,
285
+ storage,
286
+ storageCleared: new Set(
287
+ record.storageCleared.map((a) => packAddressKey(hexToBytes(a))),
288
+ ),
289
+ };
290
+ }
185
291
  function txHashOf(tx: TypedTransaction): string {
186
292
  return hex(tx.hash());
187
293
  }
@@ -264,6 +370,32 @@ interface StoredBlock {
264
370
  */
265
371
  function swallow(): void {}
266
372
 
373
+ /**
374
+ * ONE ACCOUNT'S WORTH OF STATE TO WRITE into the checkpoint a pure read opens
375
+ * (`withStateEntries` in {@link createNodeWithInternals}), already parsed so it
376
+ * cannot fail to apply. Two producers, one apply step (`applyStateEntry`):
377
+ * the geth-style state overrides of `eth_call` / `eth_estimateGas`
378
+ * (`parseStateOverrides`), and block K's state for a call pinned to K
379
+ * (`historicalEntries`, from the `stateHistory` undo log). INTERNAL: not RPC
380
+ * JSON, and not exported.
381
+ */
382
+ interface StateEntry {
383
+ readonly address: Address;
384
+ /** The address's code; written FIRST (it rewrites, or creates, the account). */
385
+ code?: Uint8Array;
386
+ /** A WHOLE account (history), replacing whatever is there. */
387
+ account?: Account;
388
+ /** Override fields, a read-modify-write on the account. */
389
+ balance?: bigint;
390
+ nonce?: bigint;
391
+ /** Clear the account's storage before `slots` are written. */
392
+ clearStorage: boolean;
393
+ /** Slot writes, keys 32 bytes, values in shortest form. */
394
+ slots: {key: Uint8Array; value: Uint8Array}[];
395
+ /** The account is ABSENT: emptied code, then deleted, as the LAST step. */
396
+ absent: boolean;
397
+ }
398
+
267
399
  /**
268
400
  * ONE SUBMITTED TRANSACTION, as the node carries it from `eth_sendRawTransaction*`
269
401
  * (or the `evm_*As` cheats) to the block it is mined in: the parsed transaction,
@@ -283,15 +415,143 @@ interface SubmittedTx {
283
415
  readonly sender: Address;
284
416
  }
285
417
 
418
+ /**
419
+ * Switches the node's INTERNAL machinery on that no {@link NodeOptions} field
420
+ * exposes yet. NOT exported from `src/index.ts`: only this package's own tests
421
+ * and the next tasks reach it.
422
+ */
423
+ export interface NodeInternals {
424
+ /**
425
+ * Record the per-block CHANGE SET (the open record of prior values; see the
426
+ * header of ./state-manager.ts). Off by default, and a node with it off
427
+ * records nothing and pays nothing. `stateHistory` turns it on (and RETAINS
428
+ * the records); `computeStateRoot: true` does too (the change set is the list of
429
+ * keys the derived trie rehashes, ./derived-trie.ts). This flag turns on
430
+ * recording alone, for the tests, through {@link createNodeWithInternals}.
431
+ */
432
+ recordChangeSets?: boolean;
433
+ }
434
+
435
+ /**
436
+ * What {@link changeSetsForTests} returns: the change set of the HEAD block
437
+ * (taken when it was mined) and the OPEN record (every write since), as live
438
+ * read-only references. `recording: false` and both `undefined` on a node that
439
+ * does not record.
440
+ */
441
+ export interface ChangeSetProbe {
442
+ recording: boolean;
443
+ /**
444
+ * The block numbers whose change set the node RETAINS as a sealed undo record
445
+ * (`stateHistory`), oldest first. Empty on a node without history.
446
+ */
447
+ sealedBlocks: readonly number[];
448
+ /** What the last MINED block changed, with each key's value at the end of the block before it. */
449
+ headBlock: ChangeSet | undefined;
450
+ /** Every write since the head was mined (cheats, a loaded baseline is cleared). */
451
+ open: ChangeSet | undefined;
452
+ }
453
+
454
+ const changeSetProbes = new WeakMap<SlimNode, () => ChangeSetProbe>();
455
+
456
+ /**
457
+ * TEST-ONLY ACCESSOR for a node's change sets, named as such: it hands out the
458
+ * node's own record objects (read-only by contract) so a test can hold them
459
+ * against the state it reads through the public surface. Not part of
460
+ * `SlimNode` (the worker proxy's shape test would otherwise demand it cross a
461
+ * comlink boundary) and not exported from `src/index.ts`.
462
+ */
463
+ export function changeSetsForTests(node: SlimNode): ChangeSetProbe {
464
+ const probe = changeSetProbes.get(node);
465
+ if (probe === undefined)
466
+ throw new Error(
467
+ 'webevm: changeSetsForTests() was handed an object createNode() did not return.',
468
+ );
469
+ return probe();
470
+ }
471
+
472
+ /**
473
+ * Validate {@link NodeOptions.stateHistory}: ABSENT (`undefined`) is off and
474
+ * returns `undefined`; `{blocks: N}` with N a positive safe integer returns N;
475
+ * anything else throws.
476
+ *
477
+ * It composes with `computeStateRoot: true`: every node runs on the same flat state,
478
+ * which is what the undo log records, and the derived trie only reads it. (It
479
+ * was refused there while trie mode, as a root-computing node was then
480
+ * called, ran on `MerkleStateManager`, which recorded
481
+ * nothing; `trie-derived-from-the-flat-state` lifted that.)
482
+ */
483
+ function validateStateHistory(options: NodeOptions): number | undefined {
484
+ if (options.stateHistory === undefined) return undefined;
485
+ const value = options.stateHistory as unknown;
486
+ const blocks =
487
+ typeof value === 'object' && value !== null
488
+ ? (value as {blocks?: unknown}).blocks
489
+ : undefined;
490
+ if (
491
+ typeof blocks !== 'number' ||
492
+ !Number.isSafeInteger(blocks) ||
493
+ blocks <= 0
494
+ )
495
+ throw new Error(
496
+ `webevm: stateHistory must be {blocks: N} with N a positive safe integer ` +
497
+ `(how many blocks below the head stay readable), or absent for no history; ` +
498
+ `got ${describeOption(value)}.`,
499
+ );
500
+ return blocks;
501
+ }
502
+
503
+ /**
504
+ * Validate {@link NodeOptions.genesisTimestamp}: ABSENT (`undefined`) returns
505
+ * `undefined` (block 0 takes the wall clock); a non-negative bigint returns
506
+ * itself; anything else throws. A NUMBER is refused rather than converted, even
507
+ * a whole one: every other timestamp the node takes (`blockEnv.timestamp`) is a
508
+ * bigint, and accepting both would make the option mean two types.
509
+ */
510
+ function validateGenesisTimestamp(options: NodeOptions): bigint | undefined {
511
+ if (options.genesisTimestamp === undefined) return undefined;
512
+ const value = options.genesisTimestamp as unknown;
513
+ if (typeof value !== 'bigint' || value < 0n)
514
+ throw new Error(
515
+ `webevm: genesisTimestamp must be a non-negative bigint (seconds since the ` +
516
+ `epoch, e.g. 1700000000n), or absent for the wall clock; got ` +
517
+ `${typeof value === 'bigint' ? `${value}n` : `${describeOption(value)} (${typeof value})`}.`,
518
+ );
519
+ return value;
520
+ }
521
+
522
+ function describeOption(value: unknown): string {
523
+ try {
524
+ const s = JSON.stringify(value);
525
+ return s === undefined ? String(value) : s;
526
+ } catch {
527
+ return String(value);
528
+ }
529
+ }
530
+
286
531
  export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
532
+ return createNodeWithInternals(options, {});
533
+ }
534
+
535
+ /** {@link createNode} with {@link NodeInternals}; internal, see there. */
536
+ export async function createNodeWithInternals(
537
+ options: NodeOptions,
538
+ internals: NodeInternals,
539
+ ): Promise<SlimNode> {
287
540
  const chainId = options.chainId ?? 31337;
288
- const stateMode = options.stateMode ?? 'none';
289
541
  const senderMode: SenderMode = options.senderMode ?? 'recover';
290
542
  const miningConfig = options.miningConfig ?? {type: 'auto'};
291
543
  const baseFeePerGas = options.baseFeePerGas ?? 1_000_000_000n;
292
544
  const gasPrice = options.gasPrice ?? 1_000_000_000n;
293
545
  const maxPriorityFeePerGas = options.maxPriorityFeePerGas ?? 1_000_000_000n;
294
546
  const blockGasLimit = options.blockGasLimit ?? 30_000_000n;
547
+ // Validated before anything is built, so a bad option costs nothing.
548
+ const stateHistoryBlocks = validateStateHistory(options);
549
+ const genesisTimestamp = validateGenesisTimestamp(options);
550
+ /**
551
+ * `computeStateRoot: true`: derive a trie from the flat state, report its
552
+ * root. Only `true` turns it on (see {@link NodeOptions.computeStateRoot}).
553
+ */
554
+ const computeStateRoot = options.computeStateRoot === true;
295
555
 
296
556
  const common = new Common({
297
557
  chain: {...Mainnet, chainId, name: 'webevm'},
@@ -299,17 +559,63 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
299
559
  customCrypto: {keccak256: (m: Uint8Array) => keccak_256(m)},
300
560
  });
301
561
 
302
- // State backing: SimpleStateManager (no trie, fast — default) or
303
- // MerkleStateManager (real trie + state root — opt-in, slower, conformance-able).
304
- // The 'none' manager is our SUBCLASS: storage is per-account with per-checkpoint
305
- // OVERLAYS (upstream copies the whole flat storage map on every message frame),
306
- // and it implements the `clearStorage(address)` that upstream ships as an empty
307
- // no-op — without which a contract created at an address that already holds
308
- // storage inherits it. See ./state-manager.ts.
309
- const sm =
310
- stateMode === 'trie'
311
- ? new MerkleStateManager()
312
- : new OverlayStorageStateManager();
562
+ // State backing, ONE for every node: our `SimpleStateManager` SUBCLASS, plain
563
+ // Maps with no trie. Storage is per-account with per-checkpoint OVERLAYS
564
+ // (upstream copies the whole flat storage map on every message frame), and it
565
+ // implements the `clearStorage(address)` that upstream ships as an empty no-op,
566
+ // without which a contract created at an address that already holds storage
567
+ // inherits it. See ./state-manager.ts. `computeStateRoot` does NOT change it:
568
+ // it adds a trie DERIVED from this state (`derivedTrie` below), which no engine
569
+ // ever reads.
570
+ const sm = new OverlayStorageStateManager();
571
+
572
+ // THE CHANGE SET, switched on BEFORE the first write so that the construction
573
+ // baselines below really go through the recorder and really get cleared when
574
+ // genesis is stored (a baseline left in the record would reconstruct EMPTY
575
+ // state at genesis). `changeSets` is the manager when recording, else
576
+ // `undefined`, so every use below is one optional call.
577
+ let changeSets: OverlayStorageStateManager | undefined;
578
+ if (
579
+ internals.recordChangeSets ||
580
+ stateHistoryBlocks !== undefined ||
581
+ computeStateRoot
582
+ ) {
583
+ sm.enableChangeSets();
584
+ changeSets = sm;
585
+ }
586
+ /**
587
+ * The change set of the HEAD block, taken from the open record when the block
588
+ * was mined. With `stateHistory` it is also the newest entry of {@link sealed};
589
+ * this slot is what the test probe reports as `headBlock`, with or without it.
590
+ */
591
+ let headBlockChangeSet: ChangeSet | undefined;
592
+ /**
593
+ * THE UNDO LOG (`stateHistory`): the SEALED change set of each of the last N
594
+ * mined blocks, oldest first. `sealed[i].changes` holds, for every key block
595
+ * `sealed[i].number` changed, the value it had at the END of the block before.
596
+ * Appended in `executeAndMine`, evicted there (anything at or below `head - N`
597
+ * serves no block in the window), and cleared by `loadState`. Always empty on a
598
+ * node without the option. See {@link historicalValue} for how a read uses it,
599
+ * and `docs/adr/0013-bounded-state-history-is-an-undo-log-over-the-flat-state.md`
600
+ * for why it is an undo log.
601
+ */
602
+ const sealed: {number: number; changes: ChangeSet}[] = [];
603
+ /**
604
+ * The oldest block whose state the undo log can reconstruct, WHATEVER the
605
+ * window: genesis at construction, the loaded head after `loadState` (a loaded
606
+ * dump is a baseline and carries no history). The window's oldest servable
607
+ * block is the later of this and `head - N`.
608
+ */
609
+ let historyFloor = 0;
610
+ /**
611
+ * Run a PURE READ (`eth_call`, `eth_estimateGas`, `eth_fillTransaction`'s
612
+ * estimate, with or without state overrides) with change-set recording
613
+ * suspended: every level it opens is reverted, so recording there is wasted
614
+ * work. A cost rule; see `withChangeSetsSuspended` in ./state-manager.ts.
615
+ */
616
+ function pureRead<T>(read: () => Promise<T>): Promise<T> {
617
+ return changeSets ? changeSets.withChangeSetsSuspended(read) : read();
618
+ }
313
619
 
314
620
  /**
315
621
  * THE SERIALISATION POINT: the tail of a promise chain that every public entry
@@ -421,30 +727,36 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
421
727
  return run;
422
728
  }
423
729
 
424
- // Touched-account set for the trie-mode dump (storage is read back via the
425
- // trie's own dumpStorage). We record the addresses each tx touches at the NODE
426
- // level (sender / to / created) rather than monkeypatching the state manager —
427
- // MerkleStateManager's cache/flush path is sensitive to method wrapping.
428
- const touchedAccounts = new Set<string>();
730
+ /**
731
+ * THE DERIVED TRIE (`computeStateRoot: true` only; `undefined`, and never created,
732
+ * otherwise). Built from the WHOLE flat state once the genesis baselines are
733
+ * written and again at the end of `loadState`, and kept current from change
734
+ * sets by {@link currentStateRoot}. See ./derived-trie.ts.
735
+ */
736
+ let derivedTrie: DerivedStateTrie | undefined;
429
737
 
430
738
  const ZERO_ROOT = ZERO_HASH;
739
+ /**
740
+ * The state root of the flat state AS IT STANDS: the derived trie brought up
741
+ * to date with the OPEN RECORD (every key written since the head was mined)
742
+ * and its root read. Called at the end of each mined block, BEFORE the block's
743
+ * record is taken (so the block's own writes are in it), and by
744
+ * `getStateRoot()` for cheats since the head. Applying the open record twice
745
+ * (a `getStateRoot()`, then the block that includes the same writes) is
746
+ * harmless: the record only NAMES keys, and their values are re-read from the
747
+ * flat state each time. Both callers run inside the serialisation point with
748
+ * no checkpoint open, which the trie insists on. Without
749
+ * `computeStateRoot`: the zero placeholder, and no trie work at all.
750
+ */
431
751
  async function currentStateRoot(): Promise<string> {
432
- if (stateMode !== 'trie') return ZERO_ROOT;
433
- const msm = sm as MerkleStateManager;
434
- await msm.flush(); // write cached trie nodes before reading the root
435
- return hex(await msm.getStateRoot());
436
- }
437
-
438
- // Flush cache into the trie after a direct state mutation (trie mode only) so
439
- // the next getStateRoot() reflects it. No-op in 'none' mode (the Map IS state).
440
- async function commitIfTrie(): Promise<void> {
441
- if (stateMode !== 'trie') return;
442
- await sm.checkpoint();
443
- await sm.commit();
752
+ if (derivedTrie === undefined) return ZERO_ROOT;
753
+ const open = sm.peekChangeSet();
754
+ if (open !== undefined) await derivedTrie.apply(open);
755
+ return hex(derivedTrie.root());
444
756
  }
445
757
 
446
758
  // Read-modify-write an account (creating an empty one if absent), used by the
447
- // evm_set* cheat methods. Commits into the trie in trie mode.
759
+ // evm_set* cheat methods.
448
760
  async function mutateAccount(
449
761
  addr: ReturnType<typeof createAddressFromString>,
450
762
  fn: (acc: Account) => void,
@@ -452,13 +764,11 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
452
764
  const acc = (await sm.getAccount(addr)) ?? new Account();
453
765
  fn(acc);
454
766
  await sm.putAccount(addr, acc);
455
- touchedAccounts.add(addr.toString());
456
- await commitIfTrie();
457
767
  }
458
768
 
459
769
  // Minimal mock blockchain: `runTx` (inside the default engine) only needs
460
- // getBlock (for BLOCKHASH) + shallowCopy. In 'none' mode we never compute a
461
- // canonical state root.
770
+ // getBlock (for BLOCKHASH) + shallowCopy. Without `computeStateRoot` we never
771
+ // compute a canonical state root.
462
772
  const blockStore = new Map<number, StoredBlock>();
463
773
  const blockByHash = new Map<string, number>();
464
774
  const receipts = new Map<string, SerializedReceipt>();
@@ -505,7 +815,6 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
505
815
  await connectEngine(engine, {
506
816
  stateManager: sm,
507
817
  common,
508
- stateMode,
509
818
  // Block hashes for BLOCKHASH, read LIVE (no block exists yet at this point)
510
819
  // and SYNCHRONOUSLY, because an engine answers BLOCKHASH mid-opcode.
511
820
  getBlockHash: (blockNumber: bigint) => {
@@ -529,15 +838,14 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
529
838
  let latestNumber = 0;
530
839
  let parentHash = hexToBytes(ZERO_HASH);
531
840
 
532
- // Initial balances FIRST (so the genesis state root, in trie mode, reflects them).
841
+ // Initial balances FIRST (so the genesis state root, when computed, reflects them).
533
842
  if (options.initialBalances) {
534
843
  for (const [addr, bal] of Object.entries(options.initialBalances)) {
535
844
  await sm.putAccount(createAddressFromString(addr), new Account(0n, bal));
536
- touchedAccounts.add(createAddressFromString(addr).toString());
537
845
  }
538
846
  }
539
847
  // Full genesis pre-state (balance/nonce/code/storage) — e.g. a GeneralStateTest
540
- // `pre` section. Applied before block 0 so the trie-mode genesis root reflects
848
+ // `pre` section. Applied before block 0 so a computed genesis root reflects
541
849
  // it and a post-tx getStateRoot() can be compared to the fixture's hash.
542
850
  if (options.initialState) {
543
851
  for (const [addr, acc] of Object.entries(options.initialState)) {
@@ -555,14 +863,13 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
555
863
  hexToBytes(val),
556
864
  );
557
865
  }
558
- touchedAccounts.add(address.toString());
559
- }
560
- // Commit the cache into the trie so the genesis root is correct in trie mode.
561
- if (stateMode === 'trie') {
562
- await sm.checkpoint();
563
- await sm.commit();
564
866
  }
565
867
  }
868
+ // THE TRIE IS BUILT FROM THE FULL FLAT STATE, here, once: the baselines above
869
+ // are block 0 and deliberately in NO change set (the record is cleared just
870
+ // after genesis is stored), so a trie kept from change sets alone would omit
871
+ // them and every genesis-dependent root would be wrong.
872
+ if (computeStateRoot) derivedTrie = await DerivedStateTrie.build(sm, common);
566
873
 
567
874
  const blockEnv = options.blockEnv;
568
875
 
@@ -595,13 +902,16 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
595
902
  // `number`, `timestamp` and `gasLimit` stay the node's own: genesis IS block 0,
596
903
  // and `blockEnv.number` places a MINED block rather than renumbering the chain's
597
904
  // genesis (`minedBlockGasLimit` above is likewise the MINED block's limit).
905
+ // Its timestamp is `genesisTimestamp` when given, else the wall clock: a
906
+ // separate option rather than `blockEnv.timestamp`, which pins every MINED
907
+ // block to one value and so cannot also be block 0's (see the option's JSDoc).
598
908
  const genesis = createBlock(
599
909
  {
600
910
  header: {
601
911
  number: 0n,
602
912
  gasLimit: blockGasLimit,
603
913
  baseFeePerGas,
604
- timestamp: BigInt(Math.floor(Date.now() / 1000)),
914
+ timestamp: genesisTimestamp ?? BigInt(Math.floor(Date.now() / 1000)),
605
915
  ...(blockEnv?.coinbase
606
916
  ? {coinbase: createAddressFromString(blockEnv.coinbase)}
607
917
  : {}),
@@ -614,6 +924,9 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
614
924
  {common},
615
925
  );
616
926
  storeBlock(genesis, [], [], await currentStateRoot());
927
+ // BASELINES ARE NOT HISTORY: `initialBalances` / `initialState` ARE block 0,
928
+ // not a change to it.
929
+ changeSets?.takeChangeSet();
617
930
 
618
931
  // Pending raw txs awaiting the next mined block (manual/interval modes). Each
619
932
  // carries its SENDER, decided once at parse time by `parseTx`: the node derives
@@ -749,13 +1062,6 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
749
1062
  const from = sender.toString();
750
1063
  const to = (tx as any).to ? (tx as any).to.toString() : null;
751
1064
  const created = res.createdAddress ? hex(res.createdAddress) : null;
752
- // Track touched accounts for the trie-mode dump (sender, recipient, created,
753
- // and any account that emitted a log — that set covers what changed).
754
- touchedAccounts.add(from);
755
- if (to) touchedAccounts.add(to);
756
- if (created) touchedAccounts.add(created);
757
- for (const log of res.logs) touchedAccounts.add(hex(log.address));
758
-
759
1065
  const rcptLogs: SerializedLog[] = res.logs.map((log, i) => {
760
1066
  const sl: SerializedLog = {
761
1067
  address: hex(log.address),
@@ -821,13 +1127,45 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
821
1127
  }
822
1128
 
823
1129
  allLogs.push(...blockLogs);
1130
+ // The root BEFORE the record is taken below: `currentStateRoot` applies the
1131
+ // open record, which at this point is exactly what this block changed.
824
1132
  storeBlock(block, txHashes, blockLogs, await currentStateRoot());
1133
+ // THE BLOCK'S CHANGE SET is everything written since the previous head was
1134
+ // mined: this block's transactions AND any `evm_set*` cheat issued between
1135
+ // the two blocks, which belongs to this block (the first one that can see
1136
+ // it). Taken with no checkpoint open, which `takeChangeSet` insists on.
1137
+ if (changeSets) headBlockChangeSet = changeSets.takeChangeSet();
1138
+ if (stateHistoryBlocks !== undefined && headBlockChangeSet !== undefined)
1139
+ sealBlock(blockNumber, headBlockChangeSet, stateHistoryBlocks);
825
1140
  // emit newHeads
826
1141
  for (const cb of headSubs) cb({number: blockNumber, hash: blockHash});
827
1142
 
828
1143
  return {blockNumber, blockHash, txHashes};
829
1144
  }
830
1145
 
1146
+ /**
1147
+ * SEAL the change set just taken as block `number`'s undo record, and EVICT
1148
+ * every record at or below `head - N`: a read at the oldest servable block
1149
+ * `head - N` needs the records of blocks `head - N + 1 .. head` and no other,
1150
+ * so exactly N are kept.
1151
+ *
1152
+ * A block MINED UNDER THE SAME NUMBER as the newest record (a fixed
1153
+ * `blockEnv.number` does that: every mined block replaces the head) is MERGED
1154
+ * into it, the older entry winning, as a checkpoint commit merges: the merged
1155
+ * record then holds each key's value from before the first of them, which is
1156
+ * what a read below that number needs, and the log stays bounded.
1157
+ */
1158
+ function sealBlock(number: number, changes: ChangeSet, window: number): void {
1159
+ const newest = sealed[sealed.length - 1];
1160
+ if (newest !== undefined && newest.number === number)
1161
+ mergeChangeSetOlderWins(newest.changes, changes);
1162
+ else sealed.push({number, changes});
1163
+ const oldestKept = latestNumber - window;
1164
+ let drop = 0;
1165
+ while (drop < sealed.length && sealed[drop].number <= oldestKept) drop++;
1166
+ if (drop > 0) sealed.splice(0, drop);
1167
+ }
1168
+
831
1169
  async function mineBlock() {
832
1170
  const batch = pending.splice(0, pending.length);
833
1171
  return executeAndMine(batch);
@@ -1143,7 +1481,28 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
1143
1481
  return r ? receiptToRpc(r) : null;
1144
1482
  }
1145
1483
 
1484
+ /**
1485
+ * The nonce `address` sends with next: its account nonce, advanced past each
1486
+ * CONTIGUOUS queued transaction of its own (manual/interval mining; the queue
1487
+ * is always empty under auto mining). Contiguous, as geth counts it: a queued
1488
+ * nonce beyond a gap does not advance it, because that transaction will not
1489
+ * execute until the gap is filled.
1490
+ */
1491
+ async function pendingNonce(address: Address): Promise<bigint> {
1492
+ let n = (await sm.getAccount(address))?.nonce ?? 0n;
1493
+ const queued = new Set<bigint>();
1494
+ for (const q of pending)
1495
+ if (q.sender.equals(address)) queued.add(q.tx.nonce);
1496
+ while (queued.has(n)) n++;
1497
+ return n;
1498
+ }
1499
+
1146
1500
  // ---------- block lookup helpers ----------
1501
+ /**
1502
+ * A block TAG or NUMBER as a block number. A string that is neither is a
1503
+ * -32602, not a JavaScript `SyntaxError` escaping from `BigInt` (which is what
1504
+ * `eth_getBlockByNumber('yesterday')` used to throw), and not a silent `latest`.
1505
+ */
1147
1506
  function resolveBlockTag(tag: unknown): number {
1148
1507
  if (
1149
1508
  tag === 'latest' ||
@@ -1154,9 +1513,285 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
1154
1513
  )
1155
1514
  return latestNumber;
1156
1515
  if (tag === 'earliest') return 0;
1157
- if (typeof tag === 'string') return Number(BigInt(tag));
1158
- if (typeof tag === 'number') return tag;
1159
- return latestNumber;
1516
+ // A 32-byte hex string is a block HASH, which this parameter does not take:
1517
+ // read as a number it would be ~1e76 and look like "far above the head".
1518
+ if (typeof tag === 'string' && /^0x[0-9a-fA-F]{64}$/.test(tag))
1519
+ throw new RpcError(
1520
+ -32602,
1521
+ `invalid block parameter: ${tag} is a block hash, and this parameter takes a block number or tag.`,
1522
+ );
1523
+ if (typeof tag === 'string' && /^0x[0-9a-fA-F]+$/.test(tag))
1524
+ return Number(BigInt(tag));
1525
+ if (typeof tag === 'number' && Number.isSafeInteger(tag) && tag >= 0)
1526
+ return tag;
1527
+ throw new RpcError(
1528
+ -32602,
1529
+ `invalid block parameter: ${JSON.stringify(tag)}. Expected a block tag (latest, pending, safe, finalized, earliest) or a hex block number.`,
1530
+ );
1531
+ }
1532
+
1533
+ /**
1534
+ * THE GATE FOR EVERY STATE READ AT A BLOCK: `undefined` when the parameter
1535
+ * names the head (read or execute live), the block number K when it names a
1536
+ * block in the `stateHistory` window (served from the undo log), and a refusal
1537
+ * otherwise. Every method that reads STATE at a block (`eth_call`,
1538
+ * `eth_estimateGas`, `eth_getBalance`, `eth_getCode`, `eth_getStorageAt`,
1539
+ * `eth_getTransactionCount`) calls this with its block parameter BEFORE
1540
+ * touching state.
1541
+ *
1542
+ * ## Why this exists
1543
+ *
1544
+ * Those methods used to ignore the block parameter entirely and answer from the
1545
+ * live state, while `eth_getLogs` and `eth_getBlockByNumber` honoured theirs. A
1546
+ * client that pins a PAIR of reads to one block so they describe the same moment
1547
+ * (logs up to block N, and a view call at block N) got logs as of N and storage
1548
+ * as of the head: a position whose move it could not find, with no error. That is
1549
+ * a different answer from every other node, delivered silently, which is the one
1550
+ * outcome that is not acceptable. (This gate was `requireHeadState` while the
1551
+ * node served the head only.)
1552
+ *
1553
+ * ## What the node holds: the head, plus an OPT-IN undo log
1554
+ *
1555
+ * This node holds ONE state: the live one. On every node the
1556
+ * state manager's checkpoint/overlay stack is the journal of the execution in
1557
+ * flight, not a history of blocks. Without `stateHistory` nothing of block N
1558
+ * survives the mining of N+1, and the honest answer to "what was the state at
1559
+ * N" is "not available here".
1560
+ *
1561
+ * WITH `stateHistory: {blocks: N}` the node keeps, per mined block, the value
1562
+ * every key the block changed had BEFORE it (the sealed change sets, an undo
1563
+ * log over the one flat state; see
1564
+ * `docs/adr/0013-bounded-state-history-is-an-undo-log-over-the-flat-state.md`).
1565
+ * The four POINT reads at a block K in the window are answered from it by
1566
+ * {@link historicalValue} with no state manager involvement and no checkpoint.
1567
+ * `eth_call` and `eth_estimateGas` at K EXECUTE: the same records, as K's
1568
+ * state, are written into a checkpoint the request opens and reverts
1569
+ * ({@link historicalEntries}, {@link withStateEntries}), and the engine runs
1570
+ * with K's stored `Block`. That SUPERSEDES the reasoning this comment used to
1571
+ * give for refusing all history (retained copies, or swapping a shared state
1572
+ * manager's root under a read): an undo log needs neither.
1573
+ *
1574
+ * ## What is served, and what is refused
1575
+ *
1576
+ * - SERVED: `latest`, `pending`, `safe`, `finalized`, an absent parameter, and a
1577
+ * number, hash or EIP-1898 `{blockNumber}` / `{blockHash}` object that names
1578
+ * the HEAD block. Pinning to the block you just read is the common case and it
1579
+ * is almost always the head, so it must keep working. (`pending` is the head
1580
+ * because in `manual`/`interval` mining the queued transactions have not
1581
+ * executed yet and this node has no speculative pending state; the one
1582
+ * exception is `eth_getTransactionCount`, which adds the sender's queued
1583
+ * transactions so that two sends before a mine get two nonces. `safe` and
1584
+ * `finalized` are the head because a local chain has no reorgs.) `earliest`
1585
+ * is served while block 0 is the head or in the window.
1586
+ * - SERVED FROM HISTORY: any block from {@link oldestServableBlock} up to the
1587
+ * head, named any of those ways, by all six methods.
1588
+ * - REFUSED, -32000 `historical state not available`: a block below the oldest
1589
+ * servable one (with no `stateHistory`, that is every block below the head),
1590
+ * with a message naming the oldest servable block and the `stateHistory`
1591
+ * option. The same code geth uses for pruned state (`missing trie node`).
1592
+ * - REFUSED, -32000 `header not found`: a number above the head, a hash no
1593
+ * block has (geth's exact wording for both), or a number between two blocks
1594
+ * of a chain whose numbering jumps.
1595
+ * - REFUSED, -32602: a parameter that is not a block at all.
1596
+ *
1597
+ * THE STATE AT THE HEAD INCLUDES `evm_set*` CHEATS applied since it was mined,
1598
+ * exactly as `latest` always has: those mutate live state without a block. They
1599
+ * are in the OPEN record, which a read below the head consults after the sealed
1600
+ * ones, so they are visible at the head and at no older block.
1601
+ */
1602
+ function historicalBlock(
1603
+ blockParam: unknown,
1604
+ method: string,
1605
+ ): number | undefined {
1606
+ const number = pinnedBlockNumber(blockParam, method);
1607
+ if (number === latestNumber) return undefined;
1608
+ const oldest = oldestServableBlock();
1609
+ if (number < oldest) throw beyondHistory(method, number, oldest);
1610
+ // Numbering has gaps only under a `blockEnv.number` that jumps; a number
1611
+ // between two blocks names no block, and is not answered as if it did.
1612
+ if (!blockStore.has(number))
1613
+ throw new RpcError(
1614
+ -32000,
1615
+ `header not found: ${method} was pinned to block ${number}, which this node never mined.`,
1616
+ );
1617
+ return number;
1618
+ }
1619
+
1620
+ /**
1621
+ * The oldest block whose state a point read can be answered at: the head
1622
+ * without `stateHistory`; with it, `head - N`, but never below where the undo
1623
+ * log starts ({@link historyFloor}: genesis, or the head a state was loaded at).
1624
+ */
1625
+ function oldestServableBlock(): number {
1626
+ if (stateHistoryBlocks === undefined) return latestNumber;
1627
+ return Math.max(historyFloor, latestNumber - stateHistoryBlocks, 0);
1628
+ }
1629
+
1630
+ /** The refusal for a block older than {@link oldestServableBlock}. */
1631
+ function beyondHistory(
1632
+ method: string,
1633
+ number: number,
1634
+ oldest: number,
1635
+ ): RpcError {
1636
+ const holds =
1637
+ stateHistoryBlocks === undefined
1638
+ ? `but the oldest block whose state this node holds is block ${oldest}, its head, because it was created without stateHistory. ` +
1639
+ `Create the node with stateHistory: {blocks: N} to keep the last N blocks readable, or pin to the head (or 'latest') instead.`
1640
+ : `but the oldest block whose state this node holds is block ${oldest} (head ${latestNumber}, stateHistory: {blocks: ${stateHistoryBlocks}}` +
1641
+ (oldest > latestNumber - stateHistoryBlocks
1642
+ ? `; history starts at block ${oldest}, where this node's state was loaded`
1643
+ : '') +
1644
+ `). Pin to a block in that window, or widen stateHistory.blocks.`;
1645
+ return new RpcError(
1646
+ -32000,
1647
+ `historical state not available: ${method} was pinned to block ${number}, ${holds} ` +
1648
+ `It REFUSES rather than answer from a later state than the one you asked for; logs and blocks remain queryable at any height.`,
1649
+ );
1650
+ }
1651
+
1652
+ /**
1653
+ * THE BLOCK NUMBER a state read's block parameter names (the head for a tag),
1654
+ * refusing what is not a block (-32602), a hash no block has and a number above
1655
+ * the head (-32000 `header not found`).
1656
+ */
1657
+ function pinnedBlockNumber(blockParam: unknown, method: string): number {
1658
+ if (
1659
+ blockParam == null ||
1660
+ blockParam === 'latest' ||
1661
+ blockParam === 'pending' ||
1662
+ blockParam === 'safe' ||
1663
+ blockParam === 'finalized'
1664
+ )
1665
+ return latestNumber;
1666
+ let number: number | undefined;
1667
+ let hash: string | undefined;
1668
+ if (blockParam === 'earliest') number = 0;
1669
+ else if (typeof blockParam === 'number') number = blockParam;
1670
+ else if (typeof blockParam === 'string') {
1671
+ // A 32-byte hex string is a block HASH (geth accepts it bare, EIP-1898).
1672
+ if (/^0x[0-9a-fA-F]{64}$/.test(blockParam)) hash = blockParam;
1673
+ else if (/^0x[0-9a-fA-F]+$/.test(blockParam))
1674
+ number = Number(BigInt(blockParam));
1675
+ } else if (typeof blockParam === 'object') {
1676
+ const o = blockParam as {blockNumber?: unknown; blockHash?: unknown};
1677
+ // EIP-1898: exactly one of the two. geth refuses both at once, and so
1678
+ // does this node rather than silently preferring one.
1679
+ if (o.blockHash != null && o.blockNumber != null)
1680
+ throw new RpcError(
1681
+ -32602,
1682
+ `invalid block parameter for ${method}: pass blockHash or blockNumber, not both.`,
1683
+ );
1684
+ if (typeof o.blockHash === 'string') hash = o.blockHash;
1685
+ else if (typeof o.blockNumber === 'string') {
1686
+ if (o.blockNumber === 'earliest') number = 0;
1687
+ else if (/^0x[0-9a-fA-F]+$/.test(o.blockNumber))
1688
+ number = Number(BigInt(o.blockNumber));
1689
+ else return pinnedBlockNumber(o.blockNumber, method);
1690
+ }
1691
+ }
1692
+ if (hash !== undefined) {
1693
+ const n = blockByHash.get(hash.toLowerCase());
1694
+ if (n === undefined)
1695
+ throw new RpcError(
1696
+ -32000,
1697
+ `header not found: ${method} was pinned to block hash ${hash}, which no block on this node has.`,
1698
+ );
1699
+ number = n;
1700
+ }
1701
+ // A well-formed number too large to be a safe integer names a block far
1702
+ // above the head: that is "not found", not "not a block".
1703
+ if (number !== undefined && number > Number.MAX_SAFE_INTEGER)
1704
+ number = Number.MAX_SAFE_INTEGER;
1705
+ if (number === undefined || !Number.isSafeInteger(number) || number < 0)
1706
+ throw new RpcError(
1707
+ -32602,
1708
+ `invalid block parameter for ${method}: ${JSON.stringify(blockParam)}. ` +
1709
+ `Expected a block tag (latest, pending, safe, finalized, earliest), a hex block number, a block hash, or {blockNumber}/{blockHash}.`,
1710
+ );
1711
+ if (number > latestNumber)
1712
+ throw new RpcError(
1713
+ -32000,
1714
+ `header not found: ${method} was pinned to block ${number}, but the head of this node is block ${latestNumber}.`,
1715
+ );
1716
+ return number;
1717
+ }
1718
+
1719
+ /**
1720
+ * ONE KEY'S VALUE AT THE END OF BLOCK `k` (below the head, in the window): the
1721
+ * FIRST record naming the key among the sealed records of blocks `k+1 .. head`
1722
+ * (oldest first), then the OPEN record (writes since the head was mined:
1723
+ * cheats, and a batch that threw mid-block), else the live value. Each record
1724
+ * holds a key's value from before its block, so the first one after `k` that
1725
+ * names the key holds its value at the end of `k`; a key no record names has
1726
+ * not changed since `k`, so its live value is its value then.
1727
+ *
1728
+ * A PURE LOOKUP: no state manager write, no checkpoint, and nothing an engine
1729
+ * sees, which is why it is safe on both engines and needs nothing from the
1730
+ * serialisation point beyond running inside it (the dispatcher does). `pick`
1731
+ * returns `{value}` when the record names the key, `undefined` when it does
1732
+ * not; `live` reads the head.
1733
+ */
1734
+ async function historicalValue<T>(
1735
+ k: number,
1736
+ pick: (changes: ChangeSet) => {value: T} | undefined,
1737
+ live: () => Promise<T>,
1738
+ ): Promise<T> {
1739
+ for (const record of sealed) {
1740
+ if (record.number <= k) continue;
1741
+ const hit = pick(record.changes);
1742
+ if (hit !== undefined) return hit.value;
1743
+ }
1744
+ const open = changeSets?.peekChangeSet();
1745
+ const hit = open && pick(open);
1746
+ if (hit !== undefined) return hit.value;
1747
+ return live();
1748
+ }
1749
+
1750
+ /** The account at `k`, `undefined` if absent: see {@link historicalValue}. */
1751
+ function accountAt(
1752
+ k: number,
1753
+ address: Address,
1754
+ ): Promise<Account | undefined> {
1755
+ const key = address.toString();
1756
+ return historicalValue(
1757
+ k,
1758
+ (cs) =>
1759
+ cs.accounts.has(key) ? {value: cs.accounts.get(key)} : undefined,
1760
+ () => sm.getAccount(address),
1761
+ );
1762
+ }
1763
+
1764
+ /** The code at `k`, empty if none: see {@link historicalValue}. */
1765
+ function codeAt(k: number, address: Address): Promise<Uint8Array> {
1766
+ const key = address.toString();
1767
+ return historicalValue(
1768
+ k,
1769
+ (cs) =>
1770
+ cs.code.has(key)
1771
+ ? {value: cs.code.get(key) ?? new Uint8Array(0)}
1772
+ : undefined,
1773
+ () => sm.getCode(address),
1774
+ );
1775
+ }
1776
+
1777
+ /** One storage slot at `k`, empty if unset: see {@link historicalValue}. */
1778
+ function storageAt(
1779
+ k: number,
1780
+ address: Address,
1781
+ slot: Uint8Array,
1782
+ ): Promise<Uint8Array> {
1783
+ const addressKey = packAddressKey(address.bytes);
1784
+ const slotKey = packSlotKey(slot);
1785
+ return historicalValue(
1786
+ k,
1787
+ (cs) => {
1788
+ const slots = cs.storage.get(addressKey);
1789
+ return slots?.has(slotKey)
1790
+ ? {value: slots.get(slotKey) ?? new Uint8Array(0)}
1791
+ : undefined;
1792
+ },
1793
+ () => sm.getStorage(address, slot),
1794
+ );
1160
1795
  }
1161
1796
 
1162
1797
  /**
@@ -1169,7 +1804,7 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
1169
1804
  * a uniform zero, because nothing tells a consumer which side of the trip they
1170
1805
  * are on. Every value below is therefore one a dump carries.
1171
1806
  *
1172
- * `stateRoot` is the one REAL value among the roots (in `'trie'` mode);
1807
+ * `stateRoot` is the one REAL value among the roots (with `computeStateRoot: true`);
1173
1808
  * `sha3Uncles`, `transactionsRoot` and `receiptsRoot` stay honest zero
1174
1809
  * placeholders, named as such in the README, because this node builds no tries
1175
1810
  * over its transactions or receipts. `logsBloom` used to be in that list and is
@@ -1255,13 +1890,38 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
1255
1890
  };
1256
1891
  }
1257
1892
 
1893
+ /**
1894
+ * One log as RPC serves it, from `eth_getLogs` and inside receipts alike.
1895
+ *
1896
+ * `blockTimestamp` (execution-apis#639, served by geth, reth, besu, erigon,
1897
+ * anvil and Hardhat's EDR; some indexers refuse a log without it) is LOOKED UP
1898
+ * from the log's block here rather than stored on {@link SerializedLog}. The
1899
+ * block's header is the one source of truth for the timestamp, so a lookup
1900
+ * cannot disagree with `eth_getBlockBy*`, and the block store is only ever
1901
+ * cleared to be refilled by `loadState`. Storing it
1902
+ * instead would duplicate the value on every log, change the persisted dump's
1903
+ * shape, and leave a dump written without it needing a fallback to this very
1904
+ * lookup anyway; as it is, every dump, old or new, answers with it.
1905
+ */
1258
1906
  function logToRpc(l: SerializedLog) {
1907
+ const stored = blockStore.get(l.blockNumber);
1908
+ if (!stored) {
1909
+ // NOT unreachable today: when a manual/interval batch has a transaction
1910
+ // refused mid-batch, the receipts of the transactions before it are
1911
+ // already recorded, naming a block that is never stored (hole 2 of the
1912
+ // backlog task `two-remaining-holes-in-the-submit-and-mine-refusal-path`).
1913
+ // Such a receipt names a block that does not exist, so it is refused
1914
+ // loudly here rather than served without a timestamp, or with whatever
1915
+ // block later reuses the number. Closing that hole makes this unreachable.
1916
+ throw new Error(`log names block ${l.blockNumber}, which the node lacks`);
1917
+ }
1259
1918
  return {
1260
1919
  address: l.address,
1261
1920
  topics: l.topics,
1262
1921
  data: l.data,
1263
1922
  blockNumber: numHex(l.blockNumber),
1264
1923
  blockHash: l.blockHash,
1924
+ blockTimestamp: numHex(stored.header.timestamp),
1265
1925
  transactionHash: l.transactionHash,
1266
1926
  transactionIndex: numHex(l.transactionIndex),
1267
1927
  logIndex: numHex(l.logIndex),
@@ -1269,6 +1929,296 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
1269
1929
  };
1270
1930
  }
1271
1931
 
1932
+ /**
1933
+ * K'S STATE, AS STATE ENTRIES: for every key the undo log names after block
1934
+ * `k` (the sealed records of blocks `k+1 .. head`, then the OPEN record), the
1935
+ * value it had at the end of `k`, the earliest record winning per key, exactly
1936
+ * the lookup {@link historicalValue} makes for one key. A key no record names
1937
+ * has not changed since `k`, so the live state already holds it and it needs
1938
+ * no entry. O(keys changed since `k`), which is the cost of a historical
1939
+ * `eth_call` on top of the call itself.
1940
+ *
1941
+ * Written into a checkpoint by {@link withStateEntries}, so the engine
1942
+ * executes on K's state with no copy of state and no root swapped. An account
1943
+ * absent at `k` becomes an ABSENT entry, and an account whose storage was
1944
+ * cleared after `k` becomes a `clearStorage` entry: the clear recorded every
1945
+ * slot the account held at that moment, so the union holds every slot it
1946
+ * held at `k`, and clearing first also drops the slots written since.
1947
+ *
1948
+ * THE UNION IS BUILT FRESH. `mergeChangeSetOlderWins` is not reused here
1949
+ * because it CONSUMES its second argument (inner storage maps are handed over
1950
+ * whole), and these are the sealed records themselves, which a later read
1951
+ * still needs intact.
1952
+ */
1953
+ function historicalEntries(k: number): StateEntry[] {
1954
+ const accounts = new Map<string, Account | undefined>();
1955
+ const code = new Map<string, Uint8Array | undefined>();
1956
+ const storage = new Map<string, Map<string, Uint8Array | undefined>>();
1957
+ const cleared = new Set<string>();
1958
+ const take = (cs: ChangeSet) => {
1959
+ for (const [key, value] of cs.accounts)
1960
+ if (!accounts.has(key)) accounts.set(key, value);
1961
+ for (const [key, value] of cs.code)
1962
+ if (!code.has(key)) code.set(key, value);
1963
+ for (const [addressKey, slots] of cs.storage) {
1964
+ let target = storage.get(addressKey);
1965
+ if (target === undefined) {
1966
+ target = new Map();
1967
+ storage.set(addressKey, target);
1968
+ }
1969
+ for (const [slotKey, value] of slots)
1970
+ if (!target.has(slotKey)) target.set(slotKey, value);
1971
+ }
1972
+ for (const addressKey of cs.storageCleared) cleared.add(addressKey);
1973
+ };
1974
+ for (const record of sealed) if (record.number > k) take(record.changes);
1975
+ const open = changeSets?.peekChangeSet();
1976
+ if (open) take(open);
1977
+
1978
+ // One entry per address, keyed as `address.toString()` gives it (the
1979
+ // account and code maps' key; `unpackAddressKey` yields the same form).
1980
+ const entries = new Map<string, StateEntry>();
1981
+ const entry = (key: string): StateEntry => {
1982
+ let e = entries.get(key);
1983
+ if (e === undefined) {
1984
+ e = {
1985
+ address: createAddressFromString(key),
1986
+ clearStorage: false,
1987
+ slots: [],
1988
+ absent: false,
1989
+ };
1990
+ entries.set(key, e);
1991
+ }
1992
+ return e;
1993
+ };
1994
+ for (const [key, account] of accounts) {
1995
+ const e = entry(key);
1996
+ if (account === undefined) e.absent = true;
1997
+ // A COPY: the engine is handed the object through the state manager, and
1998
+ // the sealed record must go on saying what the account was.
1999
+ else e.account = copyAccount(account);
2000
+ }
2001
+ for (const [key, value] of code)
2002
+ entry(key).code = value ?? new Uint8Array(0);
2003
+ for (const addressKey of cleared)
2004
+ entry(unpackAddressKey(addressKey)).clearStorage = true;
2005
+ for (const [addressKey, slots] of storage) {
2006
+ const e = entry(unpackAddressKey(addressKey));
2007
+ for (const [slotKey, value] of slots)
2008
+ e.slots.push({
2009
+ key: hexToBytes(unpackSlotKey(slotKey)),
2010
+ value: value ?? new Uint8Array(0),
2011
+ });
2012
+ }
2013
+ return [...entries.values()];
2014
+ }
2015
+
2016
+ /**
2017
+ * PARSE geth-STYLE STATE OVERRIDES into {@link StateEntry}s. `eth_call` and
2018
+ * `eth_estimateGas` take them as their third parameter:
2019
+ * `{[address]: {balance?, nonce?, code?, state?, stateDiff?}}`, where `state`
2020
+ * REPLACES the account's whole storage and `stateDiff` patches individual
2021
+ * slots. They used to be ignored, which answered a question the caller had not
2022
+ * asked, with no error.
2023
+ *
2024
+ * PARSED BEFORE ANY LEVEL IS OPENED, into values that cannot fail to apply, so
2025
+ * a malformed override is a -32602 naming it (never a raw `SyntaxError` from
2026
+ * `BigInt`), and a refusal never has a half-applied override to unwind.
2027
+ *
2028
+ * ## What is refused
2029
+ *
2030
+ * `state` and `stateDiff` on the same account (geth refuses that too), and any
2031
+ * field this node does not implement (`movePrecompileToAddress`, for one): a
2032
+ * -32602 naming it, never a call run without it.
2033
+ */
2034
+ function parseStateOverrides(
2035
+ overrides: unknown,
2036
+ method: string,
2037
+ ): StateEntry[] {
2038
+ if (overrides == null) return [];
2039
+ if (typeof overrides !== 'object' || Array.isArray(overrides))
2040
+ throw new RpcError(
2041
+ -32602,
2042
+ `invalid state overrides for ${method}: expected an object keyed by address.`,
2043
+ );
2044
+ const supported = new Set([
2045
+ 'balance',
2046
+ 'nonce',
2047
+ 'code',
2048
+ 'state',
2049
+ 'stateDiff',
2050
+ ]);
2051
+ const bad = (what: string): never => {
2052
+ throw new RpcError(
2053
+ -32602,
2054
+ `invalid state override in ${method}: ${what}.`,
2055
+ );
2056
+ };
2057
+ const quantity = (v: unknown, what: string): bigint => {
2058
+ if (typeof v !== 'string' || !/^0x[0-9a-fA-F]+$/.test(v))
2059
+ return bad(`${what} must be a hex quantity, got ${JSON.stringify(v)}`);
2060
+ const n = BigInt(v);
2061
+ // A 32-byte word is the widest thing any override field names.
2062
+ if (n >= 1n << 256n) return bad(`${what} does not fit in 32 bytes`);
2063
+ return n;
2064
+ };
2065
+ const data = (v: unknown, what: string): Uint8Array => {
2066
+ if (typeof v !== 'string' || !/^0x([0-9a-fA-F]{2})*$/.test(v))
2067
+ return bad(`${what} must be even-length hex, got ${JSON.stringify(v)}`);
2068
+ return hexToBytes(v);
2069
+ };
2070
+ return Object.entries(overrides as Record<string, any>).map(
2071
+ ([addr, o]): StateEntry => {
2072
+ if (o == null || typeof o !== 'object' || Array.isArray(o))
2073
+ return bad(`the override for ${addr} must be an object`);
2074
+ for (const k of Object.keys(o))
2075
+ if (!supported.has(k))
2076
+ throw new RpcError(
2077
+ -32602,
2078
+ `state override field not supported by this node: ${addr}.${k} in ${method}. ` +
2079
+ `Supported: balance, nonce, code, state, stateDiff.`,
2080
+ );
2081
+ if (o.state != null && o.stateDiff != null)
2082
+ throw new RpcError(
2083
+ -32602,
2084
+ `account ${addr} has both 'state' and 'stateDiff' in ${method}; pass one.`,
2085
+ );
2086
+ let address: Address;
2087
+ try {
2088
+ address = createAddressFromString(addr);
2089
+ } catch {
2090
+ return bad(`${JSON.stringify(addr)} is not an address`);
2091
+ }
2092
+ const slotsIn = o.state ?? o.stateDiff;
2093
+ if (
2094
+ slotsIn != null &&
2095
+ (typeof slotsIn !== 'object' || Array.isArray(slotsIn))
2096
+ )
2097
+ return bad(
2098
+ `${addr}.${o.state != null ? 'state' : 'stateDiff'} must be an object of slot -> value`,
2099
+ );
2100
+ const slots = Object.entries(slotsIn ?? {}).map(([slot, val]) => {
2101
+ const value = data(val, `${addr} slot ${slot}`);
2102
+ // A slot value is ONE word: a longer one would be silently truncated
2103
+ // to its low 32 bytes by the padding below, so it is refused.
2104
+ if (value.length > 32)
2105
+ return bad(`${addr} slot ${slot} value is longer than 32 bytes`);
2106
+ return {
2107
+ key: setLengthLeft(
2108
+ bigIntToBytes(quantity(slot, `${addr} slot key`)),
2109
+ 32,
2110
+ ),
2111
+ // SHORTEST FORM, as the EVM itself stores a value: a padded zero
2112
+ // and a missing slot must be the same thing to SSTORE's gas rules.
2113
+ value: unpadBytes(setLengthLeft(value, 32)),
2114
+ };
2115
+ });
2116
+ return {
2117
+ address,
2118
+ balance:
2119
+ o.balance != null
2120
+ ? quantity(o.balance, `${addr}.balance`)
2121
+ : undefined,
2122
+ nonce:
2123
+ o.nonce != null ? quantity(o.nonce, `${addr}.nonce`) : undefined,
2124
+ code: o.code != null ? data(o.code, `${addr}.code`) : undefined,
2125
+ clearStorage: o.state != null,
2126
+ slots,
2127
+ absent: false,
2128
+ };
2129
+ },
2130
+ );
2131
+ }
2132
+
2133
+ /**
2134
+ * RUN A READ WITH STATE ENTRIES WRITTEN INTO A CHECKPOINT IT OPENS, and leave
2135
+ * no trace of them. The entries are K's state for a historical call
2136
+ * ({@link historicalEntries}) followed by the caller's state overrides
2137
+ * ({@link parseStateOverrides}), so the overrides land ON TOP of K's state,
2138
+ * as geth applies them on top of the block's. With no entries (a call at the
2139
+ * head without overrides) no level is opened at all.
2140
+ *
2141
+ * ## Why a checkpoint here is safe, given the hazard documented at `serialise`
2142
+ *
2143
+ * The corruption described there needs two executions to interleave on the one
2144
+ * checkpoint stack. This level is opened and closed by the SAME request, inside
2145
+ * the serialisation point, with the read nested strictly inside it: the default
2146
+ * engine's own checkpoint/revert lands on top of this one and pops before this
2147
+ * one does, and revm reads the top of the stack on every access and never
2148
+ * commits. So the stack is `[base, entries, (call)]` and unwinds in order,
2149
+ * whether the read returns, reverts or throws (the `finally`). It is also the
2150
+ * same mechanism `evmCall` already relies on for purity, one level lower. The
2151
+ * derived trie of a `computeStateRoot` node is never involved: change-set recording is
2152
+ * suspended for the read and the level is reverted, so nothing it wrote is
2153
+ * ever named to the trie.
2154
+ */
2155
+ async function withStateEntries<T>(
2156
+ entries: readonly StateEntry[],
2157
+ read: () => Promise<T>,
2158
+ ): Promise<T> {
2159
+ if (entries.length === 0) return read();
2160
+ await sm.checkpoint();
2161
+ try {
2162
+ for (const e of entries) await applyStateEntry(e);
2163
+ return await read();
2164
+ } finally {
2165
+ await sm.revert();
2166
+ }
2167
+ }
2168
+
2169
+ /**
2170
+ * WRITE ONE {@link StateEntry} into the top level. The ONE apply step shared by
2171
+ * the RPC override path and the historical path.
2172
+ *
2173
+ * ORDER MATTERS, and each step re-reads the account so no step writes back a
2174
+ * stale copy over the previous one:
2175
+ *
2176
+ * 1. CODE FIRST. `putCode` rewrites the account's `codeHash`, and CREATES an
2177
+ * empty account when there is none, so it must come before
2178
+ * anything that states the account.
2179
+ * 2. THE ACCOUNT: a whole account replaces what `putCode` left (its `codeHash`
2180
+ * is K's own), and `balance` / `nonce` are a read-modify-write on top.
2181
+ * 3. STORAGE: a clear, then the slots.
2182
+ * 4. ABSENT LAST: an empty code entry, then `deleteAccount`. The account must
2183
+ * read as ABSENT, not as a zero account, and two upstream behaviours stand
2184
+ * in the way: `putCode` creates an account (so the code is emptied BEFORE
2185
+ * the delete), and `deleteAccount` leaves the address's code in the code
2186
+ * map, where `eth_getCode` and the default engine's `EXTCODESIZE` would
2187
+ * still see it (so the code is emptied at all). `deleteAccount` also clears
2188
+ * the storage.
2189
+ */
2190
+ async function applyStateEntry(e: StateEntry): Promise<void> {
2191
+ if (e.code !== undefined) await sm.putCode(e.address, e.code);
2192
+ if (e.account !== undefined) await sm.putAccount(e.address, e.account);
2193
+ if (e.balance !== undefined || e.nonce !== undefined) {
2194
+ const acc = (await sm.getAccount(e.address)) ?? new Account();
2195
+ if (e.balance !== undefined) acc.balance = e.balance;
2196
+ if (e.nonce !== undefined) acc.nonce = e.nonce;
2197
+ await sm.putAccount(e.address, acc);
2198
+ }
2199
+ if (e.clearStorage) await sm.clearStorage(e.address);
2200
+ for (const {key, value} of e.slots)
2201
+ await sm.putStorage(e.address, key, value);
2202
+ if (e.absent) {
2203
+ await sm.putCode(e.address, new Uint8Array(0));
2204
+ await sm.deleteAccount(e.address);
2205
+ }
2206
+ }
2207
+
2208
+ /**
2209
+ * geth's `eth_call` takes BLOCK overrides as a fourth parameter. This node does
2210
+ * not implement them, so a request carrying them is refused rather than run
2211
+ * against the real block environment.
2212
+ */
2213
+ function refuseBlockOverrides(blockOverrides: unknown, method: string): void {
2214
+ if (blockOverrides == null) return;
2215
+ throw new RpcError(
2216
+ -32602,
2217
+ `block overrides are not supported by this node (${method}, 4th parameter). ` +
2218
+ `The call would otherwise run against the real block environment.`,
2219
+ );
2220
+ }
2221
+
1272
2222
  // ---------- eth_call / estimateGas through the ENGINE's READ half (no signing) ----
1273
2223
  /**
1274
2224
  * The node's single pure-read helper, and the read half of the engine seam: it
@@ -1281,9 +2231,18 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
1281
2231
  * `@ethereumjs/evm` engine checkpoints/reverts and resets EIP-2929 warmth
1282
2232
  * because that EVM requires it; an engine that cannot commit pays for neither.
1283
2233
  * See ./engine.ts.
2234
+ *
2235
+ * `block` is the block the call executes IN: the head's for a call at the
2236
+ * head, block K's stored `Block` for a call pinned to K, so `NUMBER`,
2237
+ * `TIMESTAMP`, `COINBASE`, `PREVRANDAO`, `BASEFEE` and `GASLIMIT` are K's. It
2238
+ * also bounds `BLOCKHASH`: both engines answer zero for any number at or above
2239
+ * the block's own, so a call at K cannot see the hash of K or of anything
2240
+ * after it without any further mechanism (measured on both engines by
2241
+ * `test/historical-call.spec.ts` and its revm twin).
1284
2242
  */
1285
2243
  async function evmCall(
1286
2244
  params: any,
2245
+ block: Block,
1287
2246
  budget?: bigint,
1288
2247
  ): Promise<ReadCallResult> {
1289
2248
  const from = params.from
@@ -1331,7 +2290,7 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
1331
2290
  data,
1332
2291
  value,
1333
2292
  gasLimit,
1334
- block: blockStore.get(latestNumber)!.block,
2293
+ block,
1335
2294
  });
1336
2295
  }
1337
2296
 
@@ -1406,7 +2365,7 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
1406
2365
  * points callers HERE for "the number a transaction needs", so the node must
1407
2366
  * never refuse a limit it has just recommended.
1408
2367
  */
1409
- async function estimateGas(p: any): Promise<bigint> {
2368
+ async function estimateGas(p: any, block: Block): Promise<bigint> {
1410
2369
  const dataHex: string = p.data ?? p.input ?? '0x';
1411
2370
  const isCreate = !p.to;
1412
2371
  const overhead =
@@ -1418,6 +2377,11 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
1418
2377
  // back a number it will not accept. `gas` on an `eth_estimateGas` request is
1419
2378
  // geth's cap on the SEARCH ("do not consider limits above this"), which is a
1420
2379
  // different thing from `gas` on an `eth_call` ("let it run this long").
2380
+ //
2381
+ // AT A PAST BLOCK K THE CAP IS STILL THIS ONE, not K's own `gasLimit`,
2382
+ // deliberately (historical-eth-call): the number is for a transaction to be
2383
+ // SUBMITTED now, and what it meets is the limit of the blocks this node
2384
+ // mines, whatever K's was. `block` only decides what the probes execute in.
1421
2385
  const supplied = p.gas != null ? BigInt(p.gas) : undefined;
1422
2386
  const cap =
1423
2387
  supplied === undefined || supplied > minedBlockGasLimit
@@ -1441,7 +2405,7 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
1441
2405
  );
1442
2406
  }
1443
2407
 
1444
- const probe = (limit: bigint) => evmCall(p, limit - overhead);
2408
+ const probe = (limit: bigint) => evmCall(p, block, limit - overhead);
1445
2409
 
1446
2410
  // 1) THE UPPER BOUND, run first: a request that cannot succeed with all the
1447
2411
  // gas there is cannot succeed at all, and the caller learns that here rather
@@ -1578,18 +2542,47 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
1578
2542
  return sb ? blockToRpc(sb, Boolean(params[1])) : null;
1579
2543
  }
1580
2544
 
2545
+ // AT THE HEAD OR AT A BLOCK K IN THE `stateHistory` WINDOW, through the one
2546
+ // gate every state read uses (`historicalBlock`). At K the engine runs with
2547
+ // K's stored `Block` on K's state, written into a checkpoint the request
2548
+ // opens and reverts (`historicalEntries`, `withStateEntries`), with the
2549
+ // caller's state overrides applied ON TOP of it.
1581
2550
  case 'eth_call': {
1582
- const r = await evmCall(params[0] ?? {});
2551
+ const k = historicalBlock(params[1], 'eth_call');
2552
+ refuseBlockOverrides(params[3], 'eth_call');
2553
+ const entries = [
2554
+ ...(k === undefined ? [] : historicalEntries(k)),
2555
+ ...parseStateOverrides(params[2], 'eth_call'),
2556
+ ];
2557
+ const block = blockStore.get(k ?? latestNumber)!.block;
2558
+ const r = await pureRead(() =>
2559
+ withStateEntries(entries, () => evmCall(params[0] ?? {}, block)),
2560
+ );
1583
2561
  if (r.error)
1584
2562
  throw new RpcError(3, 'execution reverted', hex(r.returnValue));
1585
2563
  return hex(r.returnValue);
1586
2564
  }
1587
- case 'eth_estimateGas':
2565
+ case 'eth_estimateGas': {
1588
2566
  // THE SMALLEST GAS LIMIT AT WHICH THIS REQUEST SUCCEEDS, found by
1589
2567
  // re-executing it. The whole method is {@link estimateGas} above,
1590
2568
  // including why it is a search rather than the run-and-measure it used to
1591
- // be, and where the request's EIP-2930 access list is charged.
1592
- return numHex(await estimateGas(params[0] ?? {}));
2569
+ // be, and where the request's EIP-2930 access list is charged. The whole
2570
+ // search runs inside ONE checkpoint holding K's state (and the overrides).
2571
+ const k = historicalBlock(params[1], 'eth_estimateGas');
2572
+ refuseBlockOverrides(params[3], 'eth_estimateGas');
2573
+ const entries = [
2574
+ ...(k === undefined ? [] : historicalEntries(k)),
2575
+ ...parseStateOverrides(params[2], 'eth_estimateGas'),
2576
+ ];
2577
+ const block = blockStore.get(k ?? latestNumber)!.block;
2578
+ return numHex(
2579
+ await pureRead(() =>
2580
+ withStateEntries(entries, () =>
2581
+ estimateGas(params[0] ?? {}, block),
2582
+ ),
2583
+ ),
2584
+ );
2585
+ }
1593
2586
 
1594
2587
  case 'eth_fillTransaction': {
1595
2588
  // Fill the missing fields of a tx request and return {tx, raw} like geth
@@ -1603,8 +2596,10 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
1603
2596
  : createAddressFromString(
1604
2597
  '0x0000000000000000000000000000000000000000',
1605
2598
  );
1606
- const acc = await sm.getAccount(from);
1607
- const nonce = p.nonce != null ? BigInt(p.nonce) : (acc?.nonce ?? 0n);
2599
+ // The PENDING nonce, as geth fills it: the account's nonce advanced past
2600
+ // the transactions it already has queued.
2601
+ const nonce =
2602
+ p.nonce != null ? BigInt(p.nonce) : await pendingNonce(from);
1608
2603
  const value = p.value != null ? BigInt(p.value) : 0n;
1609
2604
  const dataHex: string = p.data ?? p.input ?? '0x';
1610
2605
  const isCreate = !p.to;
@@ -1622,7 +2617,12 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
1622
2617
  const gas: bigint =
1623
2618
  p.gas != null
1624
2619
  ? BigInt(p.gas)
1625
- : await estimateGas({...p, gas: undefined, accessList: undefined});
2620
+ : await pureRead(() =>
2621
+ estimateGas(
2622
+ {...p, gas: undefined, accessList: undefined},
2623
+ blockStore.get(latestNumber)!.block,
2624
+ ),
2625
+ );
1626
2626
  // Fee fields: legacy iff caller passed gasPrice (and no 1559 fields),
1627
2627
  // otherwise EIP-1559 with the node's constant fee market.
1628
2628
  const isLegacy =
@@ -1679,29 +2679,60 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
1679
2679
  return {raw: hex(unsigned.serialize()), tx};
1680
2680
  }
1681
2681
 
2682
+ // EVERY state read at a block is gated first: served at the head, served
2683
+ // from the undo log inside the `stateHistory` window (these four only,
2684
+ // through `historicalBlock`), and REFUSED below it, never answered from the
2685
+ // head for a block that is not the head.
1682
2686
  case 'eth_getBalance': {
1683
- const acc = await sm.getAccount(createAddressFromString(params[0]));
2687
+ const k = historicalBlock(params[1], 'eth_getBalance');
2688
+ const address = createAddressFromString(params[0]);
2689
+ const acc =
2690
+ k === undefined
2691
+ ? await sm.getAccount(address)
2692
+ : await accountAt(k, address);
1684
2693
  return numHex(acc?.balance ?? 0n);
1685
2694
  }
1686
2695
  case 'eth_getTransactionCount': {
1687
- const acc = await sm.getAccount(createAddressFromString(params[0]));
1688
- return numHex(acc?.nonce ?? 0n);
2696
+ const k = historicalBlock(params[1], 'eth_getTransactionCount');
2697
+ const address = createAddressFromString(params[0]);
2698
+ if (k !== undefined)
2699
+ return numHex((await accountAt(k, address))?.nonce ?? 0n);
2700
+ // `pending` COUNTS THE QUEUED TRANSACTIONS, the one state read where it
2701
+ // differs from the head: a client picking a nonce asks for `pending`
2702
+ // (viem does by default), and in manual/interval mining two sends
2703
+ // before a mine would otherwise get the SAME nonce, the second then
2704
+ // refused at mine time as a replay.
2705
+ return numHex(
2706
+ params[1] === 'pending'
2707
+ ? await pendingNonce(address)
2708
+ : ((await sm.getAccount(address))?.nonce ?? 0n),
2709
+ );
1689
2710
  }
1690
2711
  case 'eth_getCode': {
1691
- const code = await sm.getCode(createAddressFromString(params[0]));
1692
- return hex(code);
2712
+ const k = historicalBlock(params[1], 'eth_getCode');
2713
+ const address = createAddressFromString(params[0]);
2714
+ return hex(
2715
+ k === undefined
2716
+ ? await sm.getCode(address)
2717
+ : await codeAt(k, address),
2718
+ );
1693
2719
  }
1694
2720
  case 'eth_getStorageAt': {
2721
+ const k = historicalBlock(params[2], 'eth_getStorageAt');
1695
2722
  const addr = createAddressFromString(params[0]);
1696
2723
  const slot = setLengthLeft(bigIntToBytes(BigInt(params[1])), 32);
1697
- const val = await sm.getStorage(addr, slot);
2724
+ const val =
2725
+ k === undefined
2726
+ ? await sm.getStorage(addr, slot)
2727
+ : await storageAt(k, addr, slot);
1698
2728
  return hex(setLengthLeft(val, 32));
1699
2729
  }
1700
2730
 
1701
2731
  // ---- Runtime state cheats (anvil/hardhat-style; for tests/local tooling) ----
1702
2732
  // These MUTATE state directly (no tx). Honest about being non-standard: they
1703
- // are `evm_*`-namespaced. In trie mode each commits into the trie so the next
1704
- // getStateRoot() reflects the change.
2733
+ // are `evm_*`-namespaced. They write the flat state only; on a `computeStateRoot` node the
2734
+ // open record names what they wrote, so the next getStateRoot() (or mined
2735
+ // block) rehashes it into the derived trie.
1705
2736
  case 'evm_setBalance': {
1706
2737
  // params: [address, valueHex]
1707
2738
  const addr = createAddressFromString(params[0]);
@@ -1722,8 +2753,6 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
1722
2753
  // params: [address, codeHex]
1723
2754
  const addr = createAddressFromString(params[0]);
1724
2755
  await sm.putCode(addr, hexToBytes(params[1]));
1725
- touchedAccounts.add(addr.toString());
1726
- await commitIfTrie();
1727
2756
  return true;
1728
2757
  }
1729
2758
  case 'evm_setStorageAt': {
@@ -1735,8 +2764,6 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
1735
2764
  slot,
1736
2765
  setLengthLeft(hexToBytes(params[2]), 32),
1737
2766
  );
1738
- touchedAccounts.add(addr.toString());
1739
- await commitIfTrie();
1740
2767
  return true;
1741
2768
  }
1742
2769
  case 'evm_setAccount': {
@@ -1756,7 +2783,6 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
1756
2783
  setLengthLeft(hexToBytes(val as string), 32),
1757
2784
  );
1758
2785
  }
1759
- await commitIfTrie();
1760
2786
  return true;
1761
2787
  }
1762
2788
 
@@ -1765,7 +2791,50 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
1765
2791
  case 'eth_maxPriorityFeePerGas':
1766
2792
  return numHex(maxPriorityFeePerGas);
1767
2793
  case 'eth_feeHistory': {
1768
- const count = Number(BigInt(params[0] ?? '0x1'));
2794
+ // params: [blockCount, newestBlock, rewardPercentiles]. `newestBlock` is
2795
+ // HONOURED (it used to be ignored, and the window always ended at the head),
2796
+ // and the per-block base fee and gas-used ratio are the stored blocks' own.
2797
+ // Only `reward` stays synthetic: this node's priority fee is a constant.
2798
+ const rawCount = params[0] ?? '0x1';
2799
+ const requested =
2800
+ typeof rawCount === 'number' && Number.isSafeInteger(rawCount)
2801
+ ? rawCount
2802
+ : typeof rawCount === 'string' && /^0x[0-9a-fA-F]+$/.test(rawCount)
2803
+ ? Number(BigInt(rawCount))
2804
+ : NaN;
2805
+ if (!(requested >= 0))
2806
+ throw new RpcError(
2807
+ -32602,
2808
+ `invalid eth_feeHistory blockCount: ${JSON.stringify(rawCount)}. Expected a hex quantity.`,
2809
+ );
2810
+ const newest = resolveBlockTag(params[1] ?? 'latest');
2811
+ if (newest > latestNumber)
2812
+ throw new RpcError(
2813
+ -32000,
2814
+ `request beyond head block: eth_feeHistory newestBlock is ${newest}, but the head of this node is block ${latestNumber}.`,
2815
+ );
2816
+ // geth caps a request at 1024 blocks, and nothing precedes block 0.
2817
+ const count = Math.max(0, Math.min(requested, 1024, newest + 1));
2818
+ const oldest = newest - count + 1;
2819
+ const nextBaseFee = (n: number): string => {
2820
+ const sb = blockStore.get(n);
2821
+ return sb
2822
+ ? sb.header.baseFeePerGas
2823
+ : numHex(blockEnv?.baseFeePerGas ?? baseFeePerGas);
2824
+ };
2825
+ const ratio = (n: number): number => {
2826
+ // The header's own `gasUsed` is a documented 0x0 placeholder, so the
2827
+ // block's usage is summed from its receipts, which are real.
2828
+ const sb = blockStore.get(n);
2829
+ if (!sb) return 0;
2830
+ let used = 0n;
2831
+ for (const th of sb.header.transactions) {
2832
+ const r = receipts.get(th);
2833
+ if (r) used += BigInt(r.gasUsed);
2834
+ }
2835
+ const limit = BigInt(sb.header.gasLimit);
2836
+ return limit === 0n ? 0 : Number(used) / Number(limit);
2837
+ };
1769
2838
  // `reward` must carry ONE entry per requested percentile, per block. Returning a
1770
2839
  // single entry regardless of `rewardPercentiles` breaks any caller that asks for
1771
2840
  // several and indexes them: rocketh requests [10, 50, 80] and reads index 1 and 2,
@@ -1777,11 +2846,20 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
1777
2846
  percentiles.length > 0 ? percentiles : [50]
1778
2847
  ).map(() => numHex(maxPriorityFeePerGas));
1779
2848
  return {
1780
- oldestBlock: numHex(Math.max(0, latestNumber - count + 1)),
1781
- baseFeePerGas: Array.from({length: count + 1}, () =>
1782
- numHex(baseFeePerGas),
2849
+ // An empty window is geth's empty answer, oldestBlock included.
2850
+ oldestBlock: numHex(count === 0 ? 0 : oldest),
2851
+ // One per block in the window PLUS the block after it, which is the
2852
+ // stored block when there is one and the next block this node will mine
2853
+ // when the window ends at the head.
2854
+ baseFeePerGas:
2855
+ count === 0
2856
+ ? []
2857
+ : Array.from({length: count + 1}, (_, i) =>
2858
+ nextBaseFee(oldest + i),
2859
+ ),
2860
+ gasUsedRatio: Array.from({length: count}, (_, i) =>
2861
+ ratio(oldest + i),
1783
2862
  ),
1784
- gasUsedRatio: Array.from({length: count}, () => 0.5),
1785
2863
  reward: Array.from({length: count}, () => rewardPerBlock),
1786
2864
  };
1787
2865
  }
@@ -1825,9 +2903,33 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
1825
2903
  // is deferred — see tasks/slim-node-eth-getlogs-index.md. Keep this scan as
1826
2904
  // the authoritative semantics if/when an index is added.
1827
2905
  const f = params[0] ?? {};
1828
- const from = f.fromBlock != null ? resolveBlockTag(f.fromBlock) : 0;
1829
- const to =
1830
- f.toBlock != null ? resolveBlockTag(f.toBlock) : latestNumber;
2906
+ // `blockHash` (EIP-234) pins the query to ONE block. It used to be ignored,
2907
+ // which returned the logs of EVERY block. It excludes a range, as in geth,
2908
+ // and a hash no block has is an error rather than an empty result, so a
2909
+ // typo cannot read as "that block emitted nothing".
2910
+ let from: number;
2911
+ let to: number;
2912
+ if (f.blockHash != null) {
2913
+ if (f.fromBlock != null || f.toBlock != null)
2914
+ throw new RpcError(
2915
+ -32602,
2916
+ 'invalid eth_getLogs filter: cannot specify both blockHash and fromBlock/toBlock.',
2917
+ );
2918
+ const n = blockByHash.get(String(f.blockHash).toLowerCase());
2919
+ if (n === undefined)
2920
+ throw new RpcError(
2921
+ -32000,
2922
+ `unknown block: eth_getLogs blockHash ${f.blockHash} is not a block on this node.`,
2923
+ );
2924
+ from = n;
2925
+ to = n;
2926
+ } else {
2927
+ // geth's default for an omitted `fromBlock` is `latest`, not 0; this
2928
+ // node has always defaulted to 0 and that is kept (changing it would
2929
+ // silently shrink every existing consumer's results).
2930
+ from = f.fromBlock != null ? resolveBlockTag(f.fromBlock) : 0;
2931
+ to = f.toBlock != null ? resolveBlockTag(f.toBlock) : latestNumber;
2932
+ }
1831
2933
  const addrFilter = f.address
1832
2934
  ? (Array.isArray(f.address) ? f.address : [f.address]).map(
1833
2935
  (a: string) => a.toLowerCase(),
@@ -1893,43 +2995,25 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
1893
2995
  const code: Record<string, string> = {};
1894
2996
  const storage: Record<string, Record<string, string>> = {};
1895
2997
 
1896
- if (stateMode === 'trie') {
1897
- // Trie mode dumps accounts + code via the touched-account set. NOTE: it does
1898
- // NOT dump contract STORAGE — the EVM journals storage on an internal
1899
- // shallowCopy of the state manager that bypasses any interception, and the
1900
- // trie's own dumpStorage exposes only keccak-HASHED slot keys (not the raw
1901
- // slots loadState needs). Full-storage persistence is a 'none'-mode feature
1902
- // (where the live Map IS the committed state). Trie mode is for the REAL
1903
- // state root (conformance block roots), not for IndexedDB persist.
1904
- for (const addr of touchedAccounts) {
1905
- const address = createAddressFromString(addr);
1906
- const acc = await sm.getAccount(address);
1907
- if (acc === undefined) continue;
1908
- accounts[addr] = hex(acc.serialize());
1909
- const c = await sm.getCode(address);
1910
- if (c.length > 0) code[addr] = hex(c);
1911
- }
1912
- } else {
1913
- // 'none' mode: the account and code stacks are still plain Maps whose TOP
1914
- // frame is the live set, and storage is per-account with per-checkpoint
1915
- // OVERLAYS, flattened by liveStorage(). Dump both directly (no trie walk).
1916
- //
1917
- // THE SERIALISED FORMAT IS NOT THE INTERNAL LAYOUT and must not follow it:
1918
- // this output is persisted data (IndexedDB, loadState fixtures) with existing
1919
- // state behind it. It stays `{address: {slot: value}}` in 0x-hex, and
1920
- // `test/storage-overlay.spec.ts` asserts it byte-identical to a dump taken
1921
- // from the pre-overlay flat layout.
1922
- const live = sm as OverlayStorageStateManager;
1923
- const accMap = live.accountStack[live.accountStack.length - 1];
1924
- const codeMap = live.codeStack[live.codeStack.length - 1];
1925
- for (const [addr, acc] of accMap) {
1926
- if (acc !== undefined) accounts[addr] = hex(acc.serialize());
1927
- }
1928
- for (const [addr, c] of codeMap) code[addr] = hex(c);
1929
- for (const [addr, slots] of live.liveStorage()) {
1930
- for (const [slot, val] of slots)
1931
- (storage[addr] ??= {})[slot] = hex(val);
1932
- }
2998
+ // EVERY NODE DUMPS THE SAME WAY, storage included: the account and code
2999
+ // stacks are plain Maps whose TOP frame is the live set, and storage is
3000
+ // per-account with per-checkpoint OVERLAYS, flattened by liveStorage(). A
3001
+ // `computeStateRoot` node runs on this same flat state, and its derived trie is NOT
3002
+ // serialised: `loadState` rebuilds it from the loaded flat state.
3003
+ //
3004
+ // THE SERIALISED FORMAT IS NOT THE INTERNAL LAYOUT and must not follow it:
3005
+ // this output is persisted data (IndexedDB, loadState fixtures) with existing
3006
+ // state behind it. It stays `{address: {slot: value}}` in 0x-hex, and
3007
+ // `test/storage-overlay.spec.ts` asserts it byte-identical to a dump taken
3008
+ // from the pre-overlay flat layout.
3009
+ const accMap = sm.accountStack[sm.accountStack.length - 1];
3010
+ const codeMap = sm.codeStack[sm.codeStack.length - 1];
3011
+ for (const [addr, acc] of accMap) {
3012
+ if (acc !== undefined) accounts[addr] = hex(acc.serialize());
3013
+ }
3014
+ for (const [addr, c] of codeMap) code[addr] = hex(c);
3015
+ for (const [addr, slots] of sm.liveStorage()) {
3016
+ for (const [slot, val] of slots) (storage[addr] ??= {})[slot] = hex(val);
1933
3017
  }
1934
3018
 
1935
3019
  const blocks: SerializedBlock[] = [];
@@ -1941,16 +3025,86 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
1941
3025
  return {
1942
3026
  version: 1,
1943
3027
  chainId,
1944
- stateMode,
1945
3028
  accounts,
1946
3029
  code,
1947
3030
  storage,
1948
3031
  blocks,
1949
3032
  receipts: Object.fromEntries(receipts),
1950
3033
  transactions: Object.fromEntries(transactions),
3034
+ // ADDITIVE: a node without `stateHistory` writes no field at all, so its
3035
+ // dump is exactly what it was before history existed.
3036
+ ...(stateHistoryBlocks === undefined ? {} : {history: dumpHistory()}),
1951
3037
  };
1952
3038
  }
1953
3039
 
3040
+ /**
3041
+ * THE UNDO LOG AS THE DUMP CARRIES IT: one serialized record per sealed block,
3042
+ * oldest first, with the OPEN record FOLDED INTO THE HEAD'S RECORD (older
3043
+ * entry winning).
3044
+ *
3045
+ * WHY FOLD rather than dump the open record as a field of its own: `loadState`
3046
+ * treats the loaded state as a baseline and CLEARS the open record, so the
3047
+ * writes since the head was mined (`evm_set*` cheats, a batch that threw
3048
+ * mid-block) become part of the loaded head, which reads them live exactly as
3049
+ * it did before the dump. What must not be lost is their prior values, which
3050
+ * every read BELOW the head consults after the sealed records. Folding keeps
3051
+ * the per-key earliest-wins union over `undo[K+1] .. undo[head]` + open
3052
+ * identical for every K below the head: a key the head's record already names
3053
+ * keeps that (older) value; a key it does not name did not change in the head
3054
+ * block, so its value at the end of the block before equals its value at the
3055
+ * end of the head, which is what the open record holds. The alternative, a
3056
+ * separate `open` field restored as the open record, would make the next mined
3057
+ * block after a reload own writes made before it, and would have been a second
3058
+ * new field for the same answers.
3059
+ *
3060
+ * With NO record for the head (the head is where history starts: genesis, or a
3061
+ * loaded head nothing was mined on), no block below the head is servable, and
3062
+ * the open record is dropped with nothing lost.
3063
+ *
3064
+ * Decisions around the format (this fold, the contiguous restore, `[]` vs no
3065
+ * key) are recorded in
3066
+ * `work/notes/observations/state-history-persistence-decisions.md`.
3067
+ */
3068
+ function dumpHistory(): SerializedHistoryBlock[] {
3069
+ const out = sealed.map((r) => serializeChangeSet(r.number, r.changes));
3070
+ const open = changeSets?.peekChangeSet();
3071
+ const head = out[out.length - 1];
3072
+ if (
3073
+ open !== undefined &&
3074
+ head !== undefined &&
3075
+ head.number === latestNumber
3076
+ )
3077
+ mergeSerializedOlderWins(head, serializeChangeSet(latestNumber, open));
3078
+ return out;
3079
+ }
3080
+
3081
+ /**
3082
+ * RESTORE the undo log from a dump's `history` (see {@link dumpHistory}), after
3083
+ * the rest of the state is loaded and {@link latestNumber} is the dump's head.
3084
+ * Only the CONTIGUOUS run of records ending at the head block is kept, newest
3085
+ * first, stopping at the first gap and at this node's window (a record at or
3086
+ * below `head - N` serves no block in it, so a dump with more history than N
3087
+ * is truncated to N, and one with less serves what it has). A dump the writer
3088
+ * produced has no gap; a hand-edited or foreign one might, and a read below a
3089
+ * gap would silently be answered from a later state, which is the one thing
3090
+ * the history exists not to do. {@link historyFloor} becomes the block before
3091
+ * the oldest record kept, or the head when none is.
3092
+ */
3093
+ function loadHistory(history: SerializedHistoryBlock[], window: number) {
3094
+ const kept: {number: number; changes: ChangeSet}[] = [];
3095
+ let expected = latestNumber;
3096
+ for (let i = history.length - 1; i >= 0; i--) {
3097
+ const record = history[i];
3098
+ if (record.number !== expected || record.number <= latestNumber - window)
3099
+ break;
3100
+ kept.push({number: record.number, changes: deserializeChangeSet(record)});
3101
+ expected--;
3102
+ }
3103
+ kept.reverse();
3104
+ sealed.push(...kept);
3105
+ historyFloor = kept.length > 0 ? kept[0].number - 1 : latestNumber;
3106
+ }
3107
+
1954
3108
  async function loadState(state: SerializedState): Promise<void> {
1955
3109
  // Rehydrate accounts/code/storage directly into SimpleStateManager.
1956
3110
  for (const [addr, accHex] of Object.entries(state.accounts)) {
@@ -2036,6 +3190,27 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
2036
3190
  latestNumber = sh.number;
2037
3191
  parentHash = block.hash();
2038
3192
  }
3193
+
3194
+ // A LOADED STATE IS A BASELINE, NOT HISTORY: the record is cleared, like the
3195
+ // construction baselines at genesis. The dump carries no change set for its
3196
+ // head, so there is none to report for it either.
3197
+ changeSets?.takeChangeSet();
3198
+ headBlockChangeSet = undefined;
3199
+ // ...and the history the node held described the state this load just
3200
+ // replaced, so it goes. What replaces it is the dump's own history, when the
3201
+ // dump carries one and this node keeps any: otherwise history starts again at
3202
+ // the loaded head (an older dump, or a node without `stateHistory`, which
3203
+ // ignores the field).
3204
+ sealed.length = 0;
3205
+ historyFloor = latestNumber;
3206
+ if (stateHistoryBlocks !== undefined && state.history !== undefined)
3207
+ loadHistory(state.history, stateHistoryBlocks);
3208
+ // ...and the derived trie described that replaced state too. It is REBUILT
3209
+ // from the loaded flat state, once, exactly as at construction: the dump
3210
+ // carries no trie (it never has to: the flat state determines it), and a
3211
+ // load is a baseline in no change set, so nothing else would put it there.
3212
+ if (computeStateRoot)
3213
+ derivedTrie = await DerivedStateTrie.build(sm, common);
2039
3214
  }
2040
3215
 
2041
3216
  // ---------- persistence auto-load on creation ----------
@@ -2128,27 +3303,27 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
2128
3303
  // arriving over a served port queues exactly like one made directly.
2129
3304
  const publicRequest = (args: RequestArguments) =>
2130
3305
  serialise(() => persistingRequest(args));
2131
- return {
3306
+ const node: SlimNode = {
2132
3307
  request: publicRequest,
2133
3308
  mine: () => serialise(mineAndPersist),
2134
3309
  dumpState: () => serialise(dumpState),
2135
3310
  loadState: (state: SerializedState) => serialise(() => loadState(state)),
2136
- stateMode,
3311
+ computeStateRoot,
2137
3312
  senderMode,
2138
3313
  // Identity only: the engine object itself stays internal, so the reading is a
2139
3314
  // plain value that survives a Worker/comlink boundary unchanged.
2140
3315
  engine: {id: engine.id},
2141
3316
  async getStateRoot() {
2142
- if (stateMode !== 'trie') {
3317
+ if (!computeStateRoot) {
2143
3318
  throw new RpcError(
2144
3319
  -32004,
2145
- "no state root in 'none' mode — create the node with stateMode:'trie' for a real Merkle-Patricia root",
3320
+ 'no state root: this node was created without computeStateRoot. Create it with computeStateRoot: true for a real Merkle-Patricia root',
2146
3321
  );
2147
3322
  }
2148
- // SERIALISED like the rest, because this one READS BY WRITING: in trie mode
2149
- // `currentStateRoot` flushes the state manager's cache into the trie, so a
2150
- // root taken mid-transaction would both report an uncommitted state and
2151
- // push it into the trie on the way.
3323
+ // SERIALISED like the rest, because this one READS BY WRITING: it applies
3324
+ // the open record to the derived trie, which reads the COMMITTED flat state
3325
+ // and refuses to run with a checkpoint open, so a root taken
3326
+ // mid-transaction would report a state no block (or cheat) produced.
2152
3327
  return serialise(currentStateRoot);
2153
3328
  },
2154
3329
  onNewHead(cb) {
@@ -2187,4 +3362,11 @@ export async function createNode(options: NodeOptions = {}): Promise<SlimNode> {
2187
3362
  servedPorts.clear();
2188
3363
  },
2189
3364
  };
3365
+ changeSetProbes.set(node, () => ({
3366
+ recording: changeSets !== undefined,
3367
+ sealedBlocks: sealed.map((r) => r.number),
3368
+ headBlock: headBlockChangeSet,
3369
+ open: changeSets?.peekChangeSet(),
3370
+ }));
3371
+ return node;
2190
3372
  }