Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
feat(payouts): add the creator-fee payout module the API and crons import, with a payout_wallet step-up grant bound to agent and wallet
nirholasf55b9d6d1ac6
diff --git a/api/_lib/creator-payouts.js b/api/_lib/creator-payouts.jsnew file mode 100644index 000000000..36aa86394--- /dev/null+++ b/api/_lib/creator-payouts.js@@ -0,0 +1,542 @@+// 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 };+}diff --git a/api/_lib/destination-whitelist.js b/api/_lib/destination-whitelist.jsindex d803c66f0..fb751434f 100644--- a/api/_lib/destination-whitelist.js+++ b/api/_lib/destination-whitelist.js@@ -242,6 +242,13 @@ export function buildOp(kind, agentId, body = {}) {cs: 'cooldown_seconds' in body ? Number(body.cooldown_seconds) : undefined,en: 'enforced' in body ? body.enforced === true : undefined,};+ case 'payout_wallet': {+ // Creator-fee payout destination (api/_lib/creator-payouts.js): the grant is+ // bound to this agent and this exact wallet.+ const norm = normalizeDestination(body.wallet);+ if (!norm || norm.chain !== 'solana') throw new WhitelistError(400, 'invalid_address', 'That is not a valid Solana address.');+ return { t: 'payout_wallet', a: agentId, w: norm.key };+ }case 'set_list': {const list = Array.isArray(body.withdraw_allowlist) ? body.withdraw_allowlist : [];const keys = list.map((x) => {@@ -353,7 +360,7 @@ export async function mintStepUp({ actor, agentId, op, method, proof = {} }) {}/** Spend a grant. One use, this session, this user, this agent, this exact operation. */-async function consumeGrant({ grantId, actor, agentId, op }) {+export async function consumeGrant({ grantId, actor, agentId, op }) {const opHash = hashOp(op);if (typeof grantId === 'string' && /^[0-9a-f-]{36}$/i.test(grantId) && actor?.sessionId) {const [row] = await sql`