@piprail/sdk 1.20.1 → 1.21.0

package/dist/index.d.cts

@@ -82,12 +82,14 @@ interface X402ExactAcceptEntry {
     payTo: AddressId;
     maxTimeoutSeconds: number;
     extra: {
-        /** The exact-EVM transfer method, per the x402 `exact` EVM scheme: `'eip3009'`
-         *  for tokens with native `transferWithAuthorization`, or `'permit2'` for tokens
-         *  WITHOUT it (e.g. Binance-Peg USDC on BNB) — the payer signs a Permit2 witness
-         *  transfer whose `spender` is the canonical x402ExactPermit2Proxy and whose
-         *  `witness.to` binds the recipient. PipRail self-settles BOTH. */
-        assetTransferMethod: 'eip3009' | 'permit2';
+        /** The exact transfer method. EVM: `'eip3009'` for tokens with native
+         *  `transferWithAuthorization`, or `'permit2'` for tokens WITHOUT it (e.g.
+         *  Binance-Peg USDC on BNB) — the payer signs a Permit2 witness transfer whose
+         *  `spender` is the canonical x402ExactPermit2Proxy and whose `witness.to` binds the
+         *  recipient. **Solana (SVM): `'svm'`** — the payer partial-signs an SPL
+         *  `TransferChecked` transaction whose fee payer is the merchant (`feePayer` below),
+         *  and the gate co-signs as fee payer + broadcasts. PipRail self-settles ALL. */
+        assetTransferMethod: 'eip3009' | 'permit2' | 'svm';
         /** EIP-712 domain name of the token. OPTIONAL per the exact-EVM scheme (only
          *  `assetTransferMethod` is required) — a foreign rail may omit it. NEVER assumed
          *  from the symbol (USDC's on-chain name() is "USD Coin", not "USDC"); a PipRail gate
@@ -95,6 +97,20 @@ interface X402ExactAcceptEntry {
         name?: string;
         /** EIP-712 domain version of the token (USDC: "2"). OPTIONAL (see `name`); read/re-derived on-chain. */
         version?: string;
+        /** **SVM only** — the merchant's fee-payer (sponsor) public key (base58), per the
+         *  x402 `exact` SVM scheme. The buyer compiles the transaction with this account as
+         *  the fee payer (so the buyer spends zero SOL on the network fee), leaving its
+         *  signature slot empty; the gate fills it and broadcasts. Distinct from `payTo` —
+         *  the fee payer must never appear in any instruction's accounts (a MUST-rule). */
+        feePayer?: string;
+        /** **SVM only, OPTIONAL** — a ≤256-byte reconciliation memo the buyer attaches to the
+         *  transaction (the SVM scheme's optional `extra.memo`). */
+        memo?: string;
+        /** **SVM only** — which SPL token program the mint belongs to, so both the buyer and
+         *  the gate derive the SAME associated-token-account address (an ATA's address depends
+         *  on the token program). Defaults to `'spl-token'` (classic) when absent — the
+         *  built-in USDC/USDT are classic. */
+        tokenProgram?: 'spl-token' | 'token-2022';
         /** Confirmations the gate waits for before granting access — mirrors the gate's
          *  `minConfirmations`, so the exact rail honours the same reorg safety as onchain-proof.
          *  A PipRail convenience (standard clients ignore unknown keys). */
@@ -190,8 +206,19 @@ interface Permit2PaymentPayload {
     signature: string;
     permit2Authorization: Permit2Authorization;
 }
-/** Either `exact`-rail payload shape — EIP-3009 (`authorization`) or Permit2 (`permit2Authorization`). */
-type ExactPaymentPayloadAny = ExactPaymentPayload | Permit2PaymentPayload;
+/**
+ * The `payload` a client sends for the **SVM (Solana) `exact`** variant: a base64-encoded,
+ * serialized, **partially-signed** versioned Solana transaction (the buyer's `TransferChecked`
+ * with the merchant as fee payer; the fee-payer signature slot is left empty for the gate to
+ * fill). Per `scheme_exact_svm.md`. The transaction itself IS the proof — there's no separate
+ * authorization object (the SVM analogue of EIP-3009's `authorization`).
+ */
+interface ExactSvmPaymentPayload {
+    transaction: string;
+}
+/** Any `exact`-rail payload shape — EIP-3009 (`authorization`), Permit2 (`permit2Authorization`),
+ *  or SVM (`transaction`). */
+type ExactPaymentPayloadAny = ExactPaymentPayload | Permit2PaymentPayload | ExactSvmPaymentPayload;
 interface ParsedExactBase {
     x402Version: number;
     /** The client's claimed network (slug or CAIP-2) — for matching, not trust. */
@@ -208,7 +235,8 @@ interface ParsedExactBase {
  * `network`/`asset` are the CLIENT's claim — used only to MATCH an offered rail; the gate
  * re-derives every verified field from its own trusted rail. A discriminated union on
  * `method`, so narrowing on `method` narrows `payload`: `'eip3009'` → {@link ExactPaymentPayload}
- * (`authorization`), `'permit2'` → {@link Permit2PaymentPayload} (`permit2Authorization`).
+ * (`authorization`), `'permit2'` → {@link Permit2PaymentPayload} (`permit2Authorization`),
+ * `'svm'` → {@link ExactSvmPaymentPayload} (`transaction`).
  */
 type ParsedExactPayment = (ParsedExactBase & {
     method: 'eip3009';
@@ -216,6 +244,9 @@ type ParsedExactPayment = (ParsedExactBase & {
 }) | (ParsedExactBase & {
     method: 'permit2';
     payload: Permit2PaymentPayload;
+}) | (ParsedExactBase & {
+    method: 'svm';
+    payload: ExactSvmPaymentPayload;
 });
 interface X402Receipt {
     scheme: 'onchain-proof' | 'exact';
@@ -4224,6 +4255,22 @@ interface DiscoverySigner {
     /** Sign an arbitrary UTF-8 message (EVM: eip191) — for proofs/SIWX only. */
     signMessage(message: string): Promise<string>;
 }
+/**
+ * How a family advertises a standard `exact` rail for one asset — returned by
+ * {@link ResolvedNetwork.resolveExactRail} and consumed by the gate to build the
+ * `X402ExactAcceptEntry`. The `method` is the family's transfer method (EVM:
+ * `'eip3009'`/`'permit2'`, Solana: `'svm'`); `extra` is merged VERBATIM into the
+ * accept's `extra`, carrying the family-specific bits a payer needs (EVM: the EIP-712
+ * `name`/`version`; Solana: the merchant `feePayer` + `tokenProgram`). Keeping the
+ * chain-specific shape behind this descriptor is what lets `server.ts` stay
+ * chain-agnostic — it never names a family, it just merges `extra`.
+ */
+interface ExactRailInfo {
+    method: 'eip3009' | 'permit2' | 'svm';
+    /** Family-specific `extra` keys merged into the exact accept (e.g. `{ name, version }`
+     *  for EVM EIP-3009, `{ feePayer, tokenProgram }` for Solana). */
+    extra?: Record<string, unknown>;
+}
 /**
  * A driver bound to one concrete network — what the gate and client hold. Each
  * method's error behaviour is fixed by the SDK error standard (see ERRORS.md §5):
@@ -4342,6 +4389,30 @@ interface ResolvedNetwork {
     discoverySigner?(wallet: WalletHandle): DiscoverySigner | null;
     /** Verify `ref` satisfies `accept`, RPC-only, in-process. */
     verify(ref: string, accept: X402AcceptEntry): Promise<VerifyResult>;
+    /**
+     * OPTIONAL — resolve a standard `exact` rail for `asset` on this network, or `null`
+     * when this asset/chain can't carry one (a native coin, an unsupported token, or a
+     * family with no `exact` settlement). This is the gate's rail-ADVERTISEMENT SPI: the
+     * chain-agnostic `server.ts` calls it to decide whether to dual-advertise an `exact`
+     * rail beside `onchain-proof`, and uses the returned {@link ExactRailInfo} to build the
+     * `X402ExactAcceptEntry` — so the gate never special-cases a family.
+     *
+     * `method` is the merchant's preference (`'auto'` lets the family pick — EVM auto-selects
+     * EIP-3009 over Permit2; Solana ignores it and always uses `'svm'`). The fee payer for a
+     * family that needs one (Solana) comes from EITHER `feePayer` (a facilitator-provided
+     * sponsor pubkey, in facilitator mode — so neither buyer nor merchant pays gas) OR `relayer`
+     * (the merchant's own bound self-settle wallet, in self mode); `feePayer` takes precedence.
+     * RPC-read (EVM reads the token's EIP-712 domain; Solana reads the mint's token program); MAY
+     * throw a typed config error for an explicitly-requested-but-unsupported method (EVM does). A
+     * family that omits this method offers no `exact` rail (today: every non-EVM, non-Solana family).
+     */
+    resolveExactRail?(input: {
+        asset: string;
+        method: 'eip3009' | 'permit2' | 'svm' | 'auto';
+        relayer?: WalletHandle;
+        /** A facilitator-provided fee-payer pubkey (facilitator mode); overrides the relayer's. */
+        feePayer?: string;
+    }): Promise<ExactRailInfo | null>;
     /**
      * OPTIONAL (EVM-only today) — the on-chain EIP-712 domain `{ name, version }` of an
      * EIP-3009 token `asset`, read from the contract (`name()`/`version()`). Returns
@@ -4763,7 +4834,7 @@ interface SpendSummary {
 }
 
 /** The payment schemes a client can settle: PipRail's native `onchain-proof` (the
- *  default) and the standard x402 `exact` rail (EVM + EIP-3009 only, opt-in). */
+ *  default) and the standard x402 `exact` rail (EVM EIP-3009/Permit2 + Solana SVM, opt-in). */
 type PaymentScheme = 'onchain-proof' | 'exact';
 
 /** Observability events. `ref` is the proof — a chain-specific id (EVM tx hash, Solana signature, TON locator, Stellar tx hash). */
@@ -5064,9 +5135,10 @@ interface PipRailClientOptions {
      *
      *   new PipRailClient({ chain: 'base', wallet, schemes: ['onchain-proof', 'exact'] })
      *
-     * `exact` is **EVM + EIP-3009 only** (USDC/EURC); it's silently ignored on a
-     * non-EVM chain, for USDT/native, or for a token the SDK can't price — those keep
-     * `onchain-proof`. The agent signs an EIP-3009 authorization with its OWN wallet
+     * `exact` is **EVM (EIP-3009/Permit2) + Solana (SVM)** today (USDC/EURC); it's
+     * silently ignored on a family without an `exact` rail, for native, or for a token the
+     * SDK can't price — those keep `onchain-proof`. The agent signs the authorization (an
+     * EIP-3009 message on EVM, a partial-signed transaction on Solana) with its OWN wallet
      * and the server / merchant-chosen facilitator broadcasts it (the buyer pays ~0
      * gas; PipRail hosts/settles nothing). The same `policy` + `onBeforePay` gate it
      * BEFORE signing. **Verify against your target facilitator before production.**
@@ -5251,7 +5323,7 @@ declare class PipRailClient {
      *   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).
      */
     discover(opts?: DiscoverOptions): Promise<DiscoveredResource[]>;
     /**
@@ -5744,31 +5816,41 @@ interface AcceptOption {
 /**
  * Opt into ALSO advertising a standard x402 `exact` rail beside the default
  * `onchain-proof` rail, so ANY standard x402 client can pay this gate (dual-advertise).
- * EVM ERC-20 only — **EIP-3009** (USDC, EURC) or, for tokens without it, **Permit2**
- * (any ERC-20 — e.g. Binance-Peg USDC on BNB, settled via the canonical
- * x402ExactPermit2Proxy). NOT native coins, NOT non-EVM chains. Omitting `exact` leaves
- * the gate byte-identical to today (onchain-proof only).
+ * Supported on **EVM ERC-20** — **EIP-3009** (USDC, EURC) or, for tokens without it, **Permit2**
+ * (any ERC-20 — e.g. Binance-Peg USDC on BNB, settled via the canonical x402ExactPermit2Proxy) —
+ * and on **Solana** (any SPL token; the buyer partial-signs a `TransferChecked` and your relayer
+ * is the fee payer). NOT native coins, NOT families without a standard `exact` scheme. Omitting
+ * `exact` leaves the gate byte-identical to today (onchain-proof only).
  *
  * Two settlement modes, both backendless (PipRail hosts nothing):
- *  - `settle: 'self'`  — your own `relayer` key broadcasts the settle (EIP-3009's
- *     `transferWithAuthorization`, or the proxy's `settle` for Permit2). You pay gas to
- *     RECEIVE (the inverse of onchain-proof) and keep the relayer funded. The signature
- *     binds the recipient, so there's no redirect risk. The on-brand default for the rail.
- *  - `settle: { facilitator }` — delegate verify+settle to a third-party x402
- *     facilitator YOU choose (Coinbase CDP, x402.org, …). No relayer key needed; the
- *     facilitator pays gas. Also the only path onto Coinbase's Bazaar directory.
+ *  - `settle: 'self'`  — your own `relayer` key broadcasts the settle (EVM EIP-3009's
+ *     `transferWithAuthorization` / the proxy's `settle` for Permit2; on Solana, co-signing the
+ *     buyer's transaction as the fee payer). You pay gas to RECEIVE (the inverse of onchain-proof)
+ *     and keep the relayer funded. The signature binds the recipient, so there's no redirect risk.
+ *     The on-brand backendless default for the rail.
+ *  - `settle: { facilitator }` — delegate verify+settle to a third-party x402 facilitator YOU
+ *     choose. **The facilitator pays the gas, so neither the buyer nor the merchant pays any** —
+ *     fully gasless end to end. On **EVM** use Coinbase CDP, x402.org, PayAI, …; on **Solana** use a
+ *     facilitator that sponsors the fee payer (e.g. PayAI's `https://facilitator.payai.network`,
+ *     no API key) — the gate reads its fee-payer pubkey from `GET /supported` automatically. No
+ *     relayer key needed. (EVM facilitators are also the path onto Coinbase's Bazaar directory.)
  */
 interface ExactRailOption {
     settle: 'self' | {
         facilitator: string;
         authHeaders?: () => Promise<Record<string, string>>;
+        /** Solana only — the facilitator's fee-payer pubkey, if you'd rather set it than have the
+         *  gate read it from the facilitator's `GET /supported`. Optional: omitted, the gate
+         *  discovers it automatically (e.g. PayAI). Ignored on EVM. */
+        feePayer?: string;
     };
-    /** Required for `settle: 'self'` — the gas-paying relayer wallet: EVM `{ privateKey }`
-     *  or a bring-your-own `{ walletClient }`. (Distinct from `payTo`, the receive address.) */
+    /** Required for `settle: 'self'` — the gas-paying relayer wallet: EVM `{ privateKey }` /
+     *  `{ walletClient }`, or Solana `{ secretKey }` / `{ signer }`. (Distinct from `payTo`, the
+     *  receive address — on Solana they MUST be different keys, a scheme MUST-rule.) */
     relayer?: unknown;
-    /** Which exact-EVM transfer method to advertise. `'auto'` (default) uses EIP-3009 when the
+    /** Which exact transfer method to advertise (EVM). `'auto'` (default) uses EIP-3009 when the
      *  token supports it, else Permit2 — so a non-EIP-3009 token like Binance-Peg USDC on BNB
-     *  "just works". Force `'eip3009'` or `'permit2'` to pin one. */
+     *  "just works". Force `'eip3009'` or `'permit2'` to pin one. Ignored on Solana (always SVM). */
     method?: 'eip3009' | 'permit2' | 'auto';
 }
 interface RequirePaymentOptions {
@@ -5840,8 +5922,8 @@ interface RequirePaymentOptions {
      */
     awaitOnPaid?: boolean;
     /**
-     * ALSO advertise a standard x402 `exact` rail (EIP-3009) so any standard x402
-     * client can pay this gate — opt-in, EVM/EIP-3009 only. See {@link ExactRailOption}.
+     * ALSO advertise a standard x402 `exact` rail so any standard x402 client can pay this
+     * gate — opt-in, EVM (EIP-3009/Permit2) + Solana (SVM). See {@link ExactRailOption}.
      * Omit to keep the gate exactly as today (`onchain-proof` only).
      */
     exact?: ExactRailOption;
@@ -5963,7 +6045,9 @@ declare function requirePayment(options: RequirePaymentOptions): ExpressLikeMidd
  * SELF-settling merchant must guard replay itself (the gate's used-proof set does).
  */
 
-/** Standard x402 `exact` PaymentRequirements, built from the gate's TRUSTED rail. */
+/** Standard x402 `exact` PaymentRequirements, built from the gate's TRUSTED rail. `extra`
+ *  carries the scheme's chain-specific fields: EVM EIP-3009 → `{ name, version }` (the token's
+ *  EIP-712 domain), Solana SVM → `{ feePayer }` (the facilitator's fee-payer pubkey). */
 interface FacilitatorPaymentRequirements {
     scheme: 'exact';
     network: string;
@@ -5971,10 +6055,7 @@ interface FacilitatorPaymentRequirements {
     amount: string;
     payTo: string;
     maxTimeoutSeconds: number;
-    extra: {
-        name: string;
-        version: string;
-    };
+    extra: Record<string, unknown>;
 }
 /** A merchant-chosen facilitator: its base URL + optional per-request auth headers. */
 interface FacilitatorConfig {

package/dist/index.d.ts

@@ -82,12 +82,14 @@ interface X402ExactAcceptEntry {
     payTo: AddressId;
     maxTimeoutSeconds: number;
     extra: {
-        /** The exact-EVM transfer method, per the x402 `exact` EVM scheme: `'eip3009'`
-         *  for tokens with native `transferWithAuthorization`, or `'permit2'` for tokens
-         *  WITHOUT it (e.g. Binance-Peg USDC on BNB) — the payer signs a Permit2 witness
-         *  transfer whose `spender` is the canonical x402ExactPermit2Proxy and whose
-         *  `witness.to` binds the recipient. PipRail self-settles BOTH. */
-        assetTransferMethod: 'eip3009' | 'permit2';
+        /** The exact transfer method. EVM: `'eip3009'` for tokens with native
+         *  `transferWithAuthorization`, or `'permit2'` for tokens WITHOUT it (e.g.
+         *  Binance-Peg USDC on BNB) — the payer signs a Permit2 witness transfer whose
+         *  `spender` is the canonical x402ExactPermit2Proxy and whose `witness.to` binds the
+         *  recipient. **Solana (SVM): `'svm'`** — the payer partial-signs an SPL
+         *  `TransferChecked` transaction whose fee payer is the merchant (`feePayer` below),
+         *  and the gate co-signs as fee payer + broadcasts. PipRail self-settles ALL. */
+        assetTransferMethod: 'eip3009' | 'permit2' | 'svm';
         /** EIP-712 domain name of the token. OPTIONAL per the exact-EVM scheme (only
          *  `assetTransferMethod` is required) — a foreign rail may omit it. NEVER assumed
          *  from the symbol (USDC's on-chain name() is "USD Coin", not "USDC"); a PipRail gate
@@ -95,6 +97,20 @@ interface X402ExactAcceptEntry {
         name?: string;
         /** EIP-712 domain version of the token (USDC: "2"). OPTIONAL (see `name`); read/re-derived on-chain. */
         version?: string;
+        /** **SVM only** — the merchant's fee-payer (sponsor) public key (base58), per the
+         *  x402 `exact` SVM scheme. The buyer compiles the transaction with this account as
+         *  the fee payer (so the buyer spends zero SOL on the network fee), leaving its
+         *  signature slot empty; the gate fills it and broadcasts. Distinct from `payTo` —
+         *  the fee payer must never appear in any instruction's accounts (a MUST-rule). */
+        feePayer?: string;
+        /** **SVM only, OPTIONAL** — a ≤256-byte reconciliation memo the buyer attaches to the
+         *  transaction (the SVM scheme's optional `extra.memo`). */
+        memo?: string;
+        /** **SVM only** — which SPL token program the mint belongs to, so both the buyer and
+         *  the gate derive the SAME associated-token-account address (an ATA's address depends
+         *  on the token program). Defaults to `'spl-token'` (classic) when absent — the
+         *  built-in USDC/USDT are classic. */
+        tokenProgram?: 'spl-token' | 'token-2022';
         /** Confirmations the gate waits for before granting access — mirrors the gate's
          *  `minConfirmations`, so the exact rail honours the same reorg safety as onchain-proof.
          *  A PipRail convenience (standard clients ignore unknown keys). */
@@ -190,8 +206,19 @@ interface Permit2PaymentPayload {
     signature: string;
     permit2Authorization: Permit2Authorization;
 }
-/** Either `exact`-rail payload shape — EIP-3009 (`authorization`) or Permit2 (`permit2Authorization`). */
-type ExactPaymentPayloadAny = ExactPaymentPayload | Permit2PaymentPayload;
+/**
+ * The `payload` a client sends for the **SVM (Solana) `exact`** variant: a base64-encoded,
+ * serialized, **partially-signed** versioned Solana transaction (the buyer's `TransferChecked`
+ * with the merchant as fee payer; the fee-payer signature slot is left empty for the gate to
+ * fill). Per `scheme_exact_svm.md`. The transaction itself IS the proof — there's no separate
+ * authorization object (the SVM analogue of EIP-3009's `authorization`).
+ */
+interface ExactSvmPaymentPayload {
+    transaction: string;
+}
+/** Any `exact`-rail payload shape — EIP-3009 (`authorization`), Permit2 (`permit2Authorization`),
+ *  or SVM (`transaction`). */
+type ExactPaymentPayloadAny = ExactPaymentPayload | Permit2PaymentPayload | ExactSvmPaymentPayload;
 interface ParsedExactBase {
     x402Version: number;
     /** The client's claimed network (slug or CAIP-2) — for matching, not trust. */
@@ -208,7 +235,8 @@ interface ParsedExactBase {
  * `network`/`asset` are the CLIENT's claim — used only to MATCH an offered rail; the gate
  * re-derives every verified field from its own trusted rail. A discriminated union on
  * `method`, so narrowing on `method` narrows `payload`: `'eip3009'` → {@link ExactPaymentPayload}
- * (`authorization`), `'permit2'` → {@link Permit2PaymentPayload} (`permit2Authorization`).
+ * (`authorization`), `'permit2'` → {@link Permit2PaymentPayload} (`permit2Authorization`),
+ * `'svm'` → {@link ExactSvmPaymentPayload} (`transaction`).
  */
 type ParsedExactPayment = (ParsedExactBase & {
     method: 'eip3009';
@@ -216,6 +244,9 @@ type ParsedExactPayment = (ParsedExactBase & {
 }) | (ParsedExactBase & {
     method: 'permit2';
     payload: Permit2PaymentPayload;
+}) | (ParsedExactBase & {
+    method: 'svm';
+    payload: ExactSvmPaymentPayload;
 });
 interface X402Receipt {
     scheme: 'onchain-proof' | 'exact';
@@ -4224,6 +4255,22 @@ interface DiscoverySigner {
     /** Sign an arbitrary UTF-8 message (EVM: eip191) — for proofs/SIWX only. */
     signMessage(message: string): Promise<string>;
 }
+/**
+ * How a family advertises a standard `exact` rail for one asset — returned by
+ * {@link ResolvedNetwork.resolveExactRail} and consumed by the gate to build the
+ * `X402ExactAcceptEntry`. The `method` is the family's transfer method (EVM:
+ * `'eip3009'`/`'permit2'`, Solana: `'svm'`); `extra` is merged VERBATIM into the
+ * accept's `extra`, carrying the family-specific bits a payer needs (EVM: the EIP-712
+ * `name`/`version`; Solana: the merchant `feePayer` + `tokenProgram`). Keeping the
+ * chain-specific shape behind this descriptor is what lets `server.ts` stay
+ * chain-agnostic — it never names a family, it just merges `extra`.
+ */
+interface ExactRailInfo {
+    method: 'eip3009' | 'permit2' | 'svm';
+    /** Family-specific `extra` keys merged into the exact accept (e.g. `{ name, version }`
+     *  for EVM EIP-3009, `{ feePayer, tokenProgram }` for Solana). */
+    extra?: Record<string, unknown>;
+}
 /**
  * A driver bound to one concrete network — what the gate and client hold. Each
  * method's error behaviour is fixed by the SDK error standard (see ERRORS.md §5):
@@ -4342,6 +4389,30 @@ interface ResolvedNetwork {
     discoverySigner?(wallet: WalletHandle): DiscoverySigner | null;
     /** Verify `ref` satisfies `accept`, RPC-only, in-process. */
     verify(ref: string, accept: X402AcceptEntry): Promise<VerifyResult>;
+    /**
+     * OPTIONAL — resolve a standard `exact` rail for `asset` on this network, or `null`
+     * when this asset/chain can't carry one (a native coin, an unsupported token, or a
+     * family with no `exact` settlement). This is the gate's rail-ADVERTISEMENT SPI: the
+     * chain-agnostic `server.ts` calls it to decide whether to dual-advertise an `exact`
+     * rail beside `onchain-proof`, and uses the returned {@link ExactRailInfo} to build the
+     * `X402ExactAcceptEntry` — so the gate never special-cases a family.
+     *
+     * `method` is the merchant's preference (`'auto'` lets the family pick — EVM auto-selects
+     * EIP-3009 over Permit2; Solana ignores it and always uses `'svm'`). The fee payer for a
+     * family that needs one (Solana) comes from EITHER `feePayer` (a facilitator-provided
+     * sponsor pubkey, in facilitator mode — so neither buyer nor merchant pays gas) OR `relayer`
+     * (the merchant's own bound self-settle wallet, in self mode); `feePayer` takes precedence.
+     * RPC-read (EVM reads the token's EIP-712 domain; Solana reads the mint's token program); MAY
+     * throw a typed config error for an explicitly-requested-but-unsupported method (EVM does). A
+     * family that omits this method offers no `exact` rail (today: every non-EVM, non-Solana family).
+     */
+    resolveExactRail?(input: {
+        asset: string;
+        method: 'eip3009' | 'permit2' | 'svm' | 'auto';
+        relayer?: WalletHandle;
+        /** A facilitator-provided fee-payer pubkey (facilitator mode); overrides the relayer's. */
+        feePayer?: string;
+    }): Promise<ExactRailInfo | null>;
     /**
      * OPTIONAL (EVM-only today) — the on-chain EIP-712 domain `{ name, version }` of an
      * EIP-3009 token `asset`, read from the contract (`name()`/`version()`). Returns
@@ -4763,7 +4834,7 @@ interface SpendSummary {
 }
 
 /** The payment schemes a client can settle: PipRail's native `onchain-proof` (the
- *  default) and the standard x402 `exact` rail (EVM + EIP-3009 only, opt-in). */
+ *  default) and the standard x402 `exact` rail (EVM EIP-3009/Permit2 + Solana SVM, opt-in). */
 type PaymentScheme = 'onchain-proof' | 'exact';
 
 /** Observability events. `ref` is the proof — a chain-specific id (EVM tx hash, Solana signature, TON locator, Stellar tx hash). */
@@ -5064,9 +5135,10 @@ interface PipRailClientOptions {
      *
      *   new PipRailClient({ chain: 'base', wallet, schemes: ['onchain-proof', 'exact'] })
      *
-     * `exact` is **EVM + EIP-3009 only** (USDC/EURC); it's silently ignored on a
-     * non-EVM chain, for USDT/native, or for a token the SDK can't price — those keep
-     * `onchain-proof`. The agent signs an EIP-3009 authorization with its OWN wallet
+     * `exact` is **EVM (EIP-3009/Permit2) + Solana (SVM)** today (USDC/EURC); it's
+     * silently ignored on a family without an `exact` rail, for native, or for a token the
+     * SDK can't price — those keep `onchain-proof`. The agent signs the authorization (an
+     * EIP-3009 message on EVM, a partial-signed transaction on Solana) with its OWN wallet
      * and the server / merchant-chosen facilitator broadcasts it (the buyer pays ~0
      * gas; PipRail hosts/settles nothing). The same `policy` + `onBeforePay` gate it
      * BEFORE signing. **Verify against your target facilitator before production.**
@@ -5251,7 +5323,7 @@ declare class PipRailClient {
      *   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).
      */
     discover(opts?: DiscoverOptions): Promise<DiscoveredResource[]>;
     /**
@@ -5744,31 +5816,41 @@ interface AcceptOption {
 /**
  * Opt into ALSO advertising a standard x402 `exact` rail beside the default
  * `onchain-proof` rail, so ANY standard x402 client can pay this gate (dual-advertise).
- * EVM ERC-20 only — **EIP-3009** (USDC, EURC) or, for tokens without it, **Permit2**
- * (any ERC-20 — e.g. Binance-Peg USDC on BNB, settled via the canonical
- * x402ExactPermit2Proxy). NOT native coins, NOT non-EVM chains. Omitting `exact` leaves
- * the gate byte-identical to today (onchain-proof only).
+ * Supported on **EVM ERC-20** — **EIP-3009** (USDC, EURC) or, for tokens without it, **Permit2**
+ * (any ERC-20 — e.g. Binance-Peg USDC on BNB, settled via the canonical x402ExactPermit2Proxy) —
+ * and on **Solana** (any SPL token; the buyer partial-signs a `TransferChecked` and your relayer
+ * is the fee payer). NOT native coins, NOT families without a standard `exact` scheme. Omitting
+ * `exact` leaves the gate byte-identical to today (onchain-proof only).
  *
  * Two settlement modes, both backendless (PipRail hosts nothing):
- *  - `settle: 'self'`  — your own `relayer` key broadcasts the settle (EIP-3009's
- *     `transferWithAuthorization`, or the proxy's `settle` for Permit2). You pay gas to
- *     RECEIVE (the inverse of onchain-proof) and keep the relayer funded. The signature
- *     binds the recipient, so there's no redirect risk. The on-brand default for the rail.
- *  - `settle: { facilitator }` — delegate verify+settle to a third-party x402
- *     facilitator YOU choose (Coinbase CDP, x402.org, …). No relayer key needed; the
- *     facilitator pays gas. Also the only path onto Coinbase's Bazaar directory.
+ *  - `settle: 'self'`  — your own `relayer` key broadcasts the settle (EVM EIP-3009's
+ *     `transferWithAuthorization` / the proxy's `settle` for Permit2; on Solana, co-signing the
+ *     buyer's transaction as the fee payer). You pay gas to RECEIVE (the inverse of onchain-proof)
+ *     and keep the relayer funded. The signature binds the recipient, so there's no redirect risk.
+ *     The on-brand backendless default for the rail.
+ *  - `settle: { facilitator }` — delegate verify+settle to a third-party x402 facilitator YOU
+ *     choose. **The facilitator pays the gas, so neither the buyer nor the merchant pays any** —
+ *     fully gasless end to end. On **EVM** use Coinbase CDP, x402.org, PayAI, …; on **Solana** use a
+ *     facilitator that sponsors the fee payer (e.g. PayAI's `https://facilitator.payai.network`,
+ *     no API key) — the gate reads its fee-payer pubkey from `GET /supported` automatically. No
+ *     relayer key needed. (EVM facilitators are also the path onto Coinbase's Bazaar directory.)
  */
 interface ExactRailOption {
     settle: 'self' | {
         facilitator: string;
         authHeaders?: () => Promise<Record<string, string>>;
+        /** Solana only — the facilitator's fee-payer pubkey, if you'd rather set it than have the
+         *  gate read it from the facilitator's `GET /supported`. Optional: omitted, the gate
+         *  discovers it automatically (e.g. PayAI). Ignored on EVM. */
+        feePayer?: string;
     };
-    /** Required for `settle: 'self'` — the gas-paying relayer wallet: EVM `{ privateKey }`
-     *  or a bring-your-own `{ walletClient }`. (Distinct from `payTo`, the receive address.) */
+    /** Required for `settle: 'self'` — the gas-paying relayer wallet: EVM `{ privateKey }` /
+     *  `{ walletClient }`, or Solana `{ secretKey }` / `{ signer }`. (Distinct from `payTo`, the
+     *  receive address — on Solana they MUST be different keys, a scheme MUST-rule.) */
     relayer?: unknown;
-    /** Which exact-EVM transfer method to advertise. `'auto'` (default) uses EIP-3009 when the
+    /** Which exact transfer method to advertise (EVM). `'auto'` (default) uses EIP-3009 when the
      *  token supports it, else Permit2 — so a non-EIP-3009 token like Binance-Peg USDC on BNB
-     *  "just works". Force `'eip3009'` or `'permit2'` to pin one. */
+     *  "just works". Force `'eip3009'` or `'permit2'` to pin one. Ignored on Solana (always SVM). */
     method?: 'eip3009' | 'permit2' | 'auto';
 }
 interface RequirePaymentOptions {
@@ -5840,8 +5922,8 @@ interface RequirePaymentOptions {
      */
     awaitOnPaid?: boolean;
     /**
-     * ALSO advertise a standard x402 `exact` rail (EIP-3009) so any standard x402
-     * client can pay this gate — opt-in, EVM/EIP-3009 only. See {@link ExactRailOption}.
+     * ALSO advertise a standard x402 `exact` rail so any standard x402 client can pay this
+     * gate — opt-in, EVM (EIP-3009/Permit2) + Solana (SVM). See {@link ExactRailOption}.
      * Omit to keep the gate exactly as today (`onchain-proof` only).
      */
     exact?: ExactRailOption;
@@ -5963,7 +6045,9 @@ declare function requirePayment(options: RequirePaymentOptions): ExpressLikeMidd
  * SELF-settling merchant must guard replay itself (the gate's used-proof set does).
  */
 
-/** Standard x402 `exact` PaymentRequirements, built from the gate's TRUSTED rail. */
+/** Standard x402 `exact` PaymentRequirements, built from the gate's TRUSTED rail. `extra`
+ *  carries the scheme's chain-specific fields: EVM EIP-3009 → `{ name, version }` (the token's
+ *  EIP-712 domain), Solana SVM → `{ feePayer }` (the facilitator's fee-payer pubkey). */
 interface FacilitatorPaymentRequirements {
     scheme: 'exact';
     network: string;
@@ -5971,10 +6055,7 @@ interface FacilitatorPaymentRequirements {
     amount: string;
     payTo: string;
     maxTimeoutSeconds: number;
-    extra: {
-        name: string;
-        version: string;
-    };
+    extra: Record<string, unknown>;
 }
 /** A merchant-chosen facilitator: its base URL + optional per-request auth headers. */
 interface FacilitatorConfig {