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.

16.2 KB
Raw Blame
// Shared adapter for the four official @pump-fun/* SDKs.
// Lazy-loaded — Vercel cold starts pay only for what an endpoint touches.
//
// Public surface:
//   getConnection({ network })                   → @solana/web3.js Connection
//   getPumpSdk({ network })                      → { sdk, PUMP_SDK, BN, web3 }
//   getPumpSdkV2({ network })                    → { PUMP_SDK, onlineSdk, bondingCurvePda, isLegacyQuoteMint, BN, web3 }
//   getPumpSwapSdk({ network })                  → { sdk: PumpAmmSdk, BN, web3 }
//   getPumpAgent({ network, mint })              → { agent: PumpAgent, BN, web3, agentPda }
//   getPumpAgentOffline({ network, mint })       → instruction-only PumpAgentOffline
//   getPumpTradeClient({ network })              → { client: PumpTradeClient, BN, web3 }
//   verifySignature(network, sig)                → confirmed parsed tx, throws on missing/failed
//   solanaPubkey(s)                              → PublicKey or null
//
// Network selection: 'mainnet' | 'devnet'. Endpoint URLs come from env so
// production can pin Helius / Triton / etc. RPC providers. Setting
// SOLANA_RPC_FALLBACK_URLS (comma-separated) enables the multi-endpoint
// RpcFallback wrapper for read-side handlers that opt in via getRpcFallback().

import { PublicKey } from '@solana/web3.js';
import { solanaConnection } from './solana/connection.js';
import { rpcFallbackFromEnv } from './solana/rpc-fallback.js';
import { PUMP_PROGRAM_ID, PUMP_AGENT_PAYMENTS_PROGRAM_ID } from './solana/programs.js';
import { isRpcOutageError, rpcUnavailableError } from './rpc-degrade.js';

// @solana/web3.js calls console.error() on every 429 retry attempt. Those
// retries succeed (callers see a resolved value, not a thrown error), but
// Vercel captures console.error as level:error which pollutes the error log.
// Downgrade just those messages to console.warn so they stay visible as
// warnings without triggering alert thresholds.
{
	const _err = console.error.bind(console);
	console.error = (...args) => {
		if (
			typeof args[0] === 'string' &&
			/Server responded with \d+ .*Retrying after/.test(args[0])
		) {
			console.warn(...args);
		} else {
			_err(...args);
		}
	};
}

const RPC_MAINNET = () => process.env.SOLANA_RPC_URL || 'https://api.mainnet-beta.solana.com';
const RPC_DEVNET = () => process.env.SOLANA_RPC_URL_DEVNET || 'https://api.devnet.solana.com';

export function getConnection({ network = 'mainnet', commitment = 'confirmed' } = {}) {
	const url = network === 'devnet' ? RPC_DEVNET() : RPC_MAINNET();
	return solanaConnection({ url: url, commitment: commitment });
}

// Returns an RpcFallback wrapper for read-only flows that benefit from
// multi-endpoint rotation. Always returns an instance — when no fallbacks are
// configured it just wraps the single primary URL with no behavior change.
export function getRpcFallback({ network = 'mainnet', commitment = 'confirmed' } = {}) {
	return rpcFallbackFromEnv({ network, commitment });
}

export function solanaPubkey(s) {
	if (!s) return null;
	try {
		return new PublicKey(s);
	} catch {
		return null;
	}
}

export async function getPumpSdk({ network = 'mainnet' } = {}) {
	const [{ PumpSdk, OnlinePumpSdk }, web3, BN] = await Promise.all([
		import('@pump-fun/pump-sdk'),
		import('@solana/web3.js'),
		import('bn.js').then((m) => m.default || m),
	]);
	const connection = getConnection({ network });
	// `OnlinePumpSdk` exposes the `fetch*` helpers; the instruction builders
	// (`createInstruction`, `createV2AndBuyInstructions`, `buyInstructions`, …)
	// live on the offline `PumpSdk`. Compose both so callers see one `sdk` with
	// the full surface — required by the studio launch flow.
	const offline = new PumpSdk();
	const online = OnlinePumpSdk ? new OnlinePumpSdk(connection) : null;
	// Compose offline + online so callers see a unified `sdk`. Offline owns the
	// instruction builders (createV2Instruction, …); online owns the fetch*
	// helpers. Prefer offline for any method that exists on it — the previous
	// `prop in target` check resolved class-prototype methods on `online` to
	// `undefined`, surfacing as "sdk.createInstruction is not a function" at
	// runtime even though the method existed on `offline`.
	const sdk = online
		? new Proxy(online, {
				get(target, prop, receiver) {
					const offlineVal = offline[prop];
					if (typeof offlineVal === 'function') return offlineVal.bind(offline);
					if (offlineVal !== undefined) return offlineVal;
					return Reflect.get(target, prop, receiver);
				},
			})
		: offline;
	return { sdk, connection, BN, web3, PumpSdk, OnlinePumpSdk, offline, online };
}

// v2 bonding curve helpers — buy_v2, sell_v2, create_v2, USDC quote support
export async function getPumpSdkV2({ network = 'mainnet' } = {}) {
	const [pumpPkg, web3, BN] = await Promise.all([
		import('@pump-fun/pump-sdk'),
		import('@solana/web3.js'),
		import('bn.js').then((m) => m.default || m),
	]);
	const {
		PUMP_SDK,
		OnlinePumpSdk,
		bondingCurvePda,
		isLegacyQuoteMint,
		getBuyTokenAmountFromSolAmount,
		getBuySolAmountFromTokenAmount,
		getSellSolAmountFromTokenAmount,
		newBondingCurve,
	} = pumpPkg;
	const connection = getConnection({ network });
	const onlineSdk = new OnlinePumpSdk(connection);
	return {
		PUMP_SDK,
		onlineSdk,
		connection,
		bondingCurvePda,
		isLegacyQuoteMint,
		getBuyTokenAmountFromSolAmount,
		getBuySolAmountFromTokenAmount,
		getSellSolAmountFromTokenAmount,
		newBondingCurve,
		BN,
		web3,
	};
}

export async function getPumpTradeClient({ network = 'mainnet' } = {}) {
	const [{ PumpTradeClient }, web3, BN] = await Promise.all([
		import('@three-ws/agent-payments'),
		import('@solana/web3.js'),
		import('bn.js').then((m) => m.default || m),
	]);
	const connection = getConnection({ network });
	const client = new PumpTradeClient(connection);
	return { client, connection, BN, web3 };
}

export async function getPumpSwapSdk({ network = 'mainnet' } = {}) {
	const [{ PumpAmmSdk, PumpAmmAdminSdk }, web3, BN] = await Promise.all([
		import('@pump-fun/pump-swap-sdk'),
		import('@solana/web3.js'),
		import('bn.js').then((m) => m.default || m),
	]);
	const connection = getConnection({ network });
	const sdk = new PumpAmmSdk(connection);
	const internalSdk = PumpAmmAdminSdk ? new PumpAmmAdminSdk(connection) : null;
	return { sdk, internalSdk, connection, BN, web3 };
}

export async function getPumpAgent({ network = 'mainnet', mint } = {}) {
	if (!mint) throw Object.assign(new Error('mint required'), { status: 400 });
	const [{ PumpAgent, getTokenAgentPaymentsPDA }, web3, BN] = await Promise.all([
		import('@three-ws/agent-payments'),
		import('@solana/web3.js'),
		import('bn.js').then((m) => m.default || m),
	]);
	const connection = getConnection({ network });
	const mintPk = mint instanceof PublicKey ? mint : new PublicKey(mint);
	// Constructor is (mint, environment, connection) — the environment argument
	// sits BETWEEN the two. Passing the connection second leaves this.connection
	// undefined and every online read throws "Connection is required".
	const agent = new PumpAgent(mintPk, network === 'devnet' ? 'devnet' : 'mainnet', connection);
	const [agentPda] = getTokenAgentPaymentsPDA ? getTokenAgentPaymentsPDA(mintPk) : [null];
	return { agent, connection, BN, web3, agentPda };
}

export async function getPumpAgentOffline({ network = 'mainnet', mint } = {}) {
	if (!mint) throw Object.assign(new Error('mint required'), { status: 400 });
	const [{ PumpAgentOffline, getTokenAgentPaymentsPDA, getInvoiceIdPDA }, web3, BN] =
		await Promise.all([
			import('@three-ws/agent-payments'),
			import('@solana/web3.js'),
			import('bn.js').then((m) => m.default || m),
		]);
	const mintPk = mint instanceof PublicKey ? mint : new PublicKey(mint);
	const offline = PumpAgentOffline.load
		? PumpAgentOffline.load(mintPk, getConnection({ network }))
		: new PumpAgentOffline(mintPk);
	const [agentPda] = getTokenAgentPaymentsPDA ? getTokenAgentPaymentsPDA(mintPk) : [null];
	return { offline, getInvoiceIdPDA, BN, web3, agentPda };
}

// Confirm a signature on-chain. Returns the parsed tx (versioned-aware).
// Throws { status: 422, code } on failure so handlers can `try/catch`.
export async function verifySignature({ network, signature }) {
	const connection = getConnection({ network });
	let tx;
	try {
		tx = await connection.getParsedTransaction(signature, {
			maxSupportedTransactionVersion: 1,
			commitment: 'confirmed',
		});
	} catch {
		const e = new Error('transaction not found');
		e.status = 422;
		e.code = 'tx_not_found';
		throw e;
	}
	if (!tx) {
		const e = new Error('transaction not found');
		e.status = 422;
		e.code = 'tx_not_found';
		throw e;
	}
	if (tx.meta?.err) {
		const e = new Error('transaction failed on-chain');
		e.status = 422;
		e.code = 'tx_failed';
		throw e;
	}
	return tx;
}

// Collect every program id invoked by a parsed transaction — both top-level
// instructions and the CPIs recorded in `meta.innerInstructions`. Works for the
// `getParsedTransaction` shape, where each instruction (parsed or partially
// decoded) carries a `programId` that is a PublicKey or a base58 string.
export function txProgramIds(tx) {
	const ids = new Set();
	const add = (ix) => {
		const pid = ix?.programId;
		if (!pid) return;
		ids.add(typeof pid === 'string' ? pid : pid.toString());
	};
	for (const ix of tx?.transaction?.message?.instructions || []) add(ix);
	for (const group of tx?.meta?.innerInstructions || []) {
		for (const ix of group?.instructions || []) add(ix);
	}
	return ids;
}

// True when a confirmed tx actually invoked the pump.fun bonding-curve program.
// launch-confirm uses this so a tx that merely *references* the new mint pubkey
// (e.g. a memo/transfer touching that account) can never be recorded in
// pump_agent_mints as a real launch — the program must have run. Future-proof by
// design: it asserts the program, not a specific create-instruction
// discriminator, so a new create variant keeps confirming cleanly.
export function txInvokesPumpProgram(tx) {
	return txProgramIds(tx).has(PUMP_PROGRAM_ID);
}

// True when a confirmed tx actually invoked the three.ws agent-payments program.
// withdraw-confirm uses this for the same reason launch-confirm asserts the
// bonding-curve program: a succeeded tx that merely *lists* the agent mint and
// its authority among its accounts (any transfer or memo touching them does)
// would otherwise be reported back as a confirmed payout.
export function txInvokesAgentPaymentsProgram(tx) {
	return txProgramIds(tx).has(PUMP_AGENT_PAYMENTS_PROGRAM_ID);
}

// Resolve the canonical pump.fun AMM pool for `mint` (post-graduation). Pass
// `quoteMint` for USDC-paired coins — derives the PDA with the explicit quote
// mint instead of the default WSOL PDA. Omit (or pass null) for SOL-paired coins.
// return everything `buyQuoteInput` / `sellBaseInput` need to price a swap.
// Quote currency is WSOL on the canonical pool.
//
// Returns BOTH `quoteReserve` (raw vault balance) and `effectiveQuoteReserve`
// (raw + virtual). See the note at the reserve decode below for which to use.
//
// Throws { status: 404, code: 'pool_not_found' } if no pool exists yet.
export async function getAmmPoolState({ network = 'mainnet', mint, quoteMint = null } = {}) {
	if (!mint) throw Object.assign(new Error('mint required'), { status: 400 });
	const [{ canonicalPumpPoolPda, OnlinePumpAmmSdk, PumpAmmSdk }, web3, BN, spl] =
		await Promise.all([
			import('@pump-fun/pump-swap-sdk'),
			import('@solana/web3.js'),
			import('bn.js').then((m) => m.default || m),
			import('@solana/spl-token'),
		]);
	const connection = getConnection({ network });
	const mintPk = mint instanceof PublicKey ? mint : new PublicKey(mint);
	const quoteMintPk =
		quoteMint instanceof PublicKey ? quoteMint : quoteMint ? new PublicKey(quoteMint) : null;
	const poolKey = quoteMintPk
		? canonicalPumpPoolPda(mintPk, quoteMintPk)
		: canonicalPumpPoolPda(mintPk);

	const online = new OnlinePumpAmmSdk(connection);
	let pool;
	try {
		pool = await online.fetchPool(poolKey);
	} catch {
		const e = new Error('pump.fun AMM pool not found for mint');
		e.status = 404;
		e.code = 'pool_not_found';
		throw e;
	}

	let baseAccInfo, quoteAccInfo, baseMintInfo;
	try {
		[baseAccInfo, quoteAccInfo, baseMintInfo] = await Promise.all([
			connection.getAccountInfo(pool.poolBaseTokenAccount),
			connection.getAccountInfo(pool.poolQuoteTokenAccount),
			connection.getAccountInfo(pool.baseMint),
		]);
	} catch (err) {
		// A dead RPC lane is retryable and says nothing about the pool.
		if (isRpcOutageError(err)) throw rpcUnavailableError('pool reserves could not be read: Solana RPC is temporarily unavailable', err);
		throw err;
	}
	if (!baseAccInfo || !quoteAccInfo || !baseMintInfo) {
		const e = new Error('pool token accounts unavailable');
		e.status = 502;
		e.code = 'pool_accounts_missing';
		throw e;
	}
	const baseAcc = spl.AccountLayout.decode(baseAccInfo.data);
	const quoteAcc = spl.AccountLayout.decode(quoteAccInfo.data);
	const baseMintAccount = spl.MintLayout.decode(baseMintInfo.data);
	const baseReserve = new BN(baseAcc.amount.toString());
	const quoteReserve = new BN(quoteAcc.amount.toString());

	// PumpSwap prices against EFFECTIVE quote reserves, not the raw vault balance:
	//   effective = quote_vault_balance + pool.virtual_quote_reserves
	// The field shipped 2026-07-15 at 0 on every pool and went non-zero on
	// 2026-07-20. Per the IDL it stays 0 on non-boost pools, where effective ==
	// raw and quotes are unchanged. The base side is untouched by all of this.
	//
	// It is an i128, so it is SIGNED: effective can be LOWER than the raw vault
	// balance. Anchor decodes it to a signed BN and BN.add handles that, so the
	// arithmetic below is correct as written. Do not "fix" it by clamping to 0
	// or by re-reading the bytes unsigned; an unsigned read flips a negative
	// into a huge positive that reads as near-infinite depth.
	//
	// Two consumers, two different values — do not mix them up:
	//   · SDK quote fns (buyQuoteInput/sellBaseInput) take `virtualQuoteReserves`
	//     as its OWN argument and add it internally. Pass the raw `quoteReserve`
	//     alongside it; passing an already-summed reserve double-counts.
	//   · Our own spot-price / price-impact math takes `effectiveQuoteReserve`.
	// A pool decoded by an SDK older than 1.19.0 has no field; default to 0 so
	// this stays correct rather than NaN.
	const virtualQuoteReserves = new BN((pool.virtualQuoteReserves ?? 0).toString());
	const effectiveQuoteReserve = quoteReserve.add(virtualQuoteReserves);

	const offline = new PumpAmmSdk();
	let globalConfigInfo, feeConfigInfo;
	try {
		[globalConfigInfo, feeConfigInfo] = await Promise.all([
			connection.getAccountInfo((await import('@pump-fun/pump-swap-sdk')).GLOBAL_CONFIG_PDA),
			connection.getAccountInfo(
				(await import('@pump-fun/pump-swap-sdk')).PUMP_AMM_FEE_CONFIG_PDA,
			),
		]);
	} catch (err) {
		if (isRpcOutageError(err)) throw rpcUnavailableError('pool fee config could not be read: Solana RPC is temporarily unavailable', err);
		throw err;
	}
	const globalConfig = globalConfigInfo ? offline.decodeGlobalConfig(globalConfigInfo) : null;
	const feeConfig = feeConfigInfo ? offline.decodeFeeConfig(feeConfigInfo) : null;

	return {
		connection,
		poolKey,
		pool,
		baseReserve,
		quoteReserve,
		virtualQuoteReserves,
		effectiveQuoteReserve,
		baseMintAccount,
		globalConfig,
		feeConfig,
		BN,
		web3,
	};
}

// Build a versioned tx from a list of instructions, return base64 (unsigned).
// Mirrors the pattern used in api/agents/solana-register-prep.js so frontends
// can decode via VersionedTransaction.deserialize and submit via injected wallet.
export async function buildUnsignedTxBase64({ network, payer, instructions }) {
	const [{ TransactionMessage, VersionedTransaction, PublicKey: PK }] = await Promise.all([
		import('@solana/web3.js'),
	]);
	const connection = getConnection({ network });
	let blockhash;
	try {
		({ blockhash } = await connection.getLatestBlockhash('confirmed'));
	} catch (err) {
		if (isRpcOutageError(err)) throw rpcUnavailableError('could not fetch a recent blockhash: Solana RPC is temporarily unavailable', err);
		throw err;
	}
	const payerPk = payer instanceof PK ? payer : new PK(payer);
	const msg = new TransactionMessage({
		payerKey: payerPk,
		recentBlockhash: blockhash,
		instructions,
	}).compileToV0Message();
	const vtx = new VersionedTransaction(msg);
	return Buffer.from(vtx.serialize()).toString('base64');
}