Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

test(solana-crawl): pin the DAS lane outcomes, and record the wall fix for holders

nirholas3e45fdd5374a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 01cb2b750..aedb6089d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
## 2026-08-16
- **A coin world link now unfurls as the live world, and only ever points at three.ws**: Pasting a coin community link into WordPress, Ghost, Discord, Notion or any editor built on embed.ly or iframely now turns it into the live 3D world instead of a plain link. The service that answers those editors existed but nothing on the page told them where to find it, so it was never called. Two problems in that service are fixed at the same time. It used to build the embed from the address in the incoming request rather than from the site address, so a crafted request could hand an editor an embed that framed somebody else site under the three.ws name; the embed is now always built from three.ws itself. And it used to answer for any link at all, returning a generic three.ws world card for a link that was never ours; it now says plainly that the link is not one of ours. It also answers in both of the formats the standard defines, and ignores a coin address that is not a real Solana address instead of putting it in the embed. Separately, the share images for pages and coin worlds, the holder leaderboard card, the free model verification check and the Oracle coin page now accept only read requests, and answer anything else with a clear message rather than doing the work anyway. (`/play`) `[fix, security]`
+- **A dropped page in the agent directory no longer throws away everything you scrolled past**: The agent index loads in pages of 24, and until now a network hiccup on page five did more damage than the hiccup deserved. The Load more button vanished, and the only recovery on offer restarted the list from the top, discarding the hundred-odd agents already on screen. A failed page now says so on its own terms and offers Resume loading, which picks up exactly where it stopped; Start over is still there if you want it, and the error notice clears itself once the page arrives instead of lingering under the results. Three smaller repairs came with it: loading another page no longer redraws the agents already listed, so the grid stops flickering once a few pages are in; the search box and sort menu now show a proper focus ring for keyboard users instead of a one-pixel border tint; and the source filter chips reach a full-size tap target on tablets, not just on phones. (`/agents`) `[fix, improvement]`
- **A GitHub seed that stores nothing no longer costs you six hours**: Seeding an agent from your GitHub profile, repositories and READMEs is allowed once every six hours per agent. Two failures used to spend that window without storing a single fact. The first is entirely ours: when every model provider is busy at once, nothing is read and nothing is written, and you were still locked out for six hours over an outage you did not cause. The second is the run that comes back with no usable facts, which tells you to add a README or another repository, advice you could not act on until the window expired. Both now hand the window straight back, so you can try again as soon as a provider frees up or as soon as you have widened your selection, and the reply says which of the two happened. Nothing else changes: your existing memories are untouched by a failed run, the seed still reads only the profile, repositories and READMEs you ticked, and disconnecting GitHub still deletes every fact it wrote across all your agents. (`/docs/github-memory-seeding`) `[improvement, fix]`
- **A mistyped id on the signal marketplace answers plainly, and the live feed links to the right chain**: The signal marketplace identifies a feed or a subscription by a number. Anything that was not one (a typo, a stray word, an empty box) went straight to the database, which threw the whole query out, so the caller got an opaque "something went wrong" and our alerting recorded a fault that was never a fault. Pausing a feed, killing or resyncing a subscription, and subscribing to a feed each now answer with a plain "that is not a valid id" instead. Separately, the paid live signal stream built its Solscan links from whichever network the request named rather than the one the feed actually publishes on, so a subscriber could be handed devnet explorer links for a mainnet call; the feed's own record now decides, and every proof link lands on the chain the trade really happened on. (`/signals`) `[fix]`
- **Agent attestations that stopped indexing now recover on their own**: An agent's on-chain attestation history is indexed by walking Solana signatures newer than the last one we recorded. If that recorded signature aged out of the RPC node's history, the walk failed outright and kept failing: the same dead signature was replayed on every run, so that agent's attestations silently stopped appearing on its profile while the scheduled job still reported success. The crawler now recognises that case, re-scans from the most recent signatures instead, and clears the stale marker, so an agent that fell behind catches up by itself on the next pass. `[fix, infra]`
@@ -17,6 +18,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
- **Avatar Studio trait library: the mirror can no longer be pointed at someone else's server**: Avatar Studio loads its hair, clothing and accessory traits through a three.ws address that mirrors the open-source trait library, so your browser never talks to an outside CDN. The list of where those traits live was being written using the address in the incoming request, and that address can be set by whoever sends the request. Because the mirror is cached at the edge for a day, one crafted request could have left every Avatar Studio visitor loading trait files from a stranger's server for the next 24 hours. That list is now written the same way for everybody, with no part of it taken from the request, so there is nothing left to steer. Three smaller repairs went in alongside it: asking the mirror how big a file is no longer answers with the compressed size (a trait manifest claimed 2 KB and delivered 20 KB), the mirror will not hand back a web page or script even if the upstream library ever served one, and a failure at the library now answers plainly as either not found or mirror is down instead of passing its raw status through as ours. (`/avatar-studio`) `[security, fix]`
- **Corrected stale numbers across the avatar and animation docs**: An audit of eight documentation pages against the code they describe turned up four claims that had drifted. The Animations page said the motion-capture library held about 2,000 clips when it actually serves 2,874, so both the intro and the gallery section now quote the real size and point at the count the API itself returns. The selfie-to-avatar page listed the wrong default for the face-morph displacement clamp and credited a single tuning sweep instead of the two that chose it. The avatar-creation walkthrough still told people to pick a body type on the selfie flow, a control that was deliberately removed because it changed nothing, and named the wrong fields on the event the page dispatches. The architecture page now says plainly that the whitelist trust mode is reserved rather than enforced. (`/docs/animations`) `[docs]`
- **Creator subscription tiers save their edits again, and a mistyped subscription link says so plainly**: Editing an existing subscription tier from the creator dashboard silently failed: the save never reached the server, so the new name, price or status was lost every time. Saving works now. Alongside it, a mistyped or truncated subscription or tier link used to answer with a generic server failure; it now says the id is not valid, which is what a reader can actually act on. Tier pages are also directly addressable, so a single tier can be linked and read on its own, with unpublished drafts still visible only to the creator who wrote them. `[fix, improvement]`
+- **External Solana agents get their names and artwork back in the directory**: Every agent the platform indexes from the Metaplex Agent Registry had been sitting in the directory as a bare address since August 6: no name, no picture, no 3D model. The crawler asks a Solana node for each agent's artwork through a method only some nodes support, and it was asking the same node every time, one that does not support it. Worse, the node that does support it answers a refusal in the same shape when it is simply busy, so the crawler could not tell 'I cannot do this' from 'not right now'. It now tries each node in turn, keeps the one that answers, waits and retries a busy one instead of writing it off, and refreshes the agents that are missing artwork rather than the same handful at the top of the list every half hour. If no node will serve the artwork at all, the crawl now says so out loud instead of quietly marking every agent as failed. (`/agents`) `[fix, infra]`
- **Forge tools refuse a made-up style or file type, and a worker hiccup no longer reads as a broken job**: Three repairs to the Forge model tools. The stylize filter (voxel, brick, voronoi, lowpoly) checked the requested style against its list in a way that quietly accepted a handful of reserved words, so a request naming one of them was sent to the worker with an unknown filter and no density setting instead of being turned down. The same flaw let the reference-image uploader accept a made-up file type and hand back an upload slot with a nonsense filename. Both now check their list properly, and an unrecognised value falls back to the default or is refused. Separately, while the background remover, mesh optimiser, part splitter and stylizer were checking on a running job, a momentary fault at the worker was reported as a crash on our side, once for every check, which buried the real signal in the alerts. A fault now answers plainly and the page keeps waiting, which is what a passing hiccup deserves. (`/forge`) `[fix, improvement]`
- **Live stage hosts stop swallowing hyphens, and only confirmed tippers get greeted by name**: Two repairs to the Living Stages host. The cleanup pass that tidies the host's spoken line was stripping hyphens along with the invisible characters it was meant to remove, so every show heard "on chain" where the host said "on-chain" and "state of the art" for "state-of-the-art"; punctuation now survives and only invisible characters are removed. Separately, the host's memory of returning regulars counted tips whose on-chain settlement had not been confirmed yet, which meant anyone could post an unconfirmed tip under a name of their choosing and hear the host greet it aloud. That memory now reads confirmed tips only, matching the public leaderboard. Smaller repairs in the same pass: a stage that has not opened its first show is no longer cached as empty at the edge, an over-long coin address is refused instead of quietly trimmed into a different plaza, and the running tip total is written before the response returns. (`/stage`) `[fix, security]`
- **Memory seeding reads Farcaster with no vendor key, and X now works from the app credentials we already hold**: The memory-seeding demo asks a GitHub, X or Farcaster handle what it can learn about you in public, then writes a short memory seed your agent can carry. Two of those three connectors were showing a "connector not configured" card to everyone, because each insisted on a vendor key nobody had set. Farcaster now reads through the same failover the rest of the platform uses: an indexer when a key exists, and a public Farcaster hub with no key at all otherwise, so it returns real profiles and casts on any deployment. Anything the keyless lane genuinely cannot know, such as follower counts, is now shown as unknown instead of zero. The X connector accepts the app key and secret the platform already stores, exchanging them for a read-only token itself, so it no longer needs a separate token provisioned by hand. A mistyped Farcaster name now comes back as not found rather than as an upstream outage, and all four endpoints are documented in the API reference for the first time. (`/demos/memory-seed`) `[fix, improvement, docs]`
diff --git a/api/_lib/sketchfab.js b/api/_lib/sketchfab.js
index 568809087..752cd69a7 100644
--- a/api/_lib/sketchfab.js
+++ b/api/_lib/sketchfab.js
@@ -71,9 +71,14 @@ export function showcaseLink(path) {
// second pick. Fall back to the category instead of publishing the sentinel.
const PLACEHOLDER_PROMPT_RE = /^(image-to-3d|untitled|test)$/i;
+// `other` is the forge's catch-all bucket, not a description, so "Forged Other"
+// is no better a public name than the sentinel it replaced. Fall through to the
+// neutral generic for it and its siblings.
+const VAGUE_CATEGORY_RE = /^(other|misc|miscellaneous|unknown|general|uncategorized)$/i;
+
function categoryName(modelCategory) {
const cat = String(modelCategory || '').trim();
- if (!cat) return '3D Model';
+ if (!cat || VAGUE_CATEGORY_RE.test(cat)) return '3D Model';
// Underscores are a slug separator; hyphens are part of the word ("sci-fi").
return `Forged ${cat.replace(/_+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase())}`;
}
diff --git a/data/changelog.json b/data/changelog.json
index f899986dd..33cbb08f5 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,26 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security. `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-08-16",
+ "title": "External Solana agents get their names and artwork back in the directory",
+ "summary": "Every agent the platform indexes from the Metaplex Agent Registry had been sitting in the directory as a bare address since August 6: no name, no picture, no 3D model. The crawler asks a Solana node for each agent's artwork through a method only some nodes support, and it was asking the same node every time, one that does not support it. Worse, the node that does support it answers a refusal in the same shape when it is simply busy, so the crawler could not tell 'I cannot do this' from 'not right now'. It now tries each node in turn, keeps the one that answers, waits and retries a busy one instead of writing it off, and refreshes the agents that are missing artwork rather than the same handful at the top of the list every half hour. If no node will serve the artwork at all, the crawl now says so out loud instead of quietly marking every agent as failed.",
+ "tags": [
+ "fix",
+ "infra"
+ ],
+ "link": "/agents"
+ },
+ {
+ "date": "2026-08-16",
+ "title": "A dropped page in the agent directory no longer throws away everything you scrolled past",
+ "summary": "The agent index loads in pages of 24, and until now a network hiccup on page five did more damage than the hiccup deserved. The Load more button vanished, and the only recovery on offer restarted the list from the top, discarding the hundred-odd agents already on screen. A failed page now says so on its own terms and offers Resume loading, which picks up exactly where it stopped; Start over is still there if you want it, and the error notice clears itself once the page arrives instead of lingering under the results. Three smaller repairs came with it: loading another page no longer redraws the agents already listed, so the grid stops flickering once a few pages are in; the search box and sort menu now show a proper focus ring for keyboard users instead of a one-pixel border tint; and the source filter chips reach a full-size tap target on tablets, not just on phones.",
+ "tags": [
+ "fix",
+ "improvement"
+ ],
+ "link": "/agents"
+ },
{
"date": "2026-08-16",
"title": "Prompt polish keeps its quotes out of your model, and a busy Forge says so plainly",
diff --git a/public/changelog.json b/public/changelog.json
index 01097c3f9..fb3259380 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-08-16T17:07:14.691Z",
+ "generated_at": "2026-08-16T17:12:03.453Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
@@ -17,6 +17,17 @@
"security"
]
},
+ {
+ "date": "2026-08-16",
+ "type": "update",
+ "title": "A dropped page in the agent directory no longer throws away everything you scrolled past",
+ "summary": "The agent index loads in pages of 24, and until now a network hiccup on page five did more damage than the hiccup deserved. The Load more button vanished, and the only recovery on offer restarted the list from the top, discarding the hundred-odd agents already on screen. A failed page now says so on its own terms and offers Resume loading, which picks up exactly where it stopped; Start over is still there if you want it, and the error notice clears itself once the page arrives instead of lingering under the results. Three smaller repairs came with it: loading another page no longer redraws the agents already listed, so the grid stops flickering once a few pages are in; the search box and sort menu now show a proper focus ring for keyboard users instead of a one-pixel border tint; and the source filter chips reach a full-size tap target on tablets, not just on phones.",
+ "link": "/agents",
+ "tags": [
+ "fix",
+ "improvement"
+ ]
+ },
{
"date": "2026-08-16",
"type": "update",
@@ -122,6 +133,17 @@
"improvement"
]
},
+ {
+ "date": "2026-08-16",
+ "type": "update",
+ "title": "External Solana agents get their names and artwork back in the directory",
+ "summary": "Every agent the platform indexes from the Metaplex Agent Registry had been sitting in the directory as a bare address since August 6: no name, no picture, no 3D model. The crawler asks a Solana node for each agent's artwork through a method only some nodes support, and it was asking the same node every time, one that does not support it. Worse, the node that does support it answers a refusal in the same shape when it is simply busy, so the crawler could not tell 'I cannot do this' from 'not right now'. It now tries each node in turn, keeps the one that answers, waits and retries a busy one instead of writing it off, and refreshes the agents that are missing artwork rather than the same handful at the top of the list every half hour. If no node will serve the artwork at all, the crawl now says so out loud instead of quietly marking every agent as failed.",
+ "link": "/agents",
+ "tags": [
+ "fix",
+ "infra"
+ ]
+ },
{
"date": "2026-08-16",
"type": "update",
diff --git a/public/changelog.xml b/public/changelog.xml
index 11355bc83..b4bca3805 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -14,6 +14,14 @@
<category>fix</category>
<description>Pasting a coin community link into WordPress, Ghost, Discord, Notion or any editor built on embed.ly or iframely now turns it into the live 3D world instead of a plain link. The service that answers those editors existed but nothing on the page told them where to find it, so it was never called. Two problems in that service are fixed at the same time. It used to build the embed from the address in the incoming request rather than from the site address, so a crafted request could hand an editor an embed that framed somebody else site under the three.ws name; the embed is now always built from three.ws itself. And it used to answer for any link at all, returning a generic three.ws world card for a link that was never ours; it now says plainly that the link is not one of ours. It also answers in both of the formats the standard defines, and ignores a coin address that is not a real Solana address instead of putting it in the embed. Separately, the share images for pages and coin worlds, the holder leaderboard card, the free model verification check and the Oracle coin page now accept only read requests, and answer anything else with a clear message rather than doing the work anyway.</description>
</item>
+ <item>
+ <title>A dropped page in the agent directory no longer throws away everything you scrolled past</title>
+ <link>https://three.ws/agents</link>
+ <guid isPermaLink="false">2026-08-16:A dropped page in the agent directory no longer throws away everything you scrolled past</guid>
+ <pubDate>Sun, 16 Aug 2026 12:00:00 GMT</pubDate>
+ <category>fix</category>
+ <description>The agent index loads in pages of 24, and until now a network hiccup on page five did more damage than the hiccup deserved. The Load more button vanished, and the only recovery on offer restarted the list from the top, discarding the hundred-odd agents already on screen. A failed page now says so on its own terms and offers Resume loading, which picks up exactly where it stopped; Start over is still there if you want it, and the error notice clears itself once the page arrives instead of lingering under the results. Three smaller repairs came with it: loading another page no longer redraws the agents already listed, so the grid stops flickering once a few pages are in; the search box and sort menu now show a proper focus ring for keyboard users instead of a one-pixel border tint; and the source filter chips reach a full-size tap target on tablets, not just on phones.</description>
+ </item>
<item>
<title>A GitHub seed that stores nothing no longer costs you six hours</title>
<link>https://three.ws/docs/github-memory-seeding</link>
@@ -94,6 +102,14 @@
<category>fix</category>
<description>Editing an existing subscription tier from the creator dashboard silently failed: the save never reached the server, so the new name, price or status was lost every time. Saving works now. Alongside it, a mistyped or truncated subscription or tier link used to answer with a generic server failure; it now says the id is not valid, which is what a reader can actually act on. Tier pages are also directly addressable, so a single tier can be linked and read on its own, with unpublished drafts still visible only to the creator who wrote them.</description>
</item>
+ <item>
+ <title>External Solana agents get their names and artwork back in the directory</title>
+ <link>https://three.ws/agents</link>
+ <guid isPermaLink="false">2026-08-16:External Solana agents get their names and artwork back in the directory</guid>
+ <pubDate>Sun, 16 Aug 2026 12:00:00 GMT</pubDate>
+ <category>fix</category>
+ <description>Every agent the platform indexes from the Metaplex Agent Registry had been sitting in the directory as a bare address since August 6: no name, no picture, no 3D model. The crawler asks a Solana node for each agent's artwork through a method only some nodes support, and it was asking the same node every time, one that does not support it. Worse, the node that does support it answers a refusal in the same shape when it is simply busy, so the crawler could not tell 'I cannot do this' from 'not right now'. It now tries each node in turn, keeps the one that answers, waits and retries a busy one instead of writing it off, and refreshes the agents that are missing artwork rather than the same handful at the top of the list every half hour. If no node will serve the artwork at all, the crawl now says so out loud instead of quietly marking every agent as failed.</description>
+ </item>
<item>
<title>Forge tools refuse a made-up style or file type, and a worker hiccup no longer reads as a broken job</title>
<link>https://three.ws/forge</link>
diff --git a/public/features.json b/public/features.json
index c5eacdab9..36c178eea 100644
--- a/public/features.json
+++ b/public/features.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-08-16T17:07:14.630Z",
+ "generated_at": "2026-08-16T17:12:03.351Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json",
"site": {
"name": "three.ws",
diff --git a/tests/sketchfab-showcase.test.js b/tests/sketchfab-showcase.test.js
index df6e9e980..acd24e92a 100644
--- a/tests/sketchfab-showcase.test.js
+++ b/tests/sketchfab-showcase.test.js
@@ -38,9 +38,13 @@ describe('buildModelName', () => {
expect(buildModelName('untitled', 'prop')).toBe('Forged Prop');
});
- it('falls back to the generic name when a placeholder prompt has no category', () => {
+ it('falls back to the generic name when a placeholder prompt has no useful category', () => {
expect(buildModelName('image-to-3d')).toBe('3D Model');
expect(buildModelName('image-to-3d', null)).toBe('3D Model');
+ // The live candidate that exposed this sat in the forge's catch-all bucket;
+ // "Forged Other" would have been no better a public name than the sentinel.
+ expect(buildModelName('image-to-3d', 'other')).toBe('3D Model');
+ expect(buildModelName('image-to-3d', 'Uncategorized')).toBe('3D Model');
});
it('leaves a real prompt that merely contains the placeholder words alone', () => {
diff --git a/tests/solana-agents-crawl-das.test.js b/tests/solana-agents-crawl-das.test.js
new file mode 100644
index 000000000..5c2e5c474
--- /dev/null
+++ b/tests/solana-agents-crawl-das.test.js
@@ -0,0 +1,152 @@
+// The metadata half of the Metaplex crawl failed the same silent way the account
+// scan did, and for ten days nobody could see it: the cron answered 200 every 30
+// minutes while all 1571 rows in solana_agents_index carried
+// metadata_error = 'das fetch failed' and no name, image, or GLB.
+//
+// getAsset is a vendor extension, not core JSON-RPC. Two consequences the old
+// code collapsed into one boolean:
+// 1. A lane that does not implement it replies HTTP 200 with JSON-RPC -32601.
+// Pinning lane 0 therefore recorded "no metadata" for every account forever.
+// 2. A lane that DOES implement it says no the same way once it rate limits
+// (api.mainnet-beta.solana.com serves ~15 calls, then -32000). Treating that
+// as "this lane cannot serve DAS" abandons the only working lane in the chain.
+//
+// These pin the three-way classification: rotate past unsupported, retry through
+// throttled, and never spend the structural upsert's budget on the metered leg.
+
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+
+const ACCOUNTS = [
+ { publicKey: 'ref-one', asset: 'asset-one' },
+ { publicKey: 'ref-two', asset: 'asset-two' },
+];
+
+const LANE_UNSUPPORTED = 'https://unsupported.example';
+const LANE_SERVING = 'https://serving.example';
+
+let freshRefs = [];
+const upserts = [];
+
+vi.mock('../api/_lib/db.js', () => ({
+ sql: Object.assign(
+ async (strings, ...values) => {
+ const text = Array.isArray(strings) ? strings.join('?') : String(strings);
+ if (text.includes('last_metadata_at >')) return freshRefs.map((ref) => ({ ref }));
+ if (text.includes('INSERT INTO solana_agents_index')) {
+ upserts.push({ ref: values[1], name: values[6], enriched: values[19] });
+ }
+ return [];
+ },
+ { unsafe: async () => [] },
+ ),
+}));
+
+vi.mock('../api/_lib/solana/connection.js', () => ({
+ solanaRpcEndpoints: () => [LANE_UNSUPPORTED, LANE_SERVING],
+ solanaConnection: vi.fn(() => ({ tag: 'rotating-connection' })),
+}));
+
+function gpaBuilder(accounts) {
+ const builder = {
+ whereField: () => builder,
+ getDeserialized: async () => accounts,
+ };
+ return builder;
+}
+
+vi.mock('@metaplex-foundation/umi-bundle-defaults', () => ({
+ createUmi: () => ({ programs: { add: () => {} } }),
+}));
+vi.mock('@metaplex-foundation/umi', () => ({ publicKey: (v) => v }));
+vi.mock('@metaplex-foundation/mpl-agent-registry', () => ({
+ // All accounts come back on the v2 builder so each test drives a known count.
+ getAgentIdentityV2GpaBuilder: () => gpaBuilder(ACCOUNTS),
+ getAgentIdentityV1GpaBuilder: () => gpaBuilder([]),
+}));
+
+const { crawlMetaplexAgents } = await import('../api/_lib/solana-agents-crawl.js');
+
+const rpcError = (code, message) => ({ ok: true, status: 200, json: async () => ({ error: { code, message } }) });
+const rpcResult = (name) => ({
+ ok: true,
+ status: 200,
+ json: async () => ({ result: { id: 'asset', content: { metadata: { name }, json_uri: 'https://x.test/m.json' } } }),
+});
+
+/** Install a fetch stub that answers per lane URL, recording every call. */
+function stubFetch(perLane) {
+ const calls = [];
+ vi.stubGlobal('fetch', vi.fn(async (url) => {
+ calls.push(String(url));
+ return perLane(String(url), calls.filter((c) => c === String(url)).length);
+ }));
+ return calls;
+}
+
+describe('DAS enrichment rotates the lane chain', () => {
+ beforeEach(() => {
+ freshRefs = [];
+ upserts.length = 0;
+ vi.unstubAllGlobals();
+ });
+
+ it('skips a lane that does not implement getAsset and sticks to one that does', async () => {
+ const calls = stubFetch((url) =>
+ url === LANE_UNSUPPORTED
+ ? rpcError(-32601, 'Method not found')
+ : rpcResult('Indexed Agent'));
+
+ const report = await crawlMetaplexAgents({ deadline: Date.now() + 20_000 });
+
+ expect(report.enriched).toBe(2);
+ expect(report.dasLane).toBe(LANE_SERVING);
+ // The unsupported lane is asked exactly once for the whole run, not once
+ // per account: a -32601 is a capability answer, and re-asking is pure latency.
+ expect(calls.filter((c) => c === LANE_UNSUPPORTED)).toHaveLength(1);
+ expect(report.errors).toEqual([]);
+ });
+
+ it('treats a rate limit as transient and keeps the lane', async () => {
+ // First ask throttles, every later ask serves. A lane classifier that read
+ // -32000 as "cannot serve DAS" would drop the only working lane here.
+ const calls = stubFetch((url, nth) => {
+ if (url === LANE_UNSUPPORTED) return rpcError(-32601, 'Method not found');
+ return nth === 1 ? rpcError(-32000, 'Too many requests') : rpcResult('Indexed Agent');
+ });
+
+ const report = await crawlMetaplexAgents({ deadline: Date.now() + 20_000 });
+
+ expect(report.enriched).toBe(2);
+ expect(report.dasLane).toBe(LANE_SERVING);
+ expect(report.dasThrottled).toBe(1);
+ expect(calls.filter((c) => c === LANE_SERVING).length).toBeGreaterThan(2);
+ });
+
+ it('reports a chain with no DAS provider instead of failing silently', async () => {
+ stubFetch(() => rpcError(-32601, 'Method not found'));
+
+ const report = await crawlMetaplexAgents({ deadline: Date.now() + 20_000 });
+
+ expect(report.enriched).toBe(0);
+ expect(report.dasLane).toBeNull();
+ expect(report.errors).toContainEqual({
+ stage: 'das',
+ error: 'no mainnet RPC lane serves getAsset; rows upserted without metadata',
+ });
+ // The structural leg still covered the whole registry: a metadata outage
+ // must never cost the directory its account rows or their last_seen_at.
+ expect(report.upserted).toBe(ACCOUNTS.length);
+ });
+
+ it('does not re-fetch metadata that is already fresh', async () => {
+ freshRefs = ['ref-one', 'ref-two'];
+ const calls = stubFetch(() => rpcResult('Indexed Agent'));
+
+ const report = await crawlMetaplexAgents({ deadline: Date.now() + 20_000 });
+
+ expect(report.enrichAttempted).toBe(0);
+ expect(calls).toEqual([]);
+ // Still upserted: the structural pass is what keeps last_seen_at honest.
+ expect(report.upserted).toBe(ACCOUNTS.length);
+ });
+});