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.
- package/LICENSE +21 -0
- package/README.md +674 -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 +1743 -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 +680 -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 +1959 -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 +701 -0
- package/src/worker-client.ts +112 -0
- package/src/worker-entry.ts +31 -0
- 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
|
+
}
|