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
// /receipts page helpers. The critical contract: buildReceiptsMessage must be
// byte-identical to buildExpectedMessage() in api/x402/my-receipts.js, or
// buyer signatures stop verifying server-side.
import { describe, it, expect } from 'vitest';
import {
buildReceiptsMessage,
signatureStillFresh,
SIGNATURE_TTL_SECONDS,
networkLabel,
explorerTxUrl,
shortAddress,
resourceDisplay,
receiptsToCsv,
summarizeReceipts,
formatReceiptAmount,
totalSpend,
outboundMintSymbol,
formatOutboundAmount,
outboundReceiptsToCsv,
} from '../src/receipts-lib.js';
// The API supplies the scale (server-resolved from the same env config that
// builds the 402 accepts), so these tests exercise decimals, not addresses.
const USDC_DECIMALS = 6;
const SOL_ADDR = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';
const EVM_ADDR = '0xAbCdEf0123456789aBcDeF0123456789ABCDEF01';
describe('buildReceiptsMessage', () => {
// Mirror of the server's buildExpectedMessage, copied verbatim from
// api/x402/my-receipts.js so a drift on either side fails this test.
function serverExpectedMessage(address, issuedAt, network) {
const normalized = network === 'solana' ? address : address.toLowerCase();
return `three.ws x402 receipts read\nNetwork: ${network}\nAddress: ${normalized}\nIssued At: ${issuedAt}`;
}
it('matches the server contract for Solana (verbatim base58)', () => {
const issuedAt = '2026-07-28T12:00:00.000Z';
expect(buildReceiptsMessage(SOL_ADDR, issuedAt, 'solana')).toBe(
serverExpectedMessage(SOL_ADDR, issuedAt, 'solana'),
);
expect(buildReceiptsMessage(SOL_ADDR, issuedAt, 'solana')).toContain(SOL_ADDR);
});
it('matches the server contract for EVM (lowercased address)', () => {
const issuedAt = '2026-07-28T12:00:00.000Z';
const msg = buildReceiptsMessage(EVM_ADDR, issuedAt, 'evm');
expect(msg).toBe(serverExpectedMessage(EVM_ADDR, issuedAt, 'evm'));
expect(msg).toContain(EVM_ADDR.toLowerCase());
expect(msg).not.toContain(EVM_ADDR);
});
});
describe('signatureStillFresh', () => {
const now = Date.parse('2026-07-28T12:00:00.000Z');
it('accepts a signature issued moments ago', () => {
expect(signatureStillFresh(new Date(now - 10_000).toISOString(), now)).toBe(true);
});
it('rejects one older than the TTL minus the safety margin', () => {
const old = new Date(now - (SIGNATURE_TTL_SECONDS - 10) * 1000).toISOString();
expect(signatureStillFresh(old, now)).toBe(false);
});
it('rejects future timestamps and garbage', () => {
expect(signatureStillFresh(new Date(now + 60_000).toISOString(), now)).toBe(false);
expect(signatureStillFresh('not-a-date', now)).toBe(false);
expect(signatureStillFresh(undefined, now)).toBe(false);
});
});
describe('networkLabel + explorerTxUrl', () => {
it('handles CAIP-2 and plain network strings', () => {
expect(networkLabel('solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp')).toBe('Solana');
expect(networkLabel('solana')).toBe('Solana');
expect(networkLabel('eip155:8453')).toBe('Base');
expect(networkLabel('base')).toBe('Base');
expect(networkLabel('eip155:56')).toBe('BNB Chain');
expect(networkLabel('weird-chain')).toBe('weird-chain');
});
it('routes txs to the right explorer', () => {
expect(explorerTxUrl('solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp', 'abc123')).toBe(
'https://solscan.io/tx/abc123',
);
expect(explorerTxUrl('base', '0xdeadbeef')).toBe('https://basescan.org/tx/0xdeadbeef');
expect(explorerTxUrl('eip155:1', '0xdeadbeef')).toBe('https://etherscan.io/tx/0xdeadbeef');
});
it('returns null with no tx or no mapped explorer', () => {
expect(explorerTxUrl('solana', null)).toBe(null);
expect(explorerTxUrl('unknown-chain', 'abc')).toBe(null);
});
});
describe('display helpers', () => {
it('shortAddress truncates long addresses only', () => {
expect(shortAddress(SOL_ADDR)).toBe('FeMbDo…pump');
expect(shortAddress('short')).toBe('short');
});
it('resourceDisplay strips the three.ws origin, keeps foreign hosts', () => {
expect(resourceDisplay('https://three.ws/api/x402/d/prices')).toBe('/api/x402/d/prices');
expect(resourceDisplay('https://api.example.com/data?x=1')).toBe('api.example.com/data?x=1');
expect(resourceDisplay('not a url')).toBe('not a url');
});
});
describe('formatReceiptAmount', () => {
it('renders 6-decimal stablecoin amounts', () => {
expect(formatReceiptAmount('10000', USDC_DECIMALS).label).toBe('$0.01');
expect(formatReceiptAmount('1000000', USDC_DECIMALS).label).toBe('$1.00');
expect(formatReceiptAmount('2500000', USDC_DECIMALS).label).toBe('$2.50');
});
it('keeps precision on sub-cent micropayments instead of showing $0.00', () => {
expect(formatReceiptAmount('1000', USDC_DECIMALS).label).toBe('$0.001');
expect(formatReceiptAmount('100', USDC_DECIMALS).label).toBe('$0.0001');
});
it('refuses to guess the scale when the server did not supply one', () => {
// An asset this deployment does not settle in arrives with a null scale.
expect(formatReceiptAmount('10000', null)).toBe(null);
expect(formatReceiptAmount('10000', undefined)).toBe(null);
expect(formatReceiptAmount('10000', 'six')).toBe(null);
expect(formatReceiptAmount('10000', 99)).toBe(null);
});
it('handles missing or malformed amounts', () => {
expect(formatReceiptAmount(null, USDC_DECIMALS)).toBe(null);
expect(formatReceiptAmount('', USDC_DECIMALS)).toBe(null);
expect(formatReceiptAmount('not-a-number', USDC_DECIMALS)).toBe(null);
});
});
describe('totalSpend', () => {
it('sums priced rows and counts the unpriced ones', () => {
const s = totalSpend([
{ amountAtomics: '10000', assetDecimals: USDC_DECIMALS },
{ amountAtomics: '1000000', assetDecimals: USDC_DECIMALS },
{ amountAtomics: null, assetDecimals: null },
]);
expect(s.label).toBe('$1.01');
expect(s.priced).toBe(2);
expect(s.unpriced).toBe(1);
});
it('is zero-safe on an empty vault', () => {
const s = totalSpend([]);
expect(s.total).toBe(0);
expect(s.label).toBe('$0.00');
});
});
describe('receiptsToCsv', () => {
it('emits a stable header and escapes quoted cells', () => {
const csv = receiptsToCsv([
{
id: 1,
issuedAt: '2026-07-28T00:00:00.000Z',
network: 'solana',
resourceUrl: 'https://three.ws/api/x402/d/prices?a="x",b',
amountAtomics: '10000',
asset: 'the-settlement-asset',
transaction: 'sig1',
format: 'jws',
payer: SOL_ADDR,
},
]);
const [header, row] = csv.split('\n');
expect(header).toBe(
'id,issued_at,network,resource_url,amount_atomics,asset,transaction,format,payer',
);
expect(row).toContain('"https://three.ws/api/x402/d/prices?a=""x"",b"');
expect(row).toContain(SOL_ADDR);
expect(row).toContain('10000');
});
it('handles empty input', () => {
expect(receiptsToCsv([])).toBe(
'id,issued_at,network,resource_url,amount_atomics,asset,transaction,format,payer',
);
});
});
describe('summarizeReceipts', () => {
it('counts endpoints, networks, and the time range', () => {
const s = summarizeReceipts([
{ resourceUrl: 'https://three.ws/a', network: 'solana', issuedAt: '2026-07-01T00:00:00Z' },
{ resourceUrl: 'https://three.ws/a', network: 'solana', issuedAt: '2026-07-02T00:00:00Z' },
{ resourceUrl: 'https://three.ws/b', network: 'base', issuedAt: '2026-07-03T00:00:00Z' },
]);
expect(s.total).toBe(3);
expect(s.endpoints).toBe(2);
expect(s.networks).toEqual(['Solana', 'Base']);
expect(s.firstAt).toBe('2026-07-01T00:00:00.000Z');
expect(s.lastAt).toBe('2026-07-03T00:00:00.000Z');
});
it('handles the empty vault', () => {
const s = summarizeReceipts([]);
expect(s.total).toBe(0);
expect(s.firstAt).toBe(null);
});
});
const USDC_MINT = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
const THREE_MINT = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';
const SYNTH_MINT = 'THREEsynthetic1111111111111111111111111111';
describe('outboundMintSymbol', () => {
it('recognises USDC and $THREE, and nothing else', () => {
expect(outboundMintSymbol(USDC_MINT)).toBe('USDC');
expect(outboundMintSymbol(THREE_MINT)).toBe('THREE');
expect(outboundMintSymbol(SYNTH_MINT)).toBeNull();
});
});
describe('formatOutboundAmount', () => {
it('prefers the chain-resolved amount, under its real ticker', () => {
const amt = formatOutboundAmount({
reportedAmountUsd: 1,
resolved: { amountAtomics: '2000000000', decimals: 6, mint: THREE_MINT },
});
expect(amt.label).toBe('2,000.00 THREE');
expect(amt.usd).toBe(false);
});
it('falls back to the reported USD amount when nothing has resolved yet', () => {
const amt = formatOutboundAmount({ reportedAmountUsd: 4.5, resolved: null });
expect(amt.label).toBe('$4.50');
expect(amt.usd).toBe(true);
});
});
describe('outboundReceiptsToCsv', () => {
it('emits the resolved settlement columns when present', () => {
const csv = outboundReceiptsToCsv([
{
id: 'exec-1',
createdAt: '2026-10-15T00:00:00.000Z',
network: 'solana',
endpointHost: 'merchant.test',
endpointUrl: 'https://merchant.test/api/paid',
reportedAmountUsd: 1,
txHash: 'sig1',
resolved: { payer: 'PAYER', payee: 'PAYEE', mint: USDC_MINT, amountAtomics: '1000000', decimals: 6, feeLamports: 5000, slot: 1, blockTime: 2 },
resolveError: null,
},
]);
const [header, row] = csv.split('\n');
expect(header).toBe(
'id,created_at,network,endpoint_host,endpoint_url,reported_amount_usd,tx_hash,resolved_payer,resolved_payee,resolved_mint,resolved_amount_atomics,resolved_decimals,resolved_fee_lamports,resolved_slot,resolved_block_time,resolve_error',
);
expect(row).toContain('PAYER');
expect(row).toContain('PAYEE');
expect(row).toContain(USDC_MINT);
});
it('handles empty input', () => {
expect(outboundReceiptsToCsv([])).toBe(
'id,created_at,network,endpoint_host,endpoint_url,reported_amount_usd,tx_hash,resolved_payer,resolved_payee,resolved_mint,resolved_amount_atomics,resolved_decimals,resolved_fee_lamports,resolved_slot,resolved_block_time,resolve_error',
);
});
});