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
// 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 = null } = {}) {
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 (balance != null && 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)}
and coalesce(context ->> 'source', '') <> 'challenge'
`;
// Challenge duels (api/_lib/duel-challenges.js) can open a window before
// this generator reaches it, so only rivalry-made duels count as "done".
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,
};
}