@artblocks/abx-token-api 0.1.0-alpha.2 → 0.1.0-alpha.20

package/dist/metadata.js

@@ -1,6 +1,6 @@
-import { fieldOf, inlineText, renderArtifactKey, stitchAttributes, verifyAgainstHash, METADATA_FIELD as F, METADATA_REPRESENTATION as R, } from '@artblocks/abx-sdk';
+import { fieldOf, inlineText, renderArtifactKey, stitchAttributes, verifyAgainstHash, METADATA_FIELD as F, METADATA_REPRESENTATION as R, gatewayConfigFromEnv, projectGatewayPrefix, projectGatewayUrl, } from '@artblocks/abx-sdk';
 import { contentTypeFromPath } from '@artblocks/abx-storage';
-import { resolveFieldRendered, resolveFieldText, COLLECTION_TOKEN_ID } from './resolve.js';
+import { resolveFieldBytes, resolveFieldRendered, COLLECTION_TOKEN_ID } from './resolve.js';
 import { currentRenderArtifact, currentSettledInputsHash, isCodeProject, liveViewEnabled, liveViewUrl } from './code.js';
 /**
  * Standard, marketplace-facing metadata, built from the reconstructed projection by the
@@ -11,12 +11,29 @@ import { currentRenderArtifact, currentSettledInputsHash, isCodeProject, liveVie
 export function tokenImageUrl(baseUrl, chainId, address, tokenId) {
     return `${baseUrl}/t/${chainId}/${address}/${tokenId}/image`;
 }
+/** How the bytes reached the document — the off-chain twin of `AbxMetadataRenderer._sourceNote`.
+ *  `url`/`url-template` say "locator" because that is what the REPRESENTATION means by
+ *  construction, not because anything parsed the string. */
+const sourceNote = (rep) => {
+    if (rep === R.url)
+        return 'stored on chain; the value is a locator';
+    if (rep === R.urlTemplate)
+        return 'composed on chain from a stored template; a locator';
+    if (rep === R.renderer)
+        return 'computed on chain (field renderer)';
+    if (rep === R.inlineGzip || rep === R.readerGzip)
+        return `stored on chain (${rep} — inflated off-chain)`;
+    if (rep === R.reader)
+        return 'stored on chain (chunked)';
+    return 'stored on chain';
+};
 const onChainProv = (field, rep, fromCollection = false) => ({
     field,
     source: rep,
-    onChain: true, // the bytes live on-chain (gzip variants are just inflated off-chain on the way out)
     status: 'on-chain',
-    note: scopeNote(rep === R.inlineGzip || rep === R.readerGzip ? `on-chain (${rep} — inflated off-chain)` : `on-chain (${rep})`, fromCollection),
+    // Mirrors AbxMetadataRenderer._sourceNote exactly — the two lanes describe the same routes in
+    // the same words, and neither claims anything about where a value RESOLVES.
+    note: scopeNote(sourceNote(rep), fromCollection),
 });
 /** Tag a provenance note with `[collection]` when the value came from the collection scope
  *  (a token field fell back to the contract-wide field). Mirrors the on-chain renderer. */
@@ -50,34 +67,134 @@ function offChainProv(field, entry, served) {
         : verified === false
             ? `off-chain bytes; on-chain ${anchor} anchor MISMATCH`
             : 'off-chain operator metadata; no on-chain anchor';
-    return { field, source: 'off-chain', onChain: false, status, anchor, note };
+    return { field, source: 'off-chain', status, anchor, note };
 }
 const placeholderProv = (field, note = 'placeholder — unset') => ({
     field,
     source: 'placeholder',
-    onChain: false,
     status: 'n/a',
     note,
 });
-/** The `name` fallback: the ERC-721 `name()` (on-chain contract storage) + tokenId. `source`
- *  is "fallback" (not from the metadata field store) but the value is reconstructable from
- *  chain alone, so it's `on-chain` — mirrors the on-chain renderer's _resolveName. */
+/** The `name` fallback: the contract's `name()` (on-chain storage — `CollectionMetadataLib`,
+ *  shared by the 721 and 1155 bases) + tokenId. `source` is "fallback" (not from the metadata
+ *  field store) but the value is reconstructable from chain alone, so it's `on-chain` — mirrors
+ *  the on-chain renderer's _resolveName. */
 const fallbackNameProv = (note) => ({
     field: F.name,
     source: 'fallback',
-    onChain: true,
     status: 'on-chain',
     note,
 });
-/** Resolve a text field: on-chain content (inline/reader, gzip'd or not) → off-chain operator
- *  value → fallback default. On-chain content is decoded via the shared resolver (eth_call for
- *  `reader`), so a large reader-backed description resolves off-chain exactly as on-chain. */
-async function resolveText(client, fields, field, offChain, fallback, fallbackProv, opts = {}) {
+/**
+ * The `name` fallback's provenance, told truthfully about which read actually produced it.
+ *
+ * `state.name` is a value the spine only *pings*, so `reconstructProject` reads it at head — and a
+ * head read that fails is persisted as `null`, indistinguishable from a contract that genuinely has
+ * no name. The fallback then serves `state.address`, and the old note still claimed the value came
+ * from `ERC-721 name()`. A hosted node served `"name": "0xb844…c35e56 #0"` beside
+ * `note: "on-chain (ERC-721 name() + #id)"` while that contract's `name()` was `ABXdoku`; it
+ * self-corrected on the next re-index, which is the signature of the head-read theory.
+ *
+ * The wrong name is cosmetic. Provenance is the surface you'd point a creator at to audit their own
+ * metadata, so a false positive there costs more than the name does. We deliberately do NOT
+ * adjudicate *why* the read came back empty — the projection cannot tell an unnamed contract from a
+ * failed read, and guessing is how the original note came to lie.
+ */
+const nameFallbackProv = (named, suffix) => fallbackNameProv(named
+    ? `on-chain (name()${suffix})`
+    : `on-chain (contract address${suffix}) — name() returned no value`);
+/** Resolve a text field: on-chain content (inline/reader ±gzip, or `renderer` computed at read) →
+ *  off-chain operator value → fallback default. On-chain content is decoded via the shared resolver
+ *  (eth_call for `reader` and `renderer`), so a large reader-backed description resolves off-chain
+ *  exactly as on-chain.
+ *
+ *  `opts.uriRoute` marks a **URI-valued** field (`animation_url`): its stored bytes ARE the document,
+ *  so they cannot land as the value — a marketplace iframe would get HTML where it expected a URL.
+ *  The on-chain renderer has no URL space and must inline them as a `data:` URI; this node has one,
+ *  so it serves the same bytes at `uriRoute` (the data plane's `/…/data/{field}` route, declared
+ *  Content-Type, 302 to a durable locator when one exists) and carries the route as the value —
+ *  exactly what `image` has always done for the same content, through the same kind of route.
+ *
+ *  Why not the `data:` wrap here too: the value is repeated verbatim into the `artifacts` listing, so
+ *  a multi-megabyte inline document shipped TWICE in a document marketplaces re-fetch on every view,
+ *  while the sibling `image` — usually the smaller asset — shipped as a link. The wrap was also
+ *  already the exception rather than the rule off chain: a code project's `animation_url` has always
+ *  been the live-view route. A locator representation (`url`/`url-template`, or a computed
+ *  `text/uri-list`) still lands verbatim — it is already a URI, and re-hosting it would hide it.
+ *
+ *  `tokenAddress` is positional, not an opt, deliberately: it is only needed for the `renderer`
+ *  eth_call, and an optional field that silently disables a whole representation is exactly how
+ *  that branch went missing here in the first place. The compiler now makes every call site say it. */
+async function resolveText(client, tokenAddress, fields, field, offChain, fallback, 
+// Explicit `| undefined` rather than optional: `opts` after it carries the REQUIRED gateway
+// prefixes, and an optional parameter cannot precede a required one. Every call site already
+// passes this positionally anyway.
+fallbackProv, opts) {
     const { entry, fromCollection } = fieldWithFallback(fields, opts.collectionFields, field);
-    // on-chain content (inline/reader, ±gzip) → decoded value.
-    const onChain = await resolveFieldText(client, entry);
+    // on-chain content (inline/reader, ±gzip) → the document bytes, decoded.
+    const onChain = await resolveFieldBytes(client, entry);
     if (onChain !== null && entry) {
-        return { value: onChain, prov: onChainProv(field, entry.representation, fromCollection) };
+        // The bytes reached the document either way; `uriRoute` only decides whether they ride IN it.
+        const value = opts.uriRoute ?? new TextDecoder().decode(onChain);
+        return { value, prov: onChainProv(field, entry.representation, fromCollection) };
+    }
+    // Computed on-chain at read (`renderer`) — the field's value is a field-renderer address, so the
+    // content only exists after an eth_call. This branch mirrors {AbxMetadataRenderer._appendText}'s
+    // R_RENDERER arm **exactly**, because the two must agree: with `tokenURIRenderer` set the chain
+    // assembles this JSON and this resolver merely re-serves it, so any difference here is a resolver
+    // that contradicts the token's own tokenURI. Hence the declared contentType is used verbatim
+    // (`renderer` is the one representation that types itself on-chain) rather than assuming HTML.
+    //
+    // The `text/uri-list` exception (RFC 2483 — "this payload is a URI") carries the whole reason a
+    // URI-valued field can't just be data-wrapped: the computed bytes ARE a locator, so they land
+    // verbatim and stay dereferenceable. That is the canonical generator's directory branch.
+    let rendererFailure = null;
+    if (entry && entry.representation === R.renderer) {
+        try {
+            const rendered = await resolveFieldRendered(client, tokenAddress, opts.tokenId ?? COLLECTION_TOKEN_ID, field, entry);
+            if (rendered) {
+                const uriList = rendered.contentType === 'text/uri-list';
+                const text = new TextDecoder().decode(rendered.bytes);
+                // A computed locator lands verbatim (it IS a URI); computed CONTENT on a URI-valued field
+                // goes to the route, same as stored content above; a plain text field carries the text.
+                const value = uriList ? text.trim() : (opts.uriRoute ?? text);
+                // ONE provenance for both arms. The `text/uri-list` arm used to hand-build an object that
+                // was byte-identical to this call — same keys, same order, the same note string typed a
+                // second time — so the only thing the branch could ever do was drift from `sourceNote`.
+                // (Found by abx-services reading this function, not by a test: nothing observable differed.)
+                return { value, prov: onChainProv(field, R.renderer, fromCollection) };
+            }
+        }
+        catch (err) {
+            // `IAbxFieldRenderer`'s first invariant is NEVER REVERT, but a resolver cannot rely on a
+            // third-party contract honouring it — a reverting renderer must degrade this one field, not
+            // 500 the whole token's metadata. We still fall through to the operator's off-chain value
+            // (better than nothing), but the provenance says the on-chain attempt failed rather than
+            // quietly reporting `off-chain` as if nothing were committed on-chain.
+            rendererFailure = err.message;
+            console.warn(`[metadata] field renderer for '${field}' on ${tokenAddress} reverted: ${rendererFailure}`);
+        }
+    }
+    const noteRendererFailure = (out) => rendererFailure === null
+        ? out
+        : { ...out, prov: { ...out.prov, note: `${out.prov.note} — on-chain field renderer reverted, so it could not be used` } };
+    // Content-addressed locator (`ipfs`/`arweave`): the CID/txid is identity, the collection's
+    // preferred gateway is what makes it dereferenceable. Mirrors {AbxMetadataRenderer._appendText}'s
+    // v11 arm. A value that locates nothing (`ipfs://` with no CID) falls through and omits, rather
+    // than emitting a bare gateway prefix that 404s.
+    if (entry && (entry.representation === R.ipfs || entry.representation === R.arweave)) {
+        const wrapped = gatewayFieldUrl(entry, opts.gateways, opts.tokenId === COLLECTION_TOKEN_ID ? undefined : opts.tokenId);
+        if (wrapped !== null) {
+            return {
+                value: wrapped,
+                prov: {
+                    field,
+                    source: entry.representation,
+                    status: 'on-chain',
+                    note: scopeNote(GATEWAY_SOURCE_NOTE, fromCollection),
+                },
+            };
+        }
     }
     // on-chain locator carried AS the text value (url, or url-template with {id} substituted).
     if (entry && (entry.representation === R.url || entry.representation === R.urlTemplate)) {
@@ -88,19 +205,48 @@ async function resolveText(client, fields, field, offChain, fallback, fallbackPr
             prov: {
                 field,
                 source: entry.representation,
-                onChain: true,
                 status: 'on-chain',
-                note: scopeNote(`on-chain ${entry.representation} -> off-chain content`, fromCollection),
+                note: scopeNote('stored on chain; the value is a locator', fromCollection),
             },
         };
     }
     if (offChain != null) {
-        return { value: offChain, prov: offChainProv(field, entry, offChain) };
+        return noteRendererFailure({ value: offChain, prov: offChainProv(field, entry, offChain) });
     }
     if (fallback != null) {
-        return { value: fallback, prov: fallbackProv ?? placeholderProv(field, 'default (no on-chain or off-chain value)') };
+        return noteRendererFailure({
+            value: fallback,
+            prov: fallbackProv ?? placeholderProv(field, 'default (no on-chain or off-chain value)'),
+        });
     }
-    return { value: null, prov: placeholderProv(field) };
+    return noteRendererFailure({ value: null, prov: placeholderProv(field) });
+}
+/**
+ * The project's preferred gateway prefix per scheme, resolved ONCE per document.
+ *
+ * The off-chain twin of `AbxMetadataRenderer._gatewayPrefix` (spec v11): the collection's reserved
+ * `abx_gateway_ipfs` / `abx_gateway_arweave` field, else this host's env default, else the public
+ * floor. Two conforming resolvers given the same chain must emit the same `image`, so the env read
+ * is a FLOOR and never an override — a project that stated a preference on chain gets that
+ * preference from every resolver, and a host's own gateway only ever fills a silence (which is the
+ * only way a managed provider serving a token it does not own can offer a better default).
+ */
+export function projectGateways(state) {
+    const env = gatewayConfigFromEnv();
+    return {
+        ipfs: projectGatewayPrefix(state, 'ipfs', env),
+        arweave: projectGatewayPrefix(state, 'arweave', env),
+    };
+}
+/** The provenance note for a content-addressed locator. Byte-identical to the deployed renderer's
+ *  `_sourceNote` for `ipfs`/`arweave` — deliberately "served through", never "verified": the
+ *  locator is on chain, the bytes are not, and nothing here re-hashes what a gateway returns. */
+const GATEWAY_SOURCE_NOTE = "stored on chain; a content-addressed locator, served through the collection's preferred gateway";
+/** Project a content-addressed field value the way the deployed renderer does, or `null` when the
+ *  value locates nothing. `tokenId` omitted ⇒ no `{id}` substitution (the collection surface). */
+function gatewayFieldUrl(entry, gateways, tokenId) {
+    const network = entry.representation === R.ipfs ? 'ipfs' : 'arweave';
+    return projectGatewayUrl(network, inlineText(entry).trim(), gateways[network], tokenId);
 }
 /**
  * Map a locator to the provenance `source` describing where the bytes actually live. Locators are
@@ -125,7 +271,10 @@ function sourceForLocator(locator) {
  *    one (bridged or from the active backend) so the heavy asset resolves peer-to-peer; else
  *    this node's `/…/image` route serves it from custody. Either way it's `anchored` by the
  *    on-chain hash (verify via `/verify`).
- *  - locator on-chain (`ipfs`/`arweave`/`url`) → the on-chain pointer IS the URL; `on-chain`.
+ *  - content-addressed on-chain (`ipfs`/`arweave`) → the CID/txid wrapped in the collection's
+ *    preferred gateway prefix, so what lands in `image` is an `https://` a wallet can render;
+ *    `on-chain`.
+ *  - locator on-chain (`url`) → the on-chain pointer IS the URL; `on-chain`.
  *  - unset → this node's `/…/image` route serves the deterministic generative placeholder.
  */
 async function resolveImage(state, token, baseUrl, chainId, display, storage) {
@@ -151,7 +300,6 @@ async function resolveImage(state, token, baseUrl, chainId, display, storage) {
             prov: {
                 field: F.image,
                 source: 'url-template',
-                onChain: true,
                 status: 'on-chain',
                 note: scopeNote('on-chain url template -> off-chain content', fromCollection),
             },
@@ -168,7 +316,6 @@ async function resolveImage(state, token, baseUrl, chainId, display, storage) {
                 prov: {
                     field: F.image,
                     source: sourceForLocator(locator),
-                    onChain: false,
                     status: 'anchored',
                     anchor,
                     note: `off-chain bytes (${sourceForLocator(locator)}); on-chain ${anchor} integrity anchor`,
@@ -181,7 +328,6 @@ async function resolveImage(state, token, baseUrl, chainId, display, storage) {
             prov: {
                 field: F.image,
                 source: anchor,
-                onChain: false,
                 status: 'anchored',
                 anchor,
                 note: `off-chain bytes (served by this node); on-chain ${anchor} integrity anchor`,
@@ -189,27 +335,41 @@ async function resolveImage(state, token, baseUrl, chainId, display, storage) {
         };
     }
     // Computed on-chain (`renderer`): the value is a field-renderer address, not a locator — point
-    // at this node's route, which eth_calls the renderer and serves the computed bytes.
+    // at this node's route, which eth_calls the renderer and serves the computed bytes (302-ing to the
+    // locator if the computed content turns out to BE one). The provenance is the shared one: the route
+    // the bytes took is identical to any other on-chain content, and only the served `image` VALUE is
+    // this field's documented exception. A hand-built note here drifted from the deployed renderer's
+    // `_sourceNote` wording for the same representation.
     if (entry.representation === R.renderer) {
-        return {
-            url: nodeUrl,
-            prov: {
-                field: F.image,
-                source: 'renderer',
-                onChain: true,
-                status: 'on-chain',
-                note: scopeNote('on-chain field renderer (computed from chain state at read)', fromCollection),
-            },
-        };
+        return { url: nodeUrl, prov: onChainProv(F.image, R.renderer, fromCollection) };
     }
-    // Locator committed ON-CHAIN (ipfs/arweave/url): the on-chain value is itself the address.
+    // Content-addressed ON-CHAIN (ipfs/arweave): the value is identity, not a URL. Wrap it in the
+    // collection's preferred gateway — the twin of {AbxMetadataRenderer._resolveImage}'s v11 arm.
+    // Before v11 both planes emitted the raw `ipfs://…` here, which no marketplace dereferences, and
+    // `--onchain-uri --backend ipfs` worked around it by baking a gateway host into a `url` field.
+    if (entry.representation === R.ipfs || entry.representation === R.arweave) {
+        const wrapped = gatewayFieldUrl(entry, projectGateways(state), token.tokenId);
+        if (wrapped !== null) {
+            return {
+                url: wrapped,
+                prov: {
+                    field: F.image,
+                    source: entry.representation,
+                    status: 'on-chain',
+                    note: scopeNote(GATEWAY_SOURCE_NOTE, fromCollection),
+                },
+            };
+        }
+        // locates nothing → fall through to the node's placeholder route rather than a bare prefix
+        return { url: nodeUrl, prov: placeholderProv(F.image, 'placeholder — the committed locator names no content') };
+    }
+    // Locator committed ON-CHAIN (url): the on-chain value is itself the address.
     const onChainLocator = inlineText(entry).trim();
     return {
         url: onChainLocator || nodeUrl,
         prov: {
             field: F.image,
             source: entry.representation,
-            onChain: true,
             status: 'on-chain',
             note: scopeNote(`on-chain pointer (${entry.representation}) — bytes off-chain, located on-chain`, fromCollection),
         },
@@ -250,7 +410,11 @@ export async function fieldMimeType(client, state, entry, field, tokenId, displa
         return (await rendererContentType(client, state.address, entry, field, tokenId)) ?? 'application/octet-stream';
     }
     if (rep === R.inline || rep === R.inlineGzip || rep === R.reader || rep === R.readerGzip) {
-        return field === F.image ? 'image/svg+xml' : 'application/octet-stream';
+        // registry conventions for on-chain content bytes: an `image` is SVG, an `animation_url` is
+        // the HTML document the renderer wraps as `data:text/html` (spec v4). Anything else: the floor.
+        if (field === F.image)
+            return 'image/svg+xml';
+        return field === F.animationUrl ? 'text/html' : 'application/octet-stream';
     }
     if (rep === R.keccak256 || rep === R.sha256) {
         const stored = storage ? await storage.get(entry.value).catch(() => null) : null;
@@ -260,15 +424,21 @@ export async function fieldMimeType(client, state, entry, field, tokenId, displa
         return bridged ? contentTypeFromPath(bridged) : 'application/octet-stream';
     }
     const raw = inlineText(entry).trim();
+    // For ipfs/arweave the extension (if any) rides the stored value — no need to wrap first, and
+    // wrapping would only add a gateway host that never carries the extension.
     return contentTypeFromPath(rep === R.urlTemplate ? applyTemplate(raw, tokenId) : raw);
 }
 /** A field artifact's `uri`: locator forms verbatim (content-addressed preferred, `{id}`
  *  substituted); custody-hash forms prefer the bridged durable locator; everything this node
  *  serves itself (inline/reader/renderer) rides the given `/data/{field}` route. Total — every
  *  representation resolves to some uri (the complete-listing rule). */
-function fieldArtifactUri(entry, dataRoute, tokenId, display) {
+function fieldArtifactUri(entry, dataRoute, tokenId, display, gateways) {
     const rep = entry.representation;
-    if (rep === R.url || rep === R.ipfs || rep === R.arweave)
+    // Content-addressed forms carry the same gateway wrap the projected fields get, so a manifest
+    // entry and the `image` it duplicates never point at two different URLs for the same bytes.
+    if (rep === R.ipfs || rep === R.arweave)
+        return gatewayFieldUrl(entry, gateways, tokenId) ?? dataRoute;
+    if (rep === R.url)
         return inlineText(entry).trim() || dataRoute;
     if (rep === R.urlTemplate)
         return applyTemplate(inlineText(entry), tokenId);
@@ -283,21 +453,17 @@ function artifactFieldProv(field, entry, fromCollection) {
     if (rep === R.inline || rep === R.inlineGzip || rep === R.reader || rep === R.readerGzip) {
         return onChainProv(field, rep, fromCollection);
     }
-    if (rep === R.renderer) {
-        return {
-            field,
-            source: 'renderer',
-            onChain: true,
-            status: 'on-chain',
-            note: scopeNote('on-chain field renderer (computed from chain state at read)', fromCollection),
-        };
-    }
+    // Same call as the branch above — `renderer` is on-chain content like `inline`/`reader`, and the
+    // note belongs to `sourceNote` (which mirrors the deployed renderer's `_sourceNote` verbatim). This
+    // branch used to hand-build the object with a longer note of its own, so one function delegated in
+    // one arm and duplicated in the next.
+    if (rep === R.renderer)
+        return onChainProv(field, rep, fromCollection);
     if (rep === R.keccak256 || rep === R.sha256) {
         const anchor = rep;
         return {
             field,
             source: anchor,
-            onChain: false,
             status: 'anchored',
             anchor,
             note: `off-chain bytes; on-chain ${anchor} integrity anchor`,
@@ -306,7 +472,6 @@ function artifactFieldProv(field, entry, fromCollection) {
     return {
         field,
         source: rep,
-        onChain: true,
         status: 'on-chain',
         note: scopeNote(`on-chain pointer (${rep}) — bytes off-chain, located on-chain`, fromCollection),
     };
@@ -352,7 +517,7 @@ async function buildTokenArtifacts(client, state, token, baseUrl, chainId, displ
         entries.push({
             key: name,
             mimeType: await fieldMimeType(client, state, entry, name, token.tokenId, display, storage),
-            uri: fieldArtifactUri(entry, `${baseUrl}/t/${chainId}/${state.address}/${token.tokenId}/data/${name}`, token.tokenId, display),
+            uri: fieldArtifactUri(entry, `${baseUrl}/t/${chainId}/${state.address}/${token.tokenId}/data/${name}`, token.tokenId, display, projectGateways(state)),
         });
         prov.push(artifactFieldProv(name, entry, fromCollection));
     }
@@ -375,7 +540,6 @@ async function buildTokenArtifacts(client, state, token, baseUrl, chainId, displ
             prov.push({
                 field: key,
                 source: `effect:${row.effectKey}`,
-                onChain: false,
                 status: 'off-chain',
                 note: 'derived effect output at the current inputsHash (re-creatable bytes)',
             });
@@ -408,7 +572,6 @@ function resolveAttributes(fields, offChain, collectionFields, fromRender = fals
         prov = {
             field: F.attributes,
             source: 'inline',
-            onChain: true,
             status: 'on-chain',
             note: fromRender
                 ? 'on-chain inline JSON + render-effect traits (+ operator), stitched (on-chain wins per trait_type)'
@@ -425,7 +588,6 @@ function resolveAttributes(fields, offChain, collectionFields, fromRender = fals
         prov = {
             field: F.attributes,
             source: fromRender ? 'effect:render' : 'off-chain',
-            onChain: false,
             status: 'off-chain',
             note: fromRender
                 ? 'script-reported traits captured at render (+ operator traits; render wins per trait_type)'
@@ -434,7 +596,8 @@ function resolveAttributes(fields, offChain, collectionFields, fromRender = fals
     }
     return { attributes: merged, prov };
 }
-/** ERC-721 metadata JSON for a token (the `tokenURI` target) + `abx_provenance` + `artifacts`. */
+/** Token metadata JSON — the `tokenURI` target (ERC-721) / the `uri(id)` target (ERC-1155
+ *  editions), assembled identically either way + `abx_provenance` + `artifacts`. */
 export async function buildTokenMetadata(client, state, token, baseUrl, chainId, display = {}, storage, 
 // The effect-artifact registry read surface: rows a producer PUBLISHED to this resolver (or
 // recorded co-located). Feeds the `artifacts` manifest and the image seam's locator check —
@@ -463,7 +626,6 @@ plane) {
                 image.prov = {
                     field: F.image,
                     source: 'effect:render',
-                    onChain: false,
                     status: 'off-chain',
                     note: viaLocator
                         ? 'render effect output at the current inputsHash, published as a durable locator (resolver 302-redirects)'
@@ -484,12 +646,12 @@ plane) {
     // on-chain renderer's `_field`), and url-template fields substitute this token's id.
     const cf = state.collectionFields;
     const tid = token.tokenId;
-    const opts = { collectionFields: cf, tokenId: tid };
-    const name = await resolveText(client, f, F.name, undefined, `${state.name ?? state.address} #${token.tokenId}`, fallbackNameProv('on-chain (ERC-721 name() + #id)'), opts);
-    const description = await resolveText(client, f, F.description, display.description, null, undefined, opts); // optional → omit if unset
-    const externalUrl = await resolveText(client, f, F.externalUrl, display.externalUrl, null, undefined, opts); // optional → omit if unset
-    const backgroundColor = await resolveText(client, f, F.backgroundColor, undefined, null, undefined, opts);
-    const youtubeUrl = await resolveText(client, f, F.youtubeUrl, undefined, null, undefined, opts);
+    const opts = { collectionFields: cf, tokenId: tid, gateways: projectGateways(state) };
+    const name = await resolveText(client, state.address, f, F.name, undefined, `${state.name ?? state.address} #${token.tokenId}`, nameFallbackProv(state.name != null, ' + #id'), opts);
+    const description = await resolveText(client, state.address, f, F.description, display.description, null, undefined, opts); // optional → omit if unset
+    const externalUrl = await resolveText(client, state.address, f, F.externalUrl, display.externalUrl, null, undefined, opts); // optional → omit if unset
+    const backgroundColor = await resolveText(client, state.address, f, F.backgroundColor, undefined, null, undefined, opts);
+    const youtubeUrl = await resolveText(client, state.address, f, F.youtubeUrl, undefined, null, undefined, opts);
     provenance.push(name.prov); // name is required — always present
     // image: required — always served via our URL; image_data carries inline SVG if on-chain SVG.
     const img = fieldOf(f, F.image);
@@ -501,8 +663,13 @@ plane) {
     if (externalUrl.value !== null)
         provenance.push(externalUrl.prov);
     // animation_url: an explicit `animation` field wins; else a code project derives the
-    // live-view route (suppressible via the `display.animation = none` contract param).
-    const animation = await resolveText(client, f, F.animationUrl, undefined, null, undefined, opts);
+    // live-view route (suppressible via the `display.animation = none` contract param). On-chain
+    // content is served at this node's data route rather than inlined (see `uriRoute`); locator forms
+    // pass through untouched. The on-chain renderer still inlines it — it has no route to offer.
+    const animation = await resolveText(client, state.address, f, F.animationUrl, undefined, null, undefined, {
+        ...opts,
+        uriRoute: `${baseUrl}/t/${chainId}/${state.address}/${token.tokenId}/data/${F.animationUrl}`,
+    });
     let animationValue = animation.value;
     let animationProv = animation.prov;
     if (animationValue === null && liveViewEnabled(state)) {
@@ -510,7 +677,6 @@ plane) {
         animationProv = {
             field: F.animationUrl,
             source: 'live-view',
-            onChain: false,
             status: 'off-chain',
             note: 'live view derived from the on-chain code (canonical tokenData injected at load)',
         };
@@ -522,22 +688,27 @@ plane) {
     // traits (captured at the current inputsHash), which win over the operator's off-chain
     // traits. ABX facts (version, canonical, royalty) are NOT traits; they live in this
     // provenance block / ERC-2981, never in the marketplace trait array.
+    // `traits` is a BOUND output (`effects.md → Bound vs referenced`): its content is held by this
+    // node, so there are exactly two places it can be, and BOTH are hash-gated by the key itself —
+    // a param change re-addresses the key, so stale traits go unstitched rather than being attributed
+    // to a state they don't depict.
+    //   - the registry row (a producer REGISTERED it over /v1/effect-artifacts: bytes ride the row),
+    //   - this node's storage (a CO-LOCATED runner wrote the artifact to the shared backend).
     let renderTraits = null;
-    if (isCodeProject(state) && storage) {
+    if (isCodeProject(state) && (plane || storage)) {
         try {
-            const { key, found } = await currentRenderArtifact(client, state, token, storage, 'traits', {
+            const { key, found } = await currentRenderArtifact(client, state, token, storage ?? undefined, 'traits', {
                 hash: settledHash ?? undefined,
             });
-            if (found) {
-                const artifact = await storage.get(key);
-                const parsed = artifact ? JSON.parse(new TextDecoder().decode(artifact.bytes)) : null;
-                // scripts report either the OpenSea array or the natural object form
-                // (`abx.traits({Palette: 'Dusk'})`) — normalize the latter.
-                if (Array.isArray(parsed))
-                    renderTraits = parsed;
-                else if (parsed && typeof parsed === 'object') {
-                    renderTraits = Object.entries(parsed).map(([trait_type, value]) => ({ trait_type, value: value }));
-                }
+            const boundBytes = plane?.get(key)?.bytes ?? null;
+            const raw = boundBytes ?? (found ? (await storage?.get(key))?.bytes ?? null : null);
+            const parsed = raw ? JSON.parse(new TextDecoder().decode(raw)) : null;
+            // scripts report either the OpenSea array or the natural object form
+            // (`abx.traits({Palette: 'Dusk'})`) — normalize the latter.
+            if (Array.isArray(parsed))
+                renderTraits = parsed;
+            else if (parsed && typeof parsed === 'object') {
+                renderTraits = Object.entries(parsed).map(([trait_type, value]) => ({ trait_type, value: value }));
             }
         }
         catch {
@@ -555,6 +726,13 @@ plane) {
         provenance.push(backgroundColor.prov);
     if (youtubeUrl.value)
         provenance.push(youtubeUrl.prov);
+    // NO `abx_params` block. It was emitted here and by the on-chain renderer and read back by
+    // nobody — the only consumers in the repo were its own tests. Params already enumerate directly
+    // from the contract (`tokenParamKeys` / `tokenParam` / `paramSchemaKeys`), which is canonical and
+    // needs no indexer, and a code project's script gets them through `tokenData`. So the projection
+    // was a third serialization of data available two better ways: uncapped in size, quadratic to
+    // build, and duplicated across two implementations — which is precisely the sibling drift that
+    // produced the computed-image-locator bug. Traits that belong to marketplaces go in `attributes`.
     // the `artifacts` manifest — the plane's complete listing (data-plane.md). Omitted when empty.
     const artifacts = await buildTokenArtifacts(client, state, token, baseUrl, chainId, display, storage, plane, {
         imageUrl: image.url,
@@ -592,20 +770,24 @@ export async function buildContractMetadata(client, state, baseUrl, chainId, dis
     const f = state.collectionFields;
     const provenance = [];
     // Representative image: the first token that actually carries an `image` field, else the
-    // first token — so "first with an image" surfaces a real artwork rather than a placeholder.
+    // first token — so "first with an image" surfaces a real work rather than a placeholder.
     const rep = state.tokens.find((t) => fieldOf(t.fields, F.image)) ?? state.tokens[0];
     const image = rep ? await resolveImage(state, rep, baseUrl, chainId, display, storage) : undefined;
-    // name is required (fallback = the ERC-721 collection name); description + external_link
+    // The collection surface has no token, so a `renderer`-represented field is called with the
+    // sentinel id — the same one {AbxMetadataRenderer} passes for its collection reads, so a field
+    // renderer that serves both scopes sees an identical call from chain and from here.
+    const collOpts = { tokenId: COLLECTION_TOKEN_ID, gateways: projectGateways(state) };
+    // name is required (fallback = the on-chain collection name); description + external_link
     // are optional → omit when neither on-chain nor operator-supplied (no boilerplate).
-    const name = await resolveText(client, f, F.name, undefined, state.name ?? state.address, fallbackNameProv('on-chain (ERC-721 name())'));
-    const description = await resolveText(client, f, F.description, display.description, null);
-    const externalLink = await resolveText(client, f, F.externalLink, display.externalUrl, null);
+    const name = await resolveText(client, state.address, f, F.name, undefined, state.name ?? state.address, nameFallbackProv(state.name != null, ''), collOpts);
+    const description = await resolveText(client, state.address, f, F.description, display.description, null, undefined, collOpts);
+    const externalLink = await resolveText(client, state.address, f, F.externalLink, display.externalUrl, null, undefined, collOpts);
     // authorship + rights (collection scope) — reserved fields, on-chain-only (no operator source):
     // included only when the creator set them on-chain, omitted otherwise (no boilerplate).
-    const artist = await resolveText(client, f, F.artist, undefined, null);
-    const displayNotes = await resolveText(client, f, F.displayNotes, undefined, null);
-    const artistLinks = await resolveText(client, f, F.artistLinks, undefined, null);
-    const license = await resolveText(client, f, F.license, undefined, null);
+    const creator = await resolveText(client, state.address, f, F.creator, undefined, null, undefined, collOpts);
+    const displayNotes = await resolveText(client, state.address, f, F.displayNotes, undefined, null, undefined, collOpts);
+    const creatorLinks = await resolveText(client, state.address, f, F.creatorLinks, undefined, null, undefined, collOpts);
+    const license = await resolveText(client, state.address, f, F.license, undefined, null, undefined, collOpts);
     provenance.push(name.prov);
     if (image)
         provenance.push(image.prov);
@@ -613,18 +795,28 @@ export async function buildContractMetadata(client, state, baseUrl, chainId, dis
         provenance.push(description.prov);
     if (externalLink.value !== null)
         provenance.push(externalLink.prov);
-    if (artist.value !== null)
-        provenance.push(artist.prov);
+    if (creator.value !== null)
+        provenance.push(creator.prov);
     if (displayNotes.value !== null)
         provenance.push(displayNotes.prov);
-    if (artistLinks.value !== null)
-        provenance.push(artistLinks.prov);
+    if (creatorLinks.value !== null)
+        provenance.push(creatorLinks.prov);
     if (license.value !== null)
         provenance.push(license.prov);
-    const banner = fieldOf(f, F.bannerImage);
-    const bannerImage = banner && banner.representation === R.url ? inlineText(banner) : null;
-    if (bannerImage)
-        provenance.push(onChainProv(F.bannerImage, R.url));
+    // The two reserved collection IMAGE keys. Both are top-level here, and both are top-level on the
+    // on-chain renderer as of spec v10 — the point of the three-list table in
+    // specs/protocol/onchain-metadata.md is that a key BOTH planes can emit must not be emitted by only
+    // one of them. Two things were wrong before v10: `featured_image` appeared in `artifacts` alone
+    // (reserved, so filtered out of the top level, yet still listed — "reserved but only in artifacts",
+    // which is neither), and `banner_image` was top-level only for `representation === url`, so an
+    // `inline` or `reader` banner silently dropped even though both resolve fine. Every chain-reachable
+    // representation now counts, matching `_appendContractText` on the renderer.
+    const bannerImage = await resolveText(client, state.address, f, F.bannerImage, undefined, null, undefined, collOpts);
+    const featuredImage = await resolveText(client, state.address, f, F.featuredImage, undefined, null, undefined, collOpts);
+    if (bannerImage.value !== null)
+        provenance.push(bannerImage.prov);
+    if (featuredImage.value !== null)
+        provenance.push(featuredImage.prov);
     // the collection-scope `artifacts` manifest — content-bearing collection fields (banner,
     // featured image, plus any non-reserved field). The representative-token image is a projection
     // courtesy, not a collection artifact; a collection-scope `image` doubles as the per-token
@@ -641,7 +833,7 @@ export async function buildContractMetadata(client, state, baseUrl, chainId, dis
             key: n,
             // collection surface has no token — a field renderer gets the sentinel id (mirrors on-chain)
             mimeType: await fieldMimeType(client, state, entry, n, COLLECTION_TOKEN_ID, display, storage),
-            uri: fieldArtifactUri(entry, `${baseUrl}/c/${chainId}/${state.address}/data/${n}`, '0', display),
+            uri: fieldArtifactUri(entry, `${baseUrl}/c/${chainId}/${state.address}/data/${n}`, '0', display, collOpts.gateways),
         });
         if (!RESERVED_FIELDS.has(n))
             provenance.push(artifactFieldProv(n, entry, false));
@@ -656,16 +848,18 @@ export async function buildContractMetadata(client, state, baseUrl, chainId, dis
         json.description = description.value;
     if (externalLink.value !== null)
         json.external_link = externalLink.value;
-    if (artist.value !== null)
-        json.artist = artist.value;
+    if (creator.value !== null)
+        json.creator = creator.value;
     if (displayNotes.value !== null)
         json.display_notes = displayNotes.value;
-    if (artistLinks.value !== null)
-        json.artist_links = artistLinks.value;
+    if (creatorLinks.value !== null)
+        json.creator_links = creatorLinks.value;
     if (license.value !== null)
         json.license = license.value;
-    if (bannerImage)
-        json.banner_image = bannerImage;
+    if (bannerImage.value !== null)
+        json.banner_image = bannerImage.value;
+    if (featuredImage.value !== null)
+        json.featured_image = featuredImage.value;
     if (artifacts.length)
         json.artifacts = artifacts;
     return json;