@piprail/sdk 1.20.1 → 1.21.0

package/CHANGELOG.md

@@ -4,6 +4,45 @@ All notable changes to `@piprail/sdk` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 versions follow [Semantic Versioning](https://semver.org/).
 
+## [1.21.0] — 2026-06-13 — standard `exact` rail on Solana (SVM) + fully-gasless facilitator mode
+
+Opt-in, defaults unchanged. `onchain-proof` stays the default on every chain and is byte-identical.
+
+### Added
+- **The standard x402 `exact` rail now covers Solana**, not just EVM — so any standard x402
+  client/agent that speaks `exact` (the majority) can pay a PipRail Solana gate directly, and a
+  PipRail agent can pay any standard Solana `exact` server. Per the ratified `scheme_exact_svm.md`:
+  the buyer partial-signs an SPL `TransferChecked` transaction whose **fee payer is the merchant**,
+  and the gate co-signs as fee payer + broadcasts against your own RPC — **no facilitator, no
+  backend** (the same self-settle model as the EVM `exact` rail). Enable it exactly as on EVM:
+  `requirePayment({ chain: 'solana', token: 'USDC', amount, payTo, exact: { settle: 'self', relayer } })`,
+  and on the client `new PipRailClient({ chain: 'solana', wallet, schemes: ['onchain-proof', 'exact'] })`.
+- **Buyer-gasless on Solana, for any SPL token.** The buyer signs the canonical
+  `[setComputeUnitLimit, setComputeUnitPrice, TransferChecked]` transaction and spends **zero SOL** —
+  only the token funds the payment. Gasless-ness is transaction-level (the fee payer), not token-level,
+  so **USDC and USDT are equally gasless** (no EIP-3009/Permit2 equivalent needed, unlike EVM). The fee
+  payer must be **distinct from `payTo`** (a scheme MUST-rule the SDK enforces), and the recipient's
+  token account must already exist (the exact rail won't create it — `onchain-proof` does).
+- **Solana facilitator mode → _fully_ gasless (neither buyer nor merchant pays).** `exact: { settle: {
+  facilitator } }` now works on Solana, not just EVM: the gate auto-discovers the facilitator's
+  fee-payer pubkey from its `GET /supported`, advertises it, and forwards settlement — the **facilitator
+  pays the gas**. Live-proven on mainnet against **PayAI** (`https://facilitator.payai.network`, no API
+  key). Self-settle (your own relayer pays the sub-cent fee) remains available; PipRail hosts nothing
+  and is never the fee payer.
+
+### Security (defense-in-depth, after an adversarial review)
+- The gate counts **only authentically-signed** transfers toward the required amount (a
+  tiny-signed + large-unsigned multi-transfer can't reach the price), enforces fee-payer **isolation by
+  resolved pubkey** across every instruction (ALT-safe, not a literal index check), and **canonicalizes**
+  the SVM replay key so a base64-malleated re-submission can't bypass the replay claim.
+
+### Changed (internal — no API change)
+- The `exact` rail moved behind a new driver SPI, `ResolvedNetwork.resolveExactRail`, so the gate is
+  fully chain-agnostic (it no longer special-cases EVM). EVM's EIP-3009/Permit2 method-selection is
+  unchanged in behaviour; Solana plugs in `{ method: 'svm', extra: { feePayer, tokenProgram } }`.
+- The wire types gained the SVM `exact` payload (`{ transaction }`) and the `extra` keys
+  `feePayer`/`memo`/`tokenProgram`; `assetTransferMethod` now also accepts `'svm'`.
+
 ## [1.20.1] — 2026-06-11 — gate replay store: bounded + exception-safe
 
 Patch — internal robustness on the gate's built-in replay protection. No API change, no visible

package/dist/index.cjs

@@ -533,6 +533,37 @@ var EXACT_NETWORK_SLUGS = {
 function chainIdForExactNetwork(slug) {
   return _nullishCoalesce(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" },
@@ -1417,11 +1448,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 +1742,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 +1764,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 +1791,7 @@ var loaders = {
   solana: async () => {
     let mod;
     try {
-      mod = await Promise.resolve().then(() => _interopRequireWildcard(require("./solana-MPPE6K24.cjs")));
+      mod = await Promise.resolve().then(() => _interopRequireWildcard(require("./solana-CCVSMOKS.cjs")));
     } catch (cause) {
       throw new (0, _chunkPA6YD3HLcjs.MissingDriverError)(
         `Solana selected, but its packages aren't installed. Run: npm install @solana/web3.js @solana/spl-token bs58`,
@@ -2770,7 +2817,7 @@ var PipRailClient = (_class2 = 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 +3002,7 @@ var PipRailClient = (_class2 = class {
       );
       if (schemes.includes("exact") && exactOnNet && typeof net.payExact !== "function") {
         throw new (0, _chunkPA6YD3HLcjs.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 +3382,7 @@ var PipRailClient = (_class2 = class {
   async payExactRail(net, wallet, accept, url, init, quote) {
     if (!net.payExact) {
       throw new (0, _chunkPA6YD3HLcjs.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(_optionalChain([init, 'optionalAccess', _48 => _48.signal]));
@@ -4012,6 +4059,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(_optionalChain([body, 'optionalAccess', _64 => _64.kinds])) ? body.kinds : [];
+    const kind = kinds.find((k) => _optionalChain([k, 'optionalAccess', _65 => _65.scheme]) === "exact" && _optionalChain([k, 'optionalAccess', _66 => _66.network]) === network);
+    const fp = _optionalChain([kind, 'optionalAccess', _67 => _67.extra, 'optionalAccess', _68 => _68.feePayer]);
+    return typeof fp === "string" ? fp : void 0;
+  } catch (e32) {
+    return void 0;
+  } finally {
+    clearTimeout(timer);
+  }
+}
 function safeStringify(value) {
   return JSON.stringify(value, (_k, v) => typeof v === "bigint" ? v.toString() : v);
 }
@@ -4035,7 +4100,7 @@ async function post(url, body, headers) {
   let json = null;
   try {
     json = await res.json();
-  } catch (e32) {
+  } catch (e33) {
   }
   return { status: res.status, json };
 }
@@ -4153,7 +4218,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 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. 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 +4231,32 @@ 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 = _nullishCoalesce(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" && !(_nullishCoalesce(_optionalChain([net, 'access', _64 => _64.exactPermit2Supported, 'optionalCall', _65 => _65()]), () => ( 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 (!net.resolveExactRail) return void 0;
+    let relayer;
+    let feePayer;
     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 the settle), e.g. exact: { settle: 'self', relayer: { privateKey } }."
         );
       }
-      const relayer = net.bindWallet(cfg.relayer);
-      return { method, ...domain ? { domain } : {}, mode: { kind: "self", relayer } };
-    }
-    return {
-      method,
-      ...domain ? { domain } : {},
-      mode: {
-        kind: "facilitator",
-        url: cfg.settle.facilitator,
-        ...cfg.settle.authHeaders ? { authHeaders: cfg.settle.authHeaders } : {}
-      }
+      relayer = net.bindWallet(cfg.relayer);
+    } else {
+      feePayer = cfg.settle.feePayer;
+    }
+    const method = _nullishCoalesce(cfg.method, () => ( "auto"));
+    let info = await net.resolveExactRail({ asset, method, relayer, feePayer });
+    if (!info && cfg.settle !== "self" && !feePayer) {
+      const discovered = await fetchFacilitatorFeePayer(cfg.settle.facilitator, net.network);
+      if (discovered) info = await net.resolveExactRail({ asset, method, relayer, feePayer: discovered });
+    }
+    if (!info) return void 0;
+    const mode = cfg.settle === "self" ? { kind: "self", relayer } : {
+      kind: "facilitator",
+      url: cfg.settle.facilitator,
+      ...cfg.settle.authHeaders ? { authHeaders: cfg.settle.authHeaders } : {}
     };
+    return { method: info.method, ...info.extra ? { extra: info.extra } : {}, mode };
   }
   const hasCustomStore = Boolean(options.isUsed || options.markUsed);
   const localUsed = /* @__PURE__ */ new Map();
@@ -4269,11 +4313,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
       }
     };
   }
@@ -4289,7 +4333,7 @@ function createPaymentGate(options) {
     const specs = await ready();
     const nonce = genNonce();
     const bazaar = options.discovery ? { bazaar: buildBazaarExtension(options.discovery === true ? {} : options.discovery) } : void 0;
-    const extensions = { ...bazaar, ..._optionalChain([opts, 'optionalAccess', _66 => _66.extensions]) };
+    const extensions = { ...bazaar, ..._optionalChain([opts, 'optionalAccess', _69 => _69.extensions]) };
     const challenge2 = {
       x402Version: 2,
       resource: {
@@ -4297,7 +4341,7 @@ function createPaymentGate(options) {
         ...options.description ? { description: options.description } : {}
       },
       accepts: buildAccepts(specs, nonce),
-      ..._optionalChain([opts, 'optionalAccess', _67 => _67.error]) ? { error: opts.error } : {},
+      ..._optionalChain([opts, 'optionalAccess', _70 => _70.error]) ? { error: opts.error } : {},
       ...Object.keys(extensions).length > 0 ? { extensions } : {}
     };
     return { challenge: challenge2, requiredHeader: buildChallengeHeader(challenge2) };
@@ -4320,7 +4364,7 @@ function createPaymentGate(options) {
     let amountFormatted = receipt.amount;
     try {
       amountFormatted = _chunkPA6YD3HLcjs.formatUnits.call(void 0, BigInt(receipt.amount), spec.decimals);
-    } catch (e33) {
+    } catch (e34) {
     }
     return {
       ...receipt,
@@ -4334,7 +4378,7 @@ function createPaymentGate(options) {
     if (!options.onPaidError) return;
     try {
       options.onPaidError(error, receipt);
-    } catch (e34) {
+    } catch (e35) {
     }
   }
   function fireOnPaid(receipt) {
@@ -4426,10 +4470,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 (e36) {
+        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 +4511,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: _nullishCoalesce(accept.extra.name, () => ( "")), version: _nullishCoalesce(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: _nullishCoalesce(accept.extra.feePayer, () => ( "")) } : { name: _nullishCoalesce(accept.extra.name, () => ( "")), version: _nullishCoalesce(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) {
@@ -4537,7 +4596,7 @@ function isRetryableStatus(status) {
 }
 var sleep = (ms) => ms > 0 ? new Promise((resolve) => setTimeout(resolve, ms)) : Promise.resolve();
 async function signBody(secret, body) {
-  const subtle = _optionalChain([globalThis, 'access', _68 => _68.crypto, 'optionalAccess', _69 => _69.subtle]);
+  const subtle = _optionalChain([globalThis, 'access', _71 => _71.crypto, 'optionalAccess', _72 => _72.subtle]);
   if (!subtle) return null;
   try {
     const enc = new TextEncoder();
@@ -4547,7 +4606,7 @@ async function signBody(secret, body) {
     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 (e35) {
+  } catch (e37) {
     return null;
   }
 }
@@ -4607,8 +4666,8 @@ async function deliverReceipt(receipt, options) {
     const retryable = status === void 0 ? true : isRetryableStatus(status);
     const willRetry = !ok && retryable && attempt < maxAttempts;
     try {
-      _optionalChain([onAttempt, 'optionalCall', _70 => _70({ attempt, ok, ...status !== void 0 ? { status } : {}, ...error ? { error } : {}, willRetry })]);
-    } catch (e36) {
+      _optionalChain([onAttempt, 'optionalCall', _73 => _73({ attempt, ok, ...status !== void 0 ? { status } : {}, ...error ? { error } : {}, willRetry })]);
+    } catch (e38) {
     }
     if (ok) return { delivered: true, attempts: attempt, status };
     if (!willRetry) {