@webevm/devnode 0.0.0-stage → 0.1.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/LICENSE +21 -0
- package/README.md +221 -2
- package/dist/accounts.d.ts +82 -0
- package/dist/accounts.d.ts.map +1 -0
- package/dist/accounts.js +129 -0
- package/dist/accounts.js.map +1 -0
- package/dist/allocs.d.ts +26 -0
- package/dist/allocs.d.ts.map +1 -0
- package/dist/allocs.js +99 -0
- package/dist/allocs.js.map +1 -0
- package/dist/dev-node.d.ts +63 -0
- package/dist/dev-node.d.ts.map +1 -0
- package/dist/dev-node.js +166 -0
- package/dist/dev-node.js.map +1 -0
- package/dist/eip712.d.ts +23 -0
- package/dist/eip712.d.ts.map +1 -0
- package/dist/eip712.js +333 -0
- package/dist/eip712.js.map +1 -0
- package/dist/impersonation.d.ts +20 -0
- package/dist/impersonation.d.ts.map +1 -0
- package/dist/impersonation.js +95 -0
- package/dist/impersonation.js.map +1 -0
- package/dist/index.d.ts +11 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +8 -0
- package/dist/index.js.map +1 -0
- package/dist/send.d.ts +20 -0
- package/dist/send.d.ts.map +1 -0
- package/dist/send.js +385 -0
- package/dist/send.js.map +1 -0
- package/dist/sign.d.ts +14 -0
- package/dist/sign.d.ts.map +1 -0
- package/dist/sign.js +155 -0
- package/dist/sign.js.map +1 -0
- package/dist/worker-host.d.ts +87 -0
- package/dist/worker-host.d.ts.map +1 -0
- package/dist/worker-host.js +112 -0
- package/dist/worker-host.js.map +1 -0
- package/package.json +79 -3
- package/src/accounts.ts +218 -0
- package/src/allocs.ts +134 -0
- package/src/dev-node.ts +220 -0
- package/src/eip712.ts +390 -0
- package/src/impersonation.ts +119 -0
- package/src/index.ts +25 -0
- package/src/send.ts +469 -0
- package/src/sign.ts +199 -0
- package/src/worker-host.ts +151 -0
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* worker-host.ts: `@webevm/devnode/worker-host`, the dev node INSIDE a worker.
|
|
3
|
+
* The whole of a consumer's worker module:
|
|
4
|
+
*
|
|
5
|
+
* // dev-worker.ts
|
|
6
|
+
* import {exposeDevNode} from '@webevm/devnode/worker-host';
|
|
7
|
+
* exposeDevNode({accounts: {mnemonic}, impersonation: true});
|
|
8
|
+
*
|
|
9
|
+
* and the main thread drives it with webevm's own client, unchanged:
|
|
10
|
+
* `createWorkerNode({worker, chainId, ...})` from `webevm/worker-client`.
|
|
11
|
+
*
|
|
12
|
+
* NOT A SECOND WORKER HOST. This module ships no proxy and no client: it hands
|
|
13
|
+
* webevm's `exposeNode` a NODE FACTORY (`options => createDevNode({...options,
|
|
14
|
+
* ...devConfig})`), so the node crosses the thread boundary through the ONE
|
|
15
|
+
* `Required<SlimNode>` proxy in `webevm/worker-host` (CONTEXT.md, *worker host*),
|
|
16
|
+
* and an `RpcError` the layer raises crosses with its `code` and `data` exactly
|
|
17
|
+
* as the core's do. A factory rather than a wrap afterwards because the dev
|
|
18
|
+
* accounts are funded AT GENESIS, before the node exists
|
|
19
|
+
* (`docs/adr/0017-dev-accounts-live-in-webevm-devnode-a-slimnode-decorator-funded-at-genesis.md`).
|
|
20
|
+
*
|
|
21
|
+
* THE KEYS STAY HERE. The accounts are written in the worker module and derived
|
|
22
|
+
* in the worker; nothing this module sends to the main thread carries a key or
|
|
23
|
+
* a mnemonic (the refusal messages below name the option, never its value).
|
|
24
|
+
*
|
|
25
|
+
* A BAD CONFIG IS A VALUE, NEVER A THROW, for the reason webevm's worker host
|
|
26
|
+
* gives for a bad `createEngine`: this runs while the worker module is still
|
|
27
|
+
* evaluating, so a throw here means comlink's `expose()` never runs and the main
|
|
28
|
+
* thread's `createWorkerNode()` never settles. So the config is validated at
|
|
29
|
+
* once, the refusal is logged on this thread at once, and the factory rejects
|
|
30
|
+
* with the same text, which reaches the main thread as `createWorkerNode()`'s
|
|
31
|
+
* rejection (CONTEXT.md, *both signals*).
|
|
32
|
+
*/
|
|
33
|
+
import {
|
|
34
|
+
createNodeWorkerApi,
|
|
35
|
+
exposeNode,
|
|
36
|
+
type EngineSupplier,
|
|
37
|
+
type NodeWorkerApi,
|
|
38
|
+
type WorkerHostOptions,
|
|
39
|
+
} from 'webevm/worker-host';
|
|
40
|
+
import {deriveDevAccounts, devAccountBalances} from './accounts.js';
|
|
41
|
+
import type {DevFundingOptions} from './accounts.js';
|
|
42
|
+
import {createDevNode, type ImpersonationOptions} from './dev-node.js';
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* What the WORKER decides: the engine, the dev accounts, their funding and the
|
|
46
|
+
* impersonation switch. Everything else (`chainId`, `miningConfig`,
|
|
47
|
+
* `senderMode`, `initialBalances`, ...) is the main thread's, passed to
|
|
48
|
+
* `createWorkerNode()` as for any worker node.
|
|
49
|
+
*
|
|
50
|
+
* DECISION: `initialBalances` is NOT a worker option. It is webevm's own
|
|
51
|
+
* `createNode` option, which the main thread already passes through
|
|
52
|
+
* `createWorkerNode()`; accepting it here too would make the worker's value
|
|
53
|
+
* silently REPLACE the main thread's (the factory spreads the worker's config
|
|
54
|
+
* over the main thread's options). The worker funds extra addresses with
|
|
55
|
+
* `fundAccounts`, and the main thread's `initialBalances` still win over both,
|
|
56
|
+
* the precedence `createDevNode` documents. Alternative considered: accepting it
|
|
57
|
+
* and merging the two maps, which would be a second precedence rule to learn.
|
|
58
|
+
*/
|
|
59
|
+
export interface DevNodeWorkerHostOptions
|
|
60
|
+
extends Omit<DevFundingOptions, 'initialBalances'>, ImpersonationOptions {
|
|
61
|
+
/**
|
|
62
|
+
* Build this node's engine on THIS thread, as `webevm/worker-host`'s option
|
|
63
|
+
* of the same name (called once per node). Omit it for the default engine.
|
|
64
|
+
*/
|
|
65
|
+
createEngine?: EngineSupplier;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Why the dev config cannot create a node, or `undefined` when it can. The same
|
|
70
|
+
* checks `createDevNode` makes, run once up front so the mistake is reported
|
|
71
|
+
* when it is made rather than when a node is first asked for.
|
|
72
|
+
*/
|
|
73
|
+
function devConfigRefusal(
|
|
74
|
+
devConfig: Omit<DevNodeWorkerHostOptions, 'createEngine'>,
|
|
75
|
+
): string | undefined {
|
|
76
|
+
try {
|
|
77
|
+
deriveDevAccounts(devConfig.accounts);
|
|
78
|
+
// The balances' own checks, without deriving the accounts a second time
|
|
79
|
+
// (a mnemonic's seed is the slow part): an empty key list funds nobody.
|
|
80
|
+
devAccountBalances({...devConfig, accounts: []});
|
|
81
|
+
return undefined;
|
|
82
|
+
} catch (e) {
|
|
83
|
+
// The message already names the package and the option, never its value.
|
|
84
|
+
return String((e as Error)?.message ?? e);
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/**
|
|
89
|
+
* webevm's worker-host options for a dev node: the consumer's engine, and the
|
|
90
|
+
* dev node as the NODE FACTORY. Never throws: a bad config is logged here at
|
|
91
|
+
* once and rejects every `createNode()`.
|
|
92
|
+
*/
|
|
93
|
+
function devNodeHostOptions(
|
|
94
|
+
hostOptions: DevNodeWorkerHostOptions | undefined,
|
|
95
|
+
): WorkerHostOptions {
|
|
96
|
+
const {createEngine, ...devConfig} = hostOptions ?? {};
|
|
97
|
+
const refusal = devConfigRefusal(devConfig);
|
|
98
|
+
// THE EARLY SIGNAL, on the thread the config was written on.
|
|
99
|
+
if (refusal !== undefined) console.error(refusal);
|
|
100
|
+
return {
|
|
101
|
+
createEngine,
|
|
102
|
+
async createNode(options) {
|
|
103
|
+
// THE LATE SIGNAL: the main thread's `createWorkerNode()` rejects with it.
|
|
104
|
+
if (refusal !== undefined) throw new Error(refusal);
|
|
105
|
+
// The worker's dev config over the main thread's options (the engine
|
|
106
|
+
// already merged in by webevm's host); a refusal from `createDevNode`
|
|
107
|
+
// (impersonation on a `senderMode: 'recover'` node, say) rejects the
|
|
108
|
+
// main thread the same way.
|
|
109
|
+
return createDevNode({...options, ...devConfig});
|
|
110
|
+
},
|
|
111
|
+
};
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* The comlink api a dev-node worker exposes: webevm's `createNodeWorkerApi`
|
|
116
|
+
* with the dev node as its factory, so it is exactly what `createWorkerNode()`
|
|
117
|
+
* drives. Use {@link exposeDevNode} unless you are composing this into a larger
|
|
118
|
+
* exposed api of your own (the counterpart of webevm's `createNodeWorkerApi`).
|
|
119
|
+
*
|
|
120
|
+
* DECISION: exported (not only {@link exposeDevNode}) for the same reason
|
|
121
|
+
* webevm exports its counterpart, and so the worker-side signal can be checked
|
|
122
|
+
* without calling comlink's `expose()` on the checking thread. Alternative: the
|
|
123
|
+
* one export, with the early signal observable only in a worker's console.
|
|
124
|
+
*
|
|
125
|
+
* Never throws: a bad config is logged here and rejects every `createNode()`.
|
|
126
|
+
*/
|
|
127
|
+
export function createDevNodeWorkerApi(
|
|
128
|
+
hostOptions: DevNodeWorkerHostOptions = {},
|
|
129
|
+
): NodeWorkerApi {
|
|
130
|
+
return createNodeWorkerApi(devNodeHostOptions(hostOptions));
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* Expose a DEV node on THIS thread: the whole of a consumer's worker module.
|
|
135
|
+
*
|
|
136
|
+
* exposeDevNode({createEngine: () => createRevmEngine({wasm}), accounts: 5});
|
|
137
|
+
*
|
|
138
|
+
* The main thread uses webevm's own `createWorkerNode()` unchanged, and gets a
|
|
139
|
+
* node whose `eth_accounts`, sends and signatures are answered in here, its
|
|
140
|
+
* genesis funded here, and its keys never leaving this thread. Call it ONCE per
|
|
141
|
+
* thread, and await nothing at the module's top level before it (webevm's
|
|
142
|
+
* `exposeNode` has why: a slow top-level await can lose the main thread's first
|
|
143
|
+
* message). Needs `comlink`, as `webevm/worker-host` does.
|
|
144
|
+
*
|
|
145
|
+
* Returns the exposed api.
|
|
146
|
+
*/
|
|
147
|
+
export function exposeDevNode(
|
|
148
|
+
hostOptions: DevNodeWorkerHostOptions = {},
|
|
149
|
+
): NodeWorkerApi {
|
|
150
|
+
return exposeNode(devNodeHostOptions(hostOptions));
|
|
151
|
+
}
|