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.

26.0 KB
Raw Blame
// Creator-fee payouts: the payout wallet, the distribution run and the reads the
// earnings page and API are built on. Pure rules (held reasons, the signed
// message, the per-$100 flow) live in creator-payouts-core.js.
//
// The money path, end to end:
//   1. launcher-claimer claims creator fees into the agent wallet and records a
//      launcher_claims row (claimed lamports, and the buyback share earmarked).
//   2. runDistribution() ingests each claim as a creator_payout_distributions
//      row holding the creator's share (claim minus the earmark).
//   3. For each agent with unsent rows it asks holdReason(): no registered
//      wallet, a wallet change in its cooldown, below the minimum, the agent
//      wallet too low, or distribution switched off. A held row says why.
//   4. Otherwise the rows are locked as one batch and ONE SOL transfer from the
//      agent wallet to the registered payout wallet is sent. The wallet was
//      registered by the owner signing a message with it (Ed25519, timestamp,
//      one-use nonce) after a step-up, so the destination is the owner's
//      explicit, signed choice. Sending is off unless CREATOR_PAYOUTS_LIVE=true.

import { randomBytes } from 'node:crypto';
import { sql } from './db.js';
import { logAudit } from './audit.js';
import { sendOpsAlert } from './alerts.js';
import { verifySiwsSignature } from './siws.js';
import { WhitelistError, buildOp, consumeGrant } from './destination-whitelist.js';
import {
	HOLD_REASONS, LAMPORTS_PER_SOL, MIN_PAYOUT_LAMPORTS, WALLET_CHANGE_COOLDOWN_MS, WALLET_RESERVE_LAMPORTS,
	buildRegistrationMessage, checkRegistrationMessage, holdReason, isSolanaAddress, solFromLamports, summarizeDistributions,
} from './creator-payouts-core.js';

const MAX_INGEST = 500;
const STUCK_SENDING_MS = 10 * 60_000;
/** Held reasons that are the normal state of the system, not news worth a notification. */
const QUIET_REASONS = new Set(['below_minimum', 'payouts_paused']);

export const payoutsLive = () => String(process.env.CREATOR_PAYOUTS_LIVE ?? '') === 'true';

const sol = (lamports) => Number(solFromLamports(lamports));

// ── Ownership ────────────────────────────────────────────────────────────────

async function loadOwnedAgent(agentId, userId) {
	if (!/^[0-9a-f-]{36}$/i.test(String(agentId || ''))) throw new WhitelistError(400, 'invalid_agent_id', 'agent_id must be a UUID');
	const [agent] = await sql`SELECT id, user_id, name FROM agent_identities WHERE id = ${agentId} AND deleted_at IS NULL`;
	if (!agent) throw new WhitelistError(404, 'agent_not_found', 'Agent not found.');
	if (agent.user_id !== userId) throw new WhitelistError(403, 'forbidden', 'Only the owner of this agent can manage its payout wallet.');
	return agent;
}

function requireBrowserSession(actor) {
	if (!actor?.sessionId || actor.kind !== 'owner') {
		throw new WhitelistError(403, 'session_required', 'This needs the owner signed in to the three.ws site. API keys, OAuth tokens and agents cannot change a payout wallet.');
	}
}

// ── Wallet state ─────────────────────────────────────────────────────────────

/** Promote any staged wallet whose cooldown has ended. One agent, or all. */
export async function promoteDueWallets(agentId = null) {
	return sql`
		UPDATE creator_payout_wallets
		SET wallet = pending_wallet, registered_at = pending_effective_at, changes = changes + 1,
		    pending_wallet = NULL, pending_effective_at = NULL, pending_requested_at = NULL, updated_at = now()
		WHERE pending_wallet IS NOT NULL AND pending_effective_at <= now()
		  AND (${agentId}::uuid IS NULL OR agent_id = ${agentId}::uuid)
		RETURNING agent_id, user_id, wallet`;
}

export function walletView(row) {
	if (!row) return { wallet: null, registered_at: null, pending: null, cooldown_hours: WALLET_CHANGE_COOLDOWN_MS / 3_600_000 };
	return {
		wallet: row.wallet || null,
		registered_at: row.registered_at || null,
		pending: row.pending_wallet
			? { wallet: row.pending_wallet, effective_at: row.pending_effective_at, requested_at: row.pending_requested_at }
			: null,
		cooldown_hours: WALLET_CHANGE_COOLDOWN_MS / 3_600_000,
	};
}

export async function getPayoutWallet(agentId) {
	await promoteDueWallets(agentId).catch(() => {});
	const [row] = await sql`SELECT * FROM creator_payout_wallets WHERE agent_id = ${agentId}`;
	return walletView(row);
}

// ── Registration ─────────────────────────────────────────────────────────────

/** The message to sign. Stateless: the nonce is spent when the signature arrives. */
export async function issueRegistrationChallenge({ agentId, userId, wallet }) {
	await loadOwnedAgent(agentId, userId);
	if (!isSolanaAddress(wallet)) throw new WhitelistError(400, 'invalid_address', 'That is not a valid Solana address.');
	const nonce = randomBytes(16).toString('hex');
	const issuedAt = new Date().toISOString();
	return {
		agent_id: agentId,
		wallet,
		nonce,
		issued_at: issuedAt,
		message: buildRegistrationMessage({ agentId, wallet, nonce, issuedAt }),
		expires_in_seconds: 300,
		cooldown_hours: WALLET_CHANGE_COOLDOWN_MS / 3_600_000,
	};
}

/**
 * Register or change the payout wallet.
 *
 * Requires, in this order: an owner browser session; the wallet's own Ed25519
 * signature over the challenge message (fresh timestamp); a nonce never seen
 * before (replay guard, an atomic insert); and a step-up grant bound to this
 * agent and this wallet. The first wallet is active at once. A change is staged
 * and takes effect after the cooldown, and payouts are held until it does.
 */
export async function registerPayoutWallet({ actor, agentId, wallet, message, signature, grantId, req = null, now = Date.now() }) {
	requireBrowserSession(actor);
	const agent = await loadOwnedAgent(agentId, actor.userId);
	if (!isSolanaAddress(wallet)) throw new WhitelistError(400, 'invalid_address', 'That is not a valid Solana address.');

	const checked = checkRegistrationMessage(message, { agentId, wallet, now });
	if (!checked.ok) throw new WhitelistError(400, checked.code, checked.message);

	let valid = false;
	try {
		valid = verifySiwsSignature(String(message), String(signature || ''), wallet);
	} catch {
		valid = false;
	}
	if (!valid) throw new WhitelistError(401, 'bad_signature', 'That signature was not made by the payout wallet.');

	const [spent] = await sql`
		INSERT INTO creator_payout_nonces (nonce, agent_id, wallet, issued_at)
		VALUES (${checked.nonce}, ${agentId}, ${wallet}, ${checked.issuedAt})
		ON CONFLICT (nonce) DO NOTHING RETURNING nonce`;
	if (!spent) throw new WhitelistError(409, 'nonce_used', 'That signed message was already used. Request a new one and sign again.');

	await consumeGrant({ grantId, actor, agentId, op: buildOp('payout_wallet', agentId, { wallet }) });

	await promoteDueWallets(agentId);
	const [existing] = await sql`SELECT * FROM creator_payout_wallets WHERE agent_id = ${agentId}`;
	let outcome;
	if (!existing || (!existing.wallet && !existing.pending_wallet)) {
		await sql`
			INSERT INTO creator_payout_wallets (agent_id, user_id, wallet, registered_at)
			VALUES (${agentId}, ${actor.userId}, ${wallet}, now())
			ON CONFLICT (agent_id) DO UPDATE SET wallet = EXCLUDED.wallet, registered_at = now(), updated_at = now()`;
		outcome = 'registered';
	} else if (existing.wallet === wallet && !existing.pending_wallet) {
		outcome = 'unchanged';
	} else if (existing.wallet === wallet) {
		await sql`
			UPDATE creator_payout_wallets
			SET pending_wallet = NULL, pending_effective_at = NULL, pending_requested_at = NULL, updated_at = now()
			WHERE agent_id = ${agentId}`;
		outcome = 'change_cancelled';
	} else {
		const effectiveAt = new Date(now + WALLET_CHANGE_COOLDOWN_MS).toISOString();
		await sql`
			UPDATE creator_payout_wallets
			SET pending_wallet = ${wallet}, pending_effective_at = ${effectiveAt}, pending_requested_at = now(), updated_at = now()
			WHERE agent_id = ${agentId}`;
		outcome = 'change_staged';
	}

	logAudit({ userId: actor.userId, action: `creator_payout.${outcome}`, resourceId: agentId, meta: { wallet }, req });
	if (outcome === 'registered' || outcome === 'change_staged') {
		await notifyOwner(actor.userId, 'creator_payout_wallet', {
			agent_id: agentId,
			agent_name: agent.name,
			message:
				outcome === 'registered'
					? `Payout wallet registered for ${agent.name || 'your agent'}. Creator-fee shares will be sent to it.`
					: `Payout wallet change staged for ${agent.name || 'your agent'}. It takes effect in ${WALLET_CHANGE_COOLDOWN_MS / 3_600_000} hours, and payouts are held until then. Cancel it if this was not you.`,
			link: `/creator/payouts?agent=${agentId}`,
		});
	}
	return { outcome, ...(await getPayoutWallet(agentId)) };
}

/** Drop a staged wallet change. Instant, no step-up: it can only make the account safer. */
export async function cancelPendingWallet({ actor, agentId, req = null }) {
	requireBrowserSession(actor);
	await loadOwnedAgent(agentId, actor.userId);
	const [row] = await sql`
		UPDATE creator_payout_wallets
		SET pending_wallet = NULL, pending_effective_at = NULL, pending_requested_at = NULL, updated_at = now()
		WHERE agent_id = ${agentId} AND pending_wallet IS NOT NULL AND user_id = ${actor.userId}
		RETURNING agent_id`;
	if (!row) throw new WhitelistError(404, 'no_pending_change', 'There is no pending payout wallet change to cancel.');
	logAudit({ userId: actor.userId, action: 'creator_payout.change_cancelled', resourceId: agentId, req });
	return getPayoutWallet(agentId);
}

async function notifyOwner(userId, type, payload) {
	try {
		const { insertNotification } = await import('./notify.js');
		await insertNotification(userId, type, payload);
	} catch (e) {
		console.warn('[creator-payouts] notify failed', e?.message);
	}
}

// ── Reads ────────────────────────────────────────────────────────────────────

/** Distribution rows for an agent, newest first. */
export async function listDistributions(agentId, { limit = 50, offset = 0 } = {}) {
	return sql`
		SELECT id, agent_id, mint, network, claim_sig, creator_lamports::text AS creator_lamports, status, hold_reason,
		       payout_wallet, tx_signature, sent_at, created_at
		FROM creator_payout_distributions
		WHERE agent_id = ${agentId}
		ORDER BY created_at DESC, id
		LIMIT ${limit} OFFSET ${offset}`;
}

const distView = (r) => ({
	id: r.id,
	mint: r.mint,
	status: r.status === 'sending' ? 'pending' : r.status,
	sol: sol(r.creator_lamports),
	hold_reason: r.hold_reason || null,
	hold: r.hold_reason ? { code: r.hold_reason, ...(HOLD_REASONS[r.hold_reason] || { label: r.hold_reason, fix: '' }) } : null,
	payout_wallet: r.payout_wallet || null,
	claim_signature: r.claim_sig || null,
	signature: r.tx_signature || null,
	explorer: r.tx_signature ? `https://solscan.io/tx/${r.tx_signature}` : null,
	at: r.sent_at || r.created_at,
});

/**
 * The payouts block of GET /api/agents/:id/earnings: the payout wallet, the
 * sent/pending/held totals, the same split per coin, why anything is held, and
 * the latest distributions with their transaction signatures.
 */
export async function getAgentPayouts(agentId) {
	const [wallet, rows] = await Promise.all([
		getPayoutWallet(agentId),
		sql`
			SELECT id, mint, claim_sig, creator_lamports::text AS creator_lamports, status, hold_reason, payout_wallet,
			       tx_signature, sent_at, created_at
			FROM creator_payout_distributions
			WHERE agent_id = ${agentId} AND network = 'mainnet'
			ORDER BY created_at DESC, id`,
	]);
	const total = summarizeDistributions(rows);
	const byMint = new Map();
	for (const r of rows) {
		if (!byMint.has(r.mint)) byMint.set(r.mint, []);
		byMint.get(r.mint).push(r);
	}
	const perCoin = {};
	for (const [mint, list] of byMint) {
		const t = summarizeDistributions(list);
		perCoin[mint] = { sent_sol: sol(t.sent), pending_sol: sol(t.pending), held_sol: sol(t.held) };
	}
	const heldReasons = Object.entries(total.held_by_reason).map(([code, lamports]) => ({
		code,
		sol: sol(lamports),
		...(HOLD_REASONS[code] || { label: code, fix: '' }),
	}));
	return {
		wallet,
		minimum_payout_sol: MIN_PAYOUT_LAMPORTS / LAMPORTS_PER_SOL,
		live: payoutsLive(),
		total_sent_sol: sol(total.sent),
		total_pending_sol: sol(total.pending),
		total_held_sol: sol(total.held),
		held_reasons: heldReasons,
		per_coin: perCoin,
		recent_distributions: rows.slice(0, 20).map(distView),
	};
}

// ── Distribution run ─────────────────────────────────────────────────────────

/** Record each unrecorded claim's creator share. Returns the number ingested. */
export async function ingestClaims() {
	const rows = await sql`
		INSERT INTO creator_payout_distributions (claim_id, agent_id, user_id, mint, network, claim_sig, creator_lamports, status)
		SELECT lc.id, lc.agent_id, ai.user_id, lc.mint, lc.network, lc.claim_sig,
		       greatest(lc.claimed_lamports - round(lc.buyback_sol * 1000000000)::bigint, 0), 'pending'
		FROM launcher_claims lc
		JOIN agent_identities ai ON ai.id = lc.agent_id AND ai.deleted_at IS NULL
		WHERE lc.network = 'mainnet' AND lc.claim_sig IS NOT NULL AND lc.claimed_lamports > 0
		  AND lc.agent_id IS NOT NULL
		  AND greatest(lc.claimed_lamports - round(lc.buyback_sol * 1000000000)::bigint, 0) > 0
		  AND NOT EXISTS (SELECT 1 FROM creator_payout_distributions d WHERE d.claim_id = lc.id)
		ORDER BY lc.created_at
		LIMIT ${MAX_INGEST}
		ON CONFLICT (claim_id) DO NOTHING
		RETURNING id`;
	return rows.length;
}

/** Send `lamports` of SOL from the agent's custodial wallet. Returns { signature }. */
async function sendFromAgentWallet({ agentId, userId, fromSecret, fromAddress, to, lamports, batchId }) {
	const { recoverSolanaAgentKeypair } = await import('./agent-wallet.js');
	const { Connection, PublicKey, SystemProgram, Transaction } = await import('@solana/web3.js');
	const { getConnection } = await import('./pump.js');
	/** @type {Connection} */
	const conn = getConnection({ network: 'mainnet' });
	const kp = await recoverSolanaAgentKeypair(fromSecret, { agentId, userId, reason: 'creator_payout', meta: { batch_id: batchId, to } });
	if (kp.publicKey.toBase58() !== fromAddress) throw new Error('agent wallet key does not match its recorded address');
	const balance = await conn.getBalance(kp.publicKey, 'confirmed');
	if (BigInt(balance) < BigInt(lamports) + BigInt(WALLET_RESERVE_LAMPORTS)) {
		const err = new Error('agent wallet balance too low');
		err.code = 'agent_wallet_low';
		throw err;
	}
	const { blockhash, lastValidBlockHeight } = await conn.getLatestBlockhash('confirmed');
	const tx = new Transaction({ feePayer: kp.publicKey, blockhash, lastValidBlockHeight }).add(
		SystemProgram.transfer({ fromPubkey: kp.publicKey, toPubkey: new PublicKey(to), lamports: BigInt(lamports) }),
	);
	tx.sign(kp);
	const signature = await conn.sendRawTransaction(tx.serialize(), { skipPreflight: false });
	return { signature, conn, blockhash, lastValidBlockHeight };
}

async function holdRows(agentId, reason) {
	await sql`
		UPDATE creator_payout_distributions
		SET status = 'held', hold_reason = ${reason}, payout_wallet = NULL, updated_at = now()
		WHERE agent_id = ${agentId} AND status IN ('pending', 'held')`;
}

async function maybeNotifyHeld(agentId, userId, agentName, reason, lamports) {
	const [state] = await sql`SELECT last_held_reason FROM creator_payout_state WHERE agent_id = ${agentId}`;
	if (state?.last_held_reason === reason) return false;
	await sql`
		INSERT INTO creator_payout_state (agent_id, last_held_reason, notified_at) VALUES (${agentId}, ${reason}, now())
		ON CONFLICT (agent_id) DO UPDATE SET last_held_reason = EXCLUDED.last_held_reason, notified_at = now()`;
	if (QUIET_REASONS.has(reason)) return false;
	const info = HOLD_REASONS[reason];
	await notifyOwner(userId, 'creator_payout_held', {
		agent_id: agentId,
		agent_name: agentName,
		reason,
		message: `${solFromLamports(lamports)} SOL of creator fees for ${agentName || 'your agent'} is held: ${info?.label || reason}. ${info?.fix || ''}`.trim(),
		link: `/creator/payouts?agent=${agentId}`,
	});
	return true;
}

/**
 * One distribution pass. Idempotent: ingest is keyed by claim, the send locks its
 * batch with a status transition, so a re-run (or a second runner) cannot pay a
 * claim twice.
 * @param {{ live?: boolean, now?: number, send?: typeof sendFromAgentWallet }} [opts]
 */
export async function runDistribution({ live = payoutsLive(), now = Date.now(), send = sendFromAgentWallet } = {}) {
	const out = { ingested: 0, agents: 0, sent_batches: 0, sent_sol: 0, held_agents: 0, failed: [], promoted: 0 };
	out.promoted = (await promoteDueWallets()).length;
	out.ingested = await ingestClaims();

	const agents = await sql`
		SELECT d.agent_id, ai.user_id, ai.name, ai.meta->>'solana_address' AS solana_address,
		       ai.meta->>'encrypted_solana_secret' AS secret,
		       sum(d.creator_lamports)::text AS unsent
		FROM creator_payout_distributions d
		JOIN agent_identities ai ON ai.id = d.agent_id AND ai.deleted_at IS NULL
		WHERE d.status IN ('pending', 'held') AND d.network = 'mainnet'
		GROUP BY d.agent_id, ai.user_id, ai.name, ai.meta
		LIMIT 200`;
	out.agents = agents.length;

	for (const a of agents) {
		try {
			const [w] = await sql`SELECT * FROM creator_payout_wallets WHERE agent_id = ${a.agent_id}`;
			const unsent = BigInt(a.unsent);
			const reason = holdReason({
				activeWallet: w?.wallet || null,
				pendingWallet: w?.pending_wallet || null,
				pendingEffectiveAt: w?.pending_effective_at || null,
				unsentLamports: unsent,
				live,
				now,
			});
			if (reason) {
				await holdRows(a.agent_id, reason);
				await maybeNotifyHeld(a.agent_id, a.user_id, a.name, reason, unsent);
				out.held_agents++;
				continue;
			}
			if (!a.solana_address || !a.secret) {
				await holdRows(a.agent_id, 'signing_unavailable');
				await maybeNotifyHeld(a.agent_id, a.user_id, a.name, 'signing_unavailable', unsent);
				out.held_agents++;
				continue;
			}

			const batchId = (await sql`SELECT gen_random_uuid() AS id`)[0].id;
			const locked = await sql`
				UPDATE creator_payout_distributions
				SET status = 'sending', batch_id = ${batchId}, payout_wallet = ${w.wallet}, hold_reason = NULL, updated_at = now()
				WHERE agent_id = ${a.agent_id} AND status IN ('pending', 'held') AND network = 'mainnet'
				RETURNING creator_lamports::text AS creator_lamports`;
			const total = locked.reduce((s, r) => s + BigInt(r.creator_lamports), 0n);
			if (total === 0n) continue;

			let sent;
			try {
				sent = await send({ agentId: a.agent_id, userId: a.user_id, fromSecret: a.secret, fromAddress: a.solana_address, to: w.wallet, lamports: total, batchId });
			} catch (err) {
				const code = err?.code === 'agent_wallet_low' ? 'agent_wallet_low' : 'signing_unavailable';
				await sql`
					UPDATE creator_payout_distributions
					SET status = 'held', hold_reason = ${code}, batch_id = NULL, payout_wallet = NULL, updated_at = now()
					WHERE batch_id = ${batchId} AND status = 'sending'`;
				await maybeNotifyHeld(a.agent_id, a.user_id, a.name, code, total);
				if (code === 'signing_unavailable') out.failed.push({ agent_id: a.agent_id, error: String(err?.message || err).slice(0, 200) });
				out.held_agents++;
				continue;
			}

			// Broadcast: record the signature before waiting, so a confirmation that
			// never returns is resolved by the reconcile job instead of re-sent.
			await sql`UPDATE creator_payout_distributions SET tx_signature = ${sent.signature}, updated_at = now() WHERE batch_id = ${batchId}`;
			try {
				if (sent.conn) {
					const res = await sent.conn.confirmTransaction(
						{ signature: sent.signature, blockhash: sent.blockhash, lastValidBlockHeight: sent.lastValidBlockHeight },
						'confirmed',
					);
					if (res?.value?.err) throw new Error(`transfer failed on-chain: ${JSON.stringify(res.value.err)}`);
				}
			} catch (err) {
				out.failed.push({ agent_id: a.agent_id, signature: sent.signature, error: String(err?.message || err).slice(0, 200) });
				await sendOpsAlert('Creator payout confirmation unresolved', `agent ${a.agent_id} batch ${batchId} signature ${sent.signature}: ${err?.message || err}. The reconcile job resolves it.`, { severity: 'warning' }).catch(() => {});
				continue;
			}
			await markBatchSent(batchId);
			await sql`UPDATE creator_payout_state SET last_held_reason = NULL WHERE agent_id = ${a.agent_id}`;
			out.sent_batches++;
			out.sent_sol += sol(total);
			await notifyOwner(a.user_id, 'creator_payout_sent', {
				agent_id: a.agent_id,
				agent_name: a.name,
				sol: sol(total),
				signature: sent.signature,
				message: `${solFromLamports(total)} SOL of creator fees from ${a.name || 'your agent'} was sent to your payout wallet.`,
				link: `/creator/payouts?agent=${a.agent_id}`,
			});
		} catch (err) {
			out.failed.push({ agent_id: a.agent_id, error: String(err?.message || err).slice(0, 200) });
		}
	}
	return out;
}

async function markBatchSent(batchId) {
	await sql`
		UPDATE creator_payout_distributions
		SET status = 'sent', hold_reason = NULL, sent_at = now(), updated_at = now()
		WHERE batch_id = ${batchId} AND status = 'sending'`;
}

// ── Reconcile ────────────────────────────────────────────────────────────────

/**
 * Compare what we recorded with the chain, and alert on drift:
 *  - sending batches that never resolved: confirmed on-chain becomes sent, a
 *    transfer the cluster never saw is returned to pending, anything else alerts;
 *  - every recently sent signature must exist on-chain without error;
 *  - each agent's pump.fun vault balance on-chain against the unclaimed figure in
 *    the last earnings snapshot (drift beyond tolerance alerts: fees accrue
 *    between snapshots, so only a vault far BELOW what we recorded is drift).
 * Read-only on the chain.
 * @param {{ connection?: any, now?: number }} [opts]
 */
export async function reconcilePayouts({ connection = null, now = Date.now() } = {}) {
	const drift = [];
	const checked = { stuck_batches: 0, sent_signatures: 0, vaults: 0 };
	const { getConnection } = await import('./pump.js');
	const conn = connection || getConnection({ network: 'mainnet' });

	const stuck = await sql`
		SELECT batch_id, agent_id, min(tx_signature) AS sig, sum(creator_lamports)::text AS lamports
		FROM creator_payout_distributions
		WHERE status = 'sending' AND updated_at < ${new Date(now - STUCK_SENDING_MS).toISOString()}
		GROUP BY batch_id, agent_id`;
	for (const b of stuck) {
		checked.stuck_batches++;
		if (!b.sig) {
			await sql`UPDATE creator_payout_distributions SET status = 'pending', batch_id = NULL, payout_wallet = NULL, updated_at = now() WHERE batch_id = ${b.batch_id} AND status = 'sending'`;
			continue;
		}
		const st = (await conn.getSignatureStatuses([b.sig], { searchTransactionHistory: true }).catch(() => null))?.value?.[0];
		if (st && !st.err && (st.confirmationStatus === 'confirmed' || st.confirmationStatus === 'finalized')) {
			await markBatchSent(b.batch_id);
		} else if (!st) {
			await sql`UPDATE creator_payout_distributions SET status = 'pending', batch_id = NULL, tx_signature = NULL, payout_wallet = NULL, updated_at = now() WHERE batch_id = ${b.batch_id} AND status = 'sending'`;
		} else {
			drift.push({ kind: 'transfer_failed', agent_id: b.agent_id, signature: b.sig, lamports: b.lamports, detail: st.err ? JSON.stringify(st.err) : st.confirmationStatus });
		}
	}

	const sentSigs = await sql`
		SELECT tx_signature AS sig, agent_id, sum(creator_lamports)::text AS lamports, max(payout_wallet) AS wallet
		FROM creator_payout_distributions
		WHERE status = 'sent' AND tx_signature IS NOT NULL AND sent_at > ${new Date(now - 72 * 3_600_000).toISOString()}
		GROUP BY tx_signature, agent_id
		LIMIT 100`;
	for (const s of sentSigs) {
		checked.sent_signatures++;
		const st = (await conn.getSignatureStatuses([s.sig], { searchTransactionHistory: true }).catch(() => null))?.value?.[0];
		if (!st) drift.push({ kind: 'sent_signature_missing', agent_id: s.agent_id, signature: s.sig, lamports: s.lamports });
		else if (st.err) drift.push({ kind: 'sent_signature_failed', agent_id: s.agent_id, signature: s.sig, lamports: s.lamports, detail: JSON.stringify(st.err) });
	}

	const vaults = await sql`
		SELECT e.creator AS wallet, max(e.unclaimed_lamports)::text AS recorded_unclaimed, max(e.refreshed_at) AS refreshed_at
		FROM agent_coin_earnings e
		WHERE e.network = 'mainnet' AND e.source = 'pumpfun_creator_fees' AND e.creator IS NOT NULL AND e.unclaimed_lamports IS NOT NULL
		GROUP BY e.creator
		HAVING max(e.unclaimed_lamports) > 0
		ORDER BY max(e.refreshed_at) DESC
		LIMIT 40`;
	const { readUnclaimedLamports } = await import('./pump-creator-fees.js');
	for (const v of vaults) {
		const onchain = await readUnclaimedLamports(conn, v.wallet);
		if (onchain == null) continue;
		checked.vaults++;
		const recorded = BigInt(v.recorded_unclaimed);
		// Fees accrue between snapshots, so a vault above the record is expected.
		// A vault well below it means fees left without our claim path recording them.
		const shortfall = recorded - onchain;
		const tolerance = recorded / 20n + 1_000_000n;
		if (shortfall > tolerance) {
			drift.push({ kind: 'vault_below_record', wallet: v.wallet, recorded_lamports: recorded.toString(), onchain_lamports: onchain.toString(), shortfall_lamports: shortfall.toString() });
		}
	}

	const ok = drift.length === 0;
	await sql`INSERT INTO creator_payout_reconcile_runs (ok, checked, drift) VALUES (${ok}, ${JSON.stringify(checked)}::jsonb, ${JSON.stringify(drift)}::jsonb)`;
	if (!ok) {
		await sendOpsAlert(
			`Creator payout drift: ${drift.length} item${drift.length === 1 ? '' : 's'}`,
			drift.slice(0, 10).map((d) => `${d.kind} ${d.agent_id || d.wallet || ''} ${d.signature || ''}`.trim()).join('\n'),
			{ severity: 'critical', signature: `creator-payout-drift:${drift.map((d) => d.kind).sort().join(',')}` },
		).catch(() => {});
	}
	return { ok, checked, drift };
}