@tollxyz/guard 0.4.0 → 0.4.1

package/README.md

@@ -1,5 +1,8 @@
 # @tollxyz/guard
 
+> **New in 0.4.1: ALLOW tickets** (`ticket` option, `appendTicketSuffix`): a single-use, signed ticket for one exact
+> call, for contracts that require one. See [ALLOW tickets](#allow-tickets).
+
 > **New in 0.4.0: spend caps, allowlists, human approval and preview** (`spend` option). Unset, nothing changes.
 > See [0.4.0: spend caps, allowlists, approval, preview](#040-spend-caps-allowlists-approval-preview).
 
@@ -170,6 +173,7 @@ is at most `maxRetryWaitMs` (default 10 s); a coin still not read stays WARN, ne
 | `spend` | none | 0.4.0: caps, allowlists, approval ([below](#040-spend-caps-allowlists-approval-preview)); unset = 0.3.x behaviour |
 | `store` | in-process `MemorySpendStore` | where spend counters and paid x402 ids live |
 | `failClosed` | `false` | with `spend`: a request whose spend cannot be read is blocked |
+| `ticket` | none | 0.4.1: `true` or `{consumer?, scope?}`: ask Toll for a single-use ALLOW ticket for this exact call; it comes back as `report.ticket` ([below](#allow-tickets)) |
 
 Errors: `TollBlockedError` (`.assessment`, `.codes`, message lists each code and message) and
 `TollUnavailableError` (`.reason`, `.status`, `.paidUrl`).
@@ -333,6 +337,41 @@ export const redisStore: SpendStore = {
 const wallet = guard(walletClient, { spend: { /* ... */ }, store: redisStore });
 ```
 
+## ALLOW tickets
+
+A contract can require a Toll ALLOW ticket before a sensitive call (a router, a module, a Uniswap v4 hook, a
+delegation caveat). The Solidity side is [toll-allow](https://github.com/t0ll-xyz/toll-allow); the full guide is
+https://t0ll.xyz/agents/allow.
+
+- A ticket is an EIP-712 verdict signed by Toll for **one exact call** (target, value, data), one account (`from`),
+  an optional consumer contract and a 60 second window. It is single use.
+- A BLOCK is never signed. A WARN is signed only when no warning is high or critical (as verdict 1). No ticket
+  without `from`, or for a transaction with an EIP-7702 authorization list. When none is issued, `report.ticket` is
+  `{ why }`.
+- Toll's production signer on Robinhood Chain (4663) is `0x4A2C93066d94F1E69f3EAd5438c4efDdf80a46ba`
+  (`TOLL_ALLOW_SIGNER`). Pin it in your contract, or a `TollSignerSet` you control that includes it.
+
+```ts
+import { enforce, appendTicketSuffix } from "@tollxyz/guard";
+
+// 1. check the inner call (what the router will call), bound to your router as the consumer
+const r = await enforce("transaction", () => ({ chainId: 4663, from: me, to: target, data, value }), {
+  ticket: { consumer: ROUTER },
+});
+if (!r.ticket || !("signature" in r.ticket)) throw new Error(r.ticket?.why ?? "no ticket");
+
+// 2. put the ticket on the calldata: data ‖ abi.encode(ticket, signature) ‖ uint32 len ‖ 0x900bc3e1
+const withTicket = appendTicketSuffix(data, r.ticket.ticket, r.ticket.signature);
+// 3. call the router within 60 s: router.exec(target, withTicket) with the same value, from the same account
+```
+
+`appendTicketSuffix` is byte for byte `TollAllow.encodeSuffix` (tested against toll-allow's vectors). For a v4 hook,
+ask with `scope: "v4swap"` and pass `abi.encode(ticket, signature)` as `hookData`. The same option works on
+`checkTx(input, { ticket })`, where the ticket is in `assessment["x-toll"].ticket`.
+
+A ticket is necessary, never sufficient: the contract keeps its own checks (slippage, limits, access control), and
+should keep an owner bypass behind a timelock in case Toll is unreachable.
+
 ## Fail-open or fail-closed
 
 The default is fail-open: if Toll cannot answer, the signature goes ahead, with a `[toll-guard] ... NOT checked`

package/dist/check.d.ts

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

package/dist/check.js

@@ -2,6 +2,7 @@
  * The one call to Toll: POST https://t0ll.xyz/api/tx/check. Every check runs on Toll's server, so a new check reaches
  * every agent without a package update. This file only sends the request and reads the answer.
  */
+import { ticketAskOf } from "./ticket.js";
 export const DEFAULT_BASE_URL = "https://t0ll.xyz";
 /** Robinhood Chain: the only chain the pre-sign check reads for now */
 export const TX_CHAIN_ID = 4663;
@@ -183,7 +184,8 @@ export async function checkTx(input, opts = {}) {
     const base = trimBase(opts.baseUrl ?? DEFAULT_BASE_URL);
     const url = `${base}/api/tx/check`;
     const paid = `${base}${PAID_TX_PATH}`;
-    const body = toJson(bodyOf(input));
+    const ask = ticketAskOf(opts.ticket);
+    const body = toJson(ask ? { ...bodyOf(input), ticket: ask } : bodyOf(input));
     const first = await once(url, body, opts, f, paid);
     if (first.retryS === null || opts.retry === false)
         return first.a;

package/dist/index.d.ts

@@ -12,3 +12,5 @@ export { spendOf, NATIVE, USDG, WETH, DEFAULT_SPEND_ASSETS, UNLIMITED } from "./
 export type { Spend, SpendItem } from "./spend.js";
 export { MemorySpendStore, dayStart } from "./store.js";
 export type { SpendStore } from "./store.js";
+export { appendTicketSuffix, encodeTicketAndSig, ticketAskOf, ticketOfAnswer, TICKET_SUFFIX_MAGIC, TOLL_ALLOW_SIGNER, ALLOW_DOCS } from "./ticket.js";
+export type { TicketAsk, AllowTicket, TicketResult } from "./ticket.js";

package/dist/index.js

@@ -5,3 +5,4 @@ export { guardX402Fetch, readPaymentRequired, readPaymentForms, paymentFormsDiff
 export { read8470, latestFinding8470, decodeGetObservation, decodeLatestFinding, encodeGetObservation, encodeLatestByToken, encodeLatestFinding, FINDING_KINDS, NOT_READ, OBS_REGISTRY, OBS_DETECTOR, OBS_CHAIN_ID, RH_RPC, } from "./erc8470.js";
 export { spendOf, NATIVE, USDG, WETH, DEFAULT_SPEND_ASSETS, UNLIMITED } from "./spend.js";
 export { MemorySpendStore, dayStart } from "./store.js";
+export { appendTicketSuffix, encodeTicketAndSig, ticketAskOf, ticketOfAnswer, TICKET_SUFFIX_MAGIC, TOLL_ALLOW_SIGNER, ALLOW_DOCS } from "./ticket.js";

package/dist/policy.d.ts

@@ -1,4 +1,5 @@
 import { TollBlockedError, TollUnavailableError, type CheckInput, type CheckOptions, type RiskAssessment } from "./check.js";
+import { type TicketResult } from "./ticket.js";
 import { type Spend } from "./spend.js";
 import { type SpendStore } from "./store.js";
 export type WarnPolicy = "allow" | "block" | "block-high" | ((assessment: RiskAssessment) => boolean | Promise<boolean>);
@@ -29,6 +30,11 @@ export interface GuardReport {
         approvalRef?: string;
         needsApproval?: boolean;
     };
+    /**
+     * 0.4.1, with the `ticket` option: Toll's single-use ALLOW ticket for this exact call ({ticket, signature, signer}),
+     * or {why} none was issued. Put it on the call with appendTicketSuffix (routers) or pass abi.encode(ticket, signature).
+     */
+    ticket?: TicketResult;
 }
 export type PolicyCode = "not-allowlisted" | "cap-per-call" | "cap-per-day" | "cap-endpoint" | "approval-denied" | "duplicate-payment" | "unknown-spend";
 export interface Caps {

package/dist/policy.js

@@ -1,4 +1,5 @@
 import { TX_CHAIN_ID, TollBlockedError, TollUnavailableError, checkTx, chainIdOf, paidUrlOf, bodyOf, toJson, } from "./check.js";
+import { ticketOfAnswer } from "./ticket.js";
 import { DEFAULT_SPEND_ASSETS, spendOf } from "./spend.js";
 import { MemorySpendStore, dayStart } from "./store.js";
 /** blocked by your own spend rules; a TollBlockedError, so existing catch blocks still see a block */
@@ -155,7 +156,8 @@ async function enforceVerdict(kind, build, o) {
     }
     const paidUrl = paidUrlOf(a);
     const done = async (decision, basis) => {
-        const r = { kind, input, assessment: a, decision, basis, paidUrl };
+        const tk = ticketOfAnswer(a);
+        const r = { kind, input, assessment: a, decision, basis, paidUrl, ...(tk ? { ticket: tk } : {}) };
         await report(o, r);
         return r;
     };

package/dist/ticket.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 0.4.1: Toll's single-use ALLOW ticket. Ask for one with the `ticket` option; Toll signs a compact EIP-712 verdict
+ * bound to one exact call, one account, an optional consumer contract and a 60 second window. A contract built on
+ * toll-allow (https://github.com/t0ll-xyz/toll-allow) accepts the call only with a valid, unused ticket.
+ * A BLOCK is never signed. No ticket without `from`, or for a transaction with an EIP-7702 authorization list.
+ *
+ * appendTicketSuffix MUST match toll-allow's TollAllow.encodeSuffix / splitSuffix byte for byte:
+ *   body ‖ abi.encode((uint8,uint8,address,address,bytes32,uint64,uint64,bytes32,bytes32), bytes) ‖ uint32 len ‖ 0x900bc3e1
+ * where len is the byte length of the abi.encode part and 0x900bc3e1 = bytes4(keccak256("TollAllow.v1")).
+ */
+import type { Hex } from "./check.js";
+/** what to ask Toll for: `true` = scope "call", any consumer */
+export interface TicketAsk {
+    /** the contract that will check the ticket (its `consumer` field); unset = any contract */
+    consumer?: string;
+    /** "call" (default): bound to (target, value, keccak256(data)); "v4swap": bound to the swap a HookrRouter call makes */
+    scope?: "call" | "v4swap";
+}
+/** the ticket as Toll returns it (x-toll.ticket.ticket); uint64 times are unix seconds */
+export interface AllowTicket {
+    scope: number;
+    verdict: number;
+    account: string;
+    consumer: string;
+    subject: string;
+    validAfter: number | bigint | string;
+    validUntil: number | bigint | string;
+    nonce: string;
+    reportHash: string;
+}
+/** x-toll.ticket: a signed ticket, or why none was issued */
+export type TicketResult = {
+    ticket: AllowTicket;
+    signature: Hex;
+    signer: string;
+} | {
+    why: string;
+};
+/** bytes4(keccak256("TollAllow.v1")) */
+export declare const TICKET_SUFFIX_MAGIC = "0x900bc3e1";
+/** Toll's production ALLOW signer on Robinhood Chain (4663): pin it, or a TollSignerSet you control that includes it */
+export declare const TOLL_ALLOW_SIGNER = "0x4A2C93066d94F1E69f3EAd5438c4efDdf80a46ba";
+export declare const ALLOW_DOCS = "https://t0ll.xyz/agents/allow";
+/** the ask as the route reads it (`ticket: {consumer?, scope?}`), or null for none */
+export declare function ticketAskOf(t: boolean | TicketAsk | undefined | null): TicketAsk | null;
+/** the ticket in an answer, when the answer carries one (signed or with its why) */
+export declare function ticketOfAnswer(a: {
+    "x-toll"?: Record<string, unknown>;
+} | null | undefined): TicketResult | undefined;
+/** abi.encode(Ticket, bytes) as hex without 0x: the static tuple inline (9 words), then the offset and the bytes */
+export declare function encodeTicketAndSig(t: AllowTicket, signature: string): string;
+/**
+ * The calldata a ticket-checking router reads: `data ‖ abi.encode(ticket, signature) ‖ uint32 len ‖ 0x900bc3e1`.
+ * The ticket's subject is over `data` (the body) only. Identical to TollAllow.encodeSuffix in toll-allow.
+ */
+export declare function appendTicketSuffix(data: Hex, ticket: AllowTicket, signature: Hex): Hex;

package/dist/ticket.js

@@ -0,0 +1,90 @@
+/** bytes4(keccak256("TollAllow.v1")) */
+export const TICKET_SUFFIX_MAGIC = "0x900bc3e1";
+/** Toll's production ALLOW signer on Robinhood Chain (4663): pin it, or a TollSignerSet you control that includes it */
+export const TOLL_ALLOW_SIGNER = "0x4A2C93066d94F1E69f3EAd5438c4efDdf80a46ba";
+export const ALLOW_DOCS = "https://t0ll.xyz/agents/allow";
+/** the ask as the route reads it (`ticket: {consumer?, scope?}`), or null for none */
+export function ticketAskOf(t) {
+    if (t === undefined || t === null || t === false)
+        return null;
+    if (t === true)
+        return {};
+    const o = {};
+    if (t.consumer !== undefined)
+        o.consumer = t.consumer;
+    if (t.scope !== undefined)
+        o.scope = t.scope;
+    return o;
+}
+/** the ticket in an answer, when the answer carries one (signed or with its why) */
+export function ticketOfAnswer(a) {
+    const t = a?.["x-toll"]?.ticket;
+    if (!t || typeof t !== "object")
+        return undefined;
+    if (typeof t.why === "string")
+        return { why: t.why };
+    if (t.ticket && typeof t.ticket === "object" && typeof t.signature === "string" && typeof t.signer === "string") {
+        return { ticket: t.ticket, signature: t.signature, signer: t.signer };
+    }
+    return undefined;
+}
+/* ------------------------------------------------------------------ ABI encoding (no dependencies) */
+const hexBody = (h, what) => {
+    if (typeof h !== "string" || !/^0x([0-9a-fA-F]{2})*$/.test(h))
+        throw new TypeError(`${what} must be 0x hex with whole bytes`);
+    return h.slice(2).toLowerCase();
+};
+const word = (n, bits, what) => {
+    if (n < 0n || n >= 1n << BigInt(bits))
+        throw new RangeError(`${what} does not fit in uint${bits}`);
+    return n.toString(16).padStart(64, "0");
+};
+const uint = (v, bits, what) => {
+    let n;
+    try {
+        n = BigInt(v);
+    }
+    catch {
+        throw new TypeError(`${what} must be a whole number`);
+    }
+    return word(n, bits, what);
+};
+const addr = (a, what) => {
+    if (typeof a !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(a))
+        throw new TypeError(`${what} must be an address`);
+    return a.slice(2).toLowerCase().padStart(64, "0");
+};
+const b32 = (h, what) => {
+    if (typeof h !== "string" || !/^0x[0-9a-fA-F]{64}$/.test(h))
+        throw new TypeError(`${what} must be 32 bytes`);
+    return h.slice(2).toLowerCase();
+};
+/** abi.encode(Ticket, bytes) as hex without 0x: the static tuple inline (9 words), then the offset and the bytes */
+export function encodeTicketAndSig(t, signature) {
+    const sig = hexBody(signature, "signature");
+    const head = uint(t.scope, 8, "ticket.scope") +
+        uint(t.verdict, 8, "ticket.verdict") +
+        addr(t.account, "ticket.account") +
+        addr(t.consumer, "ticket.consumer") +
+        b32(t.subject, "ticket.subject") +
+        uint(t.validAfter, 64, "ticket.validAfter") +
+        uint(t.validUntil, 64, "ticket.validUntil") +
+        b32(t.nonce, "ticket.nonce") +
+        b32(t.reportHash, "ticket.reportHash");
+    const offset = word(10n * 32n, 256, "offset"); // 9 tuple words + this offset word
+    const len = word(BigInt(sig.length / 2), 256, "signature length");
+    const padded = sig + "0".repeat((64 - (sig.length % 64)) % 64);
+    return head + offset + len + padded;
+}
+/**
+ * The calldata a ticket-checking router reads: `data ‖ abi.encode(ticket, signature) ‖ uint32 len ‖ 0x900bc3e1`.
+ * The ticket's subject is over `data` (the body) only. Identical to TollAllow.encodeSuffix in toll-allow.
+ */
+export function appendTicketSuffix(data, ticket, signature) {
+    const body = hexBody(data, "data");
+    const enc = encodeTicketAndSig(ticket, signature);
+    const n = enc.length / 2;
+    if (n >= 2 ** 32)
+        throw new RangeError("ticket encoding too long");
+    return `0x${body}${enc}${n.toString(16).padStart(8, "0")}${TICKET_SUFFIX_MAGIC.slice(2)}`;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tollxyz/guard",
-  "version": "0.4.0",
-  "description": "Toll's live pre-sign check in front of an AI agent's wallet: viem, viem smart-account, ethers and x402 fetch wrappers that ask Toll (ALLOW / WARN / BLOCK, ERC-8265) before anything is signed on Robinhood Chain: transactions, messages, typed data, batches, user operations, EIP-7702 authorizations. Spend caps, allowlists and human approval around the verdict. Zero runtime dependencies.",
+  "version": "0.4.1",
+  "description": "Toll's live pre-sign check in front of an AI agent's wallet: viem, viem smart-account, ethers and x402 fetch wrappers that ask Toll (ALLOW / WARN / BLOCK, ERC-8265) before anything is signed on Robinhood Chain: transactions, messages, typed data, batches, user operations, EIP-7702 authorizations. Spend caps, allowlists and human approval around the verdict; single-use ALLOW tickets for contracts that require one. Zero runtime dependencies.",
   "license": "MIT",
   "author": "Toll",
   "type": "module",
@@ -37,6 +37,7 @@
     "erc-8004",
     "erc-8470",
     "erc-8265",
+    "allow-ticket",
     "robinhood-chain",
     "viem",
     "ethers",