@artblocks/abx-cli 0.1.0-alpha.0

package/dist/ownerops.js

@@ -0,0 +1,1270 @@
+/**
+ * Owner operations — the writes that *operate* a project after it's born:
+ * sell/transfer, re-point its resolver, change royalties, update or freeze
+ * content, hand over admin. Each builds an unsigned tx with the SDK and runs it
+ * through the signing harness (hot / wallet / cold lane), then re-indexes so the
+ * 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, deployChunkStore, predictChunkStore, 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, prepareSetRoyalty, prepareSetTokenField, prepareSetTokenURIBase, prepareSetTokenURIOverride, prepareSetTokenURIRenderer, prepareTransfer, prepareTransferOwnership, resolveChain, DEFAULT_CHAIN_KEY, stageContent, storeSupportsWriteContent, encodeTag, METADATA_FIELD as F, METADATA_REPRESENTATION as R, } from '@artblocks/abx-sdk';
+import { SelfHostIndexer } from '@artblocks/abx-indexer';
+import { encodeScalarParam, encodeTag as encodeTagSdk, prepareConfigureTokenParam, prepareConfigureTokenParamData, prepareSetContractParam, prepareSetContractParamData, seriesCodeAbi, } from '@artblocks/abx-sdk';
+import { paramsKeysIsLiteral, paramsKeysNudge, readParamsKeys } from './onchain-uri.js';
+import { 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 { formatEther, getAddress, isAddress, parseEther, toHex, zeroAddress } from 'viem';
+import { chunkStoreAddress, fixedPriceMinterAddress } from './config.js';
+import { openWalletSession, signTx } from './signer.js';
+import { remoteAddProject } from './remote.js';
+import { unknownFlags } from './flags.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)
+// ── 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}`;
+const green = (s) => `${C.green}${s}${C.reset}`;
+const yellow = (s) => `${C.yellow}${s}${C.reset}`;
+const bold = (s) => `${C.bold}${s}${C.reset}`;
+// ── data plane: attach files, and the keys you can't set by hand ──────────────
+// A token anchors named, typed files ("artifacts"). The served JSON's `artifacts` list is the
+// COMPLETE set — but it's COMPUTED by the resolver/renderer from the token's fields + effect
+// outputs; it is never a field you set. These keys are that computed output, so setting them by
+// hand would only pollute the manifest with a bogus entry (a real round-1 agent trap). Refuse them
+// and point at the real verb. See specs/protocol/data-plane.md.
+const COMPUTED_FIELD_KEYS = new Set(['artifacts', 'abx_provenance']);
+export function assertSettableField(field) {
+    if (COMPUTED_FIELD_KEYS.has(field)) {
+        const what = field === 'artifacts'
+            ? "the COMPUTED manifest (the complete list of this token's files), assembled by the resolver/renderer from your fields"
+            : 'the COMPUTED provenance list, assembled by the resolver/renderer';
+        throw new Error(`"${field}" is not a field you set — it's ${what}. To attach a file so it appears in the manifest, ` +
+            `pick your OWN key:\n    abx attach <address> <yourkey> <ipfs://… | ar://… | https://…>`);
+    }
+}
+/** 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'];
+/** 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). */
+export function representationForLocator(uri) {
+    const u = uri.trim();
+    if (/^ipfs:\/\//i.test(u))
+        return R.ipfs;
+    if (/^ar:\/\//i.test(u))
+        return R.arweave;
+    if (/^https?:\/\//i.test(u))
+        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);
+    }
+    return address;
+}
+function requireFlag(flags, name, usage) {
+    const v = flags[name];
+    if (!v || v === 'true') {
+        console.error(`missing --${name}\nusage: ${usage}\n`);
+        process.exit(1);
+    }
+    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). */
+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'],
+    });
+    if (!result)
+        return false; // cold lane — nothing broadcast
+    await reindexIfKnown(address, flags);
+    return true;
+}
+/** Resolve a `--remote [url]` owner-op target: explicit URL, else ABX_PUBLIC_BASE_URL / ABX_RESOLVER_URL. */
+function remoteResolverTarget(flags) {
+    const v = flags.remote;
+    if (v === undefined)
+        return null;
+    const base = v !== 'true' && v !== '' ? String(v) : (process.env.ABX_PUBLIC_BASE_URL ?? process.env.ABX_RESOLVER_URL);
+    if (!base) {
+        throw new Error('`--remote` needs a resolver URL: pass `--remote https://host` or set ABX_PUBLIC_BASE_URL in .env');
+    }
+    return base.replace(/\/+$/, '');
+}
+async function reindexIfKnown(address, flags) {
+    const indexer = new SelfHostIndexer();
+    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`);
+    }
+    else {
+        console.log(dim(`  (not indexed by this node — run \`abx add ${address}\` then \`abx index\` to serve it)`));
+    }
+    // Hosted-resolver nudge. A hosted resolver serves from ITS OWN store, so the LOCAL reindex above
+    // never reaches it: after an owner-op — especially a PostParam change — it stays stale, and its
+    // effect runner never sees the new inputsHash, so the marketplace thumbnail never auto-updates.
+    // `--remote <url>` re-indexes the hosted resolver (incremental), which pings its effect runner
+    // (ABX_EFFECTS_URL) → the automatic re-render. This is what makes a hosted `configure-param` a
+    // one-command change (no separate `abx index --remote` + no stale thumbnail).
+    const remote = remoteResolverTarget(flags);
+    if (!remote)
+        return;
+    const token = process.env.ABX_RESOLVER_ADMIN_TOKEN;
+    if (!token) {
+        console.log(dim(`  (--remote: set ABX_RESOLVER_ADMIN_TOKEN in .env to nudge ${remote}; skipped — it will serve stale state until it re-indexes)`));
+        return;
+    }
+    try {
+        const r = await remoteAddProject(remote, token, { address }); // no fromBlock ⇒ incremental nudge
+        console.log(`  ${green('✓')} nudged hosted resolver ${dim(remote)}: ${r.project.eventCount} events (${r.mode}) — its effect runner picks up the change`);
+    }
+    catch (e) {
+        console.log(dim(`  (couldn't nudge ${remote}: ${e.message} — run \`abx index ${address} --remote ${remote}\` to refresh it)`));
+    }
+}
+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)
+    }
+}
+/** 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. */
+export async function assertContractExists(address) {
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    let code;
+    try {
+        code = await publicClient.getCode({ address });
+    }
+    catch {
+        return; // can't check (RPC issue) → let the caller's original error surface
+    }
+    if (!code || code === '0x') {
+        throw new Error(`no contract at ${address} on ${CHAIN} — nothing to operate on. Owner ops run AFTER deploy: ` +
+            `deploy it first (e.g. abx deploy / deploy-series / deploy-code), or check the address and that ` +
+            `ABX_CHAIN='${CHAIN}' is the right network (a wrong-chain address reads as empty).`);
+    }
+}
+// ── configure-param ──────────────────────────────────────────────────────────
+/**
+ * `abx configure-param <address> <tokenId> <key> <value>` — set a schema-governed
+ * PostParam through the typed path, any lane. Reads the key's on-chain schema first
+ * and canonically ENCODES the human input per its type (`#rrggbb`, decimals ×1e10,
+ * Select by label, …); `String`/`Bytes` schemas take the value as UTF-8 (or
+ * `--file <path>` for bytes) via the data path. The signer must satisfy the schema's
+ * auth (Artist = contract owner, TokenOwner — delegate.xyz honored — or the named
+ * address); the chain enforces it either way.
+ */
+/** Positional args only — drops `--flags` AND the single token each value-taking flag consumes
+ *  (mirrors parseFlags). `rest.filter(r => !r.startsWith('--'))` was NOT enough: a flag's VALUE
+ *  (e.g. the URL after `--remote`, or the path after `--file`) isn't `--`-prefixed, so it leaked
+ *  into the positional value (`configure-param … #ff0000 --remote http://h` → value "#ff0000 http://h"). */
+function positionalArgs(args) {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a.startsWith('--')) {
+            if (a.indexOf('=') === -1 && args[i + 1] && !args[i + 1].startsWith('--'))
+                i++; // this flag consumes the next token
+            continue;
+        }
+        out.push(a);
+    }
+    return out;
+}
+export async function cmdConfigureParam(address, rest, flags) {
+    const usage = 'abx configure-param <address> <tokenId|-> <key> <value> [--file <path>] [--remote [url]] [--sign|--unsigned]   (tokenId "-" = contract scope, schema-less keys only)';
+    const contract = requireAddress(address, usage);
+    const [tokenIdRaw, key, ...valueParts] = positionalArgs(rest);
+    const valueInput = valueParts.join(' ');
+    if (!tokenIdRaw || !key || (!valueInput && !flags.file)) {
+        console.error(`usage: ${usage}\n`);
+        process.exit(1);
+    }
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    const schema = (await publicClient.readContract({
+        address: contract,
+        abi: seriesCodeAbi,
+        functionName: 'paramSchema',
+        args: [encodeTagSdk(key)],
+    }));
+    const [exists, paramTypeIdx, , , , , , selectOptions] = schema;
+    // Contract scope (`-`): the raw owner setters (`setContractParam[Data]`) — the write path of
+    // well-known contract params like `params.keys` / `display.gateway`. Schema-less keys only: a
+    // schema'd key closes the raw path on-chain (`SchemaGoverned`) and is per-token by design.
+    if (tokenIdRaw === '-') {
+        if (exists) {
+            throw new Error(`"${key}" is schema-governed — it's a per-token PostParam (abx configure-param ${contract} <tokenId> ${key} …). ` +
+                'Contract-scope raw params are owner-set and schema-less.');
+        }
+        const owner = await read(contract, 'owner');
+        const cid = chainId();
+        if (flags.file && flags.file !== 'true') {
+            const data = toHexSdk(new Uint8Array(readFileSync(flags.file)));
+            await runWrite(contract, prepareSetContractParamData({ contract, key, data, chainId: cid }), flags, owner);
+            return;
+        }
+        // Same encoding rule as deploy-code's params.keys leg: printable ASCII ≤ 31 chars rides as a
+        // literal readable bytes32; anything longer takes the data path (one blob, hash evented).
+        if (paramsKeysIsLiteral(valueInput)) {
+            console.log(`  ${key} (contract scope) ← "${valueInput}"  ${dim('(literal bytes32; owner-only raw setter)')}`);
+            await runWrite(contract, prepareSetContractParam({ contract, key, value: encodeTagSdk(valueInput), display: valueInput, chainId: cid }), flags, owner);
+        }
+        else {
+            console.log(`  ${key} (contract scope) ← ${valueInput.length} chars  ${dim('(data-backed; owner-only raw setter)')}`);
+            await runWrite(contract, prepareSetContractParamData({ contract, key, data: toHexSdk(new TextEncoder().encode(valueInput)), chainId: cid }), flags, owner);
+        }
+        return;
+    }
+    const tokenId = BigInt(tokenIdRaw);
+    if (!exists) {
+        throw new Error(`no PostParam schema for "${key}" on ${contract}. Schemas are declared at DEPLOY: ` +
+            `abx deploy-code … --schema ${key}:<Type>:<Auth>  (e.g. ${key}:HexColor:TokenOwner). ` +
+            `Adding a param to an already-deployed contract isn't a CLI command yet.`);
+    }
+    const typeName = ['Bool', 'Select', 'Uint256Range', 'Int256Range', 'DecimalRange', 'HexColor', 'Timestamp', 'String', 'Bytes'][paramTypeIdx];
+    let sent;
+    if (typeName === 'String' || typeName === 'Bytes') {
+        const data = flags.file
+            ? toHexSdk(new Uint8Array(readFileSync(flags.file)))
+            : toHexSdk(new TextEncoder().encode(valueInput));
+        sent = await runWrite(contract, prepareConfigureTokenParamData({ contract, tokenId, key, data, chainId: chainId() }), flags);
+    }
+    else {
+        const { value, display } = encodeScalarParam(typeName, valueInput, [...selectOptions]);
+        console.log(`  ${key} (${typeName}) ← ${display}  ${dim('(canonical encode; the chain enforces schema + auth)')}`);
+        sent = await runWrite(contract, prepareConfigureTokenParam({ contract, tokenId, key, value, display, chainId: chainId() }), flags);
+    }
+    // params.keys drift nudge (best-effort, never fails the command): a project on the on-chain
+    // URI lane enumerates its param surface in the `params.keys` contract param — the canonical
+    // generator reads it to build on-chain tokenData. A configured key that isn't listed is
+    // silently OMITTED there (byte-parity with the resolver breaks), so say it, with the fix.
+    if (sent) {
+        try {
+            const csv = await readParamsKeys(publicClient, contract);
+            const fixed = paramsKeysNudge(csv, key);
+            if (fixed !== null) {
+                console.log(`  ${yellow('⚠')} params.keys doesn't list "${key}" — the on-chain generator's tokenData will omit it. Fix:\n` +
+                    `    ${bold(`abx configure-param ${contract} - params.keys ${fixed}`)}`);
+            }
+        }
+        catch {
+            /* nudge is advisory — an RPC hiccup or a non-Params contract must never fail the write */
+        }
+        // What happens to the IMAGE depends on how it's produced. If the `image` field is computed
+        // on-chain (a `renderer` representation — the in-chain SVG lane), it re-tints AUTOMATICALLY: the
+        // renderer reads the param live, so tokenURI's image is already updated, nothing to re-render.
+        // Otherwise the image is an off-chain rendered STILL that re-addresses to a new inputsHash → it's
+        // stale until re-rendered (a running resolver+runner or `--remote` auto-catches it; a no-resolver
+        // drop has no watcher → re-render by hand). This is the "I changed palette, why is it stale?" moment.
+        if (!flags.remote) {
+            let imageOnChain = false;
+            try {
+                const res = (await publicClient.readContract({ address: contract, abi: seriesCodeAbi, functionName: 'contractField', args: [encodeTag('image')] }));
+                imageOnChain = String(res[0]).toLowerCase() === String(encodeTag('renderer')).toLowerCase();
+            }
+            catch { /* advisory — never fail the write over a field read */ }
+            if (imageOnChain) {
+                console.log(`  ${dim('the on-chain image re-tints automatically from this param — nothing to re-render (the renderer reads it live; tokenURI is already updated).')}`);
+            }
+            else {
+                console.log(`  ${dim('live view updates now; the thumbnail still is stale until re-rendered (no resolver watcher = no auto-refresh):')} ${bold(`abx render ${contract} ${tokenIdRaw}`)}`);
+            }
+        }
+    }
+}
+// ── set-param-hooks ────────────────────────────────────────────────────────────
+const HOOK_ROLES = ['configure', 'augment', 'transfer'];
+const HOOK_NOTE = {
+    configure: 'write-time veto/validator (a configure tx reverts if it reverts)',
+    augment: 'read-time derivation folded into tokenData (live view reads chain per view)',
+    transfer: 'ownership-change lifecycle, best-effort (a revert never blocks the transfer)',
+};
+const eqAddr = (a, b) => a.toLowerCase() === b.toLowerCase();
+/** Parse a hook-address flag: a 0x address, or `none`/`zero`/`0`/`0x0` to clear that role. */
+export function parseHookAddress(role, v) {
+    const s = v.trim().toLowerCase();
+    if (v === 'true' || v === '')
+        throw new Error(`--${role} needs a value: a 0x address, or "none" to clear it`);
+    if (s === 'none' || s === 'zero' || s === '0' || s === '0x0' || s === zeroAddress)
+        return zeroAddress;
+    if (!isAddress(v))
+        throw new Error(`--${role} must be a 0x address or "none" (to clear it) — got '${v}'`);
+    return getAddress(v);
+}
+/**
+ * `abx set-param-hooks <address> [--configure 0x|none] [--augment 0x|none] [--transfer 0x|none] [--clear]`
+ * — wire (or clear) a SeriesCode project's three param-lifecycle hooks. The contract has NO per-hook
+ * setter (`setParamHooks` writes all three at once), so this READS the current trio (`paramHooks()`)
+ * and re-sends it with your changes applied: omit a role to KEEP it, pass an address to set it, or
+ * `none` to clear it (`--clear` clears all three). Owner-only, any lane, guards `--dry-run`. SeriesCode
+ * only — a 1/1 or plain Series has no configurable params to hook. Bare (no flags) prints the current
+ * hooks and does nothing.
+ */
+export async function cmdSetParamHooks(address, flags) {
+    const usage = 'abx set-param-hooks <address> [--configure 0x|none] [--augment 0x|none] [--transfer 0x|none] [--clear] [--sign|--unsigned] [--dry-run]';
+    const contract = requireAddress(address, usage);
+    const clearAll = flags.clear !== undefined;
+    const roleFlags = HOOK_ROLES.filter((r) => flags[r] !== undefined);
+    if (clearAll && roleFlags.length) {
+        // Refuse the contradictory combo rather than silently pick one (enforce, don't warn).
+        throw new Error(`--clear clears ALL three hooks; don't combine it with --${roleFlags.join('/--')}. Use either --clear, or per-role flags.`);
+    }
+    // Read the current trio FIRST — this doubles as the SeriesCode guard (paramHooks() exists only on
+    // the ConfigurableParams extension; a 1/1 / plain Series reverts "no data").
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    let current;
+    try {
+        current = (await publicClient.readContract({
+            address: contract,
+            abi: seriesCodeAbi,
+            functionName: 'paramHooks',
+        }));
+    }
+    catch (err) {
+        await assertContractExists(contract); // no contract at all → the actionable no-contract error
+        throw new Error(`${contract} exposes no param hooks — the configure/augment/transfer hooks are a SeriesCode ` +
+            `(PostParams) feature. A 1/1 or a plain Series has no configurable params to hook.`);
+    }
+    const cur = { configure: current[0], augment: current[1], transfer: current[2] };
+    const label = (a) => (eqAddr(a, zeroAddress) ? dim('none') : a);
+    // Bare invocation: show the current hooks, mutate nothing.
+    if (!clearAll && roleFlags.length === 0) {
+        console.log(`  param hooks on ${contract}:`);
+        for (const r of HOOK_ROLES)
+            console.log(`    ${r.padEnd(10)} ${label(cur[r])}  ${dim(`(${HOOK_NOTE[r]})`)}`);
+        console.log(dim(`\n  set one with e.g. \`${usage}\``));
+        return;
+    }
+    // Read-modify-write: preserve each omitted role; a huge win is that changing ONE hook can't
+    // silently zero the other two (the contract's all-at-once setter would, if fed blindly).
+    const next = {
+        configure: clearAll ? zeroAddress : flags.configure !== undefined ? parseHookAddress('configure', flags.configure) : cur.configure,
+        augment: clearAll ? zeroAddress : flags.augment !== undefined ? parseHookAddress('augment', flags.augment) : cur.augment,
+        transfer: clearAll ? zeroAddress : flags.transfer !== undefined ? parseHookAddress('transfer', flags.transfer) : cur.transfer,
+    };
+    if (HOOK_ROLES.every((r) => eqAddr(next[r], cur[r]))) {
+        console.log(dim('  no change — the hooks already match. Nothing sent.'));
+        return;
+    }
+    console.log(`  param hooks on ${contract}:`);
+    for (const r of HOOK_ROLES) {
+        const changed = !eqAddr(cur[r], next[r]);
+        console.log(`    ${r.padEnd(10)} ${changed ? `${label(cur[r])} → ${label(next[r])}` : `${label(cur[r])} ${dim('(unchanged)')}`}`);
+    }
+    const owner = await read(contract, 'owner');
+    await runWrite(contract, prepareSetParamHooks({ contract, configureHook: next.configure, augmentHook: next.augment, transferHook: next.transfer, chainId: chainId() }), flags, owner);
+}
+// ── dependencies (code projects) ──────────────────────────────────────────────
+// The ordered library declarations of a template-mode code project (Dependencies
+// extension) — index 0 = the runtime, by convention; the list stays dense. Owner-only;
+// each runs through the same signing lanes + re-index as every other owner op.
+/**
+ * `abx set-dependency <address> <index> <ref>` — declare/replace the dependency at an
+ * index. The ref auto-detects: `name@version` (e.g. `p5@1.0.0` — resolves through the
+ * collection's soft registry pointer) or `0x…` (an on-chain data contract, read directly).
+ * The chain enforces density (index ≤ dependencyCount) and the lock.
+ */
+export async function cmdSetDependency(address, rest, flags) {
+    const usage = 'abx set-dependency <address> <index> <ref>   (ref: name@version | 0x<data-contract>) [--sign|--unsigned]';
+    const contract = requireAddress(address, usage);
+    const [indexRaw, refRaw] = positionalArgs(rest);
+    if (indexRaw === undefined || !refRaw) {
+        console.error(`usage: ${usage}\n`);
+        process.exit(1);
+    }
+    if (!/^\d+$/.test(indexRaw))
+        throw new Error(`<index> must be a non-negative integer (got '${indexRaw}') — the list is dense: index ≤ dependencyCount`);
+    const dep = parseDependencyRef(refRaw);
+    console.log(dim(`  dependency [${indexRaw}] ← ${dep.display} (${dep.resolution === DEP_RESOLUTION.registry ? 'registry name@version — resolves through the registry pointer' : 'on-chain data contract — read directly'})${indexRaw === '0' ? ' · index 0 = the runtime, by convention' : ''}`));
+    const owner = await read(contract, 'owner');
+    await runWrite(contract, prepareSetDependency({ contract, index: BigInt(indexRaw), resolution: dep.resolution, ref: dep.ref, display: dep.display, chainId: chainId() }), flags, owner);
+}
+/** `abx remove-last-dependency <address>` — pop the LAST dependency (the list stays dense;
+ *  to replace one in place, `set-dependency` at its index instead). */
+export async function cmdRemoveLastDependency(address, flags) {
+    const contract = requireAddress(address, 'abx remove-last-dependency <address> [--sign|--unsigned]');
+    const owner = await read(contract, 'owner');
+    await runWrite(contract, prepareRemoveLastDependency({ contract, chainId: chainId() }), flags, owner);
+}
+/** `abx set-dependency-registry <address> <registry>` — point (or clear, with `none`) the
+ *  soft, non-validating registry pointer the project's `name@version` refs resolve through. */
+export async function cmdSetDependencyRegistry(address, rest, flags) {
+    const usage = 'abx set-dependency-registry <address> <0x…|none> [--sign|--unsigned]';
+    const contract = requireAddress(address, usage);
+    const [raw] = positionalArgs(rest);
+    if (!raw) {
+        console.error(`usage: ${usage}\n`);
+        process.exit(1);
+    }
+    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}'`);
+    }
+    const registry = (raw === 'none' ? zeroAddress : raw);
+    console.log(dim('  the pointer is SOFT and non-validating — it disambiguates resolution; the declared refs stay either way.'));
+    const owner = await read(contract, 'owner');
+    await runWrite(contract, prepareSetDependencyRegistry({ contract, registry, chainId: chainId() }), flags, owner);
+}
+/** `abx lock-dependencies <address>` — freeze the dependency set (list + registry pointer) forever. */
+export async function cmdLockDependencies(address, flags) {
+    const contract = requireAddress(address, 'abx lock-dependencies <address> [--sign|--unsigned]');
+    const owner = await read(contract, 'owner');
+    console.log(dim('  note: locking the dependency set is permanent and irreversible (list AND registry pointer freeze).'));
+    await runWrite(contract, prepareLockDependencies({ contract, chainId: chainId() }), flags, owner);
+}
+// ── mint ─────────────────────────────────────────────────────────────────────
+// Issue a token — a deferred mint (deploy → warm resolver → mint) or a primary sale
+// (mint straight to the buyer). For a 1/1 this is the one-shot token #0. For a Series
+// 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 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.`));
+}
+// ── 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.
+/** Set (or clear, with `--minter none`) the single authorized minter — a drop/auction/router
+ *  contract. Setting a new one atomically replaces any previous minter. */
+export async function cmdSetMinter(address, flags) {
+    const usage = 'abx set-minter <address> --minter 0x…|none [--sign|--unsigned]';
+    const contract = requireAddress(address, usage);
+    const raw = requireFlag(flags, 'minter', usage);
+    const minter = (raw === 'none' ? zeroAddress : raw);
+    const owner = await read(contract, 'owner');
+    await runWrite(contract, prepareSetMinter({ contract, minter, chainId: chainId() }), flags, owner);
+}
+/** Lower the supply cap (monotonic — e.g. close an open edition early at `--max <totalSupply>`). */
+export async function cmdSetMaxInvocations(address, flags) {
+    const usage = 'abx set-max-invocations <address> --max <N> [--sign|--unsigned]';
+    const contract = requireAddress(address, usage);
+    const max = BigInt(requireFlag(flags, 'max', usage));
+    const owner = await read(contract, 'owner');
+    await runWrite(contract, prepareSetMaxInvocations({ contract, maxInvocations: max, chainId: chainId() }), flags, owner);
+}
+/** Pause minting — restrict it to the owner (config/reserves) until unpaused. */
+export async function cmdPause(address, flags) {
+    const contract = requireAddress(address, 'abx pause <address> [--sign|--unsigned]');
+    const owner = await read(contract, 'owner');
+    await runWrite(contract, prepareSetPaused({ contract, paused: true, chainId: chainId() }), flags, owner);
+}
+/** Unpause minting — open it to the authorized minter (go live). */
+export async function cmdUnpause(address, flags) {
+    const contract = requireAddress(address, 'abx unpause <address> [--sign|--unsigned]');
+    const owner = await read(contract, 'owner');
+    await runWrite(contract, prepareSetPaused({ contract, paused: false, chainId: chainId() }), flags, owner);
+}
+// ── authorship + rights deploy fields (parity with --description / --external-url) ───────────
+/** The optional authorship + rights deploy flags, each paired with the reserved collection-field
+ *  key it writes. Set at deploy → baked as on-chain **inline collection** fields (same slot the
+ *  `--description` / `--external-url` identity writes use); unset → nothing written. Collection
+ *  scope, so one value covers the whole project — they project into `contractURI` on the resolver
+ *  AND the on-chain renderer. Works for every token type (1/1 · Series · code). */
+export const AUTHORSHIP_DEPLOY_FIELDS = [
+    ['artist', F.artist],
+    ['display-notes', F.displayNotes],
+    ['artist-links', F.artistLinks],
+    ['license', F.license],
+];
+/** Build the on-chain (inline) collection fields for whichever authorship/rights deploy flags are
+ *  set — pure, so a deploy path just spreads the result into its `contractFields`. */
+export function authorshipContractFields(flags) {
+    return AUTHORSHIP_DEPLOY_FIELDS.flatMap(([flag, field]) => flags[flag] ? [{ field: encodeTag(field), representation: encodeTag(R.inline), value: toHex(String(flags[flag])) }] : []);
+}
+/** Set (or clear, with `--payee none`) the primary-sale payout destination. */
+export async function cmdSetPrimaryPayee(address, flags) {
+    const usage = 'abx set-primary-payee <address> --payee 0x…|none [--sign|--unsigned]';
+    const contract = requireAddress(address, usage);
+    const raw = requireFlag(flags, 'payee', usage);
+    const payee = (raw === 'none' ? zeroAddress : raw);
+    const owner = await read(contract, 'owner');
+    await runWrite(contract, prepareSetPrimaryPayee({ contract, payee, chainId: chainId() }), flags, owner);
+}
+// ── refresh ──────────────────────────────────────────────────────────────────
+// Ask marketplaces to (re)index a token's metadata. The instant a mint lands,
+// marketplaces fetch the on-chain tokenURI; if the resolver wasn't warm they cache
+// a miss until refreshed. We emit ERC-4906 on URI changes (4906-aware marketplaces
+// auto-refresh) — this is the manual fallback for the rest, and after the genesis mint.
+const OPENSEA_CHAIN = { sepolia: 'sepolia', mainnet: 'ethereum' };
+const TESTNET_CHAINS = new Set(['sepolia']);
+export async function cmdRefresh(address, flags) {
+    const contract = requireAddress(address, 'abx refresh <address> [--token 0]');
+    const tokenId = flags.token ?? '0';
+    const osChain = OPENSEA_CHAIN[CHAIN] ?? CHAIN;
+    const explorer = resolveChain(CHAIN).blockExplorers?.default?.url ?? '';
+    const apiKey = process.env.OPENSEA_API_KEY;
+    if (apiKey) {
+        const url = `https://api.opensea.io/api/v2/chain/${osChain}/contract/${contract}/nfts/${tokenId}/refresh`;
+        try {
+            const res = await fetch(url, { method: 'POST', headers: { 'x-api-key': apiKey, accept: 'application/json' } });
+            if (res.ok)
+                console.log(`  ${green('✓')} asked OpenSea to refresh ${contract} #${tokenId}`);
+            else
+                console.log(dim(`  OpenSea API ${res.status} ${res.statusText} — use the page link below and click “Refresh metadata”.`));
+        }
+        catch (err) {
+            console.log(dim(`  OpenSea API unreachable (${err.message}) — use the links below.`));
+        }
+    }
+    else {
+        console.log(dim('  no OPENSEA_API_KEY set — open these and click “Refresh metadata”:'));
+    }
+    const osBase = TESTNET_CHAINS.has(CHAIN) ? 'https://testnets.opensea.io' : 'https://opensea.io';
+    console.log(`    ${dim('OpenSea  ')}${osBase}/assets/${osChain}/${contract}/${tokenId}`);
+    if (explorer)
+        console.log(`    ${dim('Etherscan')} ${explorer}/token/${contract}?a=${tokenId}`);
+    console.log(dim('  (ERC-4906 already pings 4906-aware marketplaces on URI changes; this covers the genesis mint + the rest.)'));
+}
+// ── transfer ─────────────────────────────────────────────────────────────────
+export async function cmdTransfer(address, flags) {
+    const contract = requireAddress(address, 'abx transfer <address> --to 0x… [--token 0] [--sign|--unsigned]');
+    const to = requireFlag(flags, 'to', 'abx transfer <address> --to 0x…');
+    const tokenId = BigInt(flags.token ?? '0');
+    const from = await read(contract, 'ownerOf', [tokenId]);
+    const tx = prepareTransfer({ contract, from, to, tokenId, chainId: chainId() });
+    await runWrite(contract, tx, flags, from);
+}
+// ── set-token-uri ──────────────────────────────────────────────────────────--
+// `--uri <base>` re-points the resolver BASE (the contract derives {base}/{chainId}/{address}/{tokenId}).
+// `--override <uri> [--token <id>]` pins ONE token to a fixed locator (e.g. ipfs://) — the rare,
+// deliberate escape out of the spec; pass an empty string to clear it.
+export async function cmdSetTokenUri(address, flags) {
+    const usage = 'abx set-token-uri <address> (--uri <base> | --override <uri> [--token <id>]) [--sign|--unsigned]';
+    const contract = requireAddress(address, usage);
+    const owner = await read(contract, 'owner');
+    if (flags.override !== undefined) {
+        const tokenId = flags.token ? Number(flags.token) : 0;
+        await runWrite(contract, prepareSetTokenURIOverride({ contract, tokenId, uri: flags.override, chainId: chainId() }), flags, owner);
+        return;
+    }
+    const base = requireFlag(flags, 'uri', usage);
+    await runWrite(contract, prepareSetTokenURIBase({ contract, base, chainId: chainId() }), flags, owner);
+}
+// ── set-contract-uri ─────────────────────────────────────────────────────────
+// `--uri <base>` re-points the collection base; `--override <uri>` pins a fixed locator.
+export async function cmdSetContractUri(address, flags) {
+    const usage = 'abx set-contract-uri <address> (--uri <base> | --override <uri>) [--sign|--unsigned]';
+    const contract = requireAddress(address, usage);
+    const owner = await read(contract, 'owner');
+    if (flags.override !== undefined) {
+        await runWrite(contract, prepareSetContractURIOverride({ contract, uri: flags.override, chainId: chainId() }), flags, owner);
+        return;
+    }
+    const base = requireFlag(flags, 'uri', usage);
+    await runWrite(contract, prepareSetContractURIBase({ contract, base, chainId: chainId() }), flags, owner);
+}
+// ── set-royalty ──────────────────────────────────────────────────────────────
+/** Parse + bound-check a royalty `--bps` (basis points, 0–10000 = 0–100%). Throws a plain-language
+ *  error on a non-integer or out-of-range value instead of letting it hit the chain (or a cryptic
+ *  ABI read). Exported for the regression test. */
+export function parseRoyaltyBps(raw) {
+    const bps = Number(raw);
+    if (!Number.isInteger(bps) || bps < 0 || bps > 10000) {
+        throw new Error(`--bps must be a whole number 0–10000 (100 = 1%, 750 = 7.5%, 10000 = 100%); got '${raw}'.`);
+    }
+    return bps;
+}
+export async function cmdSetRoyalty(address, flags) {
+    const contract = requireAddress(address, 'abx set-royalty <address> --bps <0-10000> [--receiver 0x…] [--sign|--unsigned]');
+    const bps = parseRoyaltyBps(requireFlag(flags, 'bps', 'abx set-royalty <address> --bps <0-10000>'));
+    const owner = await read(contract, 'owner');
+    // Default the receiver to the CURRENT on-chain receiver so `--bps` alone just changes the rate.
+    // Read it via the ERC-2981 `royaltyInfo` view (there is NO bare `royaltyReceiver()` getter —
+    // reading one threw "not found on ABI", which broke `set-royalty --bps` without `--receiver`).
+    // Fall back to the owner if it can't be read or is unset (a zero receiver would revert on set).
+    let receiver = flags.receiver && flags.receiver !== 'true' ? flags.receiver : undefined;
+    if (!receiver) {
+        receiver = await read(contract, 'royaltyInfo', [0n, 10000n])
+            .then((r) => r[0])
+            .catch(() => owner);
+        if (!receiver || receiver === zeroAddress)
+            receiver = owner;
+    }
+    await runWrite(contract, prepareSetRoyalty({ contract, receiver, bps, chainId: chainId() }), flags, owner);
+}
+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 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.
+ */
+async function ensureChunkStore(send, override) {
+    // Resolve from the shipped manifest (flag → ABX_CHUNK_STORE → manifest); on a chain with no
+    // entry (or a stale deployment), deploy a current one and tell the operator how to reuse it.
+    const known = chunkStoreAddress(override);
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    if (known) {
+        const code = await publicClient.getCode({ address: known });
+        if (code && code !== '0x') {
+            // Has code, but is it the *current* store? A pre-`writeContent` deployment passes a
+            // bare code check yet reverts the staging call — verify the ABI, don't just assume.
+            if (await storeSupportsWriteContent(publicClient, known))
+                return known;
+            console.log(yellow(`  configured chunk store ${known} is a stale deployment (no writeContent) — deploying a current one`));
+        }
+    }
+    // No usable listed store. The canonical store is CREATE2-deterministic, so it may already exist at
+    // its predicted address — deployed by the forge script (or a prior lazy deploy) with the manifest
+    // not yet updated. Check there before deploying: self-healing, and never a duplicate at a random
+    // CREATE address. `deployChunkStore` (below) also lands at exactly this address.
+    const predicted = predictChunkStore();
+    if (!known || known.toLowerCase() !== predicted.toLowerCase()) {
+        const pcode = await publicClient.getCode({ address: predicted });
+        if (pcode && pcode !== '0x' && (await storeSupportsWriteContent(publicClient, predicted))) {
+            console.log(dim(`  using the canonical chunk store at its deterministic address ${predicted}`));
+            return predicted;
+        }
+    }
+    console.log(dim('  deploying the canonical multi-chunk content store (AbxChunkStore) — CREATE2…'));
+    const { chunkStore } = await deployChunkStore(send);
+    console.log(`  ${green('✓')} chunk store ${chunkStore}`);
+    console.log(dim(`  not in the shipped manifest for ${CHAIN} — to reuse it set ABX_CHUNK_STORE=${chunkStore} (or add it to packages/sdk/src/deployments.ts)`));
+    return chunkStore;
+}
+/**
+ * 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.
+ */
+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 });
+    };
+}
+/** 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. */
+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;
+}
+/**
+ * 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)
+        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;
+}
+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 };
+}
+/** Human-readable size line for a content plan, e.g. `2812B → 1 chunk [fastlz 2812→904B]`. */
+function planSizeLine(bytes, p, compress) {
+    const savings = compress === 'fastlz'
+        ? `fastlz ${bytes}→${p.stagedBytes}B`
+        : compress === 'gzip'
+            ? `gzip ${bytes}→${p.stagedBytes}B (off-chain decode)`
+            : 'no compression';
+    return `${bytes}B → ${p.chunks} chunk(s) [${savings}]`;
+}
+/**
+ * The transaction-count line for a content plan, given what the FINAL (owner) tx is —
+ * a separate `set-field` after staging, or the `deploy` that bakes the reader field in.
+ * Staging itself is 1 atomic `writeContent` (content fits one tx's gas) or N gas-bounded
+ * chunk-batch txs + 1 manifest tx.
+ */
+function planTxLine(p, finalLabel) {
+    return p.plan.mode === 'single'
+        ? `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`;
+}
+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 };
+}
+/**
+ * Dry-run preview of staging an image fully on-chain — the REAL chunk + transaction plan,
+ * computed without writing anything (so `abx deploy --dry-run --onchain-image` reports the
+ * true count instead of leaving the agent to guess). The final tx here is the deploy that
+ * bakes in the reader field, so the count is staging tx(s) + the deploy.
+ */
+export function previewImageStaging(imagePath, compress) {
+    const bytes = readFileSync(resolvePath(imagePath));
+    const p = computeContentPlan(bytes, compress);
+    warnIfLargeForOnChain(bytes.length, basename(resolvePath(imagePath)));
+    return (`would stage ${basename(resolvePath(imagePath))} on-chain (chunk store): ` +
+        `${planSizeLine(bytes.length, p, compress)} as ${p.representation}; ` +
+        `${planTxLine(p, '1 deploy (bakes the reader field + mints)')}`);
+}
+/**
+ * Stage an image file fully on-chain (chunk store) and return the `reader`-backed
+ * `image` field to bake into a deploy's `InitParams.tokenFields`. The staging writes
+ * are ownerless (env key) and happen before the deploy, so "deploy a 50 kB on-chain
+ * image" is just those staging tx(s) + the single deploy — no post-deploy `set-field`.
+ * The manifest is deployer-independent, so this is computed once and reused for any signer.
+ */
+export async function stageImageField(imagePath, compress, send) {
+    const bytes = readFileSync(resolvePath(imagePath));
+    const { value, representation } = await putContentOnChain(bytes, compress, 'image', send, '1 deploy (bakes the reader field + mints)');
+    return {
+        field: { field: encodeTag(F.image), representation: encodeTag(representation), value },
+        note: `image: ${bytes.length}B staged ON-CHAIN via reader (${representation}) — baked into the deploy`,
+    };
+}
+/**
+ * Stage MANY images on-chain against a **single, shared** chunk store — the batch form of
+ * {@link stageImageField} for a Series. The store is resolved/deployed **once** (not per token),
+ * then every file is staged against it and returned as its own `reader`-backed `image` field.
+ * Each field still points at its own manifest, so each token's artwork is independent; they just
+ * share the store contract. Returns the fields in input order (token order).
+ */
+export async function stageImageFieldsBatch(imagePaths, compress, send, storeOverride) {
+    const store = await ensureChunkStore(send, storeOverride);
+    const fields = [];
+    for (const imagePath of imagePaths) {
+        const bytes = readFileSync(resolvePath(imagePath));
+        const { value, representation } = await putContentOnChain(bytes, compress, 'image', send, '1 deploy (bakes the reader fields + mints)', store);
+        fields.push({ field: encodeTag(F.image), representation: encodeTag(representation), value });
+    }
+    return { fields, store };
+}
+// ── set-field ──────────────────────────────────────────────────────────────--
+// Set an on-chain metadata field. `--field` is what (e.g. image, description),
+// `--representation` is how it's carried (default `inline` for --text, `keccak256`
+// for --value). `--text "…"` stores literal UTF-8; `--value 0x..` stores raw bytes.
+// `--collection` targets the collection scope; otherwise token `--token` (default 0).
+// The resolver prefers on-chain over off-chain. Owner-only.
+export async function cmdSetField(address, flags) {
+    const contract = requireAddress(address, 'abx set-field <address> --field <name> (--text "…" | --value 0x…) [--representation <rep>] [--collection | --token 0]');
+    const field = requireFlag(flags, 'field', 'abx set-field <address> --field <name> (--text … | --value 0x… | --file <path>)');
+    assertSettableField(field); // `artifacts`/`abx_provenance` are computed, not settable → point at `abx attach`
+    await assertChainId(CHAIN); // verify network up front — this op may stage on-chain content before the field tx
+    const collection = !!flags.collection;
+    const lane = laneFromFlags(flags);
+    const owner = await read(contract, 'owner');
+    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']) {
+        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)')}`);
+        console.log(`    ${dim('scope'.padEnd(12))} ${collection ? 'collection' : `token #${flags.token ?? '0'}`}`);
+        console.log(`    ${planSizeLine(bytes.length, p, parseCompress(flags.compress))}`);
+        console.log(dim(`\n  Re-run without --dry-run to stage on-chain (lane: ${lane}).\n`));
+        return;
+    }
+    const buildTx = (value, representation) => collection
+        ? prepareSetContractField({ contract, field, representation, value, chainId: chainId() })
+        : prepareSetTokenField({ contract, tokenId: BigInt(flags.token ?? '0'), field, representation, value, chainId: chainId() });
+    // On-chain staging (--file) is a SEQUENCE — chunk write(s) → manifest → the field-set that
+    // references it — where each tx's receipt feeds the next, so it can't be signed offline.
+    if (staging && lane === 'unsigned') {
+        throw new Error('Staging on-chain content (--file) needs interactive signing — each chunk tx feeds the next, ' +
+            "so it can't run on the cold lane (--unsigned). Use the hot lane (a funded key) or --sign (browser wallet).");
+    }
+    // Wallet lane + on-chain staging: ONE sign session signs every chunk write AND the field-set,
+    // so the human connects once and approves each step (the env key is never needed).
+    if (staging && lane === 'sign') {
+        const compress = parseCompress(flags.compress);
+        const bytes = readFileSync(resolvePath(flags.file));
+        const p = computeContentPlan(bytes, compress);
+        const stagingTxs = p.plan.mode === 'single' ? 1 : p.plan.txCount;
+        const session = await openWalletSession({
+            chainKey: CHAIN,
+            expectedSigner: owner,
+            total: stagingTxs + 1,
+            port: flags.port ? Number(flags.port) : undefined,
+            signUrlFile: flags['sign-url-file'],
+        });
+        try {
+            await session.connect();
+            const { value, representation } = await putContentOnChain(bytes, compress, field, sessionStagingSender(session));
+            await session.send(buildTx(value, representation));
+        }
+        finally {
+            session.close();
+        }
+        await reindexIfKnown(contract, flags);
+        return;
+    }
+    // Hot lane (or no staging): compute the value, then sign the single field-set tx as usual.
+    let value;
+    let representation;
+    if (staging) {
+        const compress = parseCompress(flags.compress);
+        ({ value, representation } = await putContentOnChain(readFileSync(resolvePath(flags.file)), compress, field, envStagingSender()));
+    }
+    else if (flags.text && flags.text !== 'true') {
+        value = toHex(flags.text);
+        representation = flags.representation ?? R.inline;
+        console.log(dim(`  inline on-chain '${field}'${collection ? ' (collection)' : ` on token #${flags.token ?? '0'}`}: ${JSON.stringify(flags.text.slice(0, 60))}${flags.text.length > 60 ? '…' : ''}`));
+    }
+    else {
+        value = requireFlag(flags, 'value', 'abx set-field <address> --field <name> --text … | --value 0x…');
+        representation = flags.representation ?? R.keccak256;
+    }
+    await runWrite(contract, buildTx(value, representation), flags, owner);
+}
+// ── attach (the data-plane verb: put a named file on a token) ─────────────────
+/**
+ * `abx attach <address> <key> <uri>` — attach a named, typed file to a token (or the collection),
+ * so it appears in the token's served `artifacts` manifest as `{key, mimeType, uri}`. This is the
+ * creator-facing verb for the token data plane (specs/protocol/data-plane.md); it's a thin,
+ * correct-by-construction wrapper over `set-field`:
+ *   - the on-chain representation is AUTO-DETECTED from the URI scheme (ipfs:// · ar:// · https://)
+ *     — no `--representation` to guess wrong;
+ *   - `--file <path>` instead of a URI stores tiny bytes ON-CHAIN (SSTORE2), for a small file with
+ *     no external host (≈200 gas/byte — locators are the norm for anything non-trivial);
+ *   - the declared `mimeType` comes from the file EXTENSION in the URI (`…/master.tiff` → image/tiff),
+ *     so give the file a real extension or it lands as `application/octet-stream`;
+ *   - 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.
+ */
+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);
+    // 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.
+    for (const f of unknownFlags(flags, ATTACH_FLAGS)) {
+        const hint = f.includes('mime')
+            ? ' mimeType is declared from the file EXTENSION in the URI, not a flag.'
+            : f === 'for'
+                ? ' --for is a deploy flag (it pins the future owner); an owner-op signs as the on-chain owner automatically — just connect that wallet.'
+                : '';
+        console.log(yellow('  ⚠ ') + dim(`unrecognized flag --${f} (ignored).${hint}`));
+    }
+    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);
+    }
+    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);
+    }
+    if (uri && hasFile)
+        throw new Error('pass EITHER a locator URI OR --file <path>, not both.');
+    const collection = !!flags.collection;
+    const scope = collection ? 'the collection' : `token #${flags.token ?? '0'}`;
+    // --file: reuse set-field's on-chain staging path (tiny files only). Delegate rather than
+    // re-implement the chunk sequence.
+    if (hasFile) {
+        return cmdSetField(address, { ...flags, field: key });
+    }
+    // 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`.');
+    }
+    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.'));
+    }
+    console.log(`  attaching ${bold(key)} ${dim(`(${mimeType}, ${representation})`)} to ${scope}: ${dim(uri)}`);
+    // Where it surfaces — say it on the preview path too (not just post-send), so a creator/agent
+    // doesn't expect an attached custom key in a bare `abx tokenuri` (round-2 finding: they did).
+    console.log(dim(`    → appears in a resolver's artifacts listing (/t/${chainId()}/${contract}/${flags.token ?? '0'} and /data/${key}); a bare on-chain tokenURI shows reserved fields only.`));
+    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);
+    if (sent) {
+        const id = flags.token ?? '0';
+        console.log(`  ${green('✓')} attached — ${bold(key)} joins ${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`) +
+            dim(`    (The complete file listing is a resolver surface — the bare on-chain tokenURI enumerates reserved fields only.)\n`));
+    }
+}
+// ── lock-field ───────────────────────────────────────────────────────────────
+export async function cmdLockField(address, flags) {
+    const contract = requireAddress(address, 'abx lock-field <address> --field <name> [--collection | --token 0] [--sign|--unsigned]');
+    const field = requireFlag(flags, 'field', 'abx lock-field <address> --field <name>');
+    const collection = !!flags.collection;
+    const owner = await read(contract, 'owner');
+    console.log(dim(`  note: locking the '${field}' field is permanent and irreversible (freezes all its representations).`));
+    const tx = collection
+        ? prepareLockContractField({ contract, field, chainId: chainId() })
+        : prepareLockTokenField({ contract, tokenId: BigInt(flags.token ?? '0'), field, chainId: chainId() });
+    await runWrite(contract, tx, flags, owner);
+}
+// ── set-renderer (toggle on-chain URI resolution) ─────────────────────────────
+/** Point a token's URI resolution at an on-chain renderer (or clear it with `--off`).
+ *  `flags.renderer` is the resolved address (main.ts defaults it to the canonical
+ *  renderer). With it set, `tokenURI`/`contractURI` are assembled on-chain from the
+ *  fields — no resolver needed. Scope: token (default) or `--collection`. */
+export async function cmdSetRenderer(address, flags) {
+    const contract = requireAddress(address, 'abx set-renderer <address> [--collection] [--off | --renderer 0x..] [--sign|--unsigned]');
+    const collection = !!flags.collection;
+    const renderer = (flags.off ? zeroAddress : (flags.renderer ?? zeroAddress));
+    const owner = await read(contract, 'owner');
+    console.log(dim(renderer === zeroAddress
+        ? `  clearing the on-chain renderer → ${collection ? 'contractURI' : 'tokenURI'} resolves off-chain again.`
+        : `  ${collection ? 'contractURI' : 'tokenURI'} will resolve ON-CHAIN via ${renderer} (assembled from fields).`));
+    const tx = collection
+        ? prepareSetContractURIRenderer({ contract, renderer, chainId: chainId() })
+        : prepareSetTokenURIRenderer({ contract, renderer, chainId: chainId() });
+    await runWrite(contract, tx, flags, owner);
+}
+// ── lock-uri (freeze the URI config) ──────────────────────────────────────────
+/** Freeze a scope's URI config (pointer + renderer) forever. With the fields also
+ *  locked, the resolved metadata is provably immutable — the on-chain twin of a
+ *  frozen `tokenURI`. Scope: token (default) or `--collection`. */
+export async function cmdLockUri(address, flags) {
+    const contract = requireAddress(address, 'abx lock-uri <address> [--collection] [--sign|--unsigned]');
+    const collection = !!flags.collection;
+    const owner = await read(contract, 'owner');
+    console.log(dim(`  note: locking the ${collection ? 'contractURI' : 'tokenURI'} config is permanent — pointer + renderer can never change again.`));
+    const tx = collection
+        ? prepareLockContractURI({ contract, chainId: chainId() })
+        : prepareLockTokenURI({ contract, chainId: chainId() });
+    await runWrite(contract, tx, flags, owner);
+}
+// ── set-admin (transfer contract ownership) ──────────────────────────────────
+export async function cmdSetAdmin(address, flags) {
+    const contract = requireAddress(address, 'abx set-admin <address> --to 0x… [--sign|--unsigned]');
+    const newOwner = requireFlag(flags, 'to', 'abx set-admin <address> --to 0x…');
+    const owner = await read(contract, 'owner');
+    await runWrite(contract, prepareTransferOwnership({ contract, newOwner, chainId: chainId() }), flags, owner);
+}
+// ── fixed-price minter (the Minter spine) ─────────────────────────────────────
+// A shared, ownerless, multi-tenant sale singleton. `configure` defers to the token owner;
+// `buy` is public. Sale config is keyed by token address; proceeds route to the token's
+// primaryPayee; the token's Paused extension is the on/off switch. See specs/protocol/minter-spine.md.
+/** A Series read (minter/primaryPayee/paused/…) via the Series ABI (the 1/1 ABI lacks these). */
+async function readSeries(token, fn, args = []) {
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    return (await publicClient.readContract({
+        address: token,
+        abi: seriesImageAbi,
+        functionName: fn,
+        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) {
+    const known = fixedPriceMinterAddress(override);
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    if (known) {
+        const code = await publicClient.getCode({ address: known });
+        if (code && code !== '0x')
+            return known;
+        console.log(yellow(`  configured minter ${known} has no code on ${CHAIN} — deploying a fresh one`));
+    }
+    // CREATE2-deterministic: it may already exist at its predicted address (forge script deployed it,
+    // manifest not yet updated). Check there before deploying — self-healing, never a duplicate.
+    const predicted = predictFixedPriceMinter();
+    if (!known || known.toLowerCase() !== predicted.toLowerCase()) {
+        const pcode = await publicClient.getCode({ address: predicted });
+        if (pcode && pcode !== '0x') {
+            console.log(dim(`  using the canonical fixed-price minter at its deterministic address ${predicted}`));
+            return predicted;
+        }
+    }
+    const { wallet, account } = makeWalletClient({ chainKey: CHAIN });
+    console.log(dim('  deploying the canonical fixed-price minter (shared, ownerless) — CREATE2…'));
+    const { minter, txHash } = await deployFixedPriceMinter(wallet, account, 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. */
+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'],
+    });
+}
+/** 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`. */
+function parseSalePrice(flags, usage) {
+    if (flags['price-raw'] && flags['price-raw'] !== 'true')
+        return BigInt(flags['price-raw']);
+    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);
+}
+/**
+ * `abx minter configure <token> --price <eth> --allocation <n> [--erc20 0x…]` — set the fixed-price
+ * sale for a project on the shared minter. Defers to the token owner. Resolves (or deploys) the
+ * shared minter, then reports the two remaining grants the owner still needs (assign the minter on
+ * the token, set a primary payee) and whether the token is paused.
+ */
+export async function cmdMinterConfigure(address, flags) {
+    const usage = 'abx minter configure <token> (--price <eth> | --price-raw <units>) --allocation <n> [--erc20 0x…] [--minter-contract 0x…] [--sign|--unsigned]';
+    const token = requireAddress(address, usage);
+    const owner = await read(token, 'owner');
+    const erc20 = flags.erc20 && flags.erc20 !== 'true' ? flags.erc20 : zeroAddress;
+    const allocation = BigInt(requireFlag(flags, 'allocation', usage));
+    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 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.`));
+    }
+    const minter = dryRun ? (knownMinter ?? zeroAddress) : await ensureFixedPriceMinter(flags['minter-contract']);
+    const isEth = erc20 === zeroAddress;
+    // Sanity-check the allocation against what the contract can actually mint. A creator who sets
+    // --allocation 100 on a 16-supply Series would only ever sell the remainder (maxInvocations binds
+    // tighter than the minter's allocation) and discover it when mint #16 reverts. Warn loudly — but
+    // don't refuse: allocation is a cap, and holding reserves (allocating < remaining) is legitimate.
+    const [maxInv, supplyNow] = await Promise.all([
+        readSeries(token, 'maxInvocations').catch(() => 0n),
+        readSeries(token, 'totalSupply').catch(() => 0n),
+    ]);
+    const remaining = maxInv > supplyNow ? maxInv - supplyNow : 0n;
+    if (maxInv > 0n && allocation > remaining) {
+        console.log(yellow(`  ⚠ allocation ${allocation} exceeds the ${remaining} this contract can still mint `) +
+            dim(`(maxInvocations ${maxInv} − ${supplyNow} minted). The token's cap binds tighter, so only ${remaining} will actually sell.`));
+        console.log(dim(`    To sell ${allocation}, redeploy a Series with a higher --max; otherwise set --allocation ${remaining} (or less, to hold reserves).`));
+    }
+    console.log(dim(`  configuring sale on ${minter}`));
+    console.log(dim(`    token      ${token}`));
+    console.log(dim(`    price      ${isEth ? `${formatEther(price)} ETH` : `${price} units of ${erc20}`} / token`));
+    console.log(dim(`    allocation ${allocation}`));
+    await runMinterWrite(prepareConfigureSale({ minter, token, paymentToken: erc20, price, allocation, chainId: chainId() }), flags, owner);
+    // The two grants + the pause switch — surface what's still needed to actually sell.
+    const [assignedMinter, payee, paused] = await Promise.all([
+        readSeries(token, 'minter').catch(() => zeroAddress),
+        readSeries(token, 'primaryPayee').catch(() => zeroAddress),
+        readSeries(token, 'paused').catch(() => false),
+    ]);
+    const assigned = assignedMinter.toLowerCase() === minter.toLowerCase();
+    console.log('');
+    console.log(assigned ? dim('  ✓ minter is assigned on the token') : yellow(`  ⚠ assign this minter on the token:  abx set-minter ${token} --minter ${minter}`));
+    if (payee === zeroAddress)
+        console.log(yellow(`  ⚠ set a primary payee (sales revert without one):  abx set-primary-payee ${token} --payee 0x…`));
+    else
+        console.log(dim(`  ✓ proceeds → ${payee}`));
+    if (paused)
+        console.log(yellow(`  • token is paused — open the sale when ready:  abx unpause ${token}`));
+    console.log(dim(`  buyers then run:  abx minter buy ${token}`));
+}
+/** `abx minter show <token>` — the sale terms + the token's readiness (assigned? payee? paused?).
+ *  Read-only; the agent runs it to see exactly what's configured before/after a sale. */
+export async function cmdMinterShow(address, flags) {
+    const token = requireAddress(address, 'abx minter show <token> [--minter-contract 0x…]');
+    // Refuse a nonexistent contract like the sibling owner-ops (state/unpause/minter configure) do —
+    // otherwise the minter singleton returns zero-config for the unconfigured token and we print a
+    // plausible-but-fake `paused: no (open)` readout for an address that has no project at all.
+    await assertContractExists(token);
+    const minter = fixedPriceMinterAddress(flags['minter-contract']);
+    if (!minter) {
+        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 [assignedMinter, payee, paused, max, supply] = await Promise.all([
+        readSeries(token, 'minter').catch(() => zeroAddress),
+        readSeries(token, 'primaryPayee').catch(() => zeroAddress),
+        readSeries(token, 'paused').catch(() => false),
+        readSeries(token, 'maxInvocations').catch(() => 0n),
+        readSeries(token, 'totalSupply').catch(() => 0n),
+    ]);
+    const isEth = sale.paymentToken === zeroAddress;
+    const assigned = assignedMinter.toLowerCase() === minter.toLowerCase();
+    console.log(bold(`\n  minter sale — ${token}`));
+    console.log(`    shared minter:     ${minter}`);
+    if (!sale.configured) {
+        console.log(yellow(`    not configured     — abx minter configure ${token} --price <eth> --allocation <n>`));
+    }
+    else {
+        console.log(`    price:             ${isEth ? `${formatEther(sale.price)} ETH` : `${sale.price} units of ${sale.paymentToken}`}`);
+        console.log(`    allocation:        ${sale.sold}/${sale.allocation} sold`);
+    }
+    console.log(`    assigned on token: ${assigned ? green('yes') : yellow(`no — abx set-minter ${token} --minter ${minter}`)}`);
+    console.log(`    primary payee:     ${payee === zeroAddress ? yellow('none — abx set-primary-payee …') : payee}`);
+    console.log(`    paused:            ${paused ? yellow(`yes — abx unpause ${token}`) : green('no (open)')}`);
+    console.log(`    supply:            ${supply}/${max}`);
+    // Readiness must also flag an allocation that overshoots what the contract can still mint — the
+    // same check `minter configure` does, surfaced here (this is the command billed as "check state").
+    const remaining = max > supply ? max - supply : 0n;
+    if (sale.configured && max > 0n && sale.allocation > remaining) {
+        console.log(yellow(`    ⚠ allocation ${sale.allocation} exceeds the ${remaining} still mintable (cap ${max} − ${supply} minted) — only ${remaining} can actually sell.`));
+    }
+    console.log('');
+}
+/** `abx minter buy <token> [--to 0x…]` — buy one token through the shared minter (public; any
+ *  funded signer). ETH sales attach the price; ERC-20 sales need a prior approval to the minter. */
+export async function cmdMinterBuy(address, flags) {
+    const usage = 'abx minter buy <token> [--to 0x…] [--minter-contract 0x…] [--sign|--unsigned]';
+    const token = requireAddress(address, usage);
+    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);
+    if (!sale.configured)
+        throw new Error(`no sale configured for ${token} — run: abx minter configure ${token} …`);
+    const isEth = sale.paymentToken === zeroAddress;
+    const to = flags.to && flags.to !== 'true' ? flags.to : undefined;
+    const value = isEth ? sale.price : 0n;
+    if (!isEth) {
+        console.log(yellow(`  ERC-20 sale: the buyer must have approved ${minter} to spend ${sale.price} units of ${sale.paymentToken} first (else the tx reverts).`));
+    }
+    console.log(dim(`  buying 1 token${to ? ` → ${to}` : ' → signer'} for ${isEth ? `${formatEther(sale.price)} ETH` : `${sale.price} units`}`));
+    await runMinterWrite(preparePurchase({ minter, token, to, value, chainId: chainId() }), flags);
+    console.log(dim(`  next: \`abx refresh ${token}\` so marketplaces pick up the new token.`));
+}
+//# sourceMappingURL=ownerops.js.map