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
package/README.md ADDED
@@ -0,0 +1,693 @@
1
+ # webevm
2
+
3
+ A **slim, execution-only** in-browser EIP-1193 Ethereum node on
4
+ [`@ethereumjs/vm`](https://github.com/ethereumjs/ethereumjs-monorepo).
5
+
6
+ It sits BETWEEN bare `EVM.runCall` (too low-level: no blocks/receipts/logs) and a
7
+ full in-browser node (heavy): it uses `@ethereumjs/vm`'s `runTx` + a minimal mock
8
+ blockchain with `SimpleStateManager` (plain Maps, **no trie, no state-root** by
9
+ default) and **none** of the node / RPC / mempool / signing bloat. It exposes only
10
+ the read + signed-raw-tx methods a viem/wagmi client actually uses — signing stays
11
+ client-side — and **fails loudly** (`-32601`) at its intentional edges instead of
12
+ faking success.
13
+
14
+ - **Transport-agnostic core:** a node is just `{ request, mine, dumpState,
15
+ loadState, onNewHead, getStateRoot, dispose }` where `request()` is an **async**
16
+ EIP-1193 method. Because it's async, the SAME object works unchanged on the main
17
+ thread or across a Worker boundary.
18
+ - **Optional Web-Worker hosting** via comlink helpers (`worker-entry` +
19
+ `createWorkerNode()`), so `createNode()` (main thread) and `createWorkerNode()`
20
+ (Worker) are interchangeable one-liners — the consumer never hand-rolls comlink.
21
+ A Worker that must build something first (an [engine](#engine-ethereumjsevm-default-vs-revm-wasm-opt-in),
22
+ which cannot cross the boundary) calls `exposeNode()` from
23
+ `webevm/worker-host` instead: same api, same client, one line.
24
+ - **IndexedDB persistence** (`createIndexedDBPersistence()`), verified to survive a
25
+ real page reload (state + balances + `eth_getLogs`).
26
+ - **Swappable ENGINE:** reads (`eth_call`/`eth_estimateGas`) and transactions both
27
+ run on an injected engine — `@ethereumjs/evm` by default, or
28
+ [revm-wasm](#engine-ethereumjsevm-default-vs-revm-wasm-opt-in) via the
29
+ optional `webevm/revm` subpath (measured **2.7× on Chromium /
30
+ 3.3× on WebKit** for a 100-read frame, byte-identical gas). One engine answers
31
+ BOTH halves, so `node.engine` names the EVM that ran your reads and executed
32
+ your transactions.
33
+ - **Simple by design:** account/signing methods are NOT implemented; legacy
34
+ (type-0) receipts work (legacy-safe `effectiveGasPrice`); `eth_estimateGas`
35
+ answers with the **smallest gas LIMIT the transaction succeeds at**, found by
36
+ re-executing it (geth's binary search), not with the gas it consumes — the two
37
+ differ by EIP-150's 63/64 rule the moment anything calls out or creates.
38
+
39
+ ## Install
40
+
41
+ ```sh
42
+ npm install webevm
43
+ # optional, only if you use the Worker helpers:
44
+ npm install comlink
45
+ ```
46
+
47
+ (`@ethereumjs/*` and `@noble/hashes` are declared as direct dependencies and are
48
+ installed automatically; `comlink` is an optional peer used only by the Worker
49
+ entry/client.)
50
+
51
+ ## Usage (main thread)
52
+
53
+ ```ts
54
+ import {createNode, createIndexedDBPersistence} from 'webevm';
55
+ import {createPublicClient, createWalletClient, custom} from 'viem';
56
+ import {privateKeyToAccount} from 'viem/accounts';
57
+
58
+ const node = await createNode({
59
+ chainId: 31337,
60
+ miningConfig: {type: 'auto'}, // mine one block per raw tx (pairs with sync)
61
+ persistence: createIndexedDBPersistence(), // optional; survives reload
62
+ initialBalances: {'0xf39…2266': 10n ** 24n},
63
+ });
64
+
65
+ const account = privateKeyToAccount('0x…');
66
+ const transport = custom(
67
+ {request: ({method, params}) => node.request({method, params})},
68
+ {retryCount: 0},
69
+ );
70
+ const wallet = createWalletClient({account, chain, transport}); // signs locally
71
+ const pub = createPublicClient({chain, transport});
72
+ // writes via signed raw txs only; reads via eth_call.
73
+ ```
74
+
75
+ ### `eth_sendRawTransactionSync` (the fast path)
76
+
77
+ Send + mine + return the receipt in ONE call (no receipt polling = the latency
78
+ win). With `miningConfig: {type:'auto'}` this is the default behaviour.
79
+
80
+ ## Usage (Worker — same API)
81
+
82
+ ```ts
83
+ // worker.ts
84
+ import 'webevm/worker-entry'; // calls comlink expose()
85
+
86
+ // main thread
87
+ import {createWorkerNode} from 'webevm/worker-client';
88
+ const worker = new Worker(new URL('./worker.ts', import.meta.url), {type: 'module'});
89
+ const node = await createWorkerNode({worker, chainId: 31337, miningConfig: {type: 'auto'}});
90
+ // node is the SAME { request, mine, dumpState, loadState, ... } shape — drive it
91
+ // with the SAME viem client code as the main-thread node.
92
+ ```
93
+
94
+ ### A Worker that builds its own engine
95
+
96
+ `worker-entry` exposes the node the moment it is imported, which is what makes
97
+ the snippet above a one-liner, and it is also why you cannot import it to *add*
98
+ something. When your Worker has to build an [engine](#engine-ethereumjsevm-default-vs-revm-wasm-opt-in)
99
+ first (an engine cannot cross the thread boundary), write your own worker module
100
+ and call `exposeNode()`:
101
+
102
+ ```ts
103
+ // my-worker.ts
104
+ import {exposeNode} from 'webevm/worker-host';
105
+ import {createRevmEngine} from 'webevm/revm';
106
+ import wasm from 'revm-wasm/revm.wasm'; // your bundler's asset rule
107
+
108
+ exposeNode({createEngine: () => createRevmEngine({wasm})});
109
+ ```
110
+
111
+ That is the whole module. `createEngine` is called ONCE PER NODE (one engine
112
+ instance serves one node) and is the only thing this thread decides: your main
113
+ thread still passes `chainId`, `miningConfig` and the rest through
114
+ `createWorkerNode({worker, ...})` unchanged, and drives the result with the same
115
+ client code. The node proxy behind both paths is the same code in the package,
116
+ so there is nothing to copy and nothing to keep in sync.
117
+
118
+ **A function, not an engine.** `createEngine: createRevmEngine({wasm})` (no
119
+ arrow) passes the PROMISE instead of the factory, which is the one plausible typo
120
+ here. It is refused with a message that names both forms, said twice on purpose:
121
+ the worker logs it the moment the module loads, AND your `await
122
+ createWorkerNode(...)` on the main thread REJECTS with the same text, so the
123
+ mistake reaches the thread you made it on and the thread that was waiting.
124
+
125
+ **Do not `await` at the top level of a worker module before `exposeNode()`.** A
126
+ worker module that awaits something slower than a microtask (fetching wasm,
127
+ opening a database, `await createRevmEngine(...)`) before it calls `exposeNode()`
128
+ can miss the main thread's FIRST message, and then `createWorkerNode()` never
129
+ settles: comlink's handshake is posted while your module is still evaluating and
130
+ there is no listener yet to receive it. Measured on Chromium and WebKit, and not
131
+ fixable inside this package (nothing can register a listener before your module
132
+ gets that far). The recipe above is safe because `() => createRevmEngine({wasm})`
133
+ is synchronous at module scope: the factory defers the await into `createNode()`,
134
+ which is one of the reasons `createEngine` is a function. If you must await
135
+ something, do it INSIDE `createEngine`.
136
+
137
+ ## RPC surface (the contract)
138
+
139
+ This is a **curated, execution-only** method set — NOT a full EIP-1193 provider.
140
+ Anything not in the **supported** list below throws a real JSON-RPC
141
+ method-not-found (`-32601`) — it never fakes a result.
142
+
143
+ ### Supported
144
+
145
+ | method | notes |
146
+ |---|---|
147
+ | `eth_chainId`, `net_version` | from `chainId` option |
148
+ | `eth_blockNumber` | latest mined block number |
149
+ | `eth_getBlockByNumber`, `eth_getBlockByHash` | header + (optional) full txs; roots are zero in `'none'` mode. `miner`, `mixHash` and `logsBloom` are **real**: the first two are the block's [`blockEnv`](#genesis-pre-state--block-env) coinbase/prevRandao (the same values `COINBASE`/`PREVRANDAO` return to a contract), the third is the OR of the block's receipt blooms, so the standard pre-filter finds the logs that are there. `sha3Uncles`/`transactionsRoot`/`receiptsRoot`/`difficulty`/`totalDifficulty`/`size`/`nonce` are placeholders, and the header's `gasUsed` is **always `0x0`** (read the receipts' `gasUsed`) |
150
+ | `eth_call` | **runs on the [engine](#engine-ethereumjsevm-default-vs-revm-wasm-opt-in)**; pure (never mutates); reverts throw `RpcError(3, 'execution reverted')` |
151
+ | `eth_estimateGas` | **runs on the [engine](#engine-ethereumjsevm-default-vs-revm-wasm-opt-in)**; the **smallest gas LIMIT at which the request succeeds**, found by re-executing it, with intrinsic gas (incl. EIP-3860) **+ the request's EIP-2930 `accessList`** (2,400/address + 1,900/key, as geth charges it) as the floor. A request that succeeds at what it consumes — a transfer, a plain deployment — gets exactly that, in one extra execution. A request that reverts at any limit gets `RpcError(3, 'execution reverted')` naming the decoded reason and carrying the callee's bytes; one that is simply too big for the allowance gets `-32000 gas required exceeds allowance` (geth's vocabulary) — never a number. `gas` on the request is the **cap on the search**, capped in turn by the block gas limit |
152
+ | `eth_getBalance`, `eth_getCode`, `eth_getStorageAt`, `eth_getTransactionCount` | state reads at a block tag |
153
+ | `eth_gasPrice`, `eth_maxPriorityFeePerGas` | **constant** (faked fee market — local chain) |
154
+ | `eth_feeHistory` | correct response **shape**, but **constant/faked values** — not for real fee prediction |
155
+ | `eth_fillTransaction` | fills missing nonce/gas/fees of a tx request and returns `{tx, raw}` (the `raw` is **unsigned** — sign client-side); viem's `prepareTransactionRequest` uses it. Its gas estimate **runs on the [engine](#engine-ethereumjsevm-default-vs-revm-wasm-opt-in)** |
156
+ | **`eth_sendRawTransaction`** | accepts a **signed** raw tx; mines per `miningConfig`. **Executes and commits on the [engine](#engine-ethereumjsevm-default-vs-revm-wasm-opt-in)**, through its transaction operation |
157
+ | **`eth_sendRawTransactionSync`** | the fast path: send + mine + return receipt in one call |
158
+ | `eth_getTransactionReceipt`, `eth_getTransactionByHash` | from the in-memory store |
159
+ | `eth_getLogs` | address + topic filtering over mined logs. **Perf note:** a full linear scan over all logs per call (O(total_logs), no index/cache) — fine for a local chain |
160
+ | `eth_subscribe`/`eth_unsubscribe` | **`newHeads` only**; prefer `onNewHead()` over comlink |
161
+ | `evm_setBalance` / `evm_setNonce` / `evm_setCode` / `evm_setStorageAt` / `evm_setAccount` | anvil/hardhat-style runtime state cheats (mutate live state with no tx); commit into the trie in `'trie'` mode |
162
+ | `evm_sendRawTransactionAs` / `evm_sendRawTransactionSyncAs` | `[raw, from]` — execute as `from`, **skipping ecrecover**. Only exist when `senderMode: 'trusted'`; otherwise a loud `-32601`. See [Sender mode](#sender-mode-recover-authenticated-default-vs-trusted-no-ecrecover) |
163
+
164
+ ### Intentionally NOT supported (loud `-32601`)
165
+
166
+ - **Account/signing** (the point — sign client-side, send raw):
167
+ `eth_sendTransaction`, `eth_accounts`, `eth_sign`, `eth_signTransaction`,
168
+ `personal_*`, `wallet_addEthereumChain`, `wallet_switchEthereumChain`.
169
+
170
+ ### Not implemented yet (would `-32601` today)
171
+
172
+ - JSON-RPC batch requests (array payloads); filter polling (`eth_newFilter` etc.);
173
+ `eth_getBlockReceipts`; `eth_getProof`; `eth_createAccessList`; `eth_simulateV1`;
174
+ `web3_clientVersion`/`eth_syncing`/`eth_coinbase`/…
175
+
176
+ ## Correctness baked in from day one
177
+
178
+ - **Legacy-safe `effectiveGasPrice`**:
179
+ `tx.maxFeePerGas ? min(maxPriorityFeePerGas, maxFeePerGas - baseFee) + baseFee :
180
+ tx.gasPrice` — reading `maxFeePerGas` unconditionally throws on legacy (type-0)
181
+ txs. Tested for BOTH legacy and 1559 receipts (verified in-browser).
182
+ - **`eth_call` / `eth_estimateGas` never mutate state** — they run on a state
183
+ checkpoint that is reverted, and reset the EVM journal's warm/access tracking +
184
+ the EIP-2200 original-storage cache per call (so a repeated warm-SSTORE estimate
185
+ doesn't under-report and cause out-of-gas reverts).
186
+ - **One request at a time.** A node serves `request` / `mine` / `dumpState` /
187
+ `loadState` / `getStateRoot` through a single queue, so a request is always
188
+ answered against a SETTLED state. This is not politeness: reads and transactions
189
+ share one checkpoint stack, `commit()` merges the top level down and `revert()`
190
+ discards it, and neither knows who opened it — so two overlapping executions used
191
+ to destroy each other's writes while BOTH reported success (a lost nonce, state
192
+ torn at a message-frame boundary, an `eth_call` committing its own `SSTORE`, two
193
+ transactions given the same block number). Fire as many requests as you like from
194
+ as many pollers as you like; they queue. What it costs is latency, not
195
+ correctness: a cheap read issued during a 209 ms `eth_estimateGas` search waits
196
+ for it (0.1 ms → 208 ms, measured), which is why a game loop should not estimate
197
+ every frame. One consumer-visible rule follows, and it applies to exactly one
198
+ place: a `persistence.save()` hook must not await a call back into the node,
199
+ because it runs while the queue is held so that its dump is a real snapshot and
200
+ so that your request does not resolve before the write is durable. Everything
201
+ else is unaffected — an `onNewHead` subscriber MAY call back (its request queues
202
+ behind the block it was told about), and a request from anywhere else during a
203
+ save simply waits its turn.
204
+ [ADR 0012](docs/adr/0012-one-request-at-a-time-the-node-serialises-its-whole-public-surface.md)
205
+ - **`eth_estimateGas` returns a gas LIMIT, not the gas consumed.** It used to
206
+ report `executionGasUsed` + intrinsic gas, which is exact and is the wrong
207
+ question: under EIP-150's 63/64 rule a `CALL`/`CREATE` is forwarded at most
208
+ 63/64 of the gas left, so a transaction whose limit equals its own consumption
209
+ starves its sub-call. Deploying through the standard CREATE2 factory with such a
210
+ limit returns `status: 0x0` and no contract — and a caller that then points a
211
+ proxy at the address that was never deployed gets `0x` back instead of a
212
+ failure. So the method now searches for the smallest limit that SUCCEEDS, as
213
+ geth does: one run at the upper bound (the request's `gas`, capped at the block
214
+ gas limit), one probe at the measured consumption — which answers a transfer or
215
+ a plain deployment exactly, and terminates there — and otherwise a bounded
216
+ bisection above it. Gas CONSUMED is still verified equal to `runTx`'s
217
+ `totalGasSpent`; you read it off a receipt's `gasUsed`. The estimate is exact to
218
+ the gas (one less and the transaction fails) except in two cases where it is
219
+ deliberately a little high, both erring in the direction that costs you nothing:
220
+ a request naming an **access list** (the list is charged while the probe under it
221
+ still prices those entries cold — see the bullet below), and a contract that
222
+ **reads `GAS` and spends what it finds**, whose search may stop at the smallest
223
+ limit it has proven to work rather than at the true minimum.
224
+ - **A request's EIP-2930 access list is CHARGED by `eth_estimateGas`** (2,400 per
225
+ address, 1,900 per storage key), because the node's own intrinsic-gas refusal
226
+ sends you to `eth_estimateGas` for the number a transaction needs, and that
227
+ number has to be one the node would then accept. It is a slight OVER-estimate
228
+ for entries the transaction really touches (the read underneath carries no
229
+ access list, so those accesses are priced cold), which is the safe direction: a
230
+ client uses an estimate as its gas limit. Mined transactions are unaffected;
231
+ they are charged and warmed by whichever engine executed them.
232
+
233
+ ## State mode: `'none'` (fast, default) vs `'trie'` (real state root, opt-in)
234
+
235
+ ```ts
236
+ const fast = await createNode({stateMode: 'none'}); // default — SimpleStateManager
237
+ const conformant = await createNode({stateMode: 'trie'}); // MerkleStateManager
238
+ ```
239
+
240
+ - **`'none'`** (default): `SimpleStateManager`, no trie, no state root. The fast
241
+ path; measured only **~1.4× faster per signed call / ~1.35× on deploy** than trie
242
+ for typical workloads (so the cost of turning the root on is small). Block
243
+ `stateRoot`/`receiptsRoot`/`transactionsRoot` are zero placeholders and
244
+ `node.getStateRoot()` throws (there is no root). **Full-storage
245
+ persistence is a `'none'`-mode feature.**
246
+ - **`'trie'`** (opt-in): `MerkleStateManager` — a real Merkle-Patricia trie.
247
+ `node.getStateRoot()` returns the **real** root and block headers carry it. This
248
+ is what lets the node be **conformance-tested against `ethereum/tests`
249
+ GeneralStateTests** (they verify exactly that post-state root). Bundle cost ~0
250
+ (the trie code is already pulled in transitively by `@ethereumjs/vm`).
251
+ Caveat: trie-mode `dumpState` carries accounts + code but **not** contract
252
+ storage — use `'none'` for IndexedDB persistence, `'trie'` for the state root /
253
+ conformance.
254
+
255
+ One behaviour genuinely differs between the modes, when a contract is created at
256
+ an address that **already holds storage** (reachable via `evm_setStorageAt`, a
257
+ `loadState`, or a re-deploy after `SELFDESTRUCT`):
258
+
259
+ - **`'none'`** clears that storage and the creation **succeeds**, so the new
260
+ contract starts empty. This is the pre-EIP-7610 behaviour, and it is what the
261
+ EVM itself asks for on every create.
262
+ - **`'trie'`** has a real `storageRoot`, so the EIP-7610 collision check fires and
263
+ the creation **fails** with a revert. This is the spec-current behaviour.
264
+
265
+ A DELETED account, by contrast, behaves the SAME in both modes: a `SELFDESTRUCT`
266
+ (or an EIP-161 empty-account clearing) takes the account's storage with it, so a
267
+ destroyed contract's slots read `0` and `dumpState` stops carrying them. That is
268
+ free in `'trie'` (the account's storage trie goes with the account) and is our
269
+ override in `'none'`, where upstream `SimpleStateManager.deleteAccount` leaves
270
+ storage where it was — the same gap as the `clearStorage` no-op below, and
271
+ recorded in the same ADR.
272
+
273
+ Neither mode lets the new contract *inherit* the old storage, which is the part
274
+ that would silently corrupt results. `'none'` cannot detect the collision at all,
275
+ because detecting it means reading a `storageRoot` that mode does not have. Note
276
+ that `@ethereumjs/statemanager@10.1.2` does not clear it either — its
277
+ `SimpleStateManager.clearStorage` is an empty no-op, so we override it and a fresh
278
+ contract does read `0`
279
+ ([ADR 0007](docs/adr/0007-we-override-simplestatemanagers-no-op-clearstorage.md)).
280
+
281
+ ## Sender mode: `'recover'` (authenticated, default) vs `'trusted'` (no ecrecover)
282
+
283
+ ```ts
284
+ const authentic = await createNode({senderMode: 'recover'}); // default
285
+ const fast = await createNode({senderMode: 'trusted'}); // skips ecrecover
286
+ ```
287
+
288
+ `ecrecover` is a **fixed cost per transaction** and it dominates small ones
289
+ (~1.6 ms in JS, ~0.4 ms on the revm engine's own secp256k1). A client that signed
290
+ a tx **already knows** the sender, so re-deriving it on a local chain is pure
291
+ waste.
292
+
293
+ - **`'recover'`** (default): derive the sender from the signature, exactly as a
294
+ real node does. The tx is self-authenticating. This is the only mode that is
295
+ safe when the node is reachable by a caller you do not control.
296
+ - **`'trusted'`**: enables `evm_sendRawTransactionAs` / `evm_sendRawTransactionSyncAs`,
297
+ which take `[raw, from]` and **skip ecrecover**. Measured **~6.2× on the isolated
298
+ transaction path** (2.09ms → 0.33ms per tx, signing outside the window) and
299
+ **~3.6× end-to-end** through a viem-style client (2.37ms → 0.66ms per tx — the
300
+ residual is the *client's own* signing). Gas, status, logs, receipts and
301
+ post-state are **byte-identical** to `'recover'` (asserted field-by-field in
302
+ `test/trusted-sender.spec.ts`, and again with the revm engine installed in
303
+ `test/revm-trusted-sender.spec.ts` — the same suite, parameterised by engine).
304
+
305
+ **The gap depends on the engine, and it has narrowed.** `'recover'` derives the
306
+ sender with the **installed engine's** `ecrecover` when it has one —
307
+ [`webevm/revm`](#engine-ethereumjsevm-default-vs-revm-wasm-opt-in)
308
+ does, at zero additional bytes, since the `0x01` precompile's secp256k1 is already
309
+ in that wasm module. That makes the recovery ~4.3× cheaper (2.02ms → 0.65ms per
310
+ isolated tx), so on a revm-backed node the `'recover'` vs `'trusted'` ratio is
311
+ **~2.8×** rather than ~6.2×. `'trusted'` is still worth having; it has stopped
312
+ being the dominant lever. The two implementations are proven to authenticate
313
+ identically — including refusing the same malformed, high-`s` (EIP-2) and
314
+ wrong-recovery-id signatures — in `test/revm-sender-recovery.spec.ts`. All figures
315
+ measured 2026-08-11:
316
+ [measurements](docs/spikes/sender-recovery-uses-the-engines-ecrecover/measurements.md).
317
+
318
+ The sender you supply is the sender **on every engine**, including when the
319
+ signature on the wire recovers to somebody else (which is the case the mode exists
320
+ for). It is not a property an EVM works out: the node decides it once and passes it
321
+ across the [engine](#engine-ethereumjsevm-default-vs-revm-wasm-opt-in) seam as
322
+ `TransactionRequest.sender`, so the account charged, the nonce advanced and the
323
+ receipt's `from` are the same address whichever EVM executed the transaction. Both
324
+ engine specs assert that to the wei, from a transaction signed by one account and
325
+ submitted claiming another
326
+ ([amendment 3](docs/adr/0006-the-engine-is-an-injected-object-not-a-named-string.md#amendment-3-the-sender-crosses-the-seam-as-a-value-not-as-a-method-an-engine-calls)).
327
+
328
+ The primitive says exactly one thing: **execute this tx as this sender, do not
329
+ recover**. It is *not* an impersonation feature. Two different callers want it:
330
+
331
+ 1. **An ordinary, genuinely-signed tx** that just wants to bypass a redundant
332
+ recovery. The signature is real, merely unverified.
333
+ 2. **A higher layer implementing impersonation** (anvil/hardhat style) on top: it
334
+ holds no key, so it *fabricates* a signature, serialises the tx, and passes the
335
+ claimed sender. This node never needs to know that happened.
336
+
337
+ Impersonation itself — an address registry plus unsigned `eth_sendTransaction` —
338
+ is account **policy**, and this package has no accounts by design. It belongs in a
339
+ layer above.
340
+
341
+ > **⚠️ `'trusted'` removes the only thing binding a tx to its sender.** Any caller
342
+ > can claim any address. Use it for a local, same-origin dev chain or an in-browser
343
+ > game. **Never** expose a `'trusted'` node over a transport an untrusted caller
344
+ > can reach.
345
+
346
+ ### Caller contract (fabricated signatures only — case 2 above)
347
+
348
+ - **Make the tx bytes unique per sender.** `from` is *not* part of a transaction —
349
+ it is the *output* of recovery — so the hash comes from the bytes alone. Two
350
+ fabricated txs sharing a dummy signature, nonce, `to` and data hash **the same**
351
+ even for different claimed senders, and would silently overwrite each other in
352
+ the receipt/tx maps. Derive the dummy `r` from the sender address. (anvil hit
353
+ exactly this: foundry #4210.)
354
+ - **Fabricated txs are not portable to a `'recover'` node.** `dumpState` stores raw
355
+ tx bytes, so such a dump carries txs no authenticated node could validate. Fine
356
+ for a local chain; do not treat it as replayable chain history.
357
+
358
+ Both caveats apply *only* to fabricated signatures. Genuinely-signed txs (case 1)
359
+ are unaffected: real signatures already differ per signer and validate anywhere.
360
+
361
+ ## Engine: `@ethereumjs/evm` (default) vs revm-wasm (opt-in)
362
+
363
+ ```ts
364
+ import {createNode} from 'webevm';
365
+ import {createRevmEngine} from 'webevm/revm';
366
+ import {wasmUrl} from 'revm-wasm/wasm-url';
367
+
368
+ const js = await createNode({}); // default — everything on @ethereumjs/evm
369
+ const fast = await createNode({engine: await createRevmEngine({wasm: wasmUrl})});
370
+
371
+ fast.engine.id; // 'revm-wasm' — which EVM this node was created with
372
+ ```
373
+
374
+ The **engine** is the EVM behind the node, and the seam it plugs into has two
375
+ operations: a read-only **call** (`eth_call`, `eth_estimateGas` and
376
+ `eth_fillTransaction`'s estimation) and a committing **transaction** (the mining
377
+ path). It is an injected **object**, never a name the core resolves, so the core
378
+ imports no engine you did not
379
+ ([ADR 0006](docs/adr/0006-the-engine-is-an-injected-object-not-a-named-string.md)).
380
+ An engine implements BOTH operations: one that brings only `call` is refused at
381
+ `createNode()` rather than half-served, because the node has no second EVM to mine
382
+ on and would otherwise run two.
383
+
384
+ - **`@ethereumjs/evm`** (default): the node's own EVM, on both operations, exactly
385
+ as it has always behaved — including the pure-read checkpoint/revert and the
386
+ EIP-2929 warm/access reset for a read, and full validation for a transaction.
387
+ Costs nothing: no option, no extra bytes, no wasm.
388
+ - **revm-wasm** (opt-in, `webevm/revm`): the same reads AND the same
389
+ transactions on [revm](https://github.com/bluealloy/revm) compiled to
390
+ WebAssembly, charging **byte-identical gas**
391
+ ([ADR 0003](docs/adr/0003-revm-wasm-is-the-engine-direction.md)). It reads and
392
+ writes the node's own authoritative state through host callbacks — nothing is
393
+ copied into wasm, a transaction writes back only the accounts it touched and
394
+ the slots that changed, and a value it wrote is visible to the next `eth_call`
395
+ with no sync step
396
+ ([ADR 0010](docs/adr/0010-revm-reads-and-writes-through-host-callbacks-the-node-keeps-owning-state.md))
397
+ — and runs both against the node's own
398
+ **real block environment**: a contract reading `block.basefee`,
399
+ `block.prevrandao`, `block.coinbase`, `block.number` or `block.timestamp`
400
+ inside an `eth_call` gets the same answer from either engine. The differential
401
+ conformance battery diffs exactly that, through a contract, because gas cannot
402
+ see it: those opcodes are fee-independent, so an engine running your read
403
+ against a block your node never had would still charge byte-identical gas.
404
+
405
+ **Measured, on the node — not on the raw engines.** The `frame` row is 100 small
406
+ view reads back to back against the 16.6 ms 60fps budget, median of 7 repeats,
407
+ one ordinary laptop
408
+ ([conditions + raw samples](docs/spikes/revm-engine-under-conformance-and-gate/frame-measurements.md)):
409
+
410
+ | configuration | Chromium | WebKit |
411
+ |---|---|---|
412
+ | `createNode({})` — default `@ethereumjs/evm` engine | 10.2–10.4 ms (~62% of the frame) | 13.0 ms (~78%) |
413
+ | `createNode({engine: revm})` — **the node**, on revm | 3.5–3.9 ms (~22%) | 4.0 ms (~24%) |
414
+ | raw revm-wasm, no node, owning its own state (context only) | 2.9–4.2 ms | 4.0 ms |
415
+
416
+ So for this call shape the node itself gets **roughly 2.7× on Chromium and 3.3×
417
+ on WebKit**, and the node's per-call dispatch (the gap between rows 2 and 3) is
418
+ small — a fraction of a millisecond per 100 reads on Chromium, and below the
419
+ measurement floor on WebKit (which clamps `performance.now()` to 1 ms).
420
+ Do not quote the third row as what you get, and do not mix these with the
421
+ **raw-engine** figures elsewhere (11× compute / 19× keccak, and a 12.4 ms → 3.8 ms
422
+ frame): those compare interpreters with no node in the path, on a different, quiet
423
+ machine. Heavier calls (tight arithmetic, keccak loops) gain much more than this
424
+ frame row, which is dominated by per-call overhead rather than by execution.
425
+
426
+ **Scope of the revm engine: both halves, and state stays the node's.** It
427
+ implements the seam's read half AND its transaction half, so with it installed
428
+ your `eth_call`s, your `eth_estimateGas` and your mined transactions all run on
429
+ revm, against the node's own state. The node's own half never moves either way:
430
+ block construction, `cumulativeGasUsed`, receipt assembly, the RPC layer,
431
+ transaction parsing and sender derivation are the node's, on every engine — the
432
+ sender crosses the seam as a required value on the request, so an engine executes
433
+ on behalf of the address the node states rather than recovering one of its own (see
434
+ [Sender mode](#sender-mode-recover-authenticated-default-vs-trusted-no-ecrecover)).
435
+
436
+ **The block gas limit is a real limit, on both engines.** A transaction whose gas
437
+ limit exceeds the block's is REFUSED, with an error naming both numbers and the
438
+ knob, rather than mined against a limit the block does not have. If you want
439
+ enormous gas limits, say so: `createNode({blockGasLimit: 100_000_000n})`. The
440
+ block then really is that large, `GASLIMIT` reports it to a contract and
441
+ `eth_getBlockByNumber` reports it too, and both engines honour it by construction
442
+ because they are handed the same block.
443
+
444
+ This used to be the one place the two engines answered differently: the node told
445
+ `@ethereumjs/vm` to skip that check (`skipBlockGasLimitValidation`), while
446
+ `revm-wasm` expresses the same relaxation as a simulation switch it refuses to
447
+ combine with committing, so the same transaction was mined on the default engine
448
+ and rejected on revm. The flag is gone. A per-transaction exemption one engine
449
+ could not honour became a configured property of the block that both can, and the
450
+ node's default read budget for an `eth_call` that names no `gas` is deliberately
451
+ NOT tied to it (a bigger block should not silently buy every unbudgeted read a
452
+ longer runaway; pass `gas` on the call instead).
453
+
454
+ ```ts
455
+ // both wasm delivery shapes are the SAME code path — `wasm` takes bytes, a URL,
456
+ // a string, a Response, or an already-compiled WebAssembly.Module.
457
+ import {wasmUrl} from 'revm-wasm/wasm-url'; // bundler-resolved asset
458
+ await createRevmEngine({wasm: wasmUrl});
459
+ await createRevmEngine({wasm: '/assets/revm.wasm'}); // fetched at runtime, so you
460
+ // can paint UI first
461
+ ```
462
+
463
+ **`eth_call` semantics, not transaction semantics.** A read is not a
464
+ transaction, so the engine runs it with revm's simulation switches
465
+ (`disableBaseFee`, `disableBlockGasLimit`, `disableEip3607`), the same validity
466
+ rules every real client turns off to serve `eth_call`. That is what keeps a read
467
+ from an address holding **no ether** (including the zero address, which is what
468
+ `from` defaults to) working against a block with a real base fee, and a read from
469
+ an address that holds **code** (smart accounts, ERC-4337, multicall aggregators)
470
+ working at all: EIP-3607 is a rule about *sending* a transaction, and
471
+ `@ethereumjs/evm`'s `runCall` never enforced it either. The switches belong to
472
+ reads only: they are never combined with committing, which `revm-wasm` refuses
473
+ outright. **Your transactions get none of them** — the same engine's transaction
474
+ operation relaxes nothing, checks the nonce, and charges real fees, because a
475
+ transaction that runs with relaxed validity is not a transaction.
476
+
477
+ What is relaxed is a transaction's **validity**, never the **value transfer**:
478
+ revm's `disableBalanceCheck` is deliberately left off, so an `eth_call` carrying
479
+ more ether than the sender holds fails on either engine, exactly as it does on
480
+ geth (`ErrInsufficientBalance`). A read never invents funds it can then report.
481
+
482
+ Caveats, all of them real:
483
+
484
+ - **`stateMode:'none'` only.** revm reads the node's state SYNCHRONOUSLY (an
485
+ interpreter has no suspension point mid-opcode) through `SimpleStateManager`'s
486
+ checkpoint stacks, and `MerkleStateManager` has no synchronous view at any
487
+ depth ([ADR 0005](docs/adr/0005-revm-reads-the-nodes-state-through-simplestatemanagers-stacks.md)).
488
+ `createNode({stateMode:'trie', engine: revm})` **throws at construction**,
489
+ naming the reason.
490
+ - **Only the hardforks it can COST.** The engine serves `berlin`, `london`,
491
+ `paris`, `shanghai` and `cancun` (the node runs Cancun) and refuses `prague`
492
+ and `osaka` at construction, naming the EIP: revm enforces EIP-7623's calldata
493
+ floor from Prague on and the node's shared intrinsic-gas arithmetic does not
494
+ compute it, so `eth_estimateGas` could hand you a gas limit revm itself would
495
+ reject (`GasFloorMoreThanGasLimit`) — and a client uses an estimate as the
496
+ transaction's gas limit; Osaka additionally caps a transaction's gas limit
497
+ (EIP-7825) below this node's default read budget. The pre-Shanghai forks were
498
+ refused too until `revm-wasm@0.3.1`, because both this node and revm charged
499
+ EIP-3860's initcode word cost on forks that predate it; the node now charges
500
+ that term only where `@ethereumjs/common` says the protocol does, and the
501
+ three are back. The admitted range has an end at the BOTTOM too: the shared
502
+ formula hardcodes EIP-2028's 16 gas per non-zero calldata byte, which was 68
503
+ before Istanbul, so nothing below Istanbul is admissible without gating that
504
+ term as well (anything in neither table is refused outright). Measurements:
505
+ [`docs/spikes/prague-intrinsic-gas-floor-or-refuse/`](docs/spikes/prague-intrinsic-gas-floor-or-refuse/measurements.md),
506
+ [`docs/spikes/intrinsic-gas-charges-eip-3860-on-forks-that-predate-it/`](docs/spikes/intrinsic-gas-charges-eip-3860-on-forks-that-predate-it/measurements.md)
507
+ and [`docs/spikes/clause-b-covers-only-eip-3860-not-the-rest-of-the-formula/`](docs/spikes/clause-b-covers-only-eip-3860-not-the-rest-of-the-formula/measurements.md);
508
+ reasoning: [ADR 0008](docs/adr/0008-the-revm-engine-admits-only-hardforks-it-can-cost.md).
509
+ `REVM_SPEC_BY_HARDFORK` and `REVM_REFUSED_HARDFORKS` are exported if you want
510
+ to ask in code. They are frozen: a reading surface, not an editing one, so
511
+ re-admitting a fork by assigning to one of them fails at your assignment
512
+ rather than quietly removing the guard.
513
+ - **One engine instance serves one node.** `connect` binds it; handing a
514
+ connected engine to a second `createNode()` throws (it would otherwise
515
+ re-point the FIRST node's reads at the second node's state). Call
516
+ `createRevmEngine()` per node, passing the same compiled `WebAssembly.Module`
517
+ to skip recompiling.
518
+ - **Not on the Worker path; it is on `worker-host`'s.** `createWorkerNode({engine})`
519
+ is refused with a real error (an engine is a function-bearing object; comlink
520
+ structured-clones the options, which would otherwise give you an opaque
521
+ `DataCloneError`). To run revm in a Worker, build the engine INSIDE your own
522
+ worker module, which is the whole of it:
523
+
524
+ ```ts
525
+ // my-worker.ts
526
+ import {exposeNode} from 'webevm/worker-host';
527
+ import {createRevmEngine} from 'webevm/revm';
528
+ import wasm from 'revm-wasm/revm.wasm';
529
+
530
+ exposeNode({createEngine: () => createRevmEngine({wasm})});
531
+ ```
532
+
533
+ **That recipe is executed, not described.** This repository runs exactly those
534
+ lines on Chromium and WebKit on every test run. The module is
535
+ `packages/webevm/test/helpers/revm-worker.ts` and the spec driving
536
+ it is `packages/webevm/test/revm-worker.spec.ts`, both on
537
+ [GitHub](https://github.com/wighawag/webevm/tree/main/packages/webevm/test)
538
+ (they are test files in the repository, not files inside your `node_modules`;
539
+ the snippet above is what you copy). What that run proves: the engine identity
540
+ crossing the boundary reads `revm-wasm`, the reference execution gas measured
541
+ THROUGH the Worker is exact, a committing transaction lands and its state reads
542
+ back, and the main thread stays responsive throughout. Your main-thread code
543
+ does not change: `createWorkerNode()` drives your module unchanged, because
544
+ `exposeNode()` exposes the same api `worker-entry` does: the same proxy code in
545
+ the package, not a copy of it. The `.wasm` is delivered into the
546
+ worker bundle as a bundler-resolved asset there (esbuild's `binary` loader),
547
+ which is the half a README cannot promise for you: your bundler has to apply
548
+ its asset rule to the WORKER entry too. What that costs, and what serving the
549
+ `.wasm` and passing a URL costs instead:
550
+ [`docs/spikes/prove-the-revm-in-a-worker-recipe-the-readme-recommends/`](docs/spikes/prove-the-revm-in-a-worker-recipe-the-readme-recommends/measurements.md).
551
+ - **In Node.js**, `revm-wasm/wasm-url` is a `file:` URL and Node's `fetch` cannot
552
+ resolve that scheme: read the bytes yourself
553
+ (`readFileSync(fileURLToPath(wasmUrl))`) and pass those. In a browser the URL
554
+ works as-is.
555
+ - **What you pay if you never opt in: nothing you ship.** `revm-wasm` is a plain
556
+ dependency, so a JS-only consumer downloads its install bytes but bundles
557
+ **zero** of them — the default entry point is 413.5 KB raw / 124.6 KB gzip and
558
+ the benchmark suite asserts both that bound and that `revm-wasm` is absent from
559
+ the default entry's module graph. Opting in adds the `.wasm` itself: 1.17 MB
560
+ raw, 413 KB gzipped, fetched or bundled only by
561
+ `import 'webevm/revm'`.
562
+
563
+ **An engine that cannot come up takes the node down with it.** There is no
564
+ fallback path anywhere: if an engine fails to initialise, or refuses this node's
565
+ configuration, `createNode()` throws an error naming the engine and the cause. A
566
+ node quietly running `@ethereumjs/evm` when you asked for revm would work, return
567
+ correct results, and be an order of magnitude slower than you believe — you would
568
+ measure it, be confused, and have no signal. Pinned in
569
+ `test/slim-node-checks.spec.ts` beside the other honest-edge checks.
570
+
571
+ The revm engine faces the same bars as the default one: the differential
572
+ conformance battery (`test/revm-conformance.spec.ts`) and the cross-backend
573
+ execution-gas gate in `packages/benchmarks`, which asserts every backend charges
574
+ the same gas — two EVMs that agree on every return value can still disagree on
575
+ where execution runs OUT of gas.
576
+
577
+ ## Genesis pre-state + block env
578
+
579
+ - **`initialState`** — full genesis pre-state (`address -> {balance, nonce, code,
580
+ storage}`), richer than `initialBalances`. Load arbitrary starting state (funded
581
+ EOAs, pre-deployed contracts with storage).
582
+ - **`blockEnv`** — override mined-block header (`coinbase`, `baseFeePerGas`,
583
+ `number`, `timestamp`, `gasLimit`, `prevRandao`). Required to reproduce a
584
+ GeneralStateTest `env`. `coinbase` and `prevRandao` are **reported back** by
585
+ `eth_getBlockByNumber` as `miner` and `mixHash`, are the same values
586
+ `COINBASE` / `PREVRANDAO` hand a contract, and **survive a `dumpState` /
587
+ `loadState` round trip** (an IndexedDB reload included), so the block a
588
+ consumer reads and the block a contract ran in cannot disagree. Those two
589
+ fields apply to the **genesis** block as well, describing the environment the
590
+ chain runs under; `number`, `timestamp` and `gasLimit` are mined-block-only
591
+ (block 0 is block 0).
592
+
593
+ ## Persistence (IndexedDB)
594
+
595
+ `createIndexedDBPersistence()` writes the dumped state as a single IndexedDB record
596
+ and rehydrates on `createNode()`. No trie, no RLP state-root walk — live-set-sized.
597
+ Verified to round-trip across a real page reload, including `eth_getLogs`.
598
+
599
+ ## Mining
600
+
601
+ `{type:'auto'}` (mine per raw tx — pairs with `eth_sendRawTransactionSync`),
602
+ `{type:'manual'}` (only on `node.mine()`), or `{type:'interval', intervalMs}`.
603
+
604
+ ## On comprehensive EVM test fixtures (`ethereum/tests`)
605
+
606
+ `GeneralStateTests` / `execution-spec-tests` verify a tx by comparing the
607
+ post-state **Merkle-Patricia trie root** (`hash`) + a `keccak(RLP(logs))` hash. The
608
+ default `stateMode:'none'` has no trie/root by design, so it can't consume those
609
+ fixtures — but the opt-in `stateMode:'trie'` **can**, and the test suite does
610
+ exactly that (see `test/statetest.spec.ts`, 5/5 vendored cases pass). `VMTests`
611
+ (the one trie-free format) is frozen at Homestead and useless for a Cancun node.
612
+ Beyond that, the test suite also runs a **differential** conformance check
613
+ (`test/conformance.spec.ts`): a battery of signed txs through BOTH the node and a
614
+ hand-wired trie-backed `@ethereumjs/vm` `runTx` reference, asserting field-by-field
615
+ equality of receipts/logs/return-data/gas/post-state in both state modes. That
616
+ reference is the oracle for the receipt and post-state steps but deliberately not
617
+ for all of them: the block-environment and value-bearing steps are diffed instead
618
+ against the node's OWN block plus the `blockEnv` it was configured with, and
619
+ against an absolute succeed/fail statement per sender and per value, because the
620
+ reference is a separate hand-built chain (its own timestamps, a zero coinbase, and
621
+ no receipt at all for a refused read) and those two classes of bug are structurally
622
+ invisible to it (see *conformance differential* in [`CONTEXT.md`](CONTEXT.md), and
623
+ the `THE ORACLE IS ...` comments in `test/helpers/conformance.ts`).
624
+
625
+ Two further differentials sit beside it, both against a default-engine
626
+ (`@ethereumjs/vm` `runTx`) node built from identical state, because gas equality
627
+ is blind to them: `test/revm-post-state.spec.ts` diffs what transactions LEAVE
628
+ BEHIND (balances, nonces, code, storage, `dumpState`), and
629
+ `test/revm-fees.spec.ts` diffs what they COST — the sender charged, the coinbase
630
+ credited and the base fee burnt, read off BALANCES rather than off the receipt's
631
+ `effectiveGasPrice`, for legacy, EIP-2930 and EIP-1559 transactions and for a
632
+ storage-clearing refund. A receipt can carry the right price while the wrong
633
+ amount left the sender, which is why the money is asserted where the money is.
634
+
635
+ A third one is deliberately NOT a differential: `test/revm-access-list.spec.ts`
636
+ holds EIP-2930 access lists to ABSOLUTE gas figures on both engines, because a
637
+ node that dropped an access list would charge the same wrong number on each and
638
+ agree with itself perfectly (measured, with an empty `mismatches` beside seven
639
+ wrong figures, in
640
+ `docs/spikes/eip-2930-access-lists-are-charged-and-warmed/measurements.md`).
641
+ Listing an entry a transaction touches is **100 gas cheaper** (charged 2,400 or
642
+ 1,900, warmed for 2,500 or 2,000), listing entries it never touches costs
643
+ **+6,200 exactly**, and a dropped list is 0.
644
+
645
+ That same battery runs once more with the optional revm engine installed
646
+ (`test/revm-conformance.spec.ts`), in the one state mode that engine serves
647
+ (`'none'` — it refuses `'trie'` at construction), so the alternative EVM faces
648
+ the repo's strongest correctness bar rather than a softer one of its own. Nothing
649
+ is relaxed for it: `test/conformance.spec.ts` still runs both modes on the
650
+ default engine, unchanged.
651
+
652
+ The node's own state-owning features are held to that same bar rather than
653
+ assumed to survive: `dumpState`, `loadState`, IndexedDB persistence and the
654
+ `evm_set*` cheats run with the revm engine installed, through the suites that
655
+ already covered them — parameterised by engine and asserting exactly what they
656
+ asserted before (`test/revm-persistence-reload.spec.ts`,
657
+ `test/revm-genesis-cheats.spec.ts`). Two cases are new, and both are about a
658
+ WRITE crossing a transaction boundary (`test/state-roundtrip.spec.ts` and
659
+ `test/revm-state-roundtrip.spec.ts`): a cheat applied BETWEEN two transactions
660
+ must be seen by the next one, and a `dumpState` taken AFTER one must reload into
661
+ a fresh node that keeps behaving — the same receipt and the same post-state for
662
+ the same signed transaction. Every other differential above lives inside ONE
663
+ transaction and would pass unchanged for an engine that cached state between
664
+ them; these two would not, and neither failure throws (measured with the cheats
665
+ skipped, in
666
+ `docs/spikes/every-node-feature-survives-a-revm-write-engine/measurements.md`:
667
+ success receipts, empty mismatches, and only the absolute readings move).
668
+
669
+ ## Development
670
+
671
+ ```sh
672
+ pnpm install
673
+ pnpm build # tsc -> dist/
674
+ pnpm test # full browser test suite (Playwright + real Chromium)
675
+ pnpm format # prettier
676
+ ```
677
+
678
+ The browser tests run in real Chromium via
679
+ [`playwright-browser-harness`](https://www.npmjs.com/package/playwright-browser-harness)
680
+ and live under `test/` (specs + the in-browser code-under-test in `test/helpers/`,
681
+ vendored fixtures in `test/fixtures/`). They are dev-only and not published (`files`
682
+ ships `dist` + `src`). The library's devDependencies are deliberately minimal
683
+ (viem + the Playwright harness toolchain) — they do **not** include `tevm`.
684
+
685
+ The cross-backend **performance/bundle-size benchmark** (webevm vs raw
686
+ `@ethereumjs/*` and `tevm`) lives in a separate, private, never-published package
687
+ (`packages/benchmarks`) so that `tevm` and the benchmark
688
+ toolchain stay out of this library's dependency tree. Run it with
689
+ `pnpm --filter webevm-benchmarks test`.
690
+
691
+ ## License
692
+
693
+ MIT