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.

5.6 KB
Raw Blame
/**
 * Agent enumeration & metadata fetching.
 *
 * Strategy, in priority order:
 *  1. ERC-721 Enumerable: balanceOf + tokenOfOwnerByIndex (fast, one call per id)
 *  2. Event scan: query Transfer(to = owner) filter on the registry (slow on
 *     chains with many blocks; keep a bounded `fromBlock` when provided)
 *
 * Metadata resolution fetches `tokenURI(id)` and follows ipfs://, ar://, https://.
 */

import { getIdentityRegistry } from './agent-registry.js';
import { IPFS_GATEWAYS } from '../ipfs.js';

/**
 * Resolve an ipfs://, ar://, or https:// URI to an HTTP URL.
 * Returns the first gateway for ipfs — caller may retry others via `ipfsFallbackUrls`.
 * @param {string} uri
 * @returns {string}
 */
export function uriToHttp(uri) {
	if (!uri) return '';
	if (uri.startsWith('ipfs://')) return IPFS_GATEWAYS[0] + uri.slice(7);
	if (uri.startsWith('ar://')) return `https://arweave.net/${uri.slice(5)}`;
	return uri;
}

/**
 * Full list of fallback HTTP URLs for an IPFS URI (for retries).
 * @param {string} uri
 * @returns {string[]}
 */
export function ipfsFallbackUrls(uri) {
	if (!uri?.startsWith('ipfs://')) return [uri];
	const cid = uri.slice(7);
	return IPFS_GATEWAYS.map((gw) => gw + cid);
}

/**
 * Enumerate token IDs owned by `address` on the given registry.
 *
 * @param {import('ethers').Contract} registry
 * @param {string} address
 * @param {{ fromBlock?: number, onStatus?: (msg: string) => void }} [opts]
 * @returns {Promise<{tokenIds: number[], balance: number, strategy: 'enumerable'|'event-scan'|'empty'}>}
 */
export async function getAgentsByOwner(registry, address, opts = {}) {
	const log = opts.onStatus || (() => {});

	log('Reading balance…');
	const balance = Number(await registry.balanceOf(address));
	if (balance === 0) return { tokenIds: [], balance: 0, strategy: 'empty' };

	// Try ERC-721 Enumerable first.
	try {
		const tokenIds = [];
		for (let i = 0; i < balance; i++) {
			tokenIds.push(Number(await registry.tokenOfOwnerByIndex(address, i)));
		}
		return { tokenIds, balance, strategy: 'enumerable' };
	} catch {
		// Fall through to event scan.
	}

	log('Scanning Transfer events…');
	const filter = registry.filters.Transfer(null, address);
	const events = opts.fromBlock
		? await registry.queryFilter(filter, opts.fromBlock)
		: await registry.queryFilter(filter);

	const seen = new Set();
	const tokenIds = [];
	for (const e of events) {
		const id = Number(e.args.tokenId);
		if (seen.has(id)) continue;
		seen.add(id);
		try {
			const currentOwner = await registry.ownerOf(id);
			if (currentOwner.toLowerCase() === address.toLowerCase()) tokenIds.push(id);
		} catch {
			/* burned — skip */
		}
	}
	return { tokenIds, balance, strategy: 'event-scan' };
}

/**
 * Fetch `tokenURI(id)` and its resolved JSON (if reachable).
 *
 * @param {import('ethers').Contract} registry
 * @param {number} tokenId
 * @returns {Promise<{id: number, uri: string, meta: object|null, owner: string|null}>}
 */
export async function fetchTokenMeta(registry, tokenId) {
	let uri = '';
	let meta = null;
	let owner = null;

	try {
		uri = await registry.tokenURI(tokenId);
	} catch {
		/* no URI set */
	}
	try {
		owner = await registry.ownerOf(tokenId);
	} catch {
		/* burned */
	}

	if (uri) {
		const urls = ipfsFallbackUrls(uri);
		for (const u of urls) {
			try {
				const r = await fetch(u, { signal: AbortSignal.timeout(6000) });
				const ct = r.headers.get('content-type') || '';
				if (r.ok && ct.includes('json')) {
					meta = await r.json();
					break;
				}
			} catch {
				/* try next gateway */
			}
		}
	}
	return { id: tokenId, uri, meta, owner };
}

/**
 * Scan past `Registered` events for a given owner — powers the History tab.
 *
 * @param {import('ethers').Contract} registry
 * @param {string} ownerAddress
 * @param {{ fromBlock?: number, limit?: number }} [opts]
 * @returns {Promise<Array<{agentId: number, agentURI: string, txHash: string, blockNumber: number, blockHash: string}>>}
 */
export async function getRegistrationHistory(registry, ownerAddress, opts = {}) {
	const limit = opts.limit ?? 50;
	const filter = registry.filters.Registered(null, null, ownerAddress);
	const events = opts.fromBlock
		? await registry.queryFilter(filter, opts.fromBlock)
		: await registry.queryFilter(filter);

	return events
		.map((e) => ({
			agentId: Number(e.args.agentId),
			agentURI: String(e.args.agentURI || ''),
			txHash: e.transactionHash,
			blockNumber: Number(e.blockNumber),
			blockHash: e.blockHash,
		}))
		.sort((a, b) => b.blockNumber - a.blockNumber)
		.slice(0, limit);
}

/**
 * Read-only registry connect — uses a public RPC when no signer is available.
 * Used by the Search tab when a user hasn't connected a wallet yet.
 *
 * @param {number} chainId
 * @param {string} [rpcUrl]  override; omit to use the chain's failover node list
 * @returns {Promise<import('ethers').Contract>}
 */
export async function getReadOnlyRegistry(chainId, rpcUrl) {
	const { JsonRpcProvider, Contract } = await import('ethers');
	const { readProvider } = await import('./chain-meta.js');
	const { REGISTRY_DEPLOYMENTS, IDENTITY_REGISTRY_ABI } = await import('./abi.js');
	const deployment = REGISTRY_DEPLOYMENTS[chainId];
	if (!deployment?.identityRegistry) {
		throw new Error(`No registry for chain ${chainId}`);
	}
	// A caller-supplied URL is honoured as-is; otherwise the chain's failover
	// list answers, so an unconnected visitor's search does not depend on one
	// public node staying up.
	const provider = rpcUrl ? new JsonRpcProvider(rpcUrl) : readProvider(chainId);
	return new Contract(deployment.identityRegistry, IDENTITY_REGISTRY_ABI, provider);
}

export { getIdentityRegistry };