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.

fix(erc8004): give an on-chain agent's art a gateway chain to retry, not one URL

nirholasa98e7fa18b43
diff --git a/src/erc8004/resolver.js b/src/erc8004/resolver.js
index 8a484f394..cc5bfc259 100644
--- a/src/erc8004/resolver.js
+++ b/src/erc8004/resolver.js
@@ -20,6 +20,7 @@
import { getAgentOnchain, fetchAgentMetadata, findAvatar3D } from './queries.js';
import { REGISTRY_DEPLOYMENTS, agentRegistryId } from './abi.js';
import { CHAIN_META } from './chain-meta.js';
+import { uriCandidates } from '../ipfs.js';
// ---------------------------------------------------------------------------
// Parsing
@@ -100,12 +101,11 @@ export function toPublicUrl(ref, { embed = false, origin } = {}) {
// URL fallback — tries direct, then rotates IPFS gateways, then Arweave
// ---------------------------------------------------------------------------
-const IPFS_GATEWAYS = [
- 'https://ipfs.io/ipfs/',
- 'https://dweb.link/ipfs/',
- 'https://flk-ipfs.xyz/ipfs/',
- 'https://gateway.pinata.cloud/ipfs/',
-];
+// The single gateway `resolveUrl` picks first. The FALLBACK chain is not
+// duplicated here: src/ipfs.js owns the canonical, dead-host-free gateway list
+// and the CID re-extraction that makes an already-baked gateway URL rotatable,
+// so `resolveUrlCandidates` below delegates to it rather than drifting from it.
+const PRIMARY_IPFS_GATEWAY = 'https://ipfs.io/ipfs/';
const AR_GATEWAY = 'https://arweave.net/';
/**
@@ -118,27 +118,27 @@ const AR_GATEWAY = 'https://arweave.net/';
*/
export function resolveUrl(uri) {
if (!uri) return '';
- if (uri.startsWith('ipfs://')) return IPFS_GATEWAYS[0] + uri.slice(7);
+ if (uri.startsWith('ipfs://')) return PRIMARY_IPFS_GATEWAY + uri.slice(7);
if (uri.startsWith('ar://')) return AR_GATEWAY + uri.slice(5);
return uri;
}
/**
- * All HTTPS forms of an off-chain URI, in preference order. Use when you
- * want to try each in sequence — e.g. the `<img>` fallback chain or a
- * `fetch` retry loop.
+ * All HTTPS forms of an off-chain URI, in preference order. Use when you want
+ * to try each in sequence: the `<img>` fallback chain, a `fetch` retry loop, or
+ * a GLB load that should survive one dead gateway.
+ *
+ * The head of the list is always exactly what `resolveUrl` returns, so a
+ * consumer holding a single URL can find it here and continue past it. The tail
+ * is `uriCandidates` from src/ipfs.js, which owns the live gateway list and can
+ * also re-extract the CID from a URL whose gateway was already baked in
+ * upstream. Keeping two gateway lists is how one of them goes stale.
*
* @param {string} uri
* @returns {string[]}
*/
export function resolveUrlCandidates(uri) {
- if (!uri) return [];
- if (uri.startsWith('ipfs://')) {
- const rest = uri.slice(7);
- return IPFS_GATEWAYS.map((gw) => gw + rest);
- }
- if (uri.startsWith('ar://')) return [AR_GATEWAY + uri.slice(5)];
- return [uri];
+ return uriCandidates(resolveUrl(uri));
}
// ---------------------------------------------------------------------------
@@ -251,6 +251,14 @@ export async function resolveOnchainAgent(input, { ethProvider, fresh = false }
* Mirrors the shape `resolveAgentById` returns so the rest of the boot path
* (memory, skills, runtime) works unchanged.
*
+ * `image` and `body.uri` stay single URLs, unchanged, so every existing
+ * consumer keeps working. Alongside them, `_gatewayCandidates.body` and
+ * `_gatewayCandidates.image` carry the full ordered gateway chain for the same
+ * content, each starting with the single URL above. A consumer that can retry
+ * (an `<img>` onerror chain, a GLB loader) should walk those instead of giving
+ * up on one dead gateway; `uriCandidates()` in src/ipfs.js produces the same
+ * list from any single URL, which is the right call when all you have is one.
+ *
* @param {Awaited<ReturnType<typeof resolveOnchainAgent>>} resolved
* @returns {object}
*/
@@ -261,6 +269,12 @@ export function toManifest(resolved) {
const glb = resolved.glbUrl ? resolveUrl(resolved.glbUrl) : '';
const img = resolved.image ? resolveUrl(resolved.image) : '';
+ // The single URLs above name ONE gateway. When that gateway is down the
+ // avatar or the image is simply missing, with nothing to retry against, so
+ // the manifest also carries the full ordered chain for each. `body[0]` and
+ // `image[0]` are the same strings as `body.uri` and `image`.
+ const bodyCandidates = resolveUrlCandidates(resolved.glbUrl || resolved.image || '');
+ const imageCandidates = resolveUrlCandidates(resolved.image || '');
return {
spec: 'agent-manifest/0.1',
@@ -279,6 +293,7 @@ export function toManifest(resolved) {
description: resolved.description,
image: img,
body: { uri: glb || img, format: 'gltf-binary' },
+ _gatewayCandidates: { body: bodyCandidates, image: imageCandidates },
brain: brainSvc
? { provider: 'remote', endpoint: brainSvc.endpoint }
: { provider: 'none' },
diff --git a/tests/erc8004-gateway-candidates.test.js b/tests/erc8004-gateway-candidates.test.js
new file mode 100644
index 000000000..c6fdaaccf
--- /dev/null
+++ b/tests/erc8004-gateway-candidates.test.js
@@ -0,0 +1,89 @@
+// An on-chain agent's avatar and image live behind ONE IPFS gateway in the
+// manifest the resolver produces, and public gateways go down routinely. When
+// ipfs.io was unreachable the agent rendered with no body and no picture, and
+// the consumer had nothing to retry against: resolveUrlCandidates() existed but
+// had zero callers, and toManifest() fed the single-URL resolveUrl() into both
+// fields.
+//
+// This pins the two halves of the fix: the manifest now carries the full
+// ordered chain next to the single URLs (which are unchanged, so no consumer
+// breaks), and the resolver no longer keeps its own gateway list beside the
+// canonical one in src/ipfs.js.
+import { describe, it, expect } from 'vitest';
+import { resolveUrl, resolveUrlCandidates, toManifest } from '../src/erc8004/resolver.js';
+import { uriCandidates, IPFS_GATEWAYS } from '../src/ipfs.js';
+
+const CID = 'bafkreiabcdefghijklmnopqrstuvwxyz234567abcdefghijklmnopqr';
+
+describe('resolveUrlCandidates', () => {
+ it('starts with exactly what resolveUrl returned', () => {
+ // A consumer holding the single URL must be able to find it in the list
+ // and continue past it, rather than restarting on a different gateway.
+ const list = resolveUrlCandidates(`ipfs://${CID}`);
+ expect(list[0]).toBe(resolveUrl(`ipfs://${CID}`));
+ });
+
+ it('offers every live gateway, not the resolver\'s own stale copy of the list', () => {
+ const list = resolveUrlCandidates(`ipfs://${CID}`);
+ expect(list.length).toBe(IPFS_GATEWAYS.length);
+ for (const gw of IPFS_GATEWAYS) {
+ expect(list).toContain(gw + CID);
+ }
+ });
+
+ it('delegates to uriCandidates so the two can never drift apart', () => {
+ expect(resolveUrlCandidates(`ipfs://${CID}`)).toEqual(uriCandidates(resolveUrl(`ipfs://${CID}`)));
+ });
+
+ it('passes an ar:// URI and a plain https URL straight through', () => {
+ expect(resolveUrlCandidates('ar://tx123')).toEqual(['https://arweave.net/tx123']);
+ expect(resolveUrlCandidates('https://cdn.example/model.glb')).toEqual(['https://cdn.example/model.glb']);
+ });
+
+ it('returns an empty list for an absent URI instead of a list of one empty string', () => {
+ expect(resolveUrlCandidates('')).toEqual([]);
+ expect(resolveUrlCandidates(null)).toEqual([]);
+ });
+});
+
+function resolved(overrides = {}) {
+ return {
+ ref: { agentId: '42', chainId: 8453, registry: '0x0000000000000000000000000000000000000001' },
+ caip: 'eip155:8453:0x0000000000000000000000000000000000000001:42',
+ onchain: { owner: '0x0000000000000000000000000000000000000002' },
+ metadataUrl: `https://ipfs.io/ipfs/${CID}/manifest.json`,
+ name: 'Test Agent',
+ description: '',
+ services: [],
+ metadata: {},
+ ...overrides,
+ };
+}
+
+describe('toManifest gateway candidates', () => {
+ it('leaves image and body.uri exactly as they were', () => {
+ const m = toManifest(resolved({ image: `ipfs://${CID}/a.png`, glbUrl: `ipfs://${CID}/a.glb` }));
+ expect(m.image).toBe(`https://ipfs.io/ipfs/${CID}/a.png`);
+ expect(m.body.uri).toBe(`https://ipfs.io/ipfs/${CID}/a.glb`);
+ });
+
+ it('adds a retry chain whose first entry is the single URL beside it', () => {
+ const m = toManifest(resolved({ image: `ipfs://${CID}/a.png`, glbUrl: `ipfs://${CID}/a.glb` }));
+ expect(m._gatewayCandidates.body[0]).toBe(m.body.uri);
+ expect(m._gatewayCandidates.image[0]).toBe(m.image);
+ expect(m._gatewayCandidates.body.length).toBeGreaterThan(1);
+ });
+
+ it('falls back to the image for the body chain, matching body.uri', () => {
+ // An agent with a picture but no GLB renders the picture as its body;
+ // the retry chain has to follow that same choice or it retries nothing.
+ const m = toManifest(resolved({ image: `ipfs://${CID}/a.png`, glbUrl: null }));
+ expect(m.body.uri).toBe(m.image);
+ expect(m._gatewayCandidates.body).toEqual(m._gatewayCandidates.image);
+ });
+
+ it('emits empty chains, never undefined, for an agent with no off-chain art', () => {
+ const m = toManifest(resolved({ image: null, glbUrl: null }));
+ expect(m._gatewayCandidates).toEqual({ body: [], image: [] });
+ });
+});