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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// Unit tests for api/_lib/agent-trade-guards.js — the shared per-agent spend
// policy + custody ledger that governs withdraw / x402 / snipe / trade.
//
// Covers: Solana address validation (base58, on-curve, PDA rejection),
// spend-limit normalization, and enforcement of the per-tx + daily USD ceilings
// and the withdraw allowlist. The DB + SOL price feed are mocked so these are
// deterministic and fast.
import { describe, it, expect, beforeEach, vi } from 'vitest';
import { Keypair, PublicKey, SystemProgram } from '@solana/web3.js';
// ── mocks ─────────────────────────────────────────────────────────────────────
const sqlState = { queue: [], calls: [], handler: null, agentGone: false };
vi.mock('../api/_lib/db.js', () => ({
sql: vi.fn(async (strings, ...values) => {
const query = strings.join('?');
sqlState.calls.push({ query, values });
const handled = sqlState.handler ? sqlState.handler(query, values) : undefined;
if (handled !== undefined) return handled;
// The burner-tier gate reads the agent policy row when a caller names no meta.
// Serve a live agent with an empty policy by default; a test that wants the
// fail-closed path sets sqlState.agentGone.
if (/FROM agent_identities WHERE id = \? AND deleted_at IS NULL/.test(query.replace(/\s+/g, ' '))) {
return sqlState.agentGone ? [] : [{ user_id: 'user-1', meta: {} }];
}
return sqlState.queue.length ? sqlState.queue.shift() : [];
}),
isDbUnavailableError: () => false,
isDbCapacityError: () => false,
}));
vi.mock('../api/_lib/avatar-wallet.js', () => ({
solUsdPrice: vi.fn(async () => 200), // $200 / SOL
}));
vi.mock('../api/_lib/audit.js', () => ({ logAudit: vi.fn() }));
// The behavioral anomaly guard is an additive layer composed into enforceSpendLimit
// / reserveSpendUsd; it has its own dedicated tests (wallet-anomaly*.test.js). Stub
// it here so these USD-ceiling unit tests stay isolated from its async DB calls.
vi.mock('../api/_lib/anomaly-events.js', () => ({
guardOutboundAnomaly: vi.fn(async () => ({ decision: 'allow', verdict: null, anomalyId: null, froze: false })),
}));
// The sweeper-bot check is an RPC-backed heuristic with its own dedicated unit
// tests (burned-destination.test.js) against a pure classifier; stub it here so
// the allowlist/ceiling tests below stay off the network and deterministic.
vi.mock('../api/_lib/burned-destination.js', () => ({
checkBurnedDestination: vi.fn(async () => ({ checked: false, flagged: false, verdict: 'unknown', note: 'not checked in this test' })),
}));
const guards = await import('../api/_lib/agent-trade-guards.js');
const {
validateSolanaAddress, normalizeSpendLimits, enforceSpendLimit, SpendLimitError,
getDailySpendUsd, lamportsToUsd, getSpendLimits,
} = guards;
beforeEach(() => {
sqlState.queue = [];
sqlState.calls = [];
sqlState.handler = null;
sqlState.agentGone = false;
});
// The destination allowlist is table-backed: serve the settings row and the
// matching destination entry (if any) from the fake database.
function serveAllowlist({ enforced = true, entry = null } = {}) {
sqlState.handler = (query) => {
if (query.includes('destination_whitelist_settings')) return [{ agent_id: 'a', cooldown_seconds: 86400, enforced, pending_change: null }];
if (query.includes('destination_whitelist_entries')) return entry ? [entry] : [];
return undefined;
};
}
const activeEntry = (address) => ({
id: 'e1', agent_id: 'a', chain: 'solana', address, address_key: address, label: 'Cold', status: 'active',
proposed_by: 'owner', activates_at: new Date(Date.now() - 1000).toISOString(), per_tx_cap_usd: null, daily_cap_usd: null,
});
// ── address validation ─────────────────────────────────────────────────────────
describe('validateSolanaAddress', () => {
it('accepts a real on-curve wallet address', () => {
const addr = Keypair.generate().publicKey.toBase58();
const r = validateSolanaAddress(addr);
expect(r.valid).toBe(true);
expect(r.onCurve).toBe(true);
expect(r.base58).toBe(addr);
});
it('flags a program-derived (off-curve) address as not on-curve', () => {
const [pda] = PublicKey.findProgramAddressSync([Buffer.from('custody-test')], SystemProgram.programId);
const r = validateSolanaAddress(pda.toBase58());
expect(r.valid).toBe(true);
expect(r.onCurve).toBe(false);
});
it('rejects non-base58 input', () => {
expect(validateSolanaAddress('not an address!').valid).toBe(false);
expect(validateSolanaAddress('not an address!').reason).toBe('not_base58');
});
it('rejects empty / non-string input', () => {
expect(validateSolanaAddress('').valid).toBe(false);
expect(validateSolanaAddress(null).valid).toBe(false);
expect(validateSolanaAddress(undefined).valid).toBe(false);
});
it('rejects a base58 string that is the wrong byte length', () => {
// 5 base58 chars passes the length pre-filter's lower bound? No — min 32.
expect(validateSolanaAddress('abc').valid).toBe(false);
});
});
// ── limit normalization ─────────────────────────────────────────────────────────
describe('normalizeSpendLimits', () => {
it('defaults to unset ceilings + empty allowlist', () => {
const n = normalizeSpendLimits(undefined);
expect(n.daily_usd).toBeNull();
expect(n.per_tx_usd).toBeNull();
expect(n.withdraw_allowlist).toEqual([]);
});
it('coerces numeric strings and rejects negatives', () => {
expect(normalizeSpendLimits({ daily_usd: '50', per_tx_usd: 25 }).daily_usd).toBe(50);
expect(normalizeSpendLimits({ daily_usd: -5 }).daily_usd).toBeNull();
expect(normalizeSpendLimits({ per_tx_usd: 'abc' }).per_tx_usd).toBeNull();
});
// Order 519: a wallet that never sets an approval threshold keeps today's
// behavior (no human-approval gate on a2a hires); setting one is the minimal
// threshold check that lets api/agents/a2a-hire.js park a hire above it.
it('defaults approval_threshold_usd to null and coerces a numeric string', () => {
expect(normalizeSpendLimits(undefined).approval_threshold_usd).toBeNull();
expect(normalizeSpendLimits({ approval_threshold_usd: '10' }).approval_threshold_usd).toBe(10);
expect(normalizeSpendLimits({ approval_threshold_usd: -1 }).approval_threshold_usd).toBeNull();
});
it('filters invalid + de-dupes allowlist addresses', () => {
const a = Keypair.generate().publicKey.toBase58();
const n = normalizeSpendLimits({ withdraw_allowlist: [a, 'garbage', a] });
expect(n.withdraw_allowlist).toEqual([a]);
});
it('getSpendLimits reads off meta.spend_limits', () => {
const a = Keypair.generate().publicKey.toBase58();
const lim = getSpendLimits({ spend_limits: { daily_usd: 100, withdraw_allowlist: [a] } });
expect(lim.daily_usd).toBe(100);
expect(lim.withdraw_allowlist).toEqual([a]);
});
});
// ── enforcement ─────────────────────────────────────────────────────────────────
describe('enforceSpendLimit', () => {
const noLimits = { daily_usd: null, per_tx_usd: null, withdraw_allowlist: [] };
it('passes when no ceilings are set', async () => {
const r = await enforceSpendLimit({ agentId: 'a', limits: noLimits, category: 'x402', usdValue: 9999 });
expect(r.ok).toBe(true);
});
it('blocks an over-limit single transaction with a 403 SpendLimitError', async () => {
await expect(
enforceSpendLimit({ agentId: 'a', limits: { ...noLimits, per_tx_usd: 10 }, category: 'x402', usdValue: 25 }),
).rejects.toMatchObject({ name: 'SpendLimitError', code: 'per_tx_exceeded', status: 403 });
});
it('allows a transaction at the per-tx ceiling', async () => {
const r = await enforceSpendLimit({ agentId: 'a', limits: { ...noLimits, per_tx_usd: 10 }, category: 'x402', usdValue: 10 });
expect(r.ok).toBe(true);
});
it('blocks a withdraw to a non-allowlisted destination', async () => {
const other = Keypair.generate().publicKey.toBase58();
serveAllowlist({ entry: null });
await expect(
enforceSpendLimit({ agentId: 'a', limits: noLimits, category: 'withdraw', usdValue: 1, destination: other }),
).rejects.toMatchObject({ code: 'destination_not_whitelisted' });
});
it('allows a withdraw to an allowlisted destination', async () => {
const allowed = Keypair.generate().publicKey.toBase58();
serveAllowlist({ entry: activeEntry(allowed) });
const r = await enforceSpendLimit({ agentId: 'a', limits: noLimits, category: 'withdraw', usdValue: 1, destination: allowed });
expect(r.ok).toBe(true);
});
it('does not gate non-withdraw paths on the withdraw allowlist', async () => {
const allowed = Keypair.generate().publicKey.toBase58();
const r = await enforceSpendLimit({ agentId: 'a', limits: { ...noLimits, withdraw_allowlist: [allowed] }, category: 'x402', usdValue: 1, destination: 'whatever' });
expect(r.ok).toBe(true);
});
it('blocks when the rolling daily total would exceed the cap', async () => {
sqlState.queue.push([{ usd: 30 }]); // already spent today
await expect(
enforceSpendLimit({ agentId: 'a', limits: { ...noLimits, daily_usd: 50 }, category: 'snipe', usdValue: 25, network: 'mainnet' }),
).rejects.toMatchObject({ code: 'daily_exceeded' });
});
it('allows when the daily total stays within the cap', async () => {
sqlState.queue.push([{ usd: 10 }]);
const r = await enforceSpendLimit({ agentId: 'a', limits: { ...noLimits, daily_usd: 50 }, category: 'snipe', usdValue: 25 });
expect(r.ok).toBe(true);
expect(r.dailySpentUsd).toBe(10);
});
it('skips the USD ceilings for an unpriceable asset (allowlist still applies)', async () => {
// usdValue null → daily/per-tx ceilings can't be evaluated and must not throw.
// The behavioral anomaly guard still runs (it scores destination/velocity, which
// matter regardless of price), but the daily USD ledger must never be summed.
const r = await enforceSpendLimit({ agentId: 'a', limits: { ...noLimits, daily_usd: 1, per_tx_usd: 1 }, category: 'withdraw', usdValue: null, destination: Keypair.generate().publicKey.toBase58() });
expect(r.ok).toBe(true);
const summedLedger = sqlState.calls.some((c) => /SUM\(usd\)/.test(c.query) && /agent_custody_events/.test(c.query));
expect(summedLedger).toBe(false); // never summed the USD ledger for an unpriceable spend
});
it('SpendLimitError is the exported class with the breach detail', async () => {
try {
await enforceSpendLimit({ agentId: 'a', limits: { daily_usd: null, per_tx_usd: 5, withdraw_allowlist: [] }, category: 'trade', usdValue: 50 });
throw new Error('should have thrown');
} catch (e) {
expect(e).toBeInstanceOf(SpendLimitError);
expect(e.detail.per_tx_usd).toBe(5);
expect(e.detail.usd).toBe(50);
}
});
});
// ── ledger reads ────────────────────────────────────────────────────────────────
describe('getDailySpendUsd / lamportsToUsd', () => {
it('returns the summed USD from the ledger', async () => {
sqlState.queue.push([{ usd: 123.45 }]);
expect(await getDailySpendUsd('a', 'mainnet')).toBe(123.45);
});
it('treats a null sum as zero', async () => {
sqlState.queue.push([{ usd: null }]);
expect(await getDailySpendUsd('a')).toBe(0);
});
it('converts lamports to USD at the live price', async () => {
// 1 SOL at the mocked $200
expect(await lamportsToUsd(1_000_000_000n)).toBeCloseTo(200, 6);
});
});
// ── wallet freeze (kill switch) ──────────────────────────────────────────────
describe('wallet freeze', () => {
it('normalizes frozen to a strict boolean (default false)', () => {
expect(normalizeSpendLimits({}).frozen).toBe(false);
expect(normalizeSpendLimits({ frozen: true }).frozen).toBe(true);
expect(normalizeSpendLimits({ frozen: 'yes' }).frozen).toBe(false); // only literal true freezes
});
it('blocks an autonomous trade when frozen', async () => {
const limits = normalizeSpendLimits({ frozen: true });
await expect(
enforceSpendLimit({ agentId: 'a', limits, category: 'trade', usdValue: 1 }),
).rejects.toMatchObject({ code: 'wallet_frozen', status: 403 });
});
it('blocks snipe and x402 when frozen', async () => {
const limits = normalizeSpendLimits({ frozen: true });
for (const category of ['snipe', 'x402']) {
await expect(
enforceSpendLimit({ agentId: 'a', limits, category, usdValue: 5 }),
).rejects.toMatchObject({ code: 'wallet_frozen' });
}
});
it('NEVER blocks the owner withdraw when frozen (funds must stay evacuable)', async () => {
const limits = normalizeSpendLimits({ frozen: true });
const r = await enforceSpendLimit({ agentId: 'a', limits, category: 'withdraw', usdValue: 10, destination: Keypair.generate().publicKey.toBase58() });
expect(r.ok).toBe(true);
});
it('fails closed when the agent row is gone and the caller supplied no meta', async () => {
sqlState.agentGone = true;
const limits = normalizeSpendLimits({});
await expect(
enforceSpendLimit({ agentId: 'a', limits, category: 'trade', usdValue: 1 }),
).rejects.toMatchObject({ code: 'agent_not_found' });
});
it('does not block any path when not frozen', async () => {
const limits = normalizeSpendLimits({ frozen: false });
const r = await enforceSpendLimit({ agentId: 'a', limits, category: 'trade', usdValue: 1 });
expect(r.ok).toBe(true);
});
});