@tollxyz/guard 0.3.0 → 0.4.0

package/dist/policy.js

@@ -1,4 +1,24 @@
-import { TX_CHAIN_ID, TollBlockedError, TollUnavailableError, checkTx, chainIdOf, paidUrlOf, } from "./check.js";
+import { TX_CHAIN_ID, TollBlockedError, TollUnavailableError, checkTx, chainIdOf, paidUrlOf, bodyOf, toJson, } from "./check.js";
+import { DEFAULT_SPEND_ASSETS, spendOf } from "./spend.js";
+import { MemorySpendStore, dayStart } from "./store.js";
+/** blocked by your own spend rules; a TollBlockedError, so existing catch blocks still see a block */
+export class TollPolicyError extends TollBlockedError {
+    code;
+    asset;
+    amount;
+    limit;
+    /** the guard's report of this request */
+    report;
+    constructor(code, message, x = {}) {
+        super({ action: "BLOCK", warnings: [{ code: `policy-${code}`, severity: "critical", message }], ...(x.assessment?.["x-toll"] ? { "x-toll": x.assessment["x-toll"] } : {}) }, "policy");
+        this.name = "TollPolicyError";
+        this.code = code;
+        this.asset = x.asset;
+        this.amount = x.amount;
+        this.limit = x.limit;
+        this.report = x.report;
+    }
+}
 /** the effective policy: explicit options win, then the strict preset, then the defaults */
 export function resolvePolicy(o = {}) {
     const strict = o.strict === true;
@@ -96,6 +116,10 @@ export function unsupportedWhy(input) {
  * `build` may throw (e.g. calldata that could not be encoded): that counts as unavailable.
  */
 export async function enforce(kind, build, o = {}) {
+    return o.spend ? enforceSpend(kind, build, o) : enforceVerdict(kind, build, o);
+}
+/** Toll's verdict and the 0.3.x policy (onWarn, onBlock, onUnavailable, onUnsupported) */
+async function enforceVerdict(kind, build, o) {
     let input;
     try {
         input = await build();
@@ -119,7 +143,7 @@ export async function enforce(kind, build, o = {}) {
     }
     let a;
     try {
-        a = await checkTx(input, o);
+        a = takeConfirmed(o, input) ?? (await checkTx(input, o));
     }
     catch (e) {
         const err = e instanceof TollUnavailableError ? e : new TollUnavailableError(`Toll's check failed: ${e?.message ?? e}`, { reason: "network", cause: e });
@@ -221,7 +245,281 @@ export async function enforceCalls(build, o = {}) {
     if (!calls.length)
         return [await enforce("calls", () => ({}), o)];
     const out = [];
-    for (const c of calls)
-        out.push(await enforce("calls", () => c, o));
+    try {
+        for (const c of calls)
+            out.push(await enforce("calls", () => c, o));
+    }
+    catch (e) {
+        // the batch is not sent: the calls already passed give their day reservations back
+        await releaseSpend(out, o);
+        throw e;
+    }
     return out;
 }
+/* ------------------------------------------------------------------ spend mode */
+const lc = (x) => String(x ?? "").toLowerCase();
+const fmt = (a) => (a === "native" ? "native ETH" : a);
+const stores = new WeakMap();
+/** the store for these options: the one given, else one in-process store per SpendPolicy object */
+export function storeOf(o) {
+    if (o.store)
+        return o.store;
+    const sp = o.spend ?? {};
+    let s = stores.get(sp);
+    if (!s) {
+        s = new MemorySpendStore();
+        stores.set(sp, s);
+    }
+    return s;
+}
+const lower = (r) => Object.fromEntries(Object.entries(r ?? {}).map(([k, v]) => [lc(k), v]));
+function assetsOf(sp) {
+    return [...new Set([...DEFAULT_SPEND_ASSETS, ...Object.keys(sp.assets ?? {}), ...Object.keys(sp.approveAbove ?? {})].map(lc))];
+}
+/** the first counterparty off an allowlist, or null */
+function offList(sp, s) {
+    const check = (list, got, what) => {
+        if (!list)
+            return null;
+        const ok = new Set(list.map(lc));
+        const bad = got.find((x) => !ok.has(x));
+        return bad ? `${what} ${bad} is not on the allowlist` : null;
+    };
+    return check(sp.allow?.to, s.to, "recipient") ?? check(sp.allow?.spender, s.spender, "spender") ?? check(sp.allow?.payTo, s.payTo, "x402 payee");
+}
+/* previews: Toll's answer kept 30 s for one confirmed send of the identical request */
+const CONFIRM_TTL_MS = 30_000;
+const confirmed = new Map();
+let confirmSeq = 0;
+function rememberConfirm(input, assessment) {
+    const t = Date.now();
+    for (const [k, v] of confirmed)
+        if (v.until <= t)
+            confirmed.delete(k);
+    const id = `c${t.toString(36)}${(++confirmSeq).toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+    confirmed.set(id, { body: toJson(bodyOf(input)), assessment, until: t + CONFIRM_TTL_MS });
+    return id;
+}
+function takeConfirmed(o, input) {
+    const id = o._confirm;
+    if (!id)
+        return null;
+    const c = confirmed.get(id);
+    if (!c || c.until <= Date.now() || c.body !== toJson(bodyOf(input)))
+        return null;
+    confirmed.delete(id); // once
+    return c.assessment;
+}
+/** the reservations of these reports, committed: the request was sent */
+export async function commitSpend(reports, o) {
+    if (!o.spend)
+        return;
+    const store = storeOf(o);
+    for (const r of [].concat(reports))
+        for (const id of r.spend?.reservations ?? [])
+            await store.commit(id);
+}
+/** the reservations of these reports, released: the request was refused or the send threw */
+export async function releaseSpend(reports, o) {
+    if (!o.spend)
+        return;
+    const store = storeOf(o);
+    for (const r of [].concat(reports))
+        for (const id of r.spend?.reservations ?? [])
+            await store.release(id);
+}
+/** the per-endpoint caps whose prefix the URL starts with */
+function endpointCaps(sp, url) {
+    if (!url || !sp.perEndpoint)
+        return [];
+    let u;
+    try {
+        const x = new URL(url);
+        u = x.origin + x.pathname;
+    }
+    catch {
+        u = url;
+    }
+    return Object.entries(sp.perEndpoint).filter(([p]) => u.toLowerCase().startsWith(p.toLowerCase()));
+}
+/**
+ * Spend mode: allowlists -> Toll's verdict (the 0.3.x policy, unchanged) -> caps -> approval. Resolves with the report
+ * holding its day reservations (commitSpend after the send, releaseSpend when it throws); throws TollPolicyError for a
+ * spend rule, TollBlockedError / TollUnavailableError as before.
+ */
+async function enforceSpend(kind, build, o) {
+    const io = o;
+    const sp = o.spend;
+    const store = storeOf(o);
+    const assets = assetsOf(sp);
+    const preview = io._preview === true;
+    let input = null;
+    let buildErr = null;
+    try {
+        input = await build();
+    }
+    catch (e) {
+        buildErr = e;
+    }
+    const blockWith = async (base, code, message, s, x = {}) => {
+        const r = { ...base, decision: "blocked", basis: "policy", policy: code, ...(s ? { spend: { spend: s, reservations: [] } } : {}) };
+        if (!preview)
+            await report(o, r);
+        throw new TollPolicyError(code, message, { ...x, assessment: base.assessment, report: r });
+    };
+    // 1. allowlists, from the local read, before Toll is asked
+    if (input) {
+        const local = spendOf(input, null, assets);
+        const why = offList(sp, local);
+        if (why)
+            return blockWith({ kind, input, assessment: null, decision: "blocked", basis: "policy", paidUrl: null }, "not-allowlisted", `Not signed: ${why}.`, local);
+    }
+    // 2. Toll's verdict (the 0.3.x policy), reported once at the end
+    let verdict = null;
+    const vo = { ...o, onReport: (r) => void (verdict = r) };
+    let base;
+    try {
+        base = await enforceVerdict(kind, buildErr ? () => Promise.reject(buildErr) : () => input, vo);
+    }
+    catch (e) {
+        if (verdict && !preview)
+            await report(o, verdict);
+        if (preview && verdict && e instanceof Error)
+            e.report = verdict;
+        throw e;
+    }
+    // 3. what it spends, now with Toll's simulation when there is one
+    const s = input ? spendOf(input, base.assessment, assets) : { items: [], outflow: {}, approvals: {}, to: [], spender: [], payTo: [], unknown: true, simulated: false };
+    const why = offList(sp, s);
+    if (why)
+        return blockWith(base, "not-allowlisted", `Not signed: ${why}.`, s);
+    if (s.unknown && (sp.onUnknownSpend ?? (o.failClosed ? "block" : "allow")) === "block") {
+        return blockWith(base, "unknown-spend", 'Not signed: what this request spends could not be read (no simulation), and onUnknownSpend is "block".', s);
+    }
+    const caps = lower(sp.assets);
+    const touched = [...new Set([...Object.keys(s.outflow), ...Object.keys(s.approvals)])];
+    const amountOf = (a) => {
+        const out = s.outflow[a] ?? 0n;
+        const ap = s.approvals[a] ?? 0n;
+        return out > ap ? out : ap;
+    };
+    // 4. per-call caps
+    for (const a of touched) {
+        const c = caps[a]?.perCall;
+        const amt = amountOf(a);
+        if (c !== undefined && amt > c)
+            return blockWith(base, "cap-per-call", `Not signed: ${amt} of ${fmt(a)} is over the per-call cap of ${c}.`, s, { asset: a, amount: amt, limit: c });
+    }
+    const x402url = typeof input?.x402?.url === "string" ? input.x402.url : typeof input?.x402?.resource === "string" ? input.x402.resource : undefined;
+    const eps = input?.x402 ? endpointCaps(sp, io._endpoint ?? x402url) : [];
+    const epAmount = Object.values(s.outflow).reduce((m, v) => (v > m ? v : m), 0n);
+    for (const [p, c] of eps) {
+        if (c.perCall !== undefined && epAmount > c.perCall)
+            return blockWith(base, "cap-endpoint", `Not paid: ${epAmount} is over the per-call cap of ${c.perCall} for ${p}.`, s, { amount: epAmount, limit: c.perCall });
+    }
+    // 5. day caps: outflows are reserved; an allowance must fit in what is left today (checked, not reserved)
+    const held = [];
+    const day = dayStart(Date.now());
+    const giveBack = async () => {
+        for (const id of held)
+            await store.release(id);
+        held.length = 0;
+    };
+    const reserve = async (key, amt, limit, keep, code, msg, asset) => {
+        const r = await store.reserve(key, amt, limit, day);
+        if (!r.ok) {
+            await giveBack();
+            await blockWith(base, code, `${msg} (${r.used} of ${limit} used today).`, s, { asset, amount: amt, limit });
+        }
+        if (keep && !preview)
+            held.push(r.id);
+        else
+            await store.release(r.id);
+    };
+    for (const a of touched) {
+        const c = caps[a]?.perDay;
+        if (c === undefined)
+            continue;
+        const out = s.outflow[a] ?? 0n;
+        if (out > 0n)
+            await reserve(`day:${a}`, out, c, true, "cap-per-day", `Not signed: ${out} more of ${fmt(a)} is over the day cap of ${c}`, a);
+        const ap = s.approvals[a] ?? 0n;
+        if (ap > 0n)
+            await reserve(`day:${a}`, ap, c, false, "cap-per-day", `Not signed: an allowance of ${ap} ${fmt(a)} is over what is left of the day cap of ${c}`, a);
+    }
+    for (const [p, c] of eps) {
+        if (c.perDay !== undefined && epAmount > 0n)
+            await reserve(`endpoint:${p}`, epAmount, c.perDay, true, "cap-endpoint", `Not paid: ${epAmount} more is over the day cap of ${c.perDay} for ${p}`);
+    }
+    // 6. human approval above a threshold
+    const above = lower(sp.approveAbove);
+    const over = touched.filter((a) => above[a] !== undefined && amountOf(a) > above[a]).map((a) => ({ asset: a, amount: amountOf(a), threshold: above[a] }));
+    let approvalRef;
+    let needsApproval = false;
+    if (over.length && preview)
+        needsApproval = true;
+    else if (over.length) {
+        let ok = false;
+        try {
+            const res = sp.approve ? await sp.approve({ kind, input, assessment: base.assessment, spend: s, over }) : { approved: false };
+            ok = res?.approved === true;
+            approvalRef = res?.approvalRef;
+        }
+        catch (e) {
+            say(o, `approve threw: ${e?.message ?? e}`);
+        }
+        if (!ok) {
+            await giveBack();
+            const top = over[0];
+            return blockWith(base, "approval-denied", `Not signed: ${top.amount} of ${fmt(top.asset)} is over ${top.threshold} and was not approved${sp.approve ? "" : " (no approve function)"}.`, s, { asset: top.asset, amount: top.amount, limit: top.threshold });
+        }
+    }
+    const r = { ...base, spend: { spend: s, reservations: [...held], ...(approvalRef !== undefined ? { approvalRef } : {}), ...(needsApproval ? { needsApproval } : {}) } };
+    if (!preview) {
+        await report(o, r);
+        io._collect?.push(r);
+    }
+    return r;
+}
+/** a request the spend policy refuses outside enforce (a repeated x402 payment id): reported, then TollPolicyError */
+export async function policyRefuse(kind, input, code, message, o) {
+    const r = { kind, input, assessment: null, decision: "blocked", basis: "policy", policy: code, paidUrl: null };
+    await report(o, r);
+    throw new TollPolicyError(code, message, { report: r });
+}
+const kindOf = (i) => i.x402 ? "x402" : i.userOp ? "userOp" : i.typedData || i.rpc?.method === "eth_signTypedData_v4" ? "typedData" : i.message || i.rpc ? "message" : "transaction";
+/**
+ * What the guard would do with this request, without doing it: Toll is asked and every spend rule is checked, but
+ * nothing is reserved, `approve` is not called and onReport is not called. When allowed, `confirmId` passed as
+ * `tollConfirm` on the send within 30 s skips the second Toll call (once, and only for the identical request).
+ */
+export async function preview(input, opts = {}) {
+    const { kind: k, ...rest } = opts;
+    const kind = k ?? kindOf(input);
+    const io = { ...rest, onReport: undefined, _preview: true };
+    try {
+        const r = await enforce(kind, () => input, io);
+        return {
+            decision: "allowed",
+            basis: r.basis,
+            assessment: r.assessment,
+            ...(r.spend ? { spend: r.spend.spend } : {}),
+            ...(r.spend?.needsApproval ? { needsApproval: true } : {}),
+            paidUrl: r.paidUrl,
+            confirmId: r.assessment ? rememberConfirm(input, r.assessment) : "",
+        };
+    }
+    catch (e) {
+        const rep = e.report;
+        if (e instanceof TollPolicyError) {
+            return { decision: "blocked", basis: "policy", policy: e.code, assessment: rep?.assessment ?? null, ...(rep?.spend ? { spend: rep.spend.spend } : {}), reason: e.message, paidUrl: rep?.paidUrl ?? null, confirmId: "" };
+        }
+        if (e instanceof TollBlockedError) {
+            return { decision: "blocked", basis: e.assessment.action, assessment: e.assessment, reason: e.message, paidUrl: paidUrlOf(e.assessment), confirmId: "" };
+        }
+        if (e instanceof TollUnavailableError) {
+            return { decision: "blocked", basis: e.reason === "unsupported" ? "unsupported" : "unavailable", assessment: null, reason: e.message, paidUrl: e.paidUrl, confirmId: "" };
+        }
+        throw e;
+    }
+}

package/dist/spend.d.ts

@@ -0,0 +1,48 @@
+/**
+ * What a request spends, read locally (calldata, typed data, an x402 requirement) and, when Toll's answer carries one,
+ * from its simulation (x-toll.simulation). Only outflows of the spend assets count (default: native ETH, WETH and USDG
+ * on Robinhood Chain), so selling a coin that is not a spend asset is never capped.
+ */
+import { type CheckInput, type RiskAssessment } from "./check.js";
+/** native ETH as a spend-asset key */
+export declare const NATIVE = "native";
+/** USDG on Robinhood Chain */
+export declare const USDG = "0x5fc5360d0400a0fd4f2af552add042d716f1d168";
+/** WETH on Robinhood Chain */
+export declare const WETH = "0x0bd7d308f8e1639fab988df18a8011f41eacad73";
+/** the spend assets when none are given */
+export declare const DEFAULT_SPEND_ASSETS: readonly string[];
+/** an unlimited allowance (type(uint256).max): larger than any cap */
+export declare const UNLIMITED: bigint;
+export interface SpendItem {
+    kind: "value" | "transfer" | "approve" | "x402" | "simulation";
+    /** "native" or a lowercase token address */
+    asset: string;
+    /** base units; UNLIMITED for an unlimited allowance */
+    amount: bigint;
+    to?: string;
+    spender?: string;
+    payTo?: string;
+}
+export interface Spend {
+    items: SpendItem[];
+    /** per asset, base units leaving the signer: the larger of what the call declares and what the simulation shows */
+    outflow: Record<string, bigint>;
+    /** per asset, the largest allowance granted (UNLIMITED = infinite) */
+    approvals: Record<string, bigint>;
+    /** who the request pays or calls (a token transfer's recipient, else the transaction's `to`), lowercase */
+    to: string[];
+    /** spenders an approval or permit names, lowercase */
+    spender: string[];
+    /** x402 payees, lowercase */
+    payTo: string[];
+    /** true when what leaves the wallet could not be read (a contract call with no simulation, a raw user operation) */
+    unknown: boolean;
+    /** true when Toll's simulation was read */
+    simulated: boolean;
+}
+/**
+ * What a request spends. `assessment` is Toll's answer (null when Toll was not asked or could not answer): its
+ * simulation, when read, beats the declared amounts upward. `assets` are the spend assets ("native" or token addresses).
+ */
+export declare function spendOf(input: CheckInput, assessment: RiskAssessment | null | undefined, assets?: readonly string[]): Spend;

package/dist/spend.js

@@ -0,0 +1,239 @@
+/**
+ * What a request spends, read locally (calldata, typed data, an x402 requirement) and, when Toll's answer carries one,
+ * from its simulation (x-toll.simulation). Only outflows of the spend assets count (default: native ETH, WETH and USDG
+ * on Robinhood Chain), so selling a coin that is not a spend asset is never capped.
+ */
+import { isAddress } from "./check.js";
+/** native ETH as a spend-asset key */
+export const NATIVE = "native";
+/** USDG on Robinhood Chain */
+export const USDG = "0x5fc5360d0400a0fd4f2af552add042d716f1d168";
+/** WETH on Robinhood Chain */
+export const WETH = "0x0bd7d308f8e1639fab988df18a8011f41eacad73";
+/** the spend assets when none are given */
+export const DEFAULT_SPEND_ASSETS = [NATIVE, WETH, USDG];
+/** an unlimited allowance (type(uint256).max): larger than any cap */
+export const UNLIMITED = (1n << 256n) - 1n;
+/** Permit2 (same address on every chain) */
+const PERMIT2 = "0x000000000022d473030f116ddee9f6b43ac78ba3";
+/** native ETH as the simulation names it */
+const SIM_NATIVE = "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee";
+const lc = (x) => String(x ?? "").toLowerCase();
+const big = (x) => {
+    try {
+        if (typeof x === "bigint")
+            return x;
+        if (typeof x === "number")
+            return Number.isSafeInteger(x) ? BigInt(x) : null;
+        if (typeof x === "string" && /^(0x[0-9a-fA-F]+|\d+)$/.test(x.trim()))
+            return BigInt(x.trim());
+    }
+    catch {
+        /* unreadable */
+    }
+    return null;
+};
+const SEL = {
+    transfer: "0xa9059cbb",
+    transferFrom: "0x23b872dd",
+    approve: "0x095ea7b3",
+    increaseAllowance: "0x39509351",
+    deposit: "0xd0e30db0",
+    withdraw: "0x2e1a7d4d",
+};
+function words(data) {
+    const body = data.slice(10);
+    const out = [];
+    for (let i = 0; i + 64 <= body.length; i += 64)
+        out.push(body.slice(i, i + 64));
+    return out;
+}
+const wAddr = (w) => (w ? "0x" + w.slice(24).toLowerCase() : "");
+const wInt = (w) => (w ? BigInt("0x" + w) : 0n);
+class Acc {
+    assets;
+    items = [];
+    declared = {};
+    simOut = {};
+    approvals = {};
+    to = new Set();
+    spender = new Set();
+    payTo = new Set();
+    unknown = false;
+    simulated = false;
+    constructor(assets) {
+        this.assets = assets;
+    }
+    out(asset, amount, item, max = false) {
+        if (!this.assets.has(asset) || amount <= 0n)
+            return;
+        const cur = this.declared[asset] ?? 0n;
+        this.declared[asset] = max ? (amount > cur ? amount : cur) : cur + amount;
+        this.items.push({ ...item, asset, amount });
+    }
+    approve(asset, amount, spender) {
+        if (spender)
+            this.spender.add(spender);
+        if (!this.assets.has(asset))
+            return;
+        const cur = this.approvals[asset] ?? 0n;
+        if (amount > cur)
+            this.approvals[asset] = amount;
+        this.items.push({ kind: "approve", asset, amount, spender });
+    }
+    done() {
+        const outflow = {};
+        for (const a of new Set([...Object.keys(this.declared), ...Object.keys(this.simOut)])) {
+            const d = this.declared[a] ?? 0n;
+            const s = this.simOut[a] ?? 0n;
+            outflow[a] = s > d ? s : d;
+        }
+        return { items: this.items, outflow, approvals: this.approvals, to: [...this.to], spender: [...this.spender], payTo: [...this.payTo], unknown: this.unknown && !this.simulated, simulated: this.simulated };
+    }
+}
+function decodeTx(i, acc) {
+    const from = isAddress(i.from) ? lc(i.from) : null;
+    const target = lc(i.to);
+    const value = big(i.value ?? 0) ?? 0n;
+    const data = typeof i.data === "string" ? i.data : "0x";
+    if (value > 0n)
+        acc.out(NATIVE, value, { kind: "value", to: target });
+    if (data.length < 10) {
+        if (target)
+            acc.to.add(target);
+        return;
+    }
+    const sel = data.slice(0, 10).toLowerCase();
+    const w = words(data);
+    if (sel === SEL.transfer && w.length >= 2) {
+        const to = wAddr(w[0]);
+        acc.to.add(to);
+        acc.out(target, wInt(w[1]), { kind: "transfer", to });
+        return;
+    }
+    if (sel === SEL.transferFrom && w.length >= 3) {
+        const src = wAddr(w[0]);
+        const to = wAddr(w[2]);
+        acc.to.add(to);
+        // only the signer's own tokens are its spend
+        if (!from || src === from)
+            acc.out(target, wInt(w[2]), { kind: "transfer", to });
+        return;
+    }
+    if ((sel === SEL.approve || sel === SEL.increaseAllowance) && w.length >= 2) {
+        acc.approve(target, wInt(w[1]), wAddr(w[0]));
+        return;
+    }
+    acc.to.add(target);
+    // WETH deposit (the value is already counted) and withdraw (WETH back to ETH): no new spend
+    if (target === WETH && (sel === SEL.deposit || sel === SEL.withdraw))
+        return;
+    acc.unknown = true;
+}
+function decodeTyped(td, acc, signer) {
+    const vc = lc(td.domain?.verifyingContract);
+    const m = (td.message ?? {});
+    const p = String(td.primaryType ?? "");
+    if (vc === PERMIT2) {
+        const spender = lc(m.spender);
+        if (p === "PermitSingle")
+            acc.approve(lc(m.details?.token), big(m.details?.amount) ?? UNLIMITED, spender);
+        else if (p === "PermitBatch")
+            for (const d of Array.isArray(m.details) ? m.details : [])
+                acc.approve(lc(d?.token), big(d?.amount) ?? UNLIMITED, spender);
+        else if (p === "PermitTransferFrom" || p === "PermitWitnessTransferFrom")
+            acc.approve(lc(m.permitted?.token), big(m.permitted?.amount) ?? UNLIMITED, spender);
+        else if (p === "PermitBatchTransferFrom" || p === "PermitBatchWitnessTransferFrom")
+            for (const d of Array.isArray(m.permitted) ? m.permitted : [])
+                acc.approve(lc(d?.token), big(d?.amount) ?? UNLIMITED, spender);
+        return;
+    }
+    if (p === "Permit" && m.spender !== undefined) {
+        acc.approve(vc, big(m.value) ?? UNLIMITED, lc(m.spender));
+        return;
+    }
+    if ((p === "TransferWithAuthorization" || p === "ReceiveWithAuthorization") && (!signer || lc(m.from) === signer || m.from === undefined)) {
+        const to = lc(m.to);
+        acc.to.add(to);
+        acc.out(vc, big(m.value) ?? 0n, { kind: "transfer", to });
+    }
+}
+function typedOf(i) {
+    if (i.typedData)
+        return i.typedData;
+    if (i.rpc?.method !== "eth_signTypedData_v4")
+        return null;
+    let td = i.rpc.params?.[1];
+    if (typeof td === "string") {
+        try {
+            td = JSON.parse(td);
+        }
+        catch {
+            return null;
+        }
+    }
+    return td && typeof td === "object" ? td : null;
+}
+function decodeX402(x, acc) {
+    const entries = Array.isArray(x.accepts) ? x.accepts : [x];
+    for (const raw of entries) {
+        const e = (raw && typeof raw === "object" ? raw : {});
+        const payTo = lc(e.payTo);
+        if (payTo)
+            acc.payTo.add(payTo);
+        const amt = big(e.amount ?? e.maxAmountRequired);
+        // the client pays one entry: the largest per asset counts
+        if (amt !== null)
+            acc.out(lc(e.asset), amt, { kind: "x402", payTo }, true);
+    }
+}
+function readSim(a, from, acc) {
+    const s = a?.["x-toll"]?.simulation;
+    if (!s || !from)
+        return;
+    const eff = s.status === "success" || s.status === "reverted" ? s : s.status === "insufficient-eth" ? s.effects : null;
+    if (!eff || !Array.isArray(eff.deltas))
+        return;
+    acc.simulated = true;
+    for (const d of eff.deltas) {
+        if (lc(d?.holder) !== from)
+            continue;
+        const delta = big(String(d?.delta ?? "").replace(/^-/, ""));
+        if (delta === null || !String(d?.delta).startsWith("-"))
+            continue;
+        const tok = lc(d?.token);
+        const asset = tok === SIM_NATIVE || tok === "0x0000000000000000000000000000000000000000" ? NATIVE : tok;
+        if (!acc.assets.has(asset))
+            continue;
+        acc.simOut[asset] = (acc.simOut[asset] ?? 0n) + delta;
+        acc.items.push({ kind: "simulation", asset, amount: delta });
+    }
+    for (const ap of Array.isArray(eff.approvals) ? eff.approvals : []) {
+        if (lc(ap?.owner) !== from || ap?.kind === "nft-all")
+            continue;
+        acc.approve(lc(ap?.token), ap?.amount === null || ap?.amount === undefined ? UNLIMITED : (big(ap.amount) ?? UNLIMITED), lc(ap?.spender));
+    }
+}
+/**
+ * What a request spends. `assessment` is Toll's answer (null when Toll was not asked or could not answer): its
+ * simulation, when read, beats the declared amounts upward. `assets` are the spend assets ("native" or token addresses).
+ */
+export function spendOf(input, assessment, assets = DEFAULT_SPEND_ASSETS) {
+    const acc = new Acc(new Set(assets.map(lc)));
+    const isTx = input.to !== undefined || input.data !== undefined;
+    const signer = isAddress(input.from) ? lc(input.from) : isAddress(input.message?.from) ? lc(input.message?.from) : null;
+    if (isTx)
+        decodeTx(input, acc);
+    else if (input.authorizationList && input.authorizationList.length)
+        acc.unknown = true; // a delegation can move anything
+    if (input.userOp)
+        acc.unknown = true; // raw callData is not decoded here
+    const td = typedOf(input);
+    if (td)
+        decodeTyped(td, acc, signer);
+    if (input.x402)
+        decodeX402(input.x402, acc);
+    if (isTx)
+        readSim(assessment, signer, acc);
+    return acc.done();
+}

package/dist/store.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Where the guard keeps its spend counters and the x402 payment ids it has paid. The default MemorySpendStore lives in
+ * this process: it resets on restart and is not shared between processes. Pass your own SpendStore (Redis, a database)
+ * for counters that survive restarts or span several workers.
+ */
+export interface SpendStore {
+    /**
+     * Reserves `amt` under key `k` in the window starting at `windowStart` (ms, UTC). ok when committed + pending + amt
+     * stays within `limit`; `used` is committed + pending after the call. Must be atomic per key.
+     */
+    reserve(k: string, amt: bigint, limit: bigint, windowStart: number): Promise<{
+        ok: boolean;
+        id: string;
+        used: bigint;
+    }>;
+    /** the reservation was spent: it stays counted */
+    commit(id: string): Promise<void>;
+    /** the reservation was not spent (refused, the send threw): it no longer counts */
+    release(id: string): Promise<void>;
+    /** true when this x402 payment id was paid within its TTL */
+    paymentSeen(id: string): Promise<boolean>;
+    markPaid(id: string, ttlS: number): Promise<void>;
+}
+/** the start of the UTC day holding `t` (ms) */
+export declare const dayStart: (t: number) => number;
+/** an in-process SpendStore: resets on restart, not shared between processes */
+export declare class MemorySpendStore implements SpendStore {
+    private readonly buckets;
+    private readonly where;
+    private readonly paid;
+    private readonly now;
+    private seq;
+    constructor(o?: {
+        now?: () => number;
+    });
+    private prune;
+    reserve(k: string, amt: bigint, limit: bigint, windowStart: number): Promise<{
+        ok: boolean;
+        id: string;
+        used: bigint;
+    }>;
+    commit(id: string): Promise<void>;
+    release(id: string): Promise<void>;
+    paymentSeen(id: string): Promise<boolean>;
+    markPaid(id: string, ttlS: number): Promise<void>;
+}