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/fresh-workers/chain.js
//
// The on-chain legs of a fresh worker wallet's life, as small effectful helpers
// over the shared connection + read guards: fund a batch of new wallets in one
// transaction, read a wallet's SOL/USDC, and sweep a wallet back to the funders
// while closing its token account so the rent it borrowed goes home.
//
// Invariants: every recipient is a funder or a fresh wallet this lane minted;
// USDC only ever moves treasury -> fresh -> treasury; SOL only ever moves
// funder -> fresh -> funder. Nothing here touches a wallet it did not create.
import {
PublicKey, SystemProgram, TransactionMessage, VersionedTransaction, ComputeBudgetProgram,
} from '@solana/web3.js';
import {
getAssociatedTokenAddressSync,
createTransferCheckedInstruction,
createAssociatedTokenAccountIdempotentInstruction,
createCloseAccountInstruction,
TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID,
} from '@solana/spl-token';
import { env } from '../../env.js';
import { blockhashKey, getRecentBlockhashInfo, readAccountInfoOrNull } from '../../solana/read-guards.js';
import { tokenAmountFromAccountData } from '../pipelines/ring-pool-fund.js';
import { ATA_RENT_LAMPORTS, BASE_FEE_LAMPORTS, RENT_EXEMPT_FALLBACK_LAMPORTS, sweepAmountLamports } from './plan.js';
// Compute-unit ceiling for the funding tx (a handful of transfers + ATA creates)
// and the sweep (one transfer, one close, one system transfer). Generous but far
// below the 1.4M default, so a tiny priority price stays a tiny fee.
const FUND_CU_LIMIT = 200_000;
const SWEEP_CU_LIMIT = 60_000;
// Lowest nonzero priority the funding tx pays so it lands promptly under load.
const FUND_PRIORITY_MICROLAMPORTS = 5;
export function usdcAtaOf(owner, mint) {
return getAssociatedTokenAddressSync(mint, owner, false, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID);
}
let _rentExempt = { value: null, at: 0 };
/** Rent-exempt minimum for a 0-byte account, read once an hour; constant fallback when RPC is dark. */
export async function rentExemptLamports(conn, now = Date.now()) {
if (_rentExempt.value && now - _rentExempt.at < 3_600_000) return _rentExempt.value;
try {
const v = Number(await conn.getMinimumBalanceForRentExemption(0));
if (Number.isFinite(v) && v > 0) {
_rentExempt = { value: v, at: now };
return v;
}
} catch { /* fall through to the constant */ }
return _rentExempt.value || RENT_EXEMPT_FALLBACK_LAMPORTS;
}
export async function confirmSignature(conn, signature, timeoutMs = 30_000) {
const deadline = Date.now() + timeoutMs;
while (Date.now() < deadline) {
const st = await conn.getSignatureStatuses([signature]).catch(() => null);
const v = st?.value?.[0];
if (v?.err) return { confirmed: false, err: JSON.stringify(v.err) };
if (v && (v.confirmationStatus === 'confirmed' || v.confirmationStatus === 'finalized')) return { confirmed: true };
await new Promise((r) => setTimeout(r, 1200));
}
return { confirmed: false, err: 'timeout' };
}
async function sendIxs(conn, feePayer, signers, instructions, { confirmMs = 30_000 } = {}) {
const { blockhash } = await getRecentBlockhashInfo(conn, blockhashKey({ url: env.SOLANA_RPC_URL }), { forceFresh: true });
const msg = new TransactionMessage({ payerKey: feePayer.publicKey, recentBlockhash: blockhash, instructions }).compileToV0Message();
const vtx = new VersionedTransaction(msg);
vtx.sign(signers);
const signature = await conn.sendRawTransaction(vtx.serialize(), { skipPreflight: false, maxRetries: 5 });
const conf = await confirmSignature(conn, signature, confirmMs);
return { ok: conf.confirmed, signature, err: conf.confirmed ? null : conf.err };
}
/** SOL balance in lamports (0 for a never-seen account), or null when unreadable. */
// readAccountInfoOrNull({ withCause: true }) always resolves to { info, cause }:
// info === null with no cause is an account that does not exist, a cause is an
// RPC transport failure. Reading the wrapper itself as the account reported 0
// lamports for every wallet and kept the lane on funder_headroom forever.
export async function readSolLamports(conn, pubkey) {
const { info, cause } = await readAccountInfoOrNull(conn, pubkey, { commitment: 'confirmed', withCause: true });
if (cause) return null;
if (!info) return 0;
return Number(info.lamports || 0);
}
/** USDC held by an owner's ATA: { exists, atomic } or null when unreadable. */
export async function readUsdc(conn, ata) {
const { info, cause } = await readAccountInfoOrNull(conn, ata, { commitment: 'confirmed', withCause: true });
if (cause) return null;
if (!info) return { exists: false, atomic: 0n };
return { exists: true, atomic: tokenAmountFromAccountData(info.data) };
}
/**
* Fund every wallet in `targets` in ONE transaction: SOL from the funder, the
* wallet's USDC ATA created (rent paid by the funder), and the job's USDC moved
* from the treasury. Both funders sign; the treasury only as token authority.
* @param {{ conn, solFunder, treasury, mint, decimals, targets: Array<{ pubkey: PublicKey, ata: PublicKey, solLamports: number, usdcAtomic: bigint }> }} p
*/
export async function fundWallets({ conn, solFunder, treasury, mint, decimals, targets, confirmMs }) {
const treasuryAta = usdcAtaOf(treasury.publicKey, mint);
const ixs = [
ComputeBudgetProgram.setComputeUnitLimit({ units: FUND_CU_LIMIT }),
ComputeBudgetProgram.setComputeUnitPrice({ microLamports: FUND_PRIORITY_MICROLAMPORTS }),
];
for (const t of targets) {
ixs.push(SystemProgram.transfer({ fromPubkey: solFunder.publicKey, toPubkey: t.pubkey, lamports: t.solLamports }));
ixs.push(createAssociatedTokenAccountIdempotentInstruction(
solFunder.publicKey, t.ata, t.pubkey, mint, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID,
));
if (t.usdcAtomic > 0n) {
ixs.push(createTransferCheckedInstruction(
treasuryAta, mint, t.ata, treasury.publicKey, t.usdcAtomic, decimals, [], TOKEN_PROGRAM_ID,
));
}
}
const signers = solFunder.publicKey.equals(treasury.publicKey) ? [solFunder] : [solFunder, treasury];
return sendIxs(conn, solFunder, signers, ixs, { confirmMs });
}
/**
* Empty a fresh wallet and close its token account in ONE self-paid
* transaction: leftover USDC -> treasury, ATA rent -> the SOL funder, every
* remaining lamport but the base fee -> the SOL funder. The wallet ends at
* exactly zero. Returns what moved so the caller can book it.
* @param {{ conn, wallet, solFunder: PublicKey, treasury: PublicKey, mint, decimals, confirmMs?: number }} p
*/
export async function sweepWallet({ conn, wallet, solFunder, treasury, mint, decimals, confirmMs }) {
const owner = wallet.publicKey;
const ata = usdcAtaOf(owner, mint);
const [sol, usdc] = await Promise.all([readSolLamports(conn, owner), readUsdc(conn, ata)]);
if (sol === null || usdc === null) return { ok: false, err: 'balance_unreadable' };
if (sol === 0 && !usdc.exists) return { ok: true, signature: null, alreadyEmpty: true, solLamports: 0, usdcAtomic: 0n, rentLamports: 0 };
if (sol < BASE_FEE_LAMPORTS) return { ok: false, err: `below_sweep_fee:${sol}` };
const ixs = [
ComputeBudgetProgram.setComputeUnitLimit({ units: SWEEP_CU_LIMIT }),
ComputeBudgetProgram.setComputeUnitPrice({ microLamports: 0 }),
];
if (usdc.exists) {
if (usdc.atomic > 0n) {
const treasuryAta = usdcAtaOf(treasury, mint);
ixs.push(createTransferCheckedInstruction(ata, mint, treasuryAta, owner, usdc.atomic, decimals, [], TOKEN_PROGRAM_ID));
}
// closeAccount: [account, rent destination, authority]. The funder paid the
// rent when it created the account, so the funder gets it back.
ixs.push(createCloseAccountInstruction(ata, solFunder, owner, [], TOKEN_PROGRAM_ID));
}
const send = sweepAmountLamports({ balanceLamports: sol, feeLamports: BASE_FEE_LAMPORTS });
if (send > 0) ixs.push(SystemProgram.transfer({ fromPubkey: owner, toPubkey: solFunder, lamports: send }));
const res = await sendIxs(conn, wallet, [wallet], ixs, { confirmMs });
if (!res.ok) return { ok: false, signature: res.signature, err: res.err };
return {
ok: true,
signature: res.signature,
solLamports: send,
usdcAtomic: usdc.exists ? usdc.atomic : 0n,
// USDC is a classic SPL account, so its rent is the fixed classic figure
// (the same constant the facilitator books when it creates one).
rentLamports: usdc.exists ? ATA_RENT_LAMPORTS : 0,
};
}
export { PublicKey };