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.

16.8 KB
Raw Blame
// On-chain verification + settlement + audit for the $THREE token layer.
//
// Flow (server-authoritative — a client "paid" claim is never trusted):
//   1. verifyQuote()   — quote untampered + unexpired
//   2. nonce-unused    — fast reject of a replayed quote before any RPC
//   3. verifyOnChain() — tx confirmed, memo == nonce, each split leg credited
//   4. settlePayment() — record with UNIQUE(nonce) + UNIQUE(tx_signature); a
//                        duplicate insert is a replay/double-submit, surfaced
//                        as already_settled rather than crediting twice.

import { solanaConnection } from '../solana/connection.js';
import { sql } from '../db.js';
import { env } from '../env.js';
import { verifyQuote } from './quote.js';

const MEMO_PROGRAM = 'MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr';

function rpcUrl(network) {
	return network === 'devnet'
		? env.SOLANA_RPC_URL_DEVNET || 'https://api.devnet.solana.com'
		: env.SOLANA_RPC_URL || 'https://api.mainnet-beta.solana.com';
}

function verifyError(message, status = 422, code = 'verification_failed', extra = {}) {
	return Object.assign(new Error(message), { status, code, ...extra });
}

// Net atomics credited to an owner across all of its token accounts for `mint`,
// computed from pre/post token balances. Robust to which transfer variant was
// used and to the destination ATA being created within the same transaction
// (it simply has no pre-balance entry). Works uniformly for the burn address,
// treasury, and a marketplace seller.
function creditedTo(tx, { mint, ownerAddress }) {
	const pre = tx.meta?.preTokenBalances || [];
	const post = tx.meta?.postTokenBalances || [];
	let delta = 0n;
	for (const p of post) {
		if (p.mint !== mint || p.owner !== ownerAddress) continue;
		const before = pre.find((x) => x.accountIndex === p.accountIndex);
		const beforeAmt = BigInt(before?.uiTokenAmount?.amount ?? '0');
		const afterAmt = BigInt(p.uiTokenAmount?.amount ?? '0');
		delta += afterAmt - beforeAmt;
	}
	return delta;
}

/**
 * Verify the on-chain transaction satisfies the quote.
 * @returns {Promise<{ confirmedAt: string, slot: number|null, credited: object }>}
 */
export async function verifyOnChain({ quote, txSignature, network = 'mainnet' }) {
	const connection = solanaConnection({ url: rpcUrl(network), commitment: 'confirmed' });
	let tx;
	try {
		tx = await connection.getParsedTransaction(txSignature, {
			maxSupportedTransactionVersion: 1,
			commitment: 'confirmed',
		});
	} catch {
		throw verifyError(
			'transaction not found — may need more confirmations',
			422,
			'tx_not_found',
		);
	}
	if (!tx) throw verifyError('transaction not found', 422, 'tx_not_found');
	if (tx.meta?.err) throw verifyError('transaction failed on-chain', 422, 'tx_failed');

	// Memo must equal the quote nonce — binds this tx to this exact quote and
	// blocks a transfer whose numbers happen to line up from a different intent.
	const memoIx = tx.transaction.message.instructions.find(
		(ix) => ix.programId?.toString() === MEMO_PROGRAM,
	);
	const memo = typeof memoIx?.parsed === 'string' ? memoIx.parsed : null;
	if (!memo || memo !== quote.nonce) {
		throw verifyError('transaction memo does not match quote nonce', 422, 'memo_mismatch');
	}

	// Every split leg must have received at least its share. Underpaying any leg
	// (treasury, rewards, or seller) voids the whole payment.
	const credited = {};
	for (const leg of quote.legs) {
		const need = BigInt(leg.atomics);
		const got = creditedTo(tx, { mint: quote.mint, ownerAddress: leg.address });
		credited[leg.role] = got.toString();
		if (got < need) {
			throw verifyError(
				`split leg "${leg.role}" received ${got} < required ${need}`,
				422,
				'split_underpaid',
				{ role: leg.role, required: need.toString(), received: got.toString() },
			);
		}
	}

	return { confirmedAt: new Date().toISOString(), slot: tx.slot ?? null, credited };
}

function isUniqueViolation(err) {
	return err?.code === '23505' || /duplicate key|unique constraint/i.test(err?.message || '');
}

/**
 * Record a $THREE allowance pull as a settled payment, in the exact same
 * token_payments shape as settlePayment(). The allowance rail (Solana native
 * Subscriptions program) pulls funds with the platform delegate key instead of a
 * user-signed quote tx, but the economic record is identical — same purpose,
 * mint, split legs, and on-chain signature — so economy stats and creator
 * earnings (which match the `seller` split leg) stay consistent across both rails.
 *
 * Uses the issued quote's nonce as the unique key (the quote was priced normally;
 * only its settlement path differs), so a double-submit is caught by the same
 * UNIQUE(nonce)/UNIQUE(tx_signature) guard.
 */
export async function recordAllowancePayment({ quote, txSignature, network, payerWallet, userId, slot = null }) {
	try {
		const [row] = await sql`
			insert into token_payments
				(user_id, payer_wallet, purpose, mint, decimals, usd, price_usd,
				 total_atomics, splits, nonce, tx_signature, network, slot, ref_type, ref_id, confirmed_at)
			values
				(${userId ?? null}, ${payerWallet ?? null}, ${quote.purpose}, ${quote.mint}, ${quote.decimals},
				 ${quote.usd}, ${quote.priceUsd}, ${quote.total}, ${JSON.stringify(quote.legs)}::jsonb,
				 ${quote.nonce}, ${txSignature}, ${network}, ${slot},
				 ${quote.refType ?? null}, ${quote.refId ?? null}, now())
			returning id, created_at
		`;
		return { id: row.id, replay: false, created_at: row.created_at };
	} catch (err) {
		if (isUniqueViolation(err)) {
			const [existing] = await sql`
				select id, created_at from token_payments
				where nonce = ${quote.nonce} or tx_signature = ${txSignature}
				limit 1
			`;
			return { id: existing?.id ?? null, replay: true, created_at: existing?.created_at ?? null };
		}
		throw err;
	}
}

/**
 * Record a verified payment. Returns { id, replay, created_at }. A duplicate
 * nonce or tx_signature resolves to { replay: true } (the prior settled row).
 */
export async function settlePayment({
	quote,
	txSignature,
	network,
	payerWallet,
	userId,
	confirmation,
}) {
	try {
		const [row] = await sql`
			insert into token_payments
				(user_id, payer_wallet, purpose, mint, decimals, usd, price_usd,
				 total_atomics, splits, nonce, tx_signature, network, slot, ref_type, ref_id, confirmed_at)
			values
				(${userId ?? null}, ${payerWallet ?? null}, ${quote.purpose}, ${quote.mint}, ${quote.decimals},
				 ${quote.usd}, ${quote.priceUsd}, ${quote.total}, ${JSON.stringify(quote.legs)}::jsonb,
				 ${quote.nonce}, ${txSignature}, ${network}, ${confirmation?.slot ?? null},
				 ${quote.refType ?? null}, ${quote.refId ?? null}, now())
			returning id, created_at
		`;
		return { id: row.id, replay: false, created_at: row.created_at };
	} catch (err) {
		if (isUniqueViolation(err)) {
			const [existing] = await sql`
				select id, created_at from token_payments
				where nonce = ${quote.nonce} or tx_signature = ${txSignature}
				limit 1
			`;
			return {
				id: existing?.id ?? null,
				replay: true,
				created_at: existing?.created_at ?? null,
			};
		}
		throw err;
	}
}

/**
 * Full verified-payment path reused by Task 19 (paid spins) and Task 20
 * (token-priced listings). Validates the quote, rejects replays, verifies the
 * transaction on-chain, records the settlement.
 * @returns {Promise<{ ok: true, payment_id: string, quote: object, confirmation: object }>}
 */
export async function verifyAndSettlePayment({
	quoteToken,
	txSignature,
	payerWallet = null,
	userId = null,
	network,
}) {
	const quote = verifyQuote(quoteToken);
	const net = network || quote.network || 'mainnet';

	// Fast pre-check (the UNIQUE constraint in settlePayment is the source of
	// truth, but this avoids an RPC round-trip on an obvious replay).
	const [used] =
		await sql`select id, tx_signature from token_payments where nonce = ${quote.nonce} limit 1`;
	if (used) {
		throw verifyError('quote already settled', 409, 'already_settled', {
			tx_signature: used.tx_signature,
		});
	}

	const confirmation = await verifyOnChain({ quote, txSignature, network: net });
	const settled = await settlePayment({
		quote,
		txSignature,
		network: net,
		payerWallet,
		userId,
		confirmation,
	});
	if (settled.replay) {
		throw verifyError('payment already settled', 409, 'already_settled');
	}

	return { ok: true, payment_id: settled.id, quote, confirmation };
}

/**
 * Audit read for reconciliation. Keyset paginated by created_at. No secrets are
 * stored on the row, so the whole record is safe to return to an authorized reader.
 */
export async function listPayments({
	purpose = null,
	userId = null,
	refType = null,
	refId = null,
	limit = 50,
	before = null,
} = {}) {
	const cap = Math.min(Math.max(Number(limit) || 50, 1), 200);
	const rows = await sql`
		select id, user_id, payer_wallet, purpose, mint, decimals, usd, price_usd,
		       total_atomics, splits, nonce, tx_signature, network, slot,
		       ref_type, ref_id, confirmed_at, created_at
		from token_payments
		where (${purpose}::text is null or purpose = ${purpose})
		  and (${userId}::uuid is null or user_id = ${userId})
		  and (${refType}::text is null or ref_type = ${refType})
		  and (${refId}::text is null or ref_id = ${refId})
		  and (${before}::timestamptz is null or created_at < ${before})
		order by created_at desc
		limit ${cap + 1}
	`;
	const hasMore = rows.length > cap;
	const items = (hasMore ? rows.slice(0, cap) : rows).map((r) => ({
		id: r.id,
		user_id: r.user_id,
		payer_wallet: r.payer_wallet,
		purpose: r.purpose,
		mint: r.mint,
		decimals: r.decimals,
		usd: Number(r.usd),
		price_usd: Number(r.price_usd),
		total_atomics: r.total_atomics,
		splits: r.splits,
		nonce: r.nonce,
		tx_signature: r.tx_signature,
		network: r.network,
		slot: r.slot,
		ref_type: r.ref_type,
		ref_id: r.ref_id,
		confirmed_at: r.confirmed_at,
		created_at: r.created_at,
	}));
	return { items, next_cursor: hasMore ? items[items.length - 1].created_at : null };
}

/**
 * Creator/seller earnings for a wallet — every settled sale whose `seller` split
 * leg paid this wallet. Sums the seller-leg atomics so the dashboard shows real
 * $THREE earned, not the gross sale. Reads the same settle ledger; no second
 * source of truth. The leg match uses a jsonb containment so it's index-friendly.
 * @returns {Promise<{ total_atomics: string, sale_count: number, mint: string|null, decimals: number|null, items: object[] }>}
 */
export async function creatorEarnings({ sellerWallet, limit = 50, before = null } = {}) {
	if (!sellerWallet) {
		const e = new Error('sellerWallet is required');
		e.status = 400;
		e.code = 'bad_request';
		throw e;
	}
	const cap = Math.min(Math.max(Number(limit) || 50, 1), 200);
	const legMatch = JSON.stringify([{ role: 'seller', address: sellerWallet }]);
	const rows = await sql`
		select id, mint, decimals, usd, total_atomics, splits, tx_signature, ref_type, ref_id, created_at
		from token_payments
		where splits @> ${legMatch}::jsonb
		  and (${before}::timestamptz is null or created_at < ${before})
		order by created_at desc
		limit ${cap + 1}
	`;
	const hasMore = rows.length > cap;
	const page = hasMore ? rows.slice(0, cap) : rows;

	// Sum the seller leg across ALL matching sales (not just this page) for the
	// headline total, so pagination never understates lifetime earnings.
	const [{ total = '0', n = 0 } = {}] = await sql`
		select coalesce(sum((leg->>'atomics')::numeric), 0)::text as total, count(*) as n
		from token_payments,
		     lateral jsonb_array_elements(splits) as leg
		where splits @> ${legMatch}::jsonb
		  and leg->>'role' = 'seller'
		  and leg->>'address' = ${sellerWallet}
	`;

	const items = page.map((r) => {
		const sellerLeg = (r.splits || []).find((l) => l.role === 'seller' && l.address === sellerWallet);
		return {
			id: r.id,
			mint: r.mint,
			decimals: r.decimals,
			usd: Number(r.usd),
			earned_atomics: sellerLeg?.atomics ?? '0',
			total_atomics: r.total_atomics,
			tx_signature: r.tx_signature,
			ref_type: r.ref_type,
			ref_id: r.ref_id,
			created_at: r.created_at,
		};
	});

	return {
		total_atomics: String(total),
		sale_count: Number(n),
		mint: page[0]?.mint ?? null,
		decimals: page[0]?.decimals ?? null,
		items,
		next_cursor: hasMore ? items[items.length - 1].created_at : null,
	};
}

/**
 * Economy-wide aggregates over the settle ledger — the data behind the public
 * /three economy dashboard and the treasury/rewards loop. Sums gross settled
 * volume, payment count, and the per-role flow (treasury / rewards / seller) by
 * unrolling the jsonb split legs. `sinceDays` windows the dashboard headline.
 * @returns {Promise<{ since: string|null, payment_count: number, gross_atomics: string,
 *   by_role: Record<string,string>, by_purpose: { purpose: string, count: number, gross_atomics: string }[],
 *   mint: string|null, decimals: number|null }>}
 */
export async function economyStats({ sinceDays = null } = {}) {
	const since = sinceDays != null ? `${Math.max(1, Math.floor(sinceDays))} days` : null;

	const [head = {}] = await sql`
		select count(*) as n,
		       coalesce(sum(total_atomics::numeric), 0)::text as gross,
		       max(mint) as mint,
		       max(decimals) as decimals
		from token_payments
		where (${since}::interval is null or created_at >= now() - ${since}::interval)
	`;

	const roleRows = await sql`
		select leg->>'role' as role, coalesce(sum((leg->>'atomics')::numeric), 0)::text as atomics
		from token_payments, lateral jsonb_array_elements(splits) as leg
		where (${since}::interval is null or created_at >= now() - ${since}::interval)
		group by leg->>'role'
	`;
	const by_role = {};
	for (const r of roleRows) by_role[r.role] = String(r.atomics);

	const purposeRows = await sql`
		select purpose, count(*) as count, coalesce(sum(total_atomics::numeric), 0)::text as gross
		from token_payments
		where (${since}::interval is null or created_at >= now() - ${since}::interval)
		group by purpose
		order by gross desc
	`;

	return {
		since: since,
		payment_count: Number(head.n || 0),
		gross_atomics: String(head.gross || '0'),
		by_role,
		by_purpose: purposeRows.map((r) => ({
			purpose: r.purpose,
			count: Number(r.count),
			gross_atomics: String(r.gross),
		})),
		mint: head.mint ?? null,
		decimals: head.decimals ?? null,
	};
}

// ── Holder-rewards (reflections) distribution ledger ──────────────────────────
// The public, verifiable record of every distribution run. This is what lets
// /three show a real "reflected to holders" number with history — the deflation-
// free answer to a burn counter. No secrets stored; every row is on-chain facts.

/**
 * Record a distribution run. `status` is 'planned' for a dry run (no signer) or
 * 'completed'/'failed' once executed. Returns the new row's id + created_at.
 */
export async function recordRewardsDistribution({
	mint,
	poolWallet,
	poolAtomics,
	distributedAtomics = 0n,
	dustAtomics = 0n,
	holderCount = 0,
	eligibleSupplyAtomics = 0n,
	status = 'planned',
	txSignatures = [],
	note = null,
}) {
	const [row] = await sql`
		insert into three_rewards_distributions
			(mint, pool_wallet, pool_atomics, distributed_atomics, dust_atomics,
			 holder_count, eligible_supply_atomics, status, tx_signatures, note)
		values
			(${mint}, ${poolWallet}, ${String(poolAtomics)}, ${String(distributedAtomics)},
			 ${String(dustAtomics)}, ${Math.max(0, Math.floor(holderCount))},
			 ${String(eligibleSupplyAtomics)}, ${status},
			 ${JSON.stringify(txSignatures)}::jsonb, ${note})
		returning id, created_at
	`;
	return { id: row.id, created_at: row.created_at };
}

/**
 * Public history of distributions + the cumulative reflected total. `completed`
 * runs count toward the headline; `planned` (dry) runs are shown but excluded
 * from the reflected total so the number only ever reflects real on-chain payouts.
 * @returns {Promise<{ total_reflected_atomics: string, run_count: number, items: object[] }>}
 */
export async function listRewardsDistributions({ limit = 20 } = {}) {
	const cap = Math.min(Math.max(Number(limit) || 20, 1), 100);
	const rows = await sql`
		select id, mint, pool_wallet, pool_atomics, distributed_atomics, dust_atomics,
		       holder_count, eligible_supply_atomics, status, tx_signatures, note, created_at
		from three_rewards_distributions
		order by created_at desc
		limit ${cap}
	`;
	const [{ total = '0', n = 0 } = {}] = await sql`
		select coalesce(sum(distributed_atomics), 0)::text as total, count(*) as n
		from three_rewards_distributions
		where status = 'completed'
	`;
	return {
		total_reflected_atomics: String(total),
		run_count: Number(n),
		items: rows.map((r) => ({
			id: r.id,
			mint: r.mint,
			pool_wallet: r.pool_wallet,
			pool_atomics: String(r.pool_atomics),
			distributed_atomics: String(r.distributed_atomics),
			dust_atomics: String(r.dust_atomics),
			holder_count: Number(r.holder_count),
			eligible_supply_atomics: String(r.eligible_supply_atomics),
			status: r.status,
			tx_signatures: r.tx_signatures,
			note: r.note,
			created_at: r.created_at,
		})),
	};
}