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,680 @@
1
+ /**
2
+ * types.ts — the public shape of the slim node. Deliberately tiny and
3
+ * transport-agnostic: a node is just an object with an async EIP-1193 `request()`
4
+ * plus a few node-owned controls (`mine`/`dumpState`/`loadState`). It knows
5
+ * NOTHING about Workers — because `request()` is already async, the exact same
6
+ * object works unchanged whether called on the main thread or across a thread
7
+ * boundary (see ../worker.ts for the optional comlink wrapper).
8
+ *
9
+ * The `@ethereumjs/*` imports below are TYPE-ONLY (erased at build time), so this
10
+ * module — and the core entry point that re-exports it — adds no runtime import.
11
+ */
12
+ import type { Address } from '@ethereumjs/util';
13
+ import type { Block } from '@ethereumjs/block';
14
+ import type { TypedTransaction } from '@ethereumjs/tx';
15
+ import type { StateManagerInterface } from '@ethereumjs/common';
16
+ import type { Common } from '@ethereumjs/common';
17
+ /** Minimal EIP-1193 request args. */
18
+ export interface RequestArguments {
19
+ readonly method: string;
20
+ readonly params?: readonly unknown[] | object;
21
+ }
22
+ /** EIP-1193-style JSON-RPC error (what we throw for honest gaps). */
23
+ export declare class RpcError extends Error {
24
+ readonly code: number;
25
+ readonly data?: unknown;
26
+ constructor(code: number, message: string, data?: unknown);
27
+ }
28
+ export type MiningConfig = {
29
+ type: 'auto';
30
+ } | {
31
+ type: 'manual';
32
+ } | {
33
+ type: 'interval';
34
+ intervalMs: number;
35
+ };
36
+ export interface PersistenceAdapter {
37
+ /** Load the single serialized state record (or null on first run). */
38
+ load(): Promise<SerializedState | null>;
39
+ /** Persist the single serialized state record. */
40
+ save(state: SerializedState): Promise<void>;
41
+ }
42
+ /**
43
+ * State backing mode.
44
+ * - `'none'` (DEFAULT): `SimpleStateManager` — plain Maps, NO trie, NO state root.
45
+ * The fast path; block `stateRoot`/`receiptsRoot`/`transactionsRoot` are zero
46
+ * placeholders (you are a local chain; canonical roots aren't needed). This is
47
+ * the recommended mode and what makes the node ~4× faster than the trie path.
48
+ * - `'trie'`: `MerkleStateManager` — real Merkle-Patricia trie. SLOWER (recomputes
49
+ * the state root each tx) but produces a REAL `stateRoot`, which (a) lets the
50
+ * node be conformance-tested against `ethereum/tests` GeneralStateTests (they
51
+ * verify the post-state root), and (b) gives honest canonical block roots for
52
+ * consumers that need them. Opt-in: pay for the trie only when you want it.
53
+ */
54
+ export type StateMode = 'none' | 'trie';
55
+ /**
56
+ * Sender-derivation mode.
57
+ * - `'recover'` (DEFAULT): derive the sender from the signature with ecrecover,
58
+ * exactly as a real node does. The tx is self-authenticating: a caller cannot
59
+ * claim to be an address it does not hold the key for. This is the only mode
60
+ * that is safe when the node is reachable by a caller you do not control.
61
+ * - `'trusted'`: TRUST a caller-supplied sender and SKIP ecrecover entirely.
62
+ * Enables `evm_sendRawTransactionAs` / `evm_sendRawTransactionSyncAs`, which
63
+ * take an explicit `from`. The signature is still carried on the wire and the
64
+ * tx hash is still the real one, but it is NEVER verified, so ANY caller can
65
+ * claim to be ANY address.
66
+ *
67
+ * Why it exists: ecrecover is a FIXED cost per tx and it dominates small ones. A
68
+ * client that signed the tx already knows the sender, so re-deriving it is pure
69
+ * waste in a local chain. Measured (2026-08-11,
70
+ * `docs/spikes/sender-recovery-uses-the-engines-ecrecover/measurements.md`) at
71
+ * ~6.2x on the isolated transaction path (2.09 -> 0.33 ms/tx, signing outside the
72
+ * window) and ~3.6x end-to-end through a viem-style client, with byte-identical
73
+ * gas and status.
74
+ *
75
+ * HOW BIG THE GAP IS DEPENDS ON THE ENGINE NOW. `'recover'` recovers with the
76
+ * INSTALLED ENGINE's secp256k1 when it has one ({@link Engine.ecrecover}, which
77
+ * `webevm/revm` implements at zero additional bytes — the `0x01`
78
+ * precompile is already in that module), and that makes the expensive half of
79
+ * `'recover'` about 4.3x cheaper: 2.02 -> 0.65 ms/tx isolated, so the gap narrows
80
+ * to ~2.8x (~1.8x end to end). `'trusted'` is still worth having and has stopped
81
+ * being the dominant lever. With no such engine, recovery is `@ethereumjs/tx`'s
82
+ * as before, and so is the ~6.2x.
83
+ *
84
+ * The primitive is just "execute as this sender, do not recover". It serves BOTH
85
+ * an ordinary signed tx that wants to skip a redundant recovery AND a higher
86
+ * layer building anvil-style impersonation on top with a fabricated signature.
87
+ * Impersonation itself is account POLICY and is deliberately NOT this package's
88
+ * job — see the `parseTx` docblock in node.ts for the full caller contract
89
+ * (notably: fabricated txs must be made unique per sender, or their hashes
90
+ * collide).
91
+ *
92
+ * The trade is real and one-directional: `'trusted'` removes the ONLY thing that
93
+ * binds a tx to its sender. Use it for a local, same-origin dev chain or an
94
+ * in-browser game. Never expose a `'trusted'` node over a transport that an
95
+ * untrusted caller can reach.
96
+ */
97
+ export type SenderMode = 'recover' | 'trusted';
98
+ /**
99
+ * One read-only call for an {@link Engine} to execute: exactly the inputs the
100
+ * node's pure-read helper has always handed `runCall`, and nothing more.
101
+ *
102
+ * The value types are `@ethereumjs/*`'s own (`Address`, `Block`) rather than hex
103
+ * strings, because the node already holds them in that form and the default
104
+ * engine passes them straight through — converting at the seam would add cost and
105
+ * a chance to change behaviour, in a refactor whose whole point is changing none.
106
+ */
107
+ export interface ReadCallRequest {
108
+ /** Caller (`msg.sender`). The node defaults it to the zero address. */
109
+ readonly from: Address;
110
+ /** Callee, or `undefined` for a CREATE-shaped call (gas estimation). */
111
+ readonly to?: Address;
112
+ /** Calldata (or init code when `to` is absent). */
113
+ readonly data: Uint8Array;
114
+ readonly value: bigint;
115
+ /** Gas made available to EXECUTION (intrinsic gas is the node's business). */
116
+ readonly gasLimit: bigint;
117
+ /** The block the call observes (NUMBER, TIMESTAMP, COINBASE, BASEFEE...). */
118
+ readonly block: Block;
119
+ }
120
+ /** What an engine reports back for a read-only call. */
121
+ export interface ReadCallResult {
122
+ /**
123
+ * Return data (or the revert data when {@link error} is set) — the CALLEE's
124
+ * bytes, and nothing else. `eth_call` surfaces exactly these as the `data` of
125
+ * its `execution reverted` error, where a client decodes them as a revert
126
+ * reason, so a failure that ran NO code (a call the engine refused before
127
+ * execution: an unaffordable value, a gas budget below the intrinsic cost)
128
+ * reports EMPTY here on every engine and puts its explanation in
129
+ * {@link error}. An engine whose own diagnostics arrive in this field must
130
+ * drop them rather than pass them on — `src/revm.ts` does, and
131
+ * `test/helpers/revm-engine.ts` holds both engines to the same bytes.
132
+ */
133
+ readonly returnValue: Uint8Array;
134
+ /**
135
+ * EXECUTION gas only — NOT a transaction's total, and NOT by itself an answer
136
+ * to `eth_estimateGas`. The node adds the intrinsic gas (21000 base, +32000
137
+ * create, calldata bytes, EIP-3860 initcode) to it, exactly as it did before
138
+ * the seam existed, and that sum is what a request CONSUMES. `eth_estimateGas`
139
+ * uses it as the FLOOR of a search for the smallest gas LIMIT the request
140
+ * succeeds at, because EIP-150's 63/64 rule makes consumption unusable as a
141
+ * limit for anything that calls out or creates (see `estimateGas` in
142
+ * ./node.ts) — so an engine may be asked for the same call several times, at
143
+ * descending {@link ReadCallRequest.gasLimit}s.
144
+ *
145
+ * WHEN A FRAME HALTS FOR WANT OF GAS, THIS IS THE WHOLE BUDGET IT WAS GIVEN,
146
+ * and that is load-bearing rather than incidental: it is how the node tells
147
+ * "needs more gas than the allowance" apart from "reverted" without matching on
148
+ * either engine's words for it.
149
+ */
150
+ readonly executionGasUsed: bigint;
151
+ /**
152
+ * Set iff the call did not succeed (a revert, a halt, or a refusal BEFORE
153
+ * execution); the EVM's own error string, which is where an engine's words for
154
+ * a failure belong. The two engines differ here by design — `insufficient
155
+ * balance` against revm's quoted `Transaction(LackOfFundForMaxFee { .. })` —
156
+ * and `node.ts` flattens both into one `execution reverted`, so nothing above
157
+ * the seam can tell the engines apart by it.
158
+ */
159
+ readonly error?: string;
160
+ }
161
+ /**
162
+ * One SIGNED transaction for an {@link Engine} to execute AND COMMIT, plus the
163
+ * block it is being mined in.
164
+ *
165
+ * NOT an RPC-level transaction request: there is nothing to fill in here and
166
+ * nothing optional. `eth_sendTransaction` does not exist on this node, and
167
+ * `eth_fillTransaction` returns its own object, one layer above the seam.
168
+ *
169
+ * THE TRANSACTION CROSSES AS THE NODE PARSED IT, for the reason
170
+ * {@link ReadCallRequest} carries `Address`/`Block`: the node already holds it in
171
+ * that form and the default engine hands it straight to `runTx`.
172
+ *
173
+ * THE SENDER CROSSES AS A SEPARATE VALUE ({@link sender}) rather than as something
174
+ * an engine reads off {@link tx}, and that is the whole reason this field exists.
175
+ *
176
+ * WHAT IS DELIBERATELY ABSENT: any switch that relaxes this transaction's
177
+ * VALIDITY. The read path's simulation switches (base fee, block gas limit,
178
+ * EIP-3607 — see the `call` side of `src/revm.ts`) have no counterpart here, and
179
+ * `@ethereumjs/vm`'s own `skipHardForkValidation` stays INSIDE the default engine
180
+ * where it means something (see `src/engine.ts`). Its `skipBlockGasLimitValidation`
181
+ * is not here either, and it is no longer there: it relaxed a rule only ONE engine
182
+ * could relax, so the relaxation was dropped rather than relocated, and a consumer
183
+ * who wants gas limits above the block's raises `NodeOptions.blockGasLimit` so that
184
+ * the block really is that large. A transaction that runs with relaxed validity is
185
+ * not a transaction.
186
+ */
187
+ export interface TransactionRequest {
188
+ /** The signed transaction, parsed by the node (which owns parsing). */
189
+ readonly tx: TypedTransaction;
190
+ /**
191
+ * WHO SENT IT, as a VALUE the node states: `msg.sender` of the top-level frame,
192
+ * the account whose balance and nonce this transaction moves, and the `from` on
193
+ * the receipt the node builds. AUTHORITATIVE. An engine executes on behalf of
194
+ * THIS address and must never derive one of its own.
195
+ *
196
+ * WHY IT IS A FIELD AND NOT A CALL. Sender derivation is the NODE's (`ADR 0006`)
197
+ * — an engine may LEND it the curve step ({@link Engine.ecrecover}) but never the
198
+ * decision, which is the distinction that entry draws —
199
+ * and in `senderMode:'trusted'` (the `evm_*As` cheats, ADR 0002) the node is TOLD
200
+ * the sender and deliberately skips ecrecover — so the authoritative sender may
201
+ * differ from whatever {@link tx}'s signature recovers to, and for a FABRICATED
202
+ * signature there is no meaningful recoverable sender at all. An engine that
203
+ * recovers the sender itself does not fail loudly on such a transaction: it
204
+ * charges a different account, advances a different nonce, and hands back a
205
+ * receipt that looks completely right. The only way that cannot happen is for the
206
+ * sender to be DATA on the request, so that an engine which ignores it is
207
+ * ignoring a stated input rather than merely disagreeing with a convention.
208
+ *
209
+ * It is therefore REQUIRED and non-optional: `{tx, block}` with no sender is not
210
+ * a transaction request, and an engine written against this type cannot be handed
211
+ * one. What an engine does with it is the engine's: the default `@ethereumjs/evm`
212
+ * engine pins it onto the `runTx` call (`src/engine.ts` — `runTx` reads the sender
213
+ * through exactly one method), and `webevm/revm` passes it as revm's
214
+ * `from`, which takes a sender directly and recovers nothing.
215
+ *
216
+ * `sender`, NOT `from`, deliberately — the two words are not synonyms here.
217
+ * {@link ReadCallRequest.from} is `eth_call`'s own parameter: caller-supplied,
218
+ * unauthenticated by nature, defaulted to the zero address. A transaction's
219
+ * `from` is the RPC RENDERING of this value on the receipt. What crosses here is
220
+ * the SENDER, which is this repo's word for the thing `senderMode` chooses how to
221
+ * obtain (recover it, or be told it) — so the field name says which concept it is
222
+ * rather than borrowing the read path's parameter name for something stronger.
223
+ */
224
+ readonly sender: Address;
225
+ /** The block it is mined in (NUMBER, TIMESTAMP, COINBASE, BASEFEE, GASLIMIT). */
226
+ readonly block: Block;
227
+ }
228
+ /**
229
+ * One log, as the seam carries it: raw bytes, no `@ethereumjs/*` types, no
230
+ * position. Block/transaction position (`blockNumber`, `logIndex`, ...) is the
231
+ * NODE's — an engine executing one transaction cannot know where in a block it
232
+ * sits.
233
+ */
234
+ export interface TransactionLog {
235
+ /** Emitting contract, 20 bytes. */
236
+ readonly address: Uint8Array;
237
+ /** 0-4 topics, 32 bytes each. */
238
+ readonly topics: readonly Uint8Array[];
239
+ readonly data: Uint8Array;
240
+ }
241
+ /**
242
+ * What an engine reports back for an executed transaction: EVERYTHING A RECEIPT
243
+ * NEEDS FROM AN EVM, and nothing else.
244
+ *
245
+ * THIS TYPE IS THE SEAM'S POINT. It is what makes two EVMs comparable field by
246
+ * field: the default engine fills it from a `runTx` result, another fills it from
247
+ * its own outcome, and the node builds the same receipt either way. So it is
248
+ * designed from the RECEIPT backwards, not from what `@ethereumjs/vm` happens to
249
+ * return — `amountSpent`, `gasRefund`, `minerValue`, `accessList` and the
250
+ * `execResult` are all absent because no receipt reads them.
251
+ *
252
+ * WHAT STAYS THE NODE'S, and is therefore not here: `cumulativeGasUsed` (a
253
+ * block-level accumulation over several transactions), the transaction hash,
254
+ * index, type, `from`/`to`, the block it landed in, and log positions. An engine
255
+ * executes one transaction; it does not build blocks.
256
+ *
257
+ * THE VALUES ARE RAW BYTES AND BIGINTS on purpose. An engine that is not
258
+ * `@ethereumjs/*` (revm-wasm, next) produces bytes, and a seam typed in one
259
+ * engine's classes would make every other engine convert into a vocabulary it
260
+ * does not speak.
261
+ */
262
+ export interface TransactionResult {
263
+ /**
264
+ * `1` succeeded, `0` failed — the receipt's own status, and the only thing a
265
+ * receipt says about failure. A revert REASON is deliberately absent: a receipt
266
+ * has no field for it (the read path's {@link ReadCallResult.error} is what
267
+ * surfaces engine words, to `eth_call`).
268
+ */
269
+ readonly status: 0 | 1;
270
+ /**
271
+ * Gas the sender PAYS FOR: NET of refunds, which is what the receipt reports
272
+ * and what `cumulativeGasUsed` accumulates. Not the gross gas spent before
273
+ * refunds — an engine reporting both must map the net one here (the read path
274
+ * wants the gross one, because a read has no refund).
275
+ */
276
+ readonly gasUsed: bigint;
277
+ /**
278
+ * Wei per gas actually charged — `min(maxFeePerGas, baseFee + tip)` for a 1559
279
+ * transaction, `gasPrice` for a legacy one. It comes from the engine that
280
+ * executed the transaction because that engine is what CHARGED it, so there is
281
+ * exactly one implementation of the fee arithmetic per engine and none in the
282
+ * node.
283
+ */
284
+ readonly effectiveGasPrice: bigint;
285
+ /**
286
+ * Logs in EMISSION order, and only the ones that SURVIVED: a log emitted inside
287
+ * a reverted sub-call is not here.
288
+ */
289
+ readonly logs: readonly TransactionLog[];
290
+ /** The 256-byte bloom over {@link logs} (all zero when there are none). */
291
+ readonly logsBloom: Uint8Array;
292
+ /**
293
+ * The address a top-level CREATE produced, 20 bytes; absent for a call, and
294
+ * absent for the nested creations a transaction performs (they are not the
295
+ * receipt's `contractAddress`).
296
+ */
297
+ readonly createdAddress?: Uint8Array;
298
+ }
299
+ /**
300
+ * What the node hands an engine once, at construction, so the engine can reach
301
+ * the node's AUTHORITATIVE state. Deliberately minimal: a later engine that needs
302
+ * more adds a field here rather than the node guessing now (ADR 0006 names this
303
+ * additive widening as the sanctioned way to grow the seam — `getBlockHash`
304
+ * arrived that way, for `webevm/revm`).
305
+ */
306
+ export interface EngineContext {
307
+ /** The node's live state manager. The node keeps ownership; do not fork it. */
308
+ readonly stateManager: StateManagerInterface;
309
+ /** Chain params (chain id, hardfork, custom crypto) the node runs under. */
310
+ readonly common: Common;
311
+ /**
312
+ * The hash of one of the node's blocks, by number, for the `BLOCKHASH` opcode
313
+ * — `undefined` for a block the node does not have (the EVM then reads zero).
314
+ *
315
+ * SYNCHRONOUS, unlike everything else the node does with blocks, because
316
+ * `BLOCKHASH` is answered in the middle of an opcode and a wasm interpreter has
317
+ * no suspension point to await at. It is a live lookup, not a snapshot: the
318
+ * node has mined no blocks yet when `connect` runs.
319
+ *
320
+ * An engine that leaves this unwired makes `BLOCKHASH` answer nothing for
321
+ * blocks the node actually has, silently — which is why it is on the context
322
+ * rather than an engine-side option to remember to pass.
323
+ */
324
+ getBlockHash(blockNumber: bigint): Uint8Array | undefined;
325
+ /**
326
+ * The node's state mode. An engine that cannot serve it must THROW here —
327
+ * `connect` is called during `createNode()`, so the refusal lands at
328
+ * construction rather than at the first opcode.
329
+ */
330
+ readonly stateMode: StateMode;
331
+ }
332
+ /**
333
+ * THE EVM BEHIND THE NODE, in ONE interface with TWO REQUIRED operations: execute
334
+ * a read-only {@link call} (`eth_call`, `eth_estimateGas`, `eth_fillTransaction`'s
335
+ * estimation) and execute a committing {@link transact} (the mining path).
336
+ *
337
+ * ONE INTERFACE, NOT TWO, and neither operation is a capability an engine may
338
+ * decline. What differs between them is a transaction's VALIDITY rules, not their
339
+ * engine-ness: a read RELAXES them (base fee, block gas limit, EIP-3607) and
340
+ * cannot commit, a transaction relaxes nothing and commits. That asymmetry belongs
341
+ * to the operations, and stating it in one place where both are visible beats
342
+ * splitting it across two interfaces that could be pointed at two different EVMs
343
+ * (two identifiers that can disagree, for no gain).
344
+ *
345
+ * An engine is an INJECTED OBJECT, never a name the core resolves — see
346
+ * `docs/adr/0006-the-engine-is-an-injected-object-not-a-named-string.md`.
347
+ *
348
+ * A read-only call MUST NOT mutate the node's state. Whatever it takes to hold
349
+ * that (a checkpoint/revert, a warm-slot reset, or nothing at all) is the
350
+ * ENGINE's business, not the node's: the default `@ethereumjs/evm` engine needs
351
+ * both and pays for both, an engine that is structurally incapable of committing
352
+ * pays for neither.
353
+ */
354
+ export interface Engine {
355
+ /**
356
+ * Stable identifier for bug reports (`'@ethereumjs/evm'` for the default).
357
+ * Surfaced verbatim as `node.engine.id`.
358
+ */
359
+ readonly id: string;
360
+ /**
361
+ * Bind to the node's state + chain context. Called EXACTLY once, during
362
+ * `createNode()`, before any call. Optional: an engine the node itself builds
363
+ * already has what it needs. Throwing here fails node construction.
364
+ */
365
+ connect?(context: EngineContext): void | Promise<void>;
366
+ /** Execute one read-only call against the node's CURRENT state. */
367
+ call(request: ReadCallRequest): Promise<ReadCallResult>;
368
+ /**
369
+ * Execute one signed transaction against the node's state AND COMMIT it,
370
+ * reporting what a receipt needs. Full validity: nonce checked, fees charged,
371
+ * no simulation switch anywhere near it.
372
+ *
373
+ * REQUIRED, like {@link call}, and refused at construction if it is missing or
374
+ * is not callable (`connectEngine` in `src/engine.ts`). The node does not fill
375
+ * it in with its own `@ethereumjs/vm`: a node running one EVM for reads and
376
+ * another for transactions has two chances to disagree with itself, and a
377
+ * receipt from it could not be attributed to the engine `node.engine` names.
378
+ *
379
+ * NONCE CHECKING IS THE CALL PATH'S CHOICE, NOT A PARAMETER. It is ON here
380
+ * because this method is the transaction path, and OFF for {@link call} because
381
+ * that is `eth_call` semantics. Nothing on {@link TransactionRequest} can turn
382
+ * it off, and nothing should be added that can: a transaction executed without
383
+ * the check is silently replayable, so the property worth having is that
384
+ * forgetting it is impossible rather than merely discouraged.
385
+ *
386
+ * THROW to reject a transaction the chain would not accept (a replayed nonce, an
387
+ * unaffordable fee). The node's mining path is written against that shape —
388
+ * `@ethereumjs/vm`'s `runTx` throws — so an engine reporting an invalid
389
+ * transaction as a zero-gas result would have the node mine a block containing a
390
+ * receipt for a transaction that never ran.
391
+ */
392
+ transact(request: TransactionRequest): Promise<TransactionResult>;
393
+ /**
394
+ * secp256k1 PUBLIC-KEY RECOVERY, offered as a PRIMITIVE: recover the 20-byte
395
+ * address that produced `(r, s)` over `hash` with `recoveryId`, or `undefined`
396
+ * when it recovers to nothing. Synchronous, stateless, and callable BEFORE
397
+ * {@link connect} — it touches no state, no block and no hardfork.
398
+ *
399
+ * OPTIONAL, and the ONLY optional operation on this interface. {@link call} and
400
+ * {@link transact} are capabilities the node cannot supply for an engine that
401
+ * omits them, so they are refused at construction; this one the node can, and
402
+ * always could — with no engine ecrecover it recovers the sender through
403
+ * `@ethereumjs/tx` as it always did. An engine implements it when its module
404
+ * ALREADY carries secp256k1 (`webevm/revm` does: the `0x01`
405
+ * precompile's own k256, reached without a database or a journal), which is why
406
+ * it costs zero additional bytes to offer and why offering it is not a
407
+ * requirement anyone should be held to.
408
+ *
409
+ * IT IS NOT "SENDER DERIVATION", and the distinction is the whole reason this
410
+ * is shaped as `(hash, recoveryId, r, s)` rather than as a transaction. Deciding
411
+ * WHO SENT A TRANSACTION stays the node's, on every engine (see
412
+ * {@link TransactionRequest.sender}): the node computes the message hash,
413
+ * enforces EIP-2's low-`s` rule, turns the wire's `v` — 27/28, `chainId * 2 +
414
+ * 35/36`, or a bare y-parity — into a 0/1 recovery id, and only THEN asks the
415
+ * curve. An engine is handed a question about a signature and never one about a
416
+ * transaction, so it needs to know nothing about EIP-155, EIP-2718 or
417
+ * `senderMode`, and it can neither admit a transaction the node would refuse nor
418
+ * refuse one the node would admit.
419
+ *
420
+ * EIP-2 IN PARTICULAR IS NOT YOURS TO ENFORCE. revm's implementation of this is
421
+ * the `0x01` precompile's, which NORMALISES a high-`s` signature and returns an
422
+ * address — correctly, because EIP-2 constrains transactions, not the
423
+ * precompile. The node refuses such a transaction above the seam so that the
424
+ * answer is the same on every engine. Implement this as the raw curve operation
425
+ * and add no protocol opinions to it.
426
+ *
427
+ * RETURN `undefined` rather than throwing when the signature does not recover:
428
+ * the node turns that into its own refusal, in the same shape on every engine.
429
+ *
430
+ * @param hash 32-byte message digest that was signed.
431
+ * @param recoveryId 0 or 1. Never the wire's `v`.
432
+ * @param r 32 bytes, big-endian.
433
+ * @param s 32 bytes, big-endian.
434
+ */
435
+ ecrecover?(hash: Uint8Array, recoveryId: number, r: Uint8Array, s: Uint8Array): Uint8Array | undefined;
436
+ }
437
+ /** Which EVM a node is running on (see {@link SlimNode.engine}). */
438
+ export interface EngineInfo {
439
+ /** The engine's stable identifier, e.g. `'@ethereumjs/evm'`. */
440
+ readonly id: string;
441
+ }
442
+ export interface NodeOptions {
443
+ /** EIP-155 chain id. Default 31337 (anvil/hardhat-style local). */
444
+ chainId?: number;
445
+ /** State backing: `'none'` (fast, no trie/root — default) or `'trie'` (real
446
+ * state root, slower; unlocks GeneralStateTests conformance). */
447
+ stateMode?: StateMode;
448
+ /**
449
+ * Sender derivation: `'recover'` (ecrecover, authenticated — DEFAULT) or
450
+ * `'trusted'` (skip ecrecover, trust a caller-supplied `from`). See
451
+ * {@link SenderMode}. `'trusted'` is ~6.2x faster per small tx on the default
452
+ * engine, ~2.8x with a revm engine installed (which recovers with its own
453
+ * secp256k1), and it lets ANY caller impersonate ANY address — opt in only for a
454
+ * local chain you control.
455
+ */
456
+ senderMode?: SenderMode;
457
+ /** Mining strategy. Default {type:'auto'}. */
458
+ miningConfig?: MiningConfig;
459
+ /** Optional persistence adapter (e.g. IndexedDB). */
460
+ persistence?: PersistenceAdapter;
461
+ /** Constant gas-fee values (slim node — no real fee market). */
462
+ baseFeePerGas?: bigint;
463
+ gasPrice?: bigint;
464
+ maxPriorityFeePerGas?: bigint;
465
+ /**
466
+ * Block gas limit. Default 30_000_000n, and a REAL limit: a transaction whose
467
+ * own gas limit exceeds it is refused (identically on every engine) rather than
468
+ * mined against a limit the block does not have. Raise it to admit bigger
469
+ * transactions; the block then really is that large, so `GASLIMIT` reports this
470
+ * number to a contract. It does NOT change the default `eth_call` read budget,
471
+ * which stays 30_000_000 (pass `gas` on the call for more).
472
+ */
473
+ blockGasLimit?: bigint;
474
+ /** Pre-fund accounts at genesis (address -> balance wei). */
475
+ initialBalances?: Record<string, bigint>;
476
+ /**
477
+ * Full genesis pre-state (address -> {balance, nonce, code, storage}). Richer
478
+ * than `initialBalances` (which only sets balance). Used to load an arbitrary
479
+ * starting state — e.g. a GeneralStateTest `pre` section — so that, in
480
+ * `stateMode:'trie'`, `getStateRoot()` after a tx can be compared to the
481
+ * fixture's expected post-state root. Applied at genesis, before block 0.
482
+ */
483
+ initialState?: Record<string, GenesisAccount>;
484
+ /**
485
+ * Override the header fields of MINED blocks. Lets a consumer run a tx under a
486
+ * specific block environment (coinbase, base fee, number, timestamp,
487
+ * prevRandao) — required to reproduce a GeneralStateTest `env` (the coinbase is
488
+ * credited tx fees, so it affects the post-state root). When omitted, the node
489
+ * uses its own constant fee market + a zero coinbase.
490
+ *
491
+ * GENESIS TAKES `coinbase` AND `prevRandao` FROM HERE TOO, and nothing else:
492
+ * they describe the CHAIN's environment rather than one block's position in it,
493
+ * so a block 0 that reported a zero miner while every block after it reported
494
+ * the configured one would be the same disagreement this option's two fields
495
+ * were made honest to remove. `number`, `timestamp` and `gasLimit` stay the
496
+ * node's own for block 0 — genesis IS block 0 by definition, and `blockEnv.number`
497
+ * exists to place a MINED block, not to renumber the genesis of the chain.
498
+ *
499
+ * Whatever is set here is REPORTED by `eth_getBlockByNumber` as `miner` and
500
+ * `mixHash`, and survives a `dumpState` / `loadState` round trip, so the block
501
+ * a consumer reads and the block a contract ran in cannot disagree.
502
+ */
503
+ blockEnv?: BlockEnv;
504
+ /**
505
+ * The EVM this node runs on, BOTH halves: reads (`eth_call`,
506
+ * `eth_estimateGas`, `eth_fillTransaction`'s estimation) through
507
+ * {@link Engine.call} and transactions through {@link Engine.transact}.
508
+ * Default: `@ethereumjs/evm`, i.e. exactly what the node has always run.
509
+ *
510
+ * An engine that implements only one half is refused at construction rather
511
+ * than half-served — see {@link Engine.transact}.
512
+ *
513
+ * An engine is passed as an OBJECT, never named by a string: the core must not
514
+ * reference engines it does not use, or a consumer of the JS-only path would
515
+ * pay (in bundle size) for an engine they never import. See
516
+ * `docs/adr/0006-the-engine-is-an-injected-object-not-a-named-string.md`.
517
+ */
518
+ engine?: Engine;
519
+ }
520
+ /** A full genesis account (all fields optional except an implicit zero default). */
521
+ export interface GenesisAccount {
522
+ balance?: bigint;
523
+ nonce?: bigint;
524
+ code?: string;
525
+ storage?: Record<string, string>;
526
+ }
527
+ /** Mined-block header overrides (e.g. to honor a GeneralStateTest `env`). */
528
+ export interface BlockEnv {
529
+ coinbase?: string;
530
+ baseFeePerGas?: bigint;
531
+ number?: bigint;
532
+ timestamp?: bigint;
533
+ gasLimit?: bigint;
534
+ prevRandao?: string;
535
+ }
536
+ /** A slim node: transport-agnostic EIP-1193 + node-owned controls. */
537
+ export interface SlimNode {
538
+ /** EIP-1193 request. Async ⇒ same object works on main thread or over comlink. */
539
+ request(args: RequestArguments): Promise<unknown>;
540
+ /** Mine one block now (only matters in manual/interval modes). */
541
+ mine(): Promise<{
542
+ blockNumber: number;
543
+ blockHash: string;
544
+ txHashes: string[];
545
+ }>;
546
+ /** Serialize all state to a plain object (live-set-sized; no trie/RLP walk). */
547
+ dumpState(): Promise<SerializedState>;
548
+ /** Restore state previously produced by dumpState (replaces current state). */
549
+ loadState(state: SerializedState): Promise<void>;
550
+ /** Subscribe to newHeads locally (used by eth_subscribe and consumers). */
551
+ onNewHead(cb: (head: {
552
+ number: number;
553
+ hash: string;
554
+ }) => void): () => void;
555
+ /**
556
+ * Current canonical state root. In `'trie'` mode this is the REAL
557
+ * Merkle-Patricia root (usable for GeneralStateTests conformance); in `'none'`
558
+ * mode the trie is absent so this throws (honest — there is no root to give).
559
+ */
560
+ getStateRoot(): Promise<string>;
561
+ /** The state mode this node was created with. */
562
+ readonly stateMode: 'none' | 'trie';
563
+ /** The sender mode this node was created with. */
564
+ readonly senderMode: SenderMode;
565
+ /**
566
+ * The engine this node was created with — `{id: '@ethereumjs/evm'}` unless one
567
+ * was injected. It answered this node's reads AND executed its transactions, so
568
+ * a receipt from this node can be attributed to this id.
569
+ */
570
+ readonly engine: EngineInfo;
571
+ /** Stop timers / release resources. */
572
+ dispose(): Promise<void>;
573
+ }
574
+ /**
575
+ * Slim, live-set-sized serialized state. No trie, no RLP state-root walk.
576
+ *
577
+ * `version` IS STILL 1 AFTER THE BLOCK HEADER GREW `miner` / `mixHash` /
578
+ * `logsBloom` (2026-08-11), because those three fields were added as OPTIONAL
579
+ * reads rather than as a new shape: a dump written by an older version carries
580
+ * none of them and loads into this one unchanged (absent `miner` / `mixHash` read
581
+ * as zero, and the bloom is rebuilt from the receipts the dump already carries).
582
+ * A bump would have bought nothing a reader can act on and would have invalidated
583
+ * every IndexedDB record in the wild for a format they can still be read as. Bump
584
+ * it when a dump stops being loadable by the code that wrote it, which is the only
585
+ * question `version` can usefully answer.
586
+ */
587
+ export interface SerializedState {
588
+ version: 1;
589
+ chainId: number;
590
+ /** State mode the dump was produced in (informational). */
591
+ stateMode?: 'none' | 'trie';
592
+ /** SimpleStateManager Maps: address -> hex-encoded account/code/storage. */
593
+ accounts: Record<string, string>;
594
+ code: Record<string, string>;
595
+ storage: Record<string, Record<string, string>>;
596
+ /** Block list (header fields we keep) keyed by number. */
597
+ blocks: SerializedBlock[];
598
+ /** Receipts keyed by tx hash. */
599
+ receipts: Record<string, SerializedReceipt>;
600
+ /** Raw tx + meta keyed by tx hash (for eth_getTransactionByHash). */
601
+ transactions: Record<string, SerializedTx>;
602
+ }
603
+ export interface SerializedBlock {
604
+ number: number;
605
+ hash: string;
606
+ parentHash: string;
607
+ timestamp: number;
608
+ gasUsed: string;
609
+ gasLimit: string;
610
+ baseFeePerGas: string;
611
+ /** Real Merkle-Patricia state root in `'trie'` mode; zero placeholder in `'none'`. */
612
+ stateRoot: string;
613
+ /**
614
+ * The block's coinbase, under the name `eth_getBlockByNumber` reports it. Named
615
+ * for the RPC rather than for the header (`coinbase`) or the option
616
+ * ({@link BlockEnv.coinbase}) because this record exists to be SERVED: every
617
+ * other field here already carries its RPC name.
618
+ *
619
+ * OPTIONAL, and absent means the zero address — a dump written before this field
620
+ * existed has none. It is persisted rather than read off the `Block` object next
621
+ * to it because `loadState` rebuilds that object from THIS record, so a node that
622
+ * read the object would answer correctly until a reload and zero after one.
623
+ */
624
+ miner?: string;
625
+ /** The block's `mixHash`, i.e. post-Merge its PREVRANDAO. Absent means zero. */
626
+ mixHash?: string;
627
+ /**
628
+ * The block's logs bloom: the OR of its receipts' blooms, so a consumer
629
+ * pre-filtering blocks by it before calling `eth_getLogs` finds the logs that
630
+ * are really there. Absent (an older dump) means it is REBUILT on load from the
631
+ * receipts, which the dump carries either way.
632
+ */
633
+ logsBloom?: string;
634
+ transactions: string[];
635
+ logsCount: number;
636
+ }
637
+ export interface SerializedLog {
638
+ address: string;
639
+ topics: string[];
640
+ data: string;
641
+ blockNumber: number;
642
+ blockHash: string;
643
+ transactionHash: string;
644
+ transactionIndex: number;
645
+ logIndex: number;
646
+ }
647
+ export interface SerializedReceipt {
648
+ transactionHash: string;
649
+ transactionIndex: number;
650
+ blockNumber: number;
651
+ blockHash: string;
652
+ from: string;
653
+ to: string | null;
654
+ contractAddress: string | null;
655
+ cumulativeGasUsed: string;
656
+ gasUsed: string;
657
+ effectiveGasPrice: string;
658
+ status: 0 | 1;
659
+ type: number;
660
+ logs: SerializedLog[];
661
+ logsBloom: string;
662
+ }
663
+ export interface SerializedTx {
664
+ hash: string;
665
+ raw: string;
666
+ from: string;
667
+ to: string | null;
668
+ nonce: number;
669
+ value: string;
670
+ input: string;
671
+ type: number;
672
+ blockNumber: number;
673
+ blockHash: string;
674
+ transactionIndex: number;
675
+ gas: string;
676
+ gasPrice: string | null;
677
+ maxFeePerGas: string | null;
678
+ maxPriorityFeePerGas: string | null;
679
+ }
680
+ //# sourceMappingURL=types.d.ts.map