@piprail/sdk 2.15.1 → 2.16.0

package/dist/{ledger-uFtXlIHY.d.cts → ledger-Crc1bZox.d.cts}

@@ -75,8 +75,28 @@ interface X402ExactAcceptEntry {
     asset: AssetId;
     payTo: AddressId;
     maxTimeoutSeconds: number;
-    extra: {
-        /** The exact transfer method. EVM: `'eip3009'` for tokens with native
+    /**
+     * The network id EXACTLY as an x402 **v1** server wrote it (a slug like `'base'`),
+     * preserved by {@link normalizeV1Challenge} because `network` above is canonicalised to
+     * CAIP-2 for matching while a v1 server string-compares the slug it sent. Internal to the
+     * v1 compat path — absent on every v2 rail, and STRIPPED from every outgoing `accepted`
+     * echo by `withoutWireNetwork`, since the merchant never published this key.
+     */
+    wireNetwork?: string;
+    /**
+     * Scheme-defined extras. **OPTIONAL when PARSING a foreign 402** — the exact-EVM scheme
+     * makes every `extra` key optional (`assetTransferMethod` defaults to `'eip3009'`), and the
+     * SVM/Algorand/Aptos/NEAR/Hedera schemes define no `assetTransferMethod` at all, so a
+     * conformant rail may ship `extra: {}` or omit the block entirely. A PipRail **gate** always
+     * emits it. Every read on the buyer path must optional-chain.
+     */
+    extra?: {
+        /** The exact transfer method. **OPTIONAL** — `scheme_exact_evm.md`: *"If no
+         *  `assetTransferMethod` is specified in `PaymentRequired.extra`, clients should default
+         *  to `\"eip3009\"`"* (and only the non-default methods make it required). The SVM,
+         *  Algorand, Aptos, NEAR and Hedera schemes never define this key. Read it through
+         *  {@link exactTransferMethod}, never bare — 91% of the deployed x402 web omits it.
+         *  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
@@ -92,13 +112,46 @@ interface X402ExactAcceptEntry {
          *  authorizing exactly one NEP-141 `ft_transfer` to `payTo` (per `scheme_exact_near.md`); a
          *  facilitator-selected relayer (`feePayer` below) prepays gas + the 1 yoctoNEAR and submits, so
          *  the buyer holds zero NEAR. PipRail self-settles ALL. */
-        assetTransferMethod: 'eip3009' | 'permit2'
+        assetTransferMethod?: 'eip3009' | 'permit2'
         /** A FOREIGN-dialect alias for `'permit2'` — Binance's x402 ("b402") facilitator labels its
          *  EVM-Permit2 exact rail `'permit2-exact'` (the coinbase/x402 spec uses bare `'permit2'`).
          *  PipRail EMITS only `'permit2'`; it TOLERATES `'permit2-exact'` inbound so the buyer pays a
          *  Binance-issued 402 (the buyer treats the two as one rail). NB: settlement still requires the
          *  rail to bind PipRail's canonical x402ExactPermit2Proxy — see the buyer in drivers/evm. */
-         | 'permit2-exact' | 'svm' | 'algorand' | 'aptos' | 'near';
+         | 'permit2-exact' | 'svm' | 'algorand' | 'aptos' | 'near'
+        /** **XRPL** — the ledger has exactly ONE way to move value (a `Payment`), so
+         *  `scheme_exact_xrpl.md` spends this field on SEQUENCING instead of mechanism.
+         *  `'sequence'` (the DEFAULT, and what all 1,732 live XRPL rails mean by omitting it) uses
+         *  the payer's account sequence; `'ticketSequence'` sets `Sequence: 0` and supplies a
+         *  pre-minted `TicketSequence`, letting a payer sign several payments that settle out of
+         *  order. */
+         | 'sequence' | 'ticketSequence';
+        /** **XRPL, REQUIRED by the scheme — and absent from 100% of live rails.** The spec says it
+         *  "must be false" (XRPL charges the fee to the transaction's own `Account`, so the payer
+         *  always pays). Read it as *false unless present*: REQUIRING it would reject the entire
+         *  deployed XRPL x402 web, which is exactly the bug class `assetTransferMethod` already caused
+         *  once. A rail that explicitly says `true` is refused — we cannot honour a sponsor here. */
+        areFeesSponsored?: boolean;
+        /** **XRPL** — the issuer's classic address for an IOU rail (RLUSD and friends). Required by the
+         *  scheme for issued currencies, absent for native XRP; present on 869 of the 1,732 live rails,
+         *  which is precisely the IOU half. Also the discriminator the buyer uses to pick the
+         *  issued-currency `Amount` object over a bare drops string. */
+        issuer?: string;
+        /** **XRPL, OPTIONAL** — an opaque invoice identifier. When present the buyer MUST set the
+         *  transaction's `InvoiceID` to its **SHA-256**, as 32-byte hex; that hash is the challenge
+         *  binding on this rail (there is no memo — the scheme has facilitators REJECT `Memos`).
+         *  Present on 1,732 of 1,732 live rails, so treat it as always-on in practice. */
+        invoiceId?: string;
+        /** **XRPL** — a vendor correlation tag, copied verbatim into the transaction's `SourceTag`.
+         *  NOT in `scheme_exact_xrpl.md`'s extra table, but present on **1,728 of the 1,732** live XRPL
+         *  rails: it is how the deployed vendors match a payment back to their own quote. Mirrored
+         *  because it costs nothing and omitting it is a plausible reason a merchant refuses. */
+        sourceTag?: number;
+        /** **XRPL, OPTIONAL** — a destination tag the buyer MUST copy verbatim into the transaction
+         *  when the rail states one (hosted/exchange accounts route deposits by it). Never invented
+         *  when absent: unlike the onchain-proof path, which derives a tag from the nonce, the exact
+         *  rail sets `DestinationTag` only if the merchant asked for one. */
+        destinationTag?: number;
         /** 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
@@ -132,6 +185,42 @@ interface X402ExactAcceptEntry {
         symbol?: string;
     };
 }
+/**
+ * The transfer method an `exact` rail uses when it names none.
+ *
+ * `scheme_exact_evm.md` §0: *"If no `assetTransferMethod` is specified in
+ * `PaymentRequired.extra`, clients should default to `"eip3009"`."* §1 restates it per-method:
+ * `eip3009` is *"optional in `PaymentRequired`, default"*, while `permit2` and `erc7710` are
+ * *"required"*. So an absent marker is not a malformed rail — it is the common case (91% of the
+ * deployed web) and it means EIP-3009.
+ */
+declare const DEFAULT_EXACT_TRANSFER_METHOD: "eip3009";
+/**
+ * Every `assetTransferMethod` a PipRail buyer can actually sign, across all families.
+ *
+ * Used to SKIP a rail that names a method we don't implement (the spec's `erc7710`, or any
+ * future one) rather than sign an EIP-3009 authorization a facilitator built for a different
+ * mechanism and will reject. An **absent** marker is not "unknown" — see
+ * {@link DEFAULT_EXACT_TRANSFER_METHOD}. Family routing stays in each driver's `payExact`;
+ * this set only answers "could any driver of ours settle this?".
+ */
+declare const KNOWN_EXACT_TRANSFER_METHODS: ReadonlySet<string>;
+/**
+ * The effective transfer method of an `exact` rail: what it names, or the default when it names
+ * nothing. THE ONLY sanctioned way to read `extra.assetTransferMethod` — reading it bare is how
+ * the buyer came to reject 91% of the x402 web.
+ *
+ * Pass `family` to get the right default off-EVM: a Solana rail that names nothing means `svm`,
+ * not `eip3009`. Without it the EVM default is assumed (correct for the settleability check,
+ * since every family's own literal is in {@link KNOWN_EXACT_TRANSFER_METHODS} anyway).
+ */
+declare function exactTransferMethod(accept: X402ExactAcceptEntry, family?: string): string;
+/**
+ * Can any PipRail driver settle this rail's transfer method? True when the rail names a
+ * method we implement, AND when it names none (the spec default `eip3009`). False only for a
+ * method we don't implement — the rail is then skipped at gather rather than mis-signed.
+ */
+declare function isSettleableExactMethod(accept: X402ExactAcceptEntry): boolean;
 /**
  * A standard x402 `upto` rail (EVM / Permit2) — variable-amount / metered billing.
  * The buyer signs a Permit2 `PermitWitnessTransferFrom` authorization for `amount`
@@ -181,7 +270,13 @@ interface X402UptoAcceptEntry {
  *  rail, or a standard `upto` (metered) rail. */
 type X402AnyAccept = X402AcceptEntry | X402ExactAcceptEntry | X402UptoAcceptEntry;
 interface X402Challenge {
-    x402Version: 2;
+    /**
+     * `2` for every challenge PipRail EMITS. `1` appears only on the PARSE side, when
+     * {@link normalizeV1Challenge} has lifted a still-deployed v1 server's body into this
+     * shape — the buyer must then answer on the v1 wire (`X-PAYMENT`, flat payload). See the
+     * version-posture note above {@link HEADER_SIGNATURE_V1}.
+     */
+    x402Version: 1 | 2;
     /**
      * Optional human-readable reason (v2 `error?: string`). PipRail EMITS it only on a
      * rejected-proof re-challenge (omitted on a fresh challenge). Typed to also tolerate
@@ -361,10 +456,25 @@ interface ExactNearPaymentPayload {
     /** Base64 of the Borsh-encoded NEP-366 `SignedDelegateAction` (one `ft_transfer`). */
     signedDelegateAction: string;
 }
+/**
+ * The `payload` a client sends for the **XRPL `exact`** variant, per `scheme_exact_xrpl.md`:
+ * a **fully signed** XRPL `Payment` transaction, hex-encoded, that the resource server (or its
+ * facilitator) submits. The signed blob IS the proof — there is no separate authorization object.
+ *
+ * XRPL is the one family where **the payer pays the network fee**: the fee is a field inside the
+ * signed transaction and the ledger charges it to `Account`. So there is no sponsor, no fee-payer
+ * co-signature, and no fee-drain guard to write — the buyer needs XRP for the amount *and* the fee.
+ * That also means the buyer signs something immediately submittable, so `LastLedgerSequence` is
+ * mandatory: it is the only thing bounding how long the merchant may sit on it.
+ */
+interface ExactXrplPaymentPayload {
+    /** Hex-encoded, fully signed XRPL `Payment` transaction blob. */
+    signedTxBlob: string;
+}
 /** Any `exact`-rail payload shape — EIP-3009 (`authorization`), Permit2 (`permit2Authorization`),
- *  SVM (`transaction`), Algorand (`paymentGroup`), Aptos (`transaction` + `senderAuth`), or NEAR
- *  (`signedDelegateAction`). */
-type ExactPaymentPayloadAny = ExactPaymentPayload | Permit2PaymentPayload | ExactSvmPaymentPayload | ExactAlgorandPaymentPayload | ExactAptosPaymentPayload | ExactNearPaymentPayload;
+ *  SVM (`transaction`), Algorand (`paymentGroup`), Aptos (`transaction` + `senderAuth`), NEAR
+ *  (`signedDelegateAction`), or XRPL (`signedTxBlob`). */
+type ExactPaymentPayloadAny = ExactPaymentPayload | Permit2PaymentPayload | ExactSvmPaymentPayload | ExactAlgorandPaymentPayload | ExactAptosPaymentPayload | ExactNearPaymentPayload | ExactXrplPaymentPayload;
 interface ParsedExactBase {
     x402Version: number;
     /** The client's claimed network (slug or CAIP-2) — for matching, not trust. */
@@ -385,7 +495,9 @@ interface ParsedExactBase {
  * `'svm'` → {@link ExactSvmPaymentPayload} (`transaction`), `'algorand'` →
  * {@link ExactAlgorandPaymentPayload} (`paymentGroup`); `'aptos'` →
  * {@link ExactAptosPaymentPayload} (`transaction` + `senderAuth`); `'near'` →
- * {@link ExactNearPaymentPayload} (`signedDelegateAction`).
+ * {@link ExactNearPaymentPayload} (`signedDelegateAction`); `'sequence'` / `'ticketSequence'` →
+ * {@link ExactXrplPaymentPayload} (`signedTxBlob`) — XRPL is the one family whose method literal
+ * names the SEQUENCING strategy rather than a transfer mechanism, because it has only one.
  */
 type ParsedExactPayment = (ParsedExactBase & {
     method: 'eip3009';
@@ -405,6 +517,12 @@ type ParsedExactPayment = (ParsedExactBase & {
 }) | (ParsedExactBase & {
     method: 'near';
     payload: ExactNearPaymentPayload;
+}) | (ParsedExactBase & {
+    method: 'sequence';
+    payload: ExactXrplPaymentPayload;
+}) | (ParsedExactBase & {
+    method: 'ticketSequence';
+    payload: ExactXrplPaymentPayload;
 });
 /**
  * What {@link parseUptoPaymentHeader} extracts from an inbound `upto` payment — the
@@ -648,6 +766,25 @@ declare function buildUptoSignatureHeader(input: {
     accepted: X402UptoAcceptEntry;
     payload: Permit2UptoPaymentPayload;
 }): string;
+/**
+ * Build the **v1** `X-PAYMENT` header value — the flat, pre-v2 payload shape
+ * `{ x402Version: 1, scheme, network, payload }`, base64-JSON.
+ *
+ * This is the `encodeXPaymentHeader` utility the version-posture note above has always
+ * described; it had never been written, so the buyer could parse nothing from a v1 server and
+ * could answer nothing either. Needed because v2 moved the header `X-PAYMENT` →
+ * `PAYMENT-SIGNATURE` and reshaped the payload: a v1 server ignores `PAYMENT-SIGNATURE`
+ * entirely (verified live — it just re-challenges) and reads only `X-PAYMENT`.
+ *
+ * `network` MUST be the slug the v1 server itself sent (`X402ExactAcceptEntry.wireNetwork`),
+ * not our canonical CAIP-2: v1 verifiers string-compare it against their own requirement.
+ * There is no `accepted` echo in v1 — the chosen rail is identified by these two flat fields.
+ */
+declare function buildV1PaymentHeader(input: {
+    scheme: string;
+    network: string;
+    payload: unknown;
+}): string;
 /**
  * Parse the PAYMENT-REQUIRED challenge from a 402 response. Prefers the
  * `payment-required` header, falls back to the JSON body.
@@ -747,6 +884,23 @@ declare function parseUptoPaymentHeader(value: string): ParsedUptoPayment | null
  * base64 wrapper, byte-identical to before this split on the HTTP path.
  */
 declare function parseUptoObject(parsed: unknown): ParsedUptoPayment | null;
+/**
+ * Lift an x402 **v1** challenge body into the internal {@link X402Challenge} shape, so the
+ * whole buyer path downstream of `parseChallenge` stays v2-only and version-blind.
+ *
+ * Four v1→v2 skews are absorbed, and nothing else is touched (unknown keys ride along
+ * verbatim, so a facilitator's extras survive):
+ *  1. `maxAmountRequired` → `amount` (v2's rename). An accept that already has `amount` keeps it.
+ *  2. slug `network` (`'base'`) → CAIP-2 (`'eip155:8453'`) so the gather's `supports()` matches,
+ *     with the ORIGINAL preserved on {@link X402ExactAcceptEntry.wireNetwork} because the v1
+ *     server string-compares the slug it sent when we echo it back.
+ *  3. per-accept `resource` string → a top-level `resource` object (first accept that has one).
+ *  4. `x402Version: 1` is KEPT on the result — it is what tells `payExactRail` to answer on the
+ *     v1 wire (`X-PAYMENT`, flat payload) instead of v2's `PAYMENT-SIGNATURE`.
+ *
+ * Pure: never mutates `body`, never throws (a caller passing a non-v1 value gets `null`).
+ */
+declare function normalizeV1Challenge(body: unknown): X402Challenge | null;
 /**
  * Pick the first accepts[] entry on the `onchain-proof` scheme whose network
  * satisfies `matches` (any chain family). Returns null if none match.
@@ -958,4 +1112,4 @@ declare class SpendLedger {
     summary(): SpendSummary;
 }
 
-export { parseSettleResponse as $, type AddressId as A, type X402ExactAcceptEntry as B, type Caip2 as C, type X402PaymentSignature as D, EXT_OFFER_RECEIPT as E, type X402Receipt as F, type X402ResourceObject as G, HEADER_REQUIRED as H, type X402UptoAcceptEntry as I, buildChallengeHeader as J, buildExactSignatureHeader as K, buildPaymentIdentifierAdvertisement as L, buildReceiptExtension as M, buildReceiptHeader as N, buildSignatureHeader as O, type PaidReceipt as P, buildUptoSignatureHeader as Q, decodeBase64Json as R, type SettleOutcome as S, memorySpendStore as T, parseChallenge as U, type VerifyErrorCode as V, parseExactObject as W, type X402AcceptEntry as X, parseExactPaymentHeader as Y, parseReceipt as Z, parseReceiptExtension as _, type AssetId as a, parseSignatureHeader as a0, parseSignatureObject as a1, parseUptoObject as a2, parseUptoPaymentHeader as a3, pickAccept as a4, readPaymentIdentifier as a5, EXT_PAYMENT_IDENTIFIER as b, type ExactAuthorizationWire as c, type ExactPaymentPayload as d, type ExactPaymentPayloadAny as e, HEADER_RESPONSE as f, HEADER_RESPONSE_V1 as g, HEADER_SIGNATURE as h, HEADER_SIGNATURE_V1 as i, type ParsedExactPayment as j, type ParsedUptoPayment as k, type Permit2Authorization as l, type Permit2PaymentPayload as m, type Permit2UptoAuthorization as n, type Permit2UptoPaymentPayload as o, type PipRailReceipt as p, type SignedReceipt as q, type SpendAssetTotal as r, type SpendDenomTotal as s, SpendLedger as t, type SpendRecord as u, type SpendStore as v, type SpendSummary as w, type VerifyResult as x, type X402AnyAccept as y, type X402Challenge as z };
+export { normalizeV1Challenge as $, type AddressId as A, type X402ExactAcceptEntry as B, type Caip2 as C, DEFAULT_EXACT_TRANSFER_METHOD as D, EXT_OFFER_RECEIPT as E, type X402PaymentSignature as F, type X402Receipt as G, HEADER_REQUIRED as H, type X402ResourceObject as I, type X402UptoAcceptEntry as J, KNOWN_EXACT_TRANSFER_METHODS as K, buildChallengeHeader as L, buildExactSignatureHeader as M, buildPaymentIdentifierAdvertisement as N, buildReceiptExtension as O, type PaidReceipt as P, buildReceiptHeader as Q, buildSignatureHeader as R, type SettleOutcome as S, buildUptoSignatureHeader as T, buildV1PaymentHeader as U, type VerifyErrorCode as V, decodeBase64Json as W, type X402AcceptEntry as X, exactTransferMethod as Y, isSettleableExactMethod as Z, memorySpendStore as _, type AssetId as a, parseChallenge as a0, parseExactObject as a1, parseExactPaymentHeader as a2, parseReceipt as a3, parseReceiptExtension as a4, parseSettleResponse as a5, parseSignatureHeader as a6, parseSignatureObject as a7, parseUptoObject as a8, parseUptoPaymentHeader as a9, pickAccept as aa, readPaymentIdentifier as ab, EXT_PAYMENT_IDENTIFIER as b, type ExactAuthorizationWire as c, type ExactPaymentPayload as d, type ExactPaymentPayloadAny as e, HEADER_RESPONSE as f, HEADER_RESPONSE_V1 as g, HEADER_SIGNATURE as h, HEADER_SIGNATURE_V1 as i, type ParsedExactPayment as j, type ParsedUptoPayment as k, type Permit2Authorization as l, type Permit2PaymentPayload as m, type Permit2UptoAuthorization as n, type Permit2UptoPaymentPayload as o, type PipRailReceipt as p, type SignedReceipt as q, type SpendAssetTotal as r, type SpendDenomTotal as s, SpendLedger as t, type SpendRecord as u, type SpendStore as v, type SpendSummary as w, type VerifyResult as x, type X402AnyAccept as y, type X402Challenge as z };

package/dist/{ledger-uFtXlIHY.d.ts → ledger-Crc1bZox.d.ts}

@@ -75,8 +75,28 @@ interface X402ExactAcceptEntry {
     asset: AssetId;
     payTo: AddressId;
     maxTimeoutSeconds: number;
-    extra: {
-        /** The exact transfer method. EVM: `'eip3009'` for tokens with native
+    /**
+     * The network id EXACTLY as an x402 **v1** server wrote it (a slug like `'base'`),
+     * preserved by {@link normalizeV1Challenge} because `network` above is canonicalised to
+     * CAIP-2 for matching while a v1 server string-compares the slug it sent. Internal to the
+     * v1 compat path — absent on every v2 rail, and STRIPPED from every outgoing `accepted`
+     * echo by `withoutWireNetwork`, since the merchant never published this key.
+     */
+    wireNetwork?: string;
+    /**
+     * Scheme-defined extras. **OPTIONAL when PARSING a foreign 402** — the exact-EVM scheme
+     * makes every `extra` key optional (`assetTransferMethod` defaults to `'eip3009'`), and the
+     * SVM/Algorand/Aptos/NEAR/Hedera schemes define no `assetTransferMethod` at all, so a
+     * conformant rail may ship `extra: {}` or omit the block entirely. A PipRail **gate** always
+     * emits it. Every read on the buyer path must optional-chain.
+     */
+    extra?: {
+        /** The exact transfer method. **OPTIONAL** — `scheme_exact_evm.md`: *"If no
+         *  `assetTransferMethod` is specified in `PaymentRequired.extra`, clients should default
+         *  to `\"eip3009\"`"* (and only the non-default methods make it required). The SVM,
+         *  Algorand, Aptos, NEAR and Hedera schemes never define this key. Read it through
+         *  {@link exactTransferMethod}, never bare — 91% of the deployed x402 web omits it.
+         *  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
@@ -92,13 +112,46 @@ interface X402ExactAcceptEntry {
          *  authorizing exactly one NEP-141 `ft_transfer` to `payTo` (per `scheme_exact_near.md`); a
          *  facilitator-selected relayer (`feePayer` below) prepays gas + the 1 yoctoNEAR and submits, so
          *  the buyer holds zero NEAR. PipRail self-settles ALL. */
-        assetTransferMethod: 'eip3009' | 'permit2'
+        assetTransferMethod?: 'eip3009' | 'permit2'
         /** A FOREIGN-dialect alias for `'permit2'` — Binance's x402 ("b402") facilitator labels its
          *  EVM-Permit2 exact rail `'permit2-exact'` (the coinbase/x402 spec uses bare `'permit2'`).
          *  PipRail EMITS only `'permit2'`; it TOLERATES `'permit2-exact'` inbound so the buyer pays a
          *  Binance-issued 402 (the buyer treats the two as one rail). NB: settlement still requires the
          *  rail to bind PipRail's canonical x402ExactPermit2Proxy — see the buyer in drivers/evm. */
-         | 'permit2-exact' | 'svm' | 'algorand' | 'aptos' | 'near';
+         | 'permit2-exact' | 'svm' | 'algorand' | 'aptos' | 'near'
+        /** **XRPL** — the ledger has exactly ONE way to move value (a `Payment`), so
+         *  `scheme_exact_xrpl.md` spends this field on SEQUENCING instead of mechanism.
+         *  `'sequence'` (the DEFAULT, and what all 1,732 live XRPL rails mean by omitting it) uses
+         *  the payer's account sequence; `'ticketSequence'` sets `Sequence: 0` and supplies a
+         *  pre-minted `TicketSequence`, letting a payer sign several payments that settle out of
+         *  order. */
+         | 'sequence' | 'ticketSequence';
+        /** **XRPL, REQUIRED by the scheme — and absent from 100% of live rails.** The spec says it
+         *  "must be false" (XRPL charges the fee to the transaction's own `Account`, so the payer
+         *  always pays). Read it as *false unless present*: REQUIRING it would reject the entire
+         *  deployed XRPL x402 web, which is exactly the bug class `assetTransferMethod` already caused
+         *  once. A rail that explicitly says `true` is refused — we cannot honour a sponsor here. */
+        areFeesSponsored?: boolean;
+        /** **XRPL** — the issuer's classic address for an IOU rail (RLUSD and friends). Required by the
+         *  scheme for issued currencies, absent for native XRP; present on 869 of the 1,732 live rails,
+         *  which is precisely the IOU half. Also the discriminator the buyer uses to pick the
+         *  issued-currency `Amount` object over a bare drops string. */
+        issuer?: string;
+        /** **XRPL, OPTIONAL** — an opaque invoice identifier. When present the buyer MUST set the
+         *  transaction's `InvoiceID` to its **SHA-256**, as 32-byte hex; that hash is the challenge
+         *  binding on this rail (there is no memo — the scheme has facilitators REJECT `Memos`).
+         *  Present on 1,732 of 1,732 live rails, so treat it as always-on in practice. */
+        invoiceId?: string;
+        /** **XRPL** — a vendor correlation tag, copied verbatim into the transaction's `SourceTag`.
+         *  NOT in `scheme_exact_xrpl.md`'s extra table, but present on **1,728 of the 1,732** live XRPL
+         *  rails: it is how the deployed vendors match a payment back to their own quote. Mirrored
+         *  because it costs nothing and omitting it is a plausible reason a merchant refuses. */
+        sourceTag?: number;
+        /** **XRPL, OPTIONAL** — a destination tag the buyer MUST copy verbatim into the transaction
+         *  when the rail states one (hosted/exchange accounts route deposits by it). Never invented
+         *  when absent: unlike the onchain-proof path, which derives a tag from the nonce, the exact
+         *  rail sets `DestinationTag` only if the merchant asked for one. */
+        destinationTag?: number;
         /** 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
@@ -132,6 +185,42 @@ interface X402ExactAcceptEntry {
         symbol?: string;
     };
 }
+/**
+ * The transfer method an `exact` rail uses when it names none.
+ *
+ * `scheme_exact_evm.md` §0: *"If no `assetTransferMethod` is specified in
+ * `PaymentRequired.extra`, clients should default to `"eip3009"`."* §1 restates it per-method:
+ * `eip3009` is *"optional in `PaymentRequired`, default"*, while `permit2` and `erc7710` are
+ * *"required"*. So an absent marker is not a malformed rail — it is the common case (91% of the
+ * deployed web) and it means EIP-3009.
+ */
+declare const DEFAULT_EXACT_TRANSFER_METHOD: "eip3009";
+/**
+ * Every `assetTransferMethod` a PipRail buyer can actually sign, across all families.
+ *
+ * Used to SKIP a rail that names a method we don't implement (the spec's `erc7710`, or any
+ * future one) rather than sign an EIP-3009 authorization a facilitator built for a different
+ * mechanism and will reject. An **absent** marker is not "unknown" — see
+ * {@link DEFAULT_EXACT_TRANSFER_METHOD}. Family routing stays in each driver's `payExact`;
+ * this set only answers "could any driver of ours settle this?".
+ */
+declare const KNOWN_EXACT_TRANSFER_METHODS: ReadonlySet<string>;
+/**
+ * The effective transfer method of an `exact` rail: what it names, or the default when it names
+ * nothing. THE ONLY sanctioned way to read `extra.assetTransferMethod` — reading it bare is how
+ * the buyer came to reject 91% of the x402 web.
+ *
+ * Pass `family` to get the right default off-EVM: a Solana rail that names nothing means `svm`,
+ * not `eip3009`. Without it the EVM default is assumed (correct for the settleability check,
+ * since every family's own literal is in {@link KNOWN_EXACT_TRANSFER_METHODS} anyway).
+ */
+declare function exactTransferMethod(accept: X402ExactAcceptEntry, family?: string): string;
+/**
+ * Can any PipRail driver settle this rail's transfer method? True when the rail names a
+ * method we implement, AND when it names none (the spec default `eip3009`). False only for a
+ * method we don't implement — the rail is then skipped at gather rather than mis-signed.
+ */
+declare function isSettleableExactMethod(accept: X402ExactAcceptEntry): boolean;
 /**
  * A standard x402 `upto` rail (EVM / Permit2) — variable-amount / metered billing.
  * The buyer signs a Permit2 `PermitWitnessTransferFrom` authorization for `amount`
@@ -181,7 +270,13 @@ interface X402UptoAcceptEntry {
  *  rail, or a standard `upto` (metered) rail. */
 type X402AnyAccept = X402AcceptEntry | X402ExactAcceptEntry | X402UptoAcceptEntry;
 interface X402Challenge {
-    x402Version: 2;
+    /**
+     * `2` for every challenge PipRail EMITS. `1` appears only on the PARSE side, when
+     * {@link normalizeV1Challenge} has lifted a still-deployed v1 server's body into this
+     * shape — the buyer must then answer on the v1 wire (`X-PAYMENT`, flat payload). See the
+     * version-posture note above {@link HEADER_SIGNATURE_V1}.
+     */
+    x402Version: 1 | 2;
     /**
      * Optional human-readable reason (v2 `error?: string`). PipRail EMITS it only on a
      * rejected-proof re-challenge (omitted on a fresh challenge). Typed to also tolerate
@@ -361,10 +456,25 @@ interface ExactNearPaymentPayload {
     /** Base64 of the Borsh-encoded NEP-366 `SignedDelegateAction` (one `ft_transfer`). */
     signedDelegateAction: string;
 }
+/**
+ * The `payload` a client sends for the **XRPL `exact`** variant, per `scheme_exact_xrpl.md`:
+ * a **fully signed** XRPL `Payment` transaction, hex-encoded, that the resource server (or its
+ * facilitator) submits. The signed blob IS the proof — there is no separate authorization object.
+ *
+ * XRPL is the one family where **the payer pays the network fee**: the fee is a field inside the
+ * signed transaction and the ledger charges it to `Account`. So there is no sponsor, no fee-payer
+ * co-signature, and no fee-drain guard to write — the buyer needs XRP for the amount *and* the fee.
+ * That also means the buyer signs something immediately submittable, so `LastLedgerSequence` is
+ * mandatory: it is the only thing bounding how long the merchant may sit on it.
+ */
+interface ExactXrplPaymentPayload {
+    /** Hex-encoded, fully signed XRPL `Payment` transaction blob. */
+    signedTxBlob: string;
+}
 /** Any `exact`-rail payload shape — EIP-3009 (`authorization`), Permit2 (`permit2Authorization`),
- *  SVM (`transaction`), Algorand (`paymentGroup`), Aptos (`transaction` + `senderAuth`), or NEAR
- *  (`signedDelegateAction`). */
-type ExactPaymentPayloadAny = ExactPaymentPayload | Permit2PaymentPayload | ExactSvmPaymentPayload | ExactAlgorandPaymentPayload | ExactAptosPaymentPayload | ExactNearPaymentPayload;
+ *  SVM (`transaction`), Algorand (`paymentGroup`), Aptos (`transaction` + `senderAuth`), NEAR
+ *  (`signedDelegateAction`), or XRPL (`signedTxBlob`). */
+type ExactPaymentPayloadAny = ExactPaymentPayload | Permit2PaymentPayload | ExactSvmPaymentPayload | ExactAlgorandPaymentPayload | ExactAptosPaymentPayload | ExactNearPaymentPayload | ExactXrplPaymentPayload;
 interface ParsedExactBase {
     x402Version: number;
     /** The client's claimed network (slug or CAIP-2) — for matching, not trust. */
@@ -385,7 +495,9 @@ interface ParsedExactBase {
  * `'svm'` → {@link ExactSvmPaymentPayload} (`transaction`), `'algorand'` →
  * {@link ExactAlgorandPaymentPayload} (`paymentGroup`); `'aptos'` →
  * {@link ExactAptosPaymentPayload} (`transaction` + `senderAuth`); `'near'` →
- * {@link ExactNearPaymentPayload} (`signedDelegateAction`).
+ * {@link ExactNearPaymentPayload} (`signedDelegateAction`); `'sequence'` / `'ticketSequence'` →
+ * {@link ExactXrplPaymentPayload} (`signedTxBlob`) — XRPL is the one family whose method literal
+ * names the SEQUENCING strategy rather than a transfer mechanism, because it has only one.
  */
 type ParsedExactPayment = (ParsedExactBase & {
     method: 'eip3009';
@@ -405,6 +517,12 @@ type ParsedExactPayment = (ParsedExactBase & {
 }) | (ParsedExactBase & {
     method: 'near';
     payload: ExactNearPaymentPayload;
+}) | (ParsedExactBase & {
+    method: 'sequence';
+    payload: ExactXrplPaymentPayload;
+}) | (ParsedExactBase & {
+    method: 'ticketSequence';
+    payload: ExactXrplPaymentPayload;
 });
 /**
  * What {@link parseUptoPaymentHeader} extracts from an inbound `upto` payment — the
@@ -648,6 +766,25 @@ declare function buildUptoSignatureHeader(input: {
     accepted: X402UptoAcceptEntry;
     payload: Permit2UptoPaymentPayload;
 }): string;
+/**
+ * Build the **v1** `X-PAYMENT` header value — the flat, pre-v2 payload shape
+ * `{ x402Version: 1, scheme, network, payload }`, base64-JSON.
+ *
+ * This is the `encodeXPaymentHeader` utility the version-posture note above has always
+ * described; it had never been written, so the buyer could parse nothing from a v1 server and
+ * could answer nothing either. Needed because v2 moved the header `X-PAYMENT` →
+ * `PAYMENT-SIGNATURE` and reshaped the payload: a v1 server ignores `PAYMENT-SIGNATURE`
+ * entirely (verified live — it just re-challenges) and reads only `X-PAYMENT`.
+ *
+ * `network` MUST be the slug the v1 server itself sent (`X402ExactAcceptEntry.wireNetwork`),
+ * not our canonical CAIP-2: v1 verifiers string-compare it against their own requirement.
+ * There is no `accepted` echo in v1 — the chosen rail is identified by these two flat fields.
+ */
+declare function buildV1PaymentHeader(input: {
+    scheme: string;
+    network: string;
+    payload: unknown;
+}): string;
 /**
  * Parse the PAYMENT-REQUIRED challenge from a 402 response. Prefers the
  * `payment-required` header, falls back to the JSON body.
@@ -747,6 +884,23 @@ declare function parseUptoPaymentHeader(value: string): ParsedUptoPayment | null
  * base64 wrapper, byte-identical to before this split on the HTTP path.
  */
 declare function parseUptoObject(parsed: unknown): ParsedUptoPayment | null;
+/**
+ * Lift an x402 **v1** challenge body into the internal {@link X402Challenge} shape, so the
+ * whole buyer path downstream of `parseChallenge` stays v2-only and version-blind.
+ *
+ * Four v1→v2 skews are absorbed, and nothing else is touched (unknown keys ride along
+ * verbatim, so a facilitator's extras survive):
+ *  1. `maxAmountRequired` → `amount` (v2's rename). An accept that already has `amount` keeps it.
+ *  2. slug `network` (`'base'`) → CAIP-2 (`'eip155:8453'`) so the gather's `supports()` matches,
+ *     with the ORIGINAL preserved on {@link X402ExactAcceptEntry.wireNetwork} because the v1
+ *     server string-compares the slug it sent when we echo it back.
+ *  3. per-accept `resource` string → a top-level `resource` object (first accept that has one).
+ *  4. `x402Version: 1` is KEPT on the result — it is what tells `payExactRail` to answer on the
+ *     v1 wire (`X-PAYMENT`, flat payload) instead of v2's `PAYMENT-SIGNATURE`.
+ *
+ * Pure: never mutates `body`, never throws (a caller passing a non-v1 value gets `null`).
+ */
+declare function normalizeV1Challenge(body: unknown): X402Challenge | null;
 /**
  * Pick the first accepts[] entry on the `onchain-proof` scheme whose network
  * satisfies `matches` (any chain family). Returns null if none match.
@@ -958,4 +1112,4 @@ declare class SpendLedger {
     summary(): SpendSummary;
 }
 
-export { parseSettleResponse as $, type AddressId as A, type X402ExactAcceptEntry as B, type Caip2 as C, type X402PaymentSignature as D, EXT_OFFER_RECEIPT as E, type X402Receipt as F, type X402ResourceObject as G, HEADER_REQUIRED as H, type X402UptoAcceptEntry as I, buildChallengeHeader as J, buildExactSignatureHeader as K, buildPaymentIdentifierAdvertisement as L, buildReceiptExtension as M, buildReceiptHeader as N, buildSignatureHeader as O, type PaidReceipt as P, buildUptoSignatureHeader as Q, decodeBase64Json as R, type SettleOutcome as S, memorySpendStore as T, parseChallenge as U, type VerifyErrorCode as V, parseExactObject as W, type X402AcceptEntry as X, parseExactPaymentHeader as Y, parseReceipt as Z, parseReceiptExtension as _, type AssetId as a, parseSignatureHeader as a0, parseSignatureObject as a1, parseUptoObject as a2, parseUptoPaymentHeader as a3, pickAccept as a4, readPaymentIdentifier as a5, EXT_PAYMENT_IDENTIFIER as b, type ExactAuthorizationWire as c, type ExactPaymentPayload as d, type ExactPaymentPayloadAny as e, HEADER_RESPONSE as f, HEADER_RESPONSE_V1 as g, HEADER_SIGNATURE as h, HEADER_SIGNATURE_V1 as i, type ParsedExactPayment as j, type ParsedUptoPayment as k, type Permit2Authorization as l, type Permit2PaymentPayload as m, type Permit2UptoAuthorization as n, type Permit2UptoPaymentPayload as o, type PipRailReceipt as p, type SignedReceipt as q, type SpendAssetTotal as r, type SpendDenomTotal as s, SpendLedger as t, type SpendRecord as u, type SpendStore as v, type SpendSummary as w, type VerifyResult as x, type X402AnyAccept as y, type X402Challenge as z };
+export { normalizeV1Challenge as $, type AddressId as A, type X402ExactAcceptEntry as B, type Caip2 as C, DEFAULT_EXACT_TRANSFER_METHOD as D, EXT_OFFER_RECEIPT as E, type X402PaymentSignature as F, type X402Receipt as G, HEADER_REQUIRED as H, type X402ResourceObject as I, type X402UptoAcceptEntry as J, KNOWN_EXACT_TRANSFER_METHODS as K, buildChallengeHeader as L, buildExactSignatureHeader as M, buildPaymentIdentifierAdvertisement as N, buildReceiptExtension as O, type PaidReceipt as P, buildReceiptHeader as Q, buildSignatureHeader as R, type SettleOutcome as S, buildUptoSignatureHeader as T, buildV1PaymentHeader as U, type VerifyErrorCode as V, decodeBase64Json as W, type X402AcceptEntry as X, exactTransferMethod as Y, isSettleableExactMethod as Z, memorySpendStore as _, type AssetId as a, parseChallenge as a0, parseExactObject as a1, parseExactPaymentHeader as a2, parseReceipt as a3, parseReceiptExtension as a4, parseSettleResponse as a5, parseSignatureHeader as a6, parseSignatureObject as a7, parseUptoObject as a8, parseUptoPaymentHeader as a9, pickAccept as aa, readPaymentIdentifier as ab, EXT_PAYMENT_IDENTIFIER as b, type ExactAuthorizationWire as c, type ExactPaymentPayload as d, type ExactPaymentPayloadAny as e, HEADER_RESPONSE as f, HEADER_RESPONSE_V1 as g, HEADER_SIGNATURE as h, HEADER_SIGNATURE_V1 as i, type ParsedExactPayment as j, type ParsedUptoPayment as k, type Permit2Authorization as l, type Permit2PaymentPayload as m, type Permit2UptoAuthorization as n, type Permit2UptoPaymentPayload as o, type PipRailReceipt as p, type SignedReceipt as q, type SpendAssetTotal as r, type SpendDenomTotal as s, SpendLedger as t, type SpendRecord as u, type SpendStore as v, type SpendSummary as w, type VerifyResult as x, type X402AnyAccept as y, type X402Challenge as z };

package/dist/node.d.cts

@@ -1,5 +1,5 @@
-import { v as SpendStore } from './ledger-uFtXlIHY.cjs';
-export { T as memorySpendStore } from './ledger-uFtXlIHY.cjs';
+import { v as SpendStore } from './ledger-Crc1bZox.cjs';
+export { _ as memorySpendStore } from './ledger-Crc1bZox.cjs';
 
 /**
  * A durable {@link SpendStore} backed by a local JSONL file (one settled payment per

package/dist/node.d.ts

@@ -1,5 +1,5 @@
-import { v as SpendStore } from './ledger-uFtXlIHY.js';
-export { T as memorySpendStore } from './ledger-uFtXlIHY.js';
+import { v as SpendStore } from './ledger-Crc1bZox.js';
+export { _ as memorySpendStore } from './ledger-Crc1bZox.js';
 
 /**
  * A durable {@link SpendStore} backed by a local JSONL file (one settled payment per