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.

10.9 KB
Raw Blame
// Tests for the x402 ring catalog — the single source of truth for every paid
// endpoint on three.ws (api/_lib/x402/ring-catalog.js) and the rotation the ring
// drivers walk. Pure logic + a filesystem scan; no DB, no chain, no network.
//
// What these lock down:
//   • schema — every entry is structurally valid and its body()/query matches its
//     method, so a rotation call never spends money on a malformed request.
//   • 100% coverage — every `paidEndpoint(` construction site in api/ is cataloged
//     (a new paid endpoint fails this test until it is added).
//   • stale paths — every path resolves to a real handler file under api/.
//   • hourly coverage — the wired rotation touches every autobuy slug within a
//     simulated default-cadence hour.

import { describe, it, expect } from 'vitest';
import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
import { join } from 'node:path';

import {
	RING_CATALOG,
	autobuyEntries,
	rotationPlan,
	bySlug,
	AUTONOMOUS_TICKS_PER_HOUR,
	RING_CANARY_MINT,
	RING_CANARY_UUID,
} from '../api/_lib/x402/ring-catalog.js';

const KINDS = new Set(['tip', 'service', 'intel', 'health', 'commerce', 'settle']);
const TIERS = new Set(['settle', 'commerce', 'intel', 'service', 'health']);

describe('ring-catalog schema', () => {
	it('every entry is structurally valid', () => {
		for (const e of RING_CATALOG) {
			expect(typeof e.slug, `${e.slug} slug`).toBe('string');
			expect(e.slug.length, `${e.slug} slug non-empty`).toBeGreaterThan(0);
			expect(typeof e.sourceFile, `${e.slug} sourceFile`).toBe('string');
			expect(e.path.startsWith('/api/'), `${e.slug} path`).toBe(true);
			expect(['GET', 'POST'].includes(e.method), `${e.slug} method`).toBe(true);
			expect(KINDS.has(e.kind), `${e.slug} kind=${e.kind}`).toBe(true);
			expect(TIERS.has(e.tier), `${e.slug} tier=${e.tier}`).toBe(true);
			expect(Number.isInteger(e.priceAtomicDefault), `${e.slug} price int`).toBe(true);
			expect(e.priceAtomicDefault, `${e.slug} price >= 0`).toBeGreaterThanOrEqual(0);
			expect(typeof e.priceSlug, `${e.slug} priceSlug`).toBe('string');
			expect(typeof e.autobuy, `${e.slug} autobuy`).toBe('boolean');
			expect(typeof e.body, `${e.slug} body is fn`).toBe('function');
			expect(typeof e.businessEffect, `${e.slug} businessEffect`).toBe('string');
			expect(e.businessEffect.length, `${e.slug} businessEffect non-empty`).toBeGreaterThan(0);
		}
	});

	it('slugs are unique', () => {
		const slugs = RING_CATALOG.map((e) => e.slug);
		expect(new Set(slugs).size).toBe(slugs.length);
	});

	it('body() returns parseable JSON for POST and null for GET', () => {
		for (const e of RING_CATALOG) {
			const body = e.body();
			if (e.method === 'GET') {
				expect(body, `${e.slug} GET body null`).toBeNull();
			} else {
				expect(body, `${e.slug} POST body object`).toBeTypeOf('object');
				expect(body, `${e.slug} POST body non-null`).not.toBeNull();
				// Round-trips through JSON without throwing.
				expect(() => JSON.parse(JSON.stringify(body))).not.toThrow();
			}
		}
	});

	it('GET entries with query params carry a plain-object query', () => {
		for (const e of RING_CATALOG) {
			if (e.query !== undefined) {
				expect(e.method, `${e.slug} query only on GET`).toBe('GET');
				expect(e.query, `${e.slug} query object`).toBeTypeOf('object');
				for (const [k, v] of Object.entries(e.query)) {
					expect(['string', 'number'].includes(typeof v), `${e.slug} query.${k} scalar`).toBe(true);
				}
			}
		}
	});

	it('autobuy entries carry a positive weight; non-autobuy entries justify themselves', () => {
		for (const e of RING_CATALOG) {
			if (e.autobuy) {
				expect(e.weight, `${e.slug} autobuy weight >= 1`).toBeGreaterThanOrEqual(1);
			} else {
				expect(typeof e.note, `${e.slug} autobuy:false needs a note`).toBe('string');
				expect(e.note.length, `${e.slug} note non-empty`).toBeGreaterThan(0);
			}
		}
	});

	it('canary identifiers are well-formed and inert', () => {
		// A valid base58 pump-style mint (32–44 chars, no 0/O/I/l) that maps to no
		// real coin-world, so a looped billboard buy writes an inert placement.
		expect(/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(RING_CANARY_MINT)).toBe(true);
		// A well-formed v4 UUID that resolves to no registered agent.
		expect(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(RING_CANARY_UUID)).toBe(true);
	});

	it('bySlug resolves every entry and returns null for unknown', () => {
		for (const e of RING_CATALOG) expect(bySlug(e.slug)).toBe(e);
		expect(bySlug('does-not-exist')).toBeNull();
	});

	// SAFETY: the $THREE micro-buy endpoint spends real USDC on a live market buy
	// every settled call. It must NEVER be swept by the generic ring rotation — only
	// its dedicated driver (api/cron/three-buy-loop.js), which enforces the daily
	// spend cap, may fire it. Flipping it to autobuy:true would unleash uncapped real
	// buys through the ring; this pins the invariant.
	it('three-buy is real-spend and excluded from the generic ring rotation', () => {
		const entry = bySlug('three-buy');
		expect(entry, 'three-buy is cataloged').toBeTruthy();
		expect(entry.autobuy, 'three-buy must be autobuy:false').toBe(false);
		expect(entry.weight, 'three-buy carries zero rotation weight').toBe(0);
		expect(rotationPlan().some((e) => e.slug === 'three-buy')).toBe(false);
		expect(autobuyEntries().some((e) => e.slug === 'three-buy')).toBe(false);
	});
});

// ── 100% coverage: every paidEndpoint( construction site is cataloged ─────────

// Walk api/ and return every .js file that constructs a paidEndpoint, as a set of
// repo-relative paths. A construction site is `= paidEndpoint(`, `default
// paidEndpoint(`, or `return paidEndpoint(` — the helper's own definition file is
// excluded.
function paidEndpointSites() {
	const root = process.cwd();
	const CONSTRUCT = /(?:=|default|return)\s*paidEndpoint\s*\(/;
	const sites = new Set();
	const walk = (dir) => {
		for (const name of readdirSync(dir)) {
			const full = join(dir, name);
			const st = statSync(full);
			if (st.isDirectory()) {
				if (name === 'node_modules') continue;
				walk(full);
			} else if (name.endsWith('.js')) {
				const rel = full.slice(root.length + 1);
				if (rel === 'api/_lib/x402-paid-endpoint.js') continue; // the helper itself
				const src = readFileSync(full, 'utf8');
				if (CONSTRUCT.test(src)) sites.add(rel);
			}
		}
	};
	walk(join(root, 'api'));
	return sites;
}

// Construction sites that are intentionally NOT ring-catalog entries.
//   api/_lib/aggregator.js builds the dynamic /api/v1/x/<provider>/<endpoint>
//   API-aggregator proxy family per descriptor — a separate product surface, not
//   a fixed ring endpoint.
//   api/x402/d/[...path].js is the datapoint fabric — 400k+ dynamic
//   (family, id, metric) endpoints from one route; ids are runtime values, so
//   no fixed catalog path can resolve to it. Its payment rail is the same
//   paidEndpoint wrapper the rotated market-data family already settles hourly.
const SITE_ALLOWLIST = new Set(['api/_lib/aggregator.js', 'api/x402/d/[...path].js']);

describe('ring-catalog covers 100% of paid endpoints', () => {
	it('every paidEndpoint( construction site is in the catalog', () => {
		const sites = paidEndpointSites();
		const cataloged = new Set(RING_CATALOG.map((e) => e.sourceFile));
		const missing = [...sites].filter((f) => !SITE_ALLOWLIST.has(f) && !cataloged.has(f));
		expect(missing, `uncataloged paid endpoints: ${missing.join(', ')}`).toEqual([]);
	});

	it('every catalog sourceFile is a real file under api/', () => {
		for (const e of RING_CATALOG) {
			expect(existsSync(e.sourceFile), `${e.slug} sourceFile ${e.sourceFile}`).toBe(true);
			expect(e.sourceFile.startsWith('api/'), `${e.slug} sourceFile under api/`).toBe(true);
		}
	});
});

// ── stale-path: every path resolves to a handler file under api/ ───────────────

describe('ring-catalog paths resolve', () => {
	it('every path maps to a real handler file (api<path>.js)', () => {
		for (const e of RING_CATALOG) {
			expect(existsSync(`.${e.path}.js`), `${e.slug} -> .${e.path}.js`).toBe(true);
		}
	});
});

// ── hourly rotation coverage ───────────────────────────────────────────────────

describe('rotation covers every autobuy endpoint within an hour', () => {
	it('rotationPlan includes every autobuy slug at least once', () => {
		const plan = rotationPlan();
		const covered = new Set(plan.map((e) => e.slug));
		for (const e of autobuyEntries()) {
			expect(covered.has(e.slug), `${e.slug} in rotation plan`).toBe(true);
		}
		// weighted entries appear `weight` times.
		for (const e of autobuyEntries()) {
			const n = plan.filter((p) => p.slug === e.slug).length;
			expect(n, `${e.slug} appears weight times`).toBe(e.weight);
		}
	});

	it('a simulated default-cadence hour selects every autobuy slug', () => {
		const plan = rotationPlan();
		// Match volume-shared.reserveWindow: a cursor advances by the batch each
		// tick, indices taken modulo the rotation length. Default cadence:
		// AUTONOMOUS_TICKS_PER_HOUR ticks × batch selections/tick. The fallback
		// mirrors VOLUME_BATCH_PER_RUN's default in pipelines/volume-shared.js.
		const BATCH = Number(process.env.X402_VOLUME_BATCH_PER_RUN || 6);
		const callsPerHour = AUTONOMOUS_TICKS_PER_HOUR * BATCH;
		expect(callsPerHour, 'calls/hour >= rotation length').toBeGreaterThanOrEqual(plan.length);

		const seen = new Set();
		let cursor = 0;
		for (let tick = 0; tick < AUTONOMOUS_TICKS_PER_HOUR; tick++) {
			for (let i = 0; i < BATCH; i++) {
				seen.add(plan[cursor % plan.length].slug);
				cursor++;
			}
		}
		const missed = autobuyEntries().map((e) => e.slug).filter((s) => !seen.has(s));
		expect(missed, `slugs never selected in an hour: ${missed.join(', ')}`).toEqual([]);
	});
});

// ── the wired rotation (volume-shared) reflects the catalog ────────────────────

describe('volume-shared rotation is catalog-derived', () => {
	it('VOLUME_ENDPOINTS mirrors the autobuy rotation, GET query baked into path', async () => {
		const { VOLUME_ENDPOINTS, RING_SETTLE_ENDPOINT, CHEAP_ENDPOINTS } = await import(
			'../api/_lib/x402/pipelines/volume-shared.js'
		);
		const plan = rotationPlan();
		expect(VOLUME_ENDPOINTS.length).toBe(plan.length);

		// ring-settle is the settle carrier; everything else is "cheap".
		expect(RING_SETTLE_ENDPOINT?.key).toBe('ring-settle');
		expect(CHEAP_ENDPOINTS.some((e) => e.key === 'ring-settle')).toBe(false);

		for (const ve of VOLUME_ENDPOINTS) {
			const entry = bySlug(ve.key);
			expect(entry, `${ve.key} maps to a catalog entry`).toBeTruthy();
			expect(ve.method).toBe(entry.method);
			// GET → query in path, null body; POST → object body, no query in path.
			if (entry.method === 'GET') {
				expect(ve.body).toBeNull();
				if (entry.query) expect(ve.path.includes('?')).toBe(true);
			} else {
				expect(ve.body).toBeTypeOf('object');
				expect(ve.path.includes('?')).toBe(false);
			}
		}
	});
});