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
// Master → agent SOL funding for the autonomous coin launcher.
//
// The launcher never lets the master wallet mint a coin directly — that would
// detach the coin from an avatar identity. Instead the master ('coin-launcher-
// master' in SOLANA_SIGNERS) tops up the NEXT agent in the rotation with exactly
// the per-launch SOL it needs (deploy cost + dev-buy), and that agent signs its
// own pump.fun create. This module is the money-moving half of that handshake:
//
// loadMasterSigner() — the master Keypair (or null if unconfigured).
// masterBalanceSol() — current master SOL, for the circuit breaker.
// dailySpentSol(scope,uid) — SOL already spent today (enforces daily_sol_cap).
// fundAgentForLaunch(...) — the guarded transfer: caps, balance, send.
//
// Every transfer routes through sendSol → submitProtected, so it inherits the
// data-driven priority fee, blockhash-refresh rebroadcast, and hard-throw-on-
// revert behaviour — a fund step never drops silently under congestion.
import { sql } from './db.js';
import { decodeSecretKey } from './solana-signers.js';
import { sendSol, getSolBalance } from './avatar-wallet.js';
import { solanaConnection } from './agent-pumpfun.js';
const LAMPORTS_PER_SOL = 1_000_000_000;
// The master signer reuses the dedicated launcher env, falling back to the
// existing x402-launcher wallet so the feature works on current infra. Kept in
// sync with the 'coin-launcher-master' SignerSpec in solana-signers.js.
const MASTER_ENV = 'LAUNCHER_MASTER_SECRET_KEY_B64';
const MASTER_FALLBACK_ENV = 'PUMP_X402_LAUNCHER_SECRET_KEY_B64';
// SOL the master must still hold AFTER any funding transfer.
//
// This wallet is not only the launcher/sniper funding root: the same keypair is
// the x402 ring payer (it resolves to one pubkey through both SignerSpecs, which
// is why treasury-topup reports it as "coin-launcher-master+x402-ring-payer").
// In self-pay mode the facilitator hard-rejects a settle when the PAYER is under
// SPONSOR_SOL_FLOOR (0.02 SOL), so a funding transfer that left only transfer
// fees behind silently killed the entire paid-endpoint rail. That is exactly how
// the ring died on 2026-07-25 and again on 2026-07-26: the sniper auto-funder
// pulled arm top-ups until the shared wallet fell ~100 lamports under the floor,
// and every x402 settle 502'd while 3+ SOL sat idle in agent wallets.
//
// The floor is deliberately well above 0.02 so a burst of settles between two
// funding runs can never cross it. Override per-environment if the roles are
// ever split onto separate keypairs.
const DEFAULT_MASTER_RESERVE_SOL = 0.05;
export function masterReserveSol() {
const n = Number(process.env.LAUNCHER_MASTER_RESERVE_SOL);
return Number.isFinite(n) && n >= 0 ? n : DEFAULT_MASTER_RESERVE_SOL;
}
/**
* Load the master launch wallet keypair, or null when neither env is set.
* @returns {Promise<import('@solana/web3.js').Keypair|null>}
*/
export async function loadMasterSigner() {
const secret = process.env[MASTER_ENV] || process.env[MASTER_FALLBACK_ENV] || '';
if (!secret) return null;
const bytes = await decodeSecretKey(secret);
if (!bytes) {
throw Object.assign(new Error('coin-launcher-master secret did not decode'), { code: 'bad_signer' });
}
const { Keypair } = await import('@solana/web3.js');
return Keypair.fromSecretKey(bytes);
}
/**
* Current master wallet SOL balance. Null when the master is unconfigured.
* @param {'mainnet'|'devnet'} network
* @returns {Promise<number|null>}
*/
export async function masterBalanceSol(network = 'mainnet') {
const master = await loadMasterSigner();
if (!master) return null;
const conn = solanaConnection(network);
const { sol } = await getSolBalance(conn, master.publicKey);
return sol;
}
/**
* SOL the launcher has already committed today (UTC) for a scope. Sums runs that
* actually moved money (funded/launched/confirmed); dry-run + skipped rows don't
* count. Drives the daily_sol_cap ceiling.
* @param {'global'|'user'} scope
* @param {string|null} userId
* @returns {Promise<number>}
*/
export async function dailySpentSol(scope, userId = null) {
const [row] = await sql`
select coalesce(sum(sol_spent), 0)::float8 as spent
from launcher_runs
where scope = ${scope}
and ${scope === 'user' ? sql`user_id = ${userId}` : sql`true`}
and status in ('funded', 'launched', 'confirmed')
and created_at >= date_trunc('day', now())
`;
return Number(row?.spent || 0);
}
// Optional hard ceiling on how much SOL may leave the master wallet PER UTC DAY,
// summed across every automated funder — enforced inside fundAgentForLaunch
// regardless of the per-call caps a caller passes. This is the backstop that a
// caller passing `dailyCapSol: null` (or a runaway loop) can't bypass. Opt-in:
// unset ⇒ no master cap (legacy behaviour). Set LAUNCHER_MASTER_DAILY_CAP_SOL to
// bound total master outflow.
const MASTER_DAILY_CAP_ENV = 'LAUNCHER_MASTER_DAILY_CAP_SOL';
/**
* Pure cap check — extracted so the arithmetic is unit-testable. `capSol<=0`
* (or non-finite) means "no cap".
* @param {number} spentSol SOL already moved from the master today
* @param {number} amountSol the transfer about to be made
* @param {number} capSol the daily ceiling
* @returns {{ ok: boolean, reason?: string }}
*/
export function withinMasterDailyCap(spentSol, amountSol, capSol) {
if (!Number.isFinite(capSol) || capSol <= 0) return { ok: true };
if (spentSol + amountSol > capSol + 1e-9) {
return { ok: false, reason: `master_daily_cap: ${spentSol.toFixed(4)}+${amountSol} SOL > ${capSol} SOL/day` };
}
return { ok: true };
}
/**
* SOL that has left the master wallet today (UTC) via the app's automated
* funders. Sums the two known on-chain ledgers — launcher runs and sniper
* wallet top-ups — and FAILS OPEN per-source (a missing table in some env
* contributes 0 rather than throwing), so this can never break a funding call.
* @param {'mainnet'|'devnet'} network
* @returns {Promise<number>}
*/
export async function masterDailyOutflowSol(network = 'mainnet') {
let total = 0;
try {
const [r] = await sql`
select coalesce(sum(sol_spent), 0)::float8 as s from launcher_runs
where status in ('funded', 'launched', 'confirmed')
and created_at >= date_trunc('day', now())
`;
total += Number(r?.s || 0);
} catch { /* launcher_runs absent in this env — fail open on this source */ }
try {
const [r] = await sql`
select coalesce(sum(lamports), 0)::float8 / 1e9 as s from sniper_funding_events
where mode = 'live' and network = ${network}
and created_at >= date_trunc('day', now())
`;
total += Number(r?.s || 0);
} catch { /* sniper_funding_events absent in this env — fail open on this source */ }
return total;
}
/**
* @typedef {Object} FundResult
* @property {boolean} ok
* @property {string} [signature] the funding transfer signature
* @property {number} [lamports] lamports moved
* @property {string} [reason] why the fund was refused (when ok=false)
*/
/**
* Guarded master → agent SOL top-up for one launch. Refuses (never throws for a
* business-rule stop) when a cap would be breached or the master can't cover it,
* so the engine can record a clean 'skipped' run and trip the breaker. Only a
* genuine on-chain/RPC failure throws.
*
* @param {Object} p
* @param {string} p.agentAddress recipient agent Solana pubkey (base58)
* @param {number} p.sol SOL to move (per_launch_sol)
* @param {number} p.perLaunchCapSol hard ceiling for a single launch
* @param {number} p.dailyCapSol remaining daily allowance already computed by caller
* @param {'mainnet'|'devnet'} [p.network]
* @param {string} [p.memo]
* @returns {Promise<FundResult>}
*/
export async function fundAgentForLaunch({
agentAddress,
sol,
perLaunchCapSol,
dailyCapSol,
network = 'mainnet',
memo = 'three.ws launcher',
}) {
const amount = Number(sol);
if (!Number.isFinite(amount) || amount <= 0) {
return { ok: false, reason: 'per_launch_sol must be positive' };
}
if (perLaunchCapSol > 0 && amount > perLaunchCapSol) {
return { ok: false, reason: `per-launch ${amount} SOL exceeds cap ${perLaunchCapSol}` };
}
if (dailyCapSol != null && amount > dailyCapSol) {
return { ok: false, reason: `daily SOL cap reached (${dailyCapSol} remaining)` };
}
// Hard master-wide daily outflow ceiling — independent of the caller's caps, so
// a null/loose per-call cap can't drain the master. Opt-in via env; no-op unset.
const masterCapSol = Number(process.env[MASTER_DAILY_CAP_ENV]);
if (Number.isFinite(masterCapSol) && masterCapSol > 0) {
const outflow = await masterDailyOutflowSol(network);
const capCheck = withinMasterDailyCap(outflow, amount, masterCapSol);
if (!capCheck.ok) return { ok: false, reason: capCheck.reason };
}
const master = await loadMasterSigner();
if (!master) return { ok: false, reason: 'master launch wallet not configured' };
const conn = solanaConnection(network);
// Keep a fee buffer AND the shared-wallet operating reserve, so the master
// never empties below the cost of this transfer plus the SOL its other role
// (x402 ring payer) needs to keep settling. See masterReserveSol().
const reserve = masterReserveSol();
const { sol: masterSol } = await getSolBalance(conn, master.publicKey);
if (masterSol < amount + 0.002 + reserve) {
return {
ok: false,
reason: `master balance ${masterSol} SOL below ${amount} + fees + ${reserve} reserve`,
};
}
const lamports = Math.round(amount * LAMPORTS_PER_SOL);
const signature = await sendSol({
connection: conn,
fromKeypair: master,
to: agentAddress,
lamports,
memo,
network,
});
return { ok: true, signature, lamports };
}
export { LAMPORTS_PER_SOL };