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
// Tests for the settleability gate in verifyRingPayment
// (api/_lib/x402/self-facilitator.js).
//
// The paid flow is verify → run handler → settle. A static decode alone
// (validateRingTransaction) proves a payment is SHAPED right but not that it can
// actually settle, so a buyer could sign a well-formed TransferChecked from a
// ZERO-balance ATA, pass verify, make the expensive handler run (burning upstream
// provider spend), and only then have settle revert `insufficient funds`. The gate
// simulates the transaction on /verify and rejects anything that cannot settle,
// with a source-balance fallback when simulation RPC is unavailable and a
// fail-closed result when neither can run.
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import {
Keypair,
PublicKey,
TransactionInstruction,
TransactionMessage,
VersionedTransaction,
ComputeBudgetProgram,
} from '@solana/web3.js';
import {
TOKEN_PROGRAM_ID,
TOKEN_2022_PROGRAM_ID,
ASSOCIATED_TOKEN_PROGRAM_ID,
getAssociatedTokenAddressSync,
createAssociatedTokenAccountIdempotentInstruction,
createTransferCheckedInstruction,
} from '@solana/spl-token';
const { verifyRingPayment, validateRingTransaction } = await import('../api/_lib/x402/self-facilitator.js');
const DECIMALS = 6;
const AMOUNT_ATOMIC = 1000n; // 0.001 USDC
// The facilitator reads the mint account's owner to learn which token program
// the payment must call. These synthetic mints are modeled as classic SPL Token.
const classicMintOwner = async () => ({ owner: TOKEN_PROGRAM_ID });
// Build a real, buyer-signed SELF-PAY ring transaction: fee payer == the USDC
// authority, so no sponsor key is needed and validateRingTransaction accepts it as
// long as payTo is allowlisted. Returns the payment payload + requirement the
// facilitator consumes.
function buildSelfPayPayment({ amount = AMOUNT_ATOMIC } = {}) {
const buyer = Keypair.generate();
const recipientOwner = Keypair.generate();
const mint = Keypair.generate().publicKey;
const sourceAta = getAssociatedTokenAddressSync(mint, buyer.publicKey);
const destAta = getAssociatedTokenAddressSync(mint, recipientOwner.publicKey);
const transferIx = createTransferCheckedInstruction(
sourceAta, mint, destAta, buyer.publicKey, amount, DECIMALS,
);
// The facilitator only settles mints the platform issues 402s for (pinned
// to the configured env mints after the 2026-07-23 audit); model this
// synthetic mint as the configured one.
process.env.X402_ASSET_MINT_SOLANA = mint.toBase58();
const message = new TransactionMessage({
payerKey: buyer.publicKey,
recentBlockhash: '11111111111111111111111111111111',
instructions: [ComputeBudgetProgram.setComputeUnitLimit({ units: 60_000 }), transferIx],
}).compileToV0Message();
const tx = new VersionedTransaction(message);
tx.sign([buyer]);
return {
payTo: recipientOwner.publicKey.toBase58(),
feePayer: buyer.publicKey.toBase58(),
requirement: {
network: 'solana',
asset: mint.toBase58(),
amount: String(amount),
payTo: recipientOwner.publicKey.toBase58(),
},
paymentPayload: { transaction: Buffer.from(tx.serialize()).toString('base64') },
};
}
let prevPayTo;
let prevAssetMint;
let prevThreeMint;
let prevFeePayer;
beforeEach(() => {
prevPayTo = process.env.X402_PAY_TO_SOLANA;
prevAssetMint = process.env.X402_ASSET_MINT_SOLANA;
prevThreeMint = process.env.THREE_TOKEN_MINT;
prevFeePayer = process.env.X402_FEE_PAYER_SOLANA;
});
afterEach(() => {
if (prevPayTo === undefined) delete process.env.X402_PAY_TO_SOLANA;
else process.env.X402_PAY_TO_SOLANA = prevPayTo;
if (prevAssetMint === undefined) delete process.env.X402_ASSET_MINT_SOLANA;
else process.env.X402_ASSET_MINT_SOLANA = prevAssetMint;
if (prevThreeMint === undefined) delete process.env.THREE_TOKEN_MINT;
else process.env.THREE_TOKEN_MINT = prevThreeMint;
if (prevFeePayer === undefined) delete process.env.X402_FEE_PAYER_SOLANA;
else process.env.X402_FEE_PAYER_SOLANA = prevFeePayer;
});
describe('verifyRingPayment settleability gate', () => {
it('rejects a payment whose simulation reverts (zero-balance source ATA)', async () => {
const p = buildSelfPayPayment();
process.env.X402_PAY_TO_SOLANA = p.payTo;
// Simulation of a transfer from an unfunded ATA returns an InstructionError.
const conn = {
getAccountInfo: classicMintOwner,
simulateTransaction: async () => ({ value: { err: { InstructionError: [1, { Custom: 1 }] } } }),
getTokenAccountBalance: async () => { throw new Error('should not be called'); },
};
const res = await verifyRingPayment({
paymentPayload: p.paymentPayload,
requirement: p.requirement,
conn,
});
expect(res.isValid).toBe(false);
expect(res.invalidReason).toMatch(/^simulation_failed:/);
});
it('accepts a payment whose simulation succeeds (funded)', async () => {
const p = buildSelfPayPayment();
process.env.X402_PAY_TO_SOLANA = p.payTo;
const conn = {
getAccountInfo: classicMintOwner,
simulateTransaction: async () => ({ value: { err: null, logs: [] } }),
getTokenAccountBalance: async () => { throw new Error('should not be called'); },
};
const res = await verifyRingPayment({
paymentPayload: p.paymentPayload,
requirement: p.requirement,
conn,
});
expect(res.isValid).toBe(true);
expect(res.payer).toBeTruthy();
expect(res.asset).toBe(p.requirement.asset);
});
it('falls back to a source-balance read when simulation is unavailable — rejects a zero balance', async () => {
const p = buildSelfPayPayment();
process.env.X402_PAY_TO_SOLANA = p.payTo;
const conn = {
getAccountInfo: classicMintOwner,
simulateTransaction: async () => { throw new Error('rpc down'); },
getTokenAccountBalance: async () => ({ value: { amount: '0' } }),
};
const res = await verifyRingPayment({
paymentPayload: p.paymentPayload,
requirement: p.requirement,
conn,
});
expect(res.isValid).toBe(false);
expect(res.invalidReason).toMatch(/^insufficient_source_balance:/);
});
it('falls back to a source-balance read when simulation is unavailable — accepts a sufficient balance', async () => {
const p = buildSelfPayPayment();
process.env.X402_PAY_TO_SOLANA = p.payTo;
const conn = {
getAccountInfo: classicMintOwner,
simulateTransaction: async () => { throw new Error('rpc down'); },
getTokenAccountBalance: async () => ({ value: { amount: String(AMOUNT_ATOMIC) } }),
};
const res = await verifyRingPayment({
paymentPayload: p.paymentPayload,
requirement: p.requirement,
conn,
});
expect(res.isValid).toBe(true);
});
it('fails CLOSED when neither simulation nor balance read is available', async () => {
const p = buildSelfPayPayment();
process.env.X402_PAY_TO_SOLANA = p.payTo;
const conn = {
getAccountInfo: classicMintOwner,
simulateTransaction: async () => { throw new Error('rpc down'); },
getTokenAccountBalance: async () => { throw new Error('rpc down'); },
};
const res = await verifyRingPayment({
paymentPayload: p.paymentPayload,
requirement: p.requirement,
conn,
});
expect(res.isValid).toBe(false);
expect(res.invalidReason).toMatch(/^settle_precheck_unavailable:/);
});
it('still rejects a malformed static shape before ever simulating', async () => {
const p = buildSelfPayPayment();
process.env.X402_PAY_TO_SOLANA = p.payTo;
let simulated = false;
const conn = {
getAccountInfo: classicMintOwner,
simulateTransaction: async () => { simulated = true; return { value: { err: null } }; },
getTokenAccountBalance: async () => ({ value: { amount: '0' } }),
};
// payTo not in the allowlist → static validation must fail, no RPC touched.
const res = await verifyRingPayment({
paymentPayload: p.paymentPayload,
requirement: { ...p.requirement, payTo: Keypair.generate().publicKey.toBase58() },
conn,
});
expect(res.isValid).toBe(false);
expect(simulated).toBe(false);
});
});
describe('mint pin (2026-07-23 audit: junk-mint sponsor drain)', () => {
it('rejects a well-formed transfer whose mint is not a configured settleable asset', async () => {
const p = buildSelfPayPayment(); // sets X402_ASSET_MINT_SOLANA to its mint
process.env.X402_PAY_TO_SOLANA = p.payTo;
// Point the configured settleable mint ELSEWHERE: the tx's mint is now
// junk as far as the facilitator is concerned, which is exactly the
// attack shape — sponsor funds ATA rent + fees for a worthless token.
process.env.X402_ASSET_MINT_SOLANA = Keypair.generate().publicKey.toBase58();
delete process.env.THREE_TOKEN_MINT;
let simulated = false;
const conn = {
getAccountInfo: classicMintOwner,
simulateTransaction: async () => { simulated = true; return { value: { err: null } }; },
getTokenAccountBalance: async () => ({ value: { amount: '999999999' } }),
};
const res = await verifyRingPayment({
paymentPayload: p.paymentPayload,
requirement: p.requirement,
conn,
});
expect(res.isValid).toBe(false);
expect(res.invalidReason).toMatch(/^mint_not_settleable:/);
// Static rejection must happen before any simulation RPC is touched.
expect(simulated).toBe(false);
});
it('fails closed when no settleable mint is configured at all', () => {
const p = buildSelfPayPayment();
delete process.env.X402_ASSET_MINT_SOLANA;
delete process.env.THREE_TOKEN_MINT;
const tx = VersionedTransaction.deserialize(
Buffer.from(p.paymentPayload.transaction, 'base64'),
);
const out = validateRingTransaction({
txBase64: p.paymentPayload.transaction,
requirement: p.requirement,
feePayerPubkey: tx.message.staticAccountKeys[0],
allowlist: new Set([p.payTo]),
});
expect(out.ok).toBe(false);
expect(out.reason).toMatch(/^mint_not_settleable:/);
});
});
// An unfundable FEE PAYER gets its own reason class, separate from every other
// simulation revert.
//
// Every consumer of `invalidReason` groups on the token before the first ':'.
// /api/healthz exposes only that prefix, and isRailFault() in
// api/_lib/ops/x402-settle-health.js matches /simulation/, so while this verdict
// was spelled `simulation_failed` a starved platform sponsor was (a) bucketed
// with buyers signing from empty ATAs and (b) counted as a payment-RAIL fault.
// Production on 2026-09-09: 1,438 verify rejects in 24h, top of the book, every
// one of them {"InsufficientFundsForRent":{"account_index":0}} on our own
// sponsor. Account index 0 is the fee payer by definition, so the split is exact.
describe('fee-payer rent failures are their own reason class', () => {
const RENT_ERR = { InsufficientFundsForRent: { account_index: 0 } };
it('names the platform sponsor when the dry fee payer is ours', async () => {
const p = buildSelfPayPayment();
process.env.X402_PAY_TO_SOLANA = p.payTo;
process.env.X402_FEE_PAYER_SOLANA = p.feePayer;
const conn = {
getAccountInfo: classicMintOwner,
simulateTransaction: async () => ({ value: { err: RENT_ERR } }),
getTokenAccountBalance: async () => { throw new Error('should not be called'); },
};
const res = await verifyRingPayment({
paymentPayload: p.paymentPayload,
requirement: p.requirement,
conn,
});
expect(res.isValid).toBe(false);
expect(res.invalidReason.split(':')[0]).toBe('sponsor_fee_unfunded');
// The suffix keeps the evidence: which wallet the chain refused.
expect(res.invalidReason).toContain(p.feePayer);
});
it('names the buyer when the dry fee payer is not ours', async () => {
const p = buildSelfPayPayment();
process.env.X402_PAY_TO_SOLANA = p.payTo;
process.env.X402_FEE_PAYER_SOLANA = Keypair.generate().publicKey.toBase58();
const conn = {
getAccountInfo: classicMintOwner,
simulateTransaction: async () => ({ value: { err: RENT_ERR } }),
getTokenAccountBalance: async () => { throw new Error('should not be called'); },
};
const res = await verifyRingPayment({
paymentPayload: p.paymentPayload,
requirement: p.requirement,
conn,
});
expect(res.isValid).toBe(false);
// A broke buyer must never wear the platform's class: nothing to fund.
expect(res.invalidReason.split(':')[0]).toBe('payer_fee_unfunded');
});
it('leaves every other simulation revert as simulation_failed', async () => {
const p = buildSelfPayPayment();
process.env.X402_PAY_TO_SOLANA = p.payTo;
process.env.X402_FEE_PAYER_SOLANA = p.feePayer;
const conn = {
getAccountInfo: classicMintOwner,
// A rent failure on a NON-fee-payer account is a different condition and
// must not be reclassified: only index 0 is the fee payer.
simulateTransaction: async () => ({
value: { err: { InsufficientFundsForRent: { account_index: 3 } } },
}),
getTokenAccountBalance: async () => { throw new Error('should not be called'); },
};
const res = await verifyRingPayment({
paymentPayload: p.paymentPayload,
requirement: p.requirement,
conn,
});
expect(res.isValid).toBe(false);
expect(res.invalidReason.split(':')[0]).toBe('simulation_failed');
});
});
// $THREE is a Token-2022 mint. The facilitator used to pin the classic SPL Token
// program for the allowed program id and for every ATA derivation, so a $THREE
// payment could never verify: a classic-built transfer named a source ATA that
// does not exist, and a correctly built Token-2022 transfer was refused outright
// as `program_not_allowed`. Live on three.ws/club on 2026-09-20, where the cover
// charge quoted $THREE and every attempt to pay it failed at verify.
describe('Token-2022 mints settle on the same rail as classic ones', () => {
const THREE_MINT = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';
function buildThreePayment({ program, createRecipientAta = false }) {
const buyer = Keypair.generate();
const recipientOwner = Keypair.generate();
const mint = new PublicKey(THREE_MINT);
const sourceAta = getAssociatedTokenAddressSync(
mint, buyer.publicKey, false, program, ASSOCIATED_TOKEN_PROGRAM_ID,
);
const destAta = getAssociatedTokenAddressSync(
mint, recipientOwner.publicKey, false, program, ASSOCIATED_TOKEN_PROGRAM_ID,
);
const transferIx = createTransferCheckedInstruction(
sourceAta, mint, destAta, buyer.publicKey, 10_000_000n, DECIMALS, [], program,
);
const message = new TransactionMessage({
payerKey: buyer.publicKey,
recentBlockhash: '11111111111111111111111111111111',
instructions: [
ComputeBudgetProgram.setComputeUnitLimit({ units: 60_000 }),
...(createRecipientAta
? [createAssociatedTokenAccountIdempotentInstruction(
buyer.publicKey, destAta, recipientOwner.publicKey, mint, program, ASSOCIATED_TOKEN_PROGRAM_ID,
)]
: []),
transferIx,
],
}).compileToV0Message();
const tx = new VersionedTransaction(message);
tx.sign([buyer]);
process.env.THREE_TOKEN_MINT = THREE_MINT;
process.env.X402_PAY_TO_SOLANA = recipientOwner.publicKey.toBase58();
return {
requirement: {
network: 'solana',
asset: THREE_MINT,
amount: '10000000',
payTo: recipientOwner.publicKey.toBase58(),
},
paymentPayload: { transaction: Buffer.from(tx.serialize()).toString('base64') },
};
}
it('verifies a $THREE payment built against the Token-2022 program', async () => {
const p = buildThreePayment({ program: TOKEN_2022_PROGRAM_ID });
const conn = {
// The mint is seeded, so the hot path must not spend an RPC read on it.
getAccountInfo: async () => { throw new Error('should not be called'); },
simulateTransaction: async () => ({ value: { err: null, logs: [] } }),
};
const res = await verifyRingPayment({
paymentPayload: p.paymentPayload,
requirement: p.requirement,
conn,
});
expect(res.invalidReason).toBeUndefined();
expect(res.isValid).toBe(true);
expect(res.asset).toBe(THREE_MINT);
});
it('names the wrong program when a $THREE transfer is built against classic SPL Token', async () => {
const p = buildThreePayment({ program: TOKEN_PROGRAM_ID });
let simulated = false;
const conn = {
simulateTransaction: async () => { simulated = true; return { value: { err: null } }; },
};
const res = await verifyRingPayment({
paymentPayload: p.paymentPayload,
requirement: p.requirement,
conn,
});
expect(res.isValid).toBe(false);
expect(res.invalidReason).toBe(`wrong_token_program:${TOKEN_PROGRAM_ID.toBase58()}`);
expect(simulated).toBe(false);
});
it('budgets the larger Token-2022 ATA rent when the recipient account is new', () => {
const p = buildThreePayment({ program: TOKEN_2022_PROGRAM_ID, createRecipientAta: true });
const out = validateRingTransaction({
txBase64: p.paymentPayload.transaction,
requirement: p.requirement,
feePayerPubkey: null,
allowlist: new Set([p.requirement.payTo]),
});
expect(out.ok).toBe(true);
expect(out.decoded.tokenProgram).toBe(TOKEN_2022_PROGRAM_ID.toBase58());
expect(out.decoded.ataCreatePresent).toBe(true);
// One signature (5000) plus the rent ceiling for a 170-byte Token-2022 ATA,
// which must sit above the classic 165-byte figure (2,039,280).
expect(out.decoded.estFeeLamports).toBe(5000 + 2_074_080);
});
it('fails closed when a configured mint cannot be resolved to a token program', async () => {
const p = buildSelfPayPayment();
process.env.X402_PAY_TO_SOLANA = p.payTo;
const conn = {
getAccountInfo: async () => { throw new Error('rpc down'); },
simulateTransaction: async () => { throw new Error('should not be called'); },
};
const res = await verifyRingPayment({
paymentPayload: p.paymentPayload,
requirement: p.requirement,
conn,
});
expect(res.isValid).toBe(false);
expect(res.invalidReason).toMatch(/^token_program_unresolved:/);
});
});
// Phantom's transaction protection (on by default) injects Lighthouse assertion
// instructions before the user signs. The facilitator refused them as
// `program_not_allowed`, and the checkout modal, mirroring that, told the buyer
// to switch protection off. Live at the /club door on 2026-09-21 paying in USDC.
// The reference x402 SVM facilitator accepts them; so does this one, with the
// one guard a sponsored rail needs.
describe('wallet-injected Lighthouse guard instructions', () => {
const LIGHTHOUSE = new PublicKey('L2TExMFKdjpN9kozasaurPirfHy9P8sbXoAN1qA3S95');
function buildGuardedPayment({ sponsored, guardAccounts, guardCount = 1 }) {
const buyer = Keypair.generate();
const sponsor = Keypair.generate();
const recipientOwner = Keypair.generate();
const mint = Keypair.generate().publicKey;
const sourceAta = getAssociatedTokenAddressSync(mint, buyer.publicKey);
const destAta = getAssociatedTokenAddressSync(mint, recipientOwner.publicKey);
const named = { buyer: buyer.publicKey, sponsor: sponsor.publicKey, source: sourceAta };
const guards = Array.from({ length: guardCount }, () => new TransactionInstruction({
programId: LIGHTHOUSE,
keys: guardAccounts.map((k) => ({ pubkey: named[k], isSigner: false, isWritable: false })),
data: Buffer.from([9, 0, 1]),
}));
process.env.X402_ASSET_MINT_SOLANA = mint.toBase58();
process.env.X402_PAY_TO_SOLANA = recipientOwner.publicKey.toBase58();
const message = new TransactionMessage({
payerKey: sponsored ? sponsor.publicKey : buyer.publicKey,
recentBlockhash: '11111111111111111111111111111111',
instructions: [
ComputeBudgetProgram.setComputeUnitLimit({ units: 120_000 }),
createTransferCheckedInstruction(
sourceAta, mint, destAta, buyer.publicKey, AMOUNT_ATOMIC, DECIMALS,
),
...guards,
],
}).compileToV0Message();
return validateRingTransaction({
txBase64: Buffer.from(new VersionedTransaction(message).serialize()).toString('base64'),
requirement: {
network: 'solana',
asset: mint.toBase58(),
amount: String(AMOUNT_ATOMIC),
payTo: recipientOwner.publicKey.toBase58(),
},
feePayerPubkey: sponsor.publicKey.toBase58(),
allowlist: new Set([recipientOwner.publicKey.toBase58()]),
});
}
it('settles a sponsored payment whose guards assert on the buyer', () => {
const out = buildGuardedPayment({ sponsored: true, guardAccounts: ['buyer', 'source'], guardCount: 2 });
expect(out.reason).toBeUndefined();
expect(out.ok).toBe(true);
expect(out.decoded.selfPay).toBe(false);
});
it('settles a self-pay payment whose guard names the buyer as fee payer', () => {
const out = buildGuardedPayment({ sponsored: false, guardAccounts: ['buyer'] });
expect(out.ok).toBe(true);
expect(out.decoded.selfPay).toBe(true);
});
it('refuses a guard instruction that names the sponsor account', () => {
const out = buildGuardedPayment({ sponsored: true, guardAccounts: ['buyer', 'sponsor'] });
expect(out.ok).toBe(false);
expect(out.reason).toBe('guard_instruction_references_sponsor');
});
it('refuses more guard instructions than the ceiling', () => {
const out = buildGuardedPayment({ sponsored: true, guardAccounts: ['buyer'], guardCount: 4 });
expect(out.ok).toBe(false);
expect(out.reason).toBe('too_many_guard_instructions:4');
});
});