webevm 0.9.1 → 0.10.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/README.md +94 -12
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/intrinsic-gas.d.ts +70 -14
- package/dist/intrinsic-gas.d.ts.map +1 -1
- package/dist/intrinsic-gas.js +65 -0
- package/dist/intrinsic-gas.js.map +1 -1
- package/dist/node.d.ts.map +1 -1
- package/dist/node.js +686 -41
- package/dist/node.js.map +1 -1
- package/dist/revm.d.ts +18 -17
- package/dist/revm.d.ts.map +1 -1
- package/dist/revm.js +80 -40
- package/dist/revm.js.map +1 -1
- package/dist/state-manager.d.ts +19 -0
- package/dist/state-manager.d.ts.map +1 -1
- package/dist/state-manager.js +32 -0
- package/dist/state-manager.js.map +1 -1
- package/dist/types.d.ts +39 -0
- package/dist/types.d.ts.map +1 -1
- package/dist/worker-host.d.ts +30 -0
- package/dist/worker-host.d.ts.map +1 -1
- package/dist/worker-host.js +42 -5
- package/dist/worker-host.js.map +1 -1
- package/package.json +2 -2
- package/src/index.ts +1 -0
- package/src/intrinsic-gas.ts +92 -14
- package/src/node.ts +864 -44
- package/src/revm.ts +103 -47
- package/src/state-manager.ts +35 -0
- package/src/types.ts +40 -0
- package/src/worker-host.ts +79 -7
package/src/revm.ts
CHANGED
|
@@ -48,17 +48,30 @@
|
|
|
48
48
|
*
|
|
49
49
|
* AND WHICH FORKS. It serves the hardforks whose transaction costing the node's
|
|
50
50
|
* own arithmetic reproduces AND the PROTOCOL agrees with
|
|
51
|
-
* (`REVM_SPEC_BY_HARDFORK
|
|
52
|
-
* BY NAME at construction (`REVM_REFUSED_HARDFORKS`):
|
|
53
|
-
* `./intrinsic-gas.ts` does not
|
|
54
|
-
*
|
|
51
|
+
* (`REVM_SPEC_BY_HARDFORK`: Berlin through Osaka today), and refuses the rest
|
|
52
|
+
* BY NAME at construction (`REVM_REFUSED_HARDFORKS`): Amsterdam, whose gas model
|
|
53
|
+
* `./intrinsic-gas.ts` does not implement. Prague and Osaka were refused until
|
|
54
|
+
* the node applied their gas rules above the seam (ADR 0008's fourth amendment,
|
|
55
|
+
* ADR 0015).
|
|
55
56
|
*/
|
|
56
57
|
import type {Common} from '@ethereumjs/common';
|
|
57
58
|
import type {Block} from '@ethereumjs/block';
|
|
58
|
-
import {
|
|
59
|
+
import {
|
|
60
|
+
bigIntToBytes,
|
|
61
|
+
bytesToBigInt,
|
|
62
|
+
equalsBytes,
|
|
63
|
+
generateAddress,
|
|
64
|
+
setLengthLeft,
|
|
65
|
+
} from '@ethereumjs/util';
|
|
59
66
|
import type {OverlayStorageStateManager} from './state-manager.js';
|
|
60
67
|
import {createRevm, type SpecName, type WasmSource} from 'revm-wasm';
|
|
61
|
-
import type {
|
|
68
|
+
import type {
|
|
69
|
+
Authorization,
|
|
70
|
+
BlockEnv,
|
|
71
|
+
ExecuteOptions,
|
|
72
|
+
Outcome,
|
|
73
|
+
Revm,
|
|
74
|
+
} from 'revm-wasm';
|
|
62
75
|
import {intrinsicGas} from './intrinsic-gas.js';
|
|
63
76
|
import {SimpleStateManagerStore} from './revm-state-store.js';
|
|
64
77
|
import type {
|
|
@@ -85,10 +98,10 @@ export interface RevmEngineOptions {
|
|
|
85
98
|
/**
|
|
86
99
|
* ethereumjs hardfork name -> revm spec: the hardforks this engine ADMITS.
|
|
87
100
|
*
|
|
88
|
-
* The node runs Cancun
|
|
89
|
-
*
|
|
90
|
-
* that silently
|
|
91
|
-
* default engine and nothing would say so.
|
|
101
|
+
* The node runs Cancun, Prague or Osaka (`NodeOptions.hardfork`), so this table
|
|
102
|
+
* is reached by every node, and it is still a GUARD as much as a feature: an
|
|
103
|
+
* engine that silently ran one fork's rules on a node configured for another
|
|
104
|
+
* would charge different gas from the default engine and nothing would say so.
|
|
92
105
|
*
|
|
93
106
|
* WHAT MAKES A FORK ADMISSIBLE is not that revm has a spec for it, and it is not
|
|
94
107
|
* that the node and revm AGREE about it either. Agreement is necessary and not
|
|
@@ -101,14 +114,18 @@ export interface RevmEngineOptions {
|
|
|
101
114
|
* number back, so the two sides agree about intrinsic gas by construction and a
|
|
102
115
|
* term that is wrong at a fork is wrong on both sides at once.
|
|
103
116
|
*
|
|
104
|
-
* Prague and Osaka
|
|
117
|
+
* Prague and Osaka once failed (a): the node's estimate ignored EIP-7623's
|
|
118
|
+
* calldata floor and its read budget exceeded EIP-7825's cap, both of which revm
|
|
119
|
+
* enforces. The node now applies both above the seam, so every read it hands
|
|
120
|
+
* this engine is one revm accepts (ADR 0015), and both are admitted. Berlin,
|
|
121
|
+
* London and Paris once failed (b): both
|
|
105
122
|
* this node and `revm-wasm@0.3.0` charged EIP-3860's initcode word cost there,
|
|
106
123
|
* and EIP-3860 arrived in Shanghai. `revm-wasm@0.3.1` fixed its half, and
|
|
107
124
|
* ./intrinsic-gas.ts now gates the term on the node's `Common`, so all three are
|
|
108
125
|
* back.
|
|
109
126
|
*
|
|
110
127
|
* ADDING A FORK BELOW BERLIN COSTS MORE THAN A LINE HERE. ./intrinsic-gas.ts is
|
|
111
|
-
* protocol-correct over Istanbul..
|
|
128
|
+
* protocol-correct over Istanbul..Osaka only: it hardcodes EIP-2028's 16 gas per
|
|
112
129
|
* non-zero calldata byte, which was 68 before Istanbul, so a pre-Istanbul entry in
|
|
113
130
|
* this table would make `eth_estimateGas` UNDER-estimate by 52 gas per non-zero
|
|
114
131
|
* byte — and a client uses an estimate as the transaction's gas limit. Anything
|
|
@@ -152,29 +169,28 @@ export const REVM_SPEC_BY_HARDFORK: Readonly<Record<string, SpecName>> =
|
|
|
152
169
|
paris: 'MERGE',
|
|
153
170
|
shanghai: 'SHANGHAI',
|
|
154
171
|
cancun: 'CANCUN',
|
|
172
|
+
prague: 'PRAGUE',
|
|
173
|
+
osaka: 'OSAKA',
|
|
155
174
|
});
|
|
156
175
|
|
|
157
176
|
/**
|
|
158
177
|
* Hardforks revm HAS a spec for and this engine still refuses, each with the
|
|
159
178
|
* reason quoted verbatim in the refusal.
|
|
160
179
|
*
|
|
161
|
-
* These are the silent-wrong-answer cases
|
|
180
|
+
* These are the silent-wrong-answer cases: forks at which revm ENFORCES rules
|
|
162
181
|
* the node's own arithmetic does not implement, so `eth_estimateGas` could return
|
|
163
|
-
* a number the engine that produced it would REJECT
|
|
182
|
+
* a number the engine that produced it would REJECT, and viem uses that number
|
|
164
183
|
* as the transaction's gas limit. A loud refusal at construction is the honest
|
|
165
184
|
* edge (ADR 0004); a plausible estimate is not.
|
|
166
185
|
*
|
|
167
186
|
* To admit one of these, make the node's arithmetic BOTH agree with revm under
|
|
168
187
|
* that spec AND match the protocol at that fork: implement the missing rule in
|
|
169
|
-
* ./intrinsic-gas.ts
|
|
170
|
-
*
|
|
171
|
-
*
|
|
172
|
-
*
|
|
173
|
-
*
|
|
174
|
-
*
|
|
175
|
-
* `docs/spikes/prague-intrinsic-gas-floor-or-refuse/` and
|
|
176
|
-
* `docs/spikes/intrinsic-gas-charges-eip-3860-on-forks-that-predate-it/` (§6 for
|
|
177
|
-
* the re-measurement on `revm-wasm@0.3.1`, which left both of these standing).
|
|
188
|
+
* ./intrinsic-gas.ts (or, for a rule about which reads and transactions are
|
|
189
|
+
* admissible rather than a term of the formula, in the node's admission above
|
|
190
|
+
* the seam, as Prague's floor and Osaka's cap are: ADR 0015), then prove it
|
|
191
|
+
* against the engine and move the entry to {@link REVM_SPEC_BY_HARDFORK}.
|
|
192
|
+
* `prague` and `osaka` were here until that work was done; the measurements
|
|
193
|
+
* that kept them here are in `docs/spikes/prague-intrinsic-gas-floor-or-refuse/`.
|
|
178
194
|
*
|
|
179
195
|
* FROZEN for the same reason as {@link REVM_SPEC_BY_HARDFORK}, where the freeze
|
|
180
196
|
* decision (and why the guard reads these objects rather than a load-time
|
|
@@ -183,19 +199,12 @@ export const REVM_SPEC_BY_HARDFORK: Readonly<Record<string, SpecName>> =
|
|
|
183
199
|
*/
|
|
184
200
|
export const REVM_REFUSED_HARDFORKS: Readonly<Record<string, string>> =
|
|
185
201
|
Object.freeze({
|
|
186
|
-
|
|
187
|
-
`
|
|
188
|
-
`
|
|
189
|
-
`
|
|
190
|
-
`
|
|
191
|
-
`
|
|
192
|
-
`GasFloorMoreThanGasLimit for a calldata-heavy call — and a client uses an ` +
|
|
193
|
-
`estimate as the transaction's gas limit`,
|
|
194
|
-
osaka:
|
|
195
|
-
`it inherits Prague's EIP-7623 calldata floor, which src/intrinsic-gas.ts ` +
|
|
196
|
-
`does not compute, and adds the EIP-7825 transaction gas limit cap of ` +
|
|
197
|
-
`16777216, which is below the node's default read budget of 30000000 — so ` +
|
|
198
|
-
`an ordinary eth_call would be rejected outright with TxGasLimitGreaterThanCap`,
|
|
202
|
+
amsterdam:
|
|
203
|
+
`its gas model is not the one this node's shared intrinsic-gas arithmetic ` +
|
|
204
|
+
`(src/intrinsic-gas.ts) implements: EIP-8037 splits intrinsic gas into a ` +
|
|
205
|
+
`regular and a state dimension with its own cap, and EIP-7976 and EIP-7981 ` +
|
|
206
|
+
`re-price the calldata floor, so eth_estimateGas would return a gas limit ` +
|
|
207
|
+
`computed under Osaka's rules for a chain running Amsterdam's`,
|
|
199
208
|
});
|
|
200
209
|
|
|
201
210
|
/**
|
|
@@ -243,10 +252,11 @@ export async function createRevmEngine(
|
|
|
243
252
|
// A HARDFORK THIS ENGINE CANNOT COST, refused out loud and at construction:
|
|
244
253
|
// revm would run it and charge rules the node's own arithmetic does not
|
|
245
254
|
// implement, and a consumer who asked for revm and silently got something
|
|
246
|
-
// else would measure the wrong thing forever. Unreachable
|
|
247
|
-
//
|
|
248
|
-
//
|
|
249
|
-
//
|
|
255
|
+
// else would measure the wrong thing forever. Unreachable through
|
|
256
|
+
// `createNode()` today (every fork the node offers is admitted), which is
|
|
257
|
+
// the point: it fires the day the node offers a fork this engine has not
|
|
258
|
+
// been costed for, rather than letting `eth_estimateGas` return a number
|
|
259
|
+
// this engine would then reject.
|
|
250
260
|
const hardfork = context.common.hardfork();
|
|
251
261
|
const refused = REVM_REFUSED_HARDFORKS[hardfork];
|
|
252
262
|
if (refused !== undefined) {
|
|
@@ -346,6 +356,18 @@ export async function createRevmEngine(
|
|
|
346
356
|
// transaction being MINED (`transact` below, and
|
|
347
357
|
// `refuseIfOverBlockGasLimit` in ./node.ts ahead of
|
|
348
358
|
// it), and a read is not mined;
|
|
359
|
+
// disableTxGasLimitCap EIP-7825 (Osaka on) caps a TRANSACTION's gas limit
|
|
360
|
+
// at 16,777,216, and revm applies it to every
|
|
361
|
+
// execution. A read is not a transaction: geth skips
|
|
362
|
+
// the cap for `eth_call` (and keeps it for
|
|
363
|
+
// `eth_estimateGas`, which the node caps itself), and
|
|
364
|
+
// `@ethereumjs/evm`'s `runCall` never enforced it, so
|
|
365
|
+
// without this the node's default 30,000,000 budget
|
|
366
|
+
// is refused here and runs on the default engine. It
|
|
367
|
+
// lifts ONLY the cap: EIP-7623's calldata floor is
|
|
368
|
+
// still enforced, which is why the node refuses a
|
|
369
|
+
// read below the floor itself (ADR 0015). Needs
|
|
370
|
+
// `revm-wasm@0.5.0`; a no-op before Osaka;
|
|
349
371
|
// disableEip3607 EIP-3607 rejects a caller that holds code, which
|
|
350
372
|
// is a rule about SENDING a transaction. Simulating
|
|
351
373
|
// from a contract address is ordinary practice
|
|
@@ -386,6 +408,7 @@ export async function createRevmEngine(
|
|
|
386
408
|
// never a fabricated balance.
|
|
387
409
|
disableBaseFee: true,
|
|
388
410
|
disableBlockGasLimit: true,
|
|
411
|
+
disableTxGasLimitCap: true,
|
|
389
412
|
disableEip3607: true,
|
|
390
413
|
// Logs and the post-state map are not part of a read's answer, and
|
|
391
414
|
// building them costs ~0.9 microseconds per call.
|
|
@@ -493,14 +516,19 @@ export async function createRevmEngine(
|
|
|
493
516
|
})),
|
|
494
517
|
}
|
|
495
518
|
: {}),
|
|
519
|
+
// EIP-7702's authorization list (a type-4 transaction, Prague on), in
|
|
520
|
+
// revm's shape. revm recovers each authority and applies the delegations
|
|
521
|
+
// itself, exactly as `runTx` does on the default engine: an authorization
|
|
522
|
+
// is a SIGNATURE inside the transaction, not its sender, so recovering it
|
|
523
|
+
// is execution and not sender derivation, and the seam carries the list
|
|
524
|
+
// on the transaction rather than as a node-decided value.
|
|
525
|
+
...authorizationsOf(tx),
|
|
496
526
|
// NOT MAPPED, and named so it is a known gap rather than an oversight:
|
|
497
527
|
// EIP-4844's `blobVersionedHashes` / `maxFeePerBlobGas` (a type-3
|
|
498
|
-
// transaction)
|
|
499
|
-
//
|
|
500
|
-
//
|
|
501
|
-
//
|
|
502
|
-
// documented where it would be met by
|
|
503
|
-
// `document-the-type-3-receipt-gap-where-it-would-be-met`.
|
|
528
|
+
// transaction). The type-3 receipt is incomplete on BOTH engines
|
|
529
|
+
// (`blobGasUsed` / `blobGasPrice` are absent from the seam's result
|
|
530
|
+
// altogether), and that limitation is documented where it would be met
|
|
531
|
+
// by `document-the-type-3-receipt-gap-where-it-would-be-met`.
|
|
504
532
|
spec,
|
|
505
533
|
chainId,
|
|
506
534
|
block: blockEnvOf(request.block),
|
|
@@ -509,7 +537,8 @@ export async function createRevmEngine(
|
|
|
509
537
|
// changes are all part of a transaction's answer, and `returnState:false`
|
|
510
538
|
// cannot be combined with committing anyway), and above all NONE of the
|
|
511
539
|
// read path's simulation switches: `disableBaseFee`,
|
|
512
|
-
// `disableBlockGasLimit`, `disableEip3607` and
|
|
540
|
+
// `disableBlockGasLimit`, `disableTxGasLimitCap`, `disableEip3607` and
|
|
541
|
+
// `disableBalanceCheck` each
|
|
513
542
|
// relax a transaction's VALIDITY, and a transaction that runs with them
|
|
514
543
|
// relaxed is not a transaction. `revm-wasm` refuses to combine them with
|
|
515
544
|
// committing, so copying the read path's options object here would throw
|
|
@@ -701,6 +730,33 @@ interface TransactionFields {
|
|
|
701
730
|
readonly maxFeePerGas?: bigint;
|
|
702
731
|
readonly maxPriorityFeePerGas?: bigint;
|
|
703
732
|
readonly accessList?: readonly [Uint8Array, Uint8Array[]][];
|
|
733
|
+
/** EIP-7702: `[chainId, address, nonce, yParity, r, s]`, each as RLP bytes. */
|
|
734
|
+
readonly authorizationList?: readonly Uint8Array[][];
|
|
735
|
+
}
|
|
736
|
+
|
|
737
|
+
/**
|
|
738
|
+
* A type-4 transaction's authorization list, as revm takes it: the RLP byte
|
|
739
|
+
* fields `@ethereumjs/tx` holds, decoded into numbers and 32-byte signature
|
|
740
|
+
* halves. An empty object for every other transaction type, so the spread above
|
|
741
|
+
* adds nothing to a transaction that has no list. Nothing is validated here: an
|
|
742
|
+
* entry with a wrong chain id, a stale nonce or a bad signature is SKIPPED by revm
|
|
743
|
+
* during execution, as EIP-7702 requires, never refused by the host.
|
|
744
|
+
*/
|
|
745
|
+
function authorizationsOf(tx: TransactionFields): {
|
|
746
|
+
authorizationList?: Authorization[];
|
|
747
|
+
} {
|
|
748
|
+
const list = tx.authorizationList;
|
|
749
|
+
if (list === undefined) return {};
|
|
750
|
+
return {
|
|
751
|
+
authorizationList: list.map(([chainId, address, nonce, yParity, r, s]) => ({
|
|
752
|
+
chainId: bytesToBigInt(chainId),
|
|
753
|
+
address,
|
|
754
|
+
nonce: bytesToBigInt(nonce),
|
|
755
|
+
yParity: Number(bytesToBigInt(yParity)),
|
|
756
|
+
r: setLengthLeft(r, 32),
|
|
757
|
+
s: setLengthLeft(s, 32),
|
|
758
|
+
})),
|
|
759
|
+
};
|
|
704
760
|
}
|
|
705
761
|
|
|
706
762
|
/**
|
package/src/state-manager.ts
CHANGED
|
@@ -503,6 +503,41 @@ export class OverlayStorageStateManager extends SimpleStateManager {
|
|
|
503
503
|
return taken;
|
|
504
504
|
}
|
|
505
505
|
|
|
506
|
+
/**
|
|
507
|
+
* REPLACE the open record with `changes`, which the caller hands over (it must
|
|
508
|
+
* not use it afterwards). INTERNAL: the node's `evm_revert` puts back the open
|
|
509
|
+
* record it held when the snapshot was taken, so the writes made since the head
|
|
510
|
+
* was mined are attributed to the next block exactly as they would have been.
|
|
511
|
+
* A no-op with recording off; refused with a checkpoint open, as
|
|
512
|
+
* {@link takeChangeSet} is.
|
|
513
|
+
*/
|
|
514
|
+
replaceChangeSet(changes: ChangeSet): void {
|
|
515
|
+
const levels = this.changeLevels;
|
|
516
|
+
if (levels === undefined) return;
|
|
517
|
+
if (levels.length !== 1)
|
|
518
|
+
throw new Error(
|
|
519
|
+
'webevm: the change set was replaced with a checkpoint open.',
|
|
520
|
+
);
|
|
521
|
+
levels[0] = changes;
|
|
522
|
+
}
|
|
523
|
+
|
|
524
|
+
/**
|
|
525
|
+
* EMPTY THE STATE: no account, no code, no storage. INTERNAL: the node's
|
|
526
|
+
* `evm_revert` runs it before `loadState` replays the snapshot, because a load
|
|
527
|
+
* WRITES the dump's entries over what is there and removes nothing, so an
|
|
528
|
+
* account created after the snapshot would otherwise survive the revert. The
|
|
529
|
+
* frames are emptied IN PLACE (the revm store reads the top frame live, ADR
|
|
530
|
+
* 0010) and the change set is left alone: the load that follows is a baseline
|
|
531
|
+
* and takes it. Refused with a checkpoint open.
|
|
532
|
+
*/
|
|
533
|
+
clearState(): void {
|
|
534
|
+
if (this.accountStack.length !== 1)
|
|
535
|
+
throw new Error('webevm: the state was cleared with a checkpoint open.');
|
|
536
|
+
this.accountStack[0].clear();
|
|
537
|
+
this.codeStack[0].clear();
|
|
538
|
+
this.storageOverlays = [emptyOverlay()];
|
|
539
|
+
}
|
|
540
|
+
|
|
506
541
|
/**
|
|
507
542
|
* Run a PURE READ (`eth_call`, `eth_estimateGas`, a state override) with
|
|
508
543
|
* recording suspended. Its levels are always reverted, so recording there is
|
package/src/types.ts
CHANGED
|
@@ -456,9 +456,42 @@ export interface EngineInfo {
|
|
|
456
456
|
readonly id: string;
|
|
457
457
|
}
|
|
458
458
|
|
|
459
|
+
/**
|
|
460
|
+
* The hardforks a node can run on: the ones whose gas rules the node implements
|
|
461
|
+
* end to end, on both engines. See {@link NodeOptions.hardfork}.
|
|
462
|
+
*/
|
|
463
|
+
export type NodeHardfork = 'cancun' | 'prague' | 'osaka';
|
|
464
|
+
|
|
459
465
|
export interface NodeOptions {
|
|
460
466
|
/** EIP-155 chain id. Default 31337 (anvil/hardhat-style local). */
|
|
461
467
|
chainId?: number;
|
|
468
|
+
/**
|
|
469
|
+
* The hardfork every block of this node runs under, its genesis included.
|
|
470
|
+
* Default `'osaka'`, the latest fork the node can cost.
|
|
471
|
+
*
|
|
472
|
+
* - `'osaka'` (DEFAULT): Prague's rules plus EIP-7825's per-transaction gas
|
|
473
|
+
* cap of 16,777,216 (a transaction asking for more is refused at submit, and
|
|
474
|
+
* `eth_estimateGas` never recommends more; `eth_call` is not held to it, as on
|
|
475
|
+
* geth), the `CLZ` opcode, the secp256r1 precompile and the repriced `MODEXP`.
|
|
476
|
+
* - `'prague'`: EIP-7702 authorization lists (type-4 transactions), EIP-7623's
|
|
477
|
+
* calldata floor (charged on receipts, refused below at submit, and the
|
|
478
|
+
* least `eth_estimateGas` recommends) and the BLS12-381 precompiles.
|
|
479
|
+
* - `'cancun'`: what every node ran before this option existed.
|
|
480
|
+
*
|
|
481
|
+
* WHAT NO FORK GETS HERE: block-level system operations. The node builds its
|
|
482
|
+
* own blocks and runs no system call at their start or end, so EIP-4788's
|
|
483
|
+
* beacon-root contract (Cancun) and EIP-2935's block-hash history contract
|
|
484
|
+
* (Prague) are never written, and EIP-7002 / EIP-7251 requests are never
|
|
485
|
+
* produced: a chain whose genesis carries none of those contracts behaves that
|
|
486
|
+
* way on a real client too. `BLOCKHASH` is unaffected: it reads the node's own
|
|
487
|
+
* blocks at every fork.
|
|
488
|
+
*
|
|
489
|
+
* The fork is part of the chain: a `dumpState` records it and `loadState`
|
|
490
|
+
* refuses a dump taken on a different one (a dump that predates the field was
|
|
491
|
+
* taken on Cancun), because a block's hash depends on which header fields its
|
|
492
|
+
* fork defines. Anything outside {@link NodeHardfork} throws at construction.
|
|
493
|
+
*/
|
|
494
|
+
hardfork?: NodeHardfork;
|
|
462
495
|
/**
|
|
463
496
|
* Whether the node computes a STATE ROOT. Default `false`. EVERY node runs on
|
|
464
497
|
* the same state (our `SimpleStateManager` subclass: plain Maps, no trie);
|
|
@@ -728,6 +761,13 @@ export interface ServedPort {
|
|
|
728
761
|
export interface SerializedState {
|
|
729
762
|
version: 1;
|
|
730
763
|
chainId: number;
|
|
764
|
+
/**
|
|
765
|
+
* The hardfork the chain ran under ({@link NodeOptions.hardfork}). Written by
|
|
766
|
+
* every dump; ABSENT on a dump that predates the field, which means `'cancun'`,
|
|
767
|
+
* the only fork a node could run then. `loadState` refuses a dump whose fork is
|
|
768
|
+
* not the loading node's.
|
|
769
|
+
*/
|
|
770
|
+
hardfork?: string;
|
|
731
771
|
/** The node's state, on every node: address -> hex-encoded account/code/storage.
|
|
732
772
|
* A `computeStateRoot` node's trie is not serialised; `loadState` rebuilds it. */
|
|
733
773
|
accounts: Record<string, string>; // addr -> rlp/hex account
|
package/src/worker-host.ts
CHANGED
|
@@ -28,7 +28,8 @@
|
|
|
28
28
|
* itself: it enumerates the keys of a reference node INSTANCE, and an optional
|
|
29
29
|
* field that instance does not carry is invisible to it.
|
|
30
30
|
*
|
|
31
|
-
* A MISUSE OF {@link WorkerHostOptions.createEngine}
|
|
31
|
+
* A MISUSE OF {@link WorkerHostOptions.createEngine} (or of
|
|
32
|
+
* {@link WorkerHostOptions.createNode}) IS A VALUE, NEVER A THROW,
|
|
32
33
|
* and that ordering is the whole of why: `expose()` registers comlink's message
|
|
33
34
|
* listener, so a module that throws BEFORE reaching it answers the main thread
|
|
34
35
|
* nothing at all and `createWorkerNode()` stays pending forever. The refusal is
|
|
@@ -80,8 +81,39 @@ export interface WorkerHostOptions {
|
|
|
80
81
|
* still cannot come from there (see `./worker-client.ts`'s refusal).
|
|
81
82
|
*/
|
|
82
83
|
createEngine?: EngineSupplier;
|
|
84
|
+
/**
|
|
85
|
+
* Create the NODE on this thread yourself, from the main thread's options.
|
|
86
|
+
* Omit it and the worker calls webevm's own `createNode` (what `worker-entry`
|
|
87
|
+
* does). When given, it is called ONCE PER `createNode()` with the options the
|
|
88
|
+
* main thread passed to `createWorkerNode()`, the engine from
|
|
89
|
+
* {@link createEngine} already merged in when that is set, and the node it
|
|
90
|
+
* resolves to is what the main thread drives, through the same single proxy:
|
|
91
|
+
*
|
|
92
|
+
* exposeNode({createNode: (options) => createDevNode({...options, accounts: 10})});
|
|
93
|
+
*
|
|
94
|
+
* WHY A FACTORY, and not a hook that wraps the node afterwards: a layer that
|
|
95
|
+
* funds accounts AT GENESIS (as `@webevm/devnode` does, like anvil and
|
|
96
|
+
* Hardhat) has to take part in CREATING the node, because genesis is decided
|
|
97
|
+
* before the node exists. And why an option here rather than a second worker
|
|
98
|
+
* host in that layer: the thread-crossing proxy must stay singular (see
|
|
99
|
+
* {@link nodeProxy}). `docs/adr/0017-dev-accounts-live-in-webevm-devnode-a-slimnode-decorator-funded-at-genesis.md`.
|
|
100
|
+
*
|
|
101
|
+
* The name is `createNode` because it IS a `createNode`: same options, same
|
|
102
|
+
* result, and the default is webevm's own function of that name. A factory
|
|
103
|
+
* that throws or rejects makes the main thread's `createWorkerNode()` reject
|
|
104
|
+
* with its message; one that is not a function is refused the way a bad
|
|
105
|
+
* {@link createEngine} is, as a value (both signals).
|
|
106
|
+
*/
|
|
107
|
+
createNode?: NodeFactory;
|
|
83
108
|
}
|
|
84
109
|
|
|
110
|
+
/**
|
|
111
|
+
* Creates the {@link SlimNode} for ONE `createNode()` call on the worker thread,
|
|
112
|
+
* from the main thread's options (the engine merged in). webevm's own
|
|
113
|
+
* `createNode` is one; a decorating layer passes its own.
|
|
114
|
+
*/
|
|
115
|
+
export type NodeFactory = (options: NodeOptions) => Promise<SlimNode>;
|
|
116
|
+
|
|
85
117
|
/**
|
|
86
118
|
* THE ONE `SlimNode` PROXY. Comlink cannot pass the node itself (its methods are
|
|
87
119
|
* functions and its subscription hands back another one), so this is the node's
|
|
@@ -134,7 +166,7 @@ function nodeProxy(node: SlimNode): SlimNode {
|
|
|
134
166
|
* of your own; this is the same object `worker-entry` exposes.
|
|
135
167
|
*/
|
|
136
168
|
export function createNodeWorkerApi(hostOptions: WorkerHostOptions = {}) {
|
|
137
|
-
const {createEngine} = hostOptions;
|
|
169
|
+
const {createEngine, createNode: nodeFactory} = hostOptions;
|
|
138
170
|
// THE REFUSAL IS A VALUE. Passing the ENGINE (or the promise of one) where its
|
|
139
171
|
// FACTORY belongs is the one plausible mistake at this seam, and it is refused
|
|
140
172
|
// with a real message rather than left to become a `TypeError` from inside
|
|
@@ -143,7 +175,14 @@ export function createNodeWorkerApi(hostOptions: WorkerHostOptions = {}) {
|
|
|
143
175
|
// the worker registers no message listener, and an awaited `createWorkerNode()`
|
|
144
176
|
// on the main thread never settles at all. Recorded here, said out loud here,
|
|
145
177
|
// and thrown where a caller can catch it.
|
|
146
|
-
|
|
178
|
+
//
|
|
179
|
+
// Both options are checked, and a module that gets BOTH wrong hears about both
|
|
180
|
+
// at once rather than fixing one only to meet the other.
|
|
181
|
+
const refusals = [
|
|
182
|
+
engineSupplierRefusal(createEngine),
|
|
183
|
+
nodeFactoryRefusal(nodeFactory),
|
|
184
|
+
].filter((r): r is string => r !== undefined);
|
|
185
|
+
const refusal = refusals.length > 0 ? refusals.join('\n') : undefined;
|
|
147
186
|
// THE EARLY SIGNAL, on the thread the mistake was written on and at the moment
|
|
148
187
|
// it was made: a developer with the worker console open reads it before anybody
|
|
149
188
|
// asks for a node. It is not the only one, precisely because a bundled app's
|
|
@@ -156,10 +195,14 @@ export function createNodeWorkerApi(hostOptions: WorkerHostOptions = {}) {
|
|
|
156
195
|
// fails with this text instead of hanging.
|
|
157
196
|
if (refusal !== undefined) throw new Error(refusal);
|
|
158
197
|
// The main thread's options pass through UNCHANGED; the engine, and only
|
|
159
|
-
// the engine, is this thread's.
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
198
|
+
// the engine, is this thread's. Then whichever factory makes the node:
|
|
199
|
+
// the consumer's when given (a throw or rejection from it crosses to the
|
|
200
|
+
// main thread as `createWorkerNode()`'s rejection), webevm's own
|
|
201
|
+
// otherwise.
|
|
202
|
+
const nodeOptions = createEngine
|
|
203
|
+
? {...options, engine: await createEngine()}
|
|
204
|
+
: options;
|
|
205
|
+
const node = await (nodeFactory ?? createNode)(nodeOptions);
|
|
163
206
|
return proxy(nodeProxy(node));
|
|
164
207
|
},
|
|
165
208
|
};
|
|
@@ -198,6 +241,35 @@ function engineSupplierRefusal(createEngine: unknown): string | undefined {
|
|
|
198
241
|
);
|
|
199
242
|
}
|
|
200
243
|
|
|
244
|
+
/**
|
|
245
|
+
* The message for a `createNode` factory that is not a function, or `undefined`
|
|
246
|
+
* when it is one (`undefined` itself being webevm's own `createNode`).
|
|
247
|
+
*
|
|
248
|
+
* The THENABLE case names itself for the same reason it does for `createEngine`:
|
|
249
|
+
* `createNode: createDevNode({...})` (no arrow) built a node at module scope and
|
|
250
|
+
* passed the promise of it, one arrow away from right, and a node built there
|
|
251
|
+
* would not even have the main thread's options.
|
|
252
|
+
*/
|
|
253
|
+
function nodeFactoryRefusal(nodeFactory: unknown): string | undefined {
|
|
254
|
+
if (nodeFactory === undefined || typeof nodeFactory === 'function') {
|
|
255
|
+
return undefined;
|
|
256
|
+
}
|
|
257
|
+
const why =
|
|
258
|
+
"It is called ONCE PER createNode(), with the main thread's options (the engine merged in when `createEngine` is set), and the node it resolves to is the one the main thread drives.";
|
|
259
|
+
if (typeof (nodeFactory as {then?: unknown} | null)?.then === 'function') {
|
|
260
|
+
return (
|
|
261
|
+
'webevm/worker-host: `createNode` must be a FUNCTION that creates the node from the options it is given, and it was given a PROMISE of one: the factory was CALLED here instead of being passed. ' +
|
|
262
|
+
'Write `{createNode: (options) => myCreateNode(options)}`, not `{createNode: myCreateNode(...)}`. ' +
|
|
263
|
+
why
|
|
264
|
+
);
|
|
265
|
+
}
|
|
266
|
+
return (
|
|
267
|
+
`webevm/worker-host: \`createNode\` must be a FUNCTION that creates the node from the options it is given (received ${describe(nodeFactory)}). ` +
|
|
268
|
+
"Pass `{createNode: (options) => myCreateNode(options)}`, or omit it for webevm's own createNode. " +
|
|
269
|
+
why
|
|
270
|
+
);
|
|
271
|
+
}
|
|
272
|
+
|
|
201
273
|
/** What was passed, in one word a reader can match against their own code. */
|
|
202
274
|
function describe(value: unknown): string {
|
|
203
275
|
if (value === null) return 'null';
|