webevm 0.0.0 → 0.6.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 (73) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +693 -0
  3. package/dist/engine.d.ts +69 -0
  4. package/dist/engine.d.ts.map +1 -0
  5. package/dist/engine.js +269 -0
  6. package/dist/engine.js.map +1 -0
  7. package/dist/index.d.ts +12 -0
  8. package/dist/index.d.ts.map +1 -0
  9. package/dist/index.js +21 -0
  10. package/dist/index.js.map +1 -0
  11. package/dist/intrinsic-gas.d.ts +149 -0
  12. package/dist/intrinsic-gas.d.ts.map +1 -0
  13. package/dist/intrinsic-gas.js +94 -0
  14. package/dist/intrinsic-gas.js.map +1 -0
  15. package/dist/node.d.ts +3 -0
  16. package/dist/node.d.ts.map +1 -0
  17. package/dist/node.js +1931 -0
  18. package/dist/node.js.map +1 -0
  19. package/dist/persistence.d.ts +22 -0
  20. package/dist/persistence.d.ts.map +1 -0
  21. package/dist/persistence.js +54 -0
  22. package/dist/persistence.js.map +1 -0
  23. package/dist/revm-state-store.d.ts +89 -0
  24. package/dist/revm-state-store.d.ts.map +1 -0
  25. package/dist/revm-state-store.js +394 -0
  26. package/dist/revm-state-store.js.map +1 -0
  27. package/dist/revm.d.ts +124 -0
  28. package/dist/revm.d.ts.map +1 -0
  29. package/dist/revm.js +657 -0
  30. package/dist/revm.js.map +1 -0
  31. package/dist/sender-recovery.d.ts +78 -0
  32. package/dist/sender-recovery.d.ts.map +1 -0
  33. package/dist/sender-recovery.js +53 -0
  34. package/dist/sender-recovery.js.map +1 -0
  35. package/dist/state-manager.d.ts +327 -0
  36. package/dist/state-manager.d.ts.map +1 -0
  37. package/dist/state-manager.js +439 -0
  38. package/dist/state-manager.js.map +1 -0
  39. package/dist/storage-keys.d.ts +21 -0
  40. package/dist/storage-keys.d.ts.map +1 -0
  41. package/dist/storage-keys.js +113 -0
  42. package/dist/storage-keys.js.map +1 -0
  43. package/dist/types.d.ts +696 -0
  44. package/dist/types.d.ts.map +1 -0
  45. package/dist/types.js +12 -0
  46. package/dist/types.js.map +1 -0
  47. package/dist/worker-client.d.ts +21 -0
  48. package/dist/worker-client.d.ts.map +1 -0
  49. package/dist/worker-client.js +77 -0
  50. package/dist/worker-client.js.map +1 -0
  51. package/dist/worker-entry.d.ts +32 -0
  52. package/dist/worker-entry.d.ts.map +1 -0
  53. package/dist/worker-entry.js +29 -0
  54. package/dist/worker-entry.js.map +1 -0
  55. package/dist/worker-host.d.ts +75 -0
  56. package/dist/worker-host.d.ts.map +1 -0
  57. package/dist/worker-host.js +188 -0
  58. package/dist/worker-host.js.map +1 -0
  59. package/package.json +90 -2
  60. package/src/engine.ts +300 -0
  61. package/src/index.ts +46 -0
  62. package/src/intrinsic-gas.ts +191 -0
  63. package/src/node.ts +2150 -0
  64. package/src/persistence.ts +80 -0
  65. package/src/revm-state-store.ts +455 -0
  66. package/src/revm.ts +809 -0
  67. package/src/sender-recovery.ts +142 -0
  68. package/src/state-manager.ts +531 -0
  69. package/src/storage-keys.ts +150 -0
  70. package/src/types.ts +717 -0
  71. package/src/worker-client.ts +112 -0
  72. package/src/worker-entry.ts +31 -0
  73. package/src/worker-host.ts +232 -0
@@ -0,0 +1,439 @@
1
+ /**
2
+ * state-manager.ts — the node's `stateMode:'none'` state manager.
3
+ *
4
+ * `@ethereumjs/statemanager@10.1.2`'s `SimpleStateManager` keeps storage in ONE
5
+ * FLAT `Map` keyed `` `${address}_${slot}` ``, and `checkpointSync()` pushes a
6
+ * full COPY of it. `@ethereumjs/evm` checkpoints once per MESSAGE FRAME, so every
7
+ * transaction pays `frames + 1` copies of ALL of state, and `clearStorage` (which
8
+ * the EVM calls on every contract creation) can only be a prefix scan of the whole
9
+ * map. Measured end to end: four ordinary transactions cost 289 ms at 100,000
10
+ * slots on that layout and 10 ms on this one, and one transaction at 10,000 slots
11
+ * already ate between a third and nine tenths of a 16.6 ms frame budget through
12
+ * the node's own public surface. All of it is in
13
+ * `docs/spikes/spike-storage-layout-cost-for-the-revm-write-half/measurements.md`.
14
+ *
15
+ * So this subclass re-layers storage. It is `Map<address, Map<slot, value>>`, and
16
+ * a checkpoint pushes a **storage overlay** — one checkpoint's worth of CHANGE —
17
+ * rather than copying anything:
18
+ *
19
+ * - `checkpointSync()` pushes an EMPTY overlay: O(1), whatever state holds.
20
+ * - `putStorage` writes into the TOP overlay only.
21
+ * - `getStorage` walks the overlay stack DOWNWARDS until it finds the slot, or an
22
+ * overlay that cleared the account (which hides every overlay below it).
23
+ * - `commit()` merges the top overlay into the one below and pops it; `revert()`
24
+ * just pops it, so an uncommitted write was never anywhere else to begin with.
25
+ * - `clearStorage(address)` is one `delete` plus one tombstone: O(that account)
26
+ * (no tombstone on the BOTTOM overlay, which has nothing below it to hide).
27
+ *
28
+ * ## The key is PACKED, and both sides of it import ONE encoder
29
+ *
30
+ * The keys in that `Map<address, Map<slot, value>>` are the NODE'S — the point
31
+ * of owning the representation — so they are packed rather than `0x`-hex: two
32
+ * bytes per UTF-16 code unit, 10 code units for an account and 16 for a slot.
33
+ * That takes a cold revm storage access from 1.31-1.33 µs to 0.36-0.39 µs —
34
+ * 70-73%, nearly all of it JS-side key handling — and the encoder, the
35
+ * measurement and the fixed-width rule are in
36
+ * `src/storage-keys.ts` — build a key with {@link packAddressKey} /
37
+ * {@link packSlotKey} and never by hand, because the synchronous revm store
38
+ * (`src/revm-state-store.ts`) builds its keys with the same two functions and a
39
+ * silent disagreement between the two would read as ZERO rather than as an error.
40
+ *
41
+ * ACCOUNTS AND CODE ARE NOT AFFECTED: those stacks are `SimpleStateManager`'s and
42
+ * stay keyed `address.toString()`. Neither is `dumpState`'s output, which stays
43
+ * `0x`-hex — {@link OverlayStorageStateManager.liveStorage} converts on the way
44
+ * out.
45
+ *
46
+ * ONE WORD FOR THE CONCEPT: **overlay**. The spike that produced this design
47
+ * called the same thing an overlay, a diff frame and a journal frame in different
48
+ * places; "frame" already means an EVM message frame (and, in `CONTEXT.md`, the
49
+ * 16.6 ms frame budget) and "journal" already means the one `@ethereumjs/evm`
50
+ * keeps ABOVE the state manager, so neither is free. `overlay` is, and it is
51
+ * defined in `CONTEXT.md`'s glossary. Use it in code, tests and commits.
52
+ *
53
+ * ## Copy-on-write is not enough, and the naive version fails SILENTLY
54
+ *
55
+ * The plausible wrong version of this is `new Map(outer)` per checkpoint: it
56
+ * copies the outer map and SHARES every inner map, so a child frame's write
57
+ * mutates the parent's map, survives a revert, and lands in committed state with
58
+ * no error anywhere. `test/helpers/storage-overlay.ts` keeps that version as a
59
+ * CONTROL and asserts it fails the same checks this class passes — a correctness
60
+ * claim with nothing to fail against is not a claim. (Cloning the inner map on
61
+ * first write fixes the leak but leaves the checkpoint O(accounts-with-storage),
62
+ * which is the same O(total) when state is one slot per account, i.e. exactly
63
+ * what per-player game state looks like. Hence overlays.)
64
+ *
65
+ * ## `storageStack` is GONE, and reading it THROWS
66
+ *
67
+ * The base class's `storageStack` is not maintained here, because it is the thing
68
+ * being replaced. It is deliberately made unreadable rather than left present and
69
+ * empty: with an empty stack still sitting there, three shipped readers answered
70
+ * WRONG rather than throwing (the revm store reported "this slot is zero" for a
71
+ * slot holding `0x2a`, `dumpState` dumped no storage at all, and the guard meant
72
+ * to catch a shape change passed). Wrong-but-plausible is the failure this repo's
73
+ * honest-edge convention exists to prevent, so any remaining reader now gets a
74
+ * loud error naming the replacement instead of a believable zero.
75
+ *
76
+ * ## The field-initialiser trap, which will bite the next person
77
+ *
78
+ * `SimpleStateManager`'s CONSTRUCTOR calls `this.checkpointSync()`. A subclass
79
+ * field declaration runs AFTER `super()` returns, so `storageOverlays = []` would
80
+ * overwrite whatever that first checkpoint created. There is therefore NO field
81
+ * declaration for it: it is created lazily inside the override.
82
+ *
83
+ * ## `clearStorage` is also an upstream-bug fix, and still is
84
+ *
85
+ * `SimpleStateManager` ships `clearStorage` as `async clearStorage() { }`: an
86
+ * empty body taking NO parameter, while the `StateManagerInterface` it implements
87
+ * declares `clearStorage(address)`. A zero-parameter method satisfies a
88
+ * one-parameter interface member, so TypeScript never flagged it and the address
89
+ * argument is silently dropped. `@ethereumjs/evm` calls it on EVERY contract
90
+ * creation (`evm.js:555`) precisely to guarantee a fresh contract starts with
91
+ * empty storage, so with the upstream no-op a contract created at an address that
92
+ * already holds storage INHERITS it. Reported upstream; see
93
+ * `docs/adr/0007-we-override-simplestatemanagers-no-op-clearstorage.md`.
94
+ *
95
+ * WHY AN OVERRIDE RATHER THAN A `pnpm patch`: a patch would fix only THIS repo's
96
+ * own test runs. `webevm` is a library, so a consumer resolves
97
+ * `@ethereumjs/statemanager` themselves and would never see our patch. The fix
98
+ * has to live in code we publish. That argument is even stronger for the layout,
99
+ * which is a representation our own `dumpState` and revm store read directly.
100
+ *
101
+ * WHAT THIS DOES NOT FIX (and cannot, in this mode): the EIP-7610 collision guard
102
+ * sitting just above that call rejects creation outright when the target account
103
+ * has non-empty storage, and it reads `account.storageRoot`. `SimpleStateManager`
104
+ * implements no state-root logic at all, so `storageRoot` never reflects its
105
+ * storage and the guard cannot fire. `stateMode:'trie'` gets the correct,
106
+ * spec-current behaviour from `MerkleStateManager` (creation fails with
107
+ * `CREATE_COLLISION`); `stateMode:'none'` clears and proceeds, which is the
108
+ * pre-EIP-7610 semantics and what the EVM's own call asks for. Both are far
109
+ * better than silently inheriting; they are not identical to each other, and that
110
+ * asymmetry is documented in the README's state-mode section.
111
+ */
112
+ import { SimpleStateManager } from '@ethereumjs/statemanager';
113
+ import { packAddressKey, packSlotKey, unpackAddressKey, unpackSlotKey, } from './storage-keys.js';
114
+ function emptyOverlay() {
115
+ return { written: new Map(), cleared: new Set() };
116
+ }
117
+ const STORAGE_STACK_IS_GONE = "webevm: SimpleStateManager's flat `storageStack` is not maintained " +
118
+ "by this node. `stateMode:'none'` storage is per-account with per-checkpoint " +
119
+ 'OVERLAYS — read it through `storageAt(addressKey, slotKey)` (one slot, ' +
120
+ 'synchronously), `liveStorage()` (every live slot, grouped by account) or the ' +
121
+ 'async `getStorage(address, key)`. This throws on purpose: an empty ' +
122
+ '`storageStack` left in place answers "that slot is zero" for a slot that ' +
123
+ 'holds a value, and a plausible wrong answer is worse than an error. See ' +
124
+ "src/state-manager.ts. (Its keys were not this layout's either: a storage " +
125
+ 'key here is PACKED, built by src/storage-keys.ts.)';
126
+ export class OverlayStorageStateManager extends SimpleStateManager {
127
+ constructor(opts) {
128
+ super(opts);
129
+ // The base constructor assigned `this.storageStack = []`. Replace that own
130
+ // property with a throwing accessor, so a reader that has not been migrated
131
+ // fails loudly here instead of reporting an empty storage map as truth. The
132
+ // setter swallows writes rather than throwing, because the base class also
133
+ // assigns to it and a constructor that throws is not the honest edge — a
134
+ // READ is where a wrong answer would escape.
135
+ Object.defineProperty(this, 'storageStack', {
136
+ configurable: true,
137
+ get() {
138
+ throw new Error(STORAGE_STACK_IS_GONE);
139
+ },
140
+ set() { },
141
+ });
142
+ }
143
+ // --- the checkpoint contract --------------------------------------------
144
+ /**
145
+ * Push a frame. Accounts and code exactly as upstream (they are not what this
146
+ * class re-layers, and copying them byte-for-byte keeps the diff honest);
147
+ * storage pushes an EMPTY overlay, which copies nothing at any state size.
148
+ */
149
+ checkpointSync() {
150
+ const newTopA = new Map(this.topAccountStack());
151
+ for (const [address, account] of newTopA) {
152
+ newTopA.set(address, account !== undefined
153
+ ? Object.assign(Object.create(Object.getPrototypeOf(account)), account)
154
+ : undefined);
155
+ }
156
+ this.accountStack.push(newTopA);
157
+ this.codeStack.push(new Map(this.topCodeStack()));
158
+ // First call comes from the BASE constructor, before any subclass field
159
+ // could have run. `as ... | undefined` because the declared type says it is
160
+ // always there, and at this one instant it is not.
161
+ const overlays = this.storageOverlays;
162
+ if (overlays === undefined) {
163
+ this.storageOverlays = [emptyOverlay()];
164
+ return;
165
+ }
166
+ overlays.push(emptyOverlay());
167
+ }
168
+ /**
169
+ * Merge the top overlay into the one below and drop it.
170
+ *
171
+ * The clear is merged FIRST and in O(1) per account: dropping the account from
172
+ * the overlay below and re-tombstoning it there hides everything deeper,
173
+ * without touching a single slot. Then the writes land on top of that, so a
174
+ * clear-then-write inside one frame commits as "only the new slots".
175
+ *
176
+ * EXCEPT ON THE BOTTOM OVERLAY, WHICH KEEPS NO TOMBSTONES. A tombstone exists
177
+ * to hide the slots overlays BELOW it hold; the bottom overlay is committed
178
+ * state and has nothing below, so a tombstone there hides nothing and is never
179
+ * removed by anything. `@ethereumjs/evm` calls `clearStorage` on EVERY contract
180
+ * creation, so keeping them cost a long-lived in-browser node one permanent
181
+ * entry per CREATE ever executed, plus an O(addresses-ever-cleared) term in
182
+ * {@link liveStorage} and therefore in every `dumpState`. The `delete` is what
183
+ * performs the clear and it still runs, so the account still reads as cleared —
184
+ * {@link storageAt} falls off the end of the stack, which is the same
185
+ * `undefined` a tombstone would have produced. Pruned HERE, at one of the two
186
+ * places a bottom tombstone can be created (the other is
187
+ * {@link clearStorageAt}, with no checkpoint open), rather than swept later.
188
+ */
189
+ async commit() {
190
+ this.accountStack.splice(-2, 1);
191
+ this.codeStack.splice(-2, 1);
192
+ const overlays = this.storageOverlays;
193
+ const top = overlays[overlays.length - 1];
194
+ const below = overlays[overlays.length - 2];
195
+ if (top === undefined || below === undefined) {
196
+ throw new Error('webevm: commit() with no open storage checkpoint below the ' +
197
+ 'top one. Every commit must be preceded by a checkpoint.');
198
+ }
199
+ // After the `pop()` below, `below` is the bottom overlay exactly when the
200
+ // stack is two deep now.
201
+ const belowIsBottom = overlays.length === 2;
202
+ for (const address of top.cleared) {
203
+ below.written.delete(address);
204
+ if (!belowIsBottom)
205
+ below.cleared.add(address);
206
+ }
207
+ for (const [address, inner] of top.written) {
208
+ const target = below.written.get(address);
209
+ // `inner` was created by `top`, which is about to disappear, so no overlay
210
+ // below can be holding a reference to it: handing the object over is safe
211
+ // and O(1). This is the one place ownership moves, and it is why nothing
212
+ // here needs copy-on-write bookkeeping.
213
+ if (target === undefined)
214
+ below.written.set(address, inner);
215
+ else
216
+ for (const [slot, value] of inner)
217
+ target.set(slot, value);
218
+ }
219
+ overlays.pop();
220
+ }
221
+ /** Drop the top overlay. Everything written since the checkpoint goes with it. */
222
+ async revert() {
223
+ this.accountStack.pop();
224
+ this.codeStack.pop();
225
+ this.storageOverlays.pop();
226
+ }
227
+ // --- storage -------------------------------------------------------------
228
+ topOverlay() {
229
+ const overlays = this.storageOverlays;
230
+ const top = overlays[overlays.length - 1];
231
+ if (top === undefined) {
232
+ throw new Error('webevm: the storage overlay stack is empty, so there is no ' +
233
+ 'state to read or write. More reverts than checkpoints.');
234
+ }
235
+ return top;
236
+ }
237
+ /**
238
+ * Read one slot SYNCHRONOUSLY, by key, walking the overlay stack downwards.
239
+ *
240
+ * BOTH KEYS ARE PACKED and must come from `src/storage-keys.ts`
241
+ * ({@link packAddressKey} / {@link packSlotKey}). A hand-built key that happens
242
+ * to be a string compiles and MISSES, and a miss here is indistinguishable from
243
+ * a slot holding zero.
244
+ *
245
+ * `undefined` means "no overlay holds this slot", i.e. zero. A zero-LENGTH
246
+ * `Uint8Array` is different: it means an overlay explicitly stored the empty
247
+ * value (the interpreter strips leading zeros before `putStorage`, so a slot
248
+ * zeroed by `SSTORE` is stored as empty rather than deleted) and it must stop
249
+ * the walk, or a cleared slot would read through to a stale value below.
250
+ *
251
+ * The stack walk is the cost this layout ADDS, and it is two map lookups per
252
+ * open checkpoint. Measured against frame depths 1/2/4/8 it is not
253
+ * distinguishable from the flat map's single lookup; see the spike.
254
+ */
255
+ storageAt(addressKey, slotKey) {
256
+ const overlays = this.storageOverlays;
257
+ for (let i = overlays.length - 1; i >= 0; i--) {
258
+ const overlay = overlays[i];
259
+ const hit = overlay.written.get(addressKey)?.get(slotKey);
260
+ if (hit !== undefined)
261
+ return hit;
262
+ if (overlay.cleared.has(addressKey))
263
+ return undefined;
264
+ }
265
+ return undefined;
266
+ }
267
+ /**
268
+ * Write one slot SYNCHRONOUSLY, by key, into the TOP overlay — the write-side
269
+ * twin of {@link storageAt}, and for the same reason it exists: revm's commit
270
+ * runs inside a synchronous wasm callback and every method on
271
+ * `StateManagerInterface` returns a `Promise` (ADR 0005). `putStorage` below is
272
+ * this function plus an `Address`.
273
+ *
274
+ * THE VALUE MUST ALREADY BE IN SHORTEST FORM, because that is what this
275
+ * representation holds and what `dumpState` serialises: `@ethereumjs/evm`
276
+ * strips leading zeros before `putStorage` (a zeroed slot arrives as a
277
+ * ZERO-LENGTH array, which {@link storageAt} treats as "explicitly empty" and
278
+ * stops the walk at). A caller handing over 32 padded bytes would write state
279
+ * that reads back correctly and dumps differently from the same state written
280
+ * by the default engine.
281
+ */
282
+ setStorageAt(addressKey, slotKey, value) {
283
+ const top = this.topOverlay();
284
+ let inner = top.written.get(addressKey);
285
+ if (inner === undefined) {
286
+ inner = new Map();
287
+ top.written.set(addressKey, inner);
288
+ }
289
+ inner.set(slotKey, value);
290
+ }
291
+ /**
292
+ * Clear one account's storage SYNCHRONOUSLY, by key — {@link clearStorage}
293
+ * without an `Address`, for the same synchronous-callback reason as
294
+ * {@link setStorageAt}. Still O(1): one `delete` plus one tombstone.
295
+ *
296
+ * NO TOMBSTONE WHEN THE TOP OVERLAY *IS* THE BOTTOM ONE, i.e. when no
297
+ * checkpoint is open. It is the same invariant {@link commit} keeps: a
298
+ * tombstone hides what overlays BELOW hold, and the bottom overlay has nothing
299
+ * below, so the `delete` above has already removed everything there was and the
300
+ * tombstone would be an entry nothing can ever remove.
301
+ *
302
+ * THIS IS THE SITE THE REVM ENGINE REACHES, and it is why the rule is here as
303
+ * well as in `commit()`. `runTx` checkpoints, so the DEFAULT engine's
304
+ * `clearStorage` on every contract creation lands three overlays deep and is
305
+ * pruned on the way down; `webevm/revm` commits its state changes
306
+ * through `src/revm-state-store.ts`'s SYNCHRONOUS callbacks with no checkpoint
307
+ * around them, so every CREATE on that engine clears at depth 1 and arrives
308
+ * straight here. Measured before this line existed: three contract creations
309
+ * left three permanent tombstones in the bottom overlay, one per CREATE, each
310
+ * of them then walked by {@link liveStorage} and therefore by every
311
+ * `dumpState`.
312
+ */
313
+ clearStorageAt(addressKey) {
314
+ const top = this.topOverlay();
315
+ top.written.delete(addressKey);
316
+ if (this.storageOverlays.length > 1)
317
+ top.cleared.add(addressKey);
318
+ }
319
+ async getStorage(address, key) {
320
+ return (this.storageAt(packAddressKey(address.bytes), packSlotKey(key)) ??
321
+ new Uint8Array(0));
322
+ }
323
+ async putStorage(address, key, value) {
324
+ this.setStorageAt(packAddressKey(address.bytes), packSlotKey(key), value);
325
+ }
326
+ /**
327
+ * Delete every storage slot belonging to `address`. O(THAT ACCOUNT) — in fact
328
+ * O(1): drop this overlay's own writes for it and tombstone it, which hides
329
+ * every overlay below. The flat layout could only prefix-scan the whole map,
330
+ * 14 ms at 100,000 slots, on every contract creation.
331
+ *
332
+ * Revert-safe by construction: both effects live in the TOP overlay, so a
333
+ * clear inside a checkpoint that is later reverted disappears with it.
334
+ *
335
+ * The parameter is OPTIONAL for an irritating reason that is itself a symptom
336
+ * of the upstream bug: the base class declares `clearStorage()` with ZERO
337
+ * parameters, and TypeScript refuses an override that ADDS a required one
338
+ * (TS2416). Callers reaching us through `StateManagerInterface` always pass an
339
+ * address, because THAT declares `clearStorage(address)`. A no-argument call
340
+ * keeps the base's do-nothing behaviour rather than guessing which account was
341
+ * meant.
342
+ */
343
+ async clearStorage(address) {
344
+ if (address === undefined)
345
+ return;
346
+ this.clearStorageAt(packAddressKey(address.bytes));
347
+ }
348
+ /**
349
+ * Delete an account AND the storage that belonged to it.
350
+ *
351
+ * THE STORAGE HALF IS OURS, and it is the second gap in the same upstream
352
+ * shape as the `clearStorage` no-op above. `SimpleStateManager.deleteAccount`
353
+ * tombstones the account and never touches storage — it has no per-account
354
+ * index to clear with — so a `SELFDESTRUCT` (or an EIP-161 empty-account
355
+ * clearing) left every slot of the dead account READABLE at its address, and
356
+ * `dumpState` kept serialising them. Measured through the node's own surface:
357
+ * after a contract that writes slot 0 and selfdestructs in the same
358
+ * transaction, `eth_getStorageAt` answered `0x2a` in `stateMode:'none'` and
359
+ * `0x0` in `stateMode:'trie'`
360
+ * (`docs/spikes/revm-write-callbacks-reproduce-the-post-state/measurements.md`).
361
+ *
362
+ * A DELETED ACCOUNT HAS NO STORAGE, in a trie by construction: the account is
363
+ * removed and its storage trie goes with it, which is why
364
+ * `MerkleStateManager` needs no equivalent line and why `'trie'` was already
365
+ * right. This makes `'none'` say the same thing rather than leaving the two
366
+ * modes disagreeing about a destroyed contract, and it is the reason the revm
367
+ * engine — whose host is handed `clearStorage` then `removeAccount` for exactly
368
+ * these two cases, with revm's commit semantics already applied — now leaves
369
+ * post-state a diff cannot tell apart from `@ethereumjs/vm`'s. See
370
+ * `docs/adr/0007-we-override-simplestatemanagers-no-op-clearstorage.md`, whose
371
+ * amendment records this decision and what it changes for the DEFAULT engine.
372
+ *
373
+ * Still O(1), and revert-safe for the same reason {@link clearStorageAt} is:
374
+ * the tombstone lands in the TOP overlay, beside the account tombstone the base
375
+ * class writes into the top account frame, so both disappear together if the
376
+ * frame is reverted.
377
+ */
378
+ async deleteAccount(address) {
379
+ await super.deleteAccount(address);
380
+ this.clearStorageAt(packAddressKey(address.bytes));
381
+ }
382
+ /**
383
+ * Every live storage slot, grouped by account, flattened across the whole
384
+ * overlay stack — the view `dumpState` serialises.
385
+ *
386
+ * Bottom-up, applying each overlay's clears before its writes, so the result is
387
+ * what {@link storageAt} would answer for every key. Iteration order is
388
+ * insertion order (accounts in first-write order, slots likewise), which is the
389
+ * order the flat map produced, so the serialised `dumpState` output is
390
+ * byte-identical to the pre-overlay node's for the same state.
391
+ *
392
+ * THE KEYS COME BACK AS `0x`-HEX, not as the packed keys the overlays hold.
393
+ * This is the boundary where the internal format stops: `dumpState` output is
394
+ * PERSISTED data (IndexedDB, `loadState` fixtures) with existing state behind
395
+ * it, and `test/storage-overlay.spec.ts` asserts it byte-identical — key order
396
+ * included — against a dump captured before the layout ever changed. So the
397
+ * conversion lives here, on the dump path, rather than costing every read.
398
+ *
399
+ * O(live slots) and allocating, so it is a dump/persist operation, not a read
400
+ * path. Read one slot with {@link storageAt}.
401
+ */
402
+ liveStorage() {
403
+ const out = new Map();
404
+ for (const overlay of this.storageOverlays) {
405
+ for (const address of overlay.cleared)
406
+ out.delete(unpackAddressKey(address));
407
+ for (const [address, inner] of overlay.written) {
408
+ const addressHex = unpackAddressKey(address);
409
+ let target = out.get(addressHex);
410
+ if (target === undefined) {
411
+ target = new Map();
412
+ out.set(addressHex, target);
413
+ }
414
+ for (const [slot, value] of inner)
415
+ target.set(unpackSlotKey(slot), value);
416
+ }
417
+ }
418
+ return out;
419
+ }
420
+ /**
421
+ * An INDEPENDENT copy. Overlays are cloned two levels deep (the stack, each
422
+ * overlay's outer map and each inner map), because the copy's overlays are not
423
+ * this object's: sharing an inner map would let a write on the copy land in
424
+ * this manager's committed state.
425
+ */
426
+ shallowCopy() {
427
+ const copy = new OverlayStorageStateManager({ common: this.common });
428
+ copy.accountStack = this.accountStack.map((m) => new Map(m));
429
+ copy.codeStack = this.codeStack.map((m) => new Map(m));
430
+ copy.storageOverlays = this.storageOverlays.map((overlay) => {
431
+ const written = new Map();
432
+ for (const [address, inner] of overlay.written)
433
+ written.set(address, new Map(inner));
434
+ return { written, cleared: new Set(overlay.cleared) };
435
+ });
436
+ return copy;
437
+ }
438
+ }
439
+ //# sourceMappingURL=state-manager.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"state-manager.js","sourceRoot":"","sources":["../src/state-manager.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,21 @@
1
+ /** An account's storage key: 10 UTF-16 code units, two address bytes each. */
2
+ export type PackedAddressKey = string;
3
+ /** A slot's storage key: 16 UTF-16 code units, two slot bytes each. */
4
+ export type PackedSlotKey = string;
5
+ /** `0x`-prefixed lowercase hex — the SERIALISED (dumpState) form of either. */
6
+ export type HexKey = string;
7
+ /**
8
+ * The storage key for an account, from its 20 address bytes.
9
+ *
10
+ * Takes the BYTES rather than an `Address` on purpose: the synchronous revm
11
+ * store is handed revm's own 20-byte scratch buffer and must not have to
12
+ * construct anything to build a key. Pass `address.bytes` from the async side.
13
+ */
14
+ export declare function packAddressKey(address: Uint8Array): PackedAddressKey;
15
+ /** The storage key for one slot, from its 32 key bytes. */
16
+ export declare function packSlotKey(slot: Uint8Array): PackedSlotKey;
17
+ /** `0x` + 40 hex digits, i.e. exactly what `address.toString()` would give. */
18
+ export declare function unpackAddressKey(key: PackedAddressKey): HexKey;
19
+ /** `0x` + 64 hex digits, i.e. exactly what `bytesToHex(slot32)` would give. */
20
+ export declare function unpackSlotKey(key: PackedSlotKey): HexKey;
21
+ //# sourceMappingURL=storage-keys.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"storage-keys.d.ts","sourceRoot":"","sources":["../src/storage-keys.ts"],"names":[],"mappings":"AA0EA,8EAA8E;AAC9E,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC;AACtC,uEAAuE;AACvE,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC;AACnC,+EAA+E;AAC/E,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC;AAE5B;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,UAAU,GAAG,gBAAgB,CAcpE;AAED,2DAA2D;AAC3D,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,aAAa,CAoB3D;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAE9D;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAExD"}
@@ -0,0 +1,113 @@
1
+ /**
2
+ * storage-keys.ts — the node's `stateMode:'none'` STORAGE KEY encoding, and the
3
+ * ONE place either side of it is allowed to build a key.
4
+ *
5
+ * A storage key here is **PACKED**: two bytes per UTF-16 code unit, so an
6
+ * address is 10 code units and a slot is 16, rather than the 42- and
7
+ * 66-character `0x`-hex strings the node used to build. It is `revm-wasm`'s own
8
+ * `MemoryStore` encoding, adopted for the reason it exists there.
9
+ *
10
+ * ## Why, with the number
11
+ *
12
+ * A cold revm storage access with the `0x`-hex key was 1.21-1.33 µs through the
13
+ * real wasm module, and **83-87% of that was JS-side key handling**, not the wasm
14
+ * crossing (0.17-0.20 µs). Per-account NESTING recovers none of it (the cost is
15
+ * building hex at all, not concatenating it). This encoding takes the access to
16
+ * **0.36-0.39 µs: 70-73% recovered**, measured against the SHIPPED store, arm for
17
+ * arm, in `docs/spikes/revm-state-store-packed-storage-keys/measurements.md`. The
18
+ * question was first asked, of four candidate stores, in
19
+ * `docs/spikes/spike-storage-layout-cost-for-the-revm-write-half/measurements.md`
20
+ * (Q4), which predicted 50% from a prototype.
21
+ *
22
+ * The win was only available once the NODE owned the representation, which it
23
+ * does as of ADR 0009; before that the key format was `SimpleStateManager`'s and
24
+ * had to be reproduced byte for byte (ADR 0005).
25
+ *
26
+ * ## THE DANGEROUS FAILURE IS TWO KEY FORMATS THAT BOTH WORK
27
+ *
28
+ * `@ethereumjs/evm` writes storage through the ASYNC `putStorage`; revm reads it
29
+ * through the SYNCHRONOUS `storageAt`. If those two disagreed about the key,
30
+ * every read would be a MISS — and a miss reads as ZERO, not as an error, and
31
+ * costs identical gas, so neither the cross-backend gas gate nor any receipt
32
+ * diff could see it. That is why this module exists at all instead of two
33
+ * private helpers: `src/state-manager.ts` (the async half, plus `dumpState`'s
34
+ * view) and `src/revm-state-store.ts` (the synchronous half) both import THESE
35
+ * functions, so the two formats cannot drift without an edit that is visible
36
+ * here. `test/helpers/revm-storage-keys.ts` then asserts the agreement end to
37
+ * end, in both directions, on a real slot.
38
+ *
39
+ * ## Fixed width, and why it is not a generic "pack any bytes"
40
+ *
41
+ * A length-agnostic pack is NOT injective: a 31-byte key and the 32-byte key
42
+ * with a trailing zero byte produce the same string, i.e. two different slots
43
+ * would silently become one. So the two encoders take a FIXED width (20 bytes
44
+ * for an address, 32 for a slot) and NORMALISE anything else by left-padding it
45
+ * to that width rather than encoding it ambiguously. Normalising is safe and
46
+ * unreachable in practice: `@ethereumjs/evm` always hands over a 32-byte slot
47
+ * key, every caller in `src/node.ts` pads to 32 first, and `MerkleStateManager`
48
+ * (the other state mode) REFUSES a key that is not 32 bytes at all — so a short
49
+ * key names the slot it obviously means instead of an unreadable one.
50
+ *
51
+ * ## What this is NOT the key format for
52
+ *
53
+ * ACCOUNTS and CODE. Those live in `SimpleStateManager`'s own `accountStack` /
54
+ * `codeStack`, keyed `address.toString()` (`0x`-prefixed lowercase hex), and
55
+ * that format is upstream's to dictate — ADR 0005's "reproduce it byte for byte"
56
+ * still applies there, unchanged.
57
+ *
58
+ * The SERIALISED format is not this either. `dumpState` / `loadState` output is
59
+ * persisted data (IndexedDB, `loadState` fixtures) and stays `{address: {slot:
60
+ * value}}` in `0x`-hex: {@link OverlayStorageStateManager.liveStorage} converts
61
+ * back through {@link unpackAddressKey} / {@link unpackSlotKey} on the way out,
62
+ * and `test/storage-overlay.spec.ts` asserts the dump byte-identical against a
63
+ * fixture captured from the pre-overlay build. The internal key moves under that
64
+ * format; the format does not move.
65
+ */
66
+ import { setLengthLeft } from '@ethereumjs/util';
67
+ /** One byte as two lowercase hex digits, for the dump-path conversions below. */
68
+ const HEX_BYTE = /* @__PURE__ */ (() => {
69
+ const t = [];
70
+ for (let i = 0; i < 256; i++)
71
+ t.push(i.toString(16).padStart(2, '0'));
72
+ return t;
73
+ })();
74
+ /**
75
+ * The storage key for an account, from its 20 address bytes.
76
+ *
77
+ * Takes the BYTES rather than an `Address` on purpose: the synchronous revm
78
+ * store is handed revm's own 20-byte scratch buffer and must not have to
79
+ * construct anything to build a key. Pass `address.bytes` from the async side.
80
+ */
81
+ export function packAddressKey(address) {
82
+ if (address.length !== 20)
83
+ return packAddressKey(setLengthLeft(address, 20));
84
+ return String.fromCharCode((address[0] << 8) | address[1], (address[2] << 8) | address[3], (address[4] << 8) | address[5], (address[6] << 8) | address[7], (address[8] << 8) | address[9], (address[10] << 8) | address[11], (address[12] << 8) | address[13], (address[14] << 8) | address[15], (address[16] << 8) | address[17], (address[18] << 8) | address[19]);
85
+ }
86
+ /** The storage key for one slot, from its 32 key bytes. */
87
+ export function packSlotKey(slot) {
88
+ if (slot.length !== 32)
89
+ return packSlotKey(setLengthLeft(slot, 32));
90
+ return String.fromCharCode((slot[0] << 8) | slot[1], (slot[2] << 8) | slot[3], (slot[4] << 8) | slot[5], (slot[6] << 8) | slot[7], (slot[8] << 8) | slot[9], (slot[10] << 8) | slot[11], (slot[12] << 8) | slot[13], (slot[14] << 8) | slot[15], (slot[16] << 8) | slot[17], (slot[18] << 8) | slot[19], (slot[20] << 8) | slot[21], (slot[22] << 8) | slot[23], (slot[24] << 8) | slot[25], (slot[26] << 8) | slot[27], (slot[28] << 8) | slot[29], (slot[30] << 8) | slot[31]);
91
+ }
92
+ /** `0x` + 40 hex digits, i.e. exactly what `address.toString()` would give. */
93
+ export function unpackAddressKey(key) {
94
+ return unpack(key);
95
+ }
96
+ /** `0x` + 64 hex digits, i.e. exactly what `bytesToHex(slot32)` would give. */
97
+ export function unpackSlotKey(key) {
98
+ return unpack(key);
99
+ }
100
+ /**
101
+ * The inverse of the two encoders, for the dump path ONLY — it allocates a
102
+ * string per key and is O(live slots) over a whole dump. Read one slot with
103
+ * `storageAt()`; never round-trip a key through here to read it.
104
+ */
105
+ function unpack(key) {
106
+ let s = '0x';
107
+ for (let i = 0; i < key.length; i++) {
108
+ const c = key.charCodeAt(i);
109
+ s += HEX_BYTE[c >>> 8] + HEX_BYTE[c & 0xff];
110
+ }
111
+ return s;
112
+ }
113
+ //# sourceMappingURL=storage-keys.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"storage-keys.js","sourceRoot":"","sources":["../src/storage-keys.ts"],"names":[],"mappings":"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"}