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.0 KB
Raw Blame
import { describe, it, expect } from 'vitest';

import {
	pctOfSupply,
	rankHolders,
	top10PctOf,
	deriveConcentration,
	composeTokenHolders,
	heliusHolderWalk,
	realHolderDeps,
	CONCENTRATION_HIGH_PCT,
	CONCENTRATION_MEDIUM_PCT,
} from '../api/_lib/crypto-token-holders.js';

// Synthetic mints/wallets only — never a real third-party address (CLAUDE.md).
const THREE = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';
const W1 = 'THREEsynthetic1111111111111111111111111111A';
const W2 = 'THREEsynthetic2222222222222222222222222222B';
const W3 = 'THREEsynthetic3333333333333333333333333333C';

const SUPPLY = '1000000000'; // 1e9 raw units

const mintAccount = () => ({
	result: {
		value: {
			data: {
				parsed: {
					type: 'mint',
					info: { mintAuthority: null, freezeAuthority: null, supply: SUPPLY, decimals: 6 },
				},
			},
		},
	},
});

const deps = (over = {}) => ({
	fetchMintAccount: async () => mintAccount(),
	fetchLargestAccounts: async () => ({
		result: {
			value: [
				{ address: 'acctA', amount: '400000000' },
				{ address: 'acctB', amount: '300000000' },
				{ address: 'acctC', amount: '100000000' },
			],
		},
	}),
	fetchAccountOwners: async (addrs) =>
		new Map(addrs.map((a, i) => [a, [W1, W2, W3][i]].filter(Boolean)).filter((p) => p[1]).map((p) => p)),
	fetchHelius: async () => null, // keyless by default
	...over,
});

describe('pctOfSupply / top10PctOf math', () => {
	it('computes 2-decimal percentages against raw supply', () => {
		expect(pctOfSupply('400000000', SUPPLY)).toBe(40);
		expect(pctOfSupply('1234567', SUPPLY)).toBe(0.12);
		expect(pctOfSupply('1', 0)).toBeNull();
		expect(pctOfSupply(null, SUPPLY)).toBeNull();
	});

	it('top10PctOf sums the top ten and ignores null pcts', () => {
		const ranked = [
			{ owner: W1, amount: 400, pct: 40 },
			{ owner: W2, amount: 300, pct: 30 },
			{ owner: W3, amount: 100, pct: null },
		];
		expect(top10PctOf(ranked)).toBe(70);
		expect(top10PctOf([])).toBeNull();
		expect(top10PctOf([{ owner: W1, amount: 1, pct: null }])).toBeNull();
	});
});

describe('rankHolders — owner aggregation', () => {
	it('aggregates multiple token accounts of one owner into one holder', () => {
		const ranked = rankHolders(
			[
				{ owner: W1, amount: '100000000' },
				{ owner: W1, amount: '150000000' },
				{ owner: W2, amount: '200000000' },
			],
			SUPPLY,
			10,
		);
		expect(ranked).toHaveLength(2);
		expect(ranked[0]).toEqual({ owner: W1, amount: 250000000, pct: 25 });
		expect(ranked[1].owner).toBe(W2);
	});

	it('caps at limit, drops zero balances, keys unresolved owners by account address', () => {
		const ranked = rankHolders(
			[
				{ owner: null, address: 'acctX', amount: '50' },
				{ owner: W1, amount: '0' },
				{ owner: W2, amount: '100' },
			],
			SUPPLY,
			1,
		);
		expect(ranked).toHaveLength(1);
		expect(ranked[0].owner).toBe(W2);
	});
});

describe('deriveConcentration — documented thresholds', () => {
	it('maps top10Pct through the documented rule', () => {
		expect(deriveConcentration(CONCENTRATION_HIGH_PCT + 0.01)).toBe('high');
		expect(deriveConcentration(CONCENTRATION_HIGH_PCT)).toBe('medium');
		expect(deriveConcentration(CONCENTRATION_MEDIUM_PCT + 0.01)).toBe('medium');
		expect(deriveConcentration(CONCENTRATION_MEDIUM_PCT)).toBe('low');
		expect(deriveConcentration(0)).toBe('low');
		expect(deriveConcentration(null)).toBe('unknown');
	});
});

describe('composeTokenHolders — keyless RPC fallback path', () => {
	it('resolves owners, ranks, and marks the keyless truth honestly', async () => {
		const r = await composeTokenHolders({ address: THREE, limit: 10 }, deps());
		expect(r.status).toBe('ok');
		expect(r.holderCount).toBeNull(); // unknowable keylessly — never guessed
		expect(r.top[0]).toEqual({ owner: W1, amount: 400000000, pct: 40 });
		expect(r.top10Pct).toBe(80);
		expect(r.concentration).toBe('medium');
		expect(r.sources).toEqual(['solana-rpc']);
		expect(r.note).toMatch(/keyless/);
	});

	it('caps limit and floors garbage to the default', async () => {
		const r = await composeTokenHolders({ address: THREE, limit: 999 }, deps());
		expect(r.top.length).toBeLessThanOrEqual(50);
	});

	it('owner resolution failing still returns top-N keyed by account address', async () => {
		const r = await composeTokenHolders({ address: THREE }, deps({
			fetchAccountOwners: async () => { throw new Error('rpc flake'); },
		}));
		expect(r.status).toBe('ok');
		expect(r.top[0].owner).toBe('acctA');
	});
});

describe('composeTokenHolders — helius path', () => {
	const heliusAccounts = [
		{ owner: W1, address: 'a1', amount: '500000000' },
		{ owner: W1, address: 'a2', amount: '100000000' },
		{ owner: W2, address: 'a3', amount: '250000000' },
		{ owner: W3, address: 'a4', amount: '50000000' },
	];

	it('aggregates by owner and reports an exact holder count when complete', async () => {
		const r = await composeTokenHolders({ address: THREE, limit: 2 }, deps({
			fetchHelius: async () => ({ accounts: heliusAccounts, complete: true }),
		}));
		expect(r.status).toBe('ok');
		expect(r.holderCount).toBe(3);
		expect(r.top).toHaveLength(2);
		expect(r.top[0]).toEqual({ owner: W1, amount: 600000000, pct: 60 });
		expect(r.sources).toContain('helius-das');
	});

	it('incomplete walk → holderCount null with a note, top-N still real', async () => {
		const r = await composeTokenHolders({ address: THREE }, deps({
			fetchHelius: async () => ({ accounts: heliusAccounts, complete: false }),
		}));
		expect(r.holderCount).toBeNull();
		expect(r.note).toMatch(/holder count omitted/);
		expect(r.top[0].owner).toBe(W1);
	});

	it('helius throwing falls back to the keyless path', async () => {
		const r = await composeTokenHolders({ address: THREE }, deps({
			fetchHelius: async () => { throw new Error('quota'); },
		}));
		expect(r.status).toBe('ok');
		expect(r.sources).toEqual(['solana-rpc']);
	});
});

describe('composeTokenHolders — states', () => {
	it('mint answered but not a mint → not_found', async () => {
		const r = await composeTokenHolders({ address: W1 }, deps({
			fetchMintAccount: async () => ({ result: { value: null } }),
		}));
		expect(r.status).toBe('not_found');
	});

	it('brand-new mint with zero token accounts → valid empty, not an error', async () => {
		const r = await composeTokenHolders({ address: THREE }, deps({
			fetchLargestAccounts: async () => ({ result: { value: [] } }),
		}));
		expect(r.status).toBe('ok');
		expect(r.top).toEqual([]);
		expect(r.concentration).toBe('unknown');
		expect(r.note).toMatch(/brand-new/);
	});

	it('everything down → upstream_down', async () => {
		const boom = async () => { throw new Error('down'); };
		const r = await composeTokenHolders({ address: THREE }, deps({
			fetchMintAccount: boom, fetchLargestAccounts: boom, fetchHelius: async () => null,
		}));
		expect(r.status).toBe('upstream_down');
	});

	it('mint readable but holder read down → upstream_down, never a false not-found', async () => {
		const r = await composeTokenHolders({ address: THREE }, deps({
			fetchLargestAccounts: async () => { throw new Error('throttled'); },
		}));
		expect(r.status).toBe('upstream_down');
	});

	it('a JSON-RPC error envelope is NOT an answer — throttling never fakes an empty holder set', async () => {
		const r = await composeTokenHolders({ address: THREE }, deps({
			fetchLargestAccounts: async () => ({ error: { code: -32429, message: 'Too many requests' } }),
		}));
		expect(r.status).toBe('upstream_down');
	});
});

// The keyed walk is the preferred lane; when it silently dies every holder read
// lands on the keyless one, whose getTokenLargestAccounts most public RPCs
// refuse. These pin the failure shapes that took it down without a trace.
describe('heliusHolderWalk failure shapes', () => {
	const MINT = THREE;
	// The fleet-wide lane cooldown is module state; isolate each case from it.
	const noBreaker = { isCooling: () => false, markCooldown: () => {} };
	const page = (n) => ({
		ok: true,
		status: 200,
		text: async () => JSON.stringify({
			result: { token_accounts: Array.from({ length: n }, (_, i) => ({ owner: W1, address: `a${i}`, amount: '1' })) },
		}),
	});

	const withKey = async (fn) => {
		const had = process.env.HELIUS_API_KEY;
		process.env.HELIUS_API_KEY = 'test-key';
		try {
			return await fn();
		} finally {
			if (had === undefined) delete process.env.HELIUS_API_KEY;
			else process.env.HELIUS_API_KEY = had;
		}
	};

	it('returns null without a key so the caller uses the keyless lane', async () => {
		const had = process.env.HELIUS_API_KEY;
		delete process.env.HELIUS_API_KEY;
		try {
			expect(await heliusHolderWalk(MINT, { fetchImpl: async () => page(0), ...noBreaker })).toBeNull();
		} finally {
			if (had !== undefined) process.env.HELIUS_API_KEY = had;
		}
	});

	it('names an exhausted plan instead of throwing a bare JSON parse error', async () => {
		await withKey(async () => {
			const fetchImpl = async () => ({ ok: true, status: 200, text: async () => 'max usage reached' });
			await expect(heliusHolderWalk(MINT, { fetchImpl, ...noBreaker })).rejects.toThrow(/non-JSON response .*max usage reached/);
		});
	});

	it('names a JSON-RPC error envelope', async () => {
		await withKey(async () => {
			const fetchImpl = async () => ({ ok: true, status: 200, text: async () => JSON.stringify({ error: { code: -32603, message: 'nope' } }) });
			await expect(heliusHolderWalk(MINT, { fetchImpl, ...noBreaker })).rejects.toThrow(/nope/);
		});
	});

	it('keeps the pages already walked when a later page fails', async () => {
		await withKey(async () => {
			let call = 0;
			const fetchImpl = async () => {
				call++;
				if (call === 1) return page(1000);
				throw new Error('gateway timeout');
			};
			const out = await heliusHolderWalk(MINT, { fetchImpl, ...noBreaker });
			expect(out.accounts).toHaveLength(1000);
			// Incomplete, so the holder COUNT is still withheld rather than guessed.
			expect(out.complete).toBe(false);
		});
	});

	it('still throws when the very first page fails and there is nothing to keep', async () => {
		await withKey(async () => {
			const fetchImpl = async () => { throw new Error('gateway timeout'); };
			await expect(heliusHolderWalk(MINT, { fetchImpl, ...noBreaker })).rejects.toThrow(/gateway timeout/);
		});
	});

	it('marks a short page as a complete walk', async () => {
		await withKey(async () => {
			const out = await heliusHolderWalk(MINT, { fetchImpl: async () => page(3), ...noBreaker });
			expect(out.complete).toBe(true);
			expect(out.accounts).toHaveLength(3);
		});
	});

	it('skips the walk while the Helius lane is parked in the quota cooldown', async () => {
		await withKey(async () => {
			let called = false;
			const fetchImpl = async () => { called = true; return page(3); };
			const out = await heliusHolderWalk(MINT, { fetchImpl, isCooling: () => true, markCooldown: () => {} });
			expect(out).toBeNull();
			expect(called).toBe(false);
		});
	});

	it('parks the Helius lane fleet-wide when the plan reports max usage', async () => {
		await withKey(async () => {
			const marks = [];
			const fetchImpl = async () => ({ ok: false, status: 429, text: async () => 'max usage reached' });
			await expect(
				heliusHolderWalk(MINT, { fetchImpl, isCooling: () => false, markCooldown: (...a) => marks.push(a) }),
			).rejects.toThrow(/429: max usage reached/);
			expect(marks).toHaveLength(1);
			expect(marks[0][0]).toMatch(/mainnet\.helius-rpc\.com/);
			expect(marks[0][1]).toBe(429);
		});
	});

	it('does not park the lane for a transient failure', async () => {
		await withKey(async () => {
			const marks = [];
			const fetchImpl = async () => { throw new Error('gateway timeout'); };
			await expect(
				heliusHolderWalk(MINT, { fetchImpl, isCooling: () => false, markCooldown: (...a) => marks.push(a) }),
			).rejects.toThrow(/gateway timeout/);
			expect(marks).toHaveLength(0);
		});
	});
});

describe('realHolderDeps Helius budget gate', () => {
	it('takes the keyless lane without touching Helius when the budget says no', async () => {
		let asked = 0;
		const d = realHolderDeps({ heliusAllowed: async () => { asked++; return false; } });
		expect(await d.fetchHelius(THREE)).toBeNull();
		expect(asked).toBe(1);
	});
});