@tollxyz/guard 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Toll
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,140 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @tollxyz/guard
+
+Toll's live pre-sign check in front of an AI agent's wallet. Before the agent signs a transaction, an EIP-712
+signature or an x402 payment on Robinhood Chain, the guard asks [Toll](https://t0ll.xyz/agents/x402#presign) and
+gets ALLOW / WARN / BLOCK with the reasons. Zero runtime dependencies, ESM only, Node >= 20.19, with types.
+
+```sh
+npm install @tollxyz/guard
+```
+
+```ts
+const wallet = guard(walletClient);   // viem WalletClient or ethers v6 Signer; same methods, checked first
+```
+
+```ts
+import { guard, TollBlockedError } from "@tollxyz/guard";
+
+const wallet = guard(walletClient, { onWarn: "allow", onUnavailable: "allow" });
+try {
+  await wallet.writeContract({ address: token, abi: erc20Abi, functionName: "approve", args: [spender, maxUint256] });
+} catch (e) {
+  if (e instanceof TollBlockedError) console.log(e.codes, e.assessment); // not signed
+  else throw e;
+}
+```
+
+Run it as an ES module (an `.mjs`/`.mts` file, or `"type": "module"` in package.json).
+
+Toll states facts, never says safe: ALLOW means none of the checks Toll runs found a reason to stop, nothing more.
+Information only, not financial advice.
+
+## What is checked
+
+Every check runs on Toll's server (`POST https://t0ll.xyz/api/tx/check`), so new checks reach you without a package
+update. The full list is at <https://t0ll.xyz/agents/x402#presign>: what the calldata or signature does (approvals,
+Permit / Permit2, transfers, swaps), unlimited approvals and approvals to a wallet instead of a contract, spenders and
+recipients Toll has flagged, a swap that pays someone else, the coin a swap buys (Toll's coin check: who is behind
+it), and for x402 the payee against the seller's registered ERC-8004 agentWallet (including `extra.erc8004`).
+
+The answer is an [ERC-8265](https://github.com/ethereum/ERCs/pull/1753) RiskAssessment:
+`{ action, warnings: [{ code, severity, message, "x-toll-evidence" }], scanners, "x-toll": { decoded, link, checked_at, note } }`.
+Critical = BLOCK, high or medium = WARN, low or none = ALLOW.
+
+Robinhood Chain (4663) only for now. A request on another chain, or a contract deployment, is not sent to Toll and
+goes through (`onUnsupported: "block"` to stop it instead).
+
+## API
+
+### `guard(wallet, opts?)`, `guardViem(client, opts?)`, `guardEthers(signer, opts?)`
+
+Returns the same wallet behind a Proxy. Checked first:
+
+- viem WalletClient: `sendTransaction`, `writeContract` (calldata encoded with your viem's `encodeFunctionData`),
+  `signTransaction`, `signTypedData`
+- ethers v6 Signer: `sendTransaction`, `signTransaction`, `signTypedData`
+
+Everything else passes through unchanged. Wrap last: `client.extend(...)` or `signer.connect(...)` on the wrapped
+wallet returns an unguarded one. viem and ethers are optional peer dependencies, never imported at load time.
+
+### `guardX402Fetch(fetch, opts?)`
+
+Wraps the fetch your x402 client uses. When a 402 arrives, its payment requirement goes to Toll before the client
+pays; on BLOCK the 402 never reaches the payer (TollBlockedError is thrown). The paid retry (a request with a
+`PAYMENT-SIGNATURE` or `X-PAYMENT` header) and every non-402 answer pass through.
+
+```ts
+import { wrapFetchWithPayment } from "x402-fetch";
+const pay = wrapFetchWithPayment(guardX402Fetch(fetch, { agentId: 123 }), account);
+```
+
+`agentId` (the seller's ERC-8004 id, or a function of the URL) is optional.
+
+### `checkTx(input, opts?)`
+
+The raw call. `input`: `{ chainId, from, to, data, value }` for a transaction, `{ typedData }` for an EIP-712
+request, `{ x402, agentId?, payment? }` for an x402 payment, or several together. Returns the RiskAssessment. When a
+coin is still being read, Toll answers WARN `coin-not-read` with `Retry-After`: `checkTx` asks once more if the wait
+is at most `maxRetryWaitMs` (default 10 s); a coin still not read stays WARN, never ALLOW. Throws
+`TollUnavailableError` when Toll cannot answer.
+
+### Options
+
+| Option | Default | |
+| --- | --- | --- |
+| `onWarn` | `"allow"` | `"allow"` (logged and reported), `"block"`, or `(assessment) => boolean` (true lets it through) |
+| `onBlock` | `"throw"` | `"throw"` (TollBlockedError), or `(assessment) => boolean`, e.g. ask a human; true lets it through |
+| `onUnavailable` | `"allow"` | Toll unreachable, timed out, 5xx, 429, or a request it could not read: `"allow"` (fail-open, logged) or `"block"` (fail-closed, TollUnavailableError) |
+| `onUnsupported` | `"allow"` | another chain, a deployment: `"allow"` or `"block"` |
+| `onReport` | none | `(report) => void`: every decision, with `assessment`, `decision`, `basis`, `paidUrl` |
+| `logger` | `console.warn` | where WARN and unavailable lines go; `false` = silent |
+| `timeoutMs` | `15000` | one request to Toll |
+| `retry`, `maxRetryWaitMs` | `true`, `10000` | the one retry after Retry-After |
+| `baseUrl`, `fetch` | `https://t0ll.xyz`, global fetch | |
+
+Errors: `TollBlockedError` (`.assessment`, `.codes`, message lists each code and message) and
+`TollUnavailableError` (`.reason`, `.status`, `.paidUrl`).
+
+## Fail-open or fail-closed
+
+The default is fail-open: if Toll cannot answer, the signature goes ahead, with a `[toll-guard] ... NOT checked`
+line and an `onReport` call with `basis: "unavailable"`. The agent must never get stuck because of Toll, and the
+free route is rate limited per IP (a busy agent will see 429s). If an unchecked signature is worse for you than a
+stalled agent, set `onUnavailable: "block"`.
+
+## Free limit and the paid route
+
+The check is free, rate limited per IP. The coin a swap buys is read through the same free coins as Toll's coin
+check (10 new coins a day per caller, coins already read stay free); past that the coin is not read and the answer
+is WARN `coin-over-quota` naming the paid route, `https://t0ll.xyz/api/x402/tx` (0.01 USDG over x402, no daily
+limit). The guard never pays: it puts that URL in the log line, in `report.paidUrl` and in `paidUrlOf(assessment)`.
+
+## Privacy
+
+What is sent to Toll: the transaction, EIP-712 request or x402 payment requirement you are about to sign (to, data,
+value, chain id, your address as `from`), nothing else. No key, no account, no signature.
+
+## ERC-8470 observations
+
+`read8470(token, opts?)` reads Toll's latest on-chain [ERC-8470](https://github.com/ethereum/ERCs/pull/2121) Launch
+Observation of a token on Robinhood Chain (registry `0x730e3c356299c9203cb042f6c0a9274aeabf9af3`, Toll's detector
+`0x02593AbFf31f4E8eC1D5c2F297a347C51ef06E5c`) with a plain `eth_call` to `https://rpc.mainnet.chain.robinhood.com`
+(`rpcUrl` to change). Returns the observation and its findings, or null when Toll has none for that token. A finding
+not read (`type(uint256).max` on chain) is `value: null, notRead: true`, never 0.
+`latestFinding8470(token, kind, param?)` reads one finding (kind by name, e.g. `"first-block-share"`, or bytes32).
+
+## Specs
+
+- Pre-sign check: <https://t0ll.xyz/agents/x402#presign>
+- ERC-8470 Launch Observations: <https://github.com/ethereum/ERCs/pull/2121>
+- x402 Payee Verification: <https://github.com/ethereum/ERCs/pull/2132>
+- ERC-8265 RiskAssessment: <https://github.com/ethereum/ERCs/pull/1753>
+
+## Develop
+
+```sh
+npm run build && npm test     # unit tests, no network
+node scripts/smoke.mjs        # one live call with a harmless request (a 0-value transfer)
+```
+
+MIT.

package/dist/check.d.ts

@@ -0,0 +1,134 @@
+/**
+ * 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.
+ */
+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;
+/** the paid route without the daily limit (0.01 USDG over x402); the guard never pays it */
+export declare const PAID_TX_PATH = "/api/x402/tx";
+export declare const PRESIGN_DOCS = "https://t0ll.xyz/agents/x402#presign";
+export declare const DEFAULT_TIMEOUT_MS = 15000;
+export declare const DEFAULT_MAX_RETRY_WAIT_MS = 10000;
+export type Action = "ALLOW" | "WARN" | "BLOCK";
+export type Severity = "low" | "medium" | "high" | "critical";
+export interface RiskWarning {
+    /** machine-readable, kebab-case, e.g. "unbounded-approval", "coin-not-read", "payee-mismatch" */
+    code: string;
+    severity: Severity;
+    message: string;
+    /** the facts behind this warning (Toll's vendor extension) */
+    "x-toll-evidence"?: Record<string, unknown>;
+}
+export interface ScannerVerdict {
+    provider: string;
+    verdict: Action;
+    url?: string;
+}
+export interface TollExtra {
+    scanner?: {
+        agent_id: number;
+        chain_id: number;
+        registry: string;
+        site: string;
+    };
+    /** when Toll made this answer, ISO 8601 UTC */
+    checked_at?: string;
+    /** what the transaction / signature does, as Toll read it */
+    decoded?: Record<string, unknown>[];
+    coins?: Record<string, unknown>[];
+    payees?: Record<string, unknown>[];
+    /** a coin still being read: ask again after this many seconds */
+    retry_after_s?: number;
+    /** the page to read more on t0ll.xyz */
+    link?: string;
+    note?: string;
+    [key: string]: unknown;
+}
+export interface RiskAssessment {
+    action: Action;
+    score?: number;
+    warnings: RiskWarning[];
+    scanners?: ScannerVerdict[];
+    "x-toll"?: TollExtra;
+}
+export type Hex = `0x${string}`;
+export type Numberish = number | bigint | string;
+/** An EIP-712 request as the wallet would sign it. */
+export interface TypedDataLike {
+    domain?: Record<string, unknown>;
+    types: Record<string, unknown>;
+    primaryType: string;
+    message: Record<string, unknown>;
+}
+/**
+ * What to check. A transaction ({chainId, from, to, data, value}), an EIP-712 request ({typedData}), an x402 payment
+ * ({x402, agentId?, payment?}), or several together.
+ */
+export interface CheckInput {
+    chainId?: Numberish;
+    from?: string;
+    to?: string;
+    data?: string;
+    value?: Numberish;
+    typedData?: TypedDataLike;
+    /** the 402's PaymentRequired, or one of its accepts entries */
+    x402?: Record<string, unknown>;
+    /** the seller's ERC-8004 agent id, when known */
+    agentId?: number | string;
+    /** the signed payment (PaymentPayload, {authorization} or the authorization), when already signed */
+    payment?: Record<string, unknown>;
+}
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+export interface CheckOptions {
+    /** default https://t0ll.xyz */
+    baseUrl?: string;
+    /** default globalThis.fetch */
+    fetch?: FetchLike;
+    /** one HTTP request, default 15000 ms */
+    timeoutMs?: number;
+    /** ask once more after Retry-After when a coin is still being read (default true) */
+    retry?: boolean;
+    /** the longest Retry-After we wait for that one retry (default 10000 ms); longer = no retry, the WARN stands */
+    maxRetryWaitMs?: number;
+    /** for tests */
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare class TollBlockedError extends Error {
+    readonly assessment: RiskAssessment;
+    readonly codes: string[];
+    constructor(assessment: RiskAssessment, why?: Action);
+}
+export type UnavailableReason = "network" | "timeout" | "rate-limited" | "server-error" | "bad-request" | "bad-answer" | "unsupported" | "encode";
+export declare class TollUnavailableError extends Error {
+    readonly reason: UnavailableReason;
+    readonly status: number | null;
+    /** the paid route (no daily limit) when the free one was rate limited */
+    readonly paidUrl: string | null;
+    constructor(message: string, o: {
+        reason: UnavailableReason;
+        status?: number | null;
+        paidUrl?: string | null;
+        cause?: unknown;
+    });
+}
+export declare const isAddress: (x: unknown) => x is string;
+/** a chain id as wallets carry it: 4663, 4663n, "4663", "0x1237", "eip155:4663"; null when not readable */
+export declare function chainIdOf(v: unknown): number | null;
+/** JSON with bigints as decimal strings (what the route reads for value, chainId and typed-data fields) */
+export declare const toJson: (x: unknown) => string;
+/** the request body as the route reads it (lib/txcheck.ts parseTxCheckBody): payment rides inside x402 */
+export declare function bodyOf(input: CheckInput): Record<string, unknown>;
+/** seconds from a Retry-After header (delta-seconds only); null when absent or unreadable */
+export declare function retryAfterS(h: string | null): number | null;
+/** the paid URL an answer names when this caller's free coins are used ("coin-over-quota"), else null */
+export declare function paidUrlOf(a: RiskAssessment | null | undefined): string | null;
+/** true when the answer is a well-formed RiskAssessment */
+export declare function isAssessment(x: unknown): x is RiskAssessment;
+/**
+ * Checks one transaction, EIP-712 request or x402 payment before it is signed. Returns Toll's ERC-8265
+ * RiskAssessment. When a coin is still being read (Retry-After), asks once more if the wait is at most
+ * `maxRetryWaitMs`; a coin that is still not read stays a WARN ("coin-not-read"), never an ALLOW.
+ * Throws TollUnavailableError when Toll cannot answer (network, timeout, 429, 5xx, a request it cannot read).
+ */
+export declare function checkTx(input: CheckInput, opts?: CheckOptions): Promise<RiskAssessment>;

package/dist/check.js

@@ -0,0 +1,175 @@
+/**
+ * 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.
+ */
+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;
+/** the paid route without the daily limit (0.01 USDG over x402); the guard never pays it */
+export const PAID_TX_PATH = "/api/x402/tx";
+export const PRESIGN_DOCS = "https://t0ll.xyz/agents/x402#presign";
+export const DEFAULT_TIMEOUT_MS = 15_000;
+export const DEFAULT_MAX_RETRY_WAIT_MS = 10_000;
+/* ------------------------------------------------------------------ errors */
+export class TollBlockedError extends Error {
+    assessment;
+    codes;
+    constructor(assessment, why = assessment.action) {
+        const ws = assessment.warnings ?? [];
+        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}` : ""}`);
+        this.name = "TollBlockedError";
+        this.assessment = assessment;
+        this.codes = ws.map((w) => w.code);
+    }
+}
+export class TollUnavailableError extends Error {
+    reason;
+    status;
+    /** the paid route (no daily limit) when the free one was rate limited */
+    paidUrl;
+    constructor(message, o) {
+        super(message, o.cause === undefined ? undefined : { cause: o.cause });
+        this.name = "TollUnavailableError";
+        this.reason = o.reason;
+        this.status = o.status ?? null;
+        this.paidUrl = o.paidUrl ?? null;
+    }
+}
+/* ------------------------------------------------------------------ helpers */
+const ADDR = /^0x[0-9a-fA-F]{40}$/;
+export const isAddress = (x) => typeof x === "string" && ADDR.test(x);
+/** a chain id as wallets carry it: 4663, 4663n, "4663", "0x1237", "eip155:4663"; null when not readable */
+export function chainIdOf(v) {
+    if (typeof v === "bigint")
+        return v > 0n && v <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(v) : null;
+    if (typeof v === "number")
+        return Number.isSafeInteger(v) && v > 0 ? v : null;
+    if (typeof v !== "string")
+        return null;
+    const s = v.trim().replace(/^eip155:/i, "");
+    if (/^0x[0-9a-fA-F]{1,12}$/.test(s))
+        return Number(BigInt(s));
+    return /^\d{1,15}$/.test(s) ? Number(s) : null;
+}
+/** JSON with bigints as decimal strings (what the route reads for value, chainId and typed-data fields) */
+export const toJson = (x) => JSON.stringify(x, (_k, v) => (typeof v === "bigint" ? v.toString() : v));
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const trimBase = (b) => b.replace(/\/+$/, "");
+/** the request body as the route reads it (lib/txcheck.ts parseTxCheckBody): payment rides inside x402 */
+export function bodyOf(input) {
+    const b = {};
+    if (input.to !== undefined || input.data !== undefined) {
+        if (input.chainId !== undefined)
+            b.chainId = input.chainId;
+        if (input.from !== undefined)
+            b.from = input.from;
+        b.to = input.to;
+        b.data = input.data ?? "0x";
+        b.value = input.value ?? 0;
+    }
+    if (input.typedData)
+        b.typedData = input.typedData;
+    if (input.x402)
+        b.x402 = input.payment ? { ...input.x402, payment: input.payment } : input.x402;
+    if (input.agentId !== undefined && input.agentId !== null)
+        b.agentId = input.agentId;
+    return b;
+}
+/** seconds from a Retry-After header (delta-seconds only); null when absent or unreadable */
+export function retryAfterS(h) {
+    if (!h)
+        return null;
+    const n = Number(h.trim());
+    return Number.isFinite(n) && n >= 0 ? n : null;
+}
+/** the paid URL an answer names when this caller's free coins are used ("coin-over-quota"), else null */
+export function paidUrlOf(a) {
+    for (const w of a?.warnings ?? []) {
+        const p = w["x-toll-evidence"]?.paid;
+        if (typeof p === "string" && p.startsWith("http"))
+            return p;
+    }
+    return null;
+}
+/** true when the answer is a well-formed RiskAssessment */
+export function isAssessment(x) {
+    if (!x || typeof x !== "object")
+        return false;
+    const a = x;
+    return (a.action === "ALLOW" || a.action === "WARN" || a.action === "BLOCK") && Array.isArray(a.warnings);
+}
+/* ------------------------------------------------------------------ the call */
+async function once(url, body, o, f, paid) {
+    const timeoutMs = o.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), timeoutMs);
+    let res;
+    let raw;
+    try {
+        res = await f(url, { method: "POST", headers: { "content-type": "application/json", accept: "application/json" }, body, signal: ctl.signal });
+        raw = await res.text();
+    }
+    catch (e) {
+        const timedOut = ctl.signal.aborted;
+        throw new TollUnavailableError(timedOut ? `Toll did not answer within ${timeoutMs} ms.` : `Toll could not be reached: ${e?.message ?? e}.`, {
+            reason: timedOut ? "timeout" : "network",
+            cause: e,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (res.status === 429) {
+        throw new TollUnavailableError(`Toll's free check is rate limited for this caller (HTTP 429). Paid, no daily limit: ${paid}`, { reason: "rate-limited", status: 429, paidUrl: paid });
+    }
+    if (res.status >= 500)
+        throw new TollUnavailableError(`Toll answered HTTP ${res.status}.`, { reason: "server-error", status: res.status });
+    let json = null;
+    try {
+        json = raw ? JSON.parse(raw) : null;
+    }
+    catch {
+        /* handled below */
+    }
+    if (res.status !== 200) {
+        const err = json && typeof json === "object" && typeof json.error === "string" ? json.error : raw.slice(0, 200);
+        throw new TollUnavailableError(`Toll could not check this request (HTTP ${res.status}): ${err}`, { reason: res.status === 400 || res.status === 413 ? "bad-request" : "bad-answer", status: res.status });
+    }
+    if (!isAssessment(json))
+        throw new TollUnavailableError("Toll's answer was not a RiskAssessment.", { reason: "bad-answer", status: 200 });
+    const header = retryAfterS(res.headers.get("retry-after"));
+    const ext = json["x-toll"]?.retry_after_s;
+    return { a: json, retryS: header ?? (typeof ext === "number" ? ext : null) };
+}
+/**
+ * Checks one transaction, EIP-712 request or x402 payment before it is signed. Returns Toll's ERC-8265
+ * RiskAssessment. When a coin is still being read (Retry-After), asks once more if the wait is at most
+ * `maxRetryWaitMs`; a coin that is still not read stays a WARN ("coin-not-read"), never an ALLOW.
+ * Throws TollUnavailableError when Toll cannot answer (network, timeout, 429, 5xx, a request it cannot read).
+ */
+export async function checkTx(input, opts = {}) {
+    const f = opts.fetch ?? globalThis.fetch;
+    if (!f)
+        throw new TollUnavailableError("No fetch available: pass opts.fetch.", { reason: "network" });
+    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 first = await once(url, body, opts, f, paid);
+    if (first.retryS === null || opts.retry === false)
+        return first.a;
+    const waitMs = Math.max(1, first.retryS) * 1000;
+    if (waitMs > (opts.maxRetryWaitMs ?? DEFAULT_MAX_RETRY_WAIT_MS))
+        return first.a;
+    await (opts.sleep ?? realSleep)(waitMs);
+    // the first answer stands if the retry fails: it is a WARN already, never an ALLOW
+    try {
+        return (await once(url, body, opts, f, paid)).a;
+    }
+    catch {
+        return first.a;
+    }
+}

package/dist/erc8470.d.ts

@@ -0,0 +1,93 @@
+/**
+ * ERC-8470 Launch Observations: Toll's latest on-chain observation of a token on Robinhood Chain, read with plain
+ * JSON-RPC eth_call and hand-written ABI decoding (no viem / ethers). Registry and detector are the reference
+ * deployment (PR https://github.com/ethereum/ERCs/pull/2121).
+ *
+ * NOT READ IS NOT ZERO: type(uint256).max means the detector did not read that finding; it surfaces as `null`
+ * (notRead: true), never as 0.
+ */
+import type { FetchLike } from "./check.js";
+export declare const OBS_REGISTRY = "0x730e3c356299c9203cb042f6c0a9274aeabf9af3";
+/** Toll's detector wallet (the engine that records observations) */
+export declare const OBS_DETECTOR = "0x02593AbFf31f4E8eC1D5c2F297a347C51ef06E5c";
+export declare const OBS_CHAIN_ID = 4663;
+export declare const RH_RPC = "https://rpc.mainnet.chain.robinhood.com";
+/** type(uint256).max */
+export declare const NOT_READ: bigint;
+export type Unit = "bps" | "count" | "label" | "mask" | "seconds";
+/** every kind the ERC defines plus Toll's own, by name: keccak256 of the namespaced string, and its unit */
+export declare const FINDING_KINDS: Readonly<Record<string, {
+    id: string;
+    unit: Unit;
+}>>;
+export type Lean = "none" | "clear" | "careful" | "against";
+export type KeyKind = "none" | "erc8376" | "token" | "erc8462-venue";
+export interface Finding8470 {
+    /** bytes32 kind id */
+    kind: string;
+    /** the kind's name when known ("first-block-share", "signal.deployerSellRatio", ...), else null */
+    name: string | null;
+    unit: Unit | null;
+    /** null = not read (type(uint256).max on chain), never 0 */
+    value: bigint | null;
+    notRead: boolean;
+    param: bigint;
+    lean: Lean;
+}
+export interface Observation8470 {
+    id: bigint;
+    launchKey: string;
+    chainId: bigint;
+    token: string;
+    keyKind: KeyKind;
+    observedBlock: bigint;
+    hashChecked: boolean;
+    detector: string;
+    /** unix seconds */
+    recordedAt: bigint;
+    identityRegistry: string;
+    tally: {
+        against: number;
+        careful: number;
+        clear: number;
+    };
+    agentId: bigint;
+    supersedes: bigint;
+    reportHash: string;
+    evidenceRoot: string;
+    declarationId: string;
+    reportURI: string;
+    findings: Finding8470[];
+}
+export interface Read8470Options {
+    rpcUrl?: string;
+    registry?: string;
+    detector?: string;
+    chainId?: number | bigint;
+    fetch?: FetchLike;
+    timeoutMs?: number;
+}
+export declare const encodeLatestByToken: (chainId: bigint, token: string, detector: string) => string;
+export declare const encodeGetObservation: (id: bigint) => string;
+export declare const encodeLatestFinding: (chainId: bigint, token: string, detector: string, kind: string, param: bigint) => string;
+/** decodes getObservation(uint256)'s return: (Observation, Finding[]) */
+export declare function decodeGetObservation(data: string, id: bigint): Observation8470;
+/**
+ * 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 declare function read8470(token: string, opts?: Read8470Options): Promise<Observation8470 | null>;
+export interface LatestFinding8470 {
+    observationId: bigint;
+    observedBlock: bigint;
+    recordedAt: bigint;
+    /** null = not read (no observation, or the observation did not read this kind), never 0 */
+    value: bigint | null;
+    notRead: boolean;
+    lean: Lean;
+}
+/** decodes latestFinding's fixed-size return (uint256, uint64, uint64, uint256, uint8) */
+export declare function decodeLatestFinding(data: string): LatestFinding8470;
+/** One finding of Toll's latest observation of a token: latestFinding(chainId, token, detector, kind, param). */
+export declare function latestFinding8470(token: string, kind: string, param?: number | bigint, opts?: Read8470Options): Promise<LatestFinding8470>;

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

package/package.json

@@ -1,6 +1,69 @@
-{
-  "name": "@tollxyz/guard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@tollxyz/guard",
+  "version": "0.1.0",
+  "description": "Toll's live pre-sign check in front of an AI agent's wallet: viem, ethers and x402 fetch wrappers that ask Toll (ALLOW / WARN / BLOCK, ERC-8265) before anything is signed on Robinhood Chain. Zero runtime dependencies.",
+  "license": "MIT",
+  "author": "Toll",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/t0ll-xyz/toll-plugins.git",
+    "directory": "packages/guard"
+  },
+  "homepage": "https://t0ll.xyz/agents/plugins",
+  "keywords": [
+    "agent-wallet",
+    "transaction-guard",
+    "pre-sign",
+    "x402",
+    "erc-8004",
+    "erc-8470",
+    "erc-8265",
+    "robinhood-chain",
+    "viem",
+    "ethers",
+    "ai-agent",
+    "toll"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.json --noEmit && tsx --test tests/*.test.ts",
+    "smoke": "node scripts/smoke.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "ethers": "^6.0.0",
+    "viem": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ethers": {
+      "optional": true
+    },
+    "viem": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}