@artblocks/abx-token-api 0.1.0-alpha.5 → 0.1.0-alpha.51

package/dist/server.js

@@ -1,27 +1,45 @@
 import { createServer } from 'node:http';
-import { fieldOf, makePublicClient, normalizeAttributes, renderArtifactKey, resolveChain, DEFAULT_CHAIN_KEY, verifyAgainstHash, METADATA_FIELD as F, METADATA_REPRESENTATION as R, } from '@artblocks/abx-sdk';
+import { ABX_JS, fieldOf, makePublicClient, normalizeAttributes, renderArtifactKey, resolveChain, DEFAULT_CHAIN_KEY, verifyAgainstHash, METADATA_FIELD as F, METADATA_REPRESENTATION as R, gatewayConfigFromEnv, projectGatewayPrefix, projectGatewayUrl, } 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 { fallbackImageSvg, IMAGE_MEDIA_TYPE } from './content.js';
+import { buildContractMetadata, buildTokenMetadata, fieldMimeType, tokenArtifacts } from './metadata.js';
+import { currentRenderArtifact, currentSettledInputsHash, isCodeProject, liveViewAvailability, 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 { watchIntervalMs } from './watcher.js';
-import { requireBearer, routeControlPlane, safeLocators, sendJson, serviceDescriptor, summarize, } from './control-plane.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 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
+import { requireBearer, routeControlPlane, safeLocators, sendError, sendJson, serviceDescriptor, summarize, } from './control-plane.js';
+// EVERYTHING chain-derived in this module is resolved LAZILY, on first use.
+//
+// It used to be three module-scope consts, and that made an invalid `ABX_CHAIN` catastrophic in a
+// way wildly out of proportion to the mistake: the CLI imports this package (for the generator
+// runtime), so the throw happened during module evaluation — before `main()` existed to catch it.
+// `ABX_CHAIN=mainnet abx doctor` printed a raw Node stack trace with an internal source path and
+// exited 1, as did commands that should diagnose the environment. Deferring the work to first use
+// keeps a bad value an ordinary, catchable error.
+let _chainClient = null;
+/** A read-only client for resolving on-chain `reader`-represented content (eth_call). */
+function chainClientLazy() {
+    return (_chainClient ??= makePublicClient());
+}
+let _serverChainId = null;
+/**
+ * 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.
+ */
+function serverChainId() {
+    return (_serverChainId ??= resolveChain(process.env.ABX_CHAIN).id);
+}
+/** The chain *key* ('sepolia', …) the indexer registers projects under — the string form of the same
+ *  chain {@link serverChainId} identifies. MUST match its default (base-sepolia): a stale 'sepolia'
+ *  once desynced the key from the id. */
+function serverChainKey() {
+    return process.env.ABX_CHAIN ?? DEFAULT_CHAIN_KEY;
+}
 /** The context the /v1 control plane + descriptor run against (control-plane.ts owns the routes). */
 function controlPlaneCtx(indexer, storage, baseUrl) {
-    return { indexer, storage, chainId: SERVER_CHAIN_ID, chainKey: SERVER_CHAIN_KEY, baseUrl };
+    return { indexer, storage, chainId: serverChainId(), chainKey: serverChainKey(), baseUrl };
 }
 /**
  * Resolve a token's image bytes by dispatching on the `image` field's single active
@@ -35,14 +53,14 @@ function controlPlaneCtx(indexer, storage, baseUrl) {
  */
 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
+    const onChain = await resolveFieldBytes(chainClientLazy(), 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);
+            const rendered = await resolveFieldRendered(chainClientLazy(), state.address, token.tokenId, F.image, image);
             if (rendered)
                 return { contentType: rendered.contentType, body: rendered.bytes };
         }
@@ -60,7 +78,11 @@ export async function resolveContent(state, token, storage) {
     // 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`)? */
+/** Is `tokenId` a valid, not-yet-minted position within a multi-token contract's id-space cap
+ *  (`0 <= id < N`)? `maxInvocations` caps the id space the same way for a Series and its edition
+ *  twins (EditionImage/EditionCode) — "number of distinct works" is unchanged by copies-per-id
+ *  — so this needs no contractType branch. A '1of1'/'1of1-edition' has no cap at all (id space
+ *  fixed to {0}); that token gets its pre-mint view a different way — see {@link resolveTokenView}. */
 function withinCap(tokenId, maxInvocations) {
     if (maxInvocations == null)
         return false;
@@ -72,11 +94,52 @@ function withinCap(tokenId, maxInvocations) {
         return false;
     }
 }
+/**
+ * A destroyed token gets `410 Gone`, and every token route answers it before doing any other work.
+ *
+ * The rule is the contract's, not ours: a burned ERC-721's `tokenURI` reverts `NonexistentToken`
+ * (`TokenURI.sol`), so serving a metadata document for that id would put this node in contradiction
+ * with the contract it speaks for. `404` reads as "not available yet" and invites a retry that can
+ * never succeed.
+ *
+ * **There is deliberately no `contractType` check here.** An edition must never `410` — its `uri(id)`
+ * has no existence gate and a zero-supply id can mint again — and the way that is guaranteed is that
+ * `lifecycle` cannot *be* `'burned'` on that standard (it folds to `'no-live-copies'`). The first
+ * version of this function carried an `isEditionState` guard beside the check, which meant the rule
+ * lived in two places and held only as long as everyone remembered the second one. It is in the type
+ * now: `'burned'` means permanent, on either standard, and this route needs to know nothing else.
+ *
+ * Returns `true` when it has answered the request.
+ */
+function goneIfBurned(res, token) {
+    if (token.lifecycle !== 'burned')
+        return false;
+    sendError(res, 410, 'burned', `token ${token.tokenId} was burned — it no longer exists on chain`, { burned: true });
+    return true;
+}
+/**
+ * An unminted token has one public representation: its metadata route returns `{minted: false}`.
+ * Every child content route (image, data, and live view) is absent until the mint exists. Keeping
+ * this gate at the router prevents placeholder images, synthetic live views, or collection-field
+ * fallbacks from making a not-yet-created token look real.
+ *
+ * Returns `true` when it has answered a content request. The metadata route deliberately handles
+ * the same lifecycle separately because its successful, minimal response is part of the public API.
+ */
+function unavailableIfUnminted(res, token) {
+    if (token.lifecycle !== 'unminted')
+        return false;
+    sendError(res, 404, 'not_minted', `token ${token.tokenId} has not been minted`, { minted: false });
+    return true;
+}
 /**
  * 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).
+ * unminted view for a not-yet-minted id within the cap (the multi-token analogue of the 1/1's
+ * seed-token-0, which the SDK's fold seeds unconditionally — see
+ * `reconstruct.ts`'s `assembleState`, so a fresh '1of1'/'1of1-edition' always has an `issued`
+ * entry for id 0 despite carrying no `maxInvocations` cap), or `null` when the id is genuinely
+ * unknown (→ 404).
  */
 export function resolveTokenView(state, tokenId) {
     const issued = state.tokens.find((t) => t.tokenId === tokenId);
@@ -84,12 +147,19 @@ export function resolveTokenView(state, tokenId) {
         return null;
     return {
         tokenId,
-        minted: issued?.minted ?? false,
+        lifecycle: issued?.lifecycle ?? 'unminted',
         owner: issued?.owner ?? null,
         tokenURI: issued?.tokenURI ?? null,
         fields: issued?.fields ?? [],
         lockedFields: issued?.lockedFields ?? [],
         params: issued?.params,
+        // ERC-1155 editions only — absent on `issued` (a 721 token, or an edition id the fold never
+        // touched) stays absent here too; dropping them was a real bug (found while generalizing this
+        // route for editions): every synthesized/passthrough view silently lost supply/cap/holders.
+        supply: issued?.supply,
+        maxSupply: issued?.maxSupply,
+        maxSupplyOverridden: issued?.maxSupplyOverridden,
+        holders: issued?.holders,
     };
 }
 export const DEFAULT_PORT = 8787;
@@ -137,7 +207,7 @@ export function createTokenApiServer(opts) {
             // NEVER hand a raw internal error to the client. An unexpected failure here is usually an
             // upstream RPC error, and viem's message embeds the full endpoint URL — which for a keyed
             // endpoint IS a credential. On a multi-tenant provider that would leak the operator's RPC key
-            // to any tenant who can trigger a 500 (see specs/self-host-toolkit/remote-services.md). So:
+            // to any tenant who can trigger a 500 (see site/content/docs/using-abx/remote-services.mdx). So:
             // full detail to the operator's log, a generic + redacted message on the wire.
             const detail = err.message ?? 'unknown error';
             console.error(`[server] ${req.method} ${req.url} failed: ${detail}`);
@@ -187,19 +257,19 @@ async function route(req, res, indexer, baseUrl, storage) {
     // 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));
+        res.end(renderIndex(indexer.listProjects(), baseUrl, serverChainId()));
         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)
+        if (Number(parts[1]) !== serverChainId())
             return wrongChain(res, parts[1]);
         const state = indexer.getProject(parts[2]);
         if (!state)
-            return sendJson(res, 404, { error: 'unknown project' });
+            return unknownProject(res);
         res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
-        res.end(renderDashboard(state, baseUrl, SERVER_CHAIN_ID));
+        res.end(renderDashboard(state, baseUrl, serverChainId()));
         return;
     }
     // GET /health
@@ -207,7 +277,7 @@ async function route(req, res, indexer, baseUrl, storage) {
         return sendJson(res, 200, { ok: true, baseUrl });
     // GET /.well-known/abx-service — the service descriptor (public): what this node supports,
     // agent-readably, so a client can match a project's needs to this service BEFORE trusting it
-    // with a registration. See specs/self-host-toolkit/remote-services.md.
+    // with a registration. See site/content/docs/using-abx/remote-services.mdx.
     if (parts[0] === '.well-known' && parts[1] === 'abx-service') {
         return sendJson(res, 200, await serviceDescriptor(controlPlaneCtx(indexer, storage, baseUrl)));
     }
@@ -226,17 +296,40 @@ async function route(req, res, indexer, baseUrl, storage) {
     // 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)
+        if (Number(parts[1]) !== serverChainId())
             return wrongChain(res, parts[1]);
         const state = indexer.getProject(parts[2]);
         if (!state)
-            return sendJson(res, 404, { error: 'unknown project' });
+            return unknownProject(res);
         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 sendError(res, 404, 'not_registered', 'unknown token — not minted, and outside this project\'s supply cap');
+        if (goneIfBurned(res, token))
+            return;
+        if (unavailableIfUnminted(res, token))
+            return;
+        // Both no-code verdicts are answered BEFORE the chain client, since neither needs an RPC (see
+        // {liveViewAvailability} for why the two are distinguished at all — collapsing them cost a
+        // tester a day). A plain 503 in this route's own `{error}` shape rather than a structured
+        // `code`: the versioned control plane's ServiceErrorCode set is pinned by remote-services.md and
+        // has no member for "not ready yet", and widening a published interface for one serving-route
+        // diagnostic is a decision, not a bug fix. The status code carries the retry semantics.
+        const availability = liveViewAvailability(state);
+        if (availability === 'indexing') {
+            res.writeHead(503, { 'content-type': 'application/json; charset=utf-8', 'retry-after': '5' });
+            res.end(JSON.stringify({
+                error: "this IS a code project, but its on-chain code has not been folded into the projection yet — retry shortly. If it persists, this node's scan floor is above the deploy block: re-add with --from-block <deployBlock>.",
+            }, null, 2));
+            return;
+        }
+        if (availability === 'not-a-code-project')
             return sendJson(res, 404, { error: 'no live view — not a code project' });
+        const view = await resolveLiveView(chainClientLazy(), state, token);
+        if (!view) {
+            return sendJson(res, 404, {
+                error: 'no live view — this project has a `code` field whose locator is not serveable (the `code` field is locators-only: ipfs/arweave/url)',
+            });
+        }
         if (view.kind === 'redirect') {
             res.writeHead(302, { location: view.location, 'cache-control': 'no-store' });
             res.end();
@@ -270,12 +363,12 @@ async function route(req, res, indexer, baseUrl, storage) {
         // 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)
+            if (Number(parts[2]) !== serverChainId())
                 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));
+                return unknownProject(res);
+            return sendJson(res, 200, await depStatusReport(chainClientLazy(), state));
         }
         if (parts[1] === 'project' && parts[2]) {
             const address = parts[2];
@@ -295,31 +388,70 @@ async function route(req, res, indexer, baseUrl, storage) {
             if (parts[3] === 'effects') {
                 const state = indexer.getProject(address);
                 if (!state)
-                    return sendJson(res, 404, { error: 'unknown project' });
+                    return unknownProject(res);
                 return sendJson(res, 200, await effectStatusReport(indexer, state, storage));
             }
+            // GET /api/project/:addr/artifacts?token=<id> — the typed artifact-manifest read behind
+            // `abx artifacts --remote`. PUBLIC, like /effects and /api/project/:addr: it reports what this
+            // node already serves in a tokenURI document, so bearer-gating it would hide nothing.
+            // Per-token by construction — a code project's settled `inputsHash` is that token's own, so
+            // there is no coherent all-tokens form of this answer.
+            if (parts[3] === 'artifacts') {
+                const state = indexer.getProject(address);
+                if (!state)
+                    return unknownProject(res);
+                const tokenId = url.searchParams.get('token');
+                if (tokenId === null || !/^\d+$/.test(tokenId)) {
+                    return sendError(res, 400, 'invalid_request', 'artifacts is a per-token read — pass ?token=<decimal id>');
+                }
+                const token = state.tokens.find((t) => t.tokenId === tokenId);
+                // Same code + wording the metadata routes already use for this exact condition, so a client
+                // can't tell "unknown token" apart by which route it asked.
+                if (!token)
+                    return sendError(res, 404, 'not_registered', "unknown token — not minted, and outside this project's supply cap");
+                // A burned 721 has no artifacts to report, and saying so as an empty manifest would read as
+                // "nothing rendered yet". Answer what the contract answers — the same gate the metadata and
+                // image routes apply.
+                if (goneIfBurned(res, token))
+                    return;
+                return sendJson(res, 200, await tokenArtifacts(chainClientLazy(), state, token, baseUrl, serverChainId(), displayMeta(indexer, address), storage, planeAccess(indexer)));
+            }
             // GET /api/project/:addr
             const state = indexer.getProject(address);
             if (!state)
-                return sendJson(res, 404, { error: 'unknown project' });
+                return unknownProject(res);
             return sendJson(res, 200, state);
         }
-        return sendJson(res, 404, { error: 'unknown api route' });
+        return sendError(res, 404, 'unknown_route', 'unknown api route', {
+            routes: ['/api/projects', '/api/watch', '/api/project/:address', '/api/project/:address/artifacts', '/api/project/:address/effects', '/api/project/:address/verify', '/api/deps/:chainId/:address'],
+        });
     }
     // 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)
+        if (Number(parts[1]) !== serverChainId())
             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' });
+            return unknownProject(res);
         // 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' });
+            return sendError(res, 404, 'not_registered', 'unknown token — not minted, and outside this project\'s supply cap');
+        // Before the image / data / metadata branches below: all three would otherwise compose an answer
+        // for an id the contract disowns (and `/image` would warm a placeholder for it forever).
+        if (goneIfBurned(res, token))
+            return;
+        // An in-range token position is a valid metadata URL before mint, but it has no token content.
+        // Return only the lifecycle signal; do not publish image/animation URLs that intentionally 404.
+        if (token.lifecycle === 'unminted') {
+            if (parts.length === 4)
+                return sendJson(res, 200, { minted: false });
+            unavailableIfUnminted(res, token);
+            return;
+        }
         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.
@@ -327,13 +459,14 @@ async function route(req, res, indexer, baseUrl, storage) {
                 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 { key, found } = await currentRenderArtifact(chainClientLazy(), state, token, storage);
+                    // `image` is a REFERENCED output (`effects.md → Bound vs referenced`): a producer that
+                    // doesn't share this node's disk registers a locator (ipfs/ar/https) and we 302 straight to
+                    // it (gateway resolved at serve time), never proxying its bytes. `found` is the co-located
+                    // case — the producer wrote the artifact into the backend we share.
                     const published = indexer.store.getEffectArtifact(key);
                     if (published?.locator) {
-                        res.writeHead(302, { location: resolveLocatorUrl(published.locator), 'cache-control': 'public, max-age=300' });
+                        res.writeHead(302, { location: resolveLocatorUrl(state, published.locator), 'cache-control': 'public, max-age=300' });
                         res.end();
                         return;
                     }
@@ -357,7 +490,7 @@ async function route(req, res, indexer, baseUrl, 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.writeHead(302, { location: resolveLocatorUrl(state, target.trim()), 'cache-control': 'public, max-age=300' });
                 res.end();
                 return;
             }
@@ -375,22 +508,58 @@ async function route(req, res, indexer, baseUrl, storage) {
             }
             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)));
+        return sendJson(res, 200, await buildTokenMetadata(chainClientLazy(), state, token, baseUrl, serverChainId(), 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)
+        if (Number(parts[1]) !== serverChainId())
             return wrongChain(res, parts[1]);
         const address = parts[2];
         const state = indexer.getProject(address);
         if (!state)
-            return sendJson(res, 404, { error: 'unknown project' });
+            return unknownProject(res);
         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));
+        return sendJson(res, 200, await buildContractMetadata(chainClientLazy(), state, baseUrl, serverChainId(), displayMeta(indexer, address), storage));
+    }
+    return sendRouteError(res, parts);
+}
+/**
+ * The last word of the router: nothing matched. A BARE 404 here is actively misleading — it's the
+ * same answer as "this project isn't indexed", so a client that hand-built a URL (dropping the
+ * `:id` off `/t/:chainId/:address/:id` and expecting collection metadata is the observed case)
+ * reads its own mistake as a service outage and reports a non-bug.
+ *
+ * So: a KNOWN route prefix with the wrong segment count is a **400 `invalid_request`** naming the
+ * correct template, and anything else is a **404 `unknown_route`**. Same `{error, code}` shape the
+ * control plane already uses (remote-services.md → Errors), so clients key off `code`, not prose.
+ *
+ * These are hints, not a discoverable API: the route grammar is fixed by the `abx-token-api/v1`
+ * interface and committed on-chain per contract (`tokenURIBase`/`contractURIBase`). The real fix for
+ * a client is to read the URL off the contract (`abx tokenuri` / `abx contracturi`) rather than
+ * assembling one — so every hint below points at the grammar it should already have, and never
+ * invites a client to treat routes as per-node negotiable.
+ */
+const ROUTE_TEMPLATES = {
+    t: { template: '/t/:chainId/:address/:id  (· /image · /data/:field)', what: 'token metadata (ERC-721 tokenURI / ERC-1155 uri target)' },
+    c: { template: '/c/:chainId/:address  (· /data/:field)', what: 'ERC-7572 collection metadata' },
+    a: { template: '/a/:chainId/:address/:id', what: 'the live view of a code project' },
+    d: { template: '/d/:chainId/:address', what: 'the per-contract read-only dashboard' },
+};
+function sendRouteError(res, parts) {
+    const known = parts[0] ? ROUTE_TEMPLATES[parts[0]] : undefined;
+    if (known) {
+        // The single highest-value hint: a `/t/:chainId/:address` with no token id is almost always
+        // someone reaching for collection metadata. Name `/c/…` explicitly.
+        const missingId = (parts[0] === 't' || parts[0] === 'a') && parts.length === 3;
+        return sendError(res, 400, 'invalid_request', `malformed ${known.what} path — use ${known.template}` +
+            (missingId ? '. For COLLECTION-level metadata (no token id) use /c/:chainId/:address' : ''), { route: known.template, ...(missingId ? { didYouMean: `/c/${parts[1]}/${parts[2]}` } : {}) });
     }
-    sendJson(res, 404, { error: 'not found' });
+    return sendError(res, 404, 'unknown_route', 'this node serves no route at that path', {
+        routes: Object.values(ROUTE_TEMPLATES).map((r) => r.template.split('  ')[0]),
+        hint: 'a contract commits its own metadata URL on-chain (tokenURIBase/contractURIBase) — read it with `abx tokenuri` / `abx contracturi` instead of building a path',
+    });
 }
 /** The manifest's read surface over the effect-artifact registry (metadata.ts stays store-free). */
 function planeAccess(indexer) {
@@ -399,21 +568,33 @@ function planeAccess(indexer) {
         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). */
+/** Serve one EFFECT artifact's bytes at the CURRENT settled inputsHash. Three sources, in order,
+ *  mirroring `effects.md → Bound vs referenced`:
+ *   - a registered locator (a REFERENCED output) → **302**, never a proxy: the producer holds those
+ *     bytes and its egress stays its own;
+ *   - a BOUND output's content, held with the row (≤64KB, this node stitches it into the JSON too);
+ *   - this node's own custody at the artifact key — a CO-LOCATED producer sharing the backend.
+ *  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 hash = await currentSettledInputsHash(chainClientLazy(), 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.writeHead(302, { location: resolveLocatorUrl(state, row.locator), 'cache-control': 'public, max-age=300' });
             res.end();
             return;
         }
+        if (row?.bytes) {
+            res.writeHead(200, {
+                'content-type': row.contentType || 'application/octet-stream',
+                'cache-control': 'public, max-age=300',
+            });
+            res.end(row.bytes);
+            return;
+        }
         const stored = await storage.get(key);
         if (stored) {
             res.writeHead(200, {
@@ -443,21 +624,21 @@ async function serveFieldArtifact(res, state, token, field, storage, display) {
         return sendJson(res, 404, { error: `no '${field}' field set` });
     const tokenId = token?.tokenId ?? '0';
     try {
-        const onChain = await resolveFieldBytes(chainClient, entry);
+        const onChain = await resolveFieldBytes(chainClientLazy(), entry);
         if (onChain) {
             res.writeHead(200, {
-                'content-type': await fieldMimeType(chainClient, state, entry, field, tokenId, display, storage),
+                'content-type': await fieldMimeType(chainClientLazy(), 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);
+        const rendered = await resolveFieldRendered(chainClientLazy(), 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.writeHead(302, { location: resolveLocatorUrl(state, target), 'cache-control': 'public, max-age=300' });
                 res.end();
                 return;
             }
@@ -477,15 +658,15 @@ async function serveFieldArtifact(res, state, token, field, storage, display) {
             }
             const bridged = display.contentLocators?.[entry.value.toLowerCase()];
             if (bridged) {
-                res.writeHead(302, { location: resolveLocatorUrl(bridged), 'cache-control': 'public, max-age=300' });
+                res.writeHead(302, { location: resolveLocatorUrl(state, 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);
+        const locator = fieldLocatorUrl(state, entry, tokenId);
         if (locator) {
-            res.writeHead(302, { location: resolveLocatorUrl(locator), 'cache-control': 'public, max-age=300' });
+            res.writeHead(302, { location: resolveLocatorUrl(state, locator), 'cache-control': 'public, max-age=300' });
             res.end();
             return;
         }
@@ -496,8 +677,18 @@ async function serveFieldArtifact(res, state, token, field, storage, display) {
     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) {
+function fieldLocatorUrl(state, entry, tokenId) {
+    // Content-addressed values are IDENTITY, not URLs — since v11 a field stores the bare CID/txid,
+    // so returning it raw would 302 a browser to `Location: bafy…`. Project it exactly as the
+    // metadata document does, through the collection's preferred gateway.
+    if (entry.representation === R.ipfs || entry.representation === R.arweave) {
+        const network = entry.representation === R.ipfs ? 'ipfs' : 'arweave';
+        const text = Buffer.from(entry.value.slice(2), 'hex').toString('utf8').trim();
+        if (!text)
+            return null;
+        return projectGatewayUrl(network, text, projectGatewayPrefix(state, network, gatewayConfigFromEnv()), tokenId);
+    }
+    if (entry.representation === R.url) {
         const text = Buffer.from(entry.value.slice(2), 'hex').toString('utf8').trim();
         return text || null;
     }
@@ -575,8 +766,10 @@ async function effectStatusReport(indexer, state, storage) {
     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);
+        // Live tokens only: a destroyed id has no render to be up-to-date about, and reporting one
+        // would keep a producer re-rendering it forever.
+        for (const token of state.tokens.filter((t) => t.lifecycle === 'live')) {
+            const { key, found } = await currentRenderArtifact(chainClientLazy(), state, token, storage);
             const published = !found && !!indexer.store.getEffectArtifact(key);
             const row = byKey.get(key.toLowerCase());
             let status;
@@ -635,8 +828,26 @@ function watchStatusReport(indexer) {
         chains,
     };
 }
-/** 404 for a path whose chainId segment isn't the chain this resolver serves. */
+/**
+ * The path was well-formed and on the right chain — this node just doesn't index that contract.
+ * Code `not_registered` (the control plane's own code for the same condition) so a client can tell
+ * it apart from a malformed path (400 `invalid_request`) and a nonexistent route (404
+ * `unknown_route`). Those three used to be one indistinguishable `{error: '…'}` 404.
+ */
+function unknownProject(res) {
+    sendError(res, 404, 'not_registered', 'this node does not index that contract', {
+        hint: 'register it with `abx add <address> --remote <name|url>` (bearer-gated control plane), then `abx index <address> --remote`',
+    });
+}
+/**
+ * A path whose chainId segment isn't the chain this resolver serves. **400 `unsupported_chain`**,
+ * matching the control plane's `checkChain` exactly (control-plane.ts) — it's a request error, not a
+ * missing resource, and answering 404 made it indistinguishable from "that project isn't indexed
+ * here", which sent at least one client hunting a phantom outage. `chains` says what IS served.
+ */
 function wrongChain(res, got) {
-    sendJson(res, 404, { error: `this resolver serves chain ${SERVER_CHAIN_ID}, not ${got}` });
+    sendError(res, 400, 'unsupported_chain', `this resolver serves chain ${serverChainId()}, not ${got}`, {
+        chains: [serverChainId()],
+    });
 }
 //# sourceMappingURL=server.js.map