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.

60.0 KB
Raw Blame
// api/_lib/x402/self-facilitator.js
//
// three.ws SELF-HOSTED x402 facilitator — Solana verify + settle, fully in-house.
//
// Why this exists: the default settle path delegates to an EXTERNAL facilitator
// (PayAI) that co-signs the fee-payer and broadcasts. For the closed-loop
// agent-to-agent economy the platform runs against its OWN endpoints, we do not
// want any third party touching settlement or holding the sponsor key. This
// module IS the facilitator: it validates the buyer-signed Solana USDC transfer,
// co-signs it with OUR fee-payer key, broadcasts it over OUR RPC, and records the
// exact SOL fee burned. Point X402_FACILITATOR_URL_SOLANA at /api/x402-facilitator
// and no money, metadata, or signing authority ever leaves three.ws.
//
// SECURITY — the co-signing drain vector. The fee payer signs the WHOLE
// transaction, so a naive facilitator that blind-signs whatever /settle receives
// would let anyone drain the sponsor's SOL (submit a tx that SystemProgram-
// transfers the fee payer's lamports out, or sets an enormous priority fee).
// Defense: validateRingTransaction() refuses to co-sign anything whose program
// set is not EXACTLY {ComputeBudget, optional ATA-create for OUR recipient, one
// USDC TransferChecked to an allowlisted payTo}. No System instructions, capped
// compute-unit price, recipient must be a platform-controlled wallet. That single
// gate enforces BOTH "only our wallets settle here" and "the sponsor can't be
// drained".

import bs58 from 'bs58';
import { ed25519 } from '@noble/curves/ed25519.js';
import { PublicKey, Keypair, VersionedTransaction } from '@solana/web3.js';
import {
	getAssociatedTokenAddressSync,
	TOKEN_PROGRAM_ID,
	TOKEN_2022_PROGRAM_ID,
	ASSOCIATED_TOKEN_PROGRAM_ID,
} from '@solana/spl-token';

import { env } from '../env.js';
import { solanaConnection } from '../solana/connection.js';
import {
	isSupportedTokenProgram,
	knownTokenProgramForMint,
	tokenProgramForMint,
} from '../solana-token-program.js';
// Pure DB/crypto helpers: no cycle back into this module.
import {
	SETTLEMENT_PENDING_REASON,
	pendingSettlementKey,
	recordPendingOrTerminal,
} from './pending-settlements.js';

export { SETTLEMENT_PENDING_REASON };

const COMPUTE_BUDGET_PROGRAM_ID = new PublicKey(
	'ComputeBudget111111111111111111111111111111',
);
const SYSTEM_PROGRAM_ID = new PublicKey('11111111111111111111111111111111');
// SPL Memo, both live program ids. The reference x402 SVM client (@x402/svm,
// which our own buildSolanaExactPayload delegates to) attaches a memo to every
// `exact` payment it builds, so a facilitator that rejects memos cannot settle
// a payment built by the standard client at all. Memo writes to the transaction
// log and owns no accounts: it cannot move a lamport or a token, which is why it
// is skipped here the same way a ComputeBudget instruction is. Its compute cost
// still counts against the CU/fee ceiling enforced below.
const MEMO_PROGRAM_IDS = [
	new PublicKey('MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr'),
	new PublicKey('Memo1UhkJRfHyvLMcVucJwxXeuD728EqVDDwQDxFMNo'),
];

// Lighthouse, the on-chain assertion program. Phantom's transaction protection
// injects one or more Lighthouse instructions into a transaction before the
// user signs it: they assert the buyer's balances end up where the wallet's
// simulation said they would, and revert the transaction otherwise. They move
// nothing, and the reference x402 SVM facilitator (@x402/svm) accepts them for
// the same reason. Refusing them locked every Phantom buyer with protection on
// out of the rail, which is Phantom's default. One constraint is ours alone:
// Lighthouse also has a memory-write instruction that charges a payer account
// for a PDA, so in sponsor mode a Lighthouse instruction may never name the
// sponsor's fee-payer account. Enforced below, once the mode is known.
const LIGHTHOUSE_PROGRAM_ID = new PublicKey('L2TExMFKdjpN9kozasaurPirfHy9P8sbXoAN1qA3S95');
// Phantom injects one or two. The ceiling keeps a hostile client from padding
// a sponsored transaction with compute it does not pay for.
const MAX_LIGHTHOUSE_INSTRUCTIONS = 3;

// SPL Token instruction tag for TransferChecked. Plain Transfer (3) is rejected —
// TransferChecked commits the mint + decimals, so we can trust the decoded mint.
const SPL_TRANSFER_CHECKED = 12;
// ComputeBudget instruction tags.
const CB_SET_UNIT_LIMIT = 2;
const CB_SET_UNIT_PRICE = 3;

// Fee-drain guards. A malicious priority fee is paid by the SPONSOR, so cap it.
// The honest ring builder (pay.js) uses ≤1001 µlamports × 60k CU ≈ 60 lamports;
// these ceilings sit far above that but bound any adversarial submission.
const MAX_CU_LIMIT = Number(process.env.X402_SELF_FAC_MAX_CU_LIMIT || 300_000);
const MAX_CU_PRICE_MICROLAMPORTS = Number(
	process.env.X402_SELF_FAC_MAX_CU_PRICE || 100_000,
);
const MAX_PRIORITY_LAMPORTS = Number(
	process.env.X402_SELF_FAC_MAX_PRIORITY_LAMPORTS || 20_000,
);
// Rent an idempotent ATA-create locks on the sponsor for a NEW recipient token
// account (~0.00204 SOL). Reclaimable by closing the ATA. Bounded, one-time.
// A Token-2022 ATA carries the ImmutableOwner extension, so it is 170 bytes
// rather than 165 and its rent-exempt minimum is higher. Under-estimating it
// lets a settle clear the fee-floor gate and then die on chain for rent.
// Both figures are ceilings, priced at the 6960 lamports/byte-year rate. Mainnet
// charged less than that when last read (2026-09-20: 1,488,440 and 1,513,840),
// and an over-estimate only makes the floor gate stricter, never unsafe.
const ATA_RENT_LAMPORTS = 2_039_280;
const ATA_RENT_LAMPORTS_TOKEN_2022 = 2_074_080;
const ataRentLamports = (tokenProgram) =>
	String(tokenProgram) === TOKEN_2022_PROGRAM_ID.toBase58()
		? ATA_RENT_LAMPORTS_TOKEN_2022
		: ATA_RENT_LAMPORTS;

export const SELF_FACILITATOR_ENABLED =
	String(process.env.X402_SELF_FACILITATOR_ENABLED || '').toLowerCase() === 'true';

// Sponsor SOL floor — the hard stop that keeps the loop from draining our SOL.
// Below this the facilitator refuses to settle (returns success:false), which
// pauses the paying loop until the sponsor is topped up. Default 0.02 SOL.
export const SPONSOR_SOL_FLOOR_LAMPORTS = Number(
	process.env.X402_SPONSOR_SOL_FLOOR_LAMPORTS || 20_000_000,
);

// Minimum atomic amount (USDC, 6-decimals) a SPONSOR-mode settle must move. Each
// sponsor co-sign burns ~5000 lamports (≈0.001 USDC) of our SOL, so settling a
// 1-atomic dust transfer is a pure fee-burn grief: the attacker donates a
// sub-fee amount while we pay to broadcast it. Requiring the settle to at least
// cover its own base fee means a settle can never be net-negative for the
// platform. Default 1000 atomic = $0.001; raise via env if micro-tips aren't a
// concern. Self-pay settles pay their own fee, so this floor does not apply.
export const MIN_SPONSOR_SETTLE_ATOMIC = Math.max(
	0,
	Number(process.env.X402_SELF_FAC_MIN_SETTLE_ATOMIC || 1000),
);

let _feePayerCache = null;
// Load the sponsor (fee-payer) keypair the facilitator co-signs with. Its public
// key MUST equal env.X402_FEE_PAYER_SOLANA (the address the 402 challenge
// advertises) or endpoints would advertise a fee payer we cannot actually sign.
export function loadFeePayerKeypair() {
	if (_feePayerCache) return _feePayerCache;
	const b58 = process.env.X402_FEE_PAYER_SECRET_BASE58;
	if (!b58) {
		throw new Error(
			'self-facilitator: X402_FEE_PAYER_SECRET_BASE58 not set (the sponsor key that co-signs + pays SOL)',
		);
	}
	const raw = bs58.decode(b58);
	if (raw.length !== 64) {
		throw new Error(`self-facilitator: fee-payer key expected 64 bytes, got ${raw.length}`);
	}
	const kp = Keypair.fromSecretKey(raw);
	const advertised = env.X402_FEE_PAYER_SOLANA;
	if (advertised && kp.publicKey.toBase58() !== advertised) {
		throw new Error(
			`self-facilitator: fee-payer secret pubkey ${kp.publicKey.toBase58()} != advertised X402_FEE_PAYER_SOLANA ${advertised}`,
		);
	}
	_feePayerCache = kp;
	return kp;
}

// The set of recipient (payTo) addresses this facilitator will settle to. ONLY
// platform-controlled wallets belong here — that is what keeps every settled
// dollar inside three.ws. Defaults to X402_PAY_TO_SOLANA; add ring treasuries via
// X402_SELF_FACILITATOR_PAYTO_ALLOWLIST (comma-separated).
export function payToAllowlist() {
	const out = new Set();
	if (env.X402_PAY_TO_SOLANA) out.add(env.X402_PAY_TO_SOLANA);
	const extra = String(process.env.X402_SELF_FACILITATOR_PAYTO_ALLOWLIST || '')
		.split(',')
		.map((s) => s.trim())
		.filter(Boolean);
	for (const a of extra) out.add(a);
	return out;
}

function readU32LE(data, offset) {
	return (
		data[offset] |
		(data[offset + 1] << 8) |
		(data[offset + 2] << 16) |
		(data[offset + 3] << 24)
	) >>> 0;
}

function readU64LE(data, offset) {
	let v = 0n;
	for (let i = 7; i >= 0; i--) v = (v << 8n) | BigInt(data[offset + i]);
	return v;
}

// Decode + STRICTLY validate a buyer-signed ring payment transaction. Returns
// { ok:true, decoded } when it is a clean single-USDC-transfer to an allowlisted
// recipient with a bounded sponsor fee, or { ok:false, reason } otherwise. Never
// throws on adversarial input — a bad tx is a clean refusal, not a 5xx.
export function validateRingTransaction({ txBase64, requirement, feePayerPubkey, allowlist, tokenProgramId }) {
	let tx;
	try {
		tx = VersionedTransaction.deserialize(Buffer.from(txBase64, 'base64'));
	} catch (err) {
		return { ok: false, reason: `deserialize_failed:${err.message}` };
	}
	const msg = tx.message;

	// Address-table lookups would hide accounts we can't statically resolve.
	// The ring builder never uses them; reject to keep validation total.
	if (msg.addressTableLookups && msg.addressTableLookups.length > 0) {
		return { ok: false, reason: 'address_table_lookups_forbidden' };
	}

	const keys = msg.staticAccountKeys;
	if (!keys || keys.length === 0) return { ok: false, reason: 'no_account_keys' };

	// Every account index in a (possibly adversarial) compiled instruction must
	// resolve to a real static key. An out-of-range index would dereference
	// undefined and throw a TypeError, breaking the "never throws" contract this
	// facilitator's security model relies on — treat any bad index as a refusal.
	const idxInRange = (i) => Number.isInteger(i) && i >= 0 && i < keys.length;

	// Fee payer is always account index 0. Whether it must equal the configured
	// sponsor (sponsor mode) or may be the buyer itself (self-pay, 1 signature) is
	// decided AFTER we learn the transfer authority below.
	const feePayer = keys[0];

	const mint = new PublicKey(requirement.asset);
	const requiredAmount = BigInt(requirement.amount);
	const payTo = new PublicKey(requirement.payTo);

	if (!allowlist.has(payTo.toBase58())) {
		return { ok: false, reason: `pay_to_not_allowlisted:${payTo.toBase58()}` };
	}

	// The mint must be one the platform actually issues 402s for (USDC, plus
	// $THREE when configured). The requirement is caller-supplied: without
	// this pin a junk mint passes every check below — including the
	// sponsor-funded ATA create — so each call would burn sponsor ATA rent +
	// fees settling a worthless transfer, repeatable per fresh mint. Fail
	// closed when no settleable mint is configured at all.
	const settleableMints = [env.X402_ASSET_MINT_SOLANA, env.THREE_TOKEN_MINT].filter(Boolean);
	if (!settleableMints.includes(mint.toBase58())) {
		return { ok: false, reason: `mint_not_settleable:${mint.toBase58()}` };
	}

	// The program that owns the mint decides every ATA address below and is the
	// only token program this transaction may call. USDC is classic SPL Token and
	// $THREE is Token-2022. It is pinned from the mint, never read off the buyer's
	// instruction: a buyer who picks the program picks the ATA derivation too, and
	// could steer the sponsor into funding an account the mint's real program
	// will never credit.
	const tokenProgram =
		tokenProgramId || knownTokenProgramForMint(mint) || TOKEN_PROGRAM_ID;

	const expectedReceiverAta = getAssociatedTokenAddressSync(
		mint, payTo, false, tokenProgram, ASSOCIATED_TOKEN_PROGRAM_ID,
	);

	let transferCount = 0;
	let payer = null;
	let transferAmount = 0n;
	let cuLimit = 200_000; // Solana default when unset
	let cuPrice = 0n;
	let ataCreatePresent = false;
	let lighthouseCount = 0;
	let lighthouseTouchesFeePayer = false;

	const ixs = msg.compiledInstructions;
	try {
	for (const ix of ixs) {
		if (!idxInRange(ix.programIdIndex)) {
			return { ok: false, reason: 'malformed_instruction' };
		}
		const programId = keys[ix.programIdIndex];
		const data = ix.data; // Uint8Array
		const accts = ix.accountKeyIndexes;

		if (programId.equals(SYSTEM_PROGRAM_ID)) {
			// A top-level System instruction could move the sponsor's SOL. Never allow.
			return { ok: false, reason: 'system_instruction_forbidden' };
		}

		if (programId.equals(COMPUTE_BUDGET_PROGRAM_ID)) {
			const tag = data[0];
			if (tag === CB_SET_UNIT_LIMIT) {
				cuLimit = readU32LE(data, 1);
			} else if (tag === CB_SET_UNIT_PRICE) {
				cuPrice = readU64LE(data, 1);
			}
			// Other compute-budget tags carry no fund movement; ignore.
			continue;
		}

		if (MEMO_PROGRAM_IDS.some((id) => programId.equals(id))) {
			// Carries no fund movement (see MEMO_PROGRAM_IDS). Skipped, not counted.
			continue;
		}

		if (programId.equals(LIGHTHOUSE_PROGRAM_ID)) {
			// Wallet-injected assertions (see LIGHTHOUSE_PROGRAM_ID). Carries no
			// fund movement of its own; whether it may name the fee payer depends
			// on the mode, decided after the loop.
			if (!accts.every(idxInRange)) return { ok: false, reason: 'malformed_instruction' };
			lighthouseCount += 1;
			if (lighthouseCount > MAX_LIGHTHOUSE_INSTRUCTIONS) {
				return { ok: false, reason: `too_many_guard_instructions:${lighthouseCount}` };
			}
			if (accts.includes(0)) lighthouseTouchesFeePayer = true;
			continue;
		}

		if (programId.equals(ASSOCIATED_TOKEN_PROGRAM_ID)) {
			// Only permit creating OUR recipient's ATA, funded by the sponsor.
			// Accounts: [funder, ata, owner, mint, systemProgram, tokenProgram].
			if (accts.length < 4 || !accts.slice(0, 4).every(idxInRange)) {
				return { ok: false, reason: 'malformed_instruction' };
			}
			const funder = keys[accts[0]];
			const ata = keys[accts[1]];
			const owner = keys[accts[2]];
			const ixMint = keys[accts[3]];
			if (!ata.equals(expectedReceiverAta)) {
				return { ok: false, reason: 'ata_create_wrong_account' };
			}
			if (!owner.equals(payTo)) return { ok: false, reason: 'ata_create_wrong_owner' };
			if (!ixMint.equals(mint)) return { ok: false, reason: 'ata_create_wrong_mint' };
			if (!funder.equals(feePayer)) return { ok: false, reason: 'ata_create_wrong_funder' };
			// Accounts 4 and 5 are the System and token programs. The ATA address
			// already commits to the token program, so a mismatch here can only
			// fail on chain, after the sponsor paid the fee. Refuse it up front.
			if (accts.length >= 6 && idxInRange(accts[5]) && !keys[accts[5]].equals(tokenProgram)) {
				return { ok: false, reason: 'ata_create_wrong_token_program' };
			}
			ataCreatePresent = true;
			continue;
		}

		if (isSupportedTokenProgram(programId)) {
			// A real token program, but not the one that owns this mint: the
			// transfer would revert on chain. Name it instead of settling it.
			if (!programId.equals(tokenProgram)) {
				return { ok: false, reason: `wrong_token_program:${programId.toBase58()}` };
			}
			// The ONLY value-moving instruction we permit: one TransferChecked of
			// the required amount from the buyer to OUR recipient ATA.
			// Accounts: [source, mint, destination, authority].
			if (data[0] !== SPL_TRANSFER_CHECKED) {
				return { ok: false, reason: `token_ix_not_transfer_checked:${data[0]}` };
			}
			transferCount += 1;
			if (transferCount > 1) return { ok: false, reason: 'multiple_transfers' };

			// Accounts: [source, mint, destination, authority].
			if (accts.length < 4 || !accts.slice(0, 4).every(idxInRange)) {
				return { ok: false, reason: 'malformed_instruction' };
			}
			const source = keys[accts[0]];
			const ixMint = keys[accts[1]];
			const dest = keys[accts[2]];
			const authority = keys[accts[3]];

			if (!ixMint.equals(mint)) return { ok: false, reason: 'transfer_wrong_mint' };
			if (!dest.equals(expectedReceiverAta)) {
				return { ok: false, reason: 'transfer_wrong_destination' };
			}
			// The buyer (authority) must own the source ATA and must be a signer.
			const expectedSource = getAssociatedTokenAddressSync(
				mint, authority, false, tokenProgram, ASSOCIATED_TOKEN_PROGRAM_ID,
			);
			if (!source.equals(expectedSource)) {
				return { ok: false, reason: 'transfer_source_not_authority_ata' };
			}
			// authority must be a required signer (index < numRequiredSignatures).
			const authIndex = accts[3];
			if (authIndex >= msg.header.numRequiredSignatures) {
				return { ok: false, reason: 'authority_not_signer' };
			}

			// TransferChecked data: [12, u64 amount, u8 decimals].
			transferAmount = readU64LE(data, 1);
			payer = authority.toBase58();
			continue;
		}

		// Any other program touching this transaction is disallowed.
		return { ok: false, reason: `program_not_allowed:${programId.toBase58()}` };
	}
	} catch (err) {
		// Totality backstop: any unexpected throw while decoding adversarial
		// instruction bytes becomes a clean refusal, never a 5xx.
		return { ok: false, reason: `decode_error:${err?.message || err}` };
	}

	if (transferCount !== 1) return { ok: false, reason: 'no_usdc_transfer' };
	if (payer == null) return { ok: false, reason: 'no_authority' };
	if (transferAmount < requiredAmount) {
		return {
			ok: false,
			reason: `amount_below_required:${transferAmount}<${requiredAmount}`,
		};
	}

	// Self-pay vs sponsor mode. Self-pay: the buyer pays its own SOL fee (fee payer
	// == the USDC authority) → 1 signature, no sponsor, cheapest. Sponsor mode: the
	// fee payer must be the configured sponsor. Either way the sponsor can never be
	// coerced into spending USDC: in sponsor mode fee payer ≠ authority (this
	// branch), and self-pay only lets the buyer spend its own funds.
	const selfPay = feePayer.toBase58() === payer;
	if (!selfPay) {
		if (!feePayerPubkey || feePayer.toBase58() !== feePayerPubkey) {
			return { ok: false, reason: `fee_payer_not_sponsor:${feePayer.toBase58()}` };
		}
		// The sponsor signs the whole message, so an instruction that names its
		// account could charge it. A buyer's wallet guards the buyer's accounts
		// and has no reason to reference ours.
		if (lighthouseTouchesFeePayer) {
			return { ok: false, reason: 'guard_instruction_references_sponsor' };
		}
	}

	// Bound the priority fee the fee-paying wallet will pay.
	if (cuLimit > MAX_CU_LIMIT) return { ok: false, reason: `cu_limit_too_high:${cuLimit}` };
	if (cuPrice > BigInt(MAX_CU_PRICE_MICROLAMPORTS)) {
		return { ok: false, reason: `cu_price_too_high:${cuPrice}` };
	}
	const priorityLamports = Number((cuPrice * BigInt(cuLimit)) / 1_000_000n);
	if (priorityLamports > MAX_PRIORITY_LAMPORTS) {
		return { ok: false, reason: `priority_fee_too_high:${priorityLamports}` };
	}

	const baseFee = 5000 * msg.header.numRequiredSignatures;
	const estFeeLamports =
		baseFee + priorityLamports + (ataCreatePresent ? ataRentLamports(tokenProgram.toBase58()) : 0);

	return {
		ok: true,
		decoded: {
			tx,
			payer,
			payTo: payTo.toBase58(),
			mint: mint.toBase58(),
			tokenProgram: tokenProgram.toBase58(),
			amountAtomic: Number(transferAmount),
			feePayer: feePayer.toBase58(),
			selfPay,
			estFeeLamports,
			ataCreatePresent,
		},
	};
}

// Check every buyer signature on a decoded ring transaction against its message.
//
// validateRingTransaction proves the authority is LISTED as a signer and the
// settleability simulation runs with sigVerify:false (the sponsor has not
// co-signed yet), so nothing on the verify path ever checked a signature. A
// transfer naming any funded wallet as authority, carrying garbage signatures,
// therefore verified as valid and the paid handler ran (a coin launch on the
// platform's SOL, a cosmetic grant and creator payout, a GPU job) before settle
// failed. In sponsor mode the fee-payer slot is skipped: the sponsor signs only
// at settle.
export function verifyBuyerSignatures({ tx, feePayer, selfPay }) {
	const msg = tx.message;
	const required = msg.header.numRequiredSignatures;
	let bytes;
	try {
		bytes = msg.serialize();
	} catch (err) {
		return { ok: false, reason: `message_unserializable:${err?.message || err}` };
	}
	for (let i = 0; i < required; i += 1) {
		const key = msg.staticAccountKeys[i];
		if (!key) return { ok: false, reason: 'missing_signer_key' };
		const b58 = key.toBase58();
		if (!selfPay && b58 === feePayer) continue;
		const sig = tx.signatures?.[i];
		if (!sig || sig.length !== 64 || sig.every((b) => b === 0)) {
			return { ok: false, reason: `missing_signature:${b58}` };
		}
		let ok = false;
		try {
			ok = ed25519.verify(sig, bytes, key.toBytes());
		} catch {
			ok = false;
		}
		if (!ok) return { ok: false, reason: `invalid_signature:${b58}` };
	}
	return { ok: true };
}

// Is the transaction's recent blockhash still live? Returns true, false, or null
// when the RPC cannot say. A node a few slots behind the buyer's may not know a
// brand-new hash yet, so a `false` is re-asked once after a short pause before it
// is believed. A dead or made-up blockhash can never land, and the settle path
// would otherwise answer it `pending`, which the resource server delivers on.
export async function blockhashIsLive(connection, blockhash, { recheckMs = 1500 } = {}) {
	if (typeof connection?.isBlockhashValid !== 'function' || !blockhash) return null;
	const ask = async () => {
		try {
			const r = await connection.isBlockhashValid(blockhash, { commitment: 'processed' });
			const v = r && typeof r === 'object' && 'value' in r ? r.value : r;
			return typeof v === 'boolean' ? v : null;
		} catch {
			return null;
		}
	};
	const first = await ask();
	if (first !== false) return first;
	if (recheckMs > 0) await new Promise((r) => setTimeout(r, recheckMs));
	return ask();
}

// Extract the base64 signed transaction from an x402 payment payload.
export function txBase64FromPayload(paymentPayload) {
	return (
		paymentPayload?.payload?.transaction ||
		paymentPayload?.transaction ||
		null
	);
}

// ── Sponsor SOL guard ────────────────────────────────────────────────────────
// Cache the sponsor SOL balance briefly so a high-throughput settle stream does
// not hit getBalance on every payment. The floor check is the hard stop that
// keeps the loop from ever draining our SOL: below the floor, settle refuses and
// the paying loop stalls until the sponsor is topped up.
const _solCache = new Map(); // pubkeyB58 → { lamports, at }
const SOL_CACHE_MS = 20_000;

// Last observed floor state, readable synchronously. buildRequirements (the
// 402 challenge builder) is sync and hot, so it cannot await a balance read,
// but it CAN consult what the settle path most recently observed and stop
// advertising a Solana accept that is guaranteed to die at settle. Validity is
// deliberately longer than the balance cache: during a dry spell settles keep
// probing (refreshing this), and 60s of staleness only delays re-advertising
// by less than the treasury-topup cadence that refunds the wallet.
const FLOOR_STATE_MS = 60_000;
let _floorState = { below: false, at: 0 };

export function sponsorKnownBelowFloor(now = Date.now()) {
	return _floorState.below && now - _floorState.at < FLOOR_STATE_MS;
}

function noteFloorState(lamports, now) {
	_floorState = { below: lamports < SPONSOR_SOL_FLOOR_LAMPORTS, at: now };
}

/**
 * Record floor state only for the wallet the 402 challenge actually advertises.
 *
 * `_floorState` gates whether buildRequirements keeps offering the SPONSORED
 * Solana accept, so it is only meaningful for X402_FEE_PAYER_SOLANA. Recording
 * it from any fee wallet let a healthy self-pay buyer stamp `below:false` and
 * re-advertise a starved sponsor for the full FLOOR_STATE_MS, which is how a
 * dry sponsor kept handing out accepts that could not settle (2026-09).
 */
function noteFloorStateFor(pubkeyB58, lamports, now) {
	if (pubkeyB58 === env.X402_FEE_PAYER_SOLANA) noteFloorState(lamports, now);
}

/**
 * Is this simulation error the chain saying the FEE PAYER cannot afford the fee
 * without dropping below rent exemption?
 *
 * Account index 0 of a compiled Solana message is the fee payer, by definition,
 * so `InsufficientFundsForRent { account_index: 0 }` is never about the buyer's
 * token balance: it is the sponsor being too poor to sign. Both spellings the
 * RPCs use are matched, the structured `err` object and the human sentence that
 * reaches the sweep path inside a SendTransactionError message.
 * @param {unknown} simErr
 * @returns {boolean}
 */
export function isFeePayerRentFailure(simErr) {
	if (simErr == null) return false;
	if (typeof simErr === 'object') {
		return Number(/** @type {any} */ (simErr)?.InsufficientFundsForRent?.account_index) === 0;
	}
	const s = String(simErr);
	if (/InsufficientFundsForRent/.test(s)) return /"account_index"\s*:\s*0/.test(s);
	return /account \(0\) with insufficient funds for rent/i.test(s);
}

/**
 * Trip the floor guard from a settle failure instead of a balance read.
 *
 * The guard was only ever written by getBalance, which is exactly the call that
 * stops answering when the Solana RPC lanes are over quota, and
 * refreshSponsorFloorState fails open on that error by design. So the two
 * failures compounded: on 2026-08-28 all four paid lanes were exhausted at once
 * while the sponsor sat at 0.000899 SOL against a 0.02 floor, the guard never
 * learned it, and the ring spent three hours making payments that could not
 * settle. 95 attempts, 0 settled, every one of them dying on this exact error.
 *
 * A rent-exemption failure on our own fee payer is strictly better evidence than
 * the balance read it replaces: it is free, it is the chain's own verdict, and
 * it arrives precisely when the RPC is too degraded to answer anything else.
 *
 * Only OUR sponsor counts. In a self-pay settle the buyer is the fee payer, and
 * tripping the platform-wide guard because one buyer is broke would withdraw the
 * Solana accept from every 402 challenge on the site.
 * @param {unknown} simErr
 * @param {string|null|undefined} feePayer the transaction's fee payer
 * @param {number} [now]
 * @returns {boolean} true when the guard was tripped
 */
export function noteSponsorRentFailure(simErr, feePayer, now = Date.now()) {
	if (!isFeePayerRentFailure(simErr)) return false;
	const sponsor = env.X402_FEE_PAYER_SOLANA;
	if (!sponsor || !feePayer || String(feePayer) !== String(sponsor)) return false;
	_floorState = { below: true, at: now };
	return true;
}

// Keep the floor state warm on instances that never settle.
//
// The state above is per-process and was only written by the settle path, so a
// Cloud Run instance serving nothing but 402 challenges never learned the
// sponsor was dry and kept advertising a Solana accept that could not settle.
// Callers on the challenge path invoke this WITHOUT awaiting: it refreshes at
// most once per SOL_CACHE_MS per instance, swallows every error (an RPC blip
// must never affect a challenge), and leaves the state untouched on failure so
// the fail-open default stands. First request after a cold start still
// advertises Solana; every request after it is accurate.
let _floorRefreshInFlight = null;

export function refreshSponsorFloorState(now = Date.now()) {
	const pubkey = env.X402_FEE_PAYER_SOLANA;
	if (!pubkey) return;
	if (_floorRefreshInFlight) return;
	const hit = _solCache.get(pubkey);
	if (hit && hit.lamports != null && now - hit.at < SOL_CACHE_MS) return;

	_floorRefreshInFlight = (async () => {
		try {
			const conn = solanaConnection({ url: env.SOLANA_RPC_URL, commitment: 'confirmed' });
			const lamports = await conn.getBalance(new PublicKey(pubkey), 'confirmed');
			_solCache.set(pubkey, { lamports, at: Date.now() });
			noteFloorState(lamports, Date.now());
		} catch {
			/* RPC unreachable: keep the last known state, fail open */
		} finally {
			_floorRefreshInFlight = null;
		}
	})();
}

export async function sponsorSolLamports(conn, feePayerPubkey, now = Date.now()) {
	const key = feePayerPubkey.toBase58();
	const hit = _solCache.get(key);
	if (hit && hit.lamports != null && now - hit.at < SOL_CACHE_MS) return hit.lamports;
	const lamports = await conn.getBalance(feePayerPubkey, 'confirmed');
	_solCache.set(key, { lamports, at: now });
	noteFloorStateFor(key, lamports, now);
	return lamports;
}

// Debit the cache right after a settle so the next check sees the balance
// approaching the floor without another RPC round-trip.
function bumpSolCache(pubkeyB58, deltaLamports) {
	const hit = _solCache.get(pubkeyB58);
	if (hit && hit.lamports != null) {
		hit.lamports = Math.max(0, hit.lamports - deltaLamports);
		noteFloorStateFor(pubkeyB58, hit.lamports, Date.now());
	}
}

// How long a settle blocks waiting for confirmation before it answers
// `settlement_pending` and lets the reconcile cron finish the job. The old
// 30-second wait was the only thing between a slow slot and a 502, so it had to
// be long; now that an unresolved wait is a third outcome rather than a failure,
// holding the buyer's connection open for half a minute buys nothing. 12s clears
// the overwhelming majority of Solana confirmations inline and caps the settle
// leg of a paid request at a latency a client library will sit through.
// Read per call, not at import: the confirmation window is the one settle
// tunable an operator reaches for DURING an incident (a degraded RPC wants a
// shorter wait so more settles go pending and reconcile out of band), and a
// module-load constant would need a redeploy to move.
function settleConfirmTimeoutMs() {
	const raw = Number(process.env.X402_SETTLE_CONFIRM_TIMEOUT_MS);
	return Number.isFinite(raw) && raw > 0 ? raw : 12_000;
}
// Status poll cadence. Tightened with the timeout above: at 1200ms a transaction
// that confirms in 500ms still paid up to a full extra second of latency.
const CONFIRM_POLL_MS = 800;

// Wait for a signature's fate.
//
// Three answers, not two, because "we do not know yet" is a real state and the
// caller's response to it differs completely from a rejection:
//   { confirmed: true }                    landed, no error.
//   { confirmed: false, terminal: true }   landed and FAILED on chain. It ran
//                                            and reverted, so there is nothing
//                                            to wait for; report the failure.
//   { confirmed: false, terminal: false }  the wait ran out, or the RPC could
//                                            not answer. The transaction may
//                                            still land. NEVER report failure
//                                            here: this is `settlement_pending`.
//
// A transaction that was dropped without landing looks identical to the third
// case from inside the wait, and it is the reconcile pass
// (probeSettlementSignature) that later distinguishes the two, once the
// blockhash can no longer be valid.
async function confirmSignature(conn, signature, timeoutMs) {
	const deadline = Date.now() + (timeoutMs ?? settleConfirmTimeoutMs());
	let lastRpcError = null;
	for (;;) {
		try {
			const { value } = await conn.getSignatureStatuses([signature]);
			const st = value?.[0];
			if (st) {
				if (st.err) {
					// An on-chain error is definitive: this transaction ran and reverted.
					return { confirmed: false, terminal: true, err: JSON.stringify(st.err) };
				}
				if (st.confirmationStatus === 'confirmed' || st.confirmationStatus === 'finalized') {
					return { confirmed: true };
				}
			}
			lastRpcError = null;
		} catch (err) {
			// An RPC that cannot answer tells us nothing about the transaction. Keep
			// polling until the deadline, then report UNKNOWN, not failure.
			lastRpcError = String(err?.message || err).slice(0, 160);
		}
		if (Date.now() > deadline) {
			return {
				confirmed: false,
				terminal: false,
				err: lastRpcError ? `confirm_rpc_unavailable:${lastRpcError}` : 'confirm_timeout',
			};
		}
		await new Promise((r) => setTimeout(r, CONFIRM_POLL_MS));
	}
}

// Finish a settle whose transaction is already on the wire: re-await THIS
// signature instead of verifying, co-signing, and broadcasting a second
// transaction.
//
// Reached from the pending-store hit at the top of settleRingPayment, i.e. a
// retry of a payload we have already broadcast. Re-sending there is what the
// pending state exists to prevent: the original may land at any moment, and a
// second transfer of the same funds is a double charge. (The reconcile cron
// answers the same question out of band, without a payload in hand, through
// probeSettlementSignature.)
async function awaitBroadcastSettlement({
	connection,
	signature,
	network,
	payer,
	decoded,
	pendingStore,
	key,
	meta,
}) {
	const conf = await confirmSignature(connection, signature);
	if (conf.confirmed) {
		if (pendingStore && key) await pendingStore.delete(key);
		return {
			success: true,
			transaction: signature,
			network,
			payer,
			feeLamports: decoded?.estFeeLamports ?? meta?.feeLamports ?? 0,
			feePayer: decoded?.feePayer ?? meta?.feePayer ?? null,
			selfPay: decoded?.selfPay ?? false,
			reconciled: true,
		};
	}
	if (conf.terminal) {
		if (pendingStore && key) await pendingStore.delete(key);
		return { success: false, reason: `not_confirmed:${conf.err}`, transaction: signature };
	}
	// Still unknown. Re-record (refreshing the row's error detail) and stay pending.
	return recordPendingOrTerminal({
		store: pendingStore,
		key,
		signature,
		network,
		payer,
		meta,
		cause: conf.err,
	});
}

// Settle a validated ring payment: co-sign with the sponsor, broadcast over our
// RPC, confirm. Returns the x402-wire settle shape { success, transaction,
// network, payer } plus feeLamports for the burn meter and feePayer/selfPay for
// per-wallet fee attribution. Never throws for a rejected payment — a refusal
// is a clean { success:false, reason }.
//
// `feeMeter` is the optional wallet fee governor hook (wallet-fee-meter.js):
// called after the hard SOL floor passes, with the wallet that will actually
// pay this transaction's fee. A { ok:false } verdict refuses the settle before
// any co-sign/broadcast; a hook error fails OPEN — the floor is the hard
// protection, the meter is pacing.
//
// `pendingStore` is the x402 PendingSettlementStore (pending-settlements.js).
// With one supplied, a confirmation wait that ends UNKNOWN records the broadcast
// signature and answers `settlement_pending` instead of a failure the buyer's
// payment contradicts, and a retry of the same payload reconciles against that
// signature rather than broadcasting a second transaction. Without one the
// behaviour is the old binary, which is why the endpoint always passes it.
export async function settleRingPayment({
	paymentPayload,
	requirement,
	conn,
	feePayer,
	feeMeter,
	pendingStore,
	idempotencyKey,
}) {
	const network = requirement.network;
	const connection = conn || solanaConnection({ url: env.SOLANA_RPC_URL, commitment: 'confirmed' });

	const txBase64 = txBase64FromPayload(paymentPayload);
	if (!txBase64) return { success: false, reason: 'missing_transaction' };

	// The sponsor pubkey only authorizes SPONSOR-mode payments; a self-pay tx
	// carries its own fee payer and needs no sponsor key at all.
	const sponsorPubkey = feePayer?.publicKey?.toBase58() || env.X402_FEE_PAYER_SOLANA || null;
	const program = await resolveRingTokenProgram(connection, requirement);
	if (!program.ok) return { success: false, reason: program.reason };
	const validation = validateRingTransaction({
		txBase64,
		requirement,
		feePayerPubkey: sponsorPubkey,
		allowlist: payToAllowlist(),
		tokenProgramId: program.tokenProgramId,
	});
	if (!validation.ok) return { success: false, reason: validation.reason };
	const decoded = validation.decoded;
	const { tx, payer, estFeeLamports, selfPay } = decoded;
	const sigCheck = verifyBuyerSignatures(decoded);
	if (!sigCheck.ok) return { success: false, reason: sigCheck.reason };

	// Metadata every pending record and reconcile pass needs, assembled once.
	const pendingKey = pendingSettlementKey(txBase64);
	const pendingMeta = {
		network,
		payer,
		payTo: requirement.payTo,
		mint: requirement.asset,
		amountAtomic: decoded.amountAtomic,
		feeLamports: estFeeLamports,
		feePayer: decoded.feePayer,
		// The caller's settle idempotency key, stored so the reconcile pass claims
		// the settle credit under the SAME key the resource server used. Without it
		// the credit gate reads the reconciled claim as a different payment reusing
		// the signature and refuses it (settle-credit.js classify()).
		idempotencyKey: idempotencyKey || null,
	};

	// A retry of a payload we ALREADY broadcast: re-await that signature. Placed
	// before the balance reads, the fee meter, the co-sign, and the broadcast
// because none of them should run twice. The first attempt already spent
	// (or committed to spending) this transaction's fee, and a second broadcast
	// of a different transaction for the same authorization is a double charge.
	if (pendingStore && pendingKey) {
		const cachedSignature = await pendingStore.get(pendingKey);
		if (cachedSignature) {
			return awaitBroadcastSettlement({
				connection,
				signature: cachedSignature,
				network,
				payer,
				decoded,
				pendingStore,
				key: pendingKey,
				meta: pendingMeta,
			});
		}
	}

	// Anti fee-burn: a sponsor-mode settle must move at least enough to cover the
	// SOL fee we're about to burn co-signing it. Blocks the dust-transfer grief
	// (1-atomic allowlisted transfers spammed to pump down sponsor SOL). Self-pay
	// settles pay their own fee, so a dust self-pay costs us nothing — exempt them.
	if (!selfPay && decoded.amountAtomic < MIN_SPONSOR_SETTLE_ATOMIC) {
		return {
			success: false,
			reason: `amount_below_min_settle:${decoded.amountAtomic}<${MIN_SPONSOR_SETTLE_ATOMIC}`,
		};
	}

	// Hard stop: never settle if the fee-paying wallet is below its SOL floor.
	// Self-pay → the payer pays its own fee; sponsor mode → the sponsor pays.
	const feeWallet = new PublicKey(decoded.feePayer);
	const solLamports = await sponsorSolLamports(connection, feeWallet);
	// The floor is a reserve protecting OUR sponsor wallet from being drained by
	// the paying loop. In self-pay the fee wallet is the buyer's own, so holding
	// their balance to our reserve would refuse a perfectly good payment for the
	// crime of not keeping 0.02 SOL spare. They only have to afford the fee they
	// are about to pay, which the affordability check below enforces.
	const floorFor = selfPay ? 0 : SPONSOR_SOL_FLOOR_LAMPORTS;
	if (solLamports < floorFor) {
		return {
			success: false,
			reason: `fee_wallet_below_floor:${solLamports}<${floorFor}`,
			sponsorSolLamports: solLamports,
			feePayer: decoded.feePayer,
			payer,
			selfPay,
		};
	}

	// The floor is a reserve that must SURVIVE this settle, so the wallet has to
	// clear it by the cost of the settle itself, not merely sit above it.
	// estFeeLamports carries the ATA-create rent (~0.00204 SOL) when the recipient
	// has no token account for this mint yet, which is the normal state the first
	// time a resource is paid in a new token. Comparing the bare balance let such
	// a settle pass the gate and then die on chain with InsufficientFundsForRent,
	// a confusing failure at exactly the moment a new payment token goes live.
	if (solLamports - estFeeLamports < floorFor) {
		return {
			success: false,
			// Distinct reason per mode, because the two mean opposite things to the
			// person reading the error. In sponsor mode WE are short and the buyer
			// should retry later; in self-pay the BUYER's own wallet cannot cover
			// the network fee, and telling them we are topping up our wallet would
			// send them away waiting for something that will never help.
			reason: selfPay
				? `buyer_cannot_cover_fee:${solLamports}<${estFeeLamports}`
				: `fee_wallet_cannot_cover_settle:${solLamports}-${estFeeLamports}<${floorFor}`,
			sponsorSolLamports: solLamports,
			estFeeLamports,
			feePayer: decoded.feePayer,
			payer,
			selfPay,
		};
	}

	// Wallet fee governor: admit this settle only if the fee-paying wallet still
	// has daily fee budget. Governs every tenant of a shared wallet at the one
	// choke point they all pass through, instead of throttling one pipeline while
	// the others drain the same runway.
	if (feeMeter) {
		let meterVerdict = null;
		try {
			meterVerdict = await feeMeter({
				feeWalletB58: decoded.feePayer,
				buyerB58: decoded.payer,
				solLamports,
				estFeeLamports,
				selfPay,
			});
		} catch { /* meter fault → fail open; the SOL floor above is the hard stop */ }
		if (meterVerdict && meterVerdict.ok === false) {
			return {
				success: false,
				reason: meterVerdict.reason || 'fee_runway_exhausted',
				sponsorSolLamports: solLamports,
				feePayer: decoded.feePayer,
				// Recorded so the facilitator's reject book names WHO was refused.
				// Without it, 43,848 governor refusals in a day logged payer NULL and
				// the flood could only be traced through the matching verify rows.
				payer,
				selfPay,
			};
		}
	}

	// Sponsor mode co-signs the fee payer (buyer already signed); a self-pay tx is
	// already fully signed and just needs broadcasting.
	if (!selfPay) {
		let sponsor;
		try {
			sponsor = feePayer || loadFeePayerKeypair();
		} catch (err) {
			return { success: false, reason: `sponsor_key_unconfigured:${err.message}` };
		}
		try {
			tx.sign([sponsor]);
		} catch (err) {
			return { success: false, reason: `cosign_failed:${err.message}` };
		}
	}

	let signature;
	// Set only when the preflight-off resend below is attempted and also fails, so
	// the reported reason distinguishes "our read node was stale" from "the payment
	// was genuinely unsendable".
	let preflightRetryNote = '';
	let preflightBlockhashRejected = false;
	try {
		signature = await connection.sendRawTransaction(tx.serialize(), {
			skipPreflight: false,
			maxRetries: 5,
		});
	} catch (err) {
		const m = String(err?.message || err);
		const sig = tx.signatures?.[0] ? bs58.encode(tx.signatures[0]) : null;
		// A resent settle (idempotent replay) hits "already processed" — the prior
		// broadcast landed. Recover the signature from the tx and report success.
		if (/already been processed|AlreadyProcessed|already processed/i.test(m)) {
			if (sig) {
				return {
					success: true,
					transaction: sig,
					network,
					payer,
					feeLamports: estFeeLamports,
					feePayer: decoded.feePayer,
					selfPay,
					replayed: true,
				};
			}
		}
		// web3.js drops the structured preflight cause (res.error.data.err), so on
		// some RPCs a duplicate-signature rejection arrives as a bare "Transaction
		// simulation failed" with empty logs — including our own maxRetries resend
		// racing the first landing. Probe the signature: if it already landed with no
		// error, this IS this payment's settlement, not a stranger's. The x402
		// authorization is single-use (payment-identifier-server.js reserves a SHA-256
		// lock on the signed X-PAYMENT before settle, and the on-chain nonce is consumed
		// on first settle), so no other payment can reproduce this exact signature.
		// Failing closed here 502'd payments that had actually settled — the dominant
		// settle_failed wave. Recover success identically to the message-matched
		// idempotent-replay branch above; the buyer is owed the product, not a 502.
		// Only a blockhash rejection proves the transaction never reached a validator.
		// Every other failure leaves its fate UNKNOWN — including an RPC whose reply
		// web3.js could not even parse ("Expected the value to satisfy a union of
		// `type | type`", seen when a fallback endpoint answers in a non-standard
		// shape). That class skipped the probe entirely and reported failure on a
		// payment that may well have settled, so probe on everything except the one
		// provably-never-landed case.
		const provablyNeverLanded = /blockhash not found/i.test(m);
		let alreadyLanded = false;
		if (sig && !provablyNeverLanded) {
			try {
				// searchTransactionHistory so a tx that landed a moment earlier and aged
				// out of the recent-status cache is still found — else the probe returns
				// null and we wrongly fail a settled payment.
				const st = (await connection.getSignatureStatuses([sig], { searchTransactionHistory: true }))
					?.value?.[0];
				alreadyLanded = st != null && st.err == null;
			} catch { /* probe is best-effort; the generic reason below stands */ }
		}
		if (alreadyLanded) {
			return {
				success: true,
				transaction: sig,
				network,
				payer,
				feeLamports: estFeeLamports,
				feePayer: decoded.feePayer,
				selfPay,
				replayed: true,
			};
		}
		// A preflight "blockhash not found" is usually a FALSE rejection, not a dead
		// transaction. The buyer builds and signs the payment against THEIR RPC, so the
		// blockhash it carries is real; we then preflight it on whichever node our
		// rotating pool happens to answer with, and a node lagging even a few slots
		// behind the buyer's has simply never seen that hash. web3.js surfaces that as a
		// hard send failure, so a perfectly valid payment was reported broadcast_failed
		// and the buyer 502'd having already been charged for the handler.
		// Re-sending with preflight OFF hands the decision to the validator instead of
		// our read node: if the hash is live the settle lands, and if it genuinely
		// expired the transaction is dropped without landing and without a fee, so the
		// only cost is the confirm wait below. Resending the identical signed bytes is
		// idempotent (Solana dedupes by signature), so this cannot double-settle.
		if (provablyNeverLanded) {
			preflightBlockhashRejected = true;
			try {
				signature = await connection.sendRawTransaction(tx.serialize(), {
					skipPreflight: true,
					maxRetries: 5,
				});
			} catch (retryErr) {
				preflightRetryNote = ` preflight_retry_failed:${String(retryErr?.message || retryErr).slice(0, 120)}`;
			}
		}
		// Only report a broadcast failure if the preflight-off resend above did not
		// produce a signature; otherwise fall through to the confirm step below.
		if (signature == null) {
			// The dominant broadcast failure reaches production logs with NO cause at all:
			// web3.js renders the preflight rejection as "Transaction simulation failed.
			// Logs: []" and drops the structured cause (res.error.data.err), while its own
			// getLogs() only reads back a LANDED transaction, useless for a tx that never
			// landed. Re-simulate on the failure path to recover that cause. Deliberately
			// replaceRecentBlockhash:false, unlike the assertSettleable pre-check: the point
			// is to see whether the blockhash this send actually carried was unknown to the
			// endpoint that answered, which is how a rotating multi-RPC pool fails when the
			// hash is fetched from one node and the send lands on another.
			let cause = '';
			if (!/Logs: \[[^\]]/.test(m)) {
				try {
					const sim = await connection.simulateTransaction(tx, {
						sigVerify: false,
						replaceRecentBlockhash: false,
						commitment: 'confirmed',
					});
					const simErr = sim?.value?.err ?? null;
					const simLogs = Array.isArray(sim?.value?.logs) ? sim.value.logs : [];
					if (simErr) {
						cause = ` cause:${typeof simErr === 'object' ? JSON.stringify(simErr) : String(simErr)}`;
					} else {
						// The re-simulation came back CLEAN: this transaction is valid, and the
						// node that answered the send rejected it anyway. Left unmarked this was
						// the worst log line in the settle path, a "Logs: []" failure with no
						// cause appended, indistinguishable from "the cause probe found nothing"
						// and from a real program error. It names the actual condition instead:
						// our rotating pool asked one node to preflight a transaction another
						// node's blockhash built, which is the expected failure shape while the
						// paid RPC tier is exhausted and traffic is riding throttled free nodes.
						cause = ' cause:resim_clean_preflight_false_negative';
					}
					if (simLogs.length) cause += ` logs:${simLogs.slice(-3).join(' | ')}`;
				} catch (reSimErr) {
					cause = ` cause_probe_failed:${String(reSimErr?.message || reSimErr).slice(0, 120)}`;
				}
			}
			// web3.js appends the LAST simulation-log lines to the message, so the
			// failure cause sits at the END. A head-only truncation kept only the
			// ComputeBudget preamble and hid the failing instruction from every
			// production log. Keep the head (error class) and the tail (cause).
			const detail = `${m}${cause}${preflightRetryNote}`.replace(/\s+/g, ' ').trim();
			const full = `broadcast_failed:${detail}`;
			const reason = full.length <= 480 ? full : `${full.slice(0, 200)} … ${full.slice(-276)}`;
			return { success: false, reason };
		}
	}

	const conf = await confirmSignature(connection, signature);
	if (!conf.confirmed) {
		// Landed and reverted, or provably dropped: a real failure.
		if (conf.terminal) {
			if (pendingStore && pendingKey) await pendingStore.delete(pendingKey);
			return { success: false, reason: `not_confirmed:${conf.err}`, transaction: signature };
		}
		// A send our node rejected as "blockhash not found" and that still has not
		// landed is pending only if that blockhash can still be included. A dead
		// or made-up hash never lands, and answering pending would deliver the paid
		// good for a payment that can never settle, as often as the buyer likes.
		if (preflightBlockhashRejected) {
			const live = await blockhashIsLive(connection, tx.message.recentBlockhash, { recheckMs: 0 });
			if (live === false) {
				if (pendingStore && pendingKey) await pendingStore.delete(pendingKey);
				return { success: false, reason: 'blockhash_expired', transaction: signature };
			}
		}
		// Outcome unknown. The transaction is broadcast and may land at any moment,
		// so reporting failure here would tell a buyer who is about to be charged
		// that they were not. Record the signature and answer `settlement_pending`;
		// the caller's retry reconciles against it and the reconcile cron closes the
		// books either way. The fee cache is deliberately NOT bumped: whether the
		// fee was burned is exactly what we do not know yet, and the reconcile pass
		// meters it once the chain answers.
		return recordPendingOrTerminal({
			store: pendingStore,
			key: pendingKey,
			signature,
			network,
			payer,
			meta: pendingMeta,
			cause: conf.err,
		});
	}

	if (pendingStore && pendingKey) await pendingStore.delete(pendingKey);
	bumpSolCache(feeWallet.toBase58(), estFeeLamports);

	// Best-effort: read the real network fee for accurate burn accounting.
	let feeLamports = estFeeLamports;
	try {
		const parsed = await connection.getParsedTransaction(signature, {
			maxSupportedTransactionVersion: 1,
			commitment: 'confirmed',
		});
		if (parsed?.meta?.fee != null) {
			feeLamports =
				parsed.meta.fee + (decoded.ataCreatePresent ? ataRentLamports(decoded.tokenProgram) : 0);
		}
	} catch { /* estimate stands */ }

	return {
		success: true,
		transaction: signature,
		network,
		payer,
		feeLamports,
		feePayer: decoded.feePayer,
		selfPay,
	};
}

// Prove a shape-valid payment can ACTUALLY settle before /verify returns valid.
//
// validateRingTransaction() is a static decode: it proves the tx is SHAPED right
// (amount ≥ required, correct mint/recipient/authority, bounded fee) but not that
// broadcasting it would succeed. Without this check a buyer can sign a perfectly-
// formed TransferChecked from a source ATA holding ZERO USDC — static validation
// passes, the paid flow (verify → run handler → settle) executes the expensive
// handler and pays the upstream provider, then settle reverts `insufficient funds`
// and the buyer gets a 502 having paid nothing. The platform ate the provider cost.
// This closes that deliver-before-settle drain: the handler never runs unless the
// payment can settle. The external PayAI facilitator simulates on /verify for the
// same reason; the in-house one must not be weaker.
//
// Primary check is a full simulation (sigVerify:false so the sponsor's co-signature
// isn't required yet; replaceRecentBlockhash:true so an aged blockhash isn't the
// failure) — it catches a zero/low source balance, a frozen ATA, and an unfundable
// fee payer in one RPC. If simulation itself is unavailable (RPC blip) we fall back
// to a direct source-ATA balance read so the zero-balance vector stays closed, and
// fail CLOSED only when neither can run — an unverifiable payment must never reach
// the handler.
async function assertSettleable({ tx, connection, requirement, decoded }) {
	try {
		const sim = await connection.simulateTransaction(tx, {
			sigVerify: false,
			replaceRecentBlockhash: true,
			commitment: 'confirmed',
		});
		const simErr = sim?.value?.err ?? null;
		if (simErr) {
			const s = typeof simErr === 'object' ? JSON.stringify(simErr) : String(simErr);
			// A dry sponsor is a platform condition, not this payment's fault: record
			// it so the 402 challenge stops advertising a Solana accept that cannot
			// settle, rather than rejecting one payment and inviting the next.
			const sponsorDry = noteSponsorRentFailure(simErr, decoded?.feePayer);
			// Give the fee-payer verdict its own reason CLASS, because every consumer
			// of this string groups on the token before the first ':'. /api/healthz
			// exposes only that prefix, and isRailFault() in ops/x402-settle-health.js
			// matches /simulation/, so folding this into `simulation_failed` filed
			// the platform's own unfundable sponsor under the same bucket as a buyer
			// signing from an empty ATA, AND counted it as a rail fault. Measured in
			// production on 2026-09-09: `simulation_failed` sat at the top of the
			// verify book with 1,438 rejects in 24h and every single row was
			// {"InsufficientFundsForRent":{"account_index":0}} on our sponsor, a
			// wallet 0.00083 SOL under its floor. Read as a rail fault it points an
			// operator at the RPC lanes, which is the one thing this class is never
			// about. Account index 0 is the fee payer by definition, so the split is
			// exact, not a heuristic: `sponsor_fee_unfunded` is ours to fund,
			// `payer_fee_unfunded` is the buyer's own wallet and needs nothing.
			if (isFeePayerRentFailure(simErr)) {
				const cls = sponsorDry ? 'sponsor_fee_unfunded' : 'payer_fee_unfunded';
				const who = decoded?.feePayer ? String(decoded.feePayer) : 'unknown';
				return { ok: false, reason: `${cls}:${who}`.slice(0, 160) };
			}
			return { ok: false, reason: `simulation_failed:${s}`.slice(0, 160) };
		}
		return { ok: true };
	} catch (simUnavailable) {
		// Simulation RPC unreachable — do not fail open. Read the source ATA balance
		// directly; this alone still stops a transfer signed from a zero-balance ATA.
		try {
			const mint = new PublicKey(decoded.mint);
			const authority = new PublicKey(decoded.payer);
			const sourceAta = getAssociatedTokenAddressSync(
				mint, authority, false, new PublicKey(decoded.tokenProgram), ASSOCIATED_TOKEN_PROGRAM_ID,
			);
			const bal = await connection.getTokenAccountBalance(sourceAta, 'confirmed');
			const have = BigInt(bal?.value?.amount ?? '0');
			const need = BigInt(requirement.amount);
			if (have < need) {
				return { ok: false, reason: `insufficient_source_balance:${have}<${need}` };
			}
			return { ok: true };
		} catch (balUnavailable) {
			return {
				ok: false,
				reason: `settle_precheck_unavailable:${String(
					balUnavailable?.message || simUnavailable?.message || balUnavailable,
				).slice(0, 100)}`,
			};
		}
	}
}

// Resolve the token program for the requirement's mint before static validation.
// The two mints the platform settles are seeded, so this is a map read on the hot
// path. A deployment that points THREE_TOKEN_MINT or X402_ASSET_MINT_SOLANA at a
// different mint costs one cached account read. Mints outside that set are left
// unresolved on purpose: the requirement is caller-supplied, and validation
// refuses them as `mint_not_settleable` without spending an RPC call on junk.
async function resolveRingTokenProgram(connection, requirement) {
	const mint = String(requirement?.asset || '');
	const known = knownTokenProgramForMint(mint);
	if (known) return { ok: true, tokenProgramId: known };
	const settleable = [env.X402_ASSET_MINT_SOLANA, env.THREE_TOKEN_MINT].filter(Boolean);
	if (!settleable.includes(mint)) return { ok: true, tokenProgramId: null };
	try {
		return { ok: true, tokenProgramId: await tokenProgramForMint(connection, mint) };
	} catch (err) {
		return {
			ok: false,
			reason: `token_program_unresolved:${String(err?.code || err?.message || err).slice(0, 100)}`,
		};
	}
}

// Verify shape for /verify — validate statically, then prove settleability on-chain
// WITHOUT broadcasting. Async: the settleability proof is one RPC round-trip.
export async function verifyRingPayment({ paymentPayload, requirement, feePayerPubkey, conn }) {
	const txBase64 = txBase64FromPayload(paymentPayload);
	if (!txBase64) return { isValid: false, invalidReason: 'missing_transaction' };
	const connection =
		conn || solanaConnection({ url: env.SOLANA_RPC_URL, commitment: 'confirmed' });
	const program = await resolveRingTokenProgram(connection, requirement);
	if (!program.ok) return { isValid: false, invalidReason: program.reason };
	const validation = validateRingTransaction({
		txBase64,
		requirement,
		feePayerPubkey: feePayerPubkey || (env.X402_FEE_PAYER_SOLANA || null),
		allowlist: payToAllowlist(),
		tokenProgramId: program.tokenProgramId,
	});
	if (!validation.ok) return { isValid: false, invalidReason: validation.reason };

	const sigCheck = verifyBuyerSignatures(validation.decoded);
	if (!sigCheck.ok) return { isValid: false, invalidReason: sigCheck.reason };
	// The settleability simulation swaps in a fresh blockhash, so it cannot see a
	// dead one. Refuse it here, before the paid handler runs.
	if ((await blockhashIsLive(connection, validation.decoded.tx.message.recentBlockhash)) === false) {
		return { isValid: false, invalidReason: 'blockhash_expired' };
	}

	const settleable = await assertSettleable({
		tx: validation.decoded.tx,
		connection,
		requirement,
		decoded: validation.decoded,
	});
	if (!settleable.ok) return { isValid: false, invalidReason: settleable.reason };

	return {
		isValid: true,
		network: requirement.network,
		asset: validation.decoded.mint,
		payer: validation.decoded.payer,
	};
}

// A transaction can only be included while its blockhash is live (150 slots,
// ~60-90s). Past that a signature the ledger has never seen can never appear, so
// "not found" stops meaning "not yet" and starts meaning "dropped". Held well
// clear of the real limit so a lagging history index is never mistaken for a
// dropped payment.
export const SETTLEMENT_DROP_HORIZON_MS = 180_000;

// The reconcile pass's read: what does the chain say about a signature we
// broadcast and never confirmed?
//
// Strictly read-only: it never signs, re-sends, or touches a wallet. Returns
// the state the pending row should take:
//   'confirmed': landed, no error. feeLamports carries the real fee when the
//                 parsed transaction is available, so the burn meter records
//                 what was actually spent rather than the estimate.
//   'failed':    landed with an on-chain error.
//   'abandoned': no trace, and too old for its blockhash to still be valid.
//   'pending':   no trace yet, still inside the horizon, or the RPC could not
//                 answer. Ask again next pass.
export async function probeSettlementSignature({ conn, signature, broadcastAtMs }) {
	const connection =
		conn || solanaConnection({ url: env.SOLANA_RPC_URL, commitment: 'confirmed' });
	let status;
	try {
		status = (
			await connection.getSignatureStatuses([signature], { searchTransactionHistory: true })
		)?.value?.[0];
	} catch (err) {
		return { state: 'pending', error: `probe_rpc_failed:${String(err?.message || err).slice(0, 160)}` };
	}

	if (status && status.err) {
		return { state: 'failed', error: JSON.stringify(status.err).slice(0, 400) };
	}
	if (status && !status.err) {
		let feeLamports = null;
		try {
			const parsed = await connection.getParsedTransaction(signature, {
				maxSupportedTransactionVersion: 1,
				commitment: 'confirmed',
			});
			if (parsed?.meta?.fee != null) feeLamports = parsed.meta.fee;
		} catch { /* the stored estimate stands */ }
		return { state: 'confirmed', feeLamports };
	}

	const ageMs = broadcastAtMs ? Date.now() - broadcastAtMs : 0;
	if (ageMs > SETTLEMENT_DROP_HORIZON_MS) {
		return { state: 'abandoned', error: `not_found_after_${Math.round(ageMs / 1000)}s` };
	}
	return { state: 'pending', error: 'not_found_yet' };
}