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
package/src/engine.ts ADDED
@@ -0,0 +1,300 @@
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, type VM} from '@ethereumjs/vm';
25
+ import type {StateManagerInterface} from '@ethereumjs/common';
26
+ import type {Address} from '@ethereumjs/util';
27
+ import type {TypedTransaction} from '@ethereumjs/tx';
28
+ import type {
29
+ Engine,
30
+ EngineContext,
31
+ ReadCallRequest,
32
+ ReadCallResult,
33
+ TransactionRequest,
34
+ TransactionResult,
35
+ } from './types.js';
36
+
37
+ /** The default engine's stable identifier, as reported by `node.engine.id`. */
38
+ export const ETHEREUMJS_ENGINE_ID = '@ethereumjs/evm';
39
+
40
+ /**
41
+ * Wrap the node's own `@ethereumjs/vm` as an engine, covering BOTH operations.
42
+ * Built by the node (it needs the VM and the node's state manager), so it never
43
+ * needs `connect`.
44
+ */
45
+ export function createEthereumjsEngine(deps: {
46
+ vm: VM;
47
+ stateManager: StateManagerInterface;
48
+ }): Engine {
49
+ const {vm, stateManager} = deps;
50
+ const evm = vm.evm;
51
+ return {
52
+ id: ETHEREUMJS_ENGINE_ID,
53
+ async call(request: ReadCallRequest): Promise<ReadCallResult> {
54
+ // eth_call / eth_estimateGas must NEVER mutate state. runCall on a CREATE
55
+ // bumps the caller nonce (for address derivation) and writes storage, so we
56
+ // checkpoint the state manager and revert after — reads stay pure.
57
+ //
58
+ // CRITICAL: runCall (unlike runTx) does NOT reset the EVM journal's
59
+ // warm/access (EIP-2929) tracking or the EIP-2200 original-storage cache
60
+ // between calls — only runTx calls journal.cleanup(). Without resetting them
61
+ // here, slot warmth + "original value" leak from one pure call into the next,
62
+ // so the SECOND+ eth_estimateGas for a warm SSTORE comes back ~2000 gas too
63
+ // low (warm/dirty pricing instead of SSTORE_RESET). viem then uses that
64
+ // under-estimate as the tx gas LIMIT and the real tx runs OUT OF GAS. Reset
65
+ // the per-tx EVM state before each call so every estimate is computed from a
66
+ // clean baseline, exactly as a fresh transaction would see it. (cleanJournal
67
+ // + originalStorageCache.clear() reset only the warm/access bookkeeping; they
68
+ // do NOT mutate account state.)
69
+ evm.journal?.cleanJournal?.();
70
+ stateManager.originalStorageCache?.clear?.();
71
+ await stateManager.checkpoint();
72
+ try {
73
+ const res = await evm.runCall({
74
+ caller: request.from,
75
+ to: request.to,
76
+ data: request.data,
77
+ value: request.value,
78
+ gasLimit: request.gasLimit,
79
+ block: request.block as any,
80
+ });
81
+ return {
82
+ returnValue: res.execResult.returnValue,
83
+ executionGasUsed: res.execResult.executionGasUsed,
84
+ error: res.execResult.exceptionError?.error,
85
+ };
86
+ } finally {
87
+ await stateManager.revert();
88
+ }
89
+ },
90
+
91
+ async transact(request: TransactionRequest): Promise<TransactionResult> {
92
+ // ONE SKIP FLAG LIVES HERE, and nowhere else. It is `@ethereumjs/vm`'s OWN
93
+ // vocabulary, which is why it lives inside this engine rather than on the
94
+ // neutral request:
95
+ //
96
+ // skipHardForkValidation skips re-checking the transaction's own
97
+ // hardfork-activation rules; the node builds every
98
+ // block on the ONE `Common` it created, so there is
99
+ // no second fork for a transaction to be valid
100
+ // under. An engine with no equivalent simply does
101
+ // not have the check to skip.
102
+ //
103
+ // `skipBlockGasLimitValidation` USED TO LIVE HERE TOO, and it is GONE. It let
104
+ // a transaction whose gas limit exceeded the block's be mined against a
105
+ // limit the block did not have, and ONLY on this engine: `revm-wasm` expresses
106
+ // the same relaxation as a simulation switch (`disableBlockGasLimit`) and
107
+ // REFUSES to combine any simulation switch with committing, so the same
108
+ // transaction came back rejected there (`CallerGasLimitMoreThanBlock`). Same
109
+ // node, same transaction, two answers by engine, which is precisely the
110
+ // failure the seam exists to remove, and it is also why this was never made a
111
+ // neutral request field: a field one engine could only throw on is not a
112
+ // neutral request field, it is a promise the next engine cannot keep.
113
+ //
114
+ // SO THE RELAXATION IS BOUGHT BY CONFIGURATION INSTEAD. Both engines now
115
+ // enforce the block's gas limit, and a consumer who wants enormous gas limits
116
+ // raises `blockGasLimit` (`NodeOptions`, default 30,000,000), which both
117
+ // engines honour by construction because they are handed the same block. The
118
+ // node refuses an over-limit transaction ITSELF, at submit, so the refusal can
119
+ // name the numbers and the knob (see `refuseIfOverBlockGasLimit` in ./node.ts).
120
+ // `runTx`'s own "tx has a higher gas limit than the block" is the backstop
121
+ // under it, enforcing the same rule in this EVM's own words.
122
+ //
123
+ // NOTE that the conformance battery's reference `runTx` passes BOTH flags
124
+ // still, so neither dropping one here nor restoring it would show up as a
125
+ // receipt diff. The battery asserts the NODE's answer per engine instead
126
+ // (`block gas limit refuses an over-limit tx; blockGasLimit lifts it`).
127
+ const res = await runTx(vm, {
128
+ // THE SEAM'S SENDER, PINNED FOR `runTx`. See {@link asSender}: this engine
129
+ // executes on behalf of `request.sender` and derives nothing.
130
+ tx: asSender(request.tx, request.sender),
131
+ block: request.block,
132
+ skipHardForkValidation: true,
133
+ });
134
+ return {
135
+ status: (res.receipt as any).status === 0 ? 0 : 1,
136
+ // `totalGasSpent` is NET of refunds (`gasRefund` is already subtracted),
137
+ // which is what a receipt reports and what the sender paid for.
138
+ gasUsed: res.totalGasSpent,
139
+ // The base fee of the block this transaction is IN, which is the node's
140
+ // own (it builds every block with one). `?? 0n` covers a pre-London header,
141
+ // where there is no base fee to add and a legacy transaction's price is its
142
+ // `gasPrice` regardless.
143
+ effectiveGasPrice: effectiveGasPrice(
144
+ request.tx,
145
+ request.block.header.baseFeePerGas ?? 0n,
146
+ ),
147
+ logs: (res.execResult.logs ?? []).map(([address, topics, data]) => ({
148
+ address,
149
+ topics,
150
+ data,
151
+ })),
152
+ logsBloom: res.bloom.bitvector,
153
+ createdAddress: res.createdAddress?.bytes,
154
+ };
155
+ },
156
+ };
157
+ }
158
+
159
+ /**
160
+ * `tx` AS SEEN BY `runTx` WHEN IT ASKS WHO SENT IT: the seam's sender, and nothing
161
+ * else changed.
162
+ *
163
+ * WHY THIS EXISTS. The sender crosses the seam as a VALUE
164
+ * (`TransactionRequest.sender`) because it is only sometimes recoverable from the
165
+ * transaction: `senderMode:'trusted'` states it instead, and it may then differ
166
+ * from what the signature recovers to (ADR 0002). But `runTx` has no `sender`
167
+ * option — it reads the sender through exactly one call, `tx.getSenderAddress()`,
168
+ * and uses the result as `caller` for the whole transaction. So SOMETHING has to
169
+ * bridge the value onto that one call, and the right place is here: this is
170
+ * `@ethereumjs/vm`'s own vocabulary, exactly like the two `skip*Validation` flags
171
+ * above, and an engine with a real sender parameter (revm) needs none of it.
172
+ *
173
+ * WHY A VIEW RATHER THAN A PINNED INSTANCE. The node used to shadow
174
+ * `getSenderAddress()` on the transaction it parsed, which made the pin visible to
175
+ * everything downstream and made the guarantee a convention every engine had to
176
+ * know about. `Object.create` leaves the node's transaction untouched and frozen:
177
+ * the pin lives for exactly one `runTx` call, and nothing outside this function can
178
+ * read a fabricated sender back off the transaction. The prototype carries every
179
+ * field and method `runTx` reads (`type`, `nonce`, `to`, `value`, `data`,
180
+ * `gasLimit`, the fee fields, `supports`, `getIntrinsicGas`, `getUpfrontCost`,
181
+ * `hash`), so the only thing this changes is the answer to the sender question.
182
+ *
183
+ * It is applied UNCONDITIONALLY — never "only when it differs" — because comparing
184
+ * would mean calling `tx.getSenderAddress()`, i.e. paying the ~1.6 ms ecrecover
185
+ * that `senderMode:'trusted'` exists to skip.
186
+ */
187
+ function asSender(tx: TypedTransaction, sender: Address): TypedTransaction {
188
+ return Object.create(tx, {
189
+ getSenderAddress: {value: () => sender},
190
+ }) as TypedTransaction;
191
+ }
192
+
193
+ /**
194
+ * Legacy-safe effective gas price: what THIS engine charged the sender per gas.
195
+ *
196
+ * It lives behind the seam because the engine that executed the transaction is the
197
+ * engine that charged it, so the fee arithmetic has one implementation per engine
198
+ * and none in the node — an engine reporting a price it did not charge is a bug in
199
+ * that engine, not a disagreement between the node and itself.
200
+ *
201
+ * Type-0 (legacy) txs have no `maxFeePerGas`, so reading it unconditionally throws
202
+ * ("Cannot mix BigInt and other types"). Branch on the field so legacy receipts
203
+ * compute their `effectiveGasPrice` correctly.
204
+ */
205
+ function effectiveGasPrice(tx: TypedTransaction, blockBaseFee: bigint): bigint {
206
+ const anyTx = tx as any;
207
+ if (anyTx.maxFeePerGas !== undefined && anyTx.maxFeePerGas !== null) {
208
+ const maxFee: bigint = anyTx.maxFeePerGas;
209
+ const maxPrio: bigint = anyTx.maxPriorityFeePerGas ?? 0n;
210
+ const tip =
211
+ maxFee - blockBaseFee < maxPrio ? maxFee - blockBaseFee : maxPrio;
212
+ return tip + blockBaseFee;
213
+ }
214
+ return anyTx.gasPrice as bigint;
215
+ }
216
+
217
+ /**
218
+ * Bring an engine up for this node, or FAIL THE WHOLE CONSTRUCTION.
219
+ *
220
+ * THE POINT OF THIS FUNCTION IS THE ABSENCE OF A FALLBACK. Every other outcome
221
+ * here is a silent lie: a consumer who passed a revm engine and was quietly
222
+ * given `@ethereumjs/evm` instead would get a node that comes up, answers every
223
+ * call correctly, and runs an order of magnitude slower than they believe. They
224
+ * would measure it, be confused, and have no signal to follow. So there is no
225
+ * `catch` that continues, no default substituted on failure, and no partially
226
+ * connected engine: if the engine cannot serve this node, `createNode()` throws
227
+ * (honest edge — see `docs/adr/0004-no-account-or-signing-methods.md` for the
228
+ * same convention on the RPC surface).
229
+ *
230
+ * Three ways an injected engine fails, all landing here at construction rather
231
+ * than at the first opcode:
232
+ * 1. it is not an `Engine` at all (a stray object, a module namespace, a
233
+ * forgotten `await` on `createRevmEngine()`) — otherwise the node comes up
234
+ * and dies at the first `eth_call` with a `not a function` TypeError that
235
+ * reads like a node bug;
236
+ * 2. it implements only HALF the seam: no usable `transact`. There is no second
237
+ * engine to mine on, so this is a missing capability the node cannot supply;
238
+ * 3. its `connect(context)` throws, either because it cannot initialise (no
239
+ * wasm, no memory) or because it refuses this node's configuration (the
240
+ * revm engine refuses `stateMode:'trie'`, having no synchronous view of a
241
+ * `MerkleStateManager` to read through).
242
+ *
243
+ * The engine's own message is preserved verbatim inside the thrown error's
244
+ * message (not only as `cause`), because the engine is the only party that
245
+ * knows WHY, and browser consoles routinely show a message without its cause.
246
+ */
247
+ export async function connectEngine(
248
+ engine: Engine,
249
+ context: EngineContext,
250
+ ): Promise<void> {
251
+ if (typeof engine?.call !== 'function' || typeof engine?.id !== 'string') {
252
+ throw new Error(
253
+ `webevm: the value passed as \`engine\` is not an Engine — it must have a string \`id\` and a \`call(request)\` method (got ${describe(engine)}). ` +
254
+ `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. ` +
255
+ `If you built it with an async factory (e.g. \`createRevmEngine()\`), await it first.`,
256
+ );
257
+ }
258
+ // `transact` IS REQUIRED, and this is the guard that says so at construction.
259
+ // It was briefly optional — for exactly as long as the shipped revm engine had
260
+ // no write half — and an engine that omitted it had its transactions mined on
261
+ // the node's own `@ethereumjs/vm`. That fallback is GONE: a node must run ONE
262
+ // EVM, so `node.engine` names the engine that answered its reads AND executed
263
+ // its transactions, and a receipt can be attributed to it.
264
+ //
265
+ // MISSING and BROKEN are refused together, in the same words, because they are
266
+ // the same mistake from the node's point of view (a half-built engine) and
267
+ // neither can be served: there is no second engine to fall back to, and one
268
+ // substituted silently is the lie `connectEngine` exists to refuse.
269
+ if (typeof (engine as Engine).transact !== 'function') {
270
+ throw new Error(
271
+ `webevm: the engine '${engine.id}' has no usable \`transact\` method (got ${typeof engine.transact}). ` +
272
+ `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. ` +
273
+ `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.`,
274
+ );
275
+ }
276
+ try {
277
+ await engine.connect?.(context);
278
+ } catch (err) {
279
+ throw new Error(
280
+ `webevm: the engine '${engine.id}' could not be connected, so the node was NOT created. ` +
281
+ `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. ` +
282
+ `Fix the configuration (this node is stateMode:'${context.stateMode}') or pass a different engine. Cause: ${message(err)}`,
283
+ {cause: err},
284
+ );
285
+ }
286
+ }
287
+
288
+ /** A short, safe rendering of whatever was passed as an engine. */
289
+ function describe(value: unknown): string {
290
+ if (value === null) return 'null';
291
+ if (typeof value !== 'object') return typeof value;
292
+ if (typeof (value as Engine).id === 'string') {
293
+ return `an object with id '${(value as Engine).id}' and no call()`;
294
+ }
295
+ return `an object with keys [${Object.keys(value as object).join(', ')}]`;
296
+ }
297
+
298
+ function message(err: unknown): string {
299
+ return String((err as Error)?.message ?? err);
300
+ }
package/src/index.ts ADDED
@@ -0,0 +1,46 @@
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 {
10
+ createIndexedDBPersistence,
11
+ createMemoryPersistence,
12
+ } from './persistence.js';
13
+ export type {
14
+ SlimNode,
15
+ NodeOptions,
16
+ MiningConfig,
17
+ StateMode,
18
+ SenderMode,
19
+ // The engine seam: implement `Engine` to put a different EVM behind the node —
20
+ // its reads (`call`) and its transactions (`transact`). Types only, so the core
21
+ // never imports a non-default engine.
22
+ Engine,
23
+ EngineContext,
24
+ EngineInfo,
25
+ ReadCallRequest,
26
+ ReadCallResult,
27
+ TransactionRequest,
28
+ TransactionResult,
29
+ TransactionLog,
30
+ GenesisAccount,
31
+ BlockEnv,
32
+ PersistenceAdapter,
33
+ RequestArguments,
34
+ SerializedState,
35
+ } from './types.js';
36
+ export {RpcError} from './types.js';
37
+ // The revm engine is intentionally NOT re-exported here either, for the same
38
+ // reason: the core must import no engine a consumer did not. Import it directly:
39
+ // import {createRevmEngine} from 'webevm/revm';
40
+ // Worker helpers are intentionally NOT re-exported here to keep comlink out of
41
+ // the core bundle. Import them directly:
42
+ // import {createWorkerNode} from 'webevm/worker-client';
43
+ // new Worker(new URL('webevm/worker-entry', import.meta.url));
44
+ // ...and, for a Worker that must build its own engine (an engine cannot cross the
45
+ // boundary), your own worker module:
46
+ // import {exposeNode} from 'webevm/worker-host';
@@ -0,0 +1,191 @@
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
+
96
+ export function intrinsicGas(
97
+ data: Uint8Array,
98
+ isCreate: boolean,
99
+ common: Common,
100
+ ): bigint {
101
+ let gas = 21_000n;
102
+ // EIP-2028 (Istanbul): 16 per non-zero calldata byte, 4 per zero one. Hardcoded
103
+ // rather than asked of `common`, unlike the EIP-3860 term below — see the
104
+ // header: no fork this engine admits predates Istanbul, and none can.
105
+ for (const b of data) gas += b === 0 ? 4n : 16n;
106
+ if (isCreate) {
107
+ gas += 32_000n;
108
+ // EIP-3860 (Shanghai): 2 gas per 32-byte initcode word. Asked of the node's
109
+ // own `Common` rather than gated on a fork name, so this charge lands
110
+ // exactly where `@ethereumjs/vm`'s `runTx` charges it on the write path.
111
+ if (common.isActivatedEIP(3860)) {
112
+ gas += BigInt(Math.ceil(data.length / 32)) * 2n;
113
+ }
114
+ }
115
+ return gas;
116
+ }
117
+
118
+ /** EIP-2930: what one access-list entry's ADDRESS costs, up front. */
119
+ const ACCESS_LIST_ADDRESS_COST = 2_400n;
120
+ /** EIP-2930: what one access-list STORAGE KEY costs, up front. */
121
+ const ACCESS_LIST_STORAGE_KEY_COST = 1_900n;
122
+
123
+ /**
124
+ * WHAT AN `eth_estimateGas` REQUEST'S ACCESS LIST COSTS: 2,400 per address plus
125
+ * 1,900 per storage key, the EIP-2930 charge, added to {@link intrinsicGas} by
126
+ * `eth_estimateGas` alone.
127
+ *
128
+ * ## Why it is a SECOND function rather than a term of the formula above
129
+ *
130
+ * {@link intrinsicGas} has exactly two callers and they must not drift: `node.ts`
131
+ * ADDS it to the EXECUTION gas an engine reports, and `webevm/revm`
132
+ * SUBTRACTS it from revm's total. The engine seam's read request
133
+ * (`ReadCallRequest`) carries NO access list (a read is executed with none on
134
+ * either engine), so a term added to the shared formula would be subtracted from a
135
+ * number that never included it, and `eth_estimateGas` would come out 6,200 gas
136
+ * short on revm and 6,200 long on `@ethereumjs/evm` for the same request. The
137
+ * charge therefore sits ABOVE the seam, added once by the one caller that has a
138
+ * request to read it off.
139
+ *
140
+ * ## Why `eth_estimateGas` charges it at all
141
+ *
142
+ * BECAUSE THE NODE'S OWN REFUSAL POINTS THE CALLER HERE. A transaction whose gas
143
+ * limit is below the intrinsic floor is refused with "raise the gas limit to at
144
+ * least N", pointing the caller at `eth_estimateGas` for the number a transaction
145
+ * needs (`refuseIfBelowIntrinsicGas` in ./node.ts), and that floor is the
146
+ * transaction's own `getIntrinsicGas()`, WHICH INCLUDES THE ACCESS LIST. An estimate blind to
147
+ * the list answered 21,000 for a type-1 transaction with a floor of 27,200: the
148
+ * node would refuse the very number it had just recommended. It is also what geth
149
+ * does (`eth_estimateGas` honours the request's `accessList` field), so a client
150
+ * that sends one gets the same answer here as from a real node.
151
+ *
152
+ * ## It OVER-estimates a list whose entries are touched, deliberately
153
+ *
154
+ * The charge is added, but the WARMING is not modelled: the read underneath was
155
+ * executed without the list, so an access to a listed entry inside it was priced
156
+ * COLD (2,600 / 2,100) where the mined transaction pays WARM (100). The estimate
157
+ * is therefore up to 2,500 per touched address and 2,000 per touched key ABOVE
158
+ * what the transaction really costs. That is the SAFE direction: a client uses
159
+ * the estimate as its gas limit, so an over-estimate costs nothing (unused gas is
160
+ * not charged) while an under-estimate is a transaction that runs out of gas.
161
+ * Buying the exact figure would mean widening the read seam to carry an access
162
+ * list and pre-warming it on both engines, which is a change to the seam, not to
163
+ * an estimate. Both figures are measured and pinned in
164
+ * `test/revm-access-list.spec.ts`, and the run in which the node refused the very
165
+ * gas limit it had just recommended is kept in
166
+ * `docs/spikes/eip-2930-access-lists-are-charged-and-warmed/measurements.md`.
167
+ *
168
+ * ## What does NOT charge it, and why that is not an oversight
169
+ *
170
+ * `eth_fillTransaction` estimates with {@link intrinsicGas} alone, because the
171
+ * transaction it FILLS AND RETURNS carries no access list (it builds a type-0 or
172
+ * type-2 envelope and drops the field): charging for a list its own answer does
173
+ * not contain would hand back a gas limit for a different transaction.
174
+ */
175
+ export function accessListGas(accessList: unknown): bigint {
176
+ if (!Array.isArray(accessList)) return 0n;
177
+ let gas = 0n;
178
+ for (const entry of accessList) {
179
+ // TOLERANT OF THE ENTRY, STRICT ABOUT THE ARITHMETIC: this reads an unvalidated
180
+ // JSON-RPC parameter, and an entry naming no keys (`{address}` with
181
+ // `storageKeys` omitted) is a legitimate access list, not an error. What must
182
+ // never happen is a THROW here, which would turn a merely odd request into a
183
+ // failed estimate.
184
+ if (entry === null || typeof entry !== 'object') continue;
185
+ gas += ACCESS_LIST_ADDRESS_COST;
186
+ const keys = (entry as {storageKeys?: unknown}).storageKeys;
187
+ if (Array.isArray(keys))
188
+ gas += BigInt(keys.length) * ACCESS_LIST_STORAGE_KEY_COST;
189
+ }
190
+ return gas;
191
+ }