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
// @ts-check
// api/_lib/economy-sweepback.js
//
// The reverse of economy-master.js. Where the master tops engines UP, sweepback
// brings balances BACK: it walks every configured engine signer in the
// SOLANA_SIGNERS registry and returns SOL — and, where safe, SPL token
// balances — to the ONE economy master wallet. Together the two close the loop:
// master funds engines → engines do the work → surplus consolidates to master.
//
// Destination-locked by construction: the only recipient this module can pay is
// ECONOMY_MASTER_ADDRESS (a module constant, never a parameter). A caller —
// buggy, compromised, or confused — cannot point a sweep anywhere else, so
// consolidation can never become a leak.
//
// Two modes:
// • 'excess' (default, safe to schedule) — skim only SOL above each signer's
// operating float (the same refillTo the treasury-topup cron refills to, so
// the two never oscillate: topup lifts a signer TO its float, sweepback only
// takes what is ABOVE it). Token balances are swept only from signers that
// do not operationally hold tokens (`holdsTokens` in the registry protects
// e.g. the buyback wallet's USDC revenue).
// • 'drain' (explicit, on-demand) — full consolidation: every token balance
// transferred, every emptied token account closed (rent refunds straight to
// the master), then all SOL minus a small fee headroom. Leaves the engines
// unfunded until the next treasury-topup, so it is for decommission or
// emergency recovery, never a schedule.
import { SOLANA_SIGNERS, loadSignerKeypair } from './solana-signers.js';
import { ECONOMY_MASTER_ADDRESS } from './economy-master.js';
import { sendSol, LAMPORTS_PER_SOL } from './avatar-wallet.js';
import { submitProtected } from './execution-engine.js';
import { MIN_OPERATIONAL_WALLET_SOL } from './agent-trade-guards.js';
import { antiOscillationFloorSol } from './agent-funding-policy.js';
import {
PLATFORM_AGENT_OWNER_EMAIL,
PLATFORM_AGENT_EMAIL_SUFFIX,
isPlatformOwnedAgent,
} from './custodial-key-health.js';
// Same float the treasury-topup cron refills to — sweep only above it.
const DEFAULT_REFILL_MULTIPLE = 3;
function num(envName, dflt) {
const v = Number(process.env[envName]);
return Number.isFinite(v) && v >= 0 ? v : dflt;
}
/** Skip a SOL sweep smaller than this — moving dust costs more than it returns. */
export const MIN_SWEEP_SOL = num('ECONOMY_SWEEPBACK_MIN_SOL', 0.01);
/**
* Lamports a drained signer keeps: fees for its own sweep transactions PLUS the
* ~890,880-lamport rent-exempt minimum. The runtime rejects any transfer that
* leaves a system account above zero but below rent exemption
* (InsufficientFundsForRent), so a drain must leave at least this — 0.001 SOL —
* or the drain transaction itself would fail.
*/
export const DRAIN_HEADROOM_LAMPORTS = 1_000_000;
/** Most token accounts settled in one transaction (tx size + CU bound). */
const TOKEN_ACCOUNTS_PER_TX = 4;
/**
* Compute the guarded per-signer SOL sweep amounts. Pure — no RPC — so the plan
* is unit-testable and the cron can log it before touching a key.
*
* @param {Array<{name:string,pubkey:string,currentSol:number,floorSol:number}>} targets
* @param {{mode?:'excess'|'drain', minSweepSol?:number}} [opts]
* @returns {{ plan: Array<{name:string,pubkey:string,sol:number}>, skipped: Array<{name:string,reason:string}>, totalSol: number }}
*/
export function planSweepback(targets, opts = {}) {
const mode = opts.mode === 'drain' ? 'drain' : 'excess';
const minSweep = Number.isFinite(opts.minSweepSol) ? opts.minSweepSol : MIN_SWEEP_SOL;
const plan = [];
const skipped = [];
let total = 0;
for (const t of targets) {
const available =
mode === 'drain'
? round(t.currentSol - DRAIN_HEADROOM_LAMPORTS / LAMPORTS_PER_SOL)
: round(t.currentSol - t.floorSol);
if (available < minSweep) {
skipped.push({ name: t.name, reason: mode === 'drain' ? 'below_dust_threshold' : 'at_or_below_float' });
continue;
}
plan.push({ name: t.name, pubkey: t.pubkey, sol: available });
total = round(total + available);
}
return { plan, skipped, totalSol: total };
}
/**
* Sweep every non-zero SPL token balance a signer owns to the master's ATA,
* closing each emptied source account so its rent refund lands on the master
* too. Covers both the classic token program and Token-2022. Transactions are
* chunked and submitted through the fee-optimized engine (no Jito tip).
*
* @param {object} args
* @param {import('@solana/web3.js').Connection} args.connection
* @param {import('@solana/web3.js').Keypair} args.owner
* @param {'mainnet'|'devnet'} args.network
* @returns {Promise<{ swept: Array<{mint:string,amount:string,decimals:number,signature:string}>, failed: Array<{mint:string,reason:string}> }>}
*/
async function sweepTokenBalances({ connection, owner, network, dryRun = false }) {
const { PublicKey } = await import('@solana/web3.js');
const {
TOKEN_PROGRAM_ID,
TOKEN_2022_PROGRAM_ID,
getAssociatedTokenAddressSync,
createAssociatedTokenAccountIdempotentInstruction,
createTransferCheckedInstruction,
createCloseAccountInstruction,
} = await import('@solana/spl-token');
const master = new PublicKey(ECONOMY_MASTER_ADDRESS);
const swept = [];
const failed = [];
for (const programId of [TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID]) {
let accounts;
try {
({ value: accounts } = await connection.getParsedTokenAccountsByOwner(owner.publicKey, { programId }));
} catch (e) {
const msg = e?.message || '';
// web3.js validates jsonParsed responses with superstruct; some Token-2022
// accounts (extensions the installed lib can't model) make the WHOLE call
// throw "Expected the value to satisfy a union of `type | type`". That is a
// client-side parse limitation, not a sweep failure — our engines hold
// USDC + SOL, not Token-2022 — so degrade quietly rather than alerting on
// every run. A genuine RPC/network error still surfaces.
if (/satisfy a union|Expected the value|superstruct/i.test(msg)) {
console.warn('[sweepback] parsed token query unsupported for program', programId.toBase58(), '- skipping', msg);
continue;
}
failed.push({ mint: `program:${programId.toBase58()}`, reason: `rpc_error: ${msg}` });
continue;
}
const holdings = accounts
.map((a) => ({
address: a.pubkey,
mint: a.account.data.parsed?.info?.mint,
amount: BigInt(a.account.data.parsed?.info?.tokenAmount?.amount || '0'),
decimals: Number(a.account.data.parsed?.info?.tokenAmount?.decimals || 0),
}))
.filter((h) => h.mint && h.amount > 0n);
for (let i = 0; i < holdings.length; i += TOKEN_ACCOUNTS_PER_TX) {
const chunk = holdings.slice(i, i + TOKEN_ACCOUNTS_PER_TX);
if (dryRun) {
for (const h of chunk) {
swept.push({ mint: h.mint, amount: h.amount.toString(), decimals: h.decimals, signature: null, dryRun: true });
}
continue;
}
const instructions = [];
for (const h of chunk) {
const mint = new PublicKey(h.mint);
const masterAta = getAssociatedTokenAddressSync(mint, master, false, programId);
instructions.push(
createAssociatedTokenAccountIdempotentInstruction(owner.publicKey, masterAta, master, mint, programId),
createTransferCheckedInstruction(h.address, mint, masterAta, owner.publicKey, h.amount, h.decimals, [], programId),
// Rent refund straight to the master — the destination lock applies
// to every lamport this module moves, including reclaimed rent.
createCloseAccountInstruction(h.address, master, owner.publicKey, [], programId),
);
}
try {
const { signature } = await submitProtected({ network, connection, payer: owner, instructions });
for (const h of chunk) {
swept.push({ mint: h.mint, amount: h.amount.toString(), decimals: h.decimals, signature });
}
} catch (e) {
for (const h of chunk) failed.push({ mint: h.mint, reason: e?.message || 'send_failed' });
}
}
}
return { swept, failed };
}
/**
* Execute the consolidation sweep across every configured registry signer.
* Tokens first (their fees and rent refunds settle before the SOL read), then
* SOL per the mode's plan. Registry entries wired to the same physical wallet
* are swept once, with their guards merged conservatively (any-holds-tokens,
* highest float). Never throws for a business-rule stop.
*
* @param {object} args
* @param {import('@solana/web3.js').Connection} args.connection
* @param {'excess'|'drain'} [args.mode]
* @param {boolean} [args.includeTokens]
* @param {'mainnet'|'devnet'} [args.network]
* @param {boolean} [args.dryRun] plan only: same reads, same guards, no sends
* @returns {Promise<object>}
*/
export async function sweepBack({ connection, mode = 'excess', includeTokens = true, network = 'mainnet', dryRun = false }) {
const { PublicKey } = await import('@solana/web3.js');
const master = ECONOMY_MASTER_ADDRESS;
let masterSolBefore = null;
try {
masterSolBefore = round((await connection.getBalance(new PublicKey(master), 'confirmed')) / LAMPORTS_PER_SOL);
} catch {
/* balance context is best-effort; the sweep itself does not need it */
}
const sweptSol = [];
const sweptTokens = [];
const failed = [];
const skipped = [];
const readErrors = [];
// Several registry entries can be WIRED to the same physical wallet (fallback
// env vars, or the operator assigning multiple slots to one key). Sweeping is
// per-wallet, so resolve everything first and merge aliases conservatively:
// the wallet holds tokens if ANY of its slots does, and its float is the
// HIGHEST float any slot requires.
const wallets = new Map();
for (const spec of SOLANA_SIGNERS) {
if (spec.isMaster || spec.network === 'devnet') continue;
// Money held for third parties (unpaid Fee Bridge recipients) is not platform
// float: no mode, not even drain, may consolidate it.
if (spec.holdsUserFunds) {
skipped.push({ name: spec.name, reason: 'holds_user_funds' });
continue;
}
const { keypair, configured, decodeError } = await loadSignerKeypair(spec);
if (!configured) continue;
if (decodeError || !keypair) {
readErrors.push({ name: spec.name, reason: 'secret_decode_failed' });
continue;
}
const pubkey = keypair.publicKey.toBase58();
if (pubkey === master) {
skipped.push({ name: spec.name, reason: 'is_master' });
continue;
}
const floorSol = spec.refillTo ?? spec.minSol * DEFAULT_REFILL_MULTIPLE;
const existing = wallets.get(pubkey);
if (existing) {
existing.names.push(spec.name);
existing.holdsTokens = existing.holdsTokens || Boolean(spec.holdsTokens);
existing.floorSol = Math.max(existing.floorSol, floorSol);
} else {
wallets.set(pubkey, {
pubkey,
keypair,
names: [spec.name],
holdsTokens: Boolean(spec.holdsTokens),
floorSol,
});
}
}
for (const wallet of wallets.values()) {
const name = wallet.names.join('+');
// Tokens first. In excess mode a wallet that operationally holds tokens
// (buyback USDC, withdrawal SPL float, NFT collection) keeps them; a
// drain takes all.
if (includeTokens && (mode === 'drain' || !wallet.holdsTokens)) {
const tokens = await sweepTokenBalances({ connection, owner: wallet.keypair, network, dryRun });
for (const t of tokens.swept) sweptTokens.push({ name, pubkey: wallet.pubkey, ...t });
for (const f of tokens.failed) failed.push({ name, pubkey: wallet.pubkey, sol: null, reason: `token ${f.mint}: ${f.reason}` });
}
let currentSol;
try {
currentSol = round((await connection.getBalance(wallet.keypair.publicKey, 'confirmed')) / LAMPORTS_PER_SOL);
} catch (e) {
readErrors.push({ name, pubkey: wallet.pubkey, reason: `rpc_error: ${e?.message}` });
continue;
}
const { plan, skipped: planSkipped } = planSweepback(
[{ name, pubkey: wallet.pubkey, currentSol, floorSol: wallet.floorSol }],
{ mode },
);
skipped.push(...planSkipped);
for (const step of plan) {
if (dryRun) {
sweptSol.push({ name: step.name, pubkey: step.pubkey, sol: step.sol, signature: null, dryRun: true });
continue;
}
try {
const signature = await sendSol({
connection,
fromKeypair: wallet.keypair,
to: master,
lamports: Math.round(step.sol * LAMPORTS_PER_SOL),
memo: `three.ws sweepback ${name} → economy-master`,
network,
});
sweptSol.push({ name: step.name, pubkey: step.pubkey, sol: step.sol, signature });
} catch (e) {
failed.push({ name: step.name, pubkey: step.pubkey, sol: step.sol, reason: e?.message || 'send_failed' });
}
}
}
let masterSolAfter = null;
try {
masterSolAfter = round((await connection.getBalance(new PublicKey(master), 'confirmed')) / LAMPORTS_PER_SOL);
} catch {
/* best-effort */
}
return {
mode,
dryRun,
master,
masterSolBefore,
masterSolAfter,
sweptSol,
sweptTokens,
failed,
skipped,
readErrors,
receivedSol: round(sweptSol.reduce((s, f) => s + f.sol, 0)),
};
}
// Names that are the FEED SINK, not a reclaim source: pulling SOL out of the
// circulation treasury just to have the topup put it straight back is pure fee
// churn, so reclaim leaves it alone (topup funds it; reclaim feeds topup).
const RECLAIM_EXEMPT_NAMES = new Set(['circulation-treasury']);
/**
* Pure reclaim sizing (no RPC) so the anti-oscillation invariant is testable.
* Returns how much SOL to pull from an engine holding `currentSol` whose operating
* floor is `minSol`, leaving it at minSol PLUS a buffer so fee jitter can't drop it
* below minSol (which would make the topup re-fund it and reopen the ping-pong the
* design closes). Returns 0 when there is nothing worth moving.
*
* Invariant: currentSol - reclaimableSol(currentSol, minSol) >= minSol, always.
*
* @param {number} currentSol
* @param {number} minSol
* @param {number} [minSweep]
* @returns {number}
*/
export function reclaimableSol(currentSol, minSol, minSweep = MIN_SWEEP_SOL) {
const reclaimable = round(currentSol - reclaimKeepLineSol(minSol));
return reclaimable >= minSweep ? reclaimable : 0;
}
/**
* The balance a wallet is left holding: its operating floor PLUS the anti-oscillation
* buffer. Sizing (`reclaimableSol`) and reporting (`floorBlockedSkip`) both read it,
* so the number an operator is shown is by construction the number that blocked the
* sweep, and the two cannot drift apart the way a hand-written message would.
*
* @param {number} minSol
* @returns {number}
*/
export function reclaimKeepLineSol(minSol) {
const floor = Math.max(0, minSol);
return round(floor + Math.max(0.005, floor * 0.1));
}
/**
* Describe a wallet the reclaim leg will not draw from because its balance sits under
* its own keep line.
*
* The bare string `at_or_below_floor` is why this exists. It was the ONLY thing three
* consecutive triage sessions saw for every reclaim source, and it reads as "this
* wallet is empty" when it equally means "this wallet holds real SOL behind a floor
* somebody configured". Those are opposite operator situations: the first needs owner
* capital, the second needs a floor reviewed, and neither the settle-health hint nor
* the treasury-topup dry run could tell them apart. The x402 ring treasury held
* 0.055 SOL against a 0.1 SOL floor inherited from a role its own registry comment
* records as retired, and it printed exactly like the 110 genuinely-empty agent
* wallets beside it. Carrying the two numbers in the reason (the `<have><<need>`
* shape `below_swap_rent` already uses) makes that indistinguishable case impossible.
*
* @param {string} name
* @param {number} currentSol
* @param {number} minSol
* @returns {{name:string, reason:string, heldSol:number, keepSol:number, floorSol:number}}
*/
export function floorBlockedSkip(name, currentSol, minSol, minSweep = MIN_SWEEP_SOL) {
const heldSol = round(Math.max(0, currentSol));
const keepSol = reclaimKeepLineSol(minSol);
const floorSol = round(Math.max(0, minSol));
// A wallet ABOVE its keep line whose excess is under the minimum sweep is not at
// its floor; it holds dust the sweep declines to move. Printing it as
// `at_or_below_floor:0.0193<0.01` contradicted itself in one token, and on
// 2026-09-24 31 agent wallets read that way while holding 0.161 SOL of excess
// between them. The lever for that SOL is ECONOMY_SWEEPBACK_MIN_SOL, not a floor.
const excessSol = round(heldSol - keepSol);
if (excessSol > 0) {
return {
name,
reason: `below_min_sweep:${excessSol}<${round(minSweep)}`,
heldSol,
keepSol,
floorSol,
excessSol,
};
}
return {
name,
reason: `at_or_below_floor:${heldSol}<${keepSol}`,
heldSol,
keepSol,
floorSol,
};
}
/**
* Total SOL stranded on wallets the reclaim leg skipped for their own floor. A
* non-zero total is the signal that the fleet is not empty, it is fenced: capital
* exists on platform wallets and a floor decision, not an owner transfer, is what
* would release it.
*
* @param {Array<{heldSol?:number}>} skipped
* @returns {number}
*/
export function floorHeldSol(skipped) {
return round((skipped || []).reduce((sum, s) => sum + (Number(s?.heldSol) || 0), 0));
}
/**
* Emergency consolidation: pull IDLE SOL sitting above each engine's true
* operating floor (`minSol`, not the topup `refillTo`) back to the master, SOL
* only; token floats are never touched. This is the automated form of the manual
* "drain the fleet to refund the feed" recovery: when the funding root is starved,
* SOL trapped in over-provisioned engines (a launcher floored at 3 SOL that isn't
* launching, say) flows to where the Money Pulse needs it, on its own.
*
* Non-oscillating by construction: it leaves each engine at minSol PLUS a buffer,
* and the topup only ever funds engines strictly BELOW minSol, so a reclaimed
* engine is never immediately re-funded, and the two crons cannot ping-pong. The
* feed sink (circulation-treasury) is exempt. Destination is the same hard-locked
* ECONOMY_MASTER_ADDRESS constant as sweepBack; no parameter can redirect it.
*
* @param {object} args
* @param {import('@solana/web3.js').Connection} args.connection
* @param {'mainnet'|'devnet'} [args.network]
* @param {boolean} [args.dryRun]
* @returns {Promise<{master:string, reclaimedSol:number, moves:Array, skipped:Array, failed:Array, readErrors:Array}>}
*/
export async function reclaimIdleSol({ connection, network = 'mainnet', dryRun = false }) {
const master = ECONOMY_MASTER_ADDRESS;
const moves = [];
const failed = [];
const skipped = [];
const readErrors = [];
// Merge registry entries that resolve to the same physical wallet. Keep the
// HIGHEST minSol among a wallet's roles so we never leave it under any role's
// operating floor, and treat the wallet as exempt if ANY of its roles is.
const wallets = new Map();
for (const spec of SOLANA_SIGNERS) {
if (spec.isMaster || spec.network === 'devnet') continue;
// Money held for third parties (unpaid Fee Bridge recipients) is not platform
// float: no mode, not even drain, may consolidate it.
if (spec.holdsUserFunds) {
skipped.push({ name: spec.name, reason: 'holds_user_funds' });
continue;
}
const { keypair, configured, decodeError } = await loadSignerKeypair(spec);
if (!configured) continue;
if (decodeError || !keypair) {
readErrors.push({ name: spec.name, reason: 'secret_decode_failed' });
continue;
}
const pubkey = keypair.publicKey.toBase58();
if (pubkey === master) continue;
const exempt = RECLAIM_EXEMPT_NAMES.has(spec.name);
const existing = wallets.get(pubkey);
if (existing) {
existing.names.push(spec.name);
existing.minSol = Math.max(existing.minSol, spec.minSol || 0);
existing.exempt = existing.exempt || exempt;
} else {
wallets.set(pubkey, { pubkey, keypair, names: [spec.name], minSol: spec.minSol || 0, exempt });
}
}
for (const w of wallets.values()) {
const name = w.names.join('+');
if (w.exempt) {
skipped.push({ name, reason: 'feed_sink_exempt' });
continue;
}
let currentSol;
try {
currentSol = round((await connection.getBalance(w.keypair.publicKey, 'confirmed')) / LAMPORTS_PER_SOL);
} catch (e) {
readErrors.push({ name, pubkey: w.pubkey, reason: `rpc_error: ${e?.message}` });
continue;
}
// Leave the engine its floor plus a comfortable buffer (see reclaimableSol)
// so the topup never re-funds a reclaimed engine and the two cannot ping-pong.
const reclaimable = reclaimableSol(currentSol, w.minSol);
if (reclaimable <= 0) {
skipped.push({ ...floorBlockedSkip(name, currentSol, w.minSol), pubkey: w.pubkey });
continue;
}
if (dryRun) {
moves.push({ name, pubkey: w.pubkey, sol: reclaimable, dryRun: true });
continue;
}
try {
const signature = await sendSol({
connection,
fromKeypair: w.keypair,
to: master,
lamports: Math.round(reclaimable * LAMPORTS_PER_SOL),
memo: `three.ws reclaim ${name} → economy-master`,
network,
});
moves.push({ name, pubkey: w.pubkey, sol: reclaimable, signature });
} catch (e) {
failed.push({ name, pubkey: w.pubkey, sol: reclaimable, reason: e?.message || 'send_failed' });
}
}
return {
master,
reclaimedSol: round(moves.reduce((s, m) => s + m.sol, 0)),
floorHeldSol: floorHeldSol(skipped),
moves,
skipped,
failed,
readErrors,
};
}
// ── platform AGENT wallet reclaim ────────────────────────────────────────────
//
// reclaimIdleSol above walks the SOLANA_SIGNERS registry — the eight engine
// wallets. Agent custody wallets are a different universe and were structurally
// invisible to every return path: `fundAgentForLaunch` moves SOL master → agent
// one way, and nothing ever moved it back. Snipes recycle ~97% of their capital
// but the proceeds land in the AGENT wallet, so each cycle ratcheted SOL further
// from the engines until the master could not pay a 5,036-lamport settle fee.
// Audited 2026-07-28: 7.2 of the fleet's 7.53 SOL sat in agent wallets while the
// engines held 0.31 and the whole x402 rail 503'd. This closes that loop.
//
// The ownership boundary is the load-bearing part. Only wallets belonging to
// PLATFORM-OWNED agents may be swept — the `three-ws` house account and the
// `*@agents.three.ws` circulation bots, which api/_lib/launcher-engine.js
// documents as "platform-created bot accounts … never real end users". A
// customer's agent is never touched, and the SQL gate plus a redundant in-JS
// re-check make that true even if the query is later edited.
// One definition, shared with the custodial key-health audit: two copies of this
// boundary drifted apart once already (the audit carried a different house-account
// address and filed 12 platform wallets as customer ones).
export { PLATFORM_AGENT_OWNER_EMAIL, PLATFORM_AGENT_EMAIL_SUFFIX, isPlatformOwnedAgent };
/** Floor left on an idle platform agent — enough to sign its own transactions. */
const AGENT_IDLE_FLOOR_SOL = num('AGENT_RECLAIM_IDLE_FLOOR_SOL', 0.005);
/** A trading agent keeps this many trades' worth of working capital. */
const AGENT_ACTIVE_TRADE_MULTIPLE = num('AGENT_RECLAIM_TRADE_MULTIPLE', 2);
/** Wallets touched per run — keeps the cron bounded and its fee cost predictable. */
const AGENT_RECLAIM_MAX_WALLETS = num('AGENT_RECLAIM_MAX_WALLETS', 40);
/**
* Operating floor for one platform agent. An agent running an ENABLED sniper
* strategy keeps enough for `AGENT_RECLAIM_TRADE_MULTIPLE` trades at its own
* configured size, so reclaim can never starve a working trader; an agent with
* no enabled strategy keeps only transaction-fee headroom. Pure.
*
* @param {{enabled?:boolean, perTradeSol?:number}} strategy
* @returns {number} floor in SOL
*/
export function agentReclaimFloorSol(strategy = {}) {
// Anti-oscillation, and it outranks everything else here: a wallet the sniper
// auto-funder refills to a target must never be swept below that target, or the
// two crons chase the same SOL forever. Measured before this guard existed: 0.24
// SOL round-tripped six times between the funding master and two arms inside 15
// minutes, paying fees each leg, until the funding master ran dry. Applies even
// to a DISABLED strategy — the funder's opt-in flag, not `enabled`, is what
// decides whether a refill is coming.
const antiOscillation = antiOscillationFloorSol({ autoFundEnabled: strategy.autoFundEnabled });
if (!strategy.enabled) return round(Math.max(AGENT_IDLE_FLOOR_SOL, antiOscillation));
const perTrade = Number(strategy.perTradeSol);
// An ENABLED arm always keeps at least what one complete trade costs. Sizing the
// floor on `per_trade × 2` alone ignored everything a buy needs BESIDES the buy
// — the token ATA's rent, the fee and tip headroom, and the round-trip probe the
// firewall simulates from this same wallet — so a small-size arm could be
// reclaimed down to 0.004 SOL and then abort every entry at a safety simulation
// it could no longer afford to run. Fully funded and operationally dead is the
// worst state to leave a trader in: it looks healthy on every dashboard.
const working = Number.isFinite(perTrade) && perTrade > 0
? perTrade * AGENT_ACTIVE_TRADE_MULTIPLE + MIN_OPERATIONAL_WALLET_SOL
: MIN_OPERATIONAL_WALLET_SOL;
return round(Math.max(AGENT_IDLE_FLOOR_SOL, working, antiOscillation));
}
/**
* Size the per-agent reclaim. Pure, so the safety invariants are unit-testable
* without a database or an RPC.
*
* Invariants:
* · a non-platform owner is NEVER planned, whatever the balance
* · an agent with committed capital (an open position) is never planned
* · a planned agent always retains at least its floor (via reclaimableSol)
*
* @param {Array<{agentId:string,name:string,address:string,owner:string,sol:number,openPositions?:number,strategy?:{enabled?:boolean,perTradeSol?:number}}>} candidates
* @param {{minSweepSol?:number, maxWallets?:number}} [opts]
* @returns {{plan:Array<{agentId:string,name:string,address:string,sol:number,floorSol:number}>, skipped:Array<{name:string,reason:string}>, totalSol:number}}
*/
export function planAgentReclaim(candidates, opts = {}) {
const minSweep = Number.isFinite(opts.minSweepSol) ? opts.minSweepSol : MIN_SWEEP_SOL;
const maxWallets = Number.isFinite(opts.maxWallets) ? opts.maxWallets : AGENT_RECLAIM_MAX_WALLETS;
const plan = [];
const skipped = [];
let total = 0;
for (const c of candidates) {
if (!isPlatformOwnedAgent(c.owner)) {
skipped.push({ name: c.name, reason: 'not_platform_owned' });
continue;
}
if (Number(c.openPositions) > 0) {
skipped.push({ name: c.name, reason: 'capital_committed' });
continue;
}
if (c.address === ECONOMY_MASTER_ADDRESS) {
skipped.push({ name: c.name, reason: 'is_master' });
continue;
}
const floorSol = agentReclaimFloorSol(c.strategy);
const reclaimable = reclaimableSol(c.sol, floorSol, minSweep);
if (reclaimable <= 0) {
skipped.push(floorBlockedSkip(c.name, c.sol, floorSol, minSweep));
continue;
}
if (plan.length >= maxWallets) {
skipped.push({ name: c.name, reason: 'run_cap_reached' });
continue;
}
plan.push({ agentId: c.agentId, name: c.name, address: c.address, sol: reclaimable, floorSol });
total = round(total + reclaimable);
}
return { plan, skipped, totalSol: total, floorHeldSol: floorHeldSol(skipped) };
}
/**
* Shape one `reclaimIdleAgentSol` SQL row into the candidate `planAgentReclaim`
* consumes. Pure, and exported for the same reason the planner is: every safety
* guard downstream reads a field that is set HERE, so a field this mapping fails
* to carry silently disables the guard that depends on it.
*
* That is not hypothetical. `strategy.autoFundEnabled` was missing here while
* `agentReclaimFloorSol()` already derived the anti-oscillation floor from it, so
* the floor read `undefined`, collapsed to 0, and the funder/reclaim ping-pong
* the guard exists to prevent ran in production against a green unit suite. The
* pure-function tests could not catch it because they built candidates by hand.
* Keep every guard-bearing field asserted in tests/economy-sweepback.test.js.
*
* @param {{agent_id:string, name?:string|null, address:string, owner:string, secret:string,
* open_positions?:number, strategy_enabled?:boolean|null,
* auto_fund_enabled?:boolean|null, per_trade_lamports?:number|string|null}} row
* @param {number} sol on-chain balance already read for this row
* @returns {{agentId:string,name:string,address:string,owner:string,secret:string,sol:number,
* openPositions:number,strategy:{enabled:boolean,autoFundEnabled:boolean,perTradeSol:number}}}
*/
export function agentCandidateFromRow(row, sol) {
return {
agentId: row.agent_id,
name: row.name || 'Agent',
address: row.address,
owner: row.owner,
secret: row.secret,
sol,
openPositions: Number(row.open_positions) || 0,
strategy: {
enabled: Boolean(row.strategy_enabled),
// The funder's opt-in flag, NOT `enabled` — a disabled strategy still gets
// refilled, so it still oscillates if swept below the funding target.
autoFundEnabled: row.auto_fund_enabled === true,
perTradeSol:
row.per_trade_lamports != null ? Number(row.per_trade_lamports) / LAMPORTS_PER_SOL : 0,
},
};
}
/**
* Pull idle SOL out of PLATFORM-OWNED agent custody wallets back to the economy
* master, so the fee wallet refills itself from capital the platform already owns
* instead of waiting on an external top-up. Destination is the same hard-locked
* ECONOMY_MASTER_ADDRESS constant every other sweep uses; no parameter redirects it.
*
* @param {object} args
* @param {import('@solana/web3.js').Connection} args.connection
* @param {'mainnet'|'devnet'} [args.network]
* @param {boolean} [args.dryRun]
* @param {number} [args.maxWallets]
* @returns {Promise<{master:string, reclaimedSol:number, moves:Array, skipped:Array, failed:Array, readErrors:Array}>}
*/
export async function reclaimIdleAgentSol({ connection, network = 'mainnet', dryRun = false, maxWallets } = {}) {
const { PublicKey } = await import('@solana/web3.js');
const { sql } = await import('./db.js');
const master = ECONOMY_MASTER_ADDRESS;
const moves = [];
const failed = [];
const readErrors = [];
// Ownership is enforced in SQL first so a customer's agent never even leaves
// the database, and again in planAgentReclaim() so an edit here cannot widen
// the blast radius on its own.
const rows = await sql`
SELECT a.id AS agent_id,
a.name AS name,
a.meta->>'solana_address' AS address,
a.meta->>'encrypted_solana_secret' AS secret,
LOWER(u.email) AS owner,
s.enabled AS strategy_enabled,
s.per_trade_lamports AS per_trade_lamports,
-- The funder's opt-in flag, not the enabled flag: it decides whether a
-- refill is coming, so it decides whether sweeping here would oscillate.
s.auto_fund_enabled AS auto_fund_enabled,
(SELECT COUNT(*) FROM agent_sniper_positions p
WHERE p.agent_id = a.id AND p.status IN ('open', 'closing'))::int AS open_positions
FROM agent_identities a
JOIN users u ON u.id = a.user_id
LEFT JOIN agent_sniper_strategies s ON s.agent_id = a.id AND s.network = ${network}
WHERE a.deleted_at IS NULL
AND a.meta->>'solana_address' IS NOT NULL
AND a.meta->>'encrypted_solana_secret' IS NOT NULL
AND (LOWER(u.email) = ${PLATFORM_AGENT_OWNER_EMAIL}
OR LOWER(u.email) LIKE ${'%' + PLATFORM_AGENT_EMAIL_SUFFIX})
`;
const candidates = [];
for (const r of rows) {
let sol;
try {
sol = round((await connection.getBalance(new PublicKey(r.address), 'confirmed')) / LAMPORTS_PER_SOL);
} catch (e) {
readErrors.push({ name: r.name, address: r.address, reason: `rpc_error: ${e?.message}` });
continue;
}
candidates.push(agentCandidateFromRow(r, sol));
}
// Biggest balances first: the run cap should spend its budget where the SOL is.
candidates.sort((a, b) => b.sol - a.sol);
const { plan, skipped } = planAgentReclaim(candidates, { maxWallets });
const secrets = new Map(candidates.map((c) => [c.agentId, c.secret]));
const { recoverSolanaAgentKeypair } = await import('./agent-wallet.js');
// Recovery and broadcast are reported SEPARATELY on purpose. Sharing one
// catch made an undecryptable wallet secret surface as a failed send, and
// the alert then read "N failed send(s): The operation failed for an
// operation-specific reason": a WebCrypto AES-GCM OperationError wearing
// a Solana costume. That sent operators after RPC health and funding for a
// key problem no amount of either could fix.
//
// The DRY run runs this same gate, which is the whole point of it being a
// function. It used to return the raw plan without ever touching a key, so a
// wallet whose secret is sealed under a retired WALLET_ENCRYPTION_KEY was
// advertised as reclaimable forever: `?dry=1` promised 0.12 SOL the real leg
// could never move, and two separate sessions read that plan and concluded
// the treasury cron would self-heal. A plan nothing can execute is worse than
// no plan, because it reads as capital on hand.
const openReclaimWallet = async (p, { audit }) => {
let keypair;
try {
// A plan-only read passes NO audit context: the real leg's decrypt is a
// custody event worth a row, a dry run every scheduler minute is not.
keypair = await recoverSolanaAgentKeypair(
secrets.get(p.agentId),
audit ? { agentId: p.agentId, reason: 'economy_reclaim', meta: { to: master, sol: p.sol } } : null,
);
} catch (e) {
failed.push({
name: p.name, address: p.address, sol: p.sol, stage: 'recover',
reason: `secret_undecryptable: ${e?.message || 'unknown'}`,
});
return null;
}
if (keypair.publicKey.toBase58() !== p.address) {
failed.push({ name: p.name, address: p.address, sol: p.sol, stage: 'recover', reason: 'keypair_address_mismatch' });
return null;
}
return keypair;
};
if (dryRun) {
for (const p of plan) {
if (await openReclaimWallet(p, { audit: false })) moves.push({ ...p, dryRun: true });
}
return { master, reclaimedSol: round(moves.reduce((s, m) => s + m.sol, 0)), floorHeldSol: floorHeldSol(skipped), moves, skipped, failed, readErrors };
}
for (const p of plan) {
const keypair = await openReclaimWallet(p, { audit: true });
if (!keypair) continue;
try {
const signature = await sendSol({
connection,
fromKeypair: keypair,
to: master,
lamports: Math.round(p.sol * LAMPORTS_PER_SOL),
memo: `three.ws reclaim ${p.name} → economy-master`,
network,
});
moves.push({ ...p, signature });
} catch (e) {
failed.push({ name: p.name, address: p.address, sol: p.sol, stage: 'send', reason: e?.message || 'send_failed' });
}
}
return {
master,
reclaimedSol: round(moves.reduce((s, m) => s + m.sol, 0)),
floorHeldSol: floorHeldSol(skipped),
moves,
skipped,
failed,
readErrors,
};
}
function round(n) {
return Math.round(n * 1e9) / 1e9;
}