@piprail/sdk 1.20.1 → 1.21.1

package/dist/index.js

@@ -533,6 +533,37 @@ var EXACT_NETWORK_SLUGS = {
 function chainIdForExactNetwork(slug) {
   return EXACT_NETWORK_SLUGS[slug] ?? null;
 }
+async function resolveExactRailEvm(input) {
+  const { asset, method, readDomain, permit2Supported } = input;
+  if (asset === "native") return null;
+  const want = method === "eip3009" || method === "permit2" ? method : "auto";
+  let chosen;
+  let extra = {};
+  if (want === "permit2") {
+    chosen = "permit2";
+  } else {
+    const d = await readDomain(asset);
+    if (d) {
+      chosen = "eip3009";
+      extra = { name: d.name, version: d.version };
+    } else if (want === "eip3009") {
+      throw new Error(
+        `requirePayment: exact \`method: 'eip3009'\` requested for ${asset}, 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 {
+      chosen = "permit2";
+    }
+  }
+  if (chosen === "permit2" && !permit2Supported()) {
+    if (method === "permit2") {
+      throw new Error(
+        `requirePayment: exact \`method: 'permit2'\` needs the x402 Permit2 proxy deployed on this chain, 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 null;
+  }
+  return { method: chosen, extra };
+}
 var EIP3009_TYPES = {
   TransferWithAuthorization: [
     { name: "from", type: "address" },
@@ -635,10 +666,14 @@ async function payExactEvm(input) {
       `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);
+  let domain = await readExactDomain(publicClient, accept.asset);
+  if (!domain) {
+    await new Promise((r) => setTimeout(r, 300));
+    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.`
+      `exact: couldn't derive the EIP-712 domain for ${accept.asset} on ${accept.network}. Either it isn't an EIP-3009 token (USDT needs Permit2; native/plain ERC-20 aren't exact-payable) \u2014 pay via onchain-proof \u2014 OR your RPC couldn't read it (transient): if the gate advertised eip3009, pass a reliable rpcUrl and retry.`
     );
   }
   const g = globalThis.crypto;
@@ -1417,11 +1452,14 @@ function parseExactPaymentHeader(value) {
   if (typeof network !== "string") return null;
   const payload = v.payload;
   if (!payload || typeof payload !== "object") return null;
-  const signature = payload.signature;
-  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;
   const base2 = { x402Version, network, ...asset ? { asset } : {}, raw: v };
+  if (typeof payload.transaction === "string") {
+    return { ...base2, method: "svm", payload: { transaction: payload.transaction } };
+  }
+  const signature = payload.signature;
+  if (typeof signature !== "string") return null;
   const authorization = payload.authorization;
   if (authorization && typeof authorization === "object") {
     for (const k of ["from", "to", "value", "validAfter", "validBefore", "nonce"]) {
@@ -1708,6 +1746,16 @@ function makeEvmNetwork(resolved) {
     exactPermit2Supported() {
       return isPermit2ProxyChain(resolved.chainId);
     },
+    // The gate's rail-advertisement SPI — EIP-3009 vs Permit2 selection (the pure helper),
+    // injecting the on-chain domain read + the Permit2 proxy-presence check.
+    async resolveExactRail({ asset, method }) {
+      return resolveExactRailEvm({
+        asset,
+        method,
+        readDomain: (a) => readExactDomain(publicClient, a),
+        permit2Supported: () => isPermit2ProxyChain(resolved.chainId)
+      });
+    },
     async settleExactSelf({ relayer, payload, accept }) {
       const a = relayer._native;
       if ("permit2Authorization" in payload) {
@@ -1720,6 +1768,9 @@ function makeEvmNetwork(resolved) {
           accept
         });
       }
+      if ("transaction" in payload) {
+        return { ok: false, error: "signature_invalid", detail: "An SVM (Solana) payload was submitted to an EVM exact rail." };
+      }
       return verifyAndSettleExactEvm({
         publicClient,
         walletClient: a.walletClient,
@@ -1744,7 +1795,7 @@ var loaders = {
   solana: async () => {
     let mod;
     try {
-      mod = await import("./solana-WDKWWF33.js");
+      mod = await import("./solana-IBVUZS54.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Solana selected, but its packages aren't installed. Run: npm install @solana/web3.js @solana/spl-token bs58`,
@@ -2770,7 +2821,7 @@ var PipRailClient = class {
    *   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
    *   `onchain-proof` rails by default, and standard `exact` rails too once you opt in
-   *   with `schemes: ['onchain-proof', 'exact']` (EVM + EIP-3009 — USDC/EURC).
+   *   with `schemes: ['onchain-proof', 'exact']` (EVM EIP-3009/Permit2 + Solana SVM).
    */
   async discover(opts = {}) {
     const found = await searchOpenIndexes({
@@ -2955,7 +3006,7 @@ var PipRailClient = class {
       );
       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.`
+          `This 402 offers a standard 'exact' rail on ${net.network}, but the ${net.family} family can't pay 'exact' (supported on EVM + Solana today), and no 'onchain-proof' rail was offered.`
         );
       }
       if (!schemes.includes("exact") && exactOnNet && typeof net.payExact === "function") {
@@ -3335,7 +3386,7 @@ var PipRailClient = class {
   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).`
+        `the ${net.family} family can't pay a standard 'exact' rail (supported on EVM + Solana today).`
       );
     }
     throwIfAborted(init?.signal);
@@ -3600,6 +3651,18 @@ straight from your wallet to the server; PipRail custodies nothing. Follow this.
    and return the result.
 Always plan before you pay so you never commit to a payment you cannot finish.
 
+## Gasless \u2014 the exact rail (zero gas for you)
+A 402 may offer up to two rails; you don't choose per payment \u2014 the client does, automatically:
+- onchain-proof (PipRail's default): you broadcast the payment yourself and pay the network gas
+  (the native coin \u2014 ETH/SOL/\u2026). Works on every chain.
+- exact (the ratified x402 rail, opt-in): you only SIGN; the server \u2014 or a facilitator it chose
+  (e.g. PayAI) \u2014 broadcasts it, so you pay ZERO gas (you need only the token, no native coin). It
+  works on EVM + Solana, and the on-chain method (EIP-3009 / Permit2 / SVM) is picked automatically.
+When the exact scheme is enabled AND balance-aware routing is on, paying picks the cheapest
+settleable rail \u2014 i.e. the gasless exact one. Nothing changes in your loop: quote \u2192 plan \u2192 pay is
+identical. The exact scheme is OPT-IN by the operator (MCP: PIPRAIL_SCHEMES=onchain-proof,exact);
+you can't enable it yourself, but you can report when a 402 needs it (see UNSUPPORTED_SCHEME below).
+
 ## Reading a refusal \u2014 never crash, never double-spend
 A failed pay returns a STRUCTURED object, never a thrown error you must catch:
   { ok:false, code, reason, explain, ref?, reasonCode?, declined? }
@@ -3617,9 +3680,13 @@ Branch on \`code\` (always reliable). Key cases:
 - code:'INSUFFICIENT_FUNDS' \u2014 top up the wallet (token and/or native gas), retry.
 - code:'PAYMENT_TIMEOUT' / 'MAX_RETRIES_EXCEEDED' / 'CONFIRMATION_TIMEOUT' \u2014 the
   payment may ALREADY be on-chain. Recover using the proof on \`.ref\` (re-verify
-  or re-submit it); never re-pay \u2014 a fresh payment would double-spend.
+  or re-submit it); never re-pay \u2014 a fresh payment would double-spend. On a gasless
+  exact rail \`.ref\` is the authorization NONCE, not a tx hash: re-present the SAME
+  signed authorization, never sign a fresh one (that would risk a double-spend).
 - code:'NO_COMPATIBLE_ACCEPT' / 'UNSUPPORTED_SCHEME' \u2014 the 402 isn't payable on
   your chain/scheme; \`explain\` says whether it's the wrong chain or a scheme to enable.
+  If it's a standard x402 server offering an exact rail, that's a config fix the operator makes
+  once (enable the exact scheme); report it, don't retry the same call blindly.
 
 ## Knowing your leash \u2014 call piprail_budget
 piprail_budget tells you how much budget and time you have left, per
@@ -4012,6 +4079,24 @@ function buildX402DnsTxt(input) {
 }
 
 // src/facilitator.ts
+async function fetchFacilitatorFeePayer(url, network, timeoutMs = 8e3) {
+  const base2 = url.replace(/\/+$/, "");
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${base2}/supported`, { signal: ctrl.signal });
+    if (!res.ok) return void 0;
+    const body = await res.json();
+    const kinds = Array.isArray(body?.kinds) ? body.kinds : [];
+    const kind = kinds.find((k) => k?.scheme === "exact" && k?.network === network);
+    const fp = kind?.extra?.feePayer;
+    return typeof fp === "string" ? fp : void 0;
+  } catch {
+    return void 0;
+  } finally {
+    clearTimeout(timer);
+  }
+}
 function safeStringify(value) {
   return JSON.stringify(value, (_k, v) => typeof v === "bigint" ? v.toString() : v);
 }
@@ -4134,6 +4219,7 @@ function createPaymentGate(options) {
     if (resolved) return resolved;
     const p = (async () => {
       const accepts = normaliseAccepts(options);
+      const exactSkips = [];
       const specs = await Promise.all(
         accepts.map(async (a) => {
           const net = await resolveNetwork2({ chain: a.chain, rpcUrl: a.rpcUrl ?? options.rpcUrl });
@@ -4147,13 +4233,17 @@ function createPaymentGate(options) {
           const { asset, decimals, symbol } = net.resolveToken(a.token);
           const amountBase = parseUnits(a.amount, decimals);
           const spec = { net, asset, decimals, symbol, amountBase, amountFormatted: a.amount, payTo };
-          if (options.exact) spec.exact = await resolveExactRail(net, asset);
+          if (options.exact) {
+            const outcome = await resolveExactRail(net, asset);
+            if (outcome.rail) spec.exact = outcome.rail;
+            else if (outcome.skipReason) exactSkips.push(outcome.skipReason);
+          }
           return spec;
         })
       );
       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 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`."
+          "requirePayment: `exact` was requested but none of the offered rails support it. " + (exactSkips.length > 0 ? exactSkips.join(" ") : "The standard `exact` rail is EVM ERC-20 (EIP-3009 \u2014 USDC / EURC \u2014 or Permit2, e.g. Binance-Peg USDC on BNB) or a Solana SPL token (SVM) \u2014 NOT native coins, NOT families without a standard `exact` scheme. Offer an EVM ERC-20 / Solana SPL token, or drop `exact`.")
         );
       }
       return specs;
@@ -4166,53 +4256,48 @@ function createPaymentGate(options) {
   }
   async function resolveExactRail(net, asset) {
     const cfg = options.exact;
-    if (net.family !== "evm" || asset === "native" || !net.settleExactSelf) {
-      return void 0;
-    }
-    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") {
+    const settle = cfg.settle;
+    if (!net.resolveExactRail) return {};
+    let relayer;
+    let feePayer;
+    if (settle === "self") {
+      if (cfg.relayer === void 0) {
         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.)`
+          "requirePayment: exact `settle: 'self'` needs a `relayer` wallet (the gas-paying key that broadcasts the settle), e.g. exact: { settle: 'self', relayer: { privateKey } }."
         );
-      } else {
-        method = "permit2";
       }
+      relayer = net.bindWallet(cfg.relayer);
+    } else {
+      feePayer = settle.feePayer;
     }
-    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.)`
-        );
+    const method = cfg.method ?? "auto";
+    let info = await net.resolveExactRail({ asset, method, relayer, feePayer });
+    if (!info && settle !== "self" && !feePayer && asset !== "native") {
+      const discovered = await fetchFacilitatorFeePayer(settle.facilitator, net.network);
+      if (!discovered) {
+        return {
+          skipReason: `${net.network}: couldn't read a fee payer from the facilitator (${settle.facilitator}/supported) \u2014 it may be down, or may not sponsor this network. Set \`exact.settle.feePayer\` explicitly to remove the runtime dependency, switch to \`settle: 'self'\` with your own relayer, or retry.`
+        };
       }
-      return void 0;
+      info = await net.resolveExactRail({ asset, method, relayer, feePayer: discovered });
     }
-    if (cfg.settle === "self") {
-      if (cfg.relayer === void 0) {
+    if (!info) return {};
+    if (settle !== "self" && info.method === "permit2") {
+      if (cfg.method === "permit2") {
         throw new Error(
-          "requirePayment: exact `settle: 'self'` needs a `relayer` wallet (the gas-paying key that broadcasts the settle), e.g. exact: { settle: 'self', relayer: { privateKey } }."
+          "requirePayment: exact `method: 'permit2'` can't be settled by a third-party facilitator \u2014 facilitators settle the standard EIP-3009 (EVM) / SVM (Solana) schemes, not PipRail\u2019s Permit2 proxy. Use an EIP-3009 token (USDC / EURC) with the facilitator, or `settle: 'self'` (your own relayer) to settle Permit2 yourself."
         );
       }
-      const relayer = net.bindWallet(cfg.relayer);
-      return { method, ...domain ? { domain } : {}, mode: { kind: "self", relayer } };
+      return {
+        skipReason: `${net.network}: this token isn't EIP-3009 (auto-selected Permit2), which a third-party facilitator can't settle \u2014 it would serve onchain-proof only here. Use an EIP-3009 token (USDC / EURC) with the facilitator, or \`settle: 'self'\` to settle Permit2 yourself.`
+      };
     }
-    return {
-      method,
-      ...domain ? { domain } : {},
-      mode: {
-        kind: "facilitator",
-        url: cfg.settle.facilitator,
-        ...cfg.settle.authHeaders ? { authHeaders: cfg.settle.authHeaders } : {}
-      }
+    const mode = settle === "self" ? { kind: "self", relayer } : {
+      kind: "facilitator",
+      url: settle.facilitator,
+      ...settle.authHeaders ? { authHeaders: settle.authHeaders } : {}
     };
+    return { rail: { method: info.method, ...info.extra ? { extra: info.extra } : {}, mode } };
   }
   const hasCustomStore = Boolean(options.isUsed || options.markUsed);
   const localUsed = /* @__PURE__ */ new Map();
@@ -4269,11 +4354,11 @@ function createPaymentGate(options) {
       maxTimeoutSeconds,
       extra: {
         assetTransferMethod: rail.method,
-        ...rail.domain ? { name: rail.domain.name, version: rail.domain.version } : {},
         minConfirmations,
         decimals: s.decimals,
         amountFormatted: s.amountFormatted,
-        ...s.symbol ? { symbol: s.symbol } : {}
+        ...s.symbol ? { symbol: s.symbol } : {},
+        ...rail.extra
       }
     };
   }
@@ -4426,10 +4511,23 @@ 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 auth = "permit2Authorization" in exact.payload ? exact.payload.permit2Authorization : exact.payload.authorization;
-    const nonce = auth.nonce;
+    let nonce;
+    let evmAuth = null;
+    if ("transaction" in exact.payload) {
+      try {
+        nonce = Buffer.from(exact.payload.transaction, "base64").toString("base64");
+      } catch {
+        nonce = exact.payload.transaction;
+      }
+    } else if ("permit2Authorization" in exact.payload) {
+      evmAuth = exact.payload.permit2Authorization;
+      nonce = evmAuth.nonce;
+    } else {
+      evmAuth = exact.payload.authorization;
+      nonce = evmAuth.nonce;
+    }
     if (await claimTx(nonce)) {
-      return rejection("tx_already_used", `Authorization nonce ${nonce} was already redeemed.`);
+      return rejection("tx_already_used", `Authorization ${evmAuth ? `nonce ${nonce}` : "transaction"} was already redeemed.`);
     }
     const accept = buildExactAccept(spec);
     const mode = spec.exact.mode;
@@ -4454,12 +4552,14 @@ function createPaymentGate(options) {
             amount: accept.amount,
             payTo: accept.payTo,
             maxTimeoutSeconds: accept.maxTimeoutSeconds,
-            // 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 ?? "" }
+            // The scheme's chain-specific `extra`, from the gate's OWN trusted rail: SVM forwards the
+            // facilitator's `feePayer` (the gas sponsor); EVM forwards the token's EIP-712 domain.
+            extra: accept.extra.assetTransferMethod === "svm" ? { feePayer: accept.extra.feePayer ?? "" } : { name: accept.extra.name ?? "", version: accept.extra.version ?? "" }
           },
           receipt: { network: accept.network, asset: accept.asset, payTo: accept.payTo, amount: accept.amount },
-          payerHint: auth.from
+          // The buyer address, for the receipt's `payer` fallback. EVM carries it in the
+          // authorization; SVM doesn't (the facilitator returns the settled payer) → omit it.
+          ...evmAuth ? { payerHint: evmAuth.from } : {}
         });
       }
     } catch (err) {