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.

29.4 KB
Raw Blame
// Live on-chain balance + USD-price helpers, shared by /api/wallet/balances and
// /api/portfolio.
//
// Optimization strategy (2026-05-25):
//   - Solana: single Helius `getAssetsByOwner` (DAS) call returns native SOL +
//     all fungible token balances *with metadata*. Eliminates the previous
//     N+1 (getTokenAccountsByOwner + N×getAsset) burn (~200 Helius credits
//     per portfolio → ~10).
//   - Falls back to public RPC + token_metadata cache when Helius is missing
//     or rate-limited. DAS isn't available on public RPC, so metadata then
//     comes from our Postgres `token_metadata` cache.
//   - Jupiter Lite Price API replaces CoinGecko for Solana token prices —
//     faster, no rate limits, knows pump.fun bondings.
//   - Cache layer uses Upstash Redis if configured (shared across function
//     instances), in-memory otherwise.

import { cacheGet, cacheSet, cacheDel } from './cache.js';
import { getMetadataForMints } from './token-metadata.js';
import { solPriceUsd } from './sol-price.js';
import { fetchTokenPriceUsd } from './market/token-market.js';
import { fetchCoinPriceUsdOrNull } from './market-fallbacks.js';
import { solanaRpcEndpoints, makeRotatingFetch, markEndpointCooldown } from './solana/connection.js';

const BALANCES_TTL_S = 60;
// Last-known-good snapshot lifetime. A long horizon so a wallet that briefly
// can't be read (Helius quota out + flaky public RPC) is served its real prior
// balances — flagged stale — instead of erroring out. Refreshed on every
// successful read.
const BALANCES_LKG_TTL_S = 24 * 60 * 60;

const PUMP_FRONTEND_BASE = process.env.PUMP_FRONTEND_BASE || 'https://frontend-api-v3.pump.fun';
function heliusRpc() {
	const key = process.env.HELIUS_API_KEY;
	return key ? `https://mainnet.helius-rpc.com/?api-key=${key}` : null;
}

// Throttled warnings. The balance helpers are called on every portfolio /
// holder-gate / networth read; an upstream that is sustainedly degraded (a
// Helius month-quota exhaustion, a flaky public RPC) would otherwise emit one
// identical warning per request — exactly the production flood seen in the logs
// (70+ "[balances] helius failed" / "DAS path failed" lines for a single
// exhausted-quota window). Collapse repeats of the same category to one line per
// WARN_COOLDOWN_MS so a real outage stays visible without drowning the logs.
const _warnedAt = new Map();
const WARN_COOLDOWN_MS = 60_000;
function warnThrottled(category, msg) {
	const now = Date.now();
	if (now - (_warnedAt.get(category) || 0) < WARN_COOLDOWN_MS) return;
	_warnedAt.set(category, now);
	console.warn(msg);
}

// Helius quota circuit breaker. When Helius reports an exhausted plan quota
// ("max usage reached", JSON-RPC -32429, or a bare 429), every subsequent
// request would otherwise still hit Helius first, eat a doomed round-trip, warn,
// and only then fall back to the public RPC. Helius quota only clears on the
// provider's billing/usage cycle, so once we see it we skip Helius outright for a
// cooldown window and go straight to the public-RPC / DAS-fallback path. This is
// the balance-layer analogue of the market-data source breaker
// (api/_lib/market/token-market.js). Per-instance + best-effort: a cold lambda
// re-discovers the exhausted quota once, then skips for the window.
const HELIUS_QUOTA_COOLDOWN_MS = 10 * 60_000;
let heliusCooldownUntil = 0; // epoch ms; 0 = available
let heliusQuotaTrips = 0; // cumulative since cold start — trend for /healthz

function heliusAvailable(now = Date.now()) {
	return heliusCooldownUntil <= now;
}

/**
 * Point-in-time health of the Helius balance-RPC breaker, for /healthz and the
 * status page. Pure read of module state. `degraded` means we're currently in a
 * quota cooldown and serving balances from the public RPC — functional, but the
 * premium path is throttled. No key configured is reported as `configured:false`,
 * not a degradation (the public-RPC path is the intended fallback).
 * @returns {{ configured: boolean, available: boolean, degraded: boolean,
 *   cooldownRemainingMs: number, quotaTripsSinceStart: number }}
 */
export function heliusHealth() {
	const now = Date.now();
	const configured = !!heliusRpc();
	const available = heliusAvailable(now);
	return {
		configured,
		available,
		degraded: configured && !available,
		cooldownRemainingMs: available ? 0 : heliusCooldownUntil - now,
		quotaTripsSinceStart: heliusQuotaTrips,
	};
}

// True when an upstream error is a quota/rate-limit signal (vs. a transient blip
// worth retrying). Covers Helius's -32429 "max usage reached", a bare HTTP 429,
// and generic "quota/usage limit exceeded" bodies.
function isQuotaError(err) {
	const msg = String(err?.message || '');
	return /max usage reached|-32429|\b429\b|usage limit exceeded|quota exceeded|rate ?limit/i.test(msg);
}

function tripHeliusCooldown(err, category) {
	heliusCooldownUntil = Date.now() + HELIUS_QUOTA_COOLDOWN_MS;
	heliusQuotaTrips++;
	// Park Helius in the process-wide endpoint cooldown too, so the raw-RPC
	// fallback chain below (which includes the same Helius URL) skips it instead
	// of re-discovering the exhausted quota one doomed rotation at a time. A true
	// quota signal in the message picks the long (hours) window.
	const helius = heliusRpc();
	if (helius) markEndpointCooldown(helius, 429, String(err?.message || ''));
	warnThrottled(
		category,
		`[balances] helius quota/rate-limited — skipping it for ${Math.round(HELIUS_QUOTA_COOLDOWN_MS / 60_000)}min, using public RPC: ${err?.message}`,
	);
}

/** Test seam: reset the Helius breaker + warn throttle between cases. */
export function __resetBalancesBreaker() {
	heliusCooldownUntil = 0;
	heliusQuotaTrips = 0;
	_warnedAt.clear();
	// Rebuild the rotating pool too, so a test that mutates the RPC env vars gets
	// a chain reflecting them rather than the first build's snapshot.
	_rotatingRpc = null;
}

async function fetchJson(url, opts = {}) {
	// A sick upstream (Helius/public RPC, Jupiter, CoinGecko, pump.fun) must never
	// hang the holder-gate / pricing path indefinitely — bound every request to 6s
	// unless the caller already supplied its own AbortSignal. A timeout rejects, so
	// solRpc()'s Helius→public-RPC failover and the price helpers' try/catch each
	// degrade rather than stall the whole portfolio read.
	const signal = opts.signal ?? AbortSignal.timeout(6000);
	const r = await fetch(url, { ...opts, signal });
	if (!r.ok) {
		const text = await r.text().catch(() => r.status.toString());
		throw Object.assign(new Error(`upstream ${r.status}: ${text}`), { status: 502 });
	}
	return r.json();
}

// Raw JSON-RPC over the CANONICAL platform-wide failover chain (solanaRpcEndpoints:
// explicit SOLANA_RPC_URL, QuickNode, Helius, Alchemy, operator fallbacks,
// keyless public lanes, paid last-resort), sharing the process-wide endpoint
// cooldown map with every other Solana caller. The previous private pool here
// (default public mainnet-beta + SOLANA_RPC_FALLBACKS) went dark whenever Helius
// was quota-exhausted: publicnode hard-blocks getTokenAccountsByOwner-by-programId
// (403) and the public mainnet-beta endpoint 429s per-method, so every wallet
// silently read as holding $0 and the whole holder-tier lever collapsed to Member.
// makeRotatingFetch also classifies 200-status JSON-RPC error bodies (quota
// -32429, paid-tier gates like Tatum's -16401) as failover signals, so a provider
// answering 200 + error can never surface as an empty-but-successful balance.
let _rotatingRpc = null;
function rotatingRpc() {
	if (!_rotatingRpc) _rotatingRpc = makeRotatingFetch(solanaRpcEndpoints('mainnet'));
	return _rotatingRpc;
}

async function solRpc(body) {
	// One bound for the whole rotation so a deep chain of slow lanes can never
	// stall the holder-gate / portfolio path indefinitely. Individual attempts are
	// already capped inside the rotating fetch, so this only backstops the sum.
	const r = await rotatingRpc()(null, {
		method: 'POST',
		headers: { 'content-type': 'application/json' },
		body: JSON.stringify(body),
		signal: AbortSignal.timeout(30_000),
	});
	return r.json();
}

// -- Solana price helpers --

async function jupiterPrices(mints) {
	if (mints.length === 0) return {};
	const out = {};
	// Jupiter caps each request at ~100 ids
	for (let i = 0; i < mints.length; i += 100) {
		const chunk = mints.slice(i, i + 100).join(',');
		try {
			const data = await fetchJson(`https://lite-api.jup.ag/price/v3?ids=${chunk}`);
			if (data && typeof data === 'object') Object.assign(out, data);
		} catch (err) {
			console.warn('[balances] jupiter price chunk failed:', err?.message);
		}
	}
	return out;
}

const SOL_MINT = 'So11111111111111111111111111111111111111112';

// Native SOL/USD spot. Delegates to the canonical 7-source failover in
// api/_lib/sol-price.js (Jupiter/CoinGecko + Kraken/Coinbase/Bitfinex/DefiLlama/
// DIA), 60s-cached. Returns 0 when every source is exhausted — same "unpriced"
// contract the token-price path relies on.
async function solNativePrice() {
	return solPriceUsd();
}

/**
 * Pick a token's USD price, preferring a positive on-chain price (Helius
 * `price_info`) and otherwise falling back to Jupiter.
 *
 * A Helius price of exactly 0 means "Helius couldn't price this", NOT "free" —
 * so it must never suppress the Jupiter fallback. The previous `helius ?? jup`
 * did exactly that: `0 ?? jup` is `0` (nullish coalescing keeps the 0), which
 * zeroed out every coin Helius returned a 0 for (common for low-liquidity
 * pump.fun coins that Jupiter prices fine). That silently mis-valued holdings
 * to $0 — and broke the /play holder gate, which reads these USD values.
 */
export function pickTokenPrice(heliusPrice, jupiterPrice) {
	const helius = Number(heliusPrice) || 0;
	if (helius > 0) return helius;
	return Number(jupiterPrice) || 0;
}

/**
 * USD price for one pump.fun coin straight from its bonding curve / market cap.
 * price = usd_market_cap / circulating supply. Covers coins Jupiter can't route
 * yet (pre-graduation, very fresh) — exactly the long tail the holder gate must
 * price correctly. Returns 0 when pump.fun has no data for the mint (not a pump
 * coin, or no price yet).
 */
async function pumpFunMintUsd(mint) {
	const c = await fetchJson(new URL(`/coins/${mint}`, PUMP_FRONTEND_BASE).toString(), {
		headers: { accept: 'application/json' },
	});
	const mcap = Number(c?.usd_market_cap) || 0;
	const decimals = Number(c?.base_decimals ?? 6);
	const supply = Number(c?.total_supply_str || c?.total_supply) || 0;
	if (mcap > 0 && supply > 0) {
		const circulating = supply / Math.pow(10, decimals);
		if (circulating > 0) return mcap / circulating;
	}
	return 0;
}

/**
 * Authoritative USD price for a single Solana mint, independent of any wallet.
 * Jupiter Lite first (routable tokens, incl. graduated pump.fun coins), then the
 * pump.fun bonding curve (pre-graduation coins Jupiter doesn't price yet).
 * Returns 0 only when neither source can price the mint.
 */
export async function solanaMintUsdPrice(mint) {
	try {
		const data = await fetchJson(`https://lite-api.jup.ag/price/v3?ids=${mint}`);
		const p = Number(data?.[mint]?.usdPrice ?? data?.[mint]?.price) || 0;
		if (p > 0) return p;
	} catch (err) {
		console.warn('[balances] jupiter single-mint price failed:', err?.message);
	}
	// The shared market chain (Birdeye, tokens.xyz, DexScreener, GeckoTerminal,
	// each with its own stale tier) sits between Jupiter and the pump.fun curve
	// read below. Without it a Jupiter outage dropped straight to a curve price
	// that only exists for pump mints, so every other token priced at zero.
	try {
		const p = Number(await fetchTokenPriceUsd(mint)) || 0;
		if (p > 0) return p;
	} catch (err) {
		console.warn('[balances] market-chain single-mint price failed:', err?.message);
	}
	try {
		const p = await pumpFunMintUsd(mint);
		if (p > 0) return p;
	} catch (err) {
		console.warn('[balances] pump.fun price fallback failed:', err?.message);
	}
	return 0;
}

// -- Solana balance path: Helius DAS getAssetsByOwner --

async function getSolanaBalancesViaDas(address) {
	const helius = heliusRpc();
	if (!helius) return null; // signal caller to take fallback path
	// Quota exhausted recently — don't even attempt DAS; take the public-RPC
	// fallback straight away. DAS is Helius-only, so a doomed call here just burns
	// latency and re-warns.
	if (!heliusAvailable()) return null;

	let allItems = [];
	let nativeLamports = 0;
	let page = 1;
	// Helius paginates at 1000/page; loop until empty.
	while (page < 6) {
		const resp = await fetchJson(helius, {
			method: 'POST',
			headers: { 'content-type': 'application/json' },
			body: JSON.stringify({
				jsonrpc: '2.0',
				id: 'getAssetsByOwner',
				method: 'getAssetsByOwner',
				params: {
					ownerAddress: address,
					page,
					limit: 1000,
					displayOptions: { showFungible: true, showNativeBalance: true },
				},
			}),
		});
		// A 200-status JSON-RPC error envelope (how some gateways answer quota
		// exhaustion) must throw, not read as "no assets", so the caller trips the
		// breaker and takes the fallback chain instead of caching an empty portfolio.
		if (resp?.error) {
			throw Object.assign(
				new Error(`helius DAS error ${resp.error.code ?? ''}: ${resp.error.message ?? 'unknown'}`),
				{ status: 502 },
			);
		}
		const result = resp?.result;
		if (!result) break;
		if (page === 1 && result.nativeBalance) {
			nativeLamports = Number(result.nativeBalance.lamports || 0);
		}
		const items = Array.isArray(result.items) ? result.items : [];
		allItems = allItems.concat(items);
		if (items.length < 1000) break;
		page += 1;
	}

	const fungible = allItems
		.filter((a) => a?.interface === 'FungibleToken' || a?.interface === 'FungibleAsset' || a?.token_info)
		.map((a) => {
			const ti = a.token_info || {};
			const decimals = ti.decimals ?? 0;
			const rawBalance = Number(ti.balance || 0);
			if (!rawBalance) return null;
			const amount = rawBalance / Math.pow(10, decimals);
			const md = a?.content?.metadata || {};
			// No mint-slice placeholder: an unnamed mint reports null so callers
			// (and /api/crypto/wallet consumers) can tell "unknown" from a real ticker.
			const symbol = ti.symbol || md.symbol || null;
			const name = md.name || symbol;
			const logo = a?.content?.links?.image || a?.content?.files?.[0]?.uri || null;
			const priceFromHelius = ti.price_info?.price_per_token ?? null;
			return { mint: a.id, decimals, amount, symbol, name, logo, priceFromHelius };
		})
		.filter(Boolean)
		.filter((t) => t.amount > 0);

	// DAS knows most mints but not all. Anything it returned unnamed goes through
	// the shared resolver, whose keyless Jupiter rung names it, so the DAS path
	// never reports a holding the fallback path could have identified.
	const unnamed = fungible.filter((t) => !t.symbol).map((t) => t.mint);
	if (unnamed.length > 0) {
		const filled = await getMetadataForMints(unnamed);
		for (const t of fungible) {
			const md = filled.get(t.mint);
			if (!md) continue;
			t.symbol = t.symbol || md.symbol || null;
			t.name = t.name || md.name || md.symbol || null;
			t.logo = t.logo || md.logo || null;
		}
	}

	// Persist metadata for everything we just resolved so other callers
	// (which may not use DAS) can hit cache instead of re-fetching. Rows with no
	// symbol, name, or logo are skipped: caching "unknown" would shadow the
	// Jupiter rung on every later read.
	const metaPayload = fungible
		.filter((t) => t.symbol || t.name || t.logo)
		.map((t) => ({
			mint: t.mint,
			symbol: t.symbol,
			name: t.name,
			logo: t.logo,
			decimals: t.decimals,
		}));
	if (metaPayload.length > 0) {
		// Direct write (cheaper than going through getMetadataForMints):
		try {
			const { sql, sqlValues } = await import('./db.js');
			const now = new Date();
			const rows = metaPayload.map((m) => [
				m.mint,
				'solana',
				m.symbol,
				m.name,
				m.logo,
				m.decimals,
				'helius-das',
				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('[balances] token_metadata persist failed:', err?.message);
		}
	}

	// Prices: trust Helius price_info first, fall back to Jupiter for any gaps.
	const missingPrice = fungible.filter((t) => !t.priceFromHelius).map((t) => t.mint);
	const jupPrices = missingPrice.length > 0 ? await jupiterPrices(missingPrice) : {};
	const solUsd = await solNativePrice();

	const tokens = fungible
		.map((t) => {
			const price = pickTokenPrice(
				t.priceFromHelius,
				jupPrices?.[t.mint]?.usdPrice ?? jupPrices?.[t.mint]?.price,
			);
			return {
				symbol: t.symbol,
				name: t.name,
				mint: t.mint,
				decimals: t.decimals,
				amount: t.amount,
				price,
				change24h: null,
				usd: t.amount * price,
				logo: t.logo,
			};
		})
		.sort((a, b) => (b.usd || 0) - (a.usd || 0));

	return {
		chain: 'solana',
		address,
		native: {
			symbol: 'SOL',
			name: 'Solana',
			amount: nativeLamports / 1e9,
			price: solUsd,
			change24h: null,
			usd: (nativeLamports / 1e9) * solUsd,
		},
		tokens,
	};
}

// -- Solana balance fallback: plain RPC + DB metadata cache --

// Both SPL token programs. pump.fun mints (including $THREE) are Token-2022,
// so a fallback that queried only the classic program silently dropped them,
// while Helius DAS covers both. That meant every wallet's $THREE "disappeared"
// exactly when Helius was quota-exhausted and reads degraded to raw RPC, which
// zeroed the whole holder-tier lever (the "site shows You hold $0" reports).
const SPL_TOKEN_PROGRAM = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA';
const SPL_TOKEN_2022_PROGRAM = 'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb';

async function getSolanaBalancesFallback(address) {
	const solResp = await solRpc({ jsonrpc: '2.0', id: 1, method: 'getBalance', params: [address] });
	const lamports = solResp.result?.value ?? 0;
	const solAmount = lamports / 1e9;

	const [legacyResp, t22Resp] = await Promise.all(
		[SPL_TOKEN_PROGRAM, SPL_TOKEN_2022_PROGRAM].map((programId, i) =>
			solRpc({
				jsonrpc: '2.0',
				id: 2 + i,
				method: 'getTokenAccountsByOwner',
				params: [address, { programId }, { encoding: 'jsonParsed' }],
			}),
		),
	);

	const tokenAccounts = [...(legacyResp.result?.value ?? []), ...(t22Resp.result?.value ?? [])];
	const fungible = tokenAccounts
		.map((a) => {
			const info = a.account?.data?.parsed?.info;
			if (!info) return null;
			const { mint, tokenAmount } = info;
			if (!tokenAmount || !tokenAmount.uiAmount || tokenAmount.uiAmount === 0) return null;
			return { mint, amount: tokenAmount.uiAmount, decimals: tokenAmount.decimals };
		})
		.filter(Boolean);

	const mints = fungible.map((t) => t.mint);
	const [metadata, jupPrices, solUsd] = await Promise.all([
		getMetadataForMints(mints),
		jupiterPrices(mints),
		solNativePrice(),
	]);

	const tokens = fungible
		.map((t) => {
			const md = metadata.get(t.mint) || {};
			const priceInfo = jupPrices?.[t.mint] || {};
			const price = Number(priceInfo.usdPrice ?? priceInfo.price ?? 0);
			return {
				symbol: md.symbol || null,
				name: md.name || md.symbol || null,
				mint: t.mint,
				decimals: t.decimals,
				amount: t.amount,
				price,
				change24h: null,
				usd: t.amount * price,
				logo: md.logo || null,
			};
		})
		.sort((a, b) => (b.usd || 0) - (a.usd || 0));

	return {
		chain: 'solana',
		address,
		native: {
			symbol: 'SOL',
			name: 'Solana',
			amount: solAmount,
			price: solUsd,
			change24h: null,
			usd: solAmount * solUsd,
		},
		tokens,
	};
}

async function getSolanaBalances(address) {
	try {
		const viaDas = await getSolanaBalancesViaDas(address);
		if (viaDas) return viaDas;
	} catch (err) {
		// A quota error trips the breaker so subsequent reads skip Helius outright
		// rather than re-discovering the exhausted quota one doomed call at a time.
		if (isQuotaError(err)) tripHeliusCooldown(err, 'das:quota');
		else warnThrottled('das:fail', `[balances] DAS path failed, using fallback: ${err?.message}`);
	}
	return getSolanaBalancesFallback(address);
}

// -- EVM: Alchemy first, then a keyless rung, mirroring the Solana lanes above --
//
// Alchemy is the fast path (one proprietary `alchemy_getTokenBalances` call
// covers discovery), but it is a single paid dependency: when its monthly
// capacity is exhausted every EVM read used to 503, and /portfolio answered a
// pasted 0x address with "data source unavailable" for the rest of the billing
// month. Solana has had a keyless lane since day one; this gives EVM the same
// floor. See getEvmBalancesKeyless below for the free rung.

async function getEvmBalances(address) {
	const alchemyKey = process.env.ALCHEMY_API_KEY;
	if (alchemyKey) {
		try {
			return await getEvmBalancesAlchemy(address, alchemyKey);
		} catch (err) {
			warnThrottled('evm:alchemy', `[balances] Alchemy EVM path failed, using keyless rung: ${err?.message}`);
			return getEvmBalancesKeyless(address);
		}
	}
	try {
		return await getEvmBalancesKeyless(address);
	} catch (err) {
		// No key AND the free rung is down: name the var an operator can set,
		// which is what api/wallet/balances.js and api/crypto/* report.
		const e = new Error('not_configured: ALCHEMY_API_KEY');
		e.status = 503;
		e.code = 'not_configured';
		e.missing = 'ALCHEMY_API_KEY';
		e.cause = err;
		throw e;
	}
}

// Keyless EVM balance read. Native ETH comes off the canonical public RPC
// failover (api/_lib/evm/rpc.js, same list every other EVM caller uses); token
// discovery comes off Blockscout's public Ethereum instance, whose
// `/addresses/:a/tokens?type=ERC-20` page is already ordered by USD value and
// carries decimals, price and icon per row, so its first page (50 holdings)
// covers what a portfolio view renders. A wallet holding more than that is
// truncated by value, which buildOverview already reports as `truncated`.
const BLOCKSCOUT_ETH = 'https://eth.blockscout.com/api/v2';
const KEYLESS_RPC_TIMEOUT_MS = 6000;
// Blockscout walks an address's full token set to order it, which takes seconds
// on a wallet with thousands of positions. Bounded so a whale address degrades
// to a native-only read instead of hanging the portfolio request.
const BLOCKSCOUT_TIMEOUT_MS = 12_000;

async function keylessEthBalance(address) {
	const { evmRpcEndpoints } = await import('./evm/rpc.js');
	const body = JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'eth_getBalance', params: [address, 'latest'] });
	let lastErr = null;
	for (const url of evmRpcEndpoints(1)) {
		try {
			const resp = await fetchJson(url, {
				method: 'POST',
				headers: { 'content-type': 'application/json' },
				body,
				signal: AbortSignal.timeout(KEYLESS_RPC_TIMEOUT_MS),
			});
			if (resp?.error) throw new Error(resp.error.message || 'rpc error');
			return Number(BigInt(resp?.result ?? '0x0')) / 1e18;
		} catch (err) {
			lastErr = err;
		}
	}
	throw lastErr || new Error('no EVM RPC endpoint answered');
}

async function keylessErc20s(address) {
	const data = await fetchJson(
		`${BLOCKSCOUT_ETH}/addresses/${encodeURIComponent(address)}/tokens?type=ERC-20`,
		{ headers: { accept: 'application/json' }, signal: AbortSignal.timeout(BLOCKSCOUT_TIMEOUT_MS) },
	);
	const items = Array.isArray(data?.items) ? data.items : [];
	return items
		.map((it) => {
			const t = it?.token || {};
			const decimals = Number(t.decimals);
			const raw = String(it?.value ?? '0');
			if (!t.address_hash || !/^\d+$/.test(raw)) return null;
			const amount = Number(raw) / Math.pow(10, Number.isFinite(decimals) ? decimals : 18);
			if (!(amount > 0)) return null;
			const price = Number(t.exchange_rate);
			const usdPrice = Number.isFinite(price) && price > 0 ? price : 0;
			return {
				symbol: t.symbol || null,
				name: t.name || t.symbol || null,
				contract: t.address_hash,
				decimals: Number.isFinite(decimals) ? decimals : 18,
				amount,
				price: usdPrice,
				// Blockscout carries no 24h change; /api/crypto/portfolio reports the
				// resulting coverage rather than inventing one.
				change24h: null,
				usd: amount * usdPrice,
				logo: t.icon_url || null,
			};
		})
		.filter(Boolean)
		.sort((a, b) => (b.usd || 0) - (a.usd || 0));
}

async function getEvmBalancesKeyless(address) {
	const [ethAmount, tokens, ethUsdPrice] = await Promise.all([
		keylessEthBalance(address),
		keylessErc20s(address).catch((err) => {
			warnThrottled('evm:blockscout', `[balances] keyless ERC-20 discovery failed: ${err?.message}`);
			return [];
		}),
		fetchCoinPriceUsdOrNull('ethereum').catch(() => 0),
	]);
	const ethPrice = Number(ethUsdPrice) > 0 ? Number(ethUsdPrice) : 0;
	return {
		chain: 'evm',
		address,
		// Which rung answered, so a caller can name its real sources rather than
		// crediting Alchemy/CoinGecko for a read neither one served.
		keyless: true,
		native: {
			symbol: 'ETH',
			name: 'Ethereum',
			amount: ethAmount,
			price: ethPrice,
			// This lane carries no 24h move of its own; /api/crypto/portfolio
			// enriches it from DexScreener and states the coverage it achieved.
			change24h: null,
			usd: ethAmount * ethPrice,
		},
		tokens,
	};
}

async function getEvmBalancesAlchemy(address, alchemyKey) {
	const rpcUrl = `https://eth-mainnet.g.alchemy.com/v2/${alchemyKey}`;

	const ethBalResp = await fetchJson(rpcUrl, {
		method: 'POST',
		headers: { 'content-type': 'application/json' },
		body: JSON.stringify({
			jsonrpc: '2.0',
			id: 1,
			method: 'eth_getBalance',
			params: [address, 'latest'],
		}),
	});
	const ethWei = BigInt(ethBalResp.result ?? '0x0');
	const ethAmount = Number(ethWei) / 1e18;

	const tokenBalResp = await fetchJson(rpcUrl, {
		method: 'POST',
		headers: { 'content-type': 'application/json' },
		body: JSON.stringify({
			jsonrpc: '2.0',
			id: 2,
			method: 'alchemy_getTokenBalances',
			params: [address],
		}),
	});

	const rawTokens = (tokenBalResp.result?.tokenBalances ?? []).filter(
		(t) => t.tokenBalance && t.tokenBalance !== '0x0' && t.tokenBalance !== '0x',
	);

	const metadataResults = await Promise.allSettled(
		rawTokens.map((t) =>
			fetchJson(rpcUrl, {
				method: 'POST',
				headers: { 'content-type': 'application/json' },
				body: JSON.stringify({
					jsonrpc: '2.0',
					id: 'meta',
					method: 'alchemy_getTokenMetadata',
					params: [t.contractAddress],
				}),
			}),
		),
	);

	const cgTokenPrices = {};
	for (let i = 0; i < rawTokens.length; i += 80) {
		const chunk = rawTokens.slice(i, i + 80).map((t) => t.contractAddress).join(',');
		try {
			const part = await fetchJson(
				`https://api.coingecko.com/api/v3/simple/token_price/ethereum?contract_addresses=${chunk}&vs_currencies=usd&include_24hr_change=true`,
			);
			Object.assign(cgTokenPrices, part);
		} catch {
			// best-effort
		}
	}

	let ethUsdPrice = 0;
	let ethChange24h = 0;
	try {
		const cgEth = await fetchJson(
			'https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd&include_24hr_change=true',
		);
		ethUsdPrice = cgEth?.ethereum?.usd ?? 0;
		ethChange24h = cgEth?.ethereum?.usd_24h_change ?? 0;
	} catch {
		// best-effort
	}
	// CoinGecko's keyless tier is shared per egress IP and Cloud Run's is busy,
	// so this leg throttles on its own schedule. Falling back to the multi-source
	// price chain keeps the ETH leg of an EVM balance sheet valued instead of
	// rendering a wallet full of holdings with no USD against any of them. The
	// 24h change has no second source and stays absent rather than invented.
	if (!(ethUsdPrice > 0)) {
		const fallbackEth = await fetchCoinPriceUsdOrNull('ethereum');
		if (fallbackEth > 0) ethUsdPrice = fallbackEth;
	}

	const tokens = rawTokens.map((t, i) => {
		const meta = metadataResults[i].status === 'fulfilled' ? metadataResults[i].value?.result : null;
		const decimals = meta?.decimals ?? 18;
		const rawBal = BigInt(t.tokenBalance || '0x0');
		const amount = Number(rawBal) / Math.pow(10, decimals);
		const priceInfo = cgTokenPrices[t.contractAddress.toLowerCase()] || {};
		const price = priceInfo.usd ?? 0;
		const change24h = priceInfo.usd_24h_change ?? null;
		return {
			symbol: meta?.symbol || null,
			name: meta?.name || meta?.symbol || null,
			contract: t.contractAddress,
			decimals,
			amount,
			price,
			change24h,
			usd: amount * price,
			logo: meta?.logo || null,
		};
	});

	tokens.sort((a, b) => (b.usd || 0) - (a.usd || 0));
	return {
		chain: 'evm',
		address,
		native: {
			symbol: 'ETH',
			name: 'Ethereum',
			amount: ethAmount,
			price: ethUsdPrice,
			change24h: ethChange24h,
			usd: ethAmount * ethUsdPrice,
		},
		tokens,
	};
}

export async function getBalances({ chain, address }) {
	const key = `bal:${chain}:${address}`;
	const cached = await cacheGet(key);
	if (cached) return cached;
	const lkgKey = `bal:lkg:${chain}:${address}`;
	try {
		const value = chain === 'solana' ? await getSolanaBalances(address) : await getEvmBalances(address);
		await cacheSet(key, value, BALANCES_TTL_S);
		// Durable last-known-good so a transient upstream outage serves the wallet's
		// real prior balances (flagged stale) instead of a 502.
		await cacheSet(lkgKey, value, BALANCES_LKG_TTL_S);
		return value;
	} catch (err) {
		// Stale-on-error: every live RPC path failed. Serve the last-known-good
		// snapshot tagged `stale` so the caller holds the wallet's last real look.
		// Only a wallet we have never read successfully re-throws.
		const lkg = await cacheGet(lkgKey);
		if (lkg) return { ...lkg, stale: true };
		throw err;
	}
}

export async function invalidateBalances({ chain, address }) {
	await cacheDel(`bal:${chain}:${address}`);
}

export function walletUsdTotal(balances) {
	const nativeUsd = balances?.native?.usd ?? 0;
	const tokensUsd = (balances?.tokens ?? []).reduce((s, t) => s + (t.usd ?? 0), 0);
	return nativeUsd + tokensUsd;
}