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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
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.jsindex 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.jsnew file mode 100644index 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: [] });+ });+});