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.

fix(x402): let the treasury pay its own sweep fee when the sponsor is dry

nirholasa9c996e72fc8
diff --git a/api/_lib/x402/pipelines/ring-rebalance.js b/api/_lib/x402/pipelines/ring-rebalance.js
index 345789f47..6557b5700 100644
--- a/api/_lib/x402/pipelines/ring-rebalance.js
+++ b/api/_lib/x402/pipelines/ring-rebalance.js
@@ -11,10 +11,10 @@
//
// Every transfer is between platform-controlled wallets only (treasury → payer).
// The sponsor (X402_FEE_PAYER_SECRET_BASE58) pays the Solana fee so all SOL burn
-// stays on ONE monitored wallet; if the sponsor key is absent the treasury
-// self-pays. Recorded in x402_ring_ledger (kind='sweep'). It moves OUR money in a
-// circle — it is NOT spend, so it returns amountAtomic:0 and never consumes the
-// autonomous loop's daily spend cap.
+// stays on ONE monitored wallet; if the sponsor key is absent, or the sponsor
+// is too poor to pay, the treasury self-pays. Recorded in x402_ring_ledger
+// (kind='sweep'). It moves OUR money in a circle: it is NOT spend, so it returns
+// amountAtomic:0 and never consumes the autonomous loop's daily spend cap.
//
// OFF unless X402_TREASURY_SECRET_BASE58 is set (the treasury signing key). Until
// then run() is a graceful no-op.
@@ -46,6 +46,40 @@ function loadKp(b58) {
return Keypair.fromSecretKey(raw);
}
+// A system account must keep this many lamports to stay rent-exempt; a fee
+// payer that would dip under it is refused by the chain with
+// InsufficientFundsForRent on account 0. FEE_HEADROOM covers the base fee plus
+// the priority fee these transfers set, with room for a few retries.
+export const RENT_EXEMPT_SYSTEM_LAMPORTS = 890_880;
+const FEE_HEADROOM_LAMPORTS = 50_000;
+
+/** Can a wallet holding `lamports` pay one more fee and stay rent-exempt? */
+export function canPayFee(lamports) {
+ return Number(lamports) >= RENT_EXEMPT_SYSTEM_LAMPORTS + FEE_HEADROOM_LAMPORTS;
+}
+
+/**
+ * Pick who pays the Solana fee: the sponsor when it can afford it, otherwise the
+ * wallet that is moving the money.
+ *
+ * Routing every fee through the sponsor keeps SOL burn on one monitored wallet,
+ * but with no balance check a dry sponsor turned into a total ring outage: from
+ * 2026-10-03 every sweep died with "insufficient funds for rent" on account 0
+ * while the treasury held SOL of its own and 2.587 USDC it could not move, so the
+ * payer starved and settles fell to 0%. An unreadable sponsor balance keeps the
+ * sponsor (the chain is the final judge, and an RPC blip must not shift fee burn
+ * onto other wallets); only a balance we can see is short moves the fee.
+ */
+export async function resolveFeePayer(conn, sponsorKp, fallbackKp) {
+ if (!sponsorKp || sponsorKp.publicKey.equals(fallbackKp.publicKey)) return fallbackKp;
+ const held = await conn.getBalance(sponsorKp.publicKey, 'confirmed').catch(() => null);
+ if (held != null && !canPayFee(held)) {
+ log.warn('sponsor_fee_unfunded', { sponsor: sponsorKp.publicKey.toBase58(), held, fallback: fallbackKp.publicKey.toBase58() });
+ return fallbackKp;
+ }
+ return sponsorKp;
+}
+
// Keep this much USDC in the treasury after a sweep (default 0 — sweep all).
const TREASURY_BUFFER_ATOMIC = BigInt(process.env.X402_RING_TREASURY_BUFFER_ATOMIC || 0);
// Don't bother sweeping dust — default $0.10 minimum. Env-tunable via
@@ -175,16 +209,18 @@ export async function run(ctx = {}) {
return { success: true, skipped: true, amountAtomic: 0, note: `below_min_sweep:${sweep}` };
}
- // Sponsor pays the fee so SOL burn stays on one wallet; else treasury self-pays.
- let feePayerKp = treasury;
+ // Sponsor pays the fee so SOL burn stays on one wallet; the treasury self-pays
+ // when the sponsor key is absent or the sponsor cannot afford the fee.
+ let sponsorKp = null;
const sponsorSecret = process.env.X402_FEE_PAYER_SECRET_BASE58;
if (sponsorSecret) {
try {
- feePayerKp = loadKp(sponsorSecret);
+ sponsorKp = loadKp(sponsorSecret);
} catch {
- feePayerKp = treasury;
+ sponsorKp = null;
}
}
+ const feePayerKp = await resolveFeePayer(conn, sponsorKp, treasury);
const payerAta = getAssociatedTokenAddressSync(mint, payerPub, false, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID);
const payerAtaInfo = await conn.getAccountInfo(payerAta).catch(() => null);
@@ -414,11 +450,14 @@ export async function floatTopUp(ctx = {}) {
const decimals = await mintDecimals(conn, mint);
const band = floatBand();
- // Sponsor pays fees when configured so SOL burn stays on one wallet.
+ // Sponsor pays fees when configured so SOL burn stays on one wallet. Checked
+ // once per run: a sponsor too poor to pay is dropped and each transfer's
+ // source wallet pays its own fee instead (see resolveFeePayer).
let sponsorKp = null;
if (process.env.X402_FEE_PAYER_SECRET_BASE58) {
try { sponsorKp = loadKp(process.env.X402_FEE_PAYER_SECRET_BASE58); } catch { sponsorKp = null; }
}
+ if (sponsorKp && (await resolveFeePayer(conn, sponsorKp, treasury)) !== sponsorKp) sponsorKp = null;
const moves = [];
const minMove = Math.max(0, Number(process.env.X402_RING_AGENT_MIN_FLOAT_MOVE_ATOMIC || 100_000)); // $0.10
diff --git a/tests/x402-ring-fee-payer.test.js b/tests/x402-ring-fee-payer.test.js
new file mode 100644
index 000000000..8d68a9fb5
--- /dev/null
+++ b/tests/x402-ring-fee-payer.test.js
@@ -0,0 +1,51 @@
+// Who pays the Solana fee on a ring sweep or float move. A dry sponsor used to
+// be asked to pay regardless, so every sweep failed with "insufficient funds for
+// rent" on account 0 and the ring stopped settling (2026-10-03). The source
+// wallet now pays its own fee whenever the sponsor visibly cannot.
+import { describe, it, expect, vi } from 'vitest';
+import { Keypair } from '@solana/web3.js';
+import {
+ canPayFee,
+ resolveFeePayer,
+ RENT_EXEMPT_SYSTEM_LAMPORTS,
+} from '../api/_lib/x402/pipelines/ring-rebalance.js';
+
+const sponsor = Keypair.generate();
+const treasury = Keypair.generate();
+const connWith = (getBalance) => ({ getBalance: vi.fn(getBalance) });
+
+describe('canPayFee', () => {
+ it('refuses a wallet at or under the rent-exempt minimum', () => {
+ expect(canPayFee(651_828)).toBe(false);
+ expect(canPayFee(RENT_EXEMPT_SYSTEM_LAMPORTS)).toBe(false);
+ });
+
+ it('accepts a wallet with room for the fee above rent', () => {
+ expect(canPayFee(2_000_000)).toBe(true);
+ });
+});
+
+describe('resolveFeePayer', () => {
+ it('keeps the sponsor when it can afford the fee', async () => {
+ const conn = connWith(async () => 5_000_000);
+ expect(await resolveFeePayer(conn, sponsor, treasury)).toBe(sponsor);
+ });
+
+ it('falls back to the moving wallet when the sponsor is below rent', async () => {
+ const conn = connWith(async () => 651_828);
+ expect(await resolveFeePayer(conn, sponsor, treasury)).toBe(treasury);
+ });
+
+ it('keeps the sponsor when its balance cannot be read', async () => {
+ const conn = connWith(async () => {
+ throw new Error('rpc down');
+ });
+ expect(await resolveFeePayer(conn, sponsor, treasury)).toBe(sponsor);
+ });
+
+ it('uses the fallback without an RPC call when no sponsor is configured', async () => {
+ const conn = connWith(async () => 0);
+ expect(await resolveFeePayer(conn, null, treasury)).toBe(treasury);
+ expect(conn.getBalance).not.toHaveBeenCalled();
+ });
+});