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/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` — Berlin through Cancun today), and refuses the rest
52
- * BY NAME at construction (`REVM_REFUSED_HARDFORKS`): Prague and Osaka, because
53
- * `./intrinsic-gas.ts` does not compute the EIP-7623 calldata floor that revm
54
- * enforces. See ADR 0008.
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 {bigIntToBytes, equalsBytes, generateAddress} from '@ethereumjs/util';
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 {BlockEnv, ExecuteOptions, Outcome, Revm} from 'revm-wasm';
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 today and nothing here can change that, so this table is
89
- * a GUARD rather than a feature: if the node's hardfork ever moves, an engine
90
- * that silently kept running Cancun rules would charge different gas from the
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 fail (a). Berlin, London and Paris once failed (b) — both
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..Cancun only: it hardcodes EIP-2028's 16 gas per
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. From Prague on, revm ENFORCES rules
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 — and viem uses that number
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 and in the read budget here, then prove it against the
170
- * engine and move the entry to {@link REVM_SPEC_BY_HARDFORK}. Note that the
171
- * EIP-7623 floor is not a TERM of the intrinsic-gas formula but a floor on the
172
- * transaction's total, so unlike the EIP-3860 fork gate it cannot be threaded
173
- * through ./intrinsic-gas.ts alone — both callers have to learn about it. The
174
- * measurements behind each line are in
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
- prague:
187
- `revm enforces the EIP-7623 calldata floor (a transaction pays at least ` +
188
- `21000 + 10 gas per calldata token, tokens being 1 per zero byte and 4 per ` +
189
- `non-zero byte) and this node's shared intrinsic-gas arithmetic ` +
190
- `(src/intrinsic-gas.ts) computes only the pre-Prague formula, so ` +
191
- `eth_estimateGas would return a gas limit revm itself rejects with ` +
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 while the node is
247
- // pinned to Cancun, which is the point — it fires the day that moves,
248
- // rather than letting `eth_estimateGas` return a number this engine would
249
- // then reject.
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) and EIP-7702's `authorizationList` (post-Cancun, so
499
- // unreachable while this engine admits Berlin..Cancun). The type-3 receipt
500
- // is incomplete on BOTH engines — `blobGasUsed` / `blobGasPrice` are
501
- // absent from the seam's result altogether — and that limitation is
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 `disableBalanceCheck` each
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
  /**
@@ -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
@@ -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} IS A VALUE, NEVER A THROW,
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
- const refusal = engineSupplierRefusal(createEngine);
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
- const node = await createNode(
161
- createEngine ? {...options, engine: await createEngine()} : options,
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';