@artblocks/abx-token-api 0.1.0-alpha.1 → 0.1.0-alpha.11

package/dist/server.js

@@ -1,6 +1,5 @@
 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 { 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';
@@ -9,16 +8,41 @@ 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
+import { watchIntervalMs } from './watcher.js';
+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, and so did EVERY other command, including the ones whose whole job is to tell you what
+// is wrong with your environment. A cold agent hit it and reported the tool as broken; it was right.
+// 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: serverChainId(), chainKey: serverChainKey(), baseUrl };
+}
 /**
  * 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
@@ -31,14 +55,14 @@ const SERVER_CHAIN_KEY = process.env.ABX_CHAIN ?? DEFAULT_CHAIN_KEY; // MUST mat
  */
 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 };
         }
@@ -130,10 +154,32 @@ export function createTokenApiServer(opts) {
             await route(req, res, indexer, baseUrl, storage);
         }
         catch (err) {
-            sendJson(res, 500, { error: err.message });
+            // 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:
+            // 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}`);
+            sendJson(res, 500, {
+                error: `internal error serving ${req.url ?? '/'} — see the node's logs for detail${upstreamHint(detail)}`,
+                code: 'internal_error',
+            });
         }
     });
 }
+/** A safe, credential-free hint about WHAT class of thing broke, so a caller isn't left blind by the
+ *  generic 500. Recognizes the common upstream-RPC failures by status text only — never echoes the
+ *  message (which can embed a keyed endpoint URL). */
+function upstreamHint(detail) {
+    if (/\b429\b|Too Many Requests|rate limit/i.test(detail))
+        return ' (upstream RPC rate-limited this node — its operator needs a higher-capacity endpoint)';
+    if (/\b(401|403)\b|Unauthorized|Forbidden/i.test(detail))
+        return " (this node's upstream RPC rejected its credentials)";
+    if (/\b5\d\d\b|ECONNREFUSED|ETIMEDOUT|fetch failed/i.test(detail))
+        return " (this node's upstream RPC is unreachable or erroring)";
+    return '';
+}
 export function startTokenApiServer(opts) {
     const port = opts.port ?? Number(process.env.ABX_PORT ?? DEFAULT_PORT);
     const baseUrl = opts.baseUrl ?? resolveBaseUrl(port);
@@ -147,27 +193,44 @@ async function route(req, res, indexer, baseUrl, storage) {
     const url = new URL(req.url ?? '/', 'http://localhost');
     const parts = url.pathname.split('/').filter(Boolean);
     const method = req.method ?? 'GET';
+    // CORS preflight — without this, a browser client can never send Authorization to the
+    // control plane (the wildcard origin above covers simple GETs only).
+    if (method === 'OPTIONS') {
+        res.writeHead(204, {
+            'access-control-allow-methods': 'GET,POST,DELETE,OPTIONS',
+            'access-control-allow-headers': 'authorization,content-type',
+            'access-control-max-age': '86400',
+        });
+        res.end();
+        return;
+    }
     // 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
     if (parts[0] === 'health')
         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.
+    if (parts[0] === '.well-known' && parts[1] === 'abx-service') {
+        return sendJson(res, 200, await serviceDescriptor(controlPlaneCtx(indexer, storage, baseUrl)));
+    }
     // GET /abx.js — the runtime companion (directory builds include it; the generator inlines it).
     if (parts[0] === 'abx.js') {
         res.writeHead(200, {
@@ -183,15 +246,15 @@ 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);
+            return sendError(res, 404, 'not_registered', 'unknown token — not minted, and outside this project\'s supply cap');
+        const view = await resolveLiveView(chainClientLazy(), state, token);
         if (!view)
             return sendJson(res, 404, { error: 'no live view — not a code project' });
         if (view.kind === 'redirect') {
@@ -203,25 +266,14 @@ async function route(req, res, indexer, baseUrl, storage) {
         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);
+    // /v1/* — the control plane (register/list/deregister/reindex/status + the effect-publish
+    // lane). 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. Routes + auth live in control-plane.ts.
+    if (parts[0] === 'v1') {
+        return routeControlPlane(req, res, controlPlaneCtx(indexer, storage, baseUrl), parts.slice(1));
     }
     // /api/*
     if (parts[0] === 'api') {
@@ -238,30 +290,21 @@ 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];
-            // 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
+            // BEARER-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).
+            // Reindex moved to the control plane: POST /v1/projects/{chainId}/{address}/reindex.
             if (parts[3] === 'verify') {
-                if (!requireAdmin(req, res))
+                if (!requireBearer(req, res))
                     return;
                 return sendJson(res, 200, await verifyProject(indexer.getProject(address), storage));
             }
@@ -272,31 +315,33 @@ 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
             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/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');
         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.
@@ -304,10 +349,11 @@ 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' });
@@ -352,22 +398,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));
     }
-    sendJson(res, 404, { error: 'not found' });
+    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: 'ERC-721 token metadata' },
+    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]}` } : {}) });
+    }
+    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) {
@@ -376,14 +458,18 @@ 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) {
@@ -391,6 +477,14 @@ async function serveEffectArtifact(res, state, token, effectKey, outputKey, stor
             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, {
@@ -420,17 +514,17 @@ 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();
@@ -523,32 +617,6 @@ function safeTokenAttributes(json) {
         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' };
@@ -564,301 +632,6 @@ export async function verifyProject(state, storage) {
     }));
     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:
@@ -874,7 +647,7 @@ async function effectStatusReport(indexer, state, storage) {
     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 { key, found } = await currentRenderArtifact(chainClientLazy(), state, token, storage);
             const published = !found && !!indexer.store.getEffectArtifact(key);
             const row = byKey.get(key.toLowerCase());
             let status;
@@ -933,8 +706,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