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.4 KB
Raw Blame
// Cosmetic creator economy (R25) — coin-tied revenue splits on top of the R22
// avatar-shop rail.
//
// Every /play world IS a pump.fun coin (keyed by its mint). When a player buys a
// premium cosmetic inside a coin's world, the sale is "tied" to that coin: a
// configurable share of the settled USDC is paid out — as a REAL on-chain USDC
// transfer from the platform settlement wallet to the coin's creator wallet
// (reusing api/_lib/solana-transfer.js, the same payout rail the club sweep uses).
// There is no simulated balance: the creator either has a confirmed payout tx or a
// pending/failed accrual a sweep retries.
//
// The split is recorded by the verified-payment handler in
// api/x402/cosmetic-purchase.js (R22), the only writer. The creator-earnings
// dashboard and the platform "rarest fits" leaderboard read the ledger back. All
// amounts are USDC atomics (6 decimals) — the asset x402 actually settles. ($THREE
// stays the only coin the shop quotes value in; it is never a settlement asset.)

import bs58 from 'bs58';

import { sql } from './db.js';
import { databaseConfigured } from './env.js';
import { getCosmetic } from './cosmetics.js';
import { verifySiwsSignature } from './siws.js';
import { transferSolanaUSDC } from './solana-transfer.js';
import { SOLANA_USDC_MINT } from '../payments/_config.js';
import { loadCoinByMint } from './coin/index.js';

// The default creator share of a coin-tied cosmetic sale, in basis points. A coin
// creator can raise or lower their own share but never above MAX_CREATOR_BPS — the
// platform always keeps a slice to fund the worlds the cosmetics are worn in.
export const DEFAULT_CREATOR_BPS = 5000; // 50%
export const MAX_CREATOR_BPS = 9000;     // 90% ceiling

const BASE58_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
// Rarity → flex weight. Drives the "rarest fits" status score: a legendary fit is
// worth far more to a wallet's flex score than a rare one.
export const RARITY_WEIGHT = Object.freeze({ common: 1, rare: 4, epic: 12, legendary: 40 });

export function isMint(mint) {
	return typeof mint === 'string' && BASE58_RE.test(mint);
}
export function isWallet(addr) {
	return typeof addr === 'string' && BASE58_RE.test(addr);
}

// True only when a durable economy DB is configured. Recording is best-effort: a
// missing DB must never block an R22 unlock the buyer already paid for.
export function economyDbConfigured() {
	return databaseConfigured();
}

// ── Creator resolution ─────────────────────────────────────────────────────

// Resolve the creator wallet that earns a coin's cosmetic share. Order:
//   1. an explicit cosmetic_creator_splits override (the creator set it),
//   2. our own launch record (coin_launches.creator_wallet),
//   3. an agent identity that launched this mint (agent_identities.meta.token),
//   4. the on-chain pump.fun bonding-curve creator (arbitrary community coins).
// Returns { wallet, source }; { wallet:null, source:'none' } when none resolves —
// the sale then settles with no creator leg (full platform revenue).
export async function resolveCreatorWallet(mint, { allowOnchain = true } = {}) {
	if (!isMint(mint)) return { wallet: null, source: 'none' };
	try {
		const [cfg] = await sql`
			select creator_wallet from cosmetic_creator_splits where mint = ${mint} limit 1
		`;
		if (isWallet(cfg?.creator_wallet)) return { wallet: cfg.creator_wallet, source: 'config' };

		const coin = await loadCoinByMint(mint).catch(() => null);
		if (isWallet(coin?.creator_wallet)) return { wallet: coin.creator_wallet, source: 'coin_launches' };

		const [agent] = await sql`
			select meta->'token'->>'creator' as creator
			from agent_identities
			where deleted_at is null and meta->'token'->>'mint' = ${mint}
			limit 1
		`;
		if (isWallet(agent?.creator)) return { wallet: agent.creator, source: 'agent_identity' };
	} catch (err) {
		console.warn('[cosmetics-economy] DB creator lookup failed:', err?.message);
	}

	if (allowOnchain) {
		const onchain = await resolveOnchainPumpCreator(mint);
		if (onchain) return { wallet: onchain, source: 'pumpfun_onchain' };
	}
	return { wallet: null, source: 'none' };
}

// Best-effort on-chain creator from the pump.fun bonding curve. Heavy SDK imports
// are deferred so the common (DB-resolved) path never loads them. Returns null on
// any failure — an unresolvable creator just means "no creator leg".
async function resolveOnchainPumpCreator(mint) {
	try {
		const [{ PublicKey }, { PUMP_SDK, bondingCurvePda }, { getConnection }] = await Promise.all([
			import('@solana/web3.js'),
			import('@pump-fun/pump-sdk'),
			import('./pump.js'),
		]);
		const conn = getConnection({ network: 'mainnet' });
		const info = await conn.getAccountInfo(bondingCurvePda(new PublicKey(mint)));
		if (!info) return null;
		const curve = typeof PUMP_SDK?.decodeBondingCurve === 'function'
			? PUMP_SDK.decodeBondingCurve(info)
			: new PUMP_SDK().decodeBondingCurve(info);
		const creator = curve?.creator?.toBase58?.();
		return isWallet(creator) ? creator : null;
	} catch (err) {
		console.warn('[cosmetics-economy] on-chain creator lookup failed:', err?.message);
		return null;
	}
}

// ── Split config ───────────────────────────────────────────────────────────

export function clampCreatorBps(bps) {
	const n = Number(bps);
	if (!Number.isFinite(n)) return DEFAULT_CREATOR_BPS;
	return Math.max(0, Math.min(MAX_CREATOR_BPS, Math.round(n)));
}

// The effective split config for a coin: the creator wallet + share applied to its
// cosmetic sales. Reflects an explicit override when present, otherwise the
// resolved creator at the default share. `isDefault` tells the UI whether the
// creator has customized it yet.
export async function getSplitConfig(mint) {
	if (!isMint(mint)) return null;
	const [row] = await sql`
		select mint, creator_wallet, split_bps, updated_at
		from cosmetic_creator_splits where mint = ${mint} limit 1
	`;
	if (row) {
		return {
			mint: row.mint,
			creatorWallet: row.creator_wallet,
			splitBps: row.split_bps,
			source: 'config',
			isDefault: false,
			updatedAt: row.updated_at,
			maxBps: MAX_CREATOR_BPS,
		};
	}
	const { wallet, source } = await resolveCreatorWallet(mint);
	return {
		mint,
		creatorWallet: wallet,
		splitBps: wallet ? DEFAULT_CREATOR_BPS : 0,
		source,
		isDefault: true,
		updatedAt: null,
		maxBps: MAX_CREATOR_BPS,
	};
}

// The message a creator signs to authorize changing their coin's cosmetic split.
export function splitConfigMessage({ mint, bps, ts }) {
	return `three.ws cosmetic revenue split\nmint: ${mint}\nshare: ${bps} bps\nts: ${ts}`;
}

const SIGNATURE_MAX_AGE_S = 600; // a config-change signature is valid for 10 minutes

// Set a coin's cosmetic split, authorized by an ed25519 signature from the coin's
// creator wallet over splitConfigMessage(). Verifies the signer IS the resolved
// creator, the timestamp is fresh, and the bps is in range. Returns the new
// effective config. Throws { status, code, message, expose } on any failure.
export async function setSplitConfig({ mint, bps, ts, signature, signer }) {
	if (!isMint(mint)) throw fail(400, 'bad_mint', 'Invalid coin mint.');
	const bpsClamped = clampCreatorBps(bps);
	const tsNum = Number(ts);
	if (!Number.isFinite(tsNum)) throw fail(400, 'bad_timestamp', 'Missing or invalid timestamp.');
	const ageS = Math.floor(Date.now() / 1000) - tsNum;
	if (ageS < -60 || ageS > SIGNATURE_MAX_AGE_S) throw fail(400, 'stale_signature', 'Signature timestamp is too old or in the future.');
	if (!isWallet(signer)) throw fail(400, 'bad_signer', 'Invalid signer wallet.');

	const { wallet: creatorWallet } = await resolveCreatorWallet(mint);
	if (!creatorWallet) throw fail(409, 'no_creator', 'No creator wallet is established for this coin yet.');
	if (creatorWallet !== signer) throw fail(403, 'not_creator', 'Only the coin creator can set the cosmetic split.');

	let valid = false;
	try {
		valid = verifySiwsSignature(splitConfigMessage({ mint, bps: bpsClamped, ts: tsNum }), signature, signer);
	} catch { valid = false; }
	if (!valid) throw fail(401, 'bad_signature', 'Signature did not verify against the creator wallet.');

	await sql`
		insert into cosmetic_creator_splits (mint, creator_wallet, split_bps, updated_by)
		values (${mint}, ${creatorWallet}, ${bpsClamped}, ${signer})
		on conflict (mint) do update
		set creator_wallet = excluded.creator_wallet,
		    split_bps = excluded.split_bps,
		    updated_by = excluded.updated_by
	`;
	return getSplitConfig(mint);
}

// ── Record + pay the creator split ─────────────────────────────────────────

// Decode the platform settlement wallet that fronts creator payouts. This is the
// wallet the x402 Solana settlements land in; ops configures its 64-byte secret
// (base64) so the split can be sent back out on-chain. Returns the bs58 secret
// transferSolanaUSDC expects, or null when unconfigured (payouts then accrue).
function payoutTreasuryBs58() {
	const b64 = process.env.COSMETIC_SPLIT_TREASURY_SECRET_KEY_B64;
	if (!b64) return null;
	try {
		const raw = Buffer.from(b64, 'base64');
		if (raw.byteLength !== 64) {
			console.warn('[cosmetics-economy] COSMETIC_SPLIT_TREASURY_SECRET_KEY_B64 is not a 64-byte secret — payouts disabled.');
			return null;
		}
		return bs58.encode(raw);
	} catch {
		return null;
	}
}

// Record a settled cosmetic sale and pay the coin creator their share on-chain.
// Idempotent on (account, cosmetic): a replayed settle or SIWX re-access conflicts
// and returns the existing record without re-paying. On a fresh sale it resolves
// the creator + share, inserts the ledger row, then BEST-EFFORT pays the creator's
// USDC cut on Solana — a payout failure leaves the row 'pending'/'failed' (the
// buyer still owns the cosmetic; a sweep retries the payout). Never throws to the
// caller: recording/payout must not fail the unlock the buyer already paid for.
//
// @returns {Promise<{ recorded:boolean, alreadyRecorded?:boolean, creatorWallet?:string|null,
//   creatorBps?:number, creatorCutAtomics?:string, payoutStatus?:string, payoutTx?:string|null }>}
export async function recordSaleAndSplit({ account, cosmeticId, item, payerWallet, payerNetwork, asset, priceAtomics, mint }) {
	if (!economyDbConfigured()) return { recorded: false };
	const cosmetic = item || getCosmetic(cosmeticId);
	if (!cosmetic) return { recorded: false };

	let priceRaw;
	try { priceRaw = BigInt(priceAtomics || '0'); } catch { priceRaw = 0n; }

	// Resolve the creator + share for this coin world (best-effort).
	let creatorWallet = null;
	let bps = 0;
	if (isMint(mint)) {
		try {
			const cfg = await getSplitConfig(mint);
			if (cfg?.creatorWallet && isWallet(cfg.creatorWallet)) {
				creatorWallet = cfg.creatorWallet;
				bps = clampCreatorBps(cfg.splitBps);
			}
		} catch (err) {
			console.warn('[cosmetics-economy] split config resolve failed:', err?.message);
		}
	}
	// Never pay the creator out of a payment they themselves made.
	if (creatorWallet && payerWallet && creatorWallet === payerWallet) { creatorWallet = null; bps = 0; }
	const cutRaw = creatorWallet && bps > 0 ? (priceRaw * BigInt(bps)) / 10000n : 0n;
	const initialStatus = !creatorWallet || cutRaw <= 0n ? 'none' : 'pending';

	// Insert-or-skip, idempotent on (account, cosmetic). A conflict means we already
	// recorded (and possibly paid) this unlock — return without re-paying.
	let inserted;
	try {
		[inserted] = await sql`
			insert into cosmetic_sales (
				account, payer_wallet, payer_network, mint, cosmetic_id, rarity,
				price_usdc_atomics, asset, creator_wallet, split_bps, creator_cut_atomics, payout_status
			) values (
				${account}, ${payerWallet || null}, ${payerNetwork || null}, ${isMint(mint) ? mint : null},
				${cosmeticId}, ${cosmetic.rarity || 'common'}, ${priceRaw.toString()}, ${asset || null},
				${creatorWallet}, ${bps}, ${cutRaw.toString()}, ${initialStatus}
			)
			on conflict (account, cosmetic_id) do nothing
			returning id
		`;
	} catch (err) {
		console.error('[cosmetics-economy] sale insert failed:', err?.message);
		return { recorded: false };
	}
	if (!inserted) {
		return { recorded: true, alreadyRecorded: true };
	}

	// Pay the creator their cut on-chain (best-effort). Solana-only: pump.fun
	// creators are Solana wallets, and the platform fronts the USDC on Solana
	// regardless of which network the buyer paid on.
	let payoutStatus = initialStatus;
	let payoutTx = null;
	if (initialStatus === 'pending') {
		const result = await payCreatorCut({ saleId: inserted.id, creatorWallet, cutRaw });
		payoutStatus = result.status;
		payoutTx = result.tx || null;
	}

	return {
		recorded: true,
		alreadyRecorded: false,
		creatorWallet,
		creatorBps: bps,
		creatorCutAtomics: cutRaw.toString(),
		payoutStatus,
		payoutTx,
	};
}

// Send one creator cut on-chain and reconcile the ledger row. Returns the new
// payout status + tx (or the failure). Never throws.
async function payCreatorCut({ saleId, creatorWallet, cutRaw }) {
	const fromWallet = payoutTreasuryBs58();
	if (!fromWallet) {
		await markPayout(saleId, { status: 'skipped', error: 'payout treasury not configured' });
		return { status: 'skipped' };
	}
	try {
		const tx = await transferSolanaUSDC({
			fromWallet,
			toAddress: creatorWallet,
			amount: cutRaw,
			mint: SOLANA_USDC_MINT,
		});
		await markPayout(saleId, { status: 'paid', tx, network: 'solana' });
		return { status: 'paid', tx };
	} catch (err) {
		const reason = err?.message ? String(err.message).slice(0, 300) : 'payout_failed';
		console.error('[cosmetics-economy] creator payout failed:', reason);
		await markPayout(saleId, { status: 'failed', error: reason });
		return { status: 'failed' };
	}
}

async function markPayout(saleId, { status, tx = null, network = null, error = null }) {
	try {
		await sql`
			update cosmetic_sales
			set payout_status = ${status},
			    payout_tx = ${tx},
			    payout_network = ${network},
			    payout_error = ${error},
			    paid_at = ${status === 'paid' ? new Date().toISOString() : null}
			where id = ${saleId}
		`;
	} catch (err) {
		console.error('[cosmetics-economy] payout reconcile failed:', err?.message);
	}
}

// Retry creator payouts that haven't landed on-chain (pending/failed). Bounded per
// run. Returns a per-sale outcome list. Safe to call from a cron or an admin tool.
export async function sweepPendingCreatorPayouts({ limit = 25 } = {}) {
	if (!economyDbConfigured()) return { swept: 0, results: [] };
	const rows = await sql`
		select id, creator_wallet, creator_cut_atomics
		from cosmetic_sales
		where payout_status in ('pending', 'failed')
		  and creator_wallet is not null
		  and creator_cut_atomics > 0
		order by settled_at asc
		limit ${limit}
	`;
	const results = [];
	for (const r of rows) {
		const out = await payCreatorCut({ saleId: r.id, creatorWallet: r.creator_wallet, cutRaw: BigInt(r.creator_cut_atomics) });
		results.push({ id: r.id, status: out.status, tx: out.tx || null });
	}
	return { swept: results.length, results };
}

// ── Creator earnings (dashboard) ───────────────────────────────────────────

const usdc = (raw) => Number(raw || 0) / 1e6;

// Real, settled cosmetic earnings for a creator wallet: lifetime + 30-day totals,
// paid vs. pending, per-coin + per-cosmetic breakdowns, and recent sales. Every
// number is summed straight from the ledger — never estimated.
export async function creatorEarnings(creatorWallet, { recentLimit = 25 } = {}) {
	if (!isWallet(creatorWallet)) return null;

	const [totals] = await sql`
		select
			count(*)::int as sales,
			count(distinct account)::int as buyers,
			coalesce(sum(creator_cut_atomics), 0)::text as earned,
			coalesce(sum(creator_cut_atomics) filter (where payout_status = 'paid'), 0)::text as paid,
			coalesce(sum(creator_cut_atomics) filter (where payout_status in ('pending','failed')), 0)::text as pending,
			coalesce(sum(creator_cut_atomics) filter (where settled_at > now() - interval '30 days'), 0)::text as earned_30d,
			coalesce(sum(price_usdc_atomics), 0)::text as gross,
			min(settled_at) as first_sale_at,
			max(settled_at) as last_sale_at
		from cosmetic_sales
		where creator_wallet = ${creatorWallet}
	`;

	const perCoin = await sql`
		select mint, count(*)::int as sales, coalesce(sum(creator_cut_atomics),0)::text as earned
		from cosmetic_sales where creator_wallet = ${creatorWallet}
		group by mint order by sum(creator_cut_atomics) desc limit 50
	`;
	const perCosmetic = await sql`
		select cosmetic_id, rarity, count(*)::int as sales, coalesce(sum(creator_cut_atomics),0)::text as earned
		from cosmetic_sales where creator_wallet = ${creatorWallet}
		group by cosmetic_id, rarity order by sum(creator_cut_atomics) desc limit 50
	`;
	const recent = await sql`
		select cosmetic_id, rarity, mint, account, price_usdc_atomics, creator_cut_atomics,
		       split_bps, payout_status, payout_tx, settled_at
		from cosmetic_sales where creator_wallet = ${creatorWallet}
		order by settled_at desc limit ${recentLimit}
	`;

	return {
		creatorWallet,
		currency: 'USDC',
		totals: {
			sales: totals.sales,
			buyers: totals.buyers,
			earnedUsdc: usdc(totals.earned),
			paidUsdc: usdc(totals.paid),
			pendingUsdc: usdc(totals.pending),
			earned30dUsdc: usdc(totals.earned_30d),
			grossUsdc: usdc(totals.gross),
			firstSaleAt: totals.first_sale_at,
			lastSaleAt: totals.last_sale_at,
		},
		perCoin: perCoin.map((r) => ({ mint: r.mint, sales: r.sales, earnedUsdc: usdc(r.earned) })),
		perCosmetic: perCosmetic.map((r) => ({
			cosmeticId: r.cosmetic_id,
			name: getCosmetic(r.cosmetic_id)?.name || r.cosmetic_id,
			rarity: r.rarity,
			sales: r.sales,
			earnedUsdc: usdc(r.earned),
		})),
		recent: recent.map((r) => ({
			cosmeticId: r.cosmetic_id,
			name: getCosmetic(r.cosmetic_id)?.name || r.cosmetic_id,
			rarity: r.rarity,
			mint: r.mint,
			buyer: r.account,
			priceUsdc: usdc(r.price_usdc_atomics),
			earnedUsdc: usdc(r.creator_cut_atomics),
			splitBps: r.split_bps,
			payoutStatus: r.payout_status,
			payoutTx: r.payout_tx,
			settledAt: r.settled_at,
		})),
	};
}

// ── Leaderboard / rarest fits ──────────────────────────────────────────────

// The platform-wide flex surface, all from settled records:
//   • rarestFits   — premium cosmetics ranked by scarcity (fewest distinct owners),
//     each with a deep link back to a world where it's been bought.
//   • topCollectors — accounts ranked by a rarity-weighted flex score.
//   • topCreators  — creator wallets ranked by real settled cosmetic earnings.
//   • recent       — the latest settled sales (the live activity drip).
export async function cosmeticsLeaderboard({ limit = 12 } = {}) {
	const ownerRows = await sql`
		select cosmetic_id, account,
		       (array_agg(mint) filter (where mint is not null))[1] as any_mint
		from cosmetic_sales
		group by cosmetic_id, account
	`;

	const owners = new Map();        // cosmetic_id → { owners:Set, anyMint }
	const scoreByAccount = new Map(); // account → { score, count }
	for (const row of ownerRows) {
		const c = getCosmetic(row.cosmetic_id);
		if (!c) continue;
		const weight = RARITY_WEIGHT[c.rarity] || 1;
		const o = owners.get(row.cosmetic_id) || { set: new Set(), anyMint: row.any_mint || null };
		o.set.add(row.account);
		if (!o.anyMint && row.any_mint) o.anyMint = row.any_mint;
		owners.set(row.cosmetic_id, o);

		const s = scoreByAccount.get(row.account) || { score: 0, count: 0 };
		s.score += weight; s.count += 1;
		scoreByAccount.set(row.account, s);
	}

	const rarestFits = [...owners.entries()]
		.map(([cosmeticId, o]) => {
			const c = getCosmetic(cosmeticId);
			return {
				cosmeticId,
				name: c.name,
				slot: c.slot,
				rarity: c.rarity,
				owners: o.set.size,
				weight: RARITY_WEIGHT[c.rarity] || 1,
				worldMint: o.anyMint,
				previewImage: c.previewImage || null,
			};
		})
		.sort((a, b) => a.owners - b.owners || b.weight - a.weight)
		.slice(0, limit);

	const topCollectors = [...scoreByAccount.entries()]
		.map(([account, v]) => ({ account, flexScore: v.score, fits: v.count }))
		.sort((a, b) => b.flexScore - a.flexScore || b.fits - a.fits)
		.slice(0, limit);

	const creatorRows = await sql`
		select creator_wallet, count(*)::int as sales, coalesce(sum(creator_cut_atomics),0)::text as earned
		from cosmetic_sales where creator_wallet is not null
		group by creator_wallet order by sum(creator_cut_atomics) desc limit ${limit}
	`;
	const topCreators = creatorRows.map((r) => ({ wallet: r.creator_wallet, sales: r.sales, earnedUsdc: usdc(r.earned) }));

	const recentRows = await sql`
		select cosmetic_id, rarity, mint, account, price_usdc_atomics, settled_at
		from cosmetic_sales order by settled_at desc limit ${limit}
	`;
	const recent = recentRows.map((r) => ({
		cosmeticId: r.cosmetic_id,
		name: getCosmetic(r.cosmetic_id)?.name || r.cosmetic_id,
		rarity: r.rarity,
		mint: r.mint,
		buyer: r.account,
		priceUsdc: usdc(r.price_usdc_atomics),
		settledAt: r.settled_at,
	}));

	return { currency: 'USDC', rarestFits, topCollectors, topCreators, recent };
}

// ── helpers ────────────────────────────────────────────────────────────────

function fail(status, code, message) {
	return Object.assign(new Error(message), { status, code, expose: true });
}