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.

47.7 KB
Raw Blame
// Agent Trading Swarms — pooled custodial treasury, reputation-weighted consensus,
// and pro-rata on-chain profit settlement.
//
// A swarm is itself an agent-owned custodial wallet (the "treasury agent"),
// provisioned through the normal agent-wallet path. It carries a dedicated
// agent_sniper_strategies row that holds its trade policy (budget, per-trade cap,
// stop-loss/take-profit), so the existing sniper position sweep manages and exits
// its positions for free. The consensus engine (workers/agent-sniper/swarm.js)
// fires buys from the treasury only when reputation-weighted member agreement
// clears the swarm threshold; realized profit distributes pro-rata to members via
// real SOL transfers from the treasury, and a member can exit and redeem their
// share of current treasury value at any time.
//
// Every lamport moves on-chain and is reconciled to the treasury's live balance —
// there are no internal virtual balances. Contributions, distributions, and exits
// are all real transfers, spend-guarded and audited in agent_custody_events
// (category 'swarm_payout') plus the purpose-built swarm_payouts ledger.

import { sql } from './db.js';
import { ensureAgentWallet, getOrCreateAgentSolanaWallet, recoverSolanaAgentKeypair } from './agent-wallet.js';
import { transferNativeSol } from './solana-transfer.js';
import { solanaConnection } from './solana/connection.js';
import { readBalanceOrNull, rpcUnavailableError } from './solana/read-guards.js';
import { recordCustodyEvent } from './agent-trade-guards.js';

const LAMPORTS_PER_SOL = 1_000_000_000;

// Keep a small SOL buffer in the treasury for transaction fees so distributions
// and exits can never strand the wallet below the cost of its own next trade/payout.
export const GAS_RESERVE_LAMPORTS = 15_000_000n; // 0.015 SOL

// Funding floor — a contribution below this isn't worth an on-chain tx + the fee.
export const MIN_CONTRIBUTION_LAMPORTS = 5_000_000n; // 0.005 SOL

// Floor weight so a member with no track record still counts a little, while
// verified reputable members dominate the vote.
const MIN_VOTE_WEIGHT = 5;

const BPS = 10000;

// ── policy ───────────────────────────────────────────────────────────────────

const num = (v) => (v == null || v === '' || Number.isNaN(Number(v)) ? null : Number(v));
const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));

/**
 * Validate + normalize a swarm policy. Throws SwarmError on an out-of-range value
 * so a malformed policy never reaches the treasury strategy.
 */
export function normalizeSwarmPolicy(input = {}) {
	const p = input && typeof input === 'object' ? input : {};

	const minConsensus = clamp(num(p.min_consensus) ?? 0.6, 0.05, 1);
	const maxPerTrade = BigInt(Math.max(1_000_000, Math.round(num(p.max_per_trade_lamports) ?? 50_000_000)));
	const dailyBudget = BigInt(Math.max(Number(maxPerTrade), Math.round(num(p.daily_budget_lamports) ?? 500_000_000)));
	const creatorFeeBps = Math.round(clamp(num(p.creator_fee_bps) ?? 0, 0, 2000)); // ≤ 20%
	const maxMemberShareBps = Math.round(clamp(num(p.max_member_share_bps) ?? 5000, 1000, 10000)); // 10%..100%
	const stopLoss = clamp(num(p.stop_loss_pct) ?? 35, 1, 95);
	const takeProfit = num(p.take_profit_pct) != null ? clamp(num(p.take_profit_pct), 5, 100000) : 80;
	const trailing = num(p.trailing_stop_pct) != null ? clamp(num(p.trailing_stop_pct), 1, 95) : 25;
	const maxHold = Math.round(clamp(num(p.max_hold_seconds) ?? 3600, 60, 86400));
	const slippageBps = Math.round(clamp(num(p.slippage_bps) ?? 500, 50, 5000));
	const firewallLevel = ['block', 'warn', 'off'].includes(p.firewall_level) ? p.firewall_level : 'block';
	const requireSmartMoney = p.require_smart_money === true;
	const minSmartMoney = clamp(num(p.min_smart_money_score) ?? 0, 0, 100);
	const joinOpen = p.join_open !== false; // default open
	const killThresholdBps = Math.round(clamp(num(p.kill_threshold_bps) ?? 3000, 0, 10000)); // members holding ≥30% can kill
	const exitPolicy = p.exit_policy === 'wait_to_close' ? 'wait_to_close' : 'settle_at_mark';

	return {
		min_consensus: minConsensus,
		max_per_trade_lamports: maxPerTrade.toString(),
		daily_budget_lamports: dailyBudget.toString(),
		creator_fee_bps: creatorFeeBps,
		max_member_share_bps: maxMemberShareBps,
		require_smart_money: requireSmartMoney,
		min_smart_money_score: minSmartMoney,
		stop_loss_pct: stopLoss,
		take_profit_pct: takeProfit,
		trailing_stop_pct: trailing,
		max_hold_seconds: maxHold,
		slippage_bps: slippageBps,
		firewall_level: firewallLevel,
		join_open: joinOpen,
		kill_threshold_bps: killThresholdBps,
		exit_policy: exitPolicy,
	};
}

export class SwarmError extends Error {
	constructor(status, code, message) {
		super(message);
		this.status = status;
		this.code = code;
	}
}

/**
 * Parse a contribution amount from a request body into lamports. Accepts either
 * `lamports` (an integer count) or `sol` (a decimal), with `lamports` winning
 * when both are present.
 *
 * Every rejection is a 400 SwarmError, which the handler already renders as a
 * clean JSON error. That is the whole point: coercing straight to BigInt() the
 * way this used to means a caller typo (`lamports: "abc"`) or an overflowing
 * amount (`sol: 1e999`) throws a raw RangeError, which escapes as a 500
 * internal_error complete with a Sentry capture and an ops alert. Bad input from
 * a client is not a server fault and must never page anyone.
 *
 * @param {{ lamports?: unknown, sol?: unknown }} [body]
 * @returns {bigint}
 */
export function parseContributionLamports(body = {}) {
	const field = body?.lamports != null ? 'lamports' : body?.sol != null ? 'sol' : null;
	if (!field) throw new SwarmError(400, 'bad_amount', 'sol or lamports required');
	const raw = Number(body[field]);
	if (!Number.isFinite(raw)) throw new SwarmError(400, 'bad_amount', `${field} must be a number`);
	const value = Math.round(field === 'lamports' ? raw : raw * LAMPORTS_PER_SOL);
	// Beyond 2^53 a double no longer represents every integer, so the lamport
	// count a caller sent is not the one we would charge them.
	if (!Number.isSafeInteger(value)) throw new SwarmError(400, 'bad_amount', `${field} is out of range`);
	if (value <= 0) throw new SwarmError(400, 'bad_amount', 'sol or lamports required');
	return BigInt(value);
}

// ── on-chain treasury balance ─────────────────────────────────────────────────

/** Live treasury SOL balance in lamports (bigint). The single source of truth. */
export async function treasuryBalanceLamports(address, network = 'mainnet') {
	const { PublicKey } = await import('@solana/web3.js');
	const conn = solanaConnection({ network, commitment: 'confirmed' });
	// "Balance unknown" is the honest answer to an outage, and a caller must
	// never read it as zero, so this raises a typed retryable error instead of
	// letting a raw transport failure escape as a 500.
	const lamports = await readBalanceOrNull(conn, new PublicKey(address), 'confirmed');
	if (lamports == null) throw rpcUnavailableError(null, `treasury balance for ${address} is unreadable right now`);
	return BigInt(lamports);
}

// ── ownership + loading ────────────────────────────────────────────────────────

/** Assert the user owns the agent; returns the agent row. */
async function requireOwnedAgent(userId, agentId) {
	const [agent] = await sql`
		select id, user_id, name, meta from agent_identities
		where id = ${agentId} and deleted_at is null limit 1
	`;
	if (!agent) throw new SwarmError(404, 'agent_not_found', 'agent not found');
	if (agent.user_id !== userId) throw new SwarmError(403, 'forbidden', 'not your agent');
	return agent;
}

export async function getSwarm(swarmId) {
	const [row] = await sql`select * from swarms where id = ${swarmId} limit 1`;
	return row || null;
}

async function loadTreasuryStrategy(swarm) {
	const [strat] = await sql`
		select * from agent_sniper_strategies where id = ${swarm.strategy_id} limit 1
	`;
	return strat || null;
}

// ── create ─────────────────────────────────────────────────────────────────────

/**
 * Create a swarm: provision a dedicated custodial treasury agent + its sniper
 * strategy (the trade policy), persist the swarm, and enroll the creator as the
 * first member. The treasury strategy is created disabled — the consensus engine,
 * not the new-mint feed, decides when it trades.
 */
export async function createSwarm({ userId, ownerAgentId, name, description = null, network = 'mainnet', policy = {} }) {
	if (!userId) throw new SwarmError(401, 'unauthorized', 'sign in required');
	const cleanName = String(name || '').trim();
	if (!cleanName || cleanName.length > 80) throw new SwarmError(400, 'bad_name', 'name must be 1–80 chars');
	const net = network === 'devnet' ? 'devnet' : 'mainnet';
	const pol = normalizeSwarmPolicy(policy);

	const owner = await requireOwnedAgent(userId, ownerAgentId);
	await ensureAgentWallet(owner.id, userId, { reason: 'swarm_owner' });

	// Provision the treasury as its own agent (its own custodial Solana wallet).
	const [treasury] = await sql`
		insert into agent_identities (user_id, name, description, skills, meta)
		values (
			${userId}, ${`Swarm Treasury · ${cleanName}`.slice(0, 120)},
			${`Pooled trading treasury for the “${cleanName}” swarm.`.slice(0, 500)},
			${['trade']}, ${JSON.stringify({ swarm_treasury: true })}::jsonb
		)
		returning id
	`;
	const treasuryWallet = await getOrCreateAgentSolanaWallet(treasury.id);

	// The treasury's sniper strategy: disabled (so the new-mint feed ignores it),
	// kill_switch off, with the swarm's budget + exit policy. The consensus engine
	// loads it explicitly and fires buys; the position sweep manages exits.
	const [strat] = await sql`
		insert into agent_sniper_strategies
			(agent_id, user_id, network, enabled, kill_switch, trigger,
			 daily_budget_lamports, per_trade_lamports, max_concurrent_positions,
			 slippage_bps, max_price_impact_pct, mev_tip_mode, firewall_level,
			 require_sol_quote, take_profit_pct, stop_loss_pct, trailing_stop_pct,
			 max_hold_seconds, min_smart_money_score, require_smart_money, updated_at)
		values
			(${treasury.id}, ${userId}, ${net}, false, false, 'new_mint',
			 ${pol.daily_budget_lamports}, ${pol.max_per_trade_lamports}, ${8},
			 ${pol.slippage_bps}, ${15}, 'economy', ${pol.firewall_level},
			 true, ${pol.take_profit_pct}, ${pol.stop_loss_pct}, ${pol.trailing_stop_pct},
			 ${pol.max_hold_seconds}, ${pol.min_smart_money_score}, ${pol.require_smart_money}, now())
		on conflict (agent_id, network) do update set updated_at = now()
		returning id
	`;

	const [swarm] = await sql`
		insert into swarms
			(owner_user_id, owner_agent_id, treasury_agent_id, strategy_id, name, description, network, status, policy)
		values
			(${userId}, ${owner.id}, ${treasury.id}, ${strat.id}, ${cleanName},
			 ${description ? String(description).slice(0, 1000) : null}, ${net}, 'open', ${JSON.stringify(pol)}::jsonb)
		returning *
	`;

	// Creator is the first member (zero contribution until they fund).
	await sql`
		insert into swarm_members (swarm_id, agent_id, user_id, is_creator, status)
		values (${swarm.id}, ${owner.id}, ${userId}, true, 'active')
		on conflict (swarm_id, agent_id) do nothing
	`;

	await recordCustodyEvent({
		agentId: treasury.id, userId, eventType: 'limit_change', category: 'swarm_payout',
		network: net, reason: 'swarm_created',
		meta: { swarm_id: swarm.id, name: cleanName, treasury: treasuryWallet.address, policy: pol },
	}).catch(() => {});

	return { ...swarm, treasury_address: treasuryWallet.address };
}

// ── join ─────────────────────────────────────────────────────────────────────

export async function joinSwarm({ userId, swarmId, agentId }) {
	const swarm = await getSwarm(swarmId);
	if (!swarm) throw new SwarmError(404, 'not_found', 'swarm not found');
	if (['killed', 'closed'].includes(swarm.status)) throw new SwarmError(409, 'closed', 'swarm is closed');
	const pol = normalizeSwarmPolicy(swarm.policy);
	if (!pol.join_open && swarm.owner_user_id !== userId) {
		throw new SwarmError(403, 'invite_only', 'this swarm is invite-only');
	}
	const agent = await requireOwnedAgent(userId, agentId);
	await ensureAgentWallet(agent.id, userId, { reason: 'swarm_join' });

	const [member] = await sql`
		insert into swarm_members (swarm_id, agent_id, user_id, status)
		values (${swarm.id}, ${agent.id}, ${userId}, 'active')
		on conflict (swarm_id, agent_id) do update set
			status = 'active', exited_at = null, updated_at = now()
		returning *
	`;
	return member;
}

// ── contribute (real SOL transfer member → treasury) ──────────────────────────

/**
 * Fund the treasury with real SOL from the member's custodial wallet. Verifies the
 * member can afford it (keeping a fee buffer), enforces the per-member share cap
 * BEFORE moving funds, transfers on-chain, then records the net contribution and
 * recomputes every member's share. Returns the signature + updated member.
 */
export async function contributeToSwarm({ userId, swarmId, agentId, lamports }) {
	const swarm = await getSwarm(swarmId);
	if (!swarm) throw new SwarmError(404, 'not_found', 'swarm not found');
	if (['killed', 'closed'].includes(swarm.status)) throw new SwarmError(409, 'closed', 'swarm is closed');
	const amount = BigInt(lamports || 0);
	if (amount < MIN_CONTRIBUTION_LAMPORTS) {
		throw new SwarmError(400, 'too_small', `minimum contribution is ${Number(MIN_CONTRIBUTION_LAMPORTS) / LAMPORTS_PER_SOL} SOL`);
	}

	const agent = await requireOwnedAgent(userId, agentId);
	const wallet = await ensureAgentWallet(agent.id, userId, { reason: 'swarm_contribute' });

	// Member must be enrolled (auto-join if open).
	let [member] = await sql`select * from swarm_members where swarm_id = ${swarm.id} and agent_id = ${agent.id} limit 1`;
	if (!member || member.status !== 'active') {
		member = await joinSwarm({ userId, swarmId: swarm.id, agentId: agent.id });
	}

	const pol = normalizeSwarmPolicy(swarm.policy);

	// Anti-abuse: reject a contribution that would push this member past the cap.
	const members = await sql`select id, agent_id, contribution_lamports, withdrawn_lamports, status from swarm_members where swarm_id = ${swarm.id} and status = 'active'`;
	let totalNet = 0n;
	let memberNet = 0n;
	for (const m of members) {
		const net = BigInt(m.contribution_lamports) - BigInt(m.withdrawn_lamports);
		totalNet += net > 0n ? net : 0n;
		if (m.agent_id === agent.id) memberNet = net > 0n ? net : 0n;
	}
	const prospectiveMember = memberNet + amount;
	const prospectiveTotal = totalNet + amount;
	const prospectiveBps = Number((prospectiveMember * BigInt(BPS)) / prospectiveTotal);
	if (prospectiveBps > pol.max_member_share_bps && members.length > 1) {
		throw new SwarmError(409, 'share_cap', `that contribution would exceed the per-member cap of ${(pol.max_member_share_bps / 100).toFixed(0)}%`);
	}

	// Verify on-chain funds (amount + a fee buffer) before signing.
	const bal = await treasuryBalanceLamports(wallet.address, swarm.network);
	if (bal < amount + GAS_RESERVE_LAMPORTS) {
		throw new SwarmError(402, 'insufficient_funds', 'wallet balance too low to fund this contribution');
	}

	const treasury = await getSwarmTreasuryAddress(swarm);
	const keypair = await recoverSolanaAgentKeypair(agent.meta?.encrypted_solana_secret, {
		agentId: agent.id, userId, reason: 'swarm_contribute', meta: { swarm_id: swarm.id },
	});

	const signature = await transferNativeSol({
		fromKeypair: keypair, toAddress: treasury, lamports: amount, network: swarm.network,
	});

	const [updated] = await sql`
		update swarm_members
		set contribution_lamports = contribution_lamports + ${amount.toString()},
		    last_fund_sig = ${signature}, updated_at = now()
		where id = ${member.id}
		returning *
	`;
	await recordCustodyEvent({
		agentId: agent.id, userId, eventType: 'spend', category: 'swarm_payout',
		network: swarm.network, asset: 'SOL', amountLamports: amount, destination: treasury,
		signature, reason: 'swarm_contribution', status: 'confirmed',
		idempotencyKey: `swarm_contrib:${member.id}:${signature}`,
		meta: { swarm_id: swarm.id },
	}).catch(() => {});

	const shares = await recomputeShares(swarm.id);
	// First real money in flips an 'open' swarm to 'active'.
	if (swarm.status === 'open') {
		await sql`update swarms set status = 'active', updated_at = now() where id = ${swarm.id} and status = 'open'`;
	}
	return { signature, member: updated, shares };
}

async function getSwarmTreasuryAddress(swarm) {
	const wallet = await getOrCreateAgentSolanaWallet(swarm.treasury_agent_id);
	return wallet.address;
}

// ── shares ─────────────────────────────────────────────────────────────────────

/**
 * Recompute every active member's share_bps from net contributions. Caps each
 * member at the policy's max_member_share_bps and redistributes the overflow
 * proportionally across the others, so no member can capture the treasury.
 */
export async function recomputeShares(swarmId) {
	const swarm = await getSwarm(swarmId);
	if (!swarm) return [];
	const pol = normalizeSwarmPolicy(swarm.policy);
	const members = await sql`
		select id, agent_id, contribution_lamports, withdrawn_lamports
		from swarm_members where swarm_id = ${swarmId} and status = 'active'
	`;
	const nets = members.map((m) => {
		const net = BigInt(m.contribution_lamports) - BigInt(m.withdrawn_lamports);
		return { id: m.id, net: net > 0n ? Number(net) : 0 };
	});
	const total = nets.reduce((a, b) => a + b.net, 0);
	let bps = {};
	if (total <= 0) {
		for (const m of nets) bps[m.id] = 0;
	} else {
		// Initial proportional split.
		for (const m of nets) bps[m.id] = Math.round((m.net / total) * BPS);
		// Enforce the cap with proportional redistribution of overflow.
		const cap = pol.max_member_share_bps;
		const capped = new Set();
		for (let iter = 0; iter < 8; iter++) {
			const over = nets.filter((m) => !capped.has(m.id) && bps[m.id] > cap);
			if (!over.length) break;
			let overflow = 0;
			for (const m of over) { overflow += bps[m.id] - cap; bps[m.id] = cap; capped.add(m.id); }
			const free = nets.filter((m) => !capped.has(m.id));
			const freeTotal = free.reduce((a, b) => a + bps[b.id], 0);
			if (freeTotal <= 0) break;
			for (const m of free) bps[m.id] += Math.round((bps[m.id] / freeTotal) * overflow);
		}
	}
	// Persist.
	for (const m of nets) {
		await sql`update swarm_members set share_bps = ${bps[m.id] || 0}, updated_at = now() where id = ${m.id}`;
	}
	return members.map((m) => ({ member_id: m.id, agent_id: m.agent_id, share_bps: bps[m.id] || 0 }));
}

// ── reputation (vote weights) ─────────────────────────────────────────────────

/**
 * Refresh each active member's cached verified-trader reputation (0..100). This is
 * the consensus vote weight. Best-effort per member — a member with no track record
 * keeps a null/zero reputation and votes at the floor weight.
 */
export async function refreshMemberReputations(swarmId, network) {
	const { fetchTraderPositions, computeTraderMetrics } = await import('./trader-stats.js');
	const members = await sql`select id, agent_id from swarm_members where swarm_id = ${swarmId} and status = 'active'`;
	const out = [];
	for (const m of members) {
		let score = 0;
		try {
			const positions = await fetchTraderPositions({ agentId: m.agent_id, network, window: 'all' });
			score = computeTraderMetrics(positions, { solUsd: null }).score || 0;
		} catch { /* no track record yet */ }
		await sql`update swarm_members set reputation = ${score}, reputation_at = now() where id = ${m.id}`;
		out.push({ member_id: m.id, agent_id: m.agent_id, reputation: score });
	}
	return out;
}

// ── consensus tally (pure) ─────────────────────────────────────────────────────

/**
 * Reputation-weighted consensus over a candidate mint. `members` is the active
 * member set (each with agent_id + reputation); `longAgentIds` is the set of
 * members currently holding a real position in the mint (their on-chain "yes"
 * vote). Returns the weighted agreement, the conviction used to size the trade,
 * and a per-member breakdown for the audit log.
 */
export function computeConsensus({ members, longAgentIds, smartMoneyScore = 0, policy }) {
	const longSet = longAgentIds instanceof Set ? longAgentIds : new Set(longAgentIds || []);
	const weightOf = (rep) => Math.max(MIN_VOTE_WEIGHT, Number(rep) || 0);
	let totalWeight = 0;
	let longWeight = 0;
	const breakdown = [];
	for (const m of members) {
		const w = weightOf(m.reputation);
		const long = longSet.has(m.agent_id);
		totalWeight += w;
		if (long) longWeight += w;
		breakdown.push({ agent_id: m.agent_id, name: m.name || null, reputation: Number(m.reputation) || 0, long, weight: w });
	}
	const consensus = totalWeight > 0 ? longWeight / totalWeight : 0;
	// Smart-money confirmation lifts conviction (0..0.25 bonus) but cannot manufacture
	// agreement on its own — it scales what the members already voted.
	const smBonus = clamp((Number(smartMoneyScore) || 0) / 100, 0, 1) * 0.25;
	const conviction = clamp(consensus * (1 + smBonus), 0, 1);
	return {
		consensus,
		conviction,
		members_long: breakdown.filter((b) => b.long).length,
		members_total: members.length,
		total_weight: totalWeight,
		long_weight: longWeight,
		breakdown,
	};
}

// ── kill switch ────────────────────────────────────────────────────────────────

/**
 * Trigger the swarm kill switch. The creator can always kill; any member (or set
 * of members) holding ≥ policy.kill_threshold_bps of the treasury can too. Halts
 * new consensus buys and flips kill_switch on the treasury strategy + every open
 * position so the sweep liquidates them.
 */
export async function killSwarm({ userId, swarmId, reason = null }) {
	const swarm = await getSwarm(swarmId);
	if (!swarm) throw new SwarmError(404, 'not_found', 'swarm not found');
	if (swarm.status === 'killed') return swarm;
	const pol = normalizeSwarmPolicy(swarm.policy);

	const isCreator = swarm.owner_user_id === userId;
	if (!isCreator) {
		const rows = await sql`
			select coalesce(sum(share_bps),0)::int as bps from swarm_members
			where swarm_id = ${swarm.id} and user_id = ${userId} and status = 'active'
		`;
		const callerBps = rows[0]?.bps || 0;
		if (callerBps < pol.kill_threshold_bps) {
			throw new SwarmError(403, 'below_threshold', `you hold ${(callerBps / 100).toFixed(1)}% — need ${(pol.kill_threshold_bps / 100).toFixed(0)}% to kill`);
		}
	}

	await sql`
		update swarms set status = 'killed', killed_at = now(), killed_by_user_id = ${userId},
			kill_reason = ${reason ? String(reason).slice(0, 280) : null}, updated_at = now()
		where id = ${swarm.id}
	`;
	if (swarm.strategy_id) {
		// Flipping the strategy kill_switch forces every open treasury position to
		// liquidate on the next sweep: getOpenPositions joins s.kill_switch onto each
		// position, and positions.js exits any position whose kill_switch is set.
		await sql`update agent_sniper_strategies set kill_switch = true, enabled = false, updated_at = now() where id = ${swarm.strategy_id}`;
	}

	await recordCustodyEvent({
		agentId: swarm.treasury_agent_id, userId, eventType: 'limit_change', category: 'swarm_payout',
		network: swarm.network, reason: 'swarm_killed', meta: { swarm_id: swarm.id, by: isCreator ? 'creator' : 'member', note: reason || null },
	}).catch(() => {});

	return await getSwarm(swarm.id);
}

// ── pause / resume ─────────────────────────────────────────────────────────────

export async function setSwarmPaused({ userId, swarmId, paused }) {
	const swarm = await getSwarm(swarmId);
	if (!swarm) throw new SwarmError(404, 'not_found', 'swarm not found');
	if (swarm.owner_user_id !== userId) throw new SwarmError(403, 'forbidden', 'only the creator can pause');
	if (swarm.status === 'killed') throw new SwarmError(409, 'killed', 'swarm is killed');
	const next = paused ? 'paused' : 'active';
	await sql`update swarms set status = ${next}, updated_at = now() where id = ${swarm.id}`;
	return await getSwarm(swarm.id);
}

// ── exit + redeem ──────────────────────────────────────────────────────────────

/**
 * Net asset value of the treasury in lamports: liquid SOL + the marked value of
 * its open positions (last quoted value). The basis for settle_at_mark exits.
 */
export async function treasuryNavLamports(swarm) {
	const treasury = await getSwarmTreasuryAddress(swarm);
	const liquid = await treasuryBalanceLamports(treasury, swarm.network);
	const [row] = await sql`
		select coalesce(sum(coalesce(last_value_lamports, entry_quote_lamports, 0)),0)::numeric as marked
		from agent_sniper_positions
		where agent_id = ${swarm.treasury_agent_id} and network = ${swarm.network} and status in ('open','opening','closing')
	`;
	const marked = BigInt(row?.marked ? String(row.marked).split('.')[0] : '0');
	return { liquid, marked, nav: liquid + marked, treasury };
}

/**
 * Exit a member and redeem their share to their own wallet via a real SOL transfer.
 *
 * Open-position policy (explicit):
 *   - settle_at_mark (default): redeem share_bps × treasury NAV (liquid SOL + marked
 *     open-position value), PAID from liquid SOL. If liquid can't cover the marked
 *     portion, the payout is capped to available liquid (minus the fee reserve) and
 *     flagged `capped` — the member is told plainly.
 *   - wait_to_close: exit is refused while the treasury holds open positions; the
 *     member kills or waits for positions to close, then redeems pure liquid SOL.
 */
export async function exitSwarm({ userId, swarmId, agentId }) {
	const swarm = await getSwarm(swarmId);
	if (!swarm) throw new SwarmError(404, 'not_found', 'swarm not found');
	const agent = await requireOwnedAgent(userId, agentId);
	const [member] = await sql`select * from swarm_members where swarm_id = ${swarm.id} and agent_id = ${agent.id} and status = 'active' limit 1`;
	if (!member) throw new SwarmError(404, 'not_member', 'not an active member of this swarm');

	const pol = normalizeSwarmPolicy(swarm.policy);
	const dest = await ensureAgentWallet(agent.id, userId, { reason: 'swarm_exit' });

	const openCount = (await sql`
		select count(*)::int as n from agent_sniper_positions
		where agent_id = ${swarm.treasury_agent_id} and network = ${swarm.network} and status in ('open','opening','closing')
	`)[0]?.n || 0;

	if (pol.exit_policy === 'wait_to_close' && openCount > 0 && swarm.status !== 'killed') {
		throw new SwarmError(409, 'positions_open', 'this swarm settles exits only when no positions are open — wait for them to close or trigger the kill switch');
	}

	const { liquid, nav, treasury } = await treasuryNavLamports(swarm);
	const shareBps = BigInt(member.share_bps || 0);
	const spendable = liquid > GAS_RESERVE_LAMPORTS ? liquid - GAS_RESERVE_LAMPORTS : 0n;

	// Entitlement: share of NAV (settle_at_mark) or share of liquid (wait_to_close).
	const basis = pol.exit_policy === 'wait_to_close' ? liquid : nav;
	let redeem = (basis * shareBps) / BigInt(BPS);
	let capped = false;
	if (redeem > spendable) { redeem = spendable; capped = true; }

	// Claim this member's one exit BEFORE any SOL moves. The member read above is
	// a plain SELECT, so concurrent exits each saw 'active', each priced the
	// share off the same pre-transfer NAV, and each paid it: a 30% member drained
	// the treasury in a few parallel calls. The payout row's unique idempotency
	// key is the claim; a concurrent exit conflicts here and pays nothing.
	const [claim] = await sql`
		insert into swarm_payouts (swarm_id, member_id, agent_id, kind, amount_lamports, share_bps, destination, status, idempotency_key, meta)
		values (${swarm.id}, ${member.id}, ${agent.id}, 'exit', ${redeem.toString()}, ${member.share_bps || 0}, ${dest.address}, 'pending',
			${`swarm_exit:${member.id}`}, ${JSON.stringify({ capped, exit_policy: pol.exit_policy })}::jsonb)
		on conflict (idempotency_key) do nothing
		returning id
	`;
	if (!claim) throw new SwarmError(409, 'exit_in_progress', 'this member already has an exit in progress or settled');

	let signature = null;
	if (redeem > 0n) {
		try {
			const keypair = await recoverSolanaAgentKeypair(
				(await sql`select meta from agent_identities where id = ${swarm.treasury_agent_id} limit 1`)[0]?.meta?.encrypted_solana_secret,
				{ agentId: swarm.treasury_agent_id, userId, reason: 'swarm_exit_redeem', meta: { swarm_id: swarm.id, member_id: member.id } },
			);
			signature = await transferNativeSol({ fromKeypair: keypair, toAddress: dest.address, lamports: redeem, network: swarm.network });
		} catch (err) {
			// Nothing was paid: release the claim so the member can retry.
			await sql`delete from swarm_payouts where id = ${claim.id} and status = 'pending'`;
			throw err;
		}
	}
	await sql`
		update swarm_payouts set status = 'confirmed', signature = ${signature}, updated_at = now()
		where id = ${claim.id}
	`;
	if (redeem > 0n) {
		await recordCustodyEvent({
			agentId: swarm.treasury_agent_id, userId, eventType: 'withdraw', category: 'swarm_payout',
			network: swarm.network, asset: 'SOL', amountLamports: redeem, destination: dest.address,
			signature, reason: 'swarm_exit_redeem', status: 'confirmed',
			idempotencyKey: `swarm_exit:${member.id}:${signature}`, meta: { swarm_id: swarm.id, member_id: member.id, capped },
		}).catch(() => {});
	}

	await sql`
		update swarm_members
		set status = 'exited', exited_at = now(), withdrawn_lamports = withdrawn_lamports + ${redeem.toString()}, share_bps = 0, updated_at = now()
		where id = ${member.id}
	`;
	await recomputeShares(swarm.id);

	return { redeemed_lamports: redeem.toString(), redeemed_sol: Number(redeem) / LAMPORTS_PER_SOL, signature, capped, exit_policy: pol.exit_policy };
}

// ── settlement: distribute realized profit on closed positions ─────────────────

/**
 * For one swarm, distribute the realized profit of any newly-closed treasury
 * positions pro-rata to members by share, minus the creator fee. Principal stays
 * in the treasury so it keeps trading; only positive realized PnL is paid out.
 * Idempotent: a position that has any 'profit' payout row is never re-scanned.
 * Losing/break-even closes write a single zero-amount marker row so they settle
 * once and don't re-scan forever.
 *
 * Returns the number of positions settled and total lamports distributed. Pass a
 * `transfer` override for tests; defaults to a real on-chain SOL transfer.
 */
export async function settleSwarm(swarmId, { transfer = transferNativeSol } = {}) {
	const swarm = await getSwarm(swarmId);
	if (!swarm) return { settled: 0, distributed: '0' };

	const pending = await sql`
		select p.id, p.mint, p.symbol, p.realized_pnl_lamports, p.exit_quote_lamports, p.entry_quote_lamports
		from agent_sniper_positions p
		where p.agent_id = ${swarm.treasury_agent_id} and p.network = ${swarm.network}
		  and p.status = 'closed' and p.realized_pnl_lamports is not null
		  and not exists (select 1 from swarm_payouts sp where sp.position_id = p.id and sp.kind = 'profit')
		order by p.closed_at asc
		limit 25
	`;
	if (!pending.length) return { settled: 0, distributed: '0' };

	const pol = normalizeSwarmPolicy(swarm.policy);
	let settled = 0;
	let distributedTotal = 0n;
	let treasuryKeypair = null;

	for (const pos of pending) {
		const profit = BigInt(pos.realized_pnl_lamports);
		// Loss / break-even — record a settled marker (no transfer) and move on.
		if (profit <= 0n) {
			await sql`
				insert into swarm_payouts (swarm_id, position_id, kind, amount_lamports, status, idempotency_key, meta)
				values (${swarm.id}, ${pos.id}, 'profit', 0, 'confirmed', ${`swarm_profit:${pos.id}:noop`},
					${JSON.stringify({ realized_pnl_lamports: pos.realized_pnl_lamports, loss: true, mint: pos.mint })}::jsonb)
				on conflict (idempotency_key) do nothing
			`;
			settled++;
			continue;
		}

		// Snapshot member shares at settlement time.
		const members = await sql`
			select id, agent_id, user_id, share_bps from swarm_members
			where swarm_id = ${swarm.id} and status = 'active' and share_bps > 0
		`;
		if (!members.length) {
			await sql`
				insert into swarm_payouts (swarm_id, position_id, kind, amount_lamports, status, idempotency_key, meta)
				values (${swarm.id}, ${pos.id}, 'profit', 0, 'confirmed', ${`swarm_profit:${pos.id}:noop`},
					${JSON.stringify({ note: 'no_active_members', profit: profit.toString() })}::jsonb)
				on conflict (idempotency_key) do nothing
			`;
			settled++;
			continue;
		}

		// Bound distribution to liquid SOL minus the fee reserve.
		const treasuryAddr = await getSwarmTreasuryAddress(swarm);
		const liquid = await treasuryBalanceLamports(treasuryAddr, swarm.network);
		const spendable = liquid > GAS_RESERVE_LAMPORTS ? liquid - GAS_RESERVE_LAMPORTS : 0n;
		if (spendable <= 0n) break; // nothing to pay with right now — retry next sweep

		let distributable = profit > spendable ? spendable : profit;
		const fee = (distributable * BigInt(pol.creator_fee_bps)) / BigInt(BPS);
		const netDistributable = distributable - fee;

		if (!treasuryKeypair) {
			const meta = (await sql`select meta from agent_identities where id = ${swarm.treasury_agent_id} limit 1`)[0]?.meta;
			treasuryKeypair = await recoverSolanaAgentKeypair(meta?.encrypted_solana_secret, {
				agentId: swarm.treasury_agent_id, userId: swarm.owner_user_id, reason: 'swarm_profit_settle', meta: { swarm_id: swarm.id },
			});
		}

		// Pro-rata member payouts.
		for (const m of members) {
			const amount = (netDistributable * BigInt(m.share_bps)) / BigInt(BPS);
			if (amount <= 0n) continue;
			await payoutMember({
				swarm, position: pos, member: m, amount, kind: 'profit',
				keypair: treasuryKeypair, transfer,
				idempotencyKey: `swarm_profit:${pos.id}:${m.id}`,
			});
			distributedTotal += amount;
		}

		// Creator fee → owner agent wallet.
		if (fee > 0n) {
			const ownerWallet = await ensureAgentWallet(swarm.owner_agent_id, swarm.owner_user_id, { reason: 'swarm_fee' });
			await payoutFee({ swarm, position: pos, amount: fee, destination: ownerWallet.address, keypair: treasuryKeypair, transfer });
		}
		settled++;
	}

	return { settled, distributed: distributedTotal.toString() };
}

async function payoutMember({ swarm, position, member, amount, keypair, transfer, idempotencyKey }) {
	// Reserve the row first (pending) so a crash mid-transfer is recoverable +
	// never double-pays (idempotency_key is unique).
	const inserted = await sql`
		insert into swarm_payouts (swarm_id, member_id, agent_id, position_id, kind, amount_lamports, share_bps, status, idempotency_key, meta)
		values (${swarm.id}, ${member.id}, ${member.agent_id}, ${position.id}, 'profit', ${amount.toString()}, ${member.share_bps},
			'pending', ${idempotencyKey}, ${JSON.stringify({ mint: position.mint, symbol: position.symbol })}::jsonb)
		on conflict (idempotency_key) do nothing
		returning id
	`;
	if (!inserted.length) return; // already paid

	const dest = (await sql`select meta from agent_identities where id = ${member.agent_id} limit 1`)[0]?.meta?.solana_address;
	if (!dest) {
		await sql`update swarm_payouts set status = 'failed', meta = meta || ${JSON.stringify({ error: 'member_no_wallet' })}::jsonb, updated_at = now() where id = ${inserted[0].id}`;
		return;
	}
	try {
		const signature = await transfer({ fromKeypair: keypair, toAddress: dest, lamports: amount, network: swarm.network });
		await sql`update swarm_payouts set status = 'confirmed', signature = ${signature}, destination = ${dest}, updated_at = now() where id = ${inserted[0].id}`;
		await recordCustodyEvent({
			agentId: swarm.treasury_agent_id, userId: member.user_id, eventType: 'spend', category: 'swarm_payout',
			network: swarm.network, asset: 'SOL', amountLamports: amount, destination: dest, signature,
			reason: 'swarm_profit_payout', status: 'confirmed', idempotencyKey: `${idempotencyKey}:${signature}`,
			meta: { swarm_id: swarm.id, position_id: position.id, mint: position.mint },
		}).catch(() => {});
	} catch (e) {
		await sql`update swarm_payouts set status = 'failed', meta = meta || ${JSON.stringify({ error: String(e?.message || e).slice(0, 200) })}::jsonb, updated_at = now() where id = ${inserted[0].id}`;
	}
}

async function payoutFee({ swarm, position, amount, destination, keypair, transfer }) {
	const inserted = await sql`
		insert into swarm_payouts (swarm_id, agent_id, position_id, kind, amount_lamports, status, idempotency_key, destination, meta)
		values (${swarm.id}, ${swarm.owner_agent_id}, ${position.id}, 'fee', ${amount.toString()}, 'pending', ${`swarm_fee:${position.id}`}, ${destination},
			${JSON.stringify({ mint: position.mint })}::jsonb)
		on conflict (idempotency_key) do nothing
		returning id
	`;
	if (!inserted.length) return;
	try {
		const signature = await transfer({ fromKeypair: keypair, toAddress: destination, lamports: amount, network: swarm.network });
		await sql`update swarm_payouts set status = 'confirmed', signature = ${signature}, updated_at = now() where id = ${inserted[0].id}`;
		await recordCustodyEvent({
			agentId: swarm.treasury_agent_id, userId: swarm.owner_user_id, eventType: 'spend', category: 'swarm_payout',
			network: swarm.network, asset: 'SOL', amountLamports: amount, destination, signature,
			reason: 'swarm_creator_fee', status: 'confirmed', idempotencyKey: `swarm_fee:${position.id}:${signature}`,
			meta: { swarm_id: swarm.id, position_id: position.id },
		}).catch(() => {});
	} catch (e) {
		await sql`update swarm_payouts set status = 'failed', meta = meta || ${JSON.stringify({ error: String(e?.message || e).slice(0, 200) })}::jsonb, updated_at = now() where id = ${inserted[0].id}`;
	}
}

// ── reads (directory + dashboard) ──────────────────────────────────────────────

/** Directory of open/active swarms with aggregate stats. */
export async function listSwarms({ network = 'mainnet', status = null, limit = 30, offset = 0 } = {}) {
	const net = network === 'devnet' ? 'devnet' : 'mainnet';
	const rows = status
		? await sql`
			select s.*, ${net} as _n from swarms s
			where s.network = ${net} and s.status = ${status}
			order by s.created_at desc limit ${limit} offset ${offset}`
		: await sql`
			select s.* from swarms s
			where s.network = ${net} and s.status in ('open','active','paused')
			order by (s.status = 'active') desc, s.created_at desc limit ${limit} offset ${offset}`;
	return summarizeSwarms(rows);
}

/** Every swarm the user owns or is (or was) a member of, any status — for "My swarms". */
export async function listSwarmsForUser(userId) {
	const rows = await sql`
		select distinct s.* from swarms s
		left join swarm_members m on m.swarm_id = s.id and m.user_id = ${userId}
		where s.owner_user_id = ${userId} or m.id is not null
		order by s.created_at desc
		limit 100
	`;
	return summarizeSwarms(rows);
}

/**
 * Summarize a batch of swarm rows for a directory listing. Aggregate stats for
 * every swarm are fetched in two grouped queries (not two-per-swarm) so a long
 * directory stays a fixed cost. A single member/position sub-query failure
 * degrades to zeroed stats for the whole batch rather than 500-ing the endpoint,
 * and a malformed individual row is skipped — a public directory must never die
 * on one bad record.
 */
async function summarizeSwarms(rows) {
	if (!rows.length) return [];
	const swarmIds = rows.map((s) => s.id);
	const treasuryIds = [...new Set(rows.map((s) => s.treasury_agent_id).filter(Boolean))];

	const [memberRows, tradeRows] = await Promise.all([
		sql`
			select swarm_id,
			       count(*) filter (where status = 'active')::int as members,
			       coalesce(sum(contribution_lamports) filter (where status = 'active'),0)::numeric as contributed,
			       coalesce(sum(withdrawn_lamports),0)::numeric as withdrawn
			from swarm_members where swarm_id = any(${swarmIds}) group by swarm_id
		`.catch(() => []),
		treasuryIds.length
			? sql`
				select agent_id, network,
				       count(*)::int as closed,
				       coalesce(sum(realized_pnl_lamports),0)::numeric as pnl,
				       count(*) filter (where realized_pnl_lamports > 0)::int as wins,
				       count(*) filter (where status in ('open','opening','closing'))::int as open
				from agent_sniper_positions where agent_id = any(${treasuryIds}) group by agent_id, network
			`.catch(() => [])
			: Promise.resolve([]),
	]);

	const memberBy = new Map(memberRows.map((r) => [r.swarm_id, r]));
	const tradeBy = new Map(tradeRows.map((r) => [`${r.agent_id}|${r.network}`, r]));

	const out = [];
	for (const s of rows) {
		try {
			out.push(summarizeSwarmRow(s, memberBy.get(s.id), tradeBy.get(`${s.treasury_agent_id}|${s.network}`)));
		} catch {
			// A malformed row (e.g. unparseable policy) must not sink the whole list.
		}
	}
	return out;
}

function summarizeSwarmRow(swarm, agg, trades) {
	const lamports = (v) => (v == null ? 0 : Number(String(v).split('.')[0]) / LAMPORTS_PER_SOL);
	const closed = Number(trades?.closed || 0);
	return {
		id: swarm.id,
		name: swarm.name,
		description: swarm.description,
		network: swarm.network,
		status: swarm.status,
		policy: normalizeSwarmPolicy(swarm.policy),
		members: Number(agg?.members || 0),
		contributed_sol: lamports(agg?.contributed),
		closed_trades: closed,
		open_positions: Number(trades?.open || 0),
		wins: Number(trades?.wins || 0),
		win_rate: closed > 0 ? Number(trades.wins) / closed : null,
		realized_pnl_sol: lamports(trades?.pnl),
		created_at: swarm.created_at,
	};
}

/** Full dashboard state for one swarm: treasury (on-chain), members, positions, votes, payouts. */
export async function getSwarmState(swarmId, { viewerUserId = null } = {}) {
	const swarm = await getSwarm(swarmId);
	if (!swarm) return null;
	const pol = normalizeSwarmPolicy(swarm.policy);
	const treasury = await getSwarmTreasuryAddress(swarm);

	const [balance, members, positions, votes, payouts] = await Promise.all([
		treasuryBalanceLamports(treasury, swarm.network).catch(() => null),
		sql`
			select sm.id, sm.agent_id, sm.user_id, sm.contribution_lamports, sm.withdrawn_lamports, sm.share_bps,
			       sm.reputation, sm.status, sm.is_creator, sm.joined_at, ai.name as agent_name, ai.profile_image_url, ai.avatar_url
			from swarm_members sm join agent_identities ai on ai.id = sm.agent_id
			where sm.swarm_id = ${swarmId} order by sm.share_bps desc, sm.joined_at asc`,
		sql`
			select id, mint, symbol, name, status, exit_reason, entry_quote_lamports, last_value_lamports,
			       realized_pnl_lamports, realized_pnl_pct, opened_at, closed_at, buy_sig, sell_sig
			from agent_sniper_positions where agent_id = ${swarm.treasury_agent_id} and network = ${swarm.network}
			order by coalesce(closed_at, opened_at) desc limit 50`,
		sql`select id, mint, decision, consensus, min_consensus, conviction, size_lamports, members_long, members_total, smart_money_score, breakdown, position_id, reason, created_at
			from swarm_votes where swarm_id = ${swarmId} order by created_at desc limit 40`,
		sql`select id, member_id, agent_id, position_id, kind, amount_lamports, share_bps, destination, signature, status, created_at
			from swarm_payouts where swarm_id = ${swarmId} order by created_at desc limit 60`,
	]);

	const sol = (v) => (v == null ? null : Number(String(v).split('.')[0]) / LAMPORTS_PER_SOL);
	const balLamports = balance == null ? null : balance;
	const contributed = members.filter((m) => m.status === 'active').reduce((a, m) => a + (Number(m.contribution_lamports) - Number(m.withdrawn_lamports)), 0);
	const closed = positions.filter((p) => p.status === 'closed');
	const wins = closed.filter((p) => Number(p.realized_pnl_lamports) > 0).length;
	const realizedPnl = closed.reduce((a, p) => a + Number(p.realized_pnl_lamports || 0), 0);

	const solscan = (sig) => (!sig || sig === 'SIMULATED' ? null : swarm.network === 'devnet' ? `https://solscan.io/tx/${sig}?cluster=devnet` : `https://solscan.io/tx/${sig}`);

	return {
		swarm: {
			id: swarm.id, name: swarm.name, description: swarm.description, network: swarm.network, status: swarm.status,
			owner_user_id: swarm.owner_user_id, owner_agent_id: swarm.owner_agent_id, created_at: swarm.created_at,
			kill_reason: swarm.kill_reason,
		},
		policy: pol,
		is_owner: viewerUserId != null && viewerUserId === swarm.owner_user_id,
		viewer_member: viewerUserId == null ? null : members.find((m) => m.user_id === viewerUserId && m.status === 'active') || null,
		treasury: {
			address: treasury,
			balance_lamports: balLamports == null ? null : balLamports.toString(),
			balance_sol: balLamports == null ? null : Number(balLamports) / LAMPORTS_PER_SOL,
			net_contributed_sol: contributed / LAMPORTS_PER_SOL,
			explorer: swarm.network === 'devnet' ? `https://solscan.io/account/${treasury}?cluster=devnet` : `https://solscan.io/account/${treasury}`,
		},
		track_record: {
			closed_trades: closed.length, wins, win_rate: closed.length ? wins / closed.length : null,
			realized_pnl_sol: realizedPnl / LAMPORTS_PER_SOL,
			open_positions: positions.filter((p) => ['open', 'opening', 'closing'].includes(p.status)).length,
		},
		members: (() => {
			// Vote weight is what consensus actually runs on: max(MIN_VOTE_WEIGHT, rep),
			// summed over ACTIVE members only (exited members carry none). Surfacing each
			// member's share of that total turns the abstract reputation score into the
			// literal "how much of this swarm's vote do you control" number — same formula
			// as computeConsensus, so the board can't drift from the engine.
			const voteWeight = (m) => (m.status === 'active' ? Math.max(MIN_VOTE_WEIGHT, Number(m.reputation) || 0) : 0);
			const totalVoteWeight = members.reduce((sum, m) => sum + voteWeight(m), 0);
			return members.map((m) => {
				const weight = voteWeight(m);
				return {
					id: m.id, agent_id: m.agent_id, name: m.agent_name,
					image: m.profile_image_url || m.avatar_url || null,
					contribution_sol: (Number(m.contribution_lamports) - Number(m.withdrawn_lamports)) / LAMPORTS_PER_SOL,
					share_bps: m.share_bps, reputation: m.reputation == null ? null : Number(m.reputation),
					vote_weight: weight, vote_power: totalVoteWeight > 0 ? weight / totalVoteWeight : 0,
					status: m.status, is_creator: m.is_creator, joined_at: m.joined_at,
				};
			});
		})(),
		positions: positions.map((p) => ({
			id: p.id, mint: p.mint, symbol: p.symbol, name: p.name, status: p.status, exit_reason: p.exit_reason,
			entry_sol: sol(p.entry_quote_lamports), current_sol: sol(p.last_value_lamports),
			pnl_sol: p.realized_pnl_lamports == null ? null : sol(p.realized_pnl_lamports), pnl_pct: p.realized_pnl_pct == null ? null : Number(p.realized_pnl_pct),
			opened_at: p.opened_at, closed_at: p.closed_at, buy_url: solscan(p.buy_sig), sell_url: solscan(p.sell_sig),
		})),
		votes: votes.map((v) => ({
			id: v.id, mint: v.mint, decision: v.decision, consensus: v.consensus, min_consensus: v.min_consensus,
			conviction: v.conviction, size_sol: sol(v.size_lamports), members_long: v.members_long, members_total: v.members_total,
			smart_money_score: v.smart_money_score, breakdown: v.breakdown, reason: v.reason, created_at: v.created_at,
		})),
		payouts: payouts.map((p) => ({
			id: p.id, kind: p.kind, amount_sol: sol(p.amount_lamports), share_bps: p.share_bps, status: p.status,
			agent_id: p.agent_id, destination: p.destination, tx_url: solscan(p.signature), created_at: p.created_at,
		})),
	};
}