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
/**
* SpendGuard - Per-Agent Spend Envelope + Token/Target Firewall + Custody Reconciliation
*
* The quantitative money-safety layer that `PermissionGuard`, `CapabilityGuard`, and
* `DeFiGuard` do not encode. Where `DeFiGuard` scores *risk* and enforces *per-user tier*
* limits, `SpendGuard` enforces a hard **per-agent spend envelope**:
*
* 1. **Per-tx maximum** - a single outflow may never exceed `perTxMaxUsd`.
* 2. **Rolling / daily caps** - cumulative outflow over a rolling window (default 24h) may
* never exceed `rollingMaxUsd` / `dailyMaxUsd`. This is a true sliding window, not a
* calendar-day bucket.
* 3. **Reserve floor** - a transaction may not drain the agent wallet below `reserveFloorUsd`.
* 4. **Token/target firewall** - an allow/deny layer keyed by token *and* destination, with a
* strict mode that blocks anything not on the allowlist.
* 5. **Custody reconciliation** - sums the *actual* on-chain outflow (independently observed)
* against the outflow the agent *recorded* in the Task 03 tamper-evident ledger; if the
* chain moved more than the ledger recorded, that is a breach (key-compromise signal) and
* the guard **latches shut** for that agent until explicitly reset.
*
* Ported from three.ws `economy-master.js` (reserve/per-run/per-target guards + registry
* allowlist). The Solana multi-wallet funding topology is intentionally NOT ported - only the
* guard envelope. Custody here is EVM (Plutus ERC-4337).
*
* ── Design contract ──
* - **Pure & deterministic.** `check()` has no side effects and, for a fixed clock, always
* returns the same decision for the same inputs (runtime rule #4). Spend is only mutated by
* the explicit `recordSpend()` call, made *after* a transaction actually lands.
* - **DB-agnostic.** Per-agent config is resolved server-side (from `agent_spend_limits`) and
* passed in; the ledger totals for reconciliation are injected via a `SpendLedgerReader`.
* The runtime package never imports the database, exactly like `PermissionGuard`.
*/
import { debuglog } from 'node:util';
const log = debuglog('three-ws-agent-runtime-spend-guard');
const DEFAULT_ROLLING_WINDOW_MS = 24 * 60 * 60 * 1000; // 24h
const DAILY_WINDOW_MS = 24 * 60 * 60 * 1000;
/** Absolute USD epsilon to absorb float noise in comparisons. */
const USD_EPSILON = 0.01;
function usd(n) {
return `$${n.toLocaleString(undefined, { maximumFractionDigits: 2 })}`;
}
function normToken(t) {
return (t ?? '').trim().toUpperCase();
}
function normAddr(a) {
return (a ?? '').trim().toLowerCase();
}
// ============================================================================
// SpendGuard
// ============================================================================
export class SpendGuard {
config;
denyTokens;
allowTokens;
denyDests;
allowDests;
now;
/** Per-agent rolling spend log (agentId → entries). */
spendLog = new Map();
/** Per-agent breach latch. Once set, every check for that agent is blocked. */
tripped = new Map();
/**
* @param config Per-agent spend envelope, resolved server-side from `agent_spend_limits`.
* @param opts.now Injectable clock (defaults to `Date.now`) - keeps rolling-window tests
* deterministic without touching real time.
*/
constructor(config = {}, opts = {}) {
this.config = config;
this.now = opts.now ?? (() => Date.now());
const fw = config.firewall ?? {};
this.denyTokens = new Set((fw.denyTokens ?? []).map(normToken));
this.allowTokens = new Set((fw.allowTokens ?? []).map(normToken));
this.denyDests = new Set((fw.denyDestinations ?? []).map(normAddr));
this.allowDests = new Set((fw.allowDestinations ?? []).map(normAddr));
}
// ── Core check ───────────────────────────────────────────────────────────
/**
* Evaluate a single outflow against the full envelope. Pure - no state mutation.
*
* Order is fixed (hardest / most-specific block first) so the returned code is deterministic:
* breach latch → firewall deny → firewall strict allowlist → per-tx cap → reserve floor →
* rolling cap → daily cap.
*/
check(tx) {
// 0. Breach latch - a reconciliation breach blocks everything until reset.
const trip = this.tripped.get(tx.agentId);
if (trip) {
return { allowed: false, code: trip.code, reason: trip.reason };
}
const token = normToken(tx.token);
const dest = normAddr(tx.destination);
const fw = this.config.firewall;
// 1. Firewall deny lists (always enforced).
if (token && this.denyTokens.has(token)) {
return {
allowed: false,
code: 'FIREWALL_DENY_TOKEN',
reason: `Token ${token} is on the deny firewall for this agent`,
};
}
if (dest && this.denyDests.has(dest)) {
return {
allowed: false,
code: 'FIREWALL_DENY_DEST',
reason: `Destination ${dest} is on the deny firewall for this agent`,
};
}
// 2. Firewall strict allowlist - anything not explicitly allowed is blocked.
if (fw?.strictMode) {
if (this.allowTokens.size > 0 && !(token && this.allowTokens.has(token))) {
return {
allowed: false,
code: 'FIREWALL_NOT_ALLOWED',
reason: `Token ${token || '(unknown)'} is not on the strict-mode allowlist`,
};
}
if (this.allowDests.size > 0 && !(dest && this.allowDests.has(dest))) {
return {
allowed: false,
code: 'FIREWALL_NOT_ALLOWED',
reason: `Destination ${dest || '(unknown)'} is not on the strict-mode allowlist`,
};
}
}
// 3. Per-transaction maximum.
if (this.config.perTxMaxUsd != null && tx.valueUsd > this.config.perTxMaxUsd + USD_EPSILON) {
return {
allowed: false,
code: 'CAP_PER_TX',
reason: `Transaction ${usd(tx.valueUsd)} exceeds per-transaction maximum of ${usd(this.config.perTxMaxUsd)}`,
};
}
// 4. Reserve floor - must not drain the wallet below the configured minimum.
if (this.config.reserveFloorUsd != null &&
tx.balanceUsd != null &&
tx.balanceUsd - tx.valueUsd < this.config.reserveFloorUsd - USD_EPSILON) {
return {
allowed: false,
code: 'RESERVE_FLOOR',
reason: `Transaction ${usd(tx.valueUsd)} would drain balance ${usd(tx.balanceUsd)} below the reserve floor of ${usd(this.config.reserveFloorUsd)}`,
};
}
// 5. Rolling-window cap.
let remainingRollingUsd;
if (this.config.rollingMaxUsd != null) {
const windowMs = this.config.rollingWindowMs ?? DEFAULT_ROLLING_WINDOW_MS;
const spent = this.windowSpend(tx.agentId, windowMs);
remainingRollingUsd = Math.max(0, this.config.rollingMaxUsd - spent - tx.valueUsd);
if (spent + tx.valueUsd > this.config.rollingMaxUsd + USD_EPSILON) {
return {
allowed: false,
code: 'CAP_ROLLING',
reason: `Transaction ${usd(tx.valueUsd)} would exceed the rolling spend cap of ${usd(this.config.rollingMaxUsd)} (already spent ${usd(spent)} in the last ${Math.round(windowMs / 3_600_000)}h)`,
remainingRollingUsd,
};
}
}
// 6. Daily (rolling 24h) cap.
let remainingDailyUsd;
if (this.config.dailyMaxUsd != null) {
const spent = this.windowSpend(tx.agentId, DAILY_WINDOW_MS);
remainingDailyUsd = Math.max(0, this.config.dailyMaxUsd - spent - tx.valueUsd);
if (spent + tx.valueUsd > this.config.dailyMaxUsd + USD_EPSILON) {
return {
allowed: false,
code: 'CAP_DAILY',
reason: `Transaction ${usd(tx.valueUsd)} would exceed the daily spend cap of ${usd(this.config.dailyMaxUsd)} (already spent ${usd(spent)} today)`,
remainingDailyUsd,
};
}
}
return {
allowed: true,
reason: 'Within spend envelope',
remainingDailyUsd,
remainingRollingUsd,
};
}
// ── Spend recording ────────────────────────────────────────────────────────
/**
* Record an outflow that actually landed. Call this AFTER a transaction succeeds so the
* rolling/daily windows stay live within a multi-step plan. Never call it for a blocked or
* failed transaction.
*/
recordSpend(agentId, valueUsd, ts = this.now()) {
if (!agentId || !(valueUsd > 0))
return;
const entries = this.spendLog.get(agentId) ?? [];
entries.push({ ts, valueUsd });
this.spendLog.set(agentId, entries);
// Opportunistically prune anything older than the widest window we track.
this.prune(agentId, Math.max(this.config.rollingWindowMs ?? 0, DAILY_WINDOW_MS));
}
/**
* Seed the rolling window from a persisted total (e.g. confirmed outflow summed from the
* ledger) so the in-memory tracker survives a cold start. Recorded as a single entry at the
* current time; only raises the tracked total, never lowers it.
*/
syncSpendFromLedger(agentId, confirmedRollingUsd, windowMs) {
if (!agentId || !(confirmedRollingUsd > 0))
return;
const w = windowMs ?? this.config.rollingWindowMs ?? DEFAULT_ROLLING_WINDOW_MS;
const current = this.windowSpend(agentId, w);
const delta = confirmedRollingUsd - current;
if (delta > 0)
this.recordSpend(agentId, delta);
}
/** Cumulative recorded spend for an agent over the last `windowMs`. */
windowSpend(agentId, windowMs) {
const entries = this.spendLog.get(agentId);
if (!entries || entries.length === 0)
return 0;
const cutoff = this.now() - windowMs;
let total = 0;
for (const e of entries) {
if (e.ts >= cutoff)
total += e.valueUsd;
}
return total;
}
/** Remaining allowance under the daily cap for an agent (Infinity if uncapped). */
remainingDaily(agentId) {
if (this.config.dailyMaxUsd == null)
return Infinity;
return Math.max(0, this.config.dailyMaxUsd - this.windowSpend(agentId, DAILY_WINDOW_MS));
}
// ── Reconciliation / custody audit ──────────────────────────────────────────
/**
* Compare recorded vs. observed outflow. If the chain moved more than the ledger recorded
* (beyond `breachTolerance`), the agent is **latched shut**: every subsequent `check()`
* returns a `BREACH` block until `reset(agentId)` is called. This is the key-compromise
* signal from the source `economy-reconcile` cron.
*/
reconcile(agentId, figures) {
const tolerance = this.config.breachTolerance ?? 0;
const ceiling = figures.ledgerRecordedUsd * (1 + tolerance);
const unrecorded = figures.onChainOutflowUsd - figures.ledgerRecordedUsd;
if (figures.onChainOutflowUsd > ceiling + Math.max(USD_EPSILON, 0)) {
const reason = `Custody breach: on-chain outflow ${usd(figures.onChainOutflowUsd)} exceeds ledger-recorded outflow ${usd(figures.ledgerRecordedUsd)} by ${usd(unrecorded)} - agent spending latched until reviewed`;
this.tripped.set(agentId, { code: 'BREACH', reason });
log('BREACH agent=%s unrecorded=%d', agentId, unrecorded);
return { breach: true, reason, unrecordedUsd: unrecorded };
}
return {
breach: false,
reason: 'On-chain outflow matches recorded ledger within tolerance',
unrecordedUsd: Math.max(0, unrecorded),
};
}
/** Reconcile using an injected ledger reader (e.g. wired to the Task 03 ledger). */
async reconcileFromLedger(agentId, reader, userId) {
const figures = await reader({ agentId, userId });
return this.reconcile(agentId, figures);
}
/** Whether an agent is currently latched shut by a breach. */
isTripped(agentId) {
return this.tripped.has(agentId);
}
// ── Lifecycle ───────────────────────────────────────────────────────────────
/** Clear the breach latch and spend window for an agent (or all agents if omitted). */
reset(agentId) {
if (agentId) {
this.tripped.delete(agentId);
this.spendLog.delete(agentId);
}
else {
this.tripped.clear();
this.spendLog.clear();
}
}
prune(agentId, windowMs) {
const entries = this.spendLog.get(agentId);
if (!entries)
return;
const cutoff = this.now() - windowMs;
const kept = entries.filter((e) => e.ts >= cutoff);
if (kept.length !== entries.length)
this.spendLog.set(agentId, kept);
}
}