webevm 0.5.0 → 0.7.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 CHANGED
@@ -48,6 +48,8 @@ npm install comlink
48
48
  installed automatically; `comlink` is an optional peer used only by the Worker
49
49
  entry/client.)
50
50
 
51
+ (`@eip-1193/over-port` is a direct dependency too: about 6 kB, with no runtime dependency of its own, and it is what `node.serveOn(port)` speaks. A consumer on the other end of that port installs it as well, for `providerOverPort`.)
52
+
51
53
  ## Usage (main thread)
52
54
 
53
55
  ```ts
@@ -134,6 +136,37 @@ is synchronous at module scope: the factory defers the await into `createNode()`
134
136
  which is one of the reasons `createEngine` is a function. If you must await
135
137
  something, do it INSIDE `createEngine`.
136
138
 
139
+ ### Serving the node to another worker (worker to worker)
140
+
141
+ A consumer that runs in ANOTHER worker (an indexer, say) can use a worker-hosted node as its EIP-1193 provider directly, without the page relaying its requests. The page makes a `MessageChannel`, hands one end to the node with `node.serveOn(port)` (the client TRANSFERS it into the node's worker), and hands the other end to the consumer, which turns it back into a provider with [`@eip-1193/over-port`](https://www.npmjs.com/package/@eip-1193/over-port)'s `providerOverPort`:
142
+
143
+ ```ts
144
+ // page
145
+ import {createWorkerNode} from 'webevm/worker-client';
146
+
147
+ const node = await createWorkerNode({worker: nodeWorker, chainId: 31337});
148
+ const {port1, port2} = new MessageChannel();
149
+ const served = await node.serveOn(port1);
150
+ indexerWorker.postMessage({provider: port2}, [port2]);
151
+ // later, to stop answering on that port: await served.close();
152
+
153
+ // indexer worker
154
+ import {providerOverPort} from '@eip-1193/over-port';
155
+
156
+ self.addEventListener('message', (event) => {
157
+ if (event.data?.provider) {
158
+ const provider = providerOverPort(event.data.provider);
159
+ // provider.request({method: 'eth_blockNumber'}) goes straight to the node's worker
160
+ }
161
+ });
162
+ ```
163
+
164
+ Only `request` crosses; `onNewHead`, `mine` and the other controls stay with whoever holds `node`. An error the node raises arrives with its `code`, `message` and `data` (an unsupported method is still `-32601`). Call `serveOn` once per consumer: each call serves one port, each returns its own `close()`, and `node.dispose()` stops them all. Every request served this way queues on the node's one-request-at-a-time serialisation point like any other.
165
+
166
+ **It is the same call on a main-thread node.** `createNode()`'s node has `serveOn(port)` too and serves the port in place, so the two kinds of node stay interchangeable. (A main-thread node needs nothing from this package for it anyway: `serveProvider(node, port)` from `@eip-1193/over-port` works on it directly, since a node is an object with a `request`.)
167
+
168
+ **No page code relays the requests, but on Safari the page's thread still carries them.** WebKit routes `MessagePort` traffic between two workers through the main thread inside the engine, so a page that holds its thread busy stalls the consumer's requests until it yields (measured: zero answers during a one-second busy loop, all of them the moment it ends). Chromium carries them without the page's thread. Either way nothing in your page's JavaScript touches them.
169
+
137
170
  ## RPC surface (the contract)
138
171
 
139
172
  This is a **curated, execution-only** method set — NOT a full EIP-1193 provider.
@@ -183,6 +216,25 @@ method-not-found (`-32601`) — it never fakes a result.
183
216
  checkpoint that is reverted, and reset the EVM journal's warm/access tracking +
184
217
  the EIP-2200 original-storage cache per call (so a repeated warm-SSTORE estimate
185
218
  doesn't under-report and cause out-of-gas reverts).
219
+ - **One request at a time.** A node serves `request` / `mine` / `dumpState` /
220
+ `loadState` / `getStateRoot` through a single queue, so a request is always
221
+ answered against a SETTLED state. This is not politeness: reads and transactions
222
+ share one checkpoint stack, `commit()` merges the top level down and `revert()`
223
+ discards it, and neither knows who opened it — so two overlapping executions used
224
+ to destroy each other's writes while BOTH reported success (a lost nonce, state
225
+ torn at a message-frame boundary, an `eth_call` committing its own `SSTORE`, two
226
+ transactions given the same block number). Fire as many requests as you like from
227
+ as many pollers as you like; they queue. What it costs is latency, not
228
+ correctness: a cheap read issued during a 209 ms `eth_estimateGas` search waits
229
+ for it (0.1 ms → 208 ms, measured), which is why a game loop should not estimate
230
+ every frame. One consumer-visible rule follows, and it applies to exactly one
231
+ place: a `persistence.save()` hook must not await a call back into the node,
232
+ because it runs while the queue is held so that its dump is a real snapshot and
233
+ so that your request does not resolve before the write is durable. Everything
234
+ else is unaffected — an `onNewHead` subscriber MAY call back (its request queues
235
+ behind the block it was told about), and a request from anywhere else during a
236
+ save simply waits its turn.
237
+ [ADR 0012](docs/adr/0012-one-request-at-a-time-the-node-serialises-its-whole-public-surface.md)
186
238
  - **`eth_estimateGas` returns a gas LIMIT, not the gas consumed.** It used to
187
239
  report `executionGasUsed` + intrinsic gas, which is exact and is the wrong
188
240
  question: under EIP-150's 63/64 rule a `CALL`/`CREATE` is forwarded at most
package/dist/index.d.ts CHANGED
@@ -7,6 +7,6 @@
7
7
  */
8
8
  export { createNode } from './node.js';
9
9
  export { createIndexedDBPersistence, createMemoryPersistence, } from './persistence.js';
10
- export type { SlimNode, NodeOptions, MiningConfig, StateMode, SenderMode, Engine, EngineContext, EngineInfo, ReadCallRequest, ReadCallResult, TransactionRequest, TransactionResult, TransactionLog, GenesisAccount, BlockEnv, PersistenceAdapter, RequestArguments, SerializedState, } from './types.js';
10
+ export type { SlimNode, ServedPort, NodeOptions, MiningConfig, StateMode, SenderMode, Engine, EngineContext, EngineInfo, ReadCallRequest, ReadCallResult, TransactionRequest, TransactionResult, TransactionLog, GenesisAccount, BlockEnv, PersistenceAdapter, RequestArguments, SerializedState, } from './types.js';
11
11
  export { RpcError } from './types.js';
12
12
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAC,UAAU,EAAC,MAAM,WAAW,CAAC;AACrC,OAAO,EACN,0BAA0B,EAC1B,uBAAuB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACX,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,SAAS,EACT,UAAU,EAIV,MAAM,EACN,aAAa,EACb,UAAU,EACV,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,QAAQ,EACR,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAC,UAAU,EAAC,MAAM,WAAW,CAAC;AACrC,OAAO,EACN,0BAA0B,EAC1B,uBAAuB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACX,QAAQ,EACR,UAAU,EACV,WAAW,EACX,YAAY,EACZ,SAAS,EACT,UAAU,EAIV,MAAM,EACN,aAAa,EACb,UAAU,EACV,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,QAAQ,EACR,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC"}
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAC,UAAU,EAAC,MAAM,WAAW,CAAC;AACrC,OAAO,EACN,0BAA0B,EAC1B,uBAAuB,GACvB,MAAM,kBAAkB,CAAC;AAwB1B,OAAO,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC;AACpC,6EAA6E;AAC7E,iFAAiF;AACjF,kDAAkD;AAClD,+EAA+E;AAC/E,yCAAyC;AACzC,2DAA2D;AAC3D,iEAAiE;AACjE,kFAAkF;AAClF,qCAAqC;AACrC,mDAAmD"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAC,UAAU,EAAC,MAAM,WAAW,CAAC;AACrC,OAAO,EACN,0BAA0B,EAC1B,uBAAuB,GACvB,MAAM,kBAAkB,CAAC;AAyB1B,OAAO,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC;AACpC,6EAA6E;AAC7E,iFAAiF;AACjF,kDAAkD;AAClD,+EAA+E;AAC/E,yCAAyC;AACzC,2DAA2D;AAC3D,iEAAiE;AACjE,kFAAkF;AAClF,qCAAqC;AACrC,mDAAmD"}
@@ -1 +1 @@
1
- {"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AA8DA,OAAO,EAEN,KAAK,WAAW,EAIhB,KAAK,QAAQ,EAOb,MAAM,YAAY,CAAC;AAsLpB,wBAAsB,UAAU,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAqqD7E"}
1
+ {"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AA+EA,OAAO,EAEN,KAAK,WAAW,EAIhB,KAAK,QAAQ,EAOb,MAAM,YAAY,CAAC;AAiMpB,wBAAsB,UAAU,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAg3D7E"}
package/dist/node.js CHANGED
@@ -21,6 +21,17 @@
21
21
  *
22
22
  * Transport-agnostic: just `request()` (async) + mine/dump/load. Knows nothing
23
23
  * about Workers — see ./worker-entry.ts for the optional comlink wrapper.
24
+ *
25
+ * ONE THING AT A TIME. Every public entry point on the returned node —
26
+ * `request`, `mine`, `dumpState`, `loadState`, `getStateRoot` — runs through
27
+ * {@link SlimNode}'s serialisation point, so this node executes exactly one
28
+ * request at a time no matter how many are in flight. It is not an optimisation
29
+ * and it is not politeness: the node's state manager is a STACK of checkpoints
30
+ * shared by reads and transactions alike, `commit()` merges downward and
31
+ * `revert()` discards without either knowing who opened the level it acts on, so
32
+ * two overlapping executions destroy each other's writes. See the comment at
33
+ * `serialise` below and
34
+ * `docs/adr/0012-one-request-at-a-time-the-node-serialises-its-whole-public-surface.md`.
24
35
  */
25
36
  import { createVM } from '@ethereumjs/vm';
26
37
  import { MerkleStateManager } from '@ethereumjs/statemanager';
@@ -41,6 +52,12 @@ import { connectEngine, createEthereumjsEngine } from './engine.js';
41
52
  // Sender derivation stays the node's on every engine; what an engine may lend it
42
53
  // is the CURVE step. See ./sender-recovery.ts.
43
54
  import { recoverSender } from './sender-recovery.js';
55
+ // `serveOn(port)`: EIP-1193 `request` over a MessagePort, in the wire format the
56
+ // consumer's `providerOverPort` speaks. Imported HERE, the one place the node's
57
+ // public surface is built, so every node (main-thread or worker-hosted) serves a
58
+ // port the same way; see `serveOn` at the bottom of this file for why this is a
59
+ // dependency of the core rather than of `webevm/worker-host` alone.
60
+ import { serveProvider } from '@eip-1193/over-port';
44
61
  // The engine reports EXECUTION gas for a read and the node adds intrinsic gas on top;
45
62
  // an engine that charges intrinsic gas itself (revm) subtracts the SAME formula,
46
63
  // so it has exactly one home. See ./intrinsic-gas.ts.
@@ -185,6 +202,16 @@ function upfrontCost(tx) {
185
202
  : anyTx.gasPrice;
186
203
  return (anyTx.value ?? 0n) + tx.gasLimit * perGas;
187
204
  }
205
+ /**
206
+ * The no-op the node's serialisation chain passes in BOTH handler positions
207
+ * (`run.then(swallow, swallow)`), which is what keeps the chain alive across a
208
+ * FAILED request: `tail` must always be a promise that FULFILS, since a rejection
209
+ * left on it would reject every request queued behind the one that failed and turn
210
+ * one bad transaction into a dead node. It takes no arguments because it uses
211
+ * neither the value nor the reason; both are the caller's, and both have already
212
+ * been delivered to whoever awaited that request.
213
+ */
214
+ function swallow() { }
188
215
  export async function createNode(options = {}) {
189
216
  const chainId = options.chainId ?? 31337;
190
217
  const stateMode = options.stateMode ?? 'none';
@@ -209,6 +236,115 @@ export async function createNode(options = {}) {
209
236
  const sm = stateMode === 'trie'
210
237
  ? new MerkleStateManager()
211
238
  : new OverlayStorageStateManager();
239
+ /**
240
+ * THE SERIALISATION POINT: the tail of a promise chain that every public entry
241
+ * point queues its work onto, so this node runs exactly ONE piece of work at a
242
+ * time. It is declared HERE, beside `sm`, because the thing it protects is that
243
+ * object and nothing else.
244
+ *
245
+ * ## What was shared, and why it corrupts
246
+ *
247
+ * A state manager is a STACK of checkpoint levels. `checkpoint()` pushes a
248
+ * level, a write lands in the TOP one, `commit()` merges the top level into the
249
+ * one below and pops it, `revert()` pops it and throws it away. Neither
250
+ * `commit` nor `revert` knows WHO opened the level it is acting on — there is no
251
+ * handle, no owner and no identity — so the stack is only meaningful while a
252
+ * single execution owns it.
253
+ *
254
+ * Both halves of the node open levels on THIS one stack. `engine.transact`
255
+ * (`runTx`) checkpoints, executes and commits; the default engine's
256
+ * `engine.call` checkpoints and reverts, which is what makes an `eth_call` PURE
257
+ * and is a requirement of that EVM, not an option (see ./engine.ts). Both are
258
+ * `async` and `@ethereumjs/evm` yields to the microtask queue while it
259
+ * interprets, so before this existed a read arriving mid-transaction produced:
260
+ *
261
+ * ```
262
+ * tx checkpoint [base, tx]
263
+ * call checkpoint [base, tx, call] <- the read arrives mid-execution
264
+ * tx write -> lands in the TOP level, which is the CALL's
265
+ * tx commit -> merges that level down and pops it
266
+ * call revert -> pops the merged level: the transaction's write is GONE
267
+ * ```
268
+ *
269
+ * Measured through this node's own RPC surface: a whole transaction lost (a
270
+ * plain transfer loses the sender's NONCE, so every later transaction from that
271
+ * account is refused as "nonce too high"), state TORN at a message-frame
272
+ * boundary (the EVM checkpoints per frame, so the read's level can land between
273
+ * an inner frame's checkpoint and its commit, leaving a state no execution could
274
+ * produce), an `eth_call`'s OWN write committed rather than reverted, and —
275
+ * because this is not about reads — two overlapping TRANSACTIONS losing a write
276
+ * the same way, both reporting success and both holding a receipt.
277
+ *
278
+ * ## Why the lock is HERE rather than around `engine.call`
279
+ *
280
+ * Because write-versus-write interleaves too, so a lock inside the read path
281
+ * would fix half of it. And because it must be INSIDE the node: the Worker
282
+ * transport forwards straight to `node.request` and comlink delivers
283
+ * concurrently, so a lock in a transport protects only consumers who use that
284
+ * transport. It is per NODE, which is per STATE MANAGER by construction —
285
+ * `createNode` builds its own `sm` and takes no state manager option, and an
286
+ * injected engine binds to the first node it is given to and refuses a second.
287
+ *
288
+ * ## Why EVERY request and not only the executing ones
289
+ *
290
+ * A read that never touches the EVM never checkpoints and so can never corrupt
291
+ * anything — but it reads the live stack INCLUDING uncommitted levels, so it
292
+ * reports a state no block contains. Measured, with a single transfer in flight:
293
+ * `eth_getBalance` saw the sender DEBITED from tick 5 and
294
+ * `eth_getTransactionCount` saw the nonce ADVANCED from tick 6, while
295
+ * `eth_blockNumber` still said 0 — and that reading is exactly what an
296
+ * overlapping `eth_call` could then destroy. The node's own block/receipt maps
297
+ * are written per-transaction inside the mining loop too, so a mid-execution
298
+ * `eth_getTransactionReceipt` can name a `blockHash` no lookup resolves yet.
299
+ * The cost is real and is stated in the ADR: a cheap read issued during a
300
+ * 209 ms `eth_estimateGas` search used to answer in 0.1 ms and now waits for it.
301
+ * A per-method exemption list was rejected because it is a promise that has to
302
+ * be re-proven every time a method is added, by somebody who will not know that
303
+ * is what they are doing.
304
+ *
305
+ * ## The shape
306
+ *
307
+ * `tail` is ALWAYS a promise that fulfils — the assignment below swallows both
308
+ * outcomes — so a failing request cannot poison the chain and cannot stop the
309
+ * queue behind it. Nothing inside the node re-enters a serialised entry point
310
+ * (the internal `request`, `mineBlock`, `dumpState`, `loadState` and
311
+ * `currentStateRoot` are all called directly, and only the returned object's
312
+ * members are wrapped), so a single chain cannot deadlock against itself.
313
+ *
314
+ * ## The one way a CONSUMER can deadlock it, and why it is NOT detected
315
+ *
316
+ * Control leaves the node twice while the chain is held, and both times into a
317
+ * consumer's code. They are not the same risk:
318
+ *
319
+ * - an `onNewHead` callback is emitted WITHOUT being awaited, so a request it
320
+ * issues queues behind the current one and runs when the chain drains. That
321
+ * is the game-loop pattern (refetch on every head) and it is ALLOWED.
322
+ * - a `persistence.save()` hook IS awaited — so that the dump it is handed is a
323
+ * snapshot of a settled state and so that the request does not resolve before
324
+ * the write is durable — which means a hook that AWAITS a call back into the
325
+ * node waits for itself forever. That rule is documented, on
326
+ * `PersistenceAdapter.save` where an adapter is written, and enforced nowhere.
327
+ *
328
+ * IT IS DELIBERATELY NOT ENFORCED, and this is the interesting part. The obvious
329
+ * guard — a flag raised around the awaited hook, with `serialise` refusing while
330
+ * it is set — WAS BUILT AND REMOVED, because it cannot work. The flag is held
331
+ * across the hook's I/O, the `await` yields the event loop for that whole
332
+ * duration, and JavaScript offers no way (no `AsyncLocalStorage` in a browser) to
333
+ * tell a request issued by the hook's own stack from one issued by anybody else
334
+ * in that window. Measured on a 20 ms save: a plain `setInterval` poller that had
335
+ * never heard of persistence got four rejections, each telling it that IT had
336
+ * caused a deadlock. A false refusal with a confident wrong diagnosis is worse
337
+ * than the hang it replaces, and it fires for every consumer who has persistence
338
+ * and a poller, which is this package's main use. So the honest arrangement is
339
+ * the one below: everyone queues, and the one pathological hook is a documented
340
+ * rule rather than a guess dressed as a check. See ADR 0012.
341
+ */
342
+ let tail = Promise.resolve();
343
+ function serialise(job) {
344
+ const run = tail.then(job);
345
+ tail = run.then(swallow, swallow);
346
+ return run;
347
+ }
212
348
  // Touched-account set for the trie-mode dump (storage is read back via the
213
349
  // trie's own dumpStorage). We record the addresses each tx touches at the NODE
214
350
  // level (sender / to / created) rather than monkeypatching the state manager —
@@ -384,12 +520,17 @@ export async function createNode(options = {}) {
384
520
  const pending = [];
385
521
  // newHeads subscribers.
386
522
  const headSubs = new Set();
523
+ // Ports `serveOn` is serving, so `dispose` can stop them all.
524
+ const servedPorts = new Set();
525
+ // THE INTERVAL TIMER IS ARMED AT THE BOTTOM OF THIS FUNCTION, not here, at the
526
+ // `miningConfig.type === 'interval'` block just above the `return`. The reason
527
+ // is ordering: a timer armed at this point can fire while the
528
+ // REST OF CONSTRUCTION is still running, and the construction-time
529
+ // `loadState(saved)` that the persistence option performs is deliberately not
530
+ // serialised (nothing can reach the node yet, because it has not been returned).
531
+ // Those two together are the one interleaving the serialisation point does not
532
+ // cover, so the timer starts after the node is fully built instead.
387
533
  let intervalTimer;
388
- if (miningConfig.type === 'interval') {
389
- intervalTimer = setInterval(() => {
390
- void mineBlock();
391
- }, miningConfig.intervalMs);
392
- }
393
534
  /**
394
535
  * THE BLOCK'S LOGS BLOOM: the OR of its receipts' own blooms, which is what a
395
536
  * block bloom IS. Derived here rather than carried out of the mining loop so
@@ -1690,12 +1831,48 @@ export async function createNode(options = {}) {
1690
1831
  if (saved && saved.chainId === chainId)
1691
1832
  await loadState(saved);
1692
1833
  }
1834
+ // The dump is taken inside the chain, so it is a snapshot of a settled state,
1835
+ // and the hook is AWAITED inside it too, so a request does not resolve before
1836
+ // its state is durable (`test/persistence-reload.spec.ts` reloads the page on
1837
+ // the strength of that). A request arriving while the hook runs simply queues.
1693
1838
  async function persistIfNeeded() {
1694
- if (options.persistence)
1695
- await options.persistence.save(await dumpState());
1839
+ if (!options.persistence)
1840
+ return;
1841
+ await options.persistence.save(await dumpState());
1842
+ }
1843
+ /**
1844
+ * ARM INTERVAL MINING, once the node is otherwise built.
1845
+ *
1846
+ * COALESCED, which a plain `setInterval` is not. The timer keeps firing while
1847
+ * the chain is busy, so without this a period shorter than the work in flight
1848
+ * (say `intervalMs: 50` against the 209 ms `eth_estimateGas` search ADR 0012
1849
+ * measures) appends a mine per tick and they drain afterwards as a burst of
1850
+ * empty blocks — and if mining outruns the period the queue never stops growing.
1851
+ * At most ONE tick is ever waiting: the flag is cleared when the job STARTS, so
1852
+ * a tick that arrives during a mine still schedules the next one.
1853
+ *
1854
+ * It goes THROUGH the serialisation point like every other way a block gets
1855
+ * mined, because a timer is a concurrency source the consumer never sees: it
1856
+ * fires whenever the event loop reaches it, which before this meant in the
1857
+ * middle of whatever `eth_call` happened to be executing.
1858
+ */
1859
+ let minePending = false;
1860
+ if (miningConfig.type === 'interval') {
1861
+ intervalTimer = setInterval(() => {
1862
+ if (minePending)
1863
+ return;
1864
+ minePending = true;
1865
+ // The flag is cleared as the job STARTS rather than when it finishes, so a
1866
+ // tick arriving during a mine still schedules the next one, and a mine that
1867
+ // THROWS cannot strand the flag and silently stop interval mining.
1868
+ void serialise(() => {
1869
+ minePending = false;
1870
+ return mineBlock();
1871
+ });
1872
+ }, miningConfig.intervalMs);
1696
1873
  }
1697
1874
  // wrap mine() to persist
1698
- async function mine() {
1875
+ async function mineAndPersist() {
1699
1876
  const r = await mineBlock();
1700
1877
  await persistIfNeeded();
1701
1878
  return r;
@@ -1713,11 +1890,31 @@ export async function createNode(options = {}) {
1713
1890
  }
1714
1891
  return out;
1715
1892
  }
1893
+ // THE PUBLIC SURFACE, AND THE ONLY PLACE THE LOCK IS TAKEN. Everything above
1894
+ // this line calls the node's internals DIRECTLY and never through here, which is
1895
+ // what makes one promise chain safe: `persistingRequest` reaches `baseRequest`,
1896
+ // `mineAndPersist` reaches `mineBlock` and `persistIfNeeded` reaches `dumpState`,
1897
+ // none of them re-entering a wrapper. Add an entry point below and it must be
1898
+ // serialised too; call one of these wrappers from inside the node and it will
1899
+ // wait for itself forever.
1900
+ //
1901
+ // `dispose` is deliberately NOT serialised: it stops the interval timer and drops
1902
+ // the newHeads subscribers, touches no state, and would be useless at the back of
1903
+ // a queue it is meant to wind down. Note what that does NOT mean: it does not
1904
+ // CANCEL anything already queued. Work accepted before `dispose` still runs to
1905
+ // completion, including a `persistence.save()`, and only the timer stops adding
1906
+ // more. A caller that needs the node quiet should stop issuing requests and await
1907
+ // the ones it holds.
1908
+ //
1909
+ // `serveOn` is not serialised either, for the reason `dispose` is not: it
1910
+ // touches no state. It only relays `request`, which IS serialised, so a request
1911
+ // arriving over a served port queues exactly like one made directly.
1912
+ const publicRequest = (args) => serialise(() => persistingRequest(args));
1716
1913
  return {
1717
- request: persistingRequest,
1718
- mine,
1719
- dumpState,
1720
- loadState,
1914
+ request: publicRequest,
1915
+ mine: () => serialise(mineAndPersist),
1916
+ dumpState: () => serialise(dumpState),
1917
+ loadState: (state) => serialise(() => loadState(state)),
1721
1918
  stateMode,
1722
1919
  senderMode,
1723
1920
  // Identity only: the engine object itself stays internal, so the reading is a
@@ -1727,16 +1924,48 @@ export async function createNode(options = {}) {
1727
1924
  if (stateMode !== 'trie') {
1728
1925
  throw new RpcError(-32004, "no state root in 'none' mode — create the node with stateMode:'trie' for a real Merkle-Patricia root");
1729
1926
  }
1730
- return currentStateRoot();
1927
+ // SERIALISED like the rest, because this one READS BY WRITING: in trie mode
1928
+ // `currentStateRoot` flushes the state manager's cache into the trie, so a
1929
+ // root taken mid-transaction would both report an uncommitted state and
1930
+ // push it into the trie on the way.
1931
+ return serialise(currentStateRoot);
1731
1932
  },
1732
1933
  onNewHead(cb) {
1733
1934
  headSubs.add(cb);
1734
1935
  return () => headSubs.delete(cb);
1735
1936
  },
1937
+ // SERVE `request` ON A HANDED PORT, via `@eip-1193/over-port`, so a consumer
1938
+ // on another thread uses this node through `providerOverPort(otherEnd)`.
1939
+ //
1940
+ // IT LIVES ON THE CORE NODE, NOT ONLY IN `webevm/worker-host`, so the two
1941
+ // kinds of node stay interchangeable: `SlimNode` carries it, the one worker
1942
+ // proxy forwards it (its `Required<SlimNode>` annotation demands that), and a
1943
+ // main-thread node answers the same call in place. The price is that the
1944
+ // core imports `@eip-1193/over-port` (about 6 kB of unminified JS, no
1945
+ // runtime dependency of its own), which `webevm/worker-client` and
1946
+ // `webevm/revm` still do not: the client only TRANSFERS the port, and
1947
+ // the consumer brings its own `providerOverPort`.
1948
+ //
1949
+ // Only `request` is served, bound to the SERIALISED entry point above.
1950
+ async serveOn(port) {
1951
+ const server = serveProvider({ request: publicRequest }, port);
1952
+ servedPorts.add(server);
1953
+ return {
1954
+ async close() {
1955
+ server.close();
1956
+ servedPorts.delete(server);
1957
+ },
1958
+ };
1959
+ },
1736
1960
  async dispose() {
1737
1961
  if (intervalTimer)
1738
1962
  clearInterval(intervalTimer);
1739
1963
  headSubs.clear();
1964
+ // A disposed node stops answering on every port it was serving, so a
1965
+ // consumer is not left talking to a node its owner has let go of.
1966
+ for (const server of servedPorts)
1967
+ server.close();
1968
+ servedPorts.clear();
1740
1969
  },
1741
1970
  };
1742
1971
  }