@piprail/sdk 1.13.1 → 1.14.0

package/dist/index.js

@@ -13,6 +13,7 @@ import {
   SettlementError,
   UnknownTokenError,
   UnsupportedNetworkError,
+  UnsupportedSchemeError,
   WrongChainError,
   WrongFamilyError,
   floorUnits,
@@ -21,7 +22,7 @@ import {
   parseUnits,
   rejectForeignToken,
   toInsufficientFundsError
-} from "./chunk-SVMGHASK.js";
+} from "./chunk-H3A4KWLJ.js";
 
 // src/drivers/registry.ts
 var byFamily = /* @__PURE__ */ new Map();
@@ -97,13 +98,18 @@ var CHAINS = {
     defaultRpc: "https://ethereum-rpc.publicnode.com",
     tokens: {
       USDC: { address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", decimals: 6, symbol: "USDC" },
-      USDT: { address: "0xdAC17F958D2ee523a2206206994597C13D831ec7", decimals: 6, symbol: "USDT" }
+      USDT: { address: "0xdAC17F958D2ee523a2206206994597C13D831ec7", decimals: 6, symbol: "USDT" },
+      // Circle EURC — EIP-3009 (exact-payable). On-chain EIP-712 domain name is "Euro Coin" here
+      // (NOT "EURC"); the buyer re-derives it on-chain, so the symbol below is display-only.
+      EURC: { address: "0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c", decimals: 6, symbol: "EURC" }
     }
   },
   base: {
     chain: base,
     tokens: {
-      USDC: { address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", decimals: 6, symbol: "USDC" }
+      USDC: { address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", decimals: 6, symbol: "USDC" },
+      // Circle EURC — EIP-3009 (exact-payable). On-chain EIP-712 domain name is "EURC" here.
+      EURC: { address: "0x60a3E35Cc302bFA44Cb288Bc5a4F316Fdb1adb42", decimals: 6, symbol: "EURC" }
     }
   },
   arbitrum: {
@@ -139,7 +145,9 @@ var CHAINS = {
     chain: avalanche,
     tokens: {
       USDC: { address: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E", decimals: 6, symbol: "USDC" },
-      USDT: { address: "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7", decimals: 6, symbol: "USDT" }
+      USDT: { address: "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7", decimals: 6, symbol: "USDT" },
+      // Circle EURC — EIP-3009 (exact-payable). On-chain EIP-712 domain name is "Euro Coin" here.
+      EURC: { address: "0xC891EB4cbdEFf6e073e859e987815Ed1505c2ACD", decimals: 6, symbol: "EURC" }
     }
   },
   // ── More popular EVM mainnets. Every address below was verified on-chain
@@ -591,6 +599,53 @@ function encodeXPaymentHeader(input) {
   };
   return base64(JSON.stringify(payload));
 }
+async function payExactEvm(input) {
+  const { publicClient, walletClient, account, chainId, accept } = input;
+  let code;
+  try {
+    code = await publicClient.getCode({ address: account.address });
+  } catch {
+    code = void 0;
+  }
+  if (code && code !== "0x") {
+    throw new UnsupportedSchemeError(
+      `exact buyer rail requires an EOA signer; ${account.address} is a contract / EIP-1271 / EIP-7702-delegated account (no recoverable ECDSA signature). Pay via onchain-proof.`
+    );
+  }
+  const domain = await readExactDomain(publicClient, accept.asset);
+  if (!domain) {
+    throw new UnsupportedSchemeError(
+      `exact: ${accept.asset} on ${accept.network} isn't an EIP-3009 token (USDT needs Permit2; native coin and plain ERC-20s aren't exact-payable). Pay via onchain-proof.`
+    );
+  }
+  const g = globalThis.crypto;
+  if (!g?.getRandomValues) {
+    throw new UnsupportedSchemeError(
+      "this runtime lacks Web Crypto (globalThis.crypto.getRandomValues); the exact rail needs a CSPRNG nonce."
+    );
+  }
+  const raw = new Uint8Array(32);
+  g.getRandomValues(raw);
+  const nonce = `0x${[...raw].map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+  const now = Math.floor(Date.now() / 1e3);
+  const from = account.address;
+  const to = getAddress2(accept.payTo);
+  const value = accept.amount;
+  const validAfter = "0";
+  const validBefore = String(now + accept.maxTimeoutSeconds);
+  const signature = await walletClient.signTypedData({
+    account,
+    domain: { name: domain.name, version: domain.version, chainId, verifyingContract: getAddress2(accept.asset) },
+    types: EIP3009_TYPES,
+    primaryType: "TransferWithAuthorization",
+    message: { from, to, value: BigInt(value), validAfter: 0n, validBefore: BigInt(validBefore), nonce }
+  });
+  return {
+    payload: { signature, authorization: { from, to, value, validAfter, validBefore, nonce } },
+    payerFrom: from,
+    nonce
+  };
+}
 var eip3009Abi = [
   {
     type: "function",
@@ -873,6 +928,9 @@ function buildReceiptHeader(receipt) {
 function buildSignatureHeader(signature) {
   return toBase64Json(signature);
 }
+function buildExactSignatureHeader(input) {
+  return toBase64Json({ x402Version: 2, accepted: input.accepted, payload: input.payload });
+}
 async function parseChallenge(response) {
   const headerValue = response.headers.get(HEADER_REQUIRED);
   if (headerValue) {
@@ -887,11 +945,24 @@ async function parseChallenge(response) {
   return null;
 }
 function parseReceipt(response) {
-  const headerValue = response.headers.get(HEADER_RESPONSE);
+  const headerValue = response.headers.get(HEADER_RESPONSE) ?? response.headers.get(HEADER_RESPONSE_V1);
   if (!headerValue) return null;
   const parsed = fromBase64Json(headerValue);
   return isValidReceipt(parsed) ? parsed : null;
 }
+function parseSettleResponse(response) {
+  const headerValue = response.headers.get(HEADER_RESPONSE) ?? response.headers.get(HEADER_RESPONSE_V1);
+  if (!headerValue) return null;
+  const parsed = fromBase64Json(headerValue);
+  if (!parsed || typeof parsed !== "object" || typeof parsed.success !== "boolean") return null;
+  return {
+    success: parsed.success,
+    ...typeof parsed.transaction === "string" ? { transaction: parsed.transaction } : {},
+    ...typeof parsed.network === "string" ? { network: parsed.network } : {},
+    ...typeof parsed.payer === "string" ? { payer: parsed.payer } : {},
+    ...typeof parsed.errorReason === "string" ? { errorReason: parsed.errorReason } : {}
+  };
+}
 function parseSignatureHeader(value) {
   const parsed = fromBase64Json(value);
   if (!parsed || typeof parsed !== "object") return null;
@@ -1085,6 +1156,15 @@ function makeEvmNetwork(resolved) {
     },
     async estimateCost(accept) {
       const { decimals, symbol } = resolved.chain.nativeCurrency;
+      if (accept.scheme === "exact") {
+        return nativeCost({
+          symbol,
+          decimals,
+          fee: 0n,
+          basis: "estimated",
+          detail: "gasless \u2014 the server/facilitator settles the signed authorization"
+        });
+      }
       const gasLimit = accept.asset === "native" ? 21000n : 65000n;
       try {
         const gasPrice = await publicClient.getGasPrice();
@@ -1146,6 +1226,21 @@ 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.
+    async payExact(wallet, accept) {
+      const a = wallet._native;
+      const { payload, payerFrom, nonce } = await payExactEvm({
+        publicClient,
+        walletClient: a.walletClient,
+        account: a.account,
+        chainId: resolved.chainId,
+        accept
+      });
+      return { payload, accepted: accept, payerFrom, nonce };
+    },
     // Standard x402 `exact` rail (EIP-3009), seller side — EVM only.
     async exactDomain(asset) {
       return readExactDomain(publicClient, asset);
@@ -1176,7 +1271,7 @@ var loaders = {
   solana: async () => {
     let mod;
     try {
-      mod = await import("./solana-S3UFI3FE.js");
+      mod = await import("./solana-3TRYD4QB.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Solana selected, but its packages aren't installed. Run: npm install @solana/web3.js @solana/spl-token bs58`,
@@ -1188,7 +1283,7 @@ var loaders = {
   ton: async () => {
     let mod;
     try {
-      mod = await import("./ton-WPTXGLVK.js");
+      mod = await import("./ton-QHGQLJX2.js");
     } catch (cause) {
       throw new MissingDriverError(
         `TON selected, but its packages aren't installed. Run: npm install @ton/ton @ton/core @ton/crypto`,
@@ -1200,7 +1295,7 @@ var loaders = {
   stellar: async () => {
     let mod;
     try {
-      mod = await import("./stellar-Q5PO23SC.js");
+      mod = await import("./stellar-IK3UML6O.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Stellar selected, but its package isn't installed. Run: npm install @stellar/stellar-sdk`,
@@ -1212,7 +1307,7 @@ var loaders = {
   xrpl: async () => {
     let mod;
     try {
-      mod = await import("./xrpl-HEAPEXAM.js");
+      mod = await import("./xrpl-2GZMDYW5.js");
     } catch (cause) {
       throw new MissingDriverError(
         `XRPL selected, but its package isn't installed. Run: npm install xrpl`,
@@ -1224,7 +1319,7 @@ var loaders = {
   tron: async () => {
     let mod;
     try {
-      mod = await import("./tron-6GXBXTR4.js");
+      mod = await import("./tron-2N2GA62O.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Tron selected, but its package isn't installed. Run: npm install tronweb`,
@@ -1236,7 +1331,7 @@ var loaders = {
   sui: async () => {
     let mod;
     try {
-      mod = await import("./sui-WOXRKJXS.js");
+      mod = await import("./sui-VSE63WQM.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Sui selected, but its package isn't installed. Run: npm install @mysten/sui`,
@@ -1248,7 +1343,7 @@ var loaders = {
   near: async () => {
     let mod;
     try {
-      mod = await import("./near-K6BDBABG.js");
+      mod = await import("./near-DT6LRIKB.js");
     } catch (cause) {
       throw new MissingDriverError(
         `NEAR selected, but its package isn't installed. Run: npm install near-api-js`,
@@ -1260,7 +1355,7 @@ var loaders = {
   aptos: async () => {
     let mod;
     try {
-      mod = await import("./aptos-LPBLSEIQ.js");
+      mod = await import("./aptos-CDEYDDM5.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Aptos selected, but its package isn't installed. Run: npm install @aptos-labs/ts-sdk`,
@@ -1272,7 +1367,7 @@ var loaders = {
   algorand: async () => {
     let mod;
     try {
-      mod = await import("./algorand-WGVF4KTU.js");
+      mod = await import("./algorand-7EUZYL2Z.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Algorand selected, but its package isn't installed. Run: npm install algosdk`,
@@ -1859,6 +1954,7 @@ var SpendLedger = class {
 };
 
 // src/client.ts
+var DEFAULT_SCHEMES = ["onchain-proof"];
 var RECIPIENT_FIX = {
   NO_TRUSTLINE: "the recipient needs a one-time trustline for this asset before it can receive",
   NOT_REGISTERED: "the recipient must be storage_deposit-registered on this token (NEP-145, one-time)",
@@ -1901,6 +1997,11 @@ var PipRailClient = class {
       return { net, wallet };
     })();
   }
+  /** Resolve the effective scheme set: a per-call override, else the constructor's
+   *  `schemes`, else the `onchain-proof`-only default. */
+  resolveSchemes(perCall) {
+    return perCall ?? this.opts.schemes ?? DEFAULT_SCHEMES;
+  }
   /** GET that auto-handles 402. Pass a full URL to any x402-gated endpoint. */
   get(url, init) {
     return this.fetch(url, { ...init ?? {}, method: "GET" });
@@ -1945,7 +2046,7 @@ var PipRailClient = class {
   async quote(url, init) {
     const res = await fetch(url, { ...init ?? {}, method: init?.method ?? "GET" });
     if (res.status !== 402) return null;
-    const { quote } = await this.resolveChallenge(url, res);
+    const { quote } = await this.resolveChallenge(url, res, this.resolveSchemes());
     return quote;
   }
   /**
@@ -1964,7 +2065,7 @@ var PipRailClient = class {
   async estimateCost(url, init) {
     const res = await fetch(url, { ...init ?? {}, method: init?.method ?? "GET" });
     if (res.status !== 402) return null;
-    const { net, accept, quote } = await this.resolveChallenge(url, res);
+    const { net, accept, quote } = await this.resolveChallenge(url, res, this.resolveSchemes());
     const cost = await net.estimateCost(accept);
     return { quote, cost };
   }
@@ -2000,7 +2101,7 @@ var PipRailClient = class {
       throw new InvalidEnvelopeError("402 response did not include a parseable x402 challenge.");
     }
     const { net, wallet } = await this.ensure();
-    return this.planFromChallenge(net, wallet, challenge, url);
+    return this.planFromChallenge(net, wallet, challenge, url, this.resolveSchemes());
   }
   /**
    * Convenience over {@link planPayment}: can the wallet settle this URL right now?
@@ -2028,8 +2129,8 @@ var PipRailClient = class {
    * - A resource just listed via {@link register} may not appear yet — 402 Index reviews
    *   before publishing, so retry with a brief backoff if a fresh listing is missing.
    * - Results are cross-scheme (mostly the mainstream `exact` scheme); `fetch()` pays
-   *   only `onchain-proof` rails directly (pay `exact` resources with the experimental
-   *   `drivers/evm/exact.ts`).
+   *   `onchain-proof` rails by default, and standard `exact` rails too once you opt in
+   *   with `schemes: ['onchain-proof', 'exact']` (EVM + EIP-3009 — USDC/EURC).
    */
   async discover(opts = {}) {
     const found = await searchOpenIndexes({
@@ -2168,13 +2269,14 @@ var PipRailClient = class {
     }
     const firstResponse = await fetch(url, init);
     if (firstResponse.status !== 402) return firstResponse;
-    const resolved = await this.resolveChallenge(url, firstResponse);
+    const schemes = this.resolveSchemes(init?.schemes);
+    const resolved = await this.resolveChallenge(url, firstResponse, schemes);
     const { net, wallet, challenge } = resolved;
     let accept = resolved.accept;
     let quote = resolved.quote;
     const autoRoute = init?.autoRoute ?? this.opts.autoRoute ?? false;
     if (autoRoute) {
-      const plan = await this.planFromChallenge(net, wallet, challenge, url);
+      const plan = await this.planFromChallenge(net, wallet, challenge, url, schemes);
       if (!plan.best) {
         throw new PaymentDeclinedError(plan.fundingHint ?? "No rail is settleable for this payment.");
       }
@@ -2183,6 +2285,9 @@ var PipRailClient = class {
     }
     this.safeEmit({ kind: "payment-required", challenge, accept });
     await this.authorize(quote);
+    if (accept.scheme === "exact") {
+      return this.payExactRail(net, wallet, accept, url, init, quote);
+    }
     const { ref, confirmed } = await this.payAndConfirm(net, wallet, accept);
     const response = await this.retryWithProof(url, init, accept, ref, confirmed);
     this.recordSpend(quote, ref);
@@ -2194,7 +2299,7 @@ var PipRailClient = class {
    * network, pick the accept the client can pay, and build its quote. Shared by
    * `quote()` (read-only) and `fetch()` (which then authorises + pays).
    */
-  async resolveChallenge(url, response) {
+  async resolveChallenge(url, response, schemes) {
     const challenge = await parseChallenge(response);
     if (!challenge) {
       throw new InvalidEnvelopeError(
@@ -2202,11 +2307,29 @@ var PipRailClient = class {
       );
     }
     const { net, wallet } = await this.ensure();
-    const candidates = this.gatherCandidates(net, challenge);
+    const candidates = this.gatherCandidates(net, challenge, schemes);
     if (candidates.length === 0) {
-      const networks = challenge.accepts.map((a) => a.network).join(", ");
+      const exactOnNet = challenge.accepts.some(
+        (a) => a.scheme === "exact" && net.supports(a.network)
+      );
+      if (schemes.includes("exact") && exactOnNet && typeof net.payExact !== "function") {
+        throw new UnsupportedSchemeError(
+          `This 402 offers a standard 'exact' rail on ${net.network}, but the ${net.family} family can't pay 'exact' (EVM + EIP-3009 only), and no 'onchain-proof' rail was offered.`
+        );
+      }
+      if (!schemes.includes("exact") && exactOnNet && typeof net.payExact === "function") {
+        const payable = challenge.accepts.some(
+          (a) => a.scheme === "exact" && net.supports(a.network) && net.describeAsset(a.asset) != null
+        );
+        if (payable) {
+          throw new NoCompatibleAcceptError(
+            `This 402 is payable only via the standard 'exact' rail on ${net.network}, which is OFF by default. Enable it: new PipRailClient({ \u2026, schemes: ['onchain-proof', 'exact'] }) or per call fetch(url, { schemes: ['exact'] }) (MCP: PIPRAIL_SCHEMES=onchain-proof,exact).`
+          );
+        }
+      }
+      const networks = [...new Set(challenge.accepts.map((a) => a.network))].join(", ");
       throw new NoCompatibleAcceptError(
-        `No accepts[] entry for ${net.network} (challenge offered: ${networks || "none"}).`
+        `No accepts[] entry payable by this client on ${net.network} (schemes: ${schemes.join(", ")}; challenge offered: ${networks || "none"}).`
       );
     }
     const priced = candidates.map((accept) => ({
@@ -2216,20 +2339,37 @@ var PipRailClient = class {
     const chosen = priced.find((p) => p.quote.withinPolicy) ?? priced[0];
     return { net, wallet, accept: chosen.accept, challenge, quote: chosen.quote };
   }
-  /** 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. */
-  gatherCandidates(net, challenge) {
-    return challenge.accepts.filter(
-      (a) => a.scheme === "onchain-proof" && net.supports(a.network)
-    );
+  /** The candidate accepts this client could pay, on the bound network. Always the
+   *  backendless `onchain-proof` rails; PLUS standard `exact` rails when `schemes`
+   *  enables them AND the driver can settle them (EVM `payExact` + a recognised
+   *  EIP-3009 token). `onchain-proof` is gathered FIRST so default selection is
+   *  unchanged when `exact` is off. */
+  gatherCandidates(net, challenge, schemes) {
+    const out = [];
+    if (schemes.includes("onchain-proof")) {
+      out.push(
+        ...challenge.accepts.filter(
+          (a) => a.scheme === "onchain-proof" && net.supports(a.network)
+        )
+      );
+    }
+    if (schemes.includes("exact")) {
+      out.push(
+        ...challenge.accepts.filter(
+          (a) => a.scheme === "exact" && net.supports(a.network) && typeof net.payExact === "function" && net.describeAsset(a.asset) != null && // a foreign rail's maxTimeoutSeconds must be a usable positive integer, or
+          // signing it would build a NaN/garbage validBefore — drop it silently
+          // (symmetric with an unrecognised token) rather than leak a raw SyntaxError.
+          Number.isInteger(a.maxTimeoutSeconds) && a.maxTimeoutSeconds > 0
+        )
+      );
+    }
+    return out;
   }
   /** Build the full {@link PaymentPlan} from an already-parsed challenge + bound
    *  net/wallet. Shared by `planPayment` (read-only) and `fetch`'s autoRoute. */
-  async planFromChallenge(net, wallet, challenge, url) {
+  async planFromChallenge(net, wallet, challenge, url, schemes) {
     const chainLabel = typeof this.opts.chain === "string" ? this.opts.chain : net.network;
-    const candidates = this.gatherCandidates(net, challenge);
+    const candidates = this.gatherCandidates(net, challenge, schemes);
     if (candidates.length === 0) {
       const offered = [...new Set(challenge.accepts.map((a) => a.network))].join(", ") || "none";
       return {
@@ -2269,17 +2409,23 @@ var PipRailClient = class {
     const rr = await net.recipientReady(accept.payTo, accept.asset).catch(() => ({ ready: "unknown" }));
     const amount = BigInt(accept.amount);
     const fee = safeBig(cost.fee);
+    const isExact = accept.scheme === "exact";
     const isNative = accept.asset === "native";
     const blockers = [];
     const warnings = [];
     const shortfall = {};
     if (!quote.withinPolicy) blockers.push("OUTSIDE_POLICY");
     if (quote.symbolMismatch) warnings.push("SYMBOL_MISMATCH");
-    if (cost.basis === "heuristic") warnings.push("GAS_HEURISTIC");
+    if (!isExact && cost.basis === "heuristic") warnings.push("GAS_HEURISTIC");
     const tokenKnown = bal.token != null;
     const nativeKnown = bal.native != null;
-    if (!tokenKnown || !nativeKnown) warnings.push("BALANCE_UNREADABLE");
-    if (isNative) {
+    if (isExact ? !tokenKnown : !tokenKnown || !nativeKnown) warnings.push("BALANCE_UNREADABLE");
+    if (isExact) {
+      if (tokenKnown && bal.token < amount) {
+        blockers.push("INSUFFICIENT_TOKEN");
+        shortfall.token = formatUnits(amount - bal.token, quote.decimals);
+      }
+    } else if (isNative) {
       if (nativeKnown && bal.native < amount + fee) {
         blockers.push("INSUFFICIENT_TOKEN");
         shortfall.token = formatUnits(amount + fee - bal.native, quote.decimals);
@@ -2306,7 +2452,7 @@ var PipRailClient = class {
     } else {
       recipient = { ready: rr.ready };
     }
-    const unreadable = isNative ? !nativeKnown : !tokenKnown || !nativeKnown;
+    const unreadable = isExact ? !tokenKnown : isNative ? !nativeKnown : !tokenKnown || !nativeKnown;
     const state = blockers.length ? "blocked" : unreadable || rr.ready === "unknown" ? "unknown" : "payable";
     return {
       accept,
@@ -2335,6 +2481,11 @@ var PipRailClient = class {
     const amountBase = BigInt(accept.amount);
     const described = net.describeAsset(accept.asset);
     const decimals = described?.decimals ?? accept.extra.decimals;
+    if (decimals === void 0) {
+      throw new InvalidEnvelopeError(
+        `challenge for ${accept.asset} on ${accept.network} states no decimals and the SDK doesn't recognise the token \u2014 refusing to price it.`
+      );
+    }
     const symbol = described?.symbol ?? accept.extra.symbol;
     const amountFormatted = formatUnits(amountBase, decimals);
     const intent = {
@@ -2495,7 +2646,102 @@ var PipRailClient = class {
       { ref }
     );
   }
+  /**
+   * Pay a standard x402 `exact` rail — a SEPARATE, fundamentally more conservative
+   * path than {@link retryWithProof}. The buyer SIGNS an EIP-3009 authorization ONCE
+   * (the driver's `payExact`) and the server / merchant-chosen facilitator BROADCASTS
+   * it synchronously, so a blind re-POST of a still-in-flight authorization could
+   * double-BROADCAST it. Hence, unlike the onchain-proof loop:
+   *
+   *   • sign exactly once — reuse the SAME header on every retry, never re-sign;
+   *   • retry ONLY an explicit 402 (a definitive pre-broadcast rejection), bounded
+   *     well under `maxTimeoutSeconds` so the loop can't outlive the authorization;
+   *   • a post-POST transport error/timeout → {@link PaymentTimeoutError} carrying the
+   *     nonce (the facilitator MAY have settled — verify on-chain, NEVER re-pay);
+   *   • a 5xx → return as-is (server settle failure; the authorization stays valid +
+   *     its nonce unused) — no settled event, no spend;
+   *   • a 200 whose SettleResponse says `success:false` → a rejection, NEVER a spend;
+   *   • the spend is recorded EXACTLY ONCE, on an affirmative settlement only.
+   */
+  async payExactRail(net, wallet, accept, url, init, quote) {
+    if (!net.payExact) {
+      throw new UnsupportedSchemeError(
+        `the ${net.family} family can't pay a standard 'exact' rail (EVM + EIP-3009 only).`
+      );
+    }
+    throwIfAborted(init?.signal);
+    const { payload, accepted, payerFrom, nonce } = await net.payExact(wallet, accept);
+    const headers = new Headers(init?.headers);
+    headers.set(HEADER_SIGNATURE, buildExactSignatureHeader({ accepted, payload }));
+    const rejectDefinitive = (why2) => {
+      this.safeEmit({ kind: "payment-failed", reason: `exact: facilitator rejected nonce=${nonce} (${why2})` });
+      throw new MaxRetriesExceededError(
+        `exact: the facilitator rejected the payment (${why2}). Fix the cause, then re-present the SAME signed authorization (nonce=${nonce}) \u2014 do NOT re-sign a fresh nonce. ref=${nonce}.`,
+        { ref: nonce }
+      );
+    };
+    const deadline = Date.now() + Math.max(1, Math.floor(accept.maxTimeoutSeconds / 2)) * 1e3;
+    const maxAttempts = Math.min(this.maxRetries, 3);
+    let lastReason = null;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+      if (attempt > 0) {
+        if (Date.now() >= deadline) break;
+        await new Promise((r) => setTimeout(r, Math.min(2e3, 400 * 2 ** (attempt - 1))));
+      }
+      throwIfAborted(init?.signal);
+      const budget = Math.min(this.retryTimeoutMs, deadline - Date.now());
+      if (budget <= 0) break;
+      const timeoutController = new AbortController();
+      const timeoutId = setTimeout(() => timeoutController.abort(), budget);
+      const signal = init?.signal && typeof AbortSignal.any === "function" ? AbortSignal.any([timeoutController.signal, init.signal]) : timeoutController.signal;
+      let response;
+      try {
+        response = await fetch(url, { ...init ?? {}, headers, signal });
+      } catch (err) {
+        throw new PaymentTimeoutError(
+          `exact: no response after submitting the authorization (nonce=${nonce}) to ${hostOf2(url)}. The facilitator may have already settled it \u2014 verify on-chain with authorizationState(${payerFrom}, ${nonce}) before re-presenting; do NOT re-pay.`,
+          { cause: err, ref: nonce }
+        );
+      } finally {
+        clearTimeout(timeoutId);
+      }
+      const settle = parseSettleResponse(response);
+      if (response.status === 402) {
+        if (settle && settle.success === false) rejectDefinitive(settle.errorReason ?? "the facilitator reported success:false");
+        lastReason = await readInvalidReason(response) ?? lastReason;
+        continue;
+      }
+      if (response.ok && !(settle && settle.success === false)) {
+        const receipt = parseReceipt(response);
+        this.safeEmit({ kind: "payment-settled", receipt, ...settle ? { settle } : {} });
+        const ref = settle?.transaction || receipt?.transaction || `eip3009-nonce:${nonce}`;
+        this.recordSpend(quote, ref);
+        return response;
+      }
+      if (response.status >= 500) {
+        this.safeEmit({ kind: "payment-failed", reason: `exact: server ${response.status} \u2014 authorization nonce=${nonce} not settled` });
+        return response;
+      }
+      if (settle && settle.success === false) rejectDefinitive(settle.errorReason ?? "the facilitator reported success:false");
+      this.safeEmit({ kind: "payment-failed", reason: `exact: server ${response.status} \u2014 authorization nonce=${nonce} not settled` });
+      return response;
+    }
+    const why = lastReason ? `${lastReason.error}${lastReason.detail ? ` \u2014 ${lastReason.detail}` : ""}` : "server gave no reason";
+    this.safeEmit({
+      kind: "payment-failed",
+      reason: `exact: 402 after submitting authorization nonce=${nonce} (${why})`
+    });
+    throw new MaxRetriesExceededError(
+      `exact: server still returned 402 after submitting the signed authorization (nonce=${nonce}). Last rejection: ${why}. Re-present the SAME authorization \u2014 do NOT re-sign a fresh nonce; verify authorizationState(${payerFrom}, ${nonce}) first. ref=${nonce}.`,
+      { ref: nonce }
+    );
+  }
 };
+function throwIfAborted(signal) {
+  if (signal?.aborted) {
+    throw signal.reason ?? new DOMException("This operation was aborted.", "AbortError");
+  }
+}
 function safeBig(s) {
   try {
     return BigInt(s);
@@ -2596,8 +2842,16 @@ async function readInvalidReason(response) {
         detail: typeof body.detail === "string" ? body.detail : ""
       };
     }
+    if (body && body.isValid === false && typeof body.invalidReason === "string") {
+      return {
+        error: body.invalidReason,
+        detail: typeof body.invalidMessage === "string" ? body.invalidMessage : ""
+      };
+    }
   } catch {
   }
+  const settle = parseSettleResponse(response);
+  if (settle?.errorReason) return { error: settle.errorReason, detail: "" };
   return null;
 }
 
@@ -2726,17 +2980,17 @@ function paymentTools(client) {
     },
     {
       name: "piprail_pay_request",
-      description: "Fetch an x402 payment-gated URL, automatically paying the required on-chain payment if needed (subject to the spend policy + approval hook). Returns the HTTP status, the response body, and a payment receipt if one settled. If the payment is refused by policy or the approval hook, returns { declined: true, reason } \u2014 no funds moved.",
+      description: "Fetch an x402 payment-gated URL, automatically making the required payment if needed (subject to the spend policy + approval hook). Pays whichever rail the client is configured for \u2014 PipRail's backendless on-chain rail, or, when enabled, the standard `exact` rail (where the buyer signs and the server settles, so no buyer gas). Returns the HTTP status, the response body, and a payment receipt if one settled. If the payment is refused by policy or the approval hook, returns { declined: true, reason } \u2014 no funds moved.",
       annotations: {
         title: "Pay an x402 request",
         readOnlyHint: false,
         // this is the one tool that MOVES FUNDS
         destructiveHint: true,
-        // an on-chain payment is value-moving and not reversible
+        // a payment is value-moving and not reversible
         idempotentHint: false,
         // paying twice = two payments
         openWorldHint: true
-        // fetches a URL and settles on-chain
+        // fetches a URL and settles a payment
       },
       parameters: {
         type: "object",
@@ -3278,7 +3532,9 @@ function createPaymentGate(options) {
             amount: accept.amount,
             payTo: accept.payTo,
             maxTimeoutSeconds: accept.maxTimeoutSeconds,
-            extra: { name: accept.extra.name, version: accept.extra.version }
+            // name/version are OPTIONAL on the wire type (a foreign rail may omit them), but the
+            // gate's OWN exact rail always read them on-chain at resolution — so they're present here.
+            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
@@ -3372,11 +3628,13 @@ export {
   SettlementError,
   UnknownTokenError,
   UnsupportedNetworkError,
+  UnsupportedSchemeError,
   WrongChainError,
   WrongFamilyError,
   buildBazaarExtension,
   buildChallengeHeader,
   buildExactAuthorization,
+  buildExactSignatureHeader,
   buildOpenApi,
   buildReceiptHeader,
   buildSignatureHeader,
@@ -3395,6 +3653,7 @@ export {
   parseExactPaymentHeader,
   parseExactRequirements,
   parseReceipt,
+  parseSettleResponse,
   parseSignatureHeader,
   paymentTools,
   pickAccept,

package/dist/{near-K6BDBABG.js → near-DT6LRIKB.js}

@@ -7,7 +7,7 @@ import {
   nativeCost,
   rejectForeignToken,
   toInsufficientFundsError
-} from "./chunk-SVMGHASK.js";
+} from "./chunk-H3A4KWLJ.js";
 
 // src/drivers/near/index.ts
 import { JsonRpcProvider, Account, actions } from "near-api-js";