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/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;
};
}