@artblocks/abx-sdk 0.1.0-alpha.0

package/dist/abi/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/abi/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,uBAAuB,EACvB,4BAA4B,EAC5B,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,0BAA0B,EAC1B,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,yBAAyB,EACzB,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EACf,oBAAoB,EACpB,aAAa,EACb,kBAAkB,EAClB,sBAAsB,EACtB,2BAA2B,EAC3B,gBAAgB,EAChB,qBAAqB,EACrB,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,gBAAgB,CAAC;AAiBxB;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAmBtB,CAAC"}

package/dist/abi/index.js

@@ -0,0 +1,38 @@
+// The ABI surface the SDK speaks. Generated artifacts come from the contracts
+// package (Layer 1) via `pnpm sync-abis`; never hand-edit `generated.ts`.
+export { oneOfOneImageFactoryAbi, oneOfOneImageFactoryBytecode, oneOfOneImageAbi, oneOfOneImageBytecode, seriesImageFactoryAbi, seriesImageFactoryBytecode, seriesImageAbi, seriesImageBytecode, seriesCodeFactoryAbi, seriesCodeFactoryBytecode, seriesCodeAbi, seriesCodeBytecode, abxSeedSourceAbi, abxSeedSourceBytecode, abxParamsLibAbi, abxParamsLibBytecode, abxCodeLibAbi, abxCodeLibBytecode, abxMetadataRendererAbi, abxMetadataRendererBytecode, abxChunkStoreAbi, abxChunkStoreBytecode, abxFixedPriceMinterAbi, abxFixedPriceMinterBytecode, } from './generated.js';
+import { oneOfOneImageAbi, oneOfOneImageFactoryAbi, seriesImageAbi, seriesImageFactoryAbi, seriesCodeAbi, seriesCodeFactoryAbi, abxFixedPriceMinterAbi, } from './generated.js';
+/** A stable signature key for an ABI event fragment (name + input types), for de-duping. */
+function eventKey(f) {
+    return `${f.name ?? ''}(${(f.inputs ?? []).map((i) => i.type).join(',')})`;
+}
+/**
+ * The event-spine ABI: every event any ABX token type + its factory can emit — the set
+ * the reference indexer decodes. Both concrete tokens (1/1 and Series) declare the full
+ * spine they participate in (Register 1 standards + Register 2 native events); we union
+ * them plus the factories' `Deployed` and the fixed-price minter's sibling Minter-spine
+ * events (`SaleConfigured`/`Purchase`), de-duping shared fragments (e.g. `Transfer`) so a
+ * single ABI decodes any ABX contract's logs unambiguously.
+ */
+export const spineEventAbi = (() => {
+    const all = [
+        ...oneOfOneImageAbi,
+        ...seriesImageAbi,
+        ...seriesCodeAbi,
+        ...oneOfOneImageFactoryAbi,
+        ...seriesImageFactoryAbi,
+        ...seriesCodeFactoryAbi,
+        ...abxFixedPriceMinterAbi,
+    ].filter((f) => f.type === 'event');
+    const seen = new Set();
+    const out = [];
+    for (const f of all) {
+        const key = eventKey(f);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(f);
+    }
+    return out;
+})();
+//# sourceMappingURL=index.js.map

package/dist/abi/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/abi/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,0EAA0E;AAC1E,OAAO,EACL,uBAAuB,EACvB,4BAA4B,EAC5B,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,0BAA0B,EAC1B,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,yBAAyB,EACzB,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EACf,oBAAoB,EACpB,aAAa,EACb,kBAAkB,EAClB,sBAAsB,EACtB,2BAA2B,EAC3B,gBAAgB,EAChB,qBAAqB,EACrB,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,cAAc,EACd,qBAAqB,EACrB,aAAa,EACb,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AAExB,4FAA4F;AAC5F,SAAS,QAAQ,CAAC,CAAwE;IACxF,OAAO,GAAG,CAAC,CAAC,IAAI,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAC7E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE;IACjC,MAAM,GAAG,GAAG;QACV,GAAG,gBAAgB;QACnB,GAAG,cAAc;QACjB,GAAG,aAAa;QAChB,GAAG,uBAAuB;QAC1B,GAAG,qBAAqB;QACxB,GAAG,oBAAoB;QACvB,GAAG,sBAAsB;KAC1B,CAAC,MAAM,CAAC,CAAC,CAAiB,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;IACpD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,GAAG,GAAe,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;QACpB,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAU,CAAC,CAAC;QACjC,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACd,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC,CAAC,EAAE,CAAC"}

package/dist/chains.d.ts

@@ -0,0 +1,27 @@
+import type { Chain } from 'viem';
+/**
+ * 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.
+ * The protocol is per-EVM-chain (one project = one contract, per chain).
+ */
+export declare const CHAINS: Record<string, Chain>;
+export declare const DEFAULT_CHAIN_KEY = "base-sepolia";
+export declare function resolveChain(key?: string): Chain;
+/** 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`.
+ */
+export declare function resolveRpcUrls(chainKey?: string): string[];
+/** The primary RPC endpoint (the first of {@link resolveRpcUrls}). */
+export declare function resolveRpcUrl(chainKey?: 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

@@ -0,0 +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"}

package/dist/chains.js

@@ -0,0 +1,71 @@
+import { sepolia, baseSepolia } from 'viem/chains';
+import { loadDotEnv } from './env.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.
+ * The protocol is per-EVM-chain (one project = one contract, per chain).
+ */
+export const CHAINS = {
+    'base-sepolia': baseSepolia,
+    sepolia,
+};
+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.
+const DEFAULT_RPC_URLS = {
+    'base-sepolia': 'https://sepolia.base.org',
+    sepolia: 'https://ethereum-sepolia-rpc.publicnode.com',
+};
+export function resolveChain(key = DEFAULT_CHAIN_KEY) {
+    const chain = CHAINS[key];
+    if (!chain)
+        throw new Error(`Unknown chain "${key}". Known: ${Object.keys(CHAINS).join(', ')}`);
+    return chain;
+}
+/** 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, '_')}`;
+}
+/**
+ * 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`.
+ */
+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 ?? '';
+    const seen = new Set();
+    const urls = list
+        .split(/[\s,]+/)
+        .map((u) => u.trim())
+        .filter((u) => u && !seen.has(u) && seen.add(u));
+    if (urls.length === 0 && DEFAULT_RPC_URLS[chainKey])
+        urls.push(DEFAULT_RPC_URLS[chainKey]);
+    return urls;
+}
+/** The primary RPC endpoint (the first of {@link resolveRpcUrls}). */
+export function resolveRpcUrl(chainKey = DEFAULT_CHAIN_KEY) {
+    return resolveRpcUrls(chainKey)[0] ?? '';
+}
+/** A display-safe form of an RPC URL — host + a redacted key tail (URLs can embed keys). */
+export function redactRpcUrl(url) {
+    try {
+        const u = new URL(url);
+        const last = u.pathname.split('/').filter(Boolean).pop() ?? '';
+        const tail = last.length > 6 ? `…${last.slice(-4)}` : last;
+        return tail ? `${u.host}/…/${tail}` : u.host;
+    }
+    catch {
+        return url.length > 24 ? `${url.slice(0, 20)}…` : url;
+    }
+}
+//# sourceMappingURL=chains.js.map

package/dist/chains.js.map

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

package/dist/chunks.d.ts

@@ -0,0 +1,168 @@
+import { type Address, type Hex, type PublicClient, type TransactionReceipt } from 'viem';
+/**
+ * Multi-chunk on-chain content — the off-chain side of {@link AbxChunkStore}.
+ *
+ * Large content (a 30 kB image, a long description) is split into SSTORE2-sized chunks,
+ * optionally FastLZ-compressed **per chunk** off-chain (the chunk store decompresses on
+ * read, so it stays on-chain-renderable), written as immutable data contracts, and tied
+ * together by a manifest. The field then carries the `reader` representation with
+ * `value = abi.encode(chunkStore, manifest)`. gzip is *not* handled here — it's an
+ * off-chain decode signaled by the `-gzip` representation, applied to the assembled bytes.
+ */
+/** SSTORE2 data-contract code limit is 24576 bytes (EIP-170) minus the STOP byte; chunk
+ *  conservatively so even an incompressible FastLZ chunk (slight expansion) still fits. */
+export declare const DEFAULT_CHUNK_SIZE = 22000;
+/** One planned chunk: the bytes to store + whether they're FastLZ-compressed. */
+export interface PlannedChunk {
+    data: Uint8Array;
+    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).
+ */
+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
+ * compressed when that actually shrinks it (so the reader never wastes a decompress).
+ */
+export declare function planChunks(content: Uint8Array, opts?: {
+    fastlz?: boolean;
+    chunkSize?: number;
+}): PlannedChunk[];
+/**
+ * A per-transaction gas ceiling for packing chunk writes. Comfortably under mainnet's
+ * ~30M block limit so a batch always fits with room for the base + calldata cost; the
+ * planner splits content across multiple transactions to stay beneath it.
+ */
+export declare const DEFAULT_TX_GAS_BUDGET = 8000000;
+/**
+ * Rough gas for writing one chunk as an SSTORE2 data contract: a fixed CREATE + base
+ * overhead plus the code-deposit cost (~200 gas/byte) and calldata. Deliberately an
+ * over-estimate so packed batches land safely inside {@link DEFAULT_TX_GAS_BUDGET};
+ * the wallet still does the real `eth_estimateGas` before sending.
+ */
+export declare function estimateChunkGas(chunk: PlannedChunk): number;
+/** How content will be written on-chain — one atomic tx, or several batched ones. */
+export type ContentTxPlan = {
+    mode: 'single';
+    chunks: PlannedChunk[];
+    txCount: 1;
+} | {
+    mode: 'split';
+    batches: PlannedChunk[][];
+    txCount: number;
+};
+/**
+ * Decide the transaction shape for a piece of content. When the whole thing fits one
+ * tx's gas budget it's a single atomic {@link writeContent} (no address prediction, no
+ * follow-up). Otherwise it's split into gas-bounded batches of {@link writeChunk} calls
+ * (each batch one `multicall`), followed by a single {@link writeManifest} — so
+ * `txCount` is `batches.length + 1`. Pure: no chain, no I/O.
+ */
+export declare function planContentTxs(chunks: PlannedChunk[], opts?: {
+    gasBudget?: number;
+}): ContentTxPlan;
+/**
+ * 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<{
+    chunkStore: Address;
+    txHash: Hex;
+    blockNumber: bigint;
+}>;
+/**
+ * Does `store` expose the current `writeContent(bytes[],bool[])` ABI? A chunk store deployed
+ * before `writeContent` existed (an older `AbxChunkStore`) still *has code*, so a bare
+ * `getCode` check passes — but the call reverts, silently breaking the `--onchain-image`
+ * path. We probe with an empty `writeContent([],[])`: the current store returns a manifest
+ * address, a stale/incompatible one reverts. This is a pure `eth_call` (no tx, no state
+ * change, no gas spent), so it's safe to run on every staging path as a guard.
+ */
+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: {
+    store: Address;
+    data: Uint8Array;
+}): Promise<{
+    pointer: Address;
+    txHash: Hex;
+}>;
+/**
+ * Write a whole piece of content — every chunk plus the manifest — in ONE transaction
+ * via `AbxChunkStore.writeContent`. The atomic, prediction-free path for content that
+ * 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: {
+    store: Address;
+    chunks: ReadonlyArray<PlannedChunk>;
+}): Promise<{
+    manifest: Address;
+    txHash: Hex;
+}>;
+/**
+ * Write a batch of chunks in ONE transaction via the store's `multicall`, returning their
+ * pointer addresses **in order** (parsed from the `ChunkWritten` events). Used by the
+ * split path for content too large for a single tx: the caller writes one or more such
+ * 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: {
+    store: Address;
+    chunks: ReadonlyArray<PlannedChunk>;
+}): Promise<{
+    written: Array<{
+        pointer: Address;
+        compressed: boolean;
+    }>;
+    txHash: Hex;
+}>;
+/**
+ * Stage a whole piece of content on the chunk store and return its manifest — the
+ * `pointer` half of a `reader` field's value. Plans the chunks, then executes the
+ * minimal transaction set ({@link planContentTxs}): one atomic {@link writeContent} when
+ * it fits, else gas-bounded {@link writeChunkBatch} multicalls plus a final
+ * {@link writeManifest}. Returns every tx hash so a UX can report the count honestly.
+ *
+ * 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: {
+    store: Address;
+    content: Uint8Array;
+    fastlz?: boolean;
+    chunkSize?: number;
+    gasBudget?: number;
+}): Promise<{
+    manifest: Address;
+    txHashes: Hex[];
+    chunkCount: number;
+}>;
+/** Write the manifest (ordered chunk list); returns its address (the `reader` pointer). */
+export declare function writeManifest(send: SendStagingTx, args: {
+    store: Address;
+    chunks: ReadonlyArray<{
+        pointer: Address;
+        compressed: boolean;
+    }>;
+}): Promise<{
+    manifest: Address;
+    txHash: Hex;
+}>;
+//# sourceMappingURL=chunks.d.ts.map

package/dist/chunks.d.ts.map

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

package/dist/chunks.js

@@ -0,0 +1,232 @@
+import { encodeFunctionData, parseEventLogs, } from 'viem';
+import { abxChunkStoreAbi, abxChunkStoreBytecode } from './abi/index.js';
+import { flzCompress } from './fastlz.js';
+import { ABX_SALT, CREATE2_PROXY, create2Calldata, predictCreate2Address } from './create2.js';
+/**
+ * Multi-chunk on-chain content — the off-chain side of {@link AbxChunkStore}.
+ *
+ * Large content (a 30 kB image, a long description) is split into SSTORE2-sized chunks,
+ * optionally FastLZ-compressed **per chunk** off-chain (the chunk store decompresses on
+ * read, so it stays on-chain-renderable), written as immutable data contracts, and tied
+ * together by a manifest. The field then carries the `reader` representation with
+ * `value = abi.encode(chunkStore, manifest)`. gzip is *not* handled here — it's an
+ * off-chain decode signaled by the `-gzip` representation, applied to the assembled bytes.
+ */
+/** SSTORE2 data-contract code limit is 24576 bytes (EIP-170) minus the STOP byte; chunk
+ *  conservatively so even an incompressible FastLZ chunk (slight expansion) still fits. */
+export const DEFAULT_CHUNK_SIZE = 22_000;
+/**
+ * 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
+ * compressed when that actually shrinks it (so the reader never wastes a decompress).
+ */
+export function planChunks(content, opts = {}) {
+    const size = opts.chunkSize ?? DEFAULT_CHUNK_SIZE;
+    const chunks = [];
+    for (let i = 0; i < content.length; i += size) {
+        const raw = content.subarray(i, i + size);
+        if (opts.fastlz) {
+            const packed = flzCompress(raw);
+            if (packed.length < raw.length) {
+                chunks.push({ data: packed, compressed: true });
+                continue;
+            }
+        }
+        chunks.push({ data: raw, compressed: false });
+    }
+    return chunks;
+}
+const toHex = (b) => `0x${Buffer.from(b).toString('hex')}`;
+/**
+ * A per-transaction gas ceiling for packing chunk writes. Comfortably under mainnet's
+ * ~30M block limit so a batch always fits with room for the base + calldata cost; the
+ * planner splits content across multiple transactions to stay beneath it.
+ */
+export const DEFAULT_TX_GAS_BUDGET = 8_000_000;
+/**
+ * Rough gas for writing one chunk as an SSTORE2 data contract: a fixed CREATE + base
+ * overhead plus the code-deposit cost (~200 gas/byte) and calldata. Deliberately an
+ * over-estimate so packed batches land safely inside {@link DEFAULT_TX_GAS_BUDGET};
+ * the wallet still does the real `eth_estimateGas` before sending.
+ */
+export function estimateChunkGas(chunk) {
+    return 40_000 + chunk.data.length * 240;
+}
+/**
+ * Decide the transaction shape for a piece of content. When the whole thing fits one
+ * tx's gas budget it's a single atomic {@link writeContent} (no address prediction, no
+ * follow-up). Otherwise it's split into gas-bounded batches of {@link writeChunk} calls
+ * (each batch one `multicall`), followed by a single {@link writeManifest} — so
+ * `txCount` is `batches.length + 1`. Pure: no chain, no I/O.
+ */
+export function planContentTxs(chunks, opts = {}) {
+    const budget = opts.gasBudget ?? DEFAULT_TX_GAS_BUDGET;
+    const total = chunks.reduce((g, c) => g + estimateChunkGas(c), 0);
+    // writeContent also pays for the manifest write; approximate it as one more chunk.
+    if (total + 60_000 <= budget)
+        return { mode: 'single', chunks, txCount: 1 };
+    const batches = [];
+    let cur = [];
+    let curGas = 0;
+    for (const c of chunks) {
+        const g = estimateChunkGas(c);
+        if (cur.length > 0 && curGas + g > budget) {
+            batches.push(cur);
+            cur = [];
+            curGas = 0;
+        }
+        cur.push(c);
+        curGas += g;
+    }
+    if (cur.length > 0)
+        batches.push(cur);
+    return { mode: 'split', batches, txCount: batches.length + 1 };
+}
+/**
+ * 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 async function deployChunkStore(send) {
+    // CREATE2 via the keyless proxy + canonical salt → the SAME address on every chain (matches the
+    // forge `DeployChunkStore` script and the manifest). The address is deterministic, so we compute
+    // it rather than read `receipt.contractAddress` (which is null — the tx targets the proxy, not a
+    // contract creation). Deploy only when the store isn't already there (the caller checks first).
+    const chunkStore = predictCreate2Address(ABX_SALT.chunkStore, abxChunkStoreBytecode);
+    const receipt = await send({
+        to: CREATE2_PROXY,
+        data: create2Calldata(ABX_SALT.chunkStore, abxChunkStoreBytecode),
+        summary: 'Deploy the shared on-chain chunk store (AbxChunkStore) — CREATE2, deterministic address',
+        fields: { contract: 'AbxChunkStore', address: chunkStore, note: 'one-time, ownerless, shared by every chunked field' },
+    });
+    return { chunkStore, txHash: receipt.transactionHash, blockNumber: receipt.blockNumber };
+}
+/**
+ * Does `store` expose the current `writeContent(bytes[],bool[])` ABI? A chunk store deployed
+ * before `writeContent` existed (an older `AbxChunkStore`) still *has code*, so a bare
+ * `getCode` check passes — but the call reverts, silently breaking the `--onchain-image`
+ * path. We probe with an empty `writeContent([],[])`: the current store returns a manifest
+ * address, a stale/incompatible one reverts. This is a pure `eth_call` (no tx, no state
+ * change, no gas spent), so it's safe to run on every staging path as a guard.
+ */
+export async function storeSupportsWriteContent(publicClient, store) {
+    try {
+        await publicClient.call({
+            to: store,
+            data: encodeFunctionData({ abi: abxChunkStoreAbi, functionName: 'writeContent', args: [[], []] }),
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Write one chunk as an SSTORE2 data contract; returns its address (from `ChunkWritten`). */
+export async function writeChunk(send, args) {
+    const receipt = await send({
+        to: args.store,
+        data: encodeFunctionData({ abi: abxChunkStoreAbi, functionName: 'writeChunk', args: [toHex(args.data)] }),
+        summary: 'Stage one on-chain content chunk',
+        fields: { store: args.store, bytes: String(args.data.length) },
+    });
+    const ev = parseEventLogs({ abi: abxChunkStoreAbi, eventName: 'ChunkWritten', logs: receipt.logs });
+    const pointer = ev[0]?.args.pointer;
+    if (!pointer)
+        throw new Error('writeChunk emitted no ChunkWritten event');
+    return { pointer, txHash: receipt.transactionHash };
+}
+/**
+ * Write a whole piece of content — every chunk plus the manifest — in ONE transaction
+ * via `AbxChunkStore.writeContent`. The atomic, prediction-free path for content that
+ * fits a single tx's gas (see {@link planContentTxs}); returns the manifest address (the
+ * `reader` pointer) from the `ManifestWritten` event.
+ */
+export async function writeContent(send, args) {
+    const receipt = await send({
+        to: args.store,
+        data: encodeFunctionData({
+            abi: abxChunkStoreAbi,
+            functionName: 'writeContent',
+            args: [args.chunks.map((c) => toHex(c.data)), args.chunks.map((c) => c.compressed)],
+        }),
+        summary: `Stage on-chain content (${args.chunks.length} chunk${args.chunks.length === 1 ? '' : 's'}, atomic)`,
+        fields: { store: args.store, chunks: String(args.chunks.length) },
+    });
+    const ev = parseEventLogs({ abi: abxChunkStoreAbi, eventName: 'ManifestWritten', logs: receipt.logs });
+    const manifest = ev[0]?.args.manifest;
+    if (!manifest)
+        throw new Error('writeContent emitted no ManifestWritten event');
+    return { manifest, txHash: receipt.transactionHash };
+}
+/**
+ * Write a batch of chunks in ONE transaction via the store's `multicall`, returning their
+ * pointer addresses **in order** (parsed from the `ChunkWritten` events). Used by the
+ * split path for content too large for a single tx: the caller writes one or more such
+ * batches, concatenates the returned pointers, then calls {@link writeManifest}. Pairs
+ * each pointer with its planned `compressed` flag for manifest assembly.
+ */
+export async function writeChunkBatch(send, args) {
+    const calls = args.chunks.map((c) => encodeFunctionData({ abi: abxChunkStoreAbi, functionName: 'writeChunk', args: [toHex(c.data)] }));
+    const receipt = await send({
+        to: args.store,
+        data: encodeFunctionData({ abi: abxChunkStoreAbi, functionName: 'multicall', args: [calls] }),
+        summary: `Stage ${args.chunks.length} on-chain content chunk${args.chunks.length === 1 ? '' : 's'} (batch)`,
+        fields: { store: args.store, chunks: String(args.chunks.length) },
+    });
+    const txHash = receipt.transactionHash;
+    const evs = parseEventLogs({ abi: abxChunkStoreAbi, eventName: 'ChunkWritten', logs: receipt.logs });
+    if (evs.length !== args.chunks.length) {
+        throw new Error(`writeChunkBatch: expected ${args.chunks.length} ChunkWritten events, got ${evs.length}`);
+    }
+    const written = evs.map((e, i) => ({
+        pointer: e.args.pointer,
+        compressed: args.chunks[i].compressed,
+    }));
+    return { written, txHash };
+}
+/**
+ * Stage a whole piece of content on the chunk store and return its manifest — the
+ * `pointer` half of a `reader` field's value. Plans the chunks, then executes the
+ * minimal transaction set ({@link planContentTxs}): one atomic {@link writeContent} when
+ * it fits, else gas-bounded {@link writeChunkBatch} multicalls plus a final
+ * {@link writeManifest}. Returns every tx hash so a UX can report the count honestly.
+ *
+ * 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 async function stageContent(send, args) {
+    const chunks = planChunks(args.content, { fastlz: args.fastlz, chunkSize: args.chunkSize });
+    const plan = planContentTxs(chunks, { gasBudget: args.gasBudget });
+    const txHashes = [];
+    if (plan.mode === 'single') {
+        const { manifest, txHash } = await writeContent(send, { store: args.store, chunks });
+        return { manifest, txHashes: [txHash], chunkCount: chunks.length };
+    }
+    const written = [];
+    for (const batch of plan.batches) {
+        const res = await writeChunkBatch(send, { store: args.store, chunks: batch });
+        written.push(...res.written);
+        txHashes.push(res.txHash);
+    }
+    const { manifest, txHash } = await writeManifest(send, { store: args.store, chunks: written });
+    txHashes.push(txHash);
+    return { manifest, txHashes, chunkCount: chunks.length };
+}
+/** Write the manifest (ordered chunk list); returns its address (the `reader` pointer). */
+export async function writeManifest(send, args) {
+    const receipt = await send({
+        to: args.store,
+        data: encodeFunctionData({
+            abi: abxChunkStoreAbi,
+            functionName: 'writeManifest',
+            args: [args.chunks.map((c) => ({ pointer: c.pointer, compressed: c.compressed }))],
+        }),
+        summary: `Write the on-chain content manifest (${args.chunks.length} chunk${args.chunks.length === 1 ? '' : 's'})`,
+        fields: { store: args.store, chunks: String(args.chunks.length) },
+    });
+    const ev = parseEventLogs({ abi: abxChunkStoreAbi, eventName: 'ManifestWritten', logs: receipt.logs });
+    const manifest = ev[0]?.args.manifest;
+    if (!manifest)
+        throw new Error('writeManifest emitted no ManifestWritten event');
+    return { manifest, txHash: receipt.transactionHash };
+}
+//# sourceMappingURL=chunks.js.map

package/dist/chunks.js.map

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

package/dist/clients.d.ts

@@ -0,0 +1,42 @@
+import { type PublicClient, type WalletClient, type Account } from 'viem';
+export interface ClientOptions {
+    chainKey?: string;
+    rpcUrl?: string;
+}
+/** A read-only client — all the indexer and token API ever need. */
+export declare function makePublicClient(opts?: ClientOptions): PublicClient;
+/**
+ * Verify the configured RPC actually IS the chain we think it is, before any write.
+ * The env var names a network ("sepolia") but the URL behind it could point anywhere;
+ * this calls `eth_chainId` and hard-fails on a mismatch so an irreversible tx can't go
+ * to the wrong chain. Memoized per chainKey — one round-trip per process, so callers can
+ * invoke it liberally at write preflights. Reads never call it (they stay zero-overhead).
+ *
+ * `allowUnreachable` (used by `--dry-run` preflights): a *wrong-network* RPC still hard-fails
+ * with the clear mismatch message — a dry run makes RPC reads (predict address, resolve the
+ * factory/renderer) that otherwise fail deep inside viem as an opaque "returned no data" — but
+ * an *unreachable* RPC is tolerated (returns silently), so a genuinely offline `--dry-run` can
+ * still preview what it can. Only a reachable-but-wrong endpoint is a preview-blocking error.
+ */
+export declare function assertChainId(chainKey?: string, opts?: {
+    allowUnreachable?: boolean;
+}): Promise<void>;
+/**
+ * A signing client, backed by a private key from the environment. The SDK never
+ * takes custody of keys beyond reading them from the operator's own env — there
+ * is no key storage, no prompt, no remote signer here.
+ *
+ * Key precedence: `ABX_DEPLOYER_PK` → `SEPOLIA_FUNDED_PK` → `SEPOLIA_WALLET_PK`.
+ */
+export declare function makeWalletClient(opts?: ClientOptions): {
+    wallet: WalletClient;
+    account: Account;
+};
+/**
+ * The env signing key (0x-normalized), same precedence as {@link makeWalletClient}
+ * (`ABX_DEPLOYER_PK` → `SEPOLIA_FUNDED_PK` → `SEPOLIA_WALLET_PK`), or `undefined` if none is set.
+ * For reusing the hot key as a *storage* signing identity (an Ethereum Turbo identity) without
+ * constructing a wallet client. Never throws.
+ */
+export declare function envSigningKey(): `0x${string}` | undefined;
+//# sourceMappingURL=clients.d.ts.map

package/dist/clients.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clients.d.ts","sourceRoot":"","sources":["../src/clients.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,YAAY,EAEjB,KAAK,YAAY,EACjB,KAAK,OAAO,EACb,MAAM,MAAM,CAAC;AAKd,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAeD,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,aAAkB,GAAG,YAAY,CAEvE;AAID;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CACjC,QAAQ,GAAE,MAA0B,EACpC,IAAI,GAAE;IAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAM,GACtC,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,aAAkB,GAAG;IAC1D,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;CAClB,CAYA;AAOD;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,KAAK,MAAM,EAAE,GAAG,SAAS,CAIzD"}