Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

16.9 KB
Raw Blame
// api/_lib/x402/wallet-fee-meter.js
//
// I/O side of the wallet fee governor (wallet-fee-governor.js holds the pure
// math). Builds the `feeMeter` hook the facilitator handler passes into
// settleRingPayment(): before co-signing/broadcasting, the settle path asks
// this meter whether the fee-paying wallet still has daily fee budget left.
//
// Scope: ONLY platform-controlled wallets (ringAllowedAddresses) are governed.
// An external organic buyer self-paying through our facilitator spends its own
// SOL — refusing its settle would be refusing revenue, so unknown wallets are
// always admitted. The same holds for an organic buyer in SPONSOR mode: the fee
// wallet is ours and governed, but the payment is a customer's. The daily budget
// exists to pace our own autonomous traffic, and on 2026-09-21 it refused a
// visitor's $THREE cover charge at the Club door with `fee_runway_exhausted`
// because the ring had already spent the morning's slice. A buyer who is not a
// platform wallet is therefore admitted past the budget (their fee is still
// recorded against it, so our own traffic yields to them, not the reverse).
// Every failure mode in here fails OPEN: the settle path's hard SOL floor
// remains the real protection; the meter is pacing.
//
// Spent-today reads sum `x402_self_facilitator_log.fee_lamports` per fee_payer
// (migration 20260728120000) with a short in-process cache, and each settled
// fee is debited into the cache optimistically so a burst inside one cache
// window still counts against the budget on this instance.

import { PublicKey } from '@solana/web3.js';
import { sql } from '../db.js';
import { env } from '../env.js';
import { solanaConnection } from '../solana/connection.js';
import { sendOpsAlert } from '../alerts.js';
import { ringAllowedAddresses } from './ring-allowlist.js';
import { SPONSOR_SOL_FLOOR_LAMPORTS, sponsorSolLamports } from './self-facilitator.js';
import {
	walletFeeGovernorConfig,
	walletDailyFeeBudgetLamports,
	assessWalletFeeBudget,
	admissibleSettleCount,
	pacedFeeBudgetLamports,
	utcDayElapsedFraction,
} from './wallet-fee-governor.js';

// Controlled-wallet set, cached. ringAllowedAddresses() walks env + DB + the
// signer registry; once a minute is plenty for a membership check.
const ALLOWLIST_TTL_MS = 60_000;
let _allowCache = { set: null, at: 0 };

async function governedWallets(now = Date.now()) {
	if (_allowCache.set && now - _allowCache.at < ALLOWLIST_TTL_MS) return _allowCache.set;
	try {
		const set = await ringAllowedAddresses();
		_allowCache = { set, at: now };
		return set;
	} catch {
		// Unreachable set → govern nothing this window (fail open), but keep any
		// previous set so a DB blip does not un-govern a hot wallet mid-storm.
		return _allowCache.set;
	}
}

// Per-wallet spent-today cache: pubkeyB58 → { lamports, day, at }.
const _spentCache = new Map();

function utcDay(now = Date.now()) {
	return new Date(now).toISOString().slice(0, 10);
}

async function spentTodayLamports(pubkeyB58, cacheMs, now = Date.now()) {
	const hit = _spentCache.get(pubkeyB58);
	if (hit && hit.day === utcDay(now) && now - hit.at < cacheMs) return hit.lamports;
	try {
		const rows = await sql`
			SELECT COALESCE(SUM(fee_lamports), 0)::bigint AS spent
			FROM x402_self_facilitator_log
			WHERE action = 'settle' AND ok = true
			  AND fee_payer = ${pubkeyB58}
			  AND ts >= date_trunc('day', now())
		`;
		const spent = Number(rows?.[0]?.spent ?? 0);
		_spentCache.set(pubkeyB58, { lamports: spent, day: utcDay(now), at: now });
		return spent;
	} catch {
		// Ledger unreadable (or migration not applied yet) → unknown spend.
		// assessWalletFeeBudget treats non-finite as fail-open.
		return NaN;
	}
}

// Debit the cache right after a successful settle so concurrent settles inside
// one cache window see the budget shrinking without another DB round-trip.
export function recordSettledFee(pubkeyB58, feeLamports, now = Date.now()) {
	const lamports = Number(feeLamports);
	if (!pubkeyB58 || !Number.isFinite(lamports) || lamports <= 0) return;
	const hit = _spentCache.get(pubkeyB58);
	if (hit && hit.day === utcDay(now)) hit.lamports += lamports;
}

// Test seam: drop all cached state.
export function resetWalletFeeMeterCaches() {
	_allowCache = { set: null, at: 0 };
	_spentCache.clear();
	_admissionCache.clear();
	_admissionInflight.clear();
}

// ── Caller-side admission ───────────────────────────────────────────────────────
// The settle-path meter below runs at the LAST step of the x402 handshake. By the
// time it refuses, the caller has already probed the endpoint for its challenge,
// read the receiver ATA, built and signed a Solana transfer, and paid for a
// facilitator `verify`: which SIMULATES the transaction against an RPC node.
// Every one of those steps is wasted when the wallet's daily fee budget is
// already spent, because the settle is refused at the end regardless.
//
// Measured 2026-08-01: 85,264 of 90,041 daily settle attempts were refused with
// `fee_runway_exhausted`, each having already burned a simulation. That is the
// bulk of ~170k wasted RPC round-trips a day, and it is why the Solana lanes read
// 1/3 serving while the settle rate read 26%.
//
// assessFeeAdmission() answers the same question with the SAME pure math, before
// the caller spends anything, so an exhausted budget short-circuits one call
// instead of paying for a full handshake to be told no at the end. It changes no
// money: the settles it skips were never going to land. Total settled volume is
// still capped by the wallet's funded budget: this removes the waste around that
// cap, it does not raise it.
//
// Fails OPEN everywhere, exactly like the settle-path meter: an ungoverned
// wallet, an unreadable balance, or an unreadable ledger all admit. The settle
// path's meter and its hard SOL floor remain the real protection; a gate that
// refused calls it could not price would be a worse outage than the waste it
// prevents.

// A refusal is stable until a top-up or the UTC-midnight budget reset, so it may
// be cached far longer than an admission (which decays as settles land and spend
// the budget down). One minute collapses a storm while still letting a top-up
// reopen the rail promptly.
const ADMISSION_REFUSED_TTL_MS = 60_000;
// pubkeyB58 → { ok, reason, at, day, ttl, spent, budget, admitted }
const _admissionCache = new Map();
// pubkeyB58 → in-flight snapshot promise, so a burst of concurrent calls shares
// one balance read and one ledger read instead of each racing its own.
const _admissionInflight = new Map();

const ADMIT = { ok: true, reason: null };

// Why an admitted snapshot carries its headroom instead of a bare "yes".
//
// A cached admission used to mean "admit everything for the next spentCacheMs".
// Under intraday pacing the unlocked budget sits right at the spent line all day
// (the wallet earns one settle's worth of budget roughly every half minute), so
// every fresh read found room for exactly one settle and then admitted every call
// for twenty seconds. Measured on production 2026-09-24: about 230 settles an hour
// landed and about 1,700 an hour were refused by the settle-path meter with
// `fee_runway_exhausted`, one wallet, every hour of the day. Each refusal had
// already paid for an ATA read, a signature and a simulated verify, which is the
// exact waste this gate exists to remove.
//
// Each admission now spends its estimated fee out of the snapshot's headroom, with
// the same pure arithmetic the settle path runs, so one cache window admits only
// what the budget can actually fund. The first call past the headroom turns the
// snapshot into a refusal. It changes no money and no budget: the settles it holds
// back were going to be refused at the end of the handshake anyway.
function snapshotVerdict(entry, estFeeLamports, now) {
	if (!entry.ok) return { ok: false, reason: entry.reason };
	const verdict = assessWalletFeeBudget({
		spentTodayLamports: entry.spent + entry.admitted,
		budgetLamports: entry.budget,
		nextFeeLamports: estFeeLamports,
	});
	if (verdict.ok) {
		entry.admitted += Math.max(0, Number(estFeeLamports) || 0);
		return verdict;
	}
	entry.ok = false;
	entry.reason = verdict.reason;
	entry.at = now;
	entry.ttl = ADMISSION_REFUSED_TTL_MS;
	return verdict;
}

async function readAdmissionSnapshot({ feeWalletB58, connection, cfg, now, day }) {
	let solLamports;
	try {
		const conn = connection || solanaConnection({ url: env.SOLANA_RPC_URL, commitment: 'confirmed' });
		// Shares self-facilitator.js's balance cache, so this adds no RPC traffic of
		// its own beyond what the settle path already reads for the same wallet.
		solLamports = await sponsorSolLamports(conn, new PublicKey(feeWalletB58), now);
	} catch {
		return null;
	}
	const spent = await spentTodayLamports(feeWalletB58, cfg.spentCacheMs, now);
	const budget = effectiveBudgetLamports(solLamports, cfg, now);
	const entry = { ok: true, reason: null, at: now, day, ttl: cfg.spentCacheMs, spent, budget, admitted: 0 };
	_admissionCache.set(feeWalletB58, entry);
	return entry;
}

// The snapshot every admission decision is made against: the cached one while it
// is fresh and from today, otherwise one shared balance + ledger read. Resolves
// `{ entry: null }` for every fail-open case (ungoverned wallet, unreadable
// allowlist, unreadable balance), so callers admit without pricing anything.
async function admissionSnapshot({ feeWalletB58, connection, cfg, now }) {
	// Never serve a verdict across a UTC day boundary: the budget resets at
	// midnight and a stale refusal would hold the rail shut into the new day.
	const day = utcDay(now);
	const hit = _admissionCache.get(feeWalletB58);
	if (hit && hit.day === day && now - hit.at < hit.ttl) return { entry: hit, cached: true, hit: true };

	// Only platform-controlled wallets are governed. An external buyer self-paying
	// through our facilitator spends its own SOL; refusing it would refuse revenue.
	let allowed;
	try {
		allowed = await governedWallets(now);
	} catch {
		return { entry: null };
	}
	if (!allowed || !allowed.has(feeWalletB58)) return { entry: null };

	let pending = _admissionInflight.get(feeWalletB58);
	const leader = !pending;
	if (leader) {
		pending = readAdmissionSnapshot({ feeWalletB58, connection, cfg, now, day })
			.finally(() => _admissionInflight.delete(feeWalletB58));
		_admissionInflight.set(feeWalletB58, pending);
	}
	// A null entry is an unreadable balance: fail open, like the settle-path meter.
	return { entry: await pending, cached: !leader, hit: false };
}

export async function assessFeeAdmission({
	feeWalletB58, estFeeLamports = 0, connection = null, config, now = Date.now(),
} = {}) {
	const cfg = config || walletFeeGovernorConfig();
	if (!cfg.enabled || !feeWalletB58) return ADMIT;

	const { entry, cached, hit } = await admissionSnapshot({ feeWalletB58, connection, cfg, now });
	if (!entry) return ADMIT;

	const verdict = snapshotVerdict(entry, estFeeLamports, now);
	if (hit) return { ok: verdict.ok, reason: verdict.reason, cached: true };
	return {
		ok: verdict.ok,
		reason: verdict.reason,
		budgetLamports: entry.budget,
		spentTodayLamports: entry.spent,
		cached,
	};
}

// Batch twin of assessFeeAdmission(): how many of `count` settles, each costing
// up to `estFeeLamports`, may this caller start right now?
//
// Why a batch caller cannot just loop over assessFeeAdmission(): it has no way to
// say "only spend what is left over". The x402 seed cron exists to keep the
// activity feed moving, not to buy anything, so it must YIELD the fee wallet's
// budget to the pipelines that pay for real data. Measured on production
// 2026-09-29: the seeder fired 60 sponsor-mode tips every two minutes, landed
// about 720 settles a day, and in doing so spent the sponsor's paced budget out
// from under the health, oracle, volume, sniper and feed pipelines, which the
// caller-side gate then skipped about 7,400 times a day. `keepLamports` is the
// headroom this caller leaves untouched for everyone else.
//
// Admitted fees are debited from the shared snapshot exactly like single
// admissions, so other callers on this instance see the budget shrink at once.
// When the budget cannot fund even one settle regardless of `keepLamports`, the
// snapshot turns into the same cached refusal assessFeeAdmission() would record.
// Fails OPEN on every unreadable input (returns `count`), same contract as the
// single gate: the settle path's meter and SOL floor stay the real protection.
export async function reserveFeeAdmissions({
	feeWalletB58, estFeeLamports = 0, count = 1, keepLamports = 0,
	connection = null, config, now = Date.now(),
} = {}) {
	const want = Math.max(0, Math.floor(Number(count) || 0));
	const cfg = config || walletFeeGovernorConfig();
	if (!cfg.enabled || !feeWalletB58 || want === 0) {
		return { admitted: want, governed: false, reason: null };
	}

	const { entry } = await admissionSnapshot({ feeWalletB58, connection, cfg, now });
	if (!entry) return { admitted: want, governed: false, reason: null };

	const fee = Math.max(0, Number(estFeeLamports) || 0);
	const spent = entry.spent + entry.admitted;
	const base = {
		governed: true,
		budgetLamports: entry.budget,
		spentTodayLamports: spent,
		keepLamports: Math.max(0, Number(keepLamports) || 0),
	};
	if (!entry.ok) return { ...base, admitted: 0, reason: entry.reason };

	const admitted = admissibleSettleCount({
		spentTodayLamports: spent,
		budgetLamports: entry.budget,
		feeLamports: fee,
		keepLamports,
		max: want,
	});
	if (admitted > 0) {
		entry.admitted += admitted * fee;
		return { ...base, admitted, reason: null };
	}
	// Nothing fits. Distinguish "the budget is spent" (the same refusal every
	// caller should now see, so it is cached as one) from "the budget has room,
	// but only inside the headroom kept for other tenants" (not a refusal for
	// anyone else, so the snapshot stays admitting).
	const single = snapshotVerdict(entry, fee, now);
	if (single.ok) {
		// snapshotVerdict debited one fee for a settle this caller is not starting.
		entry.admitted -= fee;
		return {
			...base,
			admitted: 0,
			reason: `fee_budget_kept_for_paid_calls:${spent}+${fee}>${entry.budget}-${base.keepLamports}`,
		};
	}
	return { ...base, admitted: 0, reason: single.reason };
}

// Single source of truth for "what fee budget applies to this wallet right now".
// The caller-side admission gate and the settle-path meter MUST answer that
// question identically: a laxer admission re-creates the wasted handshakes the
// gate exists to remove, and a stricter one skips settles the rail could fund.
// Routing both through one function makes divergence impossible rather than
// merely unlikely.
//
// `daily` is what the wallet may burn across the whole UTC day. Pacing returns
// how much of that has been unlocked so far, so the allowance is spread over the
// day instead of being drainable in a morning burst. Same total per day, steadier
// rail, and no wallet gets one extra lamport out of it.
function effectiveBudgetLamports(solLamports, cfg, now = Date.now()) {
	const daily = walletDailyFeeBudgetLamports({
		solLamports,
		floorLamports: SPONSOR_SOL_FLOOR_LAMPORTS,
		runwayDays: cfg.runwayDays,
		minBudgetLamports: cfg.minBudgetLamports,
	});
	if (!cfg.paceDay) return daily;
	return pacedFeeBudgetLamports({
		budgetLamports: daily,
		dayElapsedFraction: utcDayElapsedFraction(now),
		minSliceLamports: cfg.paceMinSliceLamports,
	});
}

// Build the settle-path hook. Returns null when the governor is disabled so
// settleRingPayment skips the metering branch entirely.
export function facilitatorFeeMeter({ config } = {}) {
	const cfg = config || walletFeeGovernorConfig();
	if (!cfg.enabled) return null;
	return async ({ feeWalletB58, solLamports, estFeeLamports, buyerB58 = null }) => {
		const allowed = await governedWallets();
		if (!allowed || !allowed.has(feeWalletB58)) return { ok: true, reason: null };
		// A known buyer outside the platform's own wallets is a paying customer:
		// never pace revenue. An unknown buyer stays governed, so a caller that
		// does not say who is paying cannot use this to skip the budget.
		if (buyerB58 && !allowed.has(buyerB58)) return { ok: true, reason: null, organic: true };

		const spent = await spentTodayLamports(feeWalletB58, cfg.spentCacheMs);
		const budget = effectiveBudgetLamports(solLamports, cfg);
		const verdict = assessWalletFeeBudget({
			spentTodayLamports: spent,
			budgetLamports: budget,
			nextFeeLamports: estFeeLamports,
		});
		if (!verdict.ok) {
			// One throttled alert per wallet per dedup window — the refusal itself
			// recurs every settle attempt until midnight UTC or a top-up, and that
			// is by design (governed throttle, not an outage).
			await sendOpsAlert(
				'x402 wallet fee governor throttling settles',
				`wallet ${feeWalletB58} spent ${spent} of ${budget} lamports today; `
					+ 'paced until UTC midnight or a SOL top-up. Governed throttle, not an outage — '
					+ 'see docs/x402-ring-economy.md "The wallet fee governor".',
				{ signature: `wallet-fee-governor:${feeWalletB58}`, severity: 'warn' },
			).catch(() => {});
		}
		return verdict;
	};
}