@artblocks/abx-cli 0.1.0-alpha.20 → 0.1.0-alpha.22

package/dist/ownerops.js

@@ -6,10 +6,10 @@
  * 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, predictFixedPriceMinter1155, makeHotSender, makePublicClient, makeWalletClient, oneOfOneImageAbi, oneOfOneEditionAbi, seriesImageAbi, deployFixedPriceMinter, deployFixedPriceMinter1155, prepareConfigureSale, prepareConfigureSale1155, preparePurchase, preparePurchase1155, readSaleConfig, readSaleConfig1155, prepareEditionMint, prepareEditionTransfer, prepareSetMaxSupply, preparePingURI, 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 { assertChainId, ensureChunkStore as sdkEnsureChunkStore, predictFixedPriceMinter, predictFixedPriceMinter1155, makeHotSender, makePublicClient, makeWalletClient, oneOfOneImageAbi, oneOfOneEditionAbi, seriesImageAbi, deployFixedPriceMinter, deployFixedPriceMinter1155, prepareConfigureSale, prepareConfigureSale1155, preparePurchase, preparePurchase1155, readSaleConfig, readSaleConfig1155, prepareEditionMint, prepareEditionTransfer, prepareSetMaxSupply, preparePingURI, 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, prepareSetSeedSource, probeSeedSource, readSeedSource, predictSeedSource, getDeployment, prepareTransfer, prepareTransferOwnership, probeTransferValidator, readCreatorTokenStatus, resolveRecommendedTransferValidator, RECOMMENDED_TRANSFER_VALIDATOR, KNOWN_CHAIN_KEYS, resolveChain, resolveRpcUrl, redactRpcUrl, encodeTag, METADATA_FIELD as F, METADATA_REPRESENTATION as R, stageFieldContent, planStagedContent, exceedsOnchainSoftLimit, classifyOnchainReadSize, tokenUriGasEstimate, ONCHAIN_IMAGE_SOFT_LIMIT, ONCHAIN_PROJECT_SOFT_LIMIT, ONCHAIN_READ_WARN_BYTES, ONCHAIN_READ_REFUSE_BYTES, } 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 { decodeFieldRenderer, resolveGenerator, DEP_RESOLUTION, parseDependencyRef, prepareLockDependencies, prepareLockParamHooks, prepareLockScript, prepareRemoveLastDependency, prepareSetDependency, prepareSetDependencyRegistry, } from '@artblocks/abx-sdk';
 import { contentTypeFromPath } from '@artblocks/abx-storage';
 import { toHex as toHexSdk } from 'viem';
 import { readFileSync } from 'node:fs';
@@ -23,12 +23,12 @@ import { openWalletSession } from './signer.js';
 import { gatedSend, laneFromFlags } from './riskgate.js';
 import { withJson } from './jsonout.js';
 import { resolveRemote, serviceClient } from './remote.js';
-import { isDryRun, positionalArgs, unknownFlags } from './flags.js';
+import { allowUnreadableOnchain, isDryRun, positionalArgs, unknownFlags, warnStrayFlags } from './flags.js';
 import { parseSchemaSpecs, describeSchema } from './schema.js';
 // 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 };
+export { ONCHAIN_PROJECT_SOFT_LIMIT, ONCHAIN_READ_WARN_BYTES, ONCHAIN_READ_REFUSE_BYTES, tokenUriGasEstimate };
 // ── 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}`;
@@ -40,16 +40,17 @@ const bold = (s) => `${C.bold}${s}${C.reset}`;
 // 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. `abx_params` joins them for the same reason: it is COMPUTED from the
-// token's on-chain param enumeration, so a hand-set field of that name would be a decoy sitting
-// beside the real block. See specs/protocol/data-plane.md + specs/protocol/onchain-metadata.md.
+// and point at the real verb. `abx_params` stays in this set even though spec v8 removed the
+// projection from `tokenURI`: the name is now free, which makes it MORE attractive as a decoy field
+// and no more meaningful than before. Params are chain state; a field of that name would be a
+// hand-set impostor of a read that lives on the contract. See specs/protocol/data-plane.md + specs/protocol/onchain-metadata.md.
 const COMPUTED_FIELD_KEYS = new Set(['artifacts', 'abx_params', '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"
             : field === 'abx_params'
-                ? "the COMPUTED parameter block, enumerated from the token's on-chain params (set one with `abx configure-param`, declare one with `abx set-schema`)"
+                ? "a reserved name, not a field — params are chain state read straight off the contract (set one with `abx configure-param`, declare one with `abx set-schema`)"
                 : 'the COMPUTED provenance list, assembled by the resolver/renderer';
         throw new Error(`"${field}" is not a field you set — it's ${what}.` +
             (field === 'abx_params'
@@ -64,6 +65,28 @@ function fitsLiteralBytes32(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', 'confirm', 'port', 'sign-url-file', 'remote'];
+/**
+ * The flags EVERY owner write accepts, regardless of command — the signing lane (`laneFromFlags`),
+ * the opt-in confirm gate, the wallet-lane plumbing, the post-write reindex nudge, and `--json`.
+ * Factored out so a per-command allowlist below only has to name that command's OWN flags.
+ */
+const SHARED_WRITE_FLAGS = ['send', 'sign', 'unsigned', 'dry-run', 'yes', 'confirm', 'port', 'sign-url-file', 'remote', 'remote-token', 'json'];
+/**
+ * Per-command allowlists for the owner ops where a silently-ignored flag changes MONEY or SUPPLY.
+ *
+ * These commands took no stray-flag notice at all, and the ERC-1155 lane made that expensive: an
+ * edition's semantics live in its OPTIONAL flags, which default rather than fail. A typo'd
+ * `--amount 50` minted 1 copy; a typo'd `--quantity 5` bought 1 and paid 1×; and nothing said a word.
+ * (`deploy` refuses strays outright, but its allowlists are exhaustively maintained. Here we WARN —
+ * per `unknownFlags`' own contract and the owner's scriptability line: a false warning on a valid
+ * flag must never break someone's script, and a warning already ends the silence.)
+ */
+const MINT_FLAGS = [...SHARED_WRITE_FLAGS, 'to', 'count', 'token-id', 'amount'];
+const TRANSFER_FLAGS = [...SHARED_WRITE_FLAGS, 'to', 'token', 'token-id', 'amount', 'from'];
+const SET_MAX_SUPPLY_FLAGS = [...SHARED_WRITE_FLAGS, 'token-id', 'cap'];
+const MINTER_CONFIGURE_FLAGS = [...SHARED_WRITE_FLAGS, 'price', 'price-raw', 'allocation', 'erc20', 'token-id', 'minter-contract'];
+const MINTER_SHOW_FLAGS = [...SHARED_WRITE_FLAGS, 'token-id', 'minter-contract'];
+const MINTER_BUY_FLAGS = [...SHARED_WRITE_FLAGS, 'to', 'token-id', 'quantity', 'minter-contract'];
 /** 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). */
@@ -196,7 +219,7 @@ export async function assertContractExists(address) {
  * 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
+ * auth (Creator = 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
@@ -214,7 +237,7 @@ export async function assertContractExists(address) {
  * Nothing errored; the in-chain renderer read ASCII where it expected bytes and drew garbage. So a
  * `Bytes` value must state its encoding: `0x…` hex, or `--file` for real binary. A bare string is
  * refused rather than guessed at — there is no safe guess between "these characters" and "these
- * bytes", and the failure is invisible until an artwork renders wrong.
+ * bytes", and the failure is invisible until a work renders wrong.
  */
 export function encodePayloadParam(typeName, valueInput, key) {
     if (typeName === 'String')
@@ -331,7 +354,7 @@ 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)',
+    transfer: 'ownership-change VETO — its revert fails the transfer, and a mint too (mint = transfer from 0x0)',
 };
 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. */
@@ -409,6 +432,13 @@ export async function cmdSetParamHooks(address, flags) {
         const changed = !eqAddr(cur[r], next[r]);
         console.log(`    ${r.padEnd(10)} ${changed ? `${label(cur[r])} → ${label(next[r])}` : `${label(cur[r])} ${dim('(unchanged)')}`}`);
     }
+    // Arming a transfer hook is the one hook change with a consequence for COLLECTORS, so say it at
+    // the moment of arming rather than only in the docs. It is not a warning against doing it — an
+    // owner-dependent work needs it — it is the disclosure that comes with it.
+    if (!eqAddr(next.transfer, zeroAddress) && !eqAddr(next.transfer, cur.transfer)) {
+        console.log(`  ${bold('the transfer hook is a VETO:')} if it reverts, the transfer fails. It also runs on mint and burn (mint = transfer from 0x0), so a reverting hook stops minting for this project too — including through the shared minter.`);
+        console.log(dim(`    that is a standing power over whether a collector can sell. Disclose it, and if you want to prove you will never arm one, \`abx lock-param-hooks ${contract}\` freezes all three addresses forever.`));
+    }
     const owner = await read(contract, 'owner');
     await runWrite(contract, prepareSetParamHooks({ contract, configureHook: next.configure, augmentHook: next.augment, transferHook: next.transfer, chainId: chainId() }), flags, owner);
 }
@@ -469,8 +499,56 @@ 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).'));
+    console.log(dim("  this pins WHICH library each ref means, not the library's bytes: a Registry ref is fetched from the registry on every read, so those bytes stay in the registry owner's hands."));
     await runWrite(contract, prepareLockDependencies({ contract, chainId: chainId() }), flags, owner);
 }
+/** `abx lock-script <address>` — freeze the on-chain program (script chunks) forever. This is the
+ *  lock that actually freezes the WORK of a code project: after it, `setScriptChunk` /
+ *  `removeLastScriptChunk` revert. `lock-field`/`lock-uri` only freeze metadata; the full set for a
+ *  code drop is lock-script + lock-dependencies + lock-field/lock-uri — which freezes what THIS
+ *  contract stores, not necessarily what the token renders (params have no lock, and a Registry
+ *  dependency's bytes live in the registry). */
+export async function cmdLockScript(address, flags) {
+    const contract = requireAddress(address, 'abx lock-script <address> [--sign|--unsigned]');
+    const owner = await read(contract, 'owner');
+    console.log(dim('  note: locking the script is permanent and irreversible (the program bytes can never change again).'));
+    console.log(dim('  this freezes the WORK — pair with lock-dependencies and lock-field/lock-uri to freeze everything this contract stores.'));
+    console.log(dim('  that is not the same as a frozen OUTPUT: params stay writable and a Registry dependency is re-fetched live, so say "locked metadata" to a buyer, not "immutable".'));
+    await runWrite(contract, prepareLockScript({ contract, chainId: chainId() }), flags, owner);
+}
+/** `abx lock-param-hooks <address>` — freeze the three param-lifecycle hook addresses forever.
+ *  The sibling of lock-script/lock-dependencies/lock-uri, and the only one aimed at a BUYER rather
+ *  than at metadata: the transfer hook is a veto over transfers and mints, so an unlocked hook set
+ *  is a standing power over whether a collector can sell. After this, `set-param-hooks` reverts
+ *  ParamHooksLocked. Owner-only, any lane, guards --dry-run. */
+export async function cmdLockParamHooks(address, flags) {
+    const contract = requireAddress(address, 'abx lock-param-hooks <address> [--sign|--unsigned] [--dry-run]');
+    // Read the current trio first: it is the SeriesCode/EditionCode guard (paramHooks() exists only on
+    // the ConfigurableParams extension) AND the thing being frozen — nobody should sign a permanent
+    // freeze without seeing exactly what it freezes.
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    let current;
+    try {
+        current = (await publicClient.readContract({ address: contract, abi: seriesCodeAbi, functionName: 'paramHooks' }));
+    }
+    catch {
+        await assertContractExists(contract);
+        const kind = await detectTokenKind(publicClient, contract);
+        throw new Error(`${contract} exposes no param hooks — they are a SeriesCode/EditionCode (PostParams) feature, ` +
+            `so there is nothing to freeze. ${kind.label} 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);
+    console.log(`  freezing these three addresses on ${contract}, permanently:`);
+    for (const r of HOOK_ROLES)
+        console.log(`    ${r.padEnd(10)} ${label(cur[r])}`);
+    console.log(dim('  note: this is permanent and irreversible — no hook address can ever be set, re-pointed, or cleared again.'));
+    console.log(dim(`  you are giving up: arming a transfer veto (a hook that can block transfers and mints), arming a write-time configure veto, and re-pointing or clearing the augment hook. ` +
+        `${eqAddr(cur.transfer, zeroAddress) ? 'With no transfer hook set, freezing is how you PROVE you can never add one — the guarantee a buyer can check.' : 'The transfer hook already set stays live and keeps its veto: freezing the set is not disarming what is in it.'}`));
+    console.log(dim('  this freezes only the hooks. Schemas, param values, script, dependencies and URIs keep their own locks (`abx verify` lists them).'));
+    const owner = await read(contract, 'owner');
+    await runWrite(contract, prepareLockParamHooks({ contract, chainId: chainId() }), flags, owner);
+}
 // ── editions: shared small parsers ────────────────────────────────────────────
 /** A non-negative-integer edition flag (`--token-id`, `--amount`, …) — the shared parse +
  *  bound-check so every edition command that takes "an id" or "a count" rejects the same way. */
@@ -514,6 +592,7 @@ export function parseTokenIdRange(raw) {
 export async function cmdMint(address, flags) {
     const usage = 'abx mint <address> [--to 0x…] [--count <n> | --token-id <id> --amount <n>] [--json] [--sign|--unsigned]';
     const contract = requireAddress(address, usage);
+    warnStrayFlags(flags, new Set(MINT_FLAGS), 'mint');
     // `--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
@@ -531,9 +610,9 @@ export async function cmdMint(address, flags) {
                 throw new Error(`--count is a 721 Series flag (mint N tokens in order) — ${contract} is a ${kind.label} (edition). Use --token-id <id> --amount <n> instead.`);
             }
             // OneOfOneEdition's id space is fixed to {0}, so --token-id defaults there; EditionImage/
-            // EditionCode ids are caller-named artworks with no sensible default — require it.
+            // EditionCode ids are caller-named works with no sensible default — require it.
             if (kind.kind !== '1of1-edition' && flags['token-id'] === undefined) {
-                throw new Error(`--token-id is required on a ${kind.label} — its ids are caller-named artworks, not a single default. ` +
+                throw new Error(`--token-id is required on a ${kind.label} — its ids are caller-named works, not a single default. ` +
                     `See existing ids with \`abx tokens ${contract}\`.`);
             }
             const tokenId = flags['token-id'] !== undefined ? parseEditionCountFlag(flags['token-id'], 'token-id') : 0n;
@@ -612,6 +691,17 @@ 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));
+    // The cap only ever decreases, but `--dry-run` used to print "Set max invocations → 20" and state
+    // the new value as fact for a contract capped at 16 — then the real send reverted. A creator (or an
+    // agent) reads a clean dry run as permission to send, so the preview has to know what the chain
+    // knows. Best-effort: an unreadable getter does NOT block, since the chain enforces it regardless.
+    // `readSeries`, not `read`: the 1/1 ABI that `read` uses has no `maxInvocations` at all, so reading
+    // through it always threw and this guard silently never fired.
+    const capNow = await readSeries(contract, 'maxInvocations').catch(() => null);
+    if (capNow !== null && max > capNow) {
+        throw new Error(`${contract}'s cap is already ${capNow} and maxInvocations can only DECREASE — ${max} would raise it, which the chain refuses. ` +
+            `Pass a number at or below ${capNow} (a supply cap is one-way by design: it can be tightened, never reopened).`);
+    }
     const owner = await read(contract, 'owner');
     await runWrite(contract, prepareSetMaxInvocations({ contract, maxInvocations: max, chainId: chainId() }), flags, owner);
 }
@@ -627,6 +717,7 @@ export async function cmdSetMaxInvocations(address, flags) {
 export async function cmdSetMaxSupply(address, flags) {
     const usage = 'abx set-max-supply <address> --token-id <n> --cap <n> [--sign|--unsigned]';
     const contract = requireAddress(address, usage);
+    warnStrayFlags(flags, new Set(SET_MAX_SUPPLY_FLAGS), 'set-max-supply');
     const publicClient = makePublicClient({ chainKey: CHAIN });
     const kind = await detectTokenKind(publicClient, contract);
     if (!kind.isEdition) {
@@ -640,11 +731,29 @@ export async function cmdSetMaxSupply(address, flags) {
             `(the --copies default from deploy) — there's nothing to set. To lower an existing cap, pass the number.`);
     }
     const cap = parseEditionCountFlag(capRaw, 'cap');
+    // Both ways this reverts on chain were reachable through `--dry-run` unchanged: the preview printed
+    // "#0 supply cap → 50" and stated the new cap as fact, then the real send reverted. A dry run that
+    // green-lights an impossible write is worse than no dry run — the creator's next step is to send it.
+    // `maxSupply(id) === 0` reads as "open" (the un-overridden --copies default), so any finite cap is a
+    // decrease from open and allowed. Reads are best-effort: if either read fails we do NOT block, since
+    // the chain still enforces the invariant and a guard must not turn an RPC miss into a refusal.
+    const [capNow, supplyNow] = await Promise.all([
+        readEdition(contract, 'maxSupply', [tokenId]).catch(() => null),
+        readEdition(contract, 'totalSupply', [tokenId]).catch(() => null),
+    ]);
+    if (capNow !== null && capNow > 0n && cap > capNow) {
+        throw new Error(`#${tokenId}'s cap is already ${capNow} and a cap can only DECREASE — ${cap} would raise it, which the chain refuses. ` +
+            `Pass a number at or below ${capNow}${supplyNow !== null ? ` and at or above its ${supplyNow} live cop${supplyNow === 1n ? 'y' : 'ies'}` : ''}.`);
+    }
+    if (supplyNow !== null && cap < supplyNow) {
+        throw new Error(`#${tokenId} already has ${supplyNow} cop${supplyNow === 1n ? 'y' : 'ies'} minted, so a cap of ${cap} would sit BELOW live supply — the chain refuses that. ` +
+            `The lowest cap you can set is ${supplyNow} (which closes the id to further minting).`);
+    }
     const owner = await read(contract, 'owner');
     console.log(dim(`  #${tokenId} supply cap → ${cap}`));
     await runWrite(contract, prepareSetMaxSupply({ contract, tokenId, cap, chainId: chainId() }), flags, owner);
 }
-// ── ping-uri (editions only) — permissionless URI re-emission ────────────────────────────────────
+// ── ping-uri (editions only) — the OWNER's URI re-emission ───────────────────────────────────────
 /** How many ids one `pingURI` call carries per transaction — large enough that a normal collection
  *  fits in one tx, small enough that a genuinely huge id list doesn't build one unbounded call. */
 const PING_URI_CHUNK_SIZE = 200;
@@ -663,13 +772,14 @@ export async function cmdPingUri(address, flags) {
     const kind = await detectTokenKind(publicClient, contract);
     if (!kind.isEdition) {
         throw new Error(`ping-uri is edition-only — it re-emits the ERC-1155 URI event, which a ${kind.label} (721) doesn't have ` +
-            `(721 emits ERC-4906 MetadataUpdate automatically on a URI change — nothing to re-emit by hand).`);
+            `(both lanes emit ERC-4906 automatically on a URI change; this command is for indexers that ` +
+            `honor only the native 1155 event).`);
     }
     const ids = parseTokenIdRange(requireFlag(flags, 'token-ids', usage));
     const chunks = [];
     for (let i = 0; i < ids.length; i += PING_URI_CHUNK_SIZE)
         chunks.push(ids.slice(i, i + PING_URI_CHUNK_SIZE));
-    console.log(dim(`  re-emitting URI for ${ids.length} id${ids.length === 1 ? '' : 's'} — permissionless (no owner check) — ${chunks.length} tx${chunks.length === 1 ? '' : '(s)'} of up to ${PING_URI_CHUNK_SIZE} id(s) each`));
+    console.log(dim(`  re-emitting URI for ${ids.length} id${ids.length === 1 ? '' : 's'} — owner-only — ${chunks.length} tx${chunks.length === 1 ? '' : '(s)'} of up to ${PING_URI_CHUNK_SIZE} id(s) each`));
     for (const [i, chunk] of chunks.entries()) {
         if (chunks.length > 1)
             console.log(dim(`  chunk ${i + 1}/${chunks.length}: ${chunk.length} id(s) (#${chunk[0]}–#${chunk[chunk.length - 1]})`));
@@ -695,9 +805,9 @@ export async function cmdUnpause(address, flags) {
  *  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],
+    ['creator', F.creator],
     ['display-notes', F.displayNotes],
-    ['artist-links', F.artistLinks],
+    ['creator-links', F.creatorLinks],
     ['license', F.license],
 ];
 /** Build the on-chain (inline) collection fields for whichever authorship/rights deploy flags are
@@ -763,14 +873,29 @@ export async function cmdRefresh(address, flags) {
         console.log(`    ${dim('OpenSea  ')}${osBase}/assets/${osChain}/${contract}/${tokenId}`);
     if (explorer)
         console.log(`    ${dim('Etherscan')} ${explorer}/token/${contract}?a=${tokenId}`);
+    // Both lanes now emit ERC-4906 on a URI change, so this is one sentence again. The 1155 lane
+    // used to emit only its own config event, which is why this branched and why `ping-uri` exists;
+    // an audit found a collection-wide re-point on an edition had NO refresh signal at all, and the
+    // fix was to emit the O(1) ERC-4906 range form there too. `ping-uri` is still useful on an
+    // edition, but for a narrower reason: it re-emits the NATIVE ERC-1155 `URI` event for indexers
+    // that honor only that one.
     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 usage = 'abx transfer <address> --to 0x… [--token 0] [--amount <n> --from 0x… (editions only)] [--sign|--unsigned]';
+    const usage = 'abx transfer <address> --to 0x… [--token 0 | --token-id 0] [--amount <n> --from 0x… (editions only)] [--sign|--unsigned]';
     const contract = requireAddress(address, usage);
+    warnStrayFlags(flags, new Set(TRANSFER_FLAGS), 'transfer');
     const to = requireFlag(flags, 'to', usage);
-    const tokenId = BigInt(flags.token ?? '0');
+    // `--token-id` is accepted as an alias for `--token`: EVERY sibling id-taking command (`mint`,
+    // `set-max-supply`, `minter …`) spells it `--token-id`, so an agent that learned the name there
+    // passed it here — where it was silently ignored and id 0 moved instead of the id they named.
+    // On an edition that means transferring the WRONG WORK with no warning. Both spellings work now;
+    // disagreeing values are refused rather than silently preferring one.
+    if (flags.token !== undefined && flags['token-id'] !== undefined && flags.token !== flags['token-id']) {
+        throw new Error(`--token ${flags.token} and --token-id ${flags['token-id']} disagree — pass one (they are aliases for the same id).`);
+    }
+    const tokenId = BigInt(flags['token-id'] ?? flags.token ?? '0');
     const publicClient = makePublicClient({ chainKey: CHAIN });
     const kind = await detectTokenKind(publicClient, contract);
     if (kind.isEdition) {
@@ -937,21 +1062,26 @@ export async function cmdSetTransferValidator(address, rest, flags) {
             `Enrollment can never be added to a live collection; if enforcement is required, redeploy with ` +
             `--721c recommended (or --721c 0x…) on the deploy command.`);
     }
-    // Codeless-validator guard: the contract refuses a non-zero validator with no code
-    // (`InvalidTransferValidator()`) — surface it before gas is spent.
+    // Unusable-validator guard: the contract refuses a non-zero validator that fails its own probe —
+    // no code, OR a permissive fallback that would enforce nothing (a Safe, an uninitialised proxy, a
+    // 7702-delegated EOA). Both revert `InvalidTransferValidator()`, so the preflight has to ask the
+    // same question the chain asks; a bare has-code check passed a creator's Safe and then let the
+    // send fail on chain with an error whose documented meaning ("no code") was false for their case.
     if (validator !== zeroAddress) {
-        let code;
-        try {
-            code = await publicClient.getCode({ address: validator });
+        const probe = await probeTransferValidator(publicClient, validator, { as: contract });
+        if (probe.verdict === 'unreachable') {
+            throw new Error(`couldn't verify the validator at ${validator} (${probe.error ?? 'RPC did not answer'}) — refusing to re-point blind; retry when the RPC answers.`);
         }
-        catch (err) {
-            throw new Error(`couldn't verify the validator has code at ${validator} (${err.message}) — refusing to re-point blind; retry when the RPC answers.`);
-        }
-        if (!code || code === '0x') {
+        if (probe.verdict !== 'ok') {
             const rec = resolveRecommendedTransferValidator(cid);
-            throw new Error(`no contract code at ${validator} on ${CHAIN} — the token would revert InvalidTransferValidator(). ` +
-                `A transfer validator must be a DEPLOYED contract on this chain` +
-                (rec ? ` (the recommended one: \`abx set-transfer-validator ${contract} recommended\` → ${rec})` : '') + `.`);
+            const recHint = rec ? ` (the recommended one: \`abx set-transfer-validator ${contract} recommended\` → ${rec})` : '';
+            throw new Error(probe.verdict === 'no-code'
+                ? `no contract code at ${validator} on ${CHAIN} — the token would revert InvalidTransferValidator(). ` +
+                    `A transfer validator must be a DEPLOYED contract on this chain${recHint}.`
+                : `${validator} has code on ${CHAIN}, but it is not a transfer validator — it answers ANY function call successfully ` +
+                    `(a Safe, an uninitialised proxy, or a 7702-delegated EOA does this), so every transfer would silently pass ` +
+                    `validation while ERC-165 and getTransferValidator() reported enforcement as ON. The token refuses it too ` +
+                    `(InvalidTransferValidator()). Pass a real validator contract${recHint}, or \`none\` to suspend enforcement.`);
         }
     }
     if (eqAddr(status.validator, validator)) {
@@ -963,6 +1093,167 @@ export async function cmdSetTransferValidator(address, rest, flags) {
     const owner = await read(contract, 'owner');
     await runWrite(contract, prepareSetTransferValidator({ contract, validator, chainId: cid }), flags, owner);
 }
+// ── the seed source — where a code project's mint randomness comes from ───────
+// The canonical `AbxSeedSource` is deliberately pseudorandom: replayable after the mint (what makes
+// generative output verifiable) and computable DURING it (so a buyer can decline an outcome for the
+// price of gas — and on an EDITION, where the buyer names the id and the id is in the preimage, they
+// can shop the unminted ids rather than merely decline; bounded by how many remain)
+// price of gas). We tell creators that the escape hatch for anything lottery-like is "point
+// `seedSource` at your own IAbxSeedSource over commit-reveal or a VRF oracle" — this is the surface
+// that makes that promise real instead of a doc claim: `--seed-source` at deploy, `abx
+// set-seed-source` after, and one probe standing in front of both.
+/** The canonical `AbxSeedSource` for a chain — the manifest entry (the source of truth) with the
+ *  CREATE2 prediction as the cross-chain fallback (the singleton is address-identical everywhere).
+ *  Deliberately does NOT go through `resolveSeedSource`, which reads `ABX_SEED_SOURCE`: that env var
+ *  names the source you have CONFIGURED, which is exactly the thing `canonical` exists to name the
+ *  alternative to. Asking for `canonical` and silently getting your custom override would be the
+ *  worst possible answer. */
+export function canonicalSeedSource(chainId) {
+    return getDeployment(chainId).seedSource ?? predictSeedSource();
+}
+/**
+ * Parse a seed-source choice — the shared grammar of the deploy flag (`--seed-source`) and the owner
+ * op (`abx set-seed-source`):
+ *   - `canonical` (or a bare `--seed-source`) → the chain's canonical `AbxSeedSource`, i.e. the
+ *     default; spelled out so a creator can state it rather than rely on absence meaning it;
+ *   - a `0x…` address → checksum-validated (EIP-55) and returned canonicalized. The caller MUST
+ *     probe it (see {@link refuseUnusableSeedSource}) — a bad address here is silent until the
+ *     first buyer, and then every mint reverts;
+ *   - `none`/zero → `allowNone` decides: the owner op clears with it (future mints draw no seed);
+ *     the DEPLOY flag refuses it and points at `--no-seed`, which already means exactly that. Two
+ *     spellings of one thing is how a creator ends up unsure which they used.
+ * Pure (no RPC) — mirrors `parseTransferValidatorValue`, deliberately, so the two knobs read the
+ * same. Exported for the regression test.
+ */
+export function parseSeedSourceValue(raw, opts) {
+    const s = raw.trim().toLowerCase();
+    if (s === 'true' || s === '' || s === 'canonical' || s === 'default')
+        return canonicalSeedSource(opts.chainId);
+    if (s === 'none' || s === 'zero' || s === '0' || s === '0x0' || s === zeroAddress) {
+        if (opts.allowNone)
+            return zeroAddress;
+        throw new Error(`--seed-source none is refused: "no mint-time seed" already has a flag — pass \`--no-seed\` instead. ` +
+            `(One meaning, one spelling: --seed-source names WHERE the seed comes from, --no-seed says there isn't one.)`);
+    }
+    const trimmed = raw.trim();
+    if (!/^0x[0-9a-fA-F]{40}$/.test(trimmed)) {
+        throw new Error(`seed source must be 'canonical'${opts.allowNone ? ", 'none'," : ''} or a 0x address (0x + 40 hex); got '${raw}'`);
+    }
+    // Strict EIP-55 (see the identical note on parseTransferValidatorValue): `getAddress` alone only
+    // normalizes, so a mis-cased paste would sail through — and a seed source pointed one nibble off
+    // is a collection whose every mint reverts.
+    if (!isAddress(trimmed, { strict: true })) {
+        throw new Error(`seed source address failed its EIP-55 checksum: '${raw}' — paste it exactly (or all-lowercase).`);
+    }
+    return getAddress(trimmed);
+}
+/**
+ * Turn a non-`ok` {@link SeedSourceProbe} into the refusal a creator can act on. One place, because
+ * the deploy flag and the owner op hit the identical failure shapes and must say the identical
+ * thing; `context` only names which surface asked (so the fix names the right flag).
+ *
+ * Every branch is a REFUSAL, not a warning. A seed source is the one setting where "looks fine, is
+ * broken" is the normal outcome of a mistake: `seedSource()` reads back exactly what you set, the
+ * `SeedSourceSet` event fires, `abx state` shows it — and then the first mint reverts in the ABI
+ * decode of a return that isn't 32 bytes. There is no later moment at which this gets easier to
+ * notice, so it is caught here or it is caught by a buyer.
+ */
+export function refuseUnusableSeedSource(probe, context) {
+    const { flag, chainLabel } = context;
+    const head = `${flag}: ${probe.address} is not a usable seed source on ${chainLabel}`;
+    const tail = `\n  A seed source must answer \`seed(uint256 tokenId, address to)\` with 32 bytes — the token calls it ` +
+        `SYNCHRONOUSLY inside every mint and decodes the result as \`bytes32\`, so anything else reverts the mint.`;
+    switch (probe.verdict) {
+        case 'no-code':
+            throw new Error(`${head} — there is no contract code there.${tail}\n` +
+                `  (A Solidity call to a codeless address succeeds with empty returndata, so the revert would land in the ` +
+                `decode, at mint time, for every buyer. Check the address and the chain — ${flag} is chain-specific.)`);
+        case 'empty-return':
+            throw new Error(`${head} — it has code, answered, and returned NOTHING.${tail}\n` +
+                `  This is the permissive-fallback shape: a Safe (its fallback returns empty for an unset handler), an ` +
+                `uninitialised proxy, or an EIP-7702-delegated EOA. Pasting your own wallet/Safe here is the common way in. ` +
+                `A seed source is a purpose-built contract implementing IAbxSeedSource — commit-reveal or a VRF oracle.`);
+        case 'short-return':
+            throw new Error(`${head} — it answered with only ${probe.returnedBytes} byte(s), not 32.${tail}\n` +
+                `  Whatever is deployed there has a different ABI; it is not an IAbxSeedSource.`);
+        case 'reverted':
+            throw new Error(`${head} — the call reverted (${probe.error ?? 'no reason returned'}).${tail}\n` +
+                `  Two ways in: (1) it isn't a seed source at all — a token, a renderer, a registry has no such function; ` +
+                `(2) it IS one, but it refuses right now (gating callers, or not yet armed/committed). Both are refusals here: ` +
+                `a source that cannot answer today cannot answer at mint either, and its revert would bubble through the mint. ` +
+                `Arm the source first, then point at it.`);
+        default:
+            // `unreachable` and any verdict a future SDK adds: refuse rather than proceed. A `default` (not
+            // a `case 'unreachable'`) so a new verdict cannot silently become "allowed" by falling through.
+            throw new Error(`${head} — couldn't verify it (${probe.verdict}${probe.error ? `: ${probe.error}` : ''}). ` +
+                `Refusing to configure a seed source blind; retry when the RPC answers.`);
+    }
+}
+/**
+ * `abx set-seed-source <address> <0x…|canonical|none>` — re-point (or clear) where a code project
+ * draws its mint seeds. Owner-only; **future mints only**, because a seed settles the moment it is
+ * assigned and nothing rewrites it. Refuses before any signing: a target with no Seed Source
+ * extension (a 1/1 or an image Series — there is nothing to set), and any candidate the probe
+ * rejects.
+ *
+ * This op is deliberately loud about one thing the chain cannot enforce: re-pointing mid-sale means
+ * tokens minted before and after draw from **different** sources. That is legitimate (it is how you
+ * fix a broken source, or hand over to a commit-reveal one), and it is public — `SeedSourceSet` is
+ * on the event spine and `abx state` prints the current source — but a collector who bought early
+ * has no way to know it will happen. So the print names the split when supply already exists.
+ */
+export async function cmdSetSeedSource(address, rest, flags) {
+    const usage = 'abx set-seed-source <address> <0x…|canonical|none> [--sign|--unsigned] [--dry-run]';
+    const contract = requireAddress(address, usage);
+    const [raw] = positionalArgs(rest);
+    if (!raw) {
+        console.error(`usage: ${usage}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const cid = chainId();
+    const source = parseSeedSourceValue(raw, { chainId: cid, allowNone: true });
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    await assertContractExists(contract);
+    // Extension guard FIRST — a read, not a send. `seedSource()` is absent on a 1/1 / image Series, so
+    // `setSeedSource` there is a call to a selector the contract doesn't have: it would revert with no
+    // reason bytes at all. Say what the target actually is instead.
+    const current = await readSeedSource(publicClient, contract);
+    if (current === undefined) {
+        throw new Error(`${contract} has no seed source to set — the Seed Source extension is composed only by CODE projects ` +
+            `(SeriesCode / EditionCode, i.e. \`abx deploy-code\`). An image 1/1 or Series has no mint-time seed at all, ` +
+            `and the extension can't be added to a live contract.`);
+    }
+    if (eqAddr(current, source)) {
+        console.log(dim(`  no change — the seed source is already ${source === zeroAddress ? 'cleared (0x0 — no mint-time seed)' : source}. Nothing sent.`));
+        return;
+    }
+    if (source !== zeroAddress) {
+        const probe = await probeSeedSource(publicClient, source, { as: contract });
+        if (probe.verdict !== 'ok')
+            refuseUnusableSeedSource(probe, { flag: 'set-seed-source', chainLabel: CHAIN });
+    }
+    const label = (a) => (eqAddr(a, zeroAddress) ? 'none (0x0 — no mint-time seed)' : eqAddr(a, canonicalSeedSource(cid)) ? `${a} (canonical AbxSeedSource)` : a);
+    console.log(dim(`  seed source: ${label(current)} → ${label(source)}`));
+    // Seeds already assigned are settled — say so, and say what the split means. `totalSupply()` is a
+    // 721 getter (an edition's is per-id), so the count is best-effort; the note itself is not, because
+    // "future mints only" is the part a creator has to understand before sending.
+    const minted = await readSeries(contract, 'totalSupply').catch(() => null);
+    if (minted === null || minted > 0n) {
+        console.log(dim(`  ${minted === null ? 'Tokens' : `${minted} token(s)`} already minted carry a seed drawn from ${label(current)} — settled, and unchanged by this. ` +
+            `This applies to FUTURE mints only, so a part-sold collection ends up spanning two sources. The change is public ` +
+            `(SeedSourceSet on the event spine; \`abx state ${contract}\` prints the current one), but a collector who ` +
+            `already bought won't be told — if the drop is live, consider pausing and saying so.`));
+    }
+    if (source === zeroAddress) {
+        console.log(dim('  clearing means future mints draw NO seed at all — a generative program that expects one will render blank/identical.'));
+    }
+    else if (!eqAddr(source, canonicalSeedSource(cid))) {
+        console.log(dim("  custom source — its randomness properties are now yours to state to buyers; ABX makes no claim about them."));
+    }
+    const owner = await read(contract, 'owner');
+    await runWrite(contract, prepareSetSeedSource({ contract, seedSource: source, 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
@@ -1026,13 +1317,55 @@ export function sessionStagingSender(session) {
     return async (tx) => (await session.send(tx)).receipt;
 }
 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 (!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;
+const mgas = (n) => `~${(n / 1_000_000).toFixed(0)}M gas`;
+/** The flag that overrides {@link guardOnChainSize}'s refusal — a creator who genuinely wants a
+ *  project no default RPC can read. Named for what accepting it means, not for the check it skips. */
+export const ALLOW_UNREADABLE_FLAG = 'allow-unreadable-onchain';
+/**
+ * The size gate for content going on-chain, on the axis that actually binds: **render gas**, not
+ * storage cost. `tokenURI` reassembles the whole document per call — measured at ~360,000-405,000 gas
+ * per KB of on-chain content across 10-100 KB and climbing above that (the cost is superlinear: memory
+ * expansion is quadratic), within ~1% for `inline` and `reader` up to 75 KB (it's the renderer's string
+ * building, not the storage mechanism) — so the readable envelope is much tighter than the cost-sane one.
+ *
+ * - under ~40 KB: quiet, plus the cost note if it's past the point where off-chain is simply cheaper.
+ * - from ~40 KB: **warn** — the read needs a deliberately high-gas RPC.
+ * - past ~100 KB (~40M gas): **refuse** — a deliberate margin, not the wall. geth's own 50M
+ *   `--rpc.gascap` default holds to ~120 KB, but hosted providers commonly cap well below it, so past
+ *   100 KB the token reads as a revert to marketplaces and indexers on ordinary RPCs.
+ *   `--allow-unreadable-onchain` ships it anyway.
+ *
+ * Deliberately a toolkit gate and not an on-chain one: bricking a contract over a read budget is
+ * worse than needing a capable RPC, and this is the moment where the creator can still choose
+ * differently. Returns true if it said anything.
+ */
+export function guardOnChainSize(bytesLen, label, allowUnreadable = false) {
+    const verdict = classifyOnchainReadSize(bytesLen);
+    const gas = mgas(tokenUriGasEstimate(bytesLen));
+    if (verdict === 'refuse' && !allowUnreadable) {
+        throw new CliError(`${label} is ${kb(bytesLen)} of on-chain content — reading tokenURI would cost ${gas}, past what a default node will serve ` +
+            `(geth's --rpc.gascap defaults to 50M; hosted providers commonly cap lower). Marketplaces, indexers, and other contracts ` +
+            `would see a REVERT rather than your token, so this is refused by default.\n` +
+            `    Three ways forward:\n` +
+            `      • Off-chain custody: --backend arweave (pay-once, permanent) or ipfs|cloud — the bytes live off-chain, the JSON still resolves on-chain, and the read stays small.\n` +
+            `      • Smaller SOURCE content: a leaner SVG rather than a raster. Note --compress fastlz does not help here — it cuts the write cost, and the renderer rebuilds the full uncompressed bytes on every read.\n` +
+            `      • Ship it unreadable on purpose: re-run with --${ALLOW_UNREADABLE_FLAG}. That is a real choice (maximum durability, nothing to run, ever) — and what you accept is that rendering needs a deliberately high-gas endpoint, and most marketplaces and indexers will show nothing at all.`);
+    }
+    if (verdict === 'refuse') {
+        console.log(yellow(`  ⚠ ${label} is ${kb(bytesLen)} on-chain — tokenURI costs ${gas} to read, past a default node's eth_call cap. Shipping anyway (--${ALLOW_UNREADABLE_FLAG}).`));
+        console.log(dim(`    What you're accepting: marketplaces and indexers on ordinary RPCs will see a revert, not your token; rendering needs a deliberately high-gas endpoint. Assemble from the generator's piecewise getters (\`document\`, \`tokenDataJson\`, \`dependencyTag\`) when one eth_call won't fit.`));
+        return true;
+    }
+    if (verdict === 'warn') {
+        console.log(yellow(`  ⚠ ${label} is ${kb(bytesLen)} on-chain — reading tokenURI costs ${gas} (~360-405k gas per KB of content and climbing, whatever the representation).`));
+        console.log(dim(`    That is served by a high-gas RPC but not by every hosted one, and it is past what another contract can spend inside a transaction. Under ~${kb(ONCHAIN_READ_WARN_BYTES)} of on-chain content per token is the routinely-readable range; off-chain custody (--backend arweave|ipfs|cloud) keeps the JSON on-chain and the read small.`));
+        return true;
+    }
+    if (exceedsOnchainSoftLimit(bytesLen)) {
+        console.log(dim(`  ${label} is ${kb(bytesLen)} — past ~${kb(ONCHAIN_IMAGE_SOFT_LIMIT)}/file on-chain costs more to write than off-chain (~200 gas/byte), so pick it for self-resolution, not for price. Reading tokenURI: ${gas}.`));
+        return true;
+    }
+    return false;
 }
 /**
  * Pure staging plan for a piece of content — chunk count + transaction shape — with NO chain
@@ -1079,8 +1412,9 @@ function planTxLine(p, finalLabel) {
  * 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) {
-    warnIfLargeForOnChain(bytes.length, `'${field}'`);
+async function putContentOnChain(bytes, compress, field, send, finalLabel = '1 owner field-set', store, // pre-resolved store (batch staging reuses one); else resolve/deploy here
+allowUnreadable = false) {
+    guardOnChainSize(bytes.length, `'${field}'`, allowUnreadable);
     const content = compress === 'gzip' ? new Uint8Array(gzipSync(bytes)) : new Uint8Array(bytes);
     const publicClient = makePublicClient({ chainKey: CHAIN });
     return stageFieldContent({
@@ -1110,10 +1444,12 @@ async function putContentOnChain(bytes, compress, field, send, finalLabel = '1 o
  * 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) {
+export function previewImageStaging(imagePath, compress, allowUnreadable = false) {
     const bytes = readFileSync(resolvePath(imagePath));
     const p = computeContentPlan(bytes, compress);
-    warnIfLargeForOnChain(bytes.length, basename(resolvePath(imagePath)));
+    // The gate runs on the dry-run too: a refusal a creator only meets after the first staging tx has
+    // landed is a refusal that already cost them gas.
+    guardOnChainSize(bytes.length, basename(resolvePath(imagePath)), allowUnreadable);
     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)')}`);
@@ -1125,9 +1461,9 @@ export function previewImageStaging(imagePath, compress) {
  * 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) {
+export async function stageImageField(imagePath, compress, send, allowUnreadable = false) {
     const bytes = readFileSync(resolvePath(imagePath));
-    const { value, representation } = await putContentOnChain(bytes, compress, 'image', send, '1 deploy (bakes the reader field + mints)');
+    const { value, representation } = await putContentOnChain(bytes, compress, 'image', send, '1 deploy (bakes the reader field + mints)', undefined, allowUnreadable);
     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`,
@@ -1137,15 +1473,15 @@ export async function stageImageField(imagePath, compress, send) {
  * 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
+ * Each field still points at its own manifest, so each token's work is independent; they just
  * share the store contract. Returns the fields in input order (token order).
  */
-export async function stageImageFieldsBatch(imagePaths, compress, send, storeOverride) {
+export async function stageImageFieldsBatch(imagePaths, compress, send, storeOverride, allowUnreadable = false) {
     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);
+        const { value, representation } = await putContentOnChain(bytes, compress, 'image', send, '1 deploy (bakes the reader fields + mints)', store, allowUnreadable);
         fields.push({ field: encodeTag(F.image), representation: encodeTag(representation), value });
     }
     return { fields, store };
@@ -1220,6 +1556,8 @@ export async function cmdSetField(address, flags) {
     if (staging && isDryRun(flags)) {
         const bytes = readFileSync(resolvePath(flags.file));
         const p = computeContentPlan(bytes, parseCompress(flags.compress));
+        // Same render-gas gate the real path applies, so a refusal costs a dry run rather than gas.
+        guardOnChainSize(bytes.length, `'${field}'`, allowUnreadableOnchain(flags));
         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))}`);
@@ -1251,7 +1589,7 @@ export async function cmdSetField(address, flags) {
         });
         try {
             await session.connect();
-            const { value, representation } = await putContentOnChain(bytes, compress, field, sessionStagingSender(session));
+            const { value, representation } = await putContentOnChain(bytes, compress, field, sessionStagingSender(session), undefined, undefined, allowUnreadableOnchain(flags));
             await session.send(buildTx(value, representation));
         }
         finally {
@@ -1265,7 +1603,7 @@ export async function cmdSetField(address, flags) {
     let representation;
     if (staging) {
         const compress = parseCompress(flags.compress);
-        ({ value, representation } = await putContentOnChain(readFileSync(resolvePath(flags.file)), compress, field, envStagingSender()));
+        ({ value, representation } = await putContentOnChain(readFileSync(resolvePath(flags.file)), compress, field, envStagingSender(), undefined, undefined, allowUnreadableOnchain(flags)));
     }
     else if (flags.text && flags.text !== 'true') {
         value = toHex(flags.text);
@@ -1396,13 +1734,13 @@ 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 only (params are chain state — read them with abx tokens).`));
     }
     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 — ` +
+            `this project resolves ON-CHAIN (no resolver base baked in), and the on-chain document carries reserved fields only — ` +
             `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.)'));
+            dim('(Params are chain state, readable with abx tokens and by any contract call — 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}.`));
     }
     // ONE transaction for the whole set. `batchOps` folds a same-target run into a `multicall` and
@@ -1427,7 +1765,7 @@ export async function cmdAttach(rest, flags) {
             dim(`    verify (a resolver serves the complete listing): `) +
             `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`));
+            dim(`    (The complete file listing is a resolver surface — the bare on-chain tokenURI enumerates reserved fields. Params never need a resolver, they are read straight off the contract; attachments do.)\n`));
     }
 }
 // ── lock-field ───────────────────────────────────────────────────────────────
@@ -1435,9 +1773,9 @@ export async function cmdAttach(rest, flags) {
  * Refuse `lock-field` on a name that is a declared PARAM key.
  *
  * Fields and params are two separate namespaces that may share a name, and `lock-field` only ever
- * locks the *field*. A tester welded `grid` — a `Bytes` param holding the artwork — with
+ * locks the *field*. A tester welded `grid` — a `Bytes` param holding the work — with
  * `lock-field --field grid`, got "permanent", got `tokenFieldLocked(0,"grid") == true`, and then
- * overwrote the artwork with `configure-param` on the next call. Every individual statement the CLI
+ * overwrote the work with `configure-param` on the next call. Every individual statement the CLI
  * made was true; together they promised a protection that did not exist. Permanence is the pitch, so
  * this refuses rather than warns, and names the mechanism that actually welds a param.
  */
@@ -1502,13 +1840,14 @@ export async function cmdSetRenderer(address, flags) {
 }
 // ── 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`. */
+ *  locked, the stored metadata can never change again — the on-chain twin of a frozen
+ *  `tokenURI`. Not the same as a frozen OUTPUT: params have no lock and the renderer
+ *  projects them, and a Registry dependency resolves live. Scope: token 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.`));
+    console.log(dim(`  note: locking the ${collection ? 'contractURI' : 'tokenURI'} config is permanent — pointer + renderer can never change again. Locked metadata is not a locked output: params stay writable and the renderer serves them.`));
     const tx = collection
         ? prepareLockContractURI({ contract, chainId: chainId() })
         : prepareLockTokenURI({ contract, chainId: chainId() });
@@ -1631,12 +1970,13 @@ function parseSalePrice(flags, usage) {
  * the token, set a primary payee) and whether the token is paused.
  *
  * On an EDITION (OneOfOneEdition/EditionImage/EditionCode), `--token-id` is REQUIRED (sales are
- * keyed `(token, id)` — a per-artwork price, not one project-wide sale) and the sale routes to the
+ * keyed `(token, id)` — a per-work price, not one project-wide sale) and the sale routes to the
  * shared `AbxFixedPriceMinter1155` instead. Refused on a 721 target.
  */
 export async function cmdMinterConfigure(address, flags) {
     const usage = 'abx minter configure <token> (--price <eth> | --price-raw <units>) --allocation <n> [--erc20 0x…] [--token-id <n> (editions)] [--minter-contract 0x…] [--sign|--unsigned]';
     const token = requireAddress(address, usage);
+    warnStrayFlags(flags, new Set(MINTER_CONFIGURE_FLAGS), 'minter configure');
     const publicClient = makePublicClient({ chainKey: CHAIN });
     const kind = await detectTokenKind(publicClient, token);
     const owner = await read(token, 'owner');
@@ -1673,10 +2013,15 @@ export async function cmdMinterConfigure(address, flags) {
         console.log(dim(`    price      ${isEth ? `${formatEther(price)} ETH` : `${price} units of ${erc20}`} / copy`));
         console.log(dim(`    allocation ${allocation}`));
         await runMinterWrite(prepareConfigureSale1155({ minter, token, tokenId, paymentToken: erc20, price, allocation, chainId: chainId() }), flags, owner);
+        // Through the EDITION ABI, for the same reason `minter show` spells out: the generic `read()`
+        // is the 721 1/1 ABI, which has no minter()/primaryPayee() at all, so the call throws
+        // client-side and the `.catch` swallows it into zeroAddress. That printed "⚠ assign this
+        // minter" + "⚠ set a primary payee" on an edition that already had both — the same false
+        // "not assigned" bug as the show path, surviving here because only show got fixed in 2026-08-05.
         const [assignedMinter, payee, paused] = await Promise.all([
-            read(token, 'minter').catch(() => zeroAddress),
-            read(token, 'primaryPayee').catch(() => zeroAddress),
-            read(token, 'paused').catch(() => false),
+            readEdition(token, 'minter').catch(() => zeroAddress),
+            readEdition(token, 'primaryPayee').catch(() => zeroAddress),
+            readEdition(token, 'paused').catch(() => false),
         ]);
         const assigned = assignedMinter.toLowerCase() === minter.toLowerCase();
         console.log('');
@@ -1741,6 +2086,7 @@ export async function cmdMinterConfigure(address, flags) {
 export async function cmdMinterShow(address, flags) {
     const usage = 'abx minter show <token> [--token-id <n> (editions)] [--minter-contract 0x…]';
     const token = requireAddress(address, usage);
+    warnStrayFlags(flags, new Set(MINTER_SHOW_FLAGS), 'minter show');
     // 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.
@@ -1834,6 +2180,7 @@ export async function cmdMinterShow(address, flags) {
 export async function cmdMinterBuy(address, flags) {
     const usage = 'abx minter buy <token> [--to 0x…] [--token-id <n> --quantity <n> (editions)] [--minter-contract 0x…] [--sign|--unsigned]';
     const token = requireAddress(address, usage);
+    warnStrayFlags(flags, new Set(MINTER_BUY_FLAGS), 'minter buy');
     const publicClient = makePublicClient({ chainKey: CHAIN });
     const kind = await detectTokenKind(publicClient, token);
     if (kind.isEdition) {
@@ -1849,15 +2196,17 @@ export async function cmdMinterBuy(address, flags) {
             throw new Error(`no sale configured for ${token} #${tokenId} — run: abx minter configure ${token} --token-id ${tokenId} …`);
         const isEth = sale.paymentToken === zeroAddress;
         const to = flags.to && flags.to !== 'true' ? flags.to : undefined;
-        // Payment math: price × quantity, computed ONCE and shown in the confirm/dry-run readout below
-        // (via runMinterWrite → gatedSend's own preview) — the exact ETH the tx attaches.
-        const value = isEth ? sale.price * quantity : 0n;
+        // Payment math AND the buyer's terms bound both come off `sale` inside the SDK op (one
+        // computation of price × quantity, for the attached ETH and for `maxTotalPrice`) — the terms
+        // just read are the terms the tx commits to, so a mid-flight `configure` reverts instead of
+        // spending more. Shown in the confirm/dry-run readout below (runMinterWrite → gatedSend).
+        const total = sale.price * quantity;
         if (!isEth) {
-            console.log(yellow(`  ERC-20 sale: the buyer must have approved ${minter} to spend ${sale.price * quantity} units of ${sale.paymentToken} first (else the tx reverts).`));
+            console.log(yellow(`  ERC-20 sale: the buyer must have approved ${minter} to spend ${total} units of ${sale.paymentToken} first (else the tx reverts).`));
         }
         console.log(dim(`  buying ${quantity} cop${quantity === 1n ? 'y' : 'ies'} of #${tokenId}${to ? ` → ${to}` : ' → signer'} for ` +
-            `${isEth ? `${formatEther(value)} ETH (${formatEther(sale.price)} × ${quantity})` : `${value} units (${sale.price} × ${quantity})`}`));
-        await runMinterWrite(preparePurchase1155({ minter, token, tokenId, quantity, to, value, chainId: chainId() }), flags);
+            `${isEth ? `${formatEther(total)} ETH (${formatEther(sale.price)} × ${quantity})` : `${total} units (${sale.price} × ${quantity})`}`));
+        await runMinterWrite(preparePurchase1155({ minter, token, tokenId, quantity, sale, to, chainId: chainId() }), flags);
         console.log(dim(`  next: \`abx refresh ${token}\` so marketplaces pick up the change.`));
         return;
     }
@@ -1872,12 +2221,13 @@ export async function cmdMinterBuy(address, flags) {
         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);
+    // The terms just read go into the tx as the buyer's bound (SDK op derives value + maxPrice from
+    // `sale`), so an owner who re-`configure`s mid-flight gets a revert, not the buyer's allowance.
+    await runMinterWrite(preparePurchase({ minter, token, sale, to, chainId: chainId() }), flags);
     console.log(dim(`  next: \`abx refresh ${token}\` so marketplaces pick up the new token.`));
 }
 // ── PostParam schemas, after deploy ──────────────────────────────────────────