@piprail/sdk 1.8.0 → 1.10.0

package/dist/index.d.cts

@@ -2,7 +2,7 @@ import * as viem_zksync from 'viem/zksync';
 import * as abitype from 'abitype';
 import * as viem_chains from 'viem/chains';
 import * as viem from 'viem';
-import { Chain, Account, Hex } from 'viem';
+import { Chain, Account, Hex, PublicClient } from 'viem';
 
 /**
  * The on-the-wire payment protocol. Self-contained — it runs entirely
@@ -40,6 +40,8 @@ type AddressId = string;
 interface X402ResourceObject {
     url: string;
     description?: string;
+    /** The resource's response content-type, e.g. 'application/json' (v2 ResourceInfo, optional). */
+    mimeType?: string;
 }
 interface X402AcceptEntry {
     scheme: 'onchain-proof';
@@ -63,11 +65,55 @@ interface X402AcceptEntry {
         symbol?: string;
     };
 }
+/**
+ * A standard x402 `exact` rail (EVM / EIP-3009) — the interop rail a PipRail gate
+ * advertises ALONGSIDE its `onchain-proof` rail (dual-advertise) so any standard
+ * x402 client can pay it. Same v2 PaymentRequirements skeleton as
+ * {@link X402AcceptEntry}; only `scheme` and `extra` differ. The `extra` carries
+ * the EIP-712 domain a payer signs over — `name`/`version` are READ from the token
+ * contract by the gate (never assumed), since e.g. USDC's domain name is "USD Coin",
+ * not the "USDC" symbol.
+ */
+interface X402ExactAcceptEntry {
+    scheme: 'exact';
+    network: Caip2;
+    amount: string;
+    asset: AssetId;
+    payTo: AddressId;
+    maxTimeoutSeconds: number;
+    extra: {
+        /** The exact-EVM transfer method. PipRail self-settles EIP-3009 today. */
+        assetTransferMethod: 'eip3009';
+        /** EIP-712 domain name of the token (USDC: "USD Coin"; EURC: "EURC"). Read on-chain. */
+        name: string;
+        /** EIP-712 domain version of the token (USDC/EURC: "2"). Read on-chain. */
+        version: string;
+        /** Confirmations the gate waits for before granting access — mirrors the gate's
+         *  `minConfirmations`, so the exact rail honours the same reorg safety as onchain-proof.
+         *  A PipRail convenience (standard clients ignore unknown keys). */
+        minConfirmations?: number;
+        /** Token decimals — a PipRail convenience (standard clients ignore unknown keys). */
+        decimals?: number;
+        /** Human-readable amount, e.g. "0.05" — a PipRail convenience. */
+        amountFormatted?: string;
+        symbol?: string;
+    };
+}
+/** A challenge `accepts[]` entry — either PipRail's `onchain-proof` rail or a standard `exact` rail. */
+type X402AnyAccept = X402AcceptEntry | X402ExactAcceptEntry;
 interface X402Challenge {
     x402Version: 2;
-    error: string | null;
+    /**
+     * Optional human-readable reason (v2 `error?: string`). PipRail EMITS it only on a
+     * rejected-proof re-challenge (omitted on a fresh challenge). Typed to also tolerate
+     * `null` when PARSING a foreign challenge — some deployed servers send `error: null`.
+     */
+    error?: string | null;
     resource: X402ResourceObject;
-    accepts: X402AcceptEntry[];
+    accepts: X402AnyAccept[];
+    /** v2 optional extensions. PipRail stamps the machine-readable rejection reason here on a
+     *  rejected-proof re-challenge: `{ piprail: { code, detail } }`. Omitted otherwise. */
+    extensions?: Record<string, unknown>;
 }
 interface X402PaymentSignature {
     x402Version: 2;
@@ -86,8 +132,43 @@ interface X402PaymentSignature {
         txHash: string;
     };
 }
+/**
+ * The EIP-3009 authorization a payer signs for a standard `exact` rail. All
+ * numeric fields are DECIMAL strings on the wire (value, validAfter, validBefore);
+ * `nonce` is a 0x-prefixed 32-byte hex. Identical shape across x402 v1 and v2.
+ */
+interface ExactAuthorizationWire {
+    from: string;
+    to: string;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: string;
+}
+/** The `payload` a client sends for an `exact` rail: an EIP-3009 signature + its authorization. */
+interface ExactPaymentPayload {
+    signature: string;
+    authorization: ExactAuthorizationWire;
+}
+/**
+ * What {@link parseExactPaymentHeader} extracts from an inbound `exact` payment,
+ * normalised across the v1 (`X-PAYMENT`, flat `{scheme,network,payload}`, network
+ * slug) and v2 (`PAYMENT-SIGNATURE`, `{accepted,payload}`, CAIP-2 network) wire
+ * shapes. `network`/`asset` are the CLIENT's claim — used only to MATCH an offered
+ * rail; the gate re-derives every verified field from its own trusted rail.
+ */
+interface ParsedExactPayment {
+    x402Version: number;
+    /** The client's claimed network (slug or CAIP-2) — for matching, not trust. */
+    network: string;
+    /** The client's claimed asset, if present (v2 `accepted.asset`). */
+    asset?: string;
+    payload: ExactPaymentPayload;
+    /** The full decoded PaymentPayload, for verbatim forwarding to a facilitator (Mode B). */
+    raw: Record<string, unknown>;
+}
 interface X402Receipt {
-    scheme: 'onchain-proof';
+    scheme: 'onchain-proof' | 'exact';
     /**
      * x402 v2 SettlementResponse: settlement succeeded. Always `true` here — a
      * failed verification returns a 402, never a receipt.
@@ -122,7 +203,7 @@ interface X402Receipt {
  * `maxPaymentRetries` (a short backoff absorbs RPC lag); it does not branch on
  * the code.
  */
-type VerifyErrorCode = 'tx_not_found' | 'insufficient_confirmations' | 'tx_reverted' | 'no_meta' | 'wrong_recipient' | 'amount_too_low' | 'transfer_not_found' | 'payment_expired' | 'tx_already_used';
+type VerifyErrorCode = 'tx_not_found' | 'insufficient_confirmations' | 'tx_reverted' | 'no_meta' | 'wrong_recipient' | 'amount_too_low' | 'transfer_not_found' | 'payment_expired' | 'tx_already_used' | 'signature_invalid';
 /** The shape every driver's `verify()` returns. Shared by drivers + protocol. */
 type VerifyResult = {
     ok: true;
@@ -132,6 +213,14 @@ type VerifyResult = {
     error: VerifyErrorCode;
     detail: string;
 };
+declare const HEADER_REQUIRED = "payment-required";
+declare const HEADER_SIGNATURE = "payment-signature";
+declare const HEADER_RESPONSE = "payment-response";
+/** Legacy x402 v1 header names. PipRail EMITS v2 (the constants above) but also
+ *  READS the v1 client header and ECHOES the v1 response header, so a deprecated
+ *  v1 client (still ~half the installed base) interoperates on the `exact` rail. */
+declare const HEADER_SIGNATURE_V1 = "x-payment";
+declare const HEADER_RESPONSE_V1 = "x-payment-response";
 declare function buildChallengeHeader(challenge: X402Challenge): string;
 declare function buildReceiptHeader(receipt: X402Receipt): string;
 declare function buildSignatureHeader(signature: X402PaymentSignature): string;
@@ -144,6 +233,15 @@ declare function parseChallenge(response: Response): Promise<X402Challenge | nul
 declare function parseReceipt(response: Response): X402Receipt | null;
 /** Parse a PAYMENT-SIGNATURE header value (server side). */
 declare function parseSignatureHeader(value: string): X402PaymentSignature | null;
+/**
+ * Parse an inbound `exact` payment from a base64 header value (`PAYMENT-SIGNATURE`
+ * v2 or `X-PAYMENT` v1). Tolerant of BOTH wire shapes — the inner
+ * `{ signature, authorization }` payload is identical across versions, so we read
+ * `scheme`/`network` from either the v2 `accepted` object or the v1 flat fields.
+ * Returns null when the value isn't a recognisable `exact` payment (e.g. it's an
+ * `onchain-proof` proof, or malformed).
+ */
+declare function parseExactPaymentHeader(value: string): ParsedExactPayment | null;
 /**
  * Pick the first accepts[] entry on the `onchain-proof` scheme whose network
  * satisfies `matches` (any chain family). Returns null if none match.
@@ -838,7 +936,7 @@ declare const CHAINS: {
                         gasPrice: bigint;
                         maxFeePerBlobGas?: undefined | undefined;
                         maxFeePerGas?: undefined | undefined;
-                        maxPriorityFeePerGas? /** Native coin metadata. Defaults to 18-decimal ETH. */: undefined | undefined;
+                        maxPriorityFeePerGas?: undefined | undefined;
                         isSystemTx?: undefined | undefined;
                         mint?: undefined | undefined;
                         sourceHash?: undefined | undefined;
@@ -3340,9 +3438,7 @@ declare const CHAINS: {
                         value: bigint;
                         yParity: number;
                         accessList: viem.AccessList;
-                        authorizationList
-                        /** JSON-RPC endpoint. */
-                        ? /** JSON-RPC endpoint. */: undefined | undefined;
+                        authorizationList?: undefined | undefined;
                         blobVersionedHashes?: undefined | undefined;
                         chainId: number;
                         type: "eip2930";
@@ -3732,6 +3828,62 @@ declare const CHAINS: {
             };
         };
     };
+    kaia: {
+        chain: {
+            blockExplorers: {
+                readonly default: {
+                    readonly name: "KaiaScan";
+                    readonly url: "https://kaiascan.io";
+                    readonly apiUrl: "https://api-cypress.klaytnscope.com/api";
+                };
+            };
+            blockTime?: number | undefined | undefined;
+            contracts: {
+                readonly multicall3: {
+                    readonly address: "0xcA11bde05977b3631167028862bE2a173976CA11";
+                    readonly blockCreated: 96002415;
+                };
+            };
+            ensTlds?: readonly string[] | undefined;
+            id: 8217;
+            name: "Kaia";
+            nativeCurrency: {
+                readonly decimals: 18;
+                readonly name: "Kaia";
+                readonly symbol: "KAIA";
+            };
+            experimental_preconfirmationTime?: number | undefined | undefined;
+            rpcUrls: {
+                readonly default: {
+                    readonly http: readonly ["https://public-en.node.kaia.io"];
+                };
+            };
+            sourceId?: number | undefined | undefined;
+            testnet?: boolean | undefined | undefined;
+            custom?: Record<string, unknown> | undefined;
+            extendSchema?: Record<string, unknown> | undefined;
+            fees?: viem.ChainFees<undefined> | undefined;
+            formatters?: undefined;
+            prepareTransactionRequest?: ((args: viem.PrepareTransactionRequestParameters, options: {
+                client: viem.Client;
+                phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+            }) => Promise<viem.PrepareTransactionRequestParameters>) | [fn: ((args: viem.PrepareTransactionRequestParameters, options: {
+                client: viem.Client;
+                phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+            }) => Promise<viem.PrepareTransactionRequestParameters>) | undefined, options: {
+                runAt: readonly ("beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters")[];
+            }] | undefined;
+            serializers?: viem.ChainSerializers<undefined, viem.TransactionSerializable> | undefined;
+            verifyHash?: ((client: viem.Client, parameters: viem.VerifyHashActionParameters) => Promise<viem.VerifyHashActionReturnType>) | undefined;
+        };
+        tokens: {
+            USDT: {
+                address: "0xd077A400968890Eacc75cdc901F0356c943e4fDb";
+                decimals: number;
+                symbol: string;
+            };
+        };
+    };
 };
 /** A built-in EVM chain name. */
 type ChainName = keyof typeof CHAINS;
@@ -4014,6 +4166,38 @@ interface ResolvedNetwork {
     discoverySigner?(wallet: WalletHandle): DiscoverySigner | null;
     /** Verify `ref` satisfies `accept`, RPC-only, in-process. */
     verify(ref: string, accept: X402AcceptEntry): Promise<VerifyResult>;
+    /**
+     * OPTIONAL (EVM-only today) — the on-chain EIP-712 domain `{ name, version }` of an
+     * EIP-3009 token `asset`, read from the contract (`name()`/`version()`). Returns
+     * `null` when the asset is NOT an EIP-3009 token (no `transferWithAuthorization` —
+     * e.g. USDT, native coin, or a plain ERC-20), so the gate can refuse to advertise a
+     * standard `exact` rail for it. Never derived from the symbol (USDC's domain name is
+     * "USD Coin", not "USDC"; EURC's is "EURC"). Called once at exact-rail resolution
+     * (cached by the gate). RPC-read; may throw on a transient read (the gate surfaces a
+     * clear config error). The first of two optional server methods for the `exact` rail.
+     */
+    exactDomain?(asset: string): Promise<{
+        name: string;
+        version: string;
+    } | null>;
+    /**
+     * OPTIONAL (EVM-only today) — verify a standard x402 `exact` (EIP-3009) payment
+     * locally, then SELF-SETTLE it by broadcasting `transferWithAuthorization` from the
+     * merchant's own `relayer` wallet (the merchant pays gas to receive; the signature
+     * binds `to`, so no redirect risk). RETURNS a `VerifyResult`:
+     *   - `{ ok:false, error }` for a CLIENT-fixable fault (bad signature, expired,
+     *     wrong recipient/amount, used nonce, simulation revert) → gate replies 402;
+     *   - `{ ok:true, receipt }` once the settle tx is mined.
+     * THROWS {@link SettlementError} when a VALID + simulated payment fails to BROADCAST
+     * (relayer out of gas / RPC down) → gate replies 5xx (the payer's authorization is
+     * still good and its nonce unused). Re-derives every checked field from the trusted
+     * `accept`, never the client echo.
+     */
+    settleExactSelf?(input: {
+        relayer: WalletHandle;
+        payload: ExactPaymentPayload;
+        accept: X402ExactAcceptEntry;
+    }): Promise<VerifyResult>;
 }
 interface ResolveOptions {
     /** The developer-supplied `chain` selector. */
@@ -4606,7 +4790,10 @@ declare class PipRailClient {
      * `quote()` (read-only) and `fetch()` (which then authorises + pays).
      */
     private resolveChallenge;
-    /** The candidate accepts this client could pay: our scheme, on the bound network. */
+    /** The candidate accepts this client could pay: our scheme, on the bound network.
+     *  A dual-advertised challenge may also carry standard `exact` rails — the PipRail
+     *  client ignores those (it pays the backendless `onchain-proof` rail); the type
+     *  predicate narrows the `X402AnyAccept` union to the rails we settle. */
     private gatherCandidates;
     /** Build the full {@link PaymentPlan} from an already-parsed challenge + bound
      *  net/wallet. Shared by `planPayment` (read-only) and `fetch`'s autoRoute. */
@@ -4714,7 +4901,8 @@ declare function paymentTools(client: PipRailClient): AgentTool[];
  * consumed by every emitter below.
  */
 interface PaymentRail {
-    scheme: 'onchain-proof';
+    /** `onchain-proof` (PipRail's default) or the standard `exact` rail (dual-advertise). */
+    scheme: 'onchain-proof' | 'exact';
     network: Caip2;
     asset: AssetId;
     payTo: AddressId;
@@ -4877,6 +5065,30 @@ interface AcceptOption {
     /** RPC override for this chain (defaults to the top-level `rpcUrl`). */
     rpcUrl?: string;
 }
+/**
+ * Opt into ALSO advertising a standard x402 `exact` rail (EIP-3009) beside the
+ * default `onchain-proof` rail, so ANY standard x402 client can pay this gate
+ * (dual-advertise). EVM + EIP-3009 tokens only (USDC, EURC — NOT USDT, NOT native).
+ * Omitting `exact` leaves the gate byte-identical to today (onchain-proof only).
+ *
+ * Two settlement modes, both backendless (PipRail hosts nothing):
+ *  - `settle: 'self'`  — your own `relayer` key broadcasts `transferWithAuthorization`.
+ *     You pay gas to RECEIVE (the inverse of onchain-proof, where the payer pays gas)
+ *     and must keep the relayer funded. The signature binds `to`, so there's no
+ *     redirect risk. This is the on-brand default for the rail.
+ *  - `settle: { facilitator }` — delegate verify+settle to a third-party x402
+ *     facilitator YOU choose (Coinbase CDP, x402.org, …). No relayer key needed; the
+ *     facilitator pays gas. Also the only path onto Coinbase's Bazaar directory.
+ */
+interface ExactRailOption {
+    settle: 'self' | {
+        facilitator: string;
+        authHeaders?: () => Promise<Record<string, string>>;
+    };
+    /** Required for `settle: 'self'` — the gas-paying relayer wallet: EVM `{ privateKey }`
+     *  or a bring-your-own `{ walletClient }`. (Distinct from `payTo`, the receive address.) */
+    relayer?: unknown;
+}
 interface RequirePaymentOptions {
     /**
      * Single-chain form: which chain to accept payment on. EVM ('bnb'|'base'|…),
@@ -4925,6 +5137,12 @@ interface RequirePaymentOptions {
     markUsed?: (ref: string) => void | Promise<void>;
     /** Fired when a payment verifies successfully. */
     onPaid?: (receipt: X402Receipt) => void;
+    /**
+     * ALSO advertise a standard x402 `exact` rail (EIP-3009) so any standard x402
+     * client can pay this gate — opt-in, EVM/EIP-3009 only. See {@link ExactRailOption}.
+     * Omit to keep the gate exactly as today (`onchain-proof` only).
+     */
+    exact?: ExactRailOption;
 }
 type VerifyPaymentResult = {
     kind: 'paid';
@@ -4936,12 +5154,21 @@ type VerifyPaymentResult = {
     requiredHeader: string;
     statusCode: 402;
 } | {
+    /**
+     * A submitted proof was rejected. Conformant: this carries a FRESH
+     * re-`challenge` (full v2 PaymentRequired with `accepts[]` + the reason in
+     * `error` + the machine code in `extensions.piprail`) so a standard x402
+     * client can immediately retry. Adapters emit `challenge` + the
+     * `PAYMENT-REQUIRED` header — NOT the legacy {@link toInvalidBody}.
+     */
     kind: 'invalid';
     error: string;
     detail: string;
+    challenge: X402Challenge;
+    requiredHeader: string;
     statusCode: 402;
 };
-/** The canonical x402 v2 JSON body for a rejected proof (a 402 'invalid'). */
+/** A minimal 402 'invalid' JSON body. @deprecated — see {@link toInvalidBody}. */
 interface X402InvalidBody {
     x402Version: 2;
     status: 'invalid';
@@ -4949,9 +5176,14 @@ interface X402InvalidBody {
     detail: string;
 }
 /**
- * Build the canonical 402 'invalid' body. Use this in EVERY framework adapter
- * (Express, Hono, Fastify, Workers, …) so a rejected proof returns the IDENTICAL
- * envelope everywhere — `verify()` produces the reason, this shapes the body.
+ * @deprecated LEGACY minimal rejection body. The gate now returns a fully
+ * **conformant** rejection: `gate.verify()`'s `kind:'invalid'` result carries a full
+ * v2 PaymentRequired re-`challenge` (with `accepts[]` so a standard x402 client can
+ * retry, the reason in `error`, and the machine code in `extensions.piprail`). The
+ * built-in `requirePayment` adapter emits `result.challenge` + the `PAYMENT-REQUIRED`
+ * header. PREFER that. This helper (a bare `{ status:'invalid', error, detail }` with
+ * NO `accepts[]`) remains only for back-compat with hand-rolled adapters; a standard
+ * client that receives it can't retry. Migrate to `result.challenge`.
  */
 declare function toInvalidBody(result: {
     error: string;
@@ -5004,6 +5236,68 @@ type ExpressLikeMiddleware = (req: ExpressLikeRequest, res: ExpressLikeResponse,
  */
 declare function requirePayment(options: RequirePaymentOptions): ExpressLikeMiddleware;
 
+/**
+ * Mode-B settlement: delegate a standard `exact` payment to a THIRD-PARTY x402
+ * facilitator the MERCHANT chooses (Coinbase CDP, x402.org, or any). PipRail hosts
+ * nothing — this is two HTTP POSTs to the merchant's configured facilitator URL.
+ *
+ * PROTOCOL LAYER — pure `fetch`, ZERO chain libraries (STANDARDS §1). The other
+ * settlement mode (self-settle with the merchant's own relayer key) lives in the
+ * EVM driver; this one is chain-agnostic because the facilitator does the chain work.
+ *
+ * The wire contract (x402 v2, verified against coinbase/x402 core):
+ *   POST {url}/verify   body { x402Version, paymentPayload, paymentRequirements } → { isValid, invalidReason?, payer? }
+ *   POST {url}/settle   SAME body                                                → { success, transaction, network, payer?, errorReason? }
+ * Both protocol outcomes are HTTP 200 (the boolean flips); a non-200 is a
+ * transport/auth failure. There is no registration and no idempotency key — so a
+ * SELF-settling merchant must guard replay itself (the gate's used-proof set does).
+ */
+
+/** Standard x402 `exact` PaymentRequirements, built from the gate's TRUSTED rail. */
+interface FacilitatorPaymentRequirements {
+    scheme: 'exact';
+    network: string;
+    asset: string;
+    amount: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra: {
+        name: string;
+        version: string;
+    };
+}
+/** A merchant-chosen facilitator: its base URL + optional per-request auth headers. */
+interface FacilitatorConfig {
+    /** Base URL, e.g. 'https://x402.org/facilitator' (trailing slash stripped). */
+    url: string;
+    /** Optional async auth-header provider (e.g. CDP JWT). Omit for the free, no-auth facilitators. */
+    authHeaders?: () => Promise<Record<string, string>>;
+}
+interface SettleViaFacilitatorInput extends FacilitatorConfig {
+    x402Version: number;
+    /** The decoded PaymentPayload the client sent — forwarded verbatim. */
+    paymentPayload: Record<string, unknown>;
+    /** PaymentRequirements built from the gate's trusted rail (never the client echo). */
+    paymentRequirements: FacilitatorPaymentRequirements;
+    /** The receipt's network (CAIP-2) + asset/amount/payTo, for building the X402Receipt on success. */
+    receipt: {
+        network: Caip2;
+        asset: AssetId;
+        payTo: AddressId;
+        amount: string;
+    };
+    /** authorization.from, for the receipt's `payer`. */
+    payerHint?: string;
+}
+/**
+ * Verify-then-settle a standard `exact` payment through a third-party facilitator.
+ * Returns a {@link VerifyResult}: `{ ok:false, error }` for a client-fixable
+ * facilitator rejection (verify isValid:false, or settle success:false) → 402;
+ * `{ ok:true, receipt }` on a settled payment. THROWS {@link SettlementError} on a
+ * transport/auth failure (non-200) — the gate replies 5xx, never a misleading 402.
+ */
+declare function settleViaFacilitator(input: SettleViaFacilitatorInput): Promise<VerifyResult>;
+
 /**
  * The driver registry — the ONLY place the families meet. Routing decides a
  * family from the `chain` value (synchronously), then asks that family's
@@ -5148,6 +5442,22 @@ declare class PaymentDeclinedError extends PipRailError {
 declare class ConfirmationTimeoutError extends PipRailError {
     readonly code = "CONFIRMATION_TIMEOUT";
 }
+/**
+ * A standard `exact` payment was VALID (signature recovered, params checked,
+ * simulation passed) but SETTLEMENT failed for a SERVER-side reason — the
+ * merchant's own relayer couldn't broadcast `transferWithAuthorization` (out of
+ * gas, RPC down, dropped tx), or a Mode-B facilitator returned a transport/auth
+ * error. This is NOT the payer's fault: their signed EIP-3009 authorization is
+ * still valid and its nonce UNUSED, so it can be re-presented once the merchant
+ * fixes their relayer/facilitator. The gate THROWS this (it's an operational
+ * problem to fix, not a proof to reject), so a framework adapter returns 5xx —
+ * never a 402, which would wrongly tell the payer to re-pay. `.cause` carries the
+ * raw chain/HTTP error. (Server-side; the `onchain-proof` rail can't raise it —
+ * there the payer broadcasts, so there's nothing for the merchant to settle.)
+ */
+declare class SettlementError extends PipRailError {
+    readonly code = "SETTLEMENT_FAILED";
+}
 /** Server returned 402 but the PAYMENT-REQUIRED envelope was missing or malformed. */
 declare class InvalidEnvelopeError extends PipRailError {
     readonly code = "INVALID_ENVELOPE";
@@ -5202,28 +5512,29 @@ declare class UnsupportedNetworkError extends PipRailError {
 }
 
 /**
- * ── EVM SECTION: x402 `exact` scheme (interop building block) ──────────────
+ * ── EVM SECTION: x402 `exact` scheme (EIP-3009) — BUYER + SELLER ───────────
  *
- * EXPERIMENTAL / ADVANCED. PipRail's own gates use the `onchain-proof` scheme
- * (client pays first, proves with a tx ref, server verifies locally — no
- * facilitator). This module is the opposite end: the building blocks to PAY a
- * server that speaks the mainstream x402 `exact` scheme (Coinbase-style), where
- * the client signs an EIP-3009 `transferWithAuthorization` and a third-party
- * facilitator broadcasts it. It lets a PipRail agent buy from `exact` servers
- * too — making PipRail a *universal* x402 client — while our servers stay
- * backendless.
+ * PipRail's own gates default to the `onchain-proof` scheme (client pays first,
+ * proves with a tx ref, server verifies locally). This module is the standard
+ * x402 `exact` interop, in BOTH directions, EVM + EIP-3009 only, on the existing
+ * `viem` peer (no new dep):
  *
- * What's here is the deterministic, unit-testable core: parse an `exact`
- * requirement, build + EIP-712-sign the authorization, and encode the
- * `X-PAYMENT` header. It is intentionally NOT wired into `PipRailClient.fetch`'s
- * default flow: `exact` is a cross-vendor wire protocol whose live acceptance
- * can only be confirmed against a real facilitator, and bolting a second
- * payment protocol into the core would cut against PipRail's keep-it-simple
- * design. Use these helpers to hand-roll an `exact` payment, and validate
- * against your target facilitator before production. See
- * `.claude/plans/agent-readiness/04-universal-exact.md`.
+ *   • BUYER side (client) — parse an `exact` requirement, build + EIP-712-sign the
+ *     EIP-3009 authorization, encode the `X-PAYMENT` header. Deterministic,
+ *     unit-testable; NOT wired into `PipRailClient.fetch`'s default (see
+ *     `.claude/plans/agent-readiness/04-universal-exact.md`).
  *
- * EVM + EIP-3009 only (USDC and kin). Uses the existing `viem` peer — no new dep.
+ *   • SELLER side (gate) — {@link readExactDomain} (read the token's true EIP-712
+ *     domain so the gate can advertise + verify it) and {@link verifyAndSettleExactEvm}
+ *     (verify an inbound EIP-3009 authorization locally, then SELF-SETTLE it by
+ *     broadcasting `transferWithAuthorization` from the merchant's own relayer key —
+ *     no third-party facilitator). This is what lets a PipRail gate get PAID by ANY
+ *     standard x402 client. See `.claude/plans/compliance/`.
+ *
+ * Self-settle uses `transferWithAuthorization` (NOT `receiveWithAuthorization`,
+ * which requires `msg.sender == payTo` and so can't be broadcast by a separate
+ * relayer key). The signature binds `to`=payTo, so a front-runner can only push
+ * the same funds to the same payTo and waste their own gas — no redirect risk.
  */
 
 /** x402 network slug → EVM chain id, for the chains PipRail ships with EIP-3009
@@ -5316,5 +5627,117 @@ declare function encodeXPaymentHeader(input: {
     /** x402 envelope version (Coinbase's reference uses 1). */
     x402Version?: number;
 }): string;
+/**
+ * The minimal EIP-3009 ABI the seller needs: both `transferWithAuthorization`
+ * overloads (the 65-byte `(v,r,s)` form and the `(bytes signature)` ERC-1271 form),
+ * the `authorizationState` replay check, and `name()`/`version()` for the EIP-712
+ * domain. Mirrors Circle's deployed FiatToken.
+ */
+declare const eip3009Abi: readonly [{
+    readonly type: "function";
+    readonly name: "transferWithAuthorization";
+    readonly stateMutability: "nonpayable";
+    readonly outputs: readonly [];
+    readonly inputs: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validAfter";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validBefore";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "v";
+        readonly type: "uint8";
+    }, {
+        readonly name: "r";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "s";
+        readonly type: "bytes32";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "transferWithAuthorization";
+    readonly stateMutability: "nonpayable";
+    readonly outputs: readonly [];
+    readonly inputs: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validAfter";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validBefore";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "signature";
+        readonly type: "bytes";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "authorizationState";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "authorizer";
+        readonly type: "address";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "name";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "string";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "version";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "string";
+    }];
+}];
+/**
+ * Read an EIP-3009 token's true EIP-712 domain `{ name, version }` from the
+ * contract — what a payer must sign over. Returns `null` if the asset is NOT an
+ * EIP-3009 token (no `authorizationState`/`version` — e.g. USDT, native coin, a
+ * plain ERC-20), so the gate refuses to advertise a standard `exact` rail for it.
+ *
+ * The name is NEVER assumed from the symbol: canonical USDC's domain name is
+ * "USD Coin" (not "USDC"), EURC's is "EURC". `eip712Domain()` (EIP-5267) reverts
+ * on these proxies, so we read `name()`+`version()` and probe `authorizationState`
+ * to confirm EIP-3009 support.
+ */
+declare function readExactDomain(publicClient: PublicClient, asset: string): Promise<{
+    name: string;
+    version: string;
+} | null>;
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoverySigner, type DiscoverySource, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, GENERATOR, InsufficientFundsError, InvalidEnvelopeError, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402Challenge, type X402DnsRecord, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, createPaymentGate, encodeXPaymentHeader, evaluatePolicy, normalizeNetwork, parseChallenge, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, toInsufficientFundsError, toInvalidBody };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoverySigner, type DiscoverySource, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, createPaymentGate, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, toInsufficientFundsError, toInvalidBody };