@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.
- package/CHAINS.md +3 -2
- package/CHANGELOG.md +49 -0
- package/ERRORS.md +2 -1
- package/README.md +19 -2
- package/STANDARDS.md +2 -0
- package/dist/{algorand-WGVF4KTU.js → algorand-7EUZYL2Z.js} +1 -1
- package/dist/{algorand-MXUSKX46.cjs → algorand-OIHGJN5S.cjs} +17 -17
- package/dist/{aptos-LPBLSEIQ.js → aptos-CDEYDDM5.js} +1 -1
- package/dist/{aptos-YT7SXWPF.cjs → aptos-WDWZOU25.cjs} +16 -16
- package/dist/{chunk-MDLZJGLY.cjs → chunk-FTKVCP6K.cjs} +24 -13
- package/dist/{chunk-SVMGHASK.js → chunk-H3A4KWLJ.js} +12 -1
- package/dist/index.cjs +399 -145
- package/dist/index.d.cts +209 -31
- package/dist/index.d.ts +209 -31
- package/dist/index.js +308 -54
- package/dist/{near-K6BDBABG.js → near-DT6LRIKB.js} +1 -1
- package/dist/{near-7ZDNISUX.cjs → near-FUH3VAXT.cjs} +19 -19
- package/dist/{solana-S3UFI3FE.js → solana-3TRYD4QB.js} +1 -1
- package/dist/{solana-PU7N2M64.cjs → solana-QUVXPKBZ.cjs} +14 -14
- package/dist/{stellar-VDQOFQEO.cjs → stellar-APZEBFAD.cjs} +21 -21
- package/dist/{stellar-Q5PO23SC.js → stellar-IK3UML6O.js} +1 -1
- package/dist/{sui-FKSMLKRF.cjs → sui-L7BQNJWO.cjs} +17 -17
- package/dist/{sui-WOXRKJXS.js → sui-VSE63WQM.js} +1 -1
- package/dist/{ton-VK6KRJHP.cjs → ton-5DLKKOFE.cjs} +14 -14
- package/dist/{ton-WPTXGLVK.js → ton-QHGQLJX2.js} +1 -1
- package/dist/{tron-6GXBXTR4.js → tron-2N2GA62O.js} +1 -1
- package/dist/{tron-WLOF5OUV.cjs → tron-HHIT6WKY.cjs} +24 -24
- package/dist/{xrpl-HEAPEXAM.js → xrpl-2GZMDYW5.js} +1 -1
- package/dist/{xrpl-CMNI25BV.cjs → xrpl-USEG4AHX.cjs} +21 -21
- 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
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
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
|
|
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
|
|
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
|
|
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:
|
|
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 "
|
|
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:
|
|
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
|
-
|
|
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
|
-
*
|
|
4873
|
-
* `
|
|
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
|
|
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
|
|
4948
|
-
*
|
|
4949
|
-
*
|
|
4950
|
-
*
|
|
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
|
-
/**
|
|
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) —
|
|
5721
|
-
* EIP-3009 authorization,
|
|
5722
|
-
*
|
|
5723
|
-
*
|
|
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 "
|
|
5942
|
-
* on
|
|
5943
|
-
*
|
|
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 };
|