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.

7.8 KB
Raw Blame
// Solana token metadata resolver: Postgres cache primary, Helius DAS on miss,
// keyless Jupiter as the rung that keeps working when Helius does not.
//
// Why: getAsset/searchAssets are the most expensive Helius calls (~10 credits
// each). Mint metadata (symbol, name, logo, decimals) is effectively immutable,
// so we resolve a mint *once* and serve from `token_metadata` forever after.
//
// Cache flow for getMetadataForMints(mints[]):
//   1. SELECT cached rows from token_metadata (fabricated placeholders re-resolve)
//   2. Resolve cache misses via Helius getAssetBatch (single RPC, up to 1000 mints)
//   3. Resolve whatever Helius could not name via Jupiter token search (keyless)
//   4. INSERT new rows (ON CONFLICT DO UPDATE, refreshing stale logos)
//
// Falls back gracefully:
//   - no Helius key or exhausted Helius quota: Jupiter names the mint instead
//   - no source knows the mint: symbol/name are null, never a slice of the mint
//   - DB unreachable: in-memory map for the request lifetime

import { sql, sqlValues } from './db.js';

import { fetchUpstream, fetchUpstreamJson } from './upstream-fetch.js';
const REFRESH_AFTER_MS = 1000 * 60 * 60 * 24 * 30; // 30 days

function heliusRpcUrl() {
	const key = process.env.HELIUS_API_KEY;
	return key ? `https://mainnet.helius-rpc.com/?api-key=${key}` : null;
}

// A mint no source could name. symbol/name stay null rather than a slice of the
// mint: a fabricated "So1111" reads as a real ticker to every downstream caller
// and to any agent consuming /api/crypto/wallet. Presentation layers
// (src/portfolio.js, api/_lib/portfolio-overview.js) already derive a short-mint
// label from a null symbol, so the honest null costs nothing on screen.
function bareEntry(mint) {
	return { mint, symbol: null, name: null, logo: null, decimals: null };
}

// Rows written before the Jupiter rung existed (and any Helius row that fell back
// to a mint slice) carry a fabricated symbol. Treat those as cache misses so the
// cache heals itself on the next read instead of serving the fake forever.
function isFabricated(entry) {
	if (!entry?.symbol) return false;
	return entry.symbol === entry.mint.slice(0, 6) || entry.symbol === entry.mint.slice(0, 8);
}

async function fetchFromCache(mints) {
	if (mints.length === 0) return new Map();
	try {
		const rows = await sql`
			SELECT mint, symbol, name, logo, decimals, refreshed_at
			FROM token_metadata
			WHERE mint = ANY(${mints}) AND chain = 'solana'
		`;
		const out = new Map();
		const now = Date.now();
		for (const r of rows) {
			const age = now - new Date(r.refreshed_at).getTime();
			if (age > REFRESH_AFTER_MS) continue; // stale, re-resolve
			const entry = {
				mint: r.mint,
				symbol: r.symbol,
				name: r.name,
				logo: r.logo,
				decimals: r.decimals,
			};
			if (isFabricated(entry)) continue; // mint-slice placeholder, re-resolve
			out.set(r.mint, entry);
		}
		return out;
	} catch (err) {
		console.warn('[token-metadata] cache read failed:', err?.message);
		return new Map();
	}
}

async function persist(entries, source) {
	if (entries.length === 0) return;
	try {
		const now = new Date();
		const rows = entries.map((e) => [
			e.mint, 'solana', e.symbol, e.name, e.logo, e.decimals, source, now,
		]);
		await sql`
			INSERT INTO token_metadata (mint, chain, symbol, name, logo, decimals, source, refreshed_at)
			VALUES ${sqlValues(rows)}
			ON CONFLICT (mint) DO UPDATE SET
				symbol = EXCLUDED.symbol,
				name = EXCLUDED.name,
				logo = EXCLUDED.logo,
				decimals = EXCLUDED.decimals,
				refreshed_at = EXCLUDED.refreshed_at
		`;
	} catch (err) {
		console.warn('[token-metadata] cache write failed:', err?.message);
	}
}

async function resolveViaHelius(mints) {
	const rpc = heliusRpcUrl();
	if (!rpc || mints.length === 0) return [];
	try {
		const r = await fetchUpstream(rpc, {
			method: 'POST',
			headers: { 'content-type': 'application/json' },
			body: JSON.stringify({
				jsonrpc: '2.0',
				id: 'getAssetBatch',
				method: 'getAssetBatch',
				params: { ids: mints },
			}),
		}, { name: 'helius-das', timeoutMs: 8_000, attempts: 2, okWhen: () => true });
		if (!r.ok) {
			console.warn('[token-metadata] helius getAssetBatch failed:', r.status);
			return [];
		}
		const json = await r.json();
		const results = Array.isArray(json?.result) ? json.result : [];
		return results
			.filter(Boolean)
			.map((asset) => {
				const md = asset?.content?.metadata || {};
				const decimals = asset?.token_info?.decimals ?? null;
				return {
					mint: asset.id,
					symbol: md.symbol || null,
					name: md.name || md.symbol || null,
					logo: asset?.content?.links?.image || asset?.content?.files?.[0]?.uri || null,
					decimals,
				};
			})
			.filter((e) => e.symbol || e.name || e.logo);
	} catch (err) {
		console.warn('[token-metadata] helius resolve failed:', err?.message);
		return [];
	}
}

// Keyless metadata rung. Jupiter's token search names any mint that has ever
// traded on a Solana AMM, needs no key, and is the same host already used for
// prices in api/_lib/balances.js. It is what keeps symbols real when the Helius
// quota is exhausted (which returns HTTP 429 "max usage reached" on every call,
// including getAssetBatch) or when no HELIUS_API_KEY is configured at all.
const JUPITER_SEARCH_BATCH = 100;

async function resolveViaJupiter(mints) {
	if (mints.length === 0) return [];
	const out = [];
	for (let i = 0; i < mints.length; i += JUPITER_SEARCH_BATCH) {
		const chunk = mints.slice(i, i + JUPITER_SEARCH_BATCH);
		try {
			// One chunk failing leaves those mints unnamed in the DB cache for as
			// long as the row lives, so it is worth a retry rather than a skip.
			let rows;
			try {
				rows = await fetchUpstreamJson(
					`https://lite-api.jup.ag/tokens/v2/search?query=${chunk.join(',')}`,
					{},
					{ name: 'jupiter:tokens-search', timeoutMs: 15_000, attempts: 2 },
				);
			} catch (err) {
				console.warn('[token-metadata] jupiter search failed:', err?.message || err);
				continue;
			}
			if (!Array.isArray(rows)) continue;
			for (const t of rows) {
				if (!t?.id || !(t.symbol || t.name)) continue;
				out.push({
					mint: t.id,
					symbol: t.symbol || null,
					name: t.name || t.symbol || null,
					logo: t.icon || null,
					decimals: Number.isFinite(t.decimals) ? t.decimals : null,
				});
			}
		} catch (err) {
			console.warn('[token-metadata] jupiter chunk failed:', err?.message);
		}
	}
	return out;
}

/**
 * Resolve metadata for a list of mints. Always returns one entry per input mint
 * (bare placeholder if everything else fails).
 * @param {string[]} mints
 * @returns {Promise<Map<string, {mint,symbol,name,logo,decimals}>>}
 */
export async function getMetadataForMints(mints) {
	const unique = Array.from(new Set(mints.filter(Boolean)));
	if (unique.length === 0) return new Map();

	const cached = await fetchFromCache(unique);
	let missing = unique.filter((m) => !cached.has(m));

	if (missing.length > 0) {
		// Helius getAssetBatch caps at 1000 per request, so chunk safely.
		const resolved = [];
		for (let i = 0; i < missing.length; i += 1000) {
			const chunk = missing.slice(i, i + 1000);
			const part = await resolveViaHelius(chunk);
			resolved.push(...part);
		}
		if (resolved.length > 0) {
			await persist(resolved, 'helius-das');
			for (const r of resolved) cached.set(r.mint, r);
		}
		missing = missing.filter((m) => !cached.has(m));
	}

	// Anything Helius could not name (no key, exhausted quota, or a mint DAS has
	// no metadata for) gets the keyless Jupiter rung before we give up on it.
	if (missing.length > 0) {
		const viaJup = await resolveViaJupiter(missing);
		if (viaJup.length > 0) {
			await persist(viaJup, 'jupiter');
			for (const r of viaJup) cached.set(r.mint, r);
		}
	}

	// Fill any remaining gaps with bare placeholders so the caller gets a stable shape.
	for (const m of unique) {
		if (!cached.has(m)) cached.set(m, bareEntry(m));
	}
	return cached;
}