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

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, makeHotSender, makePublicClient, makeWalletClient, oneOfOneImageAbi, seriesImageAbi, deployFixedPriceMinter, prepareConfigureSale, preparePurchase, readSaleConfig, prepareLockContractField, prepareLockContractURI, prepareLockTokenField, prepareLockTokenURI, prepareMint, mintedTokenIds, prepareSeriesMintMany, prepareSetMinter, prepareSetMaxInvocations, prepareSetPrimaryPayee, prepareSetPaused, prepareSetContractField, prepareSetContractURIBase, prepareSetContractURIOverride, prepareSetContractURIRenderer, prepareSetParamHooks, prepareSetParamSchema, prepareRetireParam, readParamSchema, PARAM_TYPES, prepareSetRoyalty, prepareSetTokenField, batchOps, prepareSetTokenURIBase, prepareSetTokenURIOverride, prepareSetTokenURIRenderer, prepareSetTransferValidator, prepareTransfer, prepareTransferOwnership, readCreatorTokenStatus, resolveRecommendedTransferValidator, RECOMMENDED_TRANSFER_VALIDATOR, KNOWN_CHAIN_KEYS, resolveChain, resolveRpcUrl, redactRpcUrl, encodeTag, METADATA_FIELD as F, METADATA_REPRESENTATION as R, stageFieldContent, planStagedContent, exceedsOnchainSoftLimit, ONCHAIN_IMAGE_SOFT_LIMIT, ONCHAIN_PROJECT_SOFT_LIMIT, } from '@artblocks/abx-sdk';
+import { assertChainId, ensureChunkStore as sdkEnsureChunkStore, predictFixedPriceMinter, predictFixedPriceMinter1155, makeHotSender, makePublicClient, makeWalletClient, oneOfOneImageAbi, oneOfOneEditionAbi, seriesImageAbi, deployFixedPriceMinter, deployFixedPriceMinter1155, prepareConfigureSale, prepareConfigureSale1155, preparePurchase, preparePurchase1155, readSaleConfig, readSaleConfig1155, prepareEditionMint, prepareEditionTransfer, prepareSetMaxSupply, preparePingURI, prepareLockContractField, prepareLockContractURI, prepareLockTokenField, prepareLockTokenURI, prepareMint, mintedTokenIds, prepareSeriesMintMany, prepareSetMinter, prepareSetMaxInvocations, prepareSetPrimaryPayee, prepareSetPaused, prepareSetContractField, prepareSetContractURIBase, prepareSetContractURIOverride, prepareSetContractURIRenderer, prepareSetParamHooks, prepareSetParamSchema, prepareRetireParam, readParamSchema, PARAM_TYPES, prepareSetRoyalty, prepareSetTokenField, batchOps, prepareSetTokenURIBase, prepareSetTokenURIOverride, prepareSetTokenURIRenderer, prepareSetTransferValidator, prepareTransfer, prepareTransferOwnership, readCreatorTokenStatus, resolveRecommendedTransferValidator, RECOMMENDED_TRANSFER_VALIDATOR, KNOWN_CHAIN_KEYS, resolveChain, resolveRpcUrl, redactRpcUrl, encodeTag, METADATA_FIELD as F, METADATA_REPRESENTATION as R, stageFieldContent, planStagedContent, exceedsOnchainSoftLimit, ONCHAIN_IMAGE_SOFT_LIMIT, ONCHAIN_PROJECT_SOFT_LIMIT, } from '@artblocks/abx-sdk';
 import { encodeScalarParam, encodeTag as encodeTagSdk, isAccepted, prepareConfigureTokenParam, prepareConfigureTokenParamData, prepareSetContractParam, prepareSetContractParamData, seriesCodeAbi, tryReadContract, } from '@artblocks/abx-sdk';
 import { hasParamEnumeration } from '@artblocks/abx-sdk';
 import { decodeFieldRenderer, resolveGenerator, DEP_RESOLUTION, parseDependencyRef, prepareLockDependencies, prepareRemoveLastDependency, prepareSetDependency, prepareSetDependencyRegistry, } from '@artblocks/abx-sdk';
@@ -16,8 +16,9 @@ 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 { CHAIN, chainId, fixedPriceMinterAddress, localIndexer } from './config.js';
+import { CHAIN, chainId, fixedPriceMinterAddress, fixedPriceMinter1155Address, localIndexer } from './config.js';
 import { CliError } from './errors.js';
+import { detectTokenKind } from './kind.js';
 import { openWalletSession } from './signer.js';
 import { gatedSend, laneFromFlags } from './riskgate.js';
 import { withJson } from './jsonout.js';
@@ -375,8 +376,12 @@ export async function cmdSetParamHooks(address, flags) {
     }
     catch (err) {
         await assertContractExists(contract); // no contract at all → the actionable no-contract error
-        throw new Error(`${contract} exposes no param hooks — the configure/augment/transfer hooks are a SeriesCode ` +
-            `(PostParams) feature. A 1/1 or a plain Series has no configurable params to hook.`);
+        // Name the ACTUAL kind rather than assuming 721 — a 1/1-edition or EditionImage has no param
+        // hooks either (only EditionCode composes ConfigurableParams, mirroring SeriesCode), so the old
+        // blanket "a 1/1 or a plain Series" message misnamed an edition target's real kind.
+        const kind = await detectTokenKind(publicClient, contract);
+        throw new Error(`${contract} exposes no param hooks — the configure/augment/transfer hooks are a SeriesCode/EditionCode ` +
+            `(PostParams) feature. ${kind.label} has no configurable params to hook.`);
     }
     const cur = { configure: current[0], augment: current[1], transfer: current[2] };
     const label = (a) => (eqAddr(a, zeroAddress) ? dim('none') : a);
@@ -466,21 +471,96 @@ export async function cmdLockDependencies(address, flags) {
     console.log(dim('  note: locking the dependency set is permanent and irreversible (list AND registry pointer freeze).'));
     await runWrite(contract, prepareLockDependencies({ contract, chainId: chainId() }), flags, owner);
 }
+// ── editions: shared small parsers ────────────────────────────────────────────
+/** A non-negative-integer edition flag (`--token-id`, `--amount`, …) — the shared parse +
+ *  bound-check so every edition command that takes "an id" or "a count" rejects the same way. */
+export function parseEditionCountFlag(raw, flag) {
+    if (raw === 'true' || !/^\d+$/.test(raw.trim()))
+        throw new Error(`--${flag} must be a non-negative integer; got '${raw}'.`);
+    return BigInt(raw.trim());
+}
+/** `--token-ids <csv|range>` — the shape `ping-uri` (and any future batch-by-id command) takes: a
+ *  comma-separated list of ids and/or `lo-hi` ranges (`0-9,20,25-30`), de-duplicated and sorted. */
+export function parseTokenIdRange(raw) {
+    const ids = new Set();
+    for (const part of raw.split(',').map((s) => s.trim()).filter(Boolean)) {
+        const range = part.match(/^(\d+)-(\d+)$/);
+        if (range) {
+            const [lo, hi] = [BigInt(range[1]), BigInt(range[2])];
+            if (lo > hi)
+                throw new Error(`--token-ids: range '${part}' has lo > hi.`);
+            for (let i = lo; i <= hi; i++)
+                ids.add(i);
+        }
+        else if (/^\d+$/.test(part)) {
+            ids.add(BigInt(part));
+        }
+        else {
+            throw new Error(`--token-ids: '${part}' isn't a token id or a 'lo-hi' range.`);
+        }
+    }
+    if (!ids.size)
+        throw new Error("--token-ids needs at least one id (e.g. '0,1,2' or '0-99').");
+    return [...ids].sort((a, b) => Number(a - b));
+}
 // ── mint ─────────────────────────────────────────────────────────────────────
 // Issue a token — a deferred mint (deploy → warm resolver → mint) or a primary sale
 // (mint straight to the buyer). For a 1/1 this is the one-shot token #0. For a Series
 // it mints the next sequential token id (metadata = token id): bare (one), or `--count <n>`
 // (n in order). Owner or an authorized minter signs.
+// For an EDITION (OneOfOneEdition/EditionImage/EditionCode) this mints copies of ONE id:
+// --token-id (required unless the target is a 1/1-edition, whose id space is fixed to {0}) +
+// --amount (default 1). --count is the 721 Series primitive and is refused on an edition.
 export async function cmdMint(address, flags) {
-    const usage = 'abx mint <address> [--to 0x…] [--count <n>] [--json] [--sign|--unsigned]';
+    const usage = 'abx mint <address> [--to 0x…] [--count <n> | --token-id <id> --amount <n>] [--json] [--sign|--unsigned]';
     const contract = requireAddress(address, usage);
     // `--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 publicClient = makePublicClient({ chainKey: CHAIN });
+        const kind = await detectTokenKind(publicClient, contract);
         const owner = await read(contract, 'owner');
         const to = flags.to ?? owner; // default: pre-mint to the admin
+        if (kind.isEdition) {
+            // `--count` is the 721 Series primitive (N sequential ids); an edition mint always names its
+            // id and an amount — there is no "next in order" to count through. Refuse, don't silently
+            // reinterpret it as something else.
+            if (flags.count !== undefined) {
+                throw new Error(`--count is a 721 Series flag (mint N tokens in order) — ${contract} is a ${kind.label} (edition). Use --token-id <id> --amount <n> instead.`);
+            }
+            // OneOfOneEdition's id space is fixed to {0}, so --token-id defaults there; EditionImage/
+            // EditionCode ids are caller-named artworks with no sensible default — require it.
+            if (kind.kind !== '1of1-edition' && flags['token-id'] === undefined) {
+                throw new Error(`--token-id is required on a ${kind.label} — its ids are caller-named artworks, not a single default. ` +
+                    `See existing ids with \`abx tokens ${contract}\`.`);
+            }
+            const tokenId = flags['token-id'] !== undefined ? parseEditionCountFlag(flags['token-id'], 'token-id') : 0n;
+            const amount = flags.amount !== undefined ? parseEditionCountFlag(flags.amount, 'amount') : 1n;
+            console.log(dim(`  minting ${amount} cop${amount === 1n ? 'y' : 'ies'} of #${tokenId} → ${to}${flags.to ? '' : ' (owner — pass --to for a buyer)'}`));
+            const tx = prepareEditionMint({ contract, to, tokenId, amount, chainId: chainId() });
+            const result = await runWrite(contract, tx, flags, owner);
+            if (result)
+                console.log(`  ${green('✓')} minted ${amount} cop${amount === 1n ? 'y' : 'ies'} of ${bold('#' + tokenId)} → ${to}`);
+            console.log(dim(`  next: \`abx refresh ${contract}\` so marketplaces pick up the change.`));
+            return {
+                contract,
+                chainId: chainId(),
+                to,
+                sent: !!result,
+                txHash: result?.txHash ?? null,
+                blockNumber: result ? String(result.blockNumber) : null,
+                tokenIds: [tokenId.toString()],
+                amount: amount.toString(),
+            };
+        }
+        // 721 path (unchanged): --token-id/--amount have no meaning here — refuse rather than silently
+        // ignore (the membrane rule: enforce, don't warn).
+        if (flags['token-id'] !== undefined || flags.amount !== undefined) {
+            throw new Error(`--token-id/--amount are edition-only (ERC-1155 copies) — ${contract} is a ${kind.label} (721). ` +
+                `Mint the next token with \`abx mint ${contract}\`${kind.kind !== '1of1' ? ' (or --count N for several in order)' : ''}.`);
+        }
         let tx;
         let count = 1n;
         if (flags.count !== undefined && flags.count !== 'true') {
@@ -535,6 +615,67 @@ export async function cmdSetMaxInvocations(address, flags) {
     const owner = await read(contract, 'owner');
     await runWrite(contract, prepareSetMaxInvocations({ contract, maxInvocations: max, chainId: chainId() }), flags, owner);
 }
+// ── set-max-supply (editions only) — the per-id twin of set-max-invocations ──────────────────────
+/**
+ * `abx set-max-supply <address> --token-id <n> --cap <n>` — owner overrides ONE id's ERC-1155
+ * supply cap (Edition Supply extension). Monotonically non-increasing once used for that id — the
+ * chain enforces it (`MaxSupplyIncreaseForbidden`/`MaxSupplyBelowFloor`), and `--cap open` is
+ * refused HERE, before any gas: the contract's own "0" means "closed forever" once an id has been
+ * overridden (not "reopen to uncapped" — `EditionSupply.sol`'s own doc calls this out), so accepting
+ * `open` as an alias for 0 would silently promise the opposite of what it does on a re-run.
+ */
+export async function cmdSetMaxSupply(address, flags) {
+    const usage = 'abx set-max-supply <address> --token-id <n> --cap <n> [--sign|--unsigned]';
+    const contract = requireAddress(address, usage);
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    const kind = await detectTokenKind(publicClient, contract);
+    if (!kind.isEdition) {
+        throw new Error(`set-max-supply is edition-only (a per-id ERC-1155 cap) — ${contract} is a ${kind.label} (721). Use \`abx set-max-invocations\` instead (the whole-project cap).`);
+    }
+    const tokenId = parseEditionCountFlag(requireFlag(flags, 'token-id', usage), 'token-id');
+    const capRaw = requireFlag(flags, 'cap', usage);
+    if (capRaw.trim().toLowerCase() === 'open') {
+        throw new Error(`--cap open is refused: once you set a cap for #${tokenId} it can only DECREASE (never increase back to uncapped) — ` +
+            `"open" would ask for exactly the increase the chain forbids. If this id has never been overridden, it's already open ` +
+            `(the --copies default from deploy) — there's nothing to set. To lower an existing cap, pass the number.`);
+    }
+    const cap = parseEditionCountFlag(capRaw, 'cap');
+    const owner = await read(contract, 'owner');
+    console.log(dim(`  #${tokenId} supply cap → ${cap}`));
+    await runWrite(contract, prepareSetMaxSupply({ contract, tokenId, cap, chainId: chainId() }), flags, owner);
+}
+// ── ping-uri (editions only) — permissionless URI re-emission ────────────────────────────────────
+/** How many ids one `pingURI` call carries per transaction — large enough that a normal collection
+ *  fits in one tx, small enough that a genuinely huge id list doesn't build one unbounded call. */
+const PING_URI_CHUNK_SIZE = 200;
+/**
+ * `abx ping-uri <address> --token-ids <csv|range>` — re-emit the native ERC-1155 `URI` event for
+ * the given ids after a contract-wide re-point (`set-token-uri`/`set-renderer`), so marketplaces/
+ * indexers that only honor the native event re-index. Permissionless (anyone may call it — it only
+ * re-emits already-public, current truth), so there is no owner check and no `expectedSigner` to
+ * pin; whichever signer the active lane resolves sends it. Chunks a large id list into several
+ * transactions, each through the SAME `--dry-run`/`--confirm` gate as any other write.
+ */
+export async function cmdPingUri(address, flags) {
+    const usage = 'abx ping-uri <address> --token-ids <csv|range> [--sign|--unsigned]';
+    const contract = requireAddress(address, usage);
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    const kind = await detectTokenKind(publicClient, contract);
+    if (!kind.isEdition) {
+        throw new Error(`ping-uri is edition-only — it re-emits the ERC-1155 URI event, which a ${kind.label} (721) doesn't have ` +
+            `(721 emits ERC-4906 MetadataUpdate automatically on a URI change — nothing to re-emit by hand).`);
+    }
+    const ids = parseTokenIdRange(requireFlag(flags, 'token-ids', usage));
+    const chunks = [];
+    for (let i = 0; i < ids.length; i += PING_URI_CHUNK_SIZE)
+        chunks.push(ids.slice(i, i + PING_URI_CHUNK_SIZE));
+    console.log(dim(`  re-emitting URI for ${ids.length} id${ids.length === 1 ? '' : 's'} — permissionless (no owner check) — ${chunks.length} tx${chunks.length === 1 ? '' : '(s)'} of up to ${PING_URI_CHUNK_SIZE} id(s) each`));
+    for (const [i, chunk] of chunks.entries()) {
+        if (chunks.length > 1)
+            console.log(dim(`  chunk ${i + 1}/${chunks.length}: ${chunk.length} id(s) (#${chunk[0]}–#${chunk[chunk.length - 1]})`));
+        await runWrite(contract, preparePingURI({ contract, tokenIds: chunk, chainId: chainId() }), flags);
+    }
+}
 /** Pause minting — restrict it to the owner (config/reserves) until unpaused. */
 export async function cmdPause(address, flags) {
     const contract = requireAddress(address, 'abx pause <address> [--sign|--unsigned]');
@@ -626,9 +767,33 @@ export async function cmdRefresh(address, flags) {
 }
 // ── transfer ─────────────────────────────────────────────────────────────────
 export async function cmdTransfer(address, flags) {
-    const contract = requireAddress(address, 'abx transfer <address> --to 0x… [--token 0] [--sign|--unsigned]');
-    const to = requireFlag(flags, 'to', 'abx transfer <address> --to 0x…');
+    const usage = 'abx transfer <address> --to 0x… [--token 0] [--amount <n> --from 0x… (editions only)] [--sign|--unsigned]';
+    const contract = requireAddress(address, usage);
+    const to = requireFlag(flags, 'to', usage);
     const tokenId = BigInt(flags.token ?? '0');
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    const kind = await detectTokenKind(publicClient, contract);
+    if (kind.isEdition) {
+        const amount = flags.amount !== undefined ? parseEditionCountFlag(flags.amount, 'amount') : 1n;
+        // Unlike a 721 (one holder, read on-chain via ownerOf), an edition id can have MANY concurrent
+        // holders — there is no single "the owner" to move copies from, so the holder must be named.
+        const fromRaw = flags.from;
+        if (!fromRaw || fromRaw === 'true') {
+            throw new Error(`--from 0x.. is required on a ${kind.label} — an edition id can have many concurrent holders, so ` +
+                `there is no single current owner to read on-chain (unlike a 721). Pass the holder's address.`);
+        }
+        if (!isAddress(fromRaw))
+            throw new Error(`--from must be a 0x address; got '${fromRaw}'.`);
+        const from = getAddress(fromRaw);
+        const tx = prepareEditionTransfer({ contract, from, to, tokenId, amount, chainId: chainId() });
+        await runWrite(contract, tx, flags, from);
+        return;
+    }
+    // 721 path (unchanged): --amount has no meaning — a token transfers as a whole. Refuse rather
+    // than silently ignore.
+    if (flags.amount !== undefined) {
+        throw new Error(`--amount is edition-only (ERC-1155 copies) — ${contract} is a ${kind.label} (721), where a token transfers as a whole. Drop --amount.`);
+    }
     const from = await read(contract, 'ownerOf', [tokenId]);
     const tx = prepareTransfer({ contract, from, to, tokenId, chainId: chainId() });
     await runWrite(contract, tx, flags, from);
@@ -726,7 +891,7 @@ export function parseTransferValidatorValue(raw, opts) {
     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. ` +
+        throw new Error(`a zero transfer validator never enrolls — a plain (unenrolled) token 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\`.)`);
     }
@@ -768,7 +933,7 @@ export async function cmdSetTransferValidator(address, rest, flags) {
     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. ` +
+        throw new Error(`${contract} did not enroll as a creator token — 721C/1155C enrollment is a deploy-time decision. ` +
             `Enrollment can never be added to a live collection; if enforcement is required, redeploy with ` +
             `--721c recommended (or --721c 0x…) on the deploy command.`);
     }
@@ -1370,6 +1535,17 @@ async function readSeries(token, fn, args = []) {
         args: args,
     }));
 }
+/** The edition twin of {@link readSeries} — reads a per-id getter (`totalSupply(id)`,
+ *  `maxSupply(id)`, `uri(id)`, …) via the narrowest-common-superset edition ABI. */
+async function readEdition(token, fn, args = []) {
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    return (await publicClient.readContract({
+        address: token,
+        abi: oneOfOneEditionAbi,
+        functionName: fn,
+        args: args,
+    }));
+}
 /** Resolve the shared minter for the chain (flag → env → manifest), or deploy it if none exists.
  *  It's ownerless, so any funded signer can stand it up — the sibling of `ensureChunkStore`. */
 async function ensureFixedPriceMinter(override) {
@@ -1400,6 +1576,34 @@ async function ensureFixedPriceMinter(override) {
     console.log(dim(`  not in the shipped manifest for ${CHAIN} — to reuse it set ${bold(`ABX_FIXED_PRICE_MINTER=${minter}`)} (or add it to packages/sdk/src/deployments.ts)`));
     return minter;
 }
+/** The edition twin of {@link ensureFixedPriceMinter} — resolves (or deploys) the chain's shared
+ *  `AbxFixedPriceMinter1155`, the Minter spine's per-`(token, id)` sale singleton. */
+async function ensureFixedPriceMinter1155(override) {
+    const known = fixedPriceMinter1155Address(override);
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    if (known) {
+        const code = await publicClient.getCode({ address: known });
+        if (code && code !== '0x')
+            return known;
+        console.log(yellow(`  configured edition minter ${known} has no code on ${CHAIN} — deploying a fresh one`));
+    }
+    const predicted = predictFixedPriceMinter1155();
+    if (!known || known.toLowerCase() !== predicted.toLowerCase()) {
+        const pcode = await publicClient.getCode({ address: predicted });
+        if (pcode && pcode !== '0x') {
+            console.log(dim(`  using the canonical fixed-price edition minter at its deterministic address ${predicted}`));
+            return predicted;
+        }
+    }
+    const { wallet, account } = makeWalletClient({ chainKey: CHAIN });
+    const send = makeHotSender({ wallet, account, publicClient });
+    console.log(dim('  deploying the canonical fixed-price edition minter (shared, ownerless) — CREATE2…'));
+    const { minter, txHash } = await deployFixedPriceMinter1155(send, publicClient);
+    console.log(`  ${green('✓')} fixed-price edition minter ${minter}`);
+    console.log(dim(`  tx ${txHash}`));
+    console.log(dim(`  not in the shipped manifest for ${CHAIN} — to reuse it set ${bold(`ABX_FIXED_PRICE_MINTER_1155=${minter}`)} (or add it to packages/sdk/src/deployments.ts)`));
+    return minter;
+}
 /** A minter write (configure/buy). No re-index — the sale lives on the minter, not the token
  *  projection; the token's own state is unchanged by a sale config.
  *
@@ -1425,23 +1629,76 @@ function parseSalePrice(flags, usage) {
  * sale for a project on the shared minter. Defers to the token owner. Resolves (or deploys) the
  * shared minter, then reports the two remaining grants the owner still needs (assign the minter on
  * the token, set a primary payee) and whether the token is paused.
+ *
+ * On an EDITION (OneOfOneEdition/EditionImage/EditionCode), `--token-id` is REQUIRED (sales are
+ * keyed `(token, id)` — a per-artwork price, not one project-wide sale) and the sale routes to the
+ * shared `AbxFixedPriceMinter1155` instead. Refused on a 721 target.
  */
 export async function cmdMinterConfigure(address, flags) {
-    const usage = 'abx minter configure <token> (--price <eth> | --price-raw <units>) --allocation <n> [--erc20 0x…] [--minter-contract 0x…] [--sign|--unsigned]';
+    const usage = 'abx minter configure <token> (--price <eth> | --price-raw <units>) --allocation <n> [--erc20 0x…] [--token-id <n> (editions)] [--minter-contract 0x…] [--sign|--unsigned]';
     const token = requireAddress(address, usage);
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    const kind = await detectTokenKind(publicClient, token);
     const owner = await read(token, 'owner');
     const erc20 = flags.erc20 && flags.erc20 !== 'true' ? flags.erc20 : zeroAddress;
     const allocation = BigInt(requireFlag(flags, 'allocation', usage));
     const price = parseSalePrice(flags, usage);
-    // On --dry-run resolve the minter WITHOUT deploying — ensureFixedPriceMinter would deploy the
-    // shared singleton if absent, and a preview must never send. Fall back to a label if none exists.
+    const isEth = erc20 === zeroAddress;
+    // On --dry-run resolve the minter WITHOUT deploying — ensure* would deploy the shared singleton
+    // if absent, and a preview must never send. Fall back to a label if none exists.
     const dryRun = isDryRun(flags);
+    if (kind.isEdition) {
+        const tokenId = parseEditionCountFlag(requireFlag(flags, 'token-id', usage), 'token-id');
+        const knownMinter = fixedPriceMinter1155Address(flags['minter-contract']);
+        if (dryRun && !knownMinter) {
+            console.log(yellow(`  ⚠ no shared edition minter deployed on ${CHAIN} yet — a real run deploys it once (a separate tx) before configuring.`));
+        }
+        const minter = dryRun ? (knownMinter ?? zeroAddress) : await ensureFixedPriceMinter1155(flags['minter-contract']);
+        // Sanity-check the allocation against what THIS id can still mint. `maxSupply(id) === 0` reads
+        // as "open" (the un-overridden --copies default, or an id nobody has ever capped) — the same
+        // convention `tokens.ts`'s TokenRow.maxSupply documents; see set-max-supply's own note on why a
+        // bare 0 can't be told apart from "explicitly closed" without more than this one read.
+        const [maxSupply, supplyNow] = await Promise.all([
+            readEdition(token, 'maxSupply', [tokenId]).catch(() => 0n),
+            readEdition(token, 'totalSupply', [tokenId]).catch(() => 0n),
+        ]);
+        const remaining = maxSupply > 0n ? (maxSupply > supplyNow ? maxSupply - supplyNow : 0n) : null;
+        if (remaining !== null && allocation > remaining) {
+            console.log(yellow(`  ⚠ allocation ${allocation} exceeds the ${remaining} #${tokenId} can still mint `) +
+                dim(`(cap ${maxSupply} − ${supplyNow} minted). Only ${remaining} will actually sell.`));
+            console.log(dim(`    To sell ${allocation}, raise this id's cap is not possible (caps only decrease) — set --allocation ${remaining} (or less, to hold reserves).`));
+        }
+        console.log(dim(`  configuring sale on ${minter}`));
+        console.log(dim(`    token      ${token}  ·  id #${tokenId}`));
+        console.log(dim(`    price      ${isEth ? `${formatEther(price)} ETH` : `${price} units of ${erc20}`} / copy`));
+        console.log(dim(`    allocation ${allocation}`));
+        await runMinterWrite(prepareConfigureSale1155({ minter, token, tokenId, paymentToken: erc20, price, allocation, chainId: chainId() }), flags, owner);
+        const [assignedMinter, payee, paused] = await Promise.all([
+            read(token, 'minter').catch(() => zeroAddress),
+            read(token, 'primaryPayee').catch(() => zeroAddress),
+            read(token, 'paused').catch(() => false),
+        ]);
+        const assigned = assignedMinter.toLowerCase() === minter.toLowerCase();
+        console.log('');
+        console.log(assigned ? dim('  ✓ minter is assigned on the token') : yellow(`  ⚠ assign this minter on the token:  abx set-minter ${token} --minter ${minter}`));
+        if (payee === zeroAddress)
+            console.log(yellow(`  ⚠ set a primary payee (sales revert without one):  abx set-primary-payee ${token} --payee 0x…`));
+        else
+            console.log(dim(`  ✓ proceeds → ${payee}`));
+        if (paused)
+            console.log(yellow(`  • token is paused — open the sale when ready:  abx unpause ${token}`));
+        console.log(dim(`  buyers then run:  abx minter buy ${token} --token-id ${tokenId} --quantity <n>`));
+        return;
+    }
+    // 721 path (unchanged): --token-id has no meaning — a 721 sale is one project-wide price.
+    if (flags['token-id'] !== undefined) {
+        throw new Error(`--token-id is edition-only (per-(token,id) sales) — ${token} is a ${kind.label} (721), sold as a single project-wide sale. Drop --token-id.`);
+    }
     const knownMinter = fixedPriceMinterAddress(flags['minter-contract']);
     if (dryRun && !knownMinter) {
         console.log(yellow(`  ⚠ no shared minter deployed on ${CHAIN} yet — a real run deploys it once (a separate tx) before configuring.`));
     }
     const minter = dryRun ? (knownMinter ?? zeroAddress) : await ensureFixedPriceMinter(flags['minter-contract']);
-    const isEth = erc20 === zeroAddress;
     // Sanity-check the allocation against what the contract can actually mint. A creator who sets
     // --allocation 100 on a 16-supply Series would only ever sell the remainder (maxInvocations binds
     // tighter than the minter's allocation) and discover it when mint #16 reverts. Warn loudly — but
@@ -1479,19 +1736,67 @@ export async function cmdMinterConfigure(address, flags) {
     console.log(dim(`  buyers then run:  abx minter buy ${token}`));
 }
 /** `abx minter show <token>` — the sale terms + the token's readiness (assigned? payee? paused?).
- *  Read-only; the agent runs it to see exactly what's configured before/after a sale. */
+ *  Read-only; the agent runs it to see exactly what's configured before/after a sale. On an
+ *  edition, `--token-id` is required and the readout is per-id (copies, not a whole-contract cap). */
 export async function cmdMinterShow(address, flags) {
-    const token = requireAddress(address, 'abx minter show <token> [--minter-contract 0x…]');
+    const usage = 'abx minter show <token> [--token-id <n> (editions)] [--minter-contract 0x…]';
+    const token = requireAddress(address, usage);
     // Refuse a nonexistent contract like the sibling owner-ops (state/unpause/minter configure) do —
     // otherwise the minter singleton returns zero-config for the unconfigured token and we print a
     // plausible-but-fake `paused: no (open)` readout for an address that has no project at all.
     await assertContractExists(token);
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    const kind = await detectTokenKind(publicClient, token);
+    if (kind.isEdition) {
+        const tokenId = parseEditionCountFlag(requireFlag(flags, 'token-id', usage), 'token-id');
+        const minter = fixedPriceMinter1155Address(flags['minter-contract']);
+        if (!minter) {
+            console.log(yellow(`  no shared edition minter known for ${CHAIN} — configure a sale (deploys it) or set ABX_FIXED_PRICE_MINTER_1155`));
+            return;
+        }
+        const sale = await readSaleConfig1155(publicClient, minter, token, tokenId);
+        // Every read here goes through the EDITION ABI: the generic `read()` is the 721 1/1 ABI,
+        // which has no minter()/primaryPayee() at all — a swallowed client-side throw there printed
+        // a false "not assigned / no payee" for every correctly-configured edition (caught live by
+        // the Sepolia fixture sweep, 2026-08-05).
+        const [assignedMinter, payee, paused, maxSupply, supply] = await Promise.all([
+            readEdition(token, 'minter').catch(() => zeroAddress),
+            readEdition(token, 'primaryPayee').catch(() => zeroAddress),
+            readEdition(token, 'paused').catch(() => false),
+            readEdition(token, 'maxSupply', [tokenId]).catch(() => 0n),
+            readEdition(token, 'totalSupply', [tokenId]).catch(() => 0n),
+        ]);
+        const isEth = sale.paymentToken === zeroAddress;
+        const assigned = assignedMinter.toLowerCase() === minter.toLowerCase();
+        console.log(bold(`\n  minter sale — ${token} #${tokenId}`));
+        console.log(`    shared minter:     ${minter}`);
+        if (!sale.configured) {
+            console.log(yellow(`    not configured     — abx minter configure ${token} --token-id ${tokenId} --price <eth> --allocation <n>`));
+        }
+        else {
+            console.log(`    price:             ${isEth ? `${formatEther(sale.price)} ETH` : `${sale.price} units of ${sale.paymentToken}`}`);
+            console.log(`    allocation:        ${sale.sold}/${sale.allocation} sold`);
+        }
+        console.log(`    assigned on token: ${assigned ? green('yes') : yellow(`no — abx set-minter ${token} --minter ${minter}`)}`);
+        console.log(`    primary payee:     ${payee === zeroAddress ? yellow('none — abx set-primary-payee …') : payee}`);
+        console.log(`    paused:            ${paused ? yellow(`yes — abx unpause ${token}`) : green('no (open)')}`);
+        console.log(`    copies:            ${supply}${maxSupply > 0n ? `/${maxSupply}` : dim(' (open — no cap)')}`);
+        const remaining = maxSupply > 0n ? (maxSupply > supply ? maxSupply - supply : 0n) : null;
+        if (sale.configured && remaining !== null && sale.allocation > remaining) {
+            console.log(yellow(`    ⚠ allocation ${sale.allocation} exceeds the ${remaining} still mintable for #${tokenId} (cap ${maxSupply} − ${supply} minted) — only ${remaining} can actually sell.`));
+        }
+        console.log('');
+        return;
+    }
+    if (flags['token-id'] !== undefined) {
+        throw new Error(`--token-id is edition-only — ${token} is a ${kind.label} (721). Drop --token-id.`);
+    }
     const minter = fixedPriceMinterAddress(flags['minter-contract']);
     if (!minter) {
         console.log(yellow(`  no shared minter known for ${CHAIN} — configure a sale (deploys it) or set ABX_FIXED_PRICE_MINTER`));
         return;
     }
-    const sale = await readSaleConfig(makePublicClient({ chainKey: CHAIN }), minter, token);
+    const sale = await readSaleConfig(publicClient, minter, token);
     const [assignedMinter, payee, paused, max, supply] = await Promise.all([
         readSeries(token, 'minter').catch(() => zeroAddress),
         readSeries(token, 'primaryPayee').catch(() => zeroAddress),
@@ -1523,14 +1828,46 @@ export async function cmdMinterShow(address, flags) {
     console.log('');
 }
 /** `abx minter buy <token> [--to 0x…]` — buy one token through the shared minter (public; any
- *  funded signer). ETH sales attach the price; ERC-20 sales need a prior approval to the minter. */
+ *  funded signer). ETH sales attach the price; ERC-20 sales need a prior approval to the minter.
+ *  On an edition, `--token-id` is required and `--quantity` (default 1) buys several copies in the
+ *  same purchase — the total ETH attached is `price × quantity`. */
 export async function cmdMinterBuy(address, flags) {
-    const usage = 'abx minter buy <token> [--to 0x…] [--minter-contract 0x…] [--sign|--unsigned]';
+    const usage = 'abx minter buy <token> [--to 0x…] [--token-id <n> --quantity <n> (editions)] [--minter-contract 0x…] [--sign|--unsigned]';
     const token = requireAddress(address, usage);
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    const kind = await detectTokenKind(publicClient, token);
+    if (kind.isEdition) {
+        const tokenId = parseEditionCountFlag(requireFlag(flags, 'token-id', usage), 'token-id');
+        const quantity = flags.quantity !== undefined ? parseEditionCountFlag(flags.quantity, 'quantity') : 1n;
+        if (quantity === 0n)
+            throw new Error('--quantity must be at least 1 (0 copies is not a purchase).');
+        const minter = fixedPriceMinter1155Address(flags['minter-contract']);
+        if (!minter)
+            throw new Error(`no shared edition minter known for ${CHAIN} — configure a sale first, or set ABX_FIXED_PRICE_MINTER_1155`);
+        const sale = await readSaleConfig1155(publicClient, minter, token, tokenId);
+        if (!sale.configured)
+            throw new Error(`no sale configured for ${token} #${tokenId} — run: abx minter configure ${token} --token-id ${tokenId} …`);
+        const isEth = sale.paymentToken === zeroAddress;
+        const to = flags.to && flags.to !== 'true' ? flags.to : undefined;
+        // Payment math: price × quantity, computed ONCE and shown in the confirm/dry-run readout below
+        // (via runMinterWrite → gatedSend's own preview) — the exact ETH the tx attaches.
+        const value = isEth ? sale.price * quantity : 0n;
+        if (!isEth) {
+            console.log(yellow(`  ERC-20 sale: the buyer must have approved ${minter} to spend ${sale.price * quantity} units of ${sale.paymentToken} first (else the tx reverts).`));
+        }
+        console.log(dim(`  buying ${quantity} cop${quantity === 1n ? 'y' : 'ies'} of #${tokenId}${to ? ` → ${to}` : ' → signer'} for ` +
+            `${isEth ? `${formatEther(value)} ETH (${formatEther(sale.price)} × ${quantity})` : `${value} units (${sale.price} × ${quantity})`}`));
+        await runMinterWrite(preparePurchase1155({ minter, token, tokenId, quantity, to, value, chainId: chainId() }), flags);
+        console.log(dim(`  next: \`abx refresh ${token}\` so marketplaces pick up the change.`));
+        return;
+    }
+    if (flags['token-id'] !== undefined || flags.quantity !== undefined) {
+        throw new Error(`--token-id/--quantity are edition-only — ${token} is a ${kind.label} (721), where a sale buys exactly one token. Drop them.`);
+    }
     const minter = fixedPriceMinterAddress(flags['minter-contract']);
     if (!minter)
         throw new Error(`no shared minter known for ${CHAIN} — configure a sale first, or set ABX_FIXED_PRICE_MINTER`);
-    const sale = await readSaleConfig(makePublicClient({ chainKey: CHAIN }), minter, token);
+    const sale = await readSaleConfig(publicClient, minter, token);
     if (!sale.configured)
         throw new Error(`no sale configured for ${token} — run: abx minter configure ${token} …`);
     const isEth = sale.paymentToken === zeroAddress;