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.

18.6 KB
Raw Blame
// Launch a fixed-supply coin with a Uniswap V3 pool on Base from an agent's
// custodial EVM wallet.
//
// One transaction to the launcher contract (contracts/src/ThreeWsUniswapLauncher.sol)
// deploys the token, creates its WETH pool, puts the whole supply into a single
// one-sided position and, depending on the lock the creator chose, keeps the
// position in the launcher (timelock, permanent) or hands it to the creator.
// The creator never needs to hold WETH or the coin: the launch costs the
// launcher's flat ETH fee (zero by default) plus gas.
//
// Gate order matches every other custodial spend on the EVM leg (see
// paired-launch.js): the agent belongs to the caller, the agent is in
// platform-signing mode, the spend is checked against the agent's policy on
// Base, the wallet covers fee and gas, the transaction simulates, and only then
// is the key decrypted (with an audit row). The spend is written to the custody
// ledger as pending before the send and settled after the receipt.
//
// quote() and launch() share prepare() so the owner is quoted exactly what is
// signed. The one exception is the deadline, which is a ten minute window
// counted from the moment the transaction is built.

import { encodeFunctionData, formatEther, getAddress, keccak256, parseEventLogs } from 'viem';

import { sql } from '../db.js';
import { publicUrl } from '../r2.js';
import { assertPlatformSigningAllowed } from '../custody/signing.js';
import { recordCustodyEvent, updateCustodyEvent } from '../agent-trade-guards.js';
import { EvmLegError, evmLegPublicClient, evmLegWalletClient, explorerAddress, explorerTx } from './chains.js';
import { checkEvmSpend, enforceEvmSpend, getDailyEvmSpendUsd, getEvmSpendLimits, normalizeEvmAddress } from './guards.js';
import {
	GAS_HEADROOM_BPS, LIMITS, agentAccount, defaultLogo, ethUsd, hostImage, httpsOrNull, loadOwnedAgent, round2, sanitizeName,
	sanitizeSymbol, storeDescriptor,
} from './paired-launch.js';
import { PairedMarketError } from '../paired-markets.js';
import {
	DEFAULT_FEE_TIER, DEFAULT_START_MARKET_CAP_ETH, FEE_TIERS, LOCK_MODES, MAX_LOCK_DAYS, MAX_START_MARKET_CAP_ETH, MIN_LOCK_DAYS,
	MIN_START_MARKET_CAP_ETH, TOTAL_SUPPLY_WHOLE, UNISWAP_CHAIN as CHAIN, UNISWAP_VENUE, launchedEvent, launcherAbi, marketCapEthAt,
	startTickFor, uniswapLaneConfig,
} from './uniswap-config.js';

export { UNISWAP_VENUE };
const LEDGER_CHAIN = { key: CHAIN.slug, name: CHAIN.name };

// Gas a launch costs is dominated by deploying the pool and the token. Used
// only when the wallet cannot run eth_estimateGas (it is empty), so a quote can
// still say how much to fund. Measured on a Base fork at about 5.8M gas with
// either lock mode; this carries headroom over that.
const MEASURED_LAUNCH_GAS = 6_500_000n;
// The launch carries a deadline so a transaction stuck in a mempool cannot land
// long after the owner approved it.
const DEADLINE_SECONDS = 600;
const DESCRIPTOR_PREFIX = 'uniswap/meta';
const DAY_SECONDS = 86_400;

export { LIMITS };

function buildDescriptor({ name, symbol, description, image, links, agent, wallet, fee, lock, startTick }) {
	const descriptor = {
		schemaVersion: '1.0.0',
		name,
		symbol,
		description: description || undefined,
		image: image || undefined,
		links: { website: links.website || undefined, twitter: links.twitter || undefined, telegram: links.telegram || undefined },
		pool: { venue: UNISWAP_VENUE, chainId: CHAIN.chainId, feeTier: fee, startTick, lock: lock.id },
		origin: {
			platform: 'three.ws',
			channel: 'agent',
			agent: { id: agent.id, name: agent.name, url: `https://three.ws/agents/${agent.id}` },
			wallet,
		},
	};
	const bytes = Buffer.from(JSON.stringify(descriptor));
	const hash = keccak256(bytes);
	const key = `${DESCRIPTOR_PREFIX}/${hash.slice(2)}.json`;
	return { descriptor, bytes, hash, key, url: publicUrl(key) };
}

function resolveTier(input) {
	const wanted = input.fee_tier == null ? DEFAULT_FEE_TIER : Number(input.fee_tier);
	const tier = FEE_TIERS.find((t) => t.fee === wanted);
	if (!tier) throw new PairedMarketError(`The pool fee tier must be one of ${FEE_TIERS.map((t) => `${t.bps / 100}%`).join(', ')}.`);
	return tier;
}

function resolveLock(input) {
	const mode = LOCK_MODES.find((m) => m.id === (input.lock?.mode ?? 'none'));
	if (!mode) throw new PairedMarketError(`The lock must be one of ${LOCK_MODES.map((m) => m.id).join(', ')}.`);
	let unlockAt = 0n;
	if (mode.id === 'timelock') {
		const days = Number(input.lock?.unlock_days);
		if (!Number.isFinite(days) || days < MIN_LOCK_DAYS || days > MAX_LOCK_DAYS) {
			throw new PairedMarketError(`A timelock needs unlock_days between ${MIN_LOCK_DAYS} and ${MAX_LOCK_DAYS}.`);
		}
		unlockAt = BigInt(Math.floor(Date.now() / 1000) + Math.round(days * DAY_SECONDS));
	}
	return { ...mode, unlockAt };
}

/**
 * Fee income can be routed to another address, but a third-party address must
 * already be on the agent's EVM allowlist, exactly like a withdrawal. Without
 * it a stolen session could redirect a coin's fees forever.
 */
function resolveFeeRecipient(input, agent, wallet) {
	if (input.fee_recipient == null || String(input.fee_recipient).trim() === '') return wallet;
	const recipient = normalizeEvmAddress(input.fee_recipient);
	if (!recipient) throw new PairedMarketError('The fee recipient is not a valid EVM address.');
	if (recipient === wallet) return wallet;
	const allowed = getEvmSpendLimits(agent.meta).allowlist.some((a) => a.toLowerCase() === recipient.toLowerCase());
	if (!allowed) {
		throw new EvmLegError('recipient_not_allowlisted', `Add ${recipient} to this agent's EVM allowlist before routing fees to it.`, 403);
	}
	return recipient;
}

async function prepare(agent, input) {
	const name = sanitizeName(input.name);
	const symbol = sanitizeSymbol(input.symbol);
	if (!name) throw new PairedMarketError('The coin needs a name.');
	if (symbol.length < 2) throw new PairedMarketError('The ticker needs at least two letters or digits.');
	const description = String(input.description ?? '').trim();
	if (description.length > LIMITS.description) throw new PairedMarketError(`The description must be ${LIMITS.description} characters or fewer.`);
	const links = {
		website: httpsOrNull(input.socials?.website, 'The website link'),
		twitter: httpsOrNull(input.socials?.twitter, 'The X link'),
		telegram: httpsOrNull(input.socials?.telegram, 'The Telegram link'),
	};

	const config = await uniswapLaneConfig();
	if (!config.available) throw new EvmLegError('lane_unavailable', config.unavailable_reason, 503);

	const tier = resolveTier(input);
	const lock = resolveLock(input);
	const marketCapEth = Number(input.start_market_cap_eth ?? DEFAULT_START_MARKET_CAP_ETH);
	if (!Number.isFinite(marketCapEth) || marketCapEth < MIN_START_MARKET_CAP_ETH || marketCapEth > MAX_START_MARKET_CAP_ETH) {
		throw new PairedMarketError(`The starting market cap must be between ${MIN_START_MARKET_CAP_ETH} and ${MAX_START_MARKET_CAP_ETH} ETH.`);
	}
	const startTick = startTickFor(marketCapEth, tier.tickSpacing);
	const address = getAddress(agent.wallet_address);
	const feeRecipient = resolveFeeRecipient(input, agent, address);
	const launchFeeWei = BigInt(config.launchFeeWei);
	const client = evmLegPublicClient(CHAIN);

	const image = input.image_url ? await hostImage(httpsOrNull(input.image_url, 'The logo link')) : defaultLogo(agent);
	const descriptor = buildDescriptor({ name, symbol, description, image, links, agent, wallet: address, fee: tier.fee, lock, startTick });

	const params = {
		name,
		symbol,
		fee: tier.fee,
		startTick,
		creator: address,
		feeRecipient: lock.id === 'none' ? address : feeRecipient,
		lockMode: lock.value,
		unlockAt: lock.unlockAt,
		metadataHash: descriptor.hash,
		metadataURI: descriptor.url,
		deadline: BigInt(Math.floor(Date.now() / 1000) + DEADLINE_SECONDS),
	};
	const data = encodeFunctionData({ abi: launcherAbi, functionName: 'launch', args: [params] });

	const [balanceWei, gasPrice] = await Promise.all([client.getBalance({ address }), client.getGasPrice()]);
	let gas = MEASURED_LAUNCH_GAS;
	let estimated = false;
	if (balanceWei >= launchFeeWei) {
		try {
			gas = await client.estimateGas({ account: address, to: config.launcher, data, value: launchFeeWei });
			estimated = true;
		} catch (err) {
			throw new PairedMarketError(`The launcher would reject this launch: ${err.shortMessage || err.message}`, 422);
		}
	}
	const gasLimit = (gas * GAS_HEADROOM_BPS) / 10_000n;
	const gasWei = gasLimit * gasPrice;
	const totalWei = launchFeeWei + gasWei;
	const blockers = [];
	if (balanceWei < totalWei) blockers.push(`Fund ${address} with at least ${formatEther(totalWei - balanceWei)} more ETH on ${CHAIN.name}.`);
	if (lock.id === 'none' && input.fee_recipient && feeRecipient !== address) {
		blockers.push('Fee routing needs a lock. Without one, the liquidity position and its fees belong to the agent wallet.');
	}
	return {
		name, symbol, description, image, links, config, tier, lock, startTick, marketCapEth: marketCapEthAt(startTick), address, feeRecipient: params.feeRecipient,
		descriptor, params, data, launchFeeWei, balanceWei, gasLimit, gasPrice, gasWei, totalWei, estimated, blockers,
	};
}

/** USD that leaves the agent's control: the launch fee. Gas is network cost. */
function spendUsd(p, price) {
	if (p.launchFeeWei === 0n) return 0;
	return price == null ? null : round2(Number(formatEther(p.launchFeeWei)) * price);
}

function describe(agent, p, price) {
	const feeUsd = spendUsd(p, price);
	const gasUsd = price == null ? null : Number(formatEther(p.gasWei)) * price;
	return {
		lane: 'uniswap',
		chain: CHAIN.slug,
		chain_id: CHAIN.chainId,
		venue: UNISWAP_VENUE,
		launcher: p.config.launcher,
		agent: { id: agent.id, name: agent.name },
		wallet: { address: p.address, balance_eth: formatEther(p.balanceWei), explorer: explorerAddress(CHAIN, p.address) },
		coin: {
			name: p.name,
			symbol: p.symbol,
			description: p.description || null,
			image_url: p.image || null,
			socials: p.links,
			total_supply: TOTAL_SUPPLY_WHOLE.toString(),
			metadata_uri: p.descriptor.url,
			metadata_hash: p.descriptor.hash,
		},
		pool: {
			quote_asset: 'WETH',
			fee_tier_bps: p.tier.bps,
			start_tick: p.startTick,
			start_market_cap_eth: Number(p.marketCapEth.toPrecision(6)),
			supply_in_pool_pct: 100,
			opening_liquidity: 'The whole supply, one-sided. No ETH is needed to open the pool.',
		},
		lock: {
			mode: p.lock.id,
			label: p.lock.label,
			unlock_at: p.lock.unlockAt ? new Date(Number(p.lock.unlockAt) * 1000).toISOString() : null,
			fee_recipient: p.feeRecipient,
		},
		// Every fee, in the order the owner pays or earns it.
		fees: [
			{ id: 'launch', label: 'Launch fee', paid_by: 'creator', eth: formatEther(p.launchFeeWei), usd: feeUsd },
			{ id: 'gas', label: 'Gas', paid_by: 'creator', eth: formatEther(p.gasWei), usd: gasUsd == null ? null : round2(gasUsd), estimated: p.estimated },
			{ id: 'pool_fee', label: 'Pool trading fee', paid_by: 'traders', bps: p.tier.bps, note: 'Accrues to the liquidity position.' },
			{
				id: 'platform_share',
				label: 'Platform share of collected pool fees',
				paid_by: 'taken from the position\'s fees',
				bps: p.config.platformShareBps,
				note: p.lock.id === 'none' ? 'Not charged: an unlocked position is yours and its fees never pass through the launcher.' : 'Taken when fees are collected from the locked position.',
			},
		],
		creator_share_bps: p.lock.id === 'none' ? 10_000 : 10_000 - p.config.platformShareBps,
		cost: {
			launch_fee_eth: formatEther(p.launchFeeWei),
			gas_eth: formatEther(p.gasWei),
			gas_estimated: p.estimated,
			total_eth: formatEther(p.totalWei),
			total_usd: feeUsd != null && gasUsd != null ? round2(feeUsd + gasUsd) : null,
			eth_usd: price,
		},
		ready: p.blockers.length === 0,
		blockers: p.blockers,
	};
}

/** Price, policy and funding check for a Uniswap launch, without signing anything. */
export async function quoteUniswapLaunch({ agentId, userId, input }) {
	const agent = await loadOwnedAgent(agentId, userId);
	const [p, price] = await Promise.all([prepare(agent, input), ethUsd()]);
	const out = describe(agent, p, price);
	const limits = getEvmSpendLimits(agent.meta);
	const spentTodayUsd = await getDailyEvmSpendUsd(agentId, LEDGER_CHAIN.key);
	const blocked = checkEvmSpend({ limits, usdValue: spendUsd(p, price), spentTodayUsd, category: 'launch', chainName: CHAIN.name });
	if (blocked) {
		out.blockers.push(blocked.message);
		out.ready = false;
	}
	out.policy = { per_tx_usd: limits.per_tx_usd, daily_usd: limits.daily_usd, spent_today_usd: spentTodayUsd };
	return out;
}

const noStage = async () => {};

/**
 * Sign and send a Uniswap launch from the agent's custodial wallet. `stage`
 * reports progress to the launch record (api/_lib/evm-launch-records.js).
 */
export async function launchUniswap({ agentId, userId, input, req = null, stage = noStage }) {
	await assertPlatformSigningAllowed(agentId);
	const agent = await loadOwnedAgent(agentId, userId);
	const [p, price] = await Promise.all([prepare(agent, input), ethUsd()]);
	if (p.blockers.length) throw new EvmLegError('launch_blocked', p.blockers.join(' '), 409, { blockers: p.blockers });

	const usd = spendUsd(p, price);
	await enforceEvmSpend({ agentId, meta: agent.meta, chain: LEDGER_CHAIN, usdValue: usd, category: 'launch' });
	await storeDescriptor(p.descriptor);
	await stage('policy_checked', { detail: { spend_usd: usd } });

	const custodyId = await recordCustodyEvent({
		agentId,
		userId,
		eventType: 'spend',
		category: 'launch',
		chain: CHAIN.slug,
		network: CHAIN.slug,
		asset: 'ETH',
		amountRaw: p.launchFeeWei.toString(),
		usd,
		destination: p.config.launcher,
		reason: 'uniswap.launch',
		status: 'pending',
		meta: { venue: UNISWAP_VENUE, name: p.name, symbol: p.symbol, fee_tier_bps: p.tier.bps, lock: p.lock.id },
	});
	const context = {
		custody_id: custodyId,
		agent_id: agentId,
		user_id: userId,
		name: p.name,
		symbol: p.symbol,
		image: p.image || null,
		description: p.description || null,
		wallet: p.address,
		launcher: p.config.launcher,
		fee_tier_bps: p.tier.bps,
		lock: p.lock.id,
		unlock_at: p.lock.unlockAt ? Number(p.lock.unlockAt) : null,
		fee_recipient: p.feeRecipient,
		start_market_cap_eth: Number(p.marketCapEth.toPrecision(6)),
		spend_usd: usd,
		launch_fee_wei: p.launchFeeWei.toString(),
		metadata_url: p.descriptor.url,
	};
	await stage('reserved', { context });

	let account;
	try {
		account = await agentAccount(agent, userId, 'uniswap.launch', { symbol: p.symbol, chain: CHAIN.slug });
	} catch (err) {
		await updateCustodyEvent(custodyId, { status: 'failed', meta: { error: err.code || 'key_recover_failed' } });
		throw err;
	}
	const client = evmLegPublicClient(CHAIN);
	let hash;
	try {
		hash = await evmLegWalletClient(CHAIN, account).sendTransaction({ to: p.config.launcher, data: p.data, value: p.launchFeeWei, gas: p.gasLimit });
	} catch (err) {
		await updateCustodyEvent(custodyId, { status: 'failed', meta: { error: String(err.shortMessage || err.message).slice(0, 300) } });
		throw new EvmLegError('send_failed', `The launch was not sent: ${err.shortMessage || err.message}`, 502);
	}
	await stage('submitted', { status: 'submitted', txHash: hash, detail: { explorer: explorerTx(CHAIN, hash) } });

	const receipt = await client.waitForTransactionReceipt({ hash, timeout: 60_000 });
	return finishUniswap({ context, hash, receipt, stage, req });
}

/** Read the new coin off a mined launch, settle the custody row and list the coin. */
async function finishUniswap({ context, hash, receipt, stage = noStage, req = null }) {
	const { custody_id: custodyId, agent_id: agentId, user_id: userId } = context;
	if (receipt.status !== 'success') {
		await updateCustodyEvent(custodyId, { status: 'failed', signature: hash, meta: { error: 'reverted' } });
		throw new EvmLegError('launch_reverted', 'The launch transaction reverted on chain. Only gas was spent.', 502, { tx_hash: hash, explorer: explorerTx(CHAIN, hash) });
	}
	const [launched] = parseEventLogs({ abi: [launchedEvent], logs: receipt.logs, eventName: 'Launched' });
	if (!launched) {
		await updateCustodyEvent(custodyId, { status: 'failed', signature: hash, meta: { error: 'no_launch_event' } });
		throw new EvmLegError('launch_unreadable', 'The transaction landed but emitted no launch.', 502, { tx_hash: hash });
	}
	const token = getAddress(launched.args.token);
	const pool = getAddress(launched.args.pool);
	const positionId = launched.args.tokenId.toString();
	await updateCustodyEvent(custodyId, { status: 'confirmed', signature: hash, meta: { token, pool } });
	await stage('confirmed', { status: 'confirmed', token, detail: { block: Number(receipt.blockNumber), pool, position_id: positionId } });

	await sql`
		INSERT INTO fixed_supply_launches
			(agent_id, user_id, network, chain, venue, mint, name, symbol, image_url, description,
			 creator_address, token_allocation, signatures, venue_url)
		VALUES
			(${agentId}, ${userId}, 'mainnet', ${CHAIN.slug}, ${UNISWAP_VENUE}, ${token},
			 ${context.name}, ${context.symbol}, ${context.image}, ${context.description},
			 ${context.wallet}, ${TOTAL_SUPPLY_WHOLE.toString()}, ${JSON.stringify([hash])}::jsonb,
			 ${explorerAddress(CHAIN, token)})
		ON CONFLICT (mint, network) DO NOTHING
	`.catch((e) => console.error('[uniswap/launch] directory insert failed', e?.message));

	import('../audit.js')
		.then(({ logAudit }) => logAudit({ userId, action: 'agent.uniswap_launch', resourceId: agentId, meta: { token, pool, tx: hash }, req }))
		.catch(() => {});

	return {
		lane: 'uniswap',
		chain: CHAIN.slug,
		chain_id: CHAIN.chainId,
		venue: UNISWAP_VENUE,
		token,
		pool,
		position_id: positionId,
		name: context.name,
		symbol: context.symbol,
		fee_tier_bps: context.fee_tier_bps,
		lock: context.lock,
		unlock_at: context.unlock_at ? new Date(context.unlock_at * 1000).toISOString() : null,
		fee_recipient: context.fee_recipient,
		tx_hash: hash,
		block: Number(receipt.blockNumber),
		gas_used: receipt.gasUsed.toString(),
		spent_eth: formatEther(BigInt(context.launch_fee_wei) + receipt.gasUsed * receipt.effectiveGasPrice),
		spent_usd: context.spend_usd,
		urls: { token: explorerAddress(CHAIN, token), pool: explorerAddress(CHAIN, pool), explorer: explorerTx(CHAIN, hash), metadata: context.metadata_url },
	};
}

/**
 * Finish a record whose transaction was sent but whose request never saw the
 * receipt. Returns null while the transaction is unmined, { result } when the
 * coin exists, or { error } when the launch reverted.
 */
export async function settleUniswapLaunch(row) {
	const receipt = await evmLegPublicClient(CHAIN).getTransactionReceipt({ hash: row.tx_hash }).catch(() => null);
	if (!receipt) return null;
	try {
		return { result: await finishUniswap({ context: row.context, hash: row.tx_hash, receipt }) };
	} catch (err) {
		return { error: { code: err.code || 'launch_failed', message: err.message, ...(err.detail ? { detail: err.detail } : {}) } };
	}
}