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

package/dist/server.js

@@ -0,0 +1,940 @@
+import { createServer } from 'node:http';
+import { timingSafeEqual } from 'node:crypto';
+import { discoverDeployBlock, fieldOf, makePublicClient, normalizeAttributes, renderArtifactKey, resolveChain, DEFAULT_CHAIN_KEY, verifyAgainstHash, METADATA_FIELD as F, METADATA_REPRESENTATION as R, } from '@artblocks/abx-sdk';
+import { resolveBackend } from '@artblocks/abx-storage';
+import { fallbackImageSvg, IMAGE_MEDIA_TYPE } from './art.js';
+import { buildContractMetadata, buildTokenMetadata, fieldMimeType } from './metadata.js';
+import { currentRenderArtifact, currentSettledInputsHash, isCodeProject, resolveLiveView, resolveLocatorUrl } from './code.js';
+import { depStatusReport } from './deps.js';
+import { ABX_JS } from './abxjs.js';
+import { resolveFieldBytes, resolveFieldRendered, COLLECTION_TOKEN_ID } from './resolve.js';
+import { renderDashboard, renderIndex } from './dashboard.js';
+import { notifyEffects, watchIntervalMs } from './watcher.js';
+// A read-only client for resolving on-chain `reader`-represented content (eth_call).
+const chainClient = makePublicClient();
+// The chain this resolver serves. The path grammar carries the chainId
+// (`/t/{chainId}/{address}/{tokenId}`), so a single host can serve many chains and reject
+// paths for chains it doesn't index. Today one resolver = one chain; this gates that.
+const SERVER_CHAIN_ID = resolveChain(process.env.ABX_CHAIN).id;
+// The chain *key* ('sepolia', …) the indexer registers projects under — the string
+// form of the same chain SERVER_CHAIN_ID identifies. Used by the admin control plane.
+const SERVER_CHAIN_KEY = process.env.ABX_CHAIN ?? DEFAULT_CHAIN_KEY; // MUST match SERVER_CHAIN_ID's default (base-sepolia) — a stale 'sepolia' desynced the key from the id
+/**
+ * Resolve a token's image bytes by dispatching on the `image` field's single active
+ * representation (token scope first, else the collection-wide field — the same fallback the
+ * JSON assembly uses): on-chain content — `inline` / `inline-gzip` / `reader` / `reader-gzip`,
+ * all decoded by the shared {@link resolveFieldBytes} (which calls `read(pointer)` for a
+ * reader and gunzips the gzip variants) → computed content (`renderer` — eth_call, typed by
+ * the returned contentType; `text/uri-list` means the bytes are a locator the route redirects
+ * to) → off-chain custody located by the on-chain `keccak256`/`sha256` hash → graceful
+ * placeholder. The node never errors on missing bytes.
+ */
+export async function resolveContent(state, token, storage) {
+    const image = fieldOf(token.fields, F.image) ?? fieldOf(state.collectionFields, F.image);
+    const onChain = await resolveFieldBytes(chainClient, image); // inline / inline-gzip / reader / reader-gzip
+    if (onChain)
+        return { contentType: IMAGE_MEDIA_TYPE, body: onChain };
+    // computed on-chain at read (`renderer`) — best-effort: a reverting renderer degrades to the
+    // placeholder rather than erroring the route (mirrors the on-chain renderer's fallback rule).
+    if (image?.representation === R.renderer) {
+        try {
+            const rendered = await resolveFieldRendered(chainClient, state.address, token.tokenId, F.image, image);
+            if (rendered)
+                return { contentType: rendered.contentType, body: rendered.bytes };
+        }
+        catch {
+            // fall through to the placeholder
+        }
+    }
+    // off-chain custody, located by the on-chain hash of the image
+    if (image && (image.representation === R.keccak256 || image.representation === R.sha256)) {
+        const stored = await storage.get(image.value);
+        if (stored)
+            return { contentType: stored.contentType, body: stored.bytes };
+    }
+    // graceful placeholder — the deterministic fallback the on-chain renderer also uses,
+    // so a token with no resolvable image looks the same whether served here or self-resolved.
+    return { contentType: IMAGE_MEDIA_TYPE, body: fallbackImageSvg(state.address, token.tokenId) };
+}
+/** Is `tokenId` a valid, not-yet-minted position within a Series' cap (`0 <= id < N`)? */
+function withinCap(tokenId, maxInvocations) {
+    if (maxInvocations == null)
+        return false;
+    try {
+        const id = BigInt(tokenId);
+        return id >= 0n && id < BigInt(maxInvocations);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The view to resolve for a requested tokenId. A token's metadata is its token id (no
+ * decoupling), so identity and content both come from that token. Returns a synthesized,
+ * unminted view for a not-yet-minted id within the cap (pre-mint warming — the multi-token
+ * analogue of the 1/1's seed-token-0), or `null` when the id is genuinely unknown (→ 404).
+ */
+export function resolveTokenView(state, tokenId) {
+    const issued = state.tokens.find((t) => t.tokenId === tokenId);
+    if (!issued && !withinCap(tokenId, state.maxInvocations))
+        return null;
+    return {
+        tokenId,
+        minted: issued?.minted ?? false,
+        owner: issued?.owner ?? null,
+        tokenURI: issued?.tokenURI ?? null,
+        fields: issued?.fields ?? [],
+        lockedFields: issued?.lockedFields ?? [],
+        params: issued?.params,
+    };
+}
+export const DEFAULT_PORT = 8787;
+/** The base URL this node is reachable at — what gets baked into on-chain URIs. */
+export function resolveBaseUrl(port = DEFAULT_PORT) {
+    return process.env.ABX_PUBLIC_BASE_URL ?? `http://localhost:${port}`;
+}
+/**
+ * Guard the base URL a hosted resolver serves its own metadata URLs from. `.example` is RFC-2606
+ * reserved — it can only be a leftover placeholder, so refuse it anywhere. A localhost base is fine
+ * for a local `abx serve` (dev), but in a hosted image (ABX_HOSTED=1) it means the public URL was
+ * never set — refuse so the deploy fails loudly instead of silently serving dead localhost links.
+ * The scaffold now always bakes a real host, so this only fires on a stripped env or an old artifact.
+ */
+export function assertServableBaseUrl(baseUrl) {
+    let host;
+    try {
+        host = new URL(baseUrl).hostname;
+    }
+    catch {
+        throw new Error(`ABX_PUBLIC_BASE_URL is not a valid URL: ${JSON.stringify(baseUrl)}`);
+    }
+    if (host === 'example' || host.endsWith('.example')) {
+        throw new Error(`ABX_PUBLIC_BASE_URL is a placeholder host (${host}). Set it to the resolver's real public URL ` +
+            `(e.g. https://<app>.fly.dev, or your custom domain) — the metadata this node serves points ` +
+            `image/animation URLs at this base, so a placeholder serves dead links.`);
+    }
+    const isLocal = host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '0.0.0.0';
+    if (isLocal && process.env.ABX_HOSTED === '1') {
+        throw new Error(`hosted resolver has no public ABX_PUBLIC_BASE_URL (resolved to ${baseUrl}). Set it to this host's ` +
+            `URL (e.g. https://<app>.fly.dev) — otherwise it serves localhost links no client can reach.`);
+    }
+}
+export function createTokenApiServer(opts) {
+    const { indexer } = opts;
+    const port = opts.port ?? Number(process.env.ABX_PORT ?? DEFAULT_PORT);
+    const baseUrl = opts.baseUrl ?? resolveBaseUrl(port);
+    assertServableBaseUrl(baseUrl);
+    const storage = opts.storage ?? resolveBackend();
+    return createServer(async (req, res) => {
+        try {
+            await route(req, res, indexer, baseUrl, storage);
+        }
+        catch (err) {
+            sendJson(res, 500, { error: err.message });
+        }
+    });
+}
+export function startTokenApiServer(opts) {
+    const port = opts.port ?? Number(process.env.ABX_PORT ?? DEFAULT_PORT);
+    const baseUrl = opts.baseUrl ?? resolveBaseUrl(port);
+    const server = createTokenApiServer({ ...opts, port, baseUrl });
+    return new Promise((resolve) => {
+        server.listen(port, () => resolve({ server, url: baseUrl }));
+    });
+}
+async function route(req, res, indexer, baseUrl, storage) {
+    res.setHeader('access-control-allow-origin', '*');
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const parts = url.pathname.split('/').filter(Boolean);
+    const method = req.method ?? 'GET';
+    // GET / — read-only node index: which contracts this resolver serves (no actions).
+    if (parts.length === 0) {
+        res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+        res.end(renderIndex(indexer.listProjects(), baseUrl, SERVER_CHAIN_ID));
+        return;
+    }
+    // GET /d/:chainId/:addr — the per-contract dashboard (read-only; namespaced so one host can
+    // serve many contracts/chains). Actions live behind the admin token, not on this page.
+    if (parts[0] === 'd' && parts[1] && parts[2]) {
+        if (Number(parts[1]) !== SERVER_CHAIN_ID)
+            return wrongChain(res, parts[1]);
+        const state = indexer.getProject(parts[2]);
+        if (!state)
+            return sendJson(res, 404, { error: 'unknown project' });
+        res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+        res.end(renderDashboard(state, baseUrl, SERVER_CHAIN_ID));
+        return;
+    }
+    // GET /health
+    if (parts[0] === 'health')
+        return sendJson(res, 200, { ok: true, baseUrl });
+    // GET /abx.js — the runtime companion (directory builds include it; the generator inlines it).
+    if (parts[0] === 'abx.js') {
+        res.writeHead(200, {
+            'content-type': 'application/javascript; charset=utf-8',
+            'cache-control': 'public, max-age=3600',
+        });
+        res.end(ABX_JS);
+        return;
+    }
+    // GET /a/:chainId/:addr/:id — the live view: the code project's document with canonical
+    // tokenData delivered per the spec (directory mode: the build's entry document served
+    // from here with window.abxTokenData injected — the ?abx= 302 redirect is the
+    // entry-fetch-failure fallback; template mode: the generator document assembled from
+    // chain). This is the same document a render node captures — the live view IS the input.
+    if (parts[0] === 'a' && parts[1] && parts[2] && parts[3] !== undefined) {
+        if (Number(parts[1]) !== SERVER_CHAIN_ID)
+            return wrongChain(res, parts[1]);
+        const state = indexer.getProject(parts[2]);
+        if (!state)
+            return sendJson(res, 404, { error: 'unknown project' });
+        const token = resolveTokenView(state, parts[3]);
+        if (!token)
+            return sendJson(res, 404, { error: 'unknown token' });
+        const view = await resolveLiveView(chainClient, state, token);
+        if (!view)
+            return sendJson(res, 404, { error: 'no live view — not a code project' });
+        if (view.kind === 'redirect') {
+            res.writeHead(302, { location: view.location, 'cache-control': 'no-store' });
+            res.end();
+            return;
+        }
+        res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
+        res.end(view.html);
+        return;
+    }
+    // /admin/* — the control plane. This is the ONE write surface on the resolver, and
+    // it's a *remote `abx add`*: it tells THIS node (a different projection store from
+    // any local one) which contracts to index. It never signs anything on-chain — the
+    // "no signing key on the host" rule is intact; the bearer token authorizes indexing
+    // control only. Disabled unless ABX_RESOLVER_ADMIN_TOKEN is set on the resolver.
+    if (parts[0] === 'admin' && parts[1] === 'projects') {
+        return adminProjects(req, res, indexer, parts[2]);
+    }
+    // POST /admin/effect-artifacts — a conforming effect runner publishes a render output (a durable
+    // locator, or raw bytes for small must-inline outputs like traits) so a resolver that does NOT share
+    // the runner's storage disk can still serve it. Same bearer as the control plane; never signs on-chain.
+    if (parts[0] === 'admin' && parts[1] === 'effect-artifacts') {
+        return adminRenderArtifacts(req, res, indexer, storage);
+    }
+    // POST /admin/effect-status — a runner reports a run's transient state ('rendering' /
+    // 'failed{error}' / 'done'). Pure observability: correctness stays artifact-presence at the
+    // settled inputsHash; these rows are rebuildable and 'done' simply clears one. Admin-gated.
+    if (parts[0] === 'admin' && parts[1] === 'effect-status') {
+        return adminEffectStatus(req, res, indexer);
+    }
+    // /api/*
+    if (parts[0] === 'api') {
+        if (parts[1] === 'projects') {
+            return sendJson(res, 200, indexer.listProjects().map(summarize));
+        }
+        // GET /api/watch — chain-watcher liveness. Read from the `meta` table the watcher writes each
+        // tick (this resolver's watcher shares the indexer store), so a HOSTED node — where you can't
+        // tail the log — can still PROVE it's watching: `pollAt` advances, `head` tracks the chain.
+        if (parts[1] === 'watch') {
+            return sendJson(res, 200, watchStatusReport(indexer));
+        }
+        // GET /api/deps/:chainId/:addr — per-dep resolution status (a read-only dry run of the
+        // same registry-order resolution the generator document uses, sharing its cache) plus
+        // the URL-budget flag for directory projects. Public, like the other status reads.
+        if (parts[1] === 'deps' && parts[2] && parts[3]) {
+            if (Number(parts[2]) !== SERVER_CHAIN_ID)
+                return wrongChain(res, parts[2]);
+            const state = indexer.getProject(parts[3]);
+            if (!state)
+                return sendJson(res, 404, { error: 'unknown project' });
+            return sendJson(res, 200, await depStatusReport(chainClient, state));
+        }
+        if (parts[1] === 'project' && parts[2]) {
+            const address = parts[2];
+            // POST|GET /api/project/:addr/reindex — full replay from chain. ADMIN-ONLY: a full replay
+            // is expensive + mutating, so it must never be a public action (it's `abx index --remote`
+            // from the CLI). Gated by the same bearer as the control plane.
+            if (parts[3] === 'reindex') {
+                if (!requireAdmin(req, res))
+                    return;
+                const { state, elapsedMs } = await indexer.reindex(address, { full: true });
+                notifyEffects(address);
+                return sendJson(res, 200, { elapsedMs, state });
+            }
+            // GET /api/project/:addr/verify — re-hashes served bytes against the on-chain anchor.
+            // ADMIN-ONLY: it triggers outbound chain + gateway fetches, so it isn't a public endpoint
+            // (anyone can still verify independently via `abx verify` — no need for this node to do it).
+            if (parts[3] === 'verify') {
+                if (!requireAdmin(req, res))
+                    return;
+                return sendJson(res, 200, await verifyProject(indexer.getProject(address), storage));
+            }
+            // GET /api/project/:addr/effects — per-token effect status. Derived, never stored:
+            // `up-to-date` = artifact present at the CURRENT settled inputsHash (this node's store or a
+            // published locator); `rendering`/`failed` = a runner-reported transient row at that key;
+            // else `stale`. Rows for effects this resolver doesn't consume are reported verbatim.
+            if (parts[3] === 'effects') {
+                const state = indexer.getProject(address);
+                if (!state)
+                    return sendJson(res, 404, { error: 'unknown project' });
+                return sendJson(res, 200, await effectStatusReport(indexer, state, storage));
+            }
+            // GET /api/project/:addr
+            const state = indexer.getProject(address);
+            if (!state)
+                return sendJson(res, 404, { error: 'unknown project' });
+            return sendJson(res, 200, state);
+        }
+        return sendJson(res, 404, { error: 'unknown api route' });
+    }
+    // GET /t/:chainId/:addr/:id  and  /t/:chainId/:addr/:id/image
+    if (parts[0] === 't' && parts[1] && parts[2] && parts[3] !== undefined) {
+        if (Number(parts[1]) !== SERVER_CHAIN_ID)
+            return wrongChain(res, parts[1]);
+        const address = parts[2];
+        const tokenId = parts[3];
+        const state = indexer.getProject(address);
+        if (!state)
+            return sendJson(res, 404, { error: 'unknown project' });
+        // Resolve the issuance token → its metadata-id slot (identity vs. content), synthesizing a
+        // pre-mint view for a not-yet-issued id within the cap so metadata warms before mint.
+        const token = resolveTokenView(state, tokenId);
+        if (!token)
+            return sendJson(res, 404, { error: 'unknown token' });
+        if (parts[4] === 'image') {
+            // the render-effect seam: no explicit image field + a code project ⇒ serve the
+            // artifact stored at the CURRENT inputsHash address, when a producer has run.
+            const hasImageField = token.fields.some((f) => f.field === 'image') ||
+                state.collectionFields.some((f) => f.field === 'image');
+            if (!hasImageField && isCodeProject(state)) {
+                try {
+                    const { key, found } = await currentRenderArtifact(chainClient, state, token, storage);
+                    // A runner may have published a durable locator (ipfs/ar/https) for a resolver that doesn't
+                    // share its storage disk — 302 straight to it (gateway resolved at serve time). A bytes-mode
+                    // published row has locator NULL — its bytes landed in this node's storage (`found`).
+                    const published = indexer.store.getEffectArtifact(key);
+                    if (published?.locator) {
+                        res.writeHead(302, { location: resolveLocatorUrl(published.locator), 'cache-control': 'public, max-age=300' });
+                        res.end();
+                        return;
+                    }
+                    if (found) {
+                        const artifact = await storage.get(key);
+                        if (artifact) {
+                            res.writeHead(200, {
+                                'content-type': artifact.contentType || 'image/png',
+                                'cache-control': 'public, max-age=300',
+                            });
+                            res.end(artifact.bytes);
+                            return;
+                        }
+                    }
+                }
+                catch {
+                    // fall through to the standard resolution (placeholder) — the seam is best-effort
+                }
+            }
+            const content = await resolveContent(state, token, storage);
+            // a computed LOCATOR (renderer returning text/uri-list): the bytes ARE a URI — redirect.
+            if (content.contentType === 'text/uri-list') {
+                const target = typeof content.body === 'string' ? content.body : new TextDecoder().decode(content.body);
+                res.writeHead(302, { location: resolveLocatorUrl(target.trim()), 'cache-control': 'public, max-age=300' });
+                res.end();
+                return;
+            }
+            res.writeHead(200, { 'content-type': content.contentType, 'cache-control': 'public, max-age=300' });
+            res.end(content.body);
+            return;
+        }
+        // GET /t/:chainId/:addr/:id/data/{field} and /t/:chainId/:addr/:id/data/{effectKey}/{outputKey}
+        // — the plane's byte-serving route (data-plane.md → Serving): declared Content-Type, 302 to a
+        // durable locator when one is registered. Effect keys are dot-namespaced, never slashed, so
+        // segment count disambiguates a field artifact (1) from an effect artifact (2).
+        if (parts[4] === 'data' && parts[5]) {
+            if (parts[6] !== undefined) {
+                return serveEffectArtifact(res, state, token, parts[5], parts[6], storage, indexer);
+            }
+            return serveFieldArtifact(res, state, token, parts[5], storage, displayMeta(indexer, address));
+        }
+        return sendJson(res, 200, await buildTokenMetadata(chainClient, state, token, baseUrl, SERVER_CHAIN_ID, displayMeta(indexer, address), storage, planeAccess(indexer)));
+    }
+    // GET /c/:chainId/:addr  and  /c/:chainId/:addr/data/{field}
+    if (parts[0] === 'c' && parts[1] && parts[2]) {
+        if (Number(parts[1]) !== SERVER_CHAIN_ID)
+            return wrongChain(res, parts[1]);
+        const address = parts[2];
+        const state = indexer.getProject(address);
+        if (!state)
+            return sendJson(res, 404, { error: 'unknown project' });
+        if (parts[3] === 'data' && parts[4]) {
+            return serveFieldArtifact(res, state, null, parts[4], storage, displayMeta(indexer, address));
+        }
+        return sendJson(res, 200, await buildContractMetadata(chainClient, state, baseUrl, SERVER_CHAIN_ID, displayMeta(indexer, address), storage));
+    }
+    sendJson(res, 404, { error: 'not found' });
+}
+/** The manifest's read surface over the effect-artifact registry (metadata.ts stays store-free). */
+function planeAccess(indexer) {
+    return {
+        list: (address, tokenId) => indexer.store.listEffectArtifacts(address, tokenId),
+        get: (key) => indexer.store.getEffectArtifact(key),
+    };
+}
+/** Serve one EFFECT artifact's bytes at the CURRENT settled inputsHash: 302 to a registered
+ *  durable locator, else the bytes from this node's custody with the DECLARED Content-Type,
+ *  else 404 (not produced yet, or stale after a param change — self-invalidation, not an error). */
+async function serveEffectArtifact(res, state, token, effectKey, outputKey, storage, indexer) {
+    if (!isCodeProject(state))
+        return sendJson(res, 404, { error: 'no effect artifacts — not a code project' });
+    try {
+        const hash = await currentSettledInputsHash(chainClient, state, token);
+        const key = renderArtifactKey(state.chainId, state.address, token.tokenId, hash, outputKey, effectKey);
+        const row = indexer.store.getEffectArtifact(key);
+        if (row?.locator) {
+            res.writeHead(302, { location: resolveLocatorUrl(row.locator), 'cache-control': 'public, max-age=300' });
+            res.end();
+            return;
+        }
+        const stored = await storage.get(key);
+        if (stored) {
+            res.writeHead(200, {
+                'content-type': row?.contentType || stored.contentType || 'application/octet-stream',
+                'cache-control': 'public, max-age=300',
+            });
+            res.end(stored.bytes);
+            return;
+        }
+    }
+    catch {
+        // fall through to the 404 — the route is best-effort, like the image seam
+    }
+    return sendJson(res, 404, {
+        error: `no ${effectKey}/${outputKey} artifact at the current inputsHash — not produced yet, or re-addressed by a param change (re-runs on the next sweep)`,
+    });
+}
+/** Serve one FIELD artifact's bytes (token scope with collection fallback; `token === null` =
+ *  collection scope): on-chain content decoded (inline/reader ±gzip), computed content
+ *  (`renderer` — eth_call, typed by the returned contentType), custody bytes by hash,
+ *  302 for locator forms — with the declared-type ladder's Content-Type. */
+async function serveFieldArtifact(res, state, token, field, storage, display) {
+    if (field === 'code')
+        return sendJson(res, 404, { error: '`code` is never served verbatim — the live view serves the program' });
+    const entry = (token ? fieldOf(token.fields, field) : null) ?? fieldOf(state.collectionFields, field);
+    if (!entry)
+        return sendJson(res, 404, { error: `no '${field}' field set` });
+    const tokenId = token?.tokenId ?? '0';
+    try {
+        const onChain = await resolveFieldBytes(chainClient, entry);
+        if (onChain) {
+            res.writeHead(200, {
+                'content-type': await fieldMimeType(chainClient, state, entry, field, tokenId, display, storage),
+                'cache-control': 'public, max-age=300',
+            });
+            res.end(onChain);
+            return;
+        }
+        // computed on-chain at read — the collection surface passes the sentinel id (no token).
+        const rendered = await resolveFieldRendered(chainClient, state.address, token?.tokenId ?? COLLECTION_TOKEN_ID, field, entry);
+        if (rendered) {
+            if (rendered.contentType === 'text/uri-list') {
+                const target = new TextDecoder().decode(rendered.bytes).trim();
+                res.writeHead(302, { location: resolveLocatorUrl(target), 'cache-control': 'public, max-age=300' });
+                res.end();
+                return;
+            }
+            res.writeHead(200, { 'content-type': rendered.contentType, 'cache-control': 'public, max-age=300' });
+            res.end(rendered.bytes);
+            return;
+        }
+        if (entry.representation === R.keccak256 || entry.representation === R.sha256) {
+            const stored = await storage.get(entry.value);
+            if (stored) {
+                res.writeHead(200, {
+                    'content-type': stored.contentType || 'application/octet-stream',
+                    'cache-control': 'public, max-age=300',
+                });
+                res.end(stored.bytes);
+                return;
+            }
+            const bridged = display.contentLocators?.[entry.value.toLowerCase()];
+            if (bridged) {
+                res.writeHead(302, { location: resolveLocatorUrl(bridged), 'cache-control': 'public, max-age=300' });
+                res.end();
+                return;
+            }
+            return sendJson(res, 404, { error: `'${field}' bytes not in this node's custody (on-chain ${entry.representation} anchor only)` });
+        }
+        const locator = fieldLocatorUrl(entry, tokenId);
+        if (locator) {
+            res.writeHead(302, { location: resolveLocatorUrl(locator), 'cache-control': 'public, max-age=300' });
+            res.end();
+            return;
+        }
+    }
+    catch (err) {
+        return sendJson(res, 502, { error: `field '${field}' failed to resolve: ${err.message}` });
+    }
+    return sendJson(res, 404, { error: `'${field}' (${entry.representation}) is not byte-servable from this node` });
+}
+/** A locator-representation field's URL (`{id}` substituted), or null for non-locator forms. */
+function fieldLocatorUrl(entry, tokenId) {
+    if (entry.representation === R.url || entry.representation === R.ipfs || entry.representation === R.arweave) {
+        const text = Buffer.from(entry.value.slice(2), 'hex').toString('utf8').trim();
+        return text || null;
+    }
+    if (entry.representation === R.urlTemplate) {
+        const text = Buffer.from(entry.value.slice(2), 'hex').toString('utf8');
+        return text.split('{id}').join(tokenId);
+    }
+    return null; // renderer is dispatched above; anything else has no locator form
+}
+/** Operator display metadata (creator's description/external_url/traits + bridged locators) from the
+ *  registration — survives re-index. The off-chain attributes + content locators are JSON columns. */
+function displayMeta(indexer, address) {
+    const reg = indexer.store.getRegistration(address);
+    return {
+        description: reg?.description,
+        externalUrl: reg?.externalUrl,
+        attributes: reg?.attributes ? safeAttributes(reg.attributes) : undefined,
+        tokenAttributes: reg?.tokenAttributes ? safeTokenAttributes(reg.tokenAttributes) : undefined,
+        contentLocators: reg?.contentLocators ? safeLocators(reg.contentLocators) : undefined,
+    };
+}
+/** Parse a stored off-chain attributes JSON column → normalized OpenSea traits (never throws). */
+function safeAttributes(json) {
+    try {
+        return normalizeAttributes(JSON.parse(json));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Parse the per-token off-chain attributes column (`{ "<tokenId>": attrs }`) → normalized per token. */
+function safeTokenAttributes(json) {
+    try {
+        const obj = JSON.parse(json);
+        if (!obj || typeof obj !== 'object')
+            return undefined;
+        const out = {};
+        for (const [tokenId, v] of Object.entries(obj)) {
+            const attrs = normalizeAttributes(v);
+            if (attrs.length)
+                out[tokenId] = attrs;
+        }
+        return Object.keys(out).length ? out : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Parse a stored content-locators JSON column → `{hash: locator}` (lowercased keys, never throws). */
+function safeLocators(json) {
+    try {
+        const obj = JSON.parse(json);
+        const out = {};
+        for (const [k, v] of Object.entries(obj))
+            if (typeof v === 'string')
+                out[k.toLowerCase()] = v;
+        return Object.keys(out).length ? out : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Merge incoming content locators over the stored ones (additive — a re-add can bring new hashes
+ *  without dropping known ones). Returns a JSON string for the column, or undefined if empty. */
+function mergeLocators(existingJson, incoming) {
+    const base = existingJson ? safeLocators(existingJson) ?? {} : {};
+    if (incoming && typeof incoming === 'object') {
+        for (const [k, v] of Object.entries(incoming)) {
+            if (typeof v === 'string' && v)
+                base[k.toLowerCase()] = v;
+        }
+    }
+    return Object.keys(base).length ? JSON.stringify(base) : undefined;
+}
+export async function verifyProject(state, storage) {
+    if (!state)
+        return { error: 'unknown project' };
+    const tokens = await Promise.all(state.tokens.map(async (t) => {
+        const { body } = await resolveContent(state, t, storage);
+        // verify the served image bytes against the on-chain `image` field when it carries a hash
+        const image = fieldOf(t.fields, F.image);
+        const isHash = image && (image.representation === R.keccak256 || image.representation === R.sha256);
+        const checks = isHash
+            ? [{ kind: image.representation, committed: image.value, verified: verifyAgainstHash(body, image) }]
+            : [];
+        return { tokenId: t.tokenId, checks };
+    }));
+    return { address: state.address, tokens };
+}
+function summarize(s) {
+    return {
+        address: s.address,
+        name: s.name,
+        symbol: s.symbol,
+        owner: s.owner,
+        abxVersion: s.abxVersion,
+        isCanonical: s.isCanonical,
+        extensions: s.extensions.map((e) => e.name),
+        eventCount: s.eventCount,
+        tokenCount: s.tokens.length,
+        mintedCount: s.tokens.filter((t) => t.minted).length,
+        reconstructedAt: s.reconstructedAt,
+    };
+}
+function sendJson(res, status, body) {
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify(body, null, 2));
+}
+// ── admin control plane (remote `abx add`) ───────────────────────────────────--
+/** Guard an admin-only API action (reindex/verify): 404 when no admin token is configured on the
+ *  host (the action surface is disabled), 401 on a missing/bad bearer. Returns false if it handled
+ *  the response (caller must stop), true when the request is authorized to proceed. */
+function requireAdmin(req, res) {
+    if (!process.env.ABX_RESOLVER_ADMIN_TOKEN) {
+        sendJson(res, 404, { error: 'admin action disabled — set ABX_RESOLVER_ADMIN_TOKEN on the resolver (operate via the abx CLI)' });
+        return false;
+    }
+    if (!adminAuthorized(req)) {
+        sendJson(res, 401, { error: 'unauthorized — this action needs Authorization: Bearer <ABX_RESOLVER_ADMIN_TOKEN>' });
+        return false;
+    }
+    return true;
+}
+/** Constant-time bearer check against ABX_RESOLVER_ADMIN_TOKEN. */
+function adminAuthorized(req) {
+    const token = process.env.ABX_RESOLVER_ADMIN_TOKEN;
+    if (!token)
+        return false;
+    const header = req.headers['authorization'];
+    const raw = (Array.isArray(header) ? header[0] : header) ?? '';
+    const m = /^Bearer\s+(.+)$/i.exec(raw.trim());
+    if (!m)
+        return false;
+    const got = Buffer.from(m[1]);
+    const want = Buffer.from(token);
+    return got.length === want.length && timingSafeEqual(got, want);
+}
+/** Read + JSON-parse a request body, capped so a bad caller can't exhaust memory. */
+async function readJsonBody(req, maxBytes = 64 * 1024) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > maxBytes)
+            throw new Error('request body too large');
+        chunks.push(chunk);
+    }
+    if (chunks.length === 0)
+        return {};
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+/**
+ * `POST /admin/projects {address, fromBlock?, factory?, label?, description?, externalUrl?,
+ *    attributes?, contentLocators?}` — attributes are off-chain operator traits; contentLocators
+ *    bridge `{ "0x<keccak>": "ipfs://<cid>" }` so the image points at IPFS without holding bytes.
+ *   → register the contract with THIS node and replay it from chain. Idempotent: a
+ *     re-POST is the post-deploy "nudge" that pulls events that landed since.
+ * `DELETE /admin/projects/:address` → stop indexing it (drops the projection).
+ *
+ * We deliberately do NOT factory-scope here: if you own this resolver and you tell it
+ * a contract, it does its best to index it. (Allowlisting by factory is a platform
+ * concern — see docs/10-backlog.md B6 — not a self-hosting one.)
+ */
+/**
+ * Decide the scan floor + whether a full replay is needed when registering a project via the
+ * admin control plane. Pure (the discovery/refusal fallback for the null case is the caller's):
+ *   - explicit `bodyFromBlock` wins; else the `existingFromBlock` already stored.
+ *   - `null` ⇒ NEITHER supplied nor stored — the caller must derive the deploy block or refuse
+ *     (never default to genesis: a range-capped RPC would sweep millions of blocks).
+ *   - `full` is true only when forced, on a first registration (no existing floor), or when the
+ *     floor actually CHANGED — so re-sending the SAME floor (the CLI now always forwards the deploy
+ *     block, even on a nudge) stays incremental: `abx add --remote` twice ≠ two full scans.
+ */
+export function planRegistrationFloor(bodyFromBlock, existingFromBlock, forceFull = false) {
+    const fromBlock = bodyFromBlock !== undefined ? String(bodyFromBlock) : existingFromBlock;
+    if (fromBlock === undefined)
+        return null;
+    const full = forceFull || existingFromBlock === undefined || fromBlock !== existingFromBlock;
+    return { fromBlock, full };
+}
+async function adminProjects(req, res, indexer, addrSeg) {
+    if (!process.env.ABX_RESOLVER_ADMIN_TOKEN) {
+        return sendJson(res, 404, {
+            error: 'admin API disabled — set ABX_RESOLVER_ADMIN_TOKEN on the resolver to enable remote add/remove',
+        });
+    }
+    if (!adminAuthorized(req)) {
+        return sendJson(res, 401, { error: 'unauthorized — send Authorization: Bearer <ABX_RESOLVER_ADMIN_TOKEN>' });
+    }
+    const method = req.method ?? 'GET';
+    if (method === 'POST' && addrSeg === undefined) {
+        let body;
+        try {
+            body = await readJsonBody(req);
+        }
+        catch (err) {
+            return sendJson(res, 400, { error: err.message });
+        }
+        const address = body.address;
+        if (!address || !ADDRESS_RE.test(address)) {
+            return sendJson(res, 400, { error: 'body.address must be a 0x-prefixed 20-byte address' });
+        }
+        // A re-POST is the post-deploy nudge: preserve the existing scan floor + metadata
+        // (don't reset fromBlock and re-scan), and re-index incrementally. A first add — or one
+        // that supplies a *new* fromBlock — replays fully from that floor. (See planRegistrationFloor.)
+        const existing = indexer.store.getRegistration(address);
+        let plan = planRegistrationFloor(body.fromBlock, existing?.fromBlock, body.full === true);
+        if (!plan) {
+            // No floor supplied and none stored. NEVER default to genesis — a range-capped RPC would
+            // grind millions of blocks (the "resolver won't index" trap). Derive the deploy block from
+            // chain; refuse if we can't (archive getCode unavailable) rather than guess a bad floor.
+            const discovered = await discoverDeployBlock(indexer.publicClient(SERVER_CHAIN_KEY), address);
+            if (discovered === null) {
+                return sendJson(res, 400, {
+                    error: 'first registration needs fromBlock (the contract deploy block) — refusing a from-genesis scan. ' +
+                        'The abx CLI derives it automatically; if calling the API directly, pass fromBlock, or point the resolver at an archive RPC that serves historical eth_getCode.',
+                });
+            }
+            plan = { fromBlock: discovered.toString(), full: true };
+        }
+        const { fromBlock, full } = plan;
+        // Attributes / locators arrive as JSON values; store them as text. Normalize attributes so a
+        // bad payload can't poison the served traits. Each preserves the existing value when omitted.
+        let attributes = existing?.attributes;
+        if (body.attributes !== undefined) {
+            attributes = body.attributes === null ? undefined : JSON.stringify(normalizeAttributes(body.attributes));
+        }
+        // Per-token off-chain traits (a Series' editable attributes): a `{ "<tokenId>": attrs }` object,
+        // each value normalized. Same preserve-on-omit / clear-on-null semantics as `attributes`.
+        let tokenAttributes = existing?.tokenAttributes;
+        if (body.tokenAttributes !== undefined) {
+            if (body.tokenAttributes === null)
+                tokenAttributes = undefined;
+            else {
+                const norm = {};
+                for (const [tokenId, v] of Object.entries(body.tokenAttributes)) {
+                    const a = normalizeAttributes(v);
+                    if (a.length)
+                        norm[tokenId] = a;
+                }
+                tokenAttributes = Object.keys(norm).length ? JSON.stringify(norm) : undefined;
+            }
+        }
+        let contentLocators = existing?.contentLocators;
+        if (body.contentLocators !== undefined) {
+            contentLocators = mergeLocators(existing?.contentLocators, body.contentLocators);
+        }
+        indexer.register({
+            address: address,
+            chainKey: SERVER_CHAIN_KEY,
+            fromBlock,
+            factory: body.factory ?? existing?.factory ?? process.env.ABX_FACTORY ?? null,
+            label: body.label ?? existing?.label,
+            description: body.description ?? existing?.description,
+            externalUrl: body.externalUrl ?? existing?.externalUrl,
+            attributes,
+            tokenAttributes,
+            contentLocators,
+        });
+        const { state, elapsedMs, mode } = await indexer.reindex(address, { full });
+        notifyEffects(address);
+        return sendJson(res, 200, { ok: true, mode, elapsedMs, project: summarize(state) });
+    }
+    if (method === 'DELETE' && addrSeg) {
+        if (!ADDRESS_RE.test(addrSeg))
+            return sendJson(res, 400, { error: 'address path segment must be a 0x address' });
+        const existed = !!indexer.store.getRegistration(addrSeg);
+        indexer.store.deregister(addrSeg);
+        return sendJson(res, existed ? 200 : 404, existed ? { ok: true, address: addrSeg } : { error: 'not registered' });
+    }
+    return sendJson(res, 405, { error: 'use POST /admin/projects or DELETE /admin/projects/<address>' });
+}
+/**
+ * `POST /admin/effect-artifacts {address, tokenId, inputsHash, output?, effectKey?, locator? |
+ *    bytes_base64?, contentType?}` — a conforming effect runner publishes a render output so a
+ *  resolver that does NOT share the runner's storage disk can serve it. Two modes:
+ *    - `locator` (ipfs://<cid> | ar://<txid> | https://…): stored as a pointer; `/image` 302-redirects.
+ *    - `bytes_base64`: stored in this node's own byte custody (what traits use — they inline into JSON).
+ *  The artifact key is computed from the runner-supplied `inputsHash` — NOT recomputed from current
+ *  state — so a render is never re-addressed to a state it doesn't depict (a param change instead makes
+ *  it unreachable, the correct self-invalidation). Admin-token gated; never signs on-chain.
+ */
+async function adminRenderArtifacts(req, res, indexer, storage) {
+    if (!process.env.ABX_RESOLVER_ADMIN_TOKEN) {
+        return sendJson(res, 404, { error: 'admin API disabled — set ABX_RESOLVER_ADMIN_TOKEN on the resolver' });
+    }
+    if (!adminAuthorized(req)) {
+        return sendJson(res, 401, { error: 'unauthorized — send Authorization: Bearer <ABX_RESOLVER_ADMIN_TOKEN>' });
+    }
+    if ((req.method ?? 'GET') !== 'POST') {
+        return sendJson(res, 405, { error: 'use POST /admin/effect-artifacts' });
+    }
+    let body;
+    try {
+        body = await readJsonBody(req, 8 * 1024 * 1024); // a thumbnail pushed as bytes can exceed the 64KB default
+    }
+    catch (err) {
+        return sendJson(res, 400, { error: err.message });
+    }
+    const address = body.address;
+    if (!address || !ADDRESS_RE.test(address)) {
+        return sendJson(res, 400, { error: 'body.address must be a 0x-prefixed 20-byte address' });
+    }
+    if (body.tokenId === undefined || body.tokenId === null) {
+        return sendJson(res, 400, { error: 'body.tokenId required' });
+    }
+    const tokenId = String(body.tokenId);
+    const inputsHashHex = body.inputsHash;
+    if (!inputsHashHex || !/^0x[0-9a-fA-F]{64}$/.test(inputsHashHex)) {
+        return sendJson(res, 400, { error: 'body.inputsHash must be the 0x 32-byte hash the runner rendered (this node does NOT recompute it)' });
+    }
+    // Any declared output key (the data plane's generality) — 'image'/'traits' are just the
+    // reference render effect's two.
+    const output = typeof body.output === 'string' && body.output ? body.output : 'image';
+    const effectKey = typeof body.effectKey === 'string' && body.effectKey ? body.effectKey : 'render';
+    const contentType = body.contentType ?? (output === 'traits' ? 'application/json' : 'image/png');
+    const key = renderArtifactKey(SERVER_CHAIN_ID, address, tokenId, inputsHashHex, output, effectKey);
+    // BOTH modes register a row — the row is the `artifacts` manifest's enumeration surface;
+    // locator NULL on the bytes mode means "the bytes live in this node's custody at the key".
+    const row = { key, address, tokenId, effectKey, outputKey: output, inputsHash: inputsHashHex, contentType };
+    const locator = typeof body.locator === 'string' && body.locator ? body.locator : undefined;
+    if (locator) {
+        indexer.store.putEffectArtifact({ ...row, locator });
+        return sendJson(res, 200, { ok: true, mode: 'locator', key, output, locator });
+    }
+    const bytesB64 = typeof body.bytes_base64 === 'string' && body.bytes_base64 ? body.bytes_base64 : undefined;
+    if (bytesB64) {
+        const bytes = new Uint8Array(Buffer.from(bytesB64, 'base64'));
+        await storage.put(key, { bytes, contentType });
+        indexer.store.putEffectArtifact({ ...row, locator: null });
+        return sendJson(res, 200, { ok: true, mode: 'bytes', key, output, bytes: bytes.length });
+    }
+    return sendJson(res, 400, { error: 'provide body.locator (a durable ipfs://ar://https URL) or body.bytes_base64' });
+}
+/**
+ * `POST /admin/effect-status {key, address, tokenId, effectKey, status, error?, attempts?}` — a
+ * runner reports one run's transient state for the artifact `key` it is producing (the runner
+ * computes the key; this node never re-derives it, mirroring /admin/effect-artifacts). `status`
+ * 'done' clears the row (artifact presence takes over as truth); 'rendering'/'failed' upsert.
+ */
+async function adminEffectStatus(req, res, indexer) {
+    if (!process.env.ABX_RESOLVER_ADMIN_TOKEN) {
+        return sendJson(res, 404, { error: 'admin API disabled — set ABX_RESOLVER_ADMIN_TOKEN on the resolver' });
+    }
+    if (!adminAuthorized(req)) {
+        return sendJson(res, 401, { error: 'unauthorized — send Authorization: Bearer <ABX_RESOLVER_ADMIN_TOKEN>' });
+    }
+    if ((req.method ?? 'GET') !== 'POST')
+        return sendJson(res, 405, { error: 'use POST /admin/effect-status' });
+    let body;
+    try {
+        body = await readJsonBody(req);
+    }
+    catch (err) {
+        return sendJson(res, 400, { error: err.message });
+    }
+    const key = body.key;
+    if (!key || !/^0x[0-9a-fA-F]{64}$/.test(key)) {
+        return sendJson(res, 400, { error: 'body.key must be the 0x 32-byte artifact key this run produces' });
+    }
+    const address = body.address;
+    if (!address || !ADDRESS_RE.test(address)) {
+        return sendJson(res, 400, { error: 'body.address must be a 0x-prefixed 20-byte address' });
+    }
+    const status = body.status;
+    if (status === 'done') {
+        indexer.store.clearEffectStatus(key);
+        return sendJson(res, 200, { ok: true, cleared: key });
+    }
+    if (status !== 'rendering' && status !== 'failed') {
+        return sendJson(res, 400, { error: "body.status must be 'rendering' | 'failed' | 'done'" });
+    }
+    indexer.store.putEffectStatus({
+        key,
+        address,
+        tokenId: String(body.tokenId ?? ''),
+        effectKey: typeof body.effectKey === 'string' && body.effectKey ? body.effectKey : 'render',
+        status,
+        error: typeof body.error === 'string' ? body.error.slice(0, 2000) : null,
+        attempts: typeof body.attempts === 'number' ? body.attempts : undefined,
+    });
+    return sendJson(res, 200, { ok: true, key, status });
+}
+/**
+ * Per-token effect status for a project — the "did every thumbnail land?" surface behind
+ * `GET /api/project/:addr/effects` and `abx verify`. Status is DERIVED, in precedence order:
+ * artifact present at the current settled inputsHash (own store or published locator) →
+ * `up-to-date`; a runner-reported transient row at that key → `rendering` | `failed`; else
+ * `stale` (work the effects layer hasn't landed yet). Non-render effects the resolver doesn't
+ * consume are included verbatim from their reported rows — effect-agnostic by construction.
+ */
+async function effectStatusReport(indexer, state, storage) {
+    const reported = indexer.store.listEffectStatuses(state.address);
+    const byKey = new Map(reported.map((r) => [r.key.toLowerCase(), r]));
+    const tokens = [];
+    const counts = { upToDate: 0, stale: 0, rendering: 0, failed: 0 };
+    if (isCodeProject(state)) {
+        for (const token of state.tokens.filter((t) => t.minted)) {
+            const { key, found } = await currentRenderArtifact(chainClient, state, token, storage);
+            const published = !found && !!indexer.store.getEffectArtifact(key);
+            const row = byKey.get(key.toLowerCase());
+            let status;
+            if (found || published)
+                status = 'up-to-date';
+            else if (row)
+                status = row.status;
+            else
+                status = 'stale';
+            counts[status === 'up-to-date' ? 'upToDate' : status] += 1;
+            byKey.delete(key.toLowerCase());
+            tokens.push({
+                tokenId: token.tokenId,
+                effectKey: 'render',
+                status,
+                key,
+                ...(row?.error ? { error: row.error } : {}),
+                ...(row?.attempts ? { attempts: row.attempts } : {}),
+                ...(row?.updatedAt ? { updatedAt: row.updatedAt } : {}),
+            });
+        }
+    }
+    // Any remaining reported rows belong to effects this resolver doesn't consume — pass through.
+    const other = [...byKey.values()].map((r) => ({
+        tokenId: r.tokenId,
+        effectKey: r.effectKey,
+        status: r.status,
+        key: r.key,
+        ...(r.error ? { error: r.error } : {}),
+        ...(r.attempts ? { attempts: r.attempts } : {}),
+        ...(r.updatedAt ? { updatedAt: r.updatedAt } : {}),
+    }));
+    return { address: state.address, counts, tokens: [...tokens, ...other] };
+}
+/**
+ * Chain-watcher liveness behind `GET /api/watch`. Pure read of the `meta` k/v the watcher stamps
+ * each tick (`watch:pollAt`, `watch:<chainKey>:head`, `watch:<chainKey>` = watched-through block,
+ * `watch:lastDeltaAt`). `watching:false` when nothing has been recorded (watcher off / never ran).
+ * The reader judges freshness from `pollAt` vs `intervalMs` — a stale `pollAt` means it stopped.
+ */
+function watchStatusReport(indexer) {
+    const pollAt = indexer.store.getMeta('watch:pollAt');
+    const chainKeys = [...new Set(indexer.store.listRegistrations().map((r) => r.chainKey))];
+    const chains = {};
+    for (const ck of chainKeys) {
+        chains[ck] = {
+            head: indexer.store.getMeta(`watch:${ck}:head`),
+            watchedThrough: indexer.store.getMeta(`watch:${ck}`),
+        };
+    }
+    return {
+        watching: pollAt !== null,
+        intervalMs: watchIntervalMs(),
+        pollAt,
+        lastDeltaAt: indexer.store.getMeta('watch:lastDeltaAt'),
+        chains,
+    };
+}
+/** 404 for a path whose chainId segment isn't the chain this resolver serves. */
+function wrongChain(res, got) {
+    sendJson(res, 404, { error: `this resolver serves chain ${SERVER_CHAIN_ID}, not ${got}` });
+}
+//# sourceMappingURL=server.js.map