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.

7.2 KB
Raw Blame
// Guard-logic tests for the economy funding root (api/_lib/economy-master.js).
// planTopUps is pure, so we can assert the reserve floor, per-engine cap, per-run
// cap, dust skip, and neediest-first ordering without any RPC or key.
import { test } from 'vitest';
import assert from 'node:assert/strict';
import {
	planTopUps,
	filterToRegistry,
	RESERVE_SOL,
	PER_TOPUP_MAX_SOL,
	RUN_CAP_SOL,
} from '../api/_lib/economy-master.js';

// Defaults (no env overrides): reserve 0.02 (rent-exemption + fee headroom,
// not a business-scale gate), per-engine 0.5, run cap 2.
test('defaults are the documented guard values', () => {
	assert.equal(RESERVE_SOL, 0.02);
	assert.equal(PER_TOPUP_MAX_SOL, 0.5);
	assert.equal(RUN_CAP_SOL, 2);
});

test('reserve floor: a master below reserve funds nothing', () => {
	const { plan, totalSol, spendableSol } = planTopUps(0.01, [
		{ name: 'a', pubkey: 'A', currentSol: 0, refillToSol: 0.3 },
	]);
	assert.equal(spendableSol, 0);
	assert.equal(plan.length, 0);
	assert.equal(totalSol, 0);
});

test('a thinly funded master still spends nearly all of it (no oversized reserve gate)', () => {
	// 0.302 SOL master — the real prod balance this fix targets. Should be
	// able to spend ~0.282 of it, not sit fully locked behind a 1 SOL floor.
	const { plan, totalSol, spendableSol } = planTopUps(0.302, [
		{ name: 'engine', pubkey: 'E', currentSol: 0, refillToSol: 5 },
	]);
	assert.ok(spendableSol > 0.28 && spendableSol < 0.29);
	assert.equal(plan.length, 1);
	assert.equal(totalSol, spendableSol);
});

test('per-engine cap: one engine gets at most PER_TOPUP_MAX_SOL', () => {
	const { plan } = planTopUps(10, [
		{ name: 'greedy', pubkey: 'G', currentSol: 0, refillToSol: 3 },
	]);
	assert.equal(plan.length, 1);
	assert.equal(plan[0].sol, 0.5); // capped from a 3 SOL deficit
});

test('per-run cap: a sweep spends at most RUN_CAP_SOL total', () => {
	const targets = Array.from({ length: 6 }, (_, i) => ({
		name: `e${i}`,
		pubkey: `P${i}`,
		currentSol: 0,
		refillToSol: 0.5,
	}));
	const { plan, totalSol, skipped } = planTopUps(10, targets); // spendable ~9.98, runCap 2
	assert.equal(totalSol, 2);
	assert.equal(plan.length, 4); // 4 × 0.5 = 2.0
	assert.ok(skipped.some((s) => s.reason === 'run_cap_reached'));
});

test('per-run cap: a want exceeding the remaining budget is clamped, not skipped', () => {
	// master 1.32 → spendable 1.3 → runCap 1.3 (below the fixed 2 SOL cap, so the
	// balance itself is the binding constraint). Three engines each want the
	// per-engine max (0.5), but only 1.3 total exists: A and B get funded in
	// full, C should get the LEFTOVER 0.3 rather than being skipped outright —
	// a thin run cap should still be spent down, not wasted.
	const { plan, totalSol, skipped } = planTopUps(1.32, [
		{ name: 'a', pubkey: 'A', currentSol: 0, refillToSol: 1.0 },
		{ name: 'b', pubkey: 'B', currentSol: 0, refillToSol: 1.0 },
		{ name: 'c', pubkey: 'C', currentSol: 0, refillToSol: 1.0 },
	]);
	assert.equal(totalSol, 1.3);
	assert.equal(plan.length, 3);
	assert.equal(plan[0].sol, 0.5);
	assert.equal(plan[1].sol, 0.5);
	assert.equal(plan[2].sol, 0.3);
	assert.equal(skipped.length, 0);
});

test('dust: a sub-threshold deficit is skipped, not churned', () => {
	const { plan, skipped } = planTopUps(10, [
		{ name: 'hair', pubkey: 'H', currentSol: 0.499, refillToSol: 0.5 },
	]);
	assert.equal(plan.length, 0);
	assert.deepEqual(skipped, [{ name: 'hair', reason: 'below_dust_threshold' }]);
});

// The ordering only decides anything when the master is thin, and that is
// exactly when it used to decide wrong: production 2026-09-04 held a
// relayer/treasury bundle wanting 0.98 SOL and the x402 ring payer wanting 0.18,
// so every top-up under ~1 SOL went entirely to the bundle and left the payer
// under the hard floor the self-facilitator refuses to settle beneath.
test('settle-critical first: a thin master funds the fee wallet before a needier float', () => {
	const targets = [
		{ name: 'relayer+treasury', pubkey: 'W', currentSol: 0.016894, refillToSol: 1 },
		{ name: 'x402-ring-payer', pubkey: 'X', currentSol: 0.001253, refillToSol: 0.18, settleCritical: true },
	];
	// master 0.1015 → spendable ~0.0695 (reserve 0.02): only one engine fits.
	const { plan, skipped } = planTopUps(0.101508, targets);
	assert.equal(plan.length, 1);
	assert.equal(plan[0].pubkey, 'X');
	// And the top-up clears the 0.002 SOL settle floor by a wide margin.
	assert.ok(plan[0].sol + 0.001253 > 0.002);
	assert.deepEqual(skipped, [{ name: 'relayer+treasury', reason: 'run_cap_reached' }]);
});

test('settle-critical does not reorder anything once the budget covers both', () => {
	const targets = [
		{ name: 'relayer+treasury', pubkey: 'W', currentSol: 0, refillToSol: 1 },
		{ name: 'x402-ring-payer', pubkey: 'X', currentSol: 0, refillToSol: 0.18, settleCritical: true },
	];
	const { plan, skipped } = planTopUps(10, targets);
	assert.equal(plan.length, 2);
	assert.equal(plan[0].pubkey, 'X');
	assert.equal(skipped.length, 0);
});

// "run_cap_reached" on a master with nothing to give sent operators looking for
// a cap knob to raise; the fix is capital, and the reason has to say so.
test('a dry master says it is dry, not that a cap was reached', () => {
	const { plan, skipped } = planTopUps(0.001508, [
		{ name: 'relayer+treasury', pubkey: 'W', currentSol: 0.016894, refillToSol: 1 },
		{ name: 'x402-ring-payer', pubkey: 'X', currentSol: 0.001253, refillToSol: 0.18, settleCritical: true },
	]);
	assert.equal(plan.length, 0);
	assert.deepEqual(
		skipped.map((s) => s.reason),
		['master_insufficient_spendable', 'master_insufficient_spendable'],
	);
});

test('neediest first: the most-drained engine is planned before a less-needy one', () => {
	const { plan } = planTopUps(1.5, [
		{ name: 'small', pubkey: 'S', currentSol: 0.4, refillToSol: 0.5 }, // deficit 0.1
		{ name: 'big', pubkey: 'B', currentSol: 0.0, refillToSol: 0.5 }, // deficit 0.5
	]);
	assert.equal(plan[0].name, 'big');
});

// filterToRegistry is the hard leak guard: SOL can only ever move to a resolved
// registry signer, never off-registry and never the master itself.
test('allowlist: an off-registry pubkey is rejected, never funded', () => {
	const allowed = new Set(['ENGINE_A', 'ENGINE_B']);
	const { safe, rejected } = filterToRegistry(
		[
			{ name: 'legit', pubkey: 'ENGINE_A', currentSol: 0, refillToSol: 0.5 },
			{ name: 'attacker', pubkey: 'EVIL_ADDR', currentSol: 0, refillToSol: 0.5 },
		],
		allowed,
		'MASTER',
	);
	assert.deepEqual(safe.map((t) => t.name), ['legit']);
	assert.deepEqual(rejected, [{ name: 'attacker', pubkey: 'EVIL_ADDR', reason: 'not_in_registry' }]);
});

test('allowlist: the master is never a top-up target of itself', () => {
	const allowed = new Set(['MASTER', 'ENGINE_A']);
	const { safe, rejected } = filterToRegistry(
		[{ name: 'economy-master', pubkey: 'MASTER', currentSol: 0, refillToSol: 999 }],
		allowed,
		'MASTER',
	);
	assert.equal(safe.length, 0);
	assert.deepEqual(rejected, [{ name: 'economy-master', pubkey: 'MASTER', reason: 'is_master' }]);
});

test('allowlist: an empty registry funds nothing (safe default)', () => {
	const { safe, rejected } = filterToRegistry(
		[{ name: 'e', pubkey: 'ENGINE_A', currentSol: 0, refillToSol: 0.5 }],
		new Set(),
		'MASTER',
	);
	assert.equal(safe.length, 0);
	assert.equal(rejected.length, 1);
});