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
// The /api/vaults write routes take caller-supplied ids and amounts and hand them
// straight to a uuid column or to BigInt(). Before this file, a single malformed
// field ("vaultId":"not-a-uuid", "shares":"abc") raised a NeonDbError / SyntaxError
// that the wrapper turned into a 500 with a support ref, on four separate routes;
// a non-uuid agentId leaked the raw Postgres code 22P02 back to the caller as the
// error code. These tests pin the boundary: malformed input answers 4xx JSON, the
// good path still reaches the settlement layer untouched, and the owner's terms
// PATCH can never write a NaN into an integer column.
import { describe, it, expect, vi, beforeEach } from 'vitest';
const VAULT = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa';
const AGENT = 'bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb';
const USER = 'cccccccc-cccc-4ccc-8ccc-cccccccccccc';
const MINT = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';
const authWriteMock = vi.fn();
const resolveUserIdMock = vi.fn();
const loadOwnedAgentMock = vi.fn();
// The real-funds agreement gate is covered by tests/real-funds-agreement.test.js;
// here the account has signed, so the handler's own guards are what is under test.
vi.mock('../api/_lib/real-funds-agreement.js', () => ({
requireRealFundsAgreement: vi.fn(async () => true),
currentSignatureFor: vi.fn(async () => ({ signedAt: '2026-09-17T00:00:00.000Z', signatureName: 'Test Signer', context: null })),
agreementRequirement: () => ({ version: 2, sign_url: 'https://three.ws/legal/agreements', documents: [] }),
}));
vi.mock('../api/_lib/vault-auth.js', () => ({
authWrite: (...a) => authWriteMock(...a),
resolveUserId: (...a) => resolveUserIdMock(...a),
loadOwnedAgent: (...a) => loadOwnedAgentMock(...a),
loadAgent: vi.fn(async () => ({ id: AGENT, name: 'Anchor', description: null, image: null })),
assertReputationVerified: vi.fn(async () => true),
traderBadge: vi.fn(async () => null),
}));
const getVaultMock = vi.fn();
const updateVaultTermsMock = vi.fn();
vi.mock('../api/_lib/vault-store.js', () => ({
getVault: (...a) => getVaultMock(...a),
updateVaultTerms: (...a) => updateVaultTermsMock(...a),
recordVaultEvent: vi.fn(async () => ({})),
getOpenPositions: vi.fn(async () => []),
getBacker: vi.fn(async () => null),
listBackers: vi.fn(async () => []),
setVaultStatus: vi.fn(async () => ({})),
createVault: vi.fn(async () => ({ id: VAULT })),
listVaults: vi.fn(async () => []),
listBackedVaults: vi.fn(async () => []),
}));
const depositToVaultMock = vi.fn(async () => ({ status: 'settled', shares: '1' }));
const redeemFromVaultMock = vi.fn(async () => ({ status: 'settled', net_atomics: '1' }));
const claimVaultFeesMock = vi.fn(async () => ({ status: 'settled', atomics: '1' }));
vi.mock('../api/_lib/vault-transfer.js', () => ({
depositToVault: (...a) => depositToVaultMock(...a),
redeemFromVault: (...a) => redeemFromVaultMock(...a),
claimVaultFees: (...a) => claimVaultFeesMock(...a),
}));
const vaultTradeMock = vi.fn(async () => ({ status: 'filled', signature: 'sig' }));
vi.mock('../api/_lib/vault-trade.js', () => ({ vaultTrade: (...a) => vaultTradeMock(...a) }));
vi.mock('../api/_lib/vault-wallet.js', () => ({
generateVaultWallet: vi.fn(async () => ({ address: 'Vau1t', encrypted_secret: 'enc' })),
computeVaultNav: vi.fn(async () => ({ navAtomics: 0n, freeAtomics: 0n, usdcAtomics: 0n, priced: true, positions: [] })),
}));
vi.mock('../api/_lib/rate-limit.js', () => ({
limits: { tradePerUser: vi.fn(async () => ({ success: true, reset: 1_000 })) },
clientIp: () => '203.0.113.9',
}));
const { default: depositHandler } = await import('../api/vaults/deposit.js');
const { default: redeemHandler } = await import('../api/vaults/redeem.js');
const { default: tradeHandler } = await import('../api/vaults/trade.js');
const { default: claimFeesHandler } = await import('../api/vaults/claim-fees.js');
const { default: vaultsHandler } = await import('../api/vaults/index.js');
const { default: vaultDetailHandler } = await import('../api/vaults/[id].js');
function mkReq({ method = 'POST', url = '/api/vaults', body = null, headers = {} } = {}) {
const hdrs = { ...headers };
if (body != null && !hdrs['content-type']) hdrs['content-type'] = 'application/json';
return {
method, url, headers: hdrs,
on(event, cb) {
if (event === 'data' && body != null) {
const buf = Buffer.from(typeof body === 'string' ? body : JSON.stringify(body));
queueMicrotask(() => { cb(buf); this._endCb?.(); });
} else if (event === 'end') {
this._endCb = cb;
if (body == null) queueMicrotask(() => cb());
}
},
destroy() {},
};
}
function mkRes() {
return {
statusCode: 200, headers: {}, body: undefined, writableEnded: false, headersSent: false,
setHeader(k, v) { this.headers[k.toLowerCase()] = v; },
end(b) { this.body = b; this.writableEnded = true; this.headersSent = true; },
};
}
const parse = (res) => (res.body ? JSON.parse(res.body) : undefined);
async function call(handler, req) {
const res = mkRes();
await handler(req, res);
return { res, out: parse(res) };
}
const OPEN_VAULT = {
id: VAULT, agent_id: AGENT, owner_user_id: USER, network: 'mainnet', status: 'open',
performance_fee_bps: 1000, max_drawdown_bps: 2500, per_backer_cap_atomics: null,
max_per_trade_atomics: '5000000', daily_budget_atomics: '50000000',
total_shares: '0', peak_share_price_e6: '1000000', accrued_fee_atomics: '0',
halt_reason: null, paused_at: null, created_at: new Date('2026-08-01T00:00:00Z'),
vault_address: 'Vau1t',
};
beforeEach(() => {
vi.clearAllMocks();
// A bearer that holds the spend grant; the connector case below holds none.
authWriteMock.mockResolvedValue({ userId: USER, session: false, scope: 'wallet:read wallet:write' });
resolveUserIdMock.mockResolvedValue({ userId: USER, session: false });
loadOwnedAgentMock.mockResolvedValue({
id: AGENT, user_id: USER, name: 'Anchor',
meta: { solana_address: 'Ag3nt', encrypted_solana_secret: 'enc' },
});
getVaultMock.mockResolvedValue(OPEN_VAULT);
// The real store returns a row whose numeric(40,0) columns are plain strings,
// so the handler's JSON response never sees a BigInt.
updateVaultTermsMock.mockImplementation(async (_id, patch) => ({
...OPEN_VAULT,
performance_fee_bps: patch.performanceFeeBps ?? OPEN_VAULT.performance_fee_bps,
max_drawdown_bps: patch.maxDrawdownBps ?? OPEN_VAULT.max_drawdown_bps,
max_per_trade_atomics: String(patch.maxPerTradeAtomics ?? OPEN_VAULT.max_per_trade_atomics),
daily_budget_atomics: String(patch.dailyBudgetAtomics ?? OPEN_VAULT.daily_budget_atomics),
}));
});
describe('malformed ids never reach a uuid column', () => {
it('POST /api/vaults/deposit rejects a non-uuid vaultId and backerAgentId with 400', async () => {
const a = await call(depositHandler, mkReq({ url: '/api/vaults/deposit', body: { vaultId: 'not-a-uuid', backerAgentId: AGENT, usdc: 1 } }));
expect(a.res.statusCode).toBe(400);
expect(a.out.error).toBe('validation_error');
const b = await call(depositHandler, mkReq({ url: '/api/vaults/deposit', body: { vaultId: VAULT, backerAgentId: 'nope', usdc: 1 } }));
expect(b.res.statusCode).toBe(400);
expect(b.out.error).toBe('validation_error');
expect(getVaultMock).not.toHaveBeenCalled();
expect(depositToVaultMock).not.toHaveBeenCalled();
});
it('POST /api/vaults/redeem rejects a non-uuid vaultId with 400', async () => {
const { res, out } = await call(redeemHandler, mkReq({ url: '/api/vaults/redeem', body: { vaultId: 'not-a-uuid' } }));
expect(res.statusCode).toBe(400);
expect(out.error).toBe('validation_error');
expect(redeemFromVaultMock).not.toHaveBeenCalled();
});
it('POST /api/vaults/trade rejects a non-uuid vaultId and a non-address mint with 400', async () => {
const a = await call(tradeHandler, mkReq({ url: '/api/vaults/trade', body: { vaultId: 'not-a-uuid', side: 'buy', mint: MINT, usdc: 1 } }));
expect(a.res.statusCode).toBe(400);
const b = await call(tradeHandler, mkReq({ url: '/api/vaults/trade', body: { vaultId: VAULT, side: 'buy', mint: 'x', usdc: 1 } }));
expect(b.res.statusCode).toBe(400);
expect(b.out.error_description).toMatch(/mint/);
expect(vaultTradeMock).not.toHaveBeenCalled();
});
it('POST /api/vaults/claim-fees rejects a non-uuid vaultId and toAgentId with 400', async () => {
const a = await call(claimFeesHandler, mkReq({ url: '/api/vaults/claim-fees', body: { vaultId: 'not-a-uuid', toAgentId: AGENT } }));
expect(a.res.statusCode).toBe(400);
const b = await call(claimFeesHandler, mkReq({ url: '/api/vaults/claim-fees', body: { vaultId: VAULT, toAgentId: 'nope' } }));
expect(b.res.statusCode).toBe(400);
expect(claimVaultFeesMock).not.toHaveBeenCalled();
});
it('POST /api/vaults rejects a non-uuid agentId instead of leaking the Postgres 22P02 code', async () => {
const { res, out } = await call(vaultsHandler, mkReq({ body: { agentId: 'nope', maxPerTradeUsdc: 1, dailyBudgetUsdc: 2 } }));
expect(res.statusCode).toBe(400);
expect(out.error).toBe('validation_error');
expect(loadOwnedAgentMock).not.toHaveBeenCalled();
});
});
describe('caller-supplied amounts are parsed at the boundary', () => {
it('rejects a non-numeric shares value instead of throwing inside BigInt()', async () => {
const { res, out } = await call(redeemHandler, mkReq({ url: '/api/vaults/redeem', body: { vaultId: VAULT, shares: 'abc' } }));
expect(res.statusCode).toBe(400);
expect(out.error_description).toMatch(/shares/);
expect(redeemFromVaultMock).not.toHaveBeenCalled();
});
it('rejects a non-numeric sell amount on a vault the caller really owns', async () => {
const { res, out } = await call(tradeHandler, mkReq({ url: '/api/vaults/trade', body: { vaultId: VAULT, side: 'sell', mint: MINT, amount: 'abc' } }));
expect(res.statusCode).toBe(400);
expect(out.error_description).toMatch(/amount/);
expect(vaultTradeMock).not.toHaveBeenCalled();
});
it('passes a real redemption through untouched: "max" stays max, a number stays exact', async () => {
await call(redeemHandler, mkReq({ url: '/api/vaults/redeem', body: { vaultId: VAULT } }));
expect(redeemFromVaultMock).toHaveBeenLastCalledWith(expect.objectContaining({ vaultId: VAULT, userId: USER, shares: 'max' }));
await call(redeemHandler, mkReq({ url: '/api/vaults/redeem', body: { vaultId: VAULT, shares: '2500000' } }));
expect(redeemFromVaultMock).toHaveBeenLastCalledWith(expect.objectContaining({ shares: '2500000' }));
});
it('passes a real sell through as an exact BigInt of raw token units', async () => {
const { res } = await call(tradeHandler, mkReq({ url: '/api/vaults/trade', body: { vaultId: VAULT, side: 'sell', mint: MINT, amount: '123456789' } }));
expect(res.statusCode).toBe(200);
expect(vaultTradeMock).toHaveBeenLastCalledWith(expect.objectContaining({ side: 'sell', mint: MINT, amountRaw: 123456789n }));
});
});
describe('PATCH /api/vaults/:id terms', () => {
const patchReq = (body) => mkReq({ method: 'PATCH', url: `/api/vaults/${VAULT}`, body });
it('refuses a terms change from a bearer without wallet:write, and still lets it pause', async () => {
authWriteMock.mockResolvedValue({ userId: USER, session: false, scope: 'avatars:read agents:write connector' });
const { res, out } = await call(vaultDetailHandler, patchReq({ action: 'terms', maxPerTradeUsdc: 10 }));
expect(res.statusCode).toBe(403);
expect(out.error).toBe('insufficient_scope');
expect(out.error_description).toContain('wallet:write');
expect(updateVaultTermsMock).not.toHaveBeenCalled();
const paused = await call(vaultDetailHandler, patchReq({ action: 'pause' }));
expect(paused.res.statusCode).not.toBe(403);
});
it('refuses a non-numeric bps term instead of writing NaN into an integer column', async () => {
const a = await call(vaultDetailHandler, patchReq({ action: 'terms', performanceFeeBps: 'abc' }));
expect(a.res.statusCode).toBe(400);
const b = await call(vaultDetailHandler, patchReq({ action: 'terms', maxDrawdownBps: 'abc' }));
expect(b.res.statusCode).toBe(400);
expect(updateVaultTermsMock).not.toHaveBeenCalled();
});
it('refuses a non-positive spend term rather than silently ignoring it', async () => {
const { res, out } = await call(vaultDetailHandler, patchReq({ action: 'terms', maxPerTradeUsdc: -5 }));
expect(res.statusCode).toBe(400);
expect(out.error_description).toMatch(/maxPerTradeUsdc/);
expect(updateVaultTermsMock).not.toHaveBeenCalled();
});
it('refuses a per-trade ceiling above the daily budget, counting the terms already stored', async () => {
// Stored budget is 50 USDC; a 60 USDC per-trade ceiling would let one trade
// blow the whole day's limit.
const { res } = await call(vaultDetailHandler, patchReq({ action: 'terms', maxPerTradeUsdc: 60 }));
expect(res.statusCode).toBe(400);
expect(updateVaultTermsMock).not.toHaveBeenCalled();
});
it('clamps a legal-but-extreme fee into bounds and applies it', async () => {
const { res } = await call(vaultDetailHandler, patchReq({ action: 'terms', performanceFeeBps: 9999 }));
expect(res.statusCode).toBe(200);
expect(updateVaultTermsMock).toHaveBeenCalledWith(VAULT, expect.objectContaining({ performanceFeeBps: 5000 }));
});
it('applies a matched per-trade + daily budget raise', async () => {
const { res } = await call(vaultDetailHandler, patchReq({ action: 'terms', maxPerTradeUsdc: 60, dailyBudgetUsdc: 600 }));
expect(res.statusCode).toBe(200);
expect(updateVaultTermsMock).toHaveBeenCalledWith(VAULT, expect.objectContaining({
maxPerTradeAtomics: 60_000_000n, dailyBudgetAtomics: 600_000_000n,
}));
});
describe('once backers hold shares, the owner cannot loosen the terms they joined under', () => {
const BACKED = { ...OPEN_VAULT, total_shares: '5000000' };
it('refuses a fee, drawdown or budget increase with 409 and writes nothing', async () => {
for (const patch of [
{ performanceFeeBps: 2000 },
{ maxDrawdownBps: 5000 },
{ maxPerTradeUsdc: 20 },
{ dailyBudgetUsdc: 500 },
]) {
getVaultMock.mockResolvedValue(BACKED);
const { res, out } = await call(vaultDetailHandler, patchReq({ action: 'terms', ...patch }));
expect(res.statusCode, JSON.stringify(patch)).toBe(409);
expect(out.error).toBe('terms_locked_for_backers');
}
expect(updateVaultTermsMock).not.toHaveBeenCalled();
});
it('still lets the owner tighten terms or leave them unchanged', async () => {
getVaultMock.mockResolvedValue(BACKED);
const { res } = await call(vaultDetailHandler, patchReq({ action: 'terms', performanceFeeBps: 500, maxDrawdownBps: 1000, maxPerTradeUsdc: 2, dailyBudgetUsdc: 20 }));
expect(res.statusCode).toBe(200);
expect(updateVaultTermsMock).toHaveBeenCalledTimes(1);
});
});
it('answers 404 for a malformed vault id in the path, never a database error', async () => {
const { res, out } = await call(vaultDetailHandler, mkReq({ method: 'PATCH', url: '/api/vaults/not-a-uuid', body: { action: 'pause' } }));
expect(res.statusCode).toBe(404);
expect(out.error).toBe('not_found');
expect(getVaultMock).not.toHaveBeenCalled();
});
});