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.

test(leaderboard): hold every earnings-board row to the agent's own earnings, in a PGlite test and a live cross-check

nirholas9135bc57973c
diff --git a/scripts/check-earnings-board.mjs b/scripts/check-earnings-board.mjs
new file mode 100644
index 000000000..2a47942cf
--- /dev/null
+++ b/scripts/check-earnings-board.mjs
@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// check-earnings-board.mjs - cross-checks the earnings leaderboard against each
+// agent's own earnings, on real data.
+//
+// GET /api/leaderboard/earnings and GET /api/agents/:id/earnings share one read
+// model (api/_lib/agent-earnings.js), and the promise to users is that a row on
+// /leaderboard?tab=earned and the Earned card on that agent's page never
+// disagree. This script holds the live system to it: for every window it pages
+// through the whole board, asks each ranked agent for its own earnings over the
+// same window, and compares creator fees (exact lamports), service income (USD)
+// and the total. For the windows an agent page reports a rank for, the rank
+// must match the row's position too. Every row's total must equal its creator
+// fees plus service income, and the board must be sorted by total.
+//
+// Read-only: it only issues public GET requests.
+//
+// node scripts/check-earnings-board.mjs # https://three.ws
+// node scripts/check-earnings-board.mjs --base http://localhost:8080
+// node scripts/check-earnings-board.mjs --window 7d --window all
+//
+// Exit 0 when every row agrees, 1 on any mismatch, 2 when the API is unreachable.
+
+const args = process.argv.slice(2);
+const flag = (name) => {
+ const out = [];
+ args.forEach((a, i) => { if (a === `--${name}` && args[i + 1]) out.push(args[i + 1]); });
+ return out;
+};
+const BASE = (flag('base')[0] || 'https://three.ws').replace(/\/$/, '');
+const WINDOWS = flag('window').length ? flag('window') : ['24h', '7d', '30d', 'all'];
+const PAGE = 100;
+// SOL figures carry nine decimals; two independent roundings may differ in the last.
+const SOL_EPS = 2e-9;
+
+async function getJson(path) {
+ for (let attempt = 0; ; attempt++) {
+ const res = await fetch(`${BASE}${path}`, { headers: { accept: 'application/json' } });
+ if (res.status === 429 && attempt < 5) {
+ const wait = Number(res.headers.get('retry-after')) || 2 ** attempt;
+ await new Promise((r) => setTimeout(r, wait * 1000));
+ continue;
+ }
+ if (!res.ok) throw new Error(`${path} answered ${res.status}`);
+ return res.json();
+ }
+}
+
+async function wholeBoard(window) {
+ const rows = [];
+ let total = Infinity;
+ let price = null;
+ while (rows.length < total) {
+ const page = await getJson(`/api/leaderboard/earnings?window=${window}&limit=${PAGE}&offset=${rows.length}`);
+ total = page.total;
+ price = page.sol_price_usd;
+ rows.push(...page.rows);
+ if (!page.rows.length) break;
+ }
+ return { rows, total, price };
+}
+
+function compareRow(window, row, mine, boardPrice) {
+ const problems = [];
+ if (row.creator_fees.lamports !== mine.creator_fees.lamports) {
+ problems.push(`creator fees ${row.creator_fees.lamports} vs ${mine.creator_fees.lamports} lamports`);
+ }
+ if (row.service_income.usd !== mine.service_income.usd) {
+ problems.push(`service income $${row.service_income.usd} vs $${mine.service_income.usd}`);
+ }
+ // The total converts service income at the response's SOL price; the two
+ // calls can straddle a price refresh, so compare totals only at one price.
+ if (boardPrice === mine.sol_price_usd && Math.abs(row.total.sol - mine.total.sol) > SOL_EPS) {
+ problems.push(`total ${row.total.sol} vs ${mine.total.sol} SOL`);
+ }
+ const parts = (row.creator_fees.sol || 0) + (row.service_income.sol || 0);
+ if (Math.abs(parts - row.total.sol) > SOL_EPS) problems.push(`row total ${row.total.sol} is not fees + service (${parts})`);
+ // An agent page ranks itself on its own window, or on 7d when asked for all-time.
+ const rankWindow = window === 'all' ? null : window;
+ if (rankWindow && mine.rank && mine.rank.window === rankWindow && mine.rank.position !== row.rank) {
+ problems.push(`rank #${row.rank} on the board vs #${mine.rank.position} on the agent page`);
+ }
+ return problems;
+}
+
+let failures = 0;
+for (const window of WINDOWS) {
+ let board;
+ try {
+ board = await wholeBoard(window);
+ } catch (err) {
+ console.error(`[earnings-board] ${window}: ${err.message}`);
+ process.exit(2);
+ }
+ let boardSol = 0;
+ let agentSol = 0;
+ let lastTotal = Infinity;
+ for (const row of board.rows) {
+ if (row.total.sol > lastTotal + SOL_EPS) {
+ failures++;
+ console.log(` ${window} #${row.rank} ${row.agent.name}: ranked above a smaller total`);
+ }
+ lastTotal = row.total.sol;
+ const mine = await getJson(`/api/agents/${row.agent.id}/earnings?window=${window}`);
+ boardSol += row.total.sol;
+ agentSol += mine.total.sol;
+ const problems = compareRow(window, row, mine, board.price);
+ if (problems.length) {
+ failures++;
+ console.log(` ${window} #${row.rank} ${row.agent.name} (${row.agent.id}): ${problems.join('; ')}`);
+ }
+ }
+ console.log(
+ `[earnings-board] ${window}: ${board.rows.length}/${board.total} ranked agents checked, ` +
+ `board total ${boardSol.toFixed(9)} SOL, sum of agent pages ${agentSol.toFixed(9)} SOL at $${board.price ?? '?'} per SOL`,
+ );
+}
+
+if (failures) {
+ console.log(`[earnings-board] ${failures} row(s) disagree`);
+ process.exit(1);
+}
+console.log('[earnings-board] every row matches its agent page');
diff --git a/tests/agent-earnings-board.test.js b/tests/agent-earnings-board.test.js
new file mode 100644
index 000000000..29c6d4e82
--- /dev/null
+++ b/tests/agent-earnings-board.test.js
@@ -0,0 +1,285 @@
+// GET /api/leaderboard/earnings against GET /api/agents/:id/earnings, both
+// driven through their real handlers over an in-process Postgres (PGlite).
+//
+// The board and each agent's Earned card share one read model, and the promise
+// is that a row and the agent's page never disagree. These tests seed creator
+// fees (lifetime totals and fee buckets), skill sales and hires across every
+// window, then hold each board row to the agent's own figures, its rank, and
+// the attribution rules (custodial wallet only, public agents only, devnet out).
+// scripts/check-earnings-board.mjs runs the same comparison on live data.
+
+import { Readable } from 'node:stream';
+import { beforeAll, beforeEach, describe, it, expect, vi } from 'vitest';
+import { createPgliteSql } from './_helpers/pglite-sql.js';
+
+const holder = vi.hoisted(() => ({ db: null }));
+
+vi.mock('../api/_lib/db.js', async (importActual) => {
+ const actual = await importActual();
+ return { ...actual, sql: (...args) => holder.db.sql(...args) };
+});
+vi.mock('../api/_lib/auth.js', () => ({
+ getSessionUser: async () => null,
+ authenticateBearer: async () => null,
+ extractBearer: () => null,
+}));
+vi.mock('../api/_lib/rate-limit.js', async (importActual) => {
+ const actual = await importActual();
+ const ok = async () => ({ success: true, limit: 100, remaining: 99, reset: Date.now() + 60_000 });
+ return { ...actual, limits: new Proxy({}, { get: () => ok }) };
+});
+vi.mock('../api/_lib/sol-price.js', () => ({ solPriceUsd: async () => 100 }));
+vi.mock('../api/_lib/r2.js', () => ({ publicUrl: (k) => `https://cdn.three.ws.test/${k}` }));
+
+process.env.DATABASE_URL ||= 'postgres://pglite.test/db';
+
+const USDC = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
+// Synthetic, keyless base58-shaped strings; not anyone's wallet or coin.
+const WALLET = (n) => `THREEsyntheticWa11et${String(n).padStart(24, '1')}`;
+const MINT = (n) => `THREEsyntheticMint${String(n).padStart(26, '1')}`;
+const DAY = 86_400_000;
+
+const DDL = `
+ create table avatars (id uuid primary key default gen_random_uuid(), thumbnail_key text, visibility text,
+ deleted_at timestamptz);
+ create table agent_identities (
+ id uuid primary key default gen_random_uuid(), user_id uuid, name text, avatar_id uuid,
+ meta jsonb default '{}'::jsonb, is_public boolean default true, deleted_at timestamptz
+ );
+ create table pump_agent_mints (
+ id uuid primary key default gen_random_uuid(), agent_id uuid, network text, mint text,
+ name text, symbol text, created_at timestamptz default now()
+ );
+ create table agent_coin_earnings (
+ mint text, network text, agent_id uuid, creator text, earned_lamports numeric,
+ claimed_lamports numeric, unclaimed_lamports numeric, wallet_coin_count int, wallet_agent_count int,
+ source text, error text, refreshed_at timestamptz default now(), attempted_at timestamptz default now(),
+ primary key (mint, network)
+ );
+ create table creator_fee_buckets (creator text, bucket_interval text, bucket_start timestamptz, fee_lamports numeric);
+ create table agent_revenue_events (
+ id uuid primary key default gen_random_uuid(), agent_id uuid, net_amount numeric, currency_mint text,
+ created_at timestamptz
+ );
+ create table agent_hires (
+ id uuid primary key default gen_random_uuid(), provider_agent_id uuid, usd numeric, status text,
+ created_at timestamptz, completed_at timestamptz
+ );
+ create table launcher_claims (agent_id uuid, network text, claim_sig text, claimed_lamports numeric, mint text,
+ created_at timestamptz default now());
+ create table agent_actions (agent_id uuid, type text, payload jsonb, created_at timestamptz default now());
+`;
+
+function mockReqRes(url) {
+ const req = Object.assign(new Readable({ read() {} }), {
+ method: 'GET',
+ url,
+ headers: {},
+ query: {},
+ connection: { remoteAddress: '127.0.0.1' },
+ socket: { remoteAddress: '127.0.0.1' },
+ });
+ req.push(null);
+ const chunks = [];
+ const headers = {};
+ const res = {
+ statusCode: 200,
+ writableEnded: false,
+ headersSent: false,
+ setHeader: (k, v) => { headers[k.toLowerCase()] = v; },
+ getHeader: (k) => headers[k.toLowerCase()],
+ writeHead(code, h) { res.statusCode = code; Object.assign(headers, h || {}); },
+ write: (c) => chunks.push(c),
+ end(b) { if (b !== undefined) chunks.push(b); res.writableEnded = true; },
+ get json() { return JSON.parse(chunks.join('') || 'null'); },
+ };
+ return { req, res, headers };
+}
+
+let boardHandler;
+let agentHandler;
+async function call(handler, url) {
+ const { req, res, headers } = mockReqRes(url);
+ await handler(req, res);
+ return { status: res.statusCode, body: res.json, headers };
+}
+const board = (qs) => call(boardHandler, `/api/leaderboard/earnings?${qs}`);
+const mine = (id, window) => call(agentHandler, `/api/agents/${id}/earnings?id=${id}&window=${window}`);
+
+async function agent(name, n, { isPublic = true } = {}) {
+ const [row] = await holder.db.query(
+ `insert into agent_identities (name, meta, is_public) values ($1, $2, $3) returning id`,
+ [name, JSON.stringify({ solana_address: WALLET(n) }), isPublic],
+ );
+ return row.id;
+}
+
+/** A mainnet coin whose fees go to `creator`, with lifetime totals and buckets. */
+async function coin(agentId, n, creator, { lifetime, buckets = [], network = 'mainnet', walletAgents = 1 }) {
+ await holder.db.query(
+ `insert into pump_agent_mints (agent_id, network, mint, name, symbol) values ($1, $2, $3, $4, $5)`,
+ [agentId, network, MINT(n), `Coin ${n}`, `C${n}`],
+ );
+ await holder.db.query(
+ `insert into agent_coin_earnings (mint, network, agent_id, creator, earned_lamports, claimed_lamports,
+ unclaimed_lamports, wallet_coin_count, wallet_agent_count, source)
+ values ($1, $2, $3, $4, $5, $6, $7, 1, $8, 'pumpfun_creator_fees')`,
+ [MINT(n), network, agentId, creator, lifetime, Math.floor(lifetime / 2), lifetime - Math.floor(lifetime / 2), walletAgents],
+ );
+ for (const [interval, agoMs, lamports] of buckets) {
+ const start = interval === '1d' ? Math.floor((Date.now() - agoMs) / DAY) * DAY : Date.now() - agoMs;
+ await holder.db.query(
+ `insert into creator_fee_buckets (creator, bucket_interval, bucket_start, fee_lamports) values ($1, $2, $3, $4)`,
+ [creator, interval, new Date(start).toISOString(), lamports],
+ );
+ }
+}
+
+const ago = (ms) => new Date(Date.now() - ms).toISOString();
+
+let ids;
+beforeAll(async () => {
+ ({ default: boardHandler } = await import('../api/leaderboard/earnings.js'));
+ ({ default: agentHandler } = await import('../api/agents/[id]/earnings.js'));
+});
+
+beforeEach(async () => {
+ holder.db = createPgliteSql();
+ await holder.db.exec(DDL);
+ const fees = await agent('Fees', 1);
+ const seller = await agent('Seller', 2);
+ const mixed = await agent('Mixed', 3);
+ const hidden = await agent('Hidden', 4, { isPublic: false });
+ const sponsored = await agent('Sponsored', 5);
+ ids = { fees, seller, mixed, hidden, sponsored };
+
+ // Fees: 3 SOL lifetime, 0.4 SOL in the last 24h, 1 SOL three days ago, 0.5 SOL twenty days ago.
+ await coin(fees, 1, WALLET(1), {
+ lifetime: 3_000_000_000,
+ buckets: [
+ ['30m', 3_600_000, 400_000_000],
+ ['1d', 0, 400_000_000],
+ ['1d', 3 * DAY, 1_000_000_000],
+ ['1d', 20 * DAY, 500_000_000],
+ ['1d', 9 * DAY, 2_000_000_000],
+ ],
+ });
+ // A devnet coin on the same agent never counts.
+ await coin(fees, 2, WALLET(1), { lifetime: 9_000_000_000, network: 'devnet' });
+
+ // Seller: $50 of skill sales yesterday-ish and a $30 hire ten days ago.
+ await holder.db.query(
+ `insert into agent_revenue_events (agent_id, net_amount, currency_mint, created_at)
+ values ($1, 20000000, $2, $3), ($1, 30000000, $2, $4)`,
+ [seller, USDC, ago(2 * 3_600_000), ago(2 * DAY)],
+ );
+ await holder.db.query(
+ `insert into agent_hires (provider_agent_id, usd, status, created_at, completed_at)
+ values ($1, 30, 'completed', $2, $2), ($1, 999, 'failed', $3, null)`,
+ [seller, ago(10 * DAY), ago(DAY / 2)],
+ );
+
+ // Mixed: 1 SOL lifetime in fees (0.2 SOL today) plus one $40 sale this week.
+ await coin(mixed, 3, WALLET(3), {
+ lifetime: 1_000_000_000,
+ buckets: [['30m', 1_800_000, 200_000_000], ['1d', 0, 200_000_000]],
+ });
+ await holder.db.query(
+ `insert into agent_revenue_events (agent_id, net_amount, currency_mint, created_at) values ($1, 40000000, $2, $3)`,
+ [mixed, USDC, ago(4 * DAY)],
+ );
+
+ // Hidden: a private agent with a large income never appears on the board.
+ await coin(hidden, 4, WALLET(4), { lifetime: 50_000_000_000, buckets: [['30m', 600_000, 5_000_000_000]] });
+
+ // Sponsored: its coin pays someone else's wallet, so it is listed on its page but not counted.
+ await coin(sponsored, 5, WALLET(99), { lifetime: 7_000_000_000, buckets: [['30m', 600_000, 1_000_000_000]] });
+});
+
+describe('GET /api/leaderboard/earnings', () => {
+ it('ranks public agents by creator fees plus service income, newest-window first by default', async () => {
+ const { status, body, headers } = await board('');
+ expect(status).toBe(200);
+ expect(body.window).toBe('7d');
+ expect(headers['cache-control']).toMatch(/public/);
+ expect(typeof body.method).toBe('string');
+ // 7d: Fees 1.4 SOL; Mixed 0.2 SOL + $40 (0.4 SOL) = 0.6; Seller $50 = 0.5.
+ expect(body.rows.map((r) => [r.agent.name, r.total.sol])).toEqual([
+ ['Fees', 1.4],
+ ['Mixed', 0.6],
+ ['Seller', 0.5],
+ ]);
+ expect(body.rows.map((r) => r.rank)).toEqual([1, 2, 3]);
+ expect(body.rows[1]).toMatchObject({
+ creator_fees: { sol: 0.2, usd: 20 },
+ service_income: { skill_sales_usd: 40, skill_sales_count: 1, hires_usd: 0, usd: 40, sol: 0.4 },
+ coin: { symbol: 'C3', url: `/launches/${MINT(3)}` },
+ });
+ });
+
+ it('leaves out private agents, devnet coins and fees paid to another wallet', async () => {
+ for (const window of ['24h', '7d', '30d', 'all']) {
+ const { body } = await board(`window=${window}`);
+ const names = body.rows.map((r) => r.agent.name);
+ expect(names).not.toContain('Hidden');
+ expect(names).not.toContain('Sponsored');
+ }
+ const { body } = await board('window=all');
+ expect(body.rows.find((r) => r.agent.name === 'Fees').creator_fees.sol).toBe(3);
+ });
+
+ it('reports movement against the previous window', async () => {
+ const { body } = await board('window=7d');
+ const byName = Object.fromEntries(body.rows.map((r) => [r.agent.name, r]));
+ // The 7 days before this week: Fees earned 2 SOL, Seller a $30 hire, Mixed nothing.
+ expect(byName.Fees).toMatchObject({ previous_rank: 1, movement: 0 });
+ expect(byName.Seller).toMatchObject({ previous_rank: 2, movement: -1 });
+ expect(byName.Mixed).toMatchObject({ previous_rank: null, movement: 'new' });
+ const all = await board('window=all');
+ expect(all.body.rows.every((r) => r.movement === null)).toBe(true);
+ });
+
+ it('paginates without changing anyone\'s rank', async () => {
+ const full = await board('window=30d');
+ const first = await board('window=30d&limit=2&offset=0');
+ const second = await board('window=30d&limit=2&offset=2');
+ expect(first.body.total).toBe(full.body.total);
+ expect([...first.body.rows, ...second.body.rows].map((r) => [r.rank, r.agent.id])).toEqual(
+ full.body.rows.map((r) => [r.rank, r.agent.id]),
+ );
+ });
+
+ it('shows an empty board as an empty list, not an error', async () => {
+ await holder.db.exec(`delete from agent_coin_earnings; delete from agent_revenue_events; delete from agent_hires;`);
+ const { status, body } = await board('window=24h');
+ expect(status).toBe(200);
+ expect(body).toMatchObject({ total: 0, rows: [] });
+ });
+});
+
+describe('the board agrees with every agent\'s own earnings', () => {
+ it.each(['24h', '7d', '30d', 'all'])('window %s', async (window) => {
+ const { body } = await board(`window=${window}&limit=100`);
+ expect(body.rows.length).toBeGreaterThan(0);
+ let boardSol = 0;
+ let pageSol = 0;
+ for (const row of body.rows) {
+ const { status, body: own } = await mine(row.agent.id, window);
+ expect(status).toBe(200);
+ expect(own.creator_fees).toEqual(row.creator_fees);
+ expect(own.service_income).toEqual(row.service_income);
+ expect(own.total).toEqual(row.total);
+ if (window !== 'all') expect(own.rank).toMatchObject({ window, position: row.rank, of: body.total });
+ boardSol += row.total.sol;
+ pageSol += own.total.sol;
+ }
+ expect(boardSol).toBeCloseTo(pageSol, 9);
+ });
+
+ it('an agent outside the board answers zero, and its rank is null', async () => {
+ const { body } = await mine(ids.sponsored, '7d');
+ expect(body.total.sol).toBe(0);
+ expect(body.rank).toBeNull();
+ expect(body.coins[0]).toMatchObject({ status: 'other_wallet', earned_sol: 7 });
+ });
+});