@piprail/sdk 1.13.0 → 1.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/CHAINS.md +3 -2
  2. package/CHANGELOG.md +49 -0
  3. package/ERRORS.md +2 -1
  4. package/README.md +19 -2
  5. package/STANDARDS.md +2 -0
  6. package/dist/{algorand-WGVF4KTU.js → algorand-7EUZYL2Z.js} +1 -1
  7. package/dist/{algorand-MXUSKX46.cjs → algorand-OIHGJN5S.cjs} +17 -17
  8. package/dist/{aptos-LPBLSEIQ.js → aptos-CDEYDDM5.js} +1 -1
  9. package/dist/{aptos-YT7SXWPF.cjs → aptos-WDWZOU25.cjs} +16 -16
  10. package/dist/{chunk-MDLZJGLY.cjs → chunk-FTKVCP6K.cjs} +24 -13
  11. package/dist/{chunk-SVMGHASK.js → chunk-H3A4KWLJ.js} +12 -1
  12. package/dist/index.cjs +399 -145
  13. package/dist/index.d.cts +209 -31
  14. package/dist/index.d.ts +209 -31
  15. package/dist/index.js +308 -54
  16. package/dist/{near-K6BDBABG.js → near-DT6LRIKB.js} +1 -1
  17. package/dist/{near-7ZDNISUX.cjs → near-FUH3VAXT.cjs} +19 -19
  18. package/dist/{solana-S3UFI3FE.js → solana-3TRYD4QB.js} +1 -1
  19. package/dist/{solana-PU7N2M64.cjs → solana-QUVXPKBZ.cjs} +14 -14
  20. package/dist/{stellar-VDQOFQEO.cjs → stellar-APZEBFAD.cjs} +21 -21
  21. package/dist/{stellar-Q5PO23SC.js → stellar-IK3UML6O.js} +1 -1
  22. package/dist/{sui-FKSMLKRF.cjs → sui-L7BQNJWO.cjs} +17 -17
  23. package/dist/{sui-WOXRKJXS.js → sui-VSE63WQM.js} +1 -1
  24. package/dist/{ton-VK6KRJHP.cjs → ton-5DLKKOFE.cjs} +14 -14
  25. package/dist/{ton-WPTXGLVK.js → ton-QHGQLJX2.js} +1 -1
  26. package/dist/{tron-6GXBXTR4.js → tron-2N2GA62O.js} +1 -1
  27. package/dist/{tron-WLOF5OUV.cjs → tron-HHIT6WKY.cjs} +24 -24
  28. package/dist/{xrpl-HEAPEXAM.js → xrpl-2GZMDYW5.js} +1 -1
  29. package/dist/{xrpl-CMNI25BV.cjs → xrpl-USEG4AHX.cjs} +21 -21
  30. package/package.json +1 -1
package/dist/index.d.ts CHANGED
@@ -84,10 +84,13 @@ interface X402ExactAcceptEntry {
84
84
  extra: {
85
85
  /** The exact-EVM transfer method. PipRail self-settles EIP-3009 today. */
86
86
  assetTransferMethod: 'eip3009';
87
- /** EIP-712 domain name of the token (USDC: "USD Coin"; EURC: "EURC"). Read on-chain. */
88
- name: string;
89
- /** EIP-712 domain version of the token (USDC/EURC: "2"). Read on-chain. */
90
- version: string;
87
+ /** EIP-712 domain name of the token. OPTIONAL per the exact-EVM scheme (only
88
+ * `assetTransferMethod` is required) — a foreign rail may omit it. NEVER assumed
89
+ * from the symbol (USDC's on-chain name() is "USD Coin", not "USDC"); a PipRail gate
90
+ * READS it on-chain, and the PipRail buyer RE-DERIVES it on-chain and ignores this. */
91
+ name?: string;
92
+ /** EIP-712 domain version of the token (USDC: "2"). OPTIONAL (see `name`); read/re-derived on-chain. */
93
+ version?: string;
91
94
  /** Confirmations the gate waits for before granting access — mirrors the gate's
92
95
  * `minConfirmations`, so the exact rail honours the same reorg safety as onchain-proof.
93
96
  * A PipRail convenience (standard clients ignore unknown keys). */
@@ -221,13 +224,54 @@ declare const HEADER_RESPONSE_V1 = "x-payment-response";
221
224
  declare function buildChallengeHeader(challenge: X402Challenge): string;
222
225
  declare function buildReceiptHeader(receipt: X402Receipt): string;
223
226
  declare function buildSignatureHeader(signature: X402PaymentSignature): string;
227
+ /**
228
+ * Build the v2 PAYMENT-SIGNATURE header value for a standard x402 `exact` payment:
229
+ * base64 of `{ x402Version: 2, accepted, payload }`. `accepted` is the chosen rail
230
+ * echoed back VERBATIM from the challenge's `accepts[]` (preserving any extra keys a
231
+ * facilitator needs); `payload` is the EIP-3009 `{ signature, authorization }` the
232
+ * buyer's EVM driver produced. Chain-agnostic (pure JSON/base64) — the driver owns
233
+ * the signing, this only frames it for the wire. Round-trips through
234
+ * {@link parseExactPaymentHeader}. (The `onchain-proof` counterpart is
235
+ * {@link buildSignatureHeader}; the v1 flat-shape utility is `encodeXPaymentHeader`.)
236
+ */
237
+ declare function buildExactSignatureHeader(input: {
238
+ accepted: X402ExactAcceptEntry;
239
+ payload: ExactPaymentPayload;
240
+ }): string;
224
241
  /**
225
242
  * Parse the PAYMENT-REQUIRED challenge from a 402 response. Prefers the
226
243
  * `payment-required` header, falls back to the JSON body.
227
244
  */
228
245
  declare function parseChallenge(response: Response): Promise<X402Challenge | null>;
229
- /** Parse the PAYMENT-RESPONSE receipt header on a 200 settlement. */
246
+ /** Parse the PAYMENT-RESPONSE receipt header on a 200 settlement. Reads the v2
247
+ * `payment-response` header, falling back to the v1 `x-payment-response` a foreign
248
+ * server may set. Returns a fully-formed {@link X402Receipt} only (a bare foreign
249
+ * exact SettleResponse without a `payer` is read by {@link parseSettleResponse}). */
230
250
  declare function parseReceipt(response: Response): X402Receipt | null;
251
+ /**
252
+ * A standard x402 SettleResponse as the BUYER reads it off a settled (non-402)
253
+ * response. The `success` flag is authoritative: `false` is an EXPLICIT facilitator/
254
+ * server REJECTION (the buyer must NOT record a spend), `true` is an affirmative
255
+ * settlement. `transaction` is the on-chain settle tx the facilitator broadcast.
256
+ */
257
+ interface SettleOutcome {
258
+ success: boolean;
259
+ transaction?: string;
260
+ network?: string;
261
+ payer?: string;
262
+ errorReason?: string;
263
+ }
264
+ /**
265
+ * Read a standard x402 SettleResponse for the BUYER, from the v2 `payment-response`
266
+ * header (or the v1 `x-payment-response` fallback). Returns `null` when neither
267
+ * header is present, unparseable, or carries no boolean `success` — i.e. when the
268
+ * server served the resource WITHOUT echoing a settle result, which the exact buyer
269
+ * treats as an affirmative 2xx settlement (receipt-less). When a body IS present with
270
+ * a boolean `success`, that flag is returned verbatim: ONLY an explicit
271
+ * `success: false` is a rejection. Used by the exact pay path to tell a real
272
+ * settlement from a phantom one (never record a spend on `success:false`).
273
+ */
274
+ declare function parseSettleResponse(response: Response): SettleOutcome | null;
231
275
  /** Parse a PAYMENT-SIGNATURE header value (server side). */
232
276
  declare function parseSignatureHeader(value: string): X402PaymentSignature | null;
233
277
  /**
@@ -347,6 +391,11 @@ declare const CHAINS: {
347
391
  decimals: number;
348
392
  symbol: string;
349
393
  };
394
+ EURC: {
395
+ address: "0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c";
396
+ decimals: number;
397
+ symbol: string;
398
+ };
350
399
  };
351
400
  };
352
401
  base: {
@@ -561,7 +610,7 @@ declare const CHAINS: {
561
610
  value: bigint;
562
611
  yParity: number;
563
612
  accessList: viem.AccessList;
564
- authorizationList?: undefined | undefined;
613
+ authorizationList? /** EVM chain id, e.g. 5000 for Mantle. */: undefined | undefined;
565
614
  blobVersionedHashes?: undefined | undefined;
566
615
  chainId: number;
567
616
  type: "eip1559";
@@ -570,7 +619,7 @@ declare const CHAINS: {
570
619
  maxFeePerGas: bigint;
571
620
  maxPriorityFeePerGas: bigint;
572
621
  isSystemTx?: undefined | undefined;
573
- mint?: undefined | undefined;
622
+ mint? /** Known tokens on this chain (empty for unknown custom chains). */: undefined | undefined;
574
623
  sourceHash?: undefined | undefined;
575
624
  } | {
576
625
  blockHash: `0x${string}` | null;
@@ -682,6 +731,11 @@ declare const CHAINS: {
682
731
  decimals: number;
683
732
  symbol: string;
684
733
  };
734
+ EURC: {
735
+ address: "0x60a3E35Cc302bFA44Cb288Bc5a4F316Fdb1adb42";
736
+ decimals: number;
737
+ symbol: string;
738
+ };
685
739
  };
686
740
  };
687
741
  arbitrum: {
@@ -965,7 +1019,7 @@ declare const CHAINS: {
965
1019
  maxPriorityFeePerGas: bigint;
966
1020
  isSystemTx?: undefined | undefined;
967
1021
  mint?: undefined | undefined;
968
- sourceHash?: undefined | undefined;
1022
+ sourceHash? /** Known tokens on this chain (empty for unknown custom chains). */: undefined | undefined;
969
1023
  } | {
970
1024
  blockHash: `0x${string}` | null;
971
1025
  blockNumber: bigint | null;
@@ -1264,6 +1318,11 @@ declare const CHAINS: {
1264
1318
  decimals: number;
1265
1319
  symbol: string;
1266
1320
  };
1321
+ EURC: {
1322
+ address: "0xC891EB4cbdEFf6e073e859e987815Ed1505c2ACD";
1323
+ decimals: number;
1324
+ symbol: string;
1325
+ };
1267
1326
  };
1268
1327
  };
1269
1328
  mantle: {
@@ -4118,9 +4177,11 @@ interface ResolvedNetwork {
4118
4177
  * never throws for a transient RPC issue — it falls back to a 'heuristic'
4119
4178
  * constant. `opts.from` (the payer's address) sharpens chains whose fee
4120
4179
  * depends on the sender (notably Tron energy); omit it for a typical estimate.
4121
- * Payer-side + informational — the gate never calls this.
4180
+ * Payer-side + informational — the gate never calls this. Accepts either rail
4181
+ * shape ({@link X402AnyAccept}): a standard `exact` rail estimates the BUYER's gas
4182
+ * as ~0 (the server/facilitator broadcasts the signed authorization).
4122
4183
  */
4123
- estimateCost(accept: X402AcceptEntry, opts?: {
4184
+ estimateCost(accept: X402AnyAccept, opts?: {
4124
4185
  from?: string;
4125
4186
  }): Promise<CostEstimate>;
4126
4187
  /**
@@ -4148,6 +4209,32 @@ interface ResolvedNetwork {
4148
4209
  ready: boolean | 'n/a' | 'unknown';
4149
4210
  reason?: RecipientReason;
4150
4211
  }>;
4212
+ /**
4213
+ * OPTIONAL (EVM + EIP-3009 only) — the BUYER counterpart to {@link settleExactSelf}.
4214
+ * Build + EIP-712-sign an EIP-3009 `transferWithAuthorization` for a standard x402
4215
+ * `exact` rail, so a PipRail agent can PAY any standard x402 server (not just PipRail's
4216
+ * own `onchain-proof` gates). The client frames the returned `payload` + `accepted` echo
4217
+ * into the `PAYMENT-SIGNATURE` header and re-requests; the server / merchant-chosen
4218
+ * facilitator BROADCASTS the authorization (the buyer never broadcasts and spends ~0 gas).
4219
+ *
4220
+ * Re-derives the token's EIP-712 domain ON-CHAIN (never trusts the server-supplied
4221
+ * `extra.{name,version}`), generates a CSPRNG 32-byte nonce + current unix time
4222
+ * internally, and signs through the wallet client (bring-your-own JsonRpcAccount safe).
4223
+ * THROWS a typed `PipRailError` (`UnsupportedSchemeError`) when the asset isn't EIP-3009
4224
+ * (USDT/native/plain ERC-20) or the signer is a contract / EIP-1271 / EIP-7702 account.
4225
+ *
4226
+ * The third optional `exact` method (after {@link exactDomain}/{@link settleExactSelf});
4227
+ * optional `?` is the gather gate — non-EVM families omit it, so an `exact` rail is never
4228
+ * gathered/paid on those chains. Returns the signed payload, the chosen-rail echo (the
4229
+ * server's RAW rail, verbatim, so a facilitator's extra keys survive), the payer address,
4230
+ * and the nonce (for the client's spend record + a re-present-the-same-auth retry).
4231
+ */
4232
+ payExact?(wallet: WalletHandle, accept: X402ExactAcceptEntry): Promise<{
4233
+ payload: ExactPaymentPayload;
4234
+ accepted: X402ExactAcceptEntry;
4235
+ payerFrom: string;
4236
+ nonce: string;
4237
+ }>;
4151
4238
  /**
4152
4239
  * OPTIONAL — a DISCOVERY signer for the bound wallet: its public address plus a
4153
4240
  * message signer, used only for ownership proofs + SIWX index registration,
@@ -4169,7 +4256,8 @@ interface ResolvedNetwork {
4169
4256
  * `null` when the asset is NOT an EIP-3009 token (no `transferWithAuthorization` —
4170
4257
  * e.g. USDT, native coin, or a plain ERC-20), so the gate can refuse to advertise a
4171
4258
  * standard `exact` rail for it. Never derived from the symbol (USDC's domain name is
4172
- * "USD Coin", not "USDC"; EURC's is "EURC"). Called once at exact-rail resolution
4259
+ * "USD Coin", not "USDC"; EURC's is "Euro Coin" on Ethereum/Avalanche but "EURC" on Base —
4260
+ * which is exactly why it must be READ, never assumed). Called once at exact-rail resolution
4173
4261
  * (cached by the gate). RPC-read; may throw on a transient read (the gate surfaces a
4174
4262
  * clear config error). The first of two optional server methods for the `exact` rail.
4175
4263
  */
@@ -4504,11 +4592,15 @@ interface SpendSummary {
4504
4592
  records: SpendRecord[];
4505
4593
  }
4506
4594
 
4595
+ /** The payment schemes a client can settle: PipRail's native `onchain-proof` (the
4596
+ * default) and the standard x402 `exact` rail (EVM + EIP-3009 only, opt-in). */
4597
+ type PaymentScheme = 'onchain-proof' | 'exact';
4598
+
4507
4599
  /** Observability events. `ref` is the proof — a chain-specific id (EVM tx hash, Solana signature, TON locator, Stellar tx hash). */
4508
4600
  type PipRailEvent = {
4509
4601
  kind: 'payment-required';
4510
4602
  challenge: X402Challenge;
4511
- accept: X402AcceptEntry;
4603
+ accept: X402AnyAccept;
4512
4604
  } | {
4513
4605
  kind: 'payment-broadcast';
4514
4606
  ref: string;
@@ -4528,9 +4620,18 @@ type PipRailEvent = {
4528
4620
  kind: 'payment-unconfirmed';
4529
4621
  ref: string;
4530
4622
  reason: string;
4531
- } | {
4623
+ }
4624
+ /**
4625
+ * The payment settled. `receipt` is PipRail's rich {@link X402Receipt} when the
4626
+ * server returns one (its own gate, or a facilitator that echoes the full shape);
4627
+ * `settle` is the standard x402 SettleResponse (`{ success, transaction, … }`) on
4628
+ * conformant third-party-facilitator interop, where the lean SettleResponse has no
4629
+ * rich receipt — read `settle.transaction` for the on-chain settle tx there.
4630
+ */
4631
+ | {
4532
4632
  kind: 'payment-settled';
4533
4633
  receipt: X402Receipt | null;
4634
+ settle?: SettleOutcome;
4534
4635
  } | {
4535
4636
  kind: 'payment-failed';
4536
4637
  reason: string;
@@ -4627,8 +4728,9 @@ type PayBlocker = 'INSUFFICIENT_TOKEN' | 'INSUFFICIENT_GAS' | 'RECIPIENT_NOT_REA
4627
4728
  type PayWarning = 'SYMBOL_MISMATCH' | 'BALANCE_UNREADABLE' | 'RECIPIENT_READINESS_UNKNOWN' | 'GAS_HEURISTIC' | 'THIN_GAS_MARGIN';
4628
4729
  /** One offered rail, fully analysed against the bound wallet's own holdings. */
4629
4730
  interface PayOption {
4630
- /** The rail this analyses (one entry from the 402's accepts[]). */
4631
- accept: X402AcceptEntry;
4731
+ /** The rail this analyses (one entry from the 402's accepts[]) — an
4732
+ * `onchain-proof` rail or, when `schemes` enables it, a standard `exact` rail. */
4733
+ accept: X402AnyAccept;
4632
4734
  /** The priced requirement — TRUE decimals/symbol + the policy verdict. */
4633
4735
  quote: PipRailQuote;
4634
4736
  /** Estimated native-coin gas to send it (cost.basis surfaced). */
@@ -4725,6 +4827,24 @@ interface PipRailClientOptions {
4725
4827
  * per call with `fetch(url, { autoRoute: true })`.
4726
4828
  */
4727
4829
  autoRoute?: boolean;
4830
+ /**
4831
+ * Which payment SCHEMES this client may settle. Default **`['onchain-proof']`**
4832
+ * (defaults never change): the zero-config client pays only PipRail's native
4833
+ * backendless rail, exactly as before. Add `'exact'` to ALSO pay standard x402
4834
+ * `exact` rails — letting the agent pay ANY standard x402 server (the dominant
4835
+ * `exact`-on-Base-via-CDP web), not just PipRail's own gates:
4836
+ *
4837
+ * new PipRailClient({ chain: 'base', wallet, schemes: ['onchain-proof', 'exact'] })
4838
+ *
4839
+ * `exact` is **EVM + EIP-3009 only** (USDC/EURC); it's silently ignored on a
4840
+ * non-EVM chain, for USDT/native, or for a token the SDK can't price — those keep
4841
+ * `onchain-proof`. The agent signs an EIP-3009 authorization with its OWN wallet
4842
+ * and the server / merchant-chosen facilitator broadcasts it (the buyer pays ~0
4843
+ * gas; PipRail hosts/settles nothing). The same `policy` + `onBeforePay` gate it
4844
+ * BEFORE signing. **Verify against your target facilitator before production.**
4845
+ * Override per call with `fetch(url, { schemes })`.
4846
+ */
4847
+ schemes?: PaymentScheme[];
4728
4848
  /** Logger hook. Default no-op. */
4729
4849
  onEvent?: (event: PipRailEvent) => void;
4730
4850
  }
@@ -4791,6 +4911,9 @@ declare class PipRailClient {
4791
4911
  private safeEmit;
4792
4912
  /** Auto-mount the chain's driver, resolve the network, and bind the wallet — once. */
4793
4913
  private ensure;
4914
+ /** Resolve the effective scheme set: a per-call override, else the constructor's
4915
+ * `schemes`, else the `onchain-proof`-only default. */
4916
+ private resolveSchemes;
4794
4917
  /** GET that auto-handles 402. Pass a full URL to any x402-gated endpoint. */
4795
4918
  get(url: string, init?: RequestInit): Promise<Response>;
4796
4919
  /**
@@ -4869,8 +4992,8 @@ declare class PipRailClient {
4869
4992
  * - A resource just listed via {@link register} may not appear yet — 402 Index reviews
4870
4993
  * before publishing, so retry with a brief backoff if a fresh listing is missing.
4871
4994
  * - Results are cross-scheme (mostly the mainstream `exact` scheme); `fetch()` pays
4872
- * only `onchain-proof` rails directly (pay `exact` resources with the experimental
4873
- * `drivers/evm/exact.ts`).
4995
+ * `onchain-proof` rails by default, and standard `exact` rails too once you opt in
4996
+ * with `schemes: ['onchain-proof', 'exact']` (EVM + EIP-3009 — USDC/EURC).
4874
4997
  */
4875
4998
  discover(opts?: DiscoverOptions): Promise<DiscoveredResource[]>;
4876
4999
  /**
@@ -4937,17 +5060,21 @@ declare class PipRailClient {
4937
5060
  * twice (once to fetch the 402, once with the proof attached). One-shot
4938
5061
  * streams throw `NonReplayableBodyError`.
4939
5062
  */
4940
- fetch(url: string, init?: RequestInit): Promise<Response>;
5063
+ fetch(url: string, init?: RequestInit & {
5064
+ autoRoute?: boolean;
5065
+ schemes?: PaymentScheme[];
5066
+ }): Promise<Response>;
4941
5067
  /**
4942
5068
  * From a confirmed-402 response: parse the challenge, mount + bind the
4943
5069
  * network, pick the accept the client can pay, and build its quote. Shared by
4944
5070
  * `quote()` (read-only) and `fetch()` (which then authorises + pays).
4945
5071
  */
4946
5072
  private resolveChallenge;
4947
- /** The candidate accepts this client could pay: our scheme, on the bound network.
4948
- * A dual-advertised challenge may also carry standard `exact` rails the PipRail
4949
- * client ignores those (it pays the backendless `onchain-proof` rail); the type
4950
- * predicate narrows the `X402AnyAccept` union to the rails we settle. */
5073
+ /** The candidate accepts this client could pay, on the bound network. Always the
5074
+ * backendless `onchain-proof` rails; PLUS standard `exact` rails when `schemes`
5075
+ * enables them AND the driver can settle them (EVM `payExact` + a recognised
5076
+ * EIP-3009 token). `onchain-proof` is gathered FIRST so default selection is
5077
+ * unchanged when `exact` is off. */
4951
5078
  private gatherCandidates;
4952
5079
  /** Build the full {@link PaymentPlan} from an already-parsed challenge + bound
4953
5080
  * net/wallet. Shared by `planPayment` (read-only) and `fetch`'s autoRoute. */
@@ -4965,6 +5092,24 @@ declare class PipRailClient {
4965
5092
  private recordSpend;
4966
5093
  private payAndConfirm;
4967
5094
  private retryWithProof;
5095
+ /**
5096
+ * Pay a standard x402 `exact` rail — a SEPARATE, fundamentally more conservative
5097
+ * path than {@link retryWithProof}. The buyer SIGNS an EIP-3009 authorization ONCE
5098
+ * (the driver's `payExact`) and the server / merchant-chosen facilitator BROADCASTS
5099
+ * it synchronously, so a blind re-POST of a still-in-flight authorization could
5100
+ * double-BROADCAST it. Hence, unlike the onchain-proof loop:
5101
+ *
5102
+ * • sign exactly once — reuse the SAME header on every retry, never re-sign;
5103
+ * • retry ONLY an explicit 402 (a definitive pre-broadcast rejection), bounded
5104
+ * well under `maxTimeoutSeconds` so the loop can't outlive the authorization;
5105
+ * • a post-POST transport error/timeout → {@link PaymentTimeoutError} carrying the
5106
+ * nonce (the facilitator MAY have settled — verify on-chain, NEVER re-pay);
5107
+ * • a 5xx → return as-is (server settle failure; the authorization stays valid +
5108
+ * its nonce unused) — no settled event, no spend;
5109
+ * • a 200 whose SettleResponse says `success:false` → a rejection, NEVER a spend;
5110
+ * • the spend is recorded EXACTLY ONCE, on an affirmative settlement only.
5111
+ */
5112
+ private payExactRail;
4968
5113
  }
4969
5114
  /**
4970
5115
  * Plan a payment ACROSS several single-chain clients — the cross-chain brain.
@@ -5614,7 +5759,14 @@ declare class PaymentTimeoutError extends PipRailError {
5614
5759
  */
5615
5760
  declare class MaxRetriesExceededError extends PipRailError {
5616
5761
  readonly code = "MAX_RETRIES_EXCEEDED";
5617
- /** The already-broadcast proof ref — recover with it, don't re-pay. */
5762
+ /**
5763
+ * The proof ref — recover with it, don't re-pay. Its meaning depends on the
5764
+ * scheme: for `onchain-proof` it's the already-broadcast transaction ref
5765
+ * (re-verify or re-submit it). For a standard `exact` rail it's the EIP-3009
5766
+ * authorization NONCE (a `0x…` 32-byte value, NOT a tx hash) — re-PRESENT the
5767
+ * same signed authorization, never re-sign a fresh nonce; check the token's
5768
+ * `authorizationState(from, nonce)` before assuming it didn't settle.
5769
+ */
5618
5770
  readonly ref?: string;
5619
5771
  constructor(message: string, options?: ErrorOptions & {
5620
5772
  ref?: string;
@@ -5667,6 +5819,22 @@ declare class InvalidEnvelopeError extends PipRailError {
5667
5819
  declare class NoCompatibleAcceptError extends PipRailError {
5668
5820
  readonly code = "NO_COMPATIBLE_ACCEPT";
5669
5821
  }
5822
+ /**
5823
+ * The client was asked to pay a SCHEME the bound chain family/asset/signer can't
5824
+ * settle, and no fallback rail was offered. Specifically: a standard `exact` rail
5825
+ * on a non-EVM family (only EVM ships the buyer `payExact`); an `exact` rail for a
5826
+ * token that isn't EIP-3009 (USDT needs Permit2, native isn't exact-payable, a
5827
+ * plain ERC-20 has no `transferWithAuthorization`); or an `exact` rail whose signer
5828
+ * is a contract / EIP-1271 / EIP-7702-delegated account (no recoverable ECDSA sig).
5829
+ *
5830
+ * Distinct from {@link NoCompatibleAcceptError} (no rail for the network at all)
5831
+ * and {@link WrongFamilyError} (the wallet/payTo/token was given in another
5832
+ * family's shape). The fix is usually "enable/keep an `onchain-proof` rail" or
5833
+ * "pay with a supported chain/token". Thrown by the client / the EVM driver.
5834
+ */
5835
+ declare class UnsupportedSchemeError extends PipRailError {
5836
+ readonly code = "UNSUPPORTED_SCHEME";
5837
+ }
5670
5838
  /** init.body was provided but isn't replayable (e.g. a one-shot ReadableStream). */
5671
5839
  declare class NonReplayableBodyError extends PipRailError {
5672
5840
  readonly code = "NON_REPLAYABLE_BODY";
@@ -5717,10 +5885,12 @@ declare class UnsupportedNetworkError extends PipRailError {
5717
5885
  * x402 `exact` interop, in BOTH directions, EVM + EIP-3009 only, on the existing
5718
5886
  * `viem` peer (no new dep):
5719
5887
  *
5720
- * • BUYER side (client) — parse an `exact` requirement, build + EIP-712-sign the
5721
- * EIP-3009 authorization, encode the `X-PAYMENT` header. Deterministic,
5722
- * unit-testable; NOT wired into `PipRailClient.fetch`'s default (see
5723
- * `.claude/plans/agent-readiness/04-universal-exact.md`).
5888
+ * • BUYER side (client) — {@link payExactEvm} re-derives the token's EIP-712 domain
5889
+ * ON-CHAIN, signs the EIP-3009 authorization, and is wired into `PipRailClient`'s
5890
+ * pay path via the EVM driver's `payExact` SPI (OPT-IN through `schemes: ['exact']`;
5891
+ * the default is unchanged). The lower-level `buildExactAuthorization` /
5892
+ * `encodeXPaymentHeader` codecs remain for hand-rolled/v1 clients. See
5893
+ * `.claude/plans/exact-client/IMPLEMENTATION.md`.
5724
5894
  *
5725
5895
  * • SELLER side (gate) — {@link readExactDomain} (read the token's true EIP-712
5726
5896
  * domain so the gate can advertise + verify it) and {@link verifyAndSettleExactEvm}
@@ -5812,6 +5982,13 @@ interface BuildExactParams {
5812
5982
  * Build + EIP-712-sign an EIP-3009 `transferWithAuthorization` for an `exact`
5813
5983
  * requirement. Returns the authorization and its signature; pass both to
5814
5984
  * {@link encodeXPaymentHeader} to produce the `X-PAYMENT` header value.
5985
+ *
5986
+ * @deprecated Low-level primitive — prefer {@link payExactEvm}, which the client's
5987
+ * `payExact` SPI uses. This helper TRUSTS the server-supplied `accept.extra.{name,
5988
+ * version}` for the EIP-712 domain (a lying/absent value yields a silently-invalid
5989
+ * signature) and calls `account.signTypedData` directly (which is `undefined` on a
5990
+ * bring-your-own JsonRpcAccount). `payExactEvm` re-derives the domain on-chain and
5991
+ * signs via the wallet client. Kept exported as a deterministic test/codec building block.
5815
5992
  */
5816
5993
  declare function buildExactAuthorization(params: BuildExactParams): Promise<{
5817
5994
  authorization: ExactAuthorization;
@@ -5938,13 +6115,14 @@ declare const eip3009Abi: readonly [{
5938
6115
  * plain ERC-20), so the gate refuses to advertise a standard `exact` rail for it.
5939
6116
  *
5940
6117
  * The name is NEVER assumed from the symbol: canonical USDC's domain name is
5941
- * "USD Coin" (not "USDC"), EURC's is "EURC". `eip712Domain()` (EIP-5267) reverts
5942
- * on these proxies, so we read `name()`+`version()` and probe `authorizationState`
5943
- * to confirm EIP-3009 support.
6118
+ * "USD Coin" (not "USDC"), and EURC's is "Euro Coin" on Ethereum/Avalanche but "EURC"
6119
+ * on Base proof that only the on-chain read is authoritative. `eip712Domain()`
6120
+ * (EIP-5267) reverts on these proxies, so we read `name()`+`version()` and probe
6121
+ * `authorizationState` to confirm EIP-3009 support.
5944
6122
  */
5945
6123
  declare function readExactDomain(publicClient: PublicClient, asset: string): Promise<{
5946
6124
  name: string;
5947
6125
  version: string;
5948
6126
  } | null>;
5949
6127
 
5950
- export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildBazaarExtension, buildChallengeHeader, buildExactAuthorization, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, createPaymentGate, decorateOutcome, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, getDirectoryInfo, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };
6128
+ export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildBazaarExtension, buildChallengeHeader, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, createPaymentGate, decorateOutcome, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, getDirectoryInfo, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };