Skip to content

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.

10.0 KB
Raw Blame
import { describe, it, expect, vi } from 'vitest';

// The loader imports the database client; the shaping under test is pure.
vi.mock('../api/_lib/db.js', () => ({ sql: () => Promise.resolve([]) }));

const {
	evidenceTiming,
	receiptTxUrl,
	shapeTradeReceipt,
	summarizeReceipt,
	triggerLabel,
} = await import('../api/_lib/trade-receipt.js');

const OPENED = '2026-09-24T05:46:25.948Z';
const CLOSED = '2026-09-24T05:52:22.479Z';
const SOL_SIG = '3owaJHvhEbES9WmjiDmSXk9kVTepjHft4ZMHkPTauK79tj3HhuM7bbtK4jA42piV49u5jU4xVdCJW4dcDfAJdAbz';

/** A closed, live position on $THREE. Tests override one field at a time. */
function position(over = {}) {
	return {
		id: '11111111-2222-3333-4444-555555555555',
		agent_id: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
		agent_name: 'Crosshair',
		agent_image: null,
		network: 'mainnet',
		mint: 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump',
		symbol: 'THREE',
		name: 'three.ws',
		status: 'closed',
		exit_reason: 'trailing_stop',
		entry_trigger: 'oracle_crossing',
		trigger_ref: 'score:85',
		entry_quote_lamports: '2000000',
		exit_quote_lamports: '1794738',
		realized_pnl_lamports: '-205262',
		realized_pnl_pct: '-10.2631',
		entry_price_impact_pct: '0.0019',
		buy_sig: SOL_SIG,
		sell_sig: SOL_SIG,
		opened_at: OPENED,
		closed_at: CLOSED,
		...over,
	};
}

const at = (deltaSec) => new Date(new Date(OPENED).getTime() + deltaSec * 1000).toISOString();

describe('evidenceTiming', () => {
	it('places evidence before the entry, inside the clock-skew allowance', () => {
		expect(evidenceTiming(at(-60), OPENED, CLOSED)).toBe('before_entry');
		expect(evidenceTiming(at(90), OPENED, CLOSED)).toBe('before_entry');
	});
	it('separates the hold from the time after the exit', () => {
		expect(evidenceTiming(at(200), OPENED, CLOSED)).toBe('during_trade');
		expect(evidenceTiming(at(3600), OPENED, CLOSED)).toBe('after_exit');
	});
	it('treats an open position as still holding', () => {
		expect(evidenceTiming(at(3600), OPENED, null)).toBe('during_trade');
	});
	it('refuses to place a missing timestamp', () => {
		expect(evidenceTiming(null, OPENED, CLOSED)).toBeNull();
	});
});

describe('receiptTxUrl', () => {
	it('opens a Solana signature on Solscan, devnet included', () => {
		expect(receiptTxUrl(SOL_SIG)).toBe(`https://solscan.io/tx/${SOL_SIG}`);
		expect(receiptTxUrl(SOL_SIG, 'devnet')).toBe(`https://solscan.io/tx/${SOL_SIG}?cluster=devnet`);
	});
	it('opens an EVM payment hash on Basescan', () => {
		const hash = `0x${'ab'.repeat(32)}`;
		expect(receiptTxUrl(hash)).toBe(`https://basescan.org/tx/${hash}`);
	});
	it('never links a paper fill or a malformed value', () => {
		expect(receiptTxUrl('SIMULATED')).toBeNull();
		expect(receiptTxUrl('not a signature')).toBeNull();
		expect(receiptTxUrl(null)).toBeNull();
	});
});

describe('triggerLabel', () => {
	it('names every trigger the sniper writes', () => {
		for (const t of ['new_mint', 'oracle_crossing', 'intel_confirmed', 'llm_intel', 'graduation_ride']) {
			expect(triggerLabel(t).detail).toBeTruthy();
		}
	});
	it('defaults a missing trigger to a fresh launch and humanizes an unknown one', () => {
		expect(triggerLabel(null).label).toBe('Fresh launch');
		expect(triggerLabel('whale_follow').label).toBe('whale follow');
	});
});

describe('shapeTradeReceipt', () => {
	it('keeps every leg in time order with its on-chain link', () => {
		const r = shapeTradeReceipt({
			position: position(),
			journal: [
				{ event: 'exit', reason: 'trailing_stop', rationale: 'Full exit: trailing_stop.', sold_fraction: '1', leg_pnl_lamports: '-205262', ts: CLOSED, sig: SOL_SIG },
				{ event: 'entry', reason: 'oracle_crossing', rationale: 'Entered on oracle_crossing.', sold_fraction: '0', ts: at(2), sig: SOL_SIG },
			],
		});
		expect(r.legs.map((l) => l.event)).toEqual(['entry', 'exit']);
		expect(r.legs[1].leg_pnl_sol).toBeCloseTo(-0.000205262, 9);
		expect(r.legs[0].tx_url).toContain('solscan.io/tx/');
		expect(r.position.share_url).toBe('/trade/11111111-2222-3333-4444-555555555555');
		expect(r.evidence_count).toBe(0);
	});

	it('labels a paper fill and gives it no transaction links', () => {
		const r = shapeTradeReceipt({ position: position({ buy_sig: 'SIMULATED', sell_sig: 'SIMULATED' }), journal: [] });
		expect(r.position.paper).toBe(true);
		expect(r.position.buy_url).toBeNull();
		expect(r.summary).toContain('paper-bought');
	});

	it('drops evidence recorded after the exit, since it cannot have caused the trade', () => {
		const r = shapeTradeReceipt({
			position: position(),
			journal: [],
			sentiment: { signal: 'bullish', headline: 'late read', confidence: '0.9', checked_at: at(3600), tx_signature: SOL_SIG },
			judge: { buy: true, confidence: '0.8', thesis: 'after the fact', model: 'm', created_at: at(3600) },
			intel: { quality_score: 91, observation_ended_at: at(3600) },
		});
		expect(r.evidence.sentiment).toBeNull();
		expect(r.evidence.judge).toBeNull();
		expect(r.evidence.intel).toBeNull();
	});

	it('tags a paid read taken while holding as during_trade, with its payment receipt', () => {
		const r = shapeTradeReceipt({
			position: position(),
			journal: [],
			sentiment: { signal: 'bullish', headline: 'h', confidence: '0.93', sentiment_adj: -4, checked_at: at(200), tx_signature: SOL_SIG },
		});
		expect(r.evidence.sentiment.timing).toBe('during_trade');
		expect(r.evidence.sentiment.confidence).toBeCloseTo(0.93);
		expect(r.evidence.sentiment.receipt_url).toContain(SOL_SIG);
	});

	it('shows what the Sentiment Scout flagged before the entry, with sources, and nothing it said after the exit', () => {
		const scout = {
			first_scouted_at: at(-600), first_score: 64, peak_score: 71,
			first_caution: 'Most early momentum on pump.fun fades.',
			first_evidence: [
				{ type: 'volume_spike', detail: '30.0 SOL bought in its first 90s', source: 'https://three.ws/api/pump/coin-intel?mint=x', at: at(-700) },
				{ type: 'social_mention', platform: 'x', detail: '3 X posts quoted this exact contract address', source: 'https://x.com/a/status/1', at: at(-650), checked_against: 'On-chain at 05:40 UTC: 30.0 SOL bought' },
				{ type: 'paid_signal', detail: 'no link', source: 'javascript:alert(1)' },
				{ type: '', detail: 'dropped' },
			],
		};
		const r = shapeTradeReceipt({ position: position(), journal: [], scout });
		expect(r.evidence.scout).toMatchObject({ score: 64, peak_score: 71, timing: 'before_entry' });
		expect(r.evidence.scout.evidence).toHaveLength(3);
		expect(r.evidence.scout.evidence[1]).toMatchObject({ platform: 'x', source: 'https://x.com/a/status/1' });
		expect(r.evidence.scout.evidence[2].source).toBeNull();
		expect(r.summary).toContain('Sentiment Scout flagged it at 64');

		const late = shapeTradeReceipt({ position: position(), journal: [], scout: { ...scout, first_scouted_at: '2026-09-24T09:00:00.000Z' } });
		expect(late.evidence.scout).toBeNull();
	});

	it('only admits an LLM verdict that existed before the entry', () => {
		const before = shapeTradeReceipt({
			position: position(), journal: [],
			judge: { buy: true, confidence: '0.8', thesis: 'two-sided market', model: 'm', created_at: at(-30) },
		});
		expect(before.evidence.judge).toMatchObject({ buy: true, thesis: 'two-sided market' });
		const during = shapeTradeReceipt({
			position: position(), journal: [],
			judge: { buy: true, confidence: '0.8', thesis: 'x', model: 'm', created_at: at(200) },
		});
		expect(during.evidence.judge).toBeNull();
	});

	it('ranks Oracle reasons by how far they moved the base rate, and hides reasons scored after the exit', () => {
		const reasons = [
			{ text: 'near base', pillar: 'momentum', lift: 1.0 },
			{ text: 'strong lift', pillar: 'structure', lift: 2.7 },
			{ text: 'drag', pillar: 'momentum', lift: 0.3 },
		];
		const r = shapeTradeReceipt({
			position: position(), journal: [],
			oracleHistory: { score: 85, tier: 'strong', pedigree: 33, structure: 23, narrative: 11, momentum: 57, scored_at: at(-3) },
			oracleCurrent: { score: 85, reasons, scored_at: at(-3) },
		});
		expect(r.evidence.oracle.score).toBe(85);
		expect(r.evidence.oracle.reasons.map((x) => x.text)).toEqual(['strong lift', 'drag', 'near base']);
		const late = shapeTradeReceipt({
			position: position(), journal: [],
			oracleHistory: { score: 85, scored_at: at(-3) },
			oracleCurrent: { score: 60, reasons, scored_at: at(3600) },
		});
		expect(late.evidence.oracle.score).toBe(85);
		expect(late.evidence.oracle.reasons).toEqual([]);
	});

	it('carries the firewall checks and the Risk Officer review as recorded', () => {
		const r = shapeTradeReceipt({
			position: position(), journal: [],
			firewall: {
				verdict: 'warn', score: 84, reasons: ['concentrated holders'], simulated: true, enforced: false, created_at: at(0.4),
				checks: [{ name: 'round_trip', status: 'pass', reason: 'roundtrip_simulated_ok', detail: {} }, { status: 'pass' }],
			},
			riskReview: { level: 'shadow', veto: false, severity: 'caution', reasons: ['thin book'], proposed_lamports: '2000000', adjusted_lamports: '1000000', created_at: at(0) },
		});
		expect(r.evidence.firewall.checks).toEqual([{ name: 'round_trip', status: 'pass', reason: 'roundtrip_simulated_ok' }]);
		expect(r.evidence.risk_review).toMatchObject({ severity: 'caution', proposed_sol: 0.002, adjusted_sol: 0.001 });
		expect(r.evidence_count).toBe(2);
	});
});

describe('summarizeReceipt', () => {
	it('states the trigger, the drivers it has evidence for, and the result', () => {
		const r = shapeTradeReceipt({
			position: position(), journal: [],
			oracleHistory: { score: 85, tier: 'strong', scored_at: at(-3) },
			firewall: { verdict: 'warn', score: 84, created_at: at(0) },
		});
		expect(r.summary).toBe('Crosshair bought $THREE. Trigger: Oracle crossing. Oracle score 85 strong, firewall warn. Exited on trailing stop at -10.3%.');
	});
	it('says an open position is still open instead of inventing a result', () => {
		const r = shapeTradeReceipt({ position: position({ status: 'open', closed_at: null, exit_reason: null }), journal: [] });
		expect(summarizeReceipt(r)).toBe('Crosshair bought $THREE. Trigger: Oracle crossing. Still open.');
		expect(r.position.share_url).toBeNull();
	});
});