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
/**
* Persona wallet spend ledger — the durable record `persona_tip` / `persona_send`
* check BEFORE moving any USDC, so the per-call and per-session caps are real
* limits and not just numbers in a description.
*
* Mirrors the storage tiering already established by persona-store.js: a
* Postgres table in production, a JSON-on-disk fallback for local/dev/test so
* "the cap actually blocks a second call in the same session" is provable
* without a live database. Same shape either way.
*
* A "session" is caller-scoped (the `session_id` a client passes), not a
* three.ws account — persona wallets are addressable by id alone, so the spend
* cap follows the same no-account posture as the persona itself. Callers that
* omit session_id are bucketed by persona_id + UTC calendar day, which still
* bounds a runaway/looped caller even with no session id supplied.
*/
import { randomUUID } from 'node:crypto';
import { promises as fs } from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { sql } from './db.js';
import { databaseConfigured } from './env.js';
const dbConfigured = () => databaseConfigured();
const PENDING = 'pending:';
function envNumber(key, fallback) {
const raw = process.env[key];
if (raw === undefined || String(raw).trim() === '') return fallback;
const n = Number(raw);
return Number.isFinite(n) && n >= 0 ? n : fallback;
}
// ── guardrail configuration (env-tunable, conservative defaults) ─────────────
export const PERSONA_SPEND_CAPS = Object.freeze({
// Hard ceiling on a SINGLE persona_tip/persona_send call.
maxPerCallUsdc: envNumber('PERSONA_MAX_TIP_USDC', 1),
// Cumulative ceiling across every call sharing one session_id (or the daily
// fallback bucket for callers that don't pass one).
maxPerSessionUsdc: envNumber('PERSONA_MAX_SESSION_USDC', 5),
// Above this amount, the tool call must carry confirm:true — the same
// confirmation-gate shape used by the SOL wallet_send tool.
confirmAboveUsdc: envNumber('PERSONA_CONFIRM_ABOVE_USDC', 0.25),
});
export function utcDateBucket(d = new Date()) {
return d.toISOString().slice(0, 10); // YYYY-MM-DD
}
/** Deterministic fallback session key for callers that omit session_id. */
export function defaultSessionId(personaId) {
return `${personaId}:${utcDateBucket()}`;
}
// ── Postgres backend ──────────────────────────────────────────────────────────
let _schemaReady = null;
async function ensureSchema() {
if (_schemaReady) return _schemaReady;
_schemaReady = sql`
create table if not exists persona_wallet_spend_events (
id bigserial primary key,
persona_id text not null,
session_id text not null,
usdc numeric not null,
tool text not null,
to_address text,
signature text,
created_at timestamptz not null default now()
)
`.then(() => sql`
create index if not exists persona_wallet_spend_events_session_idx
on persona_wallet_spend_events (persona_id, session_id)
`).then(() => true);
return _schemaReady;
}
async function dbSessionTotal(personaId, sessionId) {
await ensureSchema();
const [row] = await sql`
select coalesce(sum(usdc), 0)::float8 as total
from persona_wallet_spend_events
where persona_id = ${personaId} and session_id = ${sessionId}
`;
return Number(row?.total || 0);
}
async function dbRecordSpend({ personaId, sessionId, usdc, tool, toAddress, signature }) {
await ensureSchema();
await sql`
insert into persona_wallet_spend_events (persona_id, session_id, usdc, tool, to_address, signature)
values (${personaId}, ${sessionId}, ${usdc}, ${tool}, ${toAddress || null}, ${signature || null})
`;
}
/**
* Atomic reserve: one statement sums the bucket and inserts the pending row only
* when the total stays within the cap, so concurrent callers cannot all pass a
* stale read. Returns true when the row was inserted.
*/
async function dbReserve({ personaId, sessionId, usdc, tool, toAddress, rid, cap }) {
await ensureSchema();
const rows = await sql`
insert into persona_wallet_spend_events (persona_id, session_id, usdc, tool, to_address, signature)
select ${personaId}, ${sessionId}, ${usdc}, ${tool}, ${toAddress || null}, ${PENDING + rid}
where (
select coalesce(sum(usdc), 0)::float8
from persona_wallet_spend_events
where persona_id = ${personaId} and session_id = ${sessionId}
) + ${usdc} <= ${cap}
returning id
`;
return rows.length > 0;
}
async function dbFinalize(rid, signature) {
await ensureSchema();
await sql`update persona_wallet_spend_events set signature = ${signature || null} where signature = ${PENDING + rid}`;
}
async function dbRelease(rid) {
await ensureSchema();
await sql`delete from persona_wallet_spend_events where signature = ${PENDING + rid}`;
}
// ── filesystem backend (local/dev/test fallback) ──────────────────────────────
function storeDir() {
return process.env.PERSONA_SPEND_STORE_DIR || path.join(process.cwd(), '.data', 'persona-spend');
}
async function fsDir() {
const dir = storeDir();
try {
await fs.mkdir(dir, { recursive: true });
return dir;
} catch {
const tmp = path.join(os.tmpdir(), 'threews-persona-spend');
await fs.mkdir(tmp, { recursive: true });
return tmp;
}
}
function fsKey(personaId, sessionId) {
// Both ids are already constrained (persona_id regex, session_id clamped
// below), but slice+strip defensively before it touches a filename.
const safe = (s) => String(s).replace(/[^A-Za-z0-9_.:-]/g, '_').slice(0, 120);
return `${safe(personaId)}__${safe(sessionId)}.json`;
}
async function fsFile(personaId, sessionId) {
return path.join(await fsDir(), fsKey(personaId, sessionId));
}
async function fsSessionEvents(personaId, sessionId) {
try {
const raw = await fs.readFile(await fsFile(personaId, sessionId), 'utf8');
const parsed = JSON.parse(raw);
return Array.isArray(parsed) ? parsed : [];
} catch {
return [];
}
}
async function fsRecordSpend({ personaId, sessionId, usdc, tool, toAddress, signature }) {
const events = await fsSessionEvents(personaId, sessionId);
events.push({ usdc, tool, to_address: toAddress || null, signature: signature || null, created_at: new Date().toISOString() });
await fs.writeFile(await fsFile(personaId, sessionId), JSON.stringify(events, null, 2), 'utf8');
}
// Serialises the read-modify-write on the fs backend inside one process.
let _fsLock = Promise.resolve();
function withFsLock(fn) {
const run = _fsLock.then(fn, fn);
_fsLock = run.catch(() => {});
return run;
}
async function fsReserve({ personaId, sessionId, usdc, tool, toAddress, rid, cap }) {
return withFsLock(async () => {
const events = await fsSessionEvents(personaId, sessionId);
const total = events.reduce((sum, e) => sum + Number(e.usdc || 0), 0);
if (total + usdc > cap) return false;
events.push({ usdc, tool, to_address: toAddress || null, signature: PENDING + rid, created_at: new Date().toISOString() });
await fs.writeFile(await fsFile(personaId, sessionId), JSON.stringify(events, null, 2), 'utf8');
return true;
});
}
async function fsRewrite(personaId, sessionId, rid, mutate) {
return withFsLock(async () => {
const events = await fsSessionEvents(personaId, sessionId);
const next = mutate(events, PENDING + rid);
await fs.writeFile(await fsFile(personaId, sessionId), JSON.stringify(next, null, 2), 'utf8');
});
}
// ── public API ────────────────────────────────────────────────────────────────
/** Sum of USDC already spent in this persona+session, real data either backend. */
export async function sessionSpentUsdc(personaId, sessionId) {
if (dbConfigured()) return dbSessionTotal(personaId, sessionId);
const events = await fsSessionEvents(personaId, sessionId);
return events.reduce((sum, e) => sum + Number(e.usdc || 0), 0);
}
/**
* Check every guardrail BEFORE a transfer is signed. Returns
* `{ ok: true }` when the call may proceed, or `{ ok: false, code, message, ... }`
* describing exactly which cap blocked it — never throws, so a handler can
* return the refusal directly as a designed result.
*/
export async function checkPersonaSpend({ personaId, sessionId, usdc }) {
const amount = Number(usdc);
if (!(amount > 0)) {
return { ok: false, code: 'invalid_amount', message: 'Amount must be a positive number of USDC.' };
}
if (amount > PERSONA_SPEND_CAPS.maxPerCallUsdc) {
return {
ok: false,
code: 'over_call_cap',
message: `$${amount} exceeds the per-call cap of $${PERSONA_SPEND_CAPS.maxPerCallUsdc} USDC.`,
cap_usdc: PERSONA_SPEND_CAPS.maxPerCallUsdc,
};
}
// The session id is caller-chosen, so a fresh one must not reset the cap:
// every spend is also booked to the persona's UTC-day bucket, and that
// bucket is held to the same ceiling whatever session_id the caller sends.
const daily = await sessionSpentUsdc(personaId, defaultSessionId(personaId));
const spent = Math.max(await sessionSpentUsdc(personaId, sessionId), daily);
if (spent + amount > PERSONA_SPEND_CAPS.maxPerSessionUsdc) {
return {
ok: false,
code: 'over_session_cap',
message: `This session has already spent $${spent.toFixed(4)} of its $${PERSONA_SPEND_CAPS.maxPerSessionUsdc} USDC cap — $${amount} would exceed it.`,
cap_usdc: PERSONA_SPEND_CAPS.maxPerSessionUsdc,
spent_usdc: spent,
};
}
return { ok: true, spent_usdc: spent, remaining_usdc: PERSONA_SPEND_CAPS.maxPerSessionUsdc - spent - amount };
}
/** Record a SETTLED spend (call only after the on-chain transfer confirms). */
export async function recordPersonaSpend({ personaId, sessionId, usdc, tool, toAddress, signature }) {
const row = { personaId, sessionId, usdc: Number(usdc), tool, toAddress, signature };
const record = dbConfigured() ? dbRecordSpend : fsRecordSpend;
await record(row);
const dailyId = defaultSessionId(personaId);
if (sessionId !== dailyId) await record({ ...row, sessionId: dailyId });
}
/**
* Check the caps AND book the spend in one atomic step, before anything is
* signed. A failed transfer must call `releasePersonaSpend`; a settled one calls
* `finalizePersonaSpend`. Because the pending row counts toward both the session
* and the UTC-day bucket immediately, parallel calls cannot each pass a stale
* read of the total. Returns `{ ok: true, reservation }` or a refusal shaped
* like `checkPersonaSpend`'s.
*/
export async function reservePersonaSpend({ personaId, sessionId, usdc, tool, toAddress }) {
const gate = await checkPersonaSpend({ personaId, sessionId, usdc });
if (!gate.ok) return gate;
const amount = Number(usdc);
const cap = PERSONA_SPEND_CAPS.maxPerSessionUsdc;
const rid = randomUUID();
const dailyId = defaultSessionId(personaId);
const buckets = sessionId === dailyId ? [sessionId] : [sessionId, dailyId];
const reserve = dbConfigured() ? dbReserve : fsReserve;
const booked = [];
for (const bucket of buckets) {
const ok = await reserve({ personaId, sessionId: bucket, usdc: amount, tool, toAddress, rid, cap });
if (!ok) {
await releasePersonaSpend({ personaId, rid, buckets: booked });
return {
ok: false,
code: 'over_session_cap',
message: `This session has already reached its $${cap} USDC cap, so $${amount} would exceed it.`,
cap_usdc: cap,
};
}
booked.push(bucket);
}
return { ok: true, spent_usdc: gate.spent_usdc, reservation: { personaId, rid, buckets: booked } };
}
/** Attach the settled signature to a reservation. The spend stays counted either way. */
export async function finalizePersonaSpend({ personaId, rid, buckets }, signature) {
if (dbConfigured()) return dbFinalize(rid, signature);
for (const bucket of buckets) {
await fsRewrite(personaId, bucket, rid, (events, marker) =>
events.map((e) => (e.signature === marker ? { ...e, signature: signature || null } : e)));
}
}
/** Void a reservation whose transfer never settled. */
export async function releasePersonaSpend({ personaId, rid, buckets }) {
if (dbConfigured()) return dbRelease(rid);
for (const bucket of buckets) {
await fsRewrite(personaId, bucket, rid, (events, marker) => events.filter((e) => e.signature !== marker));
}
}