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.

20.7 KB
Raw Blame
// Ghost-copy: paper-copy any verified leader, replayed over their REAL trades.
// ---------------------------------------------------------------------------
// The bridge between "I'll never let a bot touch my wallet" and actually copying
// one. A visitor picks a leader, a budget and a window, and we replay that
// leader's actual on-chain round-trips (`agent_sniper_positions`) through the
// SAME sizing and guard engine the live copy-fanout cron uses
// (`copy-engine.planCopyOrder`), against a hypothetical wallet. The answer is
// the sentence the whole funnel turns on: "if you'd ghost-copied this agent for
// 7 days with 1 SOL, you'd be +0.34 SOL."
//
// Zero custody, zero signing, no funded signer, no account: it is arithmetic
// over trades that already happened. Because the sizing path is literally the
// production copy-engine, a ghost result is not a marketing number. It is what
// the copy engine WOULD have generated, including every skip.
//
// Honesty rules baked in (a dishonest sim is worse than no sim):
//   - Realized P&L per trade is derived from the exact chain lamports
//     (realized_pnl / entry_quote), never from a stored percentage that could
//     drift. Trades whose entry we cannot price are dropped and counted.
//   - Survivorship-honest: every losing round-trip counts. Nothing is filtered.
//   - The ghost wallet has a real cash constraint. Capital locked in an open
//     copy is unavailable, so a leader who runs 30 concurrent positions cannot
//     be "copied" on 1 SOL without skips, and those skips are reported.
//   - The leader's still-open positions are marked at THEIR last on-chain quote
//     (`last_value_lamports`) and reported as unrealized, separately from the
//     realized headline. Never folded in silently.
//   - Every skipped copy carries a machine reason and a human sentence.
//
// $THREE is the only coin this platform promotes. The coins that appear here are
// whatever the leader actually traded: runtime data, never an endorsement.

import { sql } from './db.js';
import { normalizeSubscriptionInput, planCopyOrder } from './copy-engine.js';
import { WINDOWS, windowStartIso } from './trader-stats.js';

const LAMPORTS = 1e9;
const lamToSol = (l) => (l == null ? 0 : Number(l) / LAMPORTS);
const round4 = (x) => Math.round(x * 1e4) / 1e4;
const round2 = (x) => Math.round(x * 100) / 100;
const num = (v) => (Number.isFinite(Number(v)) ? Number(v) : null);

export const GHOST_WINDOWS = WINDOWS;
export const MAX_GHOST_TRADES = 500;

// ---------------------------------------------------------------------------
// Sizing defaults. A visitor should only have to type a budget, so every guard
// derives from it unless they override. These mirror the shape of a real
// copy_subscriptions row so the ghost and the live subscription behave the same.
// ---------------------------------------------------------------------------

/**
 * Build a normalized, copy-engine-compatible subscription from a budget plus
 * optional overrides. Returns { ok, value, error } like normalizeSubscriptionInput.
 */
export function buildGhostSubscription({
	budgetSol,
	sizing_rule = 'fixed',
	fixed_sol,
	multiplier,
	per_trade_cap_sol,
	min_order_sol,
	daily_budget_sol,
	max_open_copies,
} = {}) {
	const budget = num(budgetSol);
	if (budget == null || budget <= 0) return { ok: false, error: 'budget must be a positive number of SOL' };
	// An unrecognized rule used to fall through to 'fixed', so a caller asking for
	// a multiplier-sized replay got a fixed-sized one and no hint that the request
	// was ignored. A replay that silently simulates something else is worse than
	// no replay: reject it and let the endpoint's invalid_sizing 400 fire.
	if (!['fixed', 'multiplier'].includes(sizing_rule)) {
		return { ok: false, error: 'sizing must be "fixed" or "multiplier"' };
	}

	// Deploy the budget in roughly ten slices, never more than a quarter of it in
	// one trade, and recycle the whole budget at most once per UTC day.
	const draft = {
		sizing_rule,
		fixed_sol: num(fixed_sol) ?? round4(budget / 10),
		multiplier: num(multiplier) ?? 0.1,
		per_trade_cap_sol: num(per_trade_cap_sol) ?? round4(budget / 4),
		min_order_sol: num(min_order_sol) ?? round4(Math.min(budget / 1000, budget / 4)),
		daily_budget_sol: num(daily_budget_sol) ?? budget,
		max_open_copies: num(max_open_copies) ?? 5,
		copy_sells: true,
		require_safety_pass: false,
		perf_fee_bps: 0, // ghosts never accrue a fee; nothing was earned
	};

	const normalized = normalizeSubscriptionInput(draft);
	if (!normalized.ok) return normalized;
	// planCopyOrder gates on status; a ghost is always "active".
	return { ok: true, value: { ...normalized.value, status: 'active' } };
}

// ---------------------------------------------------------------------------
// The simulator. PURE: no DB, no network, no clock. Deterministic over its
// input, which is what tests/ghost-copy.test.js pins.
// ---------------------------------------------------------------------------

/**
 * Replay a leader's positions against a hypothetical wallet.
 *
 * @param {object} p
 * @param {Array}  p.trades        normalized trades (see normalizeLeaderTrades), any order.
 * @param {number} p.budgetSol     the ghost wallet's starting SOL.
 * @param {object} p.subscription  a buildGhostSubscription() value.
 * @param {number} [p.maxCurvePoints] downsample ceiling for the equity curve.
 * @returns {object} fills, skipped, equity_curve, summary, honesty
 */
export function simulateGhostCopy({ trades = [], budgetSol, subscription, maxCurvePoints = 160 }) {
	const sub = { ...subscription, status: 'active' };
	const start = Number(budgetSol);

	let cash = start;
	const open = new Map();           // trade id -> { order_sol, trade }
	const fills = [];
	const skipped = [];
	const spentByDay = new Map();
	const curve = [{ t: null, equity_sol: round4(start) }];

	// Close events free capital, so they must settle before same-instant opens.
	const events = [];
	for (const t of trades) {
		if (!t.opened_at) continue;
		events.push({ ts: t.opened_at, rank: 1, kind: 'open', t });
		if (t.closed_at && t.status === 'closed') events.push({ ts: t.closed_at, rank: 0, kind: 'close', t });
	}
	events.sort((a, b) => (a.ts === b.ts ? a.rank - b.rank : a.ts < b.ts ? -1 : 1));
	// Anchor the curve's origin to the first thing that actually happened, so the
	// chart's x-axis starts where the leader started rather than at a null.
	if (events.length) curve[0].t = events[0].ts;

	const lockedSol = () => {
		let s = 0;
		for (const f of open.values()) s += f.order_sol;
		return s;
	};
	const pushCurve = (ts) => curve.push({ t: ts, equity_sol: round4(cash + lockedSol()) });

	for (const ev of events) {
		const t = ev.t;
		if (ev.kind === 'open') {
			const day = String(ev.ts).slice(0, 10);
			const spentToday = spentByDay.get(day) || 0;

			const plan = planCopyOrder({
				subscription: sub,
				position: { direction: 'buy', entry_sol: t.entry_sol },
				coin: t.coin || null,
				copierBalanceSol: cash,
				spentTodaySol: spentToday,
				openCopies: open.size,
			});

			if (plan.action !== 'copy') {
				skipped.push({
					mint: t.mint, symbol: t.symbol, at: ev.ts,
					reason: plan.reason, detail: plan.detail || null,
					leader_entry_sol: round4(t.entry_sol),
				});
				continue;
			}

			const order = plan.order_sol;
			if (order > cash + 1e-12) {
				skipped.push({
					mint: t.mint, symbol: t.symbol, at: ev.ts,
					reason: 'ghost_cash_locked',
					detail: `Your ghost wallet had ${round4(cash)} SOL free (the rest was locked in open copies); this copy needed ${round4(order)} SOL.`,
					leader_entry_sol: round4(t.entry_sol),
				});
				continue;
			}

			cash -= order;
			spentByDay.set(day, spentToday + order);
			open.set(t.id, { order_sol: order, trade: t, opened_at: ev.ts });
			continue;
		}

		// close
		const held = open.get(t.id);
		if (!held) continue; // the leader closed a trade the ghost never entered
		const proceeds = held.order_sol * (1 + t.pnl_pct / 100);
		cash += proceeds;
		open.delete(t.id);

		fills.push({
			mint: t.mint, symbol: t.symbol, name: t.name,
			order_sol: round4(held.order_sol),
			proceeds_sol: round4(proceeds),
			pnl_sol: round4(proceeds - held.order_sol),
			pnl_pct: round2(t.pnl_pct),
			multiple: round2(1 + t.pnl_pct / 100),
			opened_at: held.opened_at, closed_at: ev.ts,
			hold_seconds: holdSeconds(held.opened_at, ev.ts),
			exit_reason: t.exit_reason || null,
			leader_entry_sol: round4(t.entry_sol),
			buy_sig: t.buy_sig || null, sell_sig: t.sell_sig || null,
		});
		pushCurve(ev.ts);
	}

	// Still-open ghost copies, marked at the LEADER's last on-chain quote.
	const stillOpen = [];
	let unrealized = 0;
	for (const f of open.values()) {
		const markPct = f.trade.mark_pct;
		const value = markPct == null ? f.order_sol : f.order_sol * (1 + markPct / 100);
		unrealized += value - f.order_sol;
		stillOpen.push({
			mint: f.trade.mint, symbol: f.trade.symbol, name: f.trade.name,
			order_sol: round4(f.order_sol),
			opened_at: f.opened_at,
			mark_pct: markPct == null ? null : round2(markPct),
			unrealized_sol: round4(value - f.order_sol),
			marked: markPct == null ? 'cost' : 'leader_last_quote',
		});
	}

	const realizedPnl = cash + lockedSol() - start;
	const wins = fills.filter((f) => f.pnl_sol > 0).length;
	const losses = fills.length - wins;
	const deployed = fills.reduce((s, f) => s + f.order_sol, 0) + lockedSol();
	const best = fills.length ? fills.reduce((a, b) => (b.pnl_pct > a.pnl_pct ? b : a)) : null;
	const worst = fills.length ? fills.reduce((a, b) => (b.pnl_pct < a.pnl_pct ? b : a)) : null;

	return {
		fills,
		skipped,
		still_open: stillOpen,
		equity_curve: downsampleCurve(curve, maxCurvePoints),
		summary: {
			start_sol: round4(start),
			end_sol: round4(cash + lockedSol()),
			realized_pnl_sol: round4(realizedPnl),
			realized_pnl_pct: start > 0 ? round2((realizedPnl / start) * 100) : null,
			unrealized_pnl_sol: round4(unrealized),
			mark_to_market_sol: round4(cash + lockedSol() + unrealized),
			copied: fills.length,
			wins,
			losses,
			win_rate_pct: fills.length ? round2((wins / fills.length) * 100) : null,
			deployed_sol: round4(deployed),
			idle_sol: round4(cash),
			max_drawdown_pct: maxDrawdownPct(curve),
			best: best && { symbol: best.symbol, mint: best.mint, pnl_pct: best.pnl_pct, pnl_sol: best.pnl_sol },
			worst: worst && { symbol: worst.symbol, mint: worst.mint, pnl_pct: worst.pnl_pct, pnl_sol: worst.pnl_sol },
			leader_trades: trades.length,
			skipped_count: skipped.length,
			still_open_count: stillOpen.length,
			avg_hold_seconds: avgHold(fills),
		},
		honesty: honestyNotes({ fills, skipped, stillOpen, trades }),
	};
}

function holdSeconds(a, b) {
	const t0 = Date.parse(a), t1 = Date.parse(b);
	return Number.isFinite(t0) && Number.isFinite(t1) && t1 >= t0 ? Math.round((t1 - t0) / 1000) : null;
}

function avgHold(fills) {
	const held = fills.map((f) => f.hold_seconds).filter((s) => s != null);
	return held.length ? Math.round(held.reduce((a, b) => a + b, 0) / held.length) : null;
}

/** Peak-to-trough drop on the ghost equity curve, as a pct of the running peak. */
export function maxDrawdownPct(curve) {
	let peak = -Infinity, worst = 0;
	for (const p of curve) {
		const v = p.equity_sol;
		if (v > peak) peak = v;
		if (peak > 0) worst = Math.max(worst, ((peak - v) / peak) * 100);
	}
	return round2(worst);
}

/** Keep the first and last points exactly; thin the middle evenly. */
export function downsampleCurve(curve, maxPoints) {
	if (curve.length <= maxPoints) return curve;
	const out = [curve[0]];
	const step = (curve.length - 2) / (maxPoints - 2);
	for (let i = 1; i < maxPoints - 1; i++) out.push(curve[Math.round(i * step)]);
	out.push(curve[curve.length - 1]);
	return out;
}

function honestyNotes({ fills, skipped, stillOpen, trades }) {
	const notes = [];
	notes.push('Paper only. No wallet was connected, nothing was signed, and no fee was charged.');
	notes.push('Every trade replayed here is a real on-chain round-trip by this leader, priced from the exact lamports of their entry and exit. Losses are included.');
	if (skipped.length) {
		notes.push(`${skipped.length} of the leader's ${trades.length} trades were NOT copied, because your budget, caps or open-position limit blocked them. The live copy engine would have skipped them too, for the same reasons.`);
	}
	if (stillOpen.length) {
		notes.push(`${stillOpen.length} position${stillOpen.length === 1 ? ' is' : 's are'} still open. Those are marked at the leader's last on-chain quote and reported as unrealized, never in the realized headline.`);
	}
	if (fills.length) {
		notes.push('Real copying adds slippage, priority fees and latency against you: your fills would land after the leader\'s, not at the same price. Treat this as the ceiling of the outcome, not the outcome.');
	}
	notes.push('Past results do not predict future results. This is a track record, not a forecast.');
	return notes;
}

// ---------------------------------------------------------------------------
// Data access.
//
// These queries deliberately do NOT swallow their errors into an empty array. On
// this surface an empty result is a real, meaningful answer ("this leader has no
// settled record yet") that the page renders as a designed empty state. If a
// database outage returned the same empty array, the page would confidently tell
// a visitor a profitable trader has no track record. A failure has to surface as
// a failure, so it reaches the endpoint's error boundary and the page's retry.
// ---------------------------------------------------------------------------

/**
 * Normalize raw agent_sniper_positions rows into simulator input. Rows whose
 * entry we cannot price are dropped (and counted by the caller) rather than
 * guessed at.
 */
export function normalizeLeaderTrades(rows = []) {
	const trades = [];
	let unpriced = 0;
	for (const r of rows) {
		const entrySol = lamToSol(r.entry_quote_lamports);
		if (!(entrySol > 0)) { unpriced++; continue; }

		// Derive the percentage from exact chain lamports; fall back to the stored
		// pct only when the P&L column is absent.
		let pnlPct = null;
		if (r.realized_pnl_lamports != null) pnlPct = (lamToSol(r.realized_pnl_lamports) / entrySol) * 100;
		else if (r.realized_pnl_pct != null) pnlPct = Number(r.realized_pnl_pct);

		const status = r.status === 'closed' ? 'closed' : 'open';
		if (status === 'closed' && pnlPct == null) { unpriced++; continue; }

		const lastValue = r.last_value_lamports == null ? null : lamToSol(r.last_value_lamports);
		trades.push({
			id: String(r.id),
			mint: r.mint,
			symbol: r.symbol || null,
			name: r.name || null,
			status,
			entry_sol: entrySol,
			pnl_pct: pnlPct == null ? 0 : pnlPct,
			mark_pct: status === 'open' && lastValue != null && lastValue > 0 ? ((lastValue - entrySol) / entrySol) * 100 : null,
			opened_at: toIso(r.opened_at),
			closed_at: toIso(r.closed_at),
			exit_reason: r.exit_reason || null,
			buy_sig: r.buy_sig || null,
			sell_sig: r.sell_sig || null,
			coin: null,
		});
	}
	trades.sort((a, b) => (a.opened_at < b.opened_at ? -1 : a.opened_at > b.opened_at ? 1 : 0));
	return { trades, unpriced };
}

function toIso(v) {
	if (!v) return null;
	if (typeof v === 'string') return v;
	try { return new Date(v).toISOString(); } catch { return null; }
}

/** The leader's identity card for the header. Null when the agent is not public. */
export async function fetchGhostLeader(agentId, network = 'mainnet') {
	const rows = await sql`
		select a.id, a.name, a.avatar_url, a.profile_image_url,
		       count(p.id) filter (where p.status = 'closed')::int as settled,
		       min(p.opened_at) as first_trade_at,
		       max(p.closed_at) as last_close_at
		from agent_identities a
		left join agent_sniper_positions p
		       on p.agent_id = a.id and p.network = ${network}
		where a.id = ${agentId} and a.deleted_at is null and a.is_public <> false
		group by a.id, a.name, a.avatar_url, a.profile_image_url
		limit 1
	`;
	const r = rows[0];
	if (!r) return null;
	return {
		agent_id: r.id,
		name: r.name || 'Unnamed trader',
		avatar: r.avatar_url || r.profile_image_url || null,
		settled: Number(r.settled || 0),
		first_trade_at: toIso(r.first_trade_at),
		last_close_at: toIso(r.last_close_at),
		profile_url: `/trader/${r.id}`,
	};
}

/** The leader's positions inside the window, oldest first. */
export async function fetchLeaderTrades(agentId, network = 'mainnet', sinceIso = null) {
	const rows = sinceIso
		? await sql`
			select id, mint, symbol, name, status, exit_reason,
			       entry_quote_lamports, realized_pnl_lamports, realized_pnl_pct,
			       last_value_lamports, opened_at, closed_at, buy_sig, sell_sig
			from agent_sniper_positions
			where agent_id = ${agentId} and network = ${network}
			  and status in ('open', 'closed') and opened_at >= ${sinceIso}
			order by opened_at asc
			limit ${MAX_GHOST_TRADES}
		`
		: await sql`
			select id, mint, symbol, name, status, exit_reason,
			       entry_quote_lamports, realized_pnl_lamports, realized_pnl_pct,
			       last_value_lamports, opened_at, closed_at, buy_sig, sell_sig
			from agent_sniper_positions
			where agent_id = ${agentId} and network = ${network}
			  and status in ('open', 'closed')
			order by opened_at asc
			limit ${MAX_GHOST_TRADES}
		`;
	return rows;
}

/**
 * Leaders worth ghost-copying: public agents with at least one closed round-trip
 * in the window, ranked by realized P&L. This is the picker's universe.
 */
export async function fetchGhostableLeaders(network = 'mainnet', { window = '7d', limit = 24, now = Date.now() } = {}) {
	const since = windowStartIso(WINDOWS.has(window) ? window : '7d', now);
	const rows = since
		? await sql`
			select a.id, a.name, a.avatar_url, a.profile_image_url,
			       count(p.id)::int as settled,
			       count(p.id) filter (where p.realized_pnl_lamports > 0)::int as wins,
			       coalesce(sum(p.realized_pnl_lamports), 0)::text as pnl_lamports,
			       coalesce(sum(p.entry_quote_lamports), 0)::text as entry_lamports,
			       max(p.closed_at) as last_close_at
			from agent_identities a
			join agent_sniper_positions p on p.agent_id = a.id
			where a.deleted_at is null and a.is_public <> false
			  and p.network = ${network} and p.status = 'closed'
			  and p.closed_at is not null and p.closed_at >= ${since}
			group by a.id, a.name, a.avatar_url, a.profile_image_url
			order by sum(p.realized_pnl_lamports) desc nulls last
			limit ${Math.min(100, Math.max(1, limit))}
		`
		: await sql`
			select a.id, a.name, a.avatar_url, a.profile_image_url,
			       count(p.id)::int as settled,
			       count(p.id) filter (where p.realized_pnl_lamports > 0)::int as wins,
			       coalesce(sum(p.realized_pnl_lamports), 0)::text as pnl_lamports,
			       coalesce(sum(p.entry_quote_lamports), 0)::text as entry_lamports,
			       max(p.closed_at) as last_close_at
			from agent_identities a
			join agent_sniper_positions p on p.agent_id = a.id
			where a.deleted_at is null and a.is_public <> false
			  and p.network = ${network} and p.status = 'closed' and p.closed_at is not null
			group by a.id, a.name, a.avatar_url, a.profile_image_url
			order by sum(p.realized_pnl_lamports) desc nulls last
			limit ${Math.min(100, Math.max(1, limit))}
		`;

	return rows.map((r) => {
		const settled = Number(r.settled || 0);
		const wins = Number(r.wins || 0);
		const pnlSol = lamToSol(r.pnl_lamports);
		const entrySol = lamToSol(r.entry_lamports);
		return {
			agent_id: r.id,
			name: r.name || 'Unnamed trader',
			avatar: r.avatar_url || r.profile_image_url || null,
			settled,
			win_rate_pct: settled > 0 ? round2((wins / settled) * 100) : null,
			pnl_sol: round4(pnlSol),
			roi_pct: entrySol > 0 ? round2((pnlSol / entrySol) * 100) : null,
			last_close_at: toIso(r.last_close_at),
			profile_url: `/trader/${r.id}`,
		};
	});
}

/**
 * End-to-end ghost run: fetch, normalize, simulate. Returns null when the leader
 * is unknown or private.
 */
export async function runGhostCopy({ agentId, network = 'mainnet', window = '7d', budgetSol, overrides = {}, now = Date.now() }) {
	const built = buildGhostSubscription({ budgetSol, ...overrides });
	if (!built.ok) return { error: built.error };

	const leader = await fetchGhostLeader(agentId, network);
	if (!leader) return null;

	const win = WINDOWS.has(window) ? window : '7d';
	const since = windowStartIso(win, now);
	const rows = await fetchLeaderTrades(agentId, network, since);
	const { trades, unpriced } = normalizeLeaderTrades(rows);

	const result = simulateGhostCopy({ trades, budgetSol, subscription: built.value });
	if (unpriced > 0) {
		result.honesty.push(`${unpriced} of this leader's positions could not be priced from chain data and were excluded rather than estimated.`);
	}
	if (rows.length >= MAX_GHOST_TRADES) {
		result.honesty.push(`This leader has more than ${MAX_GHOST_TRADES} positions in this window; the replay covers the oldest ${MAX_GHOST_TRADES}.`);
	}

	return {
		leader,
		network,
		window: win,
		window_start: since,
		budget_sol: round4(Number(budgetSol)),
		sizing: built.value,
		...result,
	};
}