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

package/dist/anchors.js

@@ -0,0 +1,290 @@
+import { oneOfOneImageAbi, oneOfOneImageFactoryAbi, seriesImageAbi, seriesImageFactoryAbi, abxMetadataRendererAbi } from './abi/index.js';
+import { resolveFactory, resolveSeriesFactory, resolveRenderer, resolveSeriesCodeFactory, resolveSeedSource } from './deployments.js';
+import { predictRenderer, predictSeedSource } from './create2.js';
+import { deployFactory, deploySeriesFactory, deployRenderer, deploySeriesCodeFactory, deploySeedSource } from './deploy.js';
+import { discoverDeployBlock } from './reconstruct.js';
+import { AnchorUnavailableError } from './errors.js';
+// ── the canonical 1/1 clone factory ───────────────────────────────────────────
+/** Is the deployed factory this build's version? Reads its implementation and probes the
+ *  NEWEST capability the current implementation exposes — `totalSupply()` (the live-count
+ *  read) — so an older factory whose impl predates it is detected and a fresh, source-current
+ *  (and thus Etherscan-verifiable) one deployed. A stale impl reverts the probe. (Bump this to
+ *  the newest capability with each impl change.) */
+export async function isCurrentFactory(publicClient, factory) {
+    try {
+        const impl = (await publicClient.readContract({
+            address: factory,
+            abi: oneOfOneImageFactoryAbi,
+            functionName: 'implementation',
+        }));
+        // `totalSupply()` is a view → readContract; it reverts on an impl that predates it.
+        await publicClient.readContract({ address: impl, abi: oneOfOneImageAbi, functionName: 'totalSupply' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get (or deploy) the chain's canonical 1/1 clone factory — the trust anchor: a factory is THE
+ * address platforms allowlist by. Resolves the manifest (override → env → manifest); on a chain
+ * with no current entry, deploys a fresh one when `allowBootstrap` is set (else throws
+ * {@link AnchorUnavailableError} so the caller can refuse with guidance instead of silently
+ * fragmenting trust across duplicate "canonical" factories).
+ */
+export async function ensureFactory(publicClient, send, opts) {
+    const notify = opts.onEvent ?? (() => { });
+    // Resolve the canonical factory from the shipped manifest (flag → env → manifest); on a chain
+    // with no entry, deploy a fresh trust anchor and tell the operator how to reuse it.
+    const known = resolveFactory(opts.chainId, opts.override);
+    if (known) {
+        // sanity: is there code there, and is it *this* version of the factory?
+        const code = await publicClient.getCode({ address: known });
+        if (code && code !== '0x') {
+            if (await isCurrentFactory(publicClient, known)) {
+                notify({ anchor: 'factory', kind: 'resolved', address: known });
+                return known;
+            }
+            if (!opts.allowBootstrap)
+                throw new AnchorUnavailableError('factory', 'stale-version', known);
+            notify({ anchor: 'factory', kind: 'stale', address: known, reason: 'stale-version' });
+        }
+        else {
+            if (!opts.allowBootstrap)
+                throw new AnchorUnavailableError('factory', 'no-code', known);
+            notify({ anchor: 'factory', kind: 'stale', address: known, reason: 'no-code' });
+        }
+    }
+    if (!known && !opts.allowBootstrap)
+        throw new AnchorUnavailableError('factory', 'not-configured');
+    notify({ anchor: 'factory', kind: 'deploying' });
+    const { factory, implementation, txHash } = await deployFactory(send, publicClient);
+    notify({ anchor: 'factory', kind: 'deployed', address: factory, implementation, txHash, inManifest: false });
+    return factory;
+}
+// ── the canonical Series trust anchor ─────────────────────────────────────────
+/** Is the deployed Series factory this build's version? Probes the impl for `nextTokenId()`
+ *  (the Series-specific issuance cursor), which a stale/incompatible impl won't expose. */
+export async function isCurrentSeriesFactory(publicClient, factory) {
+    try {
+        const impl = (await publicClient.readContract({
+            address: factory,
+            abi: seriesImageFactoryAbi,
+            functionName: 'implementation',
+        }));
+        // Probe the NEWEST capability the current implementation exposes — ERC-165 support for the
+        // IAbxSequentialMint primitive (mint(address) → uint256, the fixed-price-minter target).
+        // A pre-minter-spine impl (mint returns void, id not advertised) returns false → a fresh,
+        // source-current factory is deployed. (Bump this to the newest capability with each impl change.)
+        return (await publicClient.readContract({
+            address: impl,
+            abi: seriesImageAbi,
+            functionName: 'supportsInterface',
+            args: ['0x6a627842'], // type(IAbxSequentialMint).interfaceId = bytes4(keccak256("mint(address)"))
+        }));
+    }
+    catch {
+        return false;
+    }
+}
+/** Get (or deploy) the chain's `SeriesImageFactory` — the multi-token trust anchor, the sibling
+ *  of {@link ensureFactory}. Ownerless + immutable; one deployment serves every Series. */
+export async function ensureSeriesFactory(publicClient, send, opts) {
+    const notify = opts.onEvent ?? (() => { });
+    const known = resolveSeriesFactory(opts.chainId, opts.override);
+    if (known) {
+        const code = await publicClient.getCode({ address: known });
+        if (code && code !== '0x' && (await isCurrentSeriesFactory(publicClient, known))) {
+            notify({ anchor: 'series-factory', kind: 'resolved', address: known });
+            return known;
+        }
+        if (!opts.allowBootstrap)
+            throw new AnchorUnavailableError('series-factory', 'stale-version', known);
+        notify({ anchor: 'series-factory', kind: 'stale', address: known, reason: 'stale-version' });
+    }
+    if (!known && !opts.allowBootstrap)
+        throw new AnchorUnavailableError('series-factory', 'not-configured');
+    notify({ anchor: 'series-factory', kind: 'deploying' });
+    const { factory, implementation, txHash } = await deploySeriesFactory(send, publicClient);
+    notify({ anchor: 'series-factory', kind: 'deployed', address: factory, implementation, txHash, inManifest: false });
+    return factory;
+}
+// ── the canonical on-chain renderer ────────────────────────────────────────────
+/** Is the configured renderer the spec version this build expects (v4 — the computed `abx_params`
+ *  object, enumerated from chain, plus `animation_url` wrapped as `data:text/html;base64` for the
+ *  inline/reader representations)? A behind-spec renderer is treated as stale so {@link ensureRenderer}
+ *  deploys a fresh one (greenfield redeploy-freely: this number is what tells the CLI a deployed
+ *  renderer predates a projection the current build emits). A v4 renderer is safe on ANY token —
+ *  pointed at a legacy implementation it simply emits no params block. Bump in lockstep with
+ *  `AbxMetadataRenderer.SPEC_VERSION`. */
+export async function isCurrentRenderer(publicClient, renderer) {
+    try {
+        const v = (await publicClient.readContract({
+            address: renderer,
+            abi: abxMetadataRendererAbi,
+            functionName: 'specVersion',
+        }));
+        return v === 4n;
+    }
+    catch {
+        return false;
+    }
+}
+/** Get (or deploy) the chain's shared `AbxMetadataRenderer` — the on-chain metadata
+ *  renderer that fully-on-chain tokens point at. Stateless + shared, so one deployment
+ *  serves every project; redeployed only if missing or a stale spec version. */
+export async function ensureRenderer(publicClient, send, opts) {
+    const notify = opts.onEvent ?? (() => { });
+    const known = resolveRenderer(opts.chainId, opts.override);
+    if (known) {
+        const code = await publicClient.getCode({ address: known });
+        if (code && code !== '0x' && (await isCurrentRenderer(publicClient, known))) {
+            notify({ anchor: 'renderer', kind: 'resolved', address: known });
+            return known;
+        }
+        notify({ anchor: 'renderer', kind: 'stale', address: known, reason: 'stale-version' });
+    }
+    // The current renderer is CREATE2-deterministic, so it may already exist at its predicted address
+    // (deployed by the forge script, or a prior lazy deploy, with the manifest not yet updated). Check
+    // there before deploying — self-healing, and never a duplicate. `deployRenderer` lands here too.
+    const predicted = predictRenderer();
+    if (!known || known.toLowerCase() !== predicted.toLowerCase()) {
+        const pcode = await publicClient.getCode({ address: predicted });
+        if (pcode && pcode !== '0x' && (await isCurrentRenderer(publicClient, predicted))) {
+            notify({ anchor: 'renderer', kind: 'canonical', address: predicted });
+            return predicted;
+        }
+    }
+    notify({ anchor: 'renderer', kind: 'deploying' });
+    const { renderer, specVersion, txHash } = await deployRenderer(send, publicClient);
+    notify({ anchor: 'renderer', kind: 'deployed', address: renderer, specVersion, txHash, inManifest: false });
+    return renderer;
+}
+// ── the code-project (SeriesCode) trust anchor ────────────────────────────────
+/** The code-project trust anchor: use the canonical factory, else deploy one (a sandbox /
+ *  fresh chain — libraries linked in-flight; see {@link deploySeriesCodeFactory}). Unlike the
+ *  1/1 and Series factories there is no version probe (no `isCurrentSeriesCodeFactory` — a
+ *  configured factory with code is always accepted) and no CREATE2 self-heal (its bytecode is
+ *  link-time-linked against two libraries deployed by plain CREATE, so nothing about its address
+ *  is predictable — see {@link deploySeriesCodeFactory}'s own doc comment). */
+export async function ensureSeriesCodeFactory(publicClient, send, opts) {
+    const notify = opts.onEvent ?? (() => { });
+    const known = resolveSeriesCodeFactory(opts.chainId, opts.override);
+    if (known) {
+        const code = await publicClient.getCode({ address: known });
+        if (code && code !== '0x') {
+            notify({ anchor: 'series-code-factory', kind: 'resolved', address: known });
+            return known;
+        }
+        if (!opts.allowBootstrap)
+            throw new AnchorUnavailableError('series-code-factory', 'no-code', known);
+        notify({ anchor: 'series-code-factory', kind: 'stale', address: known, reason: 'no-code' });
+    }
+    if (!known && !opts.allowBootstrap)
+        throw new AnchorUnavailableError('series-code-factory', 'not-configured');
+    notify({ anchor: 'series-code-factory', kind: 'deploying' });
+    const r = await deploySeriesCodeFactory(send, publicClient);
+    notify({
+        anchor: 'series-code-factory',
+        kind: 'deployed',
+        address: r.factory,
+        implementation: r.implementation,
+        paramsLib: r.paramsLib,
+        codeLib: r.codeLib,
+        txHash: r.txHash,
+        inManifest: false,
+    });
+    return r.factory;
+}
+// ── the canonical seed source ─────────────────────────────────────────────────
+/** The canonical seed source — a clean keyless singleton (like the renderer / chunk store / minter):
+ *  single-profile, so CREATE2 lands at THE canonical address on any chain. Resolves from the manifest,
+ *  self-heals to the predicted address (deployed but not yet repointed), else auto-deploys via CREATE2. */
+export async function ensureSeedSource(publicClient, send, opts) {
+    const notify = opts.onEvent ?? (() => { });
+    const known = resolveSeedSource(opts.chainId);
+    if (known) {
+        const code = await publicClient.getCode({ address: known });
+        if (code && code !== '0x') {
+            notify({ anchor: 'seed-source', kind: 'resolved', address: known });
+            return known;
+        }
+    }
+    const predicted = predictSeedSource();
+    if (!known || known.toLowerCase() !== predicted.toLowerCase()) {
+        const pcode = await publicClient.getCode({ address: predicted });
+        if (pcode && pcode !== '0x') {
+            notify({ anchor: 'seed-source', kind: 'canonical', address: predicted });
+            return predicted;
+        }
+    }
+    const { seedSource, txHash } = await deploySeedSource(send, publicClient);
+    notify({ anchor: 'seed-source', kind: 'deployed', address: seedSource, txHash, inManifest: false });
+    return seedSource;
+}
+// ── protocol reads: which factory, and from when ──────────────────────────────
+/**
+ * Pick the canonical factory for a clone being added. An explicit override or a stored value
+ * wins; otherwise probe the chain's known factories (SeriesCode, Series, 1/1) for the ONE whose
+ * `isAbxClone` confirms this address, so `abx add` of a code / Series project records the RIGHT
+ * factory and canonicity actually verifies. Without this, `add` defaulted to the 1/1 factory, so a
+ * code/Series clone read `canonical: unverified` (the check ran against the wrong factory). One
+ * multicall, only when the factory isn't already known; falls back to the 1/1 default on any miss/RPC
+ * error (`isAbxClone` shares a selector across all factory ABIs, so one ABI probes them all).
+ */
+export async function detectCanonicalFactory(publicClient, address, opts) {
+    if (opts.override)
+        return opts.override;
+    if (opts.stored)
+        return opts.stored;
+    const known = [resolveSeriesCodeFactory(opts.chainId), resolveSeriesFactory(opts.chainId), resolveFactory(opts.chainId)].filter((f) => !!f);
+    const candidates = [...new Set(known)];
+    if (candidates.length <= 1)
+        return candidates[0]; // nothing to disambiguate
+    try {
+        const results = (await publicClient.multicall({
+            contracts: candidates.map((f) => ({
+                address: f,
+                abi: oneOfOneImageFactoryAbi,
+                functionName: 'isAbxClone',
+                args: [address],
+            })),
+            allowFailure: true,
+        }));
+        const hit = candidates.find((_, i) => results[i]?.status === 'success' && results[i].result === true);
+        if (hit)
+            return hit;
+    }
+    catch {
+        /* RPC hiccup — fall back to the default; canonicity just shows unverified, never wrong */
+    }
+    return resolveFactory(opts.chainId) ?? undefined;
+}
+/**
+ * Resolve the scan floor (fromBlock) for an add/index: an explicit override wins, else the deploy
+ * block the local deploy already stored, else discover it from chain (getCode binary search). It
+ * NEVER silently defaults to genesis — a from-0 full scan of a live chain must be an explicit
+ * opt-in, because on a range-capped RPC it's the difference between an instant index and grinding
+ * millions of blocks (the #1 reason a hosted resolver appears "not to index"). Returns a decimal
+ * block string. Only touches RPC in the discovery fallback (rare — a foreign contract we didn't
+ * deploy here), so the common post-deploy path makes no extra call.
+ */
+export async function resolveScanFloor(publicClient, address, opts = {}) {
+    const notify = opts.onEvent ?? (() => { });
+    if (opts.explicit !== undefined) {
+        if (/^0+$/.test(opts.explicit.trim()))
+            notify({ kind: 'genesis-warning' });
+        return opts.explicit;
+    }
+    if (opts.localFromBlock !== undefined)
+        return opts.localFromBlock; // the deploy stored the exact block
+    const discovered = await discoverDeployBlock(publicClient, address);
+    if (discovered !== null) {
+        notify({ kind: 'discovered', block: discovered });
+        return discovered.toString();
+    }
+    throw new Error(`couldn't determine ${address}'s deploy block (no local record, and on-chain discovery failed — a non-archive RPC?). ` +
+        `Pass --from-block <deployBlock> so indexing starts there instead of sweeping from genesis. ` +
+        `(--from-block 0 forces a full-chain scan if you really want it.)`);
+}
+//# sourceMappingURL=anchors.js.map

package/dist/anchors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchors.js","sourceRoot":"","sources":["../src/anchors.ts"],"names":[],"mappings":"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"}

package/dist/chains.d.ts

@@ -5,23 +5,48 @@ import type { Chain } from 'viem';
  * The protocol is per-EVM-chain (one project = one contract, per chain).
  */
 export declare const CHAINS: Record<string, Chain>;
+/** Every chain key this toolkit ships, for validating an `ABX_CHAIN` before anything tries to use it. */
+export declare const KNOWN_CHAIN_KEYS: string[];
 export declare const DEFAULT_CHAIN_KEY = "base-sepolia";
 export declare function resolveChain(key?: string): Chain;
+/** A supported chain by its EIP-155 id, or undefined. Callers that only carry a chainId (the
+ *  token-api's routes are `/t/<chainId>/…`) need this to reach the chain's metadata. */
+export declare function chainById(chainId: number): Chain | undefined;
+/**
+ * Block-explorer base URL for a chain id, taken from viem's own chain metadata rather than a
+ * hand-maintained table — so adding a chain to {@link CHAINS} brings its explorer along and no
+ * separate list can fall out of sync. Falls back to Etherscan's Sepolia only for an unknown id.
+ *
+ * There was a hardcoded `https://sepolia.etherscan.io` in the token-api dashboard, so every link on
+ * it — contract, tx, address — pointed at Ethereum Sepolia regardless of the chain being served.
+ * Since the default chain is Base Sepolia, that meant the dashboard for a normal `abx demo` sent you
+ * to an explorer where the contract does not exist.
+ */
+export declare function explorerUrl(chainId: number): string;
+/** Env-name suffix for a user-facing key: uppercased, any run of non-alphanumerics collapsed to
+ *  one `_` (`base-sepolia` → `BASE_SEPOLIA`, `my.provider` → `MY_PROVIDER`). Shared by every
+ *  `ABX_<FAMILY>_<NAME>_*` convention (`ABX_RPC_URLS_<CHAIN>`, `ABX_REMOTE_<NAME>_URL/_TOKEN`) so
+ *  the conventions can't drift. Lossy — the normalized form is the canonical name. */
+export declare function envSuffix(name: string): string;
 /** The env var holding RPC endpoints for a chain: per-chain `ABX_RPC_URLS_<CHAIN>` (e.g.
  *  `ABX_RPC_URLS_SEPOLIA`) when set, else the bare `ABX_RPC_URLS` (the active `ABX_CHAIN`). */
 export declare function rpcEnvVar(chainKey: string): string;
 /**
- * The ordered, de-duplicated RPC endpoints for `chainKey`. **Network-scoped**: a
- * per-chain `ABX_RPC_URLS_<CHAIN>` wins when set; otherwise the bare `ABX_RPC_URLS`
- * (understood as "for the active `ABX_CHAIN`"). Both are comma/whitespace-separated
- * lists in preference order — the client fails over across them and `abx doctor`
- * probes + ranks each (e.g. widest `eth_getLogs` range). The bare and per-chain vars
- * are never mixed, so a list for one network can't leak into another; a chainId guard
- * (see `assertChainId`) then verifies the endpoints actually ARE `chainKey`.
+ * The ordered, de-duplicated RPC endpoints for `chainKey`. Precedence is **override → env →
+ * manifest default**, the same `pick()` shape `deployments.ts` uses for every other address:
+ *   - `override` (a `ClientOptions.rpcUrls`, or a single `rpcUrl` the caller already joined) —
+ *     explicit config wins outright, no env involved.
+ *   - env: a per-chain `ABX_RPC_URLS_<CHAIN>` wins when set; otherwise the bare `ABX_RPC_URLS`
+ *     (understood as "for the active `ABX_CHAIN`"). Both are comma/whitespace-separated lists in
+ *     preference order — the client fails over across them and `abx doctor` probes + ranks each
+ *     (e.g. widest `eth_getLogs` range). The bare and per-chain vars are never mixed, so a list for
+ *     one network can't leak into another; a chainId guard (see `assertChainId`) then verifies the
+ *     endpoints actually ARE `chainKey`.
+ *   - manifest: the built-in keyless default for `chainKey`.
  */
-export declare function resolveRpcUrls(chainKey?: string): string[];
+export declare function resolveRpcUrls(chainKey?: string, override?: string | string[]): string[];
 /** The primary RPC endpoint (the first of {@link resolveRpcUrls}). */
-export declare function resolveRpcUrl(chainKey?: string): string;
+export declare function resolveRpcUrl(chainKey?: string, override?: string | string[]): string;
 /** A display-safe form of an RPC URL — host + a redacted key tail (URLs can embed keys). */
 export declare function redactRpcUrl(url: string): string;
 //# sourceMappingURL=chains.d.ts.map

package/dist/chains.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chains.d.ts","sourceRoot":"","sources":["../src/chains.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,KAAK,EAAC,MAAM,MAAM,CAAC;AAGhC;;;;GAIG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAGxC,CAAC;AAEF,eAAO,MAAM,iBAAiB,iBAAiB,CAAC;AAShD,wBAAgB,YAAY,CAAC,GAAG,GAAE,MAA0B,GAAG,KAAK,CAInE;AAED;+FAC+F;AAC/F,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIlD;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,GAAE,MAA0B,GAAG,MAAM,EAAE,CAY7E;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,QAAQ,GAAE,MAA0B,GAAG,MAAM,CAE1E;AAED,4FAA4F;AAC5F,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAShD"}
+{"version":3,"file":"chains.d.ts","sourceRoot":"","sources":["../src/chains.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,KAAK,EAAC,MAAM,MAAM,CAAC;AAGhC;;;;GAIG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAGxC,CAAC;AAEF,yGAAyG;AACzG,eAAO,MAAM,gBAAgB,UAAsB,CAAC;AAGpD,eAAO,MAAM,iBAAiB,iBAAiB,CAAC;AAShD,wBAAgB,YAAY,CAAC,GAAG,GAAE,MAA0B,GAAG,KAAK,CAInE;AAED;wFACwF;AACxF,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAE5D;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;sFAGsF;AACtF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;+FAC+F;AAC/F,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,QAAQ,GAAE,MAA0B,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,CAU3G;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,QAAQ,GAAE,MAA0B,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,CAExG;AAED,4FAA4F;AAC5F,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAShD"}

package/dist/chains.js

@@ -1,5 +1,5 @@
 import { sepolia, baseSepolia } from 'viem/chains';
-import { loadDotEnv } from './env.js';
+import { readEnv } from './util.js';
 /**
  * Chain targets. The SDK is neutral about *which* chain — it takes a target as
  * input — but the toolkit's demo runs on a testnet, so that's the default here.
@@ -9,6 +9,8 @@ export const CHAINS = {
     'base-sepolia': baseSepolia,
     sepolia,
 };
+/** Every chain key this toolkit ships, for validating an `ABX_CHAIN` before anything tries to use it. */
+export const KNOWN_CHAIN_KEYS = Object.keys(CHAINS);
 export const DEFAULT_CHAIN_KEY = 'base-sepolia';
 // Public, keyless endpoints per chain — overridable. A self-hoster points these at
 // their own node; nothing about resolution depends on a particular provider.
@@ -22,27 +24,52 @@ export function resolveChain(key = DEFAULT_CHAIN_KEY) {
         throw new Error(`Unknown chain "${key}". Known: ${Object.keys(CHAINS).join(', ')}`);
     return chain;
 }
+/** A supported chain by its EIP-155 id, or undefined. Callers that only carry a chainId (the
+ *  token-api's routes are `/t/<chainId>/…`) need this to reach the chain's metadata. */
+export function chainById(chainId) {
+    return Object.values(CHAINS).find((c) => c.id === chainId);
+}
+/**
+ * Block-explorer base URL for a chain id, taken from viem's own chain metadata rather than a
+ * hand-maintained table — so adding a chain to {@link CHAINS} brings its explorer along and no
+ * separate list can fall out of sync. Falls back to Etherscan's Sepolia only for an unknown id.
+ *
+ * There was a hardcoded `https://sepolia.etherscan.io` in the token-api dashboard, so every link on
+ * it — contract, tx, address — pointed at Ethereum Sepolia regardless of the chain being served.
+ * Since the default chain is Base Sepolia, that meant the dashboard for a normal `abx demo` sent you
+ * to an explorer where the contract does not exist.
+ */
+export function explorerUrl(chainId) {
+    return chainById(chainId)?.blockExplorers?.default?.url ?? 'https://sepolia.etherscan.io';
+}
+/** Env-name suffix for a user-facing key: uppercased, any run of non-alphanumerics collapsed to
+ *  one `_` (`base-sepolia` → `BASE_SEPOLIA`, `my.provider` → `MY_PROVIDER`). Shared by every
+ *  `ABX_<FAMILY>_<NAME>_*` convention (`ABX_RPC_URLS_<CHAIN>`, `ABX_REMOTE_<NAME>_URL/_TOKEN`) so
+ *  the conventions can't drift. Lossy — the normalized form is the canonical name. */
+export function envSuffix(name) {
+    return name.toUpperCase().replace(/[^A-Z0-9]+/g, '_');
+}
 /** The env var holding RPC endpoints for a chain: per-chain `ABX_RPC_URLS_<CHAIN>` (e.g.
  *  `ABX_RPC_URLS_SEPOLIA`) when set, else the bare `ABX_RPC_URLS` (the active `ABX_CHAIN`). */
 export function rpcEnvVar(chainKey) {
-    // Env var names can't contain hyphens, so a key like `base-sepolia` becomes
-    // `ABX_RPC_URLS_BASE_SEPOLIA` (any non-alphanumeric collapses to `_`).
-    return `ABX_RPC_URLS_${chainKey.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}`;
+    return `ABX_RPC_URLS_${envSuffix(chainKey)}`;
 }
 /**
- * The ordered, de-duplicated RPC endpoints for `chainKey`. **Network-scoped**: a
- * per-chain `ABX_RPC_URLS_<CHAIN>` wins when set; otherwise the bare `ABX_RPC_URLS`
- * (understood as "for the active `ABX_CHAIN`"). Both are comma/whitespace-separated
- * lists in preference order — the client fails over across them and `abx doctor`
- * probes + ranks each (e.g. widest `eth_getLogs` range). The bare and per-chain vars
- * are never mixed, so a list for one network can't leak into another; a chainId guard
- * (see `assertChainId`) then verifies the endpoints actually ARE `chainKey`.
+ * The ordered, de-duplicated RPC endpoints for `chainKey`. Precedence is **override → env →
+ * manifest default**, the same `pick()` shape `deployments.ts` uses for every other address:
+ *   - `override` (a `ClientOptions.rpcUrls`, or a single `rpcUrl` the caller already joined) —
+ *     explicit config wins outright, no env involved.
+ *   - env: a per-chain `ABX_RPC_URLS_<CHAIN>` wins when set; otherwise the bare `ABX_RPC_URLS`
+ *     (understood as "for the active `ABX_CHAIN`"). Both are comma/whitespace-separated lists in
+ *     preference order — the client fails over across them and `abx doctor` probes + ranks each
+ *     (e.g. widest `eth_getLogs` range). The bare and per-chain vars are never mixed, so a list for
+ *     one network can't leak into another; a chainId guard (see `assertChainId`) then verifies the
+ *     endpoints actually ARE `chainKey`.
+ *   - manifest: the built-in keyless default for `chainKey`.
  */
-export function resolveRpcUrls(chainKey = DEFAULT_CHAIN_KEY) {
-    loadDotEnv();
-    // Per-chain override is authoritative when present; bare ABX_RPC_URLS is the
-    // single-/active-chain fallback. They are NOT concatenated — mixing networks is the bug.
-    const list = process.env[rpcEnvVar(chainKey)] ?? process.env.ABX_RPC_URLS ?? '';
+export function resolveRpcUrls(chainKey = DEFAULT_CHAIN_KEY, override) {
+    const overrideList = override === undefined ? undefined : Array.isArray(override) ? override.join(',') : override;
+    const list = overrideList ?? readEnv(rpcEnvVar(chainKey)) ?? readEnv('ABX_RPC_URLS') ?? '';
     const seen = new Set();
     const urls = list
         .split(/[\s,]+/)
@@ -53,8 +80,8 @@ export function resolveRpcUrls(chainKey = DEFAULT_CHAIN_KEY) {
     return urls;
 }
 /** The primary RPC endpoint (the first of {@link resolveRpcUrls}). */
-export function resolveRpcUrl(chainKey = DEFAULT_CHAIN_KEY) {
-    return resolveRpcUrls(chainKey)[0] ?? '';
+export function resolveRpcUrl(chainKey = DEFAULT_CHAIN_KEY, override) {
+    return resolveRpcUrls(chainKey, override)[0] ?? '';
 }
 /** A display-safe form of an RPC URL — host + a redacted key tail (URLs can embed keys). */
 export function redactRpcUrl(url) {

package/dist/chains.js.map

@@ -1 +1 @@
-{"version":3,"file":"chains.js","sourceRoot":"","sources":["../src/chains.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,OAAO,EAAE,WAAW,EAAC,MAAM,aAAa,CAAC;AAEjD,OAAO,EAAC,UAAU,EAAC,MAAM,UAAU,CAAC;AAEpC;;;;GAIG;AACH,MAAM,CAAC,MAAM,MAAM,GAA0B;IAC3C,cAAc,EAAE,WAAW;IAC3B,OAAO;CACR,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG,cAAc,CAAC;AAEhD,mFAAmF;AACnF,6EAA6E;AAC7E,MAAM,gBAAgB,GAA2B;IAC/C,cAAc,EAAE,0BAA0B;IAC1C,OAAO,EAAE,6CAA6C;CACvD,CAAC;AAEF,MAAM,UAAU,YAAY,CAAC,MAAc,iBAAiB;IAC1D,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,GAAG,aAAa,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChG,OAAO,KAAK,CAAC;AACf,CAAC;AAED;+FAC+F;AAC/F,MAAM,UAAU,SAAS,CAAC,QAAgB;IACxC,4EAA4E;IAC5E,uEAAuE;IACvE,OAAO,gBAAgB,QAAQ,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,EAAE,CAAC;AAC9E,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,WAAmB,iBAAiB;IACjE,UAAU,EAAE,CAAC;IACb,6EAA6E;IAC7E,yFAAyF;IACzF,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,EAAE,CAAC;IAChF,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,IAAI,GAAG,IAAI;SACd,KAAK,CAAC,QAAQ,CAAC;SACf,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACnD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,gBAAgB,CAAC,QAAQ,CAAC;QAAE,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC3F,OAAO,IAAI,CAAC;AACd,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,aAAa,CAAC,WAAmB,iBAAiB;IAChE,OAAO,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AAC3C,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QACvB,MAAM,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC;QAC/D,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QAC3D,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;IACxD,CAAC;AACH,CAAC"}
+{"version":3,"file":"chains.js","sourceRoot":"","sources":["../src/chains.ts"],"names":[],"mappings":"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"}

package/dist/chunks.d.ts

@@ -1,4 +1,5 @@
-import { type Address, type Hex, type PublicClient, type TransactionReceipt } from 'viem';
+import { type Address, type Hex, type PublicClient } from 'viem';
+import type { SendTx } from './execute.js';
 /**
  * Multi-chunk on-chain content — the off-chain side of {@link AbxChunkStore}.
  *
@@ -18,23 +19,12 @@ export interface PlannedChunk {
     compressed: boolean;
 }
 /**
- * One staging transaction, described in lane-agnostic terms: the SDK builds the calldata,
- * the caller decides how it's signed. The chunk-store writes are **ownerless**, so they can
- * be signed by any funded signer — the env key (hot lane) *or* a connected browser wallet
- * (wallet lane). Keeping the signer out of this module is what lets on-chain staging work
- * under every signing lane instead of assuming a hot key.
- *
- * `summary` + `fields` are surfaced to a human on the wallet sign page; `to: null` means a
- * contract creation (deploying the chunk store itself).
+ * Chunk-store writes are staged in the SAME lane-agnostic terms as every other write: the SDK
+ * builds a {@link PreparedTx}, the caller decides how it's signed via a {@link SendTx}. These writes
+ * are **ownerless**, so they can be signed by any funded signer — the env key (hot lane) *or* a
+ * connected browser wallet (wallet lane). Keeping the signer out of this module is what lets
+ * on-chain staging work under every signing lane instead of assuming a hot key.
  */
-export interface StagingTx {
-    to: Address | null;
-    data: Hex;
-    summary: string;
-    fields: Record<string, string>;
-}
-/** Sign + broadcast one {@link StagingTx} and return its mined receipt (for event parsing). */
-export type SendStagingTx = (tx: StagingTx) => Promise<TransactionReceipt>;
 /**
  * Split content into chunks, FastLZ-compressing each when `fastlz` is set (per-chunk — the
  * convention the store + reader expect). Pure: no chain, no I/O. A chunk is only stored
@@ -81,7 +71,9 @@ export declare function planContentTxs(chunks: PlannedChunk[], opts?: {
  * Deploy `AbxChunkStore` — the shared, stateless multi-chunk store + reader. Deploy once
  * per chain (like the renderer); every chunked field references it as its `reader`.
  */
-export declare function deployChunkStore(send: SendStagingTx): Promise<{
+export declare function deployChunkStore(send: SendTx, opts: {
+    chainId: number;
+}): Promise<{
     chunkStore: Address;
     txHash: Hex;
     blockNumber: bigint;
@@ -96,9 +88,10 @@ export declare function deployChunkStore(send: SendStagingTx): Promise<{
  */
 export declare function storeSupportsWriteContent(publicClient: PublicClient, store: Address): Promise<boolean>;
 /** Write one chunk as an SSTORE2 data contract; returns its address (from `ChunkWritten`). */
-export declare function writeChunk(send: SendStagingTx, args: {
+export declare function writeChunk(send: SendTx, args: {
     store: Address;
     data: Uint8Array;
+    chainId: number;
 }): Promise<{
     pointer: Address;
     txHash: Hex;
@@ -109,9 +102,10 @@ export declare function writeChunk(send: SendStagingTx, args: {
  * fits a single tx's gas (see {@link planContentTxs}); returns the manifest address (the
  * `reader` pointer) from the `ManifestWritten` event.
  */
-export declare function writeContent(send: SendStagingTx, args: {
+export declare function writeContent(send: SendTx, args: {
     store: Address;
     chunks: ReadonlyArray<PlannedChunk>;
+    chainId: number;
 }): Promise<{
     manifest: Address;
     txHash: Hex;
@@ -123,9 +117,10 @@ export declare function writeContent(send: SendStagingTx, args: {
  * batches, concatenates the returned pointers, then calls {@link writeManifest}. Pairs
  * each pointer with its planned `compressed` flag for manifest assembly.
  */
-export declare function writeChunkBatch(send: SendStagingTx, args: {
+export declare function writeChunkBatch(send: SendTx, args: {
     store: Address;
     chunks: ReadonlyArray<PlannedChunk>;
+    chainId: number;
 }): Promise<{
     written: Array<{
         pointer: Address;
@@ -143,9 +138,10 @@ export declare function writeChunkBatch(send: SendStagingTx, args: {
  * This is the same path whether the manifest is later baked into a deploy's `InitParams`
  * or set on a live token — staging always precedes the contract that references it.
  */
-export declare function stageContent(send: SendStagingTx, args: {
+export declare function stageContent(send: SendTx, args: {
     store: Address;
     content: Uint8Array;
+    chainId: number;
     fastlz?: boolean;
     chunkSize?: number;
     gasBudget?: number;
@@ -155,14 +151,48 @@ export declare function stageContent(send: SendStagingTx, args: {
     chunkCount: number;
 }>;
 /** Write the manifest (ordered chunk list); returns its address (the `reader` pointer). */
-export declare function writeManifest(send: SendStagingTx, args: {
+export declare function writeManifest(send: SendTx, args: {
     store: Address;
     chunks: ReadonlyArray<{
         pointer: Address;
         compressed: boolean;
     }>;
+    chainId: number;
 }): Promise<{
     manifest: Address;
     txHash: Hex;
 }>;
+/** Progress from {@link ensureChunkStore}, so a caller can narrate without the SDK printing. */
+export type ChunkStoreEvent = {
+    kind: 'stale';
+    address: Address;
+} | {
+    kind: 'canonical';
+    address: Address;
+} | {
+    kind: 'deploying';
+} | {
+    kind: 'deployed';
+    address: Address;
+    inManifest: boolean;
+};
+/**
+ * Resolve a usable multi-chunk content store for this chain, deploying one if needed.
+ *
+ * This is the bootstrap every on-chain-content path needs, and it existed only inside the CLI — so an
+ * SDK integrator got `resolveChunkStore()` (which may return undefined) plus a separate
+ * `storeSupportsWriteContent()` they had to remember to call. Forget the second and an incapable
+ * store fails *deep inside a mint, after transactions have already landed*. One team hand-rolled this
+ * guard for exactly that reason; exporting it is cheaper than every integrator rediscovering it.
+ *
+ * Three ways to succeed, in order: the listed store if it exists AND exposes the current ABI; the
+ * CREATE2-deterministic address (the store is canonical, so a forge script or an earlier lazy deploy
+ * may have put it there before the manifest caught up — self-healing, and never a duplicate at a
+ * random CREATE address); otherwise deploy it. Ownerless, so any funded signer may stand it up.
+ */
+export declare function ensureChunkStore(publicClient: PublicClient, send: SendTx, opts?: {
+    chainId: number;
+    override?: string;
+    onEvent?: (e: ChunkStoreEvent) => void;
+}): Promise<Address>;
 //# sourceMappingURL=chunks.d.ts.map