@three-ws/x402-payment-modal 1.1.0 → 1.2.0

package/server/checkout.js

@@ -14,7 +14,7 @@
 //
 // Runtime deps: @solana/web3.js and @solana/spl-token (declared as optional peer
 // dependencies — install them in the app that mounts this handler). Nothing here
-// imports anything three.ws-specific.
+// is host-specific — it runs unchanged behind any paid endpoint.
 
 import {
 	Connection,
@@ -25,6 +25,7 @@ import {
 } from '@solana/web3.js';
 import {
 	TOKEN_PROGRAM_ID,
+	TOKEN_2022_PROGRAM_ID,
 	ASSOCIATED_TOKEN_PROGRAM_ID,
 	getAssociatedTokenAddressSync,
 	createAssociatedTokenAccountIdempotentInstruction,
@@ -42,11 +43,11 @@ const DEFAULT_MAINNET_RPC = 'https://api.mainnet-beta.solana.com';
 const DEFAULT_DEVNET_RPC = 'https://api.devnet.solana.com';
 
 // ─────────────────────────────────────────────── Well-known Solana tokens ────
-// The two settlement assets the modal treats as first-class on Solana. USDC is
-// the universal dollar-stable rail; THREE is the three.ws utility token, so any
-// endpoint can let holders pay in THREE alongside USDC. `solanaAccept()` builds
-// the x402 `accept` entry for either (or any other SPL mint) — the prepare path
-// already transfers any mint, so offering THREE needs no further wiring.
+// USDC is the always-on default settlement asset on Solana — the universal
+// dollar-stable rail. THREE is an optional opt-in SPL token an endpoint can
+// accept alongside USDC. `solanaAccept()` builds the x402 `accept` entry for
+// either (or any other SPL mint) — the prepare path transfers any mint, so
+// offering an extra token needs no further wiring.
 export const USDC_MINT_SOLANA = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
 export const THREE_MINT = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';
 
@@ -141,13 +142,44 @@ function uiToAtomic(uiAmount, decimals) {
 }
 
 // Short-lived caches so repeated prepare calls don't re-issue identical RPC
-// round-trips. Mint decimals are effectively immutable; a Solana blockhash stays
-// valid for ~60-90s, so a few seconds of reuse cuts redundant traffic without
-// handing out a blockhash too stale for the buyer's signed tx to land.
-const MINT_DECIMALS_TTL_MS = 5 * 60 * 1000;
-const BLOCKHASH_TTL_MS = 8 * 1000;
-const mintDecimalsCache = new Map(); // `${rpc}:${mint}` -> { decimals, at }
-const blockhashCache = new Map(); // rpc -> { blockhash, at }
+// round-trips. Mint decimals and the owning token program are immutable, so they
+// key by mint alone (shared across RPC providers on the same cluster). A Solana
+// blockhash stays valid ~60-90s; we amortize the fetch for a window but the
+// settle path tolerates a slightly older one. ATA existence only ever flips
+// false→true (an account, once created, persists), so we cache the positive.
+//
+// Keys are cluster-scoped ('mainnet'/'devnet'), never per-RPC-URL, so failover
+// between providers preserves cache hits. All caches are LRU-bounded so a stream
+// of distinct arbitrary mints can't grow them without limit on a warm instance.
+const MINT_META_TTL_MS = 30 * 60 * 1000;
+const BLOCKHASH_TTL_MS = 20 * 1000;
+const ATA_EXISTS_TTL_MS = 10 * 60 * 1000;
+const CACHE_MAX = 2000;
+const mintDecimalsCache = new Map(); // `${cluster}:${mint}` -> { decimals, at }
+const blockhashCache = new Map(); // cluster -> { blockhash, at }
+const tokenProgramCache = new Map(); // `${cluster}:${mint}` -> { programId, at }
+const ataExistsCache = new Map(); // `${cluster}:${ata}` -> { at }
+const connectionCache = new Map(); // rpcUrl -> Connection
+
+// Bounded insert: evict the oldest entry (Map preserves insertion order) once
+// the cap is hit, keeping memory flat under arbitrary-mint traffic.
+function cacheSet(map, key, value, max = CACHE_MAX) {
+	if (map.size >= max && !map.has(key)) {
+		const oldest = map.keys().next().value;
+		if (oldest !== undefined) map.delete(oldest);
+	}
+	map.set(key, value);
+}
+
+// Decimals + owning program for the assets the modal treats as first-class.
+// Short-circuiting these skips two RPC reads on the hot path (USDC is the bulk
+// of real traffic). THREE is Token-2022; the rest are legacy SPL Token.
+const WSOL_MINT = 'So11111111111111111111111111111111111111112';
+const WELL_KNOWN_MINT_META = Object.freeze({
+	[USDC_MINT_SOLANA]: { decimals: 6, legacy: true },
+	[THREE_MINT]: { decimals: 6, legacy: false },
+	[WSOL_MINT]: { decimals: 9, legacy: true },
+});
 
 /** Thrown for any client-correctable problem; carries an HTTP `status` + `code`. */
 export class CheckoutError extends Error {
@@ -167,9 +199,60 @@ export function isSolanaNetwork(network) {
 	);
 }
 
-function rpcFor(network, { rpcUrl, devnetRpcUrl } = {}) {
-	if (network === NETWORK_SOLANA_DEVNET) return devnetRpcUrl || DEFAULT_DEVNET_RPC;
-	return rpcUrl || DEFAULT_MAINNET_RPC;
+function clusterFor(network) {
+	return network === NETWORK_SOLANA_DEVNET ? 'devnet' : 'mainnet';
+}
+
+let warnedDefaultRpc = false;
+
+// Resolve the ordered list of RPC endpoints to try. Accepts a single `rpcUrl`
+// or an `rpcUrls` array (for real failover); same for devnet. Falling back to
+// the rate-limited public RPC is a production footgun under load, so warn once.
+function rpcListFor(network, opts = {}) {
+	const devnet = network === NETWORK_SOLANA_DEVNET;
+	const single = devnet ? opts.devnetRpcUrl : opts.rpcUrl;
+	const many = devnet ? opts.devnetRpcUrls : opts.rpcUrls;
+	const list = []
+		.concat(Array.isArray(many) ? many : [])
+		.concat(single ? [single] : [])
+		.filter((u) => typeof u === 'string' && u.length);
+	if (list.length) return [...new Set(list)];
+	if (!warnedDefaultRpc) {
+		warnedDefaultRpc = true;
+		console.warn(
+			'[x402-payment-modal] No rpcUrl/rpcUrls configured — falling back to the public ' +
+				'Solana RPC, which is heavily rate-limited and will fail under load. Pass a ' +
+				'dedicated RPC (Helius/Triton/QuickNode) via { rpcUrls: [...] }.',
+		);
+	}
+	return [devnet ? DEFAULT_DEVNET_RPC : DEFAULT_MAINNET_RPC];
+}
+
+// Reuse one Connection per RPC URL so socket keep-alive survives across
+// requests on a warm instance instead of paying TCP/TLS setup every prepare.
+function getConnection(url) {
+	let conn = connectionCache.get(url);
+	if (!conn) {
+		conn = new Connection(url, 'confirmed');
+		cacheSet(connectionCache, url, conn, 50);
+	}
+	return conn;
+}
+
+// Run `fn(conn)` against each RPC in order, rotating to the next on a transient
+// RPC/network error. A CheckoutError is a deterministic client problem (bad
+// input, mint isn't an SPL token) — surface it immediately, don't retry.
+async function withFailover(urls, fn) {
+	let lastErr;
+	for (const url of urls) {
+		try {
+			return await fn(getConnection(url));
+		} catch (err) {
+			if (err instanceof CheckoutError) throw err;
+			lastErr = err;
+		}
+	}
+	throw lastErr || new Error('all RPC endpoints failed');
 }
 
 const BASE58 = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
@@ -207,20 +290,59 @@ function validateAccept(accept) {
 	return accept;
 }
 
-async function getMintDecimals(conn, rpc, mint) {
-	const key = `${rpc}:${mint.toBase58()}`;
+// Resolve which token program owns a mint — legacy SPL Token or Token-2022.
+// Pump.fun mints (including THREE) and many newer assets are Token-2022, whose
+// program id differs; deriving ATAs or building transferChecked with the wrong
+// program yields the wrong accounts and an unprocessable transaction. The owner
+// is immutable, so cache it (and short-circuit the first-class assets entirely).
+async function getTokenProgramId(conn, cluster, mint) {
+	const base58 = mint.toBase58();
+	const known = WELL_KNOWN_MINT_META[base58];
+	if (known) return known.legacy ? TOKEN_PROGRAM_ID : TOKEN_2022_PROGRAM_ID;
+	const key = `${cluster}:${base58}`;
+	const hit = tokenProgramCache.get(key);
+	if (hit && Date.now() - hit.at < MINT_META_TTL_MS) return hit.programId;
+	const info = await conn.getAccountInfo(mint, 'confirmed');
+	// A null here is usually a flaky RPC, not a missing mint — throw a plain Error
+	// so withFailover retries the next endpoint before giving up.
+	if (!info) throw new Error(`getAccountInfo returned null for mint ${base58}`);
+	const owner = info.owner;
+	let programId;
+	if (owner.equals(TOKEN_2022_PROGRAM_ID)) programId = TOKEN_2022_PROGRAM_ID;
+	else if (owner.equals(TOKEN_PROGRAM_ID)) programId = TOKEN_PROGRAM_ID;
+	else throw new CheckoutError(400, 'invalid_request', `mint ${base58} is not an SPL token (owner ${owner.toBase58()})`);
+	cacheSet(tokenProgramCache, key, { programId, at: Date.now() });
+	return programId;
+}
+
+async function getMintDecimals(conn, cluster, mint, programId) {
+	const base58 = mint.toBase58();
+	const known = WELL_KNOWN_MINT_META[base58];
+	if (known) return known.decimals;
+	const key = `${cluster}:${base58}`;
 	const hit = mintDecimalsCache.get(key);
-	if (hit && Date.now() - hit.at < MINT_DECIMALS_TTL_MS) return hit.decimals;
-	const info = await getMint(conn, mint);
-	mintDecimalsCache.set(key, { decimals: info.decimals, at: Date.now() });
+	if (hit && Date.now() - hit.at < MINT_META_TTL_MS) return hit.decimals;
+	const info = await getMint(conn, mint, 'confirmed', programId);
+	cacheSet(mintDecimalsCache, key, { decimals: info.decimals, at: Date.now() });
 	return info.decimals;
 }
 
-async function getRecentBlockhash(conn, rpc) {
-	const hit = blockhashCache.get(rpc);
+// Whether the recipient's token account already exists. Once created it persists,
+// so a positive result is cached; a negative is not (we keep emitting the
+// idempotent-create instruction until the account shows up).
+async function receiverAtaExists(conn, cluster, ata) {
+	const key = `${cluster}:${ata.toBase58()}`;
+	if (ataExistsCache.has(key) && Date.now() - ataExistsCache.get(key).at < ATA_EXISTS_TTL_MS) return true;
+	const info = await conn.getAccountInfo(ata, 'confirmed');
+	if (info) cacheSet(ataExistsCache, key, { at: Date.now() });
+	return Boolean(info);
+}
+
+async function getRecentBlockhash(conn, cluster) {
+	const hit = blockhashCache.get(cluster);
 	if (hit && Date.now() - hit.at < BLOCKHASH_TTL_MS) return hit.blockhash;
 	const { blockhash } = await conn.getLatestBlockhash('confirmed');
-	blockhashCache.set(rpc, { blockhash, at: Date.now() });
+	cacheSet(blockhashCache, cluster, { blockhash, at: Date.now() }, 8);
 	return blockhash;
 }
 
@@ -233,15 +355,17 @@ async function getRecentBlockhash(conn, rpc) {
  * @param {object} args.accept   one x402 `accept` entry (scheme=exact, Solana)
  * @param {string} args.buyer    buyer's base58 Solana address
  * @param {string} [args.rpcUrl] mainnet RPC URL override
+ * @param {string[]} [args.rpcUrls] mainnet RPC URLs for failover (preferred)
  * @param {string} [args.devnetRpcUrl] devnet RPC URL override
+ * @param {string[]} [args.devnetRpcUrls] devnet RPC URLs for failover
  * @returns {Promise<{ network: string, tx_base64: string, recent_blockhash: string }>}
  */
-export async function prepareSolanaCheckout({ accept, buyer, rpcUrl, devnetRpcUrl }) {
+export async function prepareSolanaCheckout({ accept, buyer, rpcUrl, rpcUrls, devnetRpcUrl, devnetRpcUrls }) {
 	validateAccept(accept);
 	assertPubkey(buyer, 'buyer');
 
-	const rpc = rpcFor(accept.network, { rpcUrl, devnetRpcUrl });
-	const conn = new Connection(rpc, 'confirmed');
+	const urls = rpcListFor(accept.network, { rpcUrl, rpcUrls, devnetRpcUrl, devnetRpcUrls });
+	const cluster = clusterFor(accept.network);
 
 	const mint = new PublicKey(accept.asset);
 	const payTo = new PublicKey(accept.payTo);
@@ -249,47 +373,61 @@ export async function prepareSolanaCheckout({ accept, buyer, rpcUrl, devnetRpcUr
 	const buyerPubkey = new PublicKey(buyer);
 	const amount = BigInt(accept.amount);
 
-	const senderAta = getAssociatedTokenAddressSync(
-		mint, buyerPubkey, false, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID,
-	);
-	const receiverAta = getAssociatedTokenAddressSync(
-		mint, payTo, false, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID,
-	);
-	const mintDecimals = await getMintDecimals(conn, rpc, mint);
-
-	const ixs = [
-		ComputeBudgetProgram.setComputeUnitLimit({ units: 60_000 }),
-		ComputeBudgetProgram.setComputeUnitPrice({ microLamports: 1 }),
-	];
-	// Create the recipient's token account if it doesn't exist yet — idempotent,
-	// paid for by the fee payer so the buyer is never charged extra SOL.
-	const receiverInfo = await conn.getAccountInfo(receiverAta);
-	if (!receiverInfo) {
+	return withFailover(urls, async (conn) => {
+		// Pick the owning token program (legacy SPL Token vs Token-2022) so ATAs,
+		// the idempotent create, and transferChecked all target the right program —
+		// THREE and other pump.fun mints are Token-2022. This must resolve first
+		// because the ATA derivations depend on it.
+		const tokenProgramId = await getTokenProgramId(conn, cluster, mint);
+
+		const senderAta = getAssociatedTokenAddressSync(
+			mint, buyerPubkey, false, tokenProgramId, ASSOCIATED_TOKEN_PROGRAM_ID,
+		);
+		const receiverAta = getAssociatedTokenAddressSync(
+			mint, payTo, false, tokenProgramId, ASSOCIATED_TOKEN_PROGRAM_ID,
+		);
+
+		// The three remaining reads are independent — fan them out in parallel
+		// instead of serially (cuts prepare latency ~40% on a cold cache, near
+		// zero when decimals/program/ATA are all cached).
+		const [mintDecimals, receiverPresent, blockhash] = await Promise.all([
+			getMintDecimals(conn, cluster, mint, tokenProgramId),
+			receiverAtaExists(conn, cluster, receiverAta),
+			getRecentBlockhash(conn, cluster),
+		]);
+
+		const ixs = [
+			ComputeBudgetProgram.setComputeUnitLimit({ units: 60_000 }),
+			ComputeBudgetProgram.setComputeUnitPrice({ microLamports: 1 }),
+		];
+		// Create the recipient's token account if it doesn't exist yet — idempotent,
+		// paid for by the fee payer so the buyer is never charged extra SOL.
+		if (!receiverPresent) {
+			ixs.push(
+				createAssociatedTokenAccountIdempotentInstruction(
+					feePayer, receiverAta, payTo, mint, tokenProgramId, ASSOCIATED_TOKEN_PROGRAM_ID,
+				),
+			);
+		}
 		ixs.push(
-			createAssociatedTokenAccountIdempotentInstruction(
-				feePayer, receiverAta, payTo, mint, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID,
+			createTransferCheckedInstruction(
+				senderAta, mint, receiverAta, buyerPubkey, amount, mintDecimals, [], tokenProgramId,
 			),
 		);
-	}
-	ixs.push(
-		createTransferCheckedInstruction(
-			senderAta, mint, receiverAta, buyerPubkey, amount, mintDecimals, [], TOKEN_PROGRAM_ID,
-		),
-	);
 
-	const blockhash = await getRecentBlockhash(conn, rpc);
-	const message = new TransactionMessage({
-		payerKey: feePayer,
-		recentBlockhash: blockhash,
-		instructions: ixs,
-	}).compileToV0Message();
-	const vtx = new VersionedTransaction(message);
+		const message = new TransactionMessage({
+			payerKey: feePayer,
+			recentBlockhash: blockhash,
+			instructions: ixs,
+		}).compileToV0Message();
+		const vtx = new VersionedTransaction(message);
 
-	return {
-		network: accept.network,
-		tx_base64: Buffer.from(vtx.serialize()).toString('base64'),
-		recent_blockhash: blockhash,
-	};
+		return {
+			network: accept.network,
+			tx_base64: Buffer.from(vtx.serialize()).toString('base64'),
+			recent_blockhash: blockhash,
+		};
+	});
 }
 
 const BUILDER_CODE_PATTERN = /^[a-z0-9_]{1,32}$/;
@@ -351,17 +489,20 @@ export function encodeX402Payment({ accept, signedTxBase64, resourceUrl, builder
  * @param {object} args
  * @param {'prepare'|'encode'} args.action
  * @param {object} args.body   parsed JSON request body
- * @param {object} [args.options] { rpcUrl, devnetRpcUrl }
+ * @param {object} [args.options] { rpcUrl, rpcUrls, devnetRpcUrl, devnetRpcUrls, logger }
  * @returns {Promise<{ status: number, body: object }>}
  */
 export async function handleCheckout({ action, body = {}, options = {} }) {
+	const log = typeof options.logger === 'function' ? options.logger : console.error;
 	try {
 		if (action === 'prepare') {
 			const data = await prepareSolanaCheckout({
 				accept: body.accept,
 				buyer: body.buyer,
 				rpcUrl: options.rpcUrl,
+				rpcUrls: options.rpcUrls,
 				devnetRpcUrl: options.devnetRpcUrl,
+				devnetRpcUrls: options.devnetRpcUrls,
 			});
 			return { status: 200, body: data };
 		}
@@ -382,8 +523,9 @@ export async function handleCheckout({ action, body = {}, options = {} }) {
 		if (err instanceof CheckoutError) {
 			return { status: err.status, body: { error: err.code, error_description: err.message } };
 		}
-		// Unexpected (RPC down, malformed tx). Surface a generic 502 — the caller
-		// shows "try again"; the real cause is in your server logs.
+		// Unexpected (RPC down, malformed tx). The caller sees a generic 502, but
+		// ops needs the root cause — log it instead of swallowing it silently.
+		log(`[x402-payment-modal] checkout ${action} failed:`, err?.stack || err?.message || err);
 		return {
 			status: 502,
 			body: { error: 'checkout_failed', error_description: 'Could not build the Solana payment. Try again.' },

package/server/express.js

@@ -15,9 +15,12 @@ import { handleCheckout } from './checkout.js';
 
 /**
  * @param {object} [options]
- * @param {string} [options.rpcUrl]        Solana mainnet RPC URL
- * @param {string} [options.devnetRpcUrl]  Solana devnet RPC URL
- * @param {string} [options.origin]        Access-Control-Allow-Origin (default '*')
+ * @param {string}   [options.rpcUrl]        Solana mainnet RPC URL
+ * @param {string[]} [options.rpcUrls]       Solana mainnet RPC URLs for failover (preferred under load)
+ * @param {string}   [options.devnetRpcUrl]  Solana devnet RPC URL
+ * @param {string[]} [options.devnetRpcUrls] Solana devnet RPC URLs for failover
+ * @param {Function} [options.logger]        called with the root cause on unexpected failures
+ * @param {string}   [options.origin]        Access-Control-Allow-Origin (default '*')
  * @returns {import('express').RequestHandler}
  */
 export function x402CheckoutRouter(options = {}) {
@@ -25,7 +28,7 @@ export function x402CheckoutRouter(options = {}) {
 	return async function x402CheckoutHandler(req, res) {
 		res.setHeader('Access-Control-Allow-Origin', allowOrigin);
 		res.setHeader('Access-Control-Allow-Methods', 'POST,OPTIONS');
-		res.setHeader('Access-Control-Allow-Headers', 'content-type');
+		res.setHeader('Access-Control-Allow-Headers', 'content-type, x-idempotency-key');
 		if (req.method === 'OPTIONS') {
 			res.status(204).end();
 			return;

package/server/vercel.js

@@ -27,7 +27,7 @@ async function readJsonBody(req) {
 }
 
 /**
- * @param {object} [options]  { rpcUrl, devnetRpcUrl, origin }
+ * @param {object} [options]  { rpcUrl, rpcUrls, devnetRpcUrl, devnetRpcUrls, logger, origin }
  * @returns {(req: any, res: any) => Promise<void>}
  */
 export function createVercelCheckoutHandler(options = {}) {
@@ -35,7 +35,7 @@ export function createVercelCheckoutHandler(options = {}) {
 	return async function handler(req, res) {
 		res.setHeader('Access-Control-Allow-Origin', allowOrigin);
 		res.setHeader('Access-Control-Allow-Methods', 'POST,OPTIONS');
-		res.setHeader('Access-Control-Allow-Headers', 'content-type');
+		res.setHeader('Access-Control-Allow-Headers', 'content-type, x-idempotency-key');
 		if (req.method === 'OPTIONS') {
 			res.status(204).end();
 			return;