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.

15.5 KB
Raw Blame
// x402-checkout — buyer-side helper for the drop-in modal.
//
// The buyer's wallet (Phantom for Solana, MetaMask for EVM) needs to sign the
// payment payload that goes into the `X-PAYMENT` header. For EVM that's an
// EIP-712 typed-data signature the wallet builds locally. For Solana the
// wallet only signs serialized transactions — it does NOT build instructions.
// So we expose this endpoint: client posts { accept, buyer }, server returns
// a partially-signed v0 transaction ready for Phantom to add the payer's sig.
//
// Endpoints:
//   POST /api/x402-checkout?action=prepare   { accept, buyer }
//      → { network, tx_base64 }              v0 SPL transferChecked, fee payer
//                                            is accept.extra.feePayer (the
//                                            facilitator's sponsor account)
//   POST /api/x402-checkout?action=encode    { signed_tx_base64, accept, resource_url }
//      → { x_payment }                       base64 paymentPayload ready for
//                                            X-PAYMENT header
//
// We split prepare + encode so the modal can show "Sign in your wallet…" while
// Phantom is open, then "Sending…" while we wrap the signed tx into the
// x402 envelope. Keeps each step short and visible.

import { z } from 'zod';
import { solanaConnection } from './_lib/solana/connection.js';
import {
	PublicKey,
	TransactionMessage,
	VersionedTransaction,
	ComputeBudgetProgram,
} from '@solana/web3.js';
import {
	ASSOCIATED_TOKEN_PROGRAM_ID,
	getAssociatedTokenAddressSync,
	createAssociatedTokenAccountIdempotentInstruction,
	createTransferCheckedInstruction,
} from '@solana/spl-token';
import { cors, json, method, readJson, wrap, error, rateLimited } from './_lib/http.js';
import { parse } from './_lib/validate.js';
import { limits, clientIp } from './_lib/rate-limit.js';
import { NETWORK_SOLANA_MAINNET, NETWORK_SOLANA_DEVNET } from './_lib/x402-spec.js';
import { confirmSolanaPayment } from './_lib/x402-solana-confirm.js';
import { ataExists, getRecentBlockhash, mintDecimals, respondRpcUnavailable } from './_lib/solana/read-guards.js';
import { env } from './_lib/env.js';
import { tokenProgramForMint } from './_lib/solana-token-program.js';

// Routed through env.* so the `api-mainnet.helius-rpc.com` misconfig is repaired
// (env.normalizeRpcUrl) — a bad host 404'd getAccountInfo on the USDC mint here.
const SOLANA_RPC = env.SOLANA_RPC_URL;
const SOLANA_DEVNET_RPC = env.SOLANA_RPC_URL_DEVNET;

// The three RPC reads on the prepare hot path (mint decimals, ATA existence, a
// recent blockhash) go through the shared money-path guards: canonical mints
// resolve locally, an ATA probe fails open to "missing" (the create is
// idempotent), and a blockhash is served from cache inside its validity window
// when every RPC endpoint fails. See api/_lib/solana/read-guards.js. The two
// helpers stay exported from here because the checkout tests exercise them.
export { ataExists, getRecentBlockhash };

// Build a PublicKey from a (schema-trimmed) address, converting web3.js's raw
// "Non-base58 character" / "Invalid public key" throw into a structured 400.
// Without this, a malformed address in the posted `accept` surfaces as an opaque
// 500 — the exact failure that took down USDC checkout when a stray newline rode
// in on the challenge's payTo.
function toPubkey(value, field) {
	try {
		return new PublicKey(value);
	} catch {
		const err = new Error(`${field} is not a valid Solana address`);
		err.status = 400;
		err.code = 'invalid_address';
		throw err;
	}
}

// Solana addresses arrive inside the 402 challenge's `accept` entry, which is
// built from operator-configured env (X402_PAY_TO_SOLANA / X402_FEE_PAYER_SOLANA).
// Those values are pasted into dashboards and routinely carry a trailing newline
// or stray spaces. `.trim()` here means a whitespace-tainted challenge still
// yields a working transaction instead of 500'ing on `new PublicKey()` — the
// same defensive posture as env.js's addr(). Length is checked post-trim.
const solanaAddress = z.string().trim().min(32).max(44);

export const acceptSchema = z.object({
	scheme: z.literal('exact'),
	network: z.string().trim().min(1).max(80),
	amount: z.string().regex(/^\d+$/),
	asset: solanaAddress,
	payTo: solanaAddress,
	maxTimeoutSeconds: z.number().int().positive().optional(),
	extra: z
		.object({
			name: z.string().optional(),
			decimals: z.number().int().nonnegative().optional(),
			// Optional on purpose: an accept with no feePayer is the self-pay
			// contract, where the buyer signs as their own fee payer and no
			// sponsor is involved. Requiring it here would reject the very
			// challenge a paid endpoint issues when its sponsor wallet is empty.
			feePayer: solanaAddress.optional(),
		})
		.passthrough(),
});

// Optional buyer-approved donations appended to the same signed transaction as
// the payment (charity split + round-up giving). The buyer always sees and
// signs these in the modal — the merchant only configures the destination/rule.
// Routes the same mint as the payment, so each tip is an extra transferChecked
// to the cause's ATA. Capped to keep a misconfigured giving rule from ever
// sweeping a buyer: ≤ 100 tokens and ≤ 50× the payment per recipient.
const TIP_ABS_MAX = 100_000_000n; // 100 USDC in 6-decimal atomics
const tipSchema = z.object({
	to: z.string().trim().min(32).max(44),
	amount: z.string().regex(/^\d+$/),
});

// Validate one buyer-approved donation against the safety caps. Pure and
// exported so the money-moving rules — well-formed recipient/amount, ≤ 100
// tokens AND ≤ 50× the payment, and recipient ≠ the merchant payout — are
// unit-testable without building a Solana transaction. The handler appends a
// transferChecked only for an `ok` result. Returns exactly one of:
//   { skip: true }                       — zero/negative amount, nothing to send
//   { ok: true, to: PublicKey, amount }  — validated, ready to route
//   { ok: false, code, message }         — rejected; caller emits a 400
export function validateTip(tip, { payTo, paymentAmount }) {
	let to;
	try {
		to = new PublicKey(tip.to);
	} catch {
		return { ok: false, code: 'invalid_tip', message: `donation recipient is not a valid address: ${tip.to}` };
	}
	let amount;
	try {
		amount = BigInt(tip.amount);
	} catch {
		return { ok: false, code: 'invalid_tip', message: 'donation amount must be a whole token amount' };
	}
	if (amount <= 0n) return { skip: true };
	if (amount > TIP_ABS_MAX || amount > paymentAmount * 50n) {
		return {
			ok: false,
			code: 'tip_too_large',
			message: 'donation exceeds the safety cap (≤ 100 tokens and ≤ 50× the payment) — check the giving configuration',
		};
	}
	if (to.equals(payTo)) {
		return { ok: false, code: 'invalid_tip', message: 'donation recipient cannot be the payment recipient' };
	}
	return { ok: true, to, amount };
}

export const prepareSchema = z.object({
	accept: acceptSchema,
	buyer: solanaAddress,
	tips: z.array(tipSchema).max(2).optional(),
});

const builderCodeBlockSchema = z
	.object({
		a: z.string().regex(/^[a-z0-9_]{1,32}$/),
		w: z
			.string()
			.regex(/^[a-z0-9_]{1,32}$/)
			.optional(),
		s: z
			.array(z.string().regex(/^[a-z0-9_]{1,32}$/))
			.max(32)
			.optional(),
	})
	.optional();

const encodeSchema = z.object({
	accept: acceptSchema,
	signed_tx_base64: z.string().min(40).max(20_000),
	resource_url: z.string().url(),
	builder_code: builderCodeBlockSchema,
});

export default wrap(async (req, res) => {
	// Public, cross-origin endpoint — the drop-in script runs on any merchant
	// site and POSTs here. No credentials, allow any origin.
	if (cors(req, res, { origins: '*', methods: 'POST,OPTIONS' })) return;
	if (!method(req, res, ['POST'])) return;

	const action = req.query?.action;
	if (action === 'prepare') {
		try {
			return await handlePrepare(req, res);
		} catch (err) {
			// Every read on the prepare path is already fail-open or cache-backed, so
			// reaching here means the chain was unreadable with nothing cached. Answer
			// a typed 503 with Retry-After instead of an opaque internal_error.
			if (respondRpcUnavailable(res, err)) return;
			throw err;
		}
	}
	if (action === 'encode') return handleEncode(req, res);
	return error(res, 404, 'not_found', `unknown action: ${action ?? '(none)'}`);
});

function isSolanaNetwork(network) {
	return (
		network === NETWORK_SOLANA_MAINNET ||
		network === NETWORK_SOLANA_DEVNET ||
		network === 'solana'
	);
}

function rpcFor(network) {
	if (network === NETWORK_SOLANA_DEVNET) return SOLANA_DEVNET_RPC;
	return SOLANA_RPC;
}

async function handlePrepare(req, res) {
	// Per-IP rate limit: prepare fans out to multiple Solana RPC round-trips, so
	// throttle anonymous callers to stop quota-drain / cost amplification against
	// the (potentially paid) upstream RPC.
	const rl = await limits.x402PayIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl, 'too many prepare requests');

	const body = parse(prepareSchema, await readJson(req));
	const { accept, buyer, tips } = body;
	if (!isSolanaNetwork(accept.network)) {
		return error(
			res,
			400,
			'unsupported_network',
			`prepare only builds Solana transactions; got network=${accept.network}. EVM clients sign EIP-712 typed data locally and don't need this endpoint.`,
		);
	}

	const rpc = rpcFor(accept.network);
	const conn = solanaConnection({ url: rpc, commitment: 'confirmed' });
	const mint = toPubkey(accept.asset, 'asset');
	const payTo = toPubkey(accept.payTo, 'payTo');
	const buyerPubkey = toPubkey(buyer, 'buyer');
	// Who pays the Solana fee. Sponsor mode (the default) is a convenience we
	// offer so a buyer holding only USDC can pay without owning any SOL, and it
	// costs the platform a fee per settle. It is NOT a requirement for receiving
	// money: an accept advertised without `extra.feePayer` means "you pay your
	// own gas", the buyer signs as fee payer, and the facilitator broadcasts a
	// fully-signed transaction without touching a sponsor key or a lamport of
	// ours. That is the mode a paid endpoint falls back to when the sponsor
	// wallet is dry, so the door stays open instead of answering 503.
	const selfPay = !accept.extra?.feePayer;
	const feePayer = selfPay ? buyerPubkey : toPubkey(accept.extra.feePayer, 'feePayer');
	const amount = BigInt(accept.amount);

	// The owning program decides every ATA address and the transfer's program id.
	// USDC is classic SPL Token and $THREE is Token-2022, so resolve it per mint
	// instead of assuming classic: a classic-built $THREE transfer names a source
	// ATA that does not exist and can never settle.
	const tokenProgram = await tokenProgramForMint(conn, mint);

	const senderAta = getAssociatedTokenAddressSync(
		mint,
		buyerPubkey,
		false,
		tokenProgram,
		ASSOCIATED_TOKEN_PROGRAM_ID,
	);
	const receiverAta = getAssociatedTokenAddressSync(
		mint,
		payTo,
		false,
		tokenProgram,
		ASSOCIATED_TOKEN_PROGRAM_ID,
	);
	const decimals = await mintDecimals(conn, mint, { programId: tokenProgram });

	// Base payment needs ~60k CU; each donation adds a transfer (+ possibly an ATA
	// create), so budget headroom per tip. Unused CU isn't charged — this only
	// raises the ceiling so a tip can't blow the limit and fail the whole tx.
	const tipCount = Array.isArray(tips) ? tips.length : 0;
	const ixs = [
		ComputeBudgetProgram.setComputeUnitLimit({ units: 60_000 + tipCount * 40_000 }),
		ComputeBudgetProgram.setComputeUnitPrice({ microLamports: 1 }),
	];
	if (!(await ataExists(conn, receiverAta))) {
		ixs.push(
			createAssociatedTokenAccountIdempotentInstruction(
				feePayer,
				receiverAta,
				payTo,
				mint,
				tokenProgram,
				ASSOCIATED_TOKEN_PROGRAM_ID,
			),
		);
	}
	ixs.push(
		createTransferCheckedInstruction(
			senderAta,
			mint,
			receiverAta,
			buyerPubkey,
			amount,
			decimals,
			[],
			tokenProgram,
		),
	);

	// Buyer-approved donations (charity + round-up). Each becomes an extra
	// transferChecked of the same mint to the cause's ATA, signed by the buyer in
	// the same transaction. Validate the destination, bound the amount, and dedupe
	// against the merchant's own payout so a tip can never silently inflate it.
	if (Array.isArray(tips) && tips.length) {
		for (const tip of tips) {
			const v = validateTip(tip, { payTo, paymentAmount: amount });
			if (v.skip) continue; // zero/negative amount, nothing to send
			if (!v.ok) return error(res, 400, v.code, v.message);
			const tipAta = getAssociatedTokenAddressSync(mint, v.to, false, tokenProgram, ASSOCIATED_TOKEN_PROGRAM_ID);
			if (!(await ataExists(conn, tipAta))) {
				ixs.push(
					createAssociatedTokenAccountIdempotentInstruction(feePayer, tipAta, v.to, mint, tokenProgram, ASSOCIATED_TOKEN_PROGRAM_ID),
				);
			}
			ixs.push(
				createTransferCheckedInstruction(senderAta, mint, tipAta, buyerPubkey, v.amount, decimals, [], tokenProgram),
			);
		}
	}

	const blockhash = await getRecentBlockhash(conn, rpc);
	const message = new TransactionMessage({
		payerKey: feePayer,
		recentBlockhash: blockhash,
		instructions: ixs,
	}).compileToV0Message();
	const vtx = new VersionedTransaction(message);

	const txBase64 = Buffer.from(vtx.serialize()).toString('base64');
	return json(res, 200, {
		network: accept.network,
		tx_base64: txBase64,
		recent_blockhash: blockhash,
		// Lets the checkout tell the buyer they are covering the network fee on
		// this one, rather than silently handing them a transaction that debits
		// their SOL when every previous payment did not.
		self_pay: selfPay,
		fee_payer: feePayer.toBase58(),
	});
}

async function handleEncode(req, res) {
	// Per-IP rate limit — same anonymous, cross-origin surface as prepare.
	const rl = await limits.x402PayIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl, 'too many encode requests');

	const body = parse(encodeSchema, await readJson(req));
	const { accept, signed_tx_base64, resource_url, builder_code } = body;

	// Defense-in-depth: verify the signed transaction actually pays the declared
	// amount to the declared recipient before wrapping it into the X-PAYMENT
	// header. The downstream facilitator /verify also checks, but a bad tx caught
	// here gives the user a clear error before the payment even hits the wire.
	if (accept.asset && accept.payTo && accept.amount) {
		const check = confirmSolanaPayment({
			paymentPayload: { payload: { transaction: signed_tx_base64 } },
			requirement: { asset: accept.asset, payTo: accept.payTo, amount: accept.amount },
		});
		if (check.confirmed === false) {
			return error(res, 400, 'invalid_payment', check.reason || 'transaction does not meet payment requirements');
		}
		// confirmSolanaPayment is deliberately conservative: anything it cannot
		// decode comes back `inconclusive` so a parsing quirk never rejects a real
		// payment. One inconclusive reason is not a quirk though: a blob that does
		// not deserialize into a transaction at all can never settle anywhere, and
		// wrapping it into an X-PAYMENT header only moves the failure to the
		// facilitator, where the buyer sees an opaque error after "Sending…"
		// instead of a clear one at the step that produced the bad signature.
		if (check.reason === 'undeserializable_transaction') {
			return error(res, 400, 'invalid_payment', 'signed_tx_base64 is not a decodable Solana transaction');
		}
	}

	const payload = {
		x402Version: 2,
		scheme: 'exact',
		network: accept.network,
		resource: { url: resource_url, mimeType: 'application/json' },
		accepted: accept,
		payload: { transaction: signed_tx_base64 },
	};
	if (builder_code) {
		payload.extensions = { 'builder-code': builder_code };
	}
	const xPayment = Buffer.from(JSON.stringify(payload), 'utf8').toString('base64');
	return json(res, 200, { x_payment: xPayment });
}