@artblocks/abx-sdk 0.1.0-alpha.0 → 0.1.0-alpha.10

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 (103) hide show
  1. package/README.md +131 -0
  2. package/dist/abi/generated.d.ts +585 -12
  3. package/dist/abi/generated.d.ts.map +1 -1
  4. package/dist/abi/generated.js +16 -16
  5. package/dist/abi/generated.js.map +1 -1
  6. package/dist/abi/index.d.ts +209 -12
  7. package/dist/abi/index.d.ts.map +1 -1
  8. package/dist/anchors.d.ts +150 -0
  9. package/dist/anchors.d.ts.map +1 -0
  10. package/dist/anchors.js +290 -0
  11. package/dist/anchors.js.map +1 -0
  12. package/dist/chains.d.ts +34 -9
  13. package/dist/chains.d.ts.map +1 -1
  14. package/dist/chains.js +45 -18
  15. package/dist/chains.js.map +1 -1
  16. package/dist/chunks.d.ts +53 -23
  17. package/dist/chunks.d.ts.map +1 -1
  18. package/dist/chunks.js +68 -6
  19. package/dist/chunks.js.map +1 -1
  20. package/dist/clients.d.ts +23 -11
  21. package/dist/clients.d.ts.map +1 -1
  22. package/dist/clients.js +17 -18
  23. package/dist/clients.js.map +1 -1
  24. package/dist/creator-token.d.ts +65 -0
  25. package/dist/creator-token.d.ts.map +1 -0
  26. package/dist/creator-token.js +93 -0
  27. package/dist/creator-token.js.map +1 -0
  28. package/dist/deploy.d.ts +24 -10
  29. package/dist/deploy.d.ts.map +1 -1
  30. package/dist/deploy.js +62 -87
  31. package/dist/deploy.js.map +1 -1
  32. package/dist/deployments.d.ts.map +1 -1
  33. package/dist/deployments.js +38 -22
  34. package/dist/deployments.js.map +1 -1
  35. package/dist/deps.d.ts +38 -0
  36. package/dist/deps.d.ts.map +1 -1
  37. package/dist/deps.js +70 -1
  38. package/dist/deps.js.map +1 -1
  39. package/dist/env.d.ts +11 -0
  40. package/dist/env.d.ts.map +1 -1
  41. package/dist/env.js +42 -2
  42. package/dist/env.js.map +1 -1
  43. package/dist/errors.d.ts +63 -0
  44. package/dist/errors.d.ts.map +1 -0
  45. package/dist/errors.js +85 -0
  46. package/dist/errors.js.map +1 -0
  47. package/dist/execute.d.ts +115 -0
  48. package/dist/execute.d.ts.map +1 -0
  49. package/dist/execute.js +142 -0
  50. package/dist/execute.js.map +1 -0
  51. package/dist/index.d.ts +13 -2
  52. package/dist/index.d.ts.map +1 -1
  53. package/dist/index.js +13 -2
  54. package/dist/index.js.map +1 -1
  55. package/dist/inspect.d.ts +48 -0
  56. package/dist/inspect.d.ts.map +1 -0
  57. package/dist/inspect.js +290 -0
  58. package/dist/inspect.js.map +1 -0
  59. package/dist/migrate.d.ts +41 -0
  60. package/dist/migrate.d.ts.map +1 -0
  61. package/dist/migrate.js +140 -0
  62. package/dist/migrate.js.map +1 -0
  63. package/dist/node.d.ts +13 -0
  64. package/dist/node.d.ts.map +1 -0
  65. package/dist/node.js +13 -0
  66. package/dist/node.js.map +1 -0
  67. package/dist/onchain-uri.d.ts +96 -0
  68. package/dist/onchain-uri.d.ts.map +1 -0
  69. package/dist/onchain-uri.js +231 -0
  70. package/dist/onchain-uri.js.map +1 -0
  71. package/dist/ops.d.ts +113 -5
  72. package/dist/ops.d.ts.map +1 -1
  73. package/dist/ops.js +172 -13
  74. package/dist/ops.js.map +1 -1
  75. package/dist/reconstruct.d.ts +20 -1
  76. package/dist/reconstruct.d.ts.map +1 -1
  77. package/dist/reconstruct.js +124 -50
  78. package/dist/reconstruct.js.map +1 -1
  79. package/dist/resume.d.ts +96 -0
  80. package/dist/resume.d.ts.map +1 -0
  81. package/dist/resume.js +95 -0
  82. package/dist/resume.js.map +1 -0
  83. package/dist/service.d.ts +369 -0
  84. package/dist/service.d.ts.map +1 -0
  85. package/dist/service.js +376 -0
  86. package/dist/service.js.map +1 -0
  87. package/dist/staging.d.ts +95 -0
  88. package/dist/staging.d.ts.map +1 -0
  89. package/dist/staging.js +57 -0
  90. package/dist/staging.js.map +1 -0
  91. package/dist/tokendata.d.ts +62 -2
  92. package/dist/tokendata.d.ts.map +1 -1
  93. package/dist/tokendata.js +60 -16
  94. package/dist/tokendata.js.map +1 -1
  95. package/dist/tokens.d.ts +55 -0
  96. package/dist/tokens.d.ts.map +1 -0
  97. package/dist/tokens.js +152 -0
  98. package/dist/tokens.js.map +1 -0
  99. package/dist/util.d.ts +59 -0
  100. package/dist/util.d.ts.map +1 -0
  101. package/dist/util.js +89 -0
  102. package/dist/util.js.map +1 -0
  103. package/package.json +10 -2
package/dist/deps.js CHANGED
@@ -14,8 +14,10 @@
14
14
  * specs/protocol/dependency-registry.md): `getDependencyDetails(bytes32)` is the
15
15
  * load-bearing read behind the CLI's best-effort selection-time check.
16
16
  */
17
- import { padHex, toHex } from 'viem';
17
+ import { encodeFunctionData, padHex, toHex } from 'viem';
18
18
  import { decodeTag } from './spine.js';
19
+ import { seriesCodeAbi } from './abi/index.js';
20
+ import { resolveDependencyRegistry } from './deployments.js';
19
21
  /** `IAbxDependencies.Resolution` — index-aligned with the Solidity enum. */
20
22
  export const DEP_RESOLUTION = { registry: 0, onchain: 1 };
21
23
  // Printable non-space ASCII — what a readable bytes32 tag can carry unambiguously
@@ -100,4 +102,71 @@ export async function readRegistryDependency(client, registry, ref) {
100
102
  return null;
101
103
  return { nameAndVersion, licenseType, preferredCDN, availableOnChain, scriptCount: Number(scriptCount) };
102
104
  }
105
+ // ── the deploy-time dependency lane (registry pointer, setup legs, selection-time check) ──────
106
+ // The rest of a code project's dependency handling: resolving which registry a deploy should point
107
+ // at, composing the setup-multicall legs, and the best-effort existence check against that registry.
108
+ // `parseDepFlag` (the `--dep` CLI flag grammar) is CLI-local and stays there — everything downstream
109
+ // of a parsed `ParsedDependencyRef[]` lives here.
110
+ /**
111
+ * The registry pointer a deploy with ≥1 Registry-resolution dep should set: an explicit
112
+ * `--dep-registry` wins (validated), else the chain's known AB registry (env-overridable),
113
+ * else none — the caller WARNS and skips the leg (soft pointer; the resolver falls back to
114
+ * its built-in CDN map). Never a blocker.
115
+ */
116
+ export function resolveDepRegistryPointer(flagValue, chainId) {
117
+ if (flagValue !== undefined) {
118
+ if (flagValue === 'true' || !/^0x[0-9a-fA-F]{40}$/.test(flagValue)) {
119
+ throw new Error(`--dep-registry must be an address (0x + 40 hex); got '${flagValue}'`);
120
+ }
121
+ return { registry: flagValue, source: 'flag' };
122
+ }
123
+ const known = resolveDependencyRegistry(chainId);
124
+ return known ? { registry: known, source: 'default' } : { registry: null, source: 'none' };
125
+ }
126
+ /**
127
+ * The dependency legs of the setup multicall: one `setDependency(i, resolution, ref)` per
128
+ * dep in index order, plus the `setDependencyRegistry` leg when a pointer resolved. These
129
+ * ride the SAME atomic setup multicall as script chunks/schemas/mints, in every signing lane.
130
+ */
131
+ export function dependencySetupCalls(deps, registry) {
132
+ const calls = deps.map((d, i) => encodeFunctionData({ abi: seriesCodeAbi, functionName: 'setDependency', args: [BigInt(i), d.resolution, d.ref] }));
133
+ if (deps.length && registry) {
134
+ calls.push(encodeFunctionData({ abi: seriesCodeAbi, functionName: 'setDependencyRegistry', args: [registry] }));
135
+ }
136
+ return calls;
137
+ }
138
+ /**
139
+ * Best-effort existence/on-chain-ness check of every Registry-resolution dep against the
140
+ * pointer registry. A revert or an empty record ⇒ `not-found` (a warning — the owner may
141
+ * intend a custom registry). A transport failure ⇒ the remaining checks are `skipped` and
142
+ * `rpcOk: false` — one info line, never an error: the deploy proceeds regardless.
143
+ */
144
+ export async function checkRegistryDeps(client, registry, deps) {
145
+ const registryDeps = deps.filter((d) => d.resolution === DEP_RESOLUTION.registry);
146
+ const checks = [];
147
+ let rpcOk = true;
148
+ for (const d of registryDeps) {
149
+ if (!rpcOk) {
150
+ checks.push({ dep: d.display, status: 'skipped' });
151
+ continue;
152
+ }
153
+ try {
154
+ const details = await readRegistryDependency(client, registry, d.ref);
155
+ checks.push(details ? { dep: d.display, status: 'found', details } : { dep: d.display, status: 'not-found' });
156
+ }
157
+ catch (e) {
158
+ // A contract revert means the registry answered "no such dependency"; anything else
159
+ // (DNS, timeout, HTTP) means we couldn't ask — degrade to skipped, not failed.
160
+ const msg = `${e.name ?? ''} ${e.message ?? ''}`;
161
+ if (/ContractFunction|revert|returned no data/i.test(msg)) {
162
+ checks.push({ dep: d.display, status: 'not-found' });
163
+ }
164
+ else {
165
+ rpcOk = false;
166
+ checks.push({ dep: d.display, status: 'skipped' });
167
+ }
168
+ }
169
+ }
170
+ return { checks, rpcOk };
171
+ }
103
172
  //# sourceMappingURL=deps.js.map
package/dist/deps.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"deps.js","sourceRoot":"","sources":["../src/deps.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"deps.js","sourceRoot":"","sources":["../src/deps.ts"],"names":[],"mappings":"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"}
package/dist/env.d.ts CHANGED
@@ -1,2 +1,13 @@
1
1
  export declare function loadDotEnv(startDir?: string): void;
2
+ /**
3
+ * Parse `.env` text into ordered entries plus any keys the file sets MORE THAN ONCE (pure — the
4
+ * testable half of {@link loadDotEnv}). First occurrence wins, matching the loader; duplicates are
5
+ * returned rather than swallowed, because a stale duplicate (two `ABX_RPC_URLS_SEPOLIA` lines, one
6
+ * pointing at a different network) leaves every downstream check passing while the tool talks to
7
+ * somewhere unintended — and the symptom surfaces far away as "no contract at that address".
8
+ */
9
+ export declare function parseEnvContent(content: string): {
10
+ entries: Array<[string, string]>;
11
+ duplicates: string[];
12
+ };
2
13
  //# sourceMappingURL=env.d.ts.map
package/dist/env.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAWA,wBAAgB,UAAU,CAAC,QAAQ,GAAE,MAAsB,GAAG,IAAI,CAcjE"}
1
+ {"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAmBA,wBAAgB,UAAU,CAAC,QAAQ,GAAE,MAAsB,GAAG,IAAI,CAcjE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG;IAAC,OAAO,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAC,CA6BzG"}
package/dist/env.js CHANGED
@@ -5,6 +5,14 @@ import { dirname, resolve } from 'node:path';
5
5
  * root looking for a `.env`, and sets any keys not already present in the
6
6
  * environment. Deliberately tiny — the toolkit must run with `pnpm install`
7
7
  * and nothing else.
8
+ *
9
+ * Node-only (needs `node:fs` + `node:path`) — reached exclusively through the
10
+ * `@artblocks/abx-sdk/node` subpath, never the package's main entry (which a browser
11
+ * bundle must be able to import — see `test/browser-bundle.test.ts`). A host calls
12
+ * {@link loadDotEnv} once at startup; the SDK core never calls it itself (it reads
13
+ * whatever's already in `process.env` via `util.ts`'s `readEnv`). Because this module is
14
+ * Node-subpath-only, `parseInto`'s `console.error` on a conflicting duplicate key is fine
15
+ * to leave as a direct console write — there is no browser caller to surprise.
8
16
  */
9
17
  let loaded = false;
10
18
  export function loadDotEnv(startDir = process.cwd()) {
@@ -24,7 +32,17 @@ export function loadDotEnv(startDir = process.cwd()) {
24
32
  dir = parent;
25
33
  }
26
34
  }
27
- function parseInto(content) {
35
+ /**
36
+ * Parse `.env` text into ordered entries plus any keys the file sets MORE THAN ONCE (pure — the
37
+ * testable half of {@link loadDotEnv}). First occurrence wins, matching the loader; duplicates are
38
+ * returned rather than swallowed, because a stale duplicate (two `ABX_RPC_URLS_SEPOLIA` lines, one
39
+ * pointing at a different network) leaves every downstream check passing while the tool talks to
40
+ * somewhere unintended — and the symptom surfaces far away as "no contract at that address".
41
+ */
42
+ export function parseEnvContent(content) {
43
+ const entries = [];
44
+ const seen = new Map();
45
+ const duplicates = [];
28
46
  for (const rawLine of content.split('\n')) {
29
47
  const line = rawLine.trim();
30
48
  if (!line || line.startsWith('#'))
@@ -38,8 +56,30 @@ function parseInto(content) {
38
56
  (value.startsWith("'") && value.endsWith("'"))) {
39
57
  value = value.slice(1, -1);
40
58
  }
41
- if (key && process.env[key] === undefined)
59
+ if (!key)
60
+ continue;
61
+ if (seen.has(key)) {
62
+ // Only a duplicate with a DIFFERENT value is worth reporting. A repeated identical line is
63
+ // harmless, and warning on it turns a real signal into per-invocation noise (every `abx`
64
+ // command is its own process, so there is nowhere to throttle a genuine warning to "once").
65
+ if (seen.get(key) !== value && !duplicates.includes(key))
66
+ duplicates.push(key);
67
+ continue;
68
+ }
69
+ seen.set(key, value);
70
+ entries.push([key, value]);
71
+ }
72
+ return { entries, duplicates };
73
+ }
74
+ function parseInto(content) {
75
+ const { entries, duplicates } = parseEnvContent(content);
76
+ for (const [key, value] of entries) {
77
+ if (process.env[key] === undefined)
42
78
  process.env[key] = value;
43
79
  }
80
+ if (duplicates.length) {
81
+ console.error(`⚠ .env sets ${duplicates.length === 1 ? 'this key' : 'these keys'} to CONFLICTING values: ${duplicates.join(', ')}. ` +
82
+ `The FIRST value wins and the later one is ignored — delete the stale line, or you may be pointed somewhere you didn't intend.`);
83
+ }
44
84
  }
45
85
  //# sourceMappingURL=env.js.map
package/dist/env.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,YAAY,EAAE,UAAU,EAAC,MAAM,SAAS,CAAC;AACjD,OAAO,EAAC,OAAO,EAAE,OAAO,EAAC,MAAM,WAAW,CAAC;AAE3C;;;;;GAKG;AACH,IAAI,MAAM,GAAG,KAAK,CAAC;AAEnB,MAAM,UAAU,UAAU,CAAC,WAAmB,OAAO,CAAC,GAAG,EAAE;IACzD,IAAI,MAAM;QAAE,OAAO;IACnB,MAAM,GAAG,IAAI,CAAC;IACd,IAAI,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACvC,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC1B,SAAS,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;YAC3C,OAAO;QACT,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,MAAM;QAC1B,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;AACH,CAAC;AAED,SAAS,SAAS,CAAC,OAAe;IAChC,KAAK,MAAM,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QAC5C,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,EAAE,KAAK,CAAC,CAAC;YAAE,SAAS;QACxB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QACrC,IAAI,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACtC,IACE,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YAC9C,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAC9C,CAAC;YACD,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAC7B,CAAC;QACD,IAAI,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS;YAAE,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACtE,CAAC;AACH,CAAC"}
1
+ {"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,63 @@
1
+ import type { Address, Hex } from 'viem';
2
+ /**
3
+ * The SDK's error taxonomy — deliberately minimal. A caller that wants to react to a SPECIFIC
4
+ * failure (retry a stale estimate, surface a revert's tx hash) should catch by TYPE, not by
5
+ * parsing `.message`; every SDK-thrown error a caller is expected to distinguish extends this,
6
+ * following the same `name` + typed-fields convention `AbxServiceError` already uses (service.ts).
7
+ * This module stays small on purpose — it grows only when a real caller needs a new type to catch,
8
+ * not as a speculative taxonomy of everything that could go wrong.
9
+ */
10
+ export declare class AbxSdkError extends Error {
11
+ constructor(message: string);
12
+ }
13
+ /**
14
+ * A sent transaction MINED with `status: 'reverted'`. Thrown by {@link makeHotSender} (and anything
15
+ * else driving `SendTx`) instead of letting a revert masquerade as a "confirmed" send — carries the
16
+ * tx hash so a caller can look it up on an explorer without re-parsing a message string.
17
+ */
18
+ export declare class TxRevertedError extends AbxSdkError {
19
+ readonly op: string;
20
+ readonly txHash: Hex;
21
+ constructor(op: string, txHash: Hex);
22
+ }
23
+ /**
24
+ * `pinGas`'s refusal: every estimate attempt came back below the transaction's PROVABLE gas floor
25
+ * (`PreparedTx.gasFloor` — EVM code deposit at exactly 200 gas/byte, and nothing else is physics).
26
+ * That is proof the node answering the estimate hasn't seen the target's deploy block yet, not that
27
+ * the floor is wrong — see `pinGas` in `execute.ts` for the full reasoning. Carries both numbers so a
28
+ * caller can decide to retry against a different RPC rather than re-parse the message.
29
+ */
30
+ export declare class GasEstimateBelowFloorError extends AbxSdkError {
31
+ readonly estimate: bigint;
32
+ readonly floor: bigint;
33
+ constructor(estimate: bigint, floor: bigint);
34
+ }
35
+ /**
36
+ * No signing key resolved. SINGLE env name: `ABX_DEPLOYER_PK` — thrown by {@link makeWalletClient}
37
+ * and {@link envSigningKey} (clients.ts). Names the two retired names explicitly (`SEPOLIA_FUNDED_PK`
38
+ * / `SEPOLIA_WALLET_PK`) rather than just omitting them, because a caller upgrading from an older
39
+ * alpha has one of those set in their `.env` and would otherwise see a plain "no key found" with no
40
+ * clue that the key IS there, just under a name the SDK no longer reads.
41
+ */
42
+ export declare class MissingSigningKeyError extends AbxSdkError {
43
+ constructor();
44
+ }
45
+ /** The five bootstrap-or-refuse trust anchors / singletons `ensureFactory` & co. (anchors.ts)
46
+ * resolve. */
47
+ export type AnchorKind = 'factory' | 'series-factory' | 'series-code-factory' | 'renderer' | 'seed-source';
48
+ /**
49
+ * A trust anchor {@link AnchorKind} that `ensureFactory`/`ensureSeriesFactory`/
50
+ * `ensureSeriesCodeFactory` (anchors.ts) could not resolve to a usable address, with
51
+ * `allowBootstrap` false — the caller must either point at a working one (override / env /
52
+ * manifest) or opt in to deploying a private one. Carries structured `detail` + `address` instead
53
+ * of a formatted sentence: the SDK doesn't know a UX's flag names or chain-key strings, so it never
54
+ * composes the actual guidance text itself — that's the CLI's `refuseMissingFactory`, which catches
55
+ * this and names the env var / `--bootstrap-factory` / the chain.
56
+ */
57
+ export declare class AnchorUnavailableError extends AbxSdkError {
58
+ readonly anchor: AnchorKind;
59
+ readonly detail: 'no-code' | 'stale-version' | 'not-configured';
60
+ readonly address?: Address;
61
+ constructor(anchor: AnchorKind, detail: 'no-code' | 'stale-version' | 'not-configured', address?: Address);
62
+ }
63
+ //# sourceMappingURL=errors.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,OAAO,EAAE,GAAG,EAAC,MAAM,MAAM,CAAC;AAEvC;;;;;;;GAOG;AACH,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,WAAW;IAC9C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC;gBACT,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG;CAMpC;AAED;;;;;;GAMG;AACH,qBAAa,0BAA2B,SAAQ,WAAW;IACzD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBACX,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAW5C;AAED;;;;;;GAMG;AACH,qBAAa,sBAAuB,SAAQ,WAAW;;CAQtD;AAED;eACe;AACf,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,gBAAgB,GAAG,qBAAqB,GAAG,UAAU,GAAG,aAAa,CAAC;AAE3G;;;;;;;;GAQG;AACH,qBAAa,sBAAuB,SAAQ,WAAW;IACrD,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,eAAe,GAAG,gBAAgB,CAAC;IAChE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;gBACf,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,GAAG,eAAe,GAAG,gBAAgB,EAAE,OAAO,CAAC,EAAE,OAAO;CAO1G"}
package/dist/errors.js ADDED
@@ -0,0 +1,85 @@
1
+ /**
2
+ * The SDK's error taxonomy — deliberately minimal. A caller that wants to react to a SPECIFIC
3
+ * failure (retry a stale estimate, surface a revert's tx hash) should catch by TYPE, not by
4
+ * parsing `.message`; every SDK-thrown error a caller is expected to distinguish extends this,
5
+ * following the same `name` + typed-fields convention `AbxServiceError` already uses (service.ts).
6
+ * This module stays small on purpose — it grows only when a real caller needs a new type to catch,
7
+ * not as a speculative taxonomy of everything that could go wrong.
8
+ */
9
+ export class AbxSdkError extends Error {
10
+ constructor(message) {
11
+ super(message);
12
+ this.name = 'AbxSdkError';
13
+ }
14
+ }
15
+ /**
16
+ * A sent transaction MINED with `status: 'reverted'`. Thrown by {@link makeHotSender} (and anything
17
+ * else driving `SendTx`) instead of letting a revert masquerade as a "confirmed" send — carries the
18
+ * tx hash so a caller can look it up on an explorer without re-parsing a message string.
19
+ */
20
+ export class TxRevertedError extends AbxSdkError {
21
+ op;
22
+ txHash;
23
+ constructor(op, txHash) {
24
+ super(`${op} reverted (${txHash})`);
25
+ this.name = 'TxRevertedError';
26
+ this.op = op;
27
+ this.txHash = txHash;
28
+ }
29
+ }
30
+ /**
31
+ * `pinGas`'s refusal: every estimate attempt came back below the transaction's PROVABLE gas floor
32
+ * (`PreparedTx.gasFloor` — EVM code deposit at exactly 200 gas/byte, and nothing else is physics).
33
+ * That is proof the node answering the estimate hasn't seen the target's deploy block yet, not that
34
+ * the floor is wrong — see `pinGas` in `execute.ts` for the full reasoning. Carries both numbers so a
35
+ * caller can decide to retry against a different RPC rather than re-parse the message.
36
+ */
37
+ export class GasEstimateBelowFloorError extends AbxSdkError {
38
+ estimate;
39
+ floor;
40
+ constructor(estimate, floor) {
41
+ super(`Refusing to send: the RPC estimated ${estimate} gas for a transaction that provably needs at least ${floor} ` +
42
+ `(storing ${floor / 200n} bytes on-chain costs 200 gas/byte in code deposit alone). An estimate below the floor means the node ` +
43
+ `is answering from stale state — usually it has not seen the contract's deploy block yet, so the call looks like it is going to ` +
44
+ `an empty account. Sending this would revert DeploymentFailed() and burn the gas. Retry in a few seconds, or use a different RPC.`);
45
+ this.name = 'GasEstimateBelowFloorError';
46
+ this.estimate = estimate;
47
+ this.floor = floor;
48
+ }
49
+ }
50
+ /**
51
+ * No signing key resolved. SINGLE env name: `ABX_DEPLOYER_PK` — thrown by {@link makeWalletClient}
52
+ * and {@link envSigningKey} (clients.ts). Names the two retired names explicitly (`SEPOLIA_FUNDED_PK`
53
+ * / `SEPOLIA_WALLET_PK`) rather than just omitting them, because a caller upgrading from an older
54
+ * alpha has one of those set in their `.env` and would otherwise see a plain "no key found" with no
55
+ * clue that the key IS there, just under a name the SDK no longer reads.
56
+ */
57
+ export class MissingSigningKeyError extends AbxSdkError {
58
+ constructor() {
59
+ super('No signing key found. Set ABX_DEPLOYER_PK in your .env. ' +
60
+ '(SEPOLIA_FUNDED_PK and SEPOLIA_WALLET_PK are no longer read — rename the key to ABX_DEPLOYER_PK.)');
61
+ this.name = 'MissingSigningKeyError';
62
+ }
63
+ }
64
+ /**
65
+ * A trust anchor {@link AnchorKind} that `ensureFactory`/`ensureSeriesFactory`/
66
+ * `ensureSeriesCodeFactory` (anchors.ts) could not resolve to a usable address, with
67
+ * `allowBootstrap` false — the caller must either point at a working one (override / env /
68
+ * manifest) or opt in to deploying a private one. Carries structured `detail` + `address` instead
69
+ * of a formatted sentence: the SDK doesn't know a UX's flag names or chain-key strings, so it never
70
+ * composes the actual guidance text itself — that's the CLI's `refuseMissingFactory`, which catches
71
+ * this and names the env var / `--bootstrap-factory` / the chain.
72
+ */
73
+ export class AnchorUnavailableError extends AbxSdkError {
74
+ anchor;
75
+ detail;
76
+ address;
77
+ constructor(anchor, detail, address) {
78
+ super(`${anchor} trust anchor unavailable (${detail}${address ? `: ${address}` : ''})`);
79
+ this.name = 'AnchorUnavailableError';
80
+ this.anchor = anchor;
81
+ this.detail = detail;
82
+ this.address = address;
83
+ }
84
+ }
85
+ //# sourceMappingURL=errors.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,eAAgB,SAAQ,WAAW;IACrC,EAAE,CAAS;IACX,MAAM,CAAM;IACrB,YAAY,EAAU,EAAE,MAAW;QACjC,KAAK,CAAC,GAAG,EAAE,cAAc,MAAM,GAAG,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,0BAA2B,SAAQ,WAAW;IAChD,QAAQ,CAAS;IACjB,KAAK,CAAS;IACvB,YAAY,QAAgB,EAAE,KAAa;QACzC,KAAK,CACH,uCAAuC,QAAQ,uDAAuD,KAAK,GAAG;YAC5G,YAAY,KAAK,GAAG,IAAI,wGAAwG;YAChI,iIAAiI;YACjI,kIAAkI,CACrI,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;QACzC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,sBAAuB,SAAQ,WAAW;IACrD;QACE,KAAK,CACH,0DAA0D;YACxD,mGAAmG,CACtG,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAMD;;;;;;;;GAQG;AACH,MAAM,OAAO,sBAAuB,SAAQ,WAAW;IAC5C,MAAM,CAAa;IACnB,MAAM,CAAiD;IACvD,OAAO,CAAW;IAC3B,YAAY,MAAkB,EAAE,MAAsD,EAAE,OAAiB;QACvG,KAAK,CAAC,GAAG,MAAM,8BAA8B,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACxF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF"}
@@ -0,0 +1,115 @@
1
+ /**
2
+ * Gas limits for a sequenced transaction — decided HERE, once, rather than re-read at signing time.
3
+ *
4
+ * The failure this exists to prevent, in full, because it is not obvious and it cost a reporter every
5
+ * `deploy-code` attempt of a session: a project deploys in two transactions, and the second targets
6
+ * the contract the first just created. If the node answering `eth_estimateGas` has not yet seen the
7
+ * deploy block, the target looks like an account with no code — and an estimate for a call to a
8
+ * codeless account is just the calldata cost, around 200k. That number is then sent as the gas limit.
9
+ * Once the contract does exist the same call needs ~941k, because storing a program on-chain is
10
+ * dominated by CREATE code deposit at ~200 gas per byte. The CREATE receives 63/64 of a budget that
11
+ * cannot cover the deposit, returns 0, and Solady's `SSTORE2.write` reverts `DeploymentFailed()` — a
12
+ * revert that reads like a contract bug and is really an out-of-gas.
13
+ *
14
+ * (Measured, from the real transactions: `gasLimit 201,616 / gasUsed 198,870` and
15
+ * `gasLimit 169,301 / gasUsed 166,810` — 98.6% and 98.5% of their limits. Replaying those payloads
16
+ * against a codeless address reproduces both limits to the gas; against the real contract the same
17
+ * calls estimate at 941,331.)
18
+ *
19
+ * The deploy loop already pinned the *nonce* against exactly this read-after-write lag on a
20
+ * distributed RPC. The rule generalizes, and it is the reason this module exists: **anything read at
21
+ * send time on a distributed RPC needs pinning, not just the nonce.**
22
+ */
23
+ import type { Account, Address, Hex, PublicClient, TransactionReceipt, WalletClient } from 'viem';
24
+ import type { PreparedTx } from './ops.js';
25
+ /**
26
+ * Wait until `address` has code from THIS client's point of view. A deploy receipt proves the
27
+ * contract exists on chain; it does not prove the node answering the next request has caught up.
28
+ * Bounded — on timeout we proceed and let the gas floor carry it, since a slow RPC is not a reason
29
+ * to refuse to continue a deploy that already spent money.
30
+ */
31
+ export declare function waitForCodeAt(client: PublicClient, address: Address, timeoutMs?: number): Promise<boolean>;
32
+ /**
33
+ * Decide a transaction's gas limit once, here.
34
+ *
35
+ * The important design point, because the obvious approach is wrong: when an estimate looks too low
36
+ * we do **not** substitute a computed number. A caller can only compute the *provable* part of a
37
+ * payload's cost (see `PreparedTx.gasFloor` — code deposit is 200 gas/byte and nothing else is
38
+ * physics); the same setup multicall also carries schema writes, dependency legs, URI legs and
39
+ * mints, whose cost we cannot derive without simulating them. A "probably enough" constant is a
40
+ * number tuned to whatever case was in front of its author: it papers over the symptom, then
41
+ * under-funds the next payload that carries a few more legs, producing the identical
42
+ * `DeploymentFailed()` with a fresh mystery attached.
43
+ *
44
+ * So the floor is used as a **detector**. An estimate below a provable minimum is not "low", it is
45
+ * *impossible* — proof that the node answering us is looking at the wrong state (typically it has
46
+ * not seen the deploy block yet, so the target reads as an account with no code and the estimate
47
+ * comes back as the calldata cost alone). The right response to a broken measurement is to take it
48
+ * again, and if it stays broken, to refuse — sending a transaction we can prove is under-funded
49
+ * would burn the gas AND orphan the contract.
50
+ *
51
+ * When the estimate IS plausible it is trusted, plus headroom for state drift between estimate and
52
+ * inclusion.
53
+ */
54
+ export declare function pinGas(client: PublicClient, tx: {
55
+ from: Address;
56
+ to: Address | null;
57
+ data: Hex;
58
+ value?: Hex;
59
+ gasFloor?: Hex;
60
+ }, opts?: {
61
+ attempts?: number;
62
+ delayMs?: number;
63
+ }): Promise<bigint>;
64
+ /** Sign + broadcast one {@link PreparedTx} and return its mined receipt (for event parsing). The
65
+ * SDK's one send-injection point: a hot key ({@link makeHotSender}), a browser wallet (a
66
+ * `WalletSession`), or anything else a caller wires up — the SDK never picks or performs the
67
+ * signing itself. */
68
+ export type SendTx = (tx: PreparedTx) => Promise<TransactionReceipt>;
69
+ /** Progress from a {@link SendTx} built by {@link makeHotSender}, so a caller can narrate without
70
+ * the SDK printing anything itself (the SDK never prints — see clients.ts / chunks.ts for the same
71
+ * `onEvent` pattern). */
72
+ export type SendEvent = {
73
+ kind: 'sending';
74
+ tx: PreparedTx;
75
+ } | {
76
+ kind: 'mined';
77
+ receipt: TransactionReceipt;
78
+ tx: PreparedTx;
79
+ };
80
+ /**
81
+ * Build a {@link SendTx} that signs with an env-style hot key and broadcasts — the generalization of
82
+ * what used to be hand-rolled per call site (a deploy-then-setup loop in the CLI, the hot lane in
83
+ * `signer.ts`, the chunk-staging sender in `ownerops.ts`): one function that gets the read-after-
84
+ * write-lag handling right ONCE.
85
+ *
86
+ * Two lags, pinned once at construction / tracked locally per send, rather than re-read at send time:
87
+ * - the NONCE — fetched once here, then incremented locally per tx. Right after a tx is mined a
88
+ * distributed RPC (e.g. Alchemy) can briefly serve a stale `pending` transaction count
89
+ * (read-after-write lag), so re-fetching it for the NEXT send in the same sequence risks reusing
90
+ * the just-spent nonce — the tx it already has in the mempool rejects the duplicate as
91
+ * "replacement transaction underpriced", and that send is silently lost.
92
+ * - GAS, one field over: a tx after the first in a sequence may target a contract an EARLIER tx in
93
+ * this same sequence just created. If the node answering `eth_estimateGas` hasn't seen that
94
+ * block yet, the target looks codeless and the estimate comes back as the calldata cost alone —
95
+ * see `pinGas` above for the full story (and the measured numbers). So every send after the
96
+ * first waits for its target's code to be visible before estimating.
97
+ *
98
+ * Every send: wait for code at the target when it's not the first send in this sender's sequence
99
+ * (mirrors the exact rule the deploy-code hot lane hand-rolled: every tx after the first, since the
100
+ * first is what creates what the rest target), pin the gas (a provable floor detector, never a
101
+ * substitute limit), broadcast, wait for the receipt, and throw a typed {@link TxRevertedError} —
102
+ * carrying the tx hash — on a `reverted` status rather than reporting a burned transaction as
103
+ * "confirmed".
104
+ */
105
+ export declare function makeHotSender(args: {
106
+ wallet: WalletClient;
107
+ account: Account;
108
+ publicClient: PublicClient;
109
+ onEvent?: (e: SendEvent) => void;
110
+ }): SendTx;
111
+ /** Send a list of prepared txs, in order, via `send`; returns their receipts in the same order.
112
+ * A small convenience for the common "just run this sequence" case — narration (if any) rides
113
+ * `send`'s own `onEvent`, not a callback here. */
114
+ export declare function runPrepared(txs: PreparedTx[], send: SendTx): Promise<TransactionReceipt[]>;
115
+ //# sourceMappingURL=execute.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../src/execute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,kBAAkB,EAAE,YAAY,EAAC,MAAM,MAAM,CAAC;AAChG,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,UAAU,CAAC;AAGzC;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAQhH;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,MAAM,CAC1B,MAAM,EAAE,YAAY,EACpB,EAAE,EAAE;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,GAAG,CAAC;IAAC,KAAK,CAAC,EAAE,GAAG,CAAC;IAAC,QAAQ,CAAC,EAAE,GAAG,CAAA;CAAC,EAC/E,IAAI,GAAE;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAM,GAC/C,OAAO,CAAC,MAAM,CAAC,CA8BjB;AAED;;;sBAGsB;AACtB,MAAM,MAAM,MAAM,GAAG,CAAC,EAAE,EAAE,UAAU,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAErE;;0BAE0B;AAC1B,MAAM,MAAM,SAAS,GACjB;IAAC,IAAI,EAAE,SAAS,CAAC;IAAC,EAAE,EAAE,UAAU,CAAA;CAAC,GACjC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,kBAAkB,CAAC;IAAC,EAAE,EAAE,UAAU,CAAA;CAAC,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,YAAY,CAAC;IAC3B,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,KAAK,IAAI,CAAC;CAClC,GAAG,MAAM,CAkCT;AAED;;mDAEmD;AACnD,wBAAsB,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAIhG"}
@@ -0,0 +1,142 @@
1
+ import { GasEstimateBelowFloorError, TxRevertedError } from './errors.js';
2
+ /**
3
+ * Wait until `address` has code from THIS client's point of view. A deploy receipt proves the
4
+ * contract exists on chain; it does not prove the node answering the next request has caught up.
5
+ * Bounded — on timeout we proceed and let the gas floor carry it, since a slow RPC is not a reason
6
+ * to refuse to continue a deploy that already spent money.
7
+ */
8
+ export async function waitForCodeAt(client, address, timeoutMs = 15_000) {
9
+ const deadline = Date.now() + timeoutMs;
10
+ for (;;) {
11
+ const code = await client.getCode({ address }).catch(() => undefined);
12
+ if (code && code !== '0x')
13
+ return true;
14
+ if (Date.now() >= deadline)
15
+ return false;
16
+ await new Promise((r) => setTimeout(r, 750));
17
+ }
18
+ }
19
+ /**
20
+ * Decide a transaction's gas limit once, here.
21
+ *
22
+ * The important design point, because the obvious approach is wrong: when an estimate looks too low
23
+ * we do **not** substitute a computed number. A caller can only compute the *provable* part of a
24
+ * payload's cost (see `PreparedTx.gasFloor` — code deposit is 200 gas/byte and nothing else is
25
+ * physics); the same setup multicall also carries schema writes, dependency legs, URI legs and
26
+ * mints, whose cost we cannot derive without simulating them. A "probably enough" constant is a
27
+ * number tuned to whatever case was in front of its author: it papers over the symptom, then
28
+ * under-funds the next payload that carries a few more legs, producing the identical
29
+ * `DeploymentFailed()` with a fresh mystery attached.
30
+ *
31
+ * So the floor is used as a **detector**. An estimate below a provable minimum is not "low", it is
32
+ * *impossible* — proof that the node answering us is looking at the wrong state (typically it has
33
+ * not seen the deploy block yet, so the target reads as an account with no code and the estimate
34
+ * comes back as the calldata cost alone). The right response to a broken measurement is to take it
35
+ * again, and if it stays broken, to refuse — sending a transaction we can prove is under-funded
36
+ * would burn the gas AND orphan the contract.
37
+ *
38
+ * When the estimate IS plausible it is trusted, plus headroom for state drift between estimate and
39
+ * inclusion.
40
+ */
41
+ export async function pinGas(client, tx, opts = {}) {
42
+ const floor = tx.gasFloor ? BigInt(tx.gasFloor) : 0n;
43
+ const attempts = opts.attempts ?? 3;
44
+ let lastEstimate = null;
45
+ let lastError;
46
+ for (let i = 0; i < attempts; i++) {
47
+ try {
48
+ const estimate = await client.estimateGas({
49
+ account: tx.from,
50
+ to: tx.to ?? undefined,
51
+ data: tx.data,
52
+ ...(tx.value && tx.value !== '0x0' ? { value: BigInt(tx.value) } : {}),
53
+ });
54
+ // Plausible (or nothing provable to check it against) → trust it.
55
+ if (estimate >= floor)
56
+ return (estimate * 125n) / 100n;
57
+ lastEstimate = estimate;
58
+ }
59
+ catch (err) {
60
+ lastError = err;
61
+ // A revert during estimation is a real answer about the transaction, not a lagging node —
62
+ // surface it immediately, since its message ("caller is not the owner") is the useful part.
63
+ if (floor === 0n)
64
+ throw err;
65
+ }
66
+ if (i < attempts - 1)
67
+ await new Promise((r) => setTimeout(r, opts.delayMs ?? 1_500));
68
+ }
69
+ if (lastEstimate !== null) {
70
+ throw new GasEstimateBelowFloorError(lastEstimate, floor);
71
+ }
72
+ throw lastError instanceof Error ? lastError : new Error('gas estimation failed');
73
+ }
74
+ /**
75
+ * Build a {@link SendTx} that signs with an env-style hot key and broadcasts — the generalization of
76
+ * what used to be hand-rolled per call site (a deploy-then-setup loop in the CLI, the hot lane in
77
+ * `signer.ts`, the chunk-staging sender in `ownerops.ts`): one function that gets the read-after-
78
+ * write-lag handling right ONCE.
79
+ *
80
+ * Two lags, pinned once at construction / tracked locally per send, rather than re-read at send time:
81
+ * - the NONCE — fetched once here, then incremented locally per tx. Right after a tx is mined a
82
+ * distributed RPC (e.g. Alchemy) can briefly serve a stale `pending` transaction count
83
+ * (read-after-write lag), so re-fetching it for the NEXT send in the same sequence risks reusing
84
+ * the just-spent nonce — the tx it already has in the mempool rejects the duplicate as
85
+ * "replacement transaction underpriced", and that send is silently lost.
86
+ * - GAS, one field over: a tx after the first in a sequence may target a contract an EARLIER tx in
87
+ * this same sequence just created. If the node answering `eth_estimateGas` hasn't seen that
88
+ * block yet, the target looks codeless and the estimate comes back as the calldata cost alone —
89
+ * see `pinGas` above for the full story (and the measured numbers). So every send after the
90
+ * first waits for its target's code to be visible before estimating.
91
+ *
92
+ * Every send: wait for code at the target when it's not the first send in this sender's sequence
93
+ * (mirrors the exact rule the deploy-code hot lane hand-rolled: every tx after the first, since the
94
+ * first is what creates what the rest target), pin the gas (a provable floor detector, never a
95
+ * substitute limit), broadcast, wait for the receipt, and throw a typed {@link TxRevertedError} —
96
+ * carrying the tx hash — on a `reverted` status rather than reporting a burned transaction as
97
+ * "confirmed".
98
+ */
99
+ export function makeHotSender(args) {
100
+ const { wallet, account, publicClient } = args;
101
+ const notify = args.onEvent ?? (() => { });
102
+ let nonce;
103
+ let sent = 0;
104
+ return async (tx) => {
105
+ if (nonce === undefined) {
106
+ // Fetch once, then increment locally per send — see the read-after-write-lag reasoning above.
107
+ nonce = await publicClient.getTransactionCount({ address: account.address, blockTag: 'pending' });
108
+ }
109
+ // The SAME lag, one field over: every send after the first in this sender's sequence may target
110
+ // what an earlier send just created.
111
+ if (sent > 0 && tx.to)
112
+ await waitForCodeAt(publicClient, tx.to);
113
+ const gas = await pinGas(publicClient, { from: account.address, to: tx.to, data: tx.data, value: tx.value, gasFloor: tx.gasFloor });
114
+ notify({ kind: 'sending', tx });
115
+ const hash = await wallet.sendTransaction({
116
+ to: tx.to ?? undefined,
117
+ data: tx.data,
118
+ value: tx.value && tx.value !== '0x0' ? BigInt(tx.value) : undefined,
119
+ account,
120
+ chain: wallet.chain,
121
+ nonce,
122
+ gas,
123
+ });
124
+ nonce += 1;
125
+ sent += 1;
126
+ const receipt = await publicClient.waitForTransactionReceipt({ hash });
127
+ if (receipt.status !== 'success')
128
+ throw new TxRevertedError(tx.op, hash);
129
+ notify({ kind: 'mined', receipt, tx });
130
+ return receipt;
131
+ };
132
+ }
133
+ /** Send a list of prepared txs, in order, via `send`; returns their receipts in the same order.
134
+ * A small convenience for the common "just run this sequence" case — narration (if any) rides
135
+ * `send`'s own `onEvent`, not a callback here. */
136
+ export async function runPrepared(txs, send) {
137
+ const receipts = [];
138
+ for (const tx of txs)
139
+ receipts.push(await send(tx));
140
+ return receipts;
141
+ }
142
+ //# sourceMappingURL=execute.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"execute.js","sourceRoot":"","sources":["../src/execute.ts"],"names":[],"mappings":"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"}