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

package/dist/ownerops.d.ts

@@ -6,7 +6,7 @@
  * 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 { planContentTxs, type OnChainParamSchema, type SendStagingTx, type Address, type OnChainFieldInput } from '@artblocks/abx-sdk';
+import { planContentTxs, type OnChainParamSchema, type SendStagingTx, type Address, type Hex, type OnChainFieldInput } from '@artblocks/abx-sdk';
 import { type Lane, type WalletSession } from './signer.js';
 import { type ParsedSchema } from './schema.js';
 type Flags = Record<string, string | undefined>;
@@ -20,6 +20,33 @@ export declare function laneFromFlags(flags: Flags): Lane;
 /** Throw a clear, actionable error when `address` has no contract on the active chain — the common
  *  cause of an owner-op's raw `returned no data ("0x")`. No-op when code is present or unknowable. */
 export declare function assertContractExists(address: Address): Promise<void>;
+/**
+ * `abx configure-param <address> <tokenId> <key> <value>` — set a schema-governed
+ * PostParam through the typed path, any lane. Reads the key's on-chain schema first
+ * and canonically ENCODES the human input per its type (`#rrggbb`, decimals ×1e10,
+ * Select by label, …); `String`/`Bytes` schemas take the value as UTF-8 (or
+ * `--file <path>` for bytes) via the data path. The signer must satisfy the schema's
+ * auth (Artist = contract owner, TokenOwner — delegate.xyz honored — or the named
+ * address); the chain enforces it either way.
+ */
+/** Positional args only — drops `--flags` AND the single token each value-taking flag consumes
+ *  (mirrors parseFlags). `rest.filter(r => !r.startsWith('--'))` was NOT enough: a flag's VALUE
+ *  (e.g. the URL after `--remote`, or the path after `--file`) isn't `--`-prefixed, so it leaked
+ *  into the positional value (`configure-param … #ff0000 --remote http://h` → value "#ff0000 http://h"). */
+/**
+ * Encode a command-line value for a payload-typed param (`String` / `Bytes`).
+ *
+ * `String` is UTF-8 text — the literal characters are the value, which is what a user means.
+ *
+ * `Bytes` is NOT text, and the old code UTF-8'd whatever string it was handed. A tester passed
+ * base64 (the encoding the params docs mention — which describes the *canonical decode* a program
+ * receives, not what you type here), and 128 packed bytes were stored as 172 bytes of base64 ASCII.
+ * 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.
+ */
+export declare function encodePayloadParam(typeName: 'String' | 'Bytes', valueInput: string, key: string): Hex;
 export declare function cmdConfigureParam(address: string | undefined, rest: string[], flags: Flags): Promise<void>;
 declare const HOOK_ROLES: readonly ["configure", "augment", "transfer"];
 type HookRole = (typeof HOOK_ROLES)[number];
@@ -195,6 +222,20 @@ export declare function cmdSetField(address: string | undefined, flags: Flags):
  *   - computed keys (`artifacts`, `abx_provenance`) are refused — they're the manifest, not inputs.
  * Scope: token (`--token`, default 0) or `--collection`. Any signing lane. Owner-only.
  */
+/**
+ * Attach one or more artifacts. Several `<key> <uri>` pairs in one invocation become **one
+ * transaction**.
+ *
+ * That batching is a safety fix, not a convenience (backlog B20). The CLI's most-documented flow —
+ * mint, then attach each artifact, then refresh — sent one transaction per step with no all-or-nothing
+ * boundary, so a failure partway through left a permanently half-written token that cannot be
+ * un-minted. An integrator hit exactly this and folded 8 operations into 1 transaction using the SDK's
+ * `batchOps`, which the CLI already shipped and did not use. Now it does: N pairs are one
+ * `multicall`, so either every artifact lands or none does.
+ *
+ * A single pair passes through `batchOps` untouched, so the one-artifact case sends the identical
+ * transaction it always did.
+ */
 export declare function cmdAttach(rest: string[], flags: Flags): Promise<void>;
 export declare function cmdLockField(address: string | undefined, flags: Flags): Promise<void>;
 /** Point a token's URI resolution at an on-chain renderer (or clear it with `--off`).

package/dist/ownerops.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ownerops.d.ts","sourceRoot":"","sources":["../src/ownerops.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ownerops.d.ts","sourceRoot":"","sources":["../src/ownerops.ts"],"names":[],"mappings":"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"}

package/dist/ownerops.js

@@ -6,7 +6,7 @@
  * served state reflects the change. The agent picks the lane; the human only
  * approves (wallet lane) or it's the env key (hot lane).
  */
-import { assertChainId, ensureChunkStore as sdkEnsureChunkStore, predictFixedPriceMinter, encodeReader, makePublicClient, makeWalletClient, oneOfOneImageAbi, seriesImageAbi, abxFixedPriceMinterAbi, deployFixedPriceMinter, prepareConfigureSale, preparePurchase, planChunks, planContentTxs, prepareLockContractField, prepareLockContractURI, prepareLockTokenField, prepareLockTokenURI, prepareMint, prepareSeriesMintMany, prepareSetMinter, prepareSetMaxInvocations, prepareSetPrimaryPayee, prepareSetPaused, prepareSetContractField, prepareSetContractURIBase, prepareSetContractURIOverride, prepareSetContractURIRenderer, prepareSetParamHooks, prepareSetParamSchema, prepareRetireParam, readParamSchema, PARAM_TYPES, prepareSetRoyalty, prepareSetTokenField, prepareSetTokenURIBase, prepareSetTokenURIOverride, prepareSetTokenURIRenderer, prepareSetTransferValidator, prepareTransfer, prepareTransferOwnership, readCreatorTokenStatus, resolveRecommendedTransferValidator, RECOMMENDED_TRANSFER_VALIDATOR, KNOWN_CHAIN_KEYS, resolveChain, resolveRpcUrl, redactRpcUrl, DEFAULT_CHAIN_KEY, stageContent, encodeTag, METADATA_FIELD as F, METADATA_REPRESENTATION as R, } from '@artblocks/abx-sdk';
+import { 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, batchOps, prepareSetTokenURIBase, prepareSetTokenURIOverride, prepareSetTokenURIRenderer, prepareSetTransferValidator, prepareTransfer, prepareTransferOwnership, readCreatorTokenStatus, resolveRecommendedTransferValidator, RECOMMENDED_TRANSFER_VALIDATOR, KNOWN_CHAIN_KEYS, resolveChain, resolveRpcUrl, redactRpcUrl, DEFAULT_CHAIN_KEY, stageContent, encodeTag, METADATA_FIELD as F, METADATA_REPRESENTATION as R, } from '@artblocks/abx-sdk';
 import { SelfHostIndexer } from '@artblocks/abx-indexer';
 import { encodeScalarParam, encodeTag as encodeTagSdk, isAccepted, prepareConfigureTokenParam, prepareConfigureTokenParamData, prepareSetContractParam, prepareSetContractParamData, seriesCodeAbi, } from '@artblocks/abx-sdk';
 import { hasParamEnumeration } from './onchain-uri.js';
@@ -16,11 +16,12 @@ 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 { decodeEventLog, formatEther, getAddress, isAddress, parseEther, toHex, zeroAddress } from 'viem';
 import { fixedPriceMinterAddress } from './config.js';
 import { openWalletSession, signTx } from './signer.js';
+import { withJson } from './jsonout.js';
 import { resolveRemote, serviceClient } from './remote.js';
-import { unknownFlags } from './flags.js';
+import { positionalArgs, unknownFlags } from './flags.js';
 import { parseSchemaSpecs, describeSchema } from './schema.js';
 const CHAIN = process.env.ABX_CHAIN ?? DEFAULT_CHAIN_KEY; // base-sepolia default — MUST match main.ts/config.ts (a stale 'sepolia' here silently ran every owner-op on the wrong chain)
 // ── ANSI (local) ─────────────────────────────────────────────────────────────
@@ -99,6 +100,15 @@ function requireFlag(flags, name, usage) {
 }
 /** Run a prepared write through the chosen lane, then re-index if the project is known.
  *  Returns whether anything was BROADCAST (false on the cold lane — the tx was only printed). */
+/**
+ * Every owner-op's send choke point. Returns the {@link SignResult} when a tx was broadcast, else
+ * `null` (dry run, or the cold lane which prints a tx instead of sending one).
+ *
+ * It used to return a bare boolean. It returns the result now because a caller sometimes needs the
+ * *receipt* — `abx mint --json` has to report which token id was actually minted, and the only
+ * authoritative answer is the Transfer log the mint emitted. Callers that only asked "did it send?"
+ * keep working: `null` is falsy, and a result object is truthy.
+ */
 async function runWrite(address, provider, flags, expectedSigner) {
     // --dry-run: preview the exact tx and send NOTHING. This is the shared choke point for every
     // owner-op, so --dry-run is uniform across them — it must never fall through to a real send just
@@ -113,7 +123,7 @@ async function runWrite(address, provider, flags, expectedSigner) {
         if (expectedSigner)
             console.log(`    ${dim('owner'.padEnd(12))} ${expectedSigner}`);
         console.log(dim(`\n  Re-run without --dry-run to send (lane: ${laneFromFlags(flags)}).\n`));
-        return false;
+        return null;
     }
     await assertChainId(CHAIN); // verify the RPC really is CHAIN before any irreversible write
     const result = await signTx(provider, {
@@ -125,9 +135,9 @@ async function runWrite(address, provider, flags, expectedSigner) {
         signUrlFile: flags['sign-url-file'],
     });
     if (!result)
-        return false; // cold lane — nothing broadcast
+        return null; // cold lane — nothing broadcast
     await reindexIfKnown(address, flags);
-    return true;
+    return result;
 }
 async function reindexIfKnown(address, flags) {
     const indexer = new SelfHostIndexer();
@@ -220,18 +230,35 @@ export async function assertContractExists(address) {
  *  (mirrors parseFlags). `rest.filter(r => !r.startsWith('--'))` was NOT enough: a flag's VALUE
  *  (e.g. the URL after `--remote`, or the path after `--file`) isn't `--`-prefixed, so it leaked
  *  into the positional value (`configure-param … #ff0000 --remote http://h` → value "#ff0000 http://h"). */
-function positionalArgs(args) {
-    const out = [];
-    for (let i = 0; i < args.length; i++) {
-        const a = args[i];
-        if (a.startsWith('--')) {
-            if (a.indexOf('=') === -1 && args[i + 1] && !args[i + 1].startsWith('--'))
-                i++; // this flag consumes the next token
-            continue;
+/**
+ * Encode a command-line value for a payload-typed param (`String` / `Bytes`).
+ *
+ * `String` is UTF-8 text — the literal characters are the value, which is what a user means.
+ *
+ * `Bytes` is NOT text, and the old code UTF-8'd whatever string it was handed. A tester passed
+ * base64 (the encoding the params docs mention — which describes the *canonical decode* a program
+ * receives, not what you type here), and 128 packed bytes were stored as 172 bytes of base64 ASCII.
+ * 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.
+ */
+export function encodePayloadParam(typeName, valueInput, key) {
+    if (typeName === 'String')
+        return toHexSdk(new TextEncoder().encode(valueInput));
+    const v = valueInput.trim();
+    if (/^0x[0-9a-fA-F]*$/.test(v)) {
+        if (v.length % 2 !== 0) {
+            throw new Error(`--${key} hex value has an odd number of digits (${v.length - 2}) — a byte is two hex digits.`);
         }
-        out.push(a);
+        return v;
     }
-    return out;
+    throw new Error(`"${key}" is a Bytes param, so its value must say what its bytes ARE — this looks like text.\n` +
+        `  Pass 0x-prefixed hex:   abx configure-param <addr> <id> ${key} 0x00112233…\n` +
+        `  Or the bytes in a file: abx configure-param <addr> <id> ${key} --file ./payload.bin\n` +
+        `  (Base64 is how a Bytes param is DECODED for your program — not how you write it here. ` +
+        `Storing base64 text would put ASCII on-chain where a renderer expects bytes, silently. ` +
+        `To store these literal characters on purpose, declare the key as String instead.)`);
 }
 export async function cmdConfigureParam(address, rest, flags) {
     const usage = 'abx configure-param <address> <tokenId|-> <key> <value> [--file <path>] [--remote [url]] [--sign|--unsigned]   (tokenId "-" = contract scope, schema-less keys only)';
@@ -289,7 +316,12 @@ export async function cmdConfigureParam(address, rest, flags) {
     if (typeName === 'String' || typeName === 'Bytes') {
         const data = flags.file
             ? toHexSdk(new Uint8Array(readFileSync(flags.file)))
-            : toHexSdk(new TextEncoder().encode(valueInput));
+            : encodePayloadParam(typeName, valueInput, key);
+        const bytes = (data.length - 2) / 2;
+        // Echo the DECODED byte count. The old code echoed the string's length, which is precisely how a
+        // wrong encoding announced itself and was missed: 128 packed bytes passed as base64 printed
+        // "172 bytes".
+        console.log(`  ${key} (${typeName}) ← ${bytes} bytes  ${dim(flags.file ? '(file contents, verbatim)' : typeName === 'Bytes' ? '(decoded from hex)' : '(UTF-8 text)')}`);
         sent = await runWrite(contract, prepareConfigureTokenParamData({ contract, tokenId, key, data, chainId: chainId() }), flags);
     }
     else {
@@ -465,24 +497,84 @@ export async function cmdLockDependencies(address, flags) {
 // it mints the next sequential token id (metadata = token id): bare (one), or `--count <n>`
 // (n in order). Owner or an authorized minter signs.
 export async function cmdMint(address, flags) {
-    const usage = 'abx mint <address> [--to 0x…] [--count <n>] [--sign|--unsigned]';
+    const usage = 'abx mint <address> [--to 0x…] [--count <n>] [--json] [--sign|--unsigned]';
     const contract = requireAddress(address, usage);
-    const owner = await read(contract, 'owner');
-    const to = flags.to ?? owner; // default: pre-mint to the admin
-    let tx;
-    if (flags.count !== undefined && flags.count !== 'true') {
-        const count = BigInt(flags.count);
-        console.log(dim(`  minting ${count} Series tokens in order → ${to}`));
-        tx = prepareSeriesMintMany({ contract, to, count, chainId: chainId() });
+    // `--json`: the TOKEN ID is the value a program came for, and it was previously only obtainable by
+    // regex-scraping coloured prose (B19). It is read from the mint's own Transfer logs rather than by
+    // re-reading `nextTokenId` afterwards — a concurrent mint would make that answer wrong, and a
+    // number that is usually right is worse than no number.
+    return withJson(flags, async () => {
+        const owner = await read(contract, 'owner');
+        const to = flags.to ?? owner; // default: pre-mint to the admin
+        let tx;
+        let count = 1n;
+        if (flags.count !== undefined && flags.count !== 'true') {
+            count = BigInt(flags.count);
+            console.log(dim(`  minting ${count} Series tokens in order → ${to}`));
+            tx = prepareSeriesMintMany({ contract, to, count, chainId: chainId() });
+        }
+        else {
+            // Bare mint: the `mint(address)` selector is shared by the 1/1 (token #0) and a
+            // Series (next sequential token) — one path serves both.
+            console.log(dim(`  minting token → ${to}${flags.to ? '' : ' (owner — pass --to for a buyer)'}`));
+            tx = prepareMint({ contract, to, chainId: chainId() });
+        }
+        const result = await runWrite(contract, tx, flags, owner);
+        const tokenIds = result ? await mintedTokenIds(contract, result.txHash) : [];
+        if (result && tokenIds.length) {
+            console.log(`  ${green('✓')} minted token${tokenIds.length > 1 ? 's' : ''} ${bold(tokenIds.map((t) => '#' + t).join(', '))} → ${to}`);
+        }
+        console.log(dim(`  next: \`abx refresh ${contract}\` so marketplaces pick up the new token.`));
+        return {
+            contract,
+            chainId: chainId(),
+            to,
+            // `sent: false` is the dry-run and cold-lane answer — an empty tokenIds with no explanation
+            // would read as a failed mint.
+            sent: !!result,
+            txHash: result?.txHash ?? null,
+            blockNumber: result ? String(result.blockNumber) : null,
+            tokenIds,
+            requestedCount: Number(count),
+        };
+    });
+}
+/**
+ * The token ids a mint actually created, decoded from its receipt's `Transfer(from=0x0)` logs.
+ *
+ * Authoritative by construction: the ids come from the transaction that minted them, so a
+ * `--count N` batch reports all N and a concurrent mint elsewhere cannot skew the answer. Returns
+ * `[]` rather than throwing if the receipt can't be read — a mint that landed on-chain must not be
+ * reported as failed because a follow-up read hiccuped.
+ */
+async function mintedTokenIds(contract, txHash) {
+    try {
+        const publicClient = makePublicClient({ chainKey: CHAIN });
+        const receipt = await publicClient.getTransactionReceipt({ hash: txHash });
+        const ids = [];
+        for (const log of receipt.logs) {
+            if (log.address.toLowerCase() !== contract.toLowerCase())
+                continue;
+            try {
+                const decoded = decodeEventLog({ abi: oneOfOneImageAbi, data: log.data, topics: log.topics });
+                if (decoded.eventName !== 'Transfer')
+                    continue;
+                const args = decoded.args;
+                if (args.from && args.from !== zeroAddress)
+                    continue; // a transfer, not a mint
+                const id = args.id ?? args.tokenId;
+                if (id !== undefined)
+                    ids.push(id.toString());
+            }
+            catch {
+                continue; // a log from another interface on the same contract
+            }
+        }
+        return ids.sort((a, b) => Number(BigInt(a) - BigInt(b)));
     }
-    else {
-        // Bare mint: the `mint(address)` selector is shared by the 1/1 (token #0) and a
-        // Series (next sequential token) — one path serves both.
-        console.log(dim(`  minting token → ${to}${flags.to ? '' : ' (owner — pass --to for a buyer)'}`));
-        tx = prepareMint({ contract, to, chainId: chainId() });
+    catch {
+        return [];
     }
-    await runWrite(contract, tx, flags, owner);
-    console.log(dim(`  next: \`abx refresh ${contract}\` so marketplaces pick up the new token.`));
 }
 // ── series owner ops (minter set · supply cap · primary payee) ────────────────
 // The multi-token knobs. All owner-only; each runs through the same signing lane +
@@ -1097,9 +1189,25 @@ export async function cmdSetField(address, flags) {
  *   - computed keys (`artifacts`, `abx_provenance`) are refused — they're the manifest, not inputs.
  * Scope: token (`--token`, default 0) or `--collection`. Any signing lane. Owner-only.
  */
+/**
+ * Attach one or more artifacts. Several `<key> <uri>` pairs in one invocation become **one
+ * transaction**.
+ *
+ * That batching is a safety fix, not a convenience (backlog B20). The CLI's most-documented flow —
+ * mint, then attach each artifact, then refresh — sent one transaction per step with no all-or-nothing
+ * boundary, so a failure partway through left a permanently half-written token that cannot be
+ * un-minted. An integrator hit exactly this and folded 8 operations into 1 transaction using the SDK's
+ * `batchOps`, which the CLI already shipped and did not use. Now it does: N pairs are one
+ * `multicall`, so either every artifact lands or none does.
+ *
+ * A single pair passes through `batchOps` untouched, so the one-artifact case sends the identical
+ * transaction it always did.
+ */
 export async function cmdAttach(rest, flags) {
-    const usage = 'abx attach <address> <key> <ipfs://… | ar://… | https://…>   [--file <path>] [--collection | --token 0] [--sign|--unsigned] [--dry-run]';
-    const [address, key, uri] = positionalArgs(rest);
+    const usage = 'abx attach <address> <key> <ipfs://… | ar://… | https://…> [<key> <uri> …]   [--file <path>] [--collection | --token 0] [--sign|--unsigned] [--dry-run]';
+    const [address, ...pairArgs] = positionalArgs(rest);
+    const key = pairArgs[0];
+    const uri = pairArgs[1];
     // Warn (never throw) on an unrecognized flag — a typo or a hopeful `--mime-type` otherwise no-ops
     // INVISIBLY (round-1: an agent passed `--mime-type` and it was silently swallowed). mimeType is
     // declared from the URL extension, not a flag; say so.
@@ -1134,19 +1242,44 @@ export async function cmdAttach(rest, flags) {
     // Locator path (the common case): auto-detect the representation, refuse an unrecognized scheme
     // loudly (never silently store a bad value) — fail fast before any RPC. Derive the declared
     // mimeType from the extension.
-    const representation = representationForLocator(uri);
-    if (!representation) {
-        throw new Error(`"${uri}" isn't a recognized file locator. Use ipfs://… (pinned/IPFS), ar://… (Arweave), or https://… . ` +
-            'To store literal text or raw bytes on-chain instead, use `abx set-field`.');
+    // Every `<key> <uri>` pair, validated BEFORE anything is sent — a batch that would revert partway
+    // is exactly what this command now exists to prevent, so a bad locator in pair 5 must stop pair 1.
+    if (pairArgs.length % 2 !== 0) {
+        throw new Error(`attach takes <key> <uri> PAIRS; got ${pairArgs.length} positional argument(s) after the address. ` +
+            `Last one seen: "${pairArgs[pairArgs.length - 1]}".`);
+    }
+    const pairs = [];
+    for (let i = 0; i < pairArgs.length; i += 2) {
+        const k = pairArgs[i];
+        const u = pairArgs[i + 1];
+        assertSettableField(k);
+        const rep = representationForLocator(u);
+        if (!rep) {
+            throw new Error(`"${u}" isn't a recognized file locator. Use ipfs://… (pinned/IPFS), ar://… (Arweave), or https://… . ` +
+                'To store literal text or raw bytes on-chain instead, use `abx set-field`.');
+        }
+        pairs.push({ key: k, uri: u, representation: rep, mimeType: contentTypeFromPath(u) });
+    }
+    // A key repeated within one batch would have the later write silently win — the same
+    // full-column-upsert hazard that bit `register` and `lock-field`. Refuse instead.
+    const dupes = pairs.map((p) => p.key).filter((k, i, a) => a.indexOf(k) !== i);
+    if (dupes.length) {
+        throw new Error(`the same key appears twice in one batch: ${[...new Set(dupes)].join(', ')}. ` +
+            'Each field holds ONE active value, so the last write would silently win — attach them separately if that is really what you want.');
     }
+    const representation = pairs[0].representation;
     const owner = await read(contract, 'owner');
-    const mimeType = contentTypeFromPath(uri);
-    if (mimeType === 'application/octet-stream') {
-        console.log(yellow('  ⚠ ') +
-            dim(`no file extension in "${uri.slice(0, 64)}" → declared type will be application/octet-stream. `) +
-            dim('Point the URI at the file itself (…/master.tiff, …/coa.pdf) so collectors get the right type.'));
+    for (const p of pairs) {
+        if (p.mimeType === 'application/octet-stream') {
+            console.log(yellow('  ⚠ ') +
+                dim(`no file extension in "${p.uri.slice(0, 64)}" → declared type will be application/octet-stream. `) +
+                dim('Point the URI at the file itself (…/master.tiff, …/coa.pdf) so collectors get the right type.'));
+        }
+    }
+    const mimeType = pairs[0].mimeType;
+    for (const p of pairs) {
+        console.log(`  attaching ${bold(p.key)} ${dim(`(${p.mimeType}, ${p.representation})`)} to ${scope}: ${dim(p.uri)}`);
     }
-    console.log(`  attaching ${bold(key)} ${dim(`(${mimeType}, ${representation})`)} to ${scope}: ${dim(uri)}`);
     // Where it surfaces. This used to be one dim line, and it read as a footnote rather than as a
     // dependency: an integrator attached five audio stems to a fully-on-chain token, paid to store
     // them, and found `tokenURI` listed none of them — "paid for, stored on-chain, and invisible".
@@ -1157,33 +1290,85 @@ export async function cmdAttach(rest, flags) {
     const uriBase = await read(contract, 'tokenURIBase').catch(() => '');
     const artifactsPath = `/t/${chainId()}/${contract}/${flags.token ?? '0'}`;
     if (uriBase && uriBase.trim() !== '') {
-        console.log(dim(`    → listed in this project's resolver artifacts (${artifactsPath} and /data/${key}); a bare on-chain tokenURI carries reserved fields plus abx_params only.`));
+        console.log(dim(`    → listed in this project's resolver artifacts (${artifactsPath} and /data/<key>); a bare on-chain tokenURI carries reserved fields plus abx_params only.`));
     }
     else {
         console.log(yellow('  ⚠ ') +
             `this project resolves ON-CHAIN (no resolver base baked in), and the on-chain document carries reserved fields plus the computed ${bold('abx_params')} block only — ` +
-            `so ${bold(key)} will NOT appear in ${bold('tokenURI')}. The bytes are stored and provable, but nothing surfaces them to a marketplace or wallet. ` +
+            `so ${pairs.map((p) => bold(p.key)).join(', ')} will NOT appear in ${bold('tokenURI')}. The bytes are stored and provable, but nothing surfaces them to a marketplace or wallet. ` +
             dim('(Configured params DO appear on-chain — attachments are the surface that needs a resolver.)'));
         console.log(dim(`    to make attached artifacts visible, point the project at a resolver (${bold('abx deploy-resolver')}, or a managed one via ${bold('abx add <addr> --remote <name>')}) — it serves the listing at ${artifactsPath}.`));
     }
-    const buildTx = () => collection
-        ? prepareSetContractField({ contract, field: key, representation, value: toHex(uri), chainId: chainId() })
-        : prepareSetTokenField({ contract, tokenId: BigInt(flags.token ?? '0'), field: key, representation, value: toHex(uri), chainId: chainId() });
-    const sent = await runWrite(contract, buildTx(), flags, owner);
+    // ONE transaction for the whole set. `batchOps` folds a same-target run into a `multicall` and
+    // passes a lone op through untouched, so a single attach is byte-identical to before.
+    const ops = pairs.map((p) => collection
+        ? prepareSetContractField({ contract, field: p.key, representation: p.representation, value: toHex(p.uri), chainId: chainId() })
+        : prepareSetTokenField({ contract, tokenId: BigInt(flags.token ?? '0'), field: p.key, representation: p.representation, value: toHex(p.uri), chainId: chainId() }));
+    const batched = batchOps(ops);
+    if (batched.length !== 1) {
+        // Defensive: every op here targets the same contract and carries no value, so batchOps must
+        // return exactly one tx. If that ever changes, fail loudly rather than send a partial set.
+        throw new Error(`attach expected to batch ${ops.length} op(s) into one transaction, got ${batched.length}`);
+    }
+    if (pairs.length > 1) {
+        console.log(dim(`  ${pairs.length} artifacts → ONE transaction (all-or-nothing: a revert lands none of them, so no half-written token).`));
+    }
+    const sent = await runWrite(contract, batched[0], flags, owner);
     if (sent) {
         const id = flags.token ?? '0';
-        console.log(`  ${green('✓')} attached — ${bold(key)} joins ${scope}'s ${bold('artifacts')} manifest (stored on-chain, anchored).\n` +
+        const names = pairs.map((p) => bold(p.key)).join(', ');
+        console.log(`  ${green('✓')} attached — ${names} join${pairs.length > 1 ? '' : 's'} ${scope}'s ${bold('artifacts')} manifest (stored on-chain, anchored).\n` +
             dim(`    verify (a resolver serves the complete listing): `) +
-            `curl <your-resolver>/t/${chainId()}/${contract}/${id}` +
-            dim(`  ${collection ? '' : `→ artifacts[].key "${key}"; /data/${key} fetches it`}\n`) +
+            `abx tokenuri ${contract}${id === '0' ? '' : ` --token ${id}`} --fetch` +
+            dim(`  ${collection ? '' : `→ artifacts[].key ${pairs.map((p) => `"${p.key}"`).join(', ')}; /data/<key> fetches each`}\n`) +
             dim(`    (The complete file listing is a resolver surface — the bare on-chain tokenURI enumerates reserved fields plus abx_params. Params never need a resolver; attachments do.)\n`));
     }
 }
 // ── lock-field ───────────────────────────────────────────────────────────────
+/**
+ * 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
+ * `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
+ * 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.
+ */
+async function refuseIfParamKey(contract, field) {
+    let exists = false;
+    try {
+        const schema = (await makePublicClient({ chainKey: CHAIN }).readContract({
+            address: contract,
+            abi: seriesCodeAbi,
+            functionName: 'paramSchema',
+            args: [encodeTagSdk(field)],
+        }));
+        exists = !!schema[0];
+    }
+    catch {
+        // No param surface at all (a 1/1 or plain Series) — nothing to confuse the name with.
+        return;
+    }
+    if (!exists)
+        return;
+    throw new Error(`"${field}" is a declared PostParam key on ${contract}, and lock-field does NOT lock params — ` +
+        `it locks the metadata FIELD of the same name. They are separate namespaces, so this would have ` +
+        `reported "permanent" while configure-param stayed free to overwrite the value.\n` +
+        `  To weld the param, lock its schema instead:\n` +
+        `    abx set-schema ${contract} --schema ${field}:<Type>:<Auth>:lock=now\n` +
+        `  (after that every configure-param on "${field}" reverts ParamLockExpired — check with ` +
+        `\`abx inspect ${contract}\`.)\n` +
+        `  If you really did mean the metadata field "${field}" and not the param, re-run with --force-field.`);
+}
 export async function cmdLockField(address, flags) {
     const contract = requireAddress(address, 'abx lock-field <address> --field <name> [--collection | --token 0] [--sign|--unsigned]');
     const field = requireFlag(flags, 'field', 'abx lock-field <address> --field <name>');
     const collection = !!flags.collection;
+    // The metadata field and a same-named param are different things; only an explicit --force-field
+    // says "yes, I mean the field". See refuseIfParamKey.
+    if (flags['force-field'] === undefined)
+        await refuseIfParamKey(contract, field);
     const owner = await read(contract, 'owner');
     console.log(dim(`  note: locking the '${field}' field is permanent and irreversible (freezes all its representations).`));
     const tx = collection