@artblocks/abx-cli 0.1.0-alpha.13 → 0.1.0-alpha.15

package/dist/ownerops.js

@@ -6,18 +6,18 @@
  * 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, prepareSetParamSchema, prepareMulticall, prepareRetireParam, readParamSchema, PARAM_TYPES, 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, prepareSetTransferValidator, prepareTransfer, prepareTransferOwnership, readCreatorTokenStatus, resolveRecommendedTransferValidator, RECOMMENDED_TRANSFER_VALIDATOR, KNOWN_CHAIN_KEYS, resolveChain, resolveRpcUrl, redactRpcUrl, DEFAULT_CHAIN_KEY, stageContent, encodeTag, METADATA_FIELD as F, METADATA_REPRESENTATION as R, } from '@artblocks/abx-sdk';
 import { SelfHostIndexer } from '@artblocks/abx-indexer';
 import { encodeScalarParam, encodeTag as encodeTagSdk, isAccepted, prepareConfigureTokenParam, prepareConfigureTokenParamData, prepareSetContractParam, prepareSetContractParamData, seriesCodeAbi, } from '@artblocks/abx-sdk';
-import { paramsKeysIsLiteral, paramsKeysNudge, readParamsKeys, PARAMS_KEYS } 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';
@@ -34,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
@@ -240,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} …). ` +
@@ -254,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);
         }
@@ -285,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.
@@ -551,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' } });
@@ -575,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.)'));
@@ -648,6 +661,112 @@ export async function cmdSetRoyalty(address, flags) {
     }
     await runWrite(contract, prepareSetRoyalty({ contract, receiver, bps, chainId: chainId() }), flags, owner);
 }
+// ── ERC-721C (creator token) — the transfer-validator surface ─────────────────
+// Enrollment is a DEPLOY-TIME decision (`--721c` on the deploy commands) and permanent in both
+// directions: an unenrolled token can never gain a validator, an enrolled one never sheds the
+// standard. Within an enrolled token the owner re-points or suspends (zero) the validator freely.
+/** The chain keys the manifest recommends a transfer validator for — for refusal messages. */
+function chainsWithRecommendedValidator() {
+    const ids = new Set(Object.keys(RECOMMENDED_TRANSFER_VALIDATOR).map(Number));
+    return KNOWN_CHAIN_KEYS.filter((k) => ids.has(resolveChain(k).id)).join(', ');
+}
+/**
+ * Parse a transfer-validator choice — the shared grammar of the deploy flag (`--721c`) and the
+ * owner op (`abx set-transfer-validator`):
+ *   - `recommended` (or a bare `--721c`) → the per-chain recommended validator, refusing on a
+ *     chain the manifest has no entry for (naming the chains that do — never guess one);
+ *   - a `0x…` address → checksum-validated (EIP-55) and returned as its canonical form;
+ *   - `none`/zero → `allowNone` decides: the owner op suspends with it; the DEPLOY flag refuses
+ *     it (a zero validator at deploy never enrolls — that is already the default, so someone
+ *     passing it either wants plain ERC-721 (drop the flag) or mistakenly believes "enrolled but
+ *     suspended" is a deploy-time state — it isn't).
+ * Pure (no RPC) — callers do the has-code precheck themselves. Exported for the regression test.
+ */
+export function parseTransferValidatorValue(raw, opts) {
+    const s = raw.trim().toLowerCase();
+    if (s === 'true' || s === '' || s === 'recommended') {
+        const rec = resolveRecommendedTransferValidator(opts.chainId);
+        if (!rec) {
+            throw new Error(`no recommended transfer validator is known for '${opts.chainLabel}' (chainId ${opts.chainId}) — ` +
+                `chains with one: ${chainsWithRecommendedValidator() || '(none shipped)'}. ` +
+                `Pass an explicit validator address instead (it must be a deployed contract on this chain).`);
+        }
+        return rec;
+    }
+    if (s === 'none' || s === 'zero' || s === '0' || s === '0x0' || s === zeroAddress) {
+        if (opts.allowNone)
+            return zeroAddress;
+        throw new Error(`a zero transfer validator never enrolls — plain ERC-721 is already the default, so drop --721c. ` +
+            `("enrolled but suspended" is not a deploy-time state: enroll with a real validator, then suspend ` +
+            `with \`abx set-transfer-validator <address> none\`.)`);
+    }
+    const trimmed = raw.trim();
+    if (!/^0x[0-9a-fA-F]{40}$/.test(trimmed)) {
+        throw new Error(`transfer validator must be 'recommended'${opts.allowNone ? ", 'none'," : ''} or a 0x address (0x + 40 hex); got '${raw}'`);
+    }
+    // `isAddress` strict-validates the EIP-55 checksum of a mixed-case address (all-lowercase carries
+    // no checksum and passes); `getAddress` alone only NORMALIZES — it would silently accept a
+    // mis-cased paste, which is exactly the transposition this check exists to catch.
+    if (!isAddress(trimmed, { strict: true })) {
+        throw new Error(`transfer validator address failed its EIP-55 checksum: '${raw}' — paste it exactly (or all-lowercase).`);
+    }
+    return getAddress(trimmed);
+}
+/**
+ * `abx set-transfer-validator <address> <0x…|none|recommended>` — re-point an ENROLLED (ERC-721C)
+ * collection's transfer validator, or suspend enforcement with `none` (address(0); the token
+ * STAYS enrolled). Refuses up front, before any signing: a plain ERC-721 (enrollment is
+ * deploy-time-only — the contract would revert `NotCreatorToken()`), and a codeless validator
+ * (would revert `InvalidTransferValidator()`). Owner-only, any lane, guards `--dry-run`.
+ */
+export async function cmdSetTransferValidator(address, rest, flags) {
+    const usage = 'abx set-transfer-validator <address> <0x…|none|recommended> [--sign|--unsigned] [--dry-run]';
+    const contract = requireAddress(address, usage);
+    const [raw] = positionalArgs(rest);
+    if (!raw) {
+        console.error(`usage: ${usage}\n`);
+        process.exit(1);
+    }
+    const cid = chainId();
+    const validator = parseTransferValidatorValue(raw, { chainId: cid, chainLabel: CHAIN, allowNone: true });
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    // Enrollment guard FIRST — a read, not a send. An unenrolled token would revert
+    // `NotCreatorToken()`; refuse with the real story instead of letting the chain say it in hex.
+    // (readCreatorTokenStatus is defensive, so check the contract exists first — a typo'd address
+    // must not read as "plain ERC-721".)
+    await assertContractExists(contract);
+    const status = await readCreatorTokenStatus(publicClient, contract);
+    if (!status.enrolled) {
+        throw new Error(`${contract} is a plain ERC-721 — 721C is a deploy-time decision, and this collection didn't enroll. ` +
+            `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.
+    if (validator !== zeroAddress) {
+        let code;
+        try {
+            code = await publicClient.getCode({ address: validator });
+        }
+        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') {
+            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})` : '') + `.`);
+        }
+    }
+    if (eqAddr(status.validator, validator)) {
+        console.log(dim(`  no change — the validator is already ${validator === zeroAddress ? 'suspended (0x0)' : validator}. Nothing sent.`));
+        return;
+    }
+    const label = (a) => (eqAddr(a, zeroAddress) ? 'suspended (0x0)' : a);
+    console.log(dim(`  transfer validator: ${label(status.validator)} → ${label(validator)}${validator === zeroAddress ? '  — transfers go unvalidated until one is set again (the token stays enrolled)' : ''}`));
+    const owner = await read(contract, 'owner');
+    await runWrite(contract, prepareSetTransferValidator({ contract, validator, chainId: cid }), flags, owner);
+}
 export function parseCompress(v) {
     const c = (v ?? 'none').toLowerCase();
     if (c === 'none' || c === 'fastlz' || c === 'gzip')
@@ -660,37 +779,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
@@ -845,6 +954,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`
@@ -859,6 +1017,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.)
@@ -988,9 +1147,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() });
@@ -1001,7 +1176,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 ───────────────────────────────────────────────────────────────
@@ -1273,25 +1448,6 @@ export async function cmdMinterBuy(address, flags) {
 // 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).
-/**
- * The `params.keys` companion write for a newly governed key, or null when none is needed.
- *
- * Pure so it can be tested without a chain: the decision (does this project even use the on-chain
- * generator? is the key already listed? does the new CSV still fit a literal bytes32?) is the part
- * that goes wrong, not the RPC call. `csv === null` means the project isn't on the on-chain URI lane
- * — a resolver reads schemas directly and needs no key list.
- */
-export function paramsKeysSyncOp(csv, key, contract, cid) {
-    const fixed = paramsKeysNudge(csv, key);
-    if (fixed === null)
-        return null;
-    // Past 31 chars the CSV can no longer ride as a literal bytes32 and takes the data path — the same
-    // rule `configure-param` and `deploy-code` apply, so all three agree on how a long list is stored.
-    const op = paramsKeysIsLiteral(fixed)
-        ? prepareSetContractParam({ contract, key: PARAMS_KEYS, value: encodeTagSdk(fixed), display: fixed, chainId: cid })
-        : prepareSetContractParamData({ contract, key: PARAMS_KEYS, data: toHexSdk(new TextEncoder().encode(fixed)), chainId: cid });
-    return { op, listed: fixed };
-}
 /** 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) {
@@ -1343,48 +1499,35 @@ export async function cmdSetSchema(address, flags) {
                 `\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.`);
         }
     }
-    const cid = chainId();
-    const ops = [
-        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: cid,
-            display: describeSchema(next),
-        }),
-    ];
-    // Keep `params.keys` in step, ATOMICALLY. On the on-chain URI lane the canonical generator builds
-    // tokenData from that CSV, so a key governed but not listed is silently omitted from every render —
-    // the schema exists, the collector can set it, and the art never sees it. `deploy-code` composes
-    // the list from `--schema` for exactly this reason; a schema added later has to do the same or
-    // `set-schema` is a second-class path that quietly half-works. `readParamsKeys` returns null when
-    // the project isn't on that lane (a resolver reads schemas directly), so this adds nothing there.
-    try {
-        const csv = await readParamsKeys(publicClient, contract);
-        const sync = paramsKeysSyncOp(csv, next.key, contract, cid);
-        if (sync) {
-            console.log(`    ${dim('params.keys')} ${dim('←')} ${sync.listed}  ${dim('(so the on-chain generator injects it; same tx)')}`);
-            ops.push(sync.op);
-        }
-    }
-    catch {
-        // Best-effort, never fails the command — but say so, because silence here looks like "no update
-        // was needed" when it actually means "we could not check".
-        console.log(`    ${C.yellow}⚠${C.reset} couldn't read params.keys — if this project is on the on-chain URI lane, verify it lists "${next.key}".`);
-    }
-    await runWrite(contract, ops.length > 1
-        ? prepareMulticall({ ops, summary: `Set the schema for "${next.key}" and list it in params.keys` })
-        : ops[0], flags, owner);
+    // 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) {