@tollxyz/guard 0.3.0 → 0.4.1

package/README.md

@@ -1,5 +1,13 @@
 # @tollxyz/guard
 
+> **New in 0.4.1: ALLOW tickets** (`ticket` option, `appendTicketSuffix`): a single-use, signed ticket for one exact
+> call, for contracts that require one. See [ALLOW tickets](#allow-tickets).
+
+> **New in 0.4.0: spend caps, allowlists, human approval and preview** (`spend` option). Unset, nothing changes.
+> See [0.4.0: spend caps, allowlists, approval, preview](#040-spend-caps-allowlists-approval-preview).
+
+> **0.3.1:** `signTypedData` (viem and ethers) now sends the signing account as `from`, so Toll can say what a Permit2 signature lets someone take.
+>
 > **What changed in 0.3.0: every signing method is checked.**
 > - Messages: viem and ethers `signMessage`, and `request()` for `personal_sign` and `eth_sign`.
 > - Typed data: `request()` for `eth_signTypedData_v4` too, any EIP-712 (orders, permits, sign-ins).
@@ -162,10 +170,208 @@ is at most `maxRetryWaitMs` (default 10 s); a coin still not read stays WARN, ne
 | `timeoutMs` | `15000` | one request to Toll |
 | `retry`, `maxRetryWaitMs` | `true`, `10000` | the one retry after Retry-After |
 | `baseUrl`, `fetch` | `https://t0ll.xyz`, global fetch | |
+| `spend` | none | 0.4.0: caps, allowlists, approval ([below](#040-spend-caps-allowlists-approval-preview)); unset = 0.3.x behaviour |
+| `store` | in-process `MemorySpendStore` | where spend counters and paid x402 ids live |
+| `failClosed` | `false` | with `spend`: a request whose spend cannot be read is blocked |
+| `ticket` | none | 0.4.1: `true` or `{consumer?, scope?}`: ask Toll for a single-use ALLOW ticket for this exact call; it comes back as `report.ticket` ([below](#allow-tickets)) |
 
 Errors: `TollBlockedError` (`.assessment`, `.codes`, message lists each code and message) and
 `TollUnavailableError` (`.reason`, `.status`, `.paidUrl`).
 
+## 0.4.0: spend caps, allowlists, approval, preview
+
+Toll's verdict says whether a request looks safe. `spend` adds your own limits on top: how much the agent may spend
+per call and per UTC day, who it may pay, and when a human has to say yes. Without `spend` nothing changes: 0.4.0
+behaves exactly like 0.3.x.
+
+The order for every request:
+
+1. **Allowlists** (`allow.to`, `allow.spender`, `allow.payTo`): read from the request itself, before Toll is asked.
+   Off the list = blocked, and Toll is not called.
+2. **Toll's verdict**: ALLOW / WARN / BLOCK with your `onWarn`, `onBlock`, `onUnavailable` as before. A WARN that
+   `block-high` blocks is still blocked, however small the amount.
+3. **Caps** (`assets`, `perEndpoint`): per call, then per day. The day amount is reserved.
+4. **Approval** (`approveAbove` + `approve`): above the threshold your `approve` function decides.
+5. **After the send**: the reservation is committed. If the send throws (rejected, nonce too low, RPC down), it is
+   released, so failures never use up the day cap.
+
+Caps never relax Toll's verdict, and Toll's ALLOW never lifts a cap: a request must pass both.
+
+```ts
+import { guard, NATIVE, USDG, TollPolicyError } from "@tollxyz/guard";
+
+const wallet = guard(walletClient, {
+  spend: {
+    // base units: ETH in wei, USDG with 6 decimals
+    assets: {
+      [NATIVE]: { perCall: 10n ** 16n, perDay: 5n * 10n ** 16n }, // 0.01 ETH a call, 0.05 ETH a day
+      [USDG]: { perCall: 20_000_000n, perDay: 100_000_000n },    // 20 USDG a call, 100 USDG a day
+    },
+    allow: { spender: ["0xYourRouter..."] },                     // approvals only to your router
+    approveAbove: { [USDG]: 10_000_000n },                       // above 10 USDG a human decides
+    approve: async (req) => {
+      const ok = await askOnTelegram(`Spend ${req.over[0].amount} of ${req.over[0].asset}?`);
+      return { approved: ok, approvalRef: ok ? "tg-msg-1234" : undefined };
+    },
+  },
+  failClosed: true, // a contract call whose spend cannot be read is blocked
+});
+
+try {
+  await wallet.sendTransaction(tx);
+} catch (e) {
+  if (e instanceof TollPolicyError) console.log(e.code, e.amount, e.limit); // "cap-per-day", ...
+  else throw e;
+}
+```
+
+**What counts as spend.** Only what leaves the wallet in a spend asset. The defaults are native ETH, WETH and USDG on
+Robinhood Chain, plus every asset you name in `assets` or `approveAbove`. A sell of any other coin is never capped.
+
+- Read locally, with no Toll answer needed: the transaction's value, ERC-20 `transfer` / `transferFrom` / `approve` /
+  `increaseAllowance` on a spend asset, EIP-2612 permits, Permit2 permits, EIP-3009 transfer authorizations, and an
+  x402 402's amount. So caps hold even when Toll is unreachable.
+- Any other contract call (a swap, a router): the amount comes from Toll's simulation (`x-toll.simulation.deltas`).
+  When the simulation shows more leaving than the call declares, the larger amount counts.
+- An approval counts against the per-call cap at its full size (an unlimited approval is over any cap) and must fit
+  in what is left of the day cap; it is not added to the day total (the later swap is).
+- Unknown spend: a contract call with no simulation (Toll unreachable), a raw user operation, a bare EIP-7702
+  authorization. `onUnknownSpend` decides: `"allow"` by default, `"block"` under `failClosed: true`.
+
+| `spend` field | |
+| --- | --- |
+| `assets` | `{ [asset]: { perCall?, perDay? } }`, asset = `"native"` or a token address, amounts in base units |
+| `perEndpoint` | x402 caps per URL prefix (origin + path), e.g. `{ "https://api.example.com/v1/": { perDay: 1_000_000n } }` |
+| `allow` | `{ to?, spender?, payTo? }`: every recipient (or called contract), approval spender, x402 payee must be listed |
+| `approveAbove` | `{ [asset]: amount }`: above it, `approve` must say yes |
+| `approve` | `(req) => Promise<{ approved, approvalRef? }>`; no function = denied. `approvalRef` lands in `report.spend.approvalRef` |
+| `onUnknownSpend` | `"allow"` (default) or `"block"` (default under `failClosed`) |
+
+New options next to `spend`: `store` (where counters live, below) and `failClosed`.
+
+`TollPolicyError` extends `TollBlockedError` (existing `catch` blocks still see a block). `.code` is one of
+`not-allowlisted`, `cap-per-call`, `cap-per-day`, `cap-endpoint`, `approval-denied`, `duplicate-payment`,
+`unknown-spend`; `.asset`, `.amount`, `.limit` when they apply. The report has `basis: "policy"` and `policy: code`.
+
+### Preview, then confirm
+
+```ts
+import { preview } from "@tollxyz/guard";
+
+const p = await preview({ chainId: 4663, from, to, data, value }, opts); // same opts as the guard
+// p.decision "allowed" | "blocked", p.basis, p.policy, p.spend, p.needsApproval, p.reason
+if (p.decision === "allowed") await wallet.sendTransaction({ to, data, value, tollConfirm: p.confirmId });
+```
+
+`preview` asks Toll and checks every rule, but reserves nothing, calls no `approve` and no `onReport`. Passing its
+`confirmId` as `tollConfirm` within 30 seconds reuses that Toll answer (one Toll call instead of two). It is used
+once, and only for the identical request; anything else is checked again. The guard strips `tollConfirm` before the
+wallet sees the request (viem `sendTransaction` / `signTransaction` / `writeContract`, ethers `sendTransaction` /
+`signTransaction`).
+
+### x402: payment ids and per-endpoint caps
+
+With `spend` set, `guardX402Fetch` also:
+
+- counts a 402's amount against `assets` and `perEndpoint` caps when it is checked. The reservation waits for the
+  paid retry: committed when the seller answers, released on another 402 or an error, released after `holdMs`
+  (default 2 minutes) when no paid retry comes.
+- never pays the same x402 `payment-identifier` twice. An id is marked paid only when the seller accepts the paid
+  request (any answer but 402); sending that id again throws `TollPolicyError` `duplicate-payment` (ids are kept
+  `paymentIdTtlS`, default 1 day). A second send of an id that is still in flight is refused too. After a network
+  error or timeout the same id may be retried (the seller dedupes it): the retry reuses the reservation of its 402,
+  so nothing is counted twice. A different id is a new payment.
+
+### Where the counters live
+
+The default store is a `MemorySpendStore` in this process, one per `spend` object. **It resets when the process
+restarts and is not shared between processes**: two workers each get the full day cap. For a cap that survives
+restarts or spans workers, pass your own `store` implementing `SpendStore`:
+
+```ts
+interface SpendStore {
+  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>;
+}
+```
+
+A Redis store (example only, not shipped; `reserve` must be atomic, hence the Lua script):
+
+```ts
+import Redis from "ioredis";
+import type { SpendStore } from "@tollxyz/guard";
+
+const redis = new Redis(process.env.REDIS_URL!);
+const RESERVE = `
+local used = tonumber(redis.call('GET', KEYS[1]) or '0')
+local amt, limit = tonumber(ARGV[1]), tonumber(ARGV[2])
+if used + amt > limit then return {0, tostring(used)} end
+redis.call('INCRBY', KEYS[1], ARGV[1])
+redis.call('EXPIRE', KEYS[1], 172800)
+redis.call('SET', KEYS[2], KEYS[1] .. '|' .. ARGV[1], 'EX', 3600)
+return {1, tostring(used + amt)}`;
+const RELEASE = `
+local v = redis.call('GET', KEYS[1])
+if not v then return 0 end
+local sep = string.find(v, '|', 1, true)
+redis.call('DECRBY', string.sub(v, 1, sep - 1), string.sub(v, sep + 1))
+redis.call('DEL', KEYS[1])
+return 1`;
+
+export const redisStore: SpendStore = {
+  async reserve(k, amt, limit, windowStart) {
+    const id = `toll:res:${crypto.randomUUID()}`;
+    // amounts as numbers in Lua: fine below 2^53 base units; use string math for larger caps
+    const [ok, used] = (await redis.eval(RESERVE, 2, `toll:cap:${k}:${windowStart}`, id, amt.toString(), limit.toString())) as [number, string];
+    return { ok: ok === 1, id: ok === 1 ? id : "", used: BigInt(used) };
+  },
+  async commit(id) { await redis.del(id); },          // the amount stays in the day counter
+  async release(id) { await redis.eval(RELEASE, 1, id); },
+  async paymentSeen(id) { return (await redis.exists(`toll:paid:${id}`)) === 1; },
+  async markPaid(id, ttlS) { await redis.set(`toll:paid:${id}`, "1", "EX", ttlS); },
+};
+
+const wallet = guard(walletClient, { spend: { /* ... */ }, store: redisStore });
+```
+
+## ALLOW tickets
+
+A contract can require a Toll ALLOW ticket before a sensitive call (a router, a module, a Uniswap v4 hook, a
+delegation caveat). The Solidity side is [toll-allow](https://github.com/t0ll-xyz/toll-allow); the full guide is
+https://t0ll.xyz/agents/allow.
+
+- A ticket is an EIP-712 verdict signed by Toll for **one exact call** (target, value, data), one account (`from`),
+  an optional consumer contract and a 60 second window. It is single use.
+- A BLOCK is never signed. A WARN is signed only when no warning is high or critical (as verdict 1). No ticket
+  without `from`, or for a transaction with an EIP-7702 authorization list. When none is issued, `report.ticket` is
+  `{ why }`.
+- Toll's production signer on Robinhood Chain (4663) is `0x4A2C93066d94F1E69f3EAd5438c4efDdf80a46ba`
+  (`TOLL_ALLOW_SIGNER`). Pin it in your contract, or a `TollSignerSet` you control that includes it.
+
+```ts
+import { enforce, appendTicketSuffix } from "@tollxyz/guard";
+
+// 1. check the inner call (what the router will call), bound to your router as the consumer
+const r = await enforce("transaction", () => ({ chainId: 4663, from: me, to: target, data, value }), {
+  ticket: { consumer: ROUTER },
+});
+if (!r.ticket || !("signature" in r.ticket)) throw new Error(r.ticket?.why ?? "no ticket");
+
+// 2. put the ticket on the calldata: data ‖ abi.encode(ticket, signature) ‖ uint32 len ‖ 0x900bc3e1
+const withTicket = appendTicketSuffix(data, r.ticket.ticket, r.ticket.signature);
+// 3. call the router within 60 s: router.exec(target, withTicket) with the same value, from the same account
+```
+
+`appendTicketSuffix` is byte for byte `TollAllow.encodeSuffix` (tested against toll-allow's vectors). For a v4 hook,
+ask with `scope: "v4swap"` and pass `abi.encode(ticket, signature)` as `hookData`. The same option works on
+`checkTx(input, { ticket })`, where the ticket is in `assessment["x-toll"].ticket`.
+
+A ticket is necessary, never sufficient: the contract keeps its own checks (slippage, limits, access control), and
+should keep an owner bypass behind a timelock in case Toll is unreachable.
+
 ## Fail-open or fail-closed
 
 The default is fail-open: if Toll cannot answer, the signature goes ahead, with a `[toll-guard] ... NOT checked`

package/dist/check.d.ts

@@ -2,6 +2,7 @@
  * The one call to Toll: POST https://t0ll.xyz/api/tx/check. Every check runs on Toll's server, so a new check reaches
  * every agent without a package update. This file only sends the request and reads the answer.
  */
+import { type TicketAsk } from "./ticket.js";
 export declare const DEFAULT_BASE_URL = "https://t0ll.xyz";
 /** Robinhood Chain: the only chain the pre-sign check reads for now */
 export declare const TX_CHAIN_ID = 4663;
@@ -117,11 +118,16 @@ export interface CheckOptions {
     maxRetryWaitMs?: number;
     /** for tests */
     sleep?: (ms: number) => Promise<void>;
+    /**
+     * 0.4.1: ask Toll for a single-use ALLOW ticket for this exact call (`true`, or {consumer?, scope?}). It comes back
+     * in x-toll.ticket (and on the GuardReport): signed, or with why none was issued. A BLOCK is never signed.
+     */
+    ticket?: boolean | TicketAsk;
 }
 export declare class TollBlockedError extends Error {
     readonly assessment: RiskAssessment;
     readonly codes: string[];
-    constructor(assessment: RiskAssessment, why?: Action);
+    constructor(assessment: RiskAssessment, why?: Action | "policy");
 }
 export type UnavailableReason = "network" | "timeout" | "rate-limited" | "server-error" | "bad-request" | "bad-answer" | "unsupported" | "encode";
 export declare class TollUnavailableError extends Error {

package/dist/check.js

@@ -2,6 +2,7 @@
  * The one call to Toll: POST https://t0ll.xyz/api/tx/check. Every check runs on Toll's server, so a new check reaches
  * every agent without a package update. This file only sends the request and reads the answer.
  */
+import { ticketAskOf } from "./ticket.js";
 export const DEFAULT_BASE_URL = "https://t0ll.xyz";
 /** Robinhood Chain: the only chain the pre-sign check reads for now */
 export const TX_CHAIN_ID = 4663;
@@ -19,7 +20,7 @@ export class TollBlockedError extends Error {
         const top = ws.filter((w) => w.severity !== "low").slice(0, 5);
         const lines = (top.length ? top : ws.slice(0, 5)).map((w) => `${w.code}: ${w.message}`);
         const link = assessment["x-toll"]?.link;
-        super(`Toll ${why}, not signed. ${lines.join(" | ") || "No reason given."}${link ? ` More: ${link}` : ""}`);
+        super(`${why === "policy" ? "Spend policy" : `Toll ${why}`}, not signed. ${lines.join(" | ") || "No reason given."}${link ? ` More: ${link}` : ""}`);
         this.name = "TollBlockedError";
         this.assessment = assessment;
         this.codes = ws.map((w) => w.code);
@@ -81,8 +82,12 @@ export function bodyOf(input) {
             b.from = input.from;
         b.authorizationList = input.authorizationList;
     }
-    if (input.typedData)
+    if (input.typedData) {
         b.typedData = input.typedData;
+        // the signer of typed data alone (0.3.1): Toll reads what the signature lets someone take from it
+        if (b.from === undefined && input.from !== undefined)
+            b.from = input.from;
+    }
     if (input.message)
         b.message = input.message;
     if (input.rpc)
@@ -179,7 +184,8 @@ export async function checkTx(input, opts = {}) {
     const base = trimBase(opts.baseUrl ?? DEFAULT_BASE_URL);
     const url = `${base}/api/tx/check`;
     const paid = `${base}${PAID_TX_PATH}`;
-    const body = toJson(bodyOf(input));
+    const ask = ticketAskOf(opts.ticket);
+    const body = toJson(ask ? { ...bodyOf(input), ticket: ask } : bodyOf(input));
     const first = await once(url, body, opts, f, paid);
     if (first.retryS === null || opts.retry === false)
         return first.a;

package/dist/index.d.ts

@@ -1,10 +1,16 @@
 export { checkTx, bodyOf, chainIdOf, paidUrlOf, isAssessment, TollBlockedError, TollUnavailableError, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, DEFAULT_MAX_RETRY_WAIT_MS, PAID_TX_PATH, PRESIGN_DOCS, TX_CHAIN_ID, } from "./check.js";
 export type { Action, Severity, RiskWarning, ScannerVerdict, TollExtra, RiskAssessment, SignMessageLike, RpcLike, CheckInput, CheckOptions, TypedDataLike, FetchLike, Hex, Numberish, UnavailableReason, } from "./check.js";
-export { enforce, enforceCalls, unsupportedWhy, refuse, gateAuthorization, resolvePolicy, hasHighWarning, isSignature, isEthSign } from "./policy.js";
-export type { GuardOptions, GuardReport, GuardKind, WarnPolicy, BlockPolicy } from "./policy.js";
+export { enforce, enforceCalls, unsupportedWhy, refuse, gateAuthorization, resolvePolicy, hasHighWarning, isSignature, isEthSign, TollPolicyError, commitSpend, releaseSpend, preview } from "./policy.js";
+export type { GuardOptions, GuardReport, GuardKind, WarnPolicy, BlockPolicy, SpendPolicy, Caps, ApprovalRequest, PolicyCode, GuardDecision } from "./policy.js";
 export { guard, guardViem, guardEthers, guardSmartAccount, isViemClient, isBundlerClient, primaryTypeOf } from "./wallets.js";
 export type { ViemGuardOptions } from "./wallets.js";
-export { guardX402Fetch, readPaymentRequired, readPaymentForms, paymentFormsDiffer } from "./x402.js";
+export { guardX402Fetch, readPaymentRequired, readPaymentForms, paymentFormsDiffer, paymentIdOf } from "./x402.js";
 export type { X402GuardOptions } from "./x402.js";
 export { read8470, latestFinding8470, decodeGetObservation, decodeLatestFinding, encodeGetObservation, encodeLatestByToken, encodeLatestFinding, FINDING_KINDS, NOT_READ, OBS_REGISTRY, OBS_DETECTOR, OBS_CHAIN_ID, RH_RPC, } from "./erc8470.js";
 export type { Observation8470, Finding8470, LatestFinding8470, Read8470Options, Lean, KeyKind, Unit } from "./erc8470.js";
+export { spendOf, NATIVE, USDG, WETH, DEFAULT_SPEND_ASSETS, UNLIMITED } from "./spend.js";
+export type { Spend, SpendItem } from "./spend.js";
+export { MemorySpendStore, dayStart } from "./store.js";
+export type { SpendStore } from "./store.js";
+export { appendTicketSuffix, encodeTicketAndSig, ticketAskOf, ticketOfAnswer, TICKET_SUFFIX_MAGIC, TOLL_ALLOW_SIGNER, ALLOW_DOCS } from "./ticket.js";
+export type { TicketAsk, AllowTicket, TicketResult } from "./ticket.js";

package/dist/index.js

@@ -1,5 +1,8 @@
 export { checkTx, bodyOf, chainIdOf, paidUrlOf, isAssessment, TollBlockedError, TollUnavailableError, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, DEFAULT_MAX_RETRY_WAIT_MS, PAID_TX_PATH, PRESIGN_DOCS, TX_CHAIN_ID, } from "./check.js";
-export { enforce, enforceCalls, unsupportedWhy, refuse, gateAuthorization, resolvePolicy, hasHighWarning, isSignature, isEthSign } from "./policy.js";
+export { enforce, enforceCalls, unsupportedWhy, refuse, gateAuthorization, resolvePolicy, hasHighWarning, isSignature, isEthSign, TollPolicyError, commitSpend, releaseSpend, preview } from "./policy.js";
 export { guard, guardViem, guardEthers, guardSmartAccount, isViemClient, isBundlerClient, primaryTypeOf } from "./wallets.js";
-export { guardX402Fetch, readPaymentRequired, readPaymentForms, paymentFormsDiffer } from "./x402.js";
+export { guardX402Fetch, readPaymentRequired, readPaymentForms, paymentFormsDiffer, paymentIdOf } from "./x402.js";
 export { read8470, latestFinding8470, decodeGetObservation, decodeLatestFinding, encodeGetObservation, encodeLatestByToken, encodeLatestFinding, FINDING_KINDS, NOT_READ, OBS_REGISTRY, OBS_DETECTOR, OBS_CHAIN_ID, RH_RPC, } from "./erc8470.js";
+export { spendOf, NATIVE, USDG, WETH, DEFAULT_SPEND_ASSETS, UNLIMITED } from "./spend.js";
+export { MemorySpendStore, dayStart } from "./store.js";
+export { appendTicketSuffix, encodeTicketAndSig, ticketAskOf, ticketOfAnswer, TICKET_SUFFIX_MAGIC, TOLL_ALLOW_SIGNER, ALLOW_DOCS } from "./ticket.js";

package/dist/policy.d.ts

@@ -1,4 +1,7 @@
-import { TollUnavailableError, type CheckInput, type CheckOptions, type RiskAssessment } from "./check.js";
+import { TollBlockedError, TollUnavailableError, type CheckInput, type CheckOptions, type RiskAssessment } from "./check.js";
+import { type TicketResult } from "./ticket.js";
+import { type Spend } from "./spend.js";
+import { type SpendStore } from "./store.js";
 export type WarnPolicy = "allow" | "block" | "block-high" | ((assessment: RiskAssessment) => boolean | Promise<boolean>);
 export type BlockPolicy = "throw" | ((assessment: RiskAssessment) => boolean | Promise<boolean>);
 export type GuardKind = "transaction" | "typedData" | "x402" | "message" | "userOp" | "calls";
@@ -10,11 +13,90 @@ export interface GuardReport {
     assessment: RiskAssessment | null;
     /** what the guard did */
     decision: "allowed" | "blocked";
-    /** why: Toll's action, "unavailable" (Toll could not answer) or "unsupported" (not a request Toll reads) */
-    basis: "ALLOW" | "WARN" | "BLOCK" | "unavailable" | "unsupported";
+    /**
+     * why: Toll's action, "unavailable" (Toll could not answer), "unsupported" (not a request Toll reads) or "policy"
+     * (blocked by your own spend rules: allowlist, cap, approval; `policy` says which)
+     */
+    basis: "ALLOW" | "WARN" | "BLOCK" | "unavailable" | "unsupported" | "policy";
     /** the paid route (no daily limit) when this caller's free checks are used */
     paidUrl: string | null;
     error?: TollUnavailableError;
+    /** the spend rule that blocked it (basis "policy") */
+    policy?: PolicyCode;
+    /** with `spend` set: what the request spends, the day-cap reservations it holds, and the approval reference */
+    spend?: {
+        spend: Spend;
+        reservations: string[];
+        approvalRef?: string;
+        needsApproval?: boolean;
+    };
+    /**
+     * 0.4.1, with the `ticket` option: Toll's single-use ALLOW ticket for this exact call ({ticket, signature, signer}),
+     * or {why} none was issued. Put it on the call with appendTicketSuffix (routers) or pass abi.encode(ticket, signature).
+     */
+    ticket?: TicketResult;
+}
+export type PolicyCode = "not-allowlisted" | "cap-per-call" | "cap-per-day" | "cap-endpoint" | "approval-denied" | "duplicate-payment" | "unknown-spend";
+export interface Caps {
+    /** the most one request may spend, base units */
+    perCall?: bigint;
+    /** the most all requests together may spend in one UTC day, base units */
+    perDay?: bigint;
+}
+export interface ApprovalRequest {
+    kind: GuardKind;
+    input: CheckInput | null;
+    /** Toll's answer (null when Toll could not answer) */
+    assessment: RiskAssessment | null;
+    spend: Spend;
+    /** each asset over its approveAbove threshold */
+    over: Array<{
+        asset: string;
+        amount: bigint;
+        threshold: bigint;
+    }>;
+}
+/**
+ * Your own rules around Toll's verdict. Order: allowlists (before Toll is asked) -> Toll's ALLOW / WARN / BLOCK
+ * (unchanged) -> per-call and per-day caps -> human approval -> the day reservation is committed after the send
+ * (released when the send throws). Keys are "native" or a token address (any case); amounts are base units.
+ */
+export interface SpendPolicy {
+    /** caps per spend asset; the spend assets are native, WETH and USDG plus every key here and in approveAbove */
+    assets?: Record<string, Caps>;
+    /** x402 caps per endpoint: a URL prefix (origin + path), in the payment asset's base units */
+    perEndpoint?: Record<string, Caps>;
+    /** when a list is given, every recipient / called contract, approval spender or x402 payee must be on it */
+    allow?: {
+        to?: string[];
+        spender?: string[];
+        payTo?: string[];
+    };
+    /** a spend (or allowance) above this amount needs `approve` to say yes */
+    approveAbove?: Record<string, bigint>;
+    /** asks a human (or another system); no function = denied */
+    approve?: (r: ApprovalRequest) => Promise<{
+        approved: boolean;
+        approvalRef?: string;
+    }>;
+    /** a request whose spend could not be read (a contract call Toll did not simulate): default "allow", "block" under failClosed */
+    onUnknownSpend?: "allow" | "block";
+}
+/** blocked by your own spend rules; a TollBlockedError, so existing catch blocks still see a block */
+export declare class TollPolicyError extends TollBlockedError {
+    readonly code: PolicyCode;
+    readonly asset?: string;
+    readonly amount?: bigint;
+    readonly limit?: bigint;
+    /** the guard's report of this request */
+    readonly report?: GuardReport;
+    constructor(code: PolicyCode, message: string, x?: {
+        asset?: string;
+        amount?: bigint;
+        limit?: bigint;
+        assessment?: RiskAssessment | null;
+        report?: GuardReport;
+    });
 }
 export interface GuardOptions extends CheckOptions {
     /**
@@ -53,6 +135,23 @@ export interface GuardOptions extends CheckOptions {
     onAuthorization?: "check" | "block" | "allow";
     /** the site asking for a signature (a URL or host name), sent with messages so Toll can match a sign-in's domain */
     origin?: string;
+    /** 0.4.0: spend caps, allowlists and human approval around Toll's verdict; unset = 0.3.x behaviour */
+    spend?: SpendPolicy;
+    /** where caps and paid x402 ids are counted; default an in-process MemorySpendStore per SpendPolicy object */
+    store?: SpendStore;
+    /** with `spend`: a request whose spend cannot be read is blocked (onUnknownSpend default "block") */
+    failClosed?: boolean;
+}
+/** fields the wrappers pass to enforce; not part of the public options */
+export interface InternalOptions extends GuardOptions {
+    /** spend-mode reports of one wrapped call, committed after the send or released when it throws */
+    _collect?: GuardReport[];
+    /** a preview's confirm id: Toll's answer from that preview is reused once when the request is identical */
+    _confirm?: string;
+    /** preview: check everything, reserve nothing, never ask for approval */
+    _preview?: boolean;
+    /** the x402 endpoint URL (per-endpoint caps) */
+    _endpoint?: string;
 }
 /** the effective policy: explicit options win, then the strict preset, then the defaults */
 export declare function resolvePolicy(o?: GuardOptions): {
@@ -91,3 +190,36 @@ export declare function gateAuthorization(kind: GuardKind, where: string, input:
  * from the batch's sender, in order; the first one blocked stops the batch. Reports carry kind "calls".
  */
 export declare function enforceCalls(build: () => CheckInput[] | Promise<CheckInput[]>, o?: GuardOptions): Promise<GuardReport[]>;
+/** the store for these options: the one given, else one in-process store per SpendPolicy object */
+export declare function storeOf(o: GuardOptions): SpendStore;
+/** the reservations of these reports, committed: the request was sent */
+export declare function commitSpend(reports: GuardReport | GuardReport[], o: GuardOptions): Promise<void>;
+/** the reservations of these reports, released: the request was refused or the send threw */
+export declare function releaseSpend(reports: GuardReport | GuardReport[], o: GuardOptions): Promise<void>;
+/** a request the spend policy refuses outside enforce (a repeated x402 payment id): reported, then TollPolicyError */
+export declare function policyRefuse(kind: GuardKind, input: CheckInput | null, code: PolicyCode, message: string, o: GuardOptions): Promise<never>;
+export interface GuardDecision {
+    decision: "allowed" | "blocked";
+    basis: GuardReport["basis"];
+    /** Toll's answer (null when Toll was not asked or could not answer) */
+    assessment: RiskAssessment | null;
+    /** the spend rule that would block it */
+    policy?: PolicyCode;
+    /** what it would spend (with `spend` set) */
+    spend?: Spend;
+    /** over an approveAbove threshold: the send will ask `approve` */
+    needsApproval?: boolean;
+    /** why it would be blocked */
+    reason?: string;
+    paidUrl: string | null;
+}
+/**
+ * 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 declare function preview(input: CheckInput, opts?: GuardOptions & {
+    kind?: GuardKind;
+}): Promise<GuardDecision & {
+    confirmId: string;
+}>;