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.

14.5 KB
Raw Blame
// Holder-distribution composition for the free Crypto Data API
// (/api/crypto/holders).
//
// An agent sizing a position needs one read: how many holders, what the top
// wallets control, and whether concentration is an exit risk. Two real paths,
// never a mock:
//   - Helius DAS `getTokenAccounts` when HELIUS_API_KEY exists — enumerates the
//     token's accounts page by page and aggregates by OWNER wallet, so a whale
//     split across several token accounts still reads as one holder. Full
//     enumeration (within the page cap) also yields the true holder count.
//   - Keyless Solana RPC otherwise — `getTokenLargestAccounts` (top 20 token
//     accounts) + `getMultipleAccounts` to resolve each account's owner +
//     the mint's supply for percentages. A coarse-but-real top-N; the total
//     holder count is unknowable keylessly and reported null, never guessed.
//
// Percentages are against on-chain supply from the same mint read the security
// endpoint uses (parseMintAccount, shared with api/v1/token/security.js).
// The `concentration` verdict is a documented threshold on top10Pct — see
// deriveConcentration; docs/crypto-api.md mirrors the exact numbers.

import { parseMintAccount } from '../v1/token/security.js';
import {
	solanaRpcEndpoints,
	makeRotatingFetch,
	isEndpointCooling,
	markEndpointCooldown,
} from './solana/connection.js';
import { withDeadline } from './rpc-degrade.js';

// Budget for ONE JSON-RPC read across the WHOLE failover chain, not per
// endpoint. makeRotatingFetch bounds each attempt itself (10s) and composes the
// caller's signal with AbortSignal.any, so a caller cap below that bound spends
// the entire budget on the first endpoint and every rotation after it aborts
// instantly: at 8s a read that hit one slow lane logged "all 9 endpoints failed
// this request" and answered 503, while a retry seconds later succeeded. Sized
// to cover a couple of real attempts, matching the wallet-activity lane.
const RPC_TIMEOUT_MS = 25_000;

// Per-call wall clock for the keyless fan-out (largest accounts, then owner
// resolution). Each read is bounded by RPC_TIMEOUT_MS, but two of them back to
// back after a slow Helius walk could still outlive the gateway; this cap makes
// the caller's upstream_down (and its last-good tier) fire while the response
// can still be delivered.
const KEYLESS_CALL_DEADLINE_MS = 20_000;

// Helius DAS getTokenAccounts pages at up to 1000 accounts; cap the walk so a
// mega-token (millions of accounts) can't burn the invocation. Within the cap
// the holder count is exact; beyond it we report null + a note, never a guess.
const HELIUS_PAGE_LIMIT = 1000;
const HELIUS_MAX_PAGES = 5;

// Documented concentration thresholds on top10Pct (aligned with the security
// reader's top10 > 80 flag so the two surfaces can't contradict each other).
export const CONCENTRATION_HIGH_PCT = 80;
export const CONCENTRATION_MEDIUM_PCT = 50;

export const MAX_LIMIT = 50;
export const DEFAULT_LIMIT = 10;

const num = (v) => {
	const n = typeof v === 'string' ? Number(v) : v;
	return Number.isFinite(n) ? n : null;
};

/** Percentage of raw base-unit `part` against raw `total`, 2 decimals. */
export function pctOfSupply(part, total) {
	const t = num(total);
	const p = num(part);
	if (!t || t <= 0 || p == null) return null;
	return Math.round((p / t) * 10000) / 100;
}

/**
 * Aggregate token accounts by owner into a ranked holder list.
 * @param {Array<{ owner?: string|null, address?: string, amount: string|number }>} accounts
 * @param {string|number|null} supplyRaw
 * @param {number} limit
 */
export function rankHolders(accounts, supplyRaw, limit) {
	if (!Array.isArray(accounts) || !accounts.length) return [];
	const byOwner = new Map();
	for (const a of accounts) {
		const amt = num(a?.amount);
		if (amt == null || amt <= 0) continue;
		// Owner unresolved (RPC couldn't parse the account) → keep the token
		// account address as the key so the balance still counts, honestly labeled.
		const key = a.owner || a.address || 'unknown';
		byOwner.set(key, (byOwner.get(key) || 0) + amt);
	}
	return [...byOwner.entries()]
		.sort((x, y) => y[1] - x[1])
		.slice(0, limit)
		.map(([owner, amount]) => ({
			owner,
			amount,
			pct: pctOfSupply(amount, supplyRaw),
		}));
}

/** Cumulative % of supply held by the top 10 aggregated holders. */
export function top10PctOf(ranked) {
	if (!Array.isArray(ranked) || !ranked.length) return null;
	let sum = 0;
	let any = false;
	for (const h of ranked.slice(0, 10)) {
		if (h.pct == null) continue;
		sum += h.pct;
		any = true;
	}
	return any ? Math.round(sum * 100) / 100 : null;
}

/**
 * The documented threshold rule (mirror any change into docs/crypto-api.md):
 *   high    — top10Pct > 80
 *   medium  — top10Pct > 50
 *   low     — top10Pct ≤ 50
 *   unknown — top10Pct unresolved
 */
export function deriveConcentration(top10Pct) {
	if (top10Pct == null) return 'unknown';
	if (top10Pct > CONCENTRATION_HIGH_PCT) return 'high';
	if (top10Pct > CONCENTRATION_MEDIUM_PCT) return 'medium';
	return 'low';
}

async function rpcCall(rpcFetch, method, params) {
	const resp = await rpcFetch(null, {
		method: 'POST',
		headers: { 'content-type': 'application/json' },
		body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
		signal: AbortSignal.timeout(RPC_TIMEOUT_MS),
	});
	return resp.json();
}

/**
 * Walk Helius DAS getTokenAccounts for a mint, aggregating by owner. Returns
 * null when no key is configured (caller falls back to keyless RPC).
 * `complete` is true iff every account was enumerated within the page cap —
 * only then is a holder count honest.
 */
export async function heliusHolderWalk(
	mint,
	{ fetchImpl = fetch, isCooling = isEndpointCooling, markCooldown = markEndpointCooldown } = {},
) {
	const key = process.env.HELIUS_API_KEY;
	if (!key) return null;
	// Same URL the canonical RPC chain parks, so the fleet-wide quota verdict
	// applies here too. Walking into a plan that is already out spent a doomed
	// round trip per read and kept the cap pinned (2,000+ "max usage reached"
	// replies in 6h on 2026-10-10).
	const url = `https://mainnet.helius-rpc.com/?api-key=${key}`;
	if (isCooling(url)) return null;
	const accounts = [];
	let complete = false;
	for (let page = 1; page <= HELIUS_MAX_PAGES; page++) {
		let batch;
		try {
			batch = await heliusPage(url, mint, page, fetchImpl);
		} catch (err) {
			if (err.quota) markCooldown(url, 429, err.message);
			// A page that fails mid-walk does not invalidate the pages already in
			// hand: 1000 accounts is far more than any top-N needs, and discarding
			// them dropped the read onto the keyless lane, whose
			// getTokenLargestAccounts most public RPCs refuse. Keep what we have and
			// mark the walk incomplete so the holder COUNT is still withheld.
			if (!accounts.length) throw err;
			console.log(`[crypto-holders] helius walk stopped at page ${page}: ${err.message}`);
			return { accounts, complete: false };
		}
		accounts.push(...batch.map((a) => ({ owner: a.owner || null, address: a.address, amount: a.amount })));
		if (batch.length < HELIUS_PAGE_LIMIT) {
			complete = true;
			break;
		}
	}
	return { accounts, complete };
}

// Helius words an exhausted plan as "max usage reached" (HTTP 429, or 200 with a
// plain-text body) or JSON-RPC -32429.
const HELIUS_QUOTA_RE = /max usage reached|-32429/i;

// One page of the walk. Helius answers an exhausted plan with HTTP 200 and the
// plain-text body "max usage reached", so parsing the body as JSON unconditionally
// surfaced a bare SyntaxError with no hint that the key was the problem. Read the
// text first and name what came back.
async function heliusPage(url, mint, page, fetchImpl) {
	const r = await fetchImpl(url, {
		method: 'POST',
		headers: { 'content-type': 'application/json' },
		body: JSON.stringify({
			jsonrpc: '2.0',
			id: 'holders',
			method: 'getTokenAccounts',
			params: { mint, page, limit: HELIUS_PAGE_LIMIT },
		}),
		signal: AbortSignal.timeout(RPC_TIMEOUT_MS),
	});
	const text = await r.text();
	const quota = r.status === 429 || HELIUS_QUOTA_RE.test(text);
	if (!r.ok) throw Object.assign(new Error(`helius getTokenAccounts ${r.status}: ${text.slice(0, 80)}`), { quota });
	let json;
	try {
		json = JSON.parse(text);
	} catch {
		throw Object.assign(new Error(`helius getTokenAccounts: non-JSON response "${text.slice(0, 60)}"`), { quota });
	}
	if (json?.error) {
		const detail = JSON.stringify(json.error);
		throw Object.assign(new Error(`helius getTokenAccounts: ${detail.slice(0, 120)}`), { quota: HELIUS_QUOTA_RE.test(detail) });
	}
	const batch = json?.result?.token_accounts;
	if (!Array.isArray(batch)) throw new Error('helius getTokenAccounts: malformed response');
	return batch;
}

// Default network dependency bundle, injectable for tests. `heliusAllowed` is
// the caller's budget gate for the keyed walk: each read costs up to
// HELIUS_MAX_PAGES DAS calls against a paid plan shared with balances, the
// sniper and the indexers, so a free keyless endpoint must not let one client
// spend it. A denied budget is not an error, the read takes the keyless lane.
export function realHolderDeps({ heliusAllowed = async () => true } = {}) {
	const rpcFetch = makeRotatingFetch(solanaRpcEndpoints('mainnet'));
	return {
		fetchMintAccount: (address) =>
			rpcCall(rpcFetch, 'getAccountInfo', [address, { encoding: 'jsonParsed', commitment: 'confirmed' }]),
		fetchLargestAccounts: (address) =>
			rpcCall(rpcFetch, 'getTokenLargestAccounts', [address, { commitment: 'confirmed' }]),
		fetchAccountOwners: async (tokenAccounts) => {
			const json = await rpcCall(rpcFetch, 'getMultipleAccounts', [tokenAccounts, { encoding: 'jsonParsed', commitment: 'confirmed' }]);
			const values = json?.result?.value;
			if (!Array.isArray(values)) return new Map();
			const owners = new Map();
			values.forEach((v, i) => {
				const owner = v?.data?.parsed?.info?.owner;
				if (owner) owners.set(tokenAccounts[i], owner);
			});
			return owners;
		},
		fetchHelius: async (address) => ((await heliusAllowed()) ? heliusHolderWalk(address) : null),
	};
}

/**
 * Compose the holder-distribution report for one mint.
 *
 * @param {{ address: string, limit?: number }} input
 * @param {ReturnType<typeof realHolderDeps>} [deps]
 * @returns {Promise<
 *   | { status: 'ok', holderCount: number|null, top: Array<{owner,amount,pct}>,
 *       top10Pct: number|null, concentration: string, sources: string[], note?: string }
 *   | { status: 'not_found' }
 *   | { status: 'upstream_down' }
 * >}
 */
export async function composeTokenHolders({ address, limit = DEFAULT_LIMIT }, deps = realHolderDeps()) {
	const capped = Math.min(MAX_LIMIT, Math.max(1, Math.floor(limit) || DEFAULT_LIMIT));

	// The mint read anchors everything: supply for percentages, and existence —
	// a mint that isn't on chain is a not-found regardless of holder sources.
	let mint = null;
	let mintAnswered = false;
	try {
		const acct = await deps.fetchMintAccount(address);
		mintAnswered = true;
		mint = parseMintAccount(acct?.result);
	} catch { /* RPC down — holder paths below may still answer */ }

	if (mintAnswered && !mint) return { status: 'not_found' };

	const supply = mint?.supply ?? null;
	const sources = [];
	let note;

	// Preferred: Helius owner-aggregated walk (exact within the page cap).
	try {
		const helius = await deps.fetchHelius(address);
		if (helius) {
			const owners = new Map();
			for (const a of helius.accounts) {
				if (num(a.amount) > 0) owners.set(a.owner || a.address, true);
			}
			const top = rankHolders(helius.accounts, supply, capped);
			if (top.length || helius.complete) {
				sources.push('helius-das');
				if (mint) sources.push('solana-rpc');
				const top10Pct = top10PctOf(rankHolders(helius.accounts, supply, 10));
				if (!helius.complete) {
					note = `holder count omitted: more than ${HELIUS_MAX_PAGES * HELIUS_PAGE_LIMIT} token accounts — top holders are computed from the first ${HELIUS_MAX_PAGES * HELIUS_PAGE_LIMIT}.`;
				}
				return {
					status: 'ok',
					holderCount: helius.complete ? owners.size : null,
					top,
					top10Pct,
					concentration: deriveConcentration(top10Pct),
					sources,
					...(note ? { note } : {}),
				};
			}
		}
	} catch (err) {
		// Named, not swallowed: an exhausted Helius plan silently demoted every
		// holder read to the keyless lane, which then 503'd roughly one call in
		// three with nothing in the logs pointing at the cause.
		console.log(`[crypto-holders] helius path unavailable, falling back to keyless RPC: ${err.message}`);
	}

	// Keyless: top-20 largest token accounts + owner resolution.
	// `largestAnswered` requires a REAL array answer. A JSON-RPC error envelope
	// (e.g. the public chain throttling getTokenLargestAccounts with "Too many
	// requests") is NOT an answer — counting it as one turned a throttled read
	// into a false "brand-new token, no holders" on live mints.
	let largest = null;
	let largestAnswered = false;
	try {
		const json = await withDeadline(deps.fetchLargestAccounts(address), KEYLESS_CALL_DEADLINE_MS, 'getTokenLargestAccounts');
		if (Array.isArray(json?.result?.value)) {
			largestAnswered = true;
			largest = json.result.value;
		}
	} catch { /* RPC down for this call */ }

	if (largest?.length) {
		let owners = new Map();
		try {
			owners = await withDeadline(deps.fetchAccountOwners(largest.map((a) => a.address)), KEYLESS_CALL_DEADLINE_MS, 'getMultipleAccounts');
		} catch { /* owner resolution is enrichment — top-N stands on account addresses */ }
		const accounts = largest.map((a) => ({
			address: a.address,
			owner: owners.get(a.address) || null,
			amount: a.amount,
		}));
		const top = rankHolders(accounts, supply, capped);
		const top10Pct = top10PctOf(rankHolders(accounts, supply, 10));
		sources.push('solana-rpc');
		return {
			status: 'ok',
			holderCount: null,
			top,
			top10Pct,
			concentration: deriveConcentration(top10Pct),
			sources,
			note: 'keyless path: top holders from the chain\'s 20 largest token accounts; total holder count is not derivable without an indexer key.',
		};
	}

	// Nothing produced holders. Mint answered (token exists) with an empty holder
	// read → a brand-new token with no accounts yet is a valid empty, not an error.
	if (mint && largestAnswered) {
		return {
			status: 'ok',
			holderCount: null,
			top: [],
			top10Pct: null,
			concentration: 'unknown',
			sources: ['solana-rpc'],
			note: 'no token accounts found yet — brand-new or unfunded mint.',
		};
	}

	// Only reachable when the largest-accounts read failed at transport level
	// (a non-mint address already returned not_found above). The token may well
	// exist — report retryable, never a false not-found.
	return { status: 'upstream_down' };
}