@artblocks/abx-cli 0.1.0-alpha.12 → 0.1.0-alpha.14

package/dist/ownerops.js

@@ -6,21 +6,22 @@
  * 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, resolveRpcUrl, redactRpcUrl, DEFAULT_CHAIN_KEY, stageContent, storeSupportsWriteContent, encodeTag, METADATA_FIELD as F, METADATA_REPRESENTATION as R, } from '@artblocks/abx-sdk';
+import { assertChainId, ensureChunkStore as sdkEnsureChunkStore, predictFixedPriceMinter, encodeReader, makePublicClient, makeWalletClient, oneOfOneImageAbi, seriesImageAbi, abxFixedPriceMinterAbi, deployFixedPriceMinter, prepareConfigureSale, preparePurchase, planChunks, planContentTxs, prepareLockContractField, prepareLockContractURI, prepareLockTokenField, prepareLockTokenURI, prepareMint, prepareSeriesMintMany, prepareSetMinter, prepareSetMaxInvocations, prepareSetPrimaryPayee, prepareSetPaused, prepareSetContractField, prepareSetContractURIBase, prepareSetContractURIOverride, prepareSetContractURIRenderer, prepareSetParamHooks, prepareSetParamSchema, prepareRetireParam, readParamSchema, PARAM_TYPES, prepareSetRoyalty, prepareSetTokenField, prepareSetTokenURIBase, prepareSetTokenURIOverride, prepareSetTokenURIRenderer, prepareTransfer, prepareTransferOwnership, resolveChain, resolveRpcUrl, redactRpcUrl, DEFAULT_CHAIN_KEY, stageContent, encodeTag, METADATA_FIELD as F, METADATA_REPRESENTATION as R, } from '@artblocks/abx-sdk';
 import { SelfHostIndexer } from '@artblocks/abx-indexer';
 import { encodeScalarParam, encodeTag as encodeTagSdk, isAccepted, prepareConfigureTokenParam, prepareConfigureTokenParamData, prepareSetContractParam, prepareSetContractParamData, seriesCodeAbi, } from '@artblocks/abx-sdk';
-import { paramsKeysIsLiteral, paramsKeysNudge, readParamsKeys } from './onchain-uri.js';
-import { DEP_RESOLUTION, parseDependencyRef, prepareLockDependencies, prepareRemoveLastDependency, prepareSetDependency, prepareSetDependencyRegistry, } from '@artblocks/abx-sdk';
+import { hasParamEnumeration } from './onchain-uri.js';
+import { decodeFieldRenderer, resolveGenerator, DEP_RESOLUTION, parseDependencyRef, prepareLockDependencies, prepareRemoveLastDependency, prepareSetDependency, prepareSetDependencyRegistry, } from '@artblocks/abx-sdk';
 import { contentTypeFromPath } from '@artblocks/abx-storage';
 import { toHex as toHexSdk } from 'viem';
 import { readFileSync } from 'node:fs';
 import { basename, resolve as resolvePath } from 'node:path';
 import { gzipSync } from 'node:zlib';
 import { formatEther, getAddress, isAddress, parseEther, toHex, zeroAddress } from 'viem';
-import { chunkStoreAddress, fixedPriceMinterAddress } from './config.js';
+import { fixedPriceMinterAddress } from './config.js';
 import { openWalletSession, signTx } from './signer.js';
 import { resolveRemote, serviceClient } from './remote.js';
 import { unknownFlags } from './flags.js';
+import { parseSchemaSpecs, describeSchema } from './schema.js';
 const CHAIN = process.env.ABX_CHAIN ?? DEFAULT_CHAIN_KEY; // base-sepolia default — MUST match main.ts/config.ts (a stale 'sepolia' here silently ran every owner-op on the wrong chain)
 // ── ANSI (local) ─────────────────────────────────────────────────────────────
 const C = { reset: '\x1b[0m', dim: '\x1b[2m', bold: '\x1b[1m', green: '\x1b[38;5;115m', yellow: '\x1b[38;5;221m' };
@@ -33,17 +34,28 @@ 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. See specs/protocol/data-plane.md.
-const COMPUTED_FIELD_KEYS = new Set(['artifacts', 'abx_provenance']);
+// 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.
+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"
-            : '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://…>`);
+            : 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`)"
+                : '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'
+                ? `\n  Set a param instead:\n    abx configure-param <address> <tokenId|-> <key> <value>\n  (or attach a FILE under your own key: abx attach <address> <yourkey> <ipfs://… | ar://… | https://…>)`
+                : ` To attach a file so it appears in the manifest, pick your OWN key:\n    abx attach <address> <yourkey> <ipfs://… | ar://… | https://…>`));
     }
 }
+/** Whether a value fits the literal `bytes32` lane of a raw contract-param write (printable ASCII,
+ *  ≤ 31 bytes). Anything longer takes the data path — one blob, its hash evented. */
+function fitsLiteralBytes32(value) {
+    return value.length <= 31 && /^[\x20-\x7e]+$/.test(value);
+}
 /** Flags `abx attach` recognizes — anything else warns (non-fatal), so a silent no-op flag surfaces. */
 const ATTACH_FLAGS = ['file', 'compress', 'collection', 'token', 'send', 'sign', 'unsigned', 'yes', 'dry-run', 'port', 'sign-url-file', 'remote'];
 /** Auto-detect the on-chain representation for an off-chain locator by its URI scheme. Returns null
@@ -239,8 +251,9 @@ export async function cmdConfigureParam(address, rest, flags) {
     }));
     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.
+    // well-known contract params like `display.gateway`. Schema-less keys only: a schema'd key closes
+    // the raw path on-chain (`SchemaGoverned`) and is per-token by design. No key is special here: a
+    // contract param is enumerated on-chain like any other and lands in tokenData for every token.
     if (tokenIdRaw === '-') {
         if (exists) {
             throw new Error(`"${key}" is schema-governed — it's a per-token PostParam (abx configure-param ${contract} <tokenId> ${key} …). ` +
@@ -253,9 +266,9 @@ export async function cmdConfigureParam(address, rest, flags) {
             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)) {
+        // Printable ASCII ≤ 31 chars rides as a literal readable bytes32; anything longer takes the
+        // data path (one blob, hash evented).
+        if (fitsLiteralBytes32(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);
         }
@@ -267,9 +280,9 @@ export async function cmdConfigureParam(address, rest, flags) {
     }
     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.`);
+        throw new Error(`no PostParam schema for "${key}" on ${contract}. Declare one — at deploy with ` +
+            `abx deploy-code … --schema ${key}:<Type>:<Auth>, or right now on the live contract with ` +
+            `abx set-schema ${contract} --schema ${key}:<Type>:<Auth>  (e.g. ${key}:HexColor:TokenOwner).`);
     }
     const typeName = ['Bool', 'Select', 'Uint256Range', 'Int256Range', 'DecimalRange', 'HexColor', 'Timestamp', 'String', 'Bytes'][paramTypeIdx];
     let sent;
@@ -284,22 +297,7 @@ export async function cmdConfigureParam(address, rest, flags) {
         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.
@@ -550,15 +548,29 @@ export async function cmdSetPrimaryPayee(address, flags) {
 // 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']);
+/**
+ * OpenSea's own chain slugs, keyed by ours. They are NOT our keys (`base-sepolia` is `base_sepolia`
+ * there) and not derivable from viem, so the map is unavoidable — but a chain missing from it must
+ * produce NO link rather than a wrong one, which is what `osChain ?? CHAIN` used to do.
+ *
+ * It previously listed only `sepolia` and `mainnet`, so the CLI's own DEFAULT chain (`base-sepolia`)
+ * fell through to the raw key: the refresh POST went to `/chain/base-sepolia/…` (a slug OpenSea does
+ * not know) and the printed link pointed at **mainnet** `opensea.io` for a testnet token. Same shape
+ * as the hardcoded explorer table that once sent every Base Sepolia link to Etherscan — hence
+ * `testnet` now comes from the chain registry instead of a second hand-maintained set.
+ */
+const OPENSEA_CHAIN = { 'base-sepolia': 'base_sepolia', sepolia: '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 chain = resolveChain(CHAIN);
+    const osChain = OPENSEA_CHAIN[CHAIN];
+    const explorer = chain.blockExplorers?.default?.url ?? '';
     const apiKey = process.env.OPENSEA_API_KEY;
-    if (apiKey) {
+    if (!osChain) {
+        console.log(dim(`  no OpenSea slug known for '${CHAIN}' — skipping the OpenSea refresh (a guessed slug 404s, and a guessed link would point at the wrong network).`));
+    }
+    else 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' } });
@@ -574,8 +586,10 @@ export async function cmdRefresh(address, flags) {
     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}`);
+    // `testnet` from the chain registry (viem), never a local set — that is the drift this bug was.
+    const osBase = chain.testnet ? 'https://testnets.opensea.io' : 'https://opensea.io';
+    if (osChain)
+        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.)'));
@@ -659,37 +673,27 @@ export function parseCompress(v) {
  * 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);
+    // The resolution logic lives in the SDK (`ensureChunkStore`) so an SDK integrator bootstraps
+    // identically instead of hand-rolling the "is this store capable?" guard — forget it and an
+    // incapable store fails deep inside a mint, after transactions have landed. The CLI keeps only the
+    // narration: the SDK reports progress through `onEvent` rather than printing.
     const publicClient = makePublicClient({ chainKey: CHAIN });
-    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;
+    return sdkEnsureChunkStore(publicClient, send, {
+        chainId: chainId(),
+        override,
+        onEvent: (e) => {
+            if (e.kind === 'stale')
+                console.log(yellow(`  configured chunk store ${e.address} is a stale deployment (no writeContent) — deploying a current one`));
+            else if (e.kind === 'canonical')
+                console.log(dim(`  using the canonical chunk store at its deterministic address ${e.address}`));
+            else if (e.kind === 'deploying')
+                console.log(dim('  deploying the canonical multi-chunk content store (AbxChunkStore) — CREATE2…'));
+            else {
+                console.log(`  ${green('✓')} chunk store ${e.address}`);
+                console.log(dim(`  not in the shipped manifest for ${CHAIN} — to reuse it set ABX_CHUNK_STORE=${e.address} (or add it to packages/sdk/src/deployments.ts)`));
+            }
+        },
+    });
 }
 /**
  * The hot-lane staging signer: the env key signs + broadcasts each chunk-store write. Built
@@ -844,6 +848,55 @@ export async function stageImageFieldsBatch(imagePaths, compress, send, storeOve
     }
     return { fields, store };
 }
+// ── the generator repoint guard ───────────────────────────────────────────────
+// The canonical AbxGenerator reads a token's param surface FROM CHAIN (`tokenParamKeys` /
+// `contractParamKeys`). A LEGACY implementation — deployed before enumeration shipped — has neither
+// getter, so the generator finds nothing: every configured param vanishes from tokenData and from
+// the live view, silently, behind a tokenURI that still looks perfectly healthy. That is the exact
+// failure class this toolkit refuses rather than warns about, so pointing a legacy token at the
+// current generator is REFUSED. (Repointing the metadata RENDERER is safe and unguarded: a v4
+// renderer on a legacy token just emits no params block.)
+/** The field-renderer address a `--value` names: the canonical `abi.encode(address)` (32 bytes),
+ *  or a bare 20-byte address. Null when it is neither. */
+function fieldRendererTarget(value) {
+    const hex = value.trim();
+    if (!/^0x[0-9a-fA-F]*$/.test(hex))
+        return null;
+    if (hex.length === 42)
+        return getAddress(hex);
+    if (hex.length !== 66)
+        return null;
+    try {
+        return decodeFieldRenderer(hex);
+    }
+    catch {
+        return null;
+    }
+}
+export async function assertGeneratorRepointable(contract, field, flags, 
+/** Injected for tests; the real probe is one eth_call. */
+probe = (c) => hasParamEnumeration(makePublicClient({ chainKey: CHAIN }), c)) {
+    if (flags.representation !== R.renderer || !flags.value || flags.value === 'true')
+        return;
+    const target = fieldRendererTarget(flags.value);
+    const generator = resolveGenerator(chainId());
+    // Only the CANONICAL generator is guarded — any other field renderer is the creator's own contract
+    // and none of our business.
+    if (!target || !generator || target.toLowerCase() !== generator.toLowerCase())
+        return;
+    // The `owner` read has already succeeded by the time this runs, so the RPC is proven reachable:
+    // a failing probe here means the getter is absent, not that the node is down.
+    if (await probe(contract))
+        return;
+    throw new Error(`refusing to point ${field} at the canonical generator ${generator} — ${contract} does not expose the param\n` +
+        `  enumeration surface (tokenParamKeys/contractParamKeys), so it is a LEGACY implementation. The current\n` +
+        `  generator reads params FROM CHAIN, so on this token it would read NOTHING: every configured param would\n` +
+        `  silently disappear from tokenData, the live view, and every render — with a tokenURI that still looks fine.\n\n` +
+        `  Two honest options:\n` +
+        `    • stay on the generator this project already uses (pass that address as --value; it reads the project's\n` +
+        `      params.keys list, which is how it has always worked here), or\n` +
+        `    • redeploy the project with the current \`abx deploy-code\` — new projects enumerate on-chain and need no list.`);
+}
 // ── 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`
@@ -858,6 +911,7 @@ export async function cmdSetField(address, flags) {
     const collection = !!flags.collection;
     const lane = laneFromFlags(flags);
     const owner = await read(contract, 'owner');
+    await assertGeneratorRepointable(contract, field, flags); // legacy impl + the current generator = params silently invisible
     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.)
@@ -987,9 +1041,25 @@ export async function cmdAttach(rest, flags) {
             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.`));
+    // Where it surfaces. This used to be one dim line, and it read as a footnote rather than as a
+    // dependency: an integrator attached five audio stems to a fully-on-chain token, paid to store
+    // them, and found `tokenURI` listed none of them — "paid for, stored on-chain, and invisible".
+    // The on-chain renderer deliberately omits locator-represented artifacts (they duplicate no
+    // on-chain type information — see specs/protocol/data-plane.md), so the artifacts manifest comes
+    // from a RESOLVER. When the project has no resolver baked in, that is not a footnote, it is the
+    // difference between a feature working and not existing, so say it as a warning.
+    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.`));
+    }
+    else {
+        console.log(yellow('  ⚠ ') +
+            `this project resolves ON-CHAIN (no resolver base baked in), and the on-chain document carries reserved fields plus the computed ${bold('abx_params')} block only — ` +
+            `so ${bold(key)} will NOT appear in ${bold('tokenURI')}. The bytes are stored and provable, but nothing surfaces them to a marketplace or wallet. ` +
+            dim('(Configured params DO appear on-chain — attachments are the surface that needs a resolver.)'));
+        console.log(dim(`    to make attached artifacts visible, point the project at a resolver (${bold('abx deploy-resolver')}, or a managed one via ${bold('abx add <addr> --remote <name>')}) — it serves the listing at ${artifactsPath}.`));
+    }
     const buildTx = () => collection
         ? prepareSetContractField({ contract, field: key, representation, value: toHex(uri), chainId: chainId() })
         : prepareSetTokenField({ contract, tokenId: BigInt(flags.token ?? '0'), field: key, representation, value: toHex(uri), chainId: chainId() });
@@ -1000,7 +1070,7 @@ export async function cmdAttach(rest, flags) {
             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`));
+            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`));
     }
 }
 // ── lock-field ───────────────────────────────────────────────────────────────
@@ -1266,4 +1336,129 @@ export async function cmdMinterBuy(address, flags) {
     await runMinterWrite(preparePurchase({ minter, token, to, value, chainId: chainId() }), flags);
     console.log(dim(`  next: \`abx refresh ${token}\` so marketplaces pick up the new token.`));
 }
+// ── PostParam schemas, after deploy ──────────────────────────────────────────
+// `setParamSchema` is owner-gated with no deploy-time restriction, so a project's param surface was
+// never actually frozen at deploy — the toolkit just had no way to reach it, which read to creators
+// as a protocol limitation ("we must guess every param up front, or redeploy and lose the address").
+// Two commands close that: `set-schema` (attach or replace one key) and `retire-param` (stop all
+// further writes, the closest thing to a delete the protocol has).
+/** Values already stored under a key can be stranded by a schema change — the contract does NOT
+ *  re-validate them. Compare old vs new and name what would break, so the guard can refuse. */
+export function strandingRisks(before, after) {
+    const risks = [];
+    const typeName = (i) => PARAM_TYPES[i] ?? String(i);
+    if (before.paramType !== after.paramType) {
+        risks.push(`type ${typeName(before.paramType)} → ${typeName(after.paramType)} (a stored value keeps its old encoding)`);
+    }
+    const dropped = before.selectOptions.filter((o) => !after.selectOptions.includes(o));
+    if (before.selectOptions.length && dropped.length) {
+        risks.push(`Select option(s) removed: ${dropped.join(', ')} (a token already set to one keeps it)`);
+    }
+    // Narrowing either bound can strand a value that sat inside the old range.
+    const asInt = (h) => (PARAM_TYPES[after.paramType] === 'Int256Range' ? BigInt.asIntN(256, BigInt(h)) : BigInt(h));
+    if (before.min !== after.min && asInt(after.min) > asInt(before.min))
+        risks.push(`min raised (${asInt(before.min)} → ${asInt(after.min)})`);
+    if (before.max !== after.max && asInt(before.max) !== 0n && asInt(after.max) < asInt(before.max)) {
+        risks.push(`max lowered (${asInt(before.max)} → ${asInt(after.max)})`);
+    }
+    return risks;
+}
+/** `abx set-schema <address> --schema key:Type:Auth[:lock=<when>]` — attach or replace ONE key's
+ *  on-chain schema, any time in a project's life. Owner-only. */
+export async function cmdSetSchema(address, flags) {
+    const usage = 'abx set-schema <address> --schema key:Type:Auth[:lock=<when>] [--force] [--dry-run] [--sign|--unsigned]';
+    const contract = requireAddress(address, usage);
+    const specs = parseSchemaSpecs(flags.schema);
+    if (specs.length !== 1) {
+        console.error(`usage: ${usage}\n\n  One key per call — a schema write is a full-row upsert, so batching them hides which one changed.\n`);
+        process.exit(1);
+    }
+    const next = specs[0];
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    const owner = await read(contract, 'owner');
+    const before = await readParamSchema(publicClient, contract, next.key);
+    if (!before.exists) {
+        console.log(`  ${next.key} ${dim('— new governed key')} ${describeSchema(next)}`);
+    }
+    else {
+        // The upsert hazard: this is a FULL row write, so anything not restated is overwritten. Show
+        // both sides, and refuse a change that could strand values unless the caller insists.
+        console.log(`  ${next.key} ${dim('— replacing an existing schema')}`);
+        console.log(`    ${dim('before')} ${describeSchema(onChainToParsed(next.key, before))}`);
+        console.log(`    ${dim('after ')} ${describeSchema(next)}`);
+        const risks = strandingRisks(before, next);
+        if (risks.length && flags.force === undefined) {
+            throw new Error(`refusing to replace "${next.key}" — this change can strand values already stored under it:\n` +
+                risks.map((r) => `    • ${r}`).join('\n') +
+                `\n\n  The contract does NOT re-validate stored values against a new schema, so affected tokens would keep\n` +
+                `  values their own schema no longer allows. Re-run with --force if that is what you intend.`);
+        }
+        // With --force, say what is being overridden. Silently applying a value-stranding change is the
+        // one outcome worse than refusing it: the operator gets no record of which tokens they may have
+        // just invalidated, and neither does anyone reading the terminal afterwards.
+        if (risks.length) {
+            console.log(`    ${C.yellow}⚠${C.reset} ${bold('--force')} — applying a change that can strand stored values:`);
+            for (const r of risks)
+                console.log(`        • ${r}`);
+            console.log(dim(`        any token already holding a value for "${next.key}" keeps it, now outside what its schema allows.`));
+        }
+        if (before.lockAfter && !next.lockAfter) {
+            console.log(`    ${C.yellow}⚠${C.reset} the existing lock (${new Date(before.lockAfter * 1000).toISOString().slice(0, 19)}Z) is being REMOVED — restate it with :lock= to keep it.`);
+        }
+    }
+    // ONE op. A schema write used to need a `params.keys` companion write in the same tx to keep the
+    // on-chain generator's key list in step; the generator now enumerates params from the token
+    // itself, so the schema write is the whole change.
+    await runWrite(contract, prepareSetParamSchema({
+        contract,
+        key: next.key,
+        paramType: next.paramType,
+        auth: next.auth,
+        authAddress: next.authAddress,
+        lockAfter: next.lockAfter,
+        min: next.min,
+        max: next.max,
+        selectOptions: next.selectOptions,
+        chainId: chainId(),
+        display: describeSchema(next),
+    }), flags, owner);
+}
+/** Render an on-chain schema through the same formatter the CLI uses for a parsed one. */
+function onChainToParsed(key, s) {
+    return {
+        key,
+        paramType: s.paramType,
+        auth: s.auth,
+        authAddress: s.authAddress,
+        lockAfter: s.lockAfter,
+        min: s.min,
+        max: s.max,
+        selectOptions: s.selectOptions,
+    };
+}
+/** `abx retire-param <address> <key>` — permanently stop further writes to a PostParam. */
+export async function cmdRetireParam(address, rest, flags) {
+    const usage = 'abx retire-param <address> <key> [--dry-run] [--sign|--unsigned]';
+    const contract = requireAddress(address, usage);
+    const [key] = positionalArgs(rest);
+    if (!key) {
+        console.error(`usage: ${usage}\n`);
+        process.exit(1);
+    }
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    const owner = await read(contract, 'owner');
+    const current = await readParamSchema(publicClient, contract, key);
+    if (!current.exists)
+        throw new Error(`no PostParam schema for "${key}" on ${contract} — nothing to retire.`);
+    if (current.lockAfter && current.lockAfter < Math.floor(Date.now() / 1000)) {
+        console.log(`  ${C.green}✓${C.reset} "${key}" is already retired (locked ${new Date(current.lockAfter * 1000).toISOString().slice(0, 19)}Z). Nothing to do.`);
+        return;
+    }
+    console.log(`  ${key} ${dim(describeSchema(onChainToParsed(key, current)))}`);
+    console.log(`    ${dim('after this: every write reverts ParamLockExpired — permanently, with no way back.')}`);
+    console.log(`    ${dim('the schema stays (a key can never be un-governed), and any value ALREADY stored stays and keeps serving.')}`);
+    // Read-modify-write: carry every field forward and change only the lock. Composing a fresh schema
+    // here would silently reset type/auth/bounds/options — the upsert clobber this command exists to avoid.
+    await runWrite(contract, prepareRetireParam({ contract, key, current, chainId: chainId() }), flags, owner);
+}
 //# sourceMappingURL=ownerops.js.map