@tollxyz/guard 0.2.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;
@@ -31,9 +51,49 @@ async function report(o, r) {
         say(o, `onReport threw: ${e?.message ?? e}`);
     }
 }
+const SIGN_RPC = new Set(["personal_sign", "eth_sign", "eth_signTypedData_v4"]);
+/** the typed data a request signs: its typedData, or an eth_signTypedData_v4 request's params[1] (JSON or object) */
+function typedOf(input) {
+    if (input.typedData)
+        return input.typedData;
+    if (input.rpc?.method !== "eth_signTypedData_v4")
+        return null;
+    let td = input.rpc.params?.[1];
+    if (typeof td === "string") {
+        try {
+            td = JSON.parse(td);
+        }
+        catch {
+            return null;
+        }
+    }
+    return td && typeof td === "object" ? td : null;
+}
+/** true for a signature request (typed data, a message, a signing RPC) rather than a transaction or an x402 payment */
+export const isSignature = (input) => !!input && !input.x402 && (!!input.typedData || !!input.message || SIGN_RPC.has(String(input.rpc?.method)));
+/** true for eth_sign: it signs any 32 bytes (a transaction hash included), so it fails closed when Toll cannot answer */
+export const isEthSign = (input) => input?.message?.kind === "eth_sign" || input?.rpc?.method === "eth_sign";
+/** the other chain a typed-data signature names (its domain chainId), or null (Robinhood Chain, none, or an x402 payment) */
+function otherChainSignature(input) {
+    if (input.x402)
+        return null;
+    const c = typedOf(input)?.domain?.chainId;
+    const cid = c === undefined || c === null ? null : chainIdOf(c);
+    return cid !== null && cid !== TX_CHAIN_ID ? cid : null;
+}
+/** Toll's 400 for a request on another chain ("... chainId N is not read ...") */
+const OTHER_CHAIN_400 = /chainId \d+ is not read/;
 /** why Toll would not read this request, or null when it does */
 export function unsupportedWhy(input) {
     const tx = input.to !== undefined || input.data !== undefined;
+    const auths = !!input.authorizationList && input.authorizationList.length > 0;
+    if (!tx && auths) {
+        const cid = input.chainId === undefined ? null : chainIdOf(input.chainId);
+        if (input.chainId !== undefined && cid === null)
+            return "the chain id could not be read";
+        if (cid !== null && cid !== TX_CHAIN_ID)
+            return `chain ${cid} is not read (Robinhood Chain ${TX_CHAIN_ID} only for now)`;
+    }
     if (tx) {
         if (input.to === undefined || input.to === null)
             return "a contract deployment (no `to`) is not read";
@@ -43,13 +103,10 @@ export function unsupportedWhy(input) {
         if (cid !== null && cid !== TX_CHAIN_ID)
             return `chain ${cid} is not read (Robinhood Chain ${TX_CHAIN_ID} only for now)`;
     }
-    if (input.typedData && !input.x402) {
-        const c = input.typedData.domain?.chainId;
-        const cid = c === undefined || c === null ? null : chainIdOf(c);
-        if (cid !== null && cid !== TX_CHAIN_ID)
-            return `a signature for chain ${cid} is not read (Robinhood Chain ${TX_CHAIN_ID} only for now)`;
-    }
-    if (!tx && !input.typedData && !input.x402)
+    const other = otherChainSignature(input);
+    if (other !== null)
+        return `a signature for chain ${other} is not read (Robinhood Chain ${TX_CHAIN_ID} only for now)`;
+    if (!tx && !auths && !input.typedData && !input.x402 && !input.message && !input.rpc && !input.userOp)
         return "nothing to check";
     return null;
 }
@@ -59,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();
@@ -68,6 +129,10 @@ export async function enforce(kind, build, o = {}) {
         return unavailable(kind, null, err, o);
     }
     const why = unsupportedWhy(input);
+    // a signature for another chain is not "unsupported -> allow": an off-chain signature Toll cannot read is refused
+    if (why && isSignature(input) && otherChainSignature(input) !== null && o.onUnsupported !== "allow") {
+        return refuse(kind, input, "signature-other-chain", `Not signed: ${why}. A signature Toll cannot read could hand over anything; onUnsupported: "allow" lets it through unchecked.`, o);
+    }
     if (why) {
         const blocked = resolvePolicy(o).onUnsupported === "block";
         const r = { kind, input, assessment: null, decision: blocked ? "blocked" : "allowed", basis: "unsupported", paidUrl: null };
@@ -78,10 +143,14 @@ 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 });
+        // Toll's 400 for a signature on another chain: blocked, never "unsupported -> allow"
+        if (err.reason === "bad-request" && isSignature(input) && OTHER_CHAIN_400.test(err.message) && o.onUnsupported !== "allow") {
+            return refuse(kind, input, "signature-other-chain", `Not signed: Toll does not read a signature for another chain (${err.message}). onUnsupported: "allow" lets it through unchecked.`, o);
+        }
         return unavailable(kind, input, err, o);
     }
     const paidUrl = paidUrlOf(a);
@@ -112,7 +181,8 @@ export async function enforce(kind, build, o = {}) {
     throw new TollBlockedError(a, "WARN");
 }
 async function unavailable(kind, input, err, o) {
-    const blocked = resolvePolicy(o).onUnavailable === "block";
+    // eth_sign signs any 32 bytes (a transaction hash included): it always fails closed
+    const blocked = resolvePolicy(o).onUnavailable === "block" || isEthSign(input);
     const r = { kind, input, assessment: null, decision: blocked ? "blocked" : "allowed", basis: "unavailable", paidUrl: err.paidUrl, error: err };
     await report(o, r);
     if (blocked)
@@ -129,12 +199,327 @@ export async function refuse(kind, input, code, message, o = {}) {
     await report(o, { kind, input, assessment: a, decision: "blocked", basis: "BLOCK", paidUrl: null });
     throw new TollBlockedError(a, "BLOCK");
 }
-/** the onAuthorization policy for an EIP-7702 authorization: resolves when it may go ahead, else throws */
+/**
+ * The onAuthorization policy for an EIP-7702 authorization. Resolves true when Toll checked the whole request (the
+ * "check" default: the caller asks nothing more), false when "allow" let it through unchecked (the caller still checks
+ * the rest of the request); throws when it is blocked. `input` is the request with its authorizationList, or a function
+ * that builds it; under "check", null is blocked (nothing to send).
+ */
 export async function gateAuthorization(kind, where, input, o = {}) {
-    if (o.onAuthorization === "allow") {
+    const p = o.onAuthorization ?? "check";
+    const shown = typeof input === "function" ? null : input;
+    if (p === "allow") {
         say(o, `EIP-7702 authorization (${where}) NOT checked, going ahead (onAuthorization "allow")`);
-        await report(o, { kind, input, assessment: null, decision: "allowed", basis: "unsupported", paidUrl: null });
+        await report(o, { kind, input: shown, assessment: null, decision: "allowed", basis: "unsupported", paidUrl: null });
+        return false;
+    }
+    const what = `${where} carries an EIP-7702 authorization, which sets this wallet's code to another contract that can then move everything it holds.`;
+    if (p === "block" || input === null) {
+        return refuse(kind, shown, "eip7702-authorization", `${what} ${p === "block" ? 'onAuthorization is "block"' : "It could not be read for Toll's check"}; onAuthorization: "allow" lets it through unchecked.`, o);
+    }
+    const build = typeof input === "function" ? input : () => input;
+    try {
+        // fail closed: an authorization Toll could not read is not signed
+        await enforce(kind, build, { ...o, onUnavailable: "block", onUnsupported: "block" });
+    }
+    catch (e) {
+        if (!(e instanceof TollUnavailableError))
+            throw e;
+        return refuse(kind, null, "eip7702-authorization", `${what} Toll could not read it (${e.message}), so it is not signed; onAuthorization: "allow" lets it through unchecked.`, o);
+    }
+    return true;
+}
+/**
+ * A batch (EIP-5792 sendCalls, wallet_sendCalls, a smart account's calls): each call is checked as its own transaction
+ * from the batch's sender, in order; the first one blocked stops the batch. Reports carry kind "calls".
+ */
+export async function enforceCalls(build, o = {}) {
+    let calls;
+    try {
+        calls = await build();
+    }
+    catch (e) {
+        const err = e instanceof TollUnavailableError ? e : new TollUnavailableError(`The batch could not be read for Toll's check: ${e?.message ?? e}`, { reason: "encode", cause: e });
+        return [await unavailable("calls", null, err, o)];
+    }
+    if (!calls.length)
+        return [await enforce("calls", () => ({}), o)];
+    const out = [];
+    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;
     }
-    await refuse(kind, input, "eip7702-authorization", `${where} carries an EIP-7702 authorization, which sets this wallet's code to another contract that can then move everything it holds. Toll does not read authorizations yet; onAuthorization: "allow" lets it through unchecked.`, o);
 }

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;