@piprail/sdk 1.15.1 → 1.18.0

package/dist/index.js

@@ -65,7 +65,7 @@ function resolveNetwork(opts) {
 }
 
 // src/drivers/evm/index.ts
-import { BaseError, createPublicClient, erc20Abi as erc20Abi3, getAddress as getAddress3, http as http2, isAddress } from "viem";
+import { BaseError, createPublicClient, erc20Abi as erc20Abi4, getAddress as getAddress4, http as http2, isAddress } from "viem";
 
 // src/drivers/evm/chains.ts
 import { defineChain } from "viem";
@@ -136,9 +136,15 @@ var CHAINS = {
   bnb: {
     chain: bsc,
     tokens: {
-      // Binance-Peg tokens on BNB Chain are 18 decimals (not the usual 6).
+      // Binance-Peg tokens on BNB Chain are 18 decimals (not the usual 6). USDC/USDT here are
+      // Binance-Peg (NOT EIP-3009) → the `exact` rail uses Permit2.
       USDC: { address: "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d", decimals: 18, symbol: "USDC" },
-      USDT: { address: "0x55d398326f99059fF775485246999027B3197955", decimals: 18, symbol: "USDT" }
+      USDT: { address: "0x55d398326f99059fF775485246999027B3197955", decimals: 18, symbol: "USDT" },
+      // FDUSD + USD1 ARE EIP-3009 (transferWithAuthorization) → the `exact` rail uses the gasless,
+      // no-Permit2-approve path. Both hardcode EIP-712 domain version "1" (no version() — the SDK
+      // derives it from DOMAIN_SEPARATOR). Verified on-chain (symbol/decimals/domain match).
+      FDUSD: { address: "0xc5f0f7b66764F6ec8C8Dff7BA683102295E16409", decimals: 18, symbol: "FDUSD" },
+      USD1: { address: "0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d", decimals: 18, symbol: "USD1" }
     }
   },
   avalanche: {
@@ -494,9 +500,12 @@ function sumTransfersTo(logs, asset, payTo) {
 
 // src/drivers/evm/exact.ts
 import {
+  encodeAbiParameters,
   getAddress as getAddress2,
+  keccak256,
   parseSignature,
-  recoverTypedDataAddress
+  recoverTypedDataAddress,
+  toHex
 } from "viem";
 var EXACT_NETWORK_SLUGS = {
   ethereum: 1,
@@ -505,7 +514,17 @@ var EXACT_NETWORK_SLUGS = {
   arbitrum: 42161,
   optimism: 10,
   polygon: 137,
-  avalanche: 43114
+  avalanche: 43114,
+  bnb: 56,
+  bsc: 56,
+  // EIP-3009 USDC verified on-chain (authorizationState present) — gasless, no proxy:
+  sonic: 146,
+  linea: 59144,
+  celo: 42220,
+  unichain: 130,
+  worldchain: 480,
+  sei: 1329,
+  hyperevm: 999
 };
 function chainIdForExactNetwork(slug) {
   return EXACT_NETWORK_SLUGS[slug] ?? null;
@@ -690,10 +709,25 @@ var eip3009Abi = [
     outputs: [{ type: "bool" }]
   },
   { type: "function", name: "name", stateMutability: "view", inputs: [], outputs: [{ type: "string" }] },
-  { type: "function", name: "version", stateMutability: "view", inputs: [], outputs: [{ type: "string" }] }
+  { type: "function", name: "version", stateMutability: "view", inputs: [], outputs: [{ type: "string" }] },
+  // EIP-3009 tokens that DON'T expose version() still expose DOMAIN_SEPARATOR — we match it to
+  // DERIVE the hardcoded domain version (e.g. FDUSD / USD1 on BNB Chain both use "1").
+  { type: "function", name: "DOMAIN_SEPARATOR", stateMutability: "view", inputs: [], outputs: [{ type: "bytes32" }] }
 ];
 var ZERO_ADDR = "0x0000000000000000000000000000000000000000";
 var ZERO_NONCE = `0x${"00".repeat(32)}`;
+var EIP712_DOMAIN_TYPEHASH = keccak256(
+  toHex("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)")
+);
+var EXACT_DOMAIN_VERSION_CANDIDATES = ["1", "2"];
+function eip712DomainSeparator(name, version, chainId, verifyingContract) {
+  return keccak256(
+    encodeAbiParameters(
+      [{ type: "bytes32" }, { type: "bytes32" }, { type: "bytes32" }, { type: "uint256" }, { type: "address" }],
+      [EIP712_DOMAIN_TYPEHASH, keccak256(toHex(name)), keccak256(toHex(version)), BigInt(chainId), verifyingContract]
+    )
+  );
+}
 async function readExactDomain(publicClient, asset) {
   if (asset === "native") return null;
   let token;
@@ -702,12 +736,10 @@ async function readExactDomain(publicClient, asset) {
   } catch {
     return null;
   }
+  let name;
   try {
-    const [name, version] = await Promise.all([
+    const [n] = await Promise.all([
       publicClient.readContract({ address: token, abi: eip3009Abi, functionName: "name" }),
-      publicClient.readContract({ address: token, abi: eip3009Abi, functionName: "version" }),
-      // The EIP-3009 probe: this view exists only on EIP-3009 tokens; it reverts on
-      // a plain ERC-20 / USDT, marking the token as not exact-payable.
       publicClient.readContract({
         address: token,
         abi: eip3009Abi,
@@ -715,11 +747,34 @@ async function readExactDomain(publicClient, asset) {
         args: [ZERO_ADDR, ZERO_NONCE]
       })
     ]);
-    if (typeof name !== "string" || typeof version !== "string" || !name || !version) return null;
-    return { name, version };
+    if (typeof n !== "string" || !n) return null;
+    name = n;
   } catch {
     return null;
   }
+  try {
+    const version = await publicClient.readContract({ address: token, abi: eip3009Abi, functionName: "version" });
+    if (typeof version === "string" && version) return { name, version };
+  } catch {
+  }
+  return deriveExactDomainVersion(publicClient, token, name);
+}
+async function deriveExactDomainVersion(publicClient, token, name) {
+  let onchain;
+  let chainId;
+  try {
+    onchain = await publicClient.readContract({ address: token, abi: eip3009Abi, functionName: "DOMAIN_SEPARATOR" });
+    chainId = publicClient.chain?.id ?? await publicClient.getChainId();
+  } catch {
+    return null;
+  }
+  const target = onchain.toLowerCase();
+  for (const version of EXACT_DOMAIN_VERSION_CANDIDATES) {
+    if (eip712DomainSeparator(name, version, chainId, token).toLowerCase() === target) {
+      return { name, version };
+    }
+  }
+  return null;
 }
 function shorten(msg) {
   const oneLine = msg.replace(/\s+/g, " ").trim();
@@ -874,6 +929,377 @@ async function verifyAndSettleExactEvm(input) {
   };
 }
 
+// src/drivers/evm/permit2.ts
+import {
+  erc20Abi as erc20Abi3,
+  getAddress as getAddress3,
+  maxUint256,
+  recoverTypedDataAddress as recoverTypedDataAddress2
+} from "viem";
+var PERMIT2_ADDRESS = "0x000000000022D473030F116dDEE9F6B43aC78BA3";
+var X402_EXACT_PERMIT2_PROXY = "0x402085c248EeA27D92E8b30b2C58ed07f9E20001";
+var PERMIT2_PROXY_CHAIN_IDS = /* @__PURE__ */ new Set([
+  1,
+  // Ethereum
+  8453,
+  // Base
+  84532,
+  // Base Sepolia
+  42161,
+  // Arbitrum
+  10,
+  // Optimism
+  137,
+  // Polygon
+  43114,
+  // Avalanche
+  56,
+  // BNB
+  42220,
+  // Celo
+  480,
+  // World Chain
+  1329,
+  // Sei
+  999,
+  // HyperEVM
+  143
+  // Monad
+]);
+function isPermit2ProxyChain(chainId) {
+  return PERMIT2_PROXY_CHAIN_IDS.has(chainId);
+}
+var PERMIT2_WITNESS_TYPES = {
+  PermitWitnessTransferFrom: [
+    { name: "permitted", type: "TokenPermissions" },
+    { name: "spender", type: "address" },
+    { name: "nonce", type: "uint256" },
+    { name: "deadline", type: "uint256" },
+    { name: "witness", type: "Witness" }
+  ],
+  TokenPermissions: [
+    { name: "token", type: "address" },
+    { name: "amount", type: "uint256" }
+  ],
+  Witness: [
+    { name: "to", type: "address" },
+    { name: "validAfter", type: "uint256" }
+  ]
+};
+var x402Permit2ProxyAbi = [
+  {
+    type: "function",
+    name: "settle",
+    stateMutability: "nonpayable",
+    outputs: [],
+    inputs: [
+      {
+        name: "permit",
+        type: "tuple",
+        components: [
+          {
+            name: "permitted",
+            type: "tuple",
+            components: [
+              { name: "token", type: "address" },
+              { name: "amount", type: "uint256" }
+            ]
+          },
+          { name: "nonce", type: "uint256" },
+          { name: "deadline", type: "uint256" }
+        ]
+      },
+      { name: "owner", type: "address" },
+      {
+        name: "witness",
+        type: "tuple",
+        components: [
+          { name: "to", type: "address" },
+          { name: "validAfter", type: "uint256" }
+        ]
+      },
+      { name: "signature", type: "bytes" }
+    ]
+  }
+];
+var permit2NonceBitmapAbi = [
+  {
+    type: "function",
+    name: "nonceBitmap",
+    stateMutability: "view",
+    inputs: [
+      { name: "owner", type: "address" },
+      { name: "word", type: "uint256" }
+    ],
+    outputs: [{ type: "uint256" }]
+  }
+];
+function shorten2(msg) {
+  const oneLine = msg.replace(/\s+/g, " ").trim();
+  return oneLine.length > 200 ? `${oneLine.slice(0, 200)}\u2026` : oneLine;
+}
+function randomPermit2Nonce() {
+  const g = globalThis.crypto;
+  if (!g?.getRandomValues) {
+    throw new UnsupportedSchemeError(
+      "this runtime lacks Web Crypto (globalThis.crypto.getRandomValues); the permit2 rail needs a CSPRNG nonce."
+    );
+  }
+  const raw = new Uint8Array(32);
+  g.getRandomValues(raw);
+  return BigInt(`0x${[...raw].map((b) => b.toString(16).padStart(2, "0")).join("")}`);
+}
+async function ensurePermit2Allowance(input) {
+  const { publicClient, walletClient, account, chain, token, amount } = input;
+  let allowance;
+  try {
+    allowance = await publicClient.readContract({
+      address: token,
+      abi: erc20Abi3,
+      functionName: "allowance",
+      args: [account.address, PERMIT2_ADDRESS]
+    });
+  } catch (err) {
+    throw new UnsupportedSchemeError(
+      `permit2: couldn't read the Permit2 allowance for ${token} (${shorten2(err instanceof Error ? err.message : String(err))}).`
+    );
+  }
+  if (allowance >= amount) return void 0;
+  try {
+    const hash = await walletClient.writeContract({
+      account,
+      chain,
+      address: token,
+      abi: erc20Abi3,
+      functionName: "approve",
+      args: [PERMIT2_ADDRESS, maxUint256]
+    });
+    await publicClient.waitForTransactionReceipt({ hash, confirmations: 1 });
+    return hash;
+  } catch (err) {
+    throw toInsufficientFundsError(err) ?? new SettlementError(
+      `permit2: the one-time Permit2 approval for ${token} failed to broadcast (${shorten2(err instanceof Error ? err.message : String(err))}).`,
+      { cause: err }
+    );
+  }
+}
+async function payPermit2Evm(input) {
+  const { publicClient, walletClient, account, chainId, chain, accept } = input;
+  let code;
+  try {
+    code = await publicClient.getCode({ address: account.address });
+  } catch {
+    code = void 0;
+  }
+  if (code && code !== "0x") {
+    throw new UnsupportedSchemeError(
+      `permit2 buyer rail requires an EOA signer; ${account.address} is a contract / EIP-1271 / EIP-7702-delegated account. Pay via onchain-proof.`
+    );
+  }
+  const token = getAddress3(accept.asset);
+  const payTo = getAddress3(accept.payTo);
+  const value = BigInt(accept.amount);
+  const approvalTx = await ensurePermit2Allowance({
+    publicClient,
+    walletClient,
+    account,
+    chain,
+    token,
+    amount: value
+  });
+  const nonce = randomPermit2Nonce();
+  const deadline = BigInt(Math.floor(Date.now() / 1e3) + accept.maxTimeoutSeconds);
+  const validAfter = 0n;
+  const spender = getAddress3(X402_EXACT_PERMIT2_PROXY);
+  const from = account.address;
+  const signature = await walletClient.signTypedData({
+    account,
+    domain: { name: "Permit2", chainId, verifyingContract: PERMIT2_ADDRESS },
+    types: PERMIT2_WITNESS_TYPES,
+    primaryType: "PermitWitnessTransferFrom",
+    message: {
+      permitted: { token, amount: value },
+      spender,
+      nonce,
+      deadline,
+      witness: { to: payTo, validAfter }
+    }
+  });
+  const permit2Authorization = {
+    permitted: { token, amount: value.toString() },
+    from,
+    spender,
+    nonce: nonce.toString(),
+    deadline: deadline.toString(),
+    witness: { to: payTo, validAfter: validAfter.toString() }
+  };
+  return {
+    payload: { signature, permit2Authorization },
+    payerFrom: from,
+    nonce: nonce.toString(),
+    ...approvalTx ? { approvalTx } : {}
+  };
+}
+async function verifyAndSettlePermit2Evm(input) {
+  const { publicClient, walletClient, account, chain, payload, accept } = input;
+  const token = getAddress3(accept.asset);
+  const payTo = getAddress3(accept.payTo);
+  const requiredAmount = BigInt(accept.amount);
+  const proxy = getAddress3(X402_EXACT_PERMIT2_PROXY);
+  let from;
+  let spender;
+  let permittedToken;
+  let witnessTo;
+  let permittedAmount;
+  let nonce;
+  let deadline;
+  let validAfter;
+  const signature = payload.signature;
+  try {
+    const pa = payload.permit2Authorization;
+    from = getAddress3(pa.from);
+    spender = getAddress3(pa.spender);
+    permittedToken = getAddress3(pa.permitted.token);
+    witnessTo = getAddress3(pa.witness.to);
+    permittedAmount = BigInt(pa.permitted.amount);
+    nonce = BigInt(pa.nonce);
+    deadline = BigInt(pa.deadline);
+    validAfter = BigInt(pa.witness.validAfter);
+    if (!/^0x[0-9a-fA-F]+$/.test(signature)) throw new Error("signature must be hex");
+  } catch (err) {
+    return {
+      ok: false,
+      error: "signature_invalid",
+      detail: `Malformed permit2 authorization: ${err instanceof Error ? err.message : String(err)}.`
+    };
+  }
+  if (witnessTo !== payTo) {
+    return { ok: false, error: "wrong_recipient", detail: `Authorization pays witness.to ${witnessTo}, not ${payTo}.` };
+  }
+  if (permittedToken !== token) {
+    return { ok: false, error: "signature_invalid", detail: `Authorization permits token ${permittedToken}, not the rail's ${token}.` };
+  }
+  if (spender !== proxy) {
+    return { ok: false, error: "signature_invalid", detail: `Authorization spender ${spender} is not the x402ExactPermit2Proxy ${proxy}; it can't be settled here.` };
+  }
+  if (permittedAmount < requiredAmount) {
+    return { ok: false, error: "amount_too_low", detail: `Permitted ${permittedAmount}, required ${requiredAmount}.` };
+  }
+  const now = BigInt(Math.floor(Date.now() / 1e3));
+  if (deadline <= now) {
+    return { ok: false, error: "payment_expired", detail: `Permit2 deadline ${deadline} <= now ${now}.` };
+  }
+  let fromCode;
+  try {
+    fromCode = await publicClient.getCode({ address: from });
+  } catch {
+    return { ok: false, error: "tx_not_found", detail: `Could not read code at ${from} (transient RPC) \u2014 retry.` };
+  }
+  if (!(fromCode && fromCode !== "0x")) {
+    let recovered;
+    try {
+      recovered = await recoverTypedDataAddress2({
+        domain: { name: "Permit2", chainId: chain.id, verifyingContract: PERMIT2_ADDRESS },
+        types: PERMIT2_WITNESS_TYPES,
+        primaryType: "PermitWitnessTransferFrom",
+        message: {
+          permitted: { token: permittedToken, amount: permittedAmount },
+          spender,
+          nonce,
+          deadline,
+          witness: { to: witnessTo, validAfter }
+        },
+        signature
+      });
+    } catch (err) {
+      return { ok: false, error: "signature_invalid", detail: `Not a valid EIP-712 signature: ${shorten2(err instanceof Error ? err.message : String(err))}.` };
+    }
+    if (recovered !== from) {
+      return { ok: false, error: "signature_invalid", detail: `Signature recovered to ${recovered}, not the authorizer ${from}.` };
+    }
+  }
+  try {
+    const word = nonce >> 8n;
+    const bit = nonce & 0xffn;
+    const bitmap = await publicClient.readContract({
+      address: PERMIT2_ADDRESS,
+      abi: permit2NonceBitmapAbi,
+      functionName: "nonceBitmap",
+      args: [from, word]
+    });
+    if ((bitmap >> bit & 1n) === 1n) {
+      return { ok: false, error: "tx_already_used", detail: `Permit2 nonce ${nonce} already used or invalidated for ${from}.` };
+    }
+  } catch {
+    return { ok: false, error: "tx_not_found", detail: "Could not read the Permit2 nonce bitmap (transient RPC) \u2014 retry." };
+  }
+  const settleArgs = [
+    { permitted: { token: permittedToken, amount: permittedAmount }, nonce, deadline },
+    from,
+    { to: witnessTo, validAfter },
+    signature
+  ];
+  try {
+    await publicClient.simulateContract({
+      account,
+      address: proxy,
+      abi: x402Permit2ProxyAbi,
+      functionName: "settle",
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      args: settleArgs
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/nonce|invalidated|used/i.test(msg)) return { ok: false, error: "tx_already_used", detail: "Permit2 nonce is used or invalidated." };
+    if (/expired|deadline|too early|not yet/i.test(msg)) return { ok: false, error: "payment_expired", detail: shorten2(msg) };
+    if (/signature/i.test(msg)) return { ok: false, error: "signature_invalid", detail: shorten2(msg) };
+    return { ok: false, error: "tx_reverted", detail: `permit2 settle would revert: ${shorten2(msg)}` };
+  }
+  let txHash;
+  try {
+    txHash = await walletClient.writeContract({
+      account,
+      chain,
+      address: proxy,
+      abi: x402Permit2ProxyAbi,
+      functionName: "settle",
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      args: settleArgs
+    });
+  } catch (err) {
+    throw new SettlementError(
+      `permit2 settle: the merchant relayer failed to broadcast the proxy settle (${shorten2(err instanceof Error ? err.message : String(err))}). The payer's signature is still valid and its nonce unused \u2014 fund/fix the relayer and the payer can retry.`,
+      { cause: err }
+    );
+  }
+  try {
+    const confirmations = accept.extra.minConfirmations ?? 1;
+    const receipt = await publicClient.waitForTransactionReceipt({ hash: txHash, confirmations });
+    if (receipt.status !== "success") {
+      return { ok: false, error: "tx_reverted", detail: `Settlement tx ${txHash} reverted on-chain.` };
+    }
+  } catch (err) {
+    throw new SettlementError(
+      `permit2 settle: broadcast ${txHash} but couldn't confirm it (${shorten2(err instanceof Error ? err.message : String(err))}).`,
+      { cause: err }
+    );
+  }
+  return {
+    ok: true,
+    receipt: {
+      scheme: "exact",
+      success: true,
+      network: accept.network,
+      transaction: txHash,
+      asset: accept.asset,
+      amount: accept.amount,
+      payer: from,
+      payTo: accept.payTo,
+      verifiedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+}
+
 // src/x402.ts
 var HEADER_REQUIRED = "payment-required";
 var HEADER_SIGNATURE = "payment-signature";
@@ -988,23 +1414,38 @@ function parseExactPaymentHeader(value) {
   const payload = v.payload;
   if (!payload || typeof payload !== "object") return null;
   const signature = payload.signature;
-  const authorization = payload.authorization;
-  if (typeof signature !== "string" || !authorization || typeof authorization !== "object") return null;
-  for (const k of ["from", "to", "value", "validAfter", "validBefore", "nonce"]) {
-    if (typeof authorization[k] !== "string") return null;
-  }
+  if (typeof signature !== "string") return null;
   const x402Version = typeof v.x402Version === "number" ? v.x402Version : 2;
   const asset = accepted && typeof accepted.asset === "string" ? accepted.asset : void 0;
-  return {
-    x402Version,
-    network,
-    ...asset ? { asset } : {},
-    payload: {
-      signature,
-      authorization
-    },
-    raw: v
-  };
+  const base2 = { x402Version, network, ...asset ? { asset } : {}, raw: v };
+  const authorization = payload.authorization;
+  if (authorization && typeof authorization === "object") {
+    for (const k of ["from", "to", "value", "validAfter", "validBefore", "nonce"]) {
+      if (typeof authorization[k] !== "string") return null;
+    }
+    return {
+      ...base2,
+      method: "eip3009",
+      payload: { signature, authorization }
+    };
+  }
+  const p2 = payload.permit2Authorization;
+  if (p2 && typeof p2 === "object") {
+    const permitted = p2.permitted;
+    const witness = p2.witness;
+    if (!permitted || typeof permitted !== "object" || !witness || typeof witness !== "object") return null;
+    if (typeof permitted.token !== "string" || typeof permitted.amount !== "string") return null;
+    if (typeof witness.to !== "string" || typeof witness.validAfter !== "string") return null;
+    for (const k of ["from", "spender", "nonce", "deadline"]) {
+      if (typeof p2[k] !== "string") return null;
+    }
+    return {
+      ...base2,
+      method: "permit2",
+      payload: { signature, permit2Authorization: p2 }
+    };
+  }
+  return null;
 }
 function isValidChallenge(value) {
   if (!value || typeof value !== "object") return false;
@@ -1095,12 +1536,12 @@ function makeEvmNetwork(resolved) {
       }
       let normalized;
       try {
-        normalized = getAddress3(asset);
+        normalized = getAddress4(asset);
       } catch {
         return null;
       }
       for (const info of Object.values(resolved.tokens)) {
-        if (getAddress3(info.address) === normalized) {
+        if (getAddress4(info.address) === normalized) {
           return { symbol: info.symbol, decimals: info.decimals };
         }
       }
@@ -1157,12 +1598,13 @@ function makeEvmNetwork(resolved) {
     async estimateCost(accept) {
       const { decimals, symbol } = resolved.chain.nativeCurrency;
       if (accept.scheme === "exact") {
+        const permit2 = accept.extra.assetTransferMethod === "permit2";
         return nativeCost({
           symbol,
           decimals,
           fee: 0n,
           basis: "estimated",
-          detail: "gasless \u2014 the server/facilitator settles the signed authorization"
+          detail: permit2 ? "gasless after a one-time Permit2 approval; the server/facilitator settles the signed authorization" : "gasless \u2014 the server/facilitator settles the signed authorization"
         });
       }
       const gasLimit = accept.asset === "native" ? 21000n : 65000n;
@@ -1193,8 +1635,8 @@ function makeEvmNetwork(resolved) {
       let token = null;
       try {
         token = await publicClient.readContract({
-          address: getAddress3(asset),
-          abi: erc20Abi3,
+          address: getAddress4(asset),
+          abi: erc20Abi4,
           functionName: "balanceOf",
           args: [owner]
         });
@@ -1226,12 +1668,24 @@ function makeEvmNetwork(resolved) {
         minConfirmations: accept.extra.minConfirmations
       });
     },
-    // Standard x402 `exact` rail (EIP-3009), BUYER side — EVM only. Re-derives the
-    // token's EIP-712 domain on-chain, signs an authorization with the agent's own
-    // key, and returns it for the client to frame into PAYMENT-SIGNATURE. Never
-    // broadcasts. Throws UnsupportedSchemeError for a non-EIP-3009 token / contract signer.
+    // Standard x402 `exact` rail, BUYER side — EVM only. Routes on the rail's
+    // `assetTransferMethod`: `permit2` (any ERC-20 — e.g. Binance-Peg USDC on BNB, signs a
+    // Permit2 witness transfer + lazily does the one-time approval) or `eip3009` (re-derives
+    // the token's EIP-712 domain on-chain + signs transferWithAuthorization). Never broadcasts.
+    // Throws UnsupportedSchemeError for a contract signer (or a non-EIP-3009 token on the eip3009 path).
     async payExact(wallet, accept) {
       const a = wallet._native;
+      if (accept.extra.assetTransferMethod === "permit2") {
+        const { payload: payload2, payerFrom: payerFrom2, nonce: nonce2 } = await payPermit2Evm({
+          publicClient,
+          walletClient: a.walletClient,
+          account: a.account,
+          chainId: resolved.chainId,
+          chain: resolved.chain,
+          accept
+        });
+        return { payload: payload2, accepted: accept, payerFrom: payerFrom2, nonce: nonce2 };
+      }
       const { payload, payerFrom, nonce } = await payExactEvm({
         publicClient,
         walletClient: a.walletClient,
@@ -1245,8 +1699,23 @@ function makeEvmNetwork(resolved) {
     async exactDomain(asset) {
       return readExactDomain(publicClient, asset);
     },
+    // Whether the Permit2 transfer method can settle here (proxy deployed). EIP-3009
+    // needs no proxy; this only gates the Permit2 fallback for non-EIP-3009 tokens.
+    exactPermit2Supported() {
+      return isPermit2ProxyChain(resolved.chainId);
+    },
     async settleExactSelf({ relayer, payload, accept }) {
       const a = relayer._native;
+      if ("permit2Authorization" in payload) {
+        return verifyAndSettlePermit2Evm({
+          publicClient,
+          walletClient: a.walletClient,
+          account: a.account,
+          chain: resolved.chain,
+          payload,
+          accept
+        });
+      }
       return verifyAndSettleExactEvm({
         publicClient,
         walletClient: a.walletClient,
@@ -3670,7 +4139,7 @@ function createPaymentGate(options) {
       );
       if (options.exact && !specs.some((s) => s.exact)) {
         throw new Error(
-          "requirePayment: `exact` was requested but none of the offered rails support it. The standard `exact` rail is EVM + EIP-3009 only (USDC / EURC) \u2014 not native coins, not USDT, not non-EVM chains. Offer an EVM EIP-3009 token, or drop `exact`."
+          "requirePayment: `exact` was requested but none of the offered rails support it. The standard `exact` rail is EVM ERC-20 only \u2014 EIP-3009 (USDC / EURC) or Permit2 (any ERC-20, e.g. Binance-Peg USDC on BNB) \u2014 NOT native coins, NOT non-EVM chains. Offer an EVM ERC-20 token, or drop `exact`."
         );
       }
       return specs;
@@ -3683,26 +4152,47 @@ function createPaymentGate(options) {
   }
   async function resolveExactRail(net, asset) {
     const cfg = options.exact;
-    if (net.family !== "evm" || asset === "native" || !net.exactDomain || !net.settleExactSelf) {
+    if (net.family !== "evm" || asset === "native" || !net.settleExactSelf) {
       return void 0;
     }
-    const domain = await net.exactDomain(asset);
-    if (!domain) {
-      throw new Error(
-        `requirePayment: \`exact\` requested for asset ${asset} on ${net.network}, but it isn't an EIP-3009 token (couldn't read name()/version()/authorizationState). The exact rail supports USDC / EURC and other EIP-3009 tokens \u2014 USDT and native coins need onchain-proof. (Or check your rpcUrl is reachable.)`
-      );
+    const want = cfg.method ?? "auto";
+    let method;
+    let domain;
+    if (want === "permit2") {
+      method = "permit2";
+    } else {
+      const d = net.exactDomain ? await net.exactDomain(asset) : null;
+      if (d) {
+        method = "eip3009";
+        domain = d;
+      } else if (want === "eip3009") {
+        throw new Error(
+          `requirePayment: exact \`method: 'eip3009'\` requested for ${asset} on ${net.network}, but it isn't an EIP-3009 token (no name()/version()/authorizationState). Use \`method: 'permit2'\` (any ERC-20, e.g. Binance-Peg USDC on BNB) or \`'auto'\`. (Or check your rpcUrl is reachable.)`
+        );
+      } else {
+        method = "permit2";
+      }
+    }
+    if (method === "permit2" && !(net.exactPermit2Supported?.() ?? false)) {
+      if (cfg.method === "permit2") {
+        throw new Error(
+          `requirePayment: exact \`method: 'permit2'\` needs the x402 Permit2 proxy deployed on ${net.network}, but it isn't there. Offer an EIP-3009 token (gasless, no proxy), or drop \`exact\` on this chain. (See PERMIT2_PROXY_CHAIN_IDS.)`
+        );
+      }
+      return void 0;
     }
     if (cfg.settle === "self") {
       if (cfg.relayer === void 0) {
         throw new Error(
-          "requirePayment: exact `settle: 'self'` needs a `relayer` wallet (the gas-paying key that broadcasts transferWithAuthorization), e.g. exact: { settle: 'self', relayer: { privateKey } }."
+          "requirePayment: exact `settle: 'self'` needs a `relayer` wallet (the gas-paying key that broadcasts the settle), e.g. exact: { settle: 'self', relayer: { privateKey } }."
         );
       }
       const relayer = net.bindWallet(cfg.relayer);
-      return { domain, mode: { kind: "self", relayer } };
+      return { method, ...domain ? { domain } : {}, mode: { kind: "self", relayer } };
     }
     return {
-      domain,
+      method,
+      ...domain ? { domain } : {},
       mode: {
         kind: "facilitator",
         url: cfg.settle.facilitator,
@@ -3746,7 +4236,7 @@ function createPaymentGate(options) {
     };
   }
   function buildExactAccept(s) {
-    const d = s.exact.domain;
+    const rail = s.exact;
     return {
       scheme: "exact",
       network: s.net.network,
@@ -3755,9 +4245,8 @@ function createPaymentGate(options) {
       payTo: s.payTo,
       maxTimeoutSeconds,
       extra: {
-        assetTransferMethod: "eip3009",
-        name: d.name,
-        version: d.version,
+        assetTransferMethod: rail.method,
+        ...rail.domain ? { name: rail.domain.name, version: rail.domain.version } : {},
         minConfirmations,
         decimals: s.decimals,
         amountFormatted: s.amountFormatted,
@@ -3804,13 +4293,44 @@ function createPaymentGate(options) {
     });
     return { kind: "invalid", error: code, detail, challenge: c, requiredHeader, statusCode: 402 };
   }
+  function enrichReceipt(spec, receipt) {
+    let amountFormatted = receipt.amount;
+    try {
+      amountFormatted = formatUnits(BigInt(receipt.amount), spec.decimals);
+    } catch {
+    }
+    return {
+      ...receipt,
+      decimals: spec.decimals,
+      ...spec.symbol ? { symbol: spec.symbol } : {},
+      amountFormatted,
+      idempotencyKey: receipt.transaction
+    };
+  }
+  function reportOnPaidError(error, receipt) {
+    if (!options.onPaidError) return;
+    try {
+      options.onPaidError(error, receipt);
+    } catch {
+    }
+  }
   function fireOnPaid(receipt) {
-    if (options.onPaid) {
-      try {
-        options.onPaid(receipt);
-      } catch {
-      }
+    if (!options.onPaid) return;
+    let outcome;
+    try {
+      outcome = options.onPaid(receipt);
+    } catch (err) {
+      reportOnPaidError(err, receipt);
+      return;
     }
+    if (outcome != null && typeof outcome.then === "function") {
+      return Promise.resolve(outcome).catch((err) => reportOnPaidError(err, receipt));
+    }
+  }
+  async function deliverOnPaid(spec, receipt) {
+    const paid = enrichReceipt(spec, receipt);
+    if (options.awaitOnPaid) await fireOnPaid(paid);
+    else void fireOnPaid(paid);
   }
   async function describe(resourceUrl = "") {
     const specs = await ready();
@@ -3854,7 +4374,7 @@ function createPaymentGate(options) {
       return rejection(result.error, result.detail);
     }
     await settleTx(ref, true);
-    fireOnPaid(result.receipt);
+    await deliverOnPaid(spec, result.receipt);
     return { kind: "paid", receipt: result.receipt, receiptHeader: buildReceiptHeader(result.receipt) };
   }
   async function verifyExact(exact) {
@@ -3877,7 +4397,8 @@ function createPaymentGate(options) {
         `No \`exact\` rail offered for ${exact.network}${exact.asset ? `/${exact.asset}` : ""} (offered: ${exactSpecs.map((s) => `${s.asset}@${s.net.network}`).join(", ")}).`
       );
     }
-    const nonce = exact.payload.authorization.nonce;
+    const auth = "permit2Authorization" in exact.payload ? exact.payload.permit2Authorization : exact.payload.authorization;
+    const nonce = auth.nonce;
     if (await claimTx(nonce)) {
       return rejection("tx_already_used", `Authorization nonce ${nonce} was already redeemed.`);
     }
@@ -3909,7 +4430,7 @@ function createPaymentGate(options) {
             extra: { name: accept.extra.name ?? "", version: accept.extra.version ?? "" }
           },
           receipt: { network: accept.network, asset: accept.asset, payTo: accept.payTo, amount: accept.amount },
-          payerHint: exact.payload.authorization.from
+          payerHint: auth.from
         });
       }
     } catch (err) {
@@ -3921,7 +4442,7 @@ function createPaymentGate(options) {
       return rejection(result.error, result.detail);
     }
     await settleTx(nonce, true);
-    fireOnPaid(result.receipt);
+    await deliverOnPaid(spec, result.receipt);
     return { kind: "paid", receipt: result.receipt, receiptHeader: buildReceiptHeader(result.receipt) };
   }
   async function verify(paymentSignature) {
@@ -3974,6 +4495,110 @@ function normaliseHeader(value) {
   if (Array.isArray(value)) return value[0];
   return value;
 }
+
+// src/receipts.ts
+var DEFAULT_RETRIES = 5;
+var DEFAULT_TIMEOUT_MS = 1e4;
+function defaultBackoff(attempt) {
+  const base2 = Math.min(3e4, 2 ** (attempt - 1) * 500);
+  return Math.round(base2 * (0.5 + Math.random()));
+}
+function isRetryableStatus(status) {
+  return status === 408 || status === 429 || status >= 500;
+}
+var sleep = (ms) => ms > 0 ? new Promise((resolve) => setTimeout(resolve, ms)) : Promise.resolve();
+async function signBody(secret, body) {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) return null;
+  try {
+    const enc = new TextEncoder();
+    const key = await subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, [
+      "sign"
+    ]);
+    const sig = await subtle.sign("HMAC", key, enc.encode(body));
+    const hex = Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
+    return `sha256=${hex}`;
+  } catch {
+    return null;
+  }
+}
+async function deliverReceipt(receipt, options) {
+  const {
+    url,
+    secret,
+    retries = DEFAULT_RETRIES,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    headers = {},
+    signatureHeader = "piprail-signature",
+    idempotencyHeader = "idempotency-key",
+    backoff = defaultBackoff,
+    fetchImpl = globalThis.fetch,
+    onAttempt
+  } = options;
+  if (typeof fetchImpl !== "function") {
+    return { delivered: false, attempts: 0, error: "no fetch implementation available" };
+  }
+  const body = JSON.stringify(receipt);
+  const signature = secret ? await signBody(secret, body) : null;
+  const baseHeaders = {
+    ...headers,
+    "content-type": "application/json",
+    [idempotencyHeader]: receipt.idempotencyKey,
+    ...signature ? { [signatureHeader]: signature } : {}
+  };
+  const maxAttempts = Math.max(1, retries + 1);
+  let lastStatus;
+  let lastError;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let ok = false;
+    let status;
+    let error;
+    try {
+      const res = await fetchImpl(url, {
+        method: "POST",
+        headers: baseHeaders,
+        body,
+        signal: controller.signal
+      });
+      status = res.status;
+      lastStatus = status;
+      ok = res.ok;
+      if (!ok) {
+        error = `HTTP ${status}`;
+        lastError = error;
+      }
+    } catch (err) {
+      error = err instanceof Error ? err.message : String(err);
+      lastError = error;
+    } finally {
+      clearTimeout(timer);
+    }
+    const retryable = status === void 0 ? true : isRetryableStatus(status);
+    const willRetry = !ok && retryable && attempt < maxAttempts;
+    try {
+      onAttempt?.({ attempt, ok, ...status !== void 0 ? { status } : {}, ...error ? { error } : {}, willRetry });
+    } catch {
+    }
+    if (ok) return { delivered: true, attempts: attempt, status };
+    if (!willRetry) {
+      return {
+        delivered: false,
+        attempts: attempt,
+        ...lastStatus !== void 0 ? { status: lastStatus } : {},
+        ...lastError ? { error: lastError } : {}
+      };
+    }
+    await sleep(backoff(attempt));
+  }
+  return {
+    delivered: false,
+    attempts: maxAttempts,
+    ...lastStatus !== void 0 ? { status: lastStatus } : {},
+    ...lastError ? { error: lastError } : {}
+  };
+}
 export {
   CHAINS,
   ConfirmationTimeoutError,
@@ -3992,6 +4617,9 @@ export {
   MissingDriverError,
   NoCompatibleAcceptError,
   NonReplayableBodyError,
+  PERMIT2_ADDRESS,
+  PERMIT2_PROXY_CHAIN_IDS,
+  PERMIT2_WITNESS_TYPES,
   PIPRAIL_AGENT_GUIDE,
   PaymentDeclinedError,
   PaymentTimeoutError,
@@ -4004,6 +4632,7 @@ export {
   UnsupportedSchemeError,
   WrongChainError,
   WrongFamilyError,
+  X402_EXACT_PERMIT2_PROXY,
   agentGuide,
   buildBazaarExtension,
   buildChallengeHeader,
@@ -4019,12 +4648,14 @@ export {
   classifyChallenge,
   createPaymentGate,
   decorateOutcome,
+  deliverReceipt,
   eip3009Abi,
   encodeXPaymentHeader,
   evaluatePolicy,
   explainDecline,
   formatSpendReport,
   getDirectoryInfo,
+  isPermit2ProxyChain,
   normalizeNetwork,
   parseChallenge,
   parseExactPaymentHeader,