@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
package/dist/sign.js ADDED
@@ -0,0 +1,155 @@
1
+ /**
2
+ * sign.ts: MESSAGE SIGNING by dev accounts: `personal_sign`, `eth_sign`
3
+ * (EIP-191 personal messages) and `eth_signTypedData_v4` (EIP-712, hashed by
4
+ * ./eip712.ts). `eth_signTransaction` is in ./send.ts, beside the send it fills
5
+ * and signs exactly as.
6
+ *
7
+ * Signing is `@noble/curves`' secp256k1 (`@ethereumjs/util` v10 exports no
8
+ * signing function; ADR 0017), on the digest itself (`prehash: false`),
9
+ * deterministic (RFC 6979, no extra entropy) and low-`s`, so the same request
10
+ * signs to the same bytes, as viem's local accounts sign. A signature is the
11
+ * 65 bytes `r ‖ s ‖ v` with `v` 27 or 28, as geth, anvil, Hardhat, MetaMask and
12
+ * viem return it.
13
+ *
14
+ * PARAMETER ORDERS, which are opposite:
15
+ *
16
+ * - `personal_sign [message, address]`, as MetaMask and geth take it (the
17
+ * order viem's `signMessage` sends);
18
+ * - `eth_sign [address, message]`, as geth takes it, and it signs the SAME
19
+ * EIP-191 digest: `keccak256("\x19Ethereum Signed Message:\n" ‖ len ‖ message)`.
20
+ * - `eth_signTypedData_v4 [address, typedData]`, `typedData` an object or its
21
+ * JSON text (viem sends the text).
22
+ *
23
+ * DECISIONS made here (task `devnode-signing-methods-and-eip-712`), each
24
+ * user-visible and reversible before 1.0:
25
+ *
26
+ * - AN ADDRESS WITH NO KEY IS REFUSED WITH `4100`, the code
27
+ * `eth_sendTransaction` uses for the same thing (see ./send.ts), naming only
28
+ * the `accounts` remedy: impersonation never signs (ADR 0017). An
29
+ * IMPERSONATED address with no key is refused with the same `4100`, saying so
30
+ * (`impersonatedNoKeyMessage` in ./impersonation.ts): a dev account that is
31
+ * also impersonated still signs with its key.
32
+ * - `personal_sign` TAKES A MESSAGE THAT IS NOT HEX AS UTF-8 TEXT, as MetaMask
33
+ * does (dapps pass a login message as plain text), and 0x hex as the bytes it
34
+ * spells. So a text message that happens to be valid 0x hex is signed as
35
+ * bytes, exactly as MetaMask signs it. `eth_sign` requires 0x hex, as geth
36
+ * does. Alternative: hex only for both (geth's and anvil's rule), which
37
+ * refuses the plain-text message a MetaMask-shaped dapp sends.
38
+ * - `eth_sign` SIGNS ARBITRARY DATA WITH THE EIP-191 PREFIX, as geth and anvil
39
+ * do (MetaMask's `eth_sign` signs a raw 32-byte hash, without the prefix, and
40
+ * is disabled by default there because a raw hash can be a transaction).
41
+ * This layer never signs a raw hash.
42
+ */
43
+ import { secp256k1 } from '@noble/curves/secp256k1.js';
44
+ import { keccak_256 } from '@noble/hashes/sha3.js';
45
+ import { RpcError } from 'webevm';
46
+ import { hashTypedData } from './eip712.js';
47
+ import { impersonatedNoKeyMessage } from './impersonation.js';
48
+ const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
49
+ const HEX_DATA = /^0x([0-9a-fA-F]{2})*$/;
50
+ const encoder = new TextEncoder();
51
+ /** The message of a `4100` refusal: no key is held for `address`. */
52
+ export function noKeyMessage(method, address) {
53
+ return (`${method}: ${address} is not a dev account, so @webevm/devnode holds no key to sign for it. ` +
54
+ `Configure its private key in the dev node's \`accounts\` option.`);
55
+ }
56
+ function invalid(method, message) {
57
+ throw new RpcError(-32602, `${method}: ${message}`);
58
+ }
59
+ function hexToBytes(hex) {
60
+ const out = new Uint8Array((hex.length - 2) / 2);
61
+ for (let i = 0; i < out.length; i++)
62
+ out[i] = parseInt(hex.slice(2 + 2 * i, 4 + 2 * i), 16);
63
+ return out;
64
+ }
65
+ function toHex(bytes) {
66
+ let s = '0x';
67
+ for (const b of bytes)
68
+ s += b.toString(16).padStart(2, '0');
69
+ return s;
70
+ }
71
+ /** EIP-191 version 0x45: the personal-message digest. */
72
+ function personalMessageHash(message) {
73
+ const prefix = encoder.encode(`\x19Ethereum Signed Message:\n${message.length}`);
74
+ const data = new Uint8Array(prefix.length + message.length);
75
+ data.set(prefix);
76
+ data.set(message, prefix.length);
77
+ return keccak_256(data);
78
+ }
79
+ /** A 32-byte digest signed as `r ‖ s ‖ v`, `v` 27 or 28. */
80
+ function signDigest(digest, privateKey) {
81
+ // 'recovered' is `recovery ‖ r ‖ s`.
82
+ const sig = secp256k1.sign(digest, privateKey, {
83
+ prehash: false,
84
+ lowS: true,
85
+ format: 'recovered',
86
+ });
87
+ const out = new Uint8Array(65);
88
+ out.set(sig.subarray(1, 65));
89
+ out[64] = 27 + sig[0];
90
+ return toHex(out);
91
+ }
92
+ export function createMessageSigner(accounts, impersonation) {
93
+ const keys = new Map(accounts.map((a) => [a.address, a.privateKey]));
94
+ function params(method, raw) {
95
+ if (!Array.isArray(raw) || raw.length < 2)
96
+ invalid(method, method === 'personal_sign'
97
+ ? 'expected [message, address].'
98
+ : method === 'eth_sign'
99
+ ? 'expected [address, message].'
100
+ : 'expected [address, typedData].');
101
+ return [raw[0], raw[1]];
102
+ }
103
+ function keyFor(method, address) {
104
+ if (typeof address !== 'string' || !ADDRESS.test(address))
105
+ invalid(method, `the address must be the 20-byte hex address of the dev account to sign with (received ${JSON.stringify(address)}).`);
106
+ const from = address.toLowerCase();
107
+ const key = keys.get(from);
108
+ if (!key)
109
+ throw new RpcError(4100, impersonation.addresses.has(from)
110
+ ? impersonatedNoKeyMessage(method, from)
111
+ : noKeyMessage(method, from));
112
+ return key;
113
+ }
114
+ return {
115
+ async personalSign(raw) {
116
+ const [message, address] = params('personal_sign', raw);
117
+ if (typeof message !== 'string')
118
+ invalid('personal_sign', 'the message must be a string, 0x hex or text.');
119
+ const key = keyFor('personal_sign', address);
120
+ const bytes = HEX_DATA.test(message)
121
+ ? hexToBytes(message)
122
+ : encoder.encode(message);
123
+ return signDigest(personalMessageHash(bytes), key);
124
+ },
125
+ async ethSign(raw) {
126
+ const [address, message] = params('eth_sign', raw);
127
+ if (typeof message !== 'string' || !HEX_DATA.test(message))
128
+ invalid('eth_sign', 'the message must be even-length 0x hex.');
129
+ const key = keyFor('eth_sign', address);
130
+ return signDigest(personalMessageHash(hexToBytes(message)), key);
131
+ },
132
+ async signTypedDataV4(raw) {
133
+ const [address, data] = params('eth_signTypedData_v4', raw);
134
+ const key = keyFor('eth_signTypedData_v4', address);
135
+ let typed = data;
136
+ if (typeof data === 'string') {
137
+ try {
138
+ typed = JSON.parse(data);
139
+ }
140
+ catch {
141
+ invalid('eth_signTypedData_v4', 'the typed data is a string that is not JSON.');
142
+ }
143
+ }
144
+ let digest;
145
+ try {
146
+ digest = hashTypedData(typed);
147
+ }
148
+ catch (e) {
149
+ return invalid('eth_signTypedData_v4', e.message);
150
+ }
151
+ return signDigest(digest, key);
152
+ },
153
+ };
154
+ }
155
+ //# sourceMappingURL=sign.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sign.js","sourceRoot":"","sources":["../src/sign.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,87 @@
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 { type EngineSupplier, type NodeWorkerApi } from 'webevm/worker-host';
34
+ import type { DevFundingOptions } from './accounts.js';
35
+ import { type ImpersonationOptions } from './dev-node.js';
36
+ /**
37
+ * What the WORKER decides: the engine, the dev accounts, their funding and the
38
+ * impersonation switch. Everything else (`chainId`, `miningConfig`,
39
+ * `senderMode`, `initialBalances`, ...) is the main thread's, passed to
40
+ * `createWorkerNode()` as for any worker node.
41
+ *
42
+ * DECISION: `initialBalances` is NOT a worker option. It is webevm's own
43
+ * `createNode` option, which the main thread already passes through
44
+ * `createWorkerNode()`; accepting it here too would make the worker's value
45
+ * silently REPLACE the main thread's (the factory spreads the worker's config
46
+ * over the main thread's options). The worker funds extra addresses with
47
+ * `fundAccounts`, and the main thread's `initialBalances` still win over both,
48
+ * the precedence `createDevNode` documents. Alternative considered: accepting it
49
+ * and merging the two maps, which would be a second precedence rule to learn.
50
+ */
51
+ export interface DevNodeWorkerHostOptions extends Omit<DevFundingOptions, 'initialBalances'>, ImpersonationOptions {
52
+ /**
53
+ * Build this node's engine on THIS thread, as `webevm/worker-host`'s option
54
+ * of the same name (called once per node). Omit it for the default engine.
55
+ */
56
+ createEngine?: EngineSupplier;
57
+ }
58
+ /**
59
+ * The comlink api a dev-node worker exposes: webevm's `createNodeWorkerApi`
60
+ * with the dev node as its factory, so it is exactly what `createWorkerNode()`
61
+ * drives. Use {@link exposeDevNode} unless you are composing this into a larger
62
+ * exposed api of your own (the counterpart of webevm's `createNodeWorkerApi`).
63
+ *
64
+ * DECISION: exported (not only {@link exposeDevNode}) for the same reason
65
+ * webevm exports its counterpart, and so the worker-side signal can be checked
66
+ * without calling comlink's `expose()` on the checking thread. Alternative: the
67
+ * one export, with the early signal observable only in a worker's console.
68
+ *
69
+ * Never throws: a bad config is logged here and rejects every `createNode()`.
70
+ */
71
+ export declare function createDevNodeWorkerApi(hostOptions?: DevNodeWorkerHostOptions): NodeWorkerApi;
72
+ /**
73
+ * Expose a DEV node on THIS thread: the whole of a consumer's worker module.
74
+ *
75
+ * exposeDevNode({createEngine: () => createRevmEngine({wasm}), accounts: 5});
76
+ *
77
+ * The main thread uses webevm's own `createWorkerNode()` unchanged, and gets a
78
+ * node whose `eth_accounts`, sends and signatures are answered in here, its
79
+ * genesis funded here, and its keys never leaving this thread. Call it ONCE per
80
+ * thread, and await nothing at the module's top level before it (webevm's
81
+ * `exposeNode` has why: a slow top-level await can lose the main thread's first
82
+ * message). Needs `comlink`, as `webevm/worker-host` does.
83
+ *
84
+ * Returns the exposed api.
85
+ */
86
+ export declare function exposeDevNode(hostOptions?: DevNodeWorkerHostOptions): NodeWorkerApi;
87
+ //# sourceMappingURL=worker-host.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"worker-host.d.ts","sourceRoot":"","sources":["../src/worker-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAGN,KAAK,cAAc,EACnB,KAAK,aAAa,EAElB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,eAAe,CAAC;AACrD,OAAO,EAAgB,KAAK,oBAAoB,EAAC,MAAM,eAAe,CAAC;AAEvE;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,wBAChB,SAAQ,IAAI,CAAC,iBAAiB,EAAE,iBAAiB,CAAC,EAAE,oBAAoB;IACxE;;;OAGG;IACH,YAAY,CAAC,EAAE,cAAc,CAAC;CAC9B;AAgDD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACrC,WAAW,GAAE,wBAA6B,GACxC,aAAa,CAEf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC5B,WAAW,GAAE,wBAA6B,GACxC,aAAa,CAEf"}
@@ -0,0 +1,112 @@
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 { createNodeWorkerApi, exposeNode, } from 'webevm/worker-host';
34
+ import { deriveDevAccounts, devAccountBalances } from './accounts.js';
35
+ import { createDevNode } from './dev-node.js';
36
+ /**
37
+ * Why the dev config cannot create a node, or `undefined` when it can. The same
38
+ * checks `createDevNode` makes, run once up front so the mistake is reported
39
+ * when it is made rather than when a node is first asked for.
40
+ */
41
+ function devConfigRefusal(devConfig) {
42
+ try {
43
+ deriveDevAccounts(devConfig.accounts);
44
+ // The balances' own checks, without deriving the accounts a second time
45
+ // (a mnemonic's seed is the slow part): an empty key list funds nobody.
46
+ devAccountBalances({ ...devConfig, accounts: [] });
47
+ return undefined;
48
+ }
49
+ catch (e) {
50
+ // The message already names the package and the option, never its value.
51
+ return String(e?.message ?? e);
52
+ }
53
+ }
54
+ /**
55
+ * webevm's worker-host options for a dev node: the consumer's engine, and the
56
+ * dev node as the NODE FACTORY. Never throws: a bad config is logged here at
57
+ * once and rejects every `createNode()`.
58
+ */
59
+ function devNodeHostOptions(hostOptions) {
60
+ const { createEngine, ...devConfig } = hostOptions ?? {};
61
+ const refusal = devConfigRefusal(devConfig);
62
+ // THE EARLY SIGNAL, on the thread the config was written on.
63
+ if (refusal !== undefined)
64
+ console.error(refusal);
65
+ return {
66
+ createEngine,
67
+ async createNode(options) {
68
+ // THE LATE SIGNAL: the main thread's `createWorkerNode()` rejects with it.
69
+ if (refusal !== undefined)
70
+ throw new Error(refusal);
71
+ // The worker's dev config over the main thread's options (the engine
72
+ // already merged in by webevm's host); a refusal from `createDevNode`
73
+ // (impersonation on a `senderMode: 'recover'` node, say) rejects the
74
+ // main thread the same way.
75
+ return createDevNode({ ...options, ...devConfig });
76
+ },
77
+ };
78
+ }
79
+ /**
80
+ * The comlink api a dev-node worker exposes: webevm's `createNodeWorkerApi`
81
+ * with the dev node as its factory, so it is exactly what `createWorkerNode()`
82
+ * drives. Use {@link exposeDevNode} unless you are composing this into a larger
83
+ * exposed api of your own (the counterpart of webevm's `createNodeWorkerApi`).
84
+ *
85
+ * DECISION: exported (not only {@link exposeDevNode}) for the same reason
86
+ * webevm exports its counterpart, and so the worker-side signal can be checked
87
+ * without calling comlink's `expose()` on the checking thread. Alternative: the
88
+ * one export, with the early signal observable only in a worker's console.
89
+ *
90
+ * Never throws: a bad config is logged here and rejects every `createNode()`.
91
+ */
92
+ export function createDevNodeWorkerApi(hostOptions = {}) {
93
+ return createNodeWorkerApi(devNodeHostOptions(hostOptions));
94
+ }
95
+ /**
96
+ * Expose a DEV node on THIS thread: the whole of a consumer's worker module.
97
+ *
98
+ * exposeDevNode({createEngine: () => createRevmEngine({wasm}), accounts: 5});
99
+ *
100
+ * The main thread uses webevm's own `createWorkerNode()` unchanged, and gets a
101
+ * node whose `eth_accounts`, sends and signatures are answered in here, its
102
+ * genesis funded here, and its keys never leaving this thread. Call it ONCE per
103
+ * thread, and await nothing at the module's top level before it (webevm's
104
+ * `exposeNode` has why: a slow top-level await can lose the main thread's first
105
+ * message). Needs `comlink`, as `webevm/worker-host` does.
106
+ *
107
+ * Returns the exposed api.
108
+ */
109
+ export function exposeDevNode(hostOptions = {}) {
110
+ return exposeNode(devNodeHostOptions(hostOptions));
111
+ }
112
+ //# sourceMappingURL=worker-host.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"worker-host.js","sourceRoot":"","sources":["../src/worker-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EACN,mBAAmB,EACnB,UAAU,GAIV,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAC,iBAAiB,EAAE,kBAAkB,EAAC,MAAM,eAAe,CAAC;AAEpE,OAAO,EAAC,aAAa,EAA4B,MAAM,eAAe,CAAC;AA0BvE;;;;GAIG;AACH,SAAS,gBAAgB,CACxB,SAAyD;IAEzD,IAAI,CAAC;QACJ,iBAAiB,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACtC,wEAAwE;QACxE,wEAAwE;QACxE,kBAAkB,CAAC,EAAC,GAAG,SAAS,EAAE,QAAQ,EAAE,EAAE,EAAC,CAAC,CAAC;QACjD,OAAO,SAAS,CAAC;IAClB,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACZ,yEAAyE;QACzE,OAAO,MAAM,CAAE,CAAW,EAAE,OAAO,IAAI,CAAC,CAAC,CAAC;IAC3C,CAAC;AACF,CAAC;AAED;;;;GAIG;AACH,SAAS,kBAAkB,CAC1B,WAAiD;IAEjD,MAAM,EAAC,YAAY,EAAE,GAAG,SAAS,EAAC,GAAG,WAAW,IAAI,EAAE,CAAC;IACvD,MAAM,OAAO,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAC5C,6DAA6D;IAC7D,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAClD,OAAO;QACN,YAAY;QACZ,KAAK,CAAC,UAAU,CAAC,OAAO;YACvB,2EAA2E;YAC3E,IAAI,OAAO,KAAK,SAAS;gBAAE,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;YACpD,qEAAqE;YACrE,sEAAsE;YACtE,qEAAqE;YACrE,4BAA4B;YAC5B,OAAO,aAAa,CAAC,EAAC,GAAG,OAAO,EAAE,GAAG,SAAS,EAAC,CAAC,CAAC;QAClD,CAAC;KACD,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,sBAAsB,CACrC,cAAwC,EAAE;IAE1C,OAAO,mBAAmB,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAC5B,cAAwC,EAAE;IAE1C,OAAO,UAAU,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAC,CAAC;AACpD,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,82 @@
1
1
  {
2
2
  "name": "@webevm/devnode",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.0",
4
+ "description": "Dev accounts for webevm: a SlimNode decorator that answers eth_accounts with anvil's / Hardhat's test accounts, funded at genesis, and forwards everything else to the node.",
5
+ "keywords": [
6
+ "ethereum",
7
+ "eip-1193",
8
+ "webevm",
9
+ "dev-node",
10
+ "anvil",
11
+ "hardhat",
12
+ "local-chain",
13
+ "in-browser"
14
+ ],
15
+ "license": "MIT",
16
+ "author": "wighawag",
17
+ "homepage": "https://github.com/wighawag/webevm/tree/main/packages/devnode#readme",
18
+ "repository": {
19
+ "type": "git",
20
+ "url": "git+https://github.com/wighawag/webevm.git",
21
+ "directory": "packages/devnode"
22
+ },
23
+ "bugs": {
24
+ "url": "https://github.com/wighawag/webevm/issues"
25
+ },
26
+ "publishConfig": {
27
+ "access": "public"
28
+ },
29
+ "type": "module",
30
+ "exports": {
31
+ ".": {
32
+ "types": "./dist/index.d.ts",
33
+ "default": "./dist/index.js"
34
+ },
35
+ "./worker-host": {
36
+ "types": "./dist/worker-host.d.ts",
37
+ "default": "./dist/worker-host.js"
38
+ }
39
+ },
40
+ "files": [
41
+ "dist",
42
+ "src"
43
+ ],
44
+ "dependencies": {
45
+ "@eip-1193/over-port": "^0.2.0",
46
+ "@ethereumjs/common": "^10.1.2",
47
+ "@ethereumjs/tx": "^10.1.2",
48
+ "@ethereumjs/util": "^10.1.2",
49
+ "@noble/curves": "^2.2.0",
50
+ "@noble/hashes": "^2.2.0",
51
+ "@scure/bip32": "^2.0.0",
52
+ "@scure/bip39": "^2.0.0"
53
+ },
54
+ "peerDependencies": {
55
+ "comlink": "^4.4.2",
56
+ "webevm": ">=0.10.0"
57
+ },
58
+ "peerDependenciesMeta": {
59
+ "comlink": {
60
+ "optional": true
61
+ }
62
+ },
63
+ "devDependencies": {
64
+ "@playwright/test": "^1.60.0",
65
+ "@types/node": "^25.2.0",
66
+ "as-soon": "^0.1.5",
67
+ "buffer": "^6.0.3",
68
+ "esbuild": "^0.28.0",
69
+ "playwright-browser-harness": "^0.3.0",
70
+ "prettier": "^3.8.0",
71
+ "typescript": "^5.3.3",
72
+ "viem": "^2.45.0",
73
+ "webevm": "0.10.0"
74
+ },
75
+ "scripts": {
76
+ "format": "prettier --write .",
77
+ "format:check": "prettier --check .",
78
+ "build": "tsc -p tsconfig.build.json",
79
+ "dev": "as-soon -w src pnpm build",
80
+ "test": "playwright test"
81
+ }
6
82
  }