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
// Spend-policy guard for agent-signed Solana transactions.
//
// Policy lives on agent_identities.meta.spend_policy:
// {
// max_sol_per_tx: number, // hard cap per individual SOL-spend tx
// daily_sol_cap: number, // rolling 24h sum across ALL SOL outflows
// allowed_mints?: string[], // optional allowlist (omit = any mint)
// }
//
// If no policy is set, a conservative default is applied so a freshly
// provisioned agent can't be drained by a stolen session token.
//
// The daily cap counts every action that moves SOL OUT of the agent wallet —
// bonding-curve buys, the initial buy of a launch, and AMM swap-buys. Sells and
// fee withdrawals are inflows and are not counted. Earlier this summed only
// `pumpfun.buy`, so a caller could alternate buys with launches/swaps and blow
// past the daily cap.
import { sql } from './db.js';
import { runLocked } from './locked-sql.js';
import { enforceSpendLimit, SpendLimitError } from './agent-trade-guards.js';
import { solUsdPrice } from './avatar-wallet.js';
// SOL-outflow action types that draw down the daily cap.
export const SOL_OUTFLOW_TYPES = ['pumpfun.buy', 'pumpfun.launch', 'pumpfun.swap.buy'];
const DEFAULT_POLICY = {
max_sol_per_tx: 1,
daily_sol_cap: 5,
allowed_mints: null,
};
export function resolveSpendPolicy(meta) {
const p = (meta && meta.spend_policy) || {};
return {
max_sol_per_tx: Number.isFinite(p.max_sol_per_tx)
? p.max_sol_per_tx
: DEFAULT_POLICY.max_sol_per_tx,
daily_sol_cap: Number.isFinite(p.daily_sol_cap)
? p.daily_sol_cap
: DEFAULT_POLICY.daily_sol_cap,
allowed_mints:
Array.isArray(p.allowed_mints) && p.allowed_mints.length ? p.allowed_mints : null,
};
}
// Static (non-DB) policy checks shared by checkBuyAllowed and reserveSpend.
// Returns null if the per-tx cap and mint allowlist pass, else a blocked object.
function staticBlock(policy, mint, amount) {
if (amount > policy.max_sol_per_tx) {
return {
status: 403,
code: 'spend_cap_exceeded',
msg: `solAmount ${amount} > max_sol_per_tx ${policy.max_sol_per_tx}`,
};
}
if (policy.allowed_mints && mint && !policy.allowed_mints.includes(mint)) {
return {
status: 403,
code: 'mint_not_allowed',
msg: `mint ${mint} not in allowed_mints`,
};
}
return null;
}
// Read-only cap check. Returns null if allowed, or { status, code, msg } if
// blocked. This is a best-effort gate: because it does not hold a lock across
// the on-chain send, two concurrent spends can both pass (TOCTOU). Callers that
// need an exact cap MUST use reserveSpend, which closes that race atomically.
// Retained for callers that record their own action row after sending.
export async function checkBuyAllowed({ agentId, meta, mint, solAmount }) {
const policy = resolveSpendPolicy(meta);
const amount = Number(solAmount) || 0;
const blocked = staticBlock(policy, mint, amount);
if (blocked) return blocked;
const [{ spent_24h } = { spent_24h: 0 }] = await sql`
SELECT COALESCE(SUM(COALESCE((payload->>'solAmount')::numeric, (payload->>'amountSol')::numeric)), 0) AS spent_24h
FROM agent_actions
WHERE agent_id = ${agentId}
AND type = ANY(${SOL_OUTFLOW_TYPES})
AND created_at > NOW() - INTERVAL '24 hours'
`;
const spent = Number(spent_24h) || 0;
if (spent + amount > policy.daily_sol_cap) {
return {
status: 403,
code: 'daily_cap_exceeded',
msg: `would spend ${spent + amount} SOL in 24h, cap is ${policy.daily_sol_cap}`,
};
}
return null;
}
// Atomically check the daily cap AND record a pending reservation row under a
// per-agent advisory lock. Concurrent spends for the SAME agent serialize on the
// lock, so two requests can never both read the same 24h total and both pass —
// closing the TOCTOU that checkBuyAllowed leaves open. The reservation row is a
// real agent_actions row (so it counts immediately toward the cap); the caller
// finalizes it with the tx signature on success, or releases it on failure.
//
// Returns { ok: true, reservationId } when allowed, or
// { ok: false, status, code, msg } when blocked.
export async function reserveSpend({ agentId, meta, mint, solAmount, type, payload = {} }) {
if (!SOL_OUTFLOW_TYPES.includes(type)) {
throw new Error(`reserveSpend: ${type} is not a SOL-outflow type`);
}
const policy = resolveSpendPolicy(meta);
const amount = Number(solAmount) || 0;
const blocked = staticBlock(policy, mint, amount);
if (blocked) return { ok: false, ...blocked };
const reserved = JSON.stringify({
...payload,
solAmount: amount,
mint: mint || null,
status: 'reserved',
});
// The advisory xact lock is taken in its own statement ahead of the INSERT…SELECT
// in one transaction (see locked-sql.js: a lock inside the same statement does
// not refresh the snapshot, so the loser would not see the winner's row). The
// INSERT…SELECT only materializes a row when the rolling 24h total plus this
// spend stays within the cap, so the check and the reservation are atomic.
const rows = await runLocked([agentId], sql`
WITH spent AS (
SELECT COALESCE(SUM(COALESCE((payload->>'solAmount')::numeric, (payload->>'amountSol')::numeric)), 0) AS s
FROM agent_actions
WHERE agent_id = ${agentId}
AND type = ANY(${SOL_OUTFLOW_TYPES})
AND created_at > NOW() - INTERVAL '24 hours'
)
INSERT INTO agent_actions (agent_id, type, payload, source_skill)
SELECT ${agentId}, ${type}, ${reserved}::jsonb, ${'pumpfun'}
FROM spent
WHERE spent.s + ${amount}::numeric <= ${policy.daily_sol_cap}::numeric
RETURNING id
`);
if (!rows.length) {
return {
status: 403,
code: 'daily_cap_exceeded',
msg: `would exceed daily_sol_cap ${policy.daily_sol_cap} SOL in 24h`,
ok: false,
};
}
return { ok: true, reservationId: rows[0].id };
}
// Finalize a reservation after the on-chain send succeeds: merge the real tx
// details (signature, network, …) into the reserved row and mark it confirmed.
export async function finalizeSpend(reservationId, payload = {}) {
if (!reservationId) return;
await sql`
UPDATE agent_actions
SET payload = payload || ${JSON.stringify({ ...payload, status: 'confirmed' })}::jsonb
WHERE id = ${reservationId}
`.catch((e) => console.error('[spend-policy] finalize failed', e));
}
// Release a reservation when the send never lands (build/sign/send failure) so a
// failed attempt does not permanently consume the agent's daily cap.
export async function releaseSpend(reservationId) {
if (!reservationId) return;
await sql`
DELETE FROM agent_actions WHERE id = ${reservationId}
`.catch((e) => console.error('[spend-policy] release failed', e));
}
// Per-run spend guard for strategy-run live buys. `guard` reserves the buy
// atomically (reserveSpend) before the trade; `settle` finalizes the reservation
// with the signature when the buy lands, or releases it when it fails. The
// reserved row is the buy's agent_actions record, so the runtime must not
// persist a second pumpfun.buy row for the same trade.
export function createStrategySpendGuard({ agentId, meta, userId = null }) {
const open = new Map();
return {
async guard({ mint, amountSol }) {
// The shared owner policy first (frozen switch, burner tier, USD caps,
// English rules), then the SOL reservation. Without this a frozen or
// capped wallet still traded through strategy-run.
const sol = Number(amountSol) || 0;
const price = await solUsdPrice().catch(() => null);
const usdValue = Number.isFinite(price) && price > 0 ? sol * price : null;
try {
await enforceSpendLimit({ agentId, meta, category: 'trade', usdValue, asset: 'SOL', userId });
} catch (err) {
if (err instanceof SpendLimitError) return { code: err.code, msg: err.message };
throw err;
}
const r = await reserveSpend({
agentId,
meta,
mint,
solAmount: amountSol,
type: 'pumpfun.buy',
payload: { source: 'strategy_run', amountSol: Number(amountSol) || 0 },
});
if (!r.ok) return { code: r.code, msg: r.msg };
open.set(mint, r.reservationId);
return null;
},
async settle({ mint, ok, sig }) {
const id = open.get(mint);
if (!id) return;
open.delete(mint);
if (ok) await finalizeSpend(id, { mint, sig: sig ?? null });
else await releaseSpend(id);
},
};
}