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.
- package/LICENSE +21 -0
- package/README.md +693 -0
- package/dist/engine.d.ts +69 -0
- package/dist/engine.d.ts.map +1 -0
- package/dist/engine.js +269 -0
- package/dist/engine.js.map +1 -0
- package/dist/index.d.ts +12 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +21 -0
- package/dist/index.js.map +1 -0
- package/dist/intrinsic-gas.d.ts +149 -0
- package/dist/intrinsic-gas.d.ts.map +1 -0
- package/dist/intrinsic-gas.js +94 -0
- package/dist/intrinsic-gas.js.map +1 -0
- package/dist/node.d.ts +3 -0
- package/dist/node.d.ts.map +1 -0
- package/dist/node.js +1931 -0
- package/dist/node.js.map +1 -0
- package/dist/persistence.d.ts +22 -0
- package/dist/persistence.d.ts.map +1 -0
- package/dist/persistence.js +54 -0
- package/dist/persistence.js.map +1 -0
- package/dist/revm-state-store.d.ts +89 -0
- package/dist/revm-state-store.d.ts.map +1 -0
- package/dist/revm-state-store.js +394 -0
- package/dist/revm-state-store.js.map +1 -0
- package/dist/revm.d.ts +124 -0
- package/dist/revm.d.ts.map +1 -0
- package/dist/revm.js +657 -0
- package/dist/revm.js.map +1 -0
- package/dist/sender-recovery.d.ts +78 -0
- package/dist/sender-recovery.d.ts.map +1 -0
- package/dist/sender-recovery.js +53 -0
- package/dist/sender-recovery.js.map +1 -0
- package/dist/state-manager.d.ts +327 -0
- package/dist/state-manager.d.ts.map +1 -0
- package/dist/state-manager.js +439 -0
- package/dist/state-manager.js.map +1 -0
- package/dist/storage-keys.d.ts +21 -0
- package/dist/storage-keys.d.ts.map +1 -0
- package/dist/storage-keys.js +113 -0
- package/dist/storage-keys.js.map +1 -0
- package/dist/types.d.ts +696 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +12 -0
- package/dist/types.js.map +1 -0
- package/dist/worker-client.d.ts +21 -0
- package/dist/worker-client.d.ts.map +1 -0
- package/dist/worker-client.js +77 -0
- package/dist/worker-client.js.map +1 -0
- package/dist/worker-entry.d.ts +32 -0
- package/dist/worker-entry.d.ts.map +1 -0
- package/dist/worker-entry.js +29 -0
- package/dist/worker-entry.js.map +1 -0
- package/dist/worker-host.d.ts +75 -0
- package/dist/worker-host.d.ts.map +1 -0
- package/dist/worker-host.js +188 -0
- package/dist/worker-host.js.map +1 -0
- package/package.json +90 -2
- package/src/engine.ts +300 -0
- package/src/index.ts +46 -0
- package/src/intrinsic-gas.ts +191 -0
- package/src/node.ts +2150 -0
- package/src/persistence.ts +80 -0
- package/src/revm-state-store.ts +455 -0
- package/src/revm.ts +809 -0
- package/src/sender-recovery.ts +142 -0
- package/src/state-manager.ts +531 -0
- package/src/storage-keys.ts +150 -0
- package/src/types.ts +717 -0
- package/src/worker-client.ts +112 -0
- package/src/worker-entry.ts +31 -0
- 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
|