@artblocks/abx-token-api 0.1.0-alpha.0

package/dist/metadata.js

@@ -0,0 +1,673 @@
+import { fieldOf, inlineText, renderArtifactKey, stitchAttributes, verifyAgainstHash, METADATA_FIELD as F, METADATA_REPRESENTATION as R, } from '@artblocks/abx-sdk';
+import { contentTypeFromPath } from '@artblocks/abx-storage';
+import { resolveFieldRendered, resolveFieldText, 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
+ * protocol rule: each field has ONE active on-chain representation — if set, it wins;
+ * otherwise the off-chain operator value fills in; otherwise a default. Every served field
+ * gets an `abx_provenance` entry saying where it came from and whether the chain vouches for it.
+ */
+export function tokenImageUrl(baseUrl, chainId, address, tokenId) {
+    return `${baseUrl}/t/${chainId}/${address}/${tokenId}/image`;
+}
+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),
+});
+/** 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. */
+const scopeNote = (note, fromCollection) => (fromCollection ? `${note} [collection]` : note);
+/** Substitute the decimal tokenId for every `{id}` in a URL template (mirrors the renderer). */
+const applyTemplate = (template, tokenId) => template.split('{id}').join(tokenId);
+/**
+ * Read a token field with COLLECTION-scope fallback: the token-scope field wins; else the
+ * contract-wide field. Mirrors {AbxMetadataRenderer._field}, so one collection-scope field
+ * (e.g. an `image` `url-template`) covers every token in O(1) storage.
+ */
+function fieldWithFallback(tokenFields, collectionFields, field) {
+    const t = fieldOf(tokenFields, field);
+    if (t)
+        return { entry: t, fromCollection: false };
+    const c = collectionFields ? fieldOf(collectionFields, field) : null;
+    return { entry: c, fromCollection: !!c };
+}
+/** Provenance for an off-chain-served value, verified against the field's hash anchor if it carries one. */
+function offChainProv(field, entry, served) {
+    const verified = entry ? verifyAgainstHash(served, entry) : null;
+    const anchor = entry && (entry.representation === R.keccak256 || entry.representation === R.sha256)
+        ? entry.representation
+        : undefined;
+    const status = verified === true ? 'verified' : verified === false ? 'mismatch' : 'off-chain';
+    // Notes are a short, DECLARATIVE gloss for whoever reads the served JSON (marketplaces, clients)
+    // — never an operator instruction ("run abx …"); the structured fields carry the signal, and
+    // how-to-act guidance lives in the CLI/skill, not the public metadata.
+    const note = verified === true
+        ? `off-chain bytes; on-chain ${anchor} anchor verified`
+        : 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 };
+}
+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. */
+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 = {}) {
+    const { entry, fromCollection } = fieldWithFallback(fields, opts.collectionFields, field);
+    // on-chain content (inline/reader, ±gzip) → decoded value.
+    const onChain = await resolveFieldText(client, entry);
+    if (onChain !== null && entry) {
+        return { value: onChain, prov: onChainProv(field, entry.representation, 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)) {
+        const raw = inlineText(entry);
+        const value = entry.representation === R.urlTemplate && opts.tokenId != null ? applyTemplate(raw, opts.tokenId) : raw;
+        return {
+            value,
+            prov: {
+                field,
+                source: entry.representation,
+                onChain: true,
+                status: 'on-chain',
+                note: scopeNote(`on-chain ${entry.representation} -> off-chain content`, fromCollection),
+            },
+        };
+    }
+    if (offChain != null) {
+        return { 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 { value: null, prov: placeholderProv(field) };
+}
+/**
+ * Map a locator to the provenance `source` describing where the bytes actually live. Locators are
+ * typically **gateway HTTPS URLs** (`https://<gw>/ipfs/<cid>`, `https://<gw>/<txid>`) — the form
+ * that renders everywhere — so we detect the backend from the URL shape, not just a `ipfs://`/`ar://`
+ * scheme. An IPFS gateway URL still reports `source: ipfs` (not the generic `url`).
+ */
+function sourceForLocator(locator) {
+    const l = locator.toLowerCase();
+    if (l.startsWith('ipfs://') || l.includes('/ipfs/') || /\.ipfs\./.test(l))
+        return 'ipfs';
+    if (l.startsWith('ar://') || l.includes('arweave.net'))
+        return 'arweave';
+    return 'url';
+}
+/**
+ * The `image` URL the metadata points at, with matching provenance. The image is *required*,
+ * so this always returns a usable URL. Cases, by the field's single active representation:
+ *  - on-chain content (`inline`/`reader`, ±gzip) → this node's `/…/image` route serves the
+ *    decoded bytes; `on-chain`.
+ *  - off-chain by hash (`keccak256`/`sha256`) → a durable `ipfs://`/`ar://` locator when we have
+ *    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`.
+ *  - unset → this node's `/…/image` route serves the deterministic generative placeholder.
+ */
+async function resolveImage(state, token, baseUrl, chainId, display, storage) {
+    const nodeUrl = tokenImageUrl(baseUrl, chainId, state.address, token.tokenId);
+    // token-scope image wins; else the collection-scope image (the O(1) directory pattern).
+    const { entry, fromCollection } = fieldWithFallback(token.fields, state.collectionFields, F.image);
+    if (!entry) {
+        return { url: nodeUrl, prov: placeholderProv(F.image, 'placeholder — generative-from-address (no committed image)') };
+    }
+    // On-chain content: the node serves the decoded bytes; nothing off-chain to locate.
+    if (entry.representation === R.inline ||
+        entry.representation === R.inlineGzip ||
+        entry.representation === R.reader ||
+        entry.representation === R.readerGzip) {
+        return { url: nodeUrl, prov: onChainProv(F.image, entry.representation, fromCollection) };
+    }
+    // Locator with a {id} placeholder → substitute the tokenId (one collection field → whole
+    // directory). The on-chain pointer IS the URL, keyed to a pinned IPFS dir / Arweave manifest.
+    if (entry.representation === R.urlTemplate) {
+        const url = applyTemplate(inlineText(entry), token.tokenId);
+        return {
+            url,
+            prov: {
+                field: F.image,
+                source: 'url-template',
+                onChain: true,
+                status: 'on-chain',
+                note: scopeNote('on-chain url template -> off-chain content', fromCollection),
+            },
+        };
+    }
+    // Off-chain bytes anchored by an on-chain hash. Point at a durable locator if we have one.
+    if (entry.representation === R.keccak256 || entry.representation === R.sha256) {
+        const anchor = entry.representation;
+        const bridged = display.contentLocators?.[entry.value.toLowerCase()];
+        const locator = bridged ?? (storage?.locator ? await storage.locator(entry.value) : null);
+        if (locator) {
+            return {
+                url: locator,
+                prov: {
+                    field: F.image,
+                    source: sourceForLocator(locator),
+                    onChain: false,
+                    status: 'anchored',
+                    anchor,
+                    note: `off-chain bytes (${sourceForLocator(locator)}); on-chain ${anchor} integrity anchor`,
+                },
+            };
+        }
+        // No durable locator known here: serve from this node's custody, still anchored on-chain.
+        return {
+            url: nodeUrl,
+            prov: {
+                field: F.image,
+                source: anchor,
+                onChain: false,
+                status: 'anchored',
+                anchor,
+                note: `off-chain bytes (served by this node); on-chain ${anchor} integrity anchor`,
+            },
+        };
+    }
+    // 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.
+    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),
+            },
+        };
+    }
+    // Locator committed ON-CHAIN (ipfs/arweave/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),
+        },
+    };
+}
+// ── the `artifacts` manifest (specs/protocol/data-plane.md) ───────────────────────
+/** The registry's reserved field vocabulary — projection/display keys. Every other field tag a
+ *  creator sets is a first-class plane artifact. */
+const RESERVED_FIELDS = new Set(Object.values(F));
+/** contentType cache per (renderer address, field) — stable per renderer in practice. */
+const rendererTypeCache = new Map();
+/** Best-effort declared contentType of a `renderer` field (null on any failure). */
+async function rendererContentType(client, tokenAddress, entry, field, tokenId) {
+    try {
+        const cacheKey = `${entry.value}:${field}`;
+        const hit = rendererTypeCache.get(cacheKey);
+        if (hit)
+            return hit;
+        const rendered = await resolveFieldRendered(client, tokenAddress, tokenId, field, entry);
+        if (rendered?.contentType)
+            rendererTypeCache.set(cacheKey, rendered.contentType);
+        return rendered?.contentType || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The declared-type ladder for a FIELD artifact (`data-plane.md → Declared type, never sniffed`):
+ * the representation is the declaration channel — `renderer` returns its contentType from chain;
+ * on-chain image bytes are SVG by the registry convention; custody bytes carry the type declared
+ * at upload; locator forms get a *labeled* extension-map fallback (never byte-sniffing). Unknown
+ * → `application/octet-stream`, never omitted (the complete-listing rule).
+ */
+export async function fieldMimeType(client, state, entry, field, tokenId, display, storage) {
+    const rep = entry.representation;
+    if (rep === R.renderer) {
+        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';
+    }
+    if (rep === R.keccak256 || rep === R.sha256) {
+        const stored = storage ? await storage.get(entry.value).catch(() => null) : null;
+        if (stored?.contentType)
+            return stored.contentType;
+        const bridged = display.contentLocators?.[entry.value.toLowerCase()];
+        return bridged ? contentTypeFromPath(bridged) : 'application/octet-stream';
+    }
+    const raw = inlineText(entry).trim();
+    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) {
+    const rep = entry.representation;
+    if (rep === R.url || rep === R.ipfs || rep === R.arweave)
+        return inlineText(entry).trim() || dataRoute;
+    if (rep === R.urlTemplate)
+        return applyTemplate(inlineText(entry), tokenId);
+    if (rep === R.keccak256 || rep === R.sha256) {
+        return display.contentLocators?.[entry.value.toLowerCase()] ?? dataRoute;
+    }
+    return dataRoute; // inline / reader / renderer — this node serves the bytes
+}
+/** Provenance for a non-reserved field artifact (reserved fields carry their projection rows). */
+function artifactFieldProv(field, entry, fromCollection) {
+    const rep = entry.representation;
+    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),
+        };
+    }
+    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`,
+        };
+    }
+    return {
+        field,
+        source: rep,
+        onChain: true,
+        status: 'on-chain',
+        note: scopeNote(`on-chain pointer (${rep}) — bytes off-chain, located on-chain`, fromCollection),
+    };
+}
+/**
+ * Assemble the token's `artifacts` manifest — the COMPLETE listing of its data plane
+ * (`data-plane.md → The manifest`): creator-set content fields (including ones already projected
+ * into reserved keys — deliberate duplication; the manifest alone reconstructs the file set) plus
+ * every producer-registered effect output whose row matches the CURRENT settled inputsHash (a
+ * param change re-addresses → stale rows go silently unlisted). Deterministic order: image,
+ * animation_url, non-reserved fields (alpha), then effect entries by effectKey/outputKey.
+ */
+async function buildTokenArtifacts(client, state, token, baseUrl, chainId, display, storage, plane, resolved) {
+    const entries = [];
+    const prov = [];
+    const cf = state.collectionFields;
+    // image — a creator-set field only (an unset image projected from the render effect is listed
+    // as its render/image entry below; the deterministic placeholder is not an artifact).
+    if (resolved.imageEntry) {
+        entries.push({
+            key: F.image,
+            mimeType: await fieldMimeType(client, state, resolved.imageEntry, F.image, token.tokenId, display, storage),
+            uri: resolved.imageUrl,
+        });
+    }
+    // animation_url — the explicit field only (the derived live view is a projection of the code;
+    // `code` never appears in served JSON per the field registry).
+    if (resolved.animationEntry && resolved.animationValue) {
+        entries.push({
+            key: F.animationUrl,
+            mimeType: await fieldMimeType(client, state, resolved.animationEntry, F.animationUrl, token.tokenId, display, storage),
+            uri: resolved.animationValue,
+        });
+    }
+    // every non-reserved field the creator set (token scope wins collection) — first-class artifacts.
+    const names = [...new Set([...token.fields, ...(cf ?? [])].map((x) => x.field))]
+        .filter((name) => !RESERVED_FIELDS.has(name) && name !== 'code')
+        .sort();
+    for (const name of names) {
+        const { entry, fromCollection } = fieldWithFallback(token.fields, cf, name);
+        if (!entry)
+            continue;
+        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),
+        });
+        prov.push(artifactFieldProv(name, entry, fromCollection));
+    }
+    // effect outputs at the CURRENT settled inputsHash — the registry rows are producer-published;
+    // the currency filter recomputes each row's expected address and drops what doesn't match.
+    if (plane && resolved.settledHash) {
+        const hash = resolved.settledHash;
+        const rows = plane
+            .list(state.address, token.tokenId)
+            .filter((row) => row.key.toLowerCase() ===
+            renderArtifactKey(state.chainId, state.address, token.tokenId, hash, row.outputKey, row.effectKey).toLowerCase())
+            .sort((a, b) => `${a.effectKey}/${a.outputKey}`.localeCompare(`${b.effectKey}/${b.outputKey}`));
+        for (const row of rows) {
+            const key = `${row.effectKey}/${row.outputKey}`;
+            entries.push({
+                key,
+                mimeType: row.contentType ?? 'application/octet-stream',
+                uri: row.locator ?? `${baseUrl}/t/${chainId}/${state.address}/${token.tokenId}/data/${key}`,
+            });
+            prov.push({
+                field: key,
+                source: `effect:${row.effectKey}`,
+                onChain: false,
+                status: 'off-chain',
+                note: 'derived effect output at the current inputsHash (re-creatable bytes)',
+            });
+        }
+    }
+    return { entries, prov };
+}
+const looksLikeSvg = (s) => /^\s*<(\?xml|svg)/i.test(s);
+/** On-chain `attributes` inline-JSON (if any) + the operator's off-chain attributes, stitched
+ *  (on-chain wins per trait_type). Returns the merged array + a provenance row, or null when
+ *  neither source has traits (so `attributes` is simply omitted — no boilerplate, no ABX facts). */
+function resolveAttributes(fields, offChain, collectionFields, fromRender = false) {
+    const { entry } = fieldWithFallback(fields, collectionFields, F.attributes);
+    let onChain = null;
+    let onChainBad = false;
+    if (entry && entry.representation === R.inline) {
+        try {
+            const parsed = JSON.parse(inlineText(entry));
+            onChain = Array.isArray(parsed) ? parsed : null;
+        }
+        catch {
+            onChainBad = true;
+        }
+    }
+    const merged = stitchAttributes(onChain, offChain);
+    if (merged.length === 0 && !onChainBad)
+        return null;
+    let prov;
+    if (onChain && offChain && offChain.length) {
+        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)'
+                : 'on-chain inline JSON + off-chain operator traits, stitched (on-chain wins per trait_type)',
+        };
+    }
+    else if (onChain) {
+        prov = onChainProv(F.attributes, R.inline);
+    }
+    else if (onChainBad) {
+        prov = placeholderProv(F.attributes, 'on-chain attributes unparseable — omitted');
+    }
+    else {
+        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)'
+                : 'off-chain operator traits',
+        };
+    }
+    return { attributes: merged, prov };
+}
+/** ERC-721 metadata JSON for a token (the `tokenURI` target) + `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 —
+// without it a locator-backed image reads "placeholder" while it serves fine.
+plane) {
+    const f = token.fields;
+    const provenance = [];
+    const image = await resolveImage(state, token, baseUrl, chainId, display, storage);
+    // ONE settled-inputsHash computation per build — shared by the image seam, the traits stitch,
+    // and the manifest's currency filter (they must all agree on "current").
+    const settledHash = isCodeProject(state)
+        ? await currentSettledInputsHash(client, state, token).catch(() => null)
+        : null;
+    // the render-effect seam: an unset image on a code project serves the artifact at the
+    // CURRENT inputsHash address when a producer has stored one (a param change re-addresses
+    // output, so this is self-invalidating — stale renders are never claimed). A render can live
+    // in this node's `storage` (co-located) OR as a published locator (the bridge) — check both, so
+    // the provenance matches what `/…/image` actually serves (the false-placeholder bug).
+    if (image.prov.source === 'placeholder' && isCodeProject(state) && (storage || plane)) {
+        try {
+            const { key, found } = await currentRenderArtifact(client, state, token, storage ?? undefined, 'image', {
+                hash: settledHash ?? undefined,
+            });
+            const viaLocator = !found && !!plane?.get(key);
+            if (found || viaLocator) {
+                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)'
+                        : 'render effect output for the current inputsHash (re-creatable derived bytes)',
+                };
+            }
+        }
+        catch {
+            // seam is best-effort — the placeholder stays honest
+        }
+    }
+    // Required fields (always present, with on-chain-computable fallbacks — mirrors the
+    // on-chain renderer). Everything else is optional: included only when it actually
+    // resolves (on-chain wins → operator-supplied off-chain → otherwise omitted, never a
+    // boilerplate filler). The off-chain caveat to renderer parity: this resolver may stitch
+    // operator/custody data + derive enrichment the on-chain renderer can't reach.
+    // token fields resolve token-scope first, then fall back to the collection scope (mirrors the
+    // 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);
+    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);
+    const imageData = img && img.representation === R.inline && looksLikeSvg(inlineText(img)) ? inlineText(img) : null;
+    provenance.push(image.prov);
+    // optional text fields → record provenance only when actually present.
+    if (description.value !== null)
+        provenance.push(description.prov);
+    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);
+    let animationValue = animation.value;
+    let animationProv = animation.prov;
+    if (animationValue === null && liveViewEnabled(state)) {
+        animationValue = liveViewUrl(baseUrl, chainId, state.address, token.tokenId);
+        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)',
+        };
+    }
+    if (animationValue !== null)
+        provenance.push(animationProv);
+    // attributes: real OpenSea traits only — three creator-controlled sources, stitched:
+    // on-chain inline JSON wins per trait_type over the render effect's script-reported
+    // 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.
+    let renderTraits = null;
+    if (isCodeProject(state) && storage) {
+        try {
+            const { key, found } = await currentRenderArtifact(client, state, token, storage, '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 }));
+                }
+            }
+        }
+        catch {
+            // seam is best-effort — traits simply don't stitch until a render lands
+        }
+    }
+    // Per-token off-chain traits (a Series' editable attributes) win over the collection-scope
+    // `display.attributes` (which a 1/1 uses); on-chain attributes still win over both (resolveAttributes).
+    const offChainBase = display.tokenAttributes?.[String(tid)] ?? display.attributes;
+    const offChainTraits = renderTraits ? stitchAttributes(renderTraits, offChainBase) : offChainBase;
+    const attr = resolveAttributes(f, offChainTraits, cf, renderTraits !== null);
+    if (attr)
+        provenance.push(attr.prov);
+    if (backgroundColor.value)
+        provenance.push(backgroundColor.prov);
+    if (youtubeUrl.value)
+        provenance.push(youtubeUrl.prov);
+    // 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,
+        imageEntry: fieldWithFallback(f, cf, F.image).entry,
+        animationValue: animation.value,
+        animationEntry: animation.value !== null ? fieldWithFallback(f, cf, F.animationUrl).entry : null,
+        settledHash,
+    });
+    provenance.push(...artifacts.prov);
+    const json = {
+        name: name.value,
+        image: image.url,
+        abx_provenance: provenance,
+    };
+    if (attr)
+        json.attributes = attr.attributes;
+    if (description.value !== null)
+        json.description = description.value;
+    if (externalUrl.value !== null)
+        json.external_url = externalUrl.value;
+    if (imageData)
+        json.image_data = imageData;
+    if (animationValue !== null)
+        json.animation_url = animationValue;
+    if (backgroundColor.value)
+        json.background_color = backgroundColor.value;
+    if (youtubeUrl.value)
+        json.youtube_url = youtubeUrl.value;
+    if (artifacts.entries.length)
+        json.artifacts = artifacts.entries;
+    return json;
+}
+/** ERC-7572 collection metadata JSON (the `contractURI` target) + `abx_provenance`. */
+export async function buildContractMetadata(client, state, baseUrl, chainId, display = {}, storage) {
+    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.
+    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
+    // 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);
+    // 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);
+    provenance.push(name.prov);
+    if (image)
+        provenance.push(image.prov);
+    if (description.value !== null)
+        provenance.push(description.prov);
+    if (externalLink.value !== null)
+        provenance.push(externalLink.prov);
+    if (artist.value !== null)
+        provenance.push(artist.prov);
+    if (displayNotes.value !== null)
+        provenance.push(displayNotes.prov);
+    if (artistLinks.value !== null)
+        provenance.push(artistLinks.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 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
+    // default (the url-template pattern), so it lists on tokens, not here. Omitted when empty.
+    const artifacts = [];
+    const artifactNames = [...new Set(f.map((x) => x.field))]
+        .filter((n) => (n === F.bannerImage || n === F.featuredImage || !RESERVED_FIELDS.has(n)) && n !== 'code')
+        .sort();
+    for (const n of artifactNames) {
+        const entry = fieldOf(f, n);
+        if (!entry || entry.representation === R.urlTemplate)
+            continue; // a per-token template lists on tokens
+        artifacts.push({
+            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),
+        });
+        if (!RESERVED_FIELDS.has(n))
+            provenance.push(artifactFieldProv(n, entry, false));
+    }
+    const json = {
+        name: name.value,
+        abx_provenance: provenance,
+    };
+    if (image)
+        json.image = image.url;
+    if (description.value !== null)
+        json.description = description.value;
+    if (externalLink.value !== null)
+        json.external_link = externalLink.value;
+    if (artist.value !== null)
+        json.artist = artist.value;
+    if (displayNotes.value !== null)
+        json.display_notes = displayNotes.value;
+    if (artistLinks.value !== null)
+        json.artist_links = artistLinks.value;
+    if (license.value !== null)
+        json.license = license.value;
+    if (bannerImage)
+        json.banner_image = bannerImage;
+    if (artifacts.length)
+        json.artifacts = artifacts;
+    return json;
+}
+//# sourceMappingURL=metadata.js.map