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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// Launch a paired coin on Robinhood Chain from an agent's custodial EVM wallet.
//
// A paired coin trades against one to five quote assets at once (tokenized
// stocks, WETH, stablecoins, chain coins), each in its own bonding curve on the
// paired launchpad (api/_lib/paired-launchpad.js, contracts/paired-launchpad/).
// The launch costs only the flat ETH fee plus gas: every curve starts from a
// virtual reserve, so the agent never needs to hold the assets it pairs with.
// An optional opening buy spends one of those assets in the same transaction.
//
// The gates match every other custodial spend on the EVM leg (see
// pons-launch.js), in order: the agent belongs to the caller, the agent is in
// platform-signing mode, the launch is priced in USD and checked against the
// agent's spend policy on Robinhood Chain, the wallet covers fee, buy and gas,
// and the transaction simulates. 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(), and the coin's descriptor is stored
// content-addressed (its URL is derived from the keccak256 of its bytes, the
// same hash the contract commits on chain), so what the owner is quoted is
// byte for byte what the agent signs.
import { createHash } from 'node:crypto';
import { encodeFunctionData, formatEther, formatUnits, getAddress, keccak256, parseEventLogs } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { sql } from '../db.js';
import { headObject, publicUrl, putObject, thumbnailUrl } from '../r2.js';
import { fetchUpstreamPublic } from '../upstream-fetch.js';
import { getOrCreateAgentEvmWallet, recoverAgentKey } from '../agent-wallet.js';
import { assertPlatformSigningAllowed } from '../custody/signing.js';
import { recordCustodyEvent, updateCustodyEvent } from '../agent-trade-guards.js';
import { fetchCoinPriceUsd } from '../market-fallbacks.js';
import {
BPS,
TOTAL_SUPPLY,
TOKEN_DECIMALS,
NO_DEV_BUY,
claimableFees,
erc20Abi,
launchedEvent,
launchpadAbi,
launchpadAddress,
launchpadConfig,
quoteRegistry,
} from '../paired-launchpad.js';
import { PairedMarketError, parseQuoteAmount, resolveAllocations } from '../paired-markets.js';
import { pairedCoinUrl } from '../paired-directory.js';
import { EVM_LEG_CHAINS, EvmLegError, evmLegPublicClient, evmLegWalletClient, explorerAddress, explorerTx, nativePriceId } from './chains.js';
import { enforceEvmSpend, getDailyEvmSpendUsd, getEvmSpendLimits, checkEvmSpend } from './guards.js';
const CHAIN = EVM_LEG_CHAINS.robinhood;
const LEDGER_CHAIN = { key: CHAIN.slug, name: CHAIN.name };
export const PAIRED_VENUE = 'paired';
// Gas the launchpad's launch() consumed on mainnet: 0.94M (2 markets) to 1.30M
// (5 markets) across the first launches on 0x6a54...fa15. Used only when the
// wallet cannot run eth_estimateGas (empty, or the opening buy is not yet
// approved), so a quote can still say how much to fund.
const MEASURED_LAUNCH_GAS = 1_450_000n;
const MEASURED_APPROVE_GAS = 60_000n;
export const GAS_HEADROOM_BPS = 13_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;
export const LIMITS = Object.freeze({ name: 32, symbol: 10, description: 480, link: 200, image: 512 });
const DESCRIPTOR_PREFIX = 'paired/meta';
const IMAGE_PREFIX = 'paired/images';
const MAX_IMAGE_BYTES = 4 * 1024 * 1024;
const IMAGE_TYPES = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp', 'image/gif': 'gif' };
export async function loadOwnedAgent(agentId, userId) {
const [row] = await sql`
SELECT ai.id, ai.user_id, ai.name, ai.wallet_address, ai.meta, a.thumbnail_key, a.visibility
FROM agent_identities ai
LEFT JOIN avatars a ON a.id = ai.avatar_id AND a.deleted_at IS NULL
WHERE ai.id = ${agentId} AND ai.deleted_at IS NULL
LIMIT 1
`;
if (!row) throw new EvmLegError('not_found', 'agent not found', 404);
if (row.user_id !== userId) throw new EvmLegError('forbidden', 'not your agent', 403);
if (!row.wallet_address || !row.meta?.encrypted_wallet_key) {
// Older agents predate the EVM leg; provision it now so the quote can
// name the address to fund instead of refusing.
const { address } = await getOrCreateAgentEvmWallet(agentId);
const [fresh] = await sql`SELECT meta FROM agent_identities WHERE id = ${agentId}`;
return { ...row, wallet_address: address, meta: fresh?.meta || row.meta };
}
return row;
}
export function sanitizeSymbol(raw) {
return String(raw ?? '').toUpperCase().replace(/[^A-Z0-9]/g, '').slice(0, LIMITS.symbol);
}
export function sanitizeName(raw) {
return String(raw ?? '').replace(/[\p{Cc}\p{Cf}]/gu, ' ').replace(/\s+/g, ' ').trim().slice(0, LIMITS.name);
}
export function httpsOrNull(value, label) {
const text = String(value ?? '').trim();
if (!text) return null;
let url;
try {
url = new URL(text);
} catch {
throw new PairedMarketError(`${label} is not a valid URL.`);
}
if (url.protocol !== 'https:') throw new PairedMarketError(`${label} must use https.`);
return url.toString();
}
/** The agent's avatar thumbnail, when public, as a default coin logo. */
export function defaultLogo(agent) {
if (agent.visibility !== 'public' && agent.visibility !== 'unlisted') return null;
const url = agent.thumbnail_key ? thumbnailUrl(agent.thumbnail_key) : null;
return url && url.startsWith('https://') ? url : null;
}
/**
* Copy a logo onto our own storage under the sha256 of its bytes, so the
* artwork a coin commits to can never change or disappear, and so the same
* image always yields the same URL (which keeps the descriptor hash stable
* between quote and launch).
*/
export async function hostImage(url) {
// The logo link is user-supplied and the bytes are republished from our
// bucket, so every redirect hop is SSRF-checked.
const resp = await fetchUpstreamPublic(url, {}, { name: 'paired:logo', timeoutMs: 15_000, attempts: 2, okWhen: (r) => r.ok });
const type = String(resp.headers.get('content-type') || '').split(';')[0].trim().toLowerCase();
const ext = IMAGE_TYPES[type];
if (!ext) throw new PairedMarketError('The logo must be a PNG, JPEG, WebP or GIF image.');
const bytes = Buffer.from(await resp.arrayBuffer());
if (bytes.byteLength > MAX_IMAGE_BYTES) throw new PairedMarketError('The logo must be under 4 MB.');
const key = `${IMAGE_PREFIX}/${createHash('sha256').update(bytes).digest('hex')}.${ext}`;
if (!(await headObject(key).catch(() => null))) await putObject({ key, body: bytes, contentType: type });
return publicUrl(key);
}
/**
* The coin's descriptor, as the exact bytes the launchpad commits to. No
* timestamps and a fixed key order, so identical inputs give identical bytes.
* `origin` binds the coin to the agent that launched it; the creator address
* the contract records is that agent's wallet, which is what makes it checkable.
*/
function buildDescriptor({ name, symbol, description, image, links, agent, wallet, allocations }) {
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,
},
pairs: allocations.map((a) => ({ quoteToken: a.quoteToken, symbol: a.symbol, weightBps: a.weightBps })),
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) };
}
export async function storeDescriptor(d) {
if (await headObject(d.key).catch(() => null)) return;
await putObject({ key: d.key, body: d.bytes, contentType: 'application/json' });
}
/**
* Tokens an opening buy receives from a fresh pool: the contract's own math,
* fee first, then constant product with the remaining reserve rounded UP so the
* amount out rounds down, exactly as PairedLaunchpad._tokensOut does.
*/
export function openingBuyTokens({ virtualQuote, virtualToken, quoteIn, swapFeeBps }) {
const fee = (quoteIn * BigInt(swapFeeBps)) / BigInt(BPS);
const k = virtualQuote * virtualToken;
const newQuote = virtualQuote + quoteIn - fee;
return virtualToken - (k === 0n ? 0n : (k - 1n) / newQuote + 1n);
}
/**
* The allocation the last market receives absorbs the division dust, exactly as
* the contract assigns it, so the opening-buy math sees the real pool size.
*/
function poolSize(allocations, index) {
if (index < allocations.length - 1) return (TOTAL_SUPPLY * BigInt(allocations[index].weightBps)) / BigInt(BPS);
const assigned = allocations.slice(0, -1).reduce((sum, a) => sum + (TOTAL_SUPPLY * BigInt(a.weightBps)) / BigInt(BPS), 0n);
return TOTAL_SUPPLY - assigned;
}
export async function ethUsd() {
const id = nativePriceId(CHAIN);
if (!id) return null;
try {
return await fetchCoinPriceUsd(id);
} catch {
return null;
}
}
export const round2 = (n) => Math.round(n * 100) / 100;
/**
* Everything a launch needs except the signature. Shared by quote and launch
* so the owner is shown exactly what is sent.
*/
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 [allocations, config, registry] = await Promise.all([
resolveAllocations(input.markets, input.weights),
launchpadConfig(),
quoteRegistry(),
]);
const launchFeeWei = BigInt(config.launchFeeWei);
const address = getAddress(agent.wallet_address);
const lp = launchpadAddress();
const client = evmLegPublicClient(CHAIN);
// Optional opening buy, in one of the coin's own markets.
let devBuy = null;
if (input.dev_buy && input.dev_buy.amount != null && String(input.dev_buy.amount).trim() !== '' && Number(input.dev_buy.amount) !== 0) {
const want = String(input.dev_buy.market ?? allocations[0].symbol).trim().replace(/^\$/, '').toLowerCase();
const index = allocations.findIndex((a) => a.symbol.toLowerCase() === want || a.quoteToken.toLowerCase() === want);
if (index === -1) throw new PairedMarketError('The opening buy must be in one of the markets the coin pairs with.');
const market = allocations[index];
const quoteIn = parseQuoteAmount(input.dev_buy.amount, market.decimals);
const full = registry.find((q) => q.address.toLowerCase() === market.quoteToken.toLowerCase());
const tokensOut = openingBuyTokens({
virtualQuote: (BigInt(full.virtualQuoteRaw) * BigInt(market.weightBps)) / BigInt(BPS),
virtualToken: poolSize(allocations, index),
quoteIn,
swapFeeBps: config.swapFeeBps,
});
const [balance, allowance] = await Promise.all([
client.readContract({ address: market.quoteToken, abi: erc20Abi, functionName: 'balanceOf', args: [address] }),
client.readContract({ address: market.quoteToken, abi: erc20Abi, functionName: 'allowance', args: [address, lp] }),
]);
devBuy = { index, market, quoteIn, tokensOut, balance, needsApproval: allowance < quoteIn };
}
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, allocations });
const params = {
name,
symbol,
metadataURI: descriptor.url,
metadataHash: descriptor.hash,
allocations: allocations.map((a) => ({ quoteToken: a.quoteToken, weightBps: a.weightBps })),
creatorFeeRecipient: address,
devBuyMarket: devBuy ? devBuy.index : NO_DEV_BUY,
devBuyQuoteIn: devBuy ? devBuy.quoteIn : 0n,
// Atomic with the launch, so no one can trade the curve first: the
// exact fill is pinned, and a registry change between quote and send
// reverts the launch instead of silently filling worse.
devBuyMinTokensOut: devBuy ? devBuy.tokensOut : 0n,
deadline: BigInt(Math.floor(Date.now() / 1000) + DEADLINE_SECONDS),
};
const data = encodeFunctionData({ abi: launchpadAbi, functionName: 'launch', args: [params] });
const [balanceWei, gasPrice] = await Promise.all([client.getBalance({ address }), client.getGasPrice()]);
let gas = MEASURED_LAUNCH_GAS;
let estimated = false;
const canSimulate = balanceWei >= launchFeeWei && (!devBuy || (!devBuy.needsApproval && devBuy.balance >= devBuy.quoteIn));
if (canSimulate) {
try {
gas = await client.estimateGas({ account: address, to: lp, data, value: launchFeeWei });
estimated = true;
} catch (err) {
throw new PairedMarketError(`The launchpad would reject this launch: ${err.shortMessage || err.message}`, 422);
}
}
const gasLimit = (gas * GAS_HEADROOM_BPS) / 10_000n;
const approveGas = devBuy?.needsApproval ? (MEASURED_APPROVE_GAS * GAS_HEADROOM_BPS) / 10_000n : 0n;
const gasWei = (gasLimit + approveGas) * gasPrice;
const totalWei = launchFeeWei + gasWei;
const blockers = [];
if (balanceWei < totalWei) {
blockers.push(`Fund ${address} with at least ${formatEther(totalWei - balanceWei)} more ETH on Robinhood Chain.`);
}
if (devBuy && devBuy.balance < devBuy.quoteIn) {
blockers.push(
`The opening buy needs ${formatUnits(devBuy.quoteIn - devBuy.balance, devBuy.market.decimals)} more ${devBuy.market.symbol} in ${address}.`,
);
}
return {
name, symbol, description, image, links, allocations, config, address, descriptor, params, data,
launchFeeWei, devBuy, balanceWei, gasLimit, approveGas, gasPrice, gasWei, totalWei, estimated, blockers,
};
}
/** USD that leaves the agent's control: the fee and the opening buy. Gas is network cost. */
function spendUsd(p, price) {
if (price == null) return null;
let usd = Number(formatEther(p.launchFeeWei)) * price;
if (p.devBuy) {
if (p.devBuy.market.priceUsd == null) return null;
usd += Number(formatUnits(p.devBuy.quoteIn, p.devBuy.market.decimals)) * p.devBuy.market.priceUsd;
}
return round2(usd);
}
function describe(agent, p, price) {
return {
chain: CHAIN.slug,
chain_id: CHAIN.chainId,
venue: PAIRED_VENUE,
launchpad: launchpadAddress(),
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: formatUnits(TOTAL_SUPPLY, TOKEN_DECIMALS),
metadata_uri: p.descriptor.url,
metadata_hash: p.descriptor.hash,
},
pairs: p.allocations.map((a) => ({
quote_token: a.quoteToken,
symbol: a.symbol,
asset_class: a.assetClass,
canonical: a.canonical,
weight_pct: a.weightBps / 100,
supply: formatUnits((TOTAL_SUPPLY * BigInt(a.weightBps)) / BigInt(BPS), TOKEN_DECIMALS),
opening_value_usd: a.openingValueUsd != null ? round2(a.openingValueUsd) : null,
})),
terms: {
launch_fee_eth: p.config.launchFeeEth,
swap_fee_bps: p.config.swapFeeBps,
creator_share_bps: p.config.creatorShareBps,
},
opening_buy: p.devBuy
? {
market: p.devBuy.market.symbol,
amount: formatUnits(p.devBuy.quoteIn, p.devBuy.market.decimals),
tokens: formatUnits(p.devBuy.tokensOut, TOKEN_DECIMALS),
pct_of_supply: Number((p.devBuy.tokensOut * 1_000_000n) / TOTAL_SUPPLY) / 10_000,
needs_approval: p.devBuy.needsApproval,
}
: null,
cost: {
launch_fee_eth: formatEther(p.launchFeeWei),
gas_eth: formatEther(p.gasWei),
gas_estimated: p.estimated,
total_eth: formatEther(p.totalWei),
total_usd: spendUsd(p, price) != null && price != null ? round2(spendUsd(p, price) + Number(formatEther(p.gasWei)) * price) : null,
eth_usd: price,
},
ready: p.blockers.length === 0,
blockers: p.blockers,
};
}
/** Price, policy and funding check for a paired launch, without signing anything. */
export async function quotePairedLaunch({ 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;
}
export async function agentAccount(agent, userId, reason, meta) {
const pk = await recoverAgentKey(agent.meta.encrypted_wallet_key, { agentId: agent.id, userId, reason, meta: { chain: CHAIN.slug, ...meta } });
const account = privateKeyToAccount(pk);
if (getAddress(account.address) !== getAddress(agent.wallet_address)) {
throw new EvmLegError('wallet_mismatch', 'The stored key does not match this agent\'s wallet address.', 500);
}
return account;
}
const noStage = async () => {};
/**
* Sign and send a paired launch from the agent's custodial wallet. Returns the
* new coin, its pairs, the transaction and the opening fill. `stage` reports
* progress to the launch record (api/_lib/evm-launch-records.js).
*/
export async function launchPaired({ 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: launchpadAddress(),
reason: 'paired.launch',
status: 'pending',
meta: {
venue: PAIRED_VENUE,
name: p.name,
symbol: p.symbol,
pairs: p.allocations.map((a) => `${a.symbol}:${a.weightBps}`),
opening_buy: p.devBuy ? { market: p.devBuy.market.quoteToken, raw: p.devBuy.quoteIn.toString() } : null,
},
});
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,
pairs: p.allocations.map((a) => ({ quote_token: a.quoteToken, symbol: a.symbol, weight_pct: a.weightBps / 100 })),
spend_usd: usd,
launch_fee_wei: p.launchFeeWei.toString(),
metadata_url: p.descriptor.url,
opening_buy: p.devBuy
? { market: p.devBuy.market.symbol, amount: formatUnits(p.devBuy.quoteIn, p.devBuy.market.decimals), tokens: formatUnits(p.devBuy.tokensOut, TOKEN_DECIMALS) }
: null,
};
await stage('reserved', { context });
let account;
try {
account = await agentAccount(agent, userId, 'paired.launch', { symbol: p.symbol });
} catch (err) {
await updateCustodyEvent(custodyId, { status: 'failed', meta: { error: err.code || 'key_recover_failed' } });
throw err;
}
const wallet = evmLegWalletClient(CHAIN, account);
const client = evmLegPublicClient(CHAIN);
let hash;
try {
if (p.devBuy?.needsApproval) {
// Exactly the opening buy, never an unlimited approval.
const approveHash = await wallet.writeContract({
address: p.devBuy.market.quoteToken,
abi: erc20Abi,
functionName: 'approve',
args: [launchpadAddress(), p.devBuy.quoteIn],
gas: p.approveGas,
});
const approval = await client.waitForTransactionReceipt({ hash: approveHash, timeout: 60_000 });
if (approval.status !== 'success') throw new Error(`the ${p.devBuy.market.symbol} approval reverted`);
await stage('approved', { detail: { tx_hash: approveHash } });
}
hash = await wallet.sendTransaction({ to: launchpadAddress(), 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 finishPaired({ context, hash, receipt, stage, req });
}
/**
* Turn a mined launch transaction into the finished result: read the new coin
* off the receipt, settle the custody row, list the coin in the directory.
* Shared by the request that sent the launch and by settlePairedLaunch(), which
* finishes a launch whose request went away before the receipt arrived.
*/
async function finishPaired({ 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);
await updateCustodyEvent(custodyId, { status: 'confirmed', signature: hash, meta: { token } });
await stage('confirmed', { status: 'confirmed', token, detail: { block: Number(receipt.blockNumber) } });
const coinPath = pairedCoinUrl(token);
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}, ${PAIRED_VENUE}, ${token},
${context.name}, ${context.symbol}, ${context.image}, ${context.description},
${context.wallet}, ${(TOTAL_SUPPLY / 10n ** 18n).toString()}, ${JSON.stringify([hash])}::jsonb,
${`https://three.ws${coinPath}`})
ON CONFLICT (mint, network) DO NOTHING
`.catch((e) => console.error('[paired/launch] directory insert failed', e?.message));
import('../audit.js')
.then(({ logAudit }) => logAudit({ userId, action: 'agent.paired_launch', resourceId: agentId, meta: { token, tx: hash }, req }))
.catch(() => {});
return {
chain: CHAIN.slug,
chain_id: CHAIN.chainId,
venue: PAIRED_VENUE,
token,
name: context.name,
symbol: context.symbol,
pairs: context.pairs,
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,
opening_buy: context.opening_buy,
urls: { coin: coinPath, 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 still unmined, { result } when
* the coin exists, or { error } when the launch reverted.
*/
export async function settlePairedLaunch(row) {
const receipt = await evmLegPublicClient(CHAIN)
.getTransactionReceipt({ hash: row.tx_hash })
.catch(() => null);
if (!receipt) return null;
try {
return { result: await finishPaired({ 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 } : {}) } };
}
}
/** Swap fees this agent's wallet has earned as a paired-coin creator, per quote asset. */
export async function pairedFeesFor({ agentId, userId }) {
const agent = await loadOwnedAgent(agentId, userId);
const address = getAddress(agent.wallet_address);
return { wallet: address, claimable: await claimableFees(address) };
}
/**
* Claim every quote asset the agent has earned in, in one transaction. Moves
* funds INTO the agent's wallet, so no spend ceiling applies; the signature is
* still custodial and audited.
*/
export async function claimPairedFees({ agentId, userId, req = null }) {
await assertPlatformSigningAllowed(agentId);
const agent = await loadOwnedAgent(agentId, userId);
const address = getAddress(agent.wallet_address);
const owed = await claimableFees(address);
if (!owed.length) throw new EvmLegError('nothing_to_claim', 'This agent has no paired-coin fees to claim yet.', 409);
const client = evmLegPublicClient(CHAIN);
const data = encodeFunctionData({ abi: launchpadAbi, functionName: 'claimFees', args: [owed.map((o) => o.quoteToken)] });
const [balanceWei, gasPrice, gas] = await Promise.all([
client.getBalance({ address }),
client.getGasPrice(),
client.estimateGas({ account: address, to: launchpadAddress(), data }).catch((err) => {
throw new EvmLegError('simulation_failed', `The claim would fail: ${err.shortMessage || err.message}`, 422);
}),
]);
const gasLimit = (gas * GAS_HEADROOM_BPS) / 10_000n;
if (balanceWei < gasLimit * gasPrice) {
throw new EvmLegError('needs_gas', `Fund ${address} with at least ${formatEther(gasLimit * gasPrice - balanceWei)} ETH on Robinhood Chain to pay the claim's gas.`, 409);
}
const account = await agentAccount(agent, userId, 'paired.claim_fees', { assets: owed.length });
const hash = await evmLegWalletClient(CHAIN, account).sendTransaction({ to: launchpadAddress(), data, gas: gasLimit });
const receipt = await client.waitForTransactionReceipt({ hash, timeout: 60_000 });
if (receipt.status !== 'success') {
throw new EvmLegError('claim_reverted', 'The claim reverted on chain. Only gas was spent.', 502, { tx_hash: hash, explorer: explorerTx(CHAIN, hash) });
}
await recordCustodyEvent({
agentId,
userId,
eventType: 'receive',
category: 'fees',
chain: CHAIN.slug,
network: CHAIN.slug,
signature: hash,
reason: 'paired.claim_fees',
status: 'confirmed',
meta: { venue: PAIRED_VENUE, claimed: owed },
}).catch((e) => console.error('[paired/claim] custody row failed', e?.message));
import('../audit.js')
.then(({ logAudit }) => logAudit({ userId, action: 'agent.paired_claim_fees', resourceId: agentId, meta: { tx: hash, assets: owed.length }, req }))
.catch(() => {});
return { wallet: address, claimed: owed, tx_hash: hash, explorer: explorerTx(CHAIN, hash) };
}