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.

12.6 KB
Raw Blame
/**
 * Universal on-chain agent resolver.
 *
 * One import point for every surface that needs to turn "an on-chain agent"
 * into something renderable: the web component, oEmbed, OG image, explore
 * page, Claude.ai artifact, LobeHub plugin, SDK.
 *
 * Inputs it understands:
 *
 *   parseAgentRef('eip155:8453:0xabc...:42')         — full CAIP-10 + tokenId
 *   parseAgentRef('onchain:8453:42')                 — shorthand (canonical registry)
 *   parseAgentRef('agent://8453/42')                 — agent URI
 *   parseAgentRef({ chainId: 8453, agentId: 42 })    — already parsed
 *   parseAgentRef('/a/8453/42')                      — URL path
 *
 * Output of resolveOnchainAgent: a normalized record with on-chain facts
 * (owner, URI) + off-chain metadata + a resolved GLB URL.
 */

import { getAgentOnchain, fetchAgentMetadata, findAvatar3D } from './queries.js';
import { REGISTRY_DEPLOYMENTS, agentRegistryId } from './abi.js';
import { CHAIN_META } from './chain-meta.js';
import { IPFS_GATEWAYS, uriCandidates } from '../ipfs.js';

// ---------------------------------------------------------------------------
// Parsing
// ---------------------------------------------------------------------------

/**
 * Parse any supported agent reference into `{ chainId, agentId, registry? }`.
 * Returns `null` if the input doesn't look like an on-chain reference.
 *
 * @param {string|object} input
 * @returns {{ chainId: number, agentId: string, registry?: string }|null}
 */
export function parseAgentRef(input) {
	if (!input) return null;

	if (typeof input === 'object') {
		if (input.chainId && input.agentId !== undefined) {
			return {
				chainId: Number(input.chainId),
				agentId: String(input.agentId),
				registry: input.registry || undefined,
			};
		}
		return null;
	}

	const s = String(input).trim();
	if (!s) return null;

	// Full CAIP-10 + token: "eip155:<chainId>:<registry>:<agentId>"
	let m = s.match(/^eip155:(\d+):(0x[0-9a-fA-F]{40}):(\d+)$/);
	if (m) return { chainId: Number(m[1]), registry: m[2], agentId: m[3] };

	// CAIP-10 assetType form: "eip155:<chainId>/erc721:<registry>/<agentId>"
	m = s.match(/^eip155:(\d+)\/erc721:(0x[0-9a-fA-F]{40})\/(\d+)$/);
	if (m) return { chainId: Number(m[1]), registry: m[2], agentId: m[3] };

	// Shorthand: "onchain:<chainId>:<agentId>"
	m = s.match(/^onchain:(\d+):(\d+)$/);
	if (m) return { chainId: Number(m[1]), agentId: m[2] };

	// agent:// scheme
	m = s.match(/^agent:\/\/(\d+)\/(\d+)$/);
	if (m) return { chainId: Number(m[1]), agentId: m[2] };

	// URL path: "/a/<chainId>/<agentId>" or with explicit registry
	m = s.match(/^\/?a\/(\d+)\/(\d+)(?:\/(embed))?\/?$/);
	if (m) return { chainId: Number(m[1]), agentId: m[2] };
	m = s.match(/^\/?a\/(\d+)\/(0x[0-9a-fA-F]{40})\/(\d+)\/?$/);
	if (m) return { chainId: Number(m[1]), registry: m[2], agentId: m[3] };

	return null;
}

/**
 * Return the canonical CAIP-10 identifier string for an agent.
 * @param {{ chainId: number, agentId: string|number, registry?: string }} ref
 */
export function toCAIP10(ref) {
	const registry = ref.registry || REGISTRY_DEPLOYMENTS[ref.chainId]?.identityRegistry;
	if (!registry) return `onchain:${ref.chainId}:${ref.agentId}`;
	return `eip155:${ref.chainId}:${registry}:${ref.agentId}`;
}

/**
 * Return the public `/a/<chainId>/<agentId>` URL for an agent.
 * @param {{ chainId: number, agentId: string|number }} ref
 * @param {object} [opts]
 * @param {boolean} [opts.embed]   Append `/embed` for chromeless iframe mode
 * @param {string}  [opts.origin]  Override origin (defaults to location.origin)
 */
export function toPublicUrl(ref, { embed = false, origin } = {}) {
	const o = origin || (typeof location !== 'undefined' ? location.origin : '');
	return `${o}/a/${ref.chainId}/${ref.agentId}${embed ? '/embed' : ''}`;
}

// ---------------------------------------------------------------------------
// URL fallback — tries direct, then rotates IPFS gateways, then Arweave
// ---------------------------------------------------------------------------

// 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 = IPFS_GATEWAYS[0];
const AR_GATEWAY = 'https://arweave.net/';

/**
 * Convert any of `https://…`, `ipfs://<cid>[/path]`, `ar://<tx>` into a plain
 * HTTPS URL. For ipfs, returns the first gateway — use `resolveUrlCandidates`
 * when you need fallbacks.
 *
 * @param {string} uri
 * @returns {string}
 */
export function resolveUrl(uri) {
	if (!uri) return '';
	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: 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) {
	return uriCandidates(resolveUrl(uri));
}

// ---------------------------------------------------------------------------
// Resolution
// ---------------------------------------------------------------------------

// Lightweight in-memory cache keyed by canonical ref string. The resolver is
// a hot path on /discover and in consumer embeds; don't hit the chain twice
// for the same agent within a page session.
const _cache = new Map();
function cacheKey(ref) {
	return `${ref.chainId}:${ref.agentId}`;
}

/**
 * Full resolution of an on-chain ERC-8004 agent.
 *
 * @param {string|object} input   Anything `parseAgentRef` accepts
 * @param {object} [opts]
 * @param {any}     [opts.ethProvider]  EIP-1193 provider for chain reads
 * @param {boolean} [opts.fresh]        Bypass the session cache
 * @returns {Promise<{
 *   ref: { chainId: number, agentId: string, registry: string },
 *   caip: string,
 *   publicUrl: string,
 *   chain: { name: string, testnet: boolean, explorer: string }|null,
 *   onchain: { owner: string|null, uri: string|null },
 *   metadata: any|null,
 *   metadataUrl: string|null,
 *   image: string|null,
 *   glbUrl: string|null,
 *   name: string,
 *   description: string,
 *   services: any[],
 *   error?: string,
 * }>}
 */
export async function resolveOnchainAgent(input, { ethProvider, fresh = false, origin } = {}) {
	const parsed = parseAgentRef(input);
	if (!parsed) throw new Error(`Unrecognised agent reference: ${input}`);

	const ref = {
		chainId: parsed.chainId,
		agentId: String(parsed.agentId),
		registry: parsed.registry || REGISTRY_DEPLOYMENTS[parsed.chainId]?.identityRegistry || null,
	};
	if (!ref.registry) throw new Error(`No registry deployed on chain ${ref.chainId}`);

	const key = cacheKey(ref);
	if (!fresh && _cache.has(key)) return _cache.get(key);

	const chainMeta = CHAIN_META[ref.chainId] || null;
	const base = {
		ref,
		caip: toCAIP10(ref),
		// `origin` is the three.ws API base when an embed on another site calls
		// this; the page's own origin would link the visitor to that site.
		publicUrl:
			origin || typeof location !== 'undefined'
				? toPublicUrl(ref, { origin })
				: `/a/${ref.chainId}/${ref.agentId}`,
		chain: chainMeta
			? { name: chainMeta.name, testnet: !!chainMeta.testnet, explorer: chainMeta.explorer }
			: null,
		onchain: { owner: null, uri: null },
		metadata: null,
		metadataUrl: null,
		image: null,
		glbUrl: null,
		name: `Agent #${ref.agentId}`,
		description: '',
		services: [],
	};

	try {
		const { owner, uri } = await getAgentOnchain({
			chainId: ref.chainId,
			agentId: ref.agentId,
			ethProvider,
		});
		base.onchain = { owner, uri };

		if (!uri) {
			base.error = 'agentURI not set';
			_cache.set(key, base);
			return base;
		}

		const metaRes = await fetchAgentMetadata(uri, { apiOrigin: origin });
		if (!metaRes.ok) {
			base.error = metaRes.error;
			base.metadataUrl = metaRes.resolvedUrl || null;
			_cache.set(key, base);
			return base;
		}
		const md = metaRes.data;
		base.metadata = md;
		base.metadataUrl = metaRes.resolvedUrl || null;
		base.name = (md?.name && String(md.name)) || base.name;
		base.description = (md?.description && String(md.description)) || '';
		base.image = md?.image ? String(md.image) : null;
		base.services = Array.isArray(md?.services) ? md.services : [];
		base.glbUrl = findAvatar3D(md);
	} catch (err) {
		base.error = err.message || String(err);
	}

	_cache.set(key, base);
	return base;
}

/**
 * Build a full agent-manifest/0.1 object from a resolved on-chain agent.
 * 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}
 */
export function toManifest(resolved) {
	const services = Array.isArray(resolved.services) ? resolved.services : [];
	const brainSvc = services.find((s) => /brain|llm|chat/i.test(s?.name || s?.type || ''));
	const skillSvcs = services.filter((s) => /skill/i.test(s?.name || s?.type || ''));

	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',
		_baseURI: resolved.metadataUrl ? trimToDir(resolved.metadataUrl) : '',
		_source: 'erc8004-resolver',
		id: {
			agentId: resolved.ref.agentId,
			chainId: resolved.ref.chainId,
			registry: resolved.ref.registry,
			owner: resolved.onchain.owner || undefined,
			walletAddress: resolved.onchain.owner || undefined,
			caip: resolved.caip,
			agentRegistry: agentRegistryId(resolved.ref.chainId, resolved.ref.registry),
		},
		name: resolved.name,
		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' },
		voice: { tts: { provider: 'browser' }, stt: { provider: 'browser' } },
		skills: skillSvcs.map((s) => ({ name: s.name, uri: s.endpoint })),
		memory: { mode: 'local', namespace: resolved.caip },
		tools: ['wave', 'lookAt', 'play_clip', 'setExpression'],
		version: '0.1.0',
		services,
		x402Support: !!(resolved.metadata?.x402Support || resolved.metadata?.x402),
		embedPolicy: resolved.metadata?.embedPolicy || null,
	};
}

function trimToDir(url) {
	const i = url.lastIndexOf('/');
	return i >= 0 ? url.slice(0, i + 1) : url;
}

/**
 * Should a given parent origin be allowed to embed this agent?
 * Respects an `embedPolicy` field in the registration JSON:
 *
 *   { mode: 'allowlist'|'denylist', hosts: ['example.com', '*.foo.com'] }
 *
 * No policy = public. Rules match hostname suffix; `*.` wildcards supported.
 *
 * @param {object|null} policy
 * @param {string} host
 * @returns {boolean}
 */
export function isEmbedAllowed(policy, host) {
	if (!policy || !policy.mode || !Array.isArray(policy.hosts)) return true;
	const match = policy.hosts.some((rule) => {
		if (!rule) return false;
		const r = String(rule).toLowerCase();
		const h = String(host || '').toLowerCase();
		if (r.startsWith('*.')) return h === r.slice(2) || h.endsWith('.' + r.slice(2));
		return h === r;
	});
	return policy.mode === 'allowlist' ? match : !match;
}