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 +52 -0
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/node.d.ts.map +1 -1
- package/dist/node.js +242 -13
- package/dist/node.js.map +1 -1
- package/dist/types.d.ts +47 -2
- package/dist/types.d.ts.map +1 -1
- package/dist/worker-client.d.ts.map +1 -1
- package/dist/worker-client.js +19 -1
- package/dist/worker-client.js.map +1 -1
- package/dist/worker-host.d.ts.map +1 -1
- package/dist/worker-host.js +5 -0
- package/dist/worker-host.js.map +1 -1
- package/package.json +2 -1
- package/src/index.ts +1 -0
- package/src/node.ts +244 -13
- package/src/types.ts +48 -2
- package/src/worker-client.ts +22 -1
- package/src/worker-host.ts +5 -0
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
|
package/dist/index.d.ts.map
CHANGED
|
@@ -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;
|
|
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"}
|
package/dist/node.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"
|
|
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
|
-
|
|
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
|
|
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:
|
|
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
|
-
|
|
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
|
}
|