webevm 0.6.0 → 0.8.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 +148 -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 +1125 -141
  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 +180 -34
  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 +37 -11
  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 +21 -8
  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 +4 -1
  45. package/src/derived-trie.ts +214 -0
  46. package/src/engine.ts +2 -3
  47. package/src/index.ts +3 -1
  48. package/src/node.ts +1335 -138
  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 +183 -35
  54. package/src/worker-client.ts +42 -11
  55. package/src/worker-host.ts +21 -8
  56. package/src/worker-rpc-error.ts +139 -0
package/dist/node.js 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,12 +37,13 @@
34
37
  * `docs/adr/0012-one-request-at-a-time-the-node-serialises-its-whole-public-surface.md`.
35
38
  */
36
39
  import { createVM } 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 { OverlayStorageStateManager, copyAccount, mergeChangeSetOlderWins, } from './state-manager.js';
42
+ import { packAddressKey, packSlotKey, unpackAddressKey, unpackSlotKey, } from './storage-keys.js';
39
43
  import { Common, Mainnet, Hardfork } from '@ethereumjs/common';
40
44
  import { createBlock } from '@ethereumjs/block';
41
45
  import { createTxFromRLP, createTx } from '@ethereumjs/tx';
42
- import { createAddressFromString, createAccountFromRLP, Account, hexToBytes as hexToBytesStrict, bytesToHex, bytesToBigInt, bigIntToHex, setLengthLeft, bigIntToBytes, } from '@ethereumjs/util';
46
+ import { createAddressFromString, createAccountFromRLP, Account, hexToBytes as hexToBytesStrict, bytesToHex, bytesToBigInt, bigIntToHex, setLengthLeft, bigIntToBytes, unpadBytes, } from '@ethereumjs/util';
43
47
  // `@ethereumjs/util`'s hexToBytes is typed to require a `0x${string}` literal.
44
48
  // Our hex comes from runtime sources (RPC params, serialized state) typed as
45
49
  // plain `string`, so wrap it once with a runtime 0x-guard rather than casting at
@@ -52,6 +56,12 @@ import { connectEngine, createEthereumjsEngine } from './engine.js';
52
56
  // Sender derivation stays the node's on every engine; what an engine may lend it
53
57
  // is the CURVE step. See ./sender-recovery.ts.
54
58
  import { recoverSender } from './sender-recovery.js';
59
+ // `serveOn(port)`: EIP-1193 `request` over a MessagePort, in the wire format the
60
+ // consumer's `providerOverPort` speaks. Imported HERE, the one place the node's
61
+ // public surface is built, so every node (main-thread or worker-hosted) serves a
62
+ // port the same way; see `serveOn` at the bottom of this file for why this is a
63
+ // dependency of the core rather than of `webevm/worker-host` alone.
64
+ import { serveProvider } from '@eip-1193/over-port';
55
65
  // The engine reports EXECUTION gas for a read and the node adds intrinsic gas on top;
56
66
  // an engine that charges intrinsic gas itself (revm) subtracts the SAME formula,
57
67
  // so it has exactly one home. See ./intrinsic-gas.ts.
@@ -143,6 +153,82 @@ function hex(b) {
143
153
  function numHex(n) {
144
154
  return bigIntToHex(BigInt(n));
145
155
  }
156
+ /**
157
+ * A change set as the dump carries it ({@link SerializedHistoryBlock}): keys in
158
+ * `0x` hex, values hex, `null` for absent. Reads `changes` and does not keep a
159
+ * reference to anything in it.
160
+ */
161
+ function serializeChangeSet(number, changes) {
162
+ const accounts = {};
163
+ for (const [key, account] of changes.accounts)
164
+ accounts[key] = account === undefined ? null : hex(account.serialize());
165
+ const code = {};
166
+ for (const [key, value] of changes.code)
167
+ code[key] = value === undefined ? null : hex(value);
168
+ const storage = {};
169
+ for (const [addressKey, slots] of changes.storage) {
170
+ const out = {};
171
+ for (const [slotKey, value] of slots)
172
+ out[unpackSlotKey(slotKey)] = value === undefined ? null : hex(value);
173
+ storage[unpackAddressKey(addressKey)] = out;
174
+ }
175
+ return {
176
+ number,
177
+ accounts,
178
+ code,
179
+ storage,
180
+ storageCleared: [...changes.storageCleared].map(unpackAddressKey),
181
+ };
182
+ }
183
+ /**
184
+ * Merge serialized record `newer` INTO `older`, the OLDER entry winning for a
185
+ * key both name: the serialized twin of `mergeChangeSetOlderWins`, used by
186
+ * `dumpState` to fold the open record into the head's record (see there).
187
+ */
188
+ function mergeSerializedOlderWins(older, newer) {
189
+ for (const [key, value] of Object.entries(newer.accounts))
190
+ if (!(key in older.accounts))
191
+ older.accounts[key] = value;
192
+ for (const [key, value] of Object.entries(newer.code))
193
+ if (!(key in older.code))
194
+ older.code[key] = value;
195
+ for (const [address, slots] of Object.entries(newer.storage)) {
196
+ const target = (older.storage[address] ??= {});
197
+ for (const [slot, value] of Object.entries(slots))
198
+ if (!(slot in target))
199
+ target[slot] = value;
200
+ }
201
+ for (const address of newer.storageCleared)
202
+ if (!older.storageCleared.includes(address))
203
+ older.storageCleared.push(address);
204
+ }
205
+ /**
206
+ * The inverse of {@link serializeChangeSet}: keys back to the representation's
207
+ * own (`address.toString()` for accounts and code, PACKED for storage), `null`
208
+ * back to `undefined`. Addresses are lowercased, so a hand-edited checksummed
209
+ * key still names the account the maps hold.
210
+ */
211
+ function deserializeChangeSet(record) {
212
+ const accounts = new Map();
213
+ for (const [key, value] of Object.entries(record.accounts))
214
+ accounts.set(key.toLowerCase(), value === null ? undefined : createAccountFromRLP(hexToBytes(value)));
215
+ const code = new Map();
216
+ for (const [key, value] of Object.entries(record.code))
217
+ code.set(key.toLowerCase(), value === null ? undefined : hexToBytes(value));
218
+ const storage = new Map();
219
+ for (const [address, slots] of Object.entries(record.storage)) {
220
+ const out = new Map();
221
+ for (const [slot, value] of Object.entries(slots))
222
+ out.set(packSlotKey(hexToBytes(slot)), value === null ? undefined : hexToBytes(value));
223
+ storage.set(packAddressKey(hexToBytes(address)), out);
224
+ }
225
+ return {
226
+ accounts,
227
+ code,
228
+ storage,
229
+ storageCleared: new Set(record.storageCleared.map((a) => packAddressKey(hexToBytes(a)))),
230
+ };
231
+ }
146
232
  function txHashOf(tx) {
147
233
  return hex(tx.hash());
148
234
  }
@@ -206,30 +292,151 @@ function upfrontCost(tx) {
206
292
  * been delivered to whoever awaited that request.
207
293
  */
208
294
  function swallow() { }
295
+ const changeSetProbes = new WeakMap();
296
+ /**
297
+ * TEST-ONLY ACCESSOR for a node's change sets, named as such: it hands out the
298
+ * node's own record objects (read-only by contract) so a test can hold them
299
+ * against the state it reads through the public surface. Not part of
300
+ * `SlimNode` (the worker proxy's shape test would otherwise demand it cross a
301
+ * comlink boundary) and not exported from `src/index.ts`.
302
+ */
303
+ export function changeSetsForTests(node) {
304
+ const probe = changeSetProbes.get(node);
305
+ if (probe === undefined)
306
+ throw new Error('webevm: changeSetsForTests() was handed an object createNode() did not return.');
307
+ return probe();
308
+ }
309
+ /**
310
+ * Validate {@link NodeOptions.stateHistory}: ABSENT (`undefined`) is off and
311
+ * returns `undefined`; `{blocks: N}` with N a positive safe integer returns N;
312
+ * anything else throws.
313
+ *
314
+ * It composes with `computeStateRoot: true`: every node runs on the same flat state,
315
+ * which is what the undo log records, and the derived trie only reads it. (It
316
+ * was refused there while trie mode, as a root-computing node was then
317
+ * called, ran on `MerkleStateManager`, which recorded
318
+ * nothing; `trie-derived-from-the-flat-state` lifted that.)
319
+ */
320
+ function validateStateHistory(options) {
321
+ if (options.stateHistory === undefined)
322
+ return undefined;
323
+ const value = options.stateHistory;
324
+ const blocks = typeof value === 'object' && value !== null
325
+ ? value.blocks
326
+ : undefined;
327
+ if (typeof blocks !== 'number' ||
328
+ !Number.isSafeInteger(blocks) ||
329
+ blocks <= 0)
330
+ throw new Error(`webevm: stateHistory must be {blocks: N} with N a positive safe integer ` +
331
+ `(how many blocks below the head stay readable), or absent for no history; ` +
332
+ `got ${describeOption(value)}.`);
333
+ return blocks;
334
+ }
335
+ /**
336
+ * Validate {@link NodeOptions.genesisTimestamp}: ABSENT (`undefined`) returns
337
+ * `undefined` (block 0 takes the wall clock); a non-negative bigint returns
338
+ * itself; anything else throws. A NUMBER is refused rather than converted, even
339
+ * a whole one: every other timestamp the node takes (`blockEnv.timestamp`) is a
340
+ * bigint, and accepting both would make the option mean two types.
341
+ */
342
+ function validateGenesisTimestamp(options) {
343
+ if (options.genesisTimestamp === undefined)
344
+ return undefined;
345
+ const value = options.genesisTimestamp;
346
+ if (typeof value !== 'bigint' || value < 0n)
347
+ throw new Error(`webevm: genesisTimestamp must be a non-negative bigint (seconds since the ` +
348
+ `epoch, e.g. 1700000000n), or absent for the wall clock; got ` +
349
+ `${typeof value === 'bigint' ? `${value}n` : `${describeOption(value)} (${typeof value})`}.`);
350
+ return value;
351
+ }
352
+ function describeOption(value) {
353
+ try {
354
+ const s = JSON.stringify(value);
355
+ return s === undefined ? String(value) : s;
356
+ }
357
+ catch {
358
+ return String(value);
359
+ }
360
+ }
209
361
  export async function createNode(options = {}) {
362
+ return createNodeWithInternals(options, {});
363
+ }
364
+ /** {@link createNode} with {@link NodeInternals}; internal, see there. */
365
+ export async function createNodeWithInternals(options, internals) {
210
366
  const chainId = options.chainId ?? 31337;
211
- const stateMode = options.stateMode ?? 'none';
212
367
  const senderMode = options.senderMode ?? 'recover';
213
368
  const miningConfig = options.miningConfig ?? { type: 'auto' };
214
369
  const baseFeePerGas = options.baseFeePerGas ?? 1000000000n;
215
370
  const gasPrice = options.gasPrice ?? 1000000000n;
216
371
  const maxPriorityFeePerGas = options.maxPriorityFeePerGas ?? 1000000000n;
217
372
  const blockGasLimit = options.blockGasLimit ?? 30000000n;
373
+ // Validated before anything is built, so a bad option costs nothing.
374
+ const stateHistoryBlocks = validateStateHistory(options);
375
+ const genesisTimestamp = validateGenesisTimestamp(options);
376
+ /**
377
+ * `computeStateRoot: true`: derive a trie from the flat state, report its
378
+ * root. Only `true` turns it on (see {@link NodeOptions.computeStateRoot}).
379
+ */
380
+ const computeStateRoot = options.computeStateRoot === true;
218
381
  const common = new Common({
219
382
  chain: { ...Mainnet, chainId, name: 'webevm' },
220
383
  hardfork: Hardfork.Cancun,
221
384
  customCrypto: { keccak256: (m) => keccak_256(m) },
222
385
  });
223
- // State backing: SimpleStateManager (no trie, fast — default) or
224
- // MerkleStateManager (real trie + state root — opt-in, slower, conformance-able).
225
- // The 'none' manager is our SUBCLASS: storage is per-account with per-checkpoint
226
- // OVERLAYS (upstream copies the whole flat storage map on every message frame),
227
- // and it implements the `clearStorage(address)` that upstream ships as an empty
228
- // no-op — without which a contract created at an address that already holds
229
- // storage inherits it. See ./state-manager.ts.
230
- const sm = stateMode === 'trie'
231
- ? new MerkleStateManager()
232
- : new OverlayStorageStateManager();
386
+ // State backing, ONE for every node: our `SimpleStateManager` SUBCLASS, plain
387
+ // Maps with no trie. Storage is per-account with per-checkpoint OVERLAYS
388
+ // (upstream copies the whole flat storage map on every message frame), and it
389
+ // implements the `clearStorage(address)` that upstream ships as an empty no-op,
390
+ // without which a contract created at an address that already holds storage
391
+ // inherits it. See ./state-manager.ts. `computeStateRoot` does NOT change it:
392
+ // it adds a trie DERIVED from this state (`derivedTrie` below), which no engine
393
+ // ever reads.
394
+ const sm = new OverlayStorageStateManager();
395
+ // THE CHANGE SET, switched on BEFORE the first write so that the construction
396
+ // baselines below really go through the recorder and really get cleared when
397
+ // genesis is stored (a baseline left in the record would reconstruct EMPTY
398
+ // state at genesis). `changeSets` is the manager when recording, else
399
+ // `undefined`, so every use below is one optional call.
400
+ let changeSets;
401
+ if (internals.recordChangeSets ||
402
+ stateHistoryBlocks !== undefined ||
403
+ computeStateRoot) {
404
+ sm.enableChangeSets();
405
+ changeSets = sm;
406
+ }
407
+ /**
408
+ * The change set of the HEAD block, taken from the open record when the block
409
+ * was mined. With `stateHistory` it is also the newest entry of {@link sealed};
410
+ * this slot is what the test probe reports as `headBlock`, with or without it.
411
+ */
412
+ let headBlockChangeSet;
413
+ /**
414
+ * THE UNDO LOG (`stateHistory`): the SEALED change set of each of the last N
415
+ * mined blocks, oldest first. `sealed[i].changes` holds, for every key block
416
+ * `sealed[i].number` changed, the value it had at the END of the block before.
417
+ * Appended in `executeAndMine`, evicted there (anything at or below `head - N`
418
+ * serves no block in the window), and cleared by `loadState`. Always empty on a
419
+ * node without the option. See {@link historicalValue} for how a read uses it,
420
+ * and `docs/adr/0013-bounded-state-history-is-an-undo-log-over-the-flat-state.md`
421
+ * for why it is an undo log.
422
+ */
423
+ const sealed = [];
424
+ /**
425
+ * The oldest block whose state the undo log can reconstruct, WHATEVER the
426
+ * window: genesis at construction, the loaded head after `loadState` (a loaded
427
+ * dump is a baseline and carries no history). The window's oldest servable
428
+ * block is the later of this and `head - N`.
429
+ */
430
+ let historyFloor = 0;
431
+ /**
432
+ * Run a PURE READ (`eth_call`, `eth_estimateGas`, `eth_fillTransaction`'s
433
+ * estimate, with or without state overrides) with change-set recording
434
+ * suspended: every level it opens is reverted, so recording there is wasted
435
+ * work. A cost rule; see `withChangeSetsSuspended` in ./state-manager.ts.
436
+ */
437
+ function pureRead(read) {
438
+ return changeSets ? changeSets.withChangeSetsSuspended(read) : read();
439
+ }
233
440
  /**
234
441
  * THE SERIALISATION POINT: the tail of a promise chain that every public entry
235
442
  * point queues its work onto, so this node runs exactly ONE piece of work at a
@@ -339,39 +546,44 @@ export async function createNode(options = {}) {
339
546
  tail = run.then(swallow, swallow);
340
547
  return run;
341
548
  }
342
- // Touched-account set for the trie-mode dump (storage is read back via the
343
- // trie's own dumpStorage). We record the addresses each tx touches at the NODE
344
- // level (sender / to / created) rather than monkeypatching the state manager —
345
- // MerkleStateManager's cache/flush path is sensitive to method wrapping.
346
- const touchedAccounts = new Set();
549
+ /**
550
+ * THE DERIVED TRIE (`computeStateRoot: true` only; `undefined`, and never created,
551
+ * otherwise). Built from the WHOLE flat state once the genesis baselines are
552
+ * written and again at the end of `loadState`, and kept current from change
553
+ * sets by {@link currentStateRoot}. See ./derived-trie.ts.
554
+ */
555
+ let derivedTrie;
347
556
  const ZERO_ROOT = ZERO_HASH;
557
+ /**
558
+ * The state root of the flat state AS IT STANDS: the derived trie brought up
559
+ * to date with the OPEN RECORD (every key written since the head was mined)
560
+ * and its root read. Called at the end of each mined block, BEFORE the block's
561
+ * record is taken (so the block's own writes are in it), and by
562
+ * `getStateRoot()` for cheats since the head. Applying the open record twice
563
+ * (a `getStateRoot()`, then the block that includes the same writes) is
564
+ * harmless: the record only NAMES keys, and their values are re-read from the
565
+ * flat state each time. Both callers run inside the serialisation point with
566
+ * no checkpoint open, which the trie insists on. Without
567
+ * `computeStateRoot`: the zero placeholder, and no trie work at all.
568
+ */
348
569
  async function currentStateRoot() {
349
- if (stateMode !== 'trie')
570
+ if (derivedTrie === undefined)
350
571
  return ZERO_ROOT;
351
- const msm = sm;
352
- await msm.flush(); // write cached trie nodes before reading the root
353
- return hex(await msm.getStateRoot());
354
- }
355
- // Flush cache into the trie after a direct state mutation (trie mode only) so
356
- // the next getStateRoot() reflects it. No-op in 'none' mode (the Map IS state).
357
- async function commitIfTrie() {
358
- if (stateMode !== 'trie')
359
- return;
360
- await sm.checkpoint();
361
- await sm.commit();
572
+ const open = sm.peekChangeSet();
573
+ if (open !== undefined)
574
+ await derivedTrie.apply(open);
575
+ return hex(derivedTrie.root());
362
576
  }
363
577
  // Read-modify-write an account (creating an empty one if absent), used by the
364
- // evm_set* cheat methods. Commits into the trie in trie mode.
578
+ // evm_set* cheat methods.
365
579
  async function mutateAccount(addr, fn) {
366
580
  const acc = (await sm.getAccount(addr)) ?? new Account();
367
581
  fn(acc);
368
582
  await sm.putAccount(addr, acc);
369
- touchedAccounts.add(addr.toString());
370
- await commitIfTrie();
371
583
  }
372
584
  // Minimal mock blockchain: `runTx` (inside the default engine) only needs
373
- // getBlock (for BLOCKHASH) + shallowCopy. In 'none' mode we never compute a
374
- // canonical state root.
585
+ // getBlock (for BLOCKHASH) + shallowCopy. Without `computeStateRoot` we never
586
+ // compute a canonical state root.
375
587
  const blockStore = new Map();
376
588
  const blockByHash = new Map();
377
589
  const receipts = new Map();
@@ -416,7 +628,6 @@ export async function createNode(options = {}) {
416
628
  await connectEngine(engine, {
417
629
  stateManager: sm,
418
630
  common,
419
- stateMode,
420
631
  // Block hashes for BLOCKHASH, read LIVE (no block exists yet at this point)
421
632
  // and SYNCHRONOUSLY, because an engine answers BLOCKHASH mid-opcode.
422
633
  getBlockHash: (blockNumber) => {
@@ -436,15 +647,14 @@ export async function createNode(options = {}) {
436
647
  : undefined;
437
648
  let latestNumber = 0;
438
649
  let parentHash = hexToBytes(ZERO_HASH);
439
- // Initial balances FIRST (so the genesis state root, in trie mode, reflects them).
650
+ // Initial balances FIRST (so the genesis state root, when computed, reflects them).
440
651
  if (options.initialBalances) {
441
652
  for (const [addr, bal] of Object.entries(options.initialBalances)) {
442
653
  await sm.putAccount(createAddressFromString(addr), new Account(0n, bal));
443
- touchedAccounts.add(createAddressFromString(addr).toString());
444
654
  }
445
655
  }
446
656
  // Full genesis pre-state (balance/nonce/code/storage) — e.g. a GeneralStateTest
447
- // `pre` section. Applied before block 0 so the trie-mode genesis root reflects
657
+ // `pre` section. Applied before block 0 so a computed genesis root reflects
448
658
  // it and a post-tx getStateRoot() can be compared to the fixture's hash.
449
659
  if (options.initialState) {
450
660
  for (const [addr, acc] of Object.entries(options.initialState)) {
@@ -455,14 +665,14 @@ export async function createNode(options = {}) {
455
665
  for (const [slot, val] of Object.entries(acc.storage ?? {})) {
456
666
  await sm.putStorage(address, setLengthLeft(bigIntToBytes(BigInt(slot)), 32), hexToBytes(val));
457
667
  }
458
- touchedAccounts.add(address.toString());
459
- }
460
- // Commit the cache into the trie so the genesis root is correct in trie mode.
461
- if (stateMode === 'trie') {
462
- await sm.checkpoint();
463
- await sm.commit();
464
668
  }
465
669
  }
670
+ // THE TRIE IS BUILT FROM THE FULL FLAT STATE, here, once: the baselines above
671
+ // are block 0 and deliberately in NO change set (the record is cleared just
672
+ // after genesis is stored), so a trie kept from change sets alone would omit
673
+ // them and every genesis-dependent root would be wrong.
674
+ if (computeStateRoot)
675
+ derivedTrie = await DerivedStateTrie.build(sm, common);
466
676
  const blockEnv = options.blockEnv;
467
677
  /**
468
678
  * THE GAS LIMIT OF EVERY BLOCK THIS NODE BUILDS, named once so that the block
@@ -492,12 +702,15 @@ export async function createNode(options = {}) {
492
702
  // `number`, `timestamp` and `gasLimit` stay the node's own: genesis IS block 0,
493
703
  // and `blockEnv.number` places a MINED block rather than renumbering the chain's
494
704
  // genesis (`minedBlockGasLimit` above is likewise the MINED block's limit).
705
+ // Its timestamp is `genesisTimestamp` when given, else the wall clock: a
706
+ // separate option rather than `blockEnv.timestamp`, which pins every MINED
707
+ // block to one value and so cannot also be block 0's (see the option's JSDoc).
495
708
  const genesis = createBlock({
496
709
  header: {
497
710
  number: 0n,
498
711
  gasLimit: blockGasLimit,
499
712
  baseFeePerGas,
500
- timestamp: BigInt(Math.floor(Date.now() / 1000)),
713
+ timestamp: genesisTimestamp ?? BigInt(Math.floor(Date.now() / 1000)),
501
714
  ...(blockEnv?.coinbase
502
715
  ? { coinbase: createAddressFromString(blockEnv.coinbase) }
503
716
  : {}),
@@ -508,12 +721,17 @@ export async function createNode(options = {}) {
508
721
  },
509
722
  }, { common });
510
723
  storeBlock(genesis, [], [], await currentStateRoot());
724
+ // BASELINES ARE NOT HISTORY: `initialBalances` / `initialState` ARE block 0,
725
+ // not a change to it.
726
+ changeSets?.takeChangeSet();
511
727
  // Pending raw txs awaiting the next mined block (manual/interval modes). Each
512
728
  // carries its SENDER, decided once at parse time by `parseTx`: the node derives
513
729
  // the sender (or is told it), never the engine.
514
730
  const pending = [];
515
731
  // newHeads subscribers.
516
732
  const headSubs = new Set();
733
+ // Ports `serveOn` is serving, so `dispose` can stop them all.
734
+ const servedPorts = new Set();
517
735
  // THE INTERVAL TIMER IS ARMED AT THE BOTTOM OF THIS FUNCTION, not here, at the
518
736
  // `miningConfig.type === 'interval'` block just above the `return`. The reason
519
737
  // is ordering: a timer armed at this point can fire while the
@@ -624,15 +842,6 @@ export async function createNode(options = {}) {
624
842
  const from = sender.toString();
625
843
  const to = tx.to ? tx.to.toString() : null;
626
844
  const created = res.createdAddress ? hex(res.createdAddress) : null;
627
- // Track touched accounts for the trie-mode dump (sender, recipient, created,
628
- // and any account that emitted a log — that set covers what changed).
629
- touchedAccounts.add(from);
630
- if (to)
631
- touchedAccounts.add(to);
632
- if (created)
633
- touchedAccounts.add(created);
634
- for (const log of res.logs)
635
- touchedAccounts.add(hex(log.address));
636
845
  const rcptLogs = res.logs.map((log, i) => {
637
846
  const sl = {
638
847
  address: hex(log.address),
@@ -692,12 +901,47 @@ export async function createNode(options = {}) {
692
901
  txIndex++;
693
902
  }
694
903
  allLogs.push(...blockLogs);
904
+ // The root BEFORE the record is taken below: `currentStateRoot` applies the
905
+ // open record, which at this point is exactly what this block changed.
695
906
  storeBlock(block, txHashes, blockLogs, await currentStateRoot());
907
+ // THE BLOCK'S CHANGE SET is everything written since the previous head was
908
+ // mined: this block's transactions AND any `evm_set*` cheat issued between
909
+ // the two blocks, which belongs to this block (the first one that can see
910
+ // it). Taken with no checkpoint open, which `takeChangeSet` insists on.
911
+ if (changeSets)
912
+ headBlockChangeSet = changeSets.takeChangeSet();
913
+ if (stateHistoryBlocks !== undefined && headBlockChangeSet !== undefined)
914
+ sealBlock(blockNumber, headBlockChangeSet, stateHistoryBlocks);
696
915
  // emit newHeads
697
916
  for (const cb of headSubs)
698
917
  cb({ number: blockNumber, hash: blockHash });
699
918
  return { blockNumber, blockHash, txHashes };
700
919
  }
920
+ /**
921
+ * SEAL the change set just taken as block `number`'s undo record, and EVICT
922
+ * every record at or below `head - N`: a read at the oldest servable block
923
+ * `head - N` needs the records of blocks `head - N + 1 .. head` and no other,
924
+ * so exactly N are kept.
925
+ *
926
+ * A block MINED UNDER THE SAME NUMBER as the newest record (a fixed
927
+ * `blockEnv.number` does that: every mined block replaces the head) is MERGED
928
+ * into it, the older entry winning, as a checkpoint commit merges: the merged
929
+ * record then holds each key's value from before the first of them, which is
930
+ * what a read below that number needs, and the log stays bounded.
931
+ */
932
+ function sealBlock(number, changes, window) {
933
+ const newest = sealed[sealed.length - 1];
934
+ if (newest !== undefined && newest.number === number)
935
+ mergeChangeSetOlderWins(newest.changes, changes);
936
+ else
937
+ sealed.push({ number, changes });
938
+ const oldestKept = latestNumber - window;
939
+ let drop = 0;
940
+ while (drop < sealed.length && sealed[drop].number <= oldestKept)
941
+ drop++;
942
+ if (drop > 0)
943
+ sealed.splice(0, drop);
944
+ }
701
945
  async function mineBlock() {
702
946
  const batch = pending.splice(0, pending.length);
703
947
  return executeAndMine(batch);
@@ -988,7 +1232,29 @@ export async function createNode(options = {}) {
988
1232
  const r = receipts.get(h);
989
1233
  return r ? receiptToRpc(r) : null;
990
1234
  }
1235
+ /**
1236
+ * The nonce `address` sends with next: its account nonce, advanced past each
1237
+ * CONTIGUOUS queued transaction of its own (manual/interval mining; the queue
1238
+ * is always empty under auto mining). Contiguous, as geth counts it: a queued
1239
+ * nonce beyond a gap does not advance it, because that transaction will not
1240
+ * execute until the gap is filled.
1241
+ */
1242
+ async function pendingNonce(address) {
1243
+ let n = (await sm.getAccount(address))?.nonce ?? 0n;
1244
+ const queued = new Set();
1245
+ for (const q of pending)
1246
+ if (q.sender.equals(address))
1247
+ queued.add(q.tx.nonce);
1248
+ while (queued.has(n))
1249
+ n++;
1250
+ return n;
1251
+ }
991
1252
  // ---------- block lookup helpers ----------
1253
+ /**
1254
+ * A block TAG or NUMBER as a block number. A string that is neither is a
1255
+ * -32602, not a JavaScript `SyntaxError` escaping from `BigInt` (which is what
1256
+ * `eth_getBlockByNumber('yesterday')` used to throw), and not a silent `latest`.
1257
+ */
992
1258
  function resolveBlockTag(tag) {
993
1259
  if (tag === 'latest' ||
994
1260
  tag === 'pending' ||
@@ -998,11 +1264,231 @@ export async function createNode(options = {}) {
998
1264
  return latestNumber;
999
1265
  if (tag === 'earliest')
1000
1266
  return 0;
1001
- if (typeof tag === 'string')
1267
+ // A 32-byte hex string is a block HASH, which this parameter does not take:
1268
+ // read as a number it would be ~1e76 and look like "far above the head".
1269
+ if (typeof tag === 'string' && /^0x[0-9a-fA-F]{64}$/.test(tag))
1270
+ throw new RpcError(-32602, `invalid block parameter: ${tag} is a block hash, and this parameter takes a block number or tag.`);
1271
+ if (typeof tag === 'string' && /^0x[0-9a-fA-F]+$/.test(tag))
1002
1272
  return Number(BigInt(tag));
1003
- if (typeof tag === 'number')
1273
+ if (typeof tag === 'number' && Number.isSafeInteger(tag) && tag >= 0)
1004
1274
  return tag;
1005
- return latestNumber;
1275
+ throw new RpcError(-32602, `invalid block parameter: ${JSON.stringify(tag)}. Expected a block tag (latest, pending, safe, finalized, earliest) or a hex block number.`);
1276
+ }
1277
+ /**
1278
+ * THE GATE FOR EVERY STATE READ AT A BLOCK: `undefined` when the parameter
1279
+ * names the head (read or execute live), the block number K when it names a
1280
+ * block in the `stateHistory` window (served from the undo log), and a refusal
1281
+ * otherwise. Every method that reads STATE at a block (`eth_call`,
1282
+ * `eth_estimateGas`, `eth_getBalance`, `eth_getCode`, `eth_getStorageAt`,
1283
+ * `eth_getTransactionCount`) calls this with its block parameter BEFORE
1284
+ * touching state.
1285
+ *
1286
+ * ## Why this exists
1287
+ *
1288
+ * Those methods used to ignore the block parameter entirely and answer from the
1289
+ * live state, while `eth_getLogs` and `eth_getBlockByNumber` honoured theirs. A
1290
+ * client that pins a PAIR of reads to one block so they describe the same moment
1291
+ * (logs up to block N, and a view call at block N) got logs as of N and storage
1292
+ * as of the head: a position whose move it could not find, with no error. That is
1293
+ * a different answer from every other node, delivered silently, which is the one
1294
+ * outcome that is not acceptable. (This gate was `requireHeadState` while the
1295
+ * node served the head only.)
1296
+ *
1297
+ * ## What the node holds: the head, plus an OPT-IN undo log
1298
+ *
1299
+ * This node holds ONE state: the live one. On every node the
1300
+ * state manager's checkpoint/overlay stack is the journal of the execution in
1301
+ * flight, not a history of blocks. Without `stateHistory` nothing of block N
1302
+ * survives the mining of N+1, and the honest answer to "what was the state at
1303
+ * N" is "not available here".
1304
+ *
1305
+ * WITH `stateHistory: {blocks: N}` the node keeps, per mined block, the value
1306
+ * every key the block changed had BEFORE it (the sealed change sets, an undo
1307
+ * log over the one flat state; see
1308
+ * `docs/adr/0013-bounded-state-history-is-an-undo-log-over-the-flat-state.md`).
1309
+ * The four POINT reads at a block K in the window are answered from it by
1310
+ * {@link historicalValue} with no state manager involvement and no checkpoint.
1311
+ * `eth_call` and `eth_estimateGas` at K EXECUTE: the same records, as K's
1312
+ * state, are written into a checkpoint the request opens and reverts
1313
+ * ({@link historicalEntries}, {@link withStateEntries}), and the engine runs
1314
+ * with K's stored `Block`. That SUPERSEDES the reasoning this comment used to
1315
+ * give for refusing all history (retained copies, or swapping a shared state
1316
+ * manager's root under a read): an undo log needs neither.
1317
+ *
1318
+ * ## What is served, and what is refused
1319
+ *
1320
+ * - SERVED: `latest`, `pending`, `safe`, `finalized`, an absent parameter, and a
1321
+ * number, hash or EIP-1898 `{blockNumber}` / `{blockHash}` object that names
1322
+ * the HEAD block. Pinning to the block you just read is the common case and it
1323
+ * is almost always the head, so it must keep working. (`pending` is the head
1324
+ * because in `manual`/`interval` mining the queued transactions have not
1325
+ * executed yet and this node has no speculative pending state; the one
1326
+ * exception is `eth_getTransactionCount`, which adds the sender's queued
1327
+ * transactions so that two sends before a mine get two nonces. `safe` and
1328
+ * `finalized` are the head because a local chain has no reorgs.) `earliest`
1329
+ * is served while block 0 is the head or in the window.
1330
+ * - SERVED FROM HISTORY: any block from {@link oldestServableBlock} up to the
1331
+ * head, named any of those ways, by all six methods.
1332
+ * - REFUSED, -32000 `historical state not available`: a block below the oldest
1333
+ * servable one (with no `stateHistory`, that is every block below the head),
1334
+ * with a message naming the oldest servable block and the `stateHistory`
1335
+ * option. The same code geth uses for pruned state (`missing trie node`).
1336
+ * - REFUSED, -32000 `header not found`: a number above the head, a hash no
1337
+ * block has (geth's exact wording for both), or a number between two blocks
1338
+ * of a chain whose numbering jumps.
1339
+ * - REFUSED, -32602: a parameter that is not a block at all.
1340
+ *
1341
+ * THE STATE AT THE HEAD INCLUDES `evm_set*` CHEATS applied since it was mined,
1342
+ * exactly as `latest` always has: those mutate live state without a block. They
1343
+ * are in the OPEN record, which a read below the head consults after the sealed
1344
+ * ones, so they are visible at the head and at no older block.
1345
+ */
1346
+ function historicalBlock(blockParam, method) {
1347
+ const number = pinnedBlockNumber(blockParam, method);
1348
+ if (number === latestNumber)
1349
+ return undefined;
1350
+ const oldest = oldestServableBlock();
1351
+ if (number < oldest)
1352
+ throw beyondHistory(method, number, oldest);
1353
+ // Numbering has gaps only under a `blockEnv.number` that jumps; a number
1354
+ // between two blocks names no block, and is not answered as if it did.
1355
+ if (!blockStore.has(number))
1356
+ throw new RpcError(-32000, `header not found: ${method} was pinned to block ${number}, which this node never mined.`);
1357
+ return number;
1358
+ }
1359
+ /**
1360
+ * The oldest block whose state a point read can be answered at: the head
1361
+ * without `stateHistory`; with it, `head - N`, but never below where the undo
1362
+ * log starts ({@link historyFloor}: genesis, or the head a state was loaded at).
1363
+ */
1364
+ function oldestServableBlock() {
1365
+ if (stateHistoryBlocks === undefined)
1366
+ return latestNumber;
1367
+ return Math.max(historyFloor, latestNumber - stateHistoryBlocks, 0);
1368
+ }
1369
+ /** The refusal for a block older than {@link oldestServableBlock}. */
1370
+ function beyondHistory(method, number, oldest) {
1371
+ const holds = stateHistoryBlocks === undefined
1372
+ ? `but the oldest block whose state this node holds is block ${oldest}, its head, because it was created without stateHistory. ` +
1373
+ `Create the node with stateHistory: {blocks: N} to keep the last N blocks readable, or pin to the head (or 'latest') instead.`
1374
+ : `but the oldest block whose state this node holds is block ${oldest} (head ${latestNumber}, stateHistory: {blocks: ${stateHistoryBlocks}}` +
1375
+ (oldest > latestNumber - stateHistoryBlocks
1376
+ ? `; history starts at block ${oldest}, where this node's state was loaded`
1377
+ : '') +
1378
+ `). Pin to a block in that window, or widen stateHistory.blocks.`;
1379
+ return new RpcError(-32000, `historical state not available: ${method} was pinned to block ${number}, ${holds} ` +
1380
+ `It REFUSES rather than answer from a later state than the one you asked for; logs and blocks remain queryable at any height.`);
1381
+ }
1382
+ /**
1383
+ * THE BLOCK NUMBER a state read's block parameter names (the head for a tag),
1384
+ * refusing what is not a block (-32602), a hash no block has and a number above
1385
+ * the head (-32000 `header not found`).
1386
+ */
1387
+ function pinnedBlockNumber(blockParam, method) {
1388
+ if (blockParam == null ||
1389
+ blockParam === 'latest' ||
1390
+ blockParam === 'pending' ||
1391
+ blockParam === 'safe' ||
1392
+ blockParam === 'finalized')
1393
+ return latestNumber;
1394
+ let number;
1395
+ let hash;
1396
+ if (blockParam === 'earliest')
1397
+ number = 0;
1398
+ else if (typeof blockParam === 'number')
1399
+ number = blockParam;
1400
+ else if (typeof blockParam === 'string') {
1401
+ // A 32-byte hex string is a block HASH (geth accepts it bare, EIP-1898).
1402
+ if (/^0x[0-9a-fA-F]{64}$/.test(blockParam))
1403
+ hash = blockParam;
1404
+ else if (/^0x[0-9a-fA-F]+$/.test(blockParam))
1405
+ number = Number(BigInt(blockParam));
1406
+ }
1407
+ else if (typeof blockParam === 'object') {
1408
+ const o = blockParam;
1409
+ // EIP-1898: exactly one of the two. geth refuses both at once, and so
1410
+ // does this node rather than silently preferring one.
1411
+ if (o.blockHash != null && o.blockNumber != null)
1412
+ throw new RpcError(-32602, `invalid block parameter for ${method}: pass blockHash or blockNumber, not both.`);
1413
+ if (typeof o.blockHash === 'string')
1414
+ hash = o.blockHash;
1415
+ else if (typeof o.blockNumber === 'string') {
1416
+ if (o.blockNumber === 'earliest')
1417
+ number = 0;
1418
+ else if (/^0x[0-9a-fA-F]+$/.test(o.blockNumber))
1419
+ number = Number(BigInt(o.blockNumber));
1420
+ else
1421
+ return pinnedBlockNumber(o.blockNumber, method);
1422
+ }
1423
+ }
1424
+ if (hash !== undefined) {
1425
+ const n = blockByHash.get(hash.toLowerCase());
1426
+ if (n === undefined)
1427
+ throw new RpcError(-32000, `header not found: ${method} was pinned to block hash ${hash}, which no block on this node has.`);
1428
+ number = n;
1429
+ }
1430
+ // A well-formed number too large to be a safe integer names a block far
1431
+ // above the head: that is "not found", not "not a block".
1432
+ if (number !== undefined && number > Number.MAX_SAFE_INTEGER)
1433
+ number = Number.MAX_SAFE_INTEGER;
1434
+ if (number === undefined || !Number.isSafeInteger(number) || number < 0)
1435
+ throw new RpcError(-32602, `invalid block parameter for ${method}: ${JSON.stringify(blockParam)}. ` +
1436
+ `Expected a block tag (latest, pending, safe, finalized, earliest), a hex block number, a block hash, or {blockNumber}/{blockHash}.`);
1437
+ if (number > latestNumber)
1438
+ throw new RpcError(-32000, `header not found: ${method} was pinned to block ${number}, but the head of this node is block ${latestNumber}.`);
1439
+ return number;
1440
+ }
1441
+ /**
1442
+ * ONE KEY'S VALUE AT THE END OF BLOCK `k` (below the head, in the window): the
1443
+ * FIRST record naming the key among the sealed records of blocks `k+1 .. head`
1444
+ * (oldest first), then the OPEN record (writes since the head was mined:
1445
+ * cheats, and a batch that threw mid-block), else the live value. Each record
1446
+ * holds a key's value from before its block, so the first one after `k` that
1447
+ * names the key holds its value at the end of `k`; a key no record names has
1448
+ * not changed since `k`, so its live value is its value then.
1449
+ *
1450
+ * A PURE LOOKUP: no state manager write, no checkpoint, and nothing an engine
1451
+ * sees, which is why it is safe on both engines and needs nothing from the
1452
+ * serialisation point beyond running inside it (the dispatcher does). `pick`
1453
+ * returns `{value}` when the record names the key, `undefined` when it does
1454
+ * not; `live` reads the head.
1455
+ */
1456
+ async function historicalValue(k, pick, live) {
1457
+ for (const record of sealed) {
1458
+ if (record.number <= k)
1459
+ continue;
1460
+ const hit = pick(record.changes);
1461
+ if (hit !== undefined)
1462
+ return hit.value;
1463
+ }
1464
+ const open = changeSets?.peekChangeSet();
1465
+ const hit = open && pick(open);
1466
+ if (hit !== undefined)
1467
+ return hit.value;
1468
+ return live();
1469
+ }
1470
+ /** The account at `k`, `undefined` if absent: see {@link historicalValue}. */
1471
+ function accountAt(k, address) {
1472
+ const key = address.toString();
1473
+ return historicalValue(k, (cs) => cs.accounts.has(key) ? { value: cs.accounts.get(key) } : undefined, () => sm.getAccount(address));
1474
+ }
1475
+ /** The code at `k`, empty if none: see {@link historicalValue}. */
1476
+ function codeAt(k, address) {
1477
+ const key = address.toString();
1478
+ return historicalValue(k, (cs) => cs.code.has(key)
1479
+ ? { value: cs.code.get(key) ?? new Uint8Array(0) }
1480
+ : undefined, () => sm.getCode(address));
1481
+ }
1482
+ /** One storage slot at `k`, empty if unset: see {@link historicalValue}. */
1483
+ function storageAt(k, address, slot) {
1484
+ const addressKey = packAddressKey(address.bytes);
1485
+ const slotKey = packSlotKey(slot);
1486
+ return historicalValue(k, (cs) => {
1487
+ const slots = cs.storage.get(addressKey);
1488
+ return slots?.has(slotKey)
1489
+ ? { value: slots.get(slotKey) ?? new Uint8Array(0) }
1490
+ : undefined;
1491
+ }, () => sm.getStorage(address, slot));
1006
1492
  }
1007
1493
  /**
1008
1494
  * The stored block, as `eth_getBlockByNumber` / `eth_getBlockByHash` report it.
@@ -1014,7 +1500,7 @@ export async function createNode(options = {}) {
1014
1500
  * a uniform zero, because nothing tells a consumer which side of the trip they
1015
1501
  * are on. Every value below is therefore one a dump carries.
1016
1502
  *
1017
- * `stateRoot` is the one REAL value among the roots (in `'trie'` mode);
1503
+ * `stateRoot` is the one REAL value among the roots (with `computeStateRoot: true`);
1018
1504
  * `sha3Uncles`, `transactionsRoot` and `receiptsRoot` stay honest zero
1019
1505
  * placeholders, named as such in the README, because this node builds no tries
1020
1506
  * over its transactions or receipts. `logsBloom` used to be in that list and is
@@ -1110,6 +1596,279 @@ export async function createNode(options = {}) {
1110
1596
  removed: false,
1111
1597
  };
1112
1598
  }
1599
+ /**
1600
+ * K'S STATE, AS STATE ENTRIES: for every key the undo log names after block
1601
+ * `k` (the sealed records of blocks `k+1 .. head`, then the OPEN record), the
1602
+ * value it had at the end of `k`, the earliest record winning per key, exactly
1603
+ * the lookup {@link historicalValue} makes for one key. A key no record names
1604
+ * has not changed since `k`, so the live state already holds it and it needs
1605
+ * no entry. O(keys changed since `k`), which is the cost of a historical
1606
+ * `eth_call` on top of the call itself.
1607
+ *
1608
+ * Written into a checkpoint by {@link withStateEntries}, so the engine
1609
+ * executes on K's state with no copy of state and no root swapped. An account
1610
+ * absent at `k` becomes an ABSENT entry, and an account whose storage was
1611
+ * cleared after `k` becomes a `clearStorage` entry: the clear recorded every
1612
+ * slot the account held at that moment, so the union holds every slot it
1613
+ * held at `k`, and clearing first also drops the slots written since.
1614
+ *
1615
+ * THE UNION IS BUILT FRESH. `mergeChangeSetOlderWins` is not reused here
1616
+ * because it CONSUMES its second argument (inner storage maps are handed over
1617
+ * whole), and these are the sealed records themselves, which a later read
1618
+ * still needs intact.
1619
+ */
1620
+ function historicalEntries(k) {
1621
+ const accounts = new Map();
1622
+ const code = new Map();
1623
+ const storage = new Map();
1624
+ const cleared = new Set();
1625
+ const take = (cs) => {
1626
+ for (const [key, value] of cs.accounts)
1627
+ if (!accounts.has(key))
1628
+ accounts.set(key, value);
1629
+ for (const [key, value] of cs.code)
1630
+ if (!code.has(key))
1631
+ code.set(key, value);
1632
+ for (const [addressKey, slots] of cs.storage) {
1633
+ let target = storage.get(addressKey);
1634
+ if (target === undefined) {
1635
+ target = new Map();
1636
+ storage.set(addressKey, target);
1637
+ }
1638
+ for (const [slotKey, value] of slots)
1639
+ if (!target.has(slotKey))
1640
+ target.set(slotKey, value);
1641
+ }
1642
+ for (const addressKey of cs.storageCleared)
1643
+ cleared.add(addressKey);
1644
+ };
1645
+ for (const record of sealed)
1646
+ if (record.number > k)
1647
+ take(record.changes);
1648
+ const open = changeSets?.peekChangeSet();
1649
+ if (open)
1650
+ take(open);
1651
+ // One entry per address, keyed as `address.toString()` gives it (the
1652
+ // account and code maps' key; `unpackAddressKey` yields the same form).
1653
+ const entries = new Map();
1654
+ const entry = (key) => {
1655
+ let e = entries.get(key);
1656
+ if (e === undefined) {
1657
+ e = {
1658
+ address: createAddressFromString(key),
1659
+ clearStorage: false,
1660
+ slots: [],
1661
+ absent: false,
1662
+ };
1663
+ entries.set(key, e);
1664
+ }
1665
+ return e;
1666
+ };
1667
+ for (const [key, account] of accounts) {
1668
+ const e = entry(key);
1669
+ if (account === undefined)
1670
+ e.absent = true;
1671
+ // A COPY: the engine is handed the object through the state manager, and
1672
+ // the sealed record must go on saying what the account was.
1673
+ else
1674
+ e.account = copyAccount(account);
1675
+ }
1676
+ for (const [key, value] of code)
1677
+ entry(key).code = value ?? new Uint8Array(0);
1678
+ for (const addressKey of cleared)
1679
+ entry(unpackAddressKey(addressKey)).clearStorage = true;
1680
+ for (const [addressKey, slots] of storage) {
1681
+ const e = entry(unpackAddressKey(addressKey));
1682
+ for (const [slotKey, value] of slots)
1683
+ e.slots.push({
1684
+ key: hexToBytes(unpackSlotKey(slotKey)),
1685
+ value: value ?? new Uint8Array(0),
1686
+ });
1687
+ }
1688
+ return [...entries.values()];
1689
+ }
1690
+ /**
1691
+ * PARSE geth-STYLE STATE OVERRIDES into {@link StateEntry}s. `eth_call` and
1692
+ * `eth_estimateGas` take them as their third parameter:
1693
+ * `{[address]: {balance?, nonce?, code?, state?, stateDiff?}}`, where `state`
1694
+ * REPLACES the account's whole storage and `stateDiff` patches individual
1695
+ * slots. They used to be ignored, which answered a question the caller had not
1696
+ * asked, with no error.
1697
+ *
1698
+ * PARSED BEFORE ANY LEVEL IS OPENED, into values that cannot fail to apply, so
1699
+ * a malformed override is a -32602 naming it (never a raw `SyntaxError` from
1700
+ * `BigInt`), and a refusal never has a half-applied override to unwind.
1701
+ *
1702
+ * ## What is refused
1703
+ *
1704
+ * `state` and `stateDiff` on the same account (geth refuses that too), and any
1705
+ * field this node does not implement (`movePrecompileToAddress`, for one): a
1706
+ * -32602 naming it, never a call run without it.
1707
+ */
1708
+ function parseStateOverrides(overrides, method) {
1709
+ if (overrides == null)
1710
+ return [];
1711
+ if (typeof overrides !== 'object' || Array.isArray(overrides))
1712
+ throw new RpcError(-32602, `invalid state overrides for ${method}: expected an object keyed by address.`);
1713
+ const supported = new Set([
1714
+ 'balance',
1715
+ 'nonce',
1716
+ 'code',
1717
+ 'state',
1718
+ 'stateDiff',
1719
+ ]);
1720
+ const bad = (what) => {
1721
+ throw new RpcError(-32602, `invalid state override in ${method}: ${what}.`);
1722
+ };
1723
+ const quantity = (v, what) => {
1724
+ if (typeof v !== 'string' || !/^0x[0-9a-fA-F]+$/.test(v))
1725
+ return bad(`${what} must be a hex quantity, got ${JSON.stringify(v)}`);
1726
+ const n = BigInt(v);
1727
+ // A 32-byte word is the widest thing any override field names.
1728
+ if (n >= 1n << 256n)
1729
+ return bad(`${what} does not fit in 32 bytes`);
1730
+ return n;
1731
+ };
1732
+ const data = (v, what) => {
1733
+ if (typeof v !== 'string' || !/^0x([0-9a-fA-F]{2})*$/.test(v))
1734
+ return bad(`${what} must be even-length hex, got ${JSON.stringify(v)}`);
1735
+ return hexToBytes(v);
1736
+ };
1737
+ return Object.entries(overrides).map(([addr, o]) => {
1738
+ if (o == null || typeof o !== 'object' || Array.isArray(o))
1739
+ return bad(`the override for ${addr} must be an object`);
1740
+ for (const k of Object.keys(o))
1741
+ if (!supported.has(k))
1742
+ throw new RpcError(-32602, `state override field not supported by this node: ${addr}.${k} in ${method}. ` +
1743
+ `Supported: balance, nonce, code, state, stateDiff.`);
1744
+ if (o.state != null && o.stateDiff != null)
1745
+ throw new RpcError(-32602, `account ${addr} has both 'state' and 'stateDiff' in ${method}; pass one.`);
1746
+ let address;
1747
+ try {
1748
+ address = createAddressFromString(addr);
1749
+ }
1750
+ catch {
1751
+ return bad(`${JSON.stringify(addr)} is not an address`);
1752
+ }
1753
+ const slotsIn = o.state ?? o.stateDiff;
1754
+ if (slotsIn != null &&
1755
+ (typeof slotsIn !== 'object' || Array.isArray(slotsIn)))
1756
+ return bad(`${addr}.${o.state != null ? 'state' : 'stateDiff'} must be an object of slot -> value`);
1757
+ const slots = Object.entries(slotsIn ?? {}).map(([slot, val]) => {
1758
+ const value = data(val, `${addr} slot ${slot}`);
1759
+ // A slot value is ONE word: a longer one would be silently truncated
1760
+ // to its low 32 bytes by the padding below, so it is refused.
1761
+ if (value.length > 32)
1762
+ return bad(`${addr} slot ${slot} value is longer than 32 bytes`);
1763
+ return {
1764
+ key: setLengthLeft(bigIntToBytes(quantity(slot, `${addr} slot key`)), 32),
1765
+ // SHORTEST FORM, as the EVM itself stores a value: a padded zero
1766
+ // and a missing slot must be the same thing to SSTORE's gas rules.
1767
+ value: unpadBytes(setLengthLeft(value, 32)),
1768
+ };
1769
+ });
1770
+ return {
1771
+ address,
1772
+ balance: o.balance != null
1773
+ ? quantity(o.balance, `${addr}.balance`)
1774
+ : undefined,
1775
+ nonce: o.nonce != null ? quantity(o.nonce, `${addr}.nonce`) : undefined,
1776
+ code: o.code != null ? data(o.code, `${addr}.code`) : undefined,
1777
+ clearStorage: o.state != null,
1778
+ slots,
1779
+ absent: false,
1780
+ };
1781
+ });
1782
+ }
1783
+ /**
1784
+ * RUN A READ WITH STATE ENTRIES WRITTEN INTO A CHECKPOINT IT OPENS, and leave
1785
+ * no trace of them. The entries are K's state for a historical call
1786
+ * ({@link historicalEntries}) followed by the caller's state overrides
1787
+ * ({@link parseStateOverrides}), so the overrides land ON TOP of K's state,
1788
+ * as geth applies them on top of the block's. With no entries (a call at the
1789
+ * head without overrides) no level is opened at all.
1790
+ *
1791
+ * ## Why a checkpoint here is safe, given the hazard documented at `serialise`
1792
+ *
1793
+ * The corruption described there needs two executions to interleave on the one
1794
+ * checkpoint stack. This level is opened and closed by the SAME request, inside
1795
+ * the serialisation point, with the read nested strictly inside it: the default
1796
+ * engine's own checkpoint/revert lands on top of this one and pops before this
1797
+ * one does, and revm reads the top of the stack on every access and never
1798
+ * commits. So the stack is `[base, entries, (call)]` and unwinds in order,
1799
+ * whether the read returns, reverts or throws (the `finally`). It is also the
1800
+ * same mechanism `evmCall` already relies on for purity, one level lower. The
1801
+ * derived trie of a `computeStateRoot` node is never involved: change-set recording is
1802
+ * suspended for the read and the level is reverted, so nothing it wrote is
1803
+ * ever named to the trie.
1804
+ */
1805
+ async function withStateEntries(entries, read) {
1806
+ if (entries.length === 0)
1807
+ return read();
1808
+ await sm.checkpoint();
1809
+ try {
1810
+ for (const e of entries)
1811
+ await applyStateEntry(e);
1812
+ return await read();
1813
+ }
1814
+ finally {
1815
+ await sm.revert();
1816
+ }
1817
+ }
1818
+ /**
1819
+ * WRITE ONE {@link StateEntry} into the top level. The ONE apply step shared by
1820
+ * the RPC override path and the historical path.
1821
+ *
1822
+ * ORDER MATTERS, and each step re-reads the account so no step writes back a
1823
+ * stale copy over the previous one:
1824
+ *
1825
+ * 1. CODE FIRST. `putCode` rewrites the account's `codeHash`, and CREATES an
1826
+ * empty account when there is none, so it must come before
1827
+ * anything that states the account.
1828
+ * 2. THE ACCOUNT: a whole account replaces what `putCode` left (its `codeHash`
1829
+ * is K's own), and `balance` / `nonce` are a read-modify-write on top.
1830
+ * 3. STORAGE: a clear, then the slots.
1831
+ * 4. ABSENT LAST: an empty code entry, then `deleteAccount`. The account must
1832
+ * read as ABSENT, not as a zero account, and two upstream behaviours stand
1833
+ * in the way: `putCode` creates an account (so the code is emptied BEFORE
1834
+ * the delete), and `deleteAccount` leaves the address's code in the code
1835
+ * map, where `eth_getCode` and the default engine's `EXTCODESIZE` would
1836
+ * still see it (so the code is emptied at all). `deleteAccount` also clears
1837
+ * the storage.
1838
+ */
1839
+ async function applyStateEntry(e) {
1840
+ if (e.code !== undefined)
1841
+ await sm.putCode(e.address, e.code);
1842
+ if (e.account !== undefined)
1843
+ await sm.putAccount(e.address, e.account);
1844
+ if (e.balance !== undefined || e.nonce !== undefined) {
1845
+ const acc = (await sm.getAccount(e.address)) ?? new Account();
1846
+ if (e.balance !== undefined)
1847
+ acc.balance = e.balance;
1848
+ if (e.nonce !== undefined)
1849
+ acc.nonce = e.nonce;
1850
+ await sm.putAccount(e.address, acc);
1851
+ }
1852
+ if (e.clearStorage)
1853
+ await sm.clearStorage(e.address);
1854
+ for (const { key, value } of e.slots)
1855
+ await sm.putStorage(e.address, key, value);
1856
+ if (e.absent) {
1857
+ await sm.putCode(e.address, new Uint8Array(0));
1858
+ await sm.deleteAccount(e.address);
1859
+ }
1860
+ }
1861
+ /**
1862
+ * geth's `eth_call` takes BLOCK overrides as a fourth parameter. This node does
1863
+ * not implement them, so a request carrying them is refused rather than run
1864
+ * against the real block environment.
1865
+ */
1866
+ function refuseBlockOverrides(blockOverrides, method) {
1867
+ if (blockOverrides == null)
1868
+ return;
1869
+ throw new RpcError(-32602, `block overrides are not supported by this node (${method}, 4th parameter). ` +
1870
+ `The call would otherwise run against the real block environment.`);
1871
+ }
1113
1872
  // ---------- eth_call / estimateGas through the ENGINE's READ half (no signing) ----
1114
1873
  /**
1115
1874
  * The node's single pure-read helper, and the read half of the engine seam: it
@@ -1122,8 +1881,16 @@ export async function createNode(options = {}) {
1122
1881
  * `@ethereumjs/evm` engine checkpoints/reverts and resets EIP-2929 warmth
1123
1882
  * because that EVM requires it; an engine that cannot commit pays for neither.
1124
1883
  * See ./engine.ts.
1884
+ *
1885
+ * `block` is the block the call executes IN: the head's for a call at the
1886
+ * head, block K's stored `Block` for a call pinned to K, so `NUMBER`,
1887
+ * `TIMESTAMP`, `COINBASE`, `PREVRANDAO`, `BASEFEE` and `GASLIMIT` are K's. It
1888
+ * also bounds `BLOCKHASH`: both engines answer zero for any number at or above
1889
+ * the block's own, so a call at K cannot see the hash of K or of anything
1890
+ * after it without any further mechanism (measured on both engines by
1891
+ * `test/historical-call.spec.ts` and its revm twin).
1125
1892
  */
1126
- async function evmCall(params, budget) {
1893
+ async function evmCall(params, block, budget) {
1127
1894
  const from = params.from
1128
1895
  ? createAddressFromString(params.from)
1129
1896
  : createAddressFromString('0x0000000000000000000000000000000000000000');
@@ -1168,7 +1935,7 @@ export async function createNode(options = {}) {
1168
1935
  data,
1169
1936
  value,
1170
1937
  gasLimit,
1171
- block: blockStore.get(latestNumber).block,
1938
+ block,
1172
1939
  });
1173
1940
  }
1174
1941
  /**
@@ -1242,7 +2009,7 @@ export async function createNode(options = {}) {
1242
2009
  * points callers HERE for "the number a transaction needs", so the node must
1243
2010
  * never refuse a limit it has just recommended.
1244
2011
  */
1245
- async function estimateGas(p) {
2012
+ async function estimateGas(p, block) {
1246
2013
  const dataHex = p.data ?? p.input ?? '0x';
1247
2014
  const isCreate = !p.to;
1248
2015
  const overhead = intrinsicGas(dataHex, isCreate, common) + accessListGas(p.accessList);
@@ -1252,6 +2019,11 @@ export async function createNode(options = {}) {
1252
2019
  // back a number it will not accept. `gas` on an `eth_estimateGas` request is
1253
2020
  // geth's cap on the SEARCH ("do not consider limits above this"), which is a
1254
2021
  // different thing from `gas` on an `eth_call` ("let it run this long").
2022
+ //
2023
+ // AT A PAST BLOCK K THE CAP IS STILL THIS ONE, not K's own `gasLimit`,
2024
+ // deliberately (historical-eth-call): the number is for a transaction to be
2025
+ // SUBMITTED now, and what it meets is the limit of the blocks this node
2026
+ // mines, whatever K's was. `block` only decides what the probes execute in.
1255
2027
  const supplied = p.gas != null ? BigInt(p.gas) : undefined;
1256
2028
  const cap = supplied === undefined || supplied > minedBlockGasLimit
1257
2029
  ? minedBlockGasLimit
@@ -1269,7 +2041,7 @@ export async function createNode(options = {}) {
1269
2041
  ? `The allowance is the \`gas\` you passed on the request; raise it or omit it.`
1270
2042
  : `The allowance is this node's block gas limit; raise it with createNode({blockGasLimit: ...}).`));
1271
2043
  }
1272
- const probe = (limit) => evmCall(p, limit - overhead);
2044
+ const probe = (limit) => evmCall(p, block, limit - overhead);
1273
2045
  // 1) THE UPPER BOUND, run first: a request that cannot succeed with all the
1274
2046
  // gas there is cannot succeed at all, and the caller learns that here rather
1275
2047
  // than from a receipt.
@@ -1395,18 +2167,39 @@ export async function createNode(options = {}) {
1395
2167
  const sb = num != null ? blockStore.get(num) : undefined;
1396
2168
  return sb ? blockToRpc(sb, Boolean(params[1])) : null;
1397
2169
  }
2170
+ // AT THE HEAD OR AT A BLOCK K IN THE `stateHistory` WINDOW, through the one
2171
+ // gate every state read uses (`historicalBlock`). At K the engine runs with
2172
+ // K's stored `Block` on K's state, written into a checkpoint the request
2173
+ // opens and reverts (`historicalEntries`, `withStateEntries`), with the
2174
+ // caller's state overrides applied ON TOP of it.
1398
2175
  case 'eth_call': {
1399
- const r = await evmCall(params[0] ?? {});
2176
+ const k = historicalBlock(params[1], 'eth_call');
2177
+ refuseBlockOverrides(params[3], 'eth_call');
2178
+ const entries = [
2179
+ ...(k === undefined ? [] : historicalEntries(k)),
2180
+ ...parseStateOverrides(params[2], 'eth_call'),
2181
+ ];
2182
+ const block = blockStore.get(k ?? latestNumber).block;
2183
+ const r = await pureRead(() => withStateEntries(entries, () => evmCall(params[0] ?? {}, block)));
1400
2184
  if (r.error)
1401
2185
  throw new RpcError(3, 'execution reverted', hex(r.returnValue));
1402
2186
  return hex(r.returnValue);
1403
2187
  }
1404
- case 'eth_estimateGas':
2188
+ case 'eth_estimateGas': {
1405
2189
  // THE SMALLEST GAS LIMIT AT WHICH THIS REQUEST SUCCEEDS, found by
1406
2190
  // re-executing it. The whole method is {@link estimateGas} above,
1407
2191
  // including why it is a search rather than the run-and-measure it used to
1408
- // be, and where the request's EIP-2930 access list is charged.
1409
- return numHex(await estimateGas(params[0] ?? {}));
2192
+ // be, and where the request's EIP-2930 access list is charged. The whole
2193
+ // search runs inside ONE checkpoint holding K's state (and the overrides).
2194
+ const k = historicalBlock(params[1], 'eth_estimateGas');
2195
+ refuseBlockOverrides(params[3], 'eth_estimateGas');
2196
+ const entries = [
2197
+ ...(k === undefined ? [] : historicalEntries(k)),
2198
+ ...parseStateOverrides(params[2], 'eth_estimateGas'),
2199
+ ];
2200
+ const block = blockStore.get(k ?? latestNumber).block;
2201
+ return numHex(await pureRead(() => withStateEntries(entries, () => estimateGas(params[0] ?? {}, block))));
2202
+ }
1410
2203
  case 'eth_fillTransaction': {
1411
2204
  // Fill the missing fields of a tx request and return {tx, raw} like geth
1412
2205
  // does (the `raw` is the UNSIGNED serialization — the node has no keys; a
@@ -1417,8 +2210,9 @@ export async function createNode(options = {}) {
1417
2210
  const from = p.from
1418
2211
  ? createAddressFromString(p.from)
1419
2212
  : createAddressFromString('0x0000000000000000000000000000000000000000');
1420
- const acc = await sm.getAccount(from);
1421
- const nonce = p.nonce != null ? BigInt(p.nonce) : (acc?.nonce ?? 0n);
2213
+ // The PENDING nonce, as geth fills it: the account's nonce advanced past
2214
+ // the transactions it already has queued.
2215
+ const nonce = p.nonce != null ? BigInt(p.nonce) : await pendingNonce(from);
1422
2216
  const value = p.value != null ? BigInt(p.value) : 0n;
1423
2217
  const dataHex = p.data ?? p.input ?? '0x';
1424
2218
  const isCreate = !p.to;
@@ -1435,7 +2229,7 @@ export async function createNode(options = {}) {
1435
2229
  // `accessListGas` in ./intrinsic-gas.ts.
1436
2230
  const gas = p.gas != null
1437
2231
  ? BigInt(p.gas)
1438
- : await estimateGas({ ...p, gas: undefined, accessList: undefined });
2232
+ : await pureRead(() => estimateGas({ ...p, gas: undefined, accessList: undefined }, blockStore.get(latestNumber).block));
1439
2233
  // Fee fields: legacy iff caller passed gasPrice (and no 1559 fields),
1440
2234
  // otherwise EIP-1559 with the node's constant fee market.
1441
2235
  const isLegacy = p.gasPrice != null &&
@@ -1491,28 +2285,53 @@ export async function createNode(options = {}) {
1491
2285
  };
1492
2286
  return { raw: hex(unsigned.serialize()), tx };
1493
2287
  }
2288
+ // EVERY state read at a block is gated first: served at the head, served
2289
+ // from the undo log inside the `stateHistory` window (these four only,
2290
+ // through `historicalBlock`), and REFUSED below it, never answered from the
2291
+ // head for a block that is not the head.
1494
2292
  case 'eth_getBalance': {
1495
- const acc = await sm.getAccount(createAddressFromString(params[0]));
2293
+ const k = historicalBlock(params[1], 'eth_getBalance');
2294
+ const address = createAddressFromString(params[0]);
2295
+ const acc = k === undefined
2296
+ ? await sm.getAccount(address)
2297
+ : await accountAt(k, address);
1496
2298
  return numHex(acc?.balance ?? 0n);
1497
2299
  }
1498
2300
  case 'eth_getTransactionCount': {
1499
- const acc = await sm.getAccount(createAddressFromString(params[0]));
1500
- return numHex(acc?.nonce ?? 0n);
2301
+ const k = historicalBlock(params[1], 'eth_getTransactionCount');
2302
+ const address = createAddressFromString(params[0]);
2303
+ if (k !== undefined)
2304
+ return numHex((await accountAt(k, address))?.nonce ?? 0n);
2305
+ // `pending` COUNTS THE QUEUED TRANSACTIONS, the one state read where it
2306
+ // differs from the head: a client picking a nonce asks for `pending`
2307
+ // (viem does by default), and in manual/interval mining two sends
2308
+ // before a mine would otherwise get the SAME nonce, the second then
2309
+ // refused at mine time as a replay.
2310
+ return numHex(params[1] === 'pending'
2311
+ ? await pendingNonce(address)
2312
+ : ((await sm.getAccount(address))?.nonce ?? 0n));
1501
2313
  }
1502
2314
  case 'eth_getCode': {
1503
- const code = await sm.getCode(createAddressFromString(params[0]));
1504
- return hex(code);
2315
+ const k = historicalBlock(params[1], 'eth_getCode');
2316
+ const address = createAddressFromString(params[0]);
2317
+ return hex(k === undefined
2318
+ ? await sm.getCode(address)
2319
+ : await codeAt(k, address));
1505
2320
  }
1506
2321
  case 'eth_getStorageAt': {
2322
+ const k = historicalBlock(params[2], 'eth_getStorageAt');
1507
2323
  const addr = createAddressFromString(params[0]);
1508
2324
  const slot = setLengthLeft(bigIntToBytes(BigInt(params[1])), 32);
1509
- const val = await sm.getStorage(addr, slot);
2325
+ const val = k === undefined
2326
+ ? await sm.getStorage(addr, slot)
2327
+ : await storageAt(k, addr, slot);
1510
2328
  return hex(setLengthLeft(val, 32));
1511
2329
  }
1512
2330
  // ---- Runtime state cheats (anvil/hardhat-style; for tests/local tooling) ----
1513
2331
  // These MUTATE state directly (no tx). Honest about being non-standard: they
1514
- // are `evm_*`-namespaced. In trie mode each commits into the trie so the next
1515
- // getStateRoot() reflects the change.
2332
+ // are `evm_*`-namespaced. They write the flat state only; on a `computeStateRoot` node the
2333
+ // open record names what they wrote, so the next getStateRoot() (or mined
2334
+ // block) rehashes it into the derived trie.
1516
2335
  case 'evm_setBalance': {
1517
2336
  // params: [address, valueHex]
1518
2337
  const addr = createAddressFromString(params[0]);
@@ -1533,8 +2352,6 @@ export async function createNode(options = {}) {
1533
2352
  // params: [address, codeHex]
1534
2353
  const addr = createAddressFromString(params[0]);
1535
2354
  await sm.putCode(addr, hexToBytes(params[1]));
1536
- touchedAccounts.add(addr.toString());
1537
- await commitIfTrie();
1538
2355
  return true;
1539
2356
  }
1540
2357
  case 'evm_setStorageAt': {
@@ -1542,8 +2359,6 @@ export async function createNode(options = {}) {
1542
2359
  const addr = createAddressFromString(params[0]);
1543
2360
  const slot = setLengthLeft(bigIntToBytes(BigInt(params[1])), 32);
1544
2361
  await sm.putStorage(addr, slot, setLengthLeft(hexToBytes(params[2]), 32));
1545
- touchedAccounts.add(addr.toString());
1546
- await commitIfTrie();
1547
2362
  return true;
1548
2363
  }
1549
2364
  case 'evm_setAccount': {
@@ -1561,7 +2376,6 @@ export async function createNode(options = {}) {
1561
2376
  for (const [slot, val] of Object.entries(a.storage ?? {})) {
1562
2377
  await sm.putStorage(addr, setLengthLeft(bigIntToBytes(BigInt(slot)), 32), setLengthLeft(hexToBytes(val), 32));
1563
2378
  }
1564
- await commitIfTrie();
1565
2379
  return true;
1566
2380
  }
1567
2381
  case 'eth_gasPrice':
@@ -1569,7 +2383,45 @@ export async function createNode(options = {}) {
1569
2383
  case 'eth_maxPriorityFeePerGas':
1570
2384
  return numHex(maxPriorityFeePerGas);
1571
2385
  case 'eth_feeHistory': {
1572
- const count = Number(BigInt(params[0] ?? '0x1'));
2386
+ // params: [blockCount, newestBlock, rewardPercentiles]. `newestBlock` is
2387
+ // HONOURED (it used to be ignored, and the window always ended at the head),
2388
+ // and the per-block base fee and gas-used ratio are the stored blocks' own.
2389
+ // Only `reward` stays synthetic: this node's priority fee is a constant.
2390
+ const rawCount = params[0] ?? '0x1';
2391
+ const requested = typeof rawCount === 'number' && Number.isSafeInteger(rawCount)
2392
+ ? rawCount
2393
+ : typeof rawCount === 'string' && /^0x[0-9a-fA-F]+$/.test(rawCount)
2394
+ ? Number(BigInt(rawCount))
2395
+ : NaN;
2396
+ if (!(requested >= 0))
2397
+ throw new RpcError(-32602, `invalid eth_feeHistory blockCount: ${JSON.stringify(rawCount)}. Expected a hex quantity.`);
2398
+ const newest = resolveBlockTag(params[1] ?? 'latest');
2399
+ if (newest > latestNumber)
2400
+ throw new RpcError(-32000, `request beyond head block: eth_feeHistory newestBlock is ${newest}, but the head of this node is block ${latestNumber}.`);
2401
+ // geth caps a request at 1024 blocks, and nothing precedes block 0.
2402
+ const count = Math.max(0, Math.min(requested, 1024, newest + 1));
2403
+ const oldest = newest - count + 1;
2404
+ const nextBaseFee = (n) => {
2405
+ const sb = blockStore.get(n);
2406
+ return sb
2407
+ ? sb.header.baseFeePerGas
2408
+ : numHex(blockEnv?.baseFeePerGas ?? baseFeePerGas);
2409
+ };
2410
+ const ratio = (n) => {
2411
+ // The header's own `gasUsed` is a documented 0x0 placeholder, so the
2412
+ // block's usage is summed from its receipts, which are real.
2413
+ const sb = blockStore.get(n);
2414
+ if (!sb)
2415
+ return 0;
2416
+ let used = 0n;
2417
+ for (const th of sb.header.transactions) {
2418
+ const r = receipts.get(th);
2419
+ if (r)
2420
+ used += BigInt(r.gasUsed);
2421
+ }
2422
+ const limit = BigInt(sb.header.gasLimit);
2423
+ return limit === 0n ? 0 : Number(used) / Number(limit);
2424
+ };
1573
2425
  // `reward` must carry ONE entry per requested percentile, per block. Returning a
1574
2426
  // single entry regardless of `rewardPercentiles` breaks any caller that asks for
1575
2427
  // several and indexes them: rocketh requests [10, 50, 80] and reads index 1 and 2,
@@ -1579,9 +2431,15 @@ export async function createNode(options = {}) {
1579
2431
  const percentiles = Array.isArray(params[2]) ? params[2] : [];
1580
2432
  const rewardPerBlock = (percentiles.length > 0 ? percentiles : [50]).map(() => numHex(maxPriorityFeePerGas));
1581
2433
  return {
1582
- oldestBlock: numHex(Math.max(0, latestNumber - count + 1)),
1583
- baseFeePerGas: Array.from({ length: count + 1 }, () => numHex(baseFeePerGas)),
1584
- gasUsedRatio: Array.from({ length: count }, () => 0.5),
2434
+ // An empty window is geth's empty answer, oldestBlock included.
2435
+ oldestBlock: numHex(count === 0 ? 0 : oldest),
2436
+ // One per block in the window PLUS the block after it, which is the
2437
+ // stored block when there is one and the next block this node will mine
2438
+ // when the window ends at the head.
2439
+ baseFeePerGas: count === 0
2440
+ ? []
2441
+ : Array.from({ length: count + 1 }, (_, i) => nextBaseFee(oldest + i)),
2442
+ gasUsedRatio: Array.from({ length: count }, (_, i) => ratio(oldest + i)),
1585
2443
  reward: Array.from({ length: count }, () => rewardPerBlock),
1586
2444
  };
1587
2445
  }
@@ -1621,8 +2479,28 @@ export async function createNode(options = {}) {
1621
2479
  // is deferred — see tasks/slim-node-eth-getlogs-index.md. Keep this scan as
1622
2480
  // the authoritative semantics if/when an index is added.
1623
2481
  const f = params[0] ?? {};
1624
- const from = f.fromBlock != null ? resolveBlockTag(f.fromBlock) : 0;
1625
- const to = f.toBlock != null ? resolveBlockTag(f.toBlock) : latestNumber;
2482
+ // `blockHash` (EIP-234) pins the query to ONE block. It used to be ignored,
2483
+ // which returned the logs of EVERY block. It excludes a range, as in geth,
2484
+ // and a hash no block has is an error rather than an empty result, so a
2485
+ // typo cannot read as "that block emitted nothing".
2486
+ let from;
2487
+ let to;
2488
+ if (f.blockHash != null) {
2489
+ if (f.fromBlock != null || f.toBlock != null)
2490
+ throw new RpcError(-32602, 'invalid eth_getLogs filter: cannot specify both blockHash and fromBlock/toBlock.');
2491
+ const n = blockByHash.get(String(f.blockHash).toLowerCase());
2492
+ if (n === undefined)
2493
+ throw new RpcError(-32000, `unknown block: eth_getLogs blockHash ${f.blockHash} is not a block on this node.`);
2494
+ from = n;
2495
+ to = n;
2496
+ }
2497
+ else {
2498
+ // geth's default for an omitted `fromBlock` is `latest`, not 0; this
2499
+ // node has always defaulted to 0 and that is kept (changing it would
2500
+ // silently shrink every existing consumer's results).
2501
+ from = f.fromBlock != null ? resolveBlockTag(f.fromBlock) : 0;
2502
+ to = f.toBlock != null ? resolveBlockTag(f.toBlock) : latestNumber;
2503
+ }
1626
2504
  const addrFilter = f.address
1627
2505
  ? (Array.isArray(f.address) ? f.address : [f.address]).map((a) => a.toLowerCase())
1628
2506
  : null;
@@ -1678,48 +2556,28 @@ export async function createNode(options = {}) {
1678
2556
  const accounts = {};
1679
2557
  const code = {};
1680
2558
  const storage = {};
1681
- if (stateMode === 'trie') {
1682
- // Trie mode dumps accounts + code via the touched-account set. NOTE: it does
1683
- // NOT dump contract STORAGE — the EVM journals storage on an internal
1684
- // shallowCopy of the state manager that bypasses any interception, and the
1685
- // trie's own dumpStorage exposes only keccak-HASHED slot keys (not the raw
1686
- // slots loadState needs). Full-storage persistence is a 'none'-mode feature
1687
- // (where the live Map IS the committed state). Trie mode is for the REAL
1688
- // state root (conformance block roots), not for IndexedDB persist.
1689
- for (const addr of touchedAccounts) {
1690
- const address = createAddressFromString(addr);
1691
- const acc = await sm.getAccount(address);
1692
- if (acc === undefined)
1693
- continue;
2559
+ // EVERY NODE DUMPS THE SAME WAY, storage included: the account and code
2560
+ // stacks are plain Maps whose TOP frame is the live set, and storage is
2561
+ // per-account with per-checkpoint OVERLAYS, flattened by liveStorage(). A
2562
+ // `computeStateRoot` node runs on this same flat state, and its derived trie is NOT
2563
+ // serialised: `loadState` rebuilds it from the loaded flat state.
2564
+ //
2565
+ // THE SERIALISED FORMAT IS NOT THE INTERNAL LAYOUT and must not follow it:
2566
+ // this output is persisted data (IndexedDB, loadState fixtures) with existing
2567
+ // state behind it. It stays `{address: {slot: value}}` in 0x-hex, and
2568
+ // `test/storage-overlay.spec.ts` asserts it byte-identical to a dump taken
2569
+ // from the pre-overlay flat layout.
2570
+ const accMap = sm.accountStack[sm.accountStack.length - 1];
2571
+ const codeMap = sm.codeStack[sm.codeStack.length - 1];
2572
+ for (const [addr, acc] of accMap) {
2573
+ if (acc !== undefined)
1694
2574
  accounts[addr] = hex(acc.serialize());
1695
- const c = await sm.getCode(address);
1696
- if (c.length > 0)
1697
- code[addr] = hex(c);
1698
- }
1699
2575
  }
1700
- else {
1701
- // 'none' mode: the account and code stacks are still plain Maps whose TOP
1702
- // frame is the live set, and storage is per-account with per-checkpoint
1703
- // OVERLAYS, flattened by liveStorage(). Dump both directly (no trie walk).
1704
- //
1705
- // THE SERIALISED FORMAT IS NOT THE INTERNAL LAYOUT and must not follow it:
1706
- // this output is persisted data (IndexedDB, loadState fixtures) with existing
1707
- // state behind it. It stays `{address: {slot: value}}` in 0x-hex, and
1708
- // `test/storage-overlay.spec.ts` asserts it byte-identical to a dump taken
1709
- // from the pre-overlay flat layout.
1710
- const live = sm;
1711
- const accMap = live.accountStack[live.accountStack.length - 1];
1712
- const codeMap = live.codeStack[live.codeStack.length - 1];
1713
- for (const [addr, acc] of accMap) {
1714
- if (acc !== undefined)
1715
- accounts[addr] = hex(acc.serialize());
1716
- }
1717
- for (const [addr, c] of codeMap)
1718
- code[addr] = hex(c);
1719
- for (const [addr, slots] of live.liveStorage()) {
1720
- for (const [slot, val] of slots)
1721
- (storage[addr] ??= {})[slot] = hex(val);
1722
- }
2576
+ for (const [addr, c] of codeMap)
2577
+ code[addr] = hex(c);
2578
+ for (const [addr, slots] of sm.liveStorage()) {
2579
+ for (const [slot, val] of slots)
2580
+ (storage[addr] ??= {})[slot] = hex(val);
1723
2581
  }
1724
2582
  const blocks = [];
1725
2583
  for (let i = 0; i <= latestNumber; i++) {
@@ -1730,15 +2588,81 @@ export async function createNode(options = {}) {
1730
2588
  return {
1731
2589
  version: 1,
1732
2590
  chainId,
1733
- stateMode,
1734
2591
  accounts,
1735
2592
  code,
1736
2593
  storage,
1737
2594
  blocks,
1738
2595
  receipts: Object.fromEntries(receipts),
1739
2596
  transactions: Object.fromEntries(transactions),
2597
+ // ADDITIVE: a node without `stateHistory` writes no field at all, so its
2598
+ // dump is exactly what it was before history existed.
2599
+ ...(stateHistoryBlocks === undefined ? {} : { history: dumpHistory() }),
1740
2600
  };
1741
2601
  }
2602
+ /**
2603
+ * THE UNDO LOG AS THE DUMP CARRIES IT: one serialized record per sealed block,
2604
+ * oldest first, with the OPEN record FOLDED INTO THE HEAD'S RECORD (older
2605
+ * entry winning).
2606
+ *
2607
+ * WHY FOLD rather than dump the open record as a field of its own: `loadState`
2608
+ * treats the loaded state as a baseline and CLEARS the open record, so the
2609
+ * writes since the head was mined (`evm_set*` cheats, a batch that threw
2610
+ * mid-block) become part of the loaded head, which reads them live exactly as
2611
+ * it did before the dump. What must not be lost is their prior values, which
2612
+ * every read BELOW the head consults after the sealed records. Folding keeps
2613
+ * the per-key earliest-wins union over `undo[K+1] .. undo[head]` + open
2614
+ * identical for every K below the head: a key the head's record already names
2615
+ * keeps that (older) value; a key it does not name did not change in the head
2616
+ * block, so its value at the end of the block before equals its value at the
2617
+ * end of the head, which is what the open record holds. The alternative, a
2618
+ * separate `open` field restored as the open record, would make the next mined
2619
+ * block after a reload own writes made before it, and would have been a second
2620
+ * new field for the same answers.
2621
+ *
2622
+ * With NO record for the head (the head is where history starts: genesis, or a
2623
+ * loaded head nothing was mined on), no block below the head is servable, and
2624
+ * the open record is dropped with nothing lost.
2625
+ *
2626
+ * Decisions around the format (this fold, the contiguous restore, `[]` vs no
2627
+ * key) are recorded in
2628
+ * `work/notes/observations/state-history-persistence-decisions.md`.
2629
+ */
2630
+ function dumpHistory() {
2631
+ const out = sealed.map((r) => serializeChangeSet(r.number, r.changes));
2632
+ const open = changeSets?.peekChangeSet();
2633
+ const head = out[out.length - 1];
2634
+ if (open !== undefined &&
2635
+ head !== undefined &&
2636
+ head.number === latestNumber)
2637
+ mergeSerializedOlderWins(head, serializeChangeSet(latestNumber, open));
2638
+ return out;
2639
+ }
2640
+ /**
2641
+ * RESTORE the undo log from a dump's `history` (see {@link dumpHistory}), after
2642
+ * the rest of the state is loaded and {@link latestNumber} is the dump's head.
2643
+ * Only the CONTIGUOUS run of records ending at the head block is kept, newest
2644
+ * first, stopping at the first gap and at this node's window (a record at or
2645
+ * below `head - N` serves no block in it, so a dump with more history than N
2646
+ * is truncated to N, and one with less serves what it has). A dump the writer
2647
+ * produced has no gap; a hand-edited or foreign one might, and a read below a
2648
+ * gap would silently be answered from a later state, which is the one thing
2649
+ * the history exists not to do. {@link historyFloor} becomes the block before
2650
+ * the oldest record kept, or the head when none is.
2651
+ */
2652
+ function loadHistory(history, window) {
2653
+ const kept = [];
2654
+ let expected = latestNumber;
2655
+ for (let i = history.length - 1; i >= 0; i--) {
2656
+ const record = history[i];
2657
+ if (record.number !== expected || record.number <= latestNumber - window)
2658
+ break;
2659
+ kept.push({ number: record.number, changes: deserializeChangeSet(record) });
2660
+ expected--;
2661
+ }
2662
+ kept.reverse();
2663
+ sealed.push(...kept);
2664
+ historyFloor = kept.length > 0 ? kept[0].number - 1 : latestNumber;
2665
+ }
1742
2666
  async function loadState(state) {
1743
2667
  // Rehydrate accounts/code/storage directly into SimpleStateManager.
1744
2668
  for (const [addr, accHex] of Object.entries(state.accounts)) {
@@ -1816,6 +2740,26 @@ export async function createNode(options = {}) {
1816
2740
  latestNumber = sh.number;
1817
2741
  parentHash = block.hash();
1818
2742
  }
2743
+ // A LOADED STATE IS A BASELINE, NOT HISTORY: the record is cleared, like the
2744
+ // construction baselines at genesis. The dump carries no change set for its
2745
+ // head, so there is none to report for it either.
2746
+ changeSets?.takeChangeSet();
2747
+ headBlockChangeSet = undefined;
2748
+ // ...and the history the node held described the state this load just
2749
+ // replaced, so it goes. What replaces it is the dump's own history, when the
2750
+ // dump carries one and this node keeps any: otherwise history starts again at
2751
+ // the loaded head (an older dump, or a node without `stateHistory`, which
2752
+ // ignores the field).
2753
+ sealed.length = 0;
2754
+ historyFloor = latestNumber;
2755
+ if (stateHistoryBlocks !== undefined && state.history !== undefined)
2756
+ loadHistory(state.history, stateHistoryBlocks);
2757
+ // ...and the derived trie described that replaced state too. It is REBUILT
2758
+ // from the loaded flat state, once, exactly as at construction: the dump
2759
+ // carries no trie (it never has to: the flat state determines it), and a
2760
+ // load is a baseline in no change set, so nothing else would put it there.
2761
+ if (computeStateRoot)
2762
+ derivedTrie = await DerivedStateTrie.build(sm, common);
1819
2763
  }
1820
2764
  // ---------- persistence auto-load on creation ----------
1821
2765
  if (options.persistence) {
@@ -1897,35 +2841,75 @@ export async function createNode(options = {}) {
1897
2841
  // completion, including a `persistence.save()`, and only the timer stops adding
1898
2842
  // more. A caller that needs the node quiet should stop issuing requests and await
1899
2843
  // the ones it holds.
1900
- return {
1901
- request: (args) => serialise(() => persistingRequest(args)),
2844
+ //
2845
+ // `serveOn` is not serialised either, for the reason `dispose` is not: it
2846
+ // touches no state. It only relays `request`, which IS serialised, so a request
2847
+ // arriving over a served port queues exactly like one made directly.
2848
+ const publicRequest = (args) => serialise(() => persistingRequest(args));
2849
+ const node = {
2850
+ request: publicRequest,
1902
2851
  mine: () => serialise(mineAndPersist),
1903
2852
  dumpState: () => serialise(dumpState),
1904
2853
  loadState: (state) => serialise(() => loadState(state)),
1905
- stateMode,
2854
+ computeStateRoot,
1906
2855
  senderMode,
1907
2856
  // Identity only: the engine object itself stays internal, so the reading is a
1908
2857
  // plain value that survives a Worker/comlink boundary unchanged.
1909
2858
  engine: { id: engine.id },
1910
2859
  async getStateRoot() {
1911
- if (stateMode !== 'trie') {
1912
- throw new RpcError(-32004, "no state root in 'none' mode — create the node with stateMode:'trie' for a real Merkle-Patricia root");
2860
+ if (!computeStateRoot) {
2861
+ throw new RpcError(-32004, 'no state root: this node was created without computeStateRoot. Create it with computeStateRoot: true for a real Merkle-Patricia root');
1913
2862
  }
1914
- // SERIALISED like the rest, because this one READS BY WRITING: in trie mode
1915
- // `currentStateRoot` flushes the state manager's cache into the trie, so a
1916
- // root taken mid-transaction would both report an uncommitted state and
1917
- // push it into the trie on the way.
2863
+ // SERIALISED like the rest, because this one READS BY WRITING: it applies
2864
+ // the open record to the derived trie, which reads the COMMITTED flat state
2865
+ // and refuses to run with a checkpoint open, so a root taken
2866
+ // mid-transaction would report a state no block (or cheat) produced.
1918
2867
  return serialise(currentStateRoot);
1919
2868
  },
1920
2869
  onNewHead(cb) {
1921
2870
  headSubs.add(cb);
1922
2871
  return () => headSubs.delete(cb);
1923
2872
  },
2873
+ // SERVE `request` ON A HANDED PORT, via `@eip-1193/over-port`, so a consumer
2874
+ // on another thread uses this node through `providerOverPort(otherEnd)`.
2875
+ //
2876
+ // IT LIVES ON THE CORE NODE, NOT ONLY IN `webevm/worker-host`, so the two
2877
+ // kinds of node stay interchangeable: `SlimNode` carries it, the one worker
2878
+ // proxy forwards it (its `Required<SlimNode>` annotation demands that), and a
2879
+ // main-thread node answers the same call in place. The price is that the
2880
+ // core imports `@eip-1193/over-port` (about 6 kB of unminified JS, no
2881
+ // runtime dependency of its own), which `webevm/worker-client` and
2882
+ // `webevm/revm` still do not: the client only TRANSFERS the port, and
2883
+ // the consumer brings its own `providerOverPort`.
2884
+ //
2885
+ // Only `request` is served, bound to the SERIALISED entry point above.
2886
+ async serveOn(port) {
2887
+ const server = serveProvider({ request: publicRequest }, port);
2888
+ servedPorts.add(server);
2889
+ return {
2890
+ async close() {
2891
+ server.close();
2892
+ servedPorts.delete(server);
2893
+ },
2894
+ };
2895
+ },
1924
2896
  async dispose() {
1925
2897
  if (intervalTimer)
1926
2898
  clearInterval(intervalTimer);
1927
2899
  headSubs.clear();
2900
+ // A disposed node stops answering on every port it was serving, so a
2901
+ // consumer is not left talking to a node its owner has let go of.
2902
+ for (const server of servedPorts)
2903
+ server.close();
2904
+ servedPorts.clear();
1928
2905
  },
1929
2906
  };
2907
+ changeSetProbes.set(node, () => ({
2908
+ recording: changeSets !== undefined,
2909
+ sealedBlocks: sealed.map((r) => r.number),
2910
+ headBlock: headBlockChangeSet,
2911
+ open: changeSets?.peekChangeSet(),
2912
+ }));
2913
+ return node;
1930
2914
  }
1931
2915
  //# sourceMappingURL=node.js.map