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
import { describe, it, expect, beforeAll } from 'vitest';
import { Keypair, PublicKey, VersionedTransaction } from '@solana/web3.js';
import { getAssociatedTokenAddressSync, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID } from '@solana/spl-token';
// Fee-floor regression + self-pay + ATA-reclaim safety for the closed x402 ring.
// The rule under test is "the lowest fees ALWAYS": 1-signature self-pay
// settlement pinned at the floor, a hard per-tx fee ceiling the builders can
// never cross, and a rent reclaim that can NEVER close a funded or active ATA.
// Pure logic — no DB, no chain.
const USDC = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
process.env.X402_ASSET_MINT_SOLANA = USDC;
const pay = await import('../api/_lib/x402/pay.js');
const {
expectedFeeLamports, ringPriorityMicrolamports, ringSelfPayDefault,
ringMaxFeePerTxLamports, buildPaymentTx, SIGNATURE_FEE_LAMPORTS, RING_CU_LIMIT,
} = pay;
const { validateRingTransaction } = await import('../api/_lib/x402/self-facilitator.js');
const {
computeFeeEfficiency, selectClosableAtas, activeRoleAtas, FEE_AUDIT,
} = await import('../api/_lib/x402/pipelines/fee-audit.js');
const solAddr = () => Keypair.generate().publicKey.toBase58();
const ataFor = (mint, owner) => getAssociatedTokenAddressSync(
new PublicKey(mint), new PublicKey(owner), false, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID,
).toBase58();
describe('expectedFeeLamports — the fee-floor math', () => {
it('self-pay is 1 signature = 5,000 lamports + priority', () => {
expect(expectedFeeLamports({ selfPay: true, priorityMicrolamports: 0, cuLimit: RING_CU_LIMIT })).toBe(5000);
// Baseline priority (5 µlamports × 60k CU = 0.3 lamports → floors to 0).
expect(expectedFeeLamports({ selfPay: true, priorityMicrolamports: 5, cuLimit: RING_CU_LIMIT })).toBe(5000);
});
it('sponsor mode is 2 signatures = 10,000 lamports + priority', () => {
expect(expectedFeeLamports({ selfPay: false, priorityMicrolamports: 0, cuLimit: RING_CU_LIMIT })).toBe(10000);
});
it('worst-case priority perturbation stays negligible', () => {
// The nonce perturbation tops out at 1001 µlamports (5 + 996).
const worst = expectedFeeLamports({ selfPay: true, priorityMicrolamports: 1001, cuLimit: RING_CU_LIMIT });
expect(worst).toBe(5060); // 5000 + floor(1001*60000/1e6=60.06)=60
expect(worst).toBeLessThanOrEqual(5100); // acceptance bar for a self-paid settle
});
});
describe('fee-floor regression guard — builders never exceed the ceiling', () => {
const ceiling = ringMaxFeePerTxLamports(); // 10,000 default
it('every nonce in a batch keeps a self-paid tx under the ceiling', () => {
for (let nonce = 0; nonce < 997; nonce++) {
const fee = expectedFeeLamports({
selfPay: true,
priorityMicrolamports: ringPriorityMicrolamports(nonce),
cuLimit: RING_CU_LIMIT,
});
expect(fee).toBeLessThanOrEqual(ceiling);
expect(fee).toBeLessThanOrEqual(5100); // and under the self-pay acceptance bar
}
});
it('sponsor mode at the baseline priority sits exactly at the ceiling, never above', () => {
for (let nonce = 0; nonce < 997; nonce++) {
const fee = expectedFeeLamports({
selfPay: false,
priorityMicrolamports: ringPriorityMicrolamports(nonce),
cuLimit: RING_CU_LIMIT,
});
// 10,000 base + up to 60 priority = 10,060 — this is why the ceiling
// default (10,000) is the SELF-PAY-mode guarantee; sponsor mode is the
// fallback and its priority is bounded by the facilitator guard instead.
expect(fee).toBeLessThanOrEqual(10_060);
}
});
});
describe('distinct-signature guard — same-amount payments must never collide', () => {
// Two payments with the same payer/payTo/mint/amount, one shared blockhash
// and the same nonce compile to byte-identical transactions → the SAME
// signature → every one after the first dies at settle preflight as
// already-processed. payX402 defaults callers onto nextAutoNonce() so this
// can only happen when a batch pipeline reuses an explicit position.
const buyer = Keypair.generate();
const treasury = Keypair.generate();
const blockhash = '11111111111111111111111111111111';
const accept = {
network: 'solana:mainnet',
asset: USDC,
payTo: treasury.publicKey.toBase58(),
amount: '10000', // $0.01 — the ring's most common price, the collision class
extra: {},
};
const build = (nonce) => buildPaymentTx({
accept, buyer, blockhash,
mintInfo: { decimals: 6 }, receiverAtaExists: true, nonce, selfPay: true,
});
it('equal nonces compile to byte-identical txs (the collision the guard exists for)', () => {
expect(build(7)).toBe(build(7));
});
it('distinct nonces produce distinct signatures', () => {
const a = VersionedTransaction.deserialize(Buffer.from(build(1), 'base64'));
const b = VersionedTransaction.deserialize(Buffer.from(build(2), 'base64'));
expect(Buffer.from(a.signatures[0]).equals(Buffer.from(b.signatures[0]))).toBe(false);
});
it('nextAutoNonce never repeats within a blockhash-sized window and stays in the fee-tested range', () => {
// The nonce space widened from a 997-slot per-process cycle to ~4.08M slots
// drawn with a CSPRNG (2026-07-29). The old sequential counter started at the
// same value on every Cloud Run instance, so two instances paying the same
// endpoint the same amount in one blockhash window built IDENTICAL
// transactions — the mechanism behind the duplicate-settle defect. What must
// still hold is the pair of properties this test has always guarded: no
// repeats inside a window, and every drawn nonce maps to a fee-safe config.
const SAMPLE = 200;
const seen = new Set();
const ceiling = ringMaxFeePerTxLamports();
for (let i = 0; i < SAMPLE; i++) {
const n = pay.nextAutoNonce();
expect(n).toBeGreaterThanOrEqual(0);
expect(n).toBeLessThan(pay.RING_NONCE_SPACE);
for (const selfPay of [true, false]) {
const { microLamports, cuLimit } = pay.ringFeeConfig(n, { selfPay });
expect(expectedFeeLamports({ selfPay, priorityMicrolamports: microLamports, cuLimit }))
.toBeLessThanOrEqual(ceiling);
}
seen.add(n);
}
// Draws are independent, so demanding 200/200 distinct values asserts a
// property a CSPRNG cannot promise: with a 4.08M slot space the birthday
// bound puts one repeat in a 200-draw sample at ~0.5%, which made this
// test fail roughly once every two hundred suite runs on nothing but luck.
// Two repeats is ~1e-5, so that is the line: it still catches a genuinely
// narrowed space (a regression to the old 997-slot cycle collides ~87% of
// the time here) without failing on the sampling itself.
expect(SAMPLE - seen.size).toBeLessThanOrEqual(1);
});
});
describe('self-pay default — operative for the ring', () => {
it('defaults to true when X402_RING_SELF_PAY is unset', () => {
delete process.env.X402_RING_SELF_PAY;
expect(ringSelfPayDefault()).toBe(true);
});
it('honors an explicit false (sponsor mode still selectable)', () => {
process.env.X402_RING_SELF_PAY = 'false';
expect(ringSelfPayDefault()).toBe(false);
process.env.X402_RING_SELF_PAY = 'FALSE';
expect(ringSelfPayDefault()).toBe(false);
delete process.env.X402_RING_SELF_PAY;
});
it('treats true/1/anything-else as self-pay', () => {
process.env.X402_RING_SELF_PAY = 'true';
expect(ringSelfPayDefault()).toBe(true);
delete process.env.X402_RING_SELF_PAY;
});
});
describe('self-pay build → facilitator validate roundtrip (zero sponsor)', () => {
const buyer = Keypair.generate();
const treasury = Keypair.generate();
const sponsor = Keypair.generate();
const blockhash = '11111111111111111111111111111111'; // any valid base58 32-byte-ish
const accept = {
network: 'solana:mainnet',
asset: USDC,
payTo: treasury.publicKey.toBase58(),
amount: '1000000', // $1.00
extra: { feePayer: sponsor.publicKey.toBase58() },
};
const requirement = { network: 'solana:mainnet', asset: USDC, payTo: accept.payTo, amount: '1000000' };
const allowlist = new Set([accept.payTo]);
it('a self-paid tx validates as self-pay with a 1-signature fee, no sponsor needed', () => {
const txBase64 = buildPaymentTx({
accept, buyer, blockhash,
mintInfo: { decimals: 6 }, receiverAtaExists: true, nonce: 0, selfPay: true,
});
const v = validateRingTransaction({
txBase64, requirement,
feePayerPubkey: null, // no sponsor advertised — self-pay must not need one
allowlist,
});
expect(v.ok).toBe(true);
expect(v.decoded.selfPay).toBe(true);
expect(v.decoded.payer).toBe(buyer.publicKey.toBase58());
expect(v.decoded.feePayer).toBe(buyer.publicKey.toBase58());
// 1 signature × 5000 + negligible priority, no ATA create.
expect(v.decoded.estFeeLamports).toBeLessThanOrEqual(5100);
expect(v.decoded.estFeeLamports).toBeGreaterThanOrEqual(SIGNATURE_FEE_LAMPORTS);
});
it('sponsor mode still validates (the gasless-buyer fallback is intact)', () => {
const txBase64 = buildPaymentTx({
accept, buyer, blockhash,
mintInfo: { decimals: 6 }, receiverAtaExists: true, nonce: 0, selfPay: false,
});
const v = validateRingTransaction({
txBase64, requirement,
feePayerPubkey: sponsor.publicKey.toBase58(),
allowlist,
});
expect(v.ok).toBe(true);
expect(v.decoded.selfPay).toBe(false);
expect(v.decoded.feePayer).toBe(sponsor.publicKey.toBase58());
expect(v.decoded.estFeeLamports).toBeLessThanOrEqual(10_100);
});
});
describe('validateRingTransaction — totality: malformed input is a clean refusal, never a throw', () => {
const buyer = Keypair.generate();
const treasury = Keypair.generate();
const sponsor = Keypair.generate();
const blockhash = '11111111111111111111111111111111';
const accept = {
network: 'solana:mainnet',
asset: USDC,
payTo: treasury.publicKey.toBase58(),
amount: '1000000',
extra: { feePayer: sponsor.publicKey.toBase58() },
};
const requirement = { network: 'solana:mainnet', asset: USDC, payTo: accept.payTo, amount: '1000000' };
const allowlist = new Set([accept.payTo]);
// Deserialize a valid ring tx, mutate its message, re-serialize to base64.
// The facilitator never verifies signatures, so a tampered message still
// exercises the decode path — exactly the adversarial surface at issue.
const tamperedTxBase64 = (mutate) => {
const good = buildPaymentTx({
accept, buyer, blockhash,
mintInfo: { decimals: 6 }, receiverAtaExists: true, nonce: 0, selfPay: true,
});
const tx = VersionedTransaction.deserialize(Buffer.from(good, 'base64'));
mutate(tx.message);
return Buffer.from(tx.serialize()).toString('base64');
};
it('an out-of-range programIdIndex refuses cleanly instead of throwing a TypeError', () => {
const txBase64 = tamperedTxBase64((msg) => {
msg.compiledInstructions[0].programIdIndex = msg.staticAccountKeys.length + 5;
});
let v;
expect(() => {
v = validateRingTransaction({ txBase64, requirement, feePayerPubkey: null, allowlist });
}).not.toThrow();
expect(v.ok).toBe(false);
expect(v.reason).toMatch(/malformed_instruction|decode_error/);
});
it('a truncated account-index list on the transfer instruction refuses cleanly', () => {
const txBase64 = tamperedTxBase64((msg) => {
// Find the SPL TransferChecked instruction (data[0] === 12) and starve it.
const ix = msg.compiledInstructions.find((i) => i.data?.[0] === 12);
if (ix) ix.accountKeyIndexes = ix.accountKeyIndexes.slice(0, 1);
});
let v;
expect(() => {
v = validateRingTransaction({ txBase64, requirement, feePayerPubkey: null, allowlist });
}).not.toThrow();
expect(v.ok).toBe(false);
expect(v.reason).toMatch(/malformed_instruction|decode_error/);
});
it('the valid self-pay path is unaffected by the bounds guards', () => {
const good = buildPaymentTx({
accept, buyer, blockhash,
mintInfo: { decimals: 6 }, receiverAtaExists: true, nonce: 0, selfPay: true,
});
const v = validateRingTransaction({ txBase64: good, requirement, feePayerPubkey: null, allowlist });
expect(v.ok).toBe(true);
expect(v.decoded.payer).toBe(buyer.publicKey.toBase58());
});
});
describe('computeFeeEfficiency — the measured numbers', () => {
it('derives lamports-per-settlement and sol-per-$100 from real totals', () => {
// 100 settlements, 5,000 lamports each = 500,000 lamports on $100 gross.
const e = computeFeeEfficiency({
feesLamports: 500_000, settlements: 100, grossVolumeAtomic: 100_000_000, budgetLamports: 50_000_000,
});
expect(e.lamports_per_settlement).toBe(5000);
expect(e.sol_burned).toBeCloseTo(0.0005, 9);
// 0.0005 SOL on $100 gross → 0.0005 SOL per $100.
expect(e.sol_per_100_usd).toBeCloseTo(0.0005, 9);
expect(e.above_floor).toBe(false);
expect(e.over_budget).toBe(false);
});
it('flags above_floor when per-settlement fee exceeds 1.5× the 1-sig floor', () => {
const e = computeFeeEfficiency({ feesLamports: 8000 * 10, settlements: 10, grossVolumeAtomic: 10_000_000 });
expect(e.lamports_per_settlement).toBe(8000);
expect(e.above_floor).toBe(true); // 8000 > 7500
});
it('flags over_budget when daily burn exceeds the budget', () => {
const e = computeFeeEfficiency({
feesLamports: 60_000_000, settlements: 10_000, grossVolumeAtomic: 1_000_000_000, budgetLamports: 50_000_000,
});
expect(e.over_budget).toBe(true); // 0.06 SOL > 0.05 SOL budget
});
it('never divides by zero — no settlements / no volume yields nulls, not NaN', () => {
const e = computeFeeEfficiency({ feesLamports: 0, settlements: 0, grossVolumeAtomic: 0 });
expect(e.lamports_per_settlement).toBeNull();
expect(e.sol_per_100_usd).toBeNull();
expect(e.above_floor).toBe(false);
});
});
describe('ATA rent reclaim — SAFETY: never closes a funded or active ATA', () => {
const payer = solAddr();
const treasury = solAddr();
const sponsor = solAddr();
const activeSet = activeRoleAtas({ mint: USDC, owners: [payer, treasury, sponsor] });
it('computes exactly the three canonical role ATAs', () => {
expect(activeSet.size).toBe(3);
expect(activeSet.has(ataFor(USDC, payer))).toBe(true);
expect(activeSet.has(ataFor(USDC, treasury))).toBe(true);
expect(activeSet.has(ataFor(USDC, sponsor))).toBe(true);
});
it('NEVER returns an active role ATA even when it is empty', () => {
const accounts = [
{ pubkey: ataFor(USDC, payer), amount: 0n, mint: USDC }, // active + empty
{ pubkey: ataFor(USDC, treasury), amount: 0n, mint: USDC }, // active + empty
{ pubkey: ataFor(USDC, sponsor), amount: 0n, mint: USDC }, // active + empty
];
const closable = selectClosableAtas({ accounts, activeAtaSet: activeSet, mint: USDC, cap: 5 });
expect(closable).toEqual([]);
});
it('NEVER returns an account with a balance, active or not', () => {
const funded = solAddr();
const accounts = [
{ pubkey: ataFor(USDC, funded), amount: 1n, mint: USDC }, // non-role but funded
{ pubkey: ataFor(USDC, payer), amount: 1_000_000n, mint: USDC }, // active + funded
];
const closable = selectClosableAtas({ accounts, activeAtaSet: activeSet, mint: USDC, cap: 5 });
expect(closable).toEqual([]);
});
it('returns ONLY zero-balance, non-role ATAs', () => {
const stale1 = ataFor(USDC, solAddr());
const stale2 = ataFor(USDC, solAddr());
const accounts = [
{ pubkey: stale1, amount: 0n, mint: USDC }, // ✓ closable
{ pubkey: ataFor(USDC, payer), amount: 0n, mint: USDC }, // active — excluded
{ pubkey: stale2, amount: 0n, mint: USDC }, // ✓ closable
{ pubkey: ataFor(USDC, treasury), amount: 500n, mint: USDC }, // active + funded — excluded
];
const closable = selectClosableAtas({ accounts, activeAtaSet: activeSet, mint: USDC, cap: 5 });
expect(closable.sort()).toEqual([stale1, stale2].sort());
});
it('ignores accounts of a different mint', () => {
const OTHER = solAddr();
const accounts = [{ pubkey: solAddr(), amount: 0n, mint: OTHER }];
expect(selectClosableAtas({ accounts, activeAtaSet: activeSet, mint: USDC, cap: 5 })).toEqual([]);
});
it('caps the number of closes per run', () => {
const accounts = Array.from({ length: 12 }, () => ({ pubkey: ataFor(USDC, solAddr()), amount: 0n, mint: USDC }));
const closable = selectClosableAtas({ accounts, activeAtaSet: activeSet, mint: USDC, cap: FEE_AUDIT.maxClosesPerRun });
expect(closable.length).toBe(FEE_AUDIT.maxClosesPerRun);
expect(FEE_AUDIT.maxClosesPerRun).toBe(5);
});
});