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.

12.9 KB
Raw Blame
/**
 * Copy-trading anti-gaming layer: who may be copied, and when copying stops.
 *
 * Copy-trading dies the moment a track record can be faked or a follower can be
 * strapped to a runaway leader. Three defenses live here, all of them enforced
 * before money is committed and all of them derived from real, closed, on-chain
 * round-trips (agent_sniper_positions), never from a self-reported number:
 *
 *   1. SELF-COPY (wash trading). A user subscribing to an agent they own pays a
 *      performance fee to themselves, inflates that leader's public copier count,
 *      and inflates the "earned X for being copied" social-proof figure. Blocked
 *      at subscribe time and skipped again in the fanout, so a row that predates
 *      this rule cannot keep firing.
 *   2. SYBIL BAR on copyable status. A brand-new agent with no history could be
 *      followed the minute it was created. A leader now needs a real record:
 *      closed round-trips, elapsed time, and capital actually deployed, before
 *      anyone can attach money to it, so dust-trading a curve into existence
 *      buys nothing.
 *   3. DRAWDOWN CIRCUIT BREAKER. A copier sets the peak-to-trough loss they are
 *      willing to ride. When the leader's realized equity curve breaches it the
 *      subscription auto-pauses with a recorded reason, instead of mirroring a
 *      leader into the ground. The copier resumes it deliberately or not at all.
 *   4. CREATOR-LINKED LEADER. A "leader" whose trading wallet shares control with
 *      a coin's creator (shared fee payer, first funder) is not a trader to copy
 *      on that coin: a follower would just be mirroring the creator's own buy of
 *      their own launch, dressed up as a signal. Checked per (leader, mint) in the
 *      fanout, before any order is sized, with the reason surfaced on the skipped
 *      copy_executions row so the follower sees exactly why.
 *
 * Drawdown is expressed as a share of capital actually deployed
 * (max peak-to-trough loss / gross entry), the same definition
 * api/_lib/meta-allocator.js ranks on and api/_lib/mirror-stats.js reports, so
 * the number a copier sets a breaker against is the number on the Trader Card.
 */

import { sql } from './db.js';
import { resolveCreatorWallet } from './cosmetics-economy.js';

const LAMPORTS = 1e9;
const lamToSol = (l) => (l == null ? 0 : Number(BigInt(Math.trunc(Number(l)))) / LAMPORTS);
const n = (v) => (Number.isFinite(Number(v)) ? Number(v) : 0);
const clamp = (x, lo, hi) => Math.min(hi, Math.max(lo, x));
const round2 = (x) => Math.round(x * 100) / 100;
const round4 = (x) => Math.round(x * 1e4) / 1e4;

/**
 * Machine reason recorded on copy_subscriptions.paused_reason when the drawdown
 * breaker trips. The resume path in api/copy/subscriptions.js keys off it to
 * refuse a resume that would just re-pause on the next tick.
 */
export const BREAKER_REASON = 'leader_drawdown_breach';

/**
 * The bar an agent must clear before a copier may attach money to it.
 *
 * Deliberately modest: this is a floor against a zero-history sybil, not a
 * curation filter. A real trader clears it inside a normal week of trading.
 * Every threshold is measured on CLOSED round-trips, so open positions and
 * paper mode contribute nothing.
 */
export const LEADER_ELIGIBILITY = {
	/** Closed round-trips (a buy AND its exit) on the network being copied. */
	minSettled: 5,
	/** Hours between the leader's first and most recent close. Blocks a burst of dust trades minted in one minute. */
	minSpanHours: 24,
	/** Gross SOL actually deployed across those closes. Blocks a curve built out of 0.0001 SOL trades. */
	minDeployedSol: 0.1,
};

/** Human labels for each unmet criterion, for the UI and the API error body. */
const CRITERION_LABELS = {
	settled: (need, have) => `${have} of ${need} closed round-trips`,
	span_hours: (need, have) => `${have}h of ${need}h of trading history`,
	deployed_sol: (need, have) => `${have} of ${need} SOL deployed`,
};

/**
 * Decide whether a leader's record clears the copyable bar. PURE.
 *
 * @param {object} record  { settled, span_hours, deployed_sol }, real closed-trade stats.
 * @param {object} [bar]   override thresholds (tests, future per-tier bars).
 * @returns {{ eligible:boolean, unmet:Array<{criterion:string,need:number,have:number,label:string}>, met:object }}
 */
export function evaluateLeaderEligibility(record = {}, bar = LEADER_ELIGIBILITY) {
	const have = {
		settled: Math.floor(n(record.settled)),
		span_hours: round2(n(record.span_hours)),
		deployed_sol: round4(n(record.deployed_sol)),
	};
	const need = {
		settled: bar.minSettled,
		span_hours: bar.minSpanHours,
		deployed_sol: bar.minDeployedSol,
	};

	const unmet = [];
	for (const criterion of ['settled', 'span_hours', 'deployed_sol']) {
		if (have[criterion] < need[criterion]) {
			unmet.push({
				criterion,
				need: need[criterion],
				have: have[criterion],
				label: CRITERION_LABELS[criterion](need[criterion], have[criterion]),
			});
		}
	}
	return { eligible: unmet.length === 0, unmet, met: have };
}

/**
 * Decide whether a leader's realized drawdown has breached a copier's tolerance. PURE.
 *
 * A null tolerance means the copier opted out of the breaker; a null drawdown
 * means the leader has no measurable curve yet (no deployed capital), and an
 * unmeasurable leader is never auto-paused; the eligibility bar is what keeps
 * a history-less leader from being copied in the first place.
 *
 * @returns {{ breached:boolean, drawdown_pct:number|null, limit_pct:number|null, detail?:string }}
 */
export function evaluateDrawdownBreaker(sub = {}, leaderDrawdownPct = null) {
	const limit = sub.max_drawdown_pct == null ? null : n(sub.max_drawdown_pct);
	if (limit == null || limit <= 0) return { breached: false, drawdown_pct: leaderDrawdownPct, limit_pct: null };
	if (leaderDrawdownPct == null) return { breached: false, drawdown_pct: null, limit_pct: limit };

	const dd = n(leaderDrawdownPct);
	if (dd < limit) return { breached: false, drawdown_pct: round2(dd), limit_pct: limit };
	return {
		breached: true,
		drawdown_pct: round2(dd),
		limit_pct: limit,
		detail: `Leader drawdown ${round2(dd)}% reached your ${limit}% limit. Copying paused.`,
	};
}

/**
 * Real closed-trade profile for one leader on one network: the numbers both the
 * eligibility bar and the drawdown breaker are judged on.
 *
 * Returns zeros (never nulls dressed as numbers) for a leader with no closes, and
 * `max_drawdown_pct: null` when no capital was deployed, because a drawdown share
 * of zero deployed capital is undefined rather than 0%.
 */
export async function leaderCopyProfile(agentId, network = 'mainnet') {
	const rows = await sql`
		select realized_pnl_lamports, entry_quote_lamports, closed_at
		from agent_sniper_positions
		where agent_id = ${agentId} and network = ${network}
		  and status = 'closed' and closed_at is not null
		order by closed_at asc
	`.catch(() => []);

	return summarizeCopyProfile(rows);
}

/**
 * Fold closed round-trips into the copy profile. PURE, and exported so the equity
 * curve walk is testable without a database.
 *
 * @param {Array<{realized_pnl_lamports:*, entry_quote_lamports:*, closed_at:*}>} rows
 *        closed round-trips, oldest first.
 */
export function summarizeCopyProfile(rows = []) {
	let equity = 0;
	let peak = 0;
	let maxDrawdownSol = 0;
	let deployedSol = 0;
	let first = null;
	let last = null;

	for (const r of rows) {
		deployedSol += lamToSol(r.entry_quote_lamports);
		equity += lamToSol(r.realized_pnl_lamports);
		if (equity > peak) peak = equity;
		const dd = peak - equity;
		if (dd > maxDrawdownSol) maxDrawdownSol = dd;

		const at = r.closed_at ? new Date(r.closed_at).getTime() : NaN;
		if (Number.isFinite(at)) {
			if (first == null || at < first) first = at;
			if (last == null || at > last) last = at;
		}
	}

	const spanHours = first != null && last != null ? (last - first) / 3_600_000 : 0;
	const maxDrawdownPct = deployedSol > 0 ? clamp((maxDrawdownSol / deployedSol) * 100, 0, 100) : null;

	return {
		settled: rows.length,
		deployed_sol: round4(deployedSol),
		span_hours: round2(spanHours),
		realized_pnl_sol: round4(equity),
		max_drawdown_sol: round4(maxDrawdownSol),
		max_drawdown_pct: maxDrawdownPct == null ? null : round2(maxDrawdownPct),
		first_closed_at: first == null ? null : new Date(first).toISOString(),
		last_closed_at: last == null ? null : new Date(last).toISOString(),
	};
}

/**
 * Batch the drawdown percentage for a set of leaders in one query. The fanout
 * cron checks every leader it is about to mirror, and a leader with a thousand
 * copiers must not cost a thousand round-trips.
 *
 * @returns {Promise<Map<string, number|null>>} agent id → drawdown %, or null when unmeasurable.
 */
export async function leaderDrawdownPcts(agentIds, network = 'mainnet') {
	const out = new Map();
	if (!Array.isArray(agentIds) || agentIds.length === 0) return out;

	const rows = await sql`
		with closed as (
			select agent_id, closed_at, entry_quote_lamports,
			       sum(realized_pnl_lamports) over (
			           partition by agent_id order by closed_at
			           rows between unbounded preceding and current row) as cum_pnl
			from agent_sniper_positions
			where agent_id = any(${agentIds}) and network = ${network}
			  and status = 'closed' and closed_at is not null
		),
		curve as (
			select agent_id, cum_pnl, entry_quote_lamports,
			       max(cum_pnl) over (
			           partition by agent_id order by closed_at
			           rows between unbounded preceding and current row) as peak
			from closed
		)
		select agent_id,
		       max(peak - cum_pnl)::text as max_dd_lamports,
		       coalesce(sum(entry_quote_lamports), 0)::text as entry_lamports
		from curve group by agent_id
	`.catch(() => []);

	for (const r of rows) {
		const deployed = lamToSol(r.entry_lamports);
		const dd = lamToSol(r.max_dd_lamports);
		out.set(r.agent_id, deployed > 0 ? round2(clamp((dd / deployed) * 100, 0, 100)) : null);
	}
	return out;
}

const LINKAGE_BAND_ORDER = ['none', 'weak', 'moderate', 'strong', 'confirmed'];

/**
 * Human reason shown on the skipped copy_executions row when a leader's wallet
 * links to the coin's creator. Mirrors the honeypot/mcap reasons copy-engine.js
 * already attaches to a skip.
 */
export const CREATOR_LINK_REASON = 'leader_linked_to_creator';

/**
 * Decide whether a single wallet-linkage pair means "this leader is the
 * creator" for copy-trading purposes. PURE: takes the one pair
 * `analyzeLinkage()` returns for a 2-address call, never touches DB/RPC.
 *
 * @param {{score:number, band:string, topSignal?:string|null}|null} pair
 * @param {{ band?: string }} [opts] trip threshold, default "strong" (score 65+)
 * @returns {{ linked:boolean, score:number|null, band:string|null, topSignal:string|null }}
 */
export function evaluateLeaderCreatorLinkPair(pair, { band = 'strong' } = {}) {
	if (!pair) return { linked: false, score: null, band: null, topSignal: null };
	const threshold = LINKAGE_BAND_ORDER.indexOf(band);
	const linked = LINKAGE_BAND_ORDER.indexOf(pair.band) >= threshold;
	return { linked, score: pair.score ?? null, band: pair.band ?? null, topSignal: pair.topSignal ?? null };
}

/**
 * Is this leader's trading wallet the same controller as this coin's creator?
 * Resolves the creator (DB first, live pump.fun bonding-curve read as a last
 * resort, via `resolveCreatorWallet`), then scores the one pair with
 * `@three-ws/wallet-linkage`'s `analyzeLinkage`, given the caller's own
 * injected RPC connection so this never hits a hardcoded endpoint.
 *
 * Fails CLOSED toward "not linked": a missing creator, a missing leader
 * wallet, or any RPC/DB error returns `linked:false` rather than guessing.
 * The eligibility bar above already keeps a history-less leader uncopyable,
 * so this check only adds signal, it never has to carry the whole gate alone.
 *
 * @param {object} o
 * @param {string} o.leaderWallet  the leader's own trading wallet (runtime input)
 * @param {string} o.mint          the coin being copied
 * @param {import('@solana/web3.js').Connection} o.connection  injected RPC
 * @param {{ band?: string }} [o.opts]
 * @returns {Promise<{ linked:boolean, creator:string|null, score:number|null, band:string|null, topSignal:string|null }>}
 */
export async function checkLeaderCreatorLinkage({ leaderWallet, mint, connection, opts = {} }) {
	if (!leaderWallet) return { linked: false, creator: null, score: null, band: null, topSignal: null };

	let creator = null;
	try {
		({ wallet: creator } = await resolveCreatorWallet(mint));
	} catch {
		return { linked: false, creator: null, score: null, band: null, topSignal: null };
	}
	if (!creator || creator === leaderWallet) {
		return { linked: false, creator, score: null, band: null, topSignal: null };
	}

	try {
		const { analyzeLinkage } = await import('@three-ws/wallet-linkage');
		const { pairs } = await analyzeLinkage(connection, [leaderWallet, creator]);
		return { ...evaluateLeaderCreatorLinkPair(pairs[0] ?? null, opts), creator };
	} catch {
		return { linked: false, creator, score: null, band: null, topSignal: null };
	}
}