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
// Per-agent spend guardrails + custody ledger — the single policy that governs
// every outbound movement of a custodial agent wallet's funds.
//
// One policy, enforced everywhere:
// - withdraw (api/agents/solana-wallet.js handleWithdraw)
// - x402 pay (api/x402-pay.js)
// - snipe (workers/agent-sniper/executor.js)
// - trade (the authenticated agent-wallet trade endpoint — calls these)
//
// Limits are stored on the agent row at meta.spend_limits and are opt-in: an
// unset ceiling (null) means "no global cap" so existing automated flows keep
// their own per-feature caps until an owner tightens the policy. Once an owner
// sets a ceiling it is a HARD limit applied uniformly across all four paths.
//
// daily_usd rolling-24h total USD-equivalent outflow ceiling
// per_tx_usd max USD-equivalent for any single outbound tx
// per_counterparty_daily_usd rolling-24h ceiling PER recipient/payee
// withdraw_allowlist if non-empty, withdraws may only target these addresses
//
// Spends are recorded into agent_custody_events (the audit trail + ledger). The
// daily ceiling is enforced by summing the last 24h of priced spend rows. SOL
// and USDC are always priceable; an arbitrary SPL withdraw that we can't price
// is governed by the allowlist (+ the per-user withdraw rate limit) rather than
// the USD cap — withdraw is an owner-initiated recovery path, not an autonomous
// spend, so we never block the owner from sweeping their own funds out.
import { PublicKey } from '@solana/web3.js';
import { sql } from './db.js';
import { runLocked } from './locked-sql.js';
import { solUsdPrice } from './avatar-wallet.js';
import { logAudit } from './audit.js';
// The capped-burner tiers: how much the agent may sign alone before the owner
// must confirm. Pure, shared with the browser policy editor's live preview.
import { normalizeBurnerPolicy, classifyBurnerSpend, validateBurnerPolicy, burnerEnabled } from './burner-tier.js';
// The destination whitelist: cooldown-gated allowlist for every outbound category.
import { evaluateDestination } from './destination-whitelist.js';
// Sweeper-bot heuristic for owner-typed withdraw destinations: an injected
// connection (this platform's own failover chain) backs a read-only check, see
// api/_lib/burned-destination.js.
import { checkBurnedDestination } from './burned-destination.js';
import { solanaConnection } from './agent-pumpfun.js';
// The wallet's behavioral immune system — an additive anomaly predicate layered on
// top of the static caps in this file. See api/_lib/anomaly-events.js +
// api/_lib/wallet-anomaly.js. Only referenced inside function bodies, so the
// mutual import with that module resolves fine at call time.
import { guardOutboundAnomaly } from './anomaly-events.js';
// Natural-language spend policies: the LLM authors the rule document, this pure,
// total evaluator enforces it. Layered ON TOP of the numeric caps below — never
// weakening them. See api/_lib/spend-policy-rules.js.
import {
getPolicyRules, normalizePolicyRules, evaluatePolicy, isDenied,
referencedFields, describePolicyRules, diffPolicies,
} from './spend-policy-rules.js';
// Scoped session keys (least-privilege capabilities). Imported for the additive
// capability gate composed into enforceSpendLimit / reserveSpendUsd below. The
// import is circular (wallet-capabilities imports recordCustodyEvent from here);
// safe because both sides only touch the bindings at runtime, never at module eval.
import {
evaluateCapabilityScope, capabilityError, capabilitySpentUsd, checkAggregate,
resolveCapabilityForSpend, reserveCapabilitySpend,
} from './wallet-capabilities.js';
// Base58 alphabet, 32–44 chars covers every ed25519 pubkey. A cheap pre-filter
// before the (heavier) PublicKey parse + curve check.
const BASE58_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
const MAX_ALLOWLIST = 50;
// Fee + rent headroom kept above a buy so it never fails for lack of lamports to
// pay the network fee / open the token ATA. The single source of truth for the
// SOL-headroom floor — both the sniper executor and the discretionary
// agent-wallet trade endpoint import this rather than redefining it.
export const SOL_FEE_HEADROOM_LAMPORTS = 3_000_000n; // ~0.003 SOL
// Rent-exempt minimum of the SPL token account a buy opens. Not optional and not
// recoverable until the position closes, so any floor that ignores it is wrong.
export const ATA_RENT_LAMPORTS = 2_039_280n;
// What an entry costs BESIDES the buy itself: fee headroom + the token ATA's rent
// + room for a priority fee and an MEV tip. A wallet holding only `size` cannot
// actually buy `size`.
export const ENTRY_HEADROOM_LAMPORTS = SOL_FEE_HEADROOM_LAMPORTS + ATA_RENT_LAMPORTS + 1_000_000n;
// The least SOL an agent wallet can hold and still complete ONE trade end to end:
// the entry overhead above, plus the firewall's round-trip probe reserve (it
// simulates a real buy AND sell from this wallet), plus a minimum entry. Below
// this a wallet looks funded and is operationally dead — every buy aborts at the
// safety simulation it cannot afford to run.
//
// This is the number every system that MOVES SOL OUT of a trading wallet must
// respect. It exists because two subsystems disagreed about it: the economy's
// idle-capital reclaim kept `per_trade × 2` (as little as 0.004 SOL) while the
// executor needed ~0.012 to place that same trade, so reclaim could strip an
// enabled arm to a balance that could never buy anything.
export const MIN_OPERATIONAL_WALLET_SOL = 0.012;
export const SPEND_LIMIT_DEFAULTS = Object.freeze({
daily_usd: null,
per_tx_usd: null,
// Rolling-24h ceiling on what this agent may send to ONE counterparty (the
// on-chain payee for a trade/x402/a2a payment, the recipient address for a
// withdraw). The wallet-wide `daily_usd` cap bounds total damage; this one
// bounds concentrated damage, which is the shape an autonomous agent actually
// fails in: a peer that reprices upward every call, or a compromised endpoint
// the agent keeps paying, drains the whole daily budget into one address while
// every individual payment stays under `per_tx_usd`. Null means no per-payee
// cap (unchanged behavior for wallets that never set one).
per_counterparty_daily_usd: null,
// Above this USD amount, an autonomous outbound payment (x402, a2a hire) does
// not execute inline: it is parked as an approval request and the owner must
// approve it before the agent's poll receives a one-time execution grant. Null
// means no threshold (unchanged behavior for every wallet that never sets one).
approval_threshold_usd: null,
withdraw_allowlist: [],
// Wallet freeze / kill switch. When true, every AUTONOMOUS outbound path
// (trade, snipe, x402) is rejected immediately. The owner's own withdraw is
// deliberately NOT blocked — a freeze must never trap the owner's funds; the
// safe direction (sweeping out) stays open so a freeze can be used to lock down
// a misbehaving agent while still evacuating its balance.
frozen: false,
// Least-privilege enforcement. When true, every AUTONOMOUS outbound path
// (trade, snipe, x402) must present a valid, unexpired, unrevoked scoped
// capability that covers the action — no covering capability ⇒ deny (fail
// safe). When false (default), capabilities still STRICTLY NARROW any spend
// that presents one, but an autonomous spend without a capability is governed
// by the wallet-wide policy alone (preserves existing automated flows). See
// api/_lib/wallet-capabilities.js. Owner withdraw is never a delegated
// capability and is unaffected by this flag.
require_capabilities: false,
});
// Per-agent discretionary-trade policy (lamports-denominated), stored at
// agent_identities.meta.trade_limits. Distinct from meta.spend_limits (the
// cross-path USD ceiling): these are the SOL-budget + circuit-breaker knobs that
// govern the agent's own buys, mirroring the sniper's per-strategy caps so the
// discretionary path is held to the same standard. All opt-in — a null cap means
// "no lamports ceiling" and the trade is still governed by the USD spend policy
// and the wallet balance.
//
// per_trade_sol max SOL spent on any single buy (null = uncapped)
// daily_budget_sol rolling-24h SOL buy budget across trade + snipe (null = uncapped)
// max_price_impact_pct circuit breaker — reject a buy/sell over this impact
// max_slippage_bps ceiling on the client-supplied slippage
// max_concurrent max open discretionary positions (null = unlimited)
// kill_switch when true, every discretionary trade is rejected
// max_insider_pct refuse a buy when creator-linked holders own more than this % of supply
// max_sniper_pct refuse a buy when launch-slot snipers own more than this % of supply
// max_bundler_pct refuse a buy when bundled (shared-funder) holders own more than this % of supply
// max_fresh_wallet_pct refuse a buy when fresh wallets own more than this % of supply
// (the four holder limits read token_due_diligence; null = not checked)
export const TRADE_LIMIT_DEFAULTS = Object.freeze({
per_trade_sol: null,
daily_budget_sol: null,
max_price_impact_pct: 15,
max_slippage_bps: 1000,
max_concurrent: null,
kill_switch: false,
max_insider_pct: null,
max_sniper_pct: null,
max_bundler_pct: null,
max_fresh_wallet_pct: null,
});
/**
* A spend-policy breach. Always a structured 4xx (never a 500) so the boundary
* can surface the reason to the user verbatim. `.code` is machine-readable;
* `.detail` carries the numbers behind the decision for the UI.
*/
export class SpendLimitError extends Error {
constructor(code, message, detail = {}) {
super(message);
this.name = 'SpendLimitError';
this.status = 403;
this.code = code;
this.detail = detail;
}
}
/**
* Validate a Solana destination address.
* @returns {{ valid: boolean, reason?: string, base58?: string, pubkey?: PublicKey, onCurve?: boolean }}
*/
export function validateSolanaAddress(addr) {
const s = typeof addr === 'string' ? addr.trim() : '';
if (!s) return { valid: false, reason: 'empty' };
if (!BASE58_RE.test(s)) return { valid: false, reason: 'not_base58' };
let pubkey;
try {
pubkey = new PublicKey(s);
} catch {
return { valid: false, reason: 'not_pubkey' };
}
// Off-curve addresses are program-derived (PDAs) and usually cannot sign or
// be swept again — sending custody funds there risks losing them. We surface
// `onCurve` so the withdraw endpoint can refuse a PDA destination.
let onCurve = false;
try {
onCurve = PublicKey.isOnCurve(pubkey.toBytes());
} catch {
onCurve = false;
}
return { valid: true, base58: pubkey.toBase58(), pubkey, onCurve };
}
function numOrNull(v) {
if (v === null || v === undefined || v === '') return null;
const n = Number(v);
if (!Number.isFinite(n) || n < 0) return null;
return n;
}
/** Coerce arbitrary input into a clean, bounded spend-limit object. */
export function normalizeSpendLimits(raw) {
const r = raw && typeof raw === 'object' ? raw : {};
const allow = (Array.isArray(r.withdraw_allowlist) ? r.withdraw_allowlist : [])
.map((a) => (typeof a === 'string' ? a.trim() : ''))
.map((a) => validateSolanaAddress(a))
.filter((v) => v.valid)
.map((v) => v.base58);
// De-dupe while preserving order, cap the list so meta can't be bloated.
const seen = new Set();
const deduped = [];
for (const a of allow) {
if (!seen.has(a)) {
seen.add(a);
deduped.push(a);
}
if (deduped.length >= MAX_ALLOWLIST) break;
}
return {
daily_usd: numOrNull(r.daily_usd),
per_tx_usd: numOrNull(r.per_tx_usd),
per_counterparty_daily_usd: numOrNull(r.per_counterparty_daily_usd),
approval_threshold_usd: numOrNull(r.approval_threshold_usd),
withdraw_allowlist: deduped,
frozen: r.frozen === true,
require_capabilities: r.require_capabilities === true,
updated_at: typeof r.updated_at === 'string' ? r.updated_at : null,
};
}
/** Read the effective spend limits off an agent's meta blob. */
export function getSpendLimits(meta) {
return normalizeSpendLimits(meta?.spend_limits);
}
/**
* Persist a spend-limit patch onto the agent (owner-only). Only the keys present
* in `patch` are changed; the rest are preserved. Writes a custody audit event
* and a platform audit-log row. Returns the new normalized limits.
*/
export async function setSpendLimits(agentId, userId, patch, { req = null } = {}) {
const [row] = await sql`
SELECT id, user_id, meta FROM agent_identities
WHERE id = ${agentId} AND deleted_at IS NULL
`;
if (!row) throw Object.assign(new Error('agent not found'), { status: 404, code: 'not_found' });
if (row.user_id !== userId) throw Object.assign(new Error('not your agent'), { status: 403, code: 'forbidden' });
const prev = getSpendLimits(row.meta);
const next = normalizeSpendLimits({
daily_usd: 'daily_usd' in patch ? patch.daily_usd : prev.daily_usd,
per_tx_usd: 'per_tx_usd' in patch ? patch.per_tx_usd : prev.per_tx_usd,
per_counterparty_daily_usd:
'per_counterparty_daily_usd' in patch
? patch.per_counterparty_daily_usd
: prev.per_counterparty_daily_usd,
approval_threshold_usd:
'approval_threshold_usd' in patch ? patch.approval_threshold_usd : prev.approval_threshold_usd,
// The allowlist lives in destination_whitelist_entries now, where a new
// address serves a cooldown (api/_lib/destination-whitelist.js). A patch can
// no longer write it through here, so no path can skip the cooldown by
// editing the limits blob.
withdraw_allowlist: prev.withdraw_allowlist,
frozen: 'frozen' in patch ? patch.frozen === true : prev.frozen,
require_capabilities:
'require_capabilities' in patch ? patch.require_capabilities === true : prev.require_capabilities,
});
next.updated_at = new Date().toISOString();
const meta = { ...(row.meta || {}), spend_limits: next };
await sql`UPDATE agent_identities SET meta = ${JSON.stringify(meta)}::jsonb WHERE id = ${agentId}`;
await recordCustodyEvent({
agentId,
userId,
eventType: 'limit_change',
reason: 'spend_limits_updated',
meta: { prev, next },
}).catch((e) => console.warn('[custody] limit_change record failed', e?.message));
logAudit({ userId, action: 'custody.limit_change', resourceId: agentId, meta: { prev, next }, req });
return next;
}
/** USD value of a lamports amount at the live SOL/USD price. Throws on price outage. */
export async function lamportsToUsd(lamports) {
const price = await solUsdPrice();
return (Number(lamports) / 1e9) * price;
}
// ── discretionary trade limits ────────────────────────────────────────────────
function clampNum(v, def, { min = 0, max = Infinity, round = false } = {}) {
const n = Number(v);
if (!Number.isFinite(n) || n < min) return def;
const c = Math.min(max, n);
return round ? Math.round(c) : c;
}
function pctCapOrNull(v) {
if (v == null || v === '') return null;
const n = Number(v);
return Number.isFinite(n) && n >= 0 && n <= 100 ? n : null;
}
/** Coerce arbitrary input into a clean, bounded trade-limit object. */
export function normalizeTradeLimits(raw) {
const r = raw && typeof raw === 'object' ? raw : {};
return {
per_trade_sol: numOrNull(r.per_trade_sol),
daily_budget_sol: numOrNull(r.daily_budget_sol),
max_price_impact_pct: clampNum(r.max_price_impact_pct, TRADE_LIMIT_DEFAULTS.max_price_impact_pct, { max: 100 }),
max_slippage_bps: clampNum(r.max_slippage_bps, TRADE_LIMIT_DEFAULTS.max_slippage_bps, { max: 10000, round: true }),
max_concurrent: r.max_concurrent == null ? null : clampNum(r.max_concurrent, null, { min: 1, max: 10000, round: true }),
kill_switch: r.kill_switch === true,
max_insider_pct: pctCapOrNull(r.max_insider_pct),
max_sniper_pct: pctCapOrNull(r.max_sniper_pct),
max_bundler_pct: pctCapOrNull(r.max_bundler_pct),
max_fresh_wallet_pct: pctCapOrNull(r.max_fresh_wallet_pct),
updated_at: typeof r.updated_at === 'string' ? r.updated_at : null,
};
}
/** Read the effective discretionary trade limits off an agent's meta blob. */
export function getTradeLimits(meta) {
return normalizeTradeLimits(meta?.trade_limits);
}
/**
* Persist a trade-limit patch onto the agent (owner-only). Only the keys present
* in `patch` change; the rest are preserved. Writes a custody audit event and a
* platform audit-log row. Returns the new normalized limits.
*/
export async function setTradeLimits(agentId, userId, patch, { req = null } = {}) {
const [row] = await sql`
SELECT id, user_id, meta FROM agent_identities
WHERE id = ${agentId} AND deleted_at IS NULL
`;
if (!row) throw Object.assign(new Error('agent not found'), { status: 404, code: 'not_found' });
if (row.user_id !== userId) throw Object.assign(new Error('not your agent'), { status: 403, code: 'forbidden' });
const prev = getTradeLimits(row.meta);
const p = patch && typeof patch === 'object' ? patch : {};
const next = normalizeTradeLimits({
per_trade_sol: 'per_trade_sol' in p ? p.per_trade_sol : prev.per_trade_sol,
daily_budget_sol: 'daily_budget_sol' in p ? p.daily_budget_sol : prev.daily_budget_sol,
max_price_impact_pct: 'max_price_impact_pct' in p ? p.max_price_impact_pct : prev.max_price_impact_pct,
max_slippage_bps: 'max_slippage_bps' in p ? p.max_slippage_bps : prev.max_slippage_bps,
max_concurrent: 'max_concurrent' in p ? p.max_concurrent : prev.max_concurrent,
kill_switch: 'kill_switch' in p ? p.kill_switch : prev.kill_switch,
max_insider_pct: 'max_insider_pct' in p ? p.max_insider_pct : prev.max_insider_pct,
max_sniper_pct: 'max_sniper_pct' in p ? p.max_sniper_pct : prev.max_sniper_pct,
max_bundler_pct: 'max_bundler_pct' in p ? p.max_bundler_pct : prev.max_bundler_pct,
max_fresh_wallet_pct: 'max_fresh_wallet_pct' in p ? p.max_fresh_wallet_pct : prev.max_fresh_wallet_pct,
});
next.updated_at = new Date().toISOString();
const meta = { ...(row.meta || {}), trade_limits: next };
await sql`UPDATE agent_identities SET meta = ${JSON.stringify(meta)}::jsonb WHERE id = ${agentId}`;
await recordCustodyEvent({
agentId,
userId,
eventType: 'limit_change',
reason: 'trade_limits_updated',
meta: { prev, next },
}).catch((e) => console.warn('[custody] trade limit_change record failed', e?.message));
logAudit({ userId, action: 'custody.trade_limit_change', resourceId: agentId, meta: { prev, next }, req });
return next;
}
// ── prediction-market limits ─────────────────────────────────────────────────
// Stored at agent_identities.meta.prediction_limits. Prediction orders are off
// until the owner turns them on for the agent: `enabled` defaults to false, so
// a fresh agent can browse, research and watch markets but cannot stake. Once
// on, two USD ceilings bound the stake on top of the wallet-wide spend policy
// (which still applies in full, including the freeze and anomaly guard):
//
// max_stake_per_market_usd total USDC at risk in any one market
// max_daily_stake_usd rolling-24h USDC staked across every market
export const PREDICTION_LIMIT_DEFAULTS = Object.freeze({
enabled: false,
max_stake_per_market_usd: 25,
max_daily_stake_usd: 100,
});
const PREDICTION_STAKE_CEILING_USD = 1_000_000;
/** Coerce arbitrary input into clean, bounded prediction limits. */
export function normalizePredictionLimits(raw) {
const r = raw && typeof raw === 'object' ? raw : {};
return {
enabled: r.enabled === true,
max_stake_per_market_usd: clampNum(r.max_stake_per_market_usd, PREDICTION_LIMIT_DEFAULTS.max_stake_per_market_usd, { min: 1, max: PREDICTION_STAKE_CEILING_USD }),
max_daily_stake_usd: clampNum(r.max_daily_stake_usd, PREDICTION_LIMIT_DEFAULTS.max_daily_stake_usd, { min: 1, max: PREDICTION_STAKE_CEILING_USD }),
updated_at: typeof r.updated_at === 'string' ? r.updated_at : null,
};
}
/** Read the effective prediction limits off an agent's meta blob. */
export function getPredictionLimits(meta) {
return normalizePredictionLimits(meta?.prediction_limits);
}
/**
* Persist a prediction-limit patch (owner-only). Keys absent from `patch` keep
* their value. Audited in the custody trail and the platform audit log.
*/
export async function setPredictionLimits(agentId, userId, patch, { req = null } = {}) {
const [row] = await sql`
SELECT id, user_id, meta FROM agent_identities
WHERE id = ${agentId} AND deleted_at IS NULL
`;
if (!row) throw Object.assign(new Error('agent not found'), { status: 404, code: 'not_found' });
if (row.user_id !== userId) throw Object.assign(new Error('not your agent'), { status: 403, code: 'forbidden' });
const prev = getPredictionLimits(row.meta);
const p = patch && typeof patch === 'object' ? patch : {};
const next = normalizePredictionLimits({
enabled: 'enabled' in p ? p.enabled : prev.enabled,
max_stake_per_market_usd: 'max_stake_per_market_usd' in p ? p.max_stake_per_market_usd : prev.max_stake_per_market_usd,
max_daily_stake_usd: 'max_daily_stake_usd' in p ? p.max_daily_stake_usd : prev.max_daily_stake_usd,
});
next.updated_at = new Date().toISOString();
await sql`
UPDATE agent_identities
SET meta = jsonb_set(coalesce(meta, '{}'::jsonb), '{prediction_limits}', ${JSON.stringify(next)}::jsonb)
WHERE id = ${agentId}
`;
await recordCustodyEvent({
agentId,
userId,
eventType: 'limit_change',
reason: 'prediction_limits_updated',
meta: { prev, next },
}).catch((e) => console.warn('[custody] prediction limit_change record failed', e?.message));
logAudit({ userId, action: 'custody.prediction_limit_change', resourceId: agentId, meta: { prev, next }, req });
return next;
}
/**
* Is this stake allowed under the agent's prediction limits? Pure: the caller
* supplies the current exposure in the market and the rolling-24h stake.
* @returns {null | { reason: string, detail: object }}
*/
export function checkPredictionStake({ limits, stakeUsd, marketExposureUsd = 0, dailyStakedUsd = 0 }) {
const lim = normalizePredictionLimits(limits);
const stake = Number(stakeUsd);
if (!lim.enabled) return { reason: 'predictions_disabled', detail: {} };
if (!Number.isFinite(stake) || stake <= 0) return { reason: 'invalid_stake', detail: { stake_usd: stakeUsd } };
const exposure = Math.max(0, Number(marketExposureUsd) || 0);
if (exposure + stake > lim.max_stake_per_market_usd + 1e-9) {
return {
reason: 'market_stake_exceeded',
detail: { stake_usd: stake, exposure_usd: exposure, max_stake_per_market_usd: lim.max_stake_per_market_usd },
};
}
const daily = Math.max(0, Number(dailyStakedUsd) || 0);
if (daily + stake > lim.max_daily_stake_usd + 1e-9) {
return {
reason: 'daily_stake_exceeded',
detail: { stake_usd: stake, staked_today_usd: daily, max_daily_stake_usd: lim.max_daily_stake_usd },
};
}
return null;
}
/**
* USDC staked into prediction markets over the trailing window, optionally for
* one market. Pending rows count: an order in flight is money committed.
*/
export async function getPredictionStakeUsd(agentId, { marketId = null, windowHours = 24 } = {}) {
const [row] = await sql`
SELECT coalesce(sum(usd), 0)::float8 AS usd
FROM agent_custody_events
WHERE agent_id = ${agentId}
AND event_type = 'spend'
AND category = 'prediction'
AND meta->>'prediction_action' = 'open'
AND status IN ('pending', 'confirmed')
AND created_at > now() - make_interval(hours => ${windowHours})
AND (${marketId}::text IS NULL OR meta->>'market_id' = ${marketId})
`;
return Number(row?.usd || 0);
}
// ── trade guard predicates ────────────────────────────────────────────────────
// Each returns null when the trade is allowed, or a structured
// { reason, detail } when blocked. These are the single source of truth for the
// "is this trade allowed" comparisons — the sniper executor and the discretionary
// agent-wallet trade endpoint both call them instead of inlining the math, so a
// cap or breaker can never drift between the two paths. Pure + synchronous: the
// caller fetches the live numbers (open count, daily spend, wallet balance,
// quote) and hands them in.
/** Discretionary trading paused for this agent. */
export function checkKillSwitch(killed) {
return killed ? { reason: 'kill_switch', detail: {} } : null;
}
/** Open-position concurrency ceiling. Blocked when openCount >= maxConcurrent. */
export function checkConcurrency(openCount, maxConcurrent) {
if (maxConcurrent == null) return null;
if (Number(openCount) >= Number(maxConcurrent)) {
return { reason: 'max_positions', detail: { open: Number(openCount), max: Number(maxConcurrent) } };
}
return null;
}
/** Per-trade spend cap (lamports). Blocked when amount > cap. */
export function checkPerTradeCap(amountLamports, capLamports) {
if (capLamports == null) return null;
const amt = BigInt(amountLamports);
const cap = BigInt(capLamports);
if (amt > cap) {
return { reason: 'per_trade_cap', detail: { amount_lamports: amt.toString(), cap_lamports: cap.toString() } };
}
return null;
}
/** Rolling daily budget (lamports). Blocked when spent + amount > budget. */
export function checkDailyBudgetLamports(spentLamports, amountLamports, budgetLamports) {
if (budgetLamports == null) return null;
const spent = BigInt(spentLamports);
const amt = BigInt(amountLamports);
const budget = BigInt(budgetLamports);
if (spent + amt > budget) {
return {
reason: 'daily_budget',
detail: { spent_lamports: spent.toString(), amount_lamports: amt.toString(), budget_lamports: budget.toString() },
};
}
return null;
}
/**
* Realized-loss circuit breaker. Blocked when an agent's NET realized P&L over
* the trailing window is a loss deeper than `lossLimitLamports`.
*
* This is the portfolio-layer guard the per-trade caps (budget, headroom, price
* impact) don't provide: a fleet armed with a valid band can still bleed out one
* losing entry at a time. Once the day's realized loss crosses the limit the
* agent stops opening new positions — and, critically, the auto-funder stops
* refilling it (see workers/agent-sniper/auto-funder.js), so the master wallet
* can't keep pouring SOL after a wallet that only loses. The exact shape of the
* rug-buy + auto-refill incident.
*
* `netRealizedLamports` is SIGNED: negative = net loss, positive = net profit.
* A profitable or break-even day never blocks. `null`/`0` limit disables it.
*
* @param {bigint|string|number} netRealizedLamports signed net realized P&L
* @param {bigint|string|number|null} lossLimitLamports max tolerated loss (positive magnitude)
* @returns {{ reason: string, detail: object }|null}
*/
export function checkDailyLoss(netRealizedLamports, lossLimitLamports) {
if (lossLimitLamports == null) return null;
const limit = BigInt(lossLimitLamports);
if (limit <= 0n) return null;
const net = BigInt(netRealizedLamports);
const loss = net < 0n ? -net : 0n;
if (loss >= limit) {
return {
reason: 'daily_loss_limit',
detail: { loss_lamports: loss.toString(), limit_lamports: limit.toString() },
};
}
return null;
}
/** Wallet must cover the spend plus a fee/rent headroom. Blocked when short. */
export function checkSolHeadroom(walletLamports, spendLamports, headroomLamports = SOL_FEE_HEADROOM_LAMPORTS) {
const wallet = BigInt(walletLamports);
const spend = BigInt(spendLamports);
const head = BigInt(headroomLamports);
if (wallet < spend + head) {
return {
reason: 'insufficient_sol',
detail: { wallet_lamports: wallet.toString(), required_lamports: (spend + head).toString() },
};
}
return null;
}
/**
* Resolve the entry size a wallet can actually trade, or decide it must sit out.
*
* Pure. Two floors apply and they are NOT the same number:
* - `ENTRY_HEADROOM_LAMPORTS` covers the buy's own network fee + the token
* ATA's rent + priority-fee/tip room. It is what the buy itself costs.
* - `MIN_OPERATIONAL_WALLET_SOL` additionally covers the checks that run from
* this wallet BEFORE any broadcast: the firewall's buy→sell round-trip probe
* and the pre-broadcast compute-unit simulation.
*
* A balance above the first floor and below the second looks tradeable and is
* operationally dead: every attempt aborts at a simulation the wallet cannot
* afford to run, so an arm gated only on the first floor re-attempts every
* candidate forever and books a failure each time. Honest behavior is to sit out
* until the auto-funder tops the wallet back up.
*
* Returns `{ sizeLamports }` to trade (possibly shrunk below `wantLamports`), or
* `{ skip: reason }` to sit this candidate out.
*
* @param {bigint|number|string} walletLamports current wallet balance
* @param {bigint|number|string} wantLamports the strategy's configured size
* @param {bigint|number|string} minTradeLamports smallest size worth placing
* @returns {{sizeLamports: bigint, skip?: undefined}|{skip: string, sizeLamports?: undefined}}
*/
export function resolveEntrySize(walletLamports, wantLamports, minTradeLamports) {
const wallet = BigInt(walletLamports);
const want = BigInt(wantLamports);
const minTrade = BigInt(minTradeLamports);
// The operational floor applies to EVERY entry, full size included. It used to
// be checked only on the shrink path, so a small configured size let a wallet
// under the floor through at full size: a 0.002 SOL arm on a 0.00999 SOL wallet
// read "funded" on /api/sniper/status while /api/sniper/experiments (and every
// real attempt) found it dry.
if (wallet < BigInt(Math.round(MIN_OPERATIONAL_WALLET_SOL * 1e9))) {
return { skip: 'insufficient_sol' };
}
const headroom = checkSolHeadroom(wallet, want, ENTRY_HEADROOM_LAMPORTS);
if (!headroom) return { sizeLamports: want };
// Short for the configured size. Shrinking is allowed (learning > profit) from a
// wallet that can still run the pre-broadcast simulations (checked above).
const dustCapable = wallet - ENTRY_HEADROOM_LAMPORTS;
if (dustCapable < minTrade) return { skip: headroom.reason };
return { sizeLamports: dustCapable };
}
/** Price-impact circuit breaker. Blocked when impact > max. */
export function checkPriceImpact(priceImpactPct, maxPct) {
if (maxPct == null) return null;
if (Number(priceImpactPct) > Number(maxPct)) {
return { reason: 'price_impact', detail: { impact_pct: Number(priceImpactPct), max_pct: Number(maxPct) } };
}
return null;
}
const DUE_DILIGENCE_LIMITS = [
['max_insider_pct', 'insider_pct', 'insider hold rate'],
['max_sniper_pct', 'sniper_pct', 'sniper share'],
['max_bundler_pct', 'bundler_pct', 'bundler exposure'],
['max_fresh_wallet_pct', 'fresh_wallet_pct', 'fresh-wallet share'],
];
/**
* Holder-quality breaker over the token_due_diligence fields. Pure: `fields` is
* the report's `fields` object (or null when the report could not be read).
* A limit that is set but cannot be evaluated (no report, or that one field is
* null because chain reads failed) blocks with `due_diligence_unavailable`, so
* a missing read never passes as a clean token. No limit set means no check.
*/
export function checkDueDiligence(fields, limits) {
for (const [limitKey, fieldKey, label] of DUE_DILIGENCE_LIMITS) {
const max = limits?.[limitKey];
if (max == null) continue;
const value = fields?.[fieldKey];
if (value == null) return { reason: 'due_diligence_unavailable', detail: { field: fieldKey, label, max_pct: Number(max) } };
if (Number(value) > Number(max)) return { reason: 'due_diligence', detail: { field: fieldKey, label, value_pct: Number(value), max_pct: Number(max) } };
}
return null;
}
/**
* Async wrapper for the trade endpoints. Fetches the cached report only when an
* owner set at least one holder limit, so agents without limits pay nothing.
* @param {string} mint
* @param {object} limits normalized trade limits
* @param {{ load?: (mint:string)=>Promise<object|null> }} [opts]
*/
export async function guardDueDiligence(mint, limits, { load } = {}) {
if (!mint || !DUE_DILIGENCE_LIMITS.some(([k]) => limits?.[k] != null)) return null;
let report = null;
try {
const loader = load || (async (m) => (await import('./token-due-diligence.js')).getTokenDueDiligence(m));
report = await loader(mint);
} catch {
report = null;
}
return checkDueDiligence(report?.status === 'ok' ? report.fields : null, limits);
}
/** Lamports spent (buys) by an agent over the trailing window — the trade +
* snipe SOL outflow that backs the discretionary daily budget. One wallet, one
* budget: a buy from the sniper and a buy from the trade endpoint both count. */
export async function getDailySpendLamports(agentId, network = 'mainnet', windowHours = 24) {
const [row] = await sql`
SELECT COALESCE(SUM(amount_lamports), 0)::text AS lamports
FROM agent_custody_events
WHERE agent_id = ${agentId}
AND network = ${network}
AND event_type = 'spend'
AND status IN ('ok', 'pending', 'confirmed')
AND amount_lamports IS NOT NULL
AND created_at > now() - (${windowHours} || ' hours')::interval
`;
return BigInt(row?.lamports ?? '0');
}
const LAMPORTS_PER_SOL = 1_000_000_000n;
function lamportsToSolStr(lamports, dp = 4) {
const n = Number(BigInt(lamports)) / 1e9;
return n.toFixed(dp).replace(/\.?0+$/, '') || '0';
}
// Map a guard-predicate reason → an HTTP status + a plain-language, actionable
// message for the boundary. A guard rejection is always a 4xx with the reason and
// the numbers behind it — never a 500, never an exception that escapes.
const GUARD_RESPONSE = {
kill_switch: {
status: 403,
message: () => 'Trading is paused for this agent. Re-enable discretionary trading under Limits & Safety to continue.',
},
per_trade_cap: {
status: 422,
message: (d) => `This trade of ${lamportsToSolStr(d.amount_lamports)} SOL is over the per-trade cap of ${lamportsToSolStr(d.cap_lamports)} SOL. Lower the amount or raise the cap under Limits & Safety.`,
},
daily_budget: {
status: 422,
message: (d) => `This trade would bring today's spend to ${lamportsToSolStr(BigInt(d.spent_lamports) + BigInt(d.amount_lamports))} SOL, over the daily budget of ${lamportsToSolStr(d.budget_lamports)} SOL. Wait for the window to roll over or raise the budget.`,
},
max_positions: {
status: 409,
message: (d) => `This agent already holds ${d.open} open ${d.open === 1 ? 'trade' : 'trades'} (max ${d.max}). Close one before opening another.`,
},
insufficient_sol: {
status: 400,
message: (d) => `The agent wallet needs about ${lamportsToSolStr(d.required_lamports)} SOL (including network fees) but holds ${lamportsToSolStr(d.wallet_lamports)}. Fund the wallet and retry.`,
},
price_impact: {
status: 422,
message: (d) => `Price impact is ${Number(d.impact_pct).toFixed(2)}% — above the ${Number(d.max_pct).toFixed(2)}% safety breaker. Lower the trade size or raise the impact limit under Limits & Safety.`,
},
due_diligence: {
status: 422,
message: (d) => `This token fails your holder-quality limit: ${d.label} is ${Number(d.value_pct).toFixed(1)}% of supply, above your ${Number(d.max_pct).toFixed(1)}% limit. Raise the limit under Limits & Safety or pick another token.`,
},
due_diligence_unavailable: {
status: 422,
message: (d) => `Your ${d.label} limit of ${Number(d.max_pct).toFixed(1)}% could not be checked because the holder data for this token could not be read right now. Retry shortly, or clear the limit under Limits & Safety.`,
},
predictions_disabled: {
status: 403,
message: () => 'Prediction orders are off for this agent. Turn them on under Prediction limits on the agent\'s predictions page to continue.',
},
invalid_stake: {
status: 400,
message: () => 'The stake must be a positive USDC amount.',
},
market_stake_exceeded: {
status: 422,
message: (d) => `This stake of $${Number(d.stake_usd).toFixed(2)} would put $${(Number(d.exposure_usd) + Number(d.stake_usd)).toFixed(2)} at risk in this market, over the per-market limit of $${Number(d.max_stake_per_market_usd).toFixed(2)}. Lower the stake or raise the limit.`,
},
daily_stake_exceeded: {
status: 422,
message: (d) => `This stake would bring today's prediction stakes to $${(Number(d.staked_today_usd) + Number(d.stake_usd)).toFixed(2)}, over the daily limit of $${Number(d.max_daily_stake_usd).toFixed(2)}. Wait for the window to roll over or raise the limit.`,
},
};
/**
* Turn a guard-predicate result into a boundary-ready 4xx response shape.
* @param {{ reason: string, detail?: object }} blocked
* @returns {{ status: number, code: string, message: string, detail: object }}
*/
export function tradeGuardResponse(blocked) {
const entry = GUARD_RESPONSE[blocked.reason] || { status: 422, message: () => `Trade rejected: ${blocked.reason}` };
return {
status: entry.status,
code: blocked.reason,
message: entry.message(blocked.detail || {}),
detail: blocked.detail || {},
};
}
export { LAMPORTS_PER_SOL };
// Re-export the policy-rules reader so routes can treat agent-trade-guards as the
// single barrel for spend/policy helpers (solana-wallet.js imports it from here).
export { getPolicyRules };
/**
* Sum the USD-equivalent of an agent's outbound spends over the trailing window.
* Only priced rows (usd not null) count — see module header on unpriced SPL.
*/
export async function getDailySpendUsd(agentId, network = 'mainnet', windowHours = 24) {
const [row] = await sql`
SELECT COALESCE(SUM(usd), 0)::float8 AS usd
FROM agent_custody_events
WHERE agent_id = ${agentId}
AND network = ${network}
AND event_type = 'spend'
AND status IN ('ok', 'pending', 'confirmed')
AND usd IS NOT NULL
AND created_at > now() - (${windowHours} || ' hours')::interval
`;
return Number(row?.usd || 0);
}
/**
* USD this agent has already sent to ONE counterparty over the trailing window.
* Backs the `per_counterparty_daily_usd` ceiling. `destination` is whatever the
* spending path recorded as the recipient: the on-chain payee for an x402 / a2a
* payment, the withdraw recipient for a sweep. A null/empty destination has no
* counterparty to meter, so it reports 0 and the cap cannot block it.
*/
export async function getCounterpartySpendUsd(
agentId,
destination,
network = 'mainnet',
windowHours = 24,
) {
if (!destination) return 0;
const [row] = await sql`
SELECT COALESCE(SUM(usd), 0)::float8 AS usd
FROM agent_custody_events
WHERE agent_id = ${agentId}
AND network = ${network}
AND event_type = 'spend'
AND destination = ${destination}
AND status IN ('ok', 'pending', 'confirmed')
AND usd IS NOT NULL
AND created_at > now() - (${windowHours} || ' hours')::interval
`;
return Number(row?.usd || 0);
}
/**
* Destination gate for every send that is not a swap, a snipe or an x402 call
* (see EXEMPT_CATEGORIES in destination-whitelist.js). Refuses an address that
* is not on the agent's allowlist, one still in its cooldown, and one an agent
* only proposed, then applies the listed destination's own caps.
*
* `destinationTrust: 'system'` is set by server code, never by a request, for a
* destination the platform itself controls or that is bound to a quote the owner
* already confirmed (escrow, treasury, a verified provider invoice). It skips the
* gate; the numeric caps and policy rules still apply.
*
* `sweepRiskAck: true` is set once the owner has already seen the blocking
* sweeper-bot confirm for THIS destination (surfaced via `destination_sweep_risk`
* below) and chose to proceed. Only withdraw carries this check: every other
* category sends to a program address or a platform-controlled wallet the owner
* never typed in by hand, so there is no "did I copy the right address" risk to warn on.
* @throws {SpendLimitError}
*/
export async function enforceDestinationAllowlist({ agentId, meta, category, destination, usdValue, network = 'mainnet', destinationTrust = null, sweepRiskAck = false }) {
if (destinationTrust === 'system') return null;
const dest = typeof destination === 'string' ? destination.trim() : '';
// Only the owner's withdraw is required to name a destination. A category
// that carries none (a treasury top-up decided by the platform) has nothing
// to check.
if (!dest && category !== 'withdraw') return null;
const decision = await evaluateDestination({ agentId, destination: dest, category, ownAddress: meta?.solana_address || null });
if (!decision.allowed) {
throw new SpendLimitError(decision.code, decision.message, {
category, destination: dest || null, state: decision.state, ...(decision.detail || {}),
});
}
const entry = decision.entry;
if (decision.state === 'active' && entry) {
if (entry.per_tx_cap_usd != null && usdValue != null && usdValue > entry.per_tx_cap_usd) {
throw new SpendLimitError(
'destination_cap_exceeded',
`That send is $${usdValue.toFixed(2)}, over the $${entry.per_tx_cap_usd.toFixed(2)} limit set for this destination${entry.label ? ` (${entry.label})` : ''}.`,
{ category, destination: dest, cap_usd: entry.per_tx_cap_usd, usd: usdValue },
);
}
if (entry.daily_cap_usd != null && usdValue != null) {
const sent = await getCounterpartySpendUsd(agentId, dest, network, 24);
if (sent + usdValue > entry.daily_cap_usd) {
throw new SpendLimitError(
'destination_daily_cap_exceeded',
`This would bring today's total to this destination${entry.label ? ` (${entry.label})` : ''} to $${(sent + usdValue).toFixed(2)}, over its $${entry.daily_cap_usd.toFixed(2)} daily limit.`,
{ category, destination: dest, cap_usd: entry.daily_cap_usd, spent_24h_usd: sent, usd: usdValue },
);
}
}
}
if (category === 'withdraw' && dest) {
const sweepRisk = await checkDestinationSweepRisk({ destination: dest, network });
if (sweepRisk?.flagged && !sweepRiskAck) {
throw new SpendLimitError(
'destination_sweep_risk',
`This address looks drained by a sweeper bot: ${sweepRisk.note}`,
{ category, destination: dest, sweepRisk },
);
}
decision.sweepRisk = sweepRisk;
}
return decision;
}
/**
* Heuristic sweeper-bot check for a withdraw destination: does its recent
* history show the "incoming SOL, drained again within seconds" pattern? A
* read-only warning, never a static cap, so it degrades to `checked: false`
* (never throws) on an RPC failure rather than blocking a legitimate withdraw.
* See api/_lib/burned-destination.js for the classifier.
*/
export async function checkDestinationSweepRisk({ destination, network = 'mainnet' }) {
const dest = typeof destination === 'string' ? destination.trim() : '';
if (!dest) return null;
const conn = solanaConnection(network === 'devnet' ? 'devnet' : 'mainnet');
return checkBurnedDestination(conn, dest);
}
// ── natural-language policy enforcement ───────────────────────────────────────
// The owner-authored, code-enforced policy (meta.policy_rules) layered on top of
// the numeric caps. A block here returns the HUMAN rule that caught the spend.
/** Count how many times this agent has previously paid a given destination. Backs
* the `counterparty_seen_before` signal ("only pay services you've used before").
* Best-effort: any error reports "not seen", and the rule itself decides what that
* means (a `is false` rule then fires — fail-safe-to-block for that intent). */
export async function countPriorSpendsTo(agentId, destination, network = 'mainnet') {
if (!destination) return 0;
const [row] = await sql`
SELECT COUNT(*)::int AS n
FROM agent_custody_events
WHERE agent_id = ${agentId}
AND network = ${network}
AND event_type = 'spend'
AND destination = ${destination}
AND status IN ('ok', 'pending', 'confirmed')
`;
return Number(row?.n || 0);
}
/** Trip the wallet freeze switch from a `freeze` policy rule. Idempotent, audited,
* and never throws — a logging/DB hiccup must not turn the (correct) block into a
* pass. Owner withdraw stays open exactly as a manual freeze. */
async function freezeWalletFromPolicy(agentId, userId, rule, network) {
try {
await sql`
UPDATE agent_identities
SET meta = jsonb_set(
jsonb_set(coalesce(meta, '{}'::jsonb), '{spend_limits}', coalesce(meta->'spend_limits', '{}'::jsonb)),
'{spend_limits,frozen}', 'true'::jsonb
)
WHERE id = ${agentId} AND coalesce((meta->'spend_limits'->>'frozen')::boolean, false) = false
`;
await recordCustodyEvent({
agentId, userId: userId ?? null, eventType: 'limit_change', network,
reason: 'policy_freeze',
meta: { trigger: 'policy_rule', rule_id: rule?.id || null, rule: rule?.label || null },
});
logAudit({ userId: userId ?? null, action: 'custody.policy_freeze', resourceId: agentId, meta: { rule_id: rule?.id || null } });
} catch (e) {
console.warn('[policy] auto-freeze failed', e?.message);
}
}
/**
* Evaluate the natural-language policy for one outbound spend and throw the human
* rule that catches it. Total: any internal failure on an AUTONOMOUS path fails
* safe to a block; the owner's own withdraw is never trapped by an internal error.
*
* @param {object} o
* @param {string} o.agentId
* @param {object} o.policy normalized policy document
* @param {string} o.category
* @param {number|null} o.usdValue
* @param {string} [o.asset]
* @param {string} [o.destination]
* @param {object} [o.limits] resolved numeric limits (for destination_allowlisted)
* @param {object} [o.policyContext] extra live signals: token_age_hours, trade_pnl_pct, sol_reserve_after
* @param {number} [o.userId]
* @param {string} [o.network]
* @throws {SpendLimitError} when the policy denies the spend
*/
async function enforcePolicyRules({ agentId, policy, category, usdValue, asset, destination, limits, policyContext = {}, userId, network = 'mainnet', stepUpApproved = false }) {
if (!policy || !Array.isArray(policy.rules) || !policy.rules.length) return;
const autonomous = category !== 'withdraw';
let ctx;
try {
const refs = referencedFields(policy);
const hasUsd = typeof usdValue === 'number' && Number.isFinite(usdValue) && usdValue >= 0;
const dest = typeof destination === 'string' ? destination.trim() : '';
const allow = Array.isArray(limits?.withdraw_allowlist) ? limits.withdraw_allowlist : [];
ctx = {
category,
asset: asset || undefined,
counterparty: dest || undefined,
amount_usd: hasUsd ? usdValue : undefined,
time_of_day_utc: new Date().getUTCHours(),
destination_allowlisted: dest ? allow.includes(dest) : undefined,
// Live signals the trade/snipe paths can supply (token age, P&L, reserve).
...sanitizePolicyContext(policyContext),
};
// Async signals — only fetched when a live rule references them.
if ((refs.has('daily_spent_usd') || refs.has('daily_total_usd')) && hasUsd) {
const spent = await getDailySpendUsd(agentId, network);
ctx.daily_spent_usd = spent;
ctx.daily_total_usd = spent + usdValue;
}
if (refs.has('counterparty_seen_before') && dest) {
ctx.counterparty_seen_before = (await countPriorSpendsTo(agentId, dest, network)) > 0;
}
} catch (e) {
// Building the context failed (DB outage, etc.). Fail safe: block an
// autonomous spend; never trap the owner's withdraw.
console.warn('[policy] context build failed', e?.message);
if (!autonomous) return;
throw new SpendLimitError('policy_unavailable', 'Couldn’t verify this spend against your safety rules right now. The spend was blocked to stay safe — try again in a moment.', { category });
}
const verdict = evaluatePolicy(policy, ctx);
if (!isDenied(verdict.decision)) return;
// The owner already answered this step-up in the approval inbox
// (api/_lib/approvals.js). Only the "ask me" verdict is lifted: a block or a
// freeze rule still stops the spend, and every numeric cap below still runs.
if (verdict.decision === 'step_up' && stepUpApproved) return;
// Audit: every block records which rule fired (deliverable). A 'failed' spend
// row is excluded from the daily-cap sum and the backtest history, so it never
// inflates totals — it exists purely so the owner can see, on the live feed,
// exactly which payment was stopped and by which rule. Fire-and-forget.
recordCustodyEvent({
agentId, userId: userId ?? null, eventType: 'spend', category, network,
asset: asset || null, usd: (typeof usdValue === 'number' && Number.isFinite(usdValue)) ? usdValue : null,
destination: destination || null, status: 'failed', reason: `policy_${verdict.decision}`,
meta: { policy_block: true, rule_id: verdict.matched?.id || null, rule: verdict.message, rule_index: verdict.ruleIndex, decision: verdict.decision },
}).catch((e) => console.warn('[policy] block-record failed', e?.message));
// A `freeze` rule also trips the wallet kill-switch so everything else stops.
if (verdict.decision === 'freeze') {
await freezeWalletFromPolicy(agentId, userId, verdict.matched, network);
throw new SpendLimitError(
'policy_freeze',
`Wallet frozen by your rule: ${verdict.message} All autonomous spending is now paused; unfreeze it under Limits & Safety.`,
{ rule_id: verdict.matched?.id || null, rule: verdict.message, rule_index: verdict.ruleIndex, decision: 'freeze' },
);
}
const code = verdict.decision === 'step_up' ? 'policy_step_up' : 'policy_blocked';
const prefix = verdict.decision === 'step_up' ? 'This spend needs your approval' : 'Blocked by your rule';
throw new SpendLimitError(
code,
`${prefix}: ${verdict.message}`,
{ rule_id: verdict.matched?.id || null, rule: verdict.message, rule_index: verdict.ruleIndex, decision: verdict.decision },
);
}
/** Keep only the numeric live signals the evaluator understands, coerced + finite. */
function sanitizePolicyContext(extra) {
const out = {};
if (!extra || typeof extra !== 'object') return out;
for (const k of ['token_age_hours', 'trade_pnl_pct', 'sol_reserve_after']) {
const n = Number(extra[k]);
if (extra[k] != null && Number.isFinite(n)) out[k] = n;
}
return out;
}
/**
* Persist a natural-language policy onto the agent (owner-only). The caller passes
* the validated rule array (from the compiler) plus the original English. The
* document is re-normalized here so the stored policy is always enforceable, a
* `limit_change` custody event records the English + a diff vs the prior policy, and
* a platform audit row is written. Returns the new normalized document.
*/
export async function setPolicyRules(agentId, userId, rules, { english = null, req = null } = {}) {
const [row] = await sql`
SELECT id, user_id, meta FROM agent_identities
WHERE id = ${agentId} AND deleted_at IS NULL
`;
if (!row) throw Object.assign(new Error('agent not found'), { status: 404, code: 'not_found' });
if (row.user_id !== userId) throw Object.assign(new Error('not your agent'), { status: 403, code: 'forbidden' });
const prev = getPolicyRules(row.meta);
const next = normalizePolicyRules({ rules, source_text: typeof english === 'string' ? english : prev.source_text });
next.updated_at = new Date().toISOString();
const diff = diffPolicies(prev, next);
const meta = { ...(row.meta || {}), policy_rules: next };
await sql`UPDATE agent_identities SET meta = ${JSON.stringify(meta)}::jsonb WHERE id = ${agentId}`;
await recordCustodyEvent({
agentId,
userId,
eventType: 'limit_change',
reason: 'policy_updated',
meta: { english: next.source_text, prev_rules: prev.rules, next_rules: next.rules, readback: describePolicyRules(next), diff },
}).catch((e) => console.warn('[custody] policy limit_change record failed', e?.message));
logAudit({ userId, action: 'custody.policy_change', resourceId: agentId, meta: { diff, rule_count: next.rules.length }, req });
return next;
}
/**
* Enforce the per-agent spend policy for one outbound movement.
*
* Fails closed on its inputs: pass `limits`, or `meta`, or neither, with
* neither, the agent's policy is read from its row rather than defaulting to an
* unrestricted wallet. There is no argument shape that silently disables the
* ceilings or the kill switch.
*
* @param {object} o
* @param {string} o.agentId
* @param {object} [o.meta] agent meta (limits + policy read from here if absent)
* @param {object} [o.limits] pre-resolved limits (skips the meta read)
* @param {object} [o.policyRules] pre-resolved NL policy document (skips the meta/DB read)
* @param {'trade'|'snipe'|'x402'|'withdraw'} o.category
* @param {number|null} o.usdValue USD-equivalent of this tx (null = unpriceable)
* @param {string} [o.asset] 'SOL' | 'USDC' | mint — for asset-scoped policy rules
* @param {string} [o.destination] base58 recipient (required for allowlist on withdraw)
* @param {object} [o.policyContext] live signals for policy rules (token_age_hours, trade_pnl_pct, sol_reserve_after)
* @param {number} [o.userId] actor (for policy-freeze audit)
* @param {string} [o.network]
* @returns {Promise<{ ok: true, limits: object, dailySpentUsd: number|null }>}
* @throws {SpendLimitError} on any breach (always 4xx)
*/
// ── capability gate (scoped session keys) ──────────────────────────────────
// Resolve + scope-check the capability that authorizes an autonomous spend, if any.
// Composed additively into both shared guards. A capability STRICTLY NARROWS: the
// wallet-wide checks must pass AND this gate must pass. Autonomous categories only
// (trade/snipe/x402); an owner-initiated withdraw is never a delegated capability.
//
// A caller may pass a pre-resolved `capability`, or a `capabilityHolderRef`
// (skill/strategy/integration id) we resolve to the tightest live grant. When the
// wallet has require_capabilities on and no covering grant exists, the spend is
// DENIED (fail safe). Returns the resolved capability, or null when none applies
// and none is required (unchanged behavior for wallets not using capabilities).
async function resolveSpendCapability({ agentId, lim, category, usdValue, target, capability, capabilityHolderRef, ownerInitiated, now }) {
if (category === 'withdraw') return null;
// Owner-present actions (e.g. the hub's discretionary Trade tab) are not delegated
// capabilities — the owner is the authority, exactly like withdraw. We still honor
// an explicitly-presented capability, but never auto-resolve or require one here.
if (ownerInitiated) {
if (!capability) return null;
const s = evaluateCapabilityScope({ cap: capability, action: category, target, usdValue, now });
if (s) throw capabilityError(s.reason, s.detail);
return capability;
}
let cap = capability || null;
if (!cap && (lim.require_capabilities || capabilityHolderRef)) {
cap = await resolveCapabilityForSpend({ agentId, action: category, holderRef: capabilityHolderRef ?? null, target, usdValue, now });
}
if (!cap) {
if (lim.require_capabilities) throw capabilityError('capability_required', { category });
return null;
}
const scope = evaluateCapabilityScope({ cap, action: category, target, usdValue, now });
if (scope) throw capabilityError(scope.reason, scope.detail);
return cap;
}
/**
* Fail-closed policy resolution for a spend whose caller supplied NEITHER a
* pre-read `limits` object NOR the agent's `meta`. Without this, both shared
* guards fell back to `normalizeSpendLimits(undefined)`: every ceiling null,
* `frozen` false, no natural-language rules. A caller that simply forgot to
* load the agent row got a wallet with no policy at all and no signal that the
* kill switch had been skipped. Autonomy makes that unacceptable: the guarantee
* has to hold because the code enforces it, not because every call site
* remembers to. One PK read closes it, mirroring what the anomaly guard in
* api/_lib/anomaly-events.js already does for the same reason. An agent that no
* longer exists (or was deleted mid-flight) can hold no policy, so its spend is
* refused rather than waved through.
*
* @returns {Promise<{ meta: object, userId: string|null }>}
* @throws {SpendLimitError} when the agent row is gone
*/
async function loadPolicyMeta(agentId) {
const [row] = await sql`
SELECT user_id, meta FROM agent_identities
WHERE id = ${agentId} AND deleted_at IS NULL
`;
if (!row) {
throw new SpendLimitError(
'agent_not_found',
'That agent no longer exists, so no spend policy can govern this payment. Nothing was spent.',
{ agent_id: String(agentId ?? '') },
);
}
return { meta: row.meta || {}, userId: row.user_id ?? null };
}
// ── capped burner ─────────────────────────────────────────────────────────────
/** Read the effective burner policy off an agent's meta blob. */
export function getBurnerPolicy(meta) {
return normalizeBurnerPolicy(meta?.burner_policy);
}
/**
* USD the agent signed ALONE over the trailing window. A spend the owner
* approved (custody row carries meta.approval_id) is the owner's decision, so
* it does not eat the agent's own daily allowance.
*/
export async function getAutoSpendUsd(agentId, network = 'mainnet', windowHours = 24) {
const [row] = await sql`
SELECT COALESCE(SUM(usd), 0)::float8 AS usd
FROM agent_custody_events
WHERE agent_id = ${agentId}
AND network = ${network}
AND event_type = 'spend'
AND status IN ('ok', 'pending', 'confirmed')
AND usd IS NOT NULL
AND (meta->>'approval_id') IS NULL
AND created_at > now() - (${windowHours} || ' hours')::interval
`;
return Number(row?.usd || 0);
}
/**
* Persist a burner-policy patch (owner-only). Keys absent from `patch` are kept.
* An all-null autoMaxUsd turns the burner off. Writes a custody audit event and
* a platform audit row. Returns the new normalized policy.
*/
export async function setBurnerPolicy(agentId, userId, patch, { req = null } = {}) {
const [row] = await sql`
SELECT id, user_id, meta FROM agent_identities
WHERE id = ${agentId} AND deleted_at IS NULL
`;
if (!row) throw Object.assign(new Error('agent not found'), { status: 404, code: 'not_found' });
if (row.user_id !== userId) throw Object.assign(new Error('not your agent'), { status: 403, code: 'forbidden' });
const prev = getBurnerPolicy(row.meta);
const next = normalizeBurnerPolicy({
autoMaxUsd: 'autoMaxUsd' in patch ? patch.autoMaxUsd : prev.autoMaxUsd,
dailyAutoMaxUsd: 'dailyAutoMaxUsd' in patch ? patch.dailyAutoMaxUsd : prev.dailyAutoMaxUsd,
confirmAboveUsd: 'confirmAboveUsd' in patch ? patch.confirmAboveUsd : prev.confirmAboveUsd,
expiryMinutes: 'expiryMinutes' in patch ? patch.expiryMinutes : prev.expiryMinutes,
});
const problem = validateBurnerPolicy(next);
if (problem) throw Object.assign(new Error(problem), { status: 422, code: 'invalid_burner_policy' });
next.updatedAt = new Date().toISOString();
const meta = { ...(row.meta || {}), burner_policy: next };
await sql`UPDATE agent_identities SET meta = ${JSON.stringify(meta)}::jsonb WHERE id = ${agentId}`;
await recordCustodyEvent({
agentId, userId, eventType: 'limit_change', reason: 'burner_policy_updated', meta: { prev, next },
}).catch((e) => console.warn('[custody] burner limit_change record failed', e?.message));
logAudit({ userId, action: 'custody.burner_policy', resourceId: agentId, meta: { prev, next }, req });
return next;
}
/**
* The burner tier gate. Throws SpendLimitError('policy_step_up') with
* detail.burner = true when the spend is above what the agent may sign alone,
* so every caller that already turns a step-up into an approval request (wallet
* intents, agent commerce, trades) handles it with no new branch.
*/
async function enforceBurnerTier({ agentId, meta, category, usdValue, network }) {
if (meta == null) meta = (await loadPolicyMeta(agentId)).meta;
const policy = getBurnerPolicy(meta);
if (!burnerEnabled(policy)) return;
const hasUsd = typeof usdValue === 'number' && Number.isFinite(usdValue) && usdValue >= 0;
const autoSpentUsd = hasUsd && policy.dailyAutoMaxUsd != null ? await getAutoSpendUsd(agentId, network) : 0;
const verdict = classifyBurnerSpend({ policy, usd: hasUsd ? usdValue : null, autoSpentUsd });
if (verdict.tier === 'auto') return;
throw new SpendLimitError(
'policy_step_up',
`This spend needs your approval: ${verdict.reason}`,
{ decision: 'step_up', burner: true, tier: verdict.tier, reason: verdict.reason, category, usd: hasUsd ? usdValue : null, auto_spent_usd: autoSpentUsd, expiry_minutes: policy.expiryMinutes },
);
}
export async function enforceSpendLimit({
agentId,
meta,
limits,
policyRules,
category,
usdValue,
asset,
destination,
policyContext,
userId,
capability,
capabilityHolderRef,
target,
ownerInitiated,
now,
network = 'mainnet',
stepUpApproved = false,
destinationTrust = null,
// The owner already saw the sweeper-bot confirm for this exact destination
// and chose to proceed. See enforceDestinationAllowlist's docstring.
sweepRiskAck = false,
// The owner is the one acting (their own session, or a button only they can
// press), so the agent's burner cap, which bounds the AGENT, does not apply.
burnerExempt = false,
}) {
// Fail closed: a caller that named neither the limits nor the meta gets the
// agent's REAL policy read from the row, never an empty default policy.
if (!limits && meta == null) {
const loaded = await loadPolicyMeta(agentId);
meta = loaded.meta;
if (userId == null) userId = loaded.userId;
}
const lim = limits || getSpendLimits(meta);
// 0. Wallet freeze — blocks every autonomous path; owner withdraw stays open.
if (lim.frozen && category !== 'withdraw') {
throw new SpendLimitError(
'wallet_frozen',
'This wallet is frozen. Autonomous spending (trades, snipes, payments) is paused. Unfreeze it under Limits & Safety to resume.',
{ category },
);
}
// 1. Destination allowlist: every outbound category, cooldown-gated.
await enforceDestinationAllowlist({ agentId, meta, category, destination, usdValue, network, destinationTrust, sweepRiskAck });
// 2. Natural-language policy — the owner's English rules, deterministically
// enforced. Resolved from the explicit `policyRules` arg or the `meta` blob —
// both are free (no extra query). A caller that passes only pre-resolved `limits`
// must pass `policyRules` to opt the path in; the autonomous trade/snipe/x402/
// withdraw paths all do (or pass `meta`).
const policy = policyRules || (meta ? getPolicyRules(meta) : null);
await enforcePolicyRules({ agentId, policy, category, usdValue, asset, destination, limits: lim, policyContext, userId, network, stepUpApproved });
// 2b. Capped burner: above the agent's own cap the spend becomes a pending
// approval (policy_step_up), never a failure. The owner's own actions, the
// owner's withdraw path and a spend the owner already approved skip it.
if (!burnerExempt && !stepUpApproved && category !== 'withdraw') {
await enforceBurnerTier({ agentId, meta, category, usdValue, network });
}
const hasUsd = typeof usdValue === 'number' && Number.isFinite(usdValue) && usdValue >= 0;
// 3. Per-transaction ceiling.
if (lim.per_tx_usd != null && hasUsd && usdValue > lim.per_tx_usd + 1e-9) {
throw new SpendLimitError(
'per_tx_exceeded',
`This ${category} is $${usdValue.toFixed(2)}, over the per-transaction limit of $${lim.per_tx_usd.toFixed(2)}.`,
{ usd: usdValue, per_tx_usd: lim.per_tx_usd },
);
}
// 4. Rolling daily ceiling.
let dailySpentUsd = null;
if (lim.daily_usd != null && hasUsd) {
dailySpentUsd = await getDailySpendUsd(agentId, network);
if (dailySpentUsd + usdValue > lim.daily_usd + 1e-9) {
throw new SpendLimitError(
'daily_exceeded',
`This ${category} would bring today’s spend to $${(dailySpentUsd + usdValue).toFixed(2)}, over the daily limit of $${lim.daily_usd.toFixed(2)}.`,
{ usd: usdValue, spent_usd: dailySpentUsd, daily_usd: lim.daily_usd },
);
}
}
// 4c. Per-counterparty rolling ceiling. Bounds concentration, not just total:
// a wallet-wide daily cap still permits the entire day's budget to flow into
// one payee.
if (lim.per_counterparty_daily_usd != null && hasUsd && destination) {
const cpSpent = await getCounterpartySpendUsd(agentId, destination, network);
if (cpSpent + usdValue > lim.per_counterparty_daily_usd + 1e-9) {
throw new SpendLimitError(
'counterparty_daily_exceeded',
`This ${category} would bring today’s spend to this counterparty to $${(cpSpent + usdValue).toFixed(2)}, over the per-counterparty limit of $${lim.per_counterparty_daily_usd.toFixed(2)}.`,
{
usd: usdValue,
destination,
counterparty_spent_usd: cpSpent,
per_counterparty_daily_usd: lim.per_counterparty_daily_usd,
},
);
}
}
// 5. Behavioral anomaly guard (the wallet's immune system). Scores this action
// against the agent's learned normal; on a freeze verdict it has already frozen
// the wallet + notified the owner, and we surface a SpendLimitError so the
// triggering action is held. Self-contained fail-safe — never fails open here.
const anomaly = await guardOutboundAnomaly({
agentId, userId, meta, category, usdValue, destination, asset, network,
});
if (anomaly.decision === 'freeze') {
throw new SpendLimitError('wallet_anomaly_frozen', anomaly.message, anomaly.detail || {});
}
// 4b. Capability gate (least-privilege). Scope (action/target/expiry/revoked/
// per-use) + a non-atomic aggregate read-check, mirroring how this enforce path
// already treats the daily cap non-atomically. The atomic aggregate reserve lives
// in reserveSpendUsd → reserveCapabilitySpend.
const _cap = await resolveSpendCapability({ agentId, lim, category, usdValue, target, capability, capabilityHolderRef, ownerInitiated, now });
const capabilityId = _cap?.id || null;
if (_cap && _cap.aggregate_usd != null && hasUsd) {
const _spent = await capabilitySpentUsd(_cap.id);
const _agg = checkAggregate(_spent, usdValue, _cap);
if (_agg) throw capabilityError(_agg.reason, _agg.detail);
}
return { ok: true, limits: lim, dailySpentUsd, capabilityId, anomaly: anomaly.verdict || null };
}
/**
* Atomically enforce the per-agent USD spend policy AND reserve a pending custody
* row, under a per-agent advisory lock. This closes the TOCTOU that
* `enforceSpendLimit` + a post-settle `recordSpend` leaves open: without the lock,
* K concurrent calls all read the same pre-spend 24h total, all pass the daily
* ceiling, and all settle — turning a $X/day cap into $X·K. Mirrors the proven
* `reserveSpend` pattern in agent-spend-policy.js (which already protects the SOL
* outflow path).
*
* Returns { ok: true, reservationId, dailySpentUsd } on success — finalize the
* reservation with `updateCustodyEvent(reservationId, { status, signature })` after
* settlement, or `releaseSpendReservation(reservationId)` if the spend never moved.
* Like `enforceSpendLimit`, it fails closed on its inputs: with neither `limits`
* nor `meta` it reads the agent's real policy instead of an empty one.
* @throws {SpendLimitError} on per-tx breach, daily breach, or withdraw-allowlist miss.
*/
export async function reserveSpendUsd({
agentId,
userId,
meta,
limits,
policyRules,
category,
usdValue,
destination,
policyContext,
capability,
capabilityHolderRef,
target,
ownerInitiated,
now,
network = 'mainnet',
asset = 'USDC',
rowMeta = {},
destinationTrust = null,
// The owner answered this exact spend in the approval inbox. Lifts only a
// policy "ask me" verdict, as in enforceSpendLimit; every cap still runs.
stepUpApproved = false,
// The owner already saw the sweeper-bot confirm for this exact destination
// and chose to proceed. See enforceDestinationAllowlist's docstring.
sweepRiskAck = false,
// The owner is the one acting (their own session, or a button only they can
// press), so the agent's burner cap, which bounds the AGENT, does not apply.
burnerExempt = false,
}) {
// Fail closed, exactly as enforceSpendLimit does: the reserve is the layer that
// runs before any key is touched, so it is the layer that must never default to
// an empty policy. Resolving the row here also attributes the reserved custody
// row (the payment receipt) to the real owner when the caller passed no userId.
if (!limits && meta == null) {
const loaded = await loadPolicyMeta(agentId);
meta = loaded.meta;
if (userId == null) userId = loaded.userId;
}
const lim = limits || getSpendLimits(meta);
// Wallet freeze — blocks every autonomous path; owner withdraw stays open.
if (lim.frozen && category !== 'withdraw') {
throw new SpendLimitError(
'wallet_frozen',
'This wallet is frozen. Autonomous spending (trades, snipes, payments) is paused. Unfreeze it under Limits & Safety to resume.',
{ category },
);
}
// Destination allowlist: same gate as enforceSpendLimit, before a row is reserved.
await enforceDestinationAllowlist({ agentId, meta, category, destination, usdValue, network, destinationTrust, sweepRiskAck });
// Natural-language policy — same deterministic evaluator as enforceSpendLimit,
// run BEFORE the row is reserved so a policy block never claims daily headroom.
const policy = policyRules || (meta ? getPolicyRules(meta) : null);
await enforcePolicyRules({ agentId, policy, category, usdValue, asset, destination, limits: lim, policyContext, userId, network, stepUpApproved });
// Capped burner: same gate as enforceSpendLimit, before a row is reserved.
if (!burnerExempt && !stepUpApproved && category !== 'withdraw') {
await enforceBurnerTier({ agentId, meta, category, usdValue, network });
}
const hasUsd = typeof usdValue === 'number' && Number.isFinite(usdValue) && usdValue >= 0;
// Per-transaction ceiling (no lock needed — a single value vs a constant).
if (lim.per_tx_usd != null && hasUsd && usdValue > lim.per_tx_usd + 1e-9) {
throw new SpendLimitError(
'per_tx_exceeded',
`This ${category} is $${usdValue.toFixed(2)}, over the per-transaction limit of $${lim.per_tx_usd.toFixed(2)}.`,
{ usd: usdValue, per_tx_usd: lim.per_tx_usd },
);
}
// Capability gate (least-privilege). When a capability is in play (presented,
// resolvable, or required for this wallet), delegate the reserve to
// reserveCapabilitySpend: it atomically meters BOTH the capability aggregate
// ceiling AND the wallet daily cap under advisory locks and tags the pending row
// with capability_id. Return early so we never double-insert.
if (category !== 'withdraw') {
const _cap = await resolveSpendCapability({ agentId, lim, category, usdValue, target: target ?? destination, capability, capabilityHolderRef, ownerInitiated, now });
if (_cap) {
const _r = await reserveCapabilitySpend({
capabilityId: _cap.id, agentId, userId, action: category,
target: target ?? destination, usdValue, dailyUsd: lim.daily_usd,
counterpartyDailyUsd: lim.per_counterparty_daily_usd,
network, asset, destination, rowMeta, now,
});
return { ok: true, reservationId: _r.reservationId, dailySpentUsd: _r.spentBefore, capabilityId: _cap.id };
}
}
const metaJson = JSON.stringify(rowMeta ?? {});
// Behavioral anomaly guard for a just-reserved spend. The pending row already
// exists (selfCounted: live velocity counts include it), so on a freeze verdict
// we RELEASE the reservation — it must not hold daily headroom — before surfacing
// the SpendLimitError. guardOutboundAnomaly has already frozen + notified.
const runAnomaly = async (reservationId, dailySpentUsd) => {
const anomaly = await guardOutboundAnomaly({
agentId, userId, meta, category, usdValue, destination, asset, network,
custodyEventId: reservationId, selfCounted: true,
});
if (anomaly.decision === 'freeze') {
await releaseSpendReservation(reservationId, 'anomaly_frozen');
throw new SpendLimitError('wallet_anomaly_frozen', anomaly.message, anomaly.detail || {});
}
return { ok: true, reservationId, dailySpentUsd, anomaly: anomaly.verdict || null };
};
// The per-counterparty ceiling only has something to meter when the spend names
// a recipient. An unaddressed spend (no payee recorded) is governed by the
// wallet-wide cap alone rather than silently passing a cap it cannot evaluate.
const cpCap = destination ? lim.per_counterparty_daily_usd : null;
const cpDestination = cpCap != null ? destination : null;
// No metered ceiling, or an unpriceable spend: just reserve a pending row (it
// can't gate a cap it has no number for) so the ledger still reflects it.
if ((lim.daily_usd == null && cpCap == null) || !hasUsd) {
const reservationId = await recordCustodyEvent({
agentId, userId, eventType: 'spend', category, network, asset,
usd: hasUsd ? usdValue : null, destination, status: 'pending', meta: rowMeta,
});
return runAnomaly(reservationId, null);
}
// Atomic cap reserve (lock taken as a separate statement, see locked-sql.js): the advisory xact lock serializes concurrent spends per
// agent, and the INSERT…SELECT only materializes the pending row when BOTH the
// rolling 24h wallet total and the rolling 24h total to this counterparty stay
// within their ceilings — check + reserve are one statement, so two requests can
// never both pass on the same stale total. A null ceiling drops out of the
// predicate, so this one statement serves a wallet that sets either cap or both.
const rows = await runLocked([agentId], sql`
WITH spent AS (
SELECT COALESCE(SUM(usd), 0)::float8 AS s
FROM agent_custody_events
WHERE agent_id = ${agentId}
AND network = ${network}
AND event_type = 'spend'
AND status IN ('ok', 'pending', 'confirmed')
AND usd IS NOT NULL
AND created_at > now() - interval '24 hours'
),
cp AS (
SELECT COALESCE(SUM(usd), 0)::float8 AS s
FROM agent_custody_events
WHERE agent_id = ${agentId}
AND network = ${network}
AND event_type = 'spend'
AND destination = ${cpDestination}
AND status IN ('ok', 'pending', 'confirmed')
AND usd IS NOT NULL
AND created_at > now() - interval '24 hours'
)
INSERT INTO agent_custody_events
(agent_id, user_id, event_type, category, network, asset, usd, destination, status, meta)
SELECT ${agentId}, ${userId ?? null}, 'spend', ${category}, ${network}, ${asset},
${usdValue}, ${destination ?? null}, 'pending', ${metaJson}::jsonb
FROM spent, cp
WHERE (${lim.daily_usd}::float8 IS NULL OR spent.s + ${usdValue}::float8 <= ${lim.daily_usd}::float8 + 1e-9)
AND (${cpCap}::float8 IS NULL OR cp.s + ${usdValue}::float8 <= ${cpCap}::float8 + 1e-9)
RETURNING id, (SELECT s FROM spent) AS spent_before, (SELECT s FROM cp) AS cp_spent_before
`);
if (!rows.length) {
// Re-read the totals for an accurate error message (outside the lock is fine)
// and name the ceiling that actually rejected the spend — a caller told to
// wait out a daily window it never hit would keep retrying forever.
const cpSpentUsd = cpCap != null ? await getCounterpartySpendUsd(agentId, destination, network) : 0;
if (cpCap != null && cpSpentUsd + usdValue > cpCap + 1e-9) {
throw new SpendLimitError(
'counterparty_daily_exceeded',
`This ${category} would bring today’s spend to this counterparty to $${(cpSpentUsd + usdValue).toFixed(2)}, over the per-counterparty limit of $${cpCap.toFixed(2)}.`,
{
usd: usdValue,
destination,
counterparty_spent_usd: cpSpentUsd,
per_counterparty_daily_usd: cpCap,
},
);
}
const dailySpentUsd = await getDailySpendUsd(agentId, network);
throw new SpendLimitError(
'daily_exceeded',
`This ${category} would bring today’s spend to $${(dailySpentUsd + usdValue).toFixed(2)}, over the daily limit of $${Number(lim.daily_usd).toFixed(2)}.`,
{ usd: usdValue, spent_usd: dailySpentUsd, daily_usd: lim.daily_usd },
);
}
return runAnomaly(rows[0].id, Number(rows[0].spent_before || 0));
}
/**
* Release a USD spend reservation that never resulted in a settled payment, so it
* stops counting toward the daily cap. Marks the pending row 'failed' rather than
* deleting it, preserving the audit trail.
*/
export async function releaseSpendReservation(reservationId, reason = 'spend_aborted') {
if (!reservationId) return;
await sql`
UPDATE agent_custody_events
SET status = 'failed', reason = ${reason}, updated_at = now()
WHERE id = ${reservationId} AND status = 'pending'
`;
}
const CUSTODY_COLUMNS = [
'agent_id', 'user_id', 'event_type', 'category', 'network', 'asset',
'amount_lamports', 'amount_raw', 'usd', 'destination', 'signature',
'reason', 'status', 'idempotency_key', 'capability_id', 'meta',
];
// `chain` is a generated column derived from `network` (migration
// 20260925210000_custody_chain.sql), so an EVM-leg writer names its chain in
// `network` ('base', 'robinhood') and must never write `chain` itself: the
// database refuses a non-default value for a generated column.
/**
* Write a row into the custody audit trail / spend ledger.
* Returns the new row id. Callers in fire-and-forget contexts should `.catch()`.
* `capabilityId` (optional) tags the row with the scoped session key that
* authorized the spend, so the per-capability aggregate ceiling and the owner
* Access UI read from the same ledger as the wallet daily cap.
*/
export async function recordCustodyEvent(e) {
const [row] = await sql`
INSERT INTO agent_custody_events
(agent_id, user_id, event_type, category, network, asset,
amount_lamports, amount_raw, usd, destination, signature,
reason, status, idempotency_key, capability_id, meta)
VALUES (
${e.agentId},
${e.userId ?? null},
${e.eventType},
${e.category ?? null},
${e.network ?? 'mainnet'},
${e.asset ?? null},
${e.amountLamports != null ? String(e.amountLamports) : null},
${e.amountRaw != null ? String(e.amountRaw) : null},
${e.usd ?? null},
${e.destination ?? null},
${e.signature ?? null},
${e.reason ?? null},
${e.status ?? 'ok'},
${e.idempotencyKey ?? null},
${e.capabilityId ?? null},
${JSON.stringify(e.meta ?? {})}::jsonb
)
RETURNING id
`;
return row?.id ?? null;
}
/** Update a custody row by id (e.g. flip a pending withdraw to confirmed/failed). */
export async function updateCustodyEvent(id, patch) {
await sql`
UPDATE agent_custody_events
SET status = COALESCE(${patch.status ?? null}, status),
signature = COALESCE(${patch.signature ?? null}, signature),
usd = COALESCE(${patch.usd ?? null}, usd),
amount_lamports = COALESCE(${patch.amountLamports != null ? String(patch.amountLamports) : null}, amount_lamports),
meta = CASE WHEN ${patch.meta ? JSON.stringify(patch.meta) : null}::jsonb IS NULL
THEN meta ELSE meta || ${patch.meta ? JSON.stringify(patch.meta) : '{}'}::jsonb END,
updated_at = now()
WHERE id = ${id}
`;
}
/** Convenience wrapper for the common case: record one outbound 'spend'. */
export async function recordSpend(e) {
return recordCustodyEvent({ ...e, eventType: 'spend' });
}
/**
* Read the agent's recent custody events for the owner-facing audit feed.
* Cursor is the `id` of the last row seen (descending, so strictly-less-than).
*/
export async function listCustodyEvents(
agentId,
{ limit = 50, beforeId = null, network = null, category = null } = {},
) {
const lim = Math.min(200, Math.max(1, Number(limit) || 50));
const rows = await sql`
SELECT id, event_type, category, network, asset, amount_lamports, amount_raw,
usd, destination, signature, reason, status, created_at, meta
FROM agent_custody_events
WHERE agent_id = ${agentId}
AND (${network}::text IS NULL OR network = ${network})
AND (${category}::text IS NULL OR category = ${category})
AND (${beforeId}::bigint IS NULL OR id < ${beforeId})
ORDER BY id DESC
LIMIT ${lim}
`;
return rows;
}