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
// Programmatic $THREE micro-buy primitive — the buy-only engine behind the x402
// micro-buy loop.
//
// WHAT IT IS. A small, fixed-size market buy of $THREE on Jupiter (USDC → $THREE,
// ExactIn), executed once per settled x402 call so the platform can run a high
// cadence of tiny, continuous buys (target ~60/min) that show up as constant,
// real on-chain buy pressure. It reuses the same Jupiter client (jupiter.js) and
// treasury policy (config.js) as the daily buyback (buyback.js); it is the
// high-frequency, small-ticket sibling of that low-frequency, large-ticket lane.
//
// BUY-ONLY. This engine never sells $THREE. It quotes USDC→$THREE, buys, and lets
// the tokens accrue in the micro-buy wallet; the treasury sweep (buyback.sweep-
// StrandedThree) is the only thing that moves them, and it moves them TO the
// treasury, never back to USDC. There is no sell path.
//
// CUSTODY. Buys are funded by the micro-buy wallet's own USDC balance
// (THREE_MICROBUY_SECRET_KEY_B64, or the shared buyback wallet
// THREE_BUYBACK_SECRET_KEY_B64 when the dedicated key is unset). The x402 toll the
// caller pays for each buy routes to the ring treasury (X402_PAY_TO_SOLANA) exactly
// like every other ring endpoint — it is NOT the buy funding, so the two money
// streams stay independent and auditable.
//
// SAFETY. Every buy is bounded by a per-buy size cap AND a UTC-daily USD ceiling
// enforced atomically (Redis reserve-before-execute, DB-sum fallback) so a flood
// of calls — from the loop or a direct payer — can never drain the wallet or burn
// unbounded SOL beyond the day's cap. Execution is gated by THREE_MICROBUY_ENABLED;
// until an operator funds the wallet and opts in, the engine is a recorded no-op.
import {
createAssociatedTokenAccountIdempotentInstruction,
createTransferInstruction,
getAssociatedTokenAddressSync,
} from '@solana/spl-token';
import { getConnection, solanaPubkey } from '../pump.js';
import { confirmOrThrow } from '../solana/confirm.js';
import { submitProtected } from '../execution-engine.js';
import { getRedis } from '../redis.js';
import { sql } from '../db.js';
import { SOLANA_USDC_MINT } from '../../payments/_config.js';
import { TOKEN_MINT, TOKEN_DECIMALS, treasuryWallet, treasuryWalletOrNull } from './config.js';
import { tokenProgramIdForMint } from './token-program.js';
import { jupiterQuote, jupiterSwapTx } from './jupiter.js';
import {
envUsd,
envSlippageBps,
usdToUsdcAtomics,
usdcAtomicsToUsd,
atomicsToTokens,
wouldExceedCap,
} from './buyback-math.js';
const MEMO_PROGRAM_ID = 'MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr';
// One-time DDL guard per warm instance. The migration owns this table in a real
// deploy; this makes the lane self-healing so the daily-cap DB fallback and the
// ledger never silently no-op on a fresh/behind database (which, combined with a
// Redis outage, would otherwise let the cap fail open).
let _schemaReady = false;
export async function ensureMicrobuySchema() {
if (_schemaReady) return;
await sql`
CREATE TABLE IF NOT EXISTS three_microbuy_runs (
id uuid primary key default gen_random_uuid(),
status text not null,
reason text,
usdc_spent_atomics bigint not null default 0,
three_bought_atomics bigint not null default 0,
price_usd numeric,
slippage_bps integer,
buy_signature text,
created_at timestamptz not null default now()
)
`;
await sql`CREATE INDEX IF NOT EXISTS three_microbuy_runs_created ON three_microbuy_runs (created_at desc)`;
_schemaReady = true;
}
// ── policy knobs (env, with safe defaults) ──────────────────────────────────
/** Execution gate. A run is a recorded no-op unless this is truthy. */
export function isEnabled() {
return ['1', 'true', 'yes', 'on'].includes(
String(process.env.THREE_MICROBUY_ENABLED || '').toLowerCase(),
);
}
/** USD spent per single micro-buy (default $0.01). Bounded to a sane band. */
export function buyUsd() {
const v = envUsd(process.env.THREE_MICROBUY_USD, 0.01);
// Never let a fat-fingered env turn a "micro" buy into a wallet-drainer.
return Math.min(v, 5);
}
/** Per-buy size in USDC atomics (6dp). */
export function buyUsdcAtomics() {
return usdToUsdcAtomics(buyUsd());
}
/** UTC-daily ceiling on total micro-buy USD (default $50). */
export function dailyCapUsd() {
return envUsd(process.env.THREE_MICROBUY_DAILY_CAP_USD, 50);
}
/** Jupiter slippage tolerance in bps (default 3%). */
export function slippageBps() {
return envSlippageBps(process.env.THREE_MICROBUY_SLIPPAGE_BPS, 300);
}
/** Seconds to wait for buy confirmation before returning `pending` (default 12). */
function confirmTimeoutMs() {
const n = Number(process.env.THREE_MICROBUY_CONFIRM_TIMEOUT_MS);
return Number.isFinite(n) && n >= 1_000 && n <= 60_000 ? n : 12_000;
}
/**
* Wait for on-chain confirmation of each buy before returning? OFF by default: the
* micro-buy lane is built for throughput (target ~60 buys/min). Waiting for
* confirmation would pin each call to the ~2–12s block time and make 60/min
* impossible inside the 60s tick budget. Broadcast-and-go is correct here because
* the daily cap is reserved BEFORE broadcast (so spend is bounded regardless) and
* the treasury sweep reads real on-chain balances (so accounting self-corrects).
* Set THREE_MICROBUY_AWAIT_CONFIRM=true to trade throughput for per-call confirmation.
*/
function awaitConfirm() {
return ['1', 'true', 'yes', 'on'].includes(
String(process.env.THREE_MICROBUY_AWAIT_CONFIRM || '').toLowerCase(),
);
}
// Micro-buy ledger statuses that count as real spend (deducted from the daily cap):
// a submitted-but-unconfirmed buy has already committed its USDC on-chain, so it
// must count exactly like a confirmed one — otherwise the DB cap fallback would
// under-count and let the day overspend.
export const SPENT_STATUSES = ['confirmed', 'pending', 'submitted'];
// ── per-buy amount jitter (transaction-distinctness) ─────────────────────────
// At ~60 buys/min, many buys of the SAME size fire within one blockhash window. If
// two used an identical quote+amount, Jupiter can build byte-identical transactions
// → the same signature → the second is rejected as already-processed and that buy
// is silently lost. A tiny per-buy jitter on the input amount (0–255 atomics, up to
// $0.000255 on a $0.01 buy) makes every buy a genuinely distinct market order:
// distinct amount → distinct quote → distinct transaction → distinct signature. The
// counter cycles every 256 buys (~4 min at 60/min), far longer than any blockhash
// window, so the same jittered amount never collides in practice. Jupiter's keyless
// tier absorbs the per-buy quote load (measured: 20 concurrent quotes, 0 throttling).
let _jitterSeq = 0;
function nextBuyAmountAtomics() {
const jitter = BigInt(_jitterSeq++ & 0xff);
return buyUsdcAtomics() + jitter;
}
/**
* Load the micro-buy signer. Prefers a DEDICATED key so micro-buys and the daily
* buyback don't fight over one wallet's USDC; falls back to the buyback wallet so
* a single funded wallet powers both lanes out of the box. Null when neither is set.
*/
export async function loadMicrobuySigner() {
const b64 =
process.env.THREE_MICROBUY_SECRET_KEY_B64 || process.env.THREE_BUYBACK_SECRET_KEY_B64;
if (!b64) return null;
const { Keypair } = await import('@solana/web3.js');
const raw = Buffer.from(b64, 'base64');
if (raw.byteLength !== 64) {
throw Object.assign(
new Error(`micro-buy signer: expected 64-byte secret key, got ${raw.byteLength}`),
{ code: 'bad_signer' },
);
}
return Keypair.fromSecretKey(raw);
}
// ── daily spend ceiling (atomic reserve-before-execute) ─────────────────────
const utcDay = () => new Date().toISOString().slice(0, 10); // YYYY-MM-DD (UTC)
const dailyKey = () => `three:microbuy:daily:${utcDay()}`;
/**
* DB sum of today's micro-buy spend (confirmed + pending rows). STRICT: throws on a
* query fault so the caller can decide whether to fail closed. The read-path
* wrappers (dailySpentAtomics, hasDailyBudget) swallow the throw; the reserve path
* treats it as "cap unverifiable" and refuses the buy.
*/
async function dbDailySpentAtomicsStrict() {
const rows = await sql`
SELECT COALESCE(SUM(usdc_spent_atomics), 0)::bigint AS spent
FROM three_microbuy_runs
WHERE status IN ('confirmed', 'pending', 'submitted') AND created_at >= date_trunc('day', now())
`;
return BigInt(rows[0]?.spent || 0);
}
/**
* Atomically reserve `atomics` of today's budget. Returns { ok, reason?,
* dailySpentAtomics, dailyCapAtomics }. When the reservation would cross the daily
* cap it is rolled back and ok:false is returned, so the caller never buys past the
* ceiling. Redis is the fast atomic path; if it is down we fall back to a (racy) DB
* sum. Crucially this FAILS CLOSED: if neither Redis nor the DB can tell us today's
* spend, the buy is refused (reason:'cap_unverifiable') rather than letting an
* uncapped flood through — an unbounded real-money spend is the one outcome the cap
* exists to prevent.
*/
export async function reserveDailySpend(atomics) {
const capAtomics = usdToUsdcAtomics(dailyCapUsd());
const need = BigInt(atomics);
const redis = getRedis();
if (redis) {
try {
const key = dailyKey();
const total = BigInt(await redis.incrby(key, Number(need)));
// First writer sets a 2-day TTL so the key self-expires after the UTC day.
if (total === need) {
try { await redis.expire(key, 86_400 * 2); } catch { /* non-fatal */ }
}
if (total > capAtomics) {
try { await redis.incrby(key, -Number(need)); } catch { /* best-effort rollback */ }
return { ok: false, reason: 'daily_cap_reached', dailySpentAtomics: total - need, dailyCapAtomics: capAtomics };
}
return { ok: true, dailySpentAtomics: total, dailyCapAtomics: capAtomics };
} catch {
/* Redis faulted — fall through to the DB fallback below. */
}
}
// Fallback: sum the ledger. STRICT — a query fault here means we cannot prove the
// cap, so refuse (fail closed) instead of assuming zero spent.
let spent;
try {
spent = await dbDailySpentAtomicsStrict();
} catch {
return { ok: false, reason: 'cap_unverifiable', dailySpentAtomics: 0n, dailyCapAtomics: capAtomics };
}
if (wouldExceedCap(spent, need, capAtomics)) {
return { ok: false, reason: 'daily_cap_reached', dailySpentAtomics: spent, dailyCapAtomics: capAtomics };
}
return { ok: true, dailySpentAtomics: spent + need, dailyCapAtomics: capAtomics };
}
/** Release a previously-reserved amount (a buy that never broadcast). Redis only. */
export async function releaseDailySpend(atomics) {
const redis = getRedis();
if (!redis) return;
try { await redis.incrby(dailyKey(), -Number(BigInt(atomics))); } catch { /* non-fatal */ }
}
/**
* Cheap best-effort check: is there room under today's cap for at least one more
* buy? Used to refuse a call BEFORE quoting Jupiter when the day's budget is spent.
* The atomic reserve in executeMicrobuy remains the real guard; this only avoids
* needless work on the exhausted path. Fails OPEN (returns true) on a read error so
* a transient Redis/DB blip never wrongly halts buys — the reserve still enforces.
*/
export async function hasDailyBudget() {
try {
const spent = await dailySpentAtomics();
return spent + buyUsdcAtomics() <= usdToUsdcAtomics(dailyCapUsd());
} catch {
return true;
}
}
/** Today's micro-buy spend so far (atomics) for status/read paths. Tolerant → 0n. */
export async function dailySpentAtomics() {
const redis = getRedis();
if (redis) {
try {
const v = await redis.get(dailyKey());
if (v != null) return BigInt(v);
} catch { /* fall through */ }
}
try { return await dbDailySpentAtomicsStrict(); } catch { return 0n; }
}
// ── helpers ─────────────────────────────────────────────────────────────────
const usd = (a) => usdcAtomicsToUsd(a);
const threeTokens = (a) => atomicsToTokens(a, TOKEN_DECIMALS);
/** SPL balance of `owner` for `mint`, in atomics. Missing ATA → 0n (never throws). */
async function splBalanceAtomics(connection, ownerPk, mintPk) {
try {
// $THREE is Token-2022; the spl-token default program derives an ATA that does
// not exist, which reads back as a zero balance on a wallet that holds tokens.
const programId = await tokenProgramIdForMint(connection, mintPk);
const ata = getAssociatedTokenAddressSync(mintPk, ownerPk, true, programId);
const bal = await connection.getTokenAccountBalance(ata);
return BigInt(bal.value.amount);
} catch {
return 0n;
}
}
/** Bounded confirmation: resolve 'confirmed' or throw/timeout without hanging the request. */
async function confirmBounded(connection, sig) {
let timer;
const timeout = new Promise((_, reject) => {
timer = setTimeout(
() => reject(Object.assign(new Error('confirm_timeout'), { code: 'tx_unconfirmed' })),
confirmTimeoutMs(),
);
});
try {
await Promise.race([confirmOrThrow(connection, sig, 'confirmed'), timeout]);
} finally {
clearTimeout(timer);
}
}
// ── plan + execute ──────────────────────────────────────────────────────────
/**
* Size + quote a single micro-buy against the wallet's live USDC balance. Pure of
* signing/sending. Returns { ok, reason?, spendUsdcAtomics, walletUsdcAtomics,
* quote?, expectedThreeAtomics?, priceUsd? }.
*/
export async function planMicrobuy(signerPubkey) {
if (!treasuryWalletOrNull()) {
return { ok: false, reason: 'treasury_unavailable', walletUsdcAtomics: 0n, spendUsdcAtomics: 0n };
}
// Jittered per-buy amount so concurrent buys never build identical transactions.
const spend = nextBuyAmountAtomics();
const connection = getConnection({ network: 'mainnet' });
const walletUsdc = await splBalanceAtomics(
connection,
solanaPubkey(signerPubkey),
solanaPubkey(SOLANA_USDC_MINT),
);
if (walletUsdc < spend) {
return { ok: false, reason: 'insufficient_usdc', walletUsdcAtomics: walletUsdc, spendUsdcAtomics: spend };
}
const quote = await jupiterQuote({
inputMint: SOLANA_USDC_MINT,
outputMint: TOKEN_MINT,
amount: spend,
slippageBps: slippageBps(),
});
const expectedThree = BigInt(quote.outAmount ?? 0);
if (expectedThree <= 0n) {
return { ok: false, reason: 'no_quote', walletUsdcAtomics: walletUsdc, spendUsdcAtomics: spend };
}
return {
ok: true,
walletUsdcAtomics: walletUsdc,
spendUsdcAtomics: spend,
quote,
expectedThreeAtomics: expectedThree,
priceUsd: usd(spend) / threeTokens(expectedThree),
};
}
/**
* Execute one micro-buy: reserve the daily budget, sign + broadcast the Jupiter buy.
* Broadcast-and-go by default (THREE_MICROBUY_AWAIT_CONFIRM off) so the lane can
* sustain ~60 buys/min without pinning each call to block time; confirmation is
* optional. The bought $THREE accrues in the micro-buy wallet (swept to the
* treasury on a cadence by the loop). Returns a receipt; on a hard failure throws
* with a `.code` so the caller records the reason and (on a never-broadcast
* failure) releases the reservation.
*
* `boughtAtomics` is the QUOTED out amount (plan.expectedThreeAtomics), not a
* wallet-balance read — the wallet holds the accrued total of every prior buy, so
* reading its balance would over-count each row. The sweep reconciles against real
* on-chain balances, so the quoted figure is the honest per-buy estimate.
*
* @returns {Promise<{ status:'submitted'|'confirmed', buySignature:string, spendUsdcAtomics:bigint, boughtAtomics:bigint, priceUsd:number|null }>}
*/
export async function executeMicrobuy(signer, plan) {
const { VersionedTransaction } = await import('@solana/web3.js');
const connection = getConnection({ network: 'mainnet' });
const payer = signer.publicKey;
// Reserve budget BEFORE broadcasting so concurrent buys can't collectively
// overshoot the daily cap. Released only if we never broadcast.
const reservation = await reserveDailySpend(plan.spendUsdcAtomics);
if (!reservation.ok) {
const code = reservation.reason || 'daily_cap_reached';
throw Object.assign(
new Error(code === 'cap_unverifiable'
? 'micro-buy cap unverifiable (Redis and DB both unavailable) — refusing to buy'
: 'daily micro-buy cap reached'),
{ code, dailySpentAtomics: reservation.dailySpentAtomics, dailyCapAtomics: reservation.dailyCapAtomics },
);
}
// jupiterSwapTx()'s default priority ceiling (0.001 SOL, 'medium') is sized for
// time-sensitive swaps elsewhere in the codebase. This lane broadcasts-and-goes
// with no confirm wait (see awaitConfirm() above), so nothing is waiting on fast
// inclusion — an occasional slower landing costs nothing. On a $0.01-$5 buy that
// ceiling can dwarf the trade itself, so cap it far tighter; 'medium' still
// prices adaptively off real network conditions, just bounded.
let swapB64;
try {
swapB64 = await jupiterSwapTx({
quote: plan.quote,
userPublicKey: payer.toBase58(),
maxPriorityLamports: 25_000,
});
} catch (err) {
await releaseDailySpend(plan.spendUsdcAtomics);
throw err;
}
const buyTx = VersionedTransaction.deserialize(Buffer.from(swapB64, 'base64'));
buyTx.sign([signer]);
let buySig;
try {
buySig = await connection.sendRawTransaction(buyTx.serialize(), { maxRetries: 5 });
} catch (err) {
// Never broadcast → the budget was not spent; give it back.
await releaseDailySpend(plan.spendUsdcAtomics);
throw Object.assign(new Error(`micro-buy broadcast failed: ${err?.message || err}`), {
code: 'swap_failed',
});
}
const boughtAtomics = plan.expectedThreeAtomics ?? 0n;
// Throughput path (default): the tx is broadcast and the USDC is committed —
// return immediately as 'submitted' without waiting for a block. The sweep and
// on-chain state are the source of truth for what actually landed.
if (!awaitConfirm()) {
return {
status: 'submitted',
buySignature: buySig,
spendUsdcAtomics: plan.spendUsdcAtomics,
boughtAtomics,
priceUsd: plan.priceUsd ?? null,
};
}
// Opt-in confirmation path: wait within a bounded window. The reservation STANDS
// on a timeout (the buy is in flight, not free); only a revert reclaims it.
try {
await confirmBounded(connection, buySig);
} catch (waitErr) {
if (waitErr?.code === 'tx_reverted') {
await releaseDailySpend(plan.spendUsdcAtomics);
throw waitErr;
}
return {
status: 'submitted',
buySignature: buySig,
spendUsdcAtomics: plan.spendUsdcAtomics,
boughtAtomics,
priceUsd: plan.priceUsd ?? null,
};
}
return {
status: 'confirmed',
buySignature: buySig,
spendUsdcAtomics: plan.spendUsdcAtomics,
boughtAtomics,
priceUsd: plan.priceUsd ?? null,
};
}
/**
* Sweep all $THREE held by the micro-buy wallet into the treasury. Buy-only lane:
* this is the ONLY thing that moves the accrued tokens, and it only moves them to
* the treasury. Returns the sweep signature, or null when there is nothing to sweep
* or the wallet already IS the treasury. Reuses submitProtected (priority fee + CU
* estimate, blockhash-refresh rebroadcast, hard throw on revert).
*/
export async function sweepMicrobuyThree(signer) {
const treasury = treasuryWalletOrNull();
if (!treasury || treasury === signer.publicKey.toBase58()) return null;
const { TransactionInstruction, PublicKey } = await import('@solana/web3.js');
const connection = getConnection({ network: 'mainnet' });
const payer = signer.publicKey;
const mintPk = new PublicKey(TOKEN_MINT);
const held = await splBalanceAtomics(connection, payer, mintPk);
if (held <= 0n) return null;
const treasuryPk = new PublicKey(treasury);
const programId = await tokenProgramIdForMint(connection, mintPk);
const fromAta = getAssociatedTokenAddressSync(mintPk, payer, true, programId);
const toAta = getAssociatedTokenAddressSync(mintPk, treasuryPk, true, programId);
const ixs = [
createAssociatedTokenAccountIdempotentInstruction(payer, toAta, treasuryPk, mintPk, programId),
createTransferInstruction(fromAta, toAta, payer, held, [], programId),
new TransactionInstruction({
keys: [],
programId: new PublicKey(MEMO_PROGRAM_ID),
data: Buffer.from('three.ws micro-buy → treasury', 'utf8'),
}),
];
const { signature } = await submitProtected({
network: 'mainnet',
connection,
payer: signer,
instructions: ixs,
});
return signature;
}
// ── public stats ─────────────────────────────────────────────────────────────
/**
* Public micro-buy summary: lifetime + today's buy count, $THREE bought, USDC
* deployed, and how much of today's budget is spent. Resilient — degrades to a sane
* default whether the query rejects (table missing) or sql throws synchronously
* (env unconfigured), so a status surface never 500s on it.
*/
export async function microbuyStats() {
let agg = { runs: 0, confirmed: 0, pending: 0, usdc: 0, three: 0 };
let today = { runs: 0, usdc: 0 };
try {
const [lifetime] = await sql`
SELECT
count(*) FILTER (WHERE status IN ('confirmed', 'pending', 'submitted'))::int AS runs,
count(*) FILTER (WHERE status = 'confirmed')::int AS confirmed,
count(*) FILTER (WHERE status IN ('pending', 'submitted'))::int AS pending,
COALESCE(SUM(usdc_spent_atomics) FILTER (WHERE status IN ('confirmed', 'pending', 'submitted')), 0)::bigint AS usdc,
COALESCE(SUM(three_bought_atomics) FILTER (WHERE status IN ('confirmed', 'pending', 'submitted')), 0)::bigint AS three
FROM three_microbuy_runs
`;
if (lifetime) {
agg = {
runs: lifetime.runs, confirmed: lifetime.confirmed, pending: lifetime.pending,
usdc: Number(lifetime.usdc), three: Number(lifetime.three),
};
}
const [day] = await sql`
SELECT count(*)::int AS runs,
COALESCE(SUM(usdc_spent_atomics), 0)::bigint AS usdc
FROM three_microbuy_runs
WHERE status IN ('confirmed', 'pending', 'submitted') AND created_at >= date_trunc('day', now())
`;
if (day) today = { runs: day.runs, usdc: Number(day.usdc) };
} catch { /* degrade to defaults */ }
const capUsd = dailyCapUsd();
const spentTodayUsd = today.usdc / 1e6;
return {
enabled: isEnabled(),
buy_usd: buyUsd(),
lifetime: {
buys: agg.runs,
confirmed: agg.confirmed,
pending: agg.pending,
usdc_deployed: usd(agg.usdc),
three_bought: threeTokens(agg.three),
},
today: {
buys: today.runs,
usdc_deployed: spentTodayUsd,
cap_usd: capUsd,
cap_used_pct: capUsd > 0 ? Math.min(100, (spentTodayUsd / capUsd) * 100) : 0,
},
};
}
export { usd as usdcAtomicsToUsd, threeTokens as threeAtomicsToTokens };