@artblocks/abx-cli 0.1.0-alpha.23 → 0.1.0-alpha.26

package/dist/commands/deploy.js

@@ -15,7 +15,7 @@
 import { createHash } from 'node:crypto';
 import { readFileSync, readdirSync, statSync } from 'node:fs';
 import { basename, extname, join as joinPath, resolve as resolvePath } from 'node:path';
-import { DEFAULT_CHAIN_KEY, DEP_RESOLUTION, METADATA_FIELD as F, METADATA_REPRESENTATION as R, analyzeScript, assertChainId, checkRegistryDeps, dependencySetupCalls, deployOneOfOne, deploySeries, deployOneOfOneEdition, deployEditionImage, discoverDeployBlock, encodeFieldRenderer, encodeTag, expectedChainComplete, makeHotSender, makePublicClient, makeWalletClient, normalizeAttributes, onchainUriSetupCalls, oneOfOneImageAbi, oneOfOneEditionAbi, parseTraitPairs, planResume, predictClone, probeSeedSource, prepareCodeSetup, prepareDeployOneOfOne, prepareDeploySeries, prepareDeploySeriesCode, prepareDeployOneOfOneEdition, prepareDeployEditionImage, prepareDeployEditionCode, redactRpcUrl, resolveChain, resolveDepRegistryPointer, resolveGenerator, probeTransferValidator, resolveRecommendedTransferValidator, resolveRpcUrl, resolveSeedSource, resolveSeriesCodeFactory, saltFor, seriesCodeAbi, seriesCodeFactoryAbi, tryReadContract, } from '@artblocks/abx-sdk';
+import { DEFAULT_CHAIN_KEY, DEP_RESOLUTION, METADATA_FIELD as F, contentIdFromLocator, METADATA_REPRESENTATION as R, analyzeScript, assertChainId, checkRegistryDeps, dependencySetupCalls, deployOneOfOne, deploySeries, deployOneOfOneEdition, deployEditionImage, discoverDeployBlock, encodeFieldRenderer, encodeTag, expectedChainComplete, makeHotSender, makePublicClient, makeWalletClient, normalizeAttributes, onchainUriSetupCalls, oneOfOneImageAbi, oneOfOneEditionAbi, parseTraitPairs, planResume, predictClone, probeSeedSource, prepareCodeSetup, prepareDeployOneOfOne, prepareDeploySeries, prepareDeploySeriesCode, prepareDeployOneOfOneEdition, prepareDeployEditionImage, prepareDeployEditionCode, redactRpcUrl, resolveChain, resolveDepRegistryPointer, resolveGenerator, probeTransferValidator, resolveRecommendedTransferValidator, resolveRpcUrl, resolveSeedSource, resolveSeriesCodeFactory, saltFor, seriesCodeAbi, seriesCodeFactoryAbi, tryReadContract, AbxServiceClient, } from '@artblocks/abx-sdk';
 import { DIRECT_URL_BACKENDS, contentTypeFromPath, decideImageContentLane, hashContent, isTurboArweave, resolveBackend, validateRenderStorageCombo, } from '@artblocks/abx-storage';
 import { DEFAULT_PORT, contentHash, generateContent, resolveBaseUrl, startTokenApiServer } from '@artblocks/abx-token-api';
 import { encodeFunctionData, toHex, zeroAddress } from 'viem';
@@ -24,10 +24,11 @@ import { parseDepFlag } from '../deps.js';
 import { allowUnreadableOnchain, isDryRun, parseSaltFlag, refuseStrayFlags, warnSignWithoutFor } from '../flags.js';
 import { isEditionContract } from '../kind.js';
 import { jsonSafe, withJson } from '../jsonout.js';
+import { planOnChainScript } from '../script-chunks.js';
 import { bold, c, dim, ensureFactory, ensureRenderer, ensureSeedSource, ensureSeriesCodeFactory, ensureSeriesFactory, ensureOneOfOneEditionFactory, ensureEditionFactory, ensureEditionCodeFactory, g, info, keepAlive, ok, p, portInUse, printServing, registerAndIndexLocally, reindexAfterDeploy, step, warn, } from '../output.js';
-import { AUTHORSHIP_DEPLOY_FIELDS, ONCHAIN_PROJECT_SOFT_LIMIT, ONCHAIN_READ_WARN_BYTES, tokenUriGasEstimate, authorshipContractFields, computeContentPlan, envStagingSender, parseCompress, parseSeedSourceValue, canonicalSeedSource, refuseUnusableSeedSource, parseTransferValidatorValue, guardOnChainSize, previewImageStaging, sessionStagingSender, stageImageField, stageImageFieldsBatch, } from '../ownerops.js';
+import { AUTHORSHIP_DEPLOY_FIELDS, ONCHAIN_PROJECT_SOFT_LIMIT, ONCHAIN_READ_WARN_BYTES, tokenUriGasEstimate, authorshipContractFields, gatewayContractFields, servingGateway, computeContentPlan, envStagingSender, parseCompress, parseSeedSourceValue, canonicalSeedSource, refuseUnusableSeedSource, parseTransferValidatorValue, guardOnChainSize, previewImageStaging, refusePrewrappedImage, sessionStagingSender, stageImageField, stageImageFieldsBatch, } from '../ownerops.js';
 import { canonicalLabel } from '../remote.js';
-import { confirmSend, gatedSend, laneFromFlags } from '../riskgate.js';
+import { assertLaneCanSign, confirmSend, gatedSend, laneFromFlags } from '../riskgate.js';
 import { describeSchema, editionSchemaAdvisory, parseSchemaSpecs } from '../schema.js';
 import { parseSeriesTraits } from '../series-traits.js';
 import { decodeOnChainJson } from '../served.js';
@@ -192,6 +193,8 @@ export function deployCommandLine(flags, salt) {
     str('backend', flags.backend);
     str('gateway', flags.gateway);
     str('bucket', flags.bucket);
+    str('ipfs-gateway', flags['ipfs-gateway']);
+    str('arweave-gateway', flags['arweave-gateway']);
     str('public-base-url', flags['public-base-url']);
     if (flags.sign !== undefined)
         parts.push('--sign');
@@ -223,6 +226,8 @@ export function deploySeriesCommandLine(flags, salt) {
     str('backend', flags.backend);
     str('gateway', flags.gateway);
     str('bucket', flags.bucket);
+    str('ipfs-gateway', flags['ipfs-gateway']);
+    str('arweave-gateway', flags['arweave-gateway']);
     str('public-base', flags['public-base']);
     str('public-base-url', flags['public-base-url']);
     bool('mint-all');
@@ -278,6 +283,8 @@ export function deployCodeCommandLine(flags, salt) {
     str('backend', flags.backend);
     str('gateway', flags.gateway);
     str('public-base-url', flags['public-base-url']);
+    str('ipfs-gateway', flags['ipfs-gateway']);
+    str('arweave-gateway', flags['arweave-gateway']);
     if (flags.sign !== undefined)
         parts.push('--sign');
     if (flags.unsigned !== undefined)
@@ -296,11 +303,14 @@ export const imageKeccakField = (value) => ({
     representation: encodeTag(R.keccak256),
     value,
 });
-export const imageInlineField = (svg) => ({
-    field: encodeTag(F.image),
-    representation: encodeTag(R.inline),
-    value: toHex(svg),
-});
+export const imageInlineField = (svg) => {
+    refusePrewrappedImage(svg, 'inline image');
+    return {
+        field: encodeTag(F.image),
+        representation: encodeTag(R.inline),
+        value: toHex(svg),
+    };
+};
 /** An `image` field pointing at an off-chain URL (the renderer emits it verbatim). */
 export const imageUrlField = (url) => ({
     field: encodeTag(F.image),
@@ -314,6 +324,82 @@ export const imageUrlTemplateField = (template) => ({
     representation: encodeTag(R.urlTemplate),
     value: toHex(template),
 });
+/**
+ * An `image` field carrying a CONTENT-ADDRESSED identity — the bare CID / txid, with the serving
+ * gateway supplied at read time from the collection's `abx_gateway_*` preference (renderer spec v11).
+ *
+ * This replaces what `--onchain-uri --backend ipfs|arweave` used to write. That path stored the
+ * backend's gateway HTTPS URL as a `url` field, which looked identical in a marketplace and was
+ * wrong in two ways that only showed up later: the creator's chosen gateway host was welded into a
+ * value they might have locked, so a dead gateway became a dead token rather than a repoint; and
+ * `abx_provenance` reported `source: url` for bytes that live on IPFS, so the chain stopped saying
+ * where the work actually was. The CID is identity and the gateway is a preference — one field each.
+ *
+ * `{id}` in the value still substitutes at read (the O(1) directory pattern), so a collection-scope
+ * `ipfs` field addresses a whole pinned folder exactly as `url-template` does for a plain CDN.
+ */
+export const imageContentAddressedField = (network, contentId) => ({
+    field: encodeTag(F.image),
+    representation: encodeTag(network === 'ipfs' ? R.ipfs : R.arweave),
+    value: toHex(contentId),
+});
+/**
+ * The `image` field for a locator a durable backend just produced — ONE decision point, so every
+ * lane (1/1, series, both edition twins) writes the same shape for the same backend.
+ *
+ * `ipfs` / `arweave` store IDENTITY: recover the bare CID/txid from the backend's gateway URL and
+ * commit that, leaving the serving prefix to the collection's `abx_gateway_*` preference. Any path
+ * suffix rides along, so a directory upload's `<cid>/{id}.png` is still one collection-scope field
+ * covering every token — the renderer substitutes `{id}` for `ipfs`/`arweave` exactly as it does for
+ * `url-template`.
+ *
+ * `cloud` and friends keep the plain `url` / `url-template` they always had: an https CDN locator IS
+ * the address, with no identity underneath to separate out.
+ */
+/**
+ * The URL a creator's token will actually carry, for a locator a durable backend just produced.
+ *
+ * For `ipfs`/`arweave` the backend's locator is an UPLOAD-gateway URL, and the on-chain field holds
+ * only the bare CID/txid — so narrating the locator verbatim told the creator a host their token
+ * does not use (a live deploy printed `gateway.pinata.cloud/…` while committing a CID served from
+ * `ipfs.io`). Rebuild it under the serving preference instead, and say which one that is, since
+ * "the floor is filling a silence" and "you chose this" have different futures.
+ *
+ * Every other backend is returned verbatim: an https CDN locator IS the address.
+ */
+function servedImageUrl(backendId, locator, flags) {
+    if (backendId !== 'ipfs' && backendId !== 'arweave')
+        return { url: locator, note: '' };
+    const contentId = contentIdFromLocator(backendId, locator);
+    if (!contentId)
+        return { url: locator, note: '' };
+    const { prefix, chosen } = servingGateway(backendId, flags);
+    return {
+        url: `${prefix}${contentId}`,
+        note: chosen ? `gateway: yours, written on-chain` : `gateway: public default — repoint any time with ${bold('abx set-gateway')}`,
+    };
+}
+/** How a lane should describe what it just committed, so the narration matches the field written. */
+function describeLocatorField(backendId) {
+    return backendId === 'ipfs' || backendId === 'arweave'
+        ? `ON-CHAIN image as a bare ${backendId} id — the gateway is the collection's preference, repointable with ${bold('abx set-gateway')}`
+        : 'ON-CHAIN image url (the locator IS the address)';
+}
+function imageLocatorField(backendId, locator, isTemplate = false) {
+    const network = backendId === 'ipfs' || backendId === 'arweave' ? backendId : null;
+    if (network) {
+        const contentId = contentIdFromLocator(network, locator);
+        if (contentId)
+            return imageContentAddressedField(network, contentId);
+        // A subdomain-style gateway (`https://<cid>.ipfs.dweb.link`), which ABX's own backends never
+        // produce. Degrade to the old shape rather than guess at the CID — and say so, because the
+        // consequence (a welded host) is exactly what the caller thought they were avoiding.
+        warn(`could not recover the ${network} content id from ${locator} — writing the gateway URL as a plain ` +
+            `'url' field instead. That URL's host is then part of the on-chain value: a gateway change ` +
+            `needs ${bold('abx set-field')}, not ${bold('abx set-gateway')}.`);
+    }
+    return isTemplate ? imageUrlTemplateField(locator) : imageUrlField(locator);
+}
 export const looksLikeSvg = (s) => /^\s*<(\?xml|svg)/i.test(s);
 /**
  * Does the IMAGE itself end up on-chain for this deploy? Two ways it can:
@@ -359,7 +445,8 @@ export function imageEndsUpOnChain(flags, onchainImage) {
 export async function prepareContent(imagePath, clone, overrides, store = true, // false for --dry-run: compute the hash but don't custody bytes
 onChain = false, // true (--onchain-uri): put the image ON-CHAIN (inline SVG) so it self-resolves
 remoteEth, // wallet-lane Turbo uploads: sign+pay with the connected browser wallet
-walletAddr) {
+walletAddr, // the deployer wallet — checked for existing Turbo credits if the managed key is short
+gatewayFlags = {}) {
     if (!imagePath) {
         // demo default = generative SVG. On-chain mode inlines it (self-resolving, no custody);
         // off-chain mode commits its keccak and regenerates/serves it.
@@ -413,8 +500,8 @@ walletAddr) {
         const backendId = backendResolution(overrides).backend;
         if (onchainUrlLane) {
             return {
-                tokenFields: [imageUrlField(`<${backendId}-url>`)],
-                contentNote: `content: ${basename(path)} (${bytes.length} bytes, ${contentType}) → would upload to ${backendId}; its public URL becomes the ON-CHAIN image field (no server)`,
+                tokenFields: [imageLocatorField(backendId, `<${backendId}-url>`)],
+                contentNote: `content: ${basename(path)} (${bytes.length} bytes, ${contentType}) → would upload to ${backendId}; ${describeLocatorField(backendId)}`,
             };
         }
         return {
@@ -440,10 +527,13 @@ walletAddr) {
             // Keep the bytes under their hash too: `abx verify` can then still prove the served image
             // matches what was uploaded, even though the on-chain field addresses it by URL.
             await backend.put(hash, { bytes, contentType });
-            ok(`image → ${url}  ${dim(`(${backend.id}; baked on-chain, no server)`)}`);
+            const served = servedImageUrl(backend.id, url, gatewayFlags);
+            ok(`image → ${served.url}  ${dim(`(${backend.id}; baked on-chain, no server)`)}`);
+            if (served.note)
+                info(dim(`  ${served.note}`));
             return {
-                tokenFields: [imageUrlField(url)],
-                contentNote: `content: ${basename(path)} (${bytes.length} bytes, ${contentType}) on ${backend.id} · ON-CHAIN image url ${url}`,
+                tokenFields: [imageLocatorField(backend.id, url)],
+                contentNote: `content: ${basename(path)} (${bytes.length} bytes, ${contentType}) on ${backend.id} · ON-CHAIN image ${describeLocatorField(backend.id)}`,
             };
         }
         warn(`'${backend.id}' cannot upload a directory, so no public image URL could be baked — falling back to custody (the on-chain image will be a placeholder).`);
@@ -475,16 +565,24 @@ export const attributesInlineField = (attrs) => ({
     representation: encodeTag(R.inline),
     value: toHex(JSON.stringify(attrs)),
 });
-/** Warn when IPFS/Arweave custody is pointed at a LOCAL gateway: the served image URL
- *  (`<gateway>/ipfs/<cid>`) would resolve only on this machine, so marketplaces/wallets can't
- *  load it — a pinning service + a PUBLIC gateway is part of operating off-chain custody. */
+/**
+ * Warn when IPFS/Arweave custody is pointed at a LOCAL gateway.
+ *
+ * Two distinct problems ride on one flag, and the warning names the one that actually applies. The
+ * bytes are pinned only to a node on this machine, so nothing off it can retrieve them — that is the
+ * real damage and it survives any later `set-gateway`. It ALSO used to weld that localhost host into
+ * the on-chain value; since the field holds a bare CID it no longer does (the serving prefix is the
+ * collection's preference), so promising "the served URL resolves only on THIS machine" would now be
+ * false and would point the creator at the wrong repair.
+ */
 export function localGatewayWarning(flags) {
     const opts = storageOptions(storageOverrides(flags));
     const gateway = opts.backend === 'ipfs' ? opts.ipfs?.gateway : opts.backend === 'arweave' ? opts.arweave?.gateway : undefined;
     if (gateway && /^https?:\/\/(localhost|127\.0\.0\.1|0\.0\.0\.0)\b/i.test(gateway)) {
-        return (`${opts.backend} gateway is ${gateway} — a LOCAL gateway. The served image URL resolves only on THIS machine; ` +
-            `marketplaces and wallets won't load it. Pin to a service with a PUBLIC gateway (e.g. a Pinata dedicated gateway) ` +
-            `via --gateway https://… or ABX_IPFS_GATEWAY.`);
+        return (`${opts.backend} gateway is ${gateway} — a LOCAL gateway, so the bytes would be pinned only to a node on THIS ` +
+            `machine and nobody else could retrieve them. The on-chain field holds the bare content id (a gateway change is ` +
+            `later just ${bold('abx set-gateway')}), but no gateway can serve content that was never pinned publicly. Pin to a ` +
+            `service with a PUBLIC gateway (e.g. a Pinata dedicated gateway) via --gateway https://… or ABX_IPFS_GATEWAY.`);
     }
     return null;
 }
@@ -815,6 +913,7 @@ export async function cmdDeployBody(flags, serveAfter, emit) {
     // explicit --salt is given. With the wallet lane the signer is unknown until they
     // connect, so this runs per-signer.
     const buildForDeployer = async (deployer) => {
+        assertLaneCanSign(flags); // no upload before we know this run can be signed — see `assertLaneCanSign`
         const salt = explicitSalt ?? saltFor(deployer);
         const clone = await predictClone(publicClient, { factory, salt });
         // A baked on-chain image (--onchain-image) replaces prepareContent's image field —
@@ -825,7 +924,7 @@ export async function cmdDeployBody(flags, serveAfter, emit) {
             ? { tokenFields: [bakedImage], contentNote: 'content: image staged ON-CHAIN via reader (self-resolving, no custody)' }
             : onchainImage
                 ? { tokenFields: [], contentNote: 'content: image would be staged ON-CHAIN via reader (chunk store) — dry run skips the staging write' }
-                : await prepareContent(flags.image, clone, storageOverrides(flags), !dryRun, onChainUri, uploadRemoteEth, deployer);
+                : await prepareContent(flags.image, clone, storageOverrides(flags), !dryRun, onChainUri, uploadRemoteEth, deployer, flags);
         // Put the description ON-CHAIN (inline) when asked, or always under --onchain-uri
         // (the on-chain renderer can only emit on-chain fields, so an off-chain-only
         // description would simply be omitted). On-chain wins at resolve either way.
@@ -853,7 +952,7 @@ export async function cmdDeployBody(flags, serveAfter, emit) {
             transferValidator,
             tokenFields,
             // authorship + rights (creator / license / …) are collection-scope on-chain fields.
-            contractFields: authorshipContractFields(flags),
+            contractFields: [...authorshipContractFields(flags), ...gatewayContractFields(flags)],
         };
         return { clone, params, salt, contentNote };
     };
@@ -1319,13 +1418,14 @@ export async function cmdDeployOneOfOneEditionBody(flags, emit) {
             info('off-chain fallback pointer left empty (the renderer is authoritative); set --public-base-url to bake one anyway.');
     }
     const buildForDeployer = async (deployer) => {
+        assertLaneCanSign(flags); // no upload before we know this run can be signed — see `assertLaneCanSign`
         const salt = explicitSalt ?? saltFor(deployer);
         const clone = await predictClone(publicClient, { factory, salt });
         const { tokenFields, contentNote } = bakedImage
             ? { tokenFields: [bakedImage], contentNote: 'content: image staged ON-CHAIN via reader (self-resolving, no custody)' }
             : onchainImage
                 ? { tokenFields: [], contentNote: 'content: image would be staged ON-CHAIN via reader (chunk store) — dry run skips the staging write' }
-                : await prepareContent(flags.image, clone, storageOverrides(flags), !dryRun, onChainUri);
+                : await prepareContent(flags.image, clone, storageOverrides(flags), !dryRun, onChainUri, undefined, undefined, flags);
         if (flags.description && (onChainUri || flags['description-onchain'])) {
             tokenFields.push({ field: encodeTag(F.description), representation: encodeTag(R.inline), value: toHex(flags.description) });
         }
@@ -1349,7 +1449,7 @@ export async function cmdDeployOneOfOneEditionBody(flags, emit) {
             minter,
             paused,
             tokenFields,
-            contractFields: authorshipContractFields(flags),
+            contractFields: [...authorshipContractFields(flags), ...gatewayContractFields(flags)],
         };
         return { clone, params, salt, contentNote };
     };
@@ -1659,7 +1759,7 @@ export async function cmdDeploySeriesBody(flags, emit) {
     // Image custody × URI resolution (see reference/hosting.md):
     //  - --onchain-image                    → chunk store (on-chain bytes), JSON on-chain
     //  - --onchain-uri + a durable backend  → image OFF-CHAIN (ipfs/arweave), JSON on-chain via the
-    //    (ipfs/arweave)                        renderer: ONE collection `url-template` when files share
+    //    (ipfs/arweave)                        renderer: ONE collection-scope image field when files share
     //                                          an extension (O(1) directory), else per-token `url` (O(N))
     //  - --onchain-uri alone                → inline SVG on-chain
     //  - neither                            → off-chain custody (keccak), served by a hosted resolver
@@ -1694,6 +1794,7 @@ export async function cmdDeploySeriesBody(flags, emit) {
     // early managed-key creation + funds guard and the up-front buildFields; the session branch runs them.
     const remoteEthUpload = lane === 'sign' && !onchainImage && !!backend && storageSignerChoice(overrides) === 'eth' && isTurboArweave(opts);
     if (backend && !remoteEthUpload) {
+        assertLaneCanSign(flags); // no upload before we know this run can be signed — see `assertLaneCanSign`
         ensureArweaveIdentityForUpload(opts); // Turbo identity, created on first upload
         // The deployer wallet (--for, else the .env key's address) — checked for existing Turbo credits
         // if the managed key is short, so we recommend `--storage-signer eth` before any top-up.
@@ -1733,23 +1834,35 @@ export async function cmdDeploySeriesBody(flags, emit) {
             const uniform = exts[0] !== '' && exts.every((e) => e === exts[0]);
             if (dryRun || !backend) {
                 if (uniform) {
-                    contractFields = [imageUrlTemplateField(`<${backendId}-dir>/{id}${exts[0]}`)];
-                    info(`would upload ${tokenPaths.length} file(s) as ONE ${backendId} directory → collection image url-template <${backendId}-dir>/{id}${exts[0]} (O(1))`);
+                    contractFields = [imageLocatorField(backendId, `<${backendId}-dir>/{id}${exts[0]}`, true)];
+                    info(`would upload ${tokenPaths.length} file(s) as ONE ${backendId} directory → collection image <${backendId}-dir>/{id}${exts[0]} (O(1); ${describeLocatorField(backendId)})`);
+                    // Name the SERVING prefix in the plan too. Without it a preview says "the gateway is the
+                    // collection's preference" and never says what that preference resolves to, so a reader
+                    // fills the blank with the upload gateway they just typed — the same confusion the live
+                    // narration used to cause outright.
+                    if (backendId === 'ipfs' || backendId === 'arweave') {
+                        const { prefix, chosen } = servingGateway(backendId, flags);
+                        info(`served from ${bold(prefix)} ${dim(chosen ? '(your --' + backendId + '-gateway, written on-chain)' : `(public default — nothing written; repoint any time with ${bold('abx set-gateway')})`)}`);
+                    }
                 }
                 else {
-                    tokenFields = tokenPaths.map(({ tokenId }) => tokenFieldOf(tokenId, imageUrlField(`<${backendId}-url-${tokenId}>`)));
+                    tokenFields = tokenPaths.map(({ tokenId }) => tokenFieldOf(tokenId, imageLocatorField(backendId, `<${backendId}-url-${tokenId}>`)));
                     info(`would upload ${tokenPaths.length} file(s) to ${backendId} → per-token url image fields (mixed extensions, O(N))`);
                 }
                 return;
             }
             if (uniform && backend.putDirectory) {
-                // O(1) directory-base: upload the folder renamed to {id}{ext}; ONE collection url-template.
+                // O(1) directory-base: upload the folder renamed to {id}{ext}; ONE collection-scope image
+                // field. `{id}` substitutes at read on every locator representation, `ipfs`/`arweave` included.
                 const entries = tokenPaths.map(({ tokenId, path }) => ({ name: `${tokenId}${exts[0]}`, bytes: new Uint8Array(readFileSync(path)), contentType: contentTypeFromPath(path) }));
                 const { base } = await backend.putDirectory(entries);
                 const template = `${base}/{id}${exts[0]}`;
-                contractFields = [imageUrlTemplateField(template)];
+                contractFields = [imageLocatorField(backendId, template, true)];
                 info(`uploaded ${entries.length} file(s) as one ${backendId} directory`);
-                info(`collection image (url-template): ${template}  ${dim('— one field covers every token (O(1))')}`);
+                const servedTemplate = servedImageUrl(backendId, template, flags);
+                info(`collection image: ${servedTemplate.url}  ${dim(`— one field covers every token (O(1); ${describeLocatorField(backendId)})`)}`);
+                if (servedTemplate.note)
+                    info(dim(`  ${servedTemplate.note}`));
             }
             else {
                 // mixed extensions (or no directory support): per-token url fields (O(N)).
@@ -1760,10 +1873,10 @@ export async function cmdDeploySeriesBody(flags, emit) {
                     const locator = (await backend.locator?.(hash)) ?? '';
                     if (!locator)
                         throw new Error(`backend ${backendId} returned no public locator for token ${tokenId} — a durable backend (ipfs/arweave) is required for --onchain-uri image hosting`);
-                    tokenFields.push(tokenFieldOf(tokenId, imageUrlField(locator)));
-                    info(`token ${tokenId} ← ${fname} → ${locator}`);
+                    tokenFields.push(tokenFieldOf(tokenId, imageLocatorField(backendId, locator)));
+                    info(`token ${tokenId} ← ${fname} → ${servedImageUrl(backendId, locator, flags).url}`);
                 }
-                info(`mixed file extensions → per-token url fields (O(N)); a uniform extension enables the O(1) directory template`);
+                info(`mixed file extensions → per-token image fields (O(N)); a uniform extension enables the O(1) directory template`);
             }
             return;
         }
@@ -1819,6 +1932,7 @@ export async function cmdDeploySeriesBody(flags, emit) {
     // Assemble the init params for a given deployer (owner/royalty/mintTo = deployer). The clone
     // address is deterministic in (factory, salt) — so URIs are baked before the tx is signed.
     const buildForDeployer = async (deployer) => {
+        assertLaneCanSign(flags); // no upload before we know this run can be signed — see `assertLaneCanSign`
         const salt = explicitSalt ?? saltFor(deployer);
         const clone = await predictClone(publicClient, { factory, salt });
         const params = {
@@ -1839,8 +1953,8 @@ export async function cmdDeploySeriesBody(flags, emit) {
             mintTo: mintCount > 0 ? deployer : zeroAddress,
             mintCount,
             tokenFields,
-            // image contract fields (the O(1) url-template) + authorship/rights (creator / license / …).
-            contractFields: [...contractFields, ...authorshipContractFields(flags)],
+            // image contract fields (the O(1) collection-scope image) + authorship/rights (creator / license / …).
+            contractFields: [...contractFields, ...authorshipContractFields(flags), ...gatewayContractFields(flags)],
         };
         return { clone, params, salt };
     };
@@ -1877,7 +1991,9 @@ export async function cmdDeploySeriesBody(flags, emit) {
         info(onchainImage
             ? 'resolution: ON-CHAIN via the renderer (chunked reader per token — image bytes on-chain)'
             : offchainImageOnchainJson
-                ? `resolution: ON-CHAIN via the renderer; image OFF-CHAIN on ${backendId} (${contractFields.length ? 'one collection url-template, O(1)' : 'per-token url, O(N)'})`
+                // Say which SHAPE landed, not a fixed representation name: since v11 a content-addressed
+                // backend writes an `ipfs`/`arweave` field, not `url`/`url-template`.
+                ? `resolution: ON-CHAIN via the renderer; image OFF-CHAIN on ${backendId} (${contractFields.length ? 'one collection-scope image field, O(1)' : 'per-token image fields, O(N)'})`
                 : onChainUri
                     ? 'resolution: ON-CHAIN via the renderer (inline SVG per token)'
                     : `resolution: off-chain, base ${params.tokenURIBase}`);
@@ -2240,7 +2356,7 @@ export async function cmdDeployEditionImageBody(flags, emit) {
         }, 0) + 1 // + the deploy tx
         : 1;
     const tokenFields = [];
-    // Collection-scope fields the image lane may add (the O(1) `url-template`). Kept separate from the
+    // Collection-scope fields the image lane may add (the O(1) directory image). Kept separate from the
     // authorship fields and CONCATENATED at the params site — never assigned over them, or an
     // `--creator`/`--license` value would silently vanish whenever pattern 2 is in play.
     let imageContractFields = [];
@@ -2263,13 +2379,21 @@ export async function cmdDeployEditionImageBody(flags, emit) {
             const uniform = exts[0] !== '' && exts.every((e) => e === exts[0]);
             if (dryRun || !backend) {
                 if (uniform) {
-                    imageContractFields = [imageUrlTemplateField(`<${backendId}-dir>/{id}${exts[0]}`)];
-                    info(`would upload ${tokenPaths.length} file(s) as ONE ${backendId} directory → collection image url-template <${backendId}-dir>/{id}${exts[0]} (O(1))`);
+                    imageContractFields = [imageLocatorField(backendId, `<${backendId}-dir>/{id}${exts[0]}`, true)];
+                    info(`would upload ${tokenPaths.length} file(s) as ONE ${backendId} directory → collection image <${backendId}-dir>/{id}${exts[0]} (O(1); ${describeLocatorField(backendId)})`);
+                    // Name the SERVING prefix in the plan too. Without it a preview says "the gateway is the
+                    // collection's preference" and never says what that preference resolves to, so a reader
+                    // fills the blank with the upload gateway they just typed — the same confusion the live
+                    // narration used to cause outright.
+                    if (backendId === 'ipfs' || backendId === 'arweave') {
+                        const { prefix, chosen } = servingGateway(backendId, flags);
+                        info(`served from ${bold(prefix)} ${dim(chosen ? '(your --' + backendId + '-gateway, written on-chain)' : `(public default — nothing written; repoint any time with ${bold('abx set-gateway')})`)}`);
+                    }
                 }
                 else {
                     for (const { tokenId } of tokenPaths)
-                        tokenFields.push(tokenFieldOf(tokenId, imageUrlField(`<${backendId}-url-${tokenId}>`)));
-                    info(`would upload ${tokenPaths.length} file(s) to ${backendId} → per-id url image fields (mixed extensions, O(N))`);
+                        tokenFields.push(tokenFieldOf(tokenId, imageLocatorField(backendId, `<${backendId}-url-${tokenId}>`)));
+                    info(`would upload ${tokenPaths.length} file(s) to ${backendId} → per-id image fields (mixed extensions, O(N); ${describeLocatorField(backendId)})`);
                 }
             }
             else if (uniform && backend.putDirectory) {
@@ -2277,9 +2401,9 @@ export async function cmdDeployEditionImageBody(flags, emit) {
                 const entries = tokenPaths.map(({ tokenId, path }) => ({ name: `${tokenId}${exts[0]}`, bytes: new Uint8Array(readFileSync(path)), contentType: contentTypeFromPath(path) }));
                 const { base } = await backend.putDirectory(entries);
                 const template = `${base}/{id}${exts[0]}`;
-                imageContractFields = [imageUrlTemplateField(template)];
+                imageContractFields = [imageLocatorField(backendId, template, true)];
                 info(`uploaded ${entries.length} file(s) as one ${backendId} directory`);
-                info(`collection image (url-template): ${template}  ${dim('— one field covers every id (O(1))')}`);
+                info(`collection image: ${template}  ${dim(`— one field covers every id (O(1); ${describeLocatorField(backendId)})`)}`);
             }
             else {
                 // mixed extensions (or no directory support): per-id url fields (O(N)).
@@ -2290,10 +2414,10 @@ export async function cmdDeployEditionImageBody(flags, emit) {
                     const locator = (await backend.locator?.(hash)) ?? '';
                     if (!locator)
                         throw new Error(`backend ${backendId} returned no public locator for id ${tokenId} — a durable backend (ipfs/arweave/cloud) is required for --onchain-uri image hosting`);
-                    tokenFields.push(tokenFieldOf(tokenId, imageUrlField(locator)));
+                    tokenFields.push(tokenFieldOf(tokenId, imageLocatorField(backendId, locator)));
                     info(`id ${tokenId} ← ${fname} → ${locator}`);
                 }
-                info(`mixed file extensions → per-id url fields (O(N)); a uniform extension enables the O(1) directory template`);
+                info(`mixed file extensions → per-id image fields (O(N)); a uniform extension enables the O(1) directory template`);
             }
             if (seriesTraitsOnchain)
                 for (const [tokenId, attrs] of seriesTraits)
@@ -2349,6 +2473,7 @@ export async function cmdDeployEditionImageBody(flags, emit) {
     if (!onchainImage)
         await buildFields();
     const buildForDeployer = async (deployer) => {
+        assertLaneCanSign(flags); // no upload before we know this run can be signed — see `assertLaneCanSign`
         const salt = explicitSalt ?? saltFor(deployer);
         const clone = await predictClone(publicClient, { factory, salt });
         const params = {
@@ -2373,7 +2498,7 @@ export async function cmdDeployEditionImageBody(flags, emit) {
             tokenFields,
             // Concatenate — the image lane's collection-scope url-template rides ALONGSIDE the authorship
             // fields. Assigning either over the other would silently drop the creator's --creator/--license.
-            contractFields: [...authorshipContractFields(flags), ...imageContractFields],
+            contractFields: [...authorshipContractFields(flags), ...gatewayContractFields(flags), ...imageContractFields],
         };
         return { clone, params, salt };
     };
@@ -2738,6 +2863,11 @@ export const DEPLOY_CODE_FLAGS = new Set([
 // Storage + signing + preview flags shared by every deploy path (mirrors storageOverrides() + the lanes).
 export const SHARED_DEPLOY_FLAGS = [
     'backend', 'endpoint', 'bucket', 'region', 'prefix', 'public-base', 'gateway', 'mode', 'api-url', 'upload-url', 'provider', 'storage-signer',
+    // The collection's PREFERRED SERVING gateways, written on chain (`abx_gateway_ipfs` /
+    // `abx_gateway_arweave`) and repointable forever with `abx set-gateway`. Distinct from `--gateway`,
+    // which is where the CLI uploads and probes; `--gateway` seeds these for the backend in use, and
+    // these override it when the two should differ. Every deploy path takes them.
+    'ipfs-gateway', 'arweave-gateway',
     'sign', 'unsigned', 'for', 'sign-url-file', 'dry-run', 'confirm', 'yes', 'salt', 'factory', 'bootstrap-factory', 'port', 'renderer', 'public-base-url',
     '721c', // opt-in ERC-721C enrollment (recommended | 0x…) — every deploy path takes it
     'json', // B19: the deployed ADDRESS as data, narration to stderr — every deploy path takes it
@@ -3006,11 +3136,9 @@ export async function cmdDeployCodeBody(flags, emit) {
     }
     else if (scriptPath) {
         const source = readFileSync(resolvePath(scriptPath), 'utf8');
-        const bytes = new TextEncoder().encode(source);
-        const CHUNK = 22_000; // SSTORE2 headroom
-        for (let off = 0; off < bytes.length; off += CHUNK)
-            scriptChunks.push(toHex(bytes.slice(off, off + CHUNK)));
-        contentSummary = `script ${bytes.length} bytes → ${scriptChunks.length} on-chain chunk(s)`;
+        scriptChunks = planOnChainScript(source);
+        const bytes = new TextEncoder().encode(source).length;
+        contentSummary = `script ${bytes} bytes → ${scriptChunks.length} on-chain chunk(s)`;
         ok(contentSummary);
         scriptAnalysis = analyzeScript(source, deps.map((d) => d.display)); // traits + PostParam reads + doc size → the Surfaces disposition below
     }
@@ -3042,7 +3170,7 @@ export async function cmdDeployCodeBody(flags, emit) {
         identityFields.push('external_url');
     }
     // authorship + rights — same on-chain inline collection-field slot (creator / license / …).
-    contractFields.push(...authorshipContractFields(flags));
+    contractFields.push(...authorshipContractFields(flags), ...gatewayContractFields(flags));
     for (const [flag, field] of AUTHORSHIP_DEPLOY_FIELDS)
         if (flags[flag])
             identityFields.push(field);
@@ -3243,7 +3371,7 @@ export async function cmdDeployCodeBody(flags, emit) {
     const undeclaredParams = (scriptAnalysis?.paramHints ?? []).filter((k) => !declaredSchemaKeys.has(k));
     const paramsDisposition = scriptAnalysis
         ? undeclaredParams.length
-            ? `⚠ the script READS ${undeclaredParams.join(', ')} but ${undeclaredParams.length === 1 ? "it isn't" : "they aren't"} in --schema → dropped at render (default used). Add --schema ${undeclaredParams.map((k) => `${k}:<Type>:<Auth>`).join(',')} (a palette collectors set = HexColor:TokenOwner)`
+            ? `⚠ the script READS ${undeclaredParams.join(', ')} but ${undeclaredParams.length === 1 ? "it isn't" : "they aren't"} in --schema → dropped at render (default used) UNLESS an augment hook supplies ${undeclaredParams.length === 1 ? 'it' : 'them'}. Add --schema ${undeclaredParams.map((k) => `${k}:<Type>:<Auth>`).join(',')} only for collector/creator inputs (a palette collectors set = HexColor:TokenOwner); ignore this for keys your augment hook derives`
             : schemas.length
                 ? `${schemas.length} declared: ${schemaSummary}`
                 : 'none (the script reads no collector params)'
@@ -3380,7 +3508,7 @@ export async function cmdDeployCodeBody(flags, emit) {
                 info(`  ${g('fully on-chain')} — the whole tokenURI (name + image SVG + traits) is computed on-chain; zero dependency outside the EVM ${dim('(abx verify confirms from chain)')}`);
             }
             else {
-                info(`  directory branch: no-server, not chain-complete — liveness rides the gateway (generator default; the ${bold('display.gateway')} contract param repoints), and the params ride the URL (8KB budget — abx verify reports urlOverBudget).`);
+                info(`  directory branch: no-server, not chain-complete — liveness rides the gateway (public default; ${bold('abx set-gateway')} repoints it), and the params ride the URL (8KB budget — abx verify reports urlOverBudget).`);
             }
             // A resolver is a "kinder serving path" ONLY when there's a live view / off-chain still to
             // serve — i.e. a program. The in-chain renderer-only lane has neither, so don't imply you
@@ -3446,12 +3574,27 @@ export async function cmdDeployCodeBody(flags, emit) {
         if (!imageOrphaned && !hasImageRenderer) {
             if (!hasPublicUrl)
                 info(`  ${dim('render mode (a still is never on-chain):')} ${bold('service')} (auto-render every mint/param change — a live/for-sale drop) · ${bold('once')} (fixed supply) · ${bold('none')} (placeholder). ${dim('freshness: no resolver ⇒ no chain-watcher ⇒ MANUAL/backfill (`abx render` after mints + each param change; the on-chain animation updates live, the bucket still does NOT). Continuous/live stills ⇒ run a resolver.')}`);
-            // The fs render-home footgun bites the RESOLVER lane hardest (a hosted resolver can't read your
-            // laptop disk → placeholder on OpenSea), so warn on BOTH lanes and name the concrete fix.
-            if (renderHome === 'fs')
+            // A managed provider whose descriptor says `render.attached` owns rendering — local
+            // ABX_STORAGE_BACKEND is irrelevant, and warning "placeholder forever" is a lie.
+            let renderAttached = false;
+            if (hasPublicUrl && !loopbackBaseUrl(baseUrl)) {
+                try {
+                    const d = await new AbxServiceClient({ baseUrl, timeoutMs: 2_500 }).descriptor();
+                    renderAttached = !!d.render?.attached;
+                }
+                catch { /* advisory — a down/non-ABX URL must not fail the dry run */ }
+            }
+            if (renderAttached) {
+                info(`  ${dim('render storage home:')} ${bold('managed by the resolver')} ${dim(`(${baseUrl}) — local ABX_STORAGE_BACKEND is irrelevant; skip abx deploy-effects`)}`);
+            }
+            else if (renderHome === 'fs') {
+                // The fs render-home footgun bites the RESOLVER lane hardest (a hosted resolver can't read your
+                // laptop disk → placeholder on OpenSea), so warn on BOTH lanes and name the concrete fix.
                 warn(`  render storage home is ${bold('fs')} — LOCAL to this machine, so ${hasPublicUrl ? 'a hosted resolver' : 'a marketplace'} can't read the rendered stills → placeholder forever. FIX before you render: ${bold('set ABX_STORAGE_BACKEND=arweave|s3|ipfs')} in .env (a PUBLIC home the runner uploads to).`);
-            else
+            }
+            else {
                 info(`  ${dim('render storage home:')} ${bold(renderHome)} ${dim('— a public home the runner uploads to ✓')}`);
+            }
         }
         (traitsBroken ? warn : info)(`traits: ${traitsDisposition}`);
         const paramsNudge = !scriptAnalysis && !schemas.length && (hasImageRenderer || hasAttributesRenderer);
@@ -3467,7 +3610,7 @@ export async function cmdDeployCodeBody(flags, emit) {
         // A dropped param is its own, milder problem: the piece renders, that input just takes its
         // default. Kept separate from the broken-surface alarm above (see the note there).
         if (undeclaredParams.length)
-            info(`  ${dim('dropped params render with their defaults — declare them to make them real:')} ${bold('--schema <key>:<Type>:<Auth>')}`);
+            info(`  ${dim('dropped params render with their defaults — declare collector/creator inputs with')} ${bold('--schema <key>:<Type>:<Auth>')} ${dim('(skip this for keys an augment hook supplies)')}`);
         // The runner/verify line is for lanes that need an off-chain STILL. An on-chain image renderer has
         // no still to render, host, or refresh — whether or not there's also a program driving
         // animation_url — so pointing at a runner and a bucket backend there is simply wrong.
@@ -3927,7 +4070,11 @@ export const DEPLOY_CODE_EDITION_FLAGS = new Set([
     // give them otherwise — a real but less helpful refusal (it doesn't say WHY, or the way out).
     // (`resume` is NOT here: --resume + --copies is refused earlier, at cmdDeployCode's dispatch —
     // this function never runs with flags.resume set, so listing it here would just be dead.)
-    'code-dir', 'dep', 'dep-registry', 'image-renderer', 'attributes-renderer', 'image-base', 'no-delegation',
+    'code-dir', 'image-renderer', 'attributes-renderer', 'image-base', 'no-delegation',
+    // NOT scope cuts: --dep/--dep-registry are fully wired on EditionCode (it inherits the same
+    // Dependencies extension, and the legs ride the same setup multicall — see the Dependencies step
+    // below). They're plain supported flags; `abx help deploy-code` documents them as working.
+    'dep', 'dep-registry',
 ]);
 export async function cmdDeployEditionCodeBody(flags, emit) {
     const usage = 'abx deploy-code --copies <n|open> --script <file> --name "Title" --symbol SYM (--public-base-url https://your.resolver.domain | --onchain-uri) ' +
@@ -4086,18 +4233,14 @@ export async function cmdDeployEditionCodeBody(flags, emit) {
     step('Content');
     const scriptPath = flags.script;
     const source = readFileSync(resolvePath(scriptPath), 'utf8');
-    const bytes = new TextEncoder().encode(source);
-    const CHUNK = 22_000; // SSTORE2 headroom
-    const scriptChunks = [];
-    for (let off = 0; off < bytes.length; off += CHUNK)
-        scriptChunks.push(toHex(bytes.slice(off, off + CHUNK)));
-    ok(`script ${bytes.length} bytes → ${scriptChunks.length} on-chain chunk(s)`);
+    const scriptChunks = planOnChainScript(source);
+    ok(`script ${new TextEncoder().encode(source).length} bytes → ${scriptChunks.length} on-chain chunk(s)`);
     const contractFields = [];
     if (flags.description)
         contractFields.push({ field: encodeTag(F.description), representation: encodeTag(R.inline), value: toHex(String(flags.description)) });
     if (flags['external-url'])
         contractFields.push({ field: encodeTag(F.externalUrl), representation: encodeTag(R.inline), value: toHex(String(flags['external-url'])) });
-    contractFields.push(...authorshipContractFields(flags));
+    contractFields.push(...authorshipContractFields(flags), ...gatewayContractFields(flags));
     const onchainUriLegs = onChainUri ? onchainUriSetupCalls({ generator, metadataRenderer }) : [];
     step('Deploy');
     const lane = laneFromFlags(flags);
@@ -4179,7 +4322,11 @@ export async function cmdDeployEditionCodeBody(flags, emit) {
     const depLegCount = dependencySetupCalls(deps, depRegistry).length;
     const approvals = 1 + (scriptChunks.length + schemas.length + depLegCount + onchainUriLegs.length + mintCount > 0 ? 1 : 0);
     if (!dryRun) {
-        await confirmSend(`About to deploy an edition code project "${name}" (${symbol}) — script ${bytes.length} bytes → ${scriptChunks.length} chunk(s); ` +
+        await confirmSend(
+        // Second site of the same missing binding as the plan line above — and the worse one: this is
+        // the REAL deploy path, so `deploy-code --copies` threw at the confirmation prompt, after the
+        // wallet and factory work was already done.
+        `About to deploy an edition code project "${name}" (${symbol}) — script ${Buffer.byteLength(source, 'utf8')} bytes → ${scriptChunks.length} chunk(s); ` +
             `up to ${max} id(s) × ${editionSize === 0n ? 'open' : editionSize.toString()} cop${editionSize === 1n ? 'y' : 'ies'} each; ` +
             `${onChainUri ? `tokenURI ON-CHAIN via the renderer (generator ${generator})` : `resolver base ${baseUrl}`}; ` +
             `mint: ${mintCount > 0 ? `${mintCount} id(s) × ${mintAmount} at deploy` : 'deferred'}; approvals: ${approvals} wallet approval(s); owner+royalty: your wallet @ ${royaltyBps / 100}%.` +
@@ -4208,7 +4355,10 @@ export async function cmdDeployEditionCodeBody(flags, emit) {
         if (shownAddr)
             info(`deterministic address: ${shownAddr}`);
         info(`name "${name}" · symbol ${symbol} · max ${max} id(s) · royalty ${royaltyBps / 100}%`);
-        info(`content: script ${bytes.length} bytes → ${scriptChunks.length} on-chain chunk(s)`);
+        // `source` is what this lane read; there has never been a `bytes` binding here, so this line
+        // threw a ReferenceError for every `deploy-code --copies … --dry-run` — the dry run crashed at the
+        // last step of the plan it was printing. Byte length, not UTF-16 code units, matching the 721 twin.
+        info(`content: script ${Buffer.byteLength(source, 'utf8')} bytes → ${scriptChunks.length} on-chain chunk(s)`);
         printSeedSourcePlan(seedSource, chainId);
         info(`PostParam schema(s): ${schemas.length ? schemas.map((s) => describeSchema(s)).join(', ') : 'none'}`);
         info(`mint: ${mintCount > 0 ? `${mintCount} id(s) × ${mintAmount} cop${mintAmount === 1n ? 'y' : 'ies'} → ${deployer ?? 'your wallet'} at deploy` : 'deferred (mint later / external minter)'}`);