@artblocks/abx-cli 0.1.0-alpha.17 → 0.1.0-alpha.19

package/dist/ownerops.js

@@ -6,24 +6,28 @@
  * served state reflects the change. The agent picks the lane; the human only
  * approves (wallet lane) or it's the env key (hot lane).
  */
-import { assertChainId, ensureChunkStore as sdkEnsureChunkStore, predictFixedPriceMinter, encodeReader, makePublicClient, makeWalletClient, oneOfOneImageAbi, seriesImageAbi, abxFixedPriceMinterAbi, deployFixedPriceMinter, prepareConfigureSale, preparePurchase, planChunks, planContentTxs, prepareLockContractField, prepareLockContractURI, prepareLockTokenField, prepareLockTokenURI, prepareMint, prepareSeriesMintMany, prepareSetMinter, prepareSetMaxInvocations, prepareSetPrimaryPayee, prepareSetPaused, prepareSetContractField, prepareSetContractURIBase, prepareSetContractURIOverride, prepareSetContractURIRenderer, prepareSetParamHooks, prepareSetParamSchema, prepareRetireParam, readParamSchema, PARAM_TYPES, prepareSetRoyalty, prepareSetTokenField, batchOps, prepareSetTokenURIBase, prepareSetTokenURIOverride, prepareSetTokenURIRenderer, prepareSetTransferValidator, prepareTransfer, prepareTransferOwnership, readCreatorTokenStatus, resolveRecommendedTransferValidator, RECOMMENDED_TRANSFER_VALIDATOR, KNOWN_CHAIN_KEYS, resolveChain, resolveRpcUrl, redactRpcUrl, DEFAULT_CHAIN_KEY, stageContent, encodeTag, METADATA_FIELD as F, METADATA_REPRESENTATION as R, } from '@artblocks/abx-sdk';
-import { SelfHostIndexer } from '@artblocks/abx-indexer';
-import { encodeScalarParam, encodeTag as encodeTagSdk, isAccepted, prepareConfigureTokenParam, prepareConfigureTokenParamData, prepareSetContractParam, prepareSetContractParamData, seriesCodeAbi, } from '@artblocks/abx-sdk';
-import { hasParamEnumeration } from './onchain-uri.js';
+import { assertChainId, ensureChunkStore as sdkEnsureChunkStore, predictFixedPriceMinter, makeHotSender, makePublicClient, makeWalletClient, oneOfOneImageAbi, seriesImageAbi, deployFixedPriceMinter, prepareConfigureSale, preparePurchase, readSaleConfig, prepareLockContractField, prepareLockContractURI, prepareLockTokenField, prepareLockTokenURI, prepareMint, mintedTokenIds, prepareSeriesMintMany, prepareSetMinter, prepareSetMaxInvocations, prepareSetPrimaryPayee, prepareSetPaused, prepareSetContractField, prepareSetContractURIBase, prepareSetContractURIOverride, prepareSetContractURIRenderer, prepareSetParamHooks, prepareSetParamSchema, prepareRetireParam, readParamSchema, PARAM_TYPES, prepareSetRoyalty, prepareSetTokenField, batchOps, prepareSetTokenURIBase, prepareSetTokenURIOverride, prepareSetTokenURIRenderer, prepareSetTransferValidator, prepareTransfer, prepareTransferOwnership, readCreatorTokenStatus, resolveRecommendedTransferValidator, RECOMMENDED_TRANSFER_VALIDATOR, KNOWN_CHAIN_KEYS, resolveChain, resolveRpcUrl, redactRpcUrl, encodeTag, METADATA_FIELD as F, METADATA_REPRESENTATION as R, stageFieldContent, planStagedContent, exceedsOnchainSoftLimit, ONCHAIN_IMAGE_SOFT_LIMIT, ONCHAIN_PROJECT_SOFT_LIMIT, } from '@artblocks/abx-sdk';
+import { encodeScalarParam, encodeTag as encodeTagSdk, isAccepted, prepareConfigureTokenParam, prepareConfigureTokenParamData, prepareSetContractParam, prepareSetContractParamData, seriesCodeAbi, tryReadContract, } from '@artblocks/abx-sdk';
+import { hasParamEnumeration } from '@artblocks/abx-sdk';
 import { decodeFieldRenderer, resolveGenerator, DEP_RESOLUTION, parseDependencyRef, prepareLockDependencies, prepareRemoveLastDependency, prepareSetDependency, prepareSetDependencyRegistry, } from '@artblocks/abx-sdk';
 import { contentTypeFromPath } from '@artblocks/abx-storage';
 import { toHex as toHexSdk } from 'viem';
 import { readFileSync } from 'node:fs';
 import { basename, resolve as resolvePath } from 'node:path';
 import { gzipSync } from 'node:zlib';
-import { decodeEventLog, formatEther, getAddress, isAddress, parseEther, toHex, zeroAddress } from 'viem';
-import { fixedPriceMinterAddress } from './config.js';
-import { openWalletSession, signTx } from './signer.js';
+import { formatEther, getAddress, isAddress, parseEther, toHex, zeroAddress } from 'viem';
+import { CHAIN, chainId, fixedPriceMinterAddress, localIndexer } from './config.js';
+import { CliError } from './errors.js';
+import { openWalletSession } from './signer.js';
+import { gatedSend, laneFromFlags } from './riskgate.js';
 import { withJson } from './jsonout.js';
 import { resolveRemote, serviceClient } from './remote.js';
-import { positionalArgs, unknownFlags } from './flags.js';
+import { isDryRun, positionalArgs, unknownFlags } from './flags.js';
 import { parseSchemaSpecs, describeSchema } from './schema.js';
-const CHAIN = process.env.ABX_CHAIN ?? DEFAULT_CHAIN_KEY; // base-sepolia default — MUST match main.ts/config.ts (a stale 'sepolia' here silently ran every owner-op on the wrong chain)
+// Re-exported for main.ts (the on-chain-vs-off-chain cost model + the compression-mode type now
+// live in the SDK's staging.ts, layered on planChunks/planContentTxs — see the comment at their
+// definition below).
+export { ONCHAIN_PROJECT_SOFT_LIMIT };
 // ── ANSI (local) ─────────────────────────────────────────────────────────────
 const C = { reset: '\x1b[0m', dim: '\x1b[2m', bold: '\x1b[1m', green: '\x1b[38;5;115m', yellow: '\x1b[38;5;221m' };
 const dim = (s) => `${C.dim}${s}${C.reset}`;
@@ -58,7 +62,7 @@ function fitsLiteralBytes32(value) {
     return value.length <= 31 && /^[\x20-\x7e]+$/.test(value);
 }
 /** Flags `abx attach` recognizes — anything else warns (non-fatal), so a silent no-op flag surfaces. */
-const ATTACH_FLAGS = ['file', 'compress', 'collection', 'token', 'send', 'sign', 'unsigned', 'yes', 'dry-run', 'port', 'sign-url-file', 'remote'];
+const ATTACH_FLAGS = ['file', 'compress', 'collection', 'token', 'send', 'sign', 'unsigned', 'yes', 'dry-run', 'confirm', 'port', 'sign-url-file', 'remote'];
 /** Auto-detect the on-chain representation for an off-chain locator by its URI scheme. Returns null
  *  for anything that isn't a recognized durable/http locator (so `attach` can refuse it loudly
  *  rather than silently storing a bad value — the round-1 `--representation` guessing trap). */
@@ -72,21 +76,10 @@ export function representationForLocator(uri) {
         return R.url;
     return null;
 }
-function chainId() {
-    return resolveChain(CHAIN).id;
-}
-/** Resolve the signing lane from flags: --unsigned (cold) · --sign (wallet) · default hot. */
-export function laneFromFlags(flags) {
-    if (flags.unsigned)
-        return 'unsigned';
-    if (flags.sign)
-        return 'sign';
-    return 'send';
-}
 function requireAddress(address, usage) {
     if (!address || address.startsWith('--')) {
         console.error(`usage: ${usage}\n`);
-        process.exit(1);
+        throw new CliError('', 1, true); // already printed above — see CliError's alreadyPrinted doc
     }
     return address;
 }
@@ -94,12 +87,10 @@ function requireFlag(flags, name, usage) {
     const v = flags[name];
     if (!v || v === 'true') {
         console.error(`missing --${name}\nusage: ${usage}\n`);
-        process.exit(1);
+        throw new CliError('', 1, true); // already printed above — see CliError's alreadyPrinted doc
     }
     return v;
 }
-/** Run a prepared write through the chosen lane, then re-index if the project is known.
- *  Returns whether anything was BROADCAST (false on the cold lane — the tx was only printed). */
 /**
  * Every owner-op's send choke point. Returns the {@link SignResult} when a tx was broadcast, else
  * `null` (dry run, or the cold lane which prints a tx instead of sending one).
@@ -108,39 +99,20 @@ function requireFlag(flags, name, usage) {
  * *receipt* — `abx mint --json` has to report which token id was actually minted, and the only
  * authoritative answer is the Transfer log the mint emitted. Callers that only asked "did it send?"
  * keep working: `null` is falsy, and a result object is truthy.
+ *
+ * The dry-run preview / `--confirm` prompt / lane selection live in {@link gatedSend} — the SAME
+ * choke point the deploy family's resumed-setup send routes through — so this is now just "gate,
+ * then re-index if the project is known."
  */
 async function runWrite(address, provider, flags, expectedSigner) {
-    // --dry-run: preview the exact tx and send NOTHING. This is the shared choke point for every
-    // owner-op, so --dry-run is uniform across them — it must never fall through to a real send just
-    // because the flag isn't wired per-command (a round-1 finding: `set-field --dry-run` silently
-    // reached the send lane and only stopped for lack of a key).
-    if (flags['dry-run']) {
-        const prepared = typeof provider === 'function' ? await provider(expectedSigner ?? zeroAddress) : provider;
-        console.log(`\n  ${C.bold}◆ ${prepared.summary}${C.reset}  ${dim('(dry run — nothing sent)')}`);
-        for (const [k, v] of Object.entries(prepared.fields))
-            console.log(`    ${dim(k.padEnd(12))} ${v}`);
-        console.log(`    ${dim('to'.padEnd(12))} ${prepared.to ?? dim('(contract deploy)')}`);
-        if (expectedSigner)
-            console.log(`    ${dim('owner'.padEnd(12))} ${expectedSigner}`);
-        console.log(dim(`\n  Re-run without --dry-run to send (lane: ${laneFromFlags(flags)}).\n`));
-        return null;
-    }
-    await assertChainId(CHAIN); // verify the RPC really is CHAIN before any irreversible write
-    const result = await signTx(provider, {
-        lane: laneFromFlags(flags),
-        chainKey: CHAIN,
-        expectedSigner,
-        yes: !!flags.yes,
-        port: flags.port ? Number(flags.port) : undefined,
-        signUrlFile: flags['sign-url-file'],
-    });
+    const result = await gatedSend(provider, flags, { chainKey: CHAIN, expectedSigner });
     if (!result)
-        return null; // cold lane — nothing broadcast
+        return null; // dry run, or the cold lane — nothing broadcast
     await reindexIfKnown(address, flags);
     return result;
 }
 async function reindexIfKnown(address, flags) {
-    const indexer = new SelfHostIndexer();
+    const indexer = localIndexer();
     if (indexer.store.getRegistration(address)) {
         const { state, elapsedMs } = await indexer.reindex(address);
         console.log(`  ${green('✓')} re-indexed ${state.name ?? address}: ${state.eventCount} events in ${elapsedMs}ms`);
@@ -181,22 +153,22 @@ async function reindexIfKnown(address, flags) {
 }
 async function read(address, functionName, args = []) {
     const publicClient = makePublicClient({ chainKey: CHAIN });
-    try {
-        return (await publicClient.readContract({
-            address,
-            abi: oneOfOneImageAbi,
-            functionName: functionName,
-            args: args,
-        }));
-    }
-    catch (err) {
-        // A read that "returned no data" is usually not a real revert but an address with NO CONTRACT —
-        // previewing before deploy, a typo'd address, or the wrong chain. Every owner-op reads the
-        // owner/ownerOf here FIRST, so this one guard turns the opaque viem error into an actionable one
-        // across all of them. Only runs on the error path (zero cost when the contract exists).
-        await assertContractExists(address);
-        throw err; // the contract DOES exist → surface the original error (a genuine revert)
-    }
+    const result = await tryReadContract(publicClient, { address, abi: oneOfOneImageAbi, functionName, args });
+    if (result !== undefined)
+        return result;
+    // A read that "returned no data" is usually not a real revert but an address with NO CONTRACT —
+    // previewing before deploy, a typo'd address, or the wrong chain. Every owner-op reads the
+    // owner/ownerOf here FIRST, so this one guard turns the opaque viem error into an actionable one
+    // across all of them. Only runs on the error path (zero cost when the contract exists).
+    await assertContractExists(address);
+    // The contract DOES exist → a genuine revert. tryReadContract already swallowed that error, so
+    // re-read once (uncaught) to surface it rather than a generic "read failed".
+    return (await publicClient.readContract({
+        address,
+        abi: oneOfOneImageAbi,
+        functionName: functionName,
+        args: args,
+    }));
 }
 /** Throw a clear, actionable error when `address` has no contract on the active chain — the common
  *  cause of an owner-op's raw `returned no data ("0x")`. No-op when code is present or unknowable. */
@@ -267,7 +239,8 @@ export async function cmdConfigureParam(address, rest, flags) {
     const valueInput = valueParts.join(' ');
     if (!tokenIdRaw || !key || (!valueInput && !flags.file)) {
         console.error(`usage: ${usage}\n`);
-        process.exit(1);
+        process.exitCode = 1;
+        return;
     }
     const publicClient = makePublicClient({ chainKey: CHAIN });
     const schema = (await publicClient.readContract({
@@ -450,7 +423,8 @@ export async function cmdSetDependency(address, rest, flags) {
     const [indexRaw, refRaw] = positionalArgs(rest);
     if (indexRaw === undefined || !refRaw) {
         console.error(`usage: ${usage}\n`);
-        process.exit(1);
+        process.exitCode = 1;
+        return;
     }
     if (!/^\d+$/.test(indexRaw))
         throw new Error(`<index> must be a non-negative integer (got '${indexRaw}') — the list is dense: index ≤ dependencyCount`);
@@ -474,7 +448,8 @@ export async function cmdSetDependencyRegistry(address, rest, flags) {
     const [raw] = positionalArgs(rest);
     if (!raw) {
         console.error(`usage: ${usage}\n`);
-        process.exit(1);
+        process.exitCode = 1;
+        return;
     }
     if (raw !== 'none' && !/^0x[0-9a-fA-F]{40}$/.test(raw)) {
         throw new Error(`<registry> must be an address (0x + 40 hex) or 'none' to clear; got '${raw}'`);
@@ -520,7 +495,7 @@ export async function cmdMint(address, flags) {
             tx = prepareMint({ contract, to, chainId: chainId() });
         }
         const result = await runWrite(contract, tx, flags, owner);
-        const tokenIds = result ? await mintedTokenIds(contract, result.txHash) : [];
+        const tokenIds = result ? await mintedTokenIds(makePublicClient({ chainKey: CHAIN }), contract, result.txHash) : [];
         if (result && tokenIds.length) {
             console.log(`  ${green('✓')} minted token${tokenIds.length > 1 ? 's' : ''} ${bold(tokenIds.map((t) => '#' + t).join(', '))} → ${to}`);
         }
@@ -539,43 +514,6 @@ export async function cmdMint(address, flags) {
         };
     });
 }
-/**
- * The token ids a mint actually created, decoded from its receipt's `Transfer(from=0x0)` logs.
- *
- * Authoritative by construction: the ids come from the transaction that minted them, so a
- * `--count N` batch reports all N and a concurrent mint elsewhere cannot skew the answer. Returns
- * `[]` rather than throwing if the receipt can't be read — a mint that landed on-chain must not be
- * reported as failed because a follow-up read hiccuped.
- */
-async function mintedTokenIds(contract, txHash) {
-    try {
-        const publicClient = makePublicClient({ chainKey: CHAIN });
-        const receipt = await publicClient.getTransactionReceipt({ hash: txHash });
-        const ids = [];
-        for (const log of receipt.logs) {
-            if (log.address.toLowerCase() !== contract.toLowerCase())
-                continue;
-            try {
-                const decoded = decodeEventLog({ abi: oneOfOneImageAbi, data: log.data, topics: log.topics });
-                if (decoded.eventName !== 'Transfer')
-                    continue;
-                const args = decoded.args;
-                if (args.from && args.from !== zeroAddress)
-                    continue; // a transfer, not a mint
-                const id = args.id ?? args.tokenId;
-                if (id !== undefined)
-                    ids.push(id.toString());
-            }
-            catch {
-                continue; // a log from another interface on the same contract
-            }
-        }
-        return ids.sort((a, b) => Number(BigInt(a) - BigInt(b)));
-    }
-    catch {
-        return [];
-    }
-}
 // ── series owner ops (minter set · supply cap · primary payee) ────────────────
 // The multi-token knobs. All owner-only; each runs through the same signing lane +
 // re-index as every other owner op.
@@ -817,7 +755,8 @@ export async function cmdSetTransferValidator(address, rest, flags) {
     const [raw] = positionalArgs(rest);
     if (!raw) {
         console.error(`usage: ${usage}\n`);
-        process.exit(1);
+        process.exitCode = 1;
+        return;
     }
     const cid = chainId();
     const validator = parseTransferValidatorValue(raw, { chainId: cid, chainLabel: CHAIN, allowNone: true });
@@ -859,16 +798,41 @@ export async function cmdSetTransferValidator(address, rest, flags) {
     const owner = await read(contract, 'owner');
     await runWrite(contract, prepareSetTransferValidator({ contract, validator, chainId: cid }), flags, owner);
 }
+// ── multi-chunk on-chain content (the `reader` path) ─────────────────────────
+// The plan math (chunk count + tx shape), the cost-model constants, and the actual
+// plan→resolve-store→stage→encode orchestration all live in the SDK's staging.ts, layered on
+// planChunks/planContentTxs/stageContent/encodeReader/ensureChunkStore — see its module doc. What
+// stays here is Node-only (reading the file, gzip) plus the narration: every console.log below is
+// this file's onEvent handler for the SDK's `StagingEvent`, so the lines are unchanged from before
+// the move.
 export function parseCompress(v) {
     const c = (v ?? 'none').toLowerCase();
     if (c === 'none' || c === 'fastlz' || c === 'gzip')
         return c;
     throw new Error(`--compress must be none | fastlz | gzip (got '${v}')`);
 }
+/** The chunk-store bootstrap narration shared by every content-staging path below — one place so
+ *  the lines are identical whether the store is resolved for a single field ({@link putContentOnChain}
+ *  → the SDK's `stageFieldContent`) or once up front for a whole batch ({@link ensureChunkStore}). */
+function printChunkStoreEvent(e) {
+    if (e.kind === 'stale')
+        console.log(yellow(`  configured chunk store ${e.address} is a stale deployment (no writeContent) — deploying a current one`));
+    else if (e.kind === 'canonical')
+        console.log(dim(`  using the canonical chunk store at its deterministic address ${e.address}`));
+    else if (e.kind === 'deploying')
+        console.log(dim('  deploying the canonical multi-chunk content store (AbxChunkStore) — CREATE2…'));
+    else {
+        console.log(`  ${green('✓')} chunk store ${e.address}`);
+        console.log(dim(`  not in the shipped manifest for ${CHAIN} — to reuse it set ABX_CHUNK_STORE=${e.address} (or add it to packages/sdk/src/deployments.ts)`));
+    }
+}
 /**
  * The chain's shared multi-chunk store/reader; deploy it once if missing, signing through
  * `send` (the env key on the hot lane, or the connected wallet on the wallet lane) — the
- * store is ownerless, so any funded signer can stand it up.
+ * store is ownerless, so any funded signer can stand it up. Used directly only by
+ * {@link stageImageFieldsBatch} (resolving ONE store up front for every token); a single-field
+ * stage ({@link putContentOnChain}) resolves its store through the SDK's `stageFieldContent`
+ * instead, which calls the very same SDK `ensureChunkStore` internally.
  */
 async function ensureChunkStore(send, override) {
     // The resolution logic lives in the SDK (`ensureChunkStore`) so an SDK integrator bootstraps
@@ -876,99 +840,46 @@ async function ensureChunkStore(send, override) {
     // incapable store fails deep inside a mint, after transactions have landed. The CLI keeps only the
     // narration: the SDK reports progress through `onEvent` rather than printing.
     const publicClient = makePublicClient({ chainKey: CHAIN });
-    return sdkEnsureChunkStore(publicClient, send, {
-        chainId: chainId(),
-        override,
-        onEvent: (e) => {
-            if (e.kind === 'stale')
-                console.log(yellow(`  configured chunk store ${e.address} is a stale deployment (no writeContent) — deploying a current one`));
-            else if (e.kind === 'canonical')
-                console.log(dim(`  using the canonical chunk store at its deterministic address ${e.address}`));
-            else if (e.kind === 'deploying')
-                console.log(dim('  deploying the canonical multi-chunk content store (AbxChunkStore) — CREATE2…'));
-            else {
-                console.log(`  ${green('✓')} chunk store ${e.address}`);
-                console.log(dim(`  not in the shipped manifest for ${CHAIN} — to reuse it set ABX_CHUNK_STORE=${e.address} (or add it to packages/sdk/src/deployments.ts)`));
-            }
-        },
-    });
+    return sdkEnsureChunkStore(publicClient, send, { chainId: chainId(), override, onEvent: printChunkStoreEvent });
 }
 /**
- * The hot-lane staging signer: the env key signs + broadcasts each chunk-store write. Built
- * lazily so commands that never stage on-chain don't require a key. The wallet lane passes a
- * session-backed sender instead (see {@link openWalletSession}); the cold lane can't stage
- * interactively, so it's rejected up front by the deploy/set-field commands.
+ * The hot-lane staging signer: the env key signs + broadcasts each chunk-store write, via the
+ * SDK's `makeHotSender` (pinned nonce, pinned gas, typed revert). Built lazily so commands that
+ * never stage on-chain don't require a key. The wallet lane passes a session-backed sender
+ * instead (see {@link openWalletSession}); the cold lane can't stage interactively, so it's
+ * rejected up front by the deploy/set-field commands.
  */
 export function envStagingSender() {
     const { wallet, account } = makeWalletClient({ chainKey: CHAIN });
     const publicClient = makePublicClient({ chainKey: CHAIN });
-    return async (tx) => {
-        const hash = await wallet.sendTransaction({
-            account,
-            chain: wallet.chain,
-            to: tx.to ?? undefined,
-            data: tx.data,
-            value: 0n,
-        });
-        return publicClient.waitForTransactionReceipt({ hash });
-    };
+    return makeHotSender({ wallet, account, publicClient });
 }
 /** Wallet-lane staging signer: each chunk-store write is approved in the human's browser
- *  wallet through the open {@link WalletSession}, sharing one connection with the final tx. */
+ *  wallet through the open {@link WalletSession}, sharing one connection with the final tx. A
+ *  {@link PreparedTx} already carries everything `session.send` needs, so this is a thin adapter. */
 export function sessionStagingSender(session) {
-    const id = chainId();
-    return async (tx) => (await session.send({
-        op: 'stage',
-        to: tx.to,
-        data: tx.data,
-        value: '0x0',
-        chainId: id,
-        summary: tx.summary,
-        fields: tx.fields,
-    })).receipt;
+    return async (tx) => (await session.send(tx)).receipt;
 }
-/**
- * Put `content` on-chain as SSTORE2 chunks behind the shared reader, and return the field's
- * `(representation, value)`. `fastlz` compresses per chunk (reader decodes on read → stays
- * on-chain renderable); `gzip` compresses the whole content (off-chain decode → the
- * `reader-gzip` representation, not on-chain renderable).
- *
- * Staging is one atomic `writeContent` when the content fits a single tx's gas, else
- * gas-bounded chunk-write `multicall`s plus a final manifest write — {@link stageContent}
- * picks, and we print the tx plan up front so the human knows the count before signing.
- * These store writes use the env key (the data contracts are ownerless); the owner only
- * signs the field set that references the manifest.
- */
-/**
- * Pure staging plan for a piece of content — chunk count + transaction shape — with NO
- * chain writes, no signer, no `ensureChunkStore`. Shared by {@link putContentOnChain}
- * (which then actually stages) and the deploy dry-run preview, so the count the human is
- * told up front is the same one the real staging will produce. `chunkSize` defaults to the
- * SDK's {@link planChunks} default (currently 22 KB), so e.g. a 2.8 KB SVG is 1 chunk.
- */
-// On-chain image storage costs ~200 gas/byte (SSTORE2 code deposit) + per-chunk tx overhead, so it
-// is cost-effective ONLY for tiny art. Past these soft limits, off-chain (Arweave pay-once, or a
-// hosted resolver + IPFS) is FAR cheaper — on-chain's remaining edge is self-resolution, not cost.
-// Per-file limit ≈ one 22 KB storage chunk; project limit caps the whole collection's gas.
-export const ONCHAIN_IMAGE_SOFT_LIMIT = 24 * 1024; // per file
-export const ONCHAIN_PROJECT_SOFT_LIMIT = 256 * 1024; // whole collection
 const kb = (n) => `${n < 10 * 1024 ? (n / 1024).toFixed(1) : Math.round(n / 1024)}KB`;
 /** Warn (loudly) when content is too big for on-chain to be the cost-sane choice. Returns true if it warned. */
 export function warnIfLargeForOnChain(bytesLen, label) {
-    if (bytesLen <= ONCHAIN_IMAGE_SOFT_LIMIT)
+    if (!exceedsOnchainSoftLimit(bytesLen))
         return false;
     console.log(yellow(`  ⚠ ${label} is ${kb(bytesLen)} — large for ON-CHAIN storage (~200 gas/byte). Past ~${kb(ONCHAIN_IMAGE_SOFT_LIMIT)}/file, on-chain is FAR more expensive than off-chain, not cheaper.`));
     console.log(dim(`    For art this size prefer off-chain: --backend arweave (pay-once, permanent) or a hosted resolver + IPFS. Use on-chain only if self-resolution is a hard requirement.`));
     return true;
 }
+/**
+ * Pure staging plan for a piece of content — chunk count + transaction shape — with NO chain
+ * writes, no signer, no `ensureChunkStore`. The CLI-facing wrapper over the SDK's pure
+ * {@link planStagedContent}: `gzip` is a Node-only transform, so it happens here (not in the SDK —
+ * see staging.ts's module doc) before handing the result off to the SDK's chunk/tx-shape math.
+ * Shared by {@link putContentOnChain} (which then actually stages) and the deploy dry-run preview,
+ * so the count the human is told up front is the same one the real staging will produce.
+ */
 export function computeContentPlan(bytes, compress) {
     const content = compress === 'gzip' ? new Uint8Array(gzipSync(bytes)) : new Uint8Array(bytes);
-    const fastlz = compress === 'fastlz';
-    const planned = planChunks(content, { fastlz });
-    const plan = planContentTxs(planned);
-    const representation = compress === 'gzip' ? R.readerGzip : R.reader;
-    const stagedBytes = planned.reduce((n, c) => n + c.data.length, 0);
-    return { content, fastlz, chunks: planned.length, stagedBytes, plan, representation };
+    return planStagedContent(content, compress);
 }
 /** Human-readable size line for a content plan, e.g. `2812B → 1 chunk [fastlz 2812→904B]`. */
 function planSizeLine(bytes, p, compress) {
@@ -990,15 +901,43 @@ function planTxLine(p, finalLabel) {
         ? `plan: 1 staging tx (atomic writeContent) + ${finalLabel} = 2 transactions`
         : `plan: ${p.plan.batches.length} chunk-batch tx(s) + 1 manifest tx + ${finalLabel} = ${p.plan.txCount + 1} transactions`;
 }
+/**
+ * Put `bytes` on-chain as SSTORE2 chunks behind the shared reader, and return the field's
+ * `(representation, value)`. `fastlz` compresses per chunk (reader decodes on read → stays
+ * on-chain renderable); `gzip` compresses the whole content (off-chain decode → the
+ * `reader-gzip` representation, not on-chain renderable) — done here, not in the SDK's
+ * `stageFieldContent` (a Node-only transform; see staging.ts's module doc).
+ *
+ * Staging is one atomic `writeContent` when the content fits a single tx's gas, else
+ * gas-bounded chunk-write `multicall`s plus a final manifest write — the SDK picks, and we
+ * print the tx plan up front (via its `onEvent`) so the human knows the count before signing.
+ * These store writes use the env key (the data contracts are ownerless); the owner only
+ * signs the field set that references the manifest.
+ */
 async function putContentOnChain(bytes, compress, field, send, finalLabel = '1 owner field-set', store) {
-    const p = computeContentPlan(bytes, compress);
     warnIfLargeForOnChain(bytes.length, `'${field}'`);
-    const resolvedStore = store ?? (await ensureChunkStore(send));
-    console.log(dim(`  '${field}' on-chain: ${planSizeLine(bytes.length, p, compress)} via reader ${resolvedStore}`));
-    console.log(dim(`    ${planTxLine(p, finalLabel)}`));
-    const { manifest, txHashes } = await stageContent(send, { store: resolvedStore, content: p.content, fastlz: p.fastlz });
-    console.log(dim(`    staged in ${txHashes.length} tx(s); manifest → ${manifest}`));
-    return { value: encodeReader(resolvedStore, manifest), representation: p.representation };
+    const content = compress === 'gzip' ? new Uint8Array(gzipSync(bytes)) : new Uint8Array(bytes);
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    return stageFieldContent({
+        content,
+        compress,
+        field,
+        send,
+        publicClient,
+        chainId: chainId(),
+        store,
+        onEvent: (e) => {
+            if (e.kind === 'chunk-store')
+                printChunkStoreEvent(e.event);
+            else if (e.kind === 'planned') {
+                console.log(dim(`  '${field}' on-chain: ${planSizeLine(bytes.length, e.contentPlan, compress)} via reader ${e.store}`));
+                console.log(dim(`    ${planTxLine(e.contentPlan, finalLabel)}`));
+            }
+            else {
+                console.log(dim(`    staged in ${e.txHashes.length} tx(s); manifest → ${e.manifest}`));
+            }
+        },
+    });
 }
 /**
  * Dry-run preview of staging an image fully on-chain — the REAL chunk + transaction plan,
@@ -1113,7 +1052,7 @@ export async function cmdSetField(address, flags) {
     const staging = !!(flags.file && flags.file !== 'true'); // large content ON-CHAIN via chunk store/reader
     // --file + --dry-run: preview the on-chain staging plan and store/send NOTHING. (The locator/text
     // path flows through runWrite, which previews there; staging must short-circuit before any upload.)
-    if (staging && flags['dry-run']) {
+    if (staging && isDryRun(flags)) {
         const bytes = readFileSync(resolvePath(flags.file));
         const p = computeContentPlan(bytes, parseCompress(flags.compress));
         console.log(`\n  ${bold('◆ set-field ' + field)} ${dim('(dry run — nothing staged or sent)')}`);
@@ -1222,13 +1161,15 @@ export async function cmdAttach(rest, flags) {
     const contract = requireAddress(address, usage);
     if (!key) {
         console.error(`usage: ${usage}\n  the <key> is the name your file appears under in the manifest (e.g. print, certificate, stems, readme).\n`);
-        process.exit(1);
+        process.exitCode = 1;
+        return;
     }
     assertSettableField(key);
     const hasFile = !!(flags.file && flags.file !== 'true');
     if (!uri && !hasFile) {
         console.error(`usage: ${usage}\n  pass a locator URI (ipfs://… / ar://… / https://…) or --file <path> to store bytes on-chain.\n`);
-        process.exit(1);
+        process.exitCode = 1;
+        return;
     }
     if (uri && hasFile)
         throw new Error('pass EITHER a locator URI OR --file <path>, not both.');
@@ -1429,16 +1370,6 @@ async function readSeries(token, fn, args = []) {
         args: args,
     }));
 }
-async function readSale(minter, token) {
-    const publicClient = makePublicClient({ chainKey: CHAIN });
-    const [configured, paymentToken, price, allocation, sold] = (await publicClient.readContract({
-        address: minter,
-        abi: abxFixedPriceMinterAbi,
-        functionName: 'sales',
-        args: [token],
-    }));
-    return { configured, paymentToken, price, allocation, sold };
-}
 /** Resolve the shared minter for the chain (flag → env → manifest), or deploy it if none exists.
  *  It's ownerless, so any funded signer can stand it up — the sibling of `ensureChunkStore`. */
 async function ensureFixedPriceMinter(override) {
@@ -1461,38 +1392,23 @@ async function ensureFixedPriceMinter(override) {
         }
     }
     const { wallet, account } = makeWalletClient({ chainKey: CHAIN });
+    const send = makeHotSender({ wallet, account, publicClient });
     console.log(dim('  deploying the canonical fixed-price minter (shared, ownerless) — CREATE2…'));
-    const { minter, txHash } = await deployFixedPriceMinter(wallet, account, publicClient);
+    const { minter, txHash } = await deployFixedPriceMinter(send, publicClient);
     console.log(`  ${green('✓')} fixed-price minter ${minter}`);
     console.log(dim(`  tx ${txHash}`));
     console.log(dim(`  not in the shipped manifest for ${CHAIN} — to reuse it set ${bold(`ABX_FIXED_PRICE_MINTER=${minter}`)} (or add it to packages/sdk/src/deployments.ts)`));
     return minter;
 }
 /** A minter write (configure/buy). No re-index — the sale lives on the minter, not the token
- *  projection; the token's own state is unchanged by a sale config. */
+ *  projection; the token's own state is unchanged by a sale config.
+ *
+ * Used to hand-roll its own dry-run guard — "the minter path does not go through runWrite, so it
+ * needs its OWN" — which is exactly the duplication {@link gatedSend} exists to end: this now shares
+ * the identical choke point `runWrite` does, so `minter configure`/`minter buy` also pick up
+ * `--confirm` (previously only the deploy family had it) with no extra code here. */
 async function runMinterWrite(provider, flags, expectedSigner) {
-    // --dry-run: preview the sale-config / purchase tx and send NOTHING. The minter path does not go
-    // through runWrite, so it needs its OWN dry-run guard — without it, `minter configure --dry-run`
-    // silently signs + broadcasts a real sale (a critical footgun: a mainnet creator "previewing"
-    // their sale would send it). Mirrors runWrite's guard.
-    if (flags['dry-run']) {
-        const prepared = typeof provider === 'function' ? await provider(expectedSigner ?? zeroAddress) : provider;
-        console.log(`\n  ${bold('◆ ' + prepared.summary)}  ${dim('(dry run — nothing sent)')}`);
-        for (const [k, v] of Object.entries(prepared.fields))
-            console.log(`    ${dim(k.padEnd(12))} ${v}`);
-        console.log(`    ${dim('to'.padEnd(12))} ${prepared.to ?? dim('(contract deploy)')}`);
-        console.log(dim(`\n  Re-run without --dry-run to send (lane: ${laneFromFlags(flags)}).\n`));
-        return;
-    }
-    await assertChainId(CHAIN);
-    await signTx(provider, {
-        lane: laneFromFlags(flags),
-        chainKey: CHAIN,
-        expectedSigner,
-        yes: !!flags.yes,
-        port: flags.port ? Number(flags.port) : undefined,
-        signUrlFile: flags['sign-url-file'],
-    });
+    await gatedSend(provider, flags, { chainKey: CHAIN, expectedSigner });
 }
 /** Parse the sale price: `--price-raw <units>` (exact base units) or the friendly `--price <ether>`
  *  (18-decimals). ETH sales use `--price`; non-18-dp ERC-20s should use `--price-raw`. */
@@ -1502,7 +1418,7 @@ function parseSalePrice(flags, usage) {
     if (flags.price && flags.price !== 'true')
         return parseEther(flags.price);
     console.error(`missing --price <ether> or --price-raw <units>\nusage: ${usage}\n`);
-    process.exit(1);
+    throw new CliError('', 1, true); // already printed above — see CliError's alreadyPrinted doc
 }
 /**
  * `abx minter configure <token> --price <eth> --allocation <n> [--erc20 0x…]` — set the fixed-price
@@ -1519,7 +1435,7 @@ export async function cmdMinterConfigure(address, flags) {
     const price = parseSalePrice(flags, usage);
     // On --dry-run resolve the minter WITHOUT deploying — ensureFixedPriceMinter would deploy the
     // shared singleton if absent, and a preview must never send. Fall back to a label if none exists.
-    const dryRun = !!flags['dry-run'];
+    const dryRun = isDryRun(flags);
     const knownMinter = fixedPriceMinterAddress(flags['minter-contract']);
     if (dryRun && !knownMinter) {
         console.log(yellow(`  ⚠ no shared minter deployed on ${CHAIN} yet — a real run deploys it once (a separate tx) before configuring.`));
@@ -1575,7 +1491,7 @@ export async function cmdMinterShow(address, flags) {
         console.log(yellow(`  no shared minter known for ${CHAIN} — configure a sale (deploys it) or set ABX_FIXED_PRICE_MINTER`));
         return;
     }
-    const sale = await readSale(minter, token);
+    const sale = await readSaleConfig(makePublicClient({ chainKey: CHAIN }), minter, token);
     const [assignedMinter, payee, paused, max, supply] = await Promise.all([
         readSeries(token, 'minter').catch(() => zeroAddress),
         readSeries(token, 'primaryPayee').catch(() => zeroAddress),
@@ -1614,7 +1530,7 @@ export async function cmdMinterBuy(address, flags) {
     const minter = fixedPriceMinterAddress(flags['minter-contract']);
     if (!minter)
         throw new Error(`no shared minter known for ${CHAIN} — configure a sale first, or set ABX_FIXED_PRICE_MINTER`);
-    const sale = await readSale(minter, token);
+    const sale = await readSaleConfig(makePublicClient({ chainKey: CHAIN }), minter, token);
     if (!sale.configured)
         throw new Error(`no sale configured for ${token} — run: abx minter configure ${token} …`);
     const isEth = sale.paymentToken === zeroAddress;
@@ -1662,7 +1578,8 @@ export async function cmdSetSchema(address, flags) {
     const specs = parseSchemaSpecs(flags.schema);
     if (specs.length !== 1) {
         console.error(`usage: ${usage}\n\n  One key per call — a schema write is a full-row upsert, so batching them hides which one changed.\n`);
-        process.exit(1);
+        process.exitCode = 1;
+        return;
     }
     const next = specs[0];
     const publicClient = makePublicClient({ chainKey: CHAIN });
@@ -1734,7 +1651,8 @@ export async function cmdRetireParam(address, rest, flags) {
     const [key] = positionalArgs(rest);
     if (!key) {
         console.error(`usage: ${usage}\n`);
-        process.exit(1);
+        process.exitCode = 1;
+        return;
     }
     const publicClient = makePublicClient({ chainKey: CHAIN });
     const owner = await read(contract, 'owner');