@artblocks/abx-cli 0.1.0-alpha.4 → 0.1.0-alpha.40

package/dist/riskgate.js

@@ -0,0 +1,234 @@
+/**
+ * The CLI's one risk gate for a write — the choke point every signing path (owner-op or deploy)
+ * routes an already-prepared tx through, so `--dry-run` and `--confirm` behave IDENTICALLY no
+ * matter which command reached them.
+ *
+ * Before this module existed, the same three-part shape (preview-and-stop under `--dry-run` →
+ * optional interactive `--confirm` → pick a lane → sign) was hand-written THREE times: ownerops.ts's
+ * `runWrite` (every owner-op), a near-identical `runMinterWrite` ("the minter path does not go
+ * through runWrite, so it needs its OWN dry-run guard" — its own comment conceding the duplication),
+ * and a third copy inline in main.ts's `deploy-code --resume` send path. Each could drift from the
+ * others without anyone deciding it should — and the two owner-op copies HAD already drifted: only
+ * one of them printed the `owner` line on a dry-run preview when the caller supplied one.
+ *
+ * `gatedSend` is the merge. Callers that had NO `--confirm` support (every owner-op) gain it for
+ * free just by routing through here — there is no owner-op-specific reason they lacked it; it was
+ * simply never wired.
+ */
+import { decodeErrorResult, zeroAddress } from 'viem';
+import { createInterface } from 'node:readline';
+import { assertChainId, envSigningKey, makePublicClient, seriesCodeAbi } from '@artblocks/abx-sdk';
+import { signTx } from './signer.js';
+import { isDryRun } from './flags.js';
+// ── tiny ANSI (kept local — every module here stands alone; see signer.ts/ownerops.ts) ───────
+const C = { reset: '\x1b[0m', dim: '\x1b[2m', bold: '\x1b[1m', green: '\x1b[38;5;115m', orange: '\x1b[38;5;215m' };
+const dim = (s) => `${C.dim}${s}${C.reset}`;
+const bold = (s) => `${C.bold}${s}${C.reset}`;
+/** Resolve the signing lane from flags: `--unsigned` (cold) · `--sign` (wallet) · default hot. The
+ *  one place this decision is made — every write reads the same three flags the same way. */
+export function laneFromFlags(flags) {
+    // Two lane flags at once is always a mistake, and silently picking one is how a caller ends up in a
+    // lane they did not choose — an agent writing `--send --sign` from two different help lines gets a
+    // browser wallet page when it meant the env key, and reads the wait as a hang. Refuse instead: the
+    // precedence order below is an implementation detail, not an interface.
+    const named = ['send', 'sign', 'unsigned'].filter((k) => flags[k] !== undefined);
+    if (named.length > 1) {
+        throw new Error(`pick ONE signing lane, not ${named.length}: ${named.map((n) => `--${n}`).join(' and ')}. ` +
+            `--send signs with the hot/env key (the default, so it can also be omitted) · --sign opens a ` +
+            `wallet page · --unsigned prints the transaction for you to sign elsewhere.`);
+    }
+    // PRESENCE, not truthiness. A bare `--sign` parses to `'true'`, but `--sign=` parses to `''`, which
+    // is falsy — so a truthiness test sent that caller down the hot-key lane after they explicitly named
+    // the wallet one. That is the one direction that matters: asking for a browser approval and getting
+    // an unattended key signature instead. Naming a lane selects it, full stop.
+    if (named.includes('unsigned'))
+        return 'unsigned';
+    if (named.includes('sign'))
+        return 'sign';
+    return 'send';
+}
+/**
+ * Refuse a real deploy on the HOT lane when there is no key to sign with — before the command has
+ * spent anything.
+ *
+ * The signing lanes are checked at *signing* time, which is the end of a deploy. Everything that
+ * makes a deploy possible happens first, and some of it is neither free nor reversible: `--backend
+ * arweave|ipfs|cloud` UPLOADS the creator's art before any transaction is prepared. So a deploy run
+ * with no key, and no `--dry-run` to say "preview only", would mint an Arweave identity, publish the
+ * art, and only THEN discover it could never have deployed. Under Turbo's free tier the upload
+ * *succeeds*, so the art is published permanently — an irreversible side effect from a run that was
+ * always going to fail.
+ *
+ * `--dry-run` guards every signing choke point (`isDryRun`, `gatedSend`); this is the same idea one
+ * step earlier, and the rule it enforces is the sibling of that one: **a spend or a publish never
+ * precedes the check that this run can be signed at all.** Only the hot lane is checked — `--sign`
+ * (browser wallet) and `--unsigned` (offline signer) deliberately have no local key, and a preview
+ * spends nothing.
+ */
+export function assertLaneCanSign(flags) {
+    if (isDryRun(flags))
+        return; // a preview neither signs nor spends
+    if (laneFromFlags(flags) !== 'send')
+        return; // wallet/cold lanes have no local key BY DESIGN
+    if (envSigningKey())
+        return;
+    throw new Error('no signing key, so this run could not be sent — stopping before it uploads or spends anything. ' +
+        'Pick a lane: --sign --for 0x.. (you approve in your own wallet, no key here) · --unsigned (print the tx ' +
+        'for an offline signer) · or set ABX_DEPLOYER_PK in .env for the unattended hot lane. ' +
+        'To preview without any of them, add --dry-run --for 0x...');
+}
+/**
+ * Opt-in pre-send confirmation gate (`--confirm`). OFF by default → scripted use is untouched. Even
+ * when opted in, it never blocks automation: `--yes` or a non-TTY stdin proceeds silently. Only an
+ * interactive `--confirm` prints the summary and waits for a y/N. Aborts on anything but yes.
+ */
+export async function confirmSend(summary, flags) {
+    if (flags.confirm === undefined)
+        return; // not opted in
+    if (flags.yes !== undefined || !process.stdin.isTTY)
+        return; // don't stall scripts/CI
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => rl.question(`\n  ${summary}\n  Proceed? [y/N] `, resolve));
+    rl.close();
+    if (!/^y(es)?$/i.test(answer.trim()))
+        throw new Error('aborted at --confirm (nothing sent).');
+}
+async function resolveProvider(provider, signer) {
+    return typeof provider === 'function' ? await provider(signer) : provider;
+}
+function printDryRunPreview(prepared, expectedSigner) {
+    console.log(`\n  ${bold('◆ ' + prepared.summary)}  ${dim('(dry run — nothing sent)')}`);
+    for (const [k, v] of Object.entries(prepared.fields))
+        console.log(`    ${dim(k.padEnd(12))} ${v}`);
+    console.log(`    ${dim('to'.padEnd(12))} ${prepared.to ?? dim('(contract deploy)')}`);
+    if (expectedSigner)
+        console.log(`    ${dim('owner'.padEnd(12))} ${expectedSigner}`);
+}
+/**
+ * A revert's own name, when the payload carries one — `RoyaltyTooHigh()` instead of a raw hex dump
+ * or "reverted for an unknown reason".
+ *
+ * Whether we get one is the NODE's choice, not ours: many public endpoints (measured:
+ * `base-sepolia-rpc.publicnode.com` and `sepolia.base.org`) answer a failed `eth_call` with a bare
+ * `execution reverted` and no data at all. So the no-data case says *that*, rather than implying we
+ * looked at a reason and couldn't read it.
+ */
+export function revertReason(err) {
+    const data = err?.data ?? err?.cause?.data;
+    const hex = typeof data === 'string' ? data : data?.data;
+    if (typeof hex === 'string' && hex.length >= 10) {
+        try {
+            const decoded = decodeErrorResult({ abi: seriesCodeAbi, data: hex });
+            return `${decoded.errorName}(${(decoded.args ?? []).join(', ')})`;
+        }
+        catch {
+            /* not one of ours — fall through to the message */
+        }
+    }
+    const short = err?.shortMessage ?? err?.message ?? 'reverted';
+    // viem's phrasing for "the node sent no revert data" reads like OUR failure to decode. Say what
+    // actually happened, and what it almost always means.
+    if (/unknown reason/i.test(short)) {
+        return 'reverted (this RPC returns no revert data) — usually a precondition the contract enforces: a lock, a cap, or the wrong signer';
+    }
+    return short;
+}
+/**
+ * `eth_call` the prepared transaction against current state, and say what would happen.
+ *
+ * This is what makes `--dry-run` an *answer* rather than an echo of its own input. It matters most
+ * for a **multicall** — `attach`'s batched pairs, `deploy-code`'s setup — because a multicall is one
+ * transaction, so simulating it exercises the whole sequence atomically against real state, with no
+ * fork and no new surface.
+ *
+ * Reports **unknown**, never a false green, whenever it cannot actually prove anything: no signer to
+ * simulate as (an owner-gated call from nobody reverts for the wrong reason), a contract deploy, a
+ * target that does not exist yet, or an unreachable node.
+ */
+async function simulateDryRun(prepared, chainKey, expectedSigner, narrate = true) {
+    const label = 'simulation'.padEnd(12);
+    const unknown = (why) => {
+        if (narrate)
+            console.log(`    ${dim(label)} ${dim(`unknown — ${why}`)}`);
+        return { status: 'unknown', reason: why };
+    };
+    if (!prepared.to)
+        return unknown('this creates a contract; there is nothing to call yet');
+    if (!expectedSigner || expectedSigner === zeroAddress) {
+        return unknown('no signer known to simulate as the caller — set a signing key, or use --sign; some commands ' +
+            '(e.g. deploy, predict) also accept --for 0x..');
+    }
+    // Everything below is best-effort: a dry run must work OFFLINE and against an unknown chain (the
+    // preview is the product; the simulation is a bonus). So even constructing the client is guarded —
+    // `resolveChain` throws on a chain key it doesn't know, and that must degrade to `unknown`, never
+    // turn a preview into a failure.
+    try {
+        const client = makePublicClient({ chainKey });
+        const code = await client.getCode({ address: prepared.to });
+        if (!code || code === '0x')
+            return unknown(`${prepared.to} has no code yet on this chain`);
+        await client.call({
+            account: expectedSigner,
+            to: prepared.to,
+            data: prepared.data,
+            ...(prepared.value && prepared.value !== '0x0' ? { value: BigInt(prepared.value) } : {}),
+        });
+        if (narrate)
+            console.log(`    ${dim(label)} ${C.green}✓${C.reset} would succeed ${dim('(eth_call against current state)')}`);
+        return { status: 'would-succeed' };
+    }
+    catch (err) {
+        // A node that cannot answer is not a failing transaction — do not report one as the other.
+        const reason = revertReason(err);
+        if (/fetch|network|timeout|ECONN|unknown chain/i.test(reason))
+            return unknown(`could not run the simulation (${reason})`);
+        if (narrate) {
+            console.log(`    ${dim(label)} ${C.orange}✗ would REVERT${C.reset} — ${reason}`);
+            console.log(`    ${dim(''.padEnd(12))} ${dim('sending this now would burn gas and change nothing.')}`);
+        }
+        return { status: 'would-revert', reason };
+    }
+}
+/**
+ * The one send choke point for a SINGLE already-prepared write: `--dry-run` preview (nothing sent,
+ * returns `null`) → optional `--confirm` prompt → lane selection → `signTx`. Every caller — an
+ * owner-op's `runWrite`/`runMinterWrite`, or the deploy family's resumed-setup send — resolves to
+ * this, so the two families can never again each carry their own (possibly diverging) idea of what
+ * `--dry-run` or `--confirm` means. The historical bug class this forecloses structurally: a write
+ * reaching the send lane under `--dry-run` because some caller re-derived the check by hand and
+ * missed a branch.
+ */
+export async function gatedSend(provider, flags, opts) {
+    if (isDryRun(flags)) {
+        const prepared = await resolveProvider(provider, opts.expectedSigner ?? zeroAddress);
+        if (flags.json !== undefined) {
+            const simulation = await simulateDryRun(prepared, opts.chainKey, opts.expectedSigner, false);
+            console.log(JSON.stringify({
+                dryRun: true,
+                sent: false,
+                lane: laneFromFlags(flags),
+                expectedSigner: opts.expectedSigner ?? null,
+                transaction: prepared,
+                simulation,
+            }, null, 2));
+        }
+        else {
+            printDryRunPreview(prepared, opts.expectedSigner);
+            await simulateDryRun(prepared, opts.chainKey, opts.expectedSigner);
+            console.log(dim(`\n  Re-run without --dry-run to send (lane: ${laneFromFlags(flags)}).\n`));
+        }
+        return null;
+    }
+    await assertChainId(opts.chainKey); // verify the RPC really is the target chain before any irreversible write
+    const preview = await resolveProvider(provider, opts.expectedSigner ?? zeroAddress);
+    await confirmSend(preview.summary, flags);
+    return signTx(provider, {
+        lane: laneFromFlags(flags),
+        chainKey: opts.chainKey,
+        expectedSigner: opts.expectedSigner,
+        yes: !!flags.yes,
+        port: flags.port ? Number(flags.port) : undefined,
+        signUrlFile: flags['sign-url-file'],
+    });
+}
+//# sourceMappingURL=riskgate.js.map

package/dist/riskgate.js.map

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

package/dist/scaffold.d.ts

@@ -0,0 +1,12 @@
+/** The file whose presence means the renderer copy genuinely happened (not just `mkdir`). */
+export declare const SCAFFOLD_ANCHOR: string;
+/**
+ * Copy the scaffold at `src` into `dir`, omitting build/dependency dirs.
+ *
+ * Throws if the copy produced no files — the caller must not print a success banner over an empty
+ * directory. Returns nothing on success; `anchor` is guaranteed to exist relative to `dir`.
+ */
+export declare function copyScaffold(src: string, dir: string, anchor: string): void;
+/** @deprecated thin wrapper kept for the existing call sites/tests — prefer {@link copyScaffold}. */
+export declare function copyRendererScaffold(src: string, dir: string): void;
+//# sourceMappingURL=scaffold.d.ts.map

package/dist/scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"AA6BA,6FAA6F;AAC7F,eAAO,MAAM,eAAe,QAAgC,CAAC;AAE7D;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAiB3E;AAED,qGAAqG;AACrG,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAEnE"}

package/dist/scaffold.js

@@ -0,0 +1,56 @@
+/**
+ * Copying the bundled renderer scaffold onto a creator's disk.
+ *
+ * This lives in its own module because the inline version of it shipped broken for six releases
+ * (alpha.9 → alpha.14) and could not be reproduced in a dev checkout. `abx scaffold-renderer`
+ * created the directory, printed the whole success walkthrough, exited 0, and wrote **zero files** —
+ * for every user, on every invocation form, while working perfectly for us.
+ *
+ * The cause was a path filter that judged absolute paths:
+ *
+ *     filter: (s) => !/(^|\/)(out|cache|dependencies|broadcast|node_modules)(\/|$)/.test(s)
+ *
+ * `cpSync` hands `filter` ABSOLUTE source paths. An installed CLI lives at
+ * `…/node_modules/@artblocks/abx-cli/assets/renderer-scaffold`, so that pattern matched the source
+ * ROOT — `cpSync` skips a directory's entire subtree when the directory itself is filtered out, and
+ * silently copies nothing rather than erroring. A dev checkout's path
+ * (`…/plan/abx/packages/cli/assets/…`) contains no `node_modules`, so every test we ran passed.
+ *
+ * Two rules follow, and the tests in `test/scaffold.test.ts` pin both:
+ *   1. Judge paths RELATIVE to the source root, never the absolute string.
+ *   2. Never report success without asserting the output actually landed.
+ */
+import { cpSync, existsSync, mkdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+/** Build/dependency dirs that must never ride along into a fresh scaffold. Matched against the
+ *  path RELATIVE to the scaffold root — see the module note. */
+const SKIP_DIR = /^(out|cache|dependencies|broadcast|node_modules)(\/|$)/;
+/** The file whose presence means the renderer copy genuinely happened (not just `mkdir`). */
+export const SCAFFOLD_ANCHOR = join('src', 'MyRenderer.sol');
+/**
+ * Copy the scaffold at `src` into `dir`, omitting build/dependency dirs.
+ *
+ * Throws if the copy produced no files — the caller must not print a success banner over an empty
+ * directory. Returns nothing on success; `anchor` is guaranteed to exist relative to `dir`.
+ */
+export function copyScaffold(src, dir, anchor) {
+    mkdirSync(dir, { recursive: true });
+    cpSync(src, dir, {
+        recursive: true,
+        filter: (s) => {
+            // Normalise separators so the same pattern holds on Windows.
+            const rel = relative(src, s).split(/[/\\]/).join('/');
+            return rel === '' || !SKIP_DIR.test(rel);
+        },
+    });
+    if (!existsSync(join(dir, anchor))) {
+        throw new Error(`scaffold copy wrote no files into ${dir} (expected ${anchor}) — nothing was written, ` +
+            `so don't build here. Scaffold source: ${src}. ` +
+            `Please report this along with your install path: https://docs.abx.io`);
+    }
+}
+/** @deprecated thin wrapper kept for the existing call sites/tests — prefer {@link copyScaffold}. */
+export function copyRendererScaffold(src, dir) {
+    copyScaffold(src, dir, SCAFFOLD_ANCHOR);
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/scaffold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAC,MAAM,SAAS,CAAC;AACtD,OAAO,EAAC,IAAI,EAAE,QAAQ,EAAC,MAAM,WAAW,CAAC;AAEzC;gEACgE;AAChE,MAAM,QAAQ,GAAG,wDAAwD,CAAC;AAE1E,6FAA6F;AAC7F,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC;AAE7D;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW,EAAE,GAAW,EAAE,MAAc;IACnE,SAAS,CAAC,GAAG,EAAE,EAAC,SAAS,EAAE,IAAI,EAAC,CAAC,CAAC;IAClC,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE;QACf,SAAS,EAAE,IAAI;QACf,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE;YACZ,6DAA6D;YAC7D,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACtD,OAAO,GAAG,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC3C,CAAC;KACF,CAAC,CAAC;IACH,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CACb,qCAAqC,GAAG,cAAc,MAAM,2BAA2B;YACrF,yCAAyC,GAAG,IAAI;YAChD,sEAAsE,CACzE,CAAC;IACJ,CAAC;AACH,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,oBAAoB,CAAC,GAAW,EAAE,GAAW;IAC3D,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,eAAe,CAAC,CAAC;AAC1C,CAAC"}

package/dist/schema.d.ts

@@ -1,15 +1,50 @@
-import type { Hex } from 'viem';
+import type { Address, Hex } from 'viem';
+/** The `--schema` type/auth/format catalog, shown wherever the CLI nudges `--schema`. Kept accurate
+ *  to the on-chain enums (PARAM_TYPES / AUTH_OPTIONS) + the Select-options / Range-bounds format —
+ *  the old hint advertised non-existent `Anyone`/`Admin` auth legs. Used by both `deploy-code`
+ *  (commands/deploy.ts) and `inspect` (commands/reads.ts), so it lives here beside the rest of the
+ *  `--schema` machinery rather than in either command module. */
+export declare const SCHEMA_CATALOG: string;
 export interface ParsedSchema {
     key: string;
     paramType: number;
     auth: number;
+    /** Required by (and only valid for) an Address-bearing auth leg; the contract pairs them strictly. */
+    authAddress: Address;
+    /** Unix seconds after which the VALUE can no longer change. 0 = never locks. A timestamp in the
+     *  past locks it immediately and permanently — that is the supported way to retire a parameter. */
+    lockAfter: number;
     min: Hex;
     max: Hex;
     selectOptions: string[];
 }
+/**
+ * A point in time for `lock=`: unix seconds, an ISO date, or `now` (which means "immediately and
+ * forever" — the retire idiom). Reuses the Timestamp encoder so `lock=2026-12-31` parses exactly
+ * like a `Timestamp[..]` bound does; one date grammar for the whole flag.
+ */
+export declare function parseWhen(raw: string): number;
 export declare function parseSchemaSpec(spec: string): ParsedSchema;
 /** Parse a full `--schema` value: comma-separated specs. */
 export declare function parseSchemaSpecs(raw: string | undefined): ParsedSchema[];
+/** The advisory an EDITION deploy needs before it commits to a schema, or `null` when there is
+ *  nothing to say. Returned rather than printed so the deploy lane decides where it lands.
+ *
+ *  Two things are true on an ERC-1155 edition and on nothing else, and a creator setting up their
+ *  first collector-configurable drop will not have thought about either:
+ *
+ *   1. **Params are per id, so every holder of that id shares one value.** `TokenOwner` means ANY
+ *      holder, and it is last-writer-wins. A "name your copy" schema does not name a copy — it
+ *      renames the work for all 1,000 holders.
+ *   2. **A data param has no on-chain size budget.** One holder can store a large valid value under
+ *      every declared key and make the shared id's `tokenURI` too expensive for common RPC limits —
+ *      for every co-holder, permanently if a `lockAfter` then bites. That is a deliberate protocol
+ *      choice (byte accounting on chain would cost every project to police a configuration almost
+ *      nobody should use), which makes saying it here the actual mitigation.
+ *
+ *  Both are fine when intended: a 1-of-1 edition behaves like a 721, and aggregate state (a counter,
+ *  a shared mood) is exactly what shared params are good at. */
+export declare function editionSchemaAdvisory(schemas: ParsedSchema[]): string | null;
 /** A human one-line rendering of a parsed schema (for the confirm readout). */
 export declare function describeSchema(s: ParsedSchema): string;
 //# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAC,GAAG,EAAC,MAAM,MAAM,CAAC;AAO9B,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,GAAG,CAAC;IACT,GAAG,EAAE,GAAG,CAAC;IACT,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAQD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAyD1D;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,EAAE,CAMxE;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAWtD"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAC,OAAO,EAAE,GAAG,EAAC,MAAM,MAAM,CAAC;AAIvC;;;;iEAIiE;AACjE,eAAO,MAAM,cAAc,QAI+B,CAAC;AAK3D,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,sGAAsG;IACtG,WAAW,EAAE,OAAO,CAAC;IACrB;uGACmG;IACnG,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,GAAG,CAAC;IACT,GAAG,EAAE,GAAG,CAAC;IACT,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAID;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAU7C;AAQD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CA2F1D;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,EAAE,CAMxE;AAED;;;;;;;;;;;;;;;;gEAgBgE;AAChE,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,GAAG,IAAI,CA0B5E;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAatD"}

package/dist/schema.js

@@ -19,10 +19,40 @@
  * outer delimiters appear there. Omit the bracket on a Range → unbounded (min=max=0, the prior
  * behavior). A Select with no bracket, or a bracket on a type that takes none, is a clear error.
  */
-import { PARAM_TYPES, AUTH_OPTIONS, encodeScalarParam } from '@artblocks/abx-sdk';
+import { PARAM_TYPES, AUTH_OPTIONS, decodeScalarParam, encodeScalarParam } from '@artblocks/abx-sdk';
 const ZERO32 = `0x${'0'.repeat(64)}`;
+/** The `--schema` type/auth/format catalog, shown wherever the CLI nudges `--schema`. Kept accurate
+ *  to the on-chain enums (PARAM_TYPES / AUTH_OPTIONS) + the Select-options / Range-bounds format —
+ *  the old hint advertised non-existent `Anyone`/`Admin` auth legs. Used by both `deploy-code`
+ *  (commands/deploy.ts) and `inspect` (commands/reads.ts), so it lives here beside the rest of the
+ *  `--schema` machinery rather than in either command module. */
+export const SCHEMA_CATALOG = 'Types: Bool·Select·Uint256Range·Int256Range·DecimalRange·HexColor·Timestamp·String·Bytes; ' +
+    'Auth: Creator·TokenOwner·Address (or the Or-combos, e.g. CreatorOrTokenOwner). ' +
+    "Select needs options — quote the whole spec: 'key:Select[A|B|C]:Auth'; a Range takes bounds — 'key:Uint256Range[0..100]:Auth'. " +
+    'A palette collectors set = palette:HexColor:TokenOwner';
 /** The types that accept a `[min..max]` bound (the contract's min/max fields are meaningful here). */
 const BOUNDED_TYPES = new Set(['Uint256Range', 'Int256Range', 'DecimalRange', 'Timestamp']);
+const ZERO_ADDR = '0x0000000000000000000000000000000000000000';
+/**
+ * A point in time for `lock=`: unix seconds, an ISO date, or `now` (which means "immediately and
+ * forever" — the retire idiom). Reuses the Timestamp encoder so `lock=2026-12-31` parses exactly
+ * like a `Timestamp[..]` bound does; one date grammar for the whole flag.
+ */
+export function parseWhen(raw) {
+    const t = raw.trim();
+    if (t === '')
+        throw new Error('lock= needs a value (unix seconds, an ISO date, or `now`)');
+    // `now` locks on the next block. Anything already past is equally permanent — the contract's test
+    // is `block.timestamp > lockAfter`.
+    if (t.toLowerCase() === 'now')
+        return Math.floor(Date.now() / 1000) - 1;
+    const secs = Number(BigInt(encodeScalarParam('Timestamp', t, []).value));
+    if (!Number.isSafeInteger(secs) || secs < 0)
+        throw new Error(`bad time "${raw}"`);
+    if (secs > 0xffffffffffff)
+        throw new Error(`"${raw}" exceeds the uint48 lock field`);
+    return secs;
+}
 /** min ≤ max in the type's own ordering (mirrors AbxParamsLib's on-chain check, but earlier + clearer). */
 function orderedBounds(typeName, min, max) {
     if (typeName === 'Int256Range')
@@ -31,33 +61,65 @@ function orderedBounds(typeName, min, max) {
 }
 export function parseSchemaSpec(spec) {
     const parts = spec.split(':');
-    if (parts.length !== 3) {
-        throw new Error(`--schema "${spec}" — expected key:Type:Auth (a Select adds options: key:Select[A|B|C]:Auth; a Range adds bounds: key:Uint256Range[0..100]:Auth).`);
+    if (parts.length !== 3 && parts.length !== 4) {
+        throw new Error(`--schema "${spec}" — expected key:Type:Auth (a Select adds options: key:Select[A|B|C]:Auth; a Range adds bounds: key:Uint256Range[0..100]:Auth; add :lock=<when> to freeze the value after a date).`);
+    }
+    const [key, typeToken, authToken, lockToken] = parts;
+    // A 4th field is ONLY ever `lock=…`. Anything else there means a colon leaked out of a label or
+    // bound and split the spec wrong — report that as the shape error it is, rather than letting the
+    // mangled fragments fail later with a confusing "malformed type".
+    if (lockToken !== undefined && !/^lock=/.test(lockToken)) {
+        throw new Error(`--schema "${spec}" — expected key:Type:Auth (with an optional 4th field, lock=<when>). ` +
+            `Got ${parts.length} colon-separated fields: a ':' inside a Select option or a bound splits the spec — use simpler labels.`);
     }
-    const [key, typeToken, authName] = parts;
     const m = typeToken.match(/^([A-Za-z0-9]+)(?:\[(.*)\])?$/);
     if (!key || !m)
         throw new Error(`--schema "${spec}" — malformed type "${typeToken}".`);
     const typeName = m[1];
     const bracket = m[2]; // undefined when there is no [...]
     const paramType = PARAM_TYPES.indexOf(typeName);
+    // An Address-bearing leg names its holder inline: `Address(0x…)`, `CreatorOrAddress(0x…)`. The
+    // contract pairs auth and authAddress strictly (one without the other reverts InvalidParamSchema),
+    // so they belong in one token rather than a second flag that could be forgotten.
+    const am = authToken.match(/^([A-Za-z]+)(?:\((0x[0-9a-fA-F]{40})\))?$/);
+    if (!am)
+        throw new Error(`--schema "${spec}" — malformed auth "${authToken}" (an Address leg looks like Address(0x…)).`);
+    const authName = am[1];
     const auth = AUTH_OPTIONS.indexOf(authName);
     if (paramType < 0 || auth < 0) {
         throw new Error(`--schema "${spec}" — Type ∈ {${PARAM_TYPES.join('|')}}, Auth ∈ {${AUTH_OPTIONS.join('|')}}.`);
     }
-    if (AUTH_OPTIONS[auth].includes('Address')) {
-        throw new Error(`--schema "${spec}" — Address-auth legs need an authAddress; set that schema post-deploy via the contract.`);
+    const wantsAddress = AUTH_OPTIONS[auth].includes('Address');
+    const authAddress = (am[2] ?? ZERO_ADDR);
+    if (wantsAddress && authAddress === ZERO_ADDR) {
+        throw new Error(`--schema "${spec}" — ${authName} names a specific writer, so it needs one: ${key}:${typeToken}:${authName}(0xYourAddress). ` +
+            `A CONTRACT may hold this leg — that is how open/multi-party participation is built (a controller applies its own rules and forwards the write).`);
+    }
+    if (!wantsAddress && am[2]) {
+        throw new Error(`--schema "${spec}" — ${authName} takes no address; only an Address-bearing leg does.`);
+    }
+    let lockAfter = 0;
+    if (lockToken !== undefined) {
+        const lm = lockToken.match(/^lock=(.*)$/);
+        if (!lm)
+            throw new Error(`--schema "${spec}" — the 4th field must be lock=<when> (unix seconds, an ISO date, or "now").`);
+        try {
+            lockAfter = parseWhen(lm[1]);
+        }
+        catch (e) {
+            throw new Error(`--schema "${spec}" — ${e.message}`);
+        }
     }
     let min = ZERO32;
     let max = ZERO32;
     let selectOptions = [];
     if (typeName === 'Select') {
         if (bracket === undefined) {
-            throw new Error(`--schema "${spec}" — a Select needs its options: ${key}:Select[Option A|Option B|Option C]:${authName}.`);
+            throw new Error(`--schema "${spec}" — a Select needs its options: '${key}:Select[Option A|Option B|Option C]:${authName}' (quote the whole value in the shell).`);
         }
         selectOptions = bracket.split('|').map((o) => o.trim());
         if (selectOptions.length === 0 || selectOptions.some((o) => o === '')) {
-            throw new Error(`--schema "${spec}" — Select options must be non-empty, e.g. ${key}:Select[A|B|C]:${authName}.`);
+            throw new Error(`--schema "${spec}" — Select options must be non-empty, e.g. '${key}:Select[A|B|C]:${authName}'.`);
         }
         if (new Set(selectOptions).size !== selectOptions.length) {
             throw new Error(`--schema "${spec}" — duplicate Select option in [${selectOptions.join('|')}].`);
@@ -73,7 +135,7 @@ export function parseSchemaSpec(spec) {
         }
         const mm = bracket.split('..');
         if (mm.length !== 2)
-            throw new Error(`--schema "${spec}" — bounds are [min..max], e.g. ${key}:${typeName}[0..100]:${authName}.`);
+            throw new Error(`--schema "${spec}" — bounds are [min..max], e.g. '${key}:${typeName}[0..100]:${authName}'.`);
         try {
             min = encodeScalarParam(typeName, mm[0].trim(), []).value;
             max = encodeScalarParam(typeName, mm[1].trim(), []).value;
@@ -85,7 +147,7 @@ export function parseSchemaSpec(spec) {
             throw new Error(`--schema "${spec}" — min must be ≤ max (got ${mm[0].trim()}..${mm[1].trim()}).`);
         }
     }
-    return { key, paramType, auth, min, max, selectOptions };
+    return { key, paramType, auth, authAddress, lockAfter, min, max, selectOptions };
 }
 /** Parse a full `--schema` value: comma-separated specs. */
 export function parseSchemaSpecs(raw) {
@@ -95,6 +157,50 @@ export function parseSchemaSpecs(raw) {
         .filter(Boolean)
         .map(parseSchemaSpec);
 }
+/** The advisory an EDITION deploy needs before it commits to a schema, or `null` when there is
+ *  nothing to say. Returned rather than printed so the deploy lane decides where it lands.
+ *
+ *  Two things are true on an ERC-1155 edition and on nothing else, and a creator setting up their
+ *  first collector-configurable drop will not have thought about either:
+ *
+ *   1. **Params are per id, so every holder of that id shares one value.** `TokenOwner` means ANY
+ *      holder, and it is last-writer-wins. A "name your copy" schema does not name a copy — it
+ *      renames the work for all 1,000 holders.
+ *   2. **A data param has no on-chain size budget.** One holder can store a large valid value under
+ *      every declared key and make the shared id's `tokenURI` too expensive for common RPC limits —
+ *      for every co-holder, permanently if a `lockAfter` then bites. That is a deliberate protocol
+ *      choice (byte accounting on chain would cost every project to police a configuration almost
+ *      nobody should use), which makes saying it here the actual mitigation.
+ *
+ *  Both are fine when intended: a 1-of-1 edition behaves like a 721, and aggregate state (a counter,
+ *  a shared mood) is exactly what shared params are good at. */
+export function editionSchemaAdvisory(schemas) {
+    const holderWritable = schemas.filter((s) => {
+        const auth = AUTH_OPTIONS[s.auth];
+        return auth === 'TokenOwner' || auth === 'CreatorOrTokenOwner' || auth === 'TokenOwnerOrAddress'
+            || auth === 'CreatorOrTokenOwnerOrAddress';
+    });
+    if (holderWritable.length === 0)
+        return null;
+    const keys = holderWritable.map((s) => s.key).join(', ');
+    const data = holderWritable.filter((s) => {
+        const t = PARAM_TYPES[s.paramType];
+        return t === 'String' || t === 'Bytes';
+    });
+    const sizeNote = data.length
+        ? ` ${data.map((s) => s.key).join(', ')} ${data.length === 1 ? 'is' : 'are'} a DATA type with no on-chain size cap, so one holder can also make this id's metadata too large for many RPCs to read — for everyone, and permanently if you later lock it.`
+        : '';
+    // `seed` is the sharpest case of the shared-state rule and worth calling out by name: it is normally
+    // settled-once and immutable, but a holder-writable `seed` schema re-opens it — so any holder of the
+    // id can re-roll the GENERATIVE seed, changing the rendered artwork for every co-holder of the work.
+    // "Each collector picks their own seed" is a 721 idea; on an edition it is "any holder re-rolls
+    // everyone's". Almost never intended; a controller contract on the Address leg is the safe shape.
+    const hasSeed = holderWritable.some((s) => s.key === 'seed');
+    const seedNote = hasSeed
+        ? ' seed is holder-writable here: the generative seed is normally immutable, but this lets ANY holder of the id re-roll it and change the artwork for every co-holder. If you want per-collector seeds, that is one id per copy; if you want it governed, put a controller contract on an Address leg.'
+        : '';
+    return `holder-writable on an edition: ${keys} — params belong to the ID, so every holder of that id shares one value and the last writer wins. If you meant "each collector configures their own", that needs one id per copy.${sizeNote}${seedNote}`;
+}
 /** A human one-line rendering of a parsed schema (for the confirm readout). */
 export function describeSchema(s) {
     const type = PARAM_TYPES[s.paramType];
@@ -103,23 +209,12 @@ export function describeSchema(s) {
     if (type === 'Select')
         detail = `[${s.selectOptions.join(' | ')}]`;
     else if (s.min !== ZERO32 || s.max !== ZERO32) {
-        const lo = decodeBound(type, s.min);
-        const hi = decodeBound(type, s.max);
+        const lo = decodeScalarParam(type, s.min);
+        const hi = decodeScalarParam(type, s.max);
         detail = `[${lo}..${hi}]`;
     }
-    return `${s.key}:${type}${detail}:${auth}`;
-}
-function decodeBound(typeName, v) {
-    // Cheap display-only decode (the SDK's decodeScalarParam is the canonical one, but this keeps the
-    // readout dependency-light for the two Range cases that matter in a bound).
-    if (typeName === 'Int256Range')
-        return BigInt.asIntN(256, BigInt(v)).toString();
-    if (typeName === 'DecimalRange') {
-        const scaled = BigInt(v);
-        const whole = scaled / 10000000000n;
-        const frac = (scaled % 10000000000n).toString().padStart(10, '0').replace(/0+$/, '');
-        return frac ? `${whole}.${frac}` : `${whole}`;
-    }
-    return BigInt(v).toString();
+    const who = s.authAddress && s.authAddress !== ZERO_ADDR ? `(${s.authAddress})` : '';
+    const lock = s.lockAfter ? `:lock=${new Date(s.lockAfter * 1000).toISOString().slice(0, 19)}Z` : '';
+    return `${s.key}:${type}${detail}:${auth}${who}${lock}`;
 }
 //# sourceMappingURL=schema.js.map