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.

23.5 KB
Raw Blame
// Oracle — store. Reads/writes Oracle's own tables and orchestrates the
// score-one-coin flow (assemble intel from the brain → ensure a narrative read →
// fuse conviction → cache it). Used by both the ingestion augmentor (writes) and
// the read APIs (lazy-score-on-miss, so the feed is warm even before the worker
// has swept a brand-new coin).

import { sql, isDbUnavailableError } from '../db.js';
import { assembleIntel, walletProfile, coinOutcome } from './sources.js';
import { classifyNarrative } from './narrative.js';
import { convict, hitRateFor, PREDICTED_EVENT } from './conviction.js';
import { ensureActiveModel, modelProvenance } from './model-store.js';
import { summarizeActions } from './settle.js';
import { evaluateExit } from './exit.js';
import { knownWallet, loadKnownWallets } from './known-wallets.js';
import { QUOTE_MINT_LIST, isQuoteMint } from '../quote-mints.js';

/** Persist a narrative classification. */
export async function upsertNarrative(mint, network, narr) {
	await sql`
		insert into oracle_narrative (mint, network, category, narrative, virality, confidence, tags, source, classified_at)
		values (${mint}, ${network}, ${narr.category}, ${narr.narrative}, ${narr.virality},
		        ${narr.confidence}, ${JSON.stringify(narr.tags || [])}::jsonb, ${narr.source}, now())
		on conflict (mint, network) do update set
			category = excluded.category, narrative = excluded.narrative,
			virality = excluded.virality, confidence = excluded.confidence,
			tags = excluded.tags, source = excluded.source, classified_at = now()
	`;
}

/** Persist a fused conviction verdict for a coin. */
export async function upsertConviction({ mint, network, intel, verdict }) {
	// Fetch the previous score before overwriting so we can decide whether to
	// append a history row. Skips the SELECT when the table is warm (will be null
	// only on cold misses or the very first score for a coin).
	const prev = await sql`
		select score from oracle_conviction where mint = ${mint} and network = ${network} limit 1
	`.then((r) => (r[0] ? Number(r[0].score) : null)).catch(() => null);

	const upserted = await sql`
		insert into oracle_conviction (
			mint, network, symbol, name, image_uri,
			score, tier, pedigree, structure, narrative, momentum, structure_cap,
			badges, reasons, components, category, smart_wallet_count, coin_first_seen_at, scored_at,
			rug_risk, upside, give_back_risk, model_version_id
		) values (
			${mint}, ${network}, ${intel.symbol || null}, ${intel.name || null}, ${intel.image_uri || null},
			${verdict.score}, ${verdict.tier}, ${verdict.pillars.pedigree}, ${verdict.pillars.structure},
			${verdict.pillars.narrative}, ${verdict.pillars.momentum}, ${verdict.structureCap},
			${JSON.stringify(verdict.badges)}::jsonb, ${JSON.stringify(verdict.reasons)}::jsonb,
			${JSON.stringify(componentSummary(intel, verdict))}::jsonb, ${intel.category || null},
			${intel.smartMoney?.smartWalletCount || 0}, ${intel.createdAt || null}, now(),
			${verdict.rugRisk ?? null}, ${verdict.upside ?? null}, ${verdict.giveBackRisk ?? null},
			${modelProvenance().version_id}
		)
		on conflict (mint, network) do update set
			symbol = excluded.symbol, name = excluded.name, image_uri = excluded.image_uri,
			score = excluded.score, tier = excluded.tier,
			pedigree = excluded.pedigree, structure = excluded.structure,
			narrative = excluded.narrative, momentum = excluded.momentum,
			structure_cap = excluded.structure_cap, badges = excluded.badges,
			reasons = excluded.reasons, components = excluded.components,
			category = excluded.category, smart_wallet_count = excluded.smart_wallet_count,
			rug_risk = excluded.rug_risk, upside = excluded.upside,
			give_back_risk = excluded.give_back_risk,
			model_version_id = excluded.model_version_id,
			scored_at = now()
		returning (xmax = 0) as inserted
	`;

	// oracle_conviction is retention-pruned, so count(*) over it can never be a
	// lifetime figure. Bump the durable counter exactly when this was a
	// first-ever score for the (mint, network). Non-fatal — the counter is a
	// stat, never worth failing a score over.
	if (upserted[0]?.inserted) {
		await sql`
			insert into oracle_counters (network, key, value)
			values (${network}, 'scored_lifetime', 1)
			on conflict (network, key) do update set
				value = oracle_counters.value + 1, updated_at = now()
		`.catch(() => { /* counter table may predate migration */ });
	}

	// Write a history row when the score changes by ≥3 pts or it's the first score.
	const delta = prev == null ? Infinity : Math.abs(verdict.score - prev);
	if (delta >= 3) {
		await sql`
			insert into oracle_conviction_history
				(mint, network, score, tier, pedigree, structure, narrative, momentum,
				 rug_risk, upside, give_back_risk)
			values (
				${mint}, ${network}, ${verdict.score}, ${verdict.tier},
				${verdict.pillars.pedigree}, ${verdict.pillars.structure},
				${verdict.pillars.narrative}, ${verdict.pillars.momentum},
				${verdict.rugRisk ?? null}, ${verdict.upside ?? null}, ${verdict.giveBackRisk ?? null}
			)
		`.catch(() => { /* non-fatal — history is a nice-to-have */ });
	}
}

// Compact audit trail of the normalized inputs that produced a verdict, plus the
// verdict's data-confidence so the coin view can show how much of the read rests
// on real data vs. defaulted inputs (no dedicated column needed).
function componentSummary(intel, verdict) {
	return {
		pedigree: intel.smartMoney,
		structure: intel.structure,
		narrative: intel.narrative,
		behavior: intel.behavior,
		quality: intel.qualityScore,
		risk_flags: intel.riskFlags,
		confidence: verdict?.confidence ?? null,
		confidence_label: verdict?.confidenceLabel ?? null,
		pedigree_cap: verdict?.pedigreeCap ?? null,
	};
}

/**
 * Score one coin end-to-end. Assembles intel from the brain; if no narrative
 * read exists yet (and classify=true) it runs the classifier and stores it;
 * fuses conviction; caches it. Returns the verdict + intel, or null if the coin
 * is unknown to the brain.
 *
 * @param {string} mint
 * @param {object} opts { network, classify, persist }
 */
export async function scoreCoin(mint, { network = 'mainnet', classify = true, persist = true } = {}) {
	// Make sure this container is scoring with the newest promoted model before
	// it forms an opinion. Cached for two minutes and shared across concurrent
	// callers, so a batch sweep costs one query, and it never throws: a model
	// lookup that fails leaves the installed model scoring rather than taking the
	// whole feed down over a stale opinion.
	await ensureActiveModel({ network });

	let intel = await assembleIntel(mint, network);
	if (!intel) return null;

	// Ensure a narrative read with a virality estimate. If the brain hasn't given
	// us one (oracle_narrative miss → fallback used a proxy with no virality),
	// classify now and persist so the next read is warm.
	if (classify && (intel.narrative?.virality == null)) {
		const narr = await classifyNarrative({
			name: intel.name, symbol: intel.symbol,
			// The description lives on intel.social (set by toCoinIntel); the old
			// intel.components path never existed, so the classifier was always run
			// blind. Thread the real off-chain signal (description + links) through.
			description: intel.social?.description,
			twitter: intel.social?.twitter,
			telegram: intel.social?.telegram,
			website: intel.social?.website,
		});
		if (persist) { try { await upsertNarrative(mint, network, narr); } catch { /* non-fatal */ } }
		intel = { ...intel, narrative: narr, category: narr.category };
	}

	const verdict = convict(intel);
	if (persist) { try { await upsertConviction({ mint, network, intel, verdict }); } catch { /* non-fatal */ } }
	return { intel, verdict };
}

/**
 * Read the live conviction feed. Serves from the oracle_conviction cache.
 * @param {object} opts { network, limit, minScore, tier, category, sinceSeconds }
 */
export async function readFeed({ network = 'mainnet', limit = 50, minScore = 0, tier = null, category = null, sinceSeconds = 12 * 3600 } = {}) {
	const lim = Math.min(200, Math.max(1, Number(limit) || 50));
	const rows = await sql`
		select c.mint, c.symbol, c.name, c.image_uri, c.score, c.tier,
		       c.pedigree, c.structure, c.narrative, c.momentum,
		       c.badges, c.reasons, c.category, c.smart_wallet_count, c.scored_at, c.coin_first_seen_at,
		       c.rug_risk, c.upside, c.give_back_risk,
		       o.graduated, o.rugged, o.ath_multiple, o.hold_multiple,
		       hist.spark
		from oracle_conviction c
		left join pump_coin_outcomes o on o.mint = c.mint
		left join lateral (
			select array_agg(h.score order by h.scored_at)::int[] as spark
			from (
				select score, scored_at
				from oracle_conviction_history
				where mint = c.mint and network = c.network
				  and scored_at > now() - interval '24 hours'
				order by scored_at desc
				limit 16
			) h
		) hist on true
		where c.network = ${network}
		  and c.score >= ${Number(minScore) || 0}
		  and (${tier}::text is null or c.tier = ${tier})
		  and (${category}::text is null or c.category = ${category})
		  and c.mint <> all(${QUOTE_MINT_LIST}::text[])
		  and c.scored_at > now() - (${sinceSeconds} || ' seconds')::interval
		order by c.score desc, c.scored_at desc
		limit ${lim}
	`;
	return rows.map(rowToFeedItem);
}

/** Newly-scored coins after a cursor — powers the SSE stream. */
export async function feedSince({ network = 'mainnet', sinceIso, limit = 40 } = {}) {
	const rows = await sql`
		select mint, symbol, name, image_uri, score, tier, pedigree, structure, narrative, momentum,
		       badges, category, smart_wallet_count, scored_at, coin_first_seen_at
		from oracle_conviction
		where network = ${network} and scored_at > ${sinceIso}::timestamptz
		  and mint <> all(${QUOTE_MINT_LIST}::text[])
		order by scored_at asc
		limit ${Math.min(100, Math.max(1, limit))}
	`;
	return rows.map(rowToFeedItem);
}

/**
 * The resolved market outcome on a feed row, or null when the join was not part
 * of the query (feedSince) or the market has not resolved the coin yet.
 * @param {object} r
 */
function outcomeFromRow(r) {
	if (r.graduated == null && r.rugged == null && r.ath_multiple == null) return null;
	const ath = r.ath_multiple != null ? Number(r.ath_multiple) : null;
	return {
		graduated: r.graduated === true,
		rugged: r.rugged === true,
		ath_multiple: Number.isFinite(ath) ? ath : null,
	};
}

function rowToFeedItem(r) {
	// Compact conviction trajectory for the inline card sparkline: the recorded
	// history points (24h, ≤16) with the live score guaranteed as the final point.
	let spark = Array.isArray(r.spark) ? r.spark.map(Number).filter(Number.isFinite) : [];
	if (r.score != null && (spark.length === 0 || spark[spark.length - 1] !== r.score)) spark.push(r.score);

	// The strongest fitted evidence behind this specific score. The feed used to
	// ship the number alone, so every card had to fall back to a per-tier
	// template and the whole page read as one sentence copy-pasted 200 times,
	// even though the engine had already written a different, quantified reason
	// for each coin. Three is what a card can show; the rest are on the coin page.
	const reasons = Array.isArray(r.reasons)
		? r.reasons
			.filter((x) => x && x.text)
			.slice(0, 3)
			.map((x) => ({ pillar: x.pillar || null, text: String(x.text) }))
		: [];

	// What the score has been worth in resolved outcomes, so no surface has to
	// treat a 0-100 rank as if it were a percentage.
	const odds = hitRateFor(r.score);

	return {
		mint: r.mint, symbol: r.symbol, name: r.name, image_uri: r.image_uri,
		score: r.score, tier: r.tier,
		pillars: { pedigree: r.pedigree, structure: r.structure, narrative: r.narrative, momentum: r.momentum },
		badges: r.badges || [],
		reasons,
		// The three v3 numbers, carried on every card. `give_back_risk` is the one
		// that answers "why is this scored well when the chart is a cliff": it is
		// the share of coins like this one that run and then hand it all back.
		rug_risk: r.rug_risk ?? null,
		upside: r.upside ?? null,
		give_back_risk: r.give_back_risk ?? null,
		hit_rate: odds.rate,
		hit_rate_lift: odds.lift,
		hit_rate_n: odds.n,
		hit_rate_band: odds.band,
		base_rate: odds.baseRate,
		category: r.category,
		smart_wallet_count: r.smart_wallet_count,
		scored_at: r.scored_at,
		coin_first_seen_at: r.coin_first_seen_at,
		spark: spark.length >= 2 ? spark : null,
		// Ground truth, carried on the card itself. The feed ranks by score, so its
		// top rows are the boldest calls, and a resolved one whose verdict is stated
		// without its result is the whole reason the engine reads as broken. Absent
		// (undefined) for callers that do not join outcomes, e.g. the SSE stream.
		outcome: outcomeFromRow(r),
	};
}

/** Full intel for one coin: cached verdict + live who's-in trader breakdown. */
export async function readCoin(mint, network = 'mainnet') {
	// Quote/stablecoin/LST mints are not coins — never serve a conviction read for
	// one, even if a stale row lingers before the next purge sweep.
	if (isQuoteMint(mint)) {
		return { conviction: null, reasons: [], components: null, structure_cap: null, narrative: null, outcome: null, whos_in: [] };
	}
	const cached = await sql`
		select * from oracle_conviction where mint = ${mint} and network = ${network} limit 1
	`.then((r) => r[0]).catch(() => null);

	// "Who's in" — join the coin's wallet footprint to reputation labels, ranked
	// by net SOL in. This is the trader classification the user asked for, live.
	const whosIn = await sql`
		select w.wallet, w.buy_lamports, w.sell_lamports, w.is_creator, w.funder,
		       r.label, r.smart_money_score, r.win_rate, r.early_win_rate
		from pump_coin_wallets w
		left join wallet_reputation r on r.wallet = w.wallet and r.network = ${network}
		where w.mint = ${mint}
		order by w.buy_lamports desc
		limit 40
	`.catch(() => []);

	const [, narr, outcome] = await Promise.all([
		loadKnownWallets(),
		sql`select category, narrative, virality, confidence, source from oracle_narrative where mint = ${mint} and network = ${network} limit 1`
			.then((r) => r[0]).catch(() => null),
		coinOutcome(mint, network),
	]);

	return {
		conviction: cached ? rowToFeedItem(cached) : null,
		reasons: cached?.reasons || [],
		components: cached?.components || null,
		structure_cap: cached?.structure_cap ?? null,
		// The event the score was fitted to predict, so no surface has to guess.
		// A bare "100" invites the reader to hear "certain"; the verdict travels
		// with what it claims (a 3x run or a graduation, not a safe hold) and, on
		// the conviction object above, with what that band has actually returned.
		predicts: PREDICTED_EVENT,
		narrative: narr,
		outcome,
		whos_in: whosIn.map((w) => {
			const brainLabel = w.label && w.label !== 'unproven' ? w.label : null;
			const known = brainLabel ? null : knownWallet(w.wallet);
			return {
				wallet: w.wallet,
				// Brain reputation wins; the known-wallet prior fills the gap for
				// wallets the brain hasn't judged yet.
				label: brainLabel || known?.label || 'unproven',
				score: w.smart_money_score != null ? Number(w.smart_money_score) : (known?.score ?? null),
				win_rate: w.win_rate != null ? Number(w.win_rate) : null,
				early_win_rate: w.early_win_rate != null ? Number(w.early_win_rate) : null,
				source: brainLabel ? 'brain' : (known ? 'gmgn' : null),
				tag: known?.tag || null,
				buy_sol: Number(w.buy_lamports || 0) / 1e9,
				sell_sol: Number(w.sell_lamports || 0) / 1e9,
				is_creator: w.is_creator,
				funder: w.funder,
			};
		}),
	};
}

/** Wallet reputation leaderboard. */
export async function readLeaderboard({ network = 'mainnet', limit = 50, label = null } = {}) {
	const rows = await sql`
		select wallet, label, smart_money_score, win_rate, early_win_rate, dump_rate,
		       coins_traded, early_entries, wins, duds, last_active_at
		from wallet_reputation
		where network = ${network}
		  and (${label}::text is null or label = ${label})
		order by smart_money_score desc nulls last
		limit ${Math.min(200, Math.max(1, limit))}
	`.catch(() => []);
	return rows.map((r) => ({
		wallet: r.wallet, label: r.label, score: Number(r.smart_money_score || 0),
		win_rate: Number(r.win_rate || 0), early_win_rate: Number(r.early_win_rate || 0),
		dump_rate: Number(r.dump_rate || 0), coins_traded: r.coins_traded,
		early_entries: r.early_entries, wins: r.wins, duds: r.duds, last_active_at: r.last_active_at,
	}));
}

/** A wallet's full profile (rep + recent coins). */
export async function readWallet(wallet, network = 'mainnet') {
	return walletProfile(wallet, network);
}

/**
 * Proof of edge: conviction-tier win rate. Joins cached verdicts to ground-truth
 * outcomes and reports, per tier, how often the coin went on to graduate / N×.
 */
export async function convictionBacktest({ network = 'mainnet' } = {}) {
	const rows = await sql`
		select c.tier,
		       count(*)::int                                             as scored,
		       count(o.mint)::int                                        as resolved,
		       coalesce(sum(case when o.graduated then 1 else 0 end),0)::int as graduated,
		       coalesce(sum(case when o.rugged then 1 else 0 end),0)::int    as rugged,
		       coalesce(avg(o.ath_multiple),0)::numeric                  as avg_ath_multiple
		from oracle_conviction c
		left join pump_coin_outcomes o on o.mint = c.mint
		where c.network = ${network}
		group by c.tier
	`.catch(() => []);
	const order = { prime: 0, strong: 1, lean: 2, watch: 3, avoid: 4 };
	return rows
		.map((r) => ({
			tier: r.tier, scored: r.scored, resolved: r.resolved,
			graduated: r.graduated, rugged: r.rugged,
			grad_rate: r.resolved ? Math.round((r.graduated / r.resolved) * 100) : null,
			avg_ath_multiple: Number(r.avg_ath_multiple) || 0,
		}))
		.sort((a, b) => (order[a.tier] ?? 9) - (order[b.tier] ?? 9));
}

// ── Agent watch (action loop config) ─────────────────────────────────────────

export async function getWatch(agentId, network = 'mainnet') {
	return sql`select * from oracle_agent_watch where agent_id = ${agentId} and network = ${network} limit 1`
		.then((r) => r[0] || null).catch(() => null);
}

export async function upsertWatch(agentId, userId, network, cfg) {
	const row = await sql`
		insert into oracle_agent_watch (
			agent_id, user_id, network, armed, mode, min_score, min_tier, categories,
			per_trade_sol, max_daily_sol, max_open, require_smart_money, size_scaling,
			telegram_chat_id, updated_at
		) values (
			${agentId}, ${userId || null}, ${network}, ${!!cfg.armed}, ${cfg.mode || 'simulate'},
			${cfg.min_score ?? 80}, ${cfg.min_tier || 'strong'}, ${JSON.stringify(cfg.categories || [])}::jsonb,
			${cfg.per_trade_sol ?? 0.05}, ${cfg.max_daily_sol ?? 0.5}, ${cfg.max_open ?? 5},
			${cfg.require_smart_money !== false}, ${!!cfg.size_scaling},
			${cfg.telegram_chat_id || null}, now()
		)
		on conflict (agent_id, network) do update set
			user_id = coalesce(excluded.user_id, oracle_agent_watch.user_id),
			armed = excluded.armed, mode = excluded.mode, min_score = excluded.min_score,
			min_tier = excluded.min_tier, categories = excluded.categories,
			per_trade_sol = excluded.per_trade_sol, max_daily_sol = excluded.max_daily_sol,
			max_open = excluded.max_open, require_smart_money = excluded.require_smart_money,
			size_scaling = excluded.size_scaling, telegram_chat_id = excluded.telegram_chat_id,
			updated_at = now()
		returning *
	`;
	return row[0];
}

/**
 * Conviction score history for a coin, oldest point first, up to 200 points.
 * The ascending order is load-bearing: /api/oracle/history derives its rising /
 * falling trend from the first and last elements.
 */
export async function readScoreHistory(mint, network = 'mainnet', hours = 72) {
	const rows = await sql`
		select score, tier, pedigree, structure, narrative, momentum, scored_at
		from oracle_conviction_history
		where mint = ${mint} and network = ${network}
		  and scored_at > now() - (${hours} || ' hours')::interval
		order by scored_at asc
		limit 200
	`.catch((err) => {
		// The sparkline reads an empty series as "this coin has no recorded
		// conviction movement", which is what the caller sees during a
		// connectivity failure too, cached for 60s by /api/oracle/history.
		// Propagate so wrap() answers 503; a statement fault still degrades.
		if (isDbUnavailableError(err)) throw err;
		return [];
	});
	return rows.map((r) => ({
		score: r.score,
		tier: r.tier,
		pillars: {
			pedigree: r.pedigree, structure: r.structure,
			narrative: r.narrative, momentum: r.momentum,
		},
		scored_at: r.scored_at,
	}));
}

/** Purge conviction history older than 72 hours. Called by the score cron. */
export async function purgeOldHistory(network = 'mainnet') {
	await sql`
		delete from oracle_conviction_history
		where scored_at < now() - interval '72 hours'
		  and network = ${network}
	`.catch(() => { /* non-fatal */ });
}

/**
 * Remove any quote/stablecoin/LST mints (USDC, USDT, wSOL, …) that were cached
 * before the ingestion guard existed. The read paths already filter them out,
 * but this self-heals the stored data so they stop wasting rows. Called by the
 * score cron. Returns the number of conviction rows deleted.
 */
export async function purgeQuoteMints(network = 'mainnet') {
	const deleted = await sql`
		delete from oracle_conviction
		where network = ${network} and mint = any(${QUOTE_MINT_LIST}::text[])
		returning mint
	`.then((r) => r.length).catch(() => 0);
	await Promise.all([
		sql`delete from oracle_conviction_history where network = ${network} and mint = any(${QUOTE_MINT_LIST}::text[])`.catch(() => {}),
		sql`delete from oracle_narrative where network = ${network} and mint = any(${QUOTE_MINT_LIST}::text[])`.catch(() => {}),
	]);
	return deleted;
}

export async function recentActions(agentId, network = 'mainnet', limit = 50) {
	const rows = await sql`
		select a.mint, a.symbol, a.conviction, a.tier, a.mode, a.size_sol, a.status, a.reason,
		       a.tx_signature, a.peak_multiple, a.realized_pnl_sol, a.outcome, a.acted_at,
		       oc.score  as current_score,
		       oc.tier   as current_tier,
		       oc.badges as current_badges
		from oracle_watch_actions a
		left join oracle_conviction oc
		       on oc.mint = a.mint and oc.network = a.network
		      and (a.outcome is null or a.outcome = 'open')
		where a.agent_id = ${agentId} and a.network = ${network}
		order by a.acted_at desc limit ${Math.min(100, Math.max(1, limit))}
	`.catch(() => []);

	// Attach an exit signal to open positions whose thesis has since broken —
	// completing the loop the entry-only agent leaves open. Uses the coin's current
	// cached verdict (score, tier, badges); the live market multiple isn't joined
	// here, so profit/stop triggers stay dormant and only the conviction/red-flag
	// triggers fire from this read.
	return rows.map((r) => {
		const isOpen = !r.outcome || r.outcome === 'open';
		let exit_signal = null;
		if (isOpen && r.current_score != null) {
			const sig = evaluateExit({
				position: { entryConviction: r.conviction, entryTier: r.tier },
				current: { score: r.current_score, tier: r.current_tier, badges: r.current_badges || [] },
			});
			if (sig.exit) exit_signal = { trigger: sig.trigger, reason: sig.reason, urgency: sig.urgency };
		}
		return { ...r, exit_signal };
	});
}

/** Agent win-rate summary across all its actions. */
export async function actionsSummary(agentId, network = 'mainnet') {
	const rows = await sql`
		select outcome, realized_pnl_sol, size_sol
		from oracle_watch_actions
		where agent_id = ${agentId} and network = ${network}
	`.catch(() => []);
	return summarizeActions(rows.map((r) => ({
		outcome: r.outcome,
		realized_pnl_sol: r.realized_pnl_sol != null ? Number(r.realized_pnl_sol) : null,
		size_sol: r.size_sol != null ? Number(r.size_sol) : 0,
	})));
}