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

package/dist/ownerops.js

@@ -10,15 +10,18 @@ import { MAX_ROYALTY_BPS, assertChainId, ensureChunkStore as sdkEnsureChunkStore
 import { encodeScalarParam, encodeTag as encodeTagSdk, isAccepted, prepareConfigureTokenParam, prepareConfigureTokenParamData, prepareSetContractParam, prepareSetContractParamData, seriesCodeAbi, tryReadContract, } from '@artblocks/abx-sdk';
 import { hasParamEnumeration, GATEWAY_FIELD, GATEWAY_FLOOR, gatewayPrefixFrom, readCollectionPolicy, readEnv } from '@artblocks/abx-sdk';
 import { decodeFieldRenderer, encodeFieldRenderer, resolveGenerator, DEP_RESOLUTION, parseDependencyRef, prepareLockDependencies, prepareLockParamHooks, prepareLockScript, prepareRemoveLastDependency, prepareSetDependency, prepareSetDependencyRegistry, } from '@artblocks/abx-sdk';
+import { planScriptReplace, prepareRemoveLastScriptChunk, prepareSetScriptChunk, verifyScriptReplace, } from '@artblocks/abx-sdk';
 import { contentTypeFromPath } from '@artblocks/abx-storage';
 import { toHex as toHexSdk } from 'viem';
-import { readFileSync } from 'node:fs';
+import { existsSync, 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 { backendResolution, CHAIN, chainId, fixedPriceMinterAddress, fixedPriceMinter1155Address, localIndexer } from './config.js';
 import { CliError } from './errors.js';
-import { detectTokenKind, isEditionContract, assertHasParamsSurface } from './kind.js';
+import { detectTokenKind, isEditionContract, assertHasParamsSurface, hasParamsSurface } from './kind.js';
+import { planOnChainScript } from './script-chunks.js';
+import { fetchServedTokenUri, servedOk } from './served.js';
 import { openWalletSession } from './signer.js';
 import { gatedSend, laneFromFlags } from './riskgate.js';
 import { withJson } from './jsonout.js';
@@ -30,11 +33,12 @@ import { parseSchemaSpecs, describeSchema } from './schema.js';
 // definition below).
 export { ONCHAIN_PROJECT_SOFT_LIMIT, ONCHAIN_READ_WARN_BYTES, ETH_CALL_GAS_FLOOR, tokenUriGasEstimate, readableBytesAtGas };
 // ── ANSI (local) ─────────────────────────────────────────────────────────────
-const C = { reset: '\x1b[0m', dim: '\x1b[2m', bold: '\x1b[1m', green: '\x1b[38;5;115m', yellow: '\x1b[38;5;221m' };
+const C = { reset: '\x1b[0m', dim: '\x1b[2m', bold: '\x1b[1m', green: '\x1b[38;5;115m', yellow: '\x1b[38;5;221m', red: '\x1b[31m' };
 const dim = (s) => `${C.dim}${s}${C.reset}`;
 const green = (s) => `${C.green}${s}${C.reset}`;
 const yellow = (s) => `${C.yellow}${s}${C.reset}`;
 const bold = (s) => `${C.bold}${s}${C.reset}`;
+const red = (s) => `${C.red}${s}${C.reset}`;
 // ── data plane: attach files, and the keys you can't set by hand ──────────────
 // A token anchors named, typed files ("artifacts"). The served JSON's `artifacts` list is the
 // COMPLETE set — but it's COMPUTED by the resolver/renderer from the token's fields + effect
@@ -532,6 +536,139 @@ export async function cmdLockScript(address, flags) {
     console.log(dim('  that is not the same as a frozen OUTPUT: params stay writable and a Registry dependency is re-fetched live, so say "locked metadata" to a buyer, not "immutable".'));
     await runWrite(contract, prepareLockScript({ contract, chainId: chainId() }), flags, owner);
 }
+/** Flags `abx replace-script` recognizes — anything else warns (non-fatal). */
+const REPLACE_SCRIPT_FLAGS = [...SHARED_WRITE_FLAGS, 'script', 'chunk-size'];
+/** A `ScriptChunkReader` backed by a real chain read — the only place `replace-script` touches
+ *  `seriesCodeAbi` directly, so `planScriptReplace`/`verifyScriptReplace` themselves stay chain-free
+ *  and testable (see packages/sdk/src/script-chunks.ts). `scriptChunk` returns `null` on a revert
+ *  (an index at/past the CURRENT on-chain count) rather than throwing — exactly what both SDK
+ *  functions expect for "nothing stored here yet". */
+function chainScriptReader(contract) {
+    const client = makePublicClient({ chainKey: CHAIN });
+    return {
+        scriptChunkCount: async () => Number(await client.readContract({ address: contract, abi: seriesCodeAbi, functionName: 'scriptChunkCount' })),
+        scriptChunk: async (index) => {
+            try {
+                return (await client.readContract({ address: contract, abi: seriesCodeAbi, functionName: 'scriptChunk', args: [BigInt(index)] }));
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}
+/**
+ * `abx replace-script <address> --script <path>` — the safe, first-class way to replace an
+ * UNLOCKED code project's on-chain program (#119). `OnChainScript.sol` permits `setScriptChunk`/
+ * `removeLastScriptChunk` right up until `lock-script` — but before this command the only writer
+ * was `deploy-code` (its initial setup, or its `--resume` leg for a setup that never landed).
+ * Neither is "replace a program that's already live and correct on-chain", which is the gap this
+ * closes: a creator iterating on a generative project pre-lock had no supported way to ship a fix.
+ *
+ * Safety properties, in the order they're enforced:
+ *   1. REFUSE outright — never warn-and-proceed — on a locked script or a non-code target. Both are
+ *      "there is nothing here for this command to safely do", not "proceed with caution".
+ *   2. Diff by CONTENT against what's on-chain now ({@link planScriptReplace}, mirroring
+ *      `resume.ts`'s script-chunk leg) so an index that already matches is never re-sent — SSTORE2
+ *      deposit is 200 gas/byte, so a needless re-store is the most expensive way to be "safe".
+ *   3. Every write AND every remove rides in ONE atomic `multicall` (`batchOps`, the same primitive
+ *      `abx attach` uses for its own all-or-nothing guarantee). This is what makes "half-applied"
+ *      structurally impossible from this command's own send: a revert undoes everything, a success
+ *      lands everything. Writes are ordered before removes — the retained indices get their correct
+ *      content before the tail is trimmed, so the intermediate calldata sequence never shrinks the
+ *      script before it's right (the two groups touch disjoint indices, so this is a documentation
+ *      choice about intent, not a correctness requirement of the atomic call itself).
+ *   4. After a real send, READ THE SCRIPT BACK and verify it reassembles EXACTLY to the source file
+ *      ({@link verifyScriptReplace}) before reporting success. A transaction not reverting proves the
+ *      EVM accepted each call; it does not prove the final program is what was intended. This is the
+ *      step that actually justifies the command existing — skip it and "replace-script" is just
+ *      "send some txs and hope".
+ *
+ * `--dry-run`/`--sign`/`--unsigned` all route through the shared `runWrite`/`gatedSend` choke point
+ * (the same one every owner-op uses), so a dry run sends nothing, per the house invariant.
+ */
+export async function cmdReplaceScript(address, flags) {
+    const usage = 'abx replace-script <address> --script <path> [--chunk-size <bytes>] [--sign|--unsigned] [--dry-run]';
+    const contract = requireAddress(address, usage);
+    warnStrayFlags(flags, new Set(REPLACE_SCRIPT_FLAGS), 'replace-script');
+    const scriptPath = requireFlag(flags, 'script', usage);
+    if (!existsSync(scriptPath)) {
+        throw new Error(`no file at ${scriptPath} — pass the path to the replacement program (the same --script a deploy-code would take).`);
+    }
+    const source = readFileSync(scriptPath, 'utf8');
+    // REFUSE (not warn) on a target this command cannot safely act on — before any signing prompt.
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    const kind = await detectTokenKind(publicClient, contract);
+    if (!hasParamsSurface(kind)) {
+        throw new Error(`${contract} is a ${kind.label} — replace-script only applies to a SeriesCode/EditionCode on-chain program ` +
+            `(the OnChainScript extension). ${kind.label} has no script to replace.`);
+    }
+    const scriptLocked = (await publicClient.readContract({ address: contract, abi: seriesCodeAbi, functionName: 'scriptLocked' }));
+    if (scriptLocked) {
+        throw new Error(`${contract}'s script is LOCKED (\`abx lock-script\` was already sent) — setScriptChunk/removeLastScriptChunk ` +
+            `revert forever, on-chain, for everyone. There is no way to replace it; that refusal IS the safety property ` +
+            `lock-script exists to guarantee, so this command does not attempt a workaround.`);
+    }
+    const owner = await read(contract, 'owner');
+    const chunkSize = flags['chunk-size'] !== undefined ? Number(flags['chunk-size']) : undefined;
+    if (chunkSize !== undefined && (!Number.isFinite(chunkSize) || chunkSize < 1)) {
+        throw new Error(`--chunk-size must be a positive integer, got "${flags['chunk-size']}"`);
+    }
+    const nextChunks = planOnChainScript(source, chunkSize);
+    if (nextChunks.length === 0) {
+        console.log(yellow('  ⚠ ') + `${scriptPath} is empty — this will REMOVE every existing script chunk, leaving no program on-chain. Ctrl-C now if that's not what you meant.`);
+    }
+    const reader = chainScriptReader(contract);
+    const plan = await planScriptReplace(reader, nextChunks);
+    console.log(`  script: ${plan.currentCount} chunk(s) on-chain → ${plan.targetCount} chunk(s) in ${scriptPath}`);
+    if (plan.noop) {
+        console.log(`  ${green('✓')} no-op — the on-chain script already matches ${scriptPath} byte-for-byte. Nothing to send.`);
+        return;
+    }
+    if (plan.toWrite.length) {
+        console.log(dim(`    write ${plan.toWrite.length} chunk(s): index ${plan.toWrite.map((w) => w.index).join(', ')}`));
+    }
+    if (plan.toRemove) {
+        console.log(dim(`    remove ${plan.toRemove} trailing chunk(s) — shrinking ${plan.currentCount} → ${plan.targetCount} (removeLastScriptChunk has no "remove N"; this is ${plan.toRemove} queued call(s))`));
+    }
+    // Writes before removes (see the function doc for why this ordering, not the reverse). Both
+    // groups fold into ONE multicall below — that's what makes a half-applied result impossible from
+    // this command's own send, not the ordering.
+    const ops = [
+        ...plan.toWrite.map((w) => prepareSetScriptChunk({ contract, index: w.index, chunk: w.hex, chainId: chainId() })),
+        ...Array.from({ length: plan.toRemove }, () => prepareRemoveLastScriptChunk({ contract, chainId: chainId() })),
+    ];
+    const batched = batchOps(ops);
+    if (batched.length !== 1) {
+        // Defensive: every op above targets the SAME contract and carries no value, so batchOps must
+        // fold them to exactly one multicall. If that ever changes, fail loudly rather than send N
+        // separate transactions with no atomicity — the one property this command exists to guarantee.
+        throw new Error(`replace-script expected to batch ${ops.length} op(s) into one transaction, got ${batched.length}`);
+    }
+    // `batchOps`/`prepareMulticall` don't sum a folded gasFloor from their sub-ops (each PER-CHUNK
+    // gasFloor is real physics — see prepareSetScriptChunk's own doc — but is dropped once several
+    // ops merge into one multicall PreparedTx). Restate it here so the eth_estimateGas sanity check
+    // still fires for a replacement that stores real bytes.
+    const depositBytes = plan.toWrite.reduce((sum, w) => sum + (w.hex.length - 2) / 2, 0);
+    const tx = depositBytes > 0 ? { ...batched[0], gasFloor: `0x${(depositBytes * 200).toString(16)}` } : batched[0];
+    const sent = await runWrite(contract, tx, flags, owner);
+    if (!sent)
+        return; // dry run, or the cold lane — nothing landed to verify yet
+    const verify = await verifyScriptReplace(reader, source);
+    if (!verify.ok) {
+        console.error(`\n  ${red('✗')} VERIFICATION FAILED — the on-chain script does NOT reassemble to ${scriptPath} after this write.\n` +
+            `  on-chain now reports ${verify.chunkCount} chunk(s) (wanted ${plan.targetCount}). This can mean the write only\n` +
+            `  partially landed, or something else wrote to this contract concurrently — either way, DO NOT assume the\n` +
+            `  program is what you intended.\n` +
+            `  Way forward: re-run \`abx replace-script ${contract} --script ${scriptPath}\` — it re-diffs against whatever\n` +
+            `  is ACTUALLY on-chain now and sends only what's still missing or wrong; it will not resend what already matches.\n` +
+            `  Inspect by hand: abx tokenuri ${contract} --fetch  (or scriptChunkCount/scriptChunk directly).\n`);
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`  ${green('✓')} verified — the on-chain script reassembles EXACTLY to ${scriptPath} (${verify.chunkCount} chunk(s), ${source.length} bytes).\n` +
+        dim(`    this is the safety property \`abx lock-script ${contract}\` later makes permanent.`));
+}
 /** `abx lock-param-hooks <address>` — freeze the three param-lifecycle hook addresses forever.
  *  The sibling of lock-script/lock-dependencies/lock-uri, and the only one aimed at a BUYER rather
  *  than at metadata: the transfer hook is a veto over transfers and mints, so an unlocked hook set
@@ -1977,6 +2114,42 @@ async function reportUriAfterFieldWrite(contract, collection, flags) {
             `  a field renderer must NEVER revert.`);
     }
 }
+// ── attach: the canonical fetch URL + a real reachability probe (#127) ────────
+/**
+ * The exact, directly-fetchable URL for one attached key — `{base}/{chainId}/{address}[/{tokenId}]
+ * /data/{key}`, the token-api route grammar (`packages/token-api/src/server.ts`'s `/t` and `/c`
+ * routes). `base` already carries its OWN `/t` or `/c` prefix (see `TokenURI.sol`/`ContractURI.sol`
+ * — `deploy-code`/`deploy`/etc. bake `tokenURIBase = "${host}/t"`), so this never re-adds one.
+ * Exported so a creator or an agent never hand-assembles this from the docs — the exact gap #127
+ * reported (`attach` produced a bare path, not a URL anyone could actually GET).
+ */
+export function canonicalAttachmentUrl(opts) {
+    const base = opts.uriBase.replace(/\/+$/, '');
+    const coords = opts.tokenId === undefined ? `${opts.chainId}/${opts.contract}` : `${opts.chainId}/${opts.contract}/${opts.tokenId}`;
+    return `${base}/${coords}/data/${encodeURIComponent(opts.key)}`;
+}
+/**
+ * Is ANY resolver actually answering for this project right now — the precondition for an
+ * attachment to ever become fetchable, and the check `attach` never ran before #127 (it warned on
+ * an EMPTY resolver base, but a non-empty one that answered nothing got a silent, confident "listed
+ * in this project's resolver artifacts"). Reuses `cmdVerifyRemote`'s own GET-and-classify shape
+ * (`served.ts`'s `fetchServedTokenUri`) rather than a second HTTP client.
+ *
+ * Deliberately probes the token's (or collection's) OWN metadata document — NEVER the specific key
+ * being attached. That document already exists for any minted token; the key being attached here
+ * does not exist server-side until the write this gates on lands and the resolver re-indexes, so
+ * probing it directly would 404 on a perfectly healthy resolver and cry wolf on every attach.
+ */
+export async function probeResolverReachable(opts) {
+    const base = opts.uriBase.replace(/\/+$/, '');
+    const coords = opts.tokenId === undefined ? `${opts.chainId}/${opts.contract}` : `${opts.chainId}/${opts.contract}/${opts.tokenId}`;
+    const url = `${base}/${coords}`;
+    const served = await fetchServedTokenUri(url, { fetchFn: opts.fetchFn });
+    if (servedOk(served))
+        return { reachable: true, url, detail: `HTTP ${served.status}` };
+    const detail = served.error ? `no response: ${served.error}` : served.status !== null ? `HTTP ${served.status}` : (served.skipped ?? 'unreachable');
+    return { reachable: false, url, detail };
+}
 // ── attach (the data-plane verb: put a named file on a token) ─────────────────
 /**
  * `abx attach <address> <key> <uri>` — attach a named, typed file to a token (or the collection),
@@ -2085,24 +2258,46 @@ export async function cmdAttach(rest, flags) {
     for (const p of pairs) {
         console.log(`  attaching ${bold(p.key)} ${dim(`(${p.mimeType}, ${p.representation})`)} to ${scope}: ${dim(p.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".
-    // The on-chain renderer deliberately omits locator-represented artifacts (they duplicate no
-    // on-chain type information — see site/content/docs/protocol/data-plane.mdx), so the artifacts manifest comes
-    // from a RESOLVER. When the project has no resolver baked in, that is not a footnote, it is the
-    // difference between a feature working and not existing, so say it as a warning.
-    const uriBase = await read(contract, 'tokenURIBase').catch(() => '');
-    const artifactsPath = `/t/${chainId()}/${contract}/${flags.token ?? '0'}`;
+    // Where it surfaces — and whether anything can actually SERVE it (#127). This used to be one dim
+    // line assuming a non-empty resolver base meant the artifact would be listed; it never checked.
+    // An integrator attached five audio stems to a fully-on-chain token, paid to store them, and found
+    // `tokenURI` listed none of them — "paid for, stored on-chain, and invisible". The on-chain
+    // renderer deliberately omits locator-represented artifacts (they duplicate no on-chain type
+    // information — see site/content/docs/protocol/data-plane.mdx), so the complete artifacts manifest
+    // comes from a RESOLVER — and a resolver base baked on-chain is a CONFIGURATION, not proof one is
+    // actually running and knows this project. `--collection` reads the collection-scope base
+    // (`contractURIBase`); a token-scope attach reads `tokenURIBase` — these are two separate on-chain
+    // fields (the earlier version of this always read `tokenURIBase`, silently wrong for --collection).
+    const uriBase = await read(contract, collection ? 'contractURIBase' : 'tokenURIBase').catch(() => '');
+    const tokenIdForUrl = collection ? undefined : BigInt(flags.token ?? '0');
+    let reachability = null;
     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 only (params are chain state — read them with abx tokens).`));
+        // The canonical fetch URL for every key, printed directly — no hand-assembling a resolver
+        // route from the docs. A PROMISE, not yet a fact: the key doesn't exist server-side until the
+        // write below lands and the resolver re-indexes, so it is printed here, never probed here.
+        for (const p of pairs) {
+            console.log(dim(`    → fetch: ${canonicalAttachmentUrl({ uriBase, chainId: chainId(), contract, tokenId: tokenIdForUrl, key: p.key })}`));
+        }
+        // What CAN be checked before any write: does ANY resolver answer for this project at all right
+        // now — the precondition for the URL(s) above to ever resolve. Same GET-and-classify shape
+        // `cmdVerifyRemote` uses for its own reachability check (served.ts).
+        reachability = await probeResolverReachable({ uriBase, chainId: chainId(), contract, tokenId: tokenIdForUrl });
+        if (reachability.reachable) {
+            console.log(dim(`    resolver answers for this project (${reachability.detail}) — the URL(s) above start serving once this write lands and re-indexes.`));
+        }
+        else {
+            console.log(yellow('  ⚠ ') +
+                `the resolver base baked on-chain (${uriBase}) does not currently answer for ${scope} (${reachability.detail}) — ` +
+                `the on-chain FIELD WRITE below will still succeed, but nothing is known to be able to SERVE ${pairs.map((p) => bold(p.key)).join(', ')} right now. ` +
+                `Local: is ${bold('abx serve')} running, and is this project ${bold('abx add')}-ed + indexed? Hosted: ${bold(`abx add ${contract} --remote <name>`)} then ${bold(`abx index ${contract} --remote <name>`)}.`);
+        }
     }
     else {
         console.log(yellow('  ⚠ ') +
-            `this project resolves ON-CHAIN (no resolver base baked in), and the on-chain document carries reserved fields only — ` +
-            `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. ` +
+            `this project resolves ON-CHAIN (no resolver base baked in) — the on-chain FIELD WRITE below will still succeed, but there is NO off-chain serving path at all: the on-chain document carries reserved fields only, ` +
+            `so ${pairs.map((p) => bold(p.key)).join(', ')} will NEVER appear in ${bold('tokenURI')} for ANY resolver. The bytes are stored and provable, but nothing surfaces them to a marketplace or wallet. ` +
             dim('(Params are chain state, readable with abx tokens and by any contract call — 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}.`));
+        console.log(dim(`    to make attached artifacts servable at all, point the project at a resolver (${bold('abx deploy-resolver')}, or a managed one via ${bold('abx add <addr> --remote <name>')}) — then re-run this.`));
     }
     // 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.
@@ -2122,7 +2317,16 @@ export async function cmdAttach(rest, flags) {
     if (sent) {
         const id = flags.token ?? '0';
         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` +
+        // The distinction #127 asked for: the on-chain FIELD WRITE succeeding (this line, always true
+        // when we get here) is not the same fact as the artifact being SERVABLE — say both, separately,
+        // rather than one "✓ attached" that a reader takes to mean "and it's live".
+        const servingLine = !uriBase || uriBase.trim() === ''
+            ? dim(`    serving: NONE — this project resolves fully on-chain (see the warning above); the bytes are stored and provable, but no resolver will ever list them.\n`)
+            : reachability?.reachable
+                ? dim(`    serving: a resolver answered for ${scope} just before this write (see above); fetch the URL(s) above once it re-indexes to confirm.\n`)
+                : dim(`    serving: NOT CONFIRMED — no resolver answered for ${scope} just before this write (see the warning above). The FIELD is on-chain now; SERVING it is a separate, still-unmet, concern.\n`);
+        console.log(`  ${green('✓')} on-chain field write succeeded — ${names} join${pairs.length > 1 ? '' : 's'} ${scope}'s ${bold('artifacts')} manifest (stored on-chain, anchored).\n` +
+            servingLine +
             dim(`    verify (a resolver serves the complete listing): `) +
             `abx tokenuri ${contract}${id === '0' ? '' : ` --token ${id}`} --fetch` +
             dim(`  ${collection ? '' : `→ artifacts[].key ${pairs.map((p) => `"${p.key}"`).join(', ')}; /data/<key> fetches each`}\n`) +