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
// api/_lib/x402/pay.js
//
// Shared Solana x402 payment client for the autonomous spend loop and every
// run()-style registry entry. The autonomous loop (api/cron/x402-autonomous-loop.js)
// pays declarative registry entries inline; richer entries that monitor a queue,
// poll a worker, or fan a call across rows declare a run(ctx) function and use
// payX402() here to settle their own USDC payments with the same primitives.
//
// Real on-chain payments only. No mocks. If the seed keypair is not configured,
// loadSeedKeypair() throws and callers degrade gracefully.
import { readFileSync } from 'node:fs';
import { randomInt } from 'node:crypto';
import bs58 from 'bs58';
import {
Connection, PublicKey, Keypair, TransactionMessage, VersionedTransaction,
ComputeBudgetProgram,
} from '@solana/web3.js';
import {
getAssociatedTokenAddressSync, createTransferCheckedInstruction,
createAssociatedTokenAccountIdempotentInstruction,
TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID,
} from '@solana/spl-token';
import { env } from '../env.js';
import { solanaConnection } from '../solana/connection.js';
import { mintDecimals, getRecentBlockhash } from '../solana/read-guards.js';
import { assessFeeAdmission } from './wallet-fee-meter.js';
export const USDC_MINT = env.X402_ASSET_MINT_SOLANA;
export const SOLANA_RPC = env.SOLANA_RPC_URL;
export const FETCH_TIMEOUT_MS = 20_000;
// ── Loud price-vs-cap skip ──────────────────────────────────────────────────────
// A silent skip when an endpoint's advertised price exceeds the caller's remaining
// per-run cap is exactly the bug the ring economy was built to kill: the flagship
// ring-settle ($1.00) was dropped every cycle because the volume loop's per-run
// cap ($0.05) was below it, and nobody saw it. Now the skip is LOUD — it names the
// endpoint, the price, the cap, and the envs to raise — throttled to once per hour
// per (url,cap) signature so a per-minute driver can't flood the logs.
const _capWarnAt = new Map();
const CAP_WARN_TTL_MS = 60 * 60 * 1000;
export function warnCapExceeded(url, priceAtomic, capAtomic) {
const now = Date.now();
const sig = `${url}|${capAtomic}`;
const last = _capWarnAt.get(sig) || 0;
if (now - last < CAP_WARN_TTL_MS) return;
_capWarnAt.set(sig, now);
if (_capWarnAt.size > 512) {
for (const [k, t] of _capWarnAt) if (now - t >= CAP_WARN_TTL_MS) _capWarnAt.delete(k);
}
console.warn(
`[x402-pay] price_exceeds_cap — ${url} advertises ${(priceAtomic / 1e6).toFixed(6)} USDC ` +
`but the remaining per-run cap is ${(capAtomic / 1e6).toFixed(6)} USDC, so the call was SKIPPED ` +
`(never settled). Raise the applicable cap to fit: X402_RING_TICK_CAP_ATOMIC (per-minute ring tick), ` +
`X402_VOLUME_PER_RUN_CAP_ATOMIC (5-min volume loop), X402_RING_DAILY_CAP_ATOMIC / ` +
`X402_AUTONOMOUS_DAILY_CAP_ATOMIC (daily), or lower X402_PRICE_RING_SETTLE.`,
);
}
/**
* Does a payment of `amountAtomic` exceed the payer's known USDC float? A null
* or unreadable float is unknown, never a shortfall.
*/
export function isFloatShortfall(amountAtomic, payerUsdcAtomic) {
if (payerUsdcAtomic === null || payerUsdcAtomic === undefined) return false;
const held = Number(payerUsdcAtomic);
return Number.isFinite(held) && Number(amountAtomic) > held;
}
/**
* The error token a skipped payment should be recorded under. A caller that
* folds the payer's float into `remainingCap` without passing it on gets
* `cap_would_exceed` back for what is really an empty wallet; this restores the
* funding signal so the ring dashboard and settle sensor stop filing it as a
* benign budget skip.
*/
export function skipReasonFor(outcome, payerUsdcAtomic) {
const reason = outcome?.errorMsg ?? null;
if (reason === 'cap_would_exceed' && isFloatShortfall(outcome?.amountAtomic, payerUsdcAtomic)) {
return 'insufficient_payer_usdc';
}
return reason;
}
// ── Fee floor ─────────────────────────────────────────────────────────────────
// The ring's operating rule is "lowest fees always": 1-signature self-pay
// settlement (5,000 lamports base) with the priority fee pinned at the floor.
// These constants are the single source of truth for the ring's priority-fee
// config — buildPaymentTx uses them, and the ceiling guard below reasons about
// the same numbers, so the builder and the guard can never drift apart.
export const SIGNATURE_FEE_LAMPORTS = 5000;
export const RING_CU_LIMIT = 60_000;
// Priority fee for a ring payment at batch position `nonce`. Baseline 5
// µlamports; the nonce perturbation (see buildPaymentTx) tops out at 1001
// µlamports ≈ 60 lamports over 60k CU — negligible against the 5,000 base.
export function ringPriorityMicrolamports(nonce = 0) {
return 5 + (Number(nonce) % 997);
}
// Compute-unit-limit jitter slots. Varying the CU LIMIT changes the compiled
// message bytes — and therefore the signature — while costing nothing: the
// priority fee is price × limit / 1e6, so at the baseline 5 µlamports even the
// top of this range is 0.32 lamports, which floors to zero. Unused compute
// units are not billed, so a slightly-high limit is free. This is what buys
// three orders of magnitude more distinct signatures than perturbing the price
// alone (which costs a lamport per step once it crosses 1e6/cuLimit).
export const RING_CU_JITTER_SLOTS = 4096;
// Map a nonce to the (priority price, compute limit) pair that makes this
// payment's transaction byte-unique.
//
// Signature collisions are the mechanism behind the duplicate-settle defect
// measured on mainnet 2026-07-28: Ed25519 signatures are deterministic, so two
// ring payments with the same payer/payTo/mint/amount, built against one shared
// tick blockhash with the same fee config, compile to THE SAME transaction and
// therefore the same signature. Only one can land; the rest were being credited
// off it (12,674 of 59,271 settles, 21.4%).
//
// Self-pay has 5,000 lamports of headroom under the ceiling, so the full 997
// price slots are available: 997 × 4096 ≈ 4.08M distinct fee configs.
// Sponsor mode sits EXACTLY at the 10,000-lamport ceiling at baseline, so it may
// only use price slots whose priority still floors to zero lamports — with the
// jitter range topping out at 64,095 CU that means price ≤ 15, i.e. 11 slots
// (5..15) — still 11 × 4096 ≈ 45k configs, all at zero extra fee.
export function ringFeeConfig(nonce = 0, { selfPay = true } = {}) {
const n = Math.abs(Number(nonce) || 0);
const priceSlots = selfPay ? 997 : 11;
const microLamports = 5 + (n % priceSlots);
const cuLimit = RING_CU_LIMIT + (Math.floor(n / priceSlots) % RING_CU_JITTER_SLOTS);
return { microLamports, cuLimit };
}
// Default nonce for payX402 callers that do not manage batch positions.
//
// This was a per-PROCESS sequential counter, which is precisely why the fix was
// needed: every Cloud Run instance started it at the same value and walked the
// same short cycle, so two instances paying the same endpoint the same amount in
// one blockhash window produced identical transactions. Drawing from a large
// space with a CSPRNG removes the cross-instance correlation entirely — there is
// no shared state to synchronise. Collisions are now a birthday problem over
// millions of slots rather than a certainty, and the facilitator's credit gate
// (settle-credit.js) makes any residual collision a clean refusal instead of a
// double credit.
export const RING_NONCE_SPACE = 997 * RING_CU_JITTER_SLOTS;
export function nextAutoNonce() {
return randomInt(0, RING_NONCE_SPACE);
}
// Self-pay is the OPERATIVE DEFAULT for ring-internal payments: the buyer pays
// its own fee → 1 signature = 5,000 lamports, half the 2-signature sponsored
// base, and the facilitator broadcasts without co-signing. An explicit
// X402_RING_SELF_PAY=false is still honored (sponsor mode stays available for
// gasless buyers); anything else — unset included — means self-pay.
export function ringSelfPayDefault() {
return String(process.env.X402_RING_SELF_PAY ?? '').trim().toLowerCase() !== 'false';
}
// Hard per-transaction fee ceiling for ring payments (lamports). The default
// 10,000 admits the worst legitimate case (2-signature sponsor mode at the
// baseline priority fee) and nothing more; the self-pay path runs at ~5,000.
export function ringMaxFeePerTxLamports() {
return Number(process.env.X402_RING_MAX_FEE_PER_TX_LAMPORTS || 10_000);
}
// Worst-case lamports a payment with this fee config can cost on-chain. Pure —
// the fee-floor regression tests assert the ring's builders stay under the
// ceiling for every possible nonce, and payX402 applies the same math at
// runtime. Priority lamports use integer floor division, mirroring the
// facilitator's guard math (self-facilitator.js) and the runtime's sub-lamport
// truncation.
export function expectedFeeLamports({ selfPay, priorityMicrolamports = 0, cuLimit = RING_CU_LIMIT }) {
const signatures = selfPay ? 1 : 2;
const priorityLamports = Math.floor(
(Number(priorityMicrolamports) * Number(cuLimit)) / 1_000_000,
);
return SIGNATURE_FEE_LAMPORTS * signatures + priorityLamports;
}
// Caller-side fee admission for a hand-built SPONSOR-mode payment, for the
// pipelines that build their own transaction instead of calling payX402() (an
// audit that must replay one exact proof, a builder-code echo, an MCP canary).
// The ring payer and the autonomous loop already ask the governor before signing;
// these did not, so each call past a spent budget paid for an ATA read, a
// signature and a simulated verify and was then refused at settle. Priced at the
// same worst case as payX402's own admission for this nonce, and fails open the
// same way (see assessFeeAdmission).
export async function admitSponsorSettle({ accept, connection = null, nonce = 0 }) {
const { microLamports, cuLimit } = ringFeeConfig(nonce, { selfPay: false });
return assessFeeAdmission({
feeWalletB58: accept?.extra?.feePayer || null,
estFeeLamports: expectedFeeLamports({
selfPay: false, priorityMicrolamports: microLamports, cuLimit,
}),
connection,
});
}
// Load the autonomous payer keypair. Seed wallet preferred; agent wallet is the
// documented fallback. In non-prod a local test wallet file is honored so the
// loop and manual tests can run without env wiring.
// Decode a 64-byte Solana secret key from any of the encodings that end up in
// env vars in practice: base58 (the canonical form), a JSON array of 64 ints
// (Solana CLI keypair file pasted verbatim), or base64. Tolerates the paste
// artifacts that broke production — surrounding quotes, whitespace, and
// newlines — instead of letting bs58 throw "Non-base58 character" and silently
// pausing every x402 engine on the ring. Returns null when nothing decodes.
export function decodeSeedSecret(secret) {
const raw = String(secret ?? '').trim().replace(/^["']|["']$/g, '').trim();
if (!raw) return null;
if (raw.startsWith('[')) {
try {
const arr = JSON.parse(raw);
if (Array.isArray(arr) && arr.length === 64) return Uint8Array.from(arr);
} catch { /* fall through */ }
return null;
}
// Strip embedded whitespace/newlines (multi-line paste) before decoding.
const compact = raw.replace(/\s+/g, '');
try {
const bytes = bs58.decode(compact);
if (bytes.length === 64) return bytes;
} catch { /* try base64 next */ }
try {
const buf = Buffer.from(compact, 'base64');
// Buffer.from is lenient — require a clean round-trip so a mistyped
// base58 string can't half-decode into 64 garbage bytes.
if (buf.length === 64 && buf.toString('base64').replace(/=+$/, '') === compact.replace(/=+$/, '')) {
return Uint8Array.from(buf);
}
} catch { /* undecodable */ }
return null;
}
export function loadSeedKeypair() {
const secret = process.env.X402_SEED_SOLANA_SECRET_BASE58
|| process.env.X402_AGENT_SOLANA_SECRET_BASE58;
if (secret) {
const bytes = decodeSeedSecret(secret);
if (!bytes) {
throw new Error('x402 pay: seed keypair undecodable — X402_SEED_SOLANA_SECRET_BASE58 must be 64 bytes as base58, base64, or a JSON array of 64 ints');
}
return Keypair.fromSecretKey(bytes);
}
if (process.env.NODE_ENV !== 'production') {
try {
const arr = JSON.parse(readFileSync('/home/codespace/.config/x402-test-wallets/solana.json', 'utf8'));
return Keypair.fromSecretKey(Uint8Array.from(arr));
} catch { /* fall through */ }
}
throw new Error('x402 pay: seed keypair not configured (set X402_SEED_SOLANA_SECRET_BASE58)');
}
export async function fetchWithTimeout(url, opts = {}, timeoutMs = FETCH_TIMEOUT_MS) {
const ctrl = new AbortController();
const t = setTimeout(() => ctrl.abort(), timeoutMs);
try {
const res = await fetch(url, { ...opts, signal: ctrl.signal, redirect: 'manual' });
let body = null;
try { body = await res.json(); } catch { try { body = await res.text(); } catch { body = null; } }
return { ok: res.ok, status: res.status, headers: res.headers, body };
} finally {
clearTimeout(t);
}
}
export function parseSolanaAccept(challenge) {
if (!challenge || !Array.isArray(challenge.accepts)) return null;
return challenge.accepts.find(
(a) => typeof a?.network === 'string' && a.network.startsWith('solana'),
) || null;
}
export function buildPaymentTx({ accept, buyer, blockhash, mintInfo, receiverAtaExists, nonce = 0, selfPay = false }) {
const mint = new PublicKey(accept.asset);
const payTo = new PublicKey(accept.payTo);
// Self-pay: the buyer IS the fee payer → the transaction needs only ONE
// signature (5000 lamports base) instead of two (buyer + sponsor = 10000), and
// the facilitator broadcasts it without co-signing. Sponsor mode keeps the
// advertised fee payer so a buyer without SOL can still be sponsored.
const feePayer = selfPay ? buyer.publicKey : new PublicKey(accept.extra.feePayer);
const amount = BigInt(accept.amount);
const senderAta = getAssociatedTokenAddressSync(
mint, buyer.publicKey, false, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID,
);
const receiverAta = getAssociatedTokenAddressSync(
mint, payTo, false, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID,
);
// `nonce` selects the (priority price, compute limit) pair that makes this
// transaction byte-unique, so a batch pipeline firing several identical-amount
// payments (same payer/payTo/mint) against one shared blockhash produces a
// DISTINCT signature per call. Two byte-identical transfers compile to the same
// message → same signature → only one can ever land, and the others used to be
// credited off it. See ringFeeConfig for the sizing of the two dimensions.
const { microLamports, cuLimit } = ringFeeConfig(nonce, { selfPay });
const ixs = [
ComputeBudgetProgram.setComputeUnitLimit({ units: cuLimit }),
ComputeBudgetProgram.setComputeUnitPrice({ microLamports }),
];
if (!receiverAtaExists) {
ixs.push(createAssociatedTokenAccountIdempotentInstruction(
feePayer, receiverAta, payTo, mint, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID,
));
}
ixs.push(createTransferCheckedInstruction(
senderAta, mint, receiverAta, buyer.publicKey,
amount, mintInfo.decimals, [], TOKEN_PROGRAM_ID,
));
const msg = new TransactionMessage({
payerKey: feePayer,
recentBlockhash: blockhash,
instructions: ixs,
}).compileToV0Message();
const vtx = new VersionedTransaction(msg);
vtx.sign([buyer]);
return Buffer.from(vtx.serialize()).toString('base64');
}
// A signed transaction carrying a blockhash older than ~60-90s (151 blocks) is
// rejected at broadcast with BlockhashNotFound. The tick-wide shared blockhash
// below ages exactly like that across a long cron tick, and the facilitator
// cannot re-sign on our behalf (the buyer signature covers the message,
// blockhash included), so freshness is the payer's job. This cache keeps the
// one-fetch-per-tick economy for fast ticks and transparently re-fetches once
// the hash is old enough to be a broadcast risk.
const BLOCKHASH_TTL_MS = 20_000;
let blockhashCache = { value: null, fetchedAt: 0 };
function seedBlockhash(value) {
if (value) blockhashCache = { value, fetchedAt: Date.now() };
}
// Resolve the blockhash to sign with: the cached one while younger than the
// TTL, else a fresh fetch. Falls back to the caller-supplied tick blockhash
// when the RPC fetch fails (a stale attempt beats no attempt: the facilitator
// side still retries preflight-off for provably-unlanded blockhash misses).
// Exported for every caller that signs later in a tick than the tick's own
// blockhash read: the autonomous loop's inline payments and the pipelines it
// runs, which can start two or three minutes into a tick.
export async function currentBlockhash(conn, fallback, { forceFresh = false } = {}) {
const age = Date.now() - blockhashCache.fetchedAt;
if (!forceFresh && blockhashCache.value && age < BLOCKHASH_TTL_MS) return blockhashCache.value;
try {
// The shared guard serves its own cached blockhash (per process and via the
// shared cache) inside the validity window when every RPC lane is down, so
// this only reaches the fallback when nothing usable exists anywhere.
// forceFresh has to travel INTO the guard as well: it keeps its own reuse
// window, so skipping only this module's cache would still hand the retry
// the very hash the facilitator just refused.
const blockhash = await getRecentBlockhash(conn, SOLANA_RPC, { forceFresh });
seedBlockhash(blockhash);
return blockhash;
} catch {
return blockhashCache.value || fallback;
}
}
// Build the per-tick shared Solana state once (blockhash + USDC mint info) so a
// run() that pays several rows reuses one blockhash. Standalone callers (manual
// tests) call this to bootstrap a full context without the cron loop.
export async function bootstrapSolanaContext({ buyer } = {}) {
if (!USDC_MINT) throw new Error('x402 pay: X402_ASSET_MINT_SOLANA not configured');
const payer = buyer || loadSeedKeypair();
const conn = solanaConnection({ url: SOLANA_RPC, commitment: 'confirmed' });
// USDC decimals resolve locally (no network read) and the blockhash goes
// through the shared cached guard, so a dead RPC only fails the bootstrap when
// no blockhash inside its validity window exists anywhere in the fleet. That
// failure is a typed 503 rpc_unavailable rather than a raw fetch error.
const [blockhash, decimals] = await Promise.all([
getRecentBlockhash(conn, SOLANA_RPC),
mintDecimals(conn, new PublicKey(USDC_MINT)),
]);
seedBlockhash(blockhash);
return { buyer: payer, conn, blockhash, mintInfo: { decimals } };
}
// Settle a single x402 payment against `url`. Probes for the 402 challenge,
// builds + signs the Solana USDC transfer, and replays with the X-PAYMENT header.
//
// Returns a structured outcome — never throws for protocol/network faults:
// { success, paid, free, skipped, amountAtomic, txSig, status, responseBody, errorMsg }
//
// paid — a USDC payment settled on-chain (success true)
// free — endpoint answered 200 with no 402 (no payment needed)
// skipped — a guard rejected the call before paying (cap, asset mismatch, …)
export async function payX402({
url, method = 'POST', body = null,
buyer, conn, blockhash, mintInfo,
remainingCap = Infinity,
// The buyer's USDC float in atomics, when the caller has read it. Callers
// that bound `remainingCap` by the float pass it too, so an empty payer is
// reported as `insufficient_payer_usdc` (a funding problem) rather than
// `cap_would_exceed` with advice to raise cap env vars that are not the limit.
payerUsdcAtomic = null,
userAgent = 'threews-x402-autonomous/1.0',
// Batch pipelines pass their own position; everyone else gets a distinct
// per-process nonce below so same-amount payments sharing a tick blockhash
// never compile to the same signature (see nextAutoNonce).
nonce = null,
// Self-pay: buyer is its own fee payer → 1 signature (5000 lamports) instead
// of 2. Half the base fee, no sponsor co-sign. The ring's operative default;
// only an explicit X402_RING_SELF_PAY=false selects sponsor mode. See
// ringSelfPayDefault() and buildPaymentTx.
selfPay = ringSelfPayDefault(),
// Optional pre-broadcast recipient gate. Called with the resolved Solana
// `accept` (payTo, asset, amount, …) AFTER the 402 challenge is parsed and
// BEFORE the payment tx is built/signed. Return `{ abort: true, reason }` to
// refuse the payment without moving money — the ring agent buyers use this to
// enforce that every counterparty is inside ringAllowedAddresses(). Returning
// null/undefined continues the normal flow. Sync or async; a thrown hook is
// treated as an abort (fail-closed), never a crash.
onAccept = null,
// Budget for the PAID replay only. The probe stays on FETCH_TIMEOUT_MS: it is
// a cheap 402 read. A route that runs its work before settling (the paid Forge
// generates the mesh, then settles) can legitimately outlast 20s, and aborting
// there does not cancel the server: it still settles, so the buyer pays for a
// result it already threw away and books the settlement as a fault.
paidTimeoutMs = FETCH_TIMEOUT_MS,
}) {
// ringFeeConfig applies the sponsor-mode price constraint itself (sponsor sits
// exactly at the fee ceiling, so only zero-lamport priority slots are legal),
// which leaves the full compute-limit jitter available in both modes.
if (nonce == null) nonce = nextAutoNonce();
const reqInit = {
method,
headers: { 'content-type': 'application/json', 'user-agent': userAgent },
...(body != null ? { body: JSON.stringify(body) } : {}),
};
// Step 1 — probe for the 402 challenge.
const probe = await fetchWithTimeout(url, reqInit);
if (probe.status !== 402) {
return {
success: probe.ok, paid: false, free: true, skipped: false,
amountAtomic: 0, txSig: null, status: probe.status,
responseBody: probe.body,
errorMsg: probe.ok ? null : `http_${probe.status}`,
};
}
let accept = parseSolanaAccept(probe.body);
if (!accept) {
return { success: false, paid: false, free: false, skipped: true, amountAtomic: 0, txSig: null, status: 402, responseBody: probe.body, errorMsg: 'no_solana_accept' };
}
// One attempt = validate THIS accept, build + sign a transaction for it, and
// replay the request carrying the payment. Returns either a terminal `skip`
// (a guard refused before money could move) or the paid response.
// `forceFreshBlockhash` is set on the post-402 retry: the refused attempt may
// have died on a stale hash, and re-signing the retry against the same one
// would reproduce the failure.
async function attemptSettle(currentAccept, attemptNonce, { forceFreshBlockhash = false } = {}) {
if (!USDC_MINT || currentAccept.asset !== USDC_MINT) {
return { skip: { success: false, paid: false, free: false, skipped: true, amountAtomic: 0, txSig: null, status: 402, responseBody: probe.body, errorMsg: `unexpected_asset:${currentAccept.asset}` } };
}
if (!selfPay && !currentAccept.extra?.feePayer) {
return { skip: { success: false, paid: false, free: false, skipped: true, amountAtomic: 0, txSig: null, status: 402, responseBody: probe.body, errorMsg: 'missing_fee_payer' } };
}
// Pre-broadcast recipient gate. A thrown hook is a fail-closed refusal, never
// a crash. The whole point is to stop money moving to an unexpected payTo.
// Re-run per attempt: a re-fetched challenge may name a different payTo, and
// the ring's allowlist must judge the accept we are actually paying.
if (typeof onAccept === 'function') {
let hook;
try {
hook = await onAccept(currentAccept);
} catch (err) {
hook = { abort: true, reason: `onaccept_error:${String(err?.message || err).slice(0, 80)}` };
}
if (hook?.abort) {
return { skip: {
success: false, paid: false, free: false, skipped: true, refusedByHook: true,
amountAtomic: Number(currentAccept.amount || 0), txSig: null, status: 402,
responseBody: probe.body, errorMsg: hook.reason || 'onaccept_abort',
} };
}
}
const attemptAmount = Number(currentAccept.amount || 0);
if (isFloatShortfall(attemptAmount, payerUsdcAtomic)) {
return { skip: { success: false, paid: false, free: false, skipped: true, amountAtomic: attemptAmount, txSig: null, status: 402, responseBody: probe.body, errorMsg: 'insufficient_payer_usdc' } };
}
if (attemptAmount > remainingCap) {
warnCapExceeded(url, attemptAmount, Number.isFinite(remainingCap) ? remainingCap : 0);
return { skip: { success: false, paid: false, free: false, skipped: true, amountAtomic: attemptAmount, txSig: null, status: 402, responseBody: probe.body, errorMsg: 'cap_would_exceed' } };
}
// Fee ceiling: refuse to send a payment whose fee config could exceed
// X402_RING_MAX_FEE_PER_TX_LAMPORTS. A structured skip, not a throw: the
// caller records it like any other guard rejection. This is the runtime
// twin of the fee-floor regression tests over expectedFeeLamports().
const feeConfig = ringFeeConfig(attemptNonce, { selfPay });
const worstCaseFeeLamports = expectedFeeLamports({
selfPay,
priorityMicrolamports: feeConfig.microLamports,
cuLimit: feeConfig.cuLimit,
});
const maxFeeLamports = ringMaxFeePerTxLamports();
if (worstCaseFeeLamports > maxFeeLamports) {
return { skip: {
success: false, paid: false, free: false, skipped: true,
amountAtomic: attemptAmount, txSig: null, status: 402, responseBody: probe.body,
errorMsg: `fee_ceiling_exceeded:${worstCaseFeeLamports}>${maxFeeLamports}`,
} };
}
// Fee-budget admission: the caller-side twin of the settle path's wallet fee
// governor. Everything past this point (an ATA read, a signature, a facilitator
// verify that simulates against an RPC node) is wasted when the fee wallet's
// daily budget is already spent, because settleRingPayment() refuses at the end
// regardless. Checking here collapses a full handshake into one skipped call.
// Fails open: assessFeeAdmission() admits whenever it cannot price the call,
// so this can only ever remove doomed work, never block a fundable payment.
const feeWalletB58 = selfPay ? buyer?.publicKey?.toBase58() : currentAccept.extra?.feePayer;
if (feeWalletB58) {
const admission = await assessFeeAdmission({
feeWalletB58,
estFeeLamports: worstCaseFeeLamports,
connection: conn,
});
if (!admission.ok) {
return { skip: {
success: false, paid: false, free: false, skipped: true,
amountAtomic: attemptAmount, txSig: null, status: 402, responseBody: probe.body,
errorMsg: admission.reason || 'fee_runway_exhausted',
} };
}
}
// Step 2: does the receiver ATA already exist? (saves an idempotent create ix)
const receiverAta = getAssociatedTokenAddressSync(
new PublicKey(currentAccept.asset), new PublicKey(currentAccept.payTo),
false, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID,
);
const receiverAtaInfo = await conn.getAccountInfo(receiverAta).catch(() => null);
// Step 3: build the signed transaction + X-PAYMENT envelope. The signing
// blockhash reads through the freshness cache: the tick-wide hash while it
// is young, a re-fetched one once it has aged past broadcast safety.
const signBlockhash = await currentBlockhash(conn, blockhash, { forceFresh: forceFreshBlockhash });
const txBase64 = buildPaymentTx({
accept: currentAccept, buyer, blockhash: signBlockhash, mintInfo,
receiverAtaExists: receiverAtaInfo !== null,
nonce: attemptNonce, selfPay,
});
const xPayment = Buffer.from(JSON.stringify({
x402Version: 2,
scheme: 'exact',
network: currentAccept.network,
resource: { url, mimeType: 'application/json' },
payload: { transaction: txBase64 },
accepted: currentAccept,
})).toString('base64');
// Step 4: replay the request carrying the payment.
const paidRes = await fetchWithTimeout(url, {
...reqInit,
headers: { ...reqInit.headers, 'x-payment': xPayment },
}, paidTimeoutMs);
return { paidRes, amountAtomic: attemptAmount };
}
// A 402 on the PAID replay means the endpoint refused the payment we just
// built: the quote moved between probe and replay, the requirements were
// re-issued, or the proof did not match what the route now advertises. The
// signed transfer is never broadcast in that case (the facilitator settles only
// after verify passes), so no money moved and exactly one retry against a
// FRESHLY fetched challenge is safe. Bounded at one: a route that 402s twice
// is reported as before. Every other status (200, 4xx, 5xx) is returned on the
// first attempt, so nothing changes for a call that already works.
let currentAccept = accept;
let attemptNonce = nonce;
let retriedAfter402 = false;
let paidRes;
let amountAtomic = 0;
for (;;) {
const outcome = await attemptSettle(currentAccept, attemptNonce, { forceFreshBlockhash: retriedAfter402 });
if (outcome.skip) return { ...outcome.skip, retriedAfter402 };
paidRes = outcome.paidRes;
amountAtomic = outcome.amountAtomic;
if (paidRes.status !== 402 || retriedAfter402) break;
const reprobe = await fetchWithTimeout(url, reqInit).catch(() => null);
const fresh = reprobe?.status === 402 ? parseSolanaAccept(reprobe.body) : null;
if (!fresh) break;
retriedAfter402 = true;
currentAccept = fresh;
// A fresh nonce keeps the retry transaction byte-distinct from the refused
// one, so a re-quote at the SAME amount cannot compile to the same signature.
attemptNonce = nextAutoNonce();
}
let txSig = null;
if (paidRes.ok) {
const responseHeader = paidRes.headers?.get?.('x-payment-response');
if (responseHeader) {
try {
const settled = JSON.parse(Buffer.from(responseHeader, 'base64').toString('utf8'));
txSig = settled?.transaction || null;
} catch { /* non-fatal */ }
}
}
return {
success: paidRes.ok, paid: paidRes.ok, free: false, skipped: false,
amountAtomic, txSig, status: paidRes.status,
responseBody: paidRes.body,
errorMsg: paidRes.ok ? null : `http_${paidRes.status}`,
retriedAfter402,
};
}