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.

22.0 KB
Raw Blame
// three.ws native launch lane dispatcher: the self-hosted coin launchpad on
// Meteora's Dynamic Bonding Curve (DBC), alongside the pump.fun lane in
// api/pump/[action].js. Same custody model: the server builds unsigned
// transactions, the user's wallet (plus the mint keypair) signs client-side,
// and a confirm step verifies the landed transaction on-chain before
// recording the launch.
//
// Namespaced /api/native-launch/* (NOT /api/launchpad/*, which is the
// unrelated Launchpad Studio page builder).
//
// Action map:
//   config          -> handleConfig        (public: lane economics + config key)
//   quote           -> handleQuote         (public: buy or sell quote on a live curve)
//   swap-prep       -> handleSwapPrep      (public: unsigned buy/sell tx for the trader's wallet)
//   pool            -> handlePool          (public: pool state / curve progress)
//   launch-prep     -> handleLaunchPrep    (authed: unsigned create-pool tx)
//   launch-confirm  -> handleLaunchConfirm (authed: verify + record launch)
//   launches        -> handleLaunches      (public: native launch directory)
//   fee-config      -> handleFeeConfig     (public: validate + describe a decaying-fee schedule, optional devnet/mainnet simulation)

import { z } from 'zod';
import { Keypair } from '@solana/web3.js';
import { sql } from '../_lib/db.js';
import { getSessionUser } from '../_lib/auth.js';
import { cors, json, method, readJson, wrap, error, rateLimited } from '../_lib/http.js';
import { thumbnailUrl } from '../_lib/r2.js';
import { env } from '../_lib/env.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { resolveOrCreateAgentForAvatar } from '../_lib/agent-identity.js';
import { parse, isUuid } from '../_lib/validate.js';
import { randomToken } from '../_lib/crypto.js';
import { publishFeedEvent } from '../_lib/feed.js';
import { normalizeGatewayURL } from '../../src/ipfs.js';
import { THREE_WS_VANITY, hasThreeWsMark } from '../../src/solana/vanity/brand.js';
import { grindVanityNode, GrindExhaustedError } from '../../src/solana/vanity/grinder-node.js';
import { verifySignature, solanaPubkey } from '../_lib/pump.js';
import { laneInfo, configKeyFor, quoteMintFor } from '../_lib/native-launch/config.js';
import { previewFeeConfig, simulateFeeConfig } from '../_lib/native-launch/fee-config.js';
import {
	buildCreatePoolTx,
	txInvokesDbcProgram,
	getPoolState,
	quoteBuy,
	quoteSell,
	buildSwapTx,
} from '../_lib/native-launch/dbc.js';
import { logger } from '../_lib/usage.js';

const log = logger('launchpad');

function shortAddr(a) {
	return a && a.length > 10 ? `${a.slice(0, 4)}…${a.slice(-4)}` : a || '';
}

// ── config ─────────────────────────────────────────────────────────────────

async function handleConfig(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;
	const rl = await limits.authedReadIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);
	const url = new URL(req.url, `http://${req.headers.host}`);
	const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';
	const info = laneInfo(network);
	return json(res, 200, { ...info, available: Boolean(info.config_key) }, {
		'cache-control': 'public, max-age=60, s-maxage=300',
	});
}

// ── quote / pool (public reads) ────────────────────────────────────────────

// Both a coin's supply and $THREE's are 1B, so no single swap can exceed this.
const MAX_SWAP_AMOUNT = 1_000_000_000;

async function handleQuote(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;
	const rl = await limits.mcpIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);
	const url = new URL(req.url, `http://${req.headers.host}`);
	const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';
	const mint = url.searchParams.get('mint');
	if (!mint || !solanaPubkey(mint)) return error(res, 400, 'validation_error', 'valid mint required');
	// A buy is sized in $THREE (three_in), a sell in the coin's own tokens (tokens_in).
	const selling = url.searchParams.has('tokens_in');
	const amount = Number(url.searchParams.get(selling ? 'tokens_in' : 'three_in') || (selling ? '0' : '1000'));
	if (!(amount > 0) || amount > MAX_SWAP_AMOUNT) {
		return error(res, 400, 'validation_error', `${selling ? 'tokens_in' : 'three_in'} must be in (0, ${MAX_SWAP_AMOUNT}]`);
	}
	try {
		const quote = selling
			? await quoteSell({ network, mint, tokensIn: amount })
			: await quoteBuy({ network, mint, threeIn: amount });
		return json(res, 200, { network, mint, ...quote });
	} catch (e) {
		return error(res, e.status || 500, e.code || 'quote_failed', e.message);
	}
}

// ── swap-prep ──────────────────────────────────────────────────────────────

const swapPrepSchema = z.object({
	mint: z.string().min(32).max(44),
	wallet_address: z.string().min(32).max(44),
	side: z.enum(['buy', 'sell']),
	amount: z.number().positive().max(MAX_SWAP_AMOUNT),
	slippage_bps: z.number().int().min(1).max(5000).default(100),
	// Referrer's token account for the quote mint; it earns the referral share of the protocol fee.
	referral_token_account: z.string().min(32).max(44).optional(),
	network: z.enum(['mainnet', 'devnet']).default('mainnet'),
});

// Builds the unsigned swap and nothing else: the trader's wallet signs and sends it,
// so this needs no session. A buy spends `amount` $THREE, a sell spends `amount` tokens.
async function handleSwapPrep(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['POST'])) return;
	const rl = await limits.mcpIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);
	try {
		const body = parse(swapPrepSchema, await readJson(req));
		if (!solanaPubkey(body.mint) || !solanaPubkey(body.wallet_address)) {
			return error(res, 400, 'validation_error', 'valid mint and wallet_address required');
		}
		const built = await buildSwapTx({
			network: body.network,
			mint: body.mint,
			trader: body.wallet_address,
			side: body.side,
			amountIn: body.amount,
			slippageBps: body.slippage_bps,
			referralTokenAccount: body.referral_token_account ?? null,
		});
		return json(res, 200, {
			network: body.network,
			mint: body.mint,
			tx_base64: built.txBase64,
			pool: built.pool,
			side: built.side,
			amount_in: built.amount_in,
			expected_out: built.expected_out,
			min_out: built.min_out,
			slippage_bps: built.slippage_bps,
			referral: built.referral,
		});
	} catch (e) {
		return error(res, e.status || 500, e.code || 'swap_prep_failed', e.message);
	}
}

async function handlePool(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;
	const rl = await limits.mcpIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);
	const url = new URL(req.url, `http://${req.headers.host}`);
	const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';
	const mint = url.searchParams.get('mint');
	if (!mint || !solanaPubkey(mint)) return error(res, 400, 'validation_error', 'valid mint required');
	try {
		const state = await getPoolState({ network, mint });
		return json(res, 200, { network, mint, ...state }, { 'cache-control': 'public, max-age=5' });
	} catch (e) {
		return error(res, e.status || 500, e.code || 'pool_state_failed', e.message);
	}
}

// ── launch-prep ────────────────────────────────────────────────────────────

const launchPrepSchema = z
	.object({
		agent_id: z.string().uuid().optional(),
		avatar_id: z.string().uuid().optional(),
		wallet_address: z.string().min(32).max(44),
		creator_address: z.string().min(32).max(44).optional(),
		name: z.string().trim().min(1).max(32),
		symbol: z.string().trim().min(1).max(10),
		uri: z.string().url().max(200),
		network: z.enum(['mainnet', 'devnet']).default('mainnet'),
		// The creator's optional first buy, in $THREE.
		three_buy_in: z.number().min(0).max(10_000_000).default(0),
		mint_address: z.string().min(32).max(44).optional(),
	})
	.refine((b) => b.agent_id || b.avatar_id, { message: 'agent_id or avatar_id required' });

async function handleLaunchPrep(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const user = await getSessionUser(req);
	if (!user) return error(res, 401, 'unauthorized', 'sign in required');

	const rl = await limits.authIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	const body = parse(launchPrepSchema, await readJson(req));
	if (!configKeyFor(body.network)) {
		return error(
			res,
			503,
			'lane_not_configured',
			`native launchpad is not deployed on ${body.network} yet`,
		);
	}
	const signer = solanaPubkey(body.wallet_address);
	if (!signer) return error(res, 400, 'validation_error', 'invalid wallet_address');

	const [walletRow] = await sql`
		select id from user_wallets
		where user_id=${user.id} and address=${body.wallet_address} and chain_type='solana'
		limit 1
	`;
	if (!walletRow) return error(res, 403, 'forbidden', 'wallet not linked to your account');

	// On-chain pool creator (trading-fee recipient). Same ownership rule as the
	// pump lane: when provided, it must be another wallet linked to this user.
	let creator = signer;
	if (body.creator_address && body.creator_address !== body.wallet_address) {
		const creatorPk = solanaPubkey(body.creator_address);
		if (!creatorPk) return error(res, 400, 'validation_error', 'invalid creator_address');
		const [creatorWallet] = await sql`
			select id from user_wallets
			where user_id=${user.id} and address=${body.creator_address} and chain_type='solana'
			limit 1
		`;
		if (!creatorWallet) {
			return error(res, 403, 'forbidden', 'creator_address must be a solana wallet linked to your account');
		}
		creator = creatorPk;
	}

	const agent = await resolveOrCreateAgentForAvatar({
		userId: user.id,
		agentId: body.agent_id,
		avatarId: body.avatar_id,
	});
	if (!agent) return error(res, 404, 'not_found', 'agent not found');

	// Mint pubkey: client-supplied (vanity-ground) or server-ground with the
	// three.ws mark. Identical branding rule to the pump lane.
	const enforceMark = env.THREE_WS_MARK_ENFORCE !== '0' && env.THREE_WS_MARK_ENFORCE !== 'false';
	let mintKeypair = null;
	let mint;
	if (body.mint_address) {
		const supplied = solanaPubkey(body.mint_address);
		if (!supplied) return error(res, 400, 'validation_error', 'invalid mint_address');
		if (enforceMark && !hasThreeWsMark(supplied.toBase58())) {
			return error(
				res,
				400,
				'unbranded_mint',
				'three.ws launches must use a mint address carrying the "3ws" mark. Grind one client-side, or omit mint_address to let the server stamp it',
			);
		}
		mint = supplied;
	} else if (enforceMark) {
		try {
			const ground = await grindVanityNode({ ...THREE_WS_VANITY });
			mintKeypair = Keypair.fromSecretKey(ground.secretKey);
			mint = mintKeypair.publicKey;
		} catch (err) {
			if (err instanceof GrindExhaustedError) {
				return error(res, 503, 'mark_grind_failed', 'could not stamp the three.ws mark, retry');
			}
			throw err;
		}
	} else {
		mintKeypair = Keypair.generate();
		mint = mintKeypair.publicKey;
	}

	let built;
	try {
		built = await buildCreatePoolTx({
			network: body.network,
			payer: signer,
			creator,
			baseMint: mint,
			name: body.name,
			symbol: body.symbol,
			uri: body.uri,
			threeBuyIn: body.three_buy_in,
		});
	} catch (e) {
		log.warn('create_pool_build_failed', { message: e.message });
		return error(res, e.status || 502, e.code || 'build_failed', e.message);
	}

	const prepId = await randomToken(24);
	const expiresAt = new Date(Date.now() + 30 * 60 * 1000);
	await sql`
		insert into agent_registrations_pending (user_id, cid, metadata_uri, payload, expires_at)
		values (
			${user.id},
			${mint.toBase58()},
			${body.uri},
			${JSON.stringify({
				kind: 'native_launch',
				agent_id: agent.id,
				wallet_address: body.wallet_address,
				creator_address: creator.toBase58(),
				mint: mint.toBase58(),
				pool: built.pool,
				config_key: built.configKey,
				name: body.name,
				symbol: body.symbol,
				network: body.network,
				prep_id: prepId,
			})}::jsonb,
			${expiresAt}
		)
	`;

	return json(res, 201, {
		prep_id: prepId,
		agent_id: agent.id,
		lane: 'native',
		mint: mint.toBase58(),
		pool: built.pool,
		config_key: built.configKey,
		mint_secret_key_b64: mintKeypair ? Buffer.from(mintKeypair.secretKey).toString('base64') : null,
		client_supplied_mint: !mintKeypair,
		tx_base64: built.txBase64,
		network: body.network,
		expires_at: expiresAt.toISOString(),
		instructions: mintKeypair
			? 'Decode tx_base64 as VersionedTransaction. Sign with the mint keypair (mint_secret_key_b64) AND the user wallet, submit, then POST /api/native-launch/launch-confirm with the tx_signature.'
			: 'Decode tx_base64 as VersionedTransaction. Sign with your locally-held vanity mint keypair AND the user wallet, submit, then POST /api/native-launch/launch-confirm with the tx_signature.',
	});
}

// ── launch-confirm ─────────────────────────────────────────────────────────

const launchConfirmSchema = z.object({
	prep_id: z.string().min(8),
	tx_signature: z.string().min(80).max(100),
});

async function handleLaunchConfirm(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const user = await getSessionUser(req);
	if (!user) return error(res, 401, 'unauthorized', 'sign in required');

	const rl = await limits.authIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	const body = parse(launchConfirmSchema, await readJson(req));
	const [pending] = await sql`
		select id, payload, metadata_uri from agent_registrations_pending
		where user_id=${user.id} and payload->>'prep_id'=${body.prep_id}
		  and expires_at > now()
		order by created_at desc limit 1
	`;
	if (!pending) return error(res, 404, 'not_found', 'prep not found or expired');
	const p = pending.payload;
	if (p.kind !== 'native_launch') return error(res, 400, 'wrong_kind', 'prep is not a native launch');

	let tx;
	try {
		tx = await verifySignature({ network: p.network, signature: body.tx_signature });
	} catch (e) {
		return error(res, e.status || 422, e.code || 'tx_failed', e.message);
	}
	const accountKeys = tx.transaction.message.accountKeys.map((k) => (k.pubkey || k).toString());
	if (!accountKeys.includes(p.mint)) {
		return error(res, 422, 'mint_not_in_tx', 'mint pubkey not present in tx');
	}
	// The confirmed tx must have run the DBC program itself. A memo/transfer
	// touching the mint account can never be recorded as a launch.
	if (!txInvokesDbcProgram(tx)) {
		return error(res, 422, 'not_a_native_launch', 'transaction did not invoke the bonding-curve program');
	}

	const [existing] = await sql`
		select id from native_launches where mint=${p.mint} and network=${p.network} limit 1
	`;
	if (existing) return error(res, 409, 'conflict', 'mint already registered');

	const [row] = await sql`
		insert into native_launches
			(agent_id, user_id, network, mint, pool, config_key, name, symbol, metadata_uri, creator_address, quote_mint)
		values
			(${p.agent_id}, ${user.id}, ${p.network}, ${p.mint}, ${p.pool}, ${p.config_key},
			 ${p.name}, ${p.symbol}, ${pending.metadata_uri || null}, ${p.creator_address}, ${quoteMintFor(p.network)})
		returning id, mint, pool, network, created_at
	`;

	await sql`delete from agent_registrations_pending where id=${pending.id}`;

	publishFeedEvent({
		type: 'coin-buy',
		ts: Date.now(),
		actor: shortAddr(p.wallet_address),
		mint: p.mint,
		sol: 0,
		network: p.network,
		branded: hasThreeWsMark(p.mint),
		lane: 'native',
	}).catch(() => {});

	return json(res, 201, { ok: true, native_launch: row, tx_signature: body.tx_signature });
}

// ── launches (public directory) ────────────────────────────────────────────

async function handleLaunches(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;
	const rl = await limits.mcpIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	const url = new URL(req.url, `http://${req.headers.host}`);
	const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';
	const agentId = url.searchParams.get('agent_id') || null;
	// agent_id lands in a uuid column: an unvalidated value makes Postgres raise
	// and the request surface as a 500. Same 400 the pump lane returns.
	if (agentId && !isUuid(agentId)) {
		return error(res, 400, 'validation_error', 'agent_id must be a uuid');
	}
	const offset = Math.max(0, parseInt(url.searchParams.get('offset') || '0', 10) || 0);
	const limit = Math.max(1, Math.min(100, parseInt(url.searchParams.get('limit') || '24', 10) || 24));

	const rows = agentId
		? await sql`
				select nl.mint, nl.pool, nl.network, nl.name, nl.symbol, nl.metadata_uri,
				       nl.status, nl.created_at,
				       ai.id as agent_id, ai.name as agent_name,
				       a.thumbnail_key as avatar_thumbnail_key, a.visibility as avatar_visibility
				from native_launches nl
				left join agent_identities ai on ai.id = nl.agent_id and ai.deleted_at is null
				left join avatars a on a.id = ai.avatar_id and a.deleted_at is null
				where nl.network=${network} and nl.agent_id=${agentId}
				order by nl.created_at desc
				limit ${limit + 1} offset ${offset}
			`
		: await sql`
				select nl.mint, nl.pool, nl.network, nl.name, nl.symbol, nl.metadata_uri,
				       nl.status, nl.created_at,
				       ai.id as agent_id, ai.name as agent_name,
				       a.thumbnail_key as avatar_thumbnail_key, a.visibility as avatar_visibility
				from native_launches nl
				left join agent_identities ai on ai.id = nl.agent_id and ai.deleted_at is null
				left join avatars a on a.id = ai.avatar_id and a.deleted_at is null
				where nl.network=${network}
				order by nl.created_at desc
				limit ${limit + 1} offset ${offset}
			`;

	const hasMore = rows.length > limit;
	const launches = rows.slice(0, limit).map((r) => {
		const avatarPublic = r.avatar_visibility === 'public' || r.avatar_visibility === 'unlisted';
		return {
			lane: 'native',
			mint: r.mint,
			pool: r.pool,
			network: r.network,
			name: r.name,
			symbol: r.symbol,
			status: r.status,
			metadata_uri: normalizeGatewayURL(r.metadata_uri) || r.metadata_uri,
			created_at: r.created_at,
			agent: r.agent_id
				? {
						id: r.agent_id,
						name: r.agent_name,
						url: `/agents/${r.agent_id}`,
						avatar_thumbnail_url:
							avatarPublic ? thumbnailUrl(r.avatar_thumbnail_key) : null,
					}
				: null,
		};
	});

	return json(
		res,
		200,
		{ data: { launches, has_more: hasMore, offset, limit, network } },
		{ 'cache-control': 'public, max-age=15' },
	);
}

// ── dispatcher ─────────────────────────────────────────────────────────────

// ── fee-config ─────────────────────────────────────────────────────────────

const feeConfigSchema = z.object({
	fee_schedule: z
		.object({
			mode: z.string().max(24).optional(),
			start_fee_bps: z.number(),
			end_fee_bps: z.number(),
			periods: z.number().optional(),
			duration_slots: z.number().optional(),
		})
		.optional(),
	simulate: z.boolean().default(false),
	wallet_address: z.string().min(32).max(44).optional(),
	network: z.enum(['mainnet', 'devnet']).default('mainnet'),
});

// Validates a candidate fee schedule exactly as the Dynamic Bonding Curve SDK and
// program will (rate-limiter mode is refused), returns its plain-language preview and
// fee curve, and with simulate:true also simulates creating the config plus a pool
// under it. Nothing is signed or sent; omitting fee_schedule previews the live lane.
async function handleFeeConfig(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['POST'])) return;
	const rl = await limits.mcpIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);
	try {
		const body = parse(feeConfigSchema, await readJson(req));
		const preview = await previewFeeConfig(body.fee_schedule);
		const out = {
			network: body.network,
			fee_schedule: preview.schedule,
			preview: preview.preview,
			fee_curve: preview.fee_curve,
			referral: {
				share_of_trading_fee_percent: preview.referral_share_of_trading_fee_percent,
				preview: preview.referral_preview,
			},
		};
		if (body.simulate) {
			out.simulation = await simulateFeeConfig({
				network: body.network,
				schedule: preview.schedule,
				payer: body.wallet_address,
			});
		}
		return json(res, 200, out);
	} catch (e) {
		return error(res, e.status || 500, e.code || 'fee_config_failed', e.message, e.details ? { details: e.details } : undefined);
	}
}

async function dispatch(req, res) {
	const url = new URL(req.url, `http://${req.headers.host}`);
	const action = req.query?.action || url.searchParams.get('action');
	switch (action) {
		case 'config': return handleConfig(req, res);
		case 'quote': return handleQuote(req, res);
		case 'swap-prep': return handleSwapPrep(req, res);
		case 'pool': return handlePool(req, res);
		case 'launch-prep': return handleLaunchPrep(req, res);
		case 'launch-confirm': return handleLaunchConfirm(req, res);
		case 'launches': return handleLaunches(req, res);
		case 'fee-config': return handleFeeConfig(req, res);
		default:
			return error(res, 404, 'not_found', `unknown launchpad action: ${action || '(none)'}`);
	}
}

export default wrap(dispatch);