@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.
Files changed (48) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +221 -2
  3. package/dist/accounts.d.ts +82 -0
  4. package/dist/accounts.d.ts.map +1 -0
  5. package/dist/accounts.js +129 -0
  6. package/dist/accounts.js.map +1 -0
  7. package/dist/allocs.d.ts +26 -0
  8. package/dist/allocs.d.ts.map +1 -0
  9. package/dist/allocs.js +99 -0
  10. package/dist/allocs.js.map +1 -0
  11. package/dist/dev-node.d.ts +63 -0
  12. package/dist/dev-node.d.ts.map +1 -0
  13. package/dist/dev-node.js +166 -0
  14. package/dist/dev-node.js.map +1 -0
  15. package/dist/eip712.d.ts +23 -0
  16. package/dist/eip712.d.ts.map +1 -0
  17. package/dist/eip712.js +333 -0
  18. package/dist/eip712.js.map +1 -0
  19. package/dist/impersonation.d.ts +20 -0
  20. package/dist/impersonation.d.ts.map +1 -0
  21. package/dist/impersonation.js +95 -0
  22. package/dist/impersonation.js.map +1 -0
  23. package/dist/index.d.ts +11 -0
  24. package/dist/index.d.ts.map +1 -0
  25. package/dist/index.js +8 -0
  26. package/dist/index.js.map +1 -0
  27. package/dist/send.d.ts +20 -0
  28. package/dist/send.d.ts.map +1 -0
  29. package/dist/send.js +385 -0
  30. package/dist/send.js.map +1 -0
  31. package/dist/sign.d.ts +14 -0
  32. package/dist/sign.d.ts.map +1 -0
  33. package/dist/sign.js +155 -0
  34. package/dist/sign.js.map +1 -0
  35. package/dist/worker-host.d.ts +87 -0
  36. package/dist/worker-host.d.ts.map +1 -0
  37. package/dist/worker-host.js +112 -0
  38. package/dist/worker-host.js.map +1 -0
  39. package/package.json +79 -3
  40. package/src/accounts.ts +218 -0
  41. package/src/allocs.ts +134 -0
  42. package/src/dev-node.ts +220 -0
  43. package/src/eip712.ts +390 -0
  44. package/src/impersonation.ts +119 -0
  45. package/src/index.ts +25 -0
  46. package/src/send.ts +469 -0
  47. package/src/sign.ts +199 -0
  48. 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
+ }