@tollxyz/guard 0.0.0-stage → 0.1.1

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,156 @@
-# 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.
+
+## Gate a buy in one call
+
+Before your agent even builds the swap, ask for one word with `@tollxyz/sdk`:
+
+```ts
+import { Toll } from "@tollxyz/sdk";
+const toll = new Toll();
+const r = await toll.preBuyCheck(token);          // Decision: BLOCK / WARN / ALLOW / WAIT, up to 3 reasons
+if (r.decision === "BLOCK") throw new Error(r.text);           // the owner decides, never the agent
+if (r.decision === "WAIT") await sleep(r.pending!.retryAfterS * 1000); // part of the coin is still being read
+```
+
+It runs the same calibrated rules as the guard's swap check (BLOCK = a finding whose coins rugged at 40% or more
+within 24 h, or sells that fail), so the gate and the guard never disagree. Then let `guardViem` / `guardEthers`
+check the transaction itself when it is signed.
+
+## 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>;