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
/**
* Real on-chain funding + reclaim rails for sealed wallet drops.
*
* Funding model: when a drop is created (and the x402 create fee is settled),
* the platform moves REAL funds into the freshly-ground drop address from its
* Solana funding wallet (`VANITY_DROP_FUNDING_KEY`, falling back to the bounty
* payout key, then the club treasury secret — every custodial-money endpoint on
* the platform shares this resolution). Three assets are supported:
* • SOL — native System transfer (lamports).
* • USDC — SPL transfer (the x402 rail asset; never marketed as a coin).
* • THREE — SPL transfer of the platform's only coin, $THREE.
* Balances are read live via the Helius-backed connection. No fake balances:
* funding is confirmed on-chain BEFORE a drop is shown as claimable.
*
* Reclaim model: an EXPIRED, unclaimed drop's funds are swept back to the
* sender's reclaim address. The sweep is signed by the drop wallet's own key,
* which the platform can reconstruct only because the SAME plaintext it sealed
* to the recipient is also held encrypted at rest under secret-box (AES-256-GCM)
* for the reclaim path — and ONLY for reclaim. (The recipient's E2E guarantee is
* unaffected: that at-rest copy is the drop wallet's key, used solely to refund
* the sender on expiry; the claim path always delivers the SEALED envelope the
* recipient opens with their own key.) The sweep is exactly-once: the store's
* funded→reclaimed compare-and-set runs first and records the resulting tx.
*
* Money-safety invariants:
* • Funding is confirmed (`confirmed` commitment) before createDrop persists a
* claimable record; a funding failure aborts the create with the fee unsettled.
* • A drop is EITHER claimed (recipient opens it) OR reclaimed (sender refunded),
* never both — the two store transitions are mutually-exclusive CAS.
* • Reclaim is idempotent: a reclaimed drop that already carries a reclaimTx
* short-circuits instead of sweeping again.
*/
import bs58 from 'bs58';
import {
Keypair,
PublicKey,
SystemProgram,
LAMPORTS_PER_SOL,
} from '@solana/web3.js';
import {
getAssociatedTokenAddress,
createAssociatedTokenAccountIdempotentInstruction,
createTransferInstruction,
getAccount,
} from '@solana/spl-token';
import { env } from './env.js';
import { ataExists } from './solana/read-guards.js';
import { solanaConnection } from './agent-pumpfun.js';
import { submitProtected } from './execution-engine.js';
import { SOLANA_USDC_MINT } from '../payments/_config.js';
import { recordReclaim } from './sealed-drop-store.js';
const BASE58_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
// Network fee headroom left in a SOL drop so the wallet can pay rent/fees when
// the recipient sweeps it onward (a drop with exactly 0 lamports of headroom
// can't even create its own ATA). Kept small so the gift is mostly the gift.
const SOL_FEE_HEADROOM_LAMPORTS = 0; // SOL drops fund the exact amount; recipient sweeps natively.
/** Resolve the platform funding wallet as a Base58 64-byte secret, or null. */
function resolveFundingKeyBase58() {
const candidates = [
env.VANITY_DROP_FUNDING_KEY,
env.VANITY_BOUNTY_PAYOUT_KEY,
].filter(Boolean);
for (const raw of candidates) {
const s = String(raw).trim();
try {
if (bs58.decode(s).length === 64) return s;
} catch {
/* try base64 */
}
try {
const buf = Buffer.from(s, 'base64');
if (buf.byteLength === 64) return bs58.encode(buf);
} catch {
/* ignore */
}
}
const clubB64 = process.env.CLUB_SOLANA_TREASURY_SECRET_KEY_B64;
if (clubB64) {
try {
const buf = Buffer.from(clubB64, 'base64');
if (buf.byteLength === 64) return bs58.encode(buf);
} catch {
/* ignore */
}
}
return null;
}
/** True when the platform can actually fund drops (wallet configured + valid). */
export function fundingConfigured() {
return !!resolveFundingKeyBase58();
}
/**
* The platform funding wallet's public address, or null when unconfigured. This
* is where a drop's funds go back to when a create is rolled back (the fee failed
* to settle after the wallet was already funded): the money returns to exactly
* the wallet it left.
*/
export function fundingWalletAddress() {
const key = resolveFundingKeyBase58();
if (!key) return null;
return Keypair.fromSecretKey(bs58.decode(key)).publicKey.toBase58();
}
function fundingKeypair() {
const key = resolveFundingKeyBase58();
if (!key) {
throw Object.assign(
new Error('drop funding wallet is not configured — set VANITY_DROP_FUNDING_KEY (Base58 64-byte secret)'),
{ status: 503, code: 'funding_unconfigured' },
);
}
return Keypair.fromSecretKey(bs58.decode(key));
}
/** The $THREE mint — the only coin a drop may be funded with as a *coin*. */
function threeMint() {
return env.THREE_TOKEN_MINT;
}
/** SPL mint for a drop asset (USDC rail or $THREE coin). SOL has no mint. */
function mintForAsset(asset) {
if (asset === 'USDC') return SOLANA_USDC_MINT;
if (asset === 'THREE') return threeMint();
return null;
}
/** Decimals for an asset → atomics conversion. */
export function decimalsForAsset(asset) {
if (asset === 'SOL') return 9;
if (asset === 'USDC') return 6;
if (asset === 'THREE') return Number(env.THREE_TOKEN_DECIMALS) || 6;
throw Object.assign(new Error(`unknown asset ${asset}`), { status: 400, code: 'invalid_asset' });
}
/** Convert a human amount (string/number) to atomics (BigInt) for an asset. */
export function amountToAtomics(amount, asset) {
const decimals = decimalsForAsset(asset);
const s = String(amount).trim();
if (!/^\d+(\.\d+)?$/.test(s)) {
throw Object.assign(new Error('amount must be a positive decimal number'), { status: 400, code: 'invalid_amount' });
}
const [whole, frac = ''] = s.split('.');
if (frac.length > decimals) {
throw Object.assign(new Error(`amount has more than ${decimals} decimal places for ${asset}`), { status: 400, code: 'invalid_amount' });
}
const padded = (whole + frac.padEnd(decimals, '0')).replace(/^0+(?=\d)/, '');
const atomics = BigInt(padded || '0');
if (atomics <= 0n) {
throw Object.assign(new Error('amount must be greater than zero'), { status: 400, code: 'invalid_amount' });
}
return atomics;
}
/** Format atomics back to a human string for display. */
export function atomicsToAmount(atomics, asset) {
const decimals = decimalsForAsset(asset);
const a = BigInt(atomics);
const s = a.toString().padStart(decimals + 1, '0');
const whole = s.slice(0, -decimals) || '0';
const frac = s.slice(-decimals).replace(/0+$/, '');
return frac ? `${whole}.${frac}` : whole;
}
/**
* Fund a freshly-ground drop address on-chain from the platform funding wallet.
* Confirms the transfer before returning. Throws (with the create aborted) on
* any failure so a drop is never shown as claimable without real funds behind it.
*
* @param {object} p
* @param {string} p.toAddress - the drop wallet's Base58 address.
* @param {string} p.asset - 'SOL' | 'USDC' | 'THREE'.
* @param {bigint} p.atomics - amount in smallest units.
* @returns {Promise<{ fundingTx:string, atomics:string, asset:string }>}
*/
export async function fundDropAddress({ toAddress, asset, atomics }) {
if (!BASE58_RE.test(String(toAddress || ''))) {
throw Object.assign(new Error('drop address must be a Base58 Solana address'), { status: 400, code: 'invalid_address' });
}
const amount = BigInt(atomics);
if (amount <= 0n) {
throw Object.assign(new Error('funding amount must be positive'), { status: 400, code: 'invalid_amount' });
}
const payer = fundingKeypair();
const recipient = new PublicKey(toAddress);
const conn = solanaConnection('mainnet');
const instructions = [];
if (asset === 'SOL') {
instructions.push(SystemProgram.transfer({ fromPubkey: payer.publicKey, toPubkey: recipient, lamports: amount }));
} else {
const mint = new PublicKey(mintForAsset(asset));
const fromATA = await getAssociatedTokenAddress(mint, payer.publicKey);
const toATA = await getAssociatedTokenAddress(mint, recipient);
// The create is the IDEMPOTENT variant on purpose: it pairs with ataExists,
// which fails open to "missing" when the chain cannot be read. With the plain
// create that guess would be unsafe (a create for an account that already
// exists fails the whole transaction); with this one an unnecessary create is a
// no-op, so a dead RPC costs nothing and the probe-then-submit race disappears
// with it.
if (!(await ataExists(conn, toATA))) {
instructions.push(createAssociatedTokenAccountIdempotentInstruction(payer.publicKey, toATA, recipient, mint));
}
instructions.push(createTransferInstruction(fromATA, toATA, payer.publicKey, amount));
}
// Protected send: priority fee + CU estimate, rebroadcast with blockhash
// refresh, hard throw on revert.
const { signature: sig } = await submitProtected({ network: 'mainnet', connection: conn, payer, instructions });
return { fundingTx: sig, atomics: amount.toString(), asset };
}
/**
* Read the live on-chain balance of a drop address for its funded asset.
* Never throws — an RPC blip returns null so the claim UI degrades to "checking".
* @returns {Promise<{ atomics:string|null }>}
*/
export async function readDropBalance({ address, asset }) {
try {
const conn = solanaConnection('mainnet');
const owner = new PublicKey(address);
if (asset === 'SOL') {
const lamports = await conn.getBalance(owner, 'confirmed');
return { atomics: String(lamports) };
}
const mint = new PublicKey(mintForAsset(asset));
const ata = await getAssociatedTokenAddress(mint, owner);
try {
const acct = await getAccount(conn, ata);
return { atomics: acct.amount.toString() };
} catch {
return { atomics: '0' }; // no ATA yet → zero
}
} catch {
return { atomics: null };
}
}
/**
* Sweep an EXPIRED, reclaimed drop's funds back to the sender's reclaim address.
* Signs with the drop wallet's OWN key (reconstructed from the at-rest encrypted
* copy by the caller and passed in as `dropSecretKey`). For SOL it sweeps the
* full balance minus the network fee; for SPL it sweeps the full token balance
* (the drop wallet must hold a little SOL for the fee — funded drops always do
* because USDC/THREE funding created the recipient ATA with the platform paying,
* so the sweep fee is paid by the platform funding wallet as fee-payer).
*
* Idempotent: a drop that already carries a reclaimTx returns it without sweeping.
*
* @param {object} p
* @param {object} p.record - the drop record (must be status 'reclaimed').
* @param {Uint8Array} p.dropSecretKey - the 64-byte secret of the drop wallet.
* @param {string} p.toAddress - the sender's reclaim Base58 address.
* @returns {Promise<{ reclaimTx:string, alreadyReclaimed:boolean }>}
*/
export async function sweepReclaim({ record, dropSecretKey, toAddress }) {
if (!record) throw Object.assign(new Error('drop not found'), { status: 404, code: 'not_found' });
if (record.status !== 'reclaimed') {
throw Object.assign(new Error(`drop is ${record.status}, not reclaimed — cannot sweep`), { status: 409, code: 'not_reclaimable' });
}
if (record.reclaimTx) {
return { reclaimTx: record.reclaimTx, alreadyReclaimed: true };
}
if (!BASE58_RE.test(String(toAddress || ''))) {
throw Object.assign(new Error('reclaim address must be a Base58 Solana address'), { status: 400, code: 'invalid_reclaim_address' });
}
const dropKp = Keypair.fromSecretKey(dropSecretKey);
const feePayer = fundingKeypair(); // platform pays the sweep network fee
const recipient = new PublicKey(toAddress);
const conn = solanaConnection('mainnet');
const asset = record.asset;
const instructions = [];
if (asset === 'SOL') {
const lamports = await conn.getBalance(dropKp.publicKey, 'confirmed');
if (lamports <= 0) {
// Nothing to sweep (already empty) — treat as a completed reclaim.
await recordReclaim({ id: record.id, reclaimTx: 'empty' });
return { reclaimTx: 'empty', alreadyReclaimed: false };
}
// Fee is paid by the platform fee-payer, so the full drop balance moves.
instructions.push(SystemProgram.transfer({ fromPubkey: dropKp.publicKey, toPubkey: recipient, lamports }));
} else {
const mint = new PublicKey(mintForAsset(asset));
const fromATA = await getAssociatedTokenAddress(mint, dropKp.publicKey);
let amount = 0n;
try {
amount = (await getAccount(conn, fromATA)).amount;
} catch {
amount = 0n;
}
if (amount <= 0n) {
await recordReclaim({ id: record.id, reclaimTx: 'empty' });
return { reclaimTx: 'empty', alreadyReclaimed: false };
}
const toATA = await getAssociatedTokenAddress(mint, recipient);
if (!(await ataExists(conn, toATA))) {
instructions.push(createAssociatedTokenAccountIdempotentInstruction(feePayer.publicKey, toATA, recipient, mint));
}
instructions.push(createTransferInstruction(fromATA, toATA, dropKp.publicKey, amount));
}
// Protected send: platform fee-payer pays + signs, the drop wallet co-signs the
// transfer of its own balance. Priority fee + CU estimate, rebroadcast with
// blockhash refresh, hard throw on an on-chain revert.
const { signature: sig } = await submitProtected({
network: 'mainnet',
connection: conn,
payer: feePayer,
instructions,
opts: { extraSigners: [dropKp] },
});
await recordReclaim({ id: record.id, reclaimTx: sig });
return { reclaimTx: sig, alreadyReclaimed: false };
}
export { BASE58_RE, LAMPORTS_PER_SOL, SOL_FEE_HEADROOM_LAMPORTS };