@tollxyz/guard 0.2.0 → 0.4.0

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>;
+}

package/dist/store.js

@@ -0,0 +1,78 @@
+/**
+ * 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.
+ */
+/** the start of the UTC day holding `t` (ms) */
+export const dayStart = (t) => t - (((t % 86_400_000) + 86_400_000) % 86_400_000);
+/** an in-process SpendStore: resets on restart, not shared between processes */
+export class MemorySpendStore {
+    buckets = new Map();
+    where = new Map();
+    paid = new Map();
+    now;
+    seq = 0;
+    constructor(o = {}) {
+        this.now = o.now ?? Date.now;
+    }
+    prune(windowStart) {
+        // windows older than the previous day are dropped
+        for (const b of this.buckets.keys()) {
+            const ws = Number(b.slice(b.lastIndexOf("@") + 1));
+            if (ws < windowStart - 86_400_000)
+                this.buckets.delete(b);
+        }
+    }
+    async reserve(k, amt, limit, windowStart) {
+        // no await before the check and the write: atomic within this process
+        const bk = `${k}@${windowStart}`;
+        let b = this.buckets.get(bk);
+        if (!b) {
+            this.prune(windowStart);
+            b = { committed: 0n, pending: new Map() };
+            this.buckets.set(bk, b);
+        }
+        let used = b.committed;
+        for (const v of b.pending.values())
+            used += v;
+        if (amt < 0n || used + amt > limit)
+            return { ok: false, id: "", used };
+        const id = `r${++this.seq}`;
+        b.pending.set(id, amt);
+        this.where.set(id, bk);
+        return { ok: true, id, used: used + amt };
+    }
+    async commit(id) {
+        const bk = this.where.get(id);
+        const b = bk ? this.buckets.get(bk) : undefined;
+        this.where.delete(id);
+        const v = b?.pending.get(id);
+        if (!b || v === undefined)
+            return;
+        b.pending.delete(id);
+        b.committed += v;
+    }
+    async release(id) {
+        const bk = this.where.get(id);
+        this.where.delete(id);
+        if (bk)
+            this.buckets.get(bk)?.pending.delete(id);
+    }
+    async paymentSeen(id) {
+        const until = this.paid.get(id);
+        if (until === undefined)
+            return false;
+        if (until <= this.now()) {
+            this.paid.delete(id);
+            return false;
+        }
+        return true;
+    }
+    async markPaid(id, ttlS) {
+        const t = this.now();
+        for (const [k, until] of this.paid)
+            if (until <= t)
+                this.paid.delete(k);
+        this.paid.set(id, t + ttlS * 1000);
+    }
+}

package/dist/wallets.d.ts

@@ -6,8 +6,8 @@ import { type Hex } from "./check.js";
 import { type GuardOptions } from "./policy.js";
 export interface ViemGuardOptions extends GuardOptions {
     /**
-     * Encodes writeContract calldata. Default: viem's own encodeFunctionData, loaded on first use (viem is installed
-     * wherever a viem WalletClient is).
+     * Encodes writeContract (and contract-call batch) calldata. Default: viem's own encodeFunctionData, loaded on first
+     * use (viem is installed wherever a viem client is).
      */
     encodeFunctionData?: (args: {
         abi: unknown;
@@ -16,27 +16,36 @@ export interface ViemGuardOptions extends GuardOptions {
     }) => Hex | string;
 }
 /**
- * Wraps a viem WalletClient: sendTransaction, writeContract, signTransaction and signTypedData ask Toll first. An
- * EIP-7702 authorization (an authorizationList on any of them, or signAuthorization) goes to onAuthorization
- * (default: blocked). Wrap last: `client.extend(...)` on the wrapped client returns an unguarded client, and the
- * account's own sign methods (client.account.sign*) are not wrapped.
+ * Wraps a viem WalletClient. Asks Toll first: sendTransaction, writeContract, signTransaction, signTypedData,
+ * signMessage, sendCalls (EIP-5792, each call), signAuthorization, and request() for eth_sendTransaction,
+ * eth_signTransaction, personal_sign, eth_sign, eth_signTypedData_v4 and wallet_sendCalls. An EIP-7702 authorization
+ * goes to onAuthorization (default "check"). Wrap last: `client.extend(...)` on the wrapped client returns an unguarded
+ * client, and the account's own sign methods (client.account.sign*) are not wrapped.
  */
 export declare function guardViem<T extends object>(client: T, opts?: ViemGuardOptions): T;
+/**
+ * Wraps a viem bundler client (account abstraction): sendUserOperation and prepareUserOperation ask Toll first.
+ * `calls` are checked one by one as transactions from the smart account's address; a ready `callData` is sent as a
+ * user operation with the account's EntryPoint. An EIP-7702 `authorization` goes to onAuthorization.
+ */
+export declare function guardSmartAccount<T extends object>(client: T, sopts?: ViemGuardOptions): T;
 /** the EIP-712 primary type: the one type no other type refers to (as ethers' TypedDataEncoder.getPrimaryType) */
 export declare function primaryTypeOf(types: Record<string, Array<{
     name: string;
     type: string;
 }>>): string;
 /**
- * Wraps an ethers v6 Signer: sendTransaction, signTransaction and signTypedData ask Toll first. An EIP-7702
- * authorization (a transaction's authorizationList, or authorize()) goes to onAuthorization (default: blocked).
- * `signer.connect(provider)` returns an unguarded signer: wrap the connected one.
+ * Wraps an ethers v6 Signer: sendTransaction, signTransaction, signTypedData, signMessage and authorize() ask Toll
+ * first. An EIP-7702 authorization (a transaction's authorizationList, or authorize()) goes to onAuthorization
+ * (default "check"). `signer.connect(provider)` returns an unguarded signer: wrap the connected one.
  */
 export declare function guardEthers<T extends object>(signer: T, opts?: GuardOptions): T;
 /** true for a viem WalletClient (has `extend` and `request`), false for an ethers Signer */
 export declare const isViemClient: (x: unknown) => boolean;
+/** true for a viem bundler client (account abstraction): it has sendUserOperation */
+export declare const isBundlerClient: (x: unknown) => boolean;
 /**
- * Puts Toll's pre-sign check in front of a wallet. A viem WalletClient or an ethers v6 Signer; the wrapped wallet has
- * the same type and methods.
+ * Puts Toll's pre-sign check in front of a wallet: a viem bundler client (smart account), a viem WalletClient or an
+ * ethers v6 Signer; the wrapped wallet has the same type and methods.
  */
 export declare function guard<T extends object>(wallet: T, opts?: ViemGuardOptions): T;