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
feat(duels): add the trader duels engine over the points-only schema
nirholas85e2bd689acd
diff --git a/api/_lib/trader-duels.js b/api/_lib/trader-duels.jsnew file mode 100644index 000000000..365263e4c--- /dev/null+++ b/api/_lib/trader-duels.js@@ -0,0 +1,954 @@+// Trader duels: a points-only skill-prediction game on head-to-head trader matchups.+// ---------------------------------------------------------------------------+// Roadmap 917 item 12.6, built free to play. Nobody deposits, stakes or wins+// anything of value: every user gets a daily allowance of duel points, points+// have no cash value, and they cannot be bought, sold, transferred or redeemed.+// No token, no escrow, no payout rail.+//+// The loop:+//+// generate /api/cron/duels-tick asks the rivalry engine (api/_lib/rivalries.js)+// for the trader pairs that sit next to each other on the 30-day+// board and opens a duel for each over the NEXT fixed UTC window: a+// 24-hour duel for tomorrow, and from Thursday a week-long duel for+// the week starting Monday.+// call a signed-in user picks a side and stakes 10 to 100 points. One call+// per user per duel, locked when the window starts, and never on a+// duel involving an agent the caller owns. The insert itself enforces+// all three, so a racing request cannot slip past a pre-check.+// resolve after the window closes (plus a grace period for late ledger+// writes) the realized P&L each trader booked inside the window is+// measured through computeTraderMetrics, the same math /trader/:id+// shows, and the side that booked more wins.+// settle a correct call returns twice its stake and earns XP in the shared+// quest ledger (trading_quest_completions, code 'duel:<market id>');+// a wrong call keeps nothing; a void duel refunds every stake.+//+// Void rules (every stake refunded, no XP):+// trader_unavailable either trader went private or was deleted, at any point+// before the duel resolved+// no_trades neither trader closed a trade in the window+// tie both booked exactly the same realized P&L+// A trader who closed nothing while the other did is scored as flat (0 SOL):+// sitting out beats losing, and loses to any profit.++import { sql } from './db.js';+import { getRivalries } from './rivalries.js';+import {+ computeTraderMetrics,+ fetchTraderPositions,+ selfDealMintsForUser,+ cachedSolUsd,+} from './trader-stats.js';+import { unlockBadge, listBadges, BADGES } from './streaks.js';+import { levelFor } from './trading-quests.js';+import { isUuid } from './validate.js';++// ── rules (every number the UI quotes comes from here) ──────────────────────++export const DUEL_RULES = Object.freeze({+ daily_allowance: 100,+ min_stake: 10,+ max_stake: 100,+ win_multiplier: 2,+ xp_per_win: 15,+ board_window: '30d',+ board_min_closed: 3,+ max_per_window: 3,+ resolve_grace_minutes: 15,+ week_open_lead_days: 4,+});++export const NETWORKS = new Set(['mainnet', 'devnet']);+export const PHASES = new Set(['open', 'live', 'settled', 'all']);+export const XP_CODE_PREFIX = 'duel:';++const DAY_MS = 86_400_000;+const GRACE_MS = DUEL_RULES.resolve_grace_minutes * 60_000;+const WEEK_LEAD_MS = DUEL_RULES.week_open_lead_days * DAY_MS;+const n = (v) => (Number.isFinite(Number(v)) ? Number(v) : 0);+const iso = (ms) => new Date(ms).toISOString();+const ms = (v) => (typeof v === 'number' ? v : Date.parse(v));++export const DUEL_BADGES = Object.freeze([+ { code: BADGES.DUEL_FIRST, how: 'Make your first call on a trader duel.' },+ { code: BADGES.DUEL_HIT, how: 'Call a trader duel correctly.' },+ { code: BADGES.DUEL_STREAK_3, how: 'Call three decided duels in a row correctly.' },+ { code: BADGES.DUEL_SHARP, how: 'Be right on at least 70% of ten or more decided duels.' },+]);+const DUEL_BADGE_CODES = new Set(DUEL_BADGES.map((b) => b.code));++// ── windows (pure) ──────────────────────────────────────────────────────────++/** Start of the UTC day containing `now`, in ms. PURE. */+export function utcDayStart(now = Date.now()) {+ return Math.floor(ms(now) / DAY_MS) * DAY_MS;+}++/**+ * The next window of a kind that has not started yet. A day window is the next+ * UTC day; a week window runs Monday 00:00 UTC to the following Monday. PURE.+ * @returns {{start:number, end:number}}+ */+export function nextWindow(kind, now = Date.now()) {+ const today = utcDayStart(now);+ if (kind === 'day') return { start: today + DAY_MS, end: today + 2 * DAY_MS };+ if (kind !== 'week') throw new RangeError(`unknown window kind: ${kind}`);+ const dow = new Date(today).getUTCDay(); // 0 Sunday .. 6 Saturday+ const days = (8 - dow) % 7 || 7;+ const start = today + days * DAY_MS;+ return { start, end: start + 7 * DAY_MS };+}++/**+ * Whether the generator should open duels for a window yet. Day duels open as+ * soon as the previous day starts; week duels open once the week is at most+ * `week_open_lead_days` away, so a call is never parked for two weeks. PURE.+ */+export function windowOpensNow(kind, start, now = Date.now()) {+ const lead = ms(start) - ms(now);+ if (lead <= 0) return false;+ return kind === 'day' ? lead <= DAY_MS : lead <= WEEK_LEAD_MS;+}++/**+ * Where a duel is in its life. open: taking calls. live: window running, calls+ * locked. resolving: window closed, waiting for the grace period and the cron.+ * resolved / void: settled. PURE.+ */+export function duelPhase(market, now = Date.now()) {+ if (market.status === 'void') return 'void';+ if (market.status === 'resolved') return 'resolved';+ const t = ms(now);+ if (t < ms(market.window_start)) return 'open';+ if (t < ms(market.window_end)) return 'live';+ return 'resolving';+}++/** When the cron will resolve a duel, as ISO. PURE. */+export function resolvesAt(market) {+ return iso(ms(market.window_end) + GRACE_MS);+}++// ── market generation (pure) ────────────────────────────────────────────────++function sideSnapshot(t) {+ return {+ agent_id: t.agent_id,+ name: t.name || 'Unnamed trader',+ image: t.image || null,+ rank: t.rank ?? null,+ score: t.score ?? null,+ closed: t.closed ?? null,+ win_rate: t.win_rate ?? null,+ realized_pnl_sol: t.realized_pnl_sol ?? null,+ };+}++/**+ * Turn rivalry-engine matchups into duel specs. Each rivalry is a leader and+ * the trader directly below them on the board, which is the only pairing the+ * next settled trade can flip, so it is the pairing worth calling. Pairs with+ * an unavailable trader are skipped, and a pair is never opened twice. PURE.+ * @param {object[]} rivalries getRivalries().rivalries+ * @param {{excluded?:Set<string>, max?:number}} [opts]+ */+export function planDuels(rivalries = [], { excluded = new Set(), max = DUEL_RULES.max_per_window } = {}) {+ const seen = new Set();+ const out = [];+ for (const r of rivalries || []) {+ const a = r?.leader;+ const b = r?.chaser;+ if (!a?.agent_id || !b?.agent_id || a.agent_id === b.agent_id) continue;+ if (excluded.has(a.agent_id) || excluded.has(b.agent_id)) continue;+ const key = [a.agent_id, b.agent_id].sort().join(':');+ if (seen.has(key)) continue;+ seen.add(key);+ out.push({+ a: sideSnapshot(a),+ b: sideSnapshot(b),+ context: {+ headline: r.headline || null,+ subline: r.subline || null,+ rivalry: r.kind || null,+ board_window: r.window || DUEL_RULES.board_window,+ a: sideSnapshot(a),+ b: sideSnapshot(b),+ },+ });+ if (out.length >= max) break;+ }+ return out;+}++// ── resolution + settlement (pure) ──────────────────────────────────────────++function lamports(v) {+ try {+ return BigInt(String(v ?? '0').split('.')[0] || '0');+ } catch {+ return 0n;+ }+}++/**+ * Decide a duel from each side's measured window. PURE.+ * @param {{a:{eligible:boolean, closed:number, pnl_lamports:string|number}, b:{...}}} sides+ * @returns {{status:'resolved'|'void', winner:'a'|'b'|null, void_reason:string|null}}+ */+export function decideDuel({ a, b } = {}) {+ if (!a?.eligible || !b?.eligible) return { status: 'void', winner: null, void_reason: 'trader_unavailable' };+ const ca = n(a.closed);+ const cb = n(b.closed);+ if (ca === 0 && cb === 0) return { status: 'void', winner: null, void_reason: 'no_trades' };+ const pa = ca ? lamports(a.pnl_lamports) : 0n;+ const pb = cb ? lamports(b.pnl_lamports) : 0n;+ if (pa === pb) return { status: 'void', winner: null, void_reason: 'tie' };+ return { status: 'resolved', winner: pa > pb ? 'a' : 'b', void_reason: null };+}++/**+ * What one call is worth once its duel settles. Mirrors the settlement SQL in+ * settleDuelPicks exactly; the tests pin both to the same table. PURE.+ */+export function settleCall(pick, market) {+ const stake = n(pick.stake);+ if (market.status === 'void') return { status: 'refunded', payout: stake };+ if (market.status !== 'resolved') return { status: 'open', payout: 0 };+ if (pick.side === market.winner) return { status: 'won', payout: stake * DUEL_RULES.win_multiplier };+ return { status: 'lost', payout: 0 };+}++/**+ * Validate a call's shape and stake against a balance. PURE.+ * @returns {{ok:true, side:'a'|'b', stake:number} | {ok:false, code:string, message:string}}+ */+export function validateCall({ side, stake, balance = Infinity } = {}) {+ if (side !== 'a' && side !== 'b') return { ok: false, code: 'invalid_side', message: 'side must be "a" or "b".' };+ const s = Number(stake);+ if (!Number.isInteger(s) || s < DUEL_RULES.min_stake || s > DUEL_RULES.max_stake) {+ return {+ ok: false,+ code: 'invalid_stake',+ message: `Stake a whole number of points from ${DUEL_RULES.min_stake} to ${DUEL_RULES.max_stake}.`,+ };+ }+ if (s > n(balance)) {+ return { ok: false, code: 'not_enough_points', message: `You have ${n(balance)} points. Your free allowance tops up at 00:00 UTC.` };+ }+ return { ok: true, side, stake: s };+}++/**+ * Which duel badges a call history has earned. Refunds never count toward a+ * streak or accuracy: a void duel was not a call that was right or wrong. PURE.+ * @param {{status:string, settled_at?:string|null, created_at?:string}[]} picks+ */+export function duelBadgesFor(picks = []) {+ const earned = [];+ if (!picks.length) return earned;+ earned.push(BADGES.DUEL_FIRST);+ const decided = picks+ .filter((p) => p.status === 'won' || p.status === 'lost')+ .sort((x, y) => ms(x.settled_at || x.created_at) - ms(y.settled_at || y.created_at));+ const wins = decided.filter((p) => p.status === 'won').length;+ if (wins > 0) earned.push(BADGES.DUEL_HIT);+ let run = 0;+ let best = 0;+ for (const p of decided) {+ run = p.status === 'won' ? run + 1 : 0;+ if (run > best) best = run;+ }+ if (best >= 3) earned.push(BADGES.DUEL_STREAK_3);+ if (decided.length >= 10 && wins / decided.length >= 0.7) earned.push(BADGES.DUEL_SHARP);+ return earned;+}++// ── seasons (pure) ──────────────────────────────────────────────────────────++const SEASON_RE = /^(\d{4})-(0[1-9]|1[0-2])$/;++/** A season is a UTC calendar month. PURE. */+export function seasonFor(now = Date.now()) {+ const d = new Date(ms(now));+ return seasonById(`${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}`);+}++/** Parse 'YYYY-MM' into season bounds, or null. PURE. */+export function seasonById(id) {+ const m = SEASON_RE.exec(String(id || ''));+ if (!m) return null;+ const y = Number(m[1]);+ const mo = Number(m[2]) - 1;+ const start = Date.UTC(y, mo, 1);+ const end = Date.UTC(y, mo + 1, 1);+ const label = new Date(start).toLocaleDateString('en-US', { month: 'long', year: 'numeric', timeZone: 'UTC' });+ return { id: m[0], label, start: iso(start), end: iso(end) };+}++/** Net points a settled call made or lost. PURE. */+export function callNet(pick) {+ if (pick.status === 'won') return n(pick.payout) - n(pick.stake);+ if (pick.status === 'lost') return -n(pick.stake);+ return 0;+}++// ── points wallet ───────────────────────────────────────────────────────────++/**+ * Credit today's free allowance if it has not been credited yet, in one+ * statement: the grant row and the balance move together or not at all.+ * @returns {Promise<{balance:number, granted:boolean}>}+ */+export async function ensureDailyGrant(userId, now = Date.now()) {+ const day = iso(utcDayStart(now)).slice(0, 10);+ const rows = await sql`+ with g as (+ insert into duel_points_ledger (user_id, kind, amount, day)+ values (${userId}, 'grant', ${DUEL_RULES.daily_allowance}, ${day}::date)+ on conflict do nothing+ returning amount+ )+ insert into duel_wallets (user_id, balance)+ select ${userId}::uuid, amount from g+ on conflict (user_id) do update set balance = duel_wallets.balance + excluded.balance, updated_at = now()+ returning balance+ `;+ if (rows.length) return { balance: n(rows[0].balance), granted: true };+ const [w] = await sql`select balance from duel_wallets where user_id = ${userId}`;+ return { balance: n(w?.balance), granted: false };+}++// ── measuring a window ──────────────────────────────────────────────────────++/** Round-trips an agent closed inside [start, end), from both real ledgers. */+async function closedInWindow(agentId, network, start, end) {+ const [sniper, strategy] = await Promise.all([+ sql`+ select p.id, p.agent_id, p.mint, p.symbol, p.name, p.status,+ p.entry_quote_lamports, p.exit_quote_lamports, p.last_value_lamports,+ p.realized_pnl_lamports, p.realized_pnl_pct, p.buy_sig, p.sell_sig,+ p.opened_at, p.closed_at, p.moonbag_base_amount, p.moonbag_last_value_lamports+ from agent_sniper_positions p+ where p.agent_id = ${agentId} and p.network = ${network} and p.status = 'closed'+ and p.closed_at >= ${start} and p.closed_at < ${end}+ `,+ sql`+ select s.id, s.agent_id, s.mint, s.symbol, s.name, s.status,+ s.entry_lamports as entry_quote_lamports, s.exit_lamports as exit_quote_lamports,+ s.last_value_lamports, s.realized_pnl_lamports, s.realized_pnl_pct,+ s.entry_sig as buy_sig, s.exit_sig as sell_sig, s.opened_at, s.closed_at+ from agent_strategy_positions s+ where s.agent_id = ${agentId} and s.network = ${network} and s.status = 'closed'+ and s.closed_at >= ${start} and s.closed_at < ${end}+ `.catch(() => []), // Strategy Objects table not migrated: the sniper ledger stands alone, as on /trader/:id+ ]);+ return strategy.length ? [...sniper, ...strategy] : sniper;+}++/**+ * One trader's realized result inside a window, through the same pure+ * computeTraderMetrics the trader card uses, including its exclusion of+ * round-trips on the trader's own coins.+ */+export async function measureWindow({ agentId, ownerUserId, network, start, end }) {+ const [positions, selfDealMints] = await Promise.all([+ closedInWindow(agentId, network, start, end),+ selfDealMintsForUser(ownerUserId, network),+ ]);+ const m = computeTraderMetrics(positions, { selfDealMints });+ return {+ closed: m.closed_count,+ wins: m.wins,+ pnl_lamports: m.realized_pnl_lamports,+ pnl_sol: m.realized_pnl_sol,+ self_dealing_count: m.self_dealing_count,+ };+}++/** The 30-day record a duel card shows for each trader, the same numbers /trader/:id shows for 30d. */+async function trailingRecord({ agentId, ownerUserId, network, now }) {+ const [positions, selfDealMints, solUsd] = await Promise.all([+ fetchTraderPositions({ agentId, network, window: DUEL_RULES.board_window, now }),+ selfDealMintsForUser(ownerUserId, network),+ cachedSolUsd(),+ ]);+ const m = computeTraderMetrics(positions, { solUsd, selfDealMints });+ return {+ window: DUEL_RULES.board_window,+ closed: m.closed_count,+ wins: m.wins,+ win_rate: m.win_rate,+ realized_pnl_sol: m.realized_pnl_sol,+ realized_pnl_usd: m.realized_pnl_usd,+ score: m.score,+ verified: m.verified,+ open_positions: m.open_count,+ pnl_series: m.pnl_series,+ last_active_at: m.last_active_at,+ };+}++// ── agents ──────────────────────────────────────────────────────────────────++async function agentRows(ids) {+ const list = ids.filter((id) => isUuid(id));+ if (!list.length) return new Map();+ const rows = await sql`+ select id, user_id, name, is_public, deleted_at, profile_image_url, avatar_url+ from agent_identities where id = any(${list}::uuid[])+ `;+ return new Map(rows.map((r) => [r.id, r]));+}++const available = (row) => !!row && row.deleted_at == null && row.is_public !== false;++// ── generation, resolution, settlement (the cron) ───────────────────────────++/** Open duels for every window that should be taking calls and has none yet. */+export async function generateDuels({ network = 'mainnet', now = Date.now() } = {}) {+ const created = [];+ let rivalries = null;+ for (const kind of ['day', 'week']) {+ const w = nextWindow(kind, now);+ if (!windowOpensNow(kind, w.start, now)) continue;+ const [existing] = await sql`+ select count(*)::int as c from duel_markets+ where network = ${network} and window_kind = ${kind} and window_start = ${iso(w.start)}+ `;+ if (n(existing?.c) > 0) continue;+ if (!rivalries) {+ const board = await getRivalries({ network, window: DUEL_RULES.board_window, lookback: '7d', limit: 12, now });+ rivalries = board.rivalries || [];+ }+ const ids = [...new Set(rivalries.flatMap((r) => [r.leader?.agent_id, r.chaser?.agent_id]).filter(Boolean))];+ const agents = await agentRows(ids);+ const excluded = new Set(ids.filter((id) => !available(agents.get(id))));+ for (const p of planDuels(rivalries, { excluded })) {+ const [row] = await sql`+ insert into duel_markets (network, window_kind, window_start, window_end, agent_a, agent_b, agent_a_name, agent_b_name, context)+ values (${network}, ${kind}, ${iso(w.start)}, ${iso(w.end)}, ${p.a.agent_id}, ${p.b.agent_id},+ ${p.a.name}, ${p.b.name}, ${JSON.stringify(p.context)}::jsonb)+ on conflict do nothing+ returning id+ `;+ if (row) created.push({ id: row.id, kind, a: p.a.name, b: p.b.name });+ }+ }+ return created;+}++/**+ * Settle every open call on a resolved or void duel, in one statement: the+ * pick status, the ledger row and the balance move together. Idempotent: an+ * already-settled pick is skipped, and the ledger's unique index refuses a+ * second payout even if the statement is replayed.+ */+export async function settleDuelPicks(marketId) {+ await sql`+ with m as (+ select id, status, winner from duel_markets where id = ${marketId} and status in ('resolved','void')+ ),+ p as (+ update duel_picks k set+ status = case when m.status = 'void' then 'refunded' when k.side = m.winner then 'won' else 'lost' end,+ payout = case when m.status = 'void' then k.stake when k.side = m.winner then k.stake * ${DUEL_RULES.win_multiplier} else 0 end,+ settled_at = now()+ from m+ where k.market_id = m.id and k.status = 'open'+ returning k.user_id, k.status, k.payout, k.market_id+ ),+ led as (+ insert into duel_points_ledger (user_id, kind, amount, market_id)+ select user_id, case when status = 'won' then 'payout' else 'refund' end, payout, market_id+ from p where payout > 0+ on conflict do nothing+ returning user_id, amount+ )+ update duel_wallets w set balance = w.balance + led.amount, updated_at = now()+ from led where w.user_id = led.user_id+ `;+ await creditDuelXp([marketId]);+ const winners = await sql`select distinct user_id from duel_picks where market_id = ${marketId} and status in ('won','lost')`;+ for (const w of winners) await refreshDuelBadges(w.user_id);+}++/** XP for correct calls, into the shared quest ledger. Insert-only and idempotent. */+async function creditDuelXp(marketIds) {+ if (!marketIds.length) return;+ await sql`+ insert into trading_quest_completions (user_id, day, code, xp)+ select k.user_id, (m.resolved_at at time zone 'UTC')::date, ${XP_CODE_PREFIX}::text || m.id::text, ${DUEL_RULES.xp_per_win}::int+ from duel_picks k join duel_markets m on m.id = k.market_id+ where k.market_id = any(${marketIds}::uuid[]) and k.status = 'won' and m.status = 'resolved'+ on conflict do nothing+ `;+}++/** Measure, decide, flip the market once, then settle its calls. */+export async function resolveDuel(market, { now = Date.now() } = {}) {+ const agents = await agentRows([market.agent_a, market.agent_b]);+ const ra = agents.get(market.agent_a);+ const rb = agents.get(market.agent_b);+ const eligibleA = available(ra);+ const eligibleB = available(rb);+ const early = ms(now) < ms(market.window_end);++ let result = null;+ let outcome;+ if (!eligibleA || !eligibleB) {+ outcome = decideDuel({ a: { eligible: eligibleA }, b: { eligible: eligibleB } });+ result = { unavailable: [!eligibleA && 'a', !eligibleB && 'b'].filter(Boolean), measured_at: iso(ms(now)) };+ } else {+ if (early) return null; // only an unavailable trader can end a duel before its window closes+ const start = iso(ms(market.window_start));+ const end = iso(ms(market.window_end));+ const [ma, mb] = await Promise.all([+ measureWindow({ agentId: market.agent_a, ownerUserId: ra.user_id, network: market.network, start, end }),+ measureWindow({ agentId: market.agent_b, ownerUserId: rb.user_id, network: market.network, start, end }),+ ]);+ outcome = decideDuel({ a: { eligible: true, ...ma }, b: { eligible: true, ...mb } });+ result = { a: ma, b: mb, measured_at: iso(ms(now)) };+ }++ const [flipped] = await sql`+ update duel_markets set+ status = ${outcome.status}, winner = ${outcome.winner}, void_reason = ${outcome.void_reason},+ result = ${JSON.stringify(result)}::jsonb, resolved_at = now()+ where id = ${market.id} and status = 'open'+ returning id+ `;+ if (!flipped) return null; // a concurrent tick got there first+ await settleDuelPicks(market.id);+ return { id: market.id, ...outcome };+}++/**+ * One cron tick: void duels whose trader went private or was deleted, resolve+ * duels whose window closed more than the grace period ago, settle any call a+ * crashed tick left open, then open duels for the next windows.+ */+export async function runDuelsTick({ network = 'mainnet', now = Date.now() } = {}) {+ const unavailable = await sql`+ select m.* from duel_markets m+ where m.status = 'open' and m.network = ${network}+ and (m.agent_a is null or m.agent_b is null or exists (+ select 1 from agent_identities a+ where a.id in (m.agent_a, m.agent_b) and (a.deleted_at is not null or a.is_public = false)+ ))+ limit 50+ `;+ const voided = [];+ for (const m of unavailable) {+ const r = await resolveDuel(m, { now });+ if (r) voided.push(r);+ }++ const due = await sql`+ select * from duel_markets+ where status = 'open' and network = ${network} and window_end <= ${iso(ms(now) - GRACE_MS)}+ order by window_end asc limit 25+ `;+ const resolved = [];+ for (const m of due) {+ const r = await resolveDuel(m, { now });+ if (r) resolved.push(r);+ }++ const stranded = await sql`+ select distinct k.market_id from duel_picks k join duel_markets m on m.id = k.market_id+ where k.status = 'open' and m.status in ('resolved','void') and m.network = ${network}+ limit 50+ `;+ for (const s of stranded) await settleDuelPicks(s.market_id);+ // A tick that died between the pick settlement and the XP insert is repaired here.+ const recent = await sql`+ select id from duel_markets+ where status = 'resolved' and network = ${network} and resolved_at > ${iso(ms(now) - 3 * DAY_MS)}+ `;+ await creditDuelXp(recent.map((r) => r.id));++ const generated = await generateDuels({ network, now });+ return { network, voided, resolved, repaired: stranded.length, generated };+}++// ── badges ──────────────────────────────────────────────────────────────────++/** Award every duel badge a user's history has earned. Returns the newly unlocked codes. */+export async function refreshDuelBadges(userId) {+ const picks = await sql`+ select status, settled_at, created_at from duel_picks where user_id = ${userId}+ `;+ const fresh = [];+ for (const code of duelBadgesFor(picks)) {+ if (await unlockBadge(userId, code)) fresh.push(code);+ }+ return fresh;+}++// ── reads ───────────────────────────────────────────────────────────────────++function sideView(market, key, agent) {+ const id = market[`agent_${key}`];+ const snap = market.context?.[key] || {};+ return {+ agent_id: id,+ name: agent?.name || market[`agent_${key}_name`],+ image: agent?.profile_image_url || agent?.avatar_url || snap.image || null,+ available: available(agent),+ links: id+ ? { trader: `/trader/${id}`, trade_room: `/trade-rooms/${id}` }+ : null,+ board: {+ rank: snap.rank ?? null,+ score: snap.score ?? null,+ closed: snap.closed ?? null,+ win_rate: snap.win_rate ?? null,+ realized_pnl_sol: snap.realized_pnl_sol ?? null,+ },+ };+}++function marketView(row, now, agents) {+ const phase = duelPhase(row, now);+ return {+ id: row.id,+ url: `/duels/${row.id}`,+ network: row.network,+ window_kind: row.window_kind,+ window_start: iso(ms(row.window_start)),+ window_end: iso(ms(row.window_end)),+ resolves_at: resolvesAt(row),+ phase,+ status: row.status,+ winner: row.winner || null,+ void_reason: row.void_reason || null,+ result: row.result || null,+ resolved_at: row.resolved_at ? iso(ms(row.resolved_at)) : null,+ headline: row.context?.headline || null,+ subline: row.context?.subline || null,+ a: sideView(row, 'a', agents.get(row.agent_a)),+ b: sideView(row, 'b', agents.get(row.agent_b)),+ crowd: {+ a: { calls: n(row.calls_a), points: n(row.points_a) },+ b: { calls: n(row.calls_b), points: n(row.points_b) },+ },+ my_call: row.my_side+ ? { side: row.my_side, stake: n(row.my_stake), status: row.my_status, payout: n(row.my_payout) }+ : null,+ };+}++/** Count of traders currently eligible to be paired, for the empty state. */+export async function eligibleTraderCount({ network = 'mainnet', now = Date.now() } = {}) {+ const since = iso(ms(now) - 30 * DAY_MS);+ const [row] = await sql`+ select count(*)::int as c from (+ select x.agent_id from (+ select agent_id from agent_sniper_positions+ where network = ${network} and status = 'closed' and closed_at >= ${since}+ ) x+ join agent_identities a on a.id = x.agent_id+ where a.is_public is not false and a.deleted_at is null+ group by x.agent_id+ having count(*) >= ${DUEL_RULES.board_min_closed}+ ) t+ `;+ return n(row?.c);+}++/**+ * Duels for the board. `phase`: open (taking calls), live (window running or+ * awaiting resolution), settled (resolved or void), all. `agentId` narrows to+ * duels featuring one trader. `userId` attaches the viewer's own call.+ */+export async function listDuels({ network = 'mainnet', phase = 'all', agentId = null, userId = null, limit = 30, now = Date.now() } = {}) {+ const t = iso(ms(now));+ const phaseSql =+ phase === 'open' ? sql`and m.status = 'open' and m.window_start > ${t}`+ : phase === 'live' ? sql`and m.status = 'open' and m.window_start <= ${t}`+ : phase === 'settled' ? sql`and m.status in ('resolved','void')`+ : sql``;+ const agentSql = agentId ? sql`and (m.agent_a = ${agentId} or m.agent_b = ${agentId})` : sql``;+ const orderSql =+ phase === 'settled' ? sql`order by m.resolved_at desc nulls last`+ : phase === 'live' ? sql`order by m.window_end asc`+ : phase === 'open' ? sql`order by m.window_start asc, m.created_at asc`+ : sql`order by (m.status = 'open') desc, m.window_start desc`;+ const rows = await sql`+ select m.*, c.calls_a, c.calls_b, c.points_a, c.points_b,+ mine.side as my_side, mine.stake as my_stake, mine.status as my_status, mine.payout as my_payout+ from duel_markets m+ left join lateral (+ select count(*) filter (where side = 'a') as calls_a,+ count(*) filter (where side = 'b') as calls_b,+ coalesce(sum(stake) filter (where side = 'a'), 0) as points_a,+ coalesce(sum(stake) filter (where side = 'b'), 0) as points_b+ from duel_picks where market_id = m.id+ ) c on true+ left join duel_picks mine on mine.market_id = m.id and mine.user_id = ${userId}+ where m.network = ${network} ${phaseSql} ${agentSql}+ ${orderSql}+ limit ${limit}+ `;+ const agents = await agentRows([...new Set(rows.flatMap((r) => [r.agent_a, r.agent_b]).filter(Boolean))]);+ return rows.map((r) => marketView(r, now, agents));+}++/** Tab counts for the board. */+export async function duelCounts({ network = 'mainnet', now = Date.now() } = {}) {+ const t = iso(ms(now));+ const [row] = await sql`+ select count(*) filter (where status = 'open' and window_start > ${t})::int as open,+ count(*) filter (where status = 'open' and window_start <= ${t})::int as live,+ count(*) filter (where status in ('resolved','void'))::int as settled+ from duel_markets where network = ${network}+ `;+ return { open: n(row?.open), live: n(row?.live), settled: n(row?.settled) };+}++/**+ * One duel with everything its page needs: both traders' 30-day records, the+ * in-window standing (live while running, final once resolved), the crowd, and+ * whether the viewer can call it.+ */+export async function getDuel(id, { userId = null, now = Date.now() } = {}) {+ if (!isUuid(id)) return null;+ const [market] = await listDuelRows(id, userId);+ if (!market) return null;+ const agents = await agentRows([market.agent_a, market.agent_b].filter(Boolean));+ const view = marketView(market, now, agents);+ const ra = agents.get(market.agent_a);+ const rb = agents.get(market.agent_b);++ const [recA, recB] = await Promise.all([+ available(ra) ? trailingRecord({ agentId: ra.id, ownerUserId: ra.user_id, network: market.network, now }) : null,+ available(rb) ? trailingRecord({ agentId: rb.id, ownerUserId: rb.user_id, network: market.network, now }) : null,+ ]);+ view.a.record = recA;+ view.b.record = recB;++ if (view.phase === 'live' || view.phase === 'resolving') {+ const start = view.window_start;+ const end = view.phase === 'live' ? iso(ms(now)) : view.window_end;+ const [sa, sb] = await Promise.all([+ available(ra) ? measureWindow({ agentId: ra.id, ownerUserId: ra.user_id, network: market.network, start, end }) : null,+ available(rb) ? measureWindow({ agentId: rb.id, ownerUserId: rb.user_id, network: market.network, start, end }) : null,+ ]);+ const leading = sa && sb ? decideDuel({ a: { eligible: true, ...sa }, b: { eligible: true, ...sb } }) : null;+ view.standing = { a: sa, b: sb, as_of: end, leading: leading?.winner || null, state: leading?.void_reason || null };+ } else if (view.phase === 'resolved' || view.phase === 'void') {+ view.standing = market.result?.a ? { a: market.result.a, b: market.result.b, as_of: view.window_end, final: true } : null;+ } else {+ view.standing = null;+ }++ const owns = userId ? [ra, rb].some((a) => a && a.user_id === userId) : false;+ view.viewer = {+ signed_in: !!userId,+ owns_a_trader: owns,+ can_call: !!userId && view.phase === 'open' && !owns && !view.my_call && view.a.available && view.b.available,+ };+ return view;+}++async function listDuelRows(id, userId) {+ return sql`+ select m.*, c.calls_a, c.calls_b, c.points_a, c.points_b,+ mine.side as my_side, mine.stake as my_stake, mine.status as my_status, mine.payout as my_payout+ from duel_markets m+ left join lateral (+ select count(*) filter (where side = 'a') as calls_a,+ count(*) filter (where side = 'b') as calls_b,+ coalesce(sum(stake) filter (where side = 'a'), 0) as points_a,+ coalesce(sum(stake) filter (where side = 'b'), 0) as points_b+ from duel_picks where market_id = m.id+ ) c on true+ left join duel_picks mine on mine.market_id = m.id and mine.user_id = ${userId}+ where m.id = ${id}+ limit 1+ `;+}++// ── making a call ───────────────────────────────────────────────────────────++const PG_UNIQUE = '23505';+const PG_CHECK = '23514';++/**+ * Place one call. Every rule is checked up front for a clear message, then+ * enforced again inside the single insert statement, so a race can only ever+ * be refused, never slip through: the unique index allows one call per user+ * per duel, the window_start comparison uses the database clock, the owner and+ * availability checks run inside the insert, and the wallet's check+ * constraint refuses an overdraft.+ * @returns {Promise<{ok:true, call:object, balance:number} | {ok:false, status:number, code:string, message:string}>}+ */+export async function placeCall({ userId, marketId, side, stake, now = Date.now() }) {+ const shape = validateCall({ side, stake });+ if (!shape.ok) return { ok: false, status: 400, code: shape.code, message: shape.message };+ if (!isUuid(marketId)) return { ok: false, status: 404, code: 'not_found', message: 'No such duel.' };++ const [market] = await sql`select * from duel_markets where id = ${marketId}`;+ if (!market) return { ok: false, status: 404, code: 'not_found', message: 'No such duel.' };+ if (duelPhase(market, now) !== 'open') {+ return { ok: false, status: 409, code: 'duel_locked', message: 'Calls locked when this duel\'s window started.' };+ }+ const agents = await agentRows([market.agent_a, market.agent_b].filter(Boolean));+ const ra = agents.get(market.agent_a);+ const rb = agents.get(market.agent_b);+ if ((ra && ra.user_id === userId) || (rb && rb.user_id === userId)) {+ return { ok: false, status: 403, code: 'own_agent', message: 'You own one of these traders, so you cannot call this duel.' };+ }+ if (!available(ra) || !available(rb)) {+ return { ok: false, status: 409, code: 'duel_unavailable', message: 'One of these traders is no longer public. This duel will be voided and every call refunded.' };+ }++ const wallet = await ensureDailyGrant(userId, now);+ const funded = validateCall({ side, stake, balance: wallet.balance });+ if (!funded.ok) return { ok: false, status: 409, code: funded.code, message: funded.message };++ let rows;+ try {+ rows = await sql`+ with pick as (+ insert into duel_picks (market_id, user_id, side, stake)+ select m.id, ${userId}::uuid, ${funded.side}::text, ${funded.stake}::int+ from duel_markets m+ join duel_wallets w on w.user_id = ${userId}+ where m.id = ${marketId} and m.status = 'open' and m.window_start > now()+ and m.agent_a is not null and m.agent_b is not null+ and not exists (+ select 1 from agent_identities a+ where a.id in (m.agent_a, m.agent_b)+ and (a.user_id = ${userId} or a.deleted_at is not null or a.is_public = false)+ )+ returning id, market_id, side, stake, created_at+ ),+ debit as (+ update duel_wallets w set balance = w.balance - pick.stake, updated_at = now()+ from pick where w.user_id = ${userId}+ returning w.balance+ ),+ led as (+ insert into duel_points_ledger (user_id, kind, amount, market_id)+ select ${userId}::uuid, 'stake', -stake, market_id from pick+ returning id+ )+ select pick.id, pick.side, pick.stake, pick.created_at, (select balance from debit) as balance from pick+ `;+ } catch (err) {+ if (err?.code === PG_UNIQUE) return { ok: false, status: 409, code: 'already_called', message: 'You already made your call on this duel.' };+ if (err?.code === PG_CHECK) return { ok: false, status: 409, code: 'not_enough_points', message: 'Not enough points for that stake. Your free allowance tops up at 00:00 UTC.' };+ throw err;+ }+ if (!rows.length) {+ return { ok: false, status: 409, code: 'duel_locked', message: 'This duel is no longer taking calls.' };+ }+ await unlockBadge(userId, BADGES.DUEL_FIRST);+ const row = rows[0];+ return {+ ok: true,+ call: { id: String(row.id), market_id: marketId, side: row.side, stake: n(row.stake), status: 'open', created_at: row.created_at },+ balance: n(row.balance),+ };+}++// ── the predictor ───────────────────────────────────────────────────────────++/** A season's predictor board: net points from decided calls on duels resolved in the season. */+export async function seasonLeaderboard({ season = seasonFor(), limit = 25, userId = null } = {}) {+ const rows = await sql`+ with s as (+ select k.user_id,+ sum(case when k.status = 'won' then k.payout - k.stake else -k.stake end)::int as net,+ count(*) filter (where k.status = 'won')::int as wins,+ count(*)::int as decided+ from duel_picks k join duel_markets m on m.id = k.market_id+ where k.status in ('won','lost') and m.resolved_at >= ${season.start} and m.resolved_at < ${season.end}+ group by k.user_id+ ),+ ranked as (+ select s.*, rank() over (order by s.net desc, s.wins desc, s.decided asc) as rank+ from s join users u on u.id = s.user_id+ where u.deleted_at is null+ )+ select r.*, u.username, u.display_name, u.avatar_url+ from ranked r join users u on u.id = r.user_id+ where r.rank <= ${limit} or r.user_id = ${userId}+ order by r.rank asc, r.user_id+ `;+ const shape = (r) => ({+ rank: n(r.rank),+ name: r.display_name || r.username || 'Anonymous predictor',+ username: r.username || null,+ profile: r.username ? `/u/${encodeURIComponent(r.username)}` : null,+ avatar: r.avatar_url || null,+ net: n(r.net),+ wins: n(r.wins),+ decided: n(r.decided),+ accuracy: n(r.decided) ? n(r.wins) / n(r.decided) : null,+ is_me: !!userId && r.user_id === userId,+ });+ const all = rows.map(shape);+ return {+ season,+ leaders: all.filter((r) => r.rank <= limit),+ me: all.find((r) => r.is_me) || null,+ };+}++/**+ * Everything the signed-in predictor sees: today's allowance (credited on this+ * read), balance, XP level, season standing, recent calls, and duel badges.+ */+export async function loadPredictor(userId, { now = Date.now() } = {}) {+ const grant = await ensureDailyGrant(userId, now);+ const freshBadges = await refreshDuelBadges(userId);+ const season = seasonFor(now);+ const [calls, [xp], board, badges] = await Promise.all([+ sql`+ select k.side, k.stake, k.status, k.payout, k.created_at, k.settled_at,+ m.id as market_id, m.window_kind, m.window_start, m.window_end, m.status as market_status,+ m.winner, m.void_reason, m.agent_a_name, m.agent_b_name+ from duel_picks k join duel_markets m on m.id = k.market_id+ where k.user_id = ${userId}+ order by k.created_at desc limit 20+ `,+ sql`+ select coalesce(sum(xp), 0)::int as total,+ coalesce(sum(xp) filter (where code like ${XP_CODE_PREFIX + '%'}), 0)::int as from_duels+ from trading_quest_completions where user_id = ${userId}+ `,+ seasonLeaderboard({ season, limit: 0, userId }),+ listBadges(userId),+ ]);+ return {+ wallet: {+ balance: grant.balance,+ granted_now: grant.granted,+ daily_allowance: DUEL_RULES.daily_allowance,+ next_grant_at: iso(utcDayStart(now) + DAY_MS),+ },+ xp: { ...levelFor(xp?.total), from_duels: n(xp?.from_duels) },+ season: { ...season, standing: board.me },+ calls: calls.map((c) => ({+ market_id: c.market_id,+ url: `/duels/${c.market_id}`,+ label: `${c.agent_a_name} vs ${c.agent_b_name}`,+ picked: c.side === 'a' ? c.agent_a_name : c.agent_b_name,+ side: c.side,+ stake: n(c.stake),+ status: c.status,+ payout: n(c.payout),+ net: callNet(c),+ window_kind: c.window_kind,+ window_start: iso(ms(c.window_start)),+ window_end: iso(ms(c.window_end)),+ phase: duelPhase({ status: c.market_status, window_start: c.window_start, window_end: c.window_end }, now),+ void_reason: c.void_reason || null,+ })),+ badges: badges.filter((b) => DUEL_BADGE_CODES.has(b.code)),+ newly_unlocked: freshBadges,+ };+}