@tollxyz/guard 0.0.0-stage → 0.1.1

package/dist/erc8470.js

@@ -0,0 +1,193 @@
+export const OBS_REGISTRY = "0x730e3c356299c9203cb042f6c0a9274aeabf9af3";
+/** Toll's detector wallet (the engine that records observations) */
+export const OBS_DETECTOR = "0x02593AbFf31f4E8eC1D5c2F297a347C51ef06E5c";
+export const OBS_CHAIN_ID = 4663;
+export const RH_RPC = "https://rpc.mainnet.chain.robinhood.com";
+/** type(uint256).max */
+export const NOT_READ = (1n << 256n) - 1n;
+/** selectors, from the compiled LaunchObservations.json methodIdentifiers */
+const SEL = {
+    getObservation: "f5fec8b1",
+    latestByToken: "8c9b1620",
+    latestFinding: "cf5fd50d",
+};
+/** every kind the ERC defines plus Toll's own, by name: keccak256 of the namespaced string, and its unit */
+export const FINDING_KINDS = {
+    "first-block-share": { id: "0xf1503018582646f41619eefcdeaae1c1b9ad5e71e1a74f59a7c177cd5d8a1b0c", unit: "bps" },
+    "early-buyer-share": { id: "0xde1880e1c55491741e8806f8091354331ccfae6d260de5624fa7b5131f8ab19a", unit: "bps" },
+    "creator-prior-launches": { id: "0xb559eb50996235dcc907f3c528e2b0bd21669b438572d50973405b9394544c38", unit: "count" },
+    "funding-linked-share": { id: "0xd0f99f8b1f2648a01d4d94c4ac89e81b3f3036b775a02e9d840391fece5b51d0", unit: "bps" },
+    "product-label": { id: "0x2af827bba451d4ec3e3a25936a27478e62bf16a8046dfec8f9369f5b9f139345", unit: "label" },
+    "text-flags": { id: "0x69c611869dc6d3ce968978b3e0a2a3b7d975d9ab462081222ae451a444230bc5", unit: "mask" },
+    "xyz.t0ll.dev-sold-share": { id: "0x0b9baa9f583b056e93eb0a650daaafff3b7aa27fbe9f4243b91f5f4337fbc10a", unit: "bps" },
+    "signal.deployerSupplyShare": { id: "0x36da7198a2ed7b9d71cd98db4049dce4bc9fe964562e0d5f3085f915405fa318", unit: "bps" },
+    "signal.insiderAllocationShare": { id: "0x03c04aaf168c10242870103dfdc5e913904f5c02b2be34091db637984b72eb72", unit: "bps" },
+    "signal.sniperConcentration": { id: "0x3f22e0f440671a38c44563d087b0027456ed5018d1cb21c5e36837aaa21eaf2c", unit: "bps" },
+    "signal.lpLockedShare": { id: "0x3c8cfdf5cbd8671de60b2c3e64bd5d69438136cd74cdc340287ba5fd7a836755", unit: "bps" },
+    "signal.lpLockRemaining": { id: "0x17c1b81f88b7beaaf5cd4b6fed97887360c13fe178a9f826064c0522c3d69ab2", unit: "seconds" },
+    "signal.liquidityRemoved": { id: "0xd0d754e325d16e378c48160ce2a439bc8587980fb9b2f69aa6a4037973ad2f71", unit: "bps" },
+    "signal.deployerSellRatio": { id: "0x5dbad0bcd30c444d847c6ae8571340fddcb77cad4ef280497f4196032ba201a4", unit: "bps" },
+    "signal.proceedsWithdrawnShare": { id: "0xcf325865161b29692c7e7d30708d3a6b2a7f788ff1859f76720127464e2a9dad", unit: "bps" },
+    "signal.privilegedPowers": { id: "0xb6b77a84953f300885ac1de83ad6cb7a3683d87ffbad4dd9963eb7bfc207a6f5", unit: "mask" },
+    "signal.priorUpheldClaims": { id: "0x1b8f9350bd49cd3504abfddf158e8726187ddd9b8060a017918c300020e9254d", unit: "count" },
+    "signal.supplyInflation": { id: "0xf695c94870a4cb86b0539718a4b7e89ed00257f15b2b7b33829785224bb25cd8", unit: "bps" },
+    "signal.washTradeRatio": { id: "0x79cbc6923e1ea8a086a7713aada26f70a0665a99e796b1fa083c2e3046d9abc0", unit: "bps" },
+};
+const BY_ID = new Map(Object.entries(FINDING_KINDS).map(([name, k]) => [k.id, { name, unit: k.unit }]));
+const LEANS = ["none", "clear", "careful", "against"];
+const KEY_KINDS = ["none", "erc8376", "token", "erc8462-venue"];
+/* ------------------------------------------------------------------ ABI, by hand */
+const ADDR = /^0x[0-9a-fA-F]{40}$/;
+const B32 = /^0x[0-9a-fA-F]{64}$/;
+const word = (n) => {
+    if (n < 0n || n > NOT_READ)
+        throw new RangeError("uint256 out of range");
+    return n.toString(16).padStart(64, "0");
+};
+const addrWord = (a) => {
+    if (!ADDR.test(a))
+        throw new TypeError(`not an address: ${a}`);
+    return a.slice(2).toLowerCase().padStart(64, "0");
+};
+export const encodeLatestByToken = (chainId, token, detector) => `0x${SEL.latestByToken}${word(chainId)}${addrWord(token)}${addrWord(detector)}`;
+export const encodeGetObservation = (id) => `0x${SEL.getObservation}${word(id)}`;
+export const encodeLatestFinding = (chainId, token, detector, kind, param) => {
+    if (!B32.test(kind))
+        throw new TypeError(`kind must be bytes32 hex: ${kind}`);
+    if (param < 0n || param >= 1n << 64n)
+        throw new RangeError("param must fit uint64");
+    return `0x${SEL.latestFinding}${word(chainId)}${addrWord(token)}${addrWord(detector)}${kind.slice(2).toLowerCase()}${word(param)}`;
+};
+/** a reader over 32-byte words of ABI-encoded return data */
+class Reader {
+    hex;
+    constructor(data) {
+        if (!/^0x([0-9a-fA-F]{2})*$/.test(data))
+            throw new TypeError("return data is not hex");
+        this.hex = data.slice(2);
+    }
+    /** the 32-byte word at a byte offset */
+    w(byteOff) {
+        const s = this.hex.slice(byteOff * 2, byteOff * 2 + 64);
+        if (s.length !== 64)
+            throw new RangeError(`return data too short at byte ${byteOff}`);
+        return s;
+    }
+    uint(byteOff) {
+        return BigInt("0x" + this.w(byteOff));
+    }
+    num(byteOff, max = 2 ** 32) {
+        const n = this.uint(byteOff);
+        if (n > BigInt(max))
+            throw new RangeError(`value too large at byte ${byteOff}`);
+        return Number(n);
+    }
+    addr(byteOff) {
+        return "0x" + this.w(byteOff).slice(24);
+    }
+    b32(byteOff) {
+        return "0x" + this.w(byteOff);
+    }
+    bool(byteOff) {
+        return this.uint(byteOff) !== 0n;
+    }
+    string(byteOff) {
+        const len = this.num(byteOff, 1 << 20);
+        const s = this.hex.slice((byteOff + 32) * 2, (byteOff + 32 + len) * 2);
+        if (s.length !== len * 2)
+            throw new RangeError("string runs past the return data");
+        const bytes = new Uint8Array(len);
+        for (let i = 0; i < len; i++)
+            bytes[i] = parseInt(s.slice(i * 2, i * 2 + 2), 16);
+        return new TextDecoder().decode(bytes);
+    }
+}
+const leanOf = (n) => LEANS[n] ?? "none";
+function finding(kind, value, param, lean) {
+    const k = BY_ID.get(kind.toLowerCase());
+    const notRead = value === NOT_READ;
+    return { kind, name: k?.name ?? null, unit: k?.unit ?? null, value: notRead ? null : value, notRead, param, lean: leanOf(lean) };
+}
+/** decodes getObservation(uint256)'s return: (Observation, Finding[]) */
+export function decodeGetObservation(data, id) {
+    const r = new Reader(data);
+    const o = r.num(0, 1 << 24);
+    const f = r.num(32, 1 << 24);
+    const at = (i) => o + i * 32;
+    const keyKind = r.num(at(3), 255);
+    const obs = {
+        id,
+        launchKey: r.b32(at(0)),
+        chainId: r.uint(at(1)),
+        token: r.addr(at(2)),
+        keyKind: KEY_KINDS[keyKind] ?? "none",
+        observedBlock: r.uint(at(4)),
+        hashChecked: r.bool(at(5)),
+        detector: r.addr(at(6)),
+        recordedAt: r.uint(at(7)),
+        identityRegistry: r.addr(at(8)),
+        tally: { against: r.num(at(9), 65535), careful: r.num(at(10), 65535), clear: r.num(at(11), 65535) },
+        agentId: r.uint(at(12)),
+        supersedes: r.uint(at(13)),
+        reportHash: r.b32(at(14)),
+        evidenceRoot: r.b32(at(15)),
+        declarationId: r.b32(at(16)),
+        reportURI: r.string(o + r.num(at(17), 1 << 24)),
+        findings: [],
+    };
+    const n = r.num(f, 64);
+    for (let i = 0; i < n; i++) {
+        const b = f + 32 + i * 128;
+        obs.findings.push(finding(r.b32(b), r.uint(b + 32), r.uint(b + 64), r.num(b + 96, 255)));
+    }
+    return obs;
+}
+/* ------------------------------------------------------------------ RPC */
+async function ethCall(to, data, o) {
+    const f = o.fetch ?? globalThis.fetch;
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), o.timeoutMs ?? 10_000);
+    try {
+        const res = await f(o.rpcUrl ?? RH_RPC, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_call", params: [{ to, data }, "latest"] }),
+            signal: ctl.signal,
+        });
+        if (!res.ok)
+            throw new Error(`RPC answered HTTP ${res.status}`);
+        const j = (await res.json());
+        if (j.error)
+            throw new Error(`eth_call failed: ${j.error.message ?? "error"}`);
+        if (typeof j.result !== "string")
+            throw new Error("eth_call returned no result");
+        return j.result;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+const kindId = (kind) => FINDING_KINDS[kind]?.id ?? kind;
+/**
+ * Toll's latest ERC-8470 observation of a token: latestByToken(chainId, token, detector), then getObservation(id).
+ * null when the detector has no observation of the token (id 0). Throws on an RPC failure (a failed read is not
+ * "no observation").
+ */
+export async function read8470(token, opts = {}) {
+    const registry = opts.registry ?? OBS_REGISTRY;
+    const id = BigInt(await ethCall(registry, encodeLatestByToken(BigInt(opts.chainId ?? OBS_CHAIN_ID), token, opts.detector ?? OBS_DETECTOR), opts));
+    if (id === 0n)
+        return null;
+    return decodeGetObservation(await ethCall(registry, encodeGetObservation(id), opts), id);
+}
+/** decodes latestFinding's fixed-size return (uint256, uint64, uint64, uint256, uint8) */
+export function decodeLatestFinding(data) {
+    const r = new Reader(data);
+    const value = r.uint(96);
+    return { observationId: r.uint(0), observedBlock: r.uint(32), recordedAt: r.uint(64), value: value === NOT_READ ? null : value, notRead: value === NOT_READ, lean: leanOf(r.num(128, 255)) };
+}
+/** One finding of Toll's latest observation of a token: latestFinding(chainId, token, detector, kind, param). */
+export async function latestFinding8470(token, kind, param = 0, opts = {}) {
+    const data = encodeLatestFinding(BigInt(opts.chainId ?? OBS_CHAIN_ID), token, opts.detector ?? OBS_DETECTOR, kindId(kind), BigInt(param));
+    return decodeLatestFinding(await ethCall(opts.registry ?? OBS_REGISTRY, data, opts));
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { checkTx, 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, CheckInput, CheckOptions, TypedDataLike, FetchLike, Hex, Numberish, UnavailableReason, } from "./check.js";
+export { enforce, unsupportedWhy } from "./policy.js";
+export type { GuardOptions, GuardReport, GuardKind, WarnPolicy, BlockPolicy } from "./policy.js";
+export { guard, guardViem, guardEthers, isViemClient, primaryTypeOf } from "./wallets.js";
+export type { ViemGuardOptions } from "./wallets.js";
+export { guardX402Fetch, readPaymentRequired } 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";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { checkTx, 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, unsupportedWhy } from "./policy.js";
+export { guard, guardViem, guardEthers, isViemClient, primaryTypeOf } from "./wallets.js";
+export { guardX402Fetch, readPaymentRequired } 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";

package/dist/policy.d.ts

@@ -0,0 +1,45 @@
+import { TollUnavailableError, type CheckInput, type CheckOptions, type RiskAssessment } from "./check.js";
+export type WarnPolicy = "allow" | "block" | ((assessment: RiskAssessment) => boolean | Promise<boolean>);
+export type BlockPolicy = "throw" | ((assessment: RiskAssessment) => boolean | Promise<boolean>);
+export type GuardKind = "transaction" | "typedData" | "x402";
+export interface GuardReport {
+    kind: GuardKind;
+    /** what was sent to Toll (null when nothing was sent) */
+    input: CheckInput | null;
+    /** Toll's answer; null when Toll was unavailable or the request was not checked */
+    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";
+    /** the paid route (no daily limit) when this caller's free checks are used */
+    paidUrl: string | null;
+    error?: TollUnavailableError;
+}
+export interface GuardOptions extends CheckOptions {
+    /** WARN: "allow" (default, reported and logged), "block", or a function; true lets it through */
+    onWarn?: WarnPolicy;
+    /** BLOCK: "throw" (default, TollBlockedError), or a function (e.g. ask a human); true lets it through */
+    onBlock?: BlockPolicy;
+    /**
+     * Toll unreachable, timed out, 5xx, 429, or a request it could not read: "allow" (default, fail-open, logged) or
+     * "block" (fail-closed, throws TollUnavailableError).
+     */
+    onUnavailable?: "allow" | "block";
+    /** a request Toll does not read (another chain, a contract deploy): "allow" (default) or "block" */
+    onUnsupported?: "allow" | "block";
+    /** every decision, with Toll's answer; errors thrown here are caught and logged */
+    onReport?: (report: GuardReport) => void | Promise<void>;
+    /** where WARN / unavailable lines go (default console.warn); false = silent */
+    logger?: ((message: string) => void) | false;
+    /** the seller's ERC-8004 agent id for x402 payments (or a function of the URL) */
+    agentId?: number | string | ((url: string) => number | string | undefined | null);
+}
+/** why Toll would not read this request, or null when it does */
+export declare function unsupportedWhy(input: CheckInput): string | null;
+/**
+ * Runs Toll's check on one request and applies the policy. Resolves with the report when the request may go ahead;
+ * throws TollBlockedError (BLOCK, or WARN under a blocking policy) or TollUnavailableError (fail-closed).
+ * `build` may throw (e.g. calldata that could not be encoded): that counts as unavailable.
+ */
+export declare function enforce(kind: GuardKind, build: () => CheckInput | Promise<CheckInput>, o?: GuardOptions): Promise<GuardReport>;

package/dist/policy.js

@@ -0,0 +1,110 @@
+import { TX_CHAIN_ID, TollBlockedError, TollUnavailableError, checkTx, chainIdOf, paidUrlOf, } from "./check.js";
+const say = (o, msg) => {
+    if (o.logger === false)
+        return;
+    try {
+        (o.logger ?? console.warn)(`[toll-guard] ${msg}`);
+    }
+    catch {
+        /* a logger must never stop a signature */
+    }
+};
+async function report(o, r) {
+    if (!o.onReport)
+        return;
+    try {
+        await o.onReport(r);
+    }
+    catch (e) {
+        say(o, `onReport threw: ${e?.message ?? e}`);
+    }
+}
+/** why Toll would not read this request, or null when it does */
+export function unsupportedWhy(input) {
+    const tx = input.to !== undefined || input.data !== undefined;
+    if (tx) {
+        if (input.to === undefined || input.to === null)
+            return "a contract deployment (no `to`) is not read";
+        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 (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)
+        return "nothing to check";
+    return null;
+}
+/**
+ * Runs Toll's check on one request and applies the policy. Resolves with the report when the request may go ahead;
+ * throws TollBlockedError (BLOCK, or WARN under a blocking policy) or TollUnavailableError (fail-closed).
+ * `build` may throw (e.g. calldata that could not be encoded): that counts as unavailable.
+ */
+export async function enforce(kind, build, o = {}) {
+    let input;
+    try {
+        input = await build();
+    }
+    catch (e) {
+        const err = e instanceof TollUnavailableError ? e : new TollUnavailableError(`The request could not be read for Toll's check: ${e?.message ?? e}`, { reason: "encode", cause: e });
+        return unavailable(kind, null, err, o);
+    }
+    const why = unsupportedWhy(input);
+    if (why) {
+        const blocked = o.onUnsupported === "block";
+        const r = { kind, input, assessment: null, decision: blocked ? "blocked" : "allowed", basis: "unsupported", paidUrl: null };
+        await report(o, r);
+        if (blocked)
+            throw new TollUnavailableError(`Not checked by Toll: ${why}. onUnsupported is "block".`, { reason: "unsupported" });
+        return r;
+    }
+    let a;
+    try {
+        a = 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 });
+        return unavailable(kind, input, err, o);
+    }
+    const paidUrl = paidUrlOf(a);
+    const done = async (decision, basis) => {
+        const r = { kind, input, assessment: a, decision, basis, paidUrl };
+        await report(o, r);
+        return r;
+    };
+    if (a.action === "ALLOW")
+        return done("allowed", "ALLOW");
+    if (a.action === "BLOCK") {
+        const p = o.onBlock ?? "throw";
+        if (typeof p === "function" && (await p(a)) === true) {
+            say(o, `BLOCK let through by onBlock: ${a.warnings.map((w) => w.code).join(", ")}`);
+            return done("allowed", "BLOCK");
+        }
+        await done("blocked", "BLOCK");
+        throw new TollBlockedError(a, "BLOCK");
+    }
+    // WARN, and anything that is not one of the three actions: never treated as an ALLOW
+    const p = o.onWarn ?? "allow";
+    const ok = p === "allow" ? true : p === "block" ? false : (await p(a)) === true;
+    if (ok) {
+        say(o, `WARN (${kind}), going ahead: ${a.warnings.map((w) => `${w.code}: ${w.message}`).join(" | ")}${paidUrl ? ` Paid, no daily limit: ${paidUrl}` : ""}`);
+        return done("allowed", "WARN");
+    }
+    await done("blocked", "WARN");
+    throw new TollBlockedError(a, "WARN");
+}
+async function unavailable(kind, input, err, o) {
+    const blocked = o.onUnavailable === "block";
+    const r = { kind, input, assessment: null, decision: blocked ? "blocked" : "allowed", basis: "unavailable", paidUrl: err.paidUrl, error: err };
+    await report(o, r);
+    if (blocked)
+        throw err;
+    say(o, `Toll unavailable, NOT checked, going ahead (onUnavailable "allow"): ${err.message}`);
+    return r;
+}

package/dist/wallets.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The wallet wrappers. Duck-typed: viem and ethers are optional peer dependencies, never imported at load time.
+ * The wrapper is a Proxy: every other method and field of the client passes through unchanged.
+ */
+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).
+     */
+    encodeFunctionData?: (args: {
+        abi: unknown;
+        functionName: string;
+        args?: readonly unknown[];
+    }) => Hex | string;
+}
+/**
+ * Wraps a viem WalletClient: sendTransaction, writeContract, signTransaction and signTypedData ask Toll first.
+ * Wrap last: `client.extend(...)` on the wrapped client returns an unguarded client.
+ */
+export declare function guardViem<T extends object>(client: T, opts?: 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.
+ * `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;
+/**
+ * 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.
+ */
+export declare function guard<T extends object>(wallet: T, opts?: ViemGuardOptions): T;

package/dist/wallets.js

@@ -0,0 +1,169 @@
+/**
+ * The wallet wrappers. Duck-typed: viem and ethers are optional peer dependencies, never imported at load time.
+ * The wrapper is a Proxy: every other method and field of the client passes through unchanged.
+ */
+import { isAddress } from "./check.js";
+import { enforce } from "./policy.js";
+/** wraps an object's methods; everything else passes through, bound to the original */
+function proxy(target, wrapped) {
+    return new Proxy(target, {
+        get(t, p) {
+            if (typeof p === "string" && Object.prototype.hasOwnProperty.call(wrapped, p))
+                return wrapped[p];
+            const v = Reflect.get(t, p, t);
+            return typeof v === "function" ? v.bind(t) : v;
+        },
+    });
+}
+const addrOf = (account) => {
+    if (isAddress(account))
+        return account;
+    const a = account?.address;
+    return isAddress(a) ? a : undefined;
+};
+/* ------------------------------------------------------------------ viem */
+let viemEncode = null;
+async function loadViemEncode() {
+    if (viemEncode)
+        return viemEncode;
+    const name = "viem";
+    const m = (await import(name));
+    if (typeof m.encodeFunctionData !== "function")
+        throw new Error("viem's encodeFunctionData was not found");
+    viemEncode = m.encodeFunctionData;
+    return viemEncode;
+}
+/**
+ * Wraps a viem WalletClient: sendTransaction, writeContract, signTransaction and signTypedData ask Toll first.
+ * Wrap last: `client.extend(...)` on the wrapped client returns an unguarded client.
+ */
+export function guardViem(client, opts = {}) {
+    const c = client;
+    const chainOf = (args) => (args?.chain === null ? undefined : (args?.chain?.id ?? c.chain?.id));
+    const fromOf = (args) => addrOf(args?.account ?? c.account);
+    const txInput = (args, data) => ({
+        chainId: chainOf(args),
+        from: fromOf(args),
+        to: args?.to ?? undefined,
+        data: data ?? "0x",
+        value: args?.value ?? 0n,
+    });
+    const wrapped = {};
+    if (typeof c.sendTransaction === "function") {
+        wrapped.sendTransaction = async (args, ...rest) => {
+            // a deployment (no `to`) goes to the unsupported policy
+            await enforce("transaction", () => txInput(args, args?.data), opts);
+            return c.sendTransaction(args, ...rest);
+        };
+    }
+    if (typeof c.signTransaction === "function") {
+        wrapped.signTransaction = async (args, ...rest) => {
+            await enforce("transaction", () => txInput(args, args?.data), opts);
+            return c.signTransaction(args, ...rest);
+        };
+    }
+    if (typeof c.writeContract === "function") {
+        wrapped.writeContract = async (args, ...rest) => {
+            await enforce("transaction", async () => {
+                const enc = opts.encodeFunctionData ?? (await loadViemEncode());
+                let data = String(enc({ abi: args.abi, functionName: args.functionName, args: args.args }));
+                if (typeof args.dataSuffix === "string")
+                    data += args.dataSuffix.replace(/^0x/, "");
+                return txInput({ ...args, to: args.address }, data);
+            }, opts);
+            return c.writeContract(args, ...rest);
+        };
+    }
+    if (typeof c.signTypedData === "function") {
+        wrapped.signTypedData = async (args, ...rest) => {
+            const td = { domain: args?.domain ?? {}, types: args?.types ?? {}, primaryType: args?.primaryType, message: args?.message ?? {} };
+            await enforce("typedData", () => ({ typedData: td }), opts);
+            return c.signTypedData(args, ...rest);
+        };
+    }
+    return proxy(client, wrapped);
+}
+/* ------------------------------------------------------------------ ethers v6 */
+/** the EIP-712 primary type: the one type no other type refers to (as ethers' TypedDataEncoder.getPrimaryType) */
+export function primaryTypeOf(types) {
+    const names = Object.keys(types).filter((n) => n !== "EIP712Domain");
+    const used = new Set();
+    for (const n of names)
+        for (const f of types[n] ?? [])
+            used.add(String(f.type).replace(/(\[\d*\])+$/, ""));
+    const roots = names.filter((n) => !used.has(n));
+    if (roots.length !== 1)
+        throw new Error(roots.length ? `ambiguous primary type: ${roots.join(", ")}` : "no primary type");
+    return roots[0];
+}
+async function ethersTx(signer, tx) {
+    let to = tx?.to;
+    if (to && typeof to === "object" && typeof to.getAddress === "function")
+        to = await to.getAddress();
+    if (typeof to === "string" && !isAddress(to)) {
+        // an ENS name: resolved the way the signer would
+        const r = typeof signer.resolveName === "function" ? await signer.resolveName(to) : null;
+        if (!isAddress(r))
+            throw new Error(`could not resolve ${to}`);
+        to = r;
+    }
+    let chainId = tx?.chainId;
+    if (chainId === undefined || chainId === null) {
+        const net = typeof signer.provider?.getNetwork === "function" ? await signer.provider.getNetwork() : null;
+        chainId = net?.chainId ?? undefined;
+    }
+    let from = tx?.from;
+    if (from && typeof from === "object" && typeof from.getAddress === "function")
+        from = await from.getAddress();
+    if (!isAddress(from) && typeof signer.getAddress === "function")
+        from = await signer.getAddress();
+    return {
+        chainId: (chainId ?? undefined),
+        from: isAddress(from) ? from : undefined,
+        to: (to ?? undefined),
+        data: typeof tx?.data === "string" ? tx.data : "0x",
+        value: tx?.value ?? 0n,
+    };
+}
+/**
+ * Wraps an ethers v6 Signer: sendTransaction, signTransaction and signTypedData ask Toll first.
+ * `signer.connect(provider)` returns an unguarded signer: wrap the connected one.
+ */
+export function guardEthers(signer, opts = {}) {
+    const s = signer;
+    const wrapped = {};
+    if (typeof s.sendTransaction === "function") {
+        wrapped.sendTransaction = async (tx, ...rest) => {
+            await enforce("transaction", () => ethersTx(s, tx), opts);
+            return s.sendTransaction(tx, ...rest);
+        };
+    }
+    if (typeof s.signTransaction === "function") {
+        wrapped.signTransaction = async (tx, ...rest) => {
+            await enforce("transaction", () => ethersTx(s, tx), opts);
+            return s.signTransaction(tx, ...rest);
+        };
+    }
+    if (typeof s.signTypedData === "function") {
+        wrapped.signTypedData = async (domain, types, value, ...rest) => {
+            await enforce("typedData", () => ({ typedData: { domain: domain ?? {}, types: types ?? {}, primaryType: primaryTypeOf(types ?? {}), message: value ?? {} } }), opts);
+            return s.signTypedData(domain, types, value, ...rest);
+        };
+    }
+    return proxy(signer, wrapped);
+}
+/* ------------------------------------------------------------------ either */
+/** true for a viem WalletClient (has `extend` and `request`), false for an ethers Signer */
+export const isViemClient = (x) => !!x && typeof x.extend === "function" && typeof x.request === "function";
+/**
+ * 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.
+ */
+export function guard(wallet, opts = {}) {
+    if (isViemClient(wallet))
+        return guardViem(wallet, opts);
+    if (typeof wallet.getAddress === "function" && (typeof wallet.sendTransaction === "function" || typeof wallet.signTypedData === "function")) {
+        return guardEthers(wallet, opts);
+    }
+    throw new TypeError("guard(): pass a viem WalletClient or an ethers v6 Signer (or use guardViem / guardEthers).");
+}

package/dist/x402.d.ts

@@ -0,0 +1,14 @@
+import { type GuardOptions, type GuardReport } from "./policy.js";
+type AnyFetch = (input: any, init?: any) => Promise<Response>;
+/** the 402's PaymentRequired: v2 from the PAYMENT-REQUIRED header, else v1 from the JSON body; null when neither */
+export declare function readPaymentRequired(res: Response): Promise<Record<string, unknown> | null>;
+export interface X402GuardOptions extends GuardOptions {
+    /** called with each 402's report (also passed to onReport) */
+    on402?: (report: GuardReport, url: string) => void;
+}
+/**
+ * Wraps a fetch so every 402 is checked by Toll before an x402 client pays it. A 402 to a request that already
+ * carries a payment header passes through (it was checked before it was signed). Non-402 answers pass untouched.
+ */
+export declare function guardX402Fetch<F extends AnyFetch>(fetchLike: F, opts?: X402GuardOptions): F;
+export {};

package/dist/x402.js

@@ -0,0 +1,75 @@
+import { enforce } from "./policy.js";
+function decodeBase64Json(value) {
+    const bin = atob(value.trim());
+    return JSON.parse(new TextDecoder().decode(Uint8Array.from(bin, (c) => c.charCodeAt(0))));
+}
+/** the 402's PaymentRequired: v2 from the PAYMENT-REQUIRED header, else v1 from the JSON body; null when neither */
+export async function readPaymentRequired(res) {
+    const h = res.headers.get("payment-required");
+    if (h) {
+        try {
+            const pr = decodeBase64Json(h);
+            if (pr && Array.isArray(pr.accepts) && pr.accepts.length)
+                return pr;
+        }
+        catch {
+            /* fall back to the body */
+        }
+    }
+    try {
+        const body = JSON.parse(await res.clone().text());
+        if (body && Array.isArray(body.accepts) && body.accepts.length)
+            return body;
+    }
+    catch {
+        /* not JSON */
+    }
+    return null;
+}
+const urlOf = (input) => {
+    if (typeof input === "string")
+        return input;
+    if (input instanceof URL)
+        return input.href;
+    const u = input?.url;
+    return typeof u === "string" ? u : String(input);
+};
+const PAY_HEADERS = ["payment-signature", "x-payment"];
+const hasPayment = (input, init) => {
+    const read = (h) => {
+        if (!h)
+            return false;
+        try {
+            const hs = new Headers(h);
+            return PAY_HEADERS.some((n) => hs.has(n));
+        }
+        catch {
+            return false;
+        }
+    };
+    return read(init?.headers) || (typeof Request !== "undefined" && input instanceof Request && read(input.headers));
+};
+/**
+ * Wraps a fetch so every 402 is checked by Toll before an x402 client pays it. A 402 to a request that already
+ * carries a payment header passes through (it was checked before it was signed). Non-402 answers pass untouched.
+ */
+export function guardX402Fetch(fetchLike, opts = {}) {
+    const toll = { ...opts, fetch: opts.fetch ?? globalThis.fetch?.bind(globalThis) };
+    const wrapped = async (input, init) => {
+        const res = await fetchLike(input, init);
+        if (res.status !== 402 || hasPayment(input, init))
+            return res;
+        const url = urlOf(input);
+        const pr = await readPaymentRequired(res);
+        const r = await enforce("x402", () => {
+            if (!pr)
+                return {}; // nothing readable: the unsupported policy decides
+            const x402 = pr.resource || pr.url ? pr : { ...pr, url };
+            const id = typeof opts.agentId === "function" ? opts.agentId(url) : opts.agentId;
+            return { x402, ...(id !== undefined && id !== null ? { agentId: id } : {}) };
+        }, toll);
+        opts.on402?.(r, url);
+        return res;
+    };
+    return wrapped;
+}