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