@artblocks/abx-cli 0.1.0-alpha.16 → 0.1.0-alpha.18

package/dist/ownerops.js

@@ -6,10 +6,9 @@
  * 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, 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';
@@ -17,12 +16,18 @@ import { readFileSync } from 'node:fs';
 import { basename, resolve as resolvePath } from 'node:path';
 import { gzipSync } from 'node:zlib';
 import { formatEther, getAddress, isAddress, parseEther, toHex, zeroAddress } from 'viem';
-import { fixedPriceMinterAddress } from './config.js';
-import { openWalletSession, signTx } from './signer.js';
+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}`;
@@ -57,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). */
@@ -71,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;
 }
@@ -93,44 +87,32 @@ 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).
+ *
+ * It used to return a bare boolean. It returns the result now because a caller sometimes needs the
+ * *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 false;
-    }
-    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 false; // cold lane — nothing broadcast
+        return null; // dry run, or the cold lane — nothing broadcast
     await reindexIfKnown(address, flags);
-    return true;
+    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`);
@@ -171,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. */
@@ -257,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({
@@ -440,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`);
@@ -464,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}'`);
@@ -487,24 +472,47 @@ export async function cmdLockDependencies(address, flags) {
 // it mints the next sequential token id (metadata = token id): bare (one), or `--count <n>`
 // (n in order). Owner or an authorized minter signs.
 export async function cmdMint(address, flags) {
-    const usage = 'abx mint <address> [--to 0x…] [--count <n>] [--sign|--unsigned]';
+    const usage = 'abx mint <address> [--to 0x…] [--count <n>] [--json] [--sign|--unsigned]';
     const contract = requireAddress(address, usage);
-    const owner = await read(contract, 'owner');
-    const to = flags.to ?? owner; // default: pre-mint to the admin
-    let tx;
-    if (flags.count !== undefined && flags.count !== 'true') {
-        const count = BigInt(flags.count);
-        console.log(dim(`  minting ${count} Series tokens in order → ${to}`));
-        tx = prepareSeriesMintMany({ contract, to, count, chainId: chainId() });
-    }
-    else {
-        // Bare mint: the `mint(address)` selector is shared by the 1/1 (token #0) and a
-        // Series (next sequential token) — one path serves both.
-        console.log(dim(`  minting token → ${to}${flags.to ? '' : ' (owner — pass --to for a buyer)'}`));
-        tx = prepareMint({ contract, to, chainId: chainId() });
-    }
-    await runWrite(contract, tx, flags, owner);
-    console.log(dim(`  next: \`abx refresh ${contract}\` so marketplaces pick up the new token.`));
+    // `--json`: the TOKEN ID is the value a program came for, and it was previously only obtainable by
+    // regex-scraping coloured prose (B19). It is read from the mint's own Transfer logs rather than by
+    // re-reading `nextTokenId` afterwards — a concurrent mint would make that answer wrong, and a
+    // number that is usually right is worse than no number.
+    return withJson(flags, async () => {
+        const owner = await read(contract, 'owner');
+        const to = flags.to ?? owner; // default: pre-mint to the admin
+        let tx;
+        let count = 1n;
+        if (flags.count !== undefined && flags.count !== 'true') {
+            count = BigInt(flags.count);
+            console.log(dim(`  minting ${count} Series tokens in order → ${to}`));
+            tx = prepareSeriesMintMany({ contract, to, count, chainId: chainId() });
+        }
+        else {
+            // Bare mint: the `mint(address)` selector is shared by the 1/1 (token #0) and a
+            // Series (next sequential token) — one path serves both.
+            console.log(dim(`  minting token → ${to}${flags.to ? '' : ' (owner — pass --to for a buyer)'}`));
+            tx = prepareMint({ contract, to, chainId: chainId() });
+        }
+        const result = await runWrite(contract, tx, flags, owner);
+        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}`);
+        }
+        console.log(dim(`  next: \`abx refresh ${contract}\` so marketplaces pick up the new token.`));
+        return {
+            contract,
+            chainId: chainId(),
+            to,
+            // `sent: false` is the dry-run and cold-lane answer — an empty tokenIds with no explanation
+            // would read as a failed mint.
+            sent: !!result,
+            txHash: result?.txHash ?? null,
+            blockNumber: result ? String(result.blockNumber) : null,
+            tokenIds,
+            requestedCount: Number(count),
+        };
+    });
 }
 // ── series owner ops (minter set · supply cap · primary payee) ────────────────
 // The multi-token knobs. All owner-only; each runs through the same signing lane +
@@ -747,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 });
@@ -789,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
@@ -806,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) {
@@ -920,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,
@@ -1043,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)')}`);
@@ -1119,9 +1128,25 @@ export async function cmdSetField(address, flags) {
  *   - computed keys (`artifacts`, `abx_provenance`) are refused — they're the manifest, not inputs.
  * Scope: token (`--token`, default 0) or `--collection`. Any signing lane. Owner-only.
  */
+/**
+ * Attach one or more artifacts. Several `<key> <uri>` pairs in one invocation become **one
+ * transaction**.
+ *
+ * That batching is a safety fix, not a convenience (backlog B20). The CLI's most-documented flow —
+ * mint, then attach each artifact, then refresh — sent one transaction per step with no all-or-nothing
+ * boundary, so a failure partway through left a permanently half-written token that cannot be
+ * un-minted. An integrator hit exactly this and folded 8 operations into 1 transaction using the SDK's
+ * `batchOps`, which the CLI already shipped and did not use. Now it does: N pairs are one
+ * `multicall`, so either every artifact lands or none does.
+ *
+ * A single pair passes through `batchOps` untouched, so the one-artifact case sends the identical
+ * transaction it always did.
+ */
 export async function cmdAttach(rest, flags) {
-    const usage = 'abx attach <address> <key> <ipfs://… | ar://… | https://…>   [--file <path>] [--collection | --token 0] [--sign|--unsigned] [--dry-run]';
-    const [address, key, uri] = positionalArgs(rest);
+    const usage = 'abx attach <address> <key> <ipfs://… | ar://… | https://…> [<key> <uri> …]   [--file <path>] [--collection | --token 0] [--sign|--unsigned] [--dry-run]';
+    const [address, ...pairArgs] = positionalArgs(rest);
+    const key = pairArgs[0];
+    const uri = pairArgs[1];
     // Warn (never throw) on an unrecognized flag — a typo or a hopeful `--mime-type` otherwise no-ops
     // INVISIBLY (round-1: an agent passed `--mime-type` and it was silently swallowed). mimeType is
     // declared from the URL extension, not a flag; say so.
@@ -1136,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.');
@@ -1156,19 +1183,44 @@ export async function cmdAttach(rest, flags) {
     // Locator path (the common case): auto-detect the representation, refuse an unrecognized scheme
     // loudly (never silently store a bad value) — fail fast before any RPC. Derive the declared
     // mimeType from the extension.
-    const representation = representationForLocator(uri);
-    if (!representation) {
-        throw new Error(`"${uri}" isn't a recognized file locator. Use ipfs://… (pinned/IPFS), ar://… (Arweave), or https://… . ` +
-            'To store literal text or raw bytes on-chain instead, use `abx set-field`.');
+    // Every `<key> <uri>` pair, validated BEFORE anything is sent — a batch that would revert partway
+    // is exactly what this command now exists to prevent, so a bad locator in pair 5 must stop pair 1.
+    if (pairArgs.length % 2 !== 0) {
+        throw new Error(`attach takes <key> <uri> PAIRS; got ${pairArgs.length} positional argument(s) after the address. ` +
+            `Last one seen: "${pairArgs[pairArgs.length - 1]}".`);
+    }
+    const pairs = [];
+    for (let i = 0; i < pairArgs.length; i += 2) {
+        const k = pairArgs[i];
+        const u = pairArgs[i + 1];
+        assertSettableField(k);
+        const rep = representationForLocator(u);
+        if (!rep) {
+            throw new Error(`"${u}" isn't a recognized file locator. Use ipfs://… (pinned/IPFS), ar://… (Arweave), or https://… . ` +
+                'To store literal text or raw bytes on-chain instead, use `abx set-field`.');
+        }
+        pairs.push({ key: k, uri: u, representation: rep, mimeType: contentTypeFromPath(u) });
+    }
+    // A key repeated within one batch would have the later write silently win — the same
+    // full-column-upsert hazard that bit `register` and `lock-field`. Refuse instead.
+    const dupes = pairs.map((p) => p.key).filter((k, i, a) => a.indexOf(k) !== i);
+    if (dupes.length) {
+        throw new Error(`the same key appears twice in one batch: ${[...new Set(dupes)].join(', ')}. ` +
+            'Each field holds ONE active value, so the last write would silently win — attach them separately if that is really what you want.');
     }
+    const representation = pairs[0].representation;
     const owner = await read(contract, 'owner');
-    const mimeType = contentTypeFromPath(uri);
-    if (mimeType === 'application/octet-stream') {
-        console.log(yellow('  ⚠ ') +
-            dim(`no file extension in "${uri.slice(0, 64)}" → declared type will be application/octet-stream. `) +
-            dim('Point the URI at the file itself (…/master.tiff, …/coa.pdf) so collectors get the right type.'));
+    for (const p of pairs) {
+        if (p.mimeType === 'application/octet-stream') {
+            console.log(yellow('  ⚠ ') +
+                dim(`no file extension in "${p.uri.slice(0, 64)}" → declared type will be application/octet-stream. `) +
+                dim('Point the URI at the file itself (…/master.tiff, …/coa.pdf) so collectors get the right type.'));
+        }
+    }
+    const mimeType = pairs[0].mimeType;
+    for (const p of pairs) {
+        console.log(`  attaching ${bold(p.key)} ${dim(`(${p.mimeType}, ${p.representation})`)} to ${scope}: ${dim(p.uri)}`);
     }
-    console.log(`  attaching ${bold(key)} ${dim(`(${mimeType}, ${representation})`)} to ${scope}: ${dim(uri)}`);
     // Where it surfaces. This used to be one dim line, and it read as a footnote rather than as a
     // dependency: an integrator attached five audio stems to a fully-on-chain token, paid to store
     // them, and found `tokenURI` listed none of them — "paid for, stored on-chain, and invisible".
@@ -1179,25 +1231,37 @@ export async function cmdAttach(rest, flags) {
     const uriBase = await read(contract, 'tokenURIBase').catch(() => '');
     const artifactsPath = `/t/${chainId()}/${contract}/${flags.token ?? '0'}`;
     if (uriBase && uriBase.trim() !== '') {
-        console.log(dim(`    → listed in this project's resolver artifacts (${artifactsPath} and /data/${key}); a bare on-chain tokenURI carries reserved fields plus abx_params only.`));
+        console.log(dim(`    → listed in this project's resolver artifacts (${artifactsPath} and /data/<key>); a bare on-chain tokenURI carries reserved fields plus abx_params only.`));
     }
     else {
         console.log(yellow('  ⚠ ') +
             `this project resolves ON-CHAIN (no resolver base baked in), and the on-chain document carries reserved fields plus the computed ${bold('abx_params')} block only — ` +
-            `so ${bold(key)} will NOT appear in ${bold('tokenURI')}. The bytes are stored and provable, but nothing surfaces them to a marketplace or wallet. ` +
+            `so ${pairs.map((p) => bold(p.key)).join(', ')} will NOT appear in ${bold('tokenURI')}. The bytes are stored and provable, but nothing surfaces them to a marketplace or wallet. ` +
             dim('(Configured params DO appear on-chain — attachments are the surface that needs a resolver.)'));
         console.log(dim(`    to make attached artifacts visible, point the project at a resolver (${bold('abx deploy-resolver')}, or a managed one via ${bold('abx add <addr> --remote <name>')}) — it serves the listing at ${artifactsPath}.`));
     }
-    const buildTx = () => collection
-        ? prepareSetContractField({ contract, field: key, representation, value: toHex(uri), chainId: chainId() })
-        : prepareSetTokenField({ contract, tokenId: BigInt(flags.token ?? '0'), field: key, representation, value: toHex(uri), chainId: chainId() });
-    const sent = await runWrite(contract, buildTx(), flags, owner);
+    // ONE transaction for the whole set. `batchOps` folds a same-target run into a `multicall` and
+    // passes a lone op through untouched, so a single attach is byte-identical to before.
+    const ops = pairs.map((p) => collection
+        ? prepareSetContractField({ contract, field: p.key, representation: p.representation, value: toHex(p.uri), chainId: chainId() })
+        : prepareSetTokenField({ contract, tokenId: BigInt(flags.token ?? '0'), field: p.key, representation: p.representation, value: toHex(p.uri), chainId: chainId() }));
+    const batched = batchOps(ops);
+    if (batched.length !== 1) {
+        // Defensive: every op here targets the same contract and carries no value, so batchOps must
+        // return exactly one tx. If that ever changes, fail loudly rather than send a partial set.
+        throw new Error(`attach expected to batch ${ops.length} op(s) into one transaction, got ${batched.length}`);
+    }
+    if (pairs.length > 1) {
+        console.log(dim(`  ${pairs.length} artifacts → ONE transaction (all-or-nothing: a revert lands none of them, so no half-written token).`));
+    }
+    const sent = await runWrite(contract, batched[0], flags, owner);
     if (sent) {
         const id = flags.token ?? '0';
-        console.log(`  ${green('✓')} attached — ${bold(key)} joins ${scope}'s ${bold('artifacts')} manifest (stored on-chain, anchored).\n` +
+        const names = pairs.map((p) => bold(p.key)).join(', ');
+        console.log(`  ${green('✓')} attached — ${names} join${pairs.length > 1 ? '' : 's'} ${scope}'s ${bold('artifacts')} manifest (stored on-chain, anchored).\n` +
             dim(`    verify (a resolver serves the complete listing): `) +
-            `curl <your-resolver>/t/${chainId()}/${contract}/${id}` +
-            dim(`  ${collection ? '' : `→ artifacts[].key "${key}"; /data/${key} fetches it`}\n`) +
+            `abx tokenuri ${contract}${id === '0' ? '' : ` --token ${id}`} --fetch` +
+            dim(`  ${collection ? '' : `→ artifacts[].key ${pairs.map((p) => `"${p.key}"`).join(', ')}; /data/<key> fetches each`}\n`) +
             dim(`    (The complete file listing is a resolver surface — the bare on-chain tokenURI enumerates reserved fields plus abx_params. Params never need a resolver; attachments do.)\n`));
     }
 }
@@ -1306,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) {
@@ -1338,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`. */
@@ -1379,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
@@ -1396,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.`));
@@ -1452,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),
@@ -1491,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;
@@ -1539,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 });
@@ -1611,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');