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.

21.9 KB
Raw Blame
// Wallet-funded credit top-ups: an agent pays for its own inference.
//
// Moves USDC from an agent's custodial Solana wallet to the platform treasury
// and credits the owner's account at the published rate (USDC_CREDIT_RATE, no
// fee). The transfer is a standard x402 `exact` payment: the agent wallet signs
// one USDC TransferChecked to the treasury, and the in-house self-facilitator
// (api/_lib/x402/self-facilitator.js) validates it, co-signs as fee payer and
// broadcasts it. The agent therefore needs USDC only, never SOL for fees, and
// no third party touches the settlement.
//
// Every top-up is guarded exactly like any other outbound agent spend:
//   • reserveSpendUsd() claims a pending custody row under the agent's per-tx
//     and daily ceilings, the natural-language policy, the kill switch and the
//     behavioural anomaly freeze, BEFORE the key is touched;
//   • the custody row is finalized with the on-chain signature, so the top-up
//     appears in the owner's audit feed and counts toward the daily cap;
//   • the credit_ledger 'deposit' row carries the same signature, and is
//     idempotent on the top-up id, so a retry never credits twice.
//
// Owner and provisioning flows are two-step: previewTopup() writes a
// single-use preview (recipient, amount, token, chain, credits) that expires in
// ten minutes, and executeTopup() requires `confirm_deposit: true` plus that
// fresh preview_id. An armed wallet intent (source 'intent') is itself the
// owner's standing authorization and calls topupFromIntent() directly.

import { PublicKey } from '@solana/web3.js';
import { getAssociatedTokenAddressSync, TOKEN_PROGRAM_ID } from '@solana/spl-token';

import { sql } from './db.js';
import { env } from './env.js';
import { creditAccount, getCreditAccount } from './credits.js';
import { USDC_CREDIT_RATE } from './pricing/catalog.js';
import { getSolanaAddressBalances, recoverSolanaAgentKeypair } from './agent-wallet.js';
import {
	enforceSpendLimit,
	reserveSpendUsd,
	releaseSpendReservation,
	updateCustodyEvent,
	SpendLimitError,
} from './agent-trade-guards.js';
import { NETWORK_SOLANA_MAINNET } from './x402/solana-networks.js';
import { bootstrapSolanaContext, buildPaymentTx, nextAutoNonce } from './x402/pay.js';
import { loadFeePayerKeypair, settleRingPayment } from './x402/self-facilitator.js';
import { facilitatorFeeMeter, recordSettledFee } from './x402/wallet-fee-meter.js';
import { claimSettleCredit } from './x402/settle-credit.js';
import { PENDING_SCOPE_FACILITATOR, SqlPendingSettlementStore } from './x402/pending-settlements.js';
import { insertNotification } from './notify.js';
import { logAudit } from './audit.js';

export const TOPUP_MIN_USDC = 0.1;
export const TOPUP_MAX_USDC = 1000;
export const PREVIEW_TTL_MINUTES = 10;
export const CUSTODY_CATEGORY = 'inference_topup';

const USDC_DECIMALS = 6;

export class TopupError extends Error {
	constructor(status, code, message, detail = {}) {
		super(message);
		this.status = status;
		this.code = code;
		this.detail = detail;
		this.expose = true;
	}
}

/** Validate and normalize a USDC amount to 6 decimals. */
export function normalizeTopupAmount(raw) {
	const n = Number(raw);
	if (!Number.isFinite(n) || n <= 0) {
		throw new TopupError(400, 'validation_error', 'amount_usdc must be a positive number');
	}
	const rounded = Math.floor(n * 10 ** USDC_DECIMALS) / 10 ** USDC_DECIMALS;
	if (rounded < TOPUP_MIN_USDC) {
		throw new TopupError(400, 'validation_error', `the smallest top-up is ${TOPUP_MIN_USDC} USDC`);
	}
	if (rounded > TOPUP_MAX_USDC) {
		throw new TopupError(400, 'validation_error', `the largest single top-up is ${TOPUP_MAX_USDC} USDC`);
	}
	return rounded;
}

/** Credits a top-up buys at the published rate. No fee is taken. */
export function creditsForUsdc(amountUsdc) {
	return Math.floor(Number(amountUsdc) * USDC_CREDIT_RATE * 1e6) / 1e6;
}

function treasuryAddress() {
	const addr = env.X402_PAY_TO_SOLANA;
	if (!addr) {
		throw new TopupError(503, 'treasury_unconfigured', 'Wallet top-ups are unavailable: the platform treasury address is not configured.');
	}
	return addr;
}

function usdcMint() {
	const mint = env.X402_ASSET_MINT_SOLANA;
	if (!mint) {
		throw new TopupError(503, 'usdc_unconfigured', 'Wallet top-ups are unavailable: the USDC mint is not configured.');
	}
	return mint;
}

/** The sponsor fee payer, or null when this deployment has none (self-pay). */
function sponsorOrNull() {
	try {
		return loadFeePayerKeypair();
	} catch {
		return null;
	}
}

async function loadOwnedAgent(agentId, userId) {
	const [row] = await sql`
		SELECT id, user_id, name, meta FROM agent_identities
		WHERE id = ${agentId} AND deleted_at IS NULL
	`;
	if (!row) throw new TopupError(404, 'not_found', 'agent not found');
	if (String(row.user_id) !== String(userId)) throw new TopupError(403, 'forbidden', 'not your agent');
	const meta = row.meta || {};
	if (!meta.solana_address || !meta.encrypted_solana_secret) {
		throw new TopupError(409, 'wallet_not_ready', 'This agent has no signable Solana wallet yet. Open its wallet page to provision one.');
	}
	return { ...row, meta };
}

function spendLimitToTopupError(e) {
	return new TopupError(403, e.code || 'spend_limit', e.message, e.detail || {});
}

async function checkTopupPolicy({ agent, userId, amount, payTo }) {
	try {
		await enforceSpendLimit({
			agentId: agent.id,
			meta: agent.meta,
			userId,
			category: CUSTODY_CATEGORY,
			usdValue: amount,
			asset: 'USDC',
			destination: payTo,
			destinationTrust: 'system',
		});
	} catch (e) {
		if (e instanceof SpendLimitError) throw spendLimitToTopupError(e);
		throw e;
	}
}

// ── quote and preview ───────────────────────────────────────────────────────

/**
 * Price a wallet-funded top-up without writing anything: reads the agent
 * wallet from Solana, runs the owner's spend policy against it, and returns
 * the confirmation table. previewTopup() is this plus the single-use preview
 * row; a dry run (scripts/inference-topup-dryrun.mjs) calls it directly.
 * `checkPolicy: false` skips the spend-policy pass, whose anomaly guard can
 * record an event or freeze the wallet: a dry run must write nothing.
 * @returns {Promise<object>} the confirmation table (no preview_id)
 */
export async function quoteTopup({ userId, agentId, amountUsdc, checkPolicy = true }) {
	const amount = normalizeTopupAmount(amountUsdc);
	const agent = await loadOwnedAgent(agentId, userId);
	const payTo = treasuryAddress();
	const mint = usdcMint();

	const balances = await getSolanaAddressBalances(agent.meta.solana_address, 'mainnet');
	if (balances.usdc == null) {
		throw new TopupError(503, 'rpc_unavailable', 'Could not read the agent wallet balance from Solana. Retry in a moment.');
	}
	if (balances.usdc + 1e-9 < amount) {
		throw new TopupError(402, 'insufficient_usdc', `The agent wallet holds ${balances.usdc} USDC, less than the ${amount} USDC requested. Fund the wallet first.`, {
			wallet_usdc: balances.usdc,
			requested_usdc: amount,
			deposit_address: agent.meta.solana_address,
		});
	}

	// Fail fast on the owner's own policy (freeze, per-tx cap, English rules)
	// so a preview never shows a top-up the guard would refuse. The binding
	// check is the atomic reserve at execution time.
	if (checkPolicy) await checkTopupPolicy({ agent, userId, amount, payTo });

	const sponsor = sponsorOrNull();
	if (!sponsor && !(balances.sol > 0.00001)) {
		throw new TopupError(409, 'no_fee_payer', 'The agent wallet needs a little SOL (0.00001) to pay the network fee on this deployment.');
	}

	const credits = creditsForUsdc(amount);
	const acct = await getCreditAccount(userId);
	return {
		confirm_flag: 'confirm_deposit',
		agent: { id: agent.id, name: agent.name },
		from: agent.meta.solana_address,
		to: payTo,
		to_label: 'three.ws treasury',
		token: 'USDC',
		mint,
		chain: 'solana',
		network: 'mainnet',
		amount_usdc: amount,
		rate: USDC_CREDIT_RATE,
		fee_usd: 0,
		credits_usd: credits,
		network_fee: sponsor ? 'paid by three.ws' : 'about 0.000005 SOL from the agent wallet',
		wallet_usdc_before: balances.usdc,
		wallet_usdc_after: Math.round((balances.usdc - amount) * 1e6) / 1e6,
		balance_before_usd: acct.balanceUsd,
		balance_after_usd: Math.round((acct.balanceUsd + credits) * 1e6) / 1e6,
		policy_checked: checkPolicy,
	};
}

/**
 * Write a single-use preview of a wallet-funded top-up. Nothing moves.
 * @returns {Promise<object>} the confirmation table the owner must approve
 */
export async function previewTopup({ userId, agentId, amountUsdc, source = 'owner' }) {
	const quote = await quoteTopup({ userId, agentId, amountUsdc });
	const [row] = await sql`
		INSERT INTO inference_topups
			(user_id, agent_id, source, status, amount_usdc, credits_usd, payer_address, pay_to, network, expires_at)
		VALUES
			(${userId}, ${quote.agent.id}, ${source}, 'previewed', ${quote.amount_usdc.toFixed(6)}, ${quote.credits_usd.toFixed(6)},
			 ${quote.from}, ${quote.to}, 'mainnet', now() + make_interval(mins => ${PREVIEW_TTL_MINUTES}))
		RETURNING id, expires_at
	`;
	return { preview_id: row.id, expires_at: row.expires_at, ...quote };
}

// ── execute ─────────────────────────────────────────────────────────────────

function rowResult(row, extra = {}) {
	return {
		topup_id: row.id,
		status: row.status,
		agent_id: row.agent_id,
		amount_usdc: Number(row.amount_usdc),
		credits_usd: Number(row.credits_usd),
		signature: row.signature || null,
		explorer_url: row.signature ? `https://solscan.io/tx/${row.signature}` : null,
		api_key_id: row.api_key_id || null,
		...extra,
	};
}

/**
 * Execute a previewed top-up. Requires `confirmDeposit === true` and a fresh,
 * unused preview owned by the caller (and, when `agentId` is given, previewed
 * for that agent). Retrying a settled or pending preview is
 * safe: it returns the recorded result or reconciles the recorded signature.
 */
export async function executeTopup({ userId, previewId, confirmDeposit, sources = ['owner'], agentId = null }) {
	if (confirmDeposit !== true) {
		throw new TopupError(400, 'confirm_required', 'Moving funds needs confirm_deposit: true together with a preview_id from the matching /preview call. Show the preview to the owner first.');
	}
	if (!previewId) {
		throw new TopupError(400, 'preview_required', 'preview_id is required: call the matching /preview route first.');
	}
	const [row] = await sql`SELECT * FROM inference_topups WHERE id = ${previewId} AND user_id = ${userId}`;
	if (!row || !sources.includes(row.source)) {
		throw new TopupError(404, 'preview_not_found', 'No preview with that id belongs to this account. Create a new one with /preview.');
	}
	// A route scoped to one agent refuses another agent's preview before
	// anything moves, never after.
	if (agentId && String(row.agent_id) !== String(agentId)) {
		throw new TopupError(409, 'agent_mismatch', 'That preview belongs to a different agent. Create a new one for this agent with /preview.');
	}
	if (row.status === 'settled') return rowResult(row, { replay: true });
	if (row.status === 'pending') return reconcileTopup(row);
	if (row.status === 'failed' || row.status === 'expired') {
		throw new TopupError(409, 'preview_used', `This preview already ${row.status === 'failed' ? `failed (${row.error || 'settlement failed'})` : 'expired'}. Create a new one with /preview.`);
	}
	if (row.status === 'executing') {
		throw new TopupError(409, 'in_flight', 'This top-up is already being settled. Retry in a few seconds to read its result.');
	}

	const [claimed] = await sql`
		UPDATE inference_topups SET status = 'executing', executed_at = now()
		WHERE id = ${previewId} AND status = 'previewed' AND expires_at > now()
		RETURNING *
	`;
	if (!claimed) {
		await sql`UPDATE inference_topups SET status = 'expired' WHERE id = ${previewId} AND status = 'previewed' AND expires_at <= now()`;
		throw new TopupError(410, 'preview_expired', `Previews are valid for ${PREVIEW_TTL_MINUTES} minutes. Create a new one with /preview and confirm it.`);
	}
	return runTopup(claimed);
}

/**
 * Fire a top-up from an armed wallet intent. Idempotent per `idempotencyKey`,
 * which the intent engine derives from the rule and its window, so a rule
 * tops up at most once per window however often the sweep runs.
 */
export async function topupFromIntent({ agentId, ownerId, amountUsdc, intentId, idempotencyKey }) {
	const amount = normalizeTopupAmount(amountUsdc);
	const agent = await loadOwnedAgent(agentId, ownerId);
	const payTo = treasuryAddress();
	const credits = creditsForUsdc(amount);
	const [row] = await sql`
		INSERT INTO inference_topups
			(user_id, agent_id, source, status, amount_usdc, credits_usd, payer_address, pay_to,
			 network, intent_id, idempotency_key, executed_at)
		VALUES
			(${ownerId}, ${agent.id}, 'intent', 'executing', ${amount.toFixed(6)}, ${credits.toFixed(6)},
			 ${agent.meta.solana_address}, ${payTo}, 'mainnet', ${intentId}, ${idempotencyKey}, now())
		ON CONFLICT (idempotency_key) WHERE idempotency_key IS NOT NULL DO NOTHING
		RETURNING *
	`;
	if (!row) return { status: 'skipped', note: 'already topped up in this window' };
	return runTopup(row);
}

async function markFailed(id, reason) {
	await sql`UPDATE inference_topups SET status = 'failed', error = ${String(reason).slice(0, 300)} WHERE id = ${id}`;
}

async function treasuryAtaExists(conn, payTo, mint) {
	const ata = getAssociatedTokenAddressSync(new PublicKey(mint), new PublicKey(payTo), false, TOKEN_PROGRAM_ID);
	const info = await conn.getAccountInfo(ata, 'confirmed');
	return info != null;
}

/** Reserve, sign, settle through the self-facilitator, then credit. */
async function runTopup(row) {
	const agent = await loadOwnedAgent(row.agent_id, row.user_id).catch(async (e) => {
		await markFailed(row.id, e.message);
		throw e;
	});
	const amount = Number(row.amount_usdc);
	const atomics = BigInt(Math.round(amount * 10 ** USDC_DECIMALS));
	const idem = `inference_topup:${row.id}`;

	let reservationId;
	try {
		const reservation = await reserveSpendUsd({
			agentId: agent.id,
			userId: row.user_id,
			meta: agent.meta,
			category: CUSTODY_CATEGORY,
			usdValue: amount,
			destination: row.pay_to,
			destinationTrust: 'system',
			asset: 'USDC',
			rowMeta: {
				topup_id: row.id,
				source: row.source,
				credits_usd: Number(row.credits_usd),
				...(row.intent_id ? { intent_id: row.intent_id } : {}),
			},
		});
		reservationId = reservation.reservationId;
	} catch (e) {
		if (e instanceof SpendLimitError) {
			await markFailed(row.id, e.message);
			throw spendLimitToTopupError(e);
		}
		await markFailed(row.id, e?.message || 'reserve failed');
		throw e;
	}
	await sql`
		UPDATE agent_custody_events SET idempotency_key = ${idem}, amount_raw = ${atomics.toString()}
		WHERE id = ${reservationId} AND idempotency_key IS NULL
	`;
	await sql`UPDATE inference_topups SET custody_event_id = ${reservationId} WHERE id = ${row.id}`;

	const fail = async (code, message, status = 502) => {
		await releaseSpendReservation(reservationId, code);
		await markFailed(row.id, message);
		throw new TopupError(status, code, message);
	};

	let keypair;
	try {
		keypair = await recoverSolanaAgentKeypair(agent.meta.encrypted_solana_secret, {
			agentId: agent.id,
			userId: row.user_id,
			reason: CUSTODY_CATEGORY,
			meta: { topup_id: row.id, usdc: amount, to: row.pay_to },
		});
	} catch {
		return fail('key_recover_failed', 'The agent wallet key could not be recovered, so nothing was signed.', 500);
	}
	if (keypair.publicKey.toBase58() !== row.payer_address) {
		return fail('wallet_changed', 'The agent wallet changed after this top-up was previewed. Nothing was signed; preview again.', 409);
	}

	const sponsor = sponsorOrNull();
	let settled;
	let requirement;
	try {
		const { conn, blockhash, mintInfo } = await bootstrapSolanaContext({ buyer: keypair });
		requirement = {
			scheme: 'exact',
			network: NETWORK_SOLANA_MAINNET,
			asset: usdcMint(),
			payTo: row.pay_to,
			amount: atomics.toString(),
			extra: sponsor ? { feePayer: sponsor.publicKey.toBase58() } : {},
		};
		const receiverAtaExists = await treasuryAtaExists(conn, row.pay_to, requirement.asset);
		const transaction = buildPaymentTx({
			accept: requirement,
			buyer: keypair,
			blockhash,
			mintInfo,
			receiverAtaExists,
			nonce: nextAutoNonce(),
			selfPay: !sponsor,
		});
		settled = await settleRingPayment({
			paymentPayload: { x402Version: 2, payload: { transaction } },
			requirement,
			conn,
			feePayer: sponsor || undefined,
			feeMeter: facilitatorFeeMeter(),
			pendingStore: new SqlPendingSettlementStore({ scope: PENDING_SCOPE_FACILITATOR }),
			idempotencyKey: idem,
		});
	} catch (e) {
		return fail('settle_failed', `The transfer could not be settled: ${String(e?.message || e).slice(0, 200)}`);
	}

	if (!settled.success && settled.pending && settled.transaction) {
		await updateCustodyEvent(reservationId, { signature: settled.transaction, meta: { confirm: 'pending' } });
		const [p] = await sql`
			UPDATE inference_topups SET status = 'pending', signature = ${settled.transaction}
			WHERE id = ${row.id} RETURNING *
		`;
		return rowResult(p, { note: 'Broadcast, waiting for Solana to confirm. Retry the same call to read the result.' });
	}
	if (!settled.success) {
		return fail('settle_failed', `The self-facilitator refused the transfer: ${settled.reason || 'unknown reason'}. Nothing moved.`);
	}

	const credit = await claimSettleCredit({
		sql,
		row: {
			network: requirement.network,
			payer: settled.payer,
			payTo: requirement.payTo,
			mint: requirement.asset,
			amountAtomic: Number(requirement.amount),
			txSig: settled.transaction,
			feeLamports: settled.feeLamports,
			idempotencyKey: idem,
			feePayer: settled.feePayer,
		},
	});
	if (!credit.granted && !credit.idempotentReplay) {
		await updateCustodyEvent(reservationId, { status: 'failed', signature: settled.transaction, meta: { refused: credit.reason } });
		await markFailed(row.id, `settlement signature refused: ${credit.reason}`);
		throw new TopupError(409, 'settle_refused', `The settlement could not be attributed to this top-up (${credit.reason}). Contact support with signature ${settled.transaction}.`);
	}
	if (credit.granted) recordSettledFee(settled.feePayer, settled.feeLamports);

	return finalizeSettled({ ...row, custody_event_id: reservationId }, settled.transaction);
}

/** Book a confirmed transfer: custody row, credit ledger, top-up row, owner notice. */
async function finalizeSettled(row, signature) {
	if (row.custody_event_id) {
		await updateCustodyEvent(row.custody_event_id, {
			status: 'confirmed',
			signature,
			usd: Number(row.amount_usdc),
		});
	}
	const credited = await creditAccount({
		userId: row.user_id,
		amountUsd: Number(row.credits_usd),
		kind: 'deposit',
		action: 'inference.topup',
		refType: 'agent_wallet_topup',
		refId: String(row.agent_id),
		txSignature: signature,
		asset: 'USDC',
		assetAmount: BigInt(Math.round(Number(row.amount_usdc) * 10 ** USDC_DECIMALS)).toString(),
		priceUsd: USDC_CREDIT_RATE,
		idempotencyKey: `inference_topup:${row.id}`,
		meta: { topup_id: row.id, agent_id: row.agent_id, source: row.source },
	});
	const [done] = await sql`
		UPDATE inference_topups
		SET status = 'settled', signature = ${signature}, ledger_id = ${credited.ledgerId}, settled_at = now(), error = NULL
		WHERE id = ${row.id}
		RETURNING *
	`;
	if (!credited.replay) {
		insertNotification(row.user_id, 'inference_topup', {
			agent_id: row.agent_id,
			amount_usdc: Number(row.amount_usdc),
			credits_usd: Number(row.credits_usd),
			signature,
			source: row.source,
			link: `/agents/${row.agent_id}/wallet#credits`,
		});
		logAudit({
			userId: row.user_id,
			action: 'inference.topup',
			resourceId: row.agent_id,
			meta: { topup_id: row.id, usdc: Number(row.amount_usdc), credits_usd: Number(row.credits_usd), signature, source: row.source },
		});
	}
	return rowResult(done, { balance_usd: credited.balanceUsd });
}

/**
 * Settle the outcome of a top-up whose broadcast was not yet confirmed. Reads
 * the recorded signature from chain: landed credits the account, reverted
 * releases the reservation, unknown stays pending for the next read.
 */
export async function reconcileTopup(row) {
	if (!row.signature) return rowResult(row);
	const { solanaConnection } = await import('./solana/connection.js');
	const conn = solanaConnection({ url: env.SOLANA_RPC_URL, commitment: 'confirmed' });
	let status = null;
	try {
		status = (await conn.getSignatureStatuses([row.signature], { searchTransactionHistory: true }))?.value?.[0] || null;
	} catch {
		return rowResult(row, { note: 'Solana did not answer; still pending. Retry shortly.' });
	}
	if (status && status.err == null && ['confirmed', 'finalized'].includes(status.confirmationStatus)) {
		return finalizeSettled(row, row.signature);
	}
	if (status && status.err != null) {
		if (row.custody_event_id) await releaseSpendReservation(row.custody_event_id, 'reverted');
		await markFailed(row.id, 'the transfer reverted on chain; nothing moved');
		const [failed] = await sql`SELECT * FROM inference_topups WHERE id = ${row.id}`;
		return rowResult(failed);
	}
	const ageMs = Date.now() - new Date(row.executed_at || row.created_at).getTime();
	if (!status && ageMs > 5 * 60_000) {
		if (row.custody_event_id) await releaseSpendReservation(row.custody_event_id, 'dropped');
		await markFailed(row.id, 'the transfer never landed (blockhash expired); nothing moved');
		const [failed] = await sql`SELECT * FROM inference_topups WHERE id = ${row.id}`;
		return rowResult(failed);
	}
	return rowResult(row, { note: 'Broadcast, waiting for Solana to confirm.' });
}

/** Reconcile every pending top-up for one account (called from the usage read). */
export async function reconcilePendingTopups(userId) {
	const rows = await sql`
		SELECT * FROM inference_topups
		WHERE user_id = ${userId} AND status = 'pending' AND signature IS NOT NULL
		ORDER BY created_at ASC LIMIT 5
	`;
	for (const row of rows) {
		await reconcileTopup(row).catch((err) => console.warn('[inference-topup] reconcile failed', row.id, err?.message));
	}
}