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

package/dist/deps.js

@@ -0,0 +1,297 @@
+import { gunzipSync } from 'node:zlib';
+import { padHex } from 'viem';
+import { codeField } from '@artblocks/abx-sdk';
+import { escapeInlineScript } from './inline.js';
+/**
+ * Registry-aware dependency resolution — the resolver's leg of the
+ * specs/protocol/dependency-registry.md "Consumers" table:
+ *
+ *   the collection's registry pointer: `availableOnChain` → serve the bytes
+ *   → else `preferredCDN` → else the built-in CDN map (last resort, warns)
+ *
+ * The read interface is AB's IDependencyRegistryV0 shape (a hard compatibility rule —
+ * any registry a collection points at speaks it). Script chunks are stored gzip'd THEN
+ * base64'd; the resolver concatenates the chunk strings, base64-decodes, and gunzips
+ * server-side so the document inlines plain JS. Resolution NEVER throws — the document
+ * must always assemble; every failure degrades to the built-in map with one warn.
+ *
+ * This module also owns the query-string size budget for URL-carried tokenData (~8KB
+ * request-line caps at gateway front-ends). It applies only to the directory 302 fallback
+ * — the primary inline-injection path carries tokenData inside the document. Over-budget
+ * redirects are still served IN FULL (never silently drop params), but warn loudly — once
+ * per project per process, then debug.
+ */
+/** The IDependencyRegistryV0 reads the resolver speaks (exact AB signatures). */
+export const DEPENDENCY_REGISTRY_ABI = [
+    {
+        type: 'function',
+        name: 'getDependencyDetails',
+        stateMutability: 'view',
+        inputs: [{ name: 'dependencyNameAndVersion', type: 'bytes32' }],
+        outputs: [
+            { name: 'nameAndVersion', type: 'string' },
+            { name: 'licenseType', type: 'string' },
+            { name: 'preferredCDN', type: 'string' },
+            { name: 'additionalCDNCount', type: 'uint24' },
+            { name: 'preferredRepository', type: 'string' },
+            { name: 'additionalRepositoryCount', type: 'uint24' },
+            { name: 'dependencyWebsite', type: 'string' },
+            { name: 'availableOnChain', type: 'bool' },
+            { name: 'scriptCount', type: 'uint24' },
+        ],
+    },
+    {
+        type: 'function',
+        name: 'getDependencyScript',
+        stateMutability: 'view',
+        inputs: [
+            { name: 'dependencyNameAndVersion', type: 'bytes32' },
+            { name: 'index', type: 'uint256' },
+        ],
+        outputs: [{ type: 'string' }],
+    },
+];
+// Resolved registry entries are effectively immutable (admin-gated writes), so an in-process
+// cache is safe; the TTL only guards admin updates. Failures negative-cache briefly so a dead
+// registry doesn't cost an eth_call (and a warn) per request.
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1h
+const NEGATIVE_TTL_MS = 60 * 1000; // 1min
+const registryCache = new Map();
+/** Reset all in-process dependency state (cache + budget flags + serve modes) — for tests. */
+export function resetDependencyResolutionState() {
+    registryCache.clear();
+    budgetFlags.clear();
+    directoryServeModes.clear();
+}
+/** The collection's registry pointer, if set to a real address (zero/undefined ⇒ none). */
+export function activeRegistry(state) {
+    const registry = state.dependencies?.registry ?? null;
+    if (!registry || /^0x0{40}$/i.test(registry))
+        return null;
+    return registry;
+}
+/**
+ * Resolve one `name@version` ref through the collection's registry. Returns the resolution
+ * (or null when the registry couldn't answer — caller falls back to the built-in map) plus
+ * whether it was served from cache. Never throws; a fresh failure logs ONE warn (the
+ * negative cache rate-limits it) naming the dep and why.
+ */
+export async function resolveRegistryDep(client, registry, dep) {
+    const key = `${registry.toLowerCase()}|${dep.refDecoded}`;
+    const hit = registryCache.get(key);
+    if (hit && hit.expiresAt > Date.now()) {
+        return { resolution: hit.value, cached: true, error: hit.error };
+    }
+    try {
+        // nameAndVersion rides as readable-ASCII bytes32 — the raw evented ref, right-padded.
+        const ref = padHex(dep.ref, { size: 32, dir: 'right' });
+        const details = (await client.readContract({
+            address: registry,
+            abi: DEPENDENCY_REGISTRY_ABI,
+            functionName: 'getDependencyDetails',
+            args: [ref],
+        }));
+        const [nameAndVersion, , preferredCDN, , , , , availableOnChain, scriptCount] = details;
+        if (availableOnChain && scriptCount > 0) {
+            // Per-chunk reads; the concatenated chunk strings form one base64(gzip(script)) stream.
+            const chunks = (await Promise.all(Array.from({ length: Number(scriptCount) }, (_, i) => client.readContract({
+                address: registry,
+                abi: DEPENDENCY_REGISTRY_ABI,
+                functionName: 'getDependencyScript',
+                args: [ref, BigInt(i)],
+            }))));
+            const script = gunzipSync(Buffer.from(chunks.join(''), 'base64')).toString('utf8');
+            const value = { kind: 'onchain', script };
+            registryCache.set(key, { value, expiresAt: Date.now() + CACHE_TTL_MS });
+            return { resolution: value, cached: false };
+        }
+        if (preferredCDN) {
+            const value = { kind: 'cdn', url: preferredCDN };
+            registryCache.set(key, { value, expiresAt: Date.now() + CACHE_TTL_MS });
+            return { resolution: value, cached: false };
+        }
+        // An empty struct back means the entry simply isn't registered.
+        const why = nameAndVersion
+            ? 'registered but has neither on-chain bytes nor a preferredCDN'
+            : 'not registered in the registry';
+        return failResolution(key, dep, registry, why);
+    }
+    catch (err) {
+        return failResolution(key, dep, registry, `registry read failed: ${err.message}`);
+    }
+}
+/** Negative-cache a failed resolution + one warn (per negative-TTL window). Never throws. */
+function failResolution(key, dep, registry, why) {
+    registryCache.set(key, { value: null, error: why, expiresAt: Date.now() + NEGATIVE_TTL_MS });
+    console.warn(`[deps] registry resolution failed for ${dep.refDecoded} via ${registry}: ${why} — falling back to the built-in CDN map`);
+    return { resolution: null, cached: false, error: why };
+}
+/**
+ * Resolve a `name@version` registry ref to a CDN URL — the built-in reference convention,
+ * the LAST-resort rung of the resolution order (the soft registry pointer stays
+ * non-validating). Known runtimes get their real dist paths; anything else is best-effort npm.
+ */
+export function registryDepUrl(ref) {
+    const at = ref.lastIndexOf('@');
+    if (at <= 0)
+        return null;
+    const name = ref.slice(0, at);
+    const version = ref.slice(at + 1);
+    const known = {
+        p5js: `https://cdn.jsdelivr.net/npm/p5@${version}/lib/p5.min.js`,
+        p5: `https://cdn.jsdelivr.net/npm/p5@${version}/lib/p5.min.js`,
+        threejs: `https://cdn.jsdelivr.net/npm/three@${version}/build/three.min.js`,
+        three: `https://cdn.jsdelivr.net/npm/three@${version}/build/three.min.js`,
+        tonejs: `https://cdn.jsdelivr.net/npm/tone@${version}/build/Tone.js`,
+    };
+    return known[name] ?? `https://cdn.jsdelivr.net/npm/${name}@${version}`;
+}
+/**
+ * The ordered dependency `<script>` tags for the generator document, each dep resolved per
+ * the Consumers table: registry on-chain bytes → registry preferredCDN → built-in map;
+ * `onchain`-resolution refs read their SSTORE2 data contract directly (never a registry).
+ * Never throws — an unresolvable dep is skipped (after the warn) and the document assembles.
+ */
+export async function dependencyScriptTags(client, state) {
+    const registry = activeRegistry(state);
+    const tags = [];
+    for (const dep of state.dependencies?.list ?? []) {
+        if (dep.resolution === 'registry') {
+            if (registry) {
+                const { resolution } = await resolveRegistryDep(client, registry, dep);
+                if (resolution?.kind === 'onchain') {
+                    tags.push(`<script>${escapeInlineScript(resolution.script)}</script>`);
+                    continue;
+                }
+                if (resolution?.kind === 'cdn') {
+                    tags.push(`<script src="${resolution.url}"></script>`);
+                    continue;
+                }
+                // fell through — resolveRegistryDep already warned; last resort below
+            }
+            const url = registryDepUrl(dep.refDecoded);
+            if (url)
+                tags.push(`<script src="${url}"></script>`);
+        }
+        else {
+            // on-chain dep: an SSTORE2 data contract holding the JS (code = 0x00 ‖ content)
+            const bytecode = await client.getCode({ address: dep.refDecoded });
+            if (bytecode && bytecode.length > 4) {
+                tags.push(`<script>${escapeInlineScript(Buffer.from(bytecode.slice(4), 'hex').toString('utf8'))}</script>`);
+            }
+        }
+    }
+    return tags;
+}
+// The last directory serve outcome per project (in-process): inline injection is the
+// primary; a redirect only happens when the entry-document fetch failed. /api/deps reports it.
+const directoryServeModes = new Map();
+/** Record which directory serving path a live-view request actually took. */
+export function recordDirectoryServe(address, mode) {
+    directoryServeModes.set(address.toLowerCase(), { mode, at: new Date().toISOString() });
+}
+// ── the query-string size budget (URL-carried tokenData lanes only) ──────────────
+/** Gateway front-ends commonly cap request lines near 8KB — the spec's URL budget. It
+ *  applies to URL-carried `?abx=` payloads (the 302 fallback); resolver inline serving
+ *  injects tokenData into the document and is unaffected. */
+export const URL_BUDGET_BYTES = 8192;
+// Per-project over-budget observations (in-process). First breach warns loudly; repeats
+// drop to debug so a hot token doesn't spam the log once the fact is known.
+const budgetFlags = new Map();
+/**
+ * Measure a URL-carried `?abx=` payload (the directory 302 fallback) against the ~8KB
+ * budget. The FULL URL is always served — params are never dropped — this only makes the
+ * breach visible: a loud structured warn on the first over-budget redirect per project per
+ * process, debug-level after. Inline-injection serving never routes through here.
+ */
+export function checkUrlBudget(address, tokenId, redirectUrl) {
+    const bytes = Buffer.byteLength(redirectUrl, 'utf8');
+    if (bytes <= URL_BUDGET_BYTES)
+        return;
+    const key = address.toLowerCase();
+    const seen = budgetFlags.has(key);
+    budgetFlags.set(key, { bytes, tokenId, at: new Date().toISOString() });
+    const payload = JSON.stringify({
+        warn: 'url-budget-exceeded',
+        address,
+        tokenId,
+        bytes,
+        limit: URL_BUDGET_BYTES,
+        hint: 'exceeds the 8KB URL budget — template mode or locator params recommended; resolver inline serving unaffected',
+    });
+    if (seen)
+        console.debug(`[deps] ${payload}`);
+    else
+        console.warn(`[deps] ${payload}`);
+}
+/** The project's URL-budget status (directory projects) — surfaced by /api/deps. */
+export function urlBudgetStatus(address) {
+    const flag = budgetFlags.get(address.toLowerCase());
+    if (!flag)
+        return { limit: URL_BUDGET_BYTES, exceeded: false };
+    return { limit: URL_BUDGET_BYTES, exceeded: true, lastBytes: flag.bytes, lastTokenId: flag.tokenId, lastAt: flag.at };
+}
+/**
+ * Per-dep resolution status for a project — a read-only dry run of the same resolution the
+ * generator document uses (and it shares the cache, so a status read warms serving). For
+ * directory projects the active serving path (inline-injection primary vs the ?abx= 302
+ * fallback) and the URL-budget flag ride along.
+ */
+export async function depStatusReport(client, state) {
+    const registry = activeRegistry(state);
+    const deps = [];
+    for (const dep of state.dependencies?.list ?? []) {
+        if (dep.resolution === 'onchain') {
+            // an SSTORE2 data contract — resolvable iff code is actually there
+            let resolvedVia = 'unresolved';
+            try {
+                const bytecode = await client.getCode({ address: dep.refDecoded });
+                if (bytecode && bytecode.length > 4)
+                    resolvedVia = 'inline-onchain';
+            }
+            catch {
+                // unreachable RPC reads as unresolved — this surface is observational, never throws
+            }
+            deps.push({ ref: dep.refDecoded, resolution: 'onchain', resolvedVia, registry: null, cached: false });
+            continue;
+        }
+        if (registry) {
+            const { resolution, cached } = await resolveRegistryDep(client, registry, dep);
+            if (resolution) {
+                deps.push({
+                    ref: dep.refDecoded,
+                    resolution: 'registry',
+                    resolvedVia: resolution.kind === 'onchain' ? 'onchain-registry' : 'cdn-registry',
+                    registry,
+                    cached,
+                });
+                continue;
+            }
+        }
+        const url = registryDepUrl(dep.refDecoded);
+        deps.push({
+            ref: dep.refDecoded,
+            resolution: 'registry',
+            resolvedVia: url ? 'builtin-map' : 'unresolved',
+            registry,
+            cached: false,
+        });
+    }
+    const directory = !!codeField(state);
+    const serve = directoryServeModes.get(state.address.toLowerCase());
+    return {
+        address: state.address,
+        registry,
+        locked: state.dependencies?.locked ?? false,
+        deps,
+        ...(directory
+            ? {
+                // inline injection is the primary; a redirect only ever means the last serve's
+                // entry-document fetch failed. `at` is absent until a live view has been served.
+                directoryServing: { primary: 'inline-injection', active: serve?.mode ?? 'inline-injection', ...(serve ? { at: serve.at } : {}) },
+                urlBudget: urlBudgetStatus(state.address),
+            }
+            : {}),
+    };
+}
+//# sourceMappingURL=deps.js.map

package/dist/deps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deps.js","sourceRoot":"","sources":["../src/deps.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAC,MAAM,WAAW,CAAC;AACrC,OAAO,EAAC,MAAM,EAAC,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAC,SAAS,EAA0E,MAAM,oBAAoB,CAAC;AACtH,OAAO,EAAC,kBAAkB,EAAC,MAAM,aAAa,CAAC;AAE/C;;;;;;;;;;;;;;;;;;GAkBG;AAEH,iFAAiF;AACjF,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC;QACE,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,sBAAsB;QAC5B,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,CAAC,EAAC,IAAI,EAAE,0BAA0B,EAAE,IAAI,EAAE,SAAS,EAAC,CAAC;QAC7D,OAAO,EAAE;YACP,EAAC,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,QAAQ,EAAC;YACxC,EAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAC;YACrC,EAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,QAAQ,EAAC;YACtC,EAAC,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,QAAQ,EAAC;YAC5C,EAAC,IAAI,EAAE,qBAAqB,EAAE,IAAI,EAAE,QAAQ,EAAC;YAC7C,EAAC,IAAI,EAAE,2BAA2B,EAAE,IAAI,EAAE,QAAQ,EAAC;YACnD,EAAC,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,QAAQ,EAAC;YAC3C,EAAC,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,EAAC;YACxC,EAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAC;SACtC;KACF;IACD;QACE,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,qBAAqB;QAC3B,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE;YACN,EAAC,IAAI,EAAE,0BAA0B,EAAE,IAAI,EAAE,SAAS,EAAC;YACnD,EAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAC;SACjC;QACD,OAAO,EAAE,CAAC,EAAC,IAAI,EAAE,QAAQ,EAAC,CAAC;KAC5B;CACO,CAAC;AAOX,6FAA6F;AAC7F,8FAA8F;AAC9F,8DAA8D;AAC9D,MAAM,YAAY,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,KAAK;AAC1C,MAAM,eAAe,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,OAAO;AAC1C,MAAM,aAAa,GAAG,IAAI,GAAG,EAAsB,CAAC;AAEpD,8FAA8F;AAC9F,MAAM,UAAU,8BAA8B;IAC5C,aAAa,CAAC,KAAK,EAAE,CAAC;IACtB,WAAW,CAAC,KAAK,EAAE,CAAC;IACpB,mBAAmB,CAAC,KAAK,EAAE,CAAC;AAC9B,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,cAAc,CAAC,KAAmB;IAChD,MAAM,QAAQ,GAAG,KAAK,CAAC,YAAY,EAAE,QAAQ,IAAI,IAAI,CAAC;IACtD,IAAI,CAAC,QAAQ,IAAI,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1D,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,MAAoB,EACpB,QAAiB,EACjB,GAAmB;IAEnB,MAAM,GAAG,GAAG,GAAG,QAAQ,CAAC,WAAW,EAAE,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;IAC1D,MAAM,GAAG,GAAG,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,GAAG,IAAI,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;QACtC,OAAO,EAAC,UAAU,EAAE,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAC,CAAC;IACjE,CAAC;IACD,IAAI,CAAC;QACH,sFAAsF;QACtF,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,EAAC,IAAI,EAAE,EAAE,EAAE,GAAG,EAAE,OAAO,EAAC,CAAC,CAAC;QACtD,MAAM,OAAO,GAAG,CAAC,MAAM,MAAM,CAAC,YAAY,CAAC;YACzC,OAAO,EAAE,QAAQ;YACjB,GAAG,EAAE,uBAAuB;YAC5B,YAAY,EAAE,sBAAsB;YACpC,IAAI,EAAE,CAAC,GAAG,CAAC;SACZ,CAAC,CAAuF,CAAC;QAC1F,MAAM,CAAC,cAAc,EAAE,AAAD,EAAG,YAAY,EAAE,AAAD,EAAG,AAAD,EAAG,AAAD,EAAG,AAAD,EAAG,gBAAgB,EAAE,WAAW,CAAC,GAAG,OAAO,CAAC;QAExF,IAAI,gBAAgB,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;YACxC,wFAAwF;YACxF,MAAM,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,GAAG,CAC/B,KAAK,CAAC,IAAI,CAAC,EAAC,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,EAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACjD,MAAM,CAAC,YAAY,CAAC;gBAClB,OAAO,EAAE,QAAQ;gBACjB,GAAG,EAAE,uBAAuB;gBAC5B,YAAY,EAAE,qBAAqB;gBACnC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;aACvB,CAAC,CACH,CACF,CAAa,CAAC;YACf,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YACnF,MAAM,KAAK,GAAuB,EAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAC,CAAC;YAC5D,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,EAAC,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,YAAY,EAAC,CAAC,CAAC;YACtE,OAAO,EAAC,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAC,CAAC;QAC5C,CAAC;QACD,IAAI,YAAY,EAAE,CAAC;YACjB,MAAM,KAAK,GAAuB,EAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,YAAY,EAAC,CAAC;YACnE,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,EAAC,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,YAAY,EAAC,CAAC,CAAC;YACtE,OAAO,EAAC,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAC,CAAC;QAC5C,CAAC;QACD,gEAAgE;QAChE,MAAM,GAAG,GAAG,cAAc;YACxB,CAAC,CAAC,8DAA8D;YAChE,CAAC,CAAC,gCAAgC,CAAC;QACrC,OAAO,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;IACjD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,yBAA0B,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IAC/F,CAAC;AACH,CAAC;AAED,6FAA6F;AAC7F,SAAS,cAAc,CACrB,GAAW,EACX,GAAmB,EACnB,QAAiB,EACjB,GAAW;IAEX,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,EAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,eAAe,EAAC,CAAC,CAAC;IAC3F,OAAO,CAAC,IAAI,CACV,yCAAyC,GAAG,CAAC,UAAU,QAAQ,QAAQ,KAAK,GAAG,yCAAyC,CACzH,CAAC;IACF,OAAO,EAAC,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAC,CAAC;AACvD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,MAAM,EAAE,GAAG,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,EAAE,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACzB,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC9B,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAClC,MAAM,KAAK,GAA2B;QACpC,IAAI,EAAE,mCAAmC,OAAO,gBAAgB;QAChE,EAAE,EAAE,mCAAmC,OAAO,gBAAgB;QAC9D,OAAO,EAAE,sCAAsC,OAAO,qBAAqB;QAC3E,KAAK,EAAE,sCAAsC,OAAO,qBAAqB;QACzE,MAAM,EAAE,qCAAqC,OAAO,gBAAgB;KACrE,CAAC;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,gCAAgC,IAAI,IAAI,OAAO,EAAE,CAAC;AAC1E,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,MAAoB,EAAE,KAAmB;IAClF,MAAM,QAAQ,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACvC,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,YAAY,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC;QACjD,IAAI,GAAG,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;YAClC,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,EAAC,UAAU,EAAC,GAAG,MAAM,kBAAkB,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;gBACrE,IAAI,UAAU,EAAE,IAAI,KAAK,SAAS,EAAE,CAAC;oBACnC,IAAI,CAAC,IAAI,CAAC,WAAW,kBAAkB,CAAC,UAAU,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;oBACvE,SAAS;gBACX,CAAC;gBACD,IAAI,UAAU,EAAE,IAAI,KAAK,KAAK,EAAE,CAAC;oBAC/B,IAAI,CAAC,IAAI,CAAC,gBAAgB,UAAU,CAAC,GAAG,aAAa,CAAC,CAAC;oBACvD,SAAS;gBACX,CAAC;gBACD,sEAAsE;YACxE,CAAC;YACD,MAAM,GAAG,GAAG,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YAC3C,IAAI,GAAG;gBAAE,IAAI,CAAC,IAAI,CAAC,gBAAgB,GAAG,aAAa,CAAC,CAAC;QACvD,CAAC;aAAM,CAAC;YACN,gFAAgF;YAChF,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,EAAC,OAAO,EAAE,GAAG,CAAC,UAAqB,EAAC,CAAC,CAAC;YAC5E,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpC,IAAI,CAAC,IAAI,CAAC,WAAW,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,WAAW,CAAC,CAAC;YAC9G,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAMD,qFAAqF;AACrF,+FAA+F;AAC/F,MAAM,mBAAmB,GAAG,IAAI,GAAG,EAAkD,CAAC;AAEtF,6EAA6E;AAC7E,MAAM,UAAU,oBAAoB,CAAC,OAAe,EAAE,IAAwB;IAC5E,mBAAmB,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,EAAC,IAAI,EAAE,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAC,CAAC,CAAC;AACvF,CAAC;AAED,oFAAoF;AAEpF;;6DAE6D;AAC7D,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAErC,wFAAwF;AACxF,4EAA4E;AAC5E,MAAM,WAAW,GAAG,IAAI,GAAG,EAAwD,CAAC;AAEpF;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe,EAAE,OAAe,EAAE,WAAmB;IAClF,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IACrD,IAAI,KAAK,IAAI,gBAAgB;QAAE,OAAO;IACtC,MAAM,GAAG,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAClC,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClC,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,EAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAC,CAAC,CAAC;IACrE,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC;QAC7B,IAAI,EAAE,qBAAqB;QAC3B,OAAO;QACP,OAAO;QACP,KAAK;QACL,KAAK,EAAE,gBAAgB;QACvB,IAAI,EAAE,8GAA8G;KACrH,CAAC,CAAC;IACH,IAAI,IAAI;QAAE,OAAO,CAAC,KAAK,CAAC,UAAU,OAAO,EAAE,CAAC,CAAC;;QACxC,OAAO,CAAC,IAAI,CAAC,UAAU,OAAO,EAAE,CAAC,CAAC;AACzC,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,eAAe,CAAC,OAAe;IAO7C,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IACpD,IAAI,CAAC,IAAI;QAAE,OAAO,EAAC,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,KAAK,EAAC,CAAC;IAC7D,OAAO,EAAC,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAC,CAAC;AACtH,CAAC;AAcD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,MAAoB,EAAE,KAAmB;IAC7E,MAAM,QAAQ,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACvC,MAAM,IAAI,GAAgB,EAAE,CAAC;IAC7B,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,YAAY,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC;QACjD,IAAI,GAAG,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YACjC,mEAAmE;YACnE,IAAI,WAAW,GAAgB,YAAY,CAAC;YAC5C,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,EAAC,OAAO,EAAE,GAAG,CAAC,UAAqB,EAAC,CAAC,CAAC;gBAC5E,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;oBAAE,WAAW,GAAG,gBAAgB,CAAC;YACtE,CAAC;YAAC,MAAM,CAAC;gBACP,oFAAoF;YACtF,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,EAAC,GAAG,EAAE,GAAG,CAAC,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAC,CAAC,CAAC;YACpG,SAAS;QACX,CAAC;QACD,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,EAAC,UAAU,EAAE,MAAM,EAAC,GAAG,MAAM,kBAAkB,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;YAC7E,IAAI,UAAU,EAAE,CAAC;gBACf,IAAI,CAAC,IAAI,CAAC;oBACR,GAAG,EAAE,GAAG,CAAC,UAAU;oBACnB,UAAU,EAAE,UAAU;oBACtB,WAAW,EAAE,UAAU,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,cAAc;oBAChF,QAAQ;oBACR,MAAM;iBACP,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;QACH,CAAC;QACD,MAAM,GAAG,GAAG,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAC3C,IAAI,CAAC,IAAI,CAAC;YACR,GAAG,EAAE,GAAG,CAAC,UAAU;YACnB,UAAU,EAAE,UAAU;YACtB,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,YAAY;YAC/C,QAAQ;YACR,MAAM,EAAE,KAAK;SACd,CAAC,CAAC;IACL,CAAC;IACD,MAAM,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACrC,MAAM,KAAK,GAAG,mBAAmB,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IACnE,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,QAAQ;QACR,MAAM,EAAE,KAAK,CAAC,YAAY,EAAE,MAAM,IAAI,KAAK;QAC3C,IAAI;QACJ,GAAG,CAAC,SAAS;YACX,CAAC,CAAC;gBACE,+EAA+E;gBAC/E,iFAAiF;gBACjF,gBAAgB,EAAE,EAAC,OAAO,EAAE,kBAAkB,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,IAAI,kBAAkB,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAC,EAAE,EAAE,KAAK,CAAC,EAAE,EAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAC;gBAC5H,SAAS,EAAE,eAAe,CAAC,KAAK,CAAC,OAAO,CAAC;aAC1C;YACH,CAAC,CAAC,EAAE,CAAC;KACR,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @artblocks/abx-token-api — Layer 3 reference token API + byte-custody server.
+ *
+ * Serves standard ERC-721 / ERC-7572 metadata, the token image, a JSON state
+ * API, and a demo dashboard — all from the reconstructed projection. The on-chain
+ * URIs point here, so this node is the resolver; switching nodes is a repoint.
+ */
+export { createTokenApiServer, startTokenApiServer, resolveBaseUrl, resolveContent, verifyProject, DEFAULT_PORT, type ServerOptions, } from './server.js';
+export { buildTokenMetadata, buildContractMetadata, tokenImageUrl, type DisplayMeta, type FieldProvenance } from './metadata.js';
+export { currentRenderArtifact, injectTokenDataIntoHtml, liveViewEnabled } from './code.js';
+export { depStatusReport, dependencyScriptTags, resolveRegistryDep, registryDepUrl, activeRegistry, urlBudgetStatus, URL_BUDGET_BYTES, DEPENDENCY_REGISTRY_ABI, type DepStatus, type DirectoryServeMode, type RegistryResolution, type ResolvedVia, } from './deps.js';
+export { startChainWatcher, notifyEffects, watchIntervalMs, DEFAULT_WATCH_INTERVAL_MS, type WatcherOptions, type WatcherStatus } from './watcher.js';
+export { generateArt, artContentHash, fallbackImageSvg, IMAGE_MEDIA_TYPE } from './art.js';
+export { renderDashboard } from './dashboard.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,aAAa,EACb,YAAY,EACZ,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAC,kBAAkB,EAAE,qBAAqB,EAAE,aAAa,EAAE,KAAK,WAAW,EAAE,KAAK,eAAe,EAAC,MAAM,eAAe,CAAC;AAC/H,OAAO,EAAC,qBAAqB,EAAE,uBAAuB,EAAE,eAAe,EAAC,MAAM,WAAW,CAAC;AAC1F,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,uBAAuB,EACvB,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,WAAW,GACjB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAC,iBAAiB,EAAE,aAAa,EAAE,eAAe,EAAE,yBAAyB,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAC,MAAM,cAAc,CAAC;AACnJ,OAAO,EAAC,WAAW,EAAE,cAAc,EAAE,gBAAgB,EAAE,gBAAgB,EAAC,MAAM,UAAU,CAAC;AACzF,OAAO,EAAC,eAAe,EAAC,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * @artblocks/abx-token-api — Layer 3 reference token API + byte-custody server.
+ *
+ * Serves standard ERC-721 / ERC-7572 metadata, the token image, a JSON state
+ * API, and a demo dashboard — all from the reconstructed projection. The on-chain
+ * URIs point here, so this node is the resolver; switching nodes is a repoint.
+ */
+export { createTokenApiServer, startTokenApiServer, resolveBaseUrl, resolveContent, verifyProject, DEFAULT_PORT, } from './server.js';
+export { buildTokenMetadata, buildContractMetadata, tokenImageUrl } from './metadata.js';
+export { currentRenderArtifact, injectTokenDataIntoHtml, liveViewEnabled } from './code.js';
+export { depStatusReport, dependencyScriptTags, resolveRegistryDep, registryDepUrl, activeRegistry, urlBudgetStatus, URL_BUDGET_BYTES, DEPENDENCY_REGISTRY_ABI, } from './deps.js';
+export { startChainWatcher, notifyEffects, watchIntervalMs, DEFAULT_WATCH_INTERVAL_MS } from './watcher.js';
+export { generateArt, artContentHash, fallbackImageSvg, IMAGE_MEDIA_TYPE } from './art.js';
+export { renderDashboard } from './dashboard.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,aAAa,EACb,YAAY,GAEb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAC,kBAAkB,EAAE,qBAAqB,EAAE,aAAa,EAAyC,MAAM,eAAe,CAAC;AAC/H,OAAO,EAAC,qBAAqB,EAAE,uBAAuB,EAAE,eAAe,EAAC,MAAM,WAAW,CAAC;AAC1F,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,uBAAuB,GAKxB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAC,iBAAiB,EAAE,aAAa,EAAE,eAAe,EAAE,yBAAyB,EAA0C,MAAM,cAAc,CAAC;AACnJ,OAAO,EAAC,WAAW,EAAE,cAAc,EAAE,gBAAgB,EAAE,gBAAgB,EAAC,MAAM,UAAU,CAAC;AACzF,OAAO,EAAC,eAAe,EAAC,MAAM,gBAAgB,CAAC"}

package/dist/inline.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Inline-document safety — the one HTML parsing rule that matters when embedding
+ * content inside <script> elements: the parser ends the element at the first
+ * `</script`, regardless of JS string/comment context. Two content shapes, two
+ * semantics-preserving escapes:
+ *
+ *  - JS source (libraries, artist scripts): `</script` → `<\/script`. In valid JS the
+ *    sequence can only occur inside a string, template, regex, or comment — contexts
+ *    where `\/` is identical to `/` — so the transform never changes behavior.
+ *  - JSON (the injected `window.abxTokenData`): every `<` → `\u003c`. `<` only occurs
+ *    inside JSON strings (never in the syntax), and `\u003c` parses to the same
+ *    character — the canonical (hashed) serialization is untouched; only the delivery
+ *    form differs.
+ */
+/** JS source safe to inline inside a <script> element. */
+export declare function escapeInlineScript(src: string): string;
+/** A JSON payload safe to inline inside a <script> element (parse-identical). */
+export declare function escapeInlineJson(json: string): string;
+//# sourceMappingURL=inline.d.ts.map

package/dist/inline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline.d.ts","sourceRoot":"","sources":["../src/inline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,0DAA0D;AAC1D,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD"}

package/dist/inline.js

@@ -0,0 +1,23 @@
+/**
+ * Inline-document safety — the one HTML parsing rule that matters when embedding
+ * content inside <script> elements: the parser ends the element at the first
+ * `</script`, regardless of JS string/comment context. Two content shapes, two
+ * semantics-preserving escapes:
+ *
+ *  - JS source (libraries, artist scripts): `</script` → `<\/script`. In valid JS the
+ *    sequence can only occur inside a string, template, regex, or comment — contexts
+ *    where `\/` is identical to `/` — so the transform never changes behavior.
+ *  - JSON (the injected `window.abxTokenData`): every `<` → `\u003c`. `<` only occurs
+ *    inside JSON strings (never in the syntax), and `\u003c` parses to the same
+ *    character — the canonical (hashed) serialization is untouched; only the delivery
+ *    form differs.
+ */
+/** JS source safe to inline inside a <script> element. */
+export function escapeInlineScript(src) {
+    return src.replace(/<\/(script)/gi, '<\\/$1');
+}
+/** A JSON payload safe to inline inside a <script> element (parse-identical). */
+export function escapeInlineJson(json) {
+    return json.replace(/</g, '\\u003c');
+}
+//# sourceMappingURL=inline.js.map

package/dist/inline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline.js","sourceRoot":"","sources":["../src/inline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,0DAA0D;AAC1D,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,OAAO,GAAG,CAAC,OAAO,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC;AAChD,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;AACvC,CAAC"}

package/dist/metadata.d.ts

@@ -0,0 +1,89 @@
+import { type MetadataField, type OpenSeaAttribute, type ProjectState, type PublicClient, type TokenState } from '@artblocks/abx-sdk';
+import { type StorageBackend } from '@artblocks/abx-storage';
+/**
+ * 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 declare function tokenImageUrl(baseUrl: string, chainId: number, address: string, tokenId: string): string;
+/** Operator-supplied off-chain display metadata (from the registration — survives re-index). */
+export interface DisplayMeta {
+    description?: string;
+    externalUrl?: string;
+    /** Operator's OpenSea attributes, stitched UNDER any on-chain `attributes` (on-chain wins).
+     *  Collection-scope (a 1/1's traits, or a Series' shared/fallback). */
+    attributes?: OpenSeaAttribute[];
+    /** Operator's PER-TOKEN off-chain attributes, keyed by tokenId string — a Series' editable traits.
+     *  A token's entry wins over the collection-scope `attributes`; on-chain `attributes` wins over both. */
+    tokenAttributes?: Record<string, OpenSeaAttribute[]>;
+    /**
+     * Durable, gateway-agnostic locators for off-chain content, keyed by the field's on-chain
+     * `keccak256`/`sha256` hash (lowercased) → e.g. `ipfs://<cid>`. Bridged from the deployer's
+     * content index via the admin control plane, so a remote resolver can point the `image` at
+     * IPFS/Arweave directly — without holding the bytes or any storage credentials itself.
+     */
+    contentLocators?: Record<string, string>;
+}
+/**
+ * Per-field source transparency — emitted as `abx_provenance` in the served JSON.
+ *
+ * `status` replaces the old ambiguous `verifiedAgainstChain: boolean | null` (which conflated
+ * "the value IS on-chain, nothing to verify" with "an off-chain value we haven't checked"):
+ *  - `on-chain`   — the value lives on-chain (or is reconstructable from chain); nothing to verify.
+ *  - `verified`   — an off-chain value we re-hashed against its on-chain anchor — it matched.
+ *  - `mismatch`   — re-hashed against the anchor — it did NOT match (served bytes are wrong).
+ *  - `anchored`   — off-chain bytes with an on-chain hash anchor, not re-hashed at build time
+ *                   (anyone can verify any gateway's bytes against the anchor — `abx verify` / `/verify`).
+ *  - `off-chain`  — a plain off-chain operator value with no on-chain anchor. A benign by-design
+ *                   state (e.g. an operator-supplied description), NOT a failure — distinct from a
+ *                   hash check that didn't run (`anchored`) or didn't match (`mismatch`).
+ *  - `n/a`        — a placeholder/default; provenance doesn't apply.
+ */
+export type ProvenanceStatus = 'on-chain' | 'verified' | 'mismatch' | 'anchored' | 'off-chain' | 'n/a';
+export interface FieldProvenance {
+    field: string;
+    source: 'inline' | 'inline-gzip' | 'reader' | 'reader-gzip' | 'renderer' | 'keccak256' | 'sha256' | 'arweave' | 'ipfs' | 'url' | 'url-template' | 'off-chain' | 'fallback' | 'placeholder' | `effect:${string}` | 'live-view';
+    onChain: boolean;
+    status: ProvenanceStatus;
+    /** Integrity-anchor kind for off-chain bytes, e.g. `keccak256` — the on-chain hash you verify against. */
+    anchor?: 'keccak256' | 'sha256';
+    note: string;
+}
+/** One entry of the `artifacts` manifest (`specs/protocol/data-plane.md`) — exactly
+ *  `{key, mimeType, uri}`, all required, nothing optional. */
+export interface ArtifactEntry {
+    key: string;
+    mimeType: string;
+    uri: string;
+}
+/** The shape of a producer-registered effect-artifact row this module consumes (structurally
+ *  `@artblocks/abx-indexer`'s EffectArtifactRow — kept structural so tests need no store). */
+export interface PlaneArtifactRow {
+    key: string;
+    effectKey: string;
+    outputKey: string;
+    contentType: string | null;
+    locator: string | null;
+}
+/** The resolver's read surface over the effect-artifact registry — how the manifest enumerates
+ *  the plane's effect source without learning any effect's internals. */
+export interface PlaneAccess {
+    /** Every registered row for (project, token) — filtered here by current-inputsHash key match. */
+    list(address: string, tokenId: string): PlaneArtifactRow[];
+    /** One row by artifact key (the image seam's published-locator check). */
+    get(key: string): PlaneArtifactRow | 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 declare function fieldMimeType(client: PublicClient, state: ProjectState, entry: MetadataField, field: string, tokenId: string, display: DisplayMeta, storage?: StorageBackend): Promise<string>;
+/** ERC-721 metadata JSON for a token (the `tokenURI` target) + `abx_provenance` + `artifacts`. */
+export declare function buildTokenMetadata(client: PublicClient, state: ProjectState, token: TokenState, baseUrl: string, chainId: number, display?: DisplayMeta, storage?: StorageBackend, plane?: PlaneAccess): Promise<Record<string, unknown>>;
+/** ERC-7572 collection metadata JSON (the `contractURI` target) + `abx_provenance`. */
+export declare function buildContractMetadata(client: PublicClient, state: ProjectState, baseUrl: string, chainId: number, display?: DisplayMeta, storage?: StorageBackend): Promise<Record<string, unknown>>;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/metadata.d.ts.map

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