@piprail/sdk 1.15.1 → 1.18.0

package/dist/index.d.ts

@@ -82,8 +82,12 @@ interface X402ExactAcceptEntry {
     payTo: AddressId;
     maxTimeoutSeconds: number;
     extra: {
-        /** The exact-EVM transfer method. PipRail self-settles EIP-3009 today. */
-        assetTransferMethod: 'eip3009';
+        /** The exact-EVM transfer method, per the x402 `exact` EVM scheme: `'eip3009'`
+         *  for tokens with native `transferWithAuthorization`, or `'permit2'` for tokens
+         *  WITHOUT it (e.g. Binance-Peg USDC on BNB) — the payer signs a Permit2 witness
+         *  transfer whose `spender` is the canonical x402ExactPermit2Proxy and whose
+         *  `witness.to` binds the recipient. PipRail self-settles BOTH. */
+        assetTransferMethod: 'eip3009' | 'permit2';
         /** EIP-712 domain name of the token. OPTIONAL per the exact-EVM scheme (only
          *  `assetTransferMethod` is required) — a foreign rail may omit it. NEVER assumed
          *  from the symbol (USDC's on-chain name() is "USD Coin", not "USDC"); a PipRail gate
@@ -154,22 +158,65 @@ interface ExactPaymentPayload {
     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.
+ * The `permit2Authorization` a payer signs for the `permit2` variant of the x402
+ * `exact` EVM scheme (tokens without EIP-3009 — e.g. Binance-Peg USDC on BNB). It is
+ * an EIP-712 `PermitWitnessTransferFrom` over the canonical Permit2 contract, whose
+ * `spender` is the canonical **x402ExactPermit2Proxy** and whose **witness** binds the
+ * recipient (`to`) + an activation time (`validAfter`). All numeric fields are DECIMAL
+ * strings on the wire (`permitted.amount`, `nonce`, `deadline`, `witness.validAfter`).
  */
-interface ParsedExactPayment {
+interface Permit2Authorization {
+    /** What may be pulled: the ERC-20 token + the exact base-unit amount. */
+    permitted: {
+        token: string;
+        amount: string;
+    };
+    /** The payer (token owner). */
+    from: string;
+    /** The signature's allowed spender — the canonical x402ExactPermit2Proxy. */
+    spender: string;
+    /** Permit2 unordered nonce (a uint256, decimal string). Single-use via its bitmap. */
+    nonce: string;
+    /** Unix-seconds signature expiry. */
+    deadline: string;
+    /** The proxy-enforced witness: funds go ONLY to `to`, and not before `validAfter`. */
+    witness: {
+        to: string;
+        validAfter: string;
+    };
+}
+/** The `payload` a client sends for the `permit2` exact variant: a signature + its Permit2 authorization. */
+interface Permit2PaymentPayload {
+    signature: string;
+    permit2Authorization: Permit2Authorization;
+}
+/** Either `exact`-rail payload shape — EIP-3009 (`authorization`) or Permit2 (`permit2Authorization`). */
+type ExactPaymentPayloadAny = ExactPaymentPayload | Permit2PaymentPayload;
+interface ParsedExactBase {
     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>;
 }
+/**
+ * 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. A discriminated union on
+ * `method`, so narrowing on `method` narrows `payload`: `'eip3009'` → {@link ExactPaymentPayload}
+ * (`authorization`), `'permit2'` → {@link Permit2PaymentPayload} (`permit2Authorization`).
+ */
+type ParsedExactPayment = (ParsedExactBase & {
+    method: 'eip3009';
+    payload: ExactPaymentPayload;
+}) | (ParsedExactBase & {
+    method: 'permit2';
+    payload: Permit2PaymentPayload;
+});
 interface X402Receipt {
     scheme: 'onchain-proof' | 'exact';
     /**
@@ -192,6 +239,37 @@ interface X402Receipt {
     payTo: AddressId;
     verifiedAt: string;
 }
+/**
+ * The settled-payment record handed to a gate's `onPaid` hook — the wire
+ * {@link X402Receipt} plus the merchant-facing extras the gate already computed
+ * for the challenge, so a receipt handler never needs a second lookup to display
+ * or reconcile it: the token's `decimals`/`symbol`, the human `amountFormatted`
+ * (derived from the SETTLED base-unit `amount`, not the requested price), and a
+ * stable `idempotencyKey`.
+ *
+ * **Delivery contract — read this before persisting receipts.** `onPaid` is
+ * **at-least-once**: with a single in-memory replay store it fires exactly once
+ * per proof, but across instances sharing a custom `isUsed`/`markUsed` store two
+ * nodes can settle the same proof in a race and each fire once. Always **dedupe on
+ * `idempotencyKey`** (a unique index / upsert). It is also fire-and-forget by
+ * default — the gate does not block the response on it and a process crash between
+ * settlement and your side-effect drops that receipt. For durability either set
+ * `awaitOnPaid` (record before the 200) or push to a durable queue inside the hook;
+ * for a webhook, use {@link deliverReceipt} (signed, retried, idempotent).
+ */
+interface PaidReceipt extends X402Receipt {
+    /** The token's on-chain decimals — pairs with `amount` so you can format without a lookup. */
+    decimals: number;
+    /** The token symbol when the gate knows it (e.g. `USDC`, `FDUSD`). */
+    symbol?: string;
+    /** Human-readable settled amount, e.g. `"0.05"` — `amount` / 10**`decimals`. */
+    amountFormatted: string;
+    /**
+     * A stable, unique key for this settlement (the settled `transaction` id). `onPaid`
+     * is at-least-once across instances — dedupe persistence and webhook delivery on this.
+     */
+    idempotencyKey: string;
+}
 /**
  * Why a verification failed — a closed, chain-agnostic vocabulary. Every code a
  * driver returns is in this union; a client/agent branches on it rather than
@@ -236,7 +314,7 @@ declare function buildSignatureHeader(signature: X402PaymentSignature): string;
  */
 declare function buildExactSignatureHeader(input: {
     accepted: X402ExactAcceptEntry;
-    payload: ExactPaymentPayload;
+    payload: ExactPaymentPayloadAny;
 }): string;
 /**
  * Parse the PAYMENT-REQUIRED challenge from a 402 response. Prefers the
@@ -610,7 +688,7 @@ declare const CHAINS: {
                         value: bigint;
                         yParity: number;
                         accessList: viem.AccessList;
-                        authorizationList? /** EVM chain id, e.g. 5000 for Mantle. */: undefined | undefined;
+                        authorizationList?: undefined | undefined;
                         blobVersionedHashes?: undefined | undefined;
                         chainId: number;
                         type: "eip1559";
@@ -619,7 +697,7 @@ declare const CHAINS: {
                         maxFeePerGas: bigint;
                         maxPriorityFeePerGas: bigint;
                         isSystemTx?: undefined | undefined;
-                        mint? /** Known tokens on this chain (empty for unknown custom chains). */: undefined | undefined;
+                        mint?: undefined | undefined;
                         sourceHash?: undefined | undefined;
                     } | {
                         blockHash: `0x${string}` | null;
@@ -1019,11 +1097,13 @@ declare const CHAINS: {
                         maxPriorityFeePerGas: bigint;
                         isSystemTx?: undefined | undefined;
                         mint?: undefined | undefined;
-                        sourceHash? /** Known tokens on this chain (empty for unknown custom chains). */: undefined | undefined;
+                        sourceHash?: undefined | undefined;
                     } | {
                         blockHash: `0x${string}` | null;
                         blockNumber: bigint | null;
-                        blockTimestamp?: bigint | undefined;
+                        blockTimestamp
+                        /** EVM chain id, e.g. 5000 for Mantle. */
+                        ? /** EVM chain id, e.g. 5000 for Mantle. */: bigint | undefined;
                         from: abitype.Address;
                         gas: bigint;
                         hash: viem.Hash;
@@ -1257,6 +1337,16 @@ declare const CHAINS: {
                 decimals: number;
                 symbol: string;
             };
+            FDUSD: {
+                address: "0xc5f0f7b66764F6ec8C8Dff7BA683102295E16409";
+                decimals: number;
+                symbol: string;
+            };
+            USD1: {
+                address: "0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d";
+                decimals: number;
+                symbol: string;
+            };
         };
     };
     avalanche: {
@@ -2725,7 +2815,9 @@ declare const CHAINS: {
                         chainId: number;
                         type: "eip7702";
                         gasPrice?: undefined | undefined;
-                        maxFeePerBlobGas?: undefined | undefined;
+                        maxFeePerBlobGas
+                        /** JSON-RPC endpoint. */
+                        ? /** JSON-RPC endpoint. */: undefined | undefined;
                         maxFeePerGas: bigint;
                         maxPriorityFeePerGas: bigint;
                         l1BatchNumber: bigint | null;
@@ -4230,7 +4322,7 @@ interface ResolvedNetwork {
      * and the nonce (for the client's spend record + a re-present-the-same-auth retry).
      */
     payExact?(wallet: WalletHandle, accept: X402ExactAcceptEntry): Promise<{
-        payload: ExactPaymentPayload;
+        payload: ExactPaymentPayloadAny;
         accepted: X402ExactAcceptEntry;
         payerFrom: string;
         nonce: string;
@@ -4265,6 +4357,15 @@ interface ResolvedNetwork {
         name: string;
         version: string;
     } | null>;
+    /**
+     * OPTIONAL (EVM-only) — whether this chain can carry the **Permit2** transfer method
+     * of the `exact` scheme: i.e. the canonical Permit2 **and** the `x402ExactPermit2Proxy`
+     * are deployed here. The gate calls it to AVOID advertising a Permit2 `exact` rail it
+     * could never settle (a non-EIP-3009 token on a proxy-less chain — e.g. Binance-Peg
+     * USDC on a chain without the proxy). EIP-3009 needs no proxy, so this gates ONLY the
+     * Permit2 fallback. Omitted (or `false`) ⇒ treat Permit2 as unavailable on this chain.
+     */
+    exactPermit2Supported?(): boolean;
     /**
      * OPTIONAL (EVM-only today) — verify a standard x402 `exact` (EIP-3009) payment
      * locally, then SELF-SETTLE it by broadcasting `transferWithAuthorization` from the
@@ -4280,7 +4381,7 @@ interface ResolvedNetwork {
      */
     settleExactSelf?(input: {
         relayer: WalletHandle;
-        payload: ExactPaymentPayload;
+        payload: ExactPaymentPayloadAny;
         accept: X402ExactAcceptEntry;
     }): Promise<VerifyResult>;
 }
@@ -5627,16 +5728,18 @@ interface AcceptOption {
     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).
+ * Opt into ALSO advertising a standard x402 `exact` rail beside the default
+ * `onchain-proof` rail, so ANY standard x402 client can pay this gate (dual-advertise).
+ * EVM ERC-20 only — **EIP-3009** (USDC, EURC) or, for tokens without it, **Permit2**
+ * (any ERC-20 — e.g. Binance-Peg USDC on BNB, settled via the canonical
+ * x402ExactPermit2Proxy). NOT native coins, NOT non-EVM chains. 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: 'self'`  — your own `relayer` key broadcasts the settle (EIP-3009's
+ *     `transferWithAuthorization`, or the proxy's `settle` for Permit2). You pay gas to
+ *     RECEIVE (the inverse of onchain-proof) and keep the relayer funded. The signature
+ *     binds the recipient, so there's no redirect risk. 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.
@@ -5649,6 +5752,10 @@ interface ExactRailOption {
     /** 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;
+    /** Which exact-EVM transfer method to advertise. `'auto'` (default) uses EIP-3009 when the
+     *  token supports it, else Permit2 — so a non-EIP-3009 token like Binance-Peg USDC on BNB
+     *  "just works". Force `'eip3009'` or `'permit2'` to pin one. */
+    method?: 'eip3009' | 'permit2' | 'auto';
 }
 interface RequirePaymentOptions {
     /**
@@ -5696,8 +5803,28 @@ interface RequirePaymentOptions {
     isUsed?: (ref: string) => boolean | Promise<boolean>;
     /** Replay hook — record a redeemed proof. */
     markUsed?: (ref: string) => void | Promise<void>;
-    /** Fired when a payment verifies successfully. */
-    onPaid?: (receipt: X402Receipt) => void;
+    /**
+     * Fired when a payment verifies successfully, with the enriched {@link PaidReceipt}.
+     * May be **sync or async** — a throw OR a rejected promise is isolated (routed to
+     * `onPaidError`), so the hook can never break the request or crash the process.
+     * Fire-and-forget by default (the response is not blocked on it); set `awaitOnPaid`
+     * to record the receipt before the resource is served. `onPaid` is **at-least-once**
+     * across instances — dedupe on `receipt.idempotencyKey`. See {@link PaidReceipt}.
+     */
+    onPaid?: (receipt: PaidReceipt) => void | Promise<void>;
+    /**
+     * Observe a failure inside `onPaid` (sync throw or async rejection). Without it,
+     * a failing receipt hook is swallowed silently — set this to log/alert/queue the
+     * dropped receipt. Its own throws are also swallowed (it can never break a request).
+     */
+    onPaidError?: (error: unknown, receipt: PaidReceipt) => void;
+    /**
+     * Await `onPaid` before returning the paid result (and thus before the gated
+     * resource is served), so "receipt recorded" is guaranteed on the happy path.
+     * Default `false` (fire-and-forget — lower latency). A rejection is still isolated
+     * via `onPaidError`; it never turns a settled payment into a 402.
+     */
+    awaitOnPaid?: boolean;
     /**
      * 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}.
@@ -5867,6 +5994,85 @@ interface SettleViaFacilitatorInput extends FacilitatorConfig {
  */
 declare function settleViaFacilitator(input: SettleViaFacilitatorInput): Promise<VerifyResult>;
 
+/**
+ * Reliable receipt delivery — the durable webhook a stateless gate can't be.
+ *
+ * `deliverReceipt(receipt, { url, secret })` POSTs a settled {@link PaidReceipt} to
+ * YOUR OWN endpoint, with retries + exponential backoff, an HMAC-SHA256 signature,
+ * and an idempotency key. It is the recommended body of an `onPaid` hook when you
+ * want at-least-once delivery to a webhook instead of a fire-and-forget callback:
+ *
+ *   createPaymentGate({
+ *     chain, token, amount, payTo,
+ *     awaitOnPaid: true,                                  // record before serving
+ *     onPaid: (r) => deliverReceipt(r, {
+ *       url: process.env.RECEIPTS_WEBHOOK,
+ *       secret: process.env.RECEIPTS_SECRET,              // signs the body
+ *     }),
+ *   })
+ *
+ * Charter note: PipRail hosts nothing — `url` is **your** endpoint. This is a pure
+ * transport primitive (no chain libraries), isomorphic (global `fetch` + Web Crypto),
+ * and it **never throws**: failures come back as `{ delivered: false, … }`, because a
+ * delivery helper that threw would reintroduce the very crash `onPaid` isolation
+ * prevents. The receiver verifies the signature and dedupes on the idempotency key.
+ */
+
+interface DeliverReceiptOptions {
+    /** Your receiving endpoint. PipRail hosts nothing — this is your server. */
+    url: string;
+    /**
+     * Shared secret. When set, the raw JSON body is signed HMAC-SHA256 and sent as
+     * `<signatureHeader>: sha256=<hex>` so the receiver can verify authenticity.
+     */
+    secret?: string;
+    /** Extra retry attempts after the first send (default 5 → up to 6 POSTs total). */
+    retries?: number;
+    /** Per-attempt timeout in ms (default 10000). An attempt that exceeds it is aborted + retried. */
+    timeoutMs?: number;
+    /** Extra request headers (merged; never override the signature/idempotency headers). */
+    headers?: Record<string, string>;
+    /** Header carrying the signature. Default `piprail-signature`. */
+    signatureHeader?: string;
+    /** Header carrying the dedupe key (= `receipt.idempotencyKey`). Default `idempotency-key`. */
+    idempotencyHeader?: string;
+    /** Backoff before retry N (1-based) in ms. Default jittered exponential (cap 30s). */
+    backoff?: (attempt: number) => number;
+    /** Injected `fetch` (tests / non-global-fetch runtimes). Defaults to the global. */
+    fetchImpl?: typeof fetch;
+    /** Observe each attempt (logging/metrics). Its own throws are ignored. */
+    onAttempt?: (info: DeliverAttempt) => void;
+}
+/** One delivery attempt's outcome (passed to `onAttempt`). */
+interface DeliverAttempt {
+    /** 1-based attempt number. */
+    attempt: number;
+    /** Did the endpoint return a 2xx? */
+    ok: boolean;
+    /** HTTP status, when a response was received. */
+    status?: number;
+    /** Transport/abort error message, when no response was received. */
+    error?: string;
+    /** Will another attempt follow? */
+    willRetry: boolean;
+}
+/** The terminal result of `deliverReceipt` — it never throws, so always inspect this. */
+interface DeliverResult {
+    /** True iff the endpoint returned a 2xx within the attempt budget. */
+    delivered: boolean;
+    /** Total POSTs made (1 + retries used). */
+    attempts: number;
+    /** Final HTTP status, when the last attempt got a response. */
+    status?: number;
+    /** Final error, when delivery failed (last transport error or a non-2xx summary). */
+    error?: string;
+}
+/**
+ * POST a settled receipt to your endpoint with retries, a timeout, an HMAC signature,
+ * and an idempotency key. Never throws — returns a {@link DeliverResult}.
+ */
+declare function deliverReceipt(receipt: PaidReceipt, options: DeliverReceiptOptions): Promise<DeliverResult>;
+
 /**
  * The driver registry — the ONLY place the families meet. Routing decides a
  * family from the `chain` value (synchronously), then asks that family's
@@ -6157,8 +6363,13 @@ declare class UnsupportedNetworkError extends PipRailError {
  * 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
- *  USDC. Extend as needed; an unknown slug just won't be selected. */
+/** x402 network slug → EVM chain id, for the chains PipRail ships an exact-payable
+ *  stablecoin on — EIP-3009 USDC/EURC on most, and **Permit2** on BNB (Binance-Peg
+ *  USDC isn't EIP-3009). This is a public REFERENCE/helper, NOT the runtime gate: the
+ *  gate offers `exact` on ANY EVM chain whose token is EIP-3009 (detected live via
+ *  `exactDomain`) or whose chain has the Permit2 proxy — so keep this list in sync with
+ *  what we've VERIFIED, but the rail isn't limited to it. An unknown slug → `null`.
+ *  (Matching uses CAIP-2 via `net.supports`.) */
 declare const EXACT_NETWORK_SLUGS: Readonly<Record<string, number>>;
 /** Resolve an x402 `exact` network slug (e.g. "base") to its EVM chain id. */
 declare function chainIdForExactNetwork(slug: string): number | null;
@@ -6359,22 +6570,119 @@ declare const eip3009Abi: readonly [{
     readonly outputs: readonly [{
         readonly type: "string";
     }];
+}, {
+    readonly type: "function";
+    readonly name: "DOMAIN_SEPARATOR";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "bytes32";
+    }];
 }];
 /**
- * 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.
+ * 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` — e.g. USDT, native coin, a plain ERC-20), so the caller falls back to
+ * permit2 / onchain-proof.
  *
- * The name is NEVER assumed from the symbol: canonical USDC's domain name is
- * "USD Coin" (not "USDC"), and EURC's is "Euro Coin" on Ethereum/Avalanche but "EURC"
- * on Base — proof that only the on-chain read is authoritative. `eip712Domain()`
- * (EIP-5267) reverts on these proxies, so we read `name()`+`version()` and probe
- * `authorizationState` to confirm EIP-3009 support.
+ * The name is NEVER assumed from the symbol: canonical USDC's domain name is "USD Coin" (not
+ * "USDC"), and EURC's is "Euro Coin" on Ethereum/Avalanche but "EURC" on Base — only the on-chain
+ * read is authoritative.
+ *
+ * The version comes from `version()` when the token exposes it (canonical FiatToken — USDC is
+ * "2"). Many EIP-3009 tokens HARDCODE the domain version and DON'T expose `version()` — e.g.
+ * **FDUSD and USD1 on BNB Chain** (both "1"). For those we DERIVE the version by matching the
+ * token's on-chain `DOMAIN_SEPARATOR()` against the standard 4-field domain for a small set of
+ * common versions; a token with a non-standard / salted domain returns `null` (→ permit2 fallback).
  */
 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 BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, 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 ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PIPRAIL_AGENT_GUIDE, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, 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, agentGuide, buildBazaarExtension, buildChallengeHeader, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, formatSpendReport, getDirectoryInfo, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };
+/**
+ * ── EVM SECTION: x402 `exact` scheme, `permit2` variant — BUYER + SELLER ──────
+ *
+ * The companion to `exact.ts` for ERC-20 tokens that do NOT implement EIP-3009
+ * `transferWithAuthorization` — most notably **Binance-Peg USDC/USDT on BNB Chain**
+ * (no native Circle USDC exists on BNB). The x402 `exact` EVM scheme defines a second
+ * `assetTransferMethod`, `"permit2"`, for exactly these tokens:
+ *
+ *   • The payer signs an EIP-712 **`PermitWitnessTransferFrom`** over the canonical
+ *     **Permit2** contract, with `spender` = the canonical **x402ExactPermit2Proxy**
+ *     and a **witness** that binds the recipient (`to`) + an activation time
+ *     (`validAfter`). The buyer never broadcasts (and, after a one-time Permit2 approval,
+ *     spends ~0 gas) — the merchant/facilitator broadcasts.
+ *   • The merchant/facilitator settles by calling the **proxy's `settle(...)`**, which
+ *     calls `Permit2.permitWitnessTransferFrom`. Because the signed `spender` is the
+ *     proxy and the proxy forces `transferDetails.to == witness.to`, a relayer can only
+ *     push the signed funds to the signed recipient — no redirect risk (same guarantee
+ *     EIP-3009's `to`-binding gives us).
+ *
+ * Spec: github.com/coinbase/x402 `specs/schemes/exact/scheme_exact_evm.md` (the Permit2
+ * method). Both contracts are canonical CREATE2 deployments (same address every EVM
+ * chain) and are verified deployed on BNB. This module mirrors `exact.ts` file-for-file
+ * (buyer {@link payPermit2Evm}; seller {@link verifyAndSettlePermit2Evm}); the EVM
+ * driver routes to it on `accept.extra.assetTransferMethod === 'permit2'`.
+ *
+ * One-time setup: the payer must `approve(Permit2, max)` on the token ONCE
+ * ({@link ensurePermit2Allowance} does this lazily) — after that, every payment is a
+ * gasless signature. This is the only way `permit2` differs operationally from EIP-3009.
+ */
+
+/** Canonical Permit2 (Uniswap), same address on every EVM chain incl. BNB. */
+declare const PERMIT2_ADDRESS: "0x000000000022D473030F116dDEE9F6B43aC78BA3";
+/** Canonical x402ExactPermit2Proxy — the SAME CREATE2 address on every chain where it's been
+ *  deployed (see {@link PERMIT2_PROXY_CHAIN_IDS}; it is NOT on every EVM chain). It is the
+ *  `spender` the buyer signs over, and the contract the seller settles through; it enforces
+ *  `transferDetails.to == witness.to`, so funds can only reach the signed payTo. */
+declare const X402_EXACT_PERMIT2_PROXY: "0x402085c248EeA27D92E8b30b2C58ed07f9E20001";
+/** EVM chain ids where BOTH the canonical Permit2 AND the x402ExactPermit2Proxy are deployed —
+ *  i.e. where the **Permit2** transfer method of `exact` can actually settle. Verified on-chain
+ *  (`eth_getCode`, 2026-06-11). EIP-3009 needs NO proxy, so this gates only the Permit2 fallback;
+ *  on a non-EIP-3009 token on a chain absent here, the gate offers `onchain-proof` only rather
+ *  than an unsettleable Permit2 rail. The proxy is a permissionless CREATE2 deploy, so extend
+ *  this as it lands on more chains (re-verify before adding). */
+declare const PERMIT2_PROXY_CHAIN_IDS: ReadonlySet<number>;
+/** Whether a chain has the x402 Permit2 proxy deployed (→ can settle the Permit2 exact method). */
+declare function isPermit2ProxyChain(chainId: number): boolean;
+/**
+ * EIP-712 type set for the x402 `permit2` exact method. MUST encode to exactly the type
+ * string Permit2 reconstructs for `permitWitnessTransferFrom`:
+ *   `PermitWitnessTransferFrom(TokenPermissions permitted,address spender,uint256 nonce,uint256 deadline,Witness witness)TokenPermissions(address token,uint256 amount)Witness(address to,uint256 validAfter)`
+ * (viem orders referenced structs alphabetically → TokenPermissions before Witness ✓.)
+ */
+declare const PERMIT2_WITNESS_TYPES: {
+    readonly PermitWitnessTransferFrom: readonly [{
+        readonly name: "permitted";
+        readonly type: "TokenPermissions";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly name: "nonce";
+        readonly type: "uint256";
+    }, {
+        readonly name: "deadline";
+        readonly type: "uint256";
+    }, {
+        readonly name: "witness";
+        readonly type: "Witness";
+    }];
+    readonly TokenPermissions: readonly [{
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly Witness: readonly [{
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "validAfter";
+        readonly type: "uint256";
+    }];
+};
+
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactPaymentPayloadAny, 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 ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type Permit2Authorization, type Permit2PaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, 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, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, buildBazaarExtension, buildChallengeHeader, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };