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
// Funded launch intents: a quoted pump.fun launch that is paid for, confirmed
// and executed in separate, checkable steps.
//
// The flow, one row in `pump_funded_launch_intents` per launch:
//
// quote POST /api/pump/launch-intents. Any credential (session or
// bearer) may create one. The response carries every fee line,
// the quote's expiry, the agent wallet that has to be funded and
// a one-time preflight token.
// paid POST /api/pump/launch-intents/:id/pay from a same-site session.
// The proof is the funding transaction's signature plus the
// preflight token. It is accepted once; the same signature replays
// the stored result, a different one is refused.
// (approval) POST /api/pump/launch-intents/:id/confirm from a same-site
// session queues the spend from the agent wallet as an approval
// request (recipient, amount, asset, chain, explicit yes). The
// approval executor is the only code that signs the launch.
// submitted The executor broadcast the create transaction.
// confirmed The transaction is confirmed on-chain.
// indexed The bonding curve account is readable.
//
// A bearer token can create an intent and poll it. It can never pay, confirm
// or sign: the handler enforces that, and the executor runs only from an
// approved request the owner answered in the browser or a paired chat.
//
// The dry run simulates the exact launch transaction on the intent's network
// with a throwaway mint and never broadcasts, so a devnet intent exercises the
// whole lane without touching mainnet.
import { Keypair, PublicKey, TransactionMessage, VersionedTransaction } from '@solana/web3.js';
import { sql } from './db.js';
import { env } from './env.js';
import { randomToken, sha256, constantTimeEquals } from './crypto.js';
import { encryptSecret, decryptSecret } from './secret-box.js';
import { logAudit } from './audit.js';
import { logger } from './usage.js';
import { findLaunchPair, earningsProjection } from './pump-launch-pairs.js';
import { getPumpSdk, solanaPubkey, verifySignature, getConnection } from './pump.js';
import { WSOL_MINT, walletQuoteDeltaAtomics } from './pump-quote.js';
import { pumpLaunchFeeBps, pumpFeeAtomics, pumpFeeRecipient, buildPlatformFeeInstructions } from './pump-platform-fee.js';
import { FIXED_LAUNCH_COST_SOL } from './agent-token-plan.js';
import { getOrCreateAgentSolanaWallet, getSolanaAddressBalances } from './agent-wallet.js';
import { createApprovalRequest } from './approvals.js';
import { solPriceUsd } from './sol-price.js';
import { THREE_WS_VANITY, hasThreeWsMark } from '../../src/solana/vanity/brand.js';
import { grindVanityNode, GrindExhaustedError } from '../../src/solana/vanity/grinder-node.js';
const log = logger('pump-funded-launch');
export const QUOTE_TTL_MS = 15 * 60 * 1000;
export const STAGES = Object.freeze(['quote', 'paid', 'submitted', 'confirmed', 'indexed']);
export const TERMINAL_STAGES = Object.freeze(['failed', 'expired']);
const LAMPORTS = 1_000_000_000;
const MAX_INITIAL_BUY = Object.freeze({ sol: 100, stable: 250_000, exotic: 1_000_000 });
export class FundedLaunchError extends Error {
constructor(status, code, message, extra = {}) {
super(message);
this.status = status;
this.code = code;
this.expose = true;
this.extra = extra;
}
}
const explorerTx = (sig, network) => (sig ? `https://solscan.io/tx/${sig}${network === 'devnet' ? '?cluster=devnet' : ''}` : null);
const explorerAccount = (addr, network) => (addr ? `https://solscan.io/account/${addr}${network === 'devnet' ? '?cluster=devnet' : ''}` : null);
const iso = (v) => (v ? new Date(v).toISOString() : null);
const ui = (atomics, decimals) => Number(atomics) / 10 ** decimals;
const atomicsFromUi = (amount, decimals) => BigInt(Math.round(Number(amount) * 10 ** decimals));
const bpsOf = (atomics, bps) => (BigInt(atomics) * BigInt(bps)) / 10_000n;
// ── validation ────────────────────────────────────────────────────────────────
function validateInput(raw = {}) {
const name = String(raw.name ?? '').trim();
const symbol = String(raw.symbol ?? '').trim();
const description = String(raw.description ?? '').trim();
const imageUrl = String(raw.image_url ?? raw.imageUrl ?? raw.image ?? '').trim();
const network = String(raw.network ?? 'mainnet').toLowerCase();
if (!name || name.length > 32) throw new FundedLaunchError(400, 'validation_error', 'name is required and must be at most 32 characters');
if (!symbol || symbol.length > 10 || !/^[A-Za-z0-9$_.-]+$/.test(symbol)) throw new FundedLaunchError(400, 'validation_error', 'symbol is required, at most 10 characters, letters and digits');
if (description.length > 1000) throw new FundedLaunchError(400, 'validation_error', 'description must be at most 1000 characters');
let image;
try {
image = new URL(imageUrl);
} catch {
throw new FundedLaunchError(400, 'validation_error', 'image_url must be an absolute https URL');
}
if (image.protocol !== 'https:') throw new FundedLaunchError(400, 'validation_error', 'image_url must use https');
if (network !== 'mainnet' && network !== 'devnet') throw new FundedLaunchError(400, 'validation_error', 'network must be mainnet or devnet');
const initialBuy = raw.initial_buy == null || raw.initial_buy === '' ? 0 : Number(raw.initial_buy);
if (!Number.isFinite(initialBuy) || initialBuy < 0) throw new FundedLaunchError(400, 'validation_error', 'initial_buy must be a non-negative number in the quote asset');
let creatorFeeBps = null;
if (raw.creator_fee_bps != null && raw.creator_fee_bps !== '') {
creatorFeeBps = Number(raw.creator_fee_bps);
if (!Number.isInteger(creatorFeeBps) || creatorFeeBps < 0 || creatorFeeBps > 10_000) throw new FundedLaunchError(400, 'validation_error', 'creator_fee_bps must be an integer between 0 and 10000');
}
return {
name,
symbol: symbol.toUpperCase(),
description,
imageUrl: image.toString(),
network,
quote: String(raw.quote ?? raw.quote_asset ?? raw.quote_mint ?? 'sol').trim(),
initialBuy,
creatorFeeBps,
};
}
/**
* The creator fee a launch on `pair` will carry: the creator's pick when the
* program lets them choose, else the schedule rate. Throws on a pick outside
* the allowed range, with the range in the error so a client can correct it.
*/
export function resolveCreatorFee(pair, requestedBps) {
const rule = pair.creator_fee || {};
if (rule.configurable) {
const bps = requestedBps == null ? rule.default_bps : requestedBps;
if (bps < rule.min_bps || bps > rule.max_bps) {
throw new FundedLaunchError(400, 'creator_fee_out_of_range', `creator_fee_bps must be between ${rule.min_bps} and ${rule.max_bps} on ${pair.symbol}`, { min_bps: rule.min_bps, max_bps: rule.max_bps, default_bps: rule.default_bps });
}
return { bps, configurable: true, min_bps: rule.min_bps, max_bps: rule.max_bps, default_bps: rule.default_bps };
}
const fixed = rule.fixed_bps ?? pair.fees?.creator_bps ?? null;
if (requestedBps != null && fixed != null && requestedBps !== fixed) {
throw new FundedLaunchError(400, 'creator_fee_fixed', `${rule.reason || 'The creator fee is not configurable on this quote.'} The rate is ${fixed} bps.`, { fixed_bps: fixed });
}
return { bps: fixed, configurable: false, fixed_bps: fixed, reason: rule.reason || null };
}
// ── quote ─────────────────────────────────────────────────────────────────────
/**
* Every fee line of a launch on `pair` with `initialBuy` in the quote asset.
* Lines marked `included` are part of the initial buy and do not add to the
* total; the rest are paid on top. Totals are per asset, in atomics and units.
*/
export async function buildLaunchQuote({ pair, network, initialBuy, creatorFee }) {
const dec = pair.decimals;
const buy = atomicsFromUi(initialBuy, dec);
const platformBps = pumpLaunchFeeBps();
const recipient = await pumpFeeRecipient().catch(() => null);
const platformFee = recipient ? pumpFeeAtomics(buy, platformBps) : 0n;
const lines = [];
const solLine = (id, label, sol, note) => {
const atomics = BigInt(Math.round(sol * LAMPORTS));
lines.push({ id, label, asset: 'SOL', amount: ui(atomics, 9), atomics: atomics.toString(), payee: 'pump.fun program (rent)', included: false, note });
};
solLine('mint_rent', 'Mint account rent', FIXED_LAUNCH_COST_SOL.mintRent, 'Refundable only if the account closes; it does not.');
solLine('bonding_curve_rent', 'Bonding curve rent', FIXED_LAUNCH_COST_SOL.bondingCurveRent, 'Held by the curve account for its lifetime.');
solLine('metadata_rent', 'Metadata account rent', FIXED_LAUNCH_COST_SOL.metadataRent, 'Stores the coin name, symbol and image link on-chain.');
lines[lines.length - 1].payee = 'Metaplex token metadata (rent)';
lines.push({
id: 'network_fee',
label: 'Network fee',
asset: 'SOL',
amount: FIXED_LAUNCH_COST_SOL.txFee,
atomics: String(Math.round(FIXED_LAUNCH_COST_SOL.txFee * LAMPORTS)),
payee: 'Solana validators',
included: false,
note: 'Base signature fee. A priority fee is added at send time from live fee markets and is bounded by the compute budget.',
});
if (buy > 0n) {
lines.push({ id: 'initial_buy', label: `Initial buy`, asset: pair.symbol, amount: ui(buy, dec), atomics: buy.toString(), payee: 'Your coin\'s bonding curve', included: false, note: 'Your opening position. The fee lines below come out of this amount.' });
if (pair.fees) {
const protocol = bpsOf(buy, pair.fees.protocol_bps);
lines.push({ id: 'pump_protocol_fee', label: `pump.fun protocol fee (${(pair.fees.protocol_bps / 100).toFixed(2)}%)`, asset: pair.symbol, amount: ui(protocol, dec), atomics: protocol.toString(), payee: 'pump.fun', included: true, note: 'Taken from the initial buy by the program.' });
if (pair.fees.lp_bps > 0) {
const lp = bpsOf(buy, pair.fees.lp_bps);
lines.push({ id: 'pump_lp_fee', label: `pump.fun liquidity fee (${(pair.fees.lp_bps / 100).toFixed(2)}%)`, asset: pair.symbol, amount: ui(lp, dec), atomics: lp.toString(), payee: 'pump.fun liquidity', included: true, note: 'Taken from the initial buy by the program.' });
}
}
if (creatorFee.bps != null) {
const creator = bpsOf(buy, creatorFee.bps);
lines.push({ id: 'creator_fee', label: `Creator fee (${(creatorFee.bps / 100).toFixed(2)}%)`, asset: pair.symbol, amount: ui(creator, dec), atomics: creator.toString(), payee: 'You, as the coin\'s creator', included: true, note: 'Paid to the creator on every trade, this one included. Claimable on three.ws.' });
}
if (platformFee > 0n) {
lines.push({ id: 'platform_launch_fee', label: `three.ws launch fee (${(platformBps / 100).toFixed(2)}%)`, asset: pair.symbol, amount: ui(platformFee, dec), atomics: platformFee.toString(), payee: recipient.toBase58(), included: false, note: 'Charged on the opening buy only. A launch with no opening buy pays nothing.' });
}
}
const totals = {};
for (const line of lines) {
if (line.included) continue;
totals[line.asset] = (totals[line.asset] || 0n) + BigInt(line.atomics);
}
const shaped = {};
for (const [asset, atomics] of Object.entries(totals)) {
const d = asset === 'SOL' ? 9 : dec;
shaped[asset] = { atomics: atomics.toString(), amount: ui(atomics, d), decimals: d };
}
const solUsd = await solPriceUsd().catch(() => null);
return {
network,
pair: { id: pair.id, symbol: pair.symbol, mint: pair.mint, decimals: dec, kind: pair.kind, fees: pair.fees },
initial_buy: { amount: ui(buy, dec), atomics: buy.toString(), asset: pair.symbol },
creator_fee: creatorFee,
platform_fee_bps: platformBps,
lines,
totals: shaped,
sol_usd: Number.isFinite(solUsd) ? solUsd : null,
fees_known: Boolean(pair.fees),
quoted_at: new Date().toISOString(),
};
}
async function resolveAgent({ userId, agentId }) {
if (!agentId) throw new FundedLaunchError(400, 'validation_error', 'agent_id is required: the launch is paid from that agent\'s wallet');
const [row] = await sql`
select id, name, user_id from agent_identities
where id = ${String(agentId)} and deleted_at is null limit 1
`;
if (!row) throw new FundedLaunchError(404, 'agent_not_found', 'no such agent');
if (row.user_id !== userId) throw new FundedLaunchError(403, 'forbidden', 'not your agent');
return row;
}
/**
* Create a quoted launch intent. Returns the intent and the raw preflight
* token, which is shown exactly once: only its hash is stored.
*/
export async function createFundedLaunchIntent({ userId, agentId, input }) {
const v = validateInput(input);
const agent = await resolveAgent({ userId, agentId });
const pair = await findLaunchPair({ network: v.network, idOrMint: v.quote });
if (!pair) throw new FundedLaunchError(400, 'unknown_quote', `"${v.quote}" is not a quote asset this lane supports; GET /api/pump/pairs lists them`);
if (pair.status !== 'live') {
throw new FundedLaunchError(409, 'quote_not_live', `${pair.symbol} is ${pair.status.replace(/_/g, ' ')} on ${v.network} right now`, { pair });
}
const cap = MAX_INITIAL_BUY[pair.kind] ?? MAX_INITIAL_BUY.exotic;
if (v.initialBuy > cap) throw new FundedLaunchError(400, 'validation_error', `initial_buy must be at most ${cap} ${pair.symbol}`);
const creatorFee = resolveCreatorFee(pair, v.creatorFeeBps);
const quote = await buildLaunchQuote({ pair, network: v.network, initialBuy: v.initialBuy, creatorFee });
const { address } = await getOrCreateAgentSolanaWallet(agent.id);
const token = randomToken(32);
const tokenHash = await sha256(token);
const expiresAt = new Date(Date.now() + QUOTE_TTL_MS).toISOString();
const [row] = await sql`
insert into pump_funded_launch_intents (
user_id, agent_id, network, stage, name, symbol, description, image_url,
quote_asset, quote_mint, quote_symbol, quote_decimals, initial_buy_atomics, creator_fee_bps,
quote, quote_expires_at, preflight_token_hash, funding_address
) values (
${userId}, ${agent.id}, ${v.network}, 'quote', ${v.name}, ${v.symbol}, ${v.description}, ${v.imageUrl},
${pair.id}, ${pair.mint}, ${pair.symbol}, ${pair.decimals}, ${quote.initial_buy.atomics}::numeric, ${creatorFee.bps},
${JSON.stringify(quote)}::jsonb, ${expiresAt}, ${tokenHash}, ${address}
)
returning *
`;
logAudit({ userId, action: 'pump_funded_launch_quoted', resourceId: row.id, meta: { agent_id: agent.id, network: v.network, quote: pair.id, initial_buy: v.initialBuy, creator_fee_bps: creatorFee.bps } });
return { intent: await shapeIntent({ ...row, agent_name: agent.name }), preflight_token: token };
}
// ── loading ───────────────────────────────────────────────────────────────────
async function loadIntent(userId, id) {
const [row] = await sql`
select i.*, a.name as agent_name
from pump_funded_launch_intents i
left join agent_identities a on a.id = i.agent_id
where i.id = ${String(id)} and i.user_id = ${userId}
limit 1
`;
if (!row) throw new FundedLaunchError(404, 'not_found', 'no such launch intent');
return row;
}
export async function listFundedLaunchIntents(userId, { agentId = null, limit = 30 } = {}) {
const n = Math.min(100, Math.max(1, Number(limit) || 30));
const rows = agentId
? await sql`
select i.*, a.name as agent_name from pump_funded_launch_intents i
left join agent_identities a on a.id = i.agent_id
where i.user_id = ${userId} and i.agent_id = ${String(agentId)}
order by i.created_at desc limit ${n}`
: await sql`
select i.*, a.name as agent_name from pump_funded_launch_intents i
left join agent_identities a on a.id = i.agent_id
where i.user_id = ${userId}
order by i.created_at desc limit ${n}`;
return Promise.all(rows.map((r) => shapeIntent(r, { withBalance: false })));
}
/** One intent, with its stages advanced from chain state first. */
export async function getFundedLaunchIntent(userId, id, { withBalance = true } = {}) {
const row = await advanceIntentStages(await loadIntent(userId, id));
return shapeIntent(row, { withBalance });
}
// ── payment proof ─────────────────────────────────────────────────────────────
function requiredAtomics(row, asset) {
return BigInt(row.quote?.totals?.[asset]?.atomics || '0');
}
async function fundingBalances(row) {
const conn = getConnection({ network: row.network });
const owner = new PublicKey(row.funding_address);
const out = { SOL: null };
try {
out.SOL = BigInt(await conn.getBalance(owner, 'confirmed'));
} catch (err) {
log.warn('balance_read_failed', { intent: row.id, asset: 'SOL', err: err?.message });
}
if (row.quote_mint && row.quote_symbol !== 'SOL') {
out[row.quote_symbol] = null;
try {
const spl = await import('@solana/spl-token');
const ata = spl.getAssociatedTokenAddressSync(new PublicKey(row.quote_mint), owner, true);
const bal = await conn.getTokenAccountBalance(ata, 'confirmed');
out[row.quote_symbol] = BigInt(bal?.value?.amount ?? '0');
} catch {
out[row.quote_symbol] = 0n;
}
}
return out;
}
function shortfall(row, balances) {
const missing = {};
for (const [asset, total] of Object.entries(row.quote?.totals || {})) {
const have = balances[asset];
if (have == null) continue;
const need = BigInt(total.atomics);
if (have < need) missing[asset] = { atomics: (need - have).toString(), amount: ui(need - have, total.decimals) };
}
return missing;
}
/**
* Record the funding transaction. Accepted exactly once per intent: the same
* signature replays the stored result, any other is refused once one landed.
* The proof must credit the funding address and leave it holding the quoted
* totals; a transfer that falls short is reported and not consumed.
*/
export async function recordFundingProof({ userId, intentId, signature, preflightToken }) {
const sig = String(signature || '').trim();
if (!/^[1-9A-HJ-NP-Za-km-z]{64,100}$/.test(sig)) throw new FundedLaunchError(400, 'validation_error', 'signature must be a base58 transaction signature');
if (!preflightToken) throw new FundedLaunchError(400, 'validation_error', 'preflight_token is required');
const row = await loadIntent(userId, intentId);
if (row.payment_signature) {
if (row.payment_signature === sig) return { intent: await shapeIntent(row), result: { ...(row.payment_result || {}), replayed: true }, replayed: true };
throw new FundedLaunchError(409, 'already_paid', 'this intent was already funded with a different transaction', { payment_signature: row.payment_signature });
}
if (row.stage !== 'quote') throw new FundedLaunchError(409, 'wrong_stage', `the intent is ${row.stage}; payment is accepted at the quote stage only`);
if (new Date(row.quote_expires_at).getTime() <= Date.now()) {
await sql`update pump_funded_launch_intents set stage = 'expired', updated_at = now() where id = ${row.id} and stage = 'quote'`;
throw new FundedLaunchError(410, 'quote_expired', 'the quote expired before it was funded; create a new intent');
}
const hash = await sha256(String(preflightToken));
if (!constantTimeEquals(hash, row.preflight_token_hash)) throw new FundedLaunchError(403, 'preflight_mismatch', 'the preflight token does not belong to this intent');
const [taken] = await sql`select id from pump_funded_launch_intents where payment_signature = ${sig} limit 1`;
if (taken) throw new FundedLaunchError(409, 'signature_used', 'that transaction already funded another intent');
const tx = await verifySignature({ network: row.network, signature: sig });
const credited = {};
const solDelta = walletQuoteDeltaAtomics({ tx, wallet: row.funding_address, quoteSymbol: 'SOL' });
if (solDelta) credited.SOL = solDelta;
if (row.quote_symbol !== 'SOL' && row.quote_mint) {
const d = walletQuoteDeltaAtomics({ tx, wallet: row.funding_address, quoteSymbol: row.quote_symbol, quoteMint: row.quote_mint });
if (d) credited[row.quote_symbol] = d;
}
if (!Object.keys(credited).length) {
throw new FundedLaunchError(422, 'not_a_funding_tx', `the transaction did not move SOL${row.quote_symbol !== 'SOL' ? ` or ${row.quote_symbol}` : ''} to ${row.funding_address}`);
}
const balances = await fundingBalances(row);
const missing = shortfall(row, balances);
if (Object.keys(missing).length) {
throw new FundedLaunchError(402, 'funding_insufficient', 'the transaction landed but the agent wallet still holds less than the quote needs', {
funding_address: row.funding_address,
shortfall: missing,
credited,
});
}
const result = {
signature: sig,
explorer: explorerTx(sig, row.network),
credited,
balance_after: Object.fromEntries(Object.entries(balances).map(([k, v]) => [k, v == null ? null : v.toString()])),
slot: tx.slot ?? null,
block_time: tx.blockTime ? new Date(tx.blockTime * 1000).toISOString() : null,
verified_at: new Date().toISOString(),
};
let updated;
try {
[updated] = await sql`
update pump_funded_launch_intents
set stage = 'paid', payment_signature = ${sig}, payment_result = ${JSON.stringify(result)}::jsonb,
paid_at = now(), updated_at = now()
where id = ${row.id} and stage = 'quote' and payment_signature is null
returning *
`;
} catch (err) {
if (String(err?.code) === '23505') throw new FundedLaunchError(409, 'signature_used', 'that transaction already funded another intent');
throw err;
}
if (!updated) {
// Lost a race with a concurrent proof for this intent: answer from what landed.
const fresh = await loadIntent(userId, intentId);
if (fresh.payment_signature === sig) return { intent: await shapeIntent(fresh), result: { ...(fresh.payment_result || {}), replayed: true }, replayed: true };
throw new FundedLaunchError(409, 'already_paid', 'this intent was already funded with a different transaction', { payment_signature: fresh.payment_signature });
}
logAudit({ userId, action: 'pump_funded_launch_paid', resourceId: row.id, meta: { signature: sig, network: row.network, credited } });
return { intent: await shapeIntent({ ...updated, agent_name: row.agent_name }), result, replayed: false };
}
// ── metadata + mint ───────────────────────────────────────────────────────────
async function ensureMetadata(row) {
if (row.metadata_uri) return row;
const { uploadPumpMetadata } = await import('./pump-launch.js');
const up = await uploadPumpMetadata({ imageUrl: row.image_url, name: row.name, symbol: row.symbol, description: row.description || '' });
const [updated] = await sql`
update pump_funded_launch_intents set metadata_uri = ${up.metadataUri}, updated_at = now()
where id = ${row.id} returning *
`;
return { ...row, ...updated };
}
function markEnforced() {
return env.THREE_WS_MARK_ENFORCE !== '0' && env.THREE_WS_MARK_ENFORCE !== 'false';
}
async function freshMintKeypair() {
if (!markEnforced()) return Keypair.generate();
try {
const ground = await grindVanityNode({ ...THREE_WS_VANITY });
return Keypair.fromSecretKey(ground.secretKey);
} catch (err) {
if (err instanceof GrindExhaustedError) throw new FundedLaunchError(503, 'mark_grind_failed', 'could not stamp the three.ws mark on a fresh mint; retry');
throw err;
}
}
async function ensureMint(row) {
if (row.mint && row.mint_secret) return row;
const kp = await freshMintKeypair();
const secret = await encryptSecret(Buffer.from(kp.secretKey).toString('base64'));
const [updated] = await sql`
update pump_funded_launch_intents set mint = ${kp.publicKey.toBase58()}, mint_secret = ${secret}, updated_at = now()
where id = ${row.id} and mint is null returning *
`;
if (!updated) return loadIntent(row.user_id, row.id);
return { ...row, ...updated };
}
async function mintKeypairFor(row) {
const b64 = await decryptSecret(row.mint_secret);
const kp = Keypair.fromSecretKey(Uint8Array.from(Buffer.from(b64, 'base64')));
if (kp.publicKey.toBase58() !== row.mint) throw new FundedLaunchError(500, 'mint_mismatch', 'the stored mint secret does not match the stored mint');
return kp;
}
// ── instruction building ──────────────────────────────────────────────────────
/**
* The create (and buy) instructions for an intent, exactly as the executor
* sends them. `payer` is the agent wallet; `mint` the coin's keypair public key.
*/
export async function buildIntentInstructions({ row, mint, payer }) {
const pumpSdk = await import('@pump-fun/pump-sdk');
const { sdk, BN } = await getPumpSdk({ network: row.network });
const global = await sdk.fetchGlobal();
const buy = new BN(String(row.initial_buy_atomics || '0'));
const hasBuy = !buy.isZero();
const configurable = Boolean(row.quote?.creator_fee?.configurable) && Boolean(global.creatorFeeConfigurable);
const creatorFeeBps = configurable && row.creator_fee_bps > 0 ? new BN(row.creator_fee_bps) : undefined;
const common = { mint, name: row.name, symbol: row.symbol, uri: row.metadata_uri, creator: payer, user: payer, mayhemMode: false, creatorFeeBps };
const quoteMint = row.quote_mint && row.quote_mint !== WSOL_MINT ? solanaPubkey(row.quote_mint) : null;
if (quoteMint) {
if (hasBuy) {
const amount = pumpSdk.getBuyTokenAmountFromSolAmount({ global, feeConfig: null, mintSupply: null, bondingCurve: null, amount: buy, quoteMint });
const ixs = await sdk.createV2AndBuyV2Instructions({ global, ...common, quoteAmount: buy, amount, quoteMint });
return Array.isArray(ixs) ? [...ixs] : [ixs];
}
return [await sdk.createV2Instruction({ ...common, quoteMint })];
}
if (hasBuy) {
const amount = pumpSdk.getBuyTokenAmountFromSolAmount({ global, feeConfig: null, mintSupply: null, bondingCurve: null, amount: buy });
const ixs = await sdk.createV2AndBuyInstructions({ global, ...common, solAmount: buy, amount });
return Array.isArray(ixs) ? [...ixs] : [ixs];
}
return [await sdk.createV2Instruction(common)];
}
async function platformFeeFor(row, payer) {
const isUsdc = Boolean(row.quote_mint) && row.quote_symbol !== 'SOL';
return buildPlatformFeeInstructions({
network: row.network,
payer,
isUsdc,
quoteMintPk: isUsdc ? solanaPubkey(row.quote_mint) : undefined,
grossAtomics: BigInt(String(row.initial_buy_atomics || '0')),
basis: 'launch_dev_buy',
bps: pumpLaunchFeeBps(),
});
}
// ── confirmation (approval request) ───────────────────────────────────────────
/**
* Queue the launch spend for the owner's explicit yes. Only a same-site session
* reaches this (the handler enforces it). Idempotent while a request is open.
*/
export async function requestLaunchConfirmation({ userId, intentId }) {
let row = await loadIntent(userId, intentId);
if (row.stage !== 'paid' && row.stage !== 'failed') {
throw new FundedLaunchError(409, 'wrong_stage', row.stage === 'quote' ? 'fund the intent before confirming it' : `the intent is already ${row.stage}`);
}
const pair = await findLaunchPair({ network: row.network, idOrMint: row.quote_asset });
if (!pair || pair.status !== 'live') throw new FundedLaunchError(409, 'quote_not_live', `${row.quote_symbol} launches are not accepting creates on ${row.network} right now`);
const balances = await fundingBalances(row);
const missing = shortfall(row, balances);
if (Object.keys(missing).length) throw new FundedLaunchError(402, 'funding_insufficient', 'the agent wallet no longer holds what the quote needs', { funding_address: row.funding_address, shortfall: missing });
row = await ensureMetadata(row);
row = await ensureMint(row);
const [{ n }] = await sql`select count(*)::int as n from approval_requests where source = 'pump_funded_launch' and source_ref = ${row.id}`;
const totals = row.quote.totals;
const primaryAsset = row.quote_symbol === 'SOL' ? 'SOL' : row.quote_symbol;
const primary = totals[primaryAsset] || totals.SOL;
const solUsd = row.quote.sol_usd;
const amountUsd = primaryAsset === 'SOL' ? (solUsd ? primary.amount * solUsd : null) : primary.amount;
const riskNotes = [
...row.quote.lines.filter((l) => !l.included).map((l) => `${l.label}: ${l.amount} ${l.asset}`),
...(totals.SOL && primaryAsset !== 'SOL' ? [`Plus ${totals.SOL.amount} SOL of rent and network fees`] : []),
`Creator fee ${(row.creator_fee_bps / 100).toFixed(2)}% on every trade, paid to the agent wallet`,
'The new coin trades publicly as soon as this lands. Launches cannot be undone.',
];
const { request, created } = await createApprovalRequest({
userId,
agentId: row.agent_id,
requesterRole: 'owner',
source: 'pump_funded_launch',
sourceRef: row.id,
actionType: 'pump_funded_launch',
venue: 'pump_launch',
payload: {
v: 1,
intent_id: row.id,
mint: row.mint,
name: row.name,
symbol: row.symbol,
network: row.network,
quote_mint: row.quote_mint,
quote_symbol: row.quote_symbol,
initial_buy_atomics: String(row.initial_buy_atomics),
creator_fee_bps: row.creator_fee_bps,
totals,
funding_address: row.funding_address,
},
summary: `Launch ${row.name} (${row.symbol}) on pump.fun from ${row.agent_name || 'the agent'}'s wallet, paying ${primary.amount} ${primaryAsset}`,
amount: primary.amount,
amountUsd: Number.isFinite(amountUsd) ? Number(amountUsd.toFixed(2)) : null,
asset: primaryAsset,
chain: 'solana',
network: row.network,
recipient: row.mint,
recipientLabel: `${row.symbol} bonding curve (new coin)`,
riskNotes,
gateReason: 'A coin launch signs from the agent wallet and cannot be undone.',
idempotencyKey: `pump_funded_launch:${row.id}:${n}`,
autoApprovable: false,
});
const [updated] = await sql`
update pump_funded_launch_intents set approval_id = ${request.id}, stage = 'paid', error = null, updated_at = now()
where id = ${row.id} returning *
`;
if (created) logAudit({ userId, action: 'pump_funded_launch_confirmation_requested', resourceId: row.id, meta: { approval_id: request.id, mint: row.mint } });
return { intent: await shapeIntent({ ...updated, agent_name: row.agent_name }), approval: { id: request.id, status: request.status, link: `/approvals/${request.id}`, expires_at: iso(request.expires_at) }, created };
}
// ── executor (the only code path that signs) ──────────────────────────────────
/**
* Approval executor. Signs the launch from the agent wallet for an intent that
* is paid and matches the approved payload byte for byte. Contract:
* `(row) -> { status, signature?, note?, usd? }`.
*/
export async function executeApprovedFundedLaunch(approval) {
const p = approval?.payload || {};
const [row] = await sql`select * from pump_funded_launch_intents where id = ${String(p.intent_id || '')} and user_id = ${approval.user_id} limit 1`;
if (!row) return { status: 'error', note: 'The launch intent no longer exists.' };
if (row.stage !== 'paid') return { status: 'skipped', note: `The intent is ${row.stage}; nothing was signed.` };
if (row.mint !== p.mint || String(row.initial_buy_atomics) !== String(p.initial_buy_atomics) || row.creator_fee_bps !== p.creator_fee_bps || (row.quote_mint || null) !== (p.quote_mint || null) || row.network !== p.network) {
return { status: 'error', note: 'The intent changed after it was approved. Nothing was signed.' };
}
if (row.approval_id && row.approval_id !== approval.id) return { status: 'skipped', note: 'A different approval owns this intent.' };
const { loadAgentForSigning } = await import('./agent-pumpfun.js');
const { reserveSpend, finalizeSpend, releaseSpend } = await import('./agent-spend-policy.js');
const { submitProtected } = await import('./execution-engine.js');
const { getPumpLookupTables } = await import('./pump-launch-tx.js');
const { markPlanLaunched } = await import('./agent-token-plan.js');
const { publishFeedEvent } = await import('./feed.js');
const loaded = await loadAgentForSigning(row.agent_id, row.user_id, { reason: 'pump_funded_launch', meta: { intent_id: row.id, approval_id: approval.id } });
if (loaded.error) return { status: 'error', note: loaded.error.msg };
const payer = loaded.keypair;
if (payer.publicKey.toBase58() !== row.funding_address) return { status: 'error', note: 'The agent wallet is not the funded address. Nothing was signed.' };
let mintKeypair;
try {
mintKeypair = await mintKeypairFor(row);
} catch (err) {
return { status: 'error', note: err?.message || 'The mint secret could not be read.' };
}
const [existing] = await sql`select id from pump_agent_mints where mint = ${row.mint} and network = ${row.network} limit 1`;
if (existing) return { status: 'skipped', note: 'This mint is already registered as launched.' };
let instructions;
let launchFee;
try {
instructions = await buildIntentInstructions({ row, mint: mintKeypair.publicKey, payer: payer.publicKey });
launchFee = await platformFeeFor(row, payer.publicKey);
} catch (err) {
await failIntent(row.id, `build: ${err?.message || err}`);
return { status: 'error', note: `Could not build the launch transaction: ${String(err?.message || err).slice(0, 160)}` };
}
const isSolPair = row.quote_symbol === 'SOL';
const solOutflow = Number(row.quote?.totals?.SOL?.atomics || '0') / LAMPORTS;
const reservation = await reserveSpend({
agentId: row.agent_id,
meta: loaded.meta,
mint: row.mint,
solAmount: isSolPair ? solOutflow : Number(row.quote?.totals?.SOL?.atomics || '0') / LAMPORTS,
type: 'pumpfun.launch',
payload: { name: row.name, symbol: row.symbol, network: row.network, source: 'funded_launch_intent', intent_id: row.id, approval_id: approval.id },
});
if (!reservation.ok) {
await failIntent(row.id, reservation.msg);
return { status: 'error', note: reservation.msg };
}
const connection = getConnection({ network: row.network });
const lookupTables = await getPumpLookupTables({ network: row.network });
const send = (ixs) => submitProtected({ network: row.network, connection, payer, instructions: ixs, opts: { extraSigners: [mintKeypair], addressLookupTables: lookupTables } });
let signature;
let feeSettlement = launchFee ? 'bundled' : null;
try {
try {
({ signature } = await send(launchFee ? [...instructions, ...launchFee.instructions] : instructions));
} catch (err) {
if (!launchFee || !/too large|overruns|RangeError/i.test(`${err?.name} ${err?.message}`)) throw err;
({ signature } = await send(instructions));
feeSettlement = 'separate';
try {
await submitProtected({ network: row.network, connection, payer, instructions: launchFee.instructions });
} catch (feeErr) {
feeSettlement = 'failed';
log.error('separate_fee_failed', { intent: row.id, err: feeErr?.message });
}
}
} catch (err) {
await releaseSpend(reservation.reservationId);
await failIntent(row.id, `send: ${err?.message || err}`);
return { status: 'error', note: `The launch transaction did not land: ${String(err?.message || err).slice(0, 160)}` };
}
const result = {
signature,
explorer: explorerTx(signature, row.network),
pumpfun_url: `https://pump.fun/coin/${row.mint}`,
launch_url: `${env.APP_ORIGIN}/launch/${row.mint}`,
platform_fee: launchFee ? { ...launchFee.disclosure, settlement: feeSettlement } : null,
approval_id: approval.id,
};
await sql`
update pump_funded_launch_intents
set stage = 'submitted', launch_signature = ${signature}, submitted_at = now(), result = ${JSON.stringify(result)}::jsonb,
mint_secret = null, error = null, updated_at = now()
where id = ${row.id}
`;
await sql`
insert into pump_agent_mints (agent_id, user_id, network, mint, name, symbol, metadata_uri, agent_authority, buyback_bps, quote_mint)
values (${row.agent_id}, ${row.user_id}, ${row.network}, ${row.mint}, ${row.name}, ${row.symbol}, ${row.metadata_uri}, ${row.funding_address}, 0, ${row.quote_mint})
on conflict (mint, network) do nothing
`.catch((err) => log.error('mint_record_failed', { intent: row.id, err: err?.message }));
await markPlanLaunched({ agentId: row.agent_id, network: row.network, mint: row.mint }).catch(() => {});
await finalizeSpend(reservation.reservationId, { mint: row.mint, name: row.name, symbol: row.symbol, uri: row.metadata_uri, signature, network: row.network, quote_mint: row.quote_mint, intent_id: row.id });
publishFeedEvent({ type: 'coin-buy', ts: Date.now(), actor: `${row.funding_address.slice(0, 4)}…${row.funding_address.slice(-4)}`, mint: row.mint, sol: isSolPair ? Number(row.initial_buy_atomics) / LAMPORTS : 0, network: row.network, branded: hasThreeWsMark(row.mint) }).catch(() => {});
logAudit({ userId: row.user_id, action: 'pump_funded_launch_submitted', resourceId: row.id, meta: { signature, mint: row.mint, network: row.network, approval_id: approval.id } });
const usd = row.quote_symbol === 'SOL' && row.quote.sol_usd ? Number((solOutflow * row.quote.sol_usd).toFixed(2)) : row.quote_symbol !== 'SOL' ? Number(row.quote.totals[row.quote_symbol]?.amount || 0) : null;
return { status: 'ok', signature, note: `Launched ${row.symbol}. Mint ${row.mint}.`, usd };
}
async function failIntent(id, message) {
await sql`
update pump_funded_launch_intents set stage = 'failed', error = ${String(message).slice(0, 400)}, updated_at = now()
where id = ${id} and stage in ('paid', 'submitted')
`.catch((err) => log.error('fail_mark_failed', { intent: id, err: err?.message }));
}
// ── stage advancement ─────────────────────────────────────────────────────────
/**
* Move an intent forward from chain state: expire a stale quote, confirm a
* submitted launch, mark it indexed once the curve account reads. Never
* throws; a read failure leaves the stage where it was.
*/
export async function advanceIntentStages(row) {
try {
if (row.stage === 'quote' && new Date(row.quote_expires_at).getTime() <= Date.now()) {
const [u] = await sql`update pump_funded_launch_intents set stage = 'expired', updated_at = now() where id = ${row.id} and stage = 'quote' returning *`;
return u ? { ...row, ...u } : row;
}
if (row.stage === 'submitted' && row.launch_signature) {
try {
await verifySignature({ network: row.network, signature: row.launch_signature });
} catch (err) {
if (err?.code === 'tx_failed') {
const [u] = await sql`update pump_funded_launch_intents set stage = 'failed', error = 'the launch transaction failed on-chain', updated_at = now() where id = ${row.id} and stage = 'submitted' returning *`;
return u ? { ...row, ...u } : row;
}
return row;
}
const [u] = await sql`update pump_funded_launch_intents set stage = 'confirmed', confirmed_at = now(), updated_at = now() where id = ${row.id} and stage = 'submitted' returning *`;
row = u ? { ...row, ...u } : row;
}
if (row.stage === 'confirmed' && row.mint) {
const { online } = await getPumpSdk({ network: row.network });
const curve = await online.fetchBondingCurve(row.mint).catch(() => null);
if (curve) {
const [u] = await sql`update pump_funded_launch_intents set stage = 'indexed', indexed_at = now(), indexed_by = 'bonding_curve', updated_at = now() where id = ${row.id} and stage = 'confirmed' returning *`;
row = u ? { ...row, ...u } : row;
}
}
} catch (err) {
log.warn('advance_failed', { intent: row.id, stage: row.stage, err: err?.message });
}
return row;
}
// ── dry run ───────────────────────────────────────────────────────────────────
/**
* Simulate the exact launch transaction with a throwaway mint and the agent
* wallet as payer. Nothing is signed or broadcast. On a devnet intent this is
* the whole lane end to end without mainnet involvement.
*/
export async function dryRunFundedLaunch({ userId, intentId }) {
let row = await loadIntent(userId, intentId);
if (['submitted', 'confirmed', 'indexed'].includes(row.stage)) throw new FundedLaunchError(409, 'wrong_stage', `the intent is already ${row.stage}`);
const started = Date.now();
const report = { at: new Date().toISOString(), network: row.network, verdict: null, mint_used: null, units_consumed: null, logs: [], error: null, instructions: 0, duration_ms: 0 };
try {
row = await ensureMetadata(row);
} catch (err) {
report.verdict = 'metadata_failed';
report.error = String(err?.message || err).slice(0, 240);
return storeDryRun(row, report);
}
const throwaway = Keypair.generate();
report.mint_used = throwaway.publicKey.toBase58();
const payer = new PublicKey(row.funding_address);
let message;
try {
const ixs = await buildIntentInstructions({ row, mint: throwaway.publicKey, payer });
const fee = await platformFeeFor(row, payer);
const all = fee ? [...ixs, ...fee.instructions] : ixs;
report.instructions = all.length;
const { getPumpLookupTables } = await import('./pump-launch-tx.js');
const tables = await getPumpLookupTables({ network: row.network });
const connection = getConnection({ network: row.network });
const { blockhash } = await connection.getLatestBlockhash('confirmed');
message = new TransactionMessage({ payerKey: payer, recentBlockhash: blockhash, instructions: all }).compileToV0Message(tables);
const sim = await connection.simulateTransaction(new VersionedTransaction(message), { sigVerify: false, replaceRecentBlockhash: true, commitment: 'confirmed' });
report.logs = (sim.value?.logs || []).slice(-14);
report.units_consumed = sim.value?.unitsConsumed ?? null;
if (sim.value?.err) {
const errText = JSON.stringify(sim.value.err);
const logsText = report.logs.join('\n');
const insufficient = /insufficient (lamports|funds)/i.test(logsText) || /"Custom":1\b/.test(errText) || /AccountNotFound/.test(errText);
report.verdict = insufficient ? 'funding_required' : 'would_fail';
report.error = errText.slice(0, 240);
} else {
report.verdict = 'would_succeed';
}
} catch (err) {
const msg = String(err?.message || err);
report.error = msg.slice(0, 240);
report.verdict = message ? 'rpc_unavailable' : /too large|overruns|RangeError|encode/i.test(`${err?.name} ${msg}`) ? 'compile_failed' : /fetch|ECONN|timeout|429|503/i.test(msg) ? 'rpc_unavailable' : 'compile_failed';
}
report.duration_ms = Date.now() - started;
return storeDryRun(row, report);
}
async function storeDryRun(row, report) {
const [u] = await sql`update pump_funded_launch_intents set dry_run = ${JSON.stringify(report)}::jsonb, updated_at = now() where id = ${row.id} returning *`;
logAudit({ userId: row.user_id, action: 'pump_funded_launch_dry_run', resourceId: row.id, meta: { verdict: report.verdict, network: report.network } });
return { intent: await shapeIntent({ ...row, ...u, agent_name: row.agent_name }), dry_run: report };
}
// ── public shape ──────────────────────────────────────────────────────────────
function stageList(row) {
const at = { quote: row.created_at, paid: row.paid_at, submitted: row.submitted_at, confirmed: row.confirmed_at, indexed: row.indexed_at };
const reached = STAGES.indexOf(row.stage);
return STAGES.map((id, i) => ({
id,
label: { quote: 'Quoted', paid: 'Funded', submitted: 'Submitted', confirmed: 'Confirmed', indexed: 'Indexed' }[id],
done: reached >= i && !(TERMINAL_STAGES.includes(row.stage) && i > 0 && !at[id]),
current: row.stage === id,
at: iso(at[id]),
}));
}
/**
* The public intent. `withBalance` reads the funding wallet live, which the
* focus view wants and a list does not.
*/
export async function shapeIntent(row, { withBalance = true } = {}) {
const quote = row.quote || {};
const totals = quote.totals || {};
let balance = null;
if (withBalance && row.funding_address && ['quote', 'paid', 'failed'].includes(row.stage)) {
const b = await getSolanaAddressBalances(row.funding_address, row.network);
balance = { SOL: b.sol, ...(row.quote_symbol === 'USDC' ? { USDC: b.usdc } : {}) };
}
const required = Object.fromEntries(Object.entries(totals).map(([asset, t]) => [asset, t.amount]));
const expiresMs = new Date(row.quote_expires_at).getTime();
const pairKind = quote.pair?.kind || (row.quote_symbol === 'SOL' ? 'sol' : 'stable');
return {
id: row.id,
agent: { id: row.agent_id, name: row.agent_name || null },
network: row.network,
stage: row.stage,
stages: stageList(row),
name: row.name,
symbol: row.symbol,
description: row.description || '',
image_url: row.image_url,
metadata_uri: row.metadata_uri || null,
quote_asset: { id: row.quote_asset, symbol: row.quote_symbol, mint: row.quote_mint, decimals: row.quote_decimals, kind: pairKind },
initial_buy: quote.initial_buy || { amount: ui(row.initial_buy_atomics || 0, row.quote_decimals), atomics: String(row.initial_buy_atomics || 0), asset: row.quote_symbol },
creator_fee: {
bps: row.creator_fee_bps,
percent: row.creator_fee_bps != null ? Number((row.creator_fee_bps / 100).toFixed(2)) : null,
...(quote.creator_fee || {}),
earnings: row.creator_fee_bps != null ? earningsProjection({ bps: row.creator_fee_bps, quoteSymbol: row.quote_symbol, kind: pairKind }) : null,
},
quote: {
lines: quote.lines || [],
totals,
sol_usd: quote.sol_usd ?? null,
fees_known: quote.fees_known ?? null,
quoted_at: quote.quoted_at || iso(row.created_at),
expires_at: iso(row.quote_expires_at),
expires_in_ms: Math.max(0, expiresMs - Date.now()),
expired: row.stage === 'expired' || (row.stage === 'quote' && expiresMs <= Date.now()),
},
funding: {
address: row.funding_address,
explorer: explorerAccount(row.funding_address, row.network),
required,
balance,
paid: Boolean(row.payment_signature),
},
payment: row.payment_signature
? { signature: row.payment_signature, explorer: explorerTx(row.payment_signature, row.network), paid_at: iso(row.paid_at), result: row.payment_result || null }
: null,
approval: row.approval_id ? { id: row.approval_id, link: `/approvals/${row.approval_id}` } : null,
mint: row.mint || null,
launch: row.launch_signature
? {
signature: row.launch_signature,
explorer: explorerTx(row.launch_signature, row.network),
pumpfun_url: `https://pump.fun/coin/${row.mint}`,
launch_url: `/launch/${row.mint}`,
submitted_at: iso(row.submitted_at),
confirmed_at: iso(row.confirmed_at),
indexed_at: iso(row.indexed_at),
platform_fee: row.result?.platform_fee || null,
}
: null,
dry_run: row.dry_run || null,
error: row.error || null,
created_at: iso(row.created_at),
updated_at: iso(row.updated_at),
links: { page: `/launch/intents/${row.id}`, api: `/api/pump/launch-intents/${row.id}` },
};
}