webevm 0.0.0 → 0.5.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 +674 -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 +1743 -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 +680 -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 +1959 -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 +701 -0
  71. package/src/worker-client.ts +112 -0
  72. package/src/worker-entry.ts +31 -0
  73. package/src/worker-host.ts +232 -0
@@ -0,0 +1,69 @@
1
+ /**
2
+ * engine.ts — the node-side half of the engine seam: the DEFAULT engine
3
+ * (`@ethereumjs/evm` via `runCall` for reads, `@ethereumjs/vm`'s `runTx` for
4
+ * transactions), plus {@link connectEngine}, the one place an engine is brought
5
+ * up.
6
+ *
7
+ * This is the engine the node uses when the consumer supplies none, and it is
8
+ * exactly what the node's pure-read helper and its mining loop used to do inline.
9
+ * Everything `@ethereumjs/vm` needs in order to make a call READ-ONLY lives HERE
10
+ * rather than in the node above the seam — the checkpoint/revert and the EIP-2929
11
+ * warm/access reset are both requirements of this EVM, not of "a read". An engine
12
+ * that is structurally incapable of committing (revm's `call`) needs neither, and
13
+ * the checkpoint is not free: `SimpleStateManager.checkpointSync()` copies all
14
+ * three state maps and clones every account (0.384 ms per call at 2002 accounts,
15
+ * larger than the whole revm read it would be wrapping). See
16
+ * `docs/adr/0005-revm-reads-the-nodes-state-through-simplestatemanagers-stacks.md`.
17
+ *
18
+ * The same rule decides where the TRANSACTION half's ethereumjs-specific settings
19
+ * live: inside this module, at `transact` below. For the one of them that turned
20
+ * out to buy a BEHAVIOUR the other engine could not reproduce
21
+ * (`skipBlockGasLimitValidation`), the same rule decided that the behaviour had to
22
+ * go rather than the seam bend around it.
23
+ */
24
+ import { type VM } from '@ethereumjs/vm';
25
+ import type { StateManagerInterface } from '@ethereumjs/common';
26
+ import type { Engine, EngineContext } from './types.js';
27
+ /** The default engine's stable identifier, as reported by `node.engine.id`. */
28
+ export declare const ETHEREUMJS_ENGINE_ID = "@ethereumjs/evm";
29
+ /**
30
+ * Wrap the node's own `@ethereumjs/vm` as an engine, covering BOTH operations.
31
+ * Built by the node (it needs the VM and the node's state manager), so it never
32
+ * needs `connect`.
33
+ */
34
+ export declare function createEthereumjsEngine(deps: {
35
+ vm: VM;
36
+ stateManager: StateManagerInterface;
37
+ }): Engine;
38
+ /**
39
+ * Bring an engine up for this node, or FAIL THE WHOLE CONSTRUCTION.
40
+ *
41
+ * THE POINT OF THIS FUNCTION IS THE ABSENCE OF A FALLBACK. Every other outcome
42
+ * here is a silent lie: a consumer who passed a revm engine and was quietly
43
+ * given `@ethereumjs/evm` instead would get a node that comes up, answers every
44
+ * call correctly, and runs an order of magnitude slower than they believe. They
45
+ * would measure it, be confused, and have no signal to follow. So there is no
46
+ * `catch` that continues, no default substituted on failure, and no partially
47
+ * connected engine: if the engine cannot serve this node, `createNode()` throws
48
+ * (honest edge — see `docs/adr/0004-no-account-or-signing-methods.md` for the
49
+ * same convention on the RPC surface).
50
+ *
51
+ * Three ways an injected engine fails, all landing here at construction rather
52
+ * than at the first opcode:
53
+ * 1. it is not an `Engine` at all (a stray object, a module namespace, a
54
+ * forgotten `await` on `createRevmEngine()`) — otherwise the node comes up
55
+ * and dies at the first `eth_call` with a `not a function` TypeError that
56
+ * reads like a node bug;
57
+ * 2. it implements only HALF the seam: no usable `transact`. There is no second
58
+ * engine to mine on, so this is a missing capability the node cannot supply;
59
+ * 3. its `connect(context)` throws, either because it cannot initialise (no
60
+ * wasm, no memory) or because it refuses this node's configuration (the
61
+ * revm engine refuses `stateMode:'trie'`, having no synchronous view of a
62
+ * `MerkleStateManager` to read through).
63
+ *
64
+ * The engine's own message is preserved verbatim inside the thrown error's
65
+ * message (not only as `cause`), because the engine is the only party that
66
+ * knows WHY, and browser consoles routinely show a message without its cause.
67
+ */
68
+ export declare function connectEngine(engine: Engine, context: EngineContext): Promise<void>;
69
+ //# sourceMappingURL=engine.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAQ,KAAK,EAAE,EAAC,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,oBAAoB,CAAC;AAG9D,OAAO,KAAK,EACX,MAAM,EACN,aAAa,EAKb,MAAM,YAAY,CAAC;AAEpB,+EAA+E;AAC/E,eAAO,MAAM,oBAAoB,oBAAoB,CAAC;AAEtD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC5C,EAAE,EAAE,EAAE,CAAC;IACP,YAAY,EAAE,qBAAqB,CAAC;CACpC,GAAG,MAAM,CA6GT;AA4DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,aAAa,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,aAAa,GACpB,OAAO,CAAC,IAAI,CAAC,CAoCf"}
package/dist/engine.js ADDED
@@ -0,0 +1,269 @@
1
+ /**
2
+ * engine.ts — the node-side half of the engine seam: the DEFAULT engine
3
+ * (`@ethereumjs/evm` via `runCall` for reads, `@ethereumjs/vm`'s `runTx` for
4
+ * transactions), plus {@link connectEngine}, the one place an engine is brought
5
+ * up.
6
+ *
7
+ * This is the engine the node uses when the consumer supplies none, and it is
8
+ * exactly what the node's pure-read helper and its mining loop used to do inline.
9
+ * Everything `@ethereumjs/vm` needs in order to make a call READ-ONLY lives HERE
10
+ * rather than in the node above the seam — the checkpoint/revert and the EIP-2929
11
+ * warm/access reset are both requirements of this EVM, not of "a read". An engine
12
+ * that is structurally incapable of committing (revm's `call`) needs neither, and
13
+ * the checkpoint is not free: `SimpleStateManager.checkpointSync()` copies all
14
+ * three state maps and clones every account (0.384 ms per call at 2002 accounts,
15
+ * larger than the whole revm read it would be wrapping). See
16
+ * `docs/adr/0005-revm-reads-the-nodes-state-through-simplestatemanagers-stacks.md`.
17
+ *
18
+ * The same rule decides where the TRANSACTION half's ethereumjs-specific settings
19
+ * live: inside this module, at `transact` below. For the one of them that turned
20
+ * out to buy a BEHAVIOUR the other engine could not reproduce
21
+ * (`skipBlockGasLimitValidation`), the same rule decided that the behaviour had to
22
+ * go rather than the seam bend around it.
23
+ */
24
+ import { runTx } from '@ethereumjs/vm';
25
+ /** The default engine's stable identifier, as reported by `node.engine.id`. */
26
+ export const ETHEREUMJS_ENGINE_ID = '@ethereumjs/evm';
27
+ /**
28
+ * Wrap the node's own `@ethereumjs/vm` as an engine, covering BOTH operations.
29
+ * Built by the node (it needs the VM and the node's state manager), so it never
30
+ * needs `connect`.
31
+ */
32
+ export function createEthereumjsEngine(deps) {
33
+ const { vm, stateManager } = deps;
34
+ const evm = vm.evm;
35
+ return {
36
+ id: ETHEREUMJS_ENGINE_ID,
37
+ async call(request) {
38
+ // eth_call / eth_estimateGas must NEVER mutate state. runCall on a CREATE
39
+ // bumps the caller nonce (for address derivation) and writes storage, so we
40
+ // checkpoint the state manager and revert after — reads stay pure.
41
+ //
42
+ // CRITICAL: runCall (unlike runTx) does NOT reset the EVM journal's
43
+ // warm/access (EIP-2929) tracking or the EIP-2200 original-storage cache
44
+ // between calls — only runTx calls journal.cleanup(). Without resetting them
45
+ // here, slot warmth + "original value" leak from one pure call into the next,
46
+ // so the SECOND+ eth_estimateGas for a warm SSTORE comes back ~2000 gas too
47
+ // low (warm/dirty pricing instead of SSTORE_RESET). viem then uses that
48
+ // under-estimate as the tx gas LIMIT and the real tx runs OUT OF GAS. Reset
49
+ // the per-tx EVM state before each call so every estimate is computed from a
50
+ // clean baseline, exactly as a fresh transaction would see it. (cleanJournal
51
+ // + originalStorageCache.clear() reset only the warm/access bookkeeping; they
52
+ // do NOT mutate account state.)
53
+ evm.journal?.cleanJournal?.();
54
+ stateManager.originalStorageCache?.clear?.();
55
+ await stateManager.checkpoint();
56
+ try {
57
+ const res = await evm.runCall({
58
+ caller: request.from,
59
+ to: request.to,
60
+ data: request.data,
61
+ value: request.value,
62
+ gasLimit: request.gasLimit,
63
+ block: request.block,
64
+ });
65
+ return {
66
+ returnValue: res.execResult.returnValue,
67
+ executionGasUsed: res.execResult.executionGasUsed,
68
+ error: res.execResult.exceptionError?.error,
69
+ };
70
+ }
71
+ finally {
72
+ await stateManager.revert();
73
+ }
74
+ },
75
+ async transact(request) {
76
+ // ONE SKIP FLAG LIVES HERE, and nowhere else. It is `@ethereumjs/vm`'s OWN
77
+ // vocabulary, which is why it lives inside this engine rather than on the
78
+ // neutral request:
79
+ //
80
+ // skipHardForkValidation skips re-checking the transaction's own
81
+ // hardfork-activation rules; the node builds every
82
+ // block on the ONE `Common` it created, so there is
83
+ // no second fork for a transaction to be valid
84
+ // under. An engine with no equivalent simply does
85
+ // not have the check to skip.
86
+ //
87
+ // `skipBlockGasLimitValidation` USED TO LIVE HERE TOO, and it is GONE. It let
88
+ // a transaction whose gas limit exceeded the block's be mined against a
89
+ // limit the block did not have, and ONLY on this engine: `revm-wasm` expresses
90
+ // the same relaxation as a simulation switch (`disableBlockGasLimit`) and
91
+ // REFUSES to combine any simulation switch with committing, so the same
92
+ // transaction came back rejected there (`CallerGasLimitMoreThanBlock`). Same
93
+ // node, same transaction, two answers by engine, which is precisely the
94
+ // failure the seam exists to remove, and it is also why this was never made a
95
+ // neutral request field: a field one engine could only throw on is not a
96
+ // neutral request field, it is a promise the next engine cannot keep.
97
+ //
98
+ // SO THE RELAXATION IS BOUGHT BY CONFIGURATION INSTEAD. Both engines now
99
+ // enforce the block's gas limit, and a consumer who wants enormous gas limits
100
+ // raises `blockGasLimit` (`NodeOptions`, default 30,000,000), which both
101
+ // engines honour by construction because they are handed the same block. The
102
+ // node refuses an over-limit transaction ITSELF, at submit, so the refusal can
103
+ // name the numbers and the knob (see `refuseIfOverBlockGasLimit` in ./node.ts).
104
+ // `runTx`'s own "tx has a higher gas limit than the block" is the backstop
105
+ // under it, enforcing the same rule in this EVM's own words.
106
+ //
107
+ // NOTE that the conformance battery's reference `runTx` passes BOTH flags
108
+ // still, so neither dropping one here nor restoring it would show up as a
109
+ // receipt diff. The battery asserts the NODE's answer per engine instead
110
+ // (`block gas limit refuses an over-limit tx; blockGasLimit lifts it`).
111
+ const res = await runTx(vm, {
112
+ // THE SEAM'S SENDER, PINNED FOR `runTx`. See {@link asSender}: this engine
113
+ // executes on behalf of `request.sender` and derives nothing.
114
+ tx: asSender(request.tx, request.sender),
115
+ block: request.block,
116
+ skipHardForkValidation: true,
117
+ });
118
+ return {
119
+ status: res.receipt.status === 0 ? 0 : 1,
120
+ // `totalGasSpent` is NET of refunds (`gasRefund` is already subtracted),
121
+ // which is what a receipt reports and what the sender paid for.
122
+ gasUsed: res.totalGasSpent,
123
+ // The base fee of the block this transaction is IN, which is the node's
124
+ // own (it builds every block with one). `?? 0n` covers a pre-London header,
125
+ // where there is no base fee to add and a legacy transaction's price is its
126
+ // `gasPrice` regardless.
127
+ effectiveGasPrice: effectiveGasPrice(request.tx, request.block.header.baseFeePerGas ?? 0n),
128
+ logs: (res.execResult.logs ?? []).map(([address, topics, data]) => ({
129
+ address,
130
+ topics,
131
+ data,
132
+ })),
133
+ logsBloom: res.bloom.bitvector,
134
+ createdAddress: res.createdAddress?.bytes,
135
+ };
136
+ },
137
+ };
138
+ }
139
+ /**
140
+ * `tx` AS SEEN BY `runTx` WHEN IT ASKS WHO SENT IT: the seam's sender, and nothing
141
+ * else changed.
142
+ *
143
+ * WHY THIS EXISTS. The sender crosses the seam as a VALUE
144
+ * (`TransactionRequest.sender`) because it is only sometimes recoverable from the
145
+ * transaction: `senderMode:'trusted'` states it instead, and it may then differ
146
+ * from what the signature recovers to (ADR 0002). But `runTx` has no `sender`
147
+ * option — it reads the sender through exactly one call, `tx.getSenderAddress()`,
148
+ * and uses the result as `caller` for the whole transaction. So SOMETHING has to
149
+ * bridge the value onto that one call, and the right place is here: this is
150
+ * `@ethereumjs/vm`'s own vocabulary, exactly like the two `skip*Validation` flags
151
+ * above, and an engine with a real sender parameter (revm) needs none of it.
152
+ *
153
+ * WHY A VIEW RATHER THAN A PINNED INSTANCE. The node used to shadow
154
+ * `getSenderAddress()` on the transaction it parsed, which made the pin visible to
155
+ * everything downstream and made the guarantee a convention every engine had to
156
+ * know about. `Object.create` leaves the node's transaction untouched and frozen:
157
+ * the pin lives for exactly one `runTx` call, and nothing outside this function can
158
+ * read a fabricated sender back off the transaction. The prototype carries every
159
+ * field and method `runTx` reads (`type`, `nonce`, `to`, `value`, `data`,
160
+ * `gasLimit`, the fee fields, `supports`, `getIntrinsicGas`, `getUpfrontCost`,
161
+ * `hash`), so the only thing this changes is the answer to the sender question.
162
+ *
163
+ * It is applied UNCONDITIONALLY — never "only when it differs" — because comparing
164
+ * would mean calling `tx.getSenderAddress()`, i.e. paying the ~1.6 ms ecrecover
165
+ * that `senderMode:'trusted'` exists to skip.
166
+ */
167
+ function asSender(tx, sender) {
168
+ return Object.create(tx, {
169
+ getSenderAddress: { value: () => sender },
170
+ });
171
+ }
172
+ /**
173
+ * Legacy-safe effective gas price: what THIS engine charged the sender per gas.
174
+ *
175
+ * It lives behind the seam because the engine that executed the transaction is the
176
+ * engine that charged it, so the fee arithmetic has one implementation per engine
177
+ * and none in the node — an engine reporting a price it did not charge is a bug in
178
+ * that engine, not a disagreement between the node and itself.
179
+ *
180
+ * Type-0 (legacy) txs have no `maxFeePerGas`, so reading it unconditionally throws
181
+ * ("Cannot mix BigInt and other types"). Branch on the field so legacy receipts
182
+ * compute their `effectiveGasPrice` correctly.
183
+ */
184
+ function effectiveGasPrice(tx, blockBaseFee) {
185
+ const anyTx = tx;
186
+ if (anyTx.maxFeePerGas !== undefined && anyTx.maxFeePerGas !== null) {
187
+ const maxFee = anyTx.maxFeePerGas;
188
+ const maxPrio = anyTx.maxPriorityFeePerGas ?? 0n;
189
+ const tip = maxFee - blockBaseFee < maxPrio ? maxFee - blockBaseFee : maxPrio;
190
+ return tip + blockBaseFee;
191
+ }
192
+ return anyTx.gasPrice;
193
+ }
194
+ /**
195
+ * Bring an engine up for this node, or FAIL THE WHOLE CONSTRUCTION.
196
+ *
197
+ * THE POINT OF THIS FUNCTION IS THE ABSENCE OF A FALLBACK. Every other outcome
198
+ * here is a silent lie: a consumer who passed a revm engine and was quietly
199
+ * given `@ethereumjs/evm` instead would get a node that comes up, answers every
200
+ * call correctly, and runs an order of magnitude slower than they believe. They
201
+ * would measure it, be confused, and have no signal to follow. So there is no
202
+ * `catch` that continues, no default substituted on failure, and no partially
203
+ * connected engine: if the engine cannot serve this node, `createNode()` throws
204
+ * (honest edge — see `docs/adr/0004-no-account-or-signing-methods.md` for the
205
+ * same convention on the RPC surface).
206
+ *
207
+ * Three ways an injected engine fails, all landing here at construction rather
208
+ * than at the first opcode:
209
+ * 1. it is not an `Engine` at all (a stray object, a module namespace, a
210
+ * forgotten `await` on `createRevmEngine()`) — otherwise the node comes up
211
+ * and dies at the first `eth_call` with a `not a function` TypeError that
212
+ * reads like a node bug;
213
+ * 2. it implements only HALF the seam: no usable `transact`. There is no second
214
+ * engine to mine on, so this is a missing capability the node cannot supply;
215
+ * 3. its `connect(context)` throws, either because it cannot initialise (no
216
+ * wasm, no memory) or because it refuses this node's configuration (the
217
+ * revm engine refuses `stateMode:'trie'`, having no synchronous view of a
218
+ * `MerkleStateManager` to read through).
219
+ *
220
+ * The engine's own message is preserved verbatim inside the thrown error's
221
+ * message (not only as `cause`), because the engine is the only party that
222
+ * knows WHY, and browser consoles routinely show a message without its cause.
223
+ */
224
+ export async function connectEngine(engine, context) {
225
+ if (typeof engine?.call !== 'function' || typeof engine?.id !== 'string') {
226
+ throw new Error(`webevm: the value passed as \`engine\` is not an Engine — it must have a string \`id\` and a \`call(request)\` method (got ${describe(engine)}). ` +
227
+ `The node does NOT fall back to the default @ethereumjs/evm engine, because a node running an engine you did not ask for is indistinguishable from one that works. ` +
228
+ `If you built it with an async factory (e.g. \`createRevmEngine()\`), await it first.`);
229
+ }
230
+ // `transact` IS REQUIRED, and this is the guard that says so at construction.
231
+ // It was briefly optional — for exactly as long as the shipped revm engine had
232
+ // no write half — and an engine that omitted it had its transactions mined on
233
+ // the node's own `@ethereumjs/vm`. That fallback is GONE: a node must run ONE
234
+ // EVM, so `node.engine` names the engine that answered its reads AND executed
235
+ // its transactions, and a receipt can be attributed to it.
236
+ //
237
+ // MISSING and BROKEN are refused together, in the same words, because they are
238
+ // the same mistake from the node's point of view (a half-built engine) and
239
+ // neither can be served: there is no second engine to fall back to, and one
240
+ // substituted silently is the lie `connectEngine` exists to refuse.
241
+ if (typeof engine.transact !== 'function') {
242
+ throw new Error(`webevm: the engine '${engine.id}' has no usable \`transact\` method (got ${typeof engine.transact}). ` +
243
+ `An Engine implements BOTH operations — \`call\` for reads and \`transact\` to execute and commit a signed transaction — because the node executes its transactions on the engine you passed. ` +
244
+ `It is deliberately NOT filled in with the default @ethereumjs/evm engine: a node running one EVM for reads and another for transactions has two chances to disagree with itself, and a receipt from it cannot be attributed to the engine ${'`node.engine`'} names.`);
245
+ }
246
+ try {
247
+ await engine.connect?.(context);
248
+ }
249
+ catch (err) {
250
+ throw new Error(`webevm: the engine '${engine.id}' could not be connected, so the node was NOT created. ` +
251
+ `It is deliberately NOT replaced by the default @ethereumjs/evm engine: that node would work, return correct results, and run at a completely different speed from the one you asked for, silently. ` +
252
+ `Fix the configuration (this node is stateMode:'${context.stateMode}') or pass a different engine. Cause: ${message(err)}`, { cause: err });
253
+ }
254
+ }
255
+ /** A short, safe rendering of whatever was passed as an engine. */
256
+ function describe(value) {
257
+ if (value === null)
258
+ return 'null';
259
+ if (typeof value !== 'object')
260
+ return typeof value;
261
+ if (typeof value.id === 'string') {
262
+ return `an object with id '${value.id}' and no call()`;
263
+ }
264
+ return `an object with keys [${Object.keys(value).join(', ')}]`;
265
+ }
266
+ function message(err) {
267
+ return String(err?.message ?? err);
268
+ }
269
+ //# sourceMappingURL=engine.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,12 @@
1
+ /**
2
+ * webevm — a slim, execution-only EIP-1193 Ethereum node
3
+ * on @ethereumjs/vm. Transport-agnostic core: just an async `request()` +
4
+ * mine/dumpState/loadState. Optional comlink Worker helpers are in ./worker-host
5
+ * and ./worker-entry (Worker side) and ./worker-client (main-thread side) so the
6
+ * core never imports comlink.
7
+ */
8
+ export { createNode } from './node.js';
9
+ export { createIndexedDBPersistence, createMemoryPersistence, } from './persistence.js';
10
+ export type { SlimNode, NodeOptions, MiningConfig, StateMode, SenderMode, Engine, EngineContext, EngineInfo, ReadCallRequest, ReadCallResult, TransactionRequest, TransactionResult, TransactionLog, GenesisAccount, BlockEnv, PersistenceAdapter, RequestArguments, SerializedState, } from './types.js';
11
+ export { RpcError } from './types.js';
12
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAC,UAAU,EAAC,MAAM,WAAW,CAAC;AACrC,OAAO,EACN,0BAA0B,EAC1B,uBAAuB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACX,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,SAAS,EACT,UAAU,EAIV,MAAM,EACN,aAAa,EACb,UAAU,EACV,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,QAAQ,EACR,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC"}
package/dist/index.js ADDED
@@ -0,0 +1,21 @@
1
+ /**
2
+ * webevm — a slim, execution-only EIP-1193 Ethereum node
3
+ * on @ethereumjs/vm. Transport-agnostic core: just an async `request()` +
4
+ * mine/dumpState/loadState. Optional comlink Worker helpers are in ./worker-host
5
+ * and ./worker-entry (Worker side) and ./worker-client (main-thread side) so the
6
+ * core never imports comlink.
7
+ */
8
+ export { createNode } from './node.js';
9
+ export { createIndexedDBPersistence, createMemoryPersistence, } from './persistence.js';
10
+ export { RpcError } from './types.js';
11
+ // The revm engine is intentionally NOT re-exported here either, for the same
12
+ // reason: the core must import no engine a consumer did not. Import it directly:
13
+ // import {createRevmEngine} from 'webevm/revm';
14
+ // Worker helpers are intentionally NOT re-exported here to keep comlink out of
15
+ // the core bundle. Import them directly:
16
+ // import {createWorkerNode} from 'webevm/worker-client';
17
+ // new Worker(new URL('webevm/worker-entry', import.meta.url));
18
+ // ...and, for a Worker that must build its own engine (an engine cannot cross the
19
+ // boundary), your own worker module:
20
+ // import {exposeNode} from 'webevm/worker-host';
21
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAC,UAAU,EAAC,MAAM,WAAW,CAAC;AACrC,OAAO,EACN,0BAA0B,EAC1B,uBAAuB,GACvB,MAAM,kBAAkB,CAAC;AAwB1B,OAAO,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC;AACpC,6EAA6E;AAC7E,iFAAiF;AACjF,kDAAkD;AAClD,+EAA+E;AAC/E,yCAAyC;AACzC,2DAA2D;AAC3D,iEAAiE;AACjE,kFAAkF;AAClF,qCAAqC;AACrC,mDAAmD"}
@@ -0,0 +1,149 @@
1
+ /**
2
+ * intrinsic-gas.ts — the transaction's INTRINSIC gas, in one place.
3
+ *
4
+ * 21000 base, plus 16 per non-zero and 4 per zero calldata byte (EIP-2028, from
5
+ * Istanbul on), plus (for a creation) 32000 and, from Shanghai on, the EIP-3860
6
+ * initcode word cost.
7
+ *
8
+ * It lives on its own because TWO callers need the same answer and a silent
9
+ * disagreement between them is expensive: `node.ts` ADDS it to whatever the read
10
+ * engine reports (an engine reports EXECUTION gas only), and
11
+ * `webevm/revm` SUBTRACTS it, because revm charges intrinsic gas
12
+ * itself out of the transaction gas limit while `@ethereumjs/evm`'s `runCall`
13
+ * charges none. Two copies of this formula would drift and the drift would show
14
+ * up as an `eth_estimateGas` that differs by engine.
15
+ *
16
+ * WHAT IT IS NOT: A TRANSACTION'S VALIDITY FLOOR. This formula answers the READ
17
+ * path's question — how much gas a call costs before execution, so the node can
18
+ * add it to what an engine reports and the revm engine can subtract it — and
19
+ * SIGNED CALLDATA IS ALL IT KNOWS ABOUT, so there is no access-list term in it. A
20
+ * TRANSACTION pays one: 2,400 per address and 1,900 per storage key, which both
21
+ * engines charge, so this figure is 6,200 gas short of the floor for a type-1
22
+ * transaction naming one address and two keys. The node therefore refuses a gas
23
+ * limit below intrinsic gas against the parsed transaction's OWN
24
+ * `getIntrinsicGas()` (`refuseIfBelowIntrinsicGas` in ./node.ts), which is also
25
+ * the figure `runTx` validates against. Two questions, two figures, both the
26
+ * node's, neither a copy of the other; measured side by side on four transaction
27
+ * shapes in
28
+ * `docs/spikes/replayed-and-invalid-transactions-are-rejected-as-the-nodes-own-errors/measurements.md`.
29
+ * Do not "unify" them by adding an access-list term to {@link intrinsicGas}: the
30
+ * two callers that share this formula must stay in lockstep, and the revm engine
31
+ * SUBTRACTS whatever it returns from a read whose engine request carries no access
32
+ * list at all, so an extra term there would be subtracted from a figure that never
33
+ * contained it. An `eth_estimateGas` REQUEST may nevertheless name an access list
34
+ * (geth's `accessList` field, and viem sends it), so the charge for THAT lives
35
+ * beside this formula rather than inside it: see {@link accessListGas}.
36
+ *
37
+ * WHY THE FORK IS A `Common` AND NOT A HARDFORK NAME. The formula has a
38
+ * fork-dependent term, so both callers have to name the same fork — and the
39
+ * cheapest way to guarantee that is not to compare two names but to pass ONE
40
+ * OBJECT. `node.ts` builds the node's `Common` and hands that very instance to
41
+ * the engine through the seam (`EngineContext.common`), so the two callers
42
+ * are asking the SAME `Common` the same question and cannot disagree even in
43
+ * principle. It is also the right authority rather than merely a convenient one:
44
+ * `common.isActivatedEIP()` is the table `@ethereumjs/vm`'s `runTx` consults, so
45
+ * the read path charges a deployment exactly what this node's own transaction
46
+ * path spends on it. A hardfork NAME would have meant a second activation table
47
+ * in this repo — a fresh copy of the knowledge that EIP-3860 arrived in
48
+ * Shanghai, which is precisely the drift this file exists to prevent. See
49
+ * `docs/adr/0008-the-revm-engine-admits-only-hardforks-it-can-cost.md`.
50
+ *
51
+ * THE FORK RANGE THIS FORMULA IS TRUE FOR IS ISTANBUL..CANCUN, AND IT HAS AN END
52
+ * AT BOTH SIDES. The node runs Cancun; `webevm/revm` admits
53
+ * Berlin..Cancun, which sits strictly inside that range. Every term above is
54
+ * measured against the protocol at every admitted fork by the clause-(b)
55
+ * assertions in `test/revm-engine.spec.ts`; the two ends are where the formula
56
+ * stops being true, so they are what anyone moving the node's hardfork owes.
57
+ *
58
+ * ABOVE, AT PRAGUE: EIP-7623's calldata floor (a transaction pays at least
59
+ * `21000 + 10` gas per calldata token) is missing here and is DELIBERATELY not
60
+ * added: it is not a term of this formula but a floor on the transaction's TOTAL
61
+ * gas, so it cannot be added without both callers also learning about it. Rather
62
+ * than cost a fork half-correctly, the engine refuses Prague and Osaka BY NAME
63
+ * (`REVM_REFUSED_HARDFORKS` in ./revm.ts).
64
+ *
65
+ * BELOW, AT ISTANBUL: the 16 above is EIP-2028's, which shipped in Istanbul, and
66
+ * it is hardcoded here rather than gated. Before Istanbul a non-zero calldata
67
+ * byte costs 68, so on a pre-Istanbul fork this formula would UNDER-charge by 52
68
+ * gas per non-zero byte — and an under-estimate is the direction that reaches a
69
+ * user, since a client uses `eth_estimateGas` as the transaction's gas limit.
70
+ * The term is NOT fork-gated on purpose: no admitted fork predates Istanbul and
71
+ * none can, because a fork in neither of ./revm.ts's two tables is refused by the
72
+ * "no revm spec is known" guard, so a gate would be arithmetic nothing can reach
73
+ * (the same argument that keeps the EIP-7623 floor out). What stands in its place
74
+ * is a measurement rather than a comment: the suite measures this term either
75
+ * side of the Istanbul boundary (`petersburg` and `istanbul`), so re-admitting a
76
+ * pre-Istanbul fork turns that measured disagreement into a failing build. If one
77
+ * is ever re-admitted, gate this term the way the EIP-3860 one is gated, on the
78
+ * `Common` — do not simply widen the tables.
79
+ *
80
+ * The fork gate on the EIP-3860 term is, by contrast, reachable and load-bearing:
81
+ * it is what makes Berlin, London and Paris admissible, because `revm-wasm@0.3.1`
82
+ * gates the term correctly and an unconditional term here would make
83
+ * `eth_estimateGas` for a deployment differ BY ENGINE on those three forks (the
84
+ * default engine's estimate moves with this formula; the revm engine's is revm's
85
+ * own number, since it subtracts this intrinsic and the node adds it back).
86
+ * Measured both ways, before and after the upstream fix, in
87
+ * `docs/spikes/intrinsic-gas-charges-eip-3860-on-forks-that-predate-it/`; every
88
+ * term of this formula measured fork by fork in
89
+ * `docs/spikes/clause-b-covers-only-eip-3860-not-the-rest-of-the-formula/`.
90
+ *
91
+ * Either way: anyone moving the node's hardfork has to do this arithmetic first;
92
+ * see `docs/adr/0008-the-revm-engine-admits-only-hardforks-it-can-cost.md`.
93
+ */
94
+ import type { Common } from '@ethereumjs/common';
95
+ export declare function intrinsicGas(data: Uint8Array, isCreate: boolean, common: Common): bigint;
96
+ /**
97
+ * WHAT AN `eth_estimateGas` REQUEST'S ACCESS LIST COSTS: 2,400 per address plus
98
+ * 1,900 per storage key, the EIP-2930 charge, added to {@link intrinsicGas} by
99
+ * `eth_estimateGas` alone.
100
+ *
101
+ * ## Why it is a SECOND function rather than a term of the formula above
102
+ *
103
+ * {@link intrinsicGas} has exactly two callers and they must not drift: `node.ts`
104
+ * ADDS it to the EXECUTION gas an engine reports, and `webevm/revm`
105
+ * SUBTRACTS it from revm's total. The engine seam's read request
106
+ * (`ReadCallRequest`) carries NO access list (a read is executed with none on
107
+ * either engine), so a term added to the shared formula would be subtracted from a
108
+ * number that never included it, and `eth_estimateGas` would come out 6,200 gas
109
+ * short on revm and 6,200 long on `@ethereumjs/evm` for the same request. The
110
+ * charge therefore sits ABOVE the seam, added once by the one caller that has a
111
+ * request to read it off.
112
+ *
113
+ * ## Why `eth_estimateGas` charges it at all
114
+ *
115
+ * BECAUSE THE NODE'S OWN REFUSAL POINTS THE CALLER HERE. A transaction whose gas
116
+ * limit is below the intrinsic floor is refused with "raise the gas limit to at
117
+ * least N", pointing the caller at `eth_estimateGas` for the number a transaction
118
+ * needs (`refuseIfBelowIntrinsicGas` in ./node.ts), and that floor is the
119
+ * transaction's own `getIntrinsicGas()`, WHICH INCLUDES THE ACCESS LIST. An estimate blind to
120
+ * the list answered 21,000 for a type-1 transaction with a floor of 27,200: the
121
+ * node would refuse the very number it had just recommended. It is also what geth
122
+ * does (`eth_estimateGas` honours the request's `accessList` field), so a client
123
+ * that sends one gets the same answer here as from a real node.
124
+ *
125
+ * ## It OVER-estimates a list whose entries are touched, deliberately
126
+ *
127
+ * The charge is added, but the WARMING is not modelled: the read underneath was
128
+ * executed without the list, so an access to a listed entry inside it was priced
129
+ * COLD (2,600 / 2,100) where the mined transaction pays WARM (100). The estimate
130
+ * is therefore up to 2,500 per touched address and 2,000 per touched key ABOVE
131
+ * what the transaction really costs. That is the SAFE direction: a client uses
132
+ * the estimate as its gas limit, so an over-estimate costs nothing (unused gas is
133
+ * not charged) while an under-estimate is a transaction that runs out of gas.
134
+ * Buying the exact figure would mean widening the read seam to carry an access
135
+ * list and pre-warming it on both engines, which is a change to the seam, not to
136
+ * an estimate. Both figures are measured and pinned in
137
+ * `test/revm-access-list.spec.ts`, and the run in which the node refused the very
138
+ * gas limit it had just recommended is kept in
139
+ * `docs/spikes/eip-2930-access-lists-are-charged-and-warmed/measurements.md`.
140
+ *
141
+ * ## What does NOT charge it, and why that is not an oversight
142
+ *
143
+ * `eth_fillTransaction` estimates with {@link intrinsicGas} alone, because the
144
+ * transaction it FILLS AND RETURNS carries no access list (it builds a type-0 or
145
+ * type-2 envelope and drops the field): charging for a list its own answer does
146
+ * not contain would hand back a gas limit for a different transaction.
147
+ */
148
+ export declare function accessListGas(accessList: unknown): bigint;
149
+ //# sourceMappingURL=intrinsic-gas.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"intrinsic-gas.d.ts","sourceRoot":"","sources":["../src/intrinsic-gas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4FG;AACH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,oBAAoB,CAAC;AAE/C,wBAAgB,YAAY,CAC3B,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,OAAO,EACjB,MAAM,EAAE,MAAM,GACZ,MAAM,CAgBR;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,OAAO,GAAG,MAAM,CAgBzD"}
@@ -0,0 +1,94 @@
1
+ export function intrinsicGas(data, isCreate, common) {
2
+ let gas = 21000n;
3
+ // EIP-2028 (Istanbul): 16 per non-zero calldata byte, 4 per zero one. Hardcoded
4
+ // rather than asked of `common`, unlike the EIP-3860 term below — see the
5
+ // header: no fork this engine admits predates Istanbul, and none can.
6
+ for (const b of data)
7
+ gas += b === 0 ? 4n : 16n;
8
+ if (isCreate) {
9
+ gas += 32000n;
10
+ // EIP-3860 (Shanghai): 2 gas per 32-byte initcode word. Asked of the node's
11
+ // own `Common` rather than gated on a fork name, so this charge lands
12
+ // exactly where `@ethereumjs/vm`'s `runTx` charges it on the write path.
13
+ if (common.isActivatedEIP(3860)) {
14
+ gas += BigInt(Math.ceil(data.length / 32)) * 2n;
15
+ }
16
+ }
17
+ return gas;
18
+ }
19
+ /** EIP-2930: what one access-list entry's ADDRESS costs, up front. */
20
+ const ACCESS_LIST_ADDRESS_COST = 2400n;
21
+ /** EIP-2930: what one access-list STORAGE KEY costs, up front. */
22
+ const ACCESS_LIST_STORAGE_KEY_COST = 1900n;
23
+ /**
24
+ * WHAT AN `eth_estimateGas` REQUEST'S ACCESS LIST COSTS: 2,400 per address plus
25
+ * 1,900 per storage key, the EIP-2930 charge, added to {@link intrinsicGas} by
26
+ * `eth_estimateGas` alone.
27
+ *
28
+ * ## Why it is a SECOND function rather than a term of the formula above
29
+ *
30
+ * {@link intrinsicGas} has exactly two callers and they must not drift: `node.ts`
31
+ * ADDS it to the EXECUTION gas an engine reports, and `webevm/revm`
32
+ * SUBTRACTS it from revm's total. The engine seam's read request
33
+ * (`ReadCallRequest`) carries NO access list (a read is executed with none on
34
+ * either engine), so a term added to the shared formula would be subtracted from a
35
+ * number that never included it, and `eth_estimateGas` would come out 6,200 gas
36
+ * short on revm and 6,200 long on `@ethereumjs/evm` for the same request. The
37
+ * charge therefore sits ABOVE the seam, added once by the one caller that has a
38
+ * request to read it off.
39
+ *
40
+ * ## Why `eth_estimateGas` charges it at all
41
+ *
42
+ * BECAUSE THE NODE'S OWN REFUSAL POINTS THE CALLER HERE. A transaction whose gas
43
+ * limit is below the intrinsic floor is refused with "raise the gas limit to at
44
+ * least N", pointing the caller at `eth_estimateGas` for the number a transaction
45
+ * needs (`refuseIfBelowIntrinsicGas` in ./node.ts), and that floor is the
46
+ * transaction's own `getIntrinsicGas()`, WHICH INCLUDES THE ACCESS LIST. An estimate blind to
47
+ * the list answered 21,000 for a type-1 transaction with a floor of 27,200: the
48
+ * node would refuse the very number it had just recommended. It is also what geth
49
+ * does (`eth_estimateGas` honours the request's `accessList` field), so a client
50
+ * that sends one gets the same answer here as from a real node.
51
+ *
52
+ * ## It OVER-estimates a list whose entries are touched, deliberately
53
+ *
54
+ * The charge is added, but the WARMING is not modelled: the read underneath was
55
+ * executed without the list, so an access to a listed entry inside it was priced
56
+ * COLD (2,600 / 2,100) where the mined transaction pays WARM (100). The estimate
57
+ * is therefore up to 2,500 per touched address and 2,000 per touched key ABOVE
58
+ * what the transaction really costs. That is the SAFE direction: a client uses
59
+ * the estimate as its gas limit, so an over-estimate costs nothing (unused gas is
60
+ * not charged) while an under-estimate is a transaction that runs out of gas.
61
+ * Buying the exact figure would mean widening the read seam to carry an access
62
+ * list and pre-warming it on both engines, which is a change to the seam, not to
63
+ * an estimate. Both figures are measured and pinned in
64
+ * `test/revm-access-list.spec.ts`, and the run in which the node refused the very
65
+ * gas limit it had just recommended is kept in
66
+ * `docs/spikes/eip-2930-access-lists-are-charged-and-warmed/measurements.md`.
67
+ *
68
+ * ## What does NOT charge it, and why that is not an oversight
69
+ *
70
+ * `eth_fillTransaction` estimates with {@link intrinsicGas} alone, because the
71
+ * transaction it FILLS AND RETURNS carries no access list (it builds a type-0 or
72
+ * type-2 envelope and drops the field): charging for a list its own answer does
73
+ * not contain would hand back a gas limit for a different transaction.
74
+ */
75
+ export function accessListGas(accessList) {
76
+ if (!Array.isArray(accessList))
77
+ return 0n;
78
+ let gas = 0n;
79
+ for (const entry of accessList) {
80
+ // TOLERANT OF THE ENTRY, STRICT ABOUT THE ARITHMETIC: this reads an unvalidated
81
+ // JSON-RPC parameter, and an entry naming no keys (`{address}` with
82
+ // `storageKeys` omitted) is a legitimate access list, not an error. What must
83
+ // never happen is a THROW here, which would turn a merely odd request into a
84
+ // failed estimate.
85
+ if (entry === null || typeof entry !== 'object')
86
+ continue;
87
+ gas += ACCESS_LIST_ADDRESS_COST;
88
+ const keys = entry.storageKeys;
89
+ if (Array.isArray(keys))
90
+ gas += BigInt(keys.length) * ACCESS_LIST_STORAGE_KEY_COST;
91
+ }
92
+ return gas;
93
+ }
94
+ //# sourceMappingURL=intrinsic-gas.js.map