@agirails/sdk 3.2.0 → 3.3.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 (209) hide show
  1. package/LICENSE +1 -1
  2. package/README.md +12 -14
  3. package/dist/ACTPClient.d.ts +8 -11
  4. package/dist/ACTPClient.d.ts.map +1 -1
  5. package/dist/ACTPClient.js +79 -20
  6. package/dist/ACTPClient.js.map +1 -1
  7. package/dist/__tests__/helpers/mockX402Server.d.ts +67 -0
  8. package/dist/__tests__/helpers/mockX402Server.d.ts.map +1 -0
  9. package/dist/__tests__/helpers/mockX402Server.js +121 -0
  10. package/dist/__tests__/helpers/mockX402Server.js.map +1 -0
  11. package/dist/adapters/BaseAdapter.d.ts +7 -1
  12. package/dist/adapters/BaseAdapter.d.ts.map +1 -1
  13. package/dist/adapters/BaseAdapter.js +11 -6
  14. package/dist/adapters/BaseAdapter.js.map +1 -1
  15. package/dist/adapters/BasicAdapter.d.ts.map +1 -1
  16. package/dist/adapters/BasicAdapter.js +12 -2
  17. package/dist/adapters/BasicAdapter.js.map +1 -1
  18. package/dist/adapters/StandardAdapter.d.ts.map +1 -1
  19. package/dist/adapters/StandardAdapter.js +12 -2
  20. package/dist/adapters/StandardAdapter.js.map +1 -1
  21. package/dist/adapters/X402Adapter.d.ts +161 -199
  22. package/dist/adapters/X402Adapter.d.ts.map +1 -1
  23. package/dist/adapters/X402Adapter.js +603 -414
  24. package/dist/adapters/X402Adapter.js.map +1 -1
  25. package/dist/adapters/index.d.ts +1 -1
  26. package/dist/adapters/index.d.ts.map +1 -1
  27. package/dist/adapters/index.js.map +1 -1
  28. package/dist/builders/DeliveryProofBuilder.d.ts.map +1 -1
  29. package/dist/builders/DeliveryProofBuilder.js +3 -2
  30. package/dist/builders/DeliveryProofBuilder.js.map +1 -1
  31. package/dist/cli/agirails.js +12 -4
  32. package/dist/cli/agirails.js.map +1 -1
  33. package/dist/cli/commands/autopublish.js +9 -1
  34. package/dist/cli/commands/autopublish.js.map +1 -1
  35. package/dist/cli/commands/config.js +1 -12
  36. package/dist/cli/commands/config.js.map +1 -1
  37. package/dist/cli/commands/deploy-env.js +1 -1
  38. package/dist/cli/commands/deploy-env.js.map +1 -1
  39. package/dist/cli/commands/diff.js +38 -4
  40. package/dist/cli/commands/diff.js.map +1 -1
  41. package/dist/cli/commands/health.js +3 -1
  42. package/dist/cli/commands/health.js.map +1 -1
  43. package/dist/cli/commands/init.d.ts +2 -0
  44. package/dist/cli/commands/init.d.ts.map +1 -1
  45. package/dist/cli/commands/init.js +75 -2
  46. package/dist/cli/commands/init.js.map +1 -1
  47. package/dist/cli/commands/pay.d.ts.map +1 -1
  48. package/dist/cli/commands/pay.js +23 -0
  49. package/dist/cli/commands/pay.js.map +1 -1
  50. package/dist/cli/commands/publish.js +15 -8
  51. package/dist/cli/commands/publish.js.map +1 -1
  52. package/dist/cli/commands/pull.js +3 -1
  53. package/dist/cli/commands/pull.js.map +1 -1
  54. package/dist/cli/commands/receipt.d.ts +17 -3
  55. package/dist/cli/commands/receipt.d.ts.map +1 -1
  56. package/dist/cli/commands/receipt.js +95 -33
  57. package/dist/cli/commands/receipt.js.map +1 -1
  58. package/dist/cli/commands/test.d.ts.map +1 -1
  59. package/dist/cli/commands/test.js +222 -60
  60. package/dist/cli/commands/test.js.map +1 -1
  61. package/dist/cli/commands/tx.js +13 -0
  62. package/dist/cli/commands/tx.js.map +1 -1
  63. package/dist/cli/index.js +3 -1
  64. package/dist/cli/index.js.map +1 -1
  65. package/dist/cli/receiptUpload.d.ts +52 -0
  66. package/dist/cli/receiptUpload.d.ts.map +1 -0
  67. package/dist/cli/receiptUpload.js +134 -0
  68. package/dist/cli/receiptUpload.js.map +1 -0
  69. package/dist/cli/utils/banner.d.ts +31 -0
  70. package/dist/cli/utils/banner.d.ts.map +1 -0
  71. package/dist/cli/utils/banner.js +92 -0
  72. package/dist/cli/utils/banner.js.map +1 -0
  73. package/dist/cli/utils/config.d.ts +0 -2
  74. package/dist/cli/utils/config.d.ts.map +1 -1
  75. package/dist/cli/utils/config.js +40 -25
  76. package/dist/cli/utils/config.js.map +1 -1
  77. package/dist/cli/utils/output.d.ts +2 -0
  78. package/dist/cli/utils/output.d.ts.map +1 -1
  79. package/dist/cli/utils/output.js +7 -1
  80. package/dist/cli/utils/output.js.map +1 -1
  81. package/dist/cli/utils/share.d.ts +51 -0
  82. package/dist/cli/utils/share.d.ts.map +1 -0
  83. package/dist/cli/utils/share.js +133 -0
  84. package/dist/cli/utils/share.js.map +1 -0
  85. package/dist/config/agirailsmd.d.ts.map +1 -1
  86. package/dist/config/agirailsmd.js +2 -1
  87. package/dist/config/agirailsmd.js.map +1 -1
  88. package/dist/config/defaults.d.ts +2 -2
  89. package/dist/config/defaults.d.ts.map +1 -1
  90. package/dist/config/defaults.js +9 -3
  91. package/dist/config/defaults.js.map +1 -1
  92. package/dist/config/networks.d.ts +7 -0
  93. package/dist/config/networks.d.ts.map +1 -1
  94. package/dist/config/networks.js +20 -11
  95. package/dist/config/networks.js.map +1 -1
  96. package/dist/config/pendingPublish.d.ts.map +1 -1
  97. package/dist/config/pendingPublish.js +10 -3
  98. package/dist/config/pendingPublish.js.map +1 -1
  99. package/dist/config/syncOperations.d.ts.map +1 -1
  100. package/dist/config/syncOperations.js +4 -2
  101. package/dist/config/syncOperations.js.map +1 -1
  102. package/dist/erc8004/ERC8004Bridge.d.ts.map +1 -1
  103. package/dist/erc8004/ERC8004Bridge.js +0 -1
  104. package/dist/erc8004/ERC8004Bridge.js.map +1 -1
  105. package/dist/errors/ACTPError.d.ts +24 -0
  106. package/dist/errors/ACTPError.d.ts.map +1 -0
  107. package/dist/errors/ACTPError.js +35 -0
  108. package/dist/errors/ACTPError.js.map +1 -0
  109. package/dist/errors/X402Errors.d.ts +106 -0
  110. package/dist/errors/X402Errors.d.ts.map +1 -0
  111. package/dist/errors/X402Errors.js +160 -0
  112. package/dist/errors/X402Errors.js.map +1 -0
  113. package/dist/errors/index.d.ts +3 -9
  114. package/dist/errors/index.d.ts.map +1 -1
  115. package/dist/errors/index.js +38 -33
  116. package/dist/errors/index.js.map +1 -1
  117. package/dist/index.d.ts +2 -1
  118. package/dist/index.d.ts.map +1 -1
  119. package/dist/index.js +15 -3
  120. package/dist/index.js.map +1 -1
  121. package/dist/level0/Provider.d.ts +5 -0
  122. package/dist/level0/Provider.d.ts.map +1 -1
  123. package/dist/level0/ServiceDirectory.d.ts.map +1 -1
  124. package/dist/level0/ServiceDirectory.js +3 -2
  125. package/dist/level0/ServiceDirectory.js.map +1 -1
  126. package/dist/level0/provide.d.ts.map +1 -1
  127. package/dist/level0/provide.js +11 -8
  128. package/dist/level0/provide.js.map +1 -1
  129. package/dist/level0/request.d.ts.map +1 -1
  130. package/dist/level0/request.js +14 -6
  131. package/dist/level0/request.js.map +1 -1
  132. package/dist/level1/Agent.d.ts +1 -1
  133. package/dist/level1/Agent.d.ts.map +1 -1
  134. package/dist/level1/Agent.js +12 -6
  135. package/dist/level1/Agent.js.map +1 -1
  136. package/dist/level1/pricing/PriceCalculator.d.ts.map +1 -1
  137. package/dist/level1/pricing/PriceCalculator.js +4 -12
  138. package/dist/level1/pricing/PriceCalculator.js.map +1 -1
  139. package/dist/protocol/ACTPKernel.d.ts +4 -1
  140. package/dist/protocol/ACTPKernel.d.ts.map +1 -1
  141. package/dist/protocol/ACTPKernel.js +2 -1
  142. package/dist/protocol/ACTPKernel.js.map +1 -1
  143. package/dist/protocol/EventMonitor.d.ts +27 -1
  144. package/dist/protocol/EventMonitor.d.ts.map +1 -1
  145. package/dist/protocol/EventMonitor.js +11 -9
  146. package/dist/protocol/EventMonitor.js.map +1 -1
  147. package/dist/protocol/ProofGenerator.d.ts.map +1 -1
  148. package/dist/protocol/ProofGenerator.js +3 -2
  149. package/dist/protocol/ProofGenerator.js.map +1 -1
  150. package/dist/runtime/BlockchainRuntime.d.ts +2 -0
  151. package/dist/runtime/BlockchainRuntime.d.ts.map +1 -1
  152. package/dist/runtime/BlockchainRuntime.js +19 -6
  153. package/dist/runtime/BlockchainRuntime.js.map +1 -1
  154. package/dist/runtime/MockRuntime.d.ts +3 -2
  155. package/dist/runtime/MockRuntime.d.ts.map +1 -1
  156. package/dist/runtime/MockRuntime.js +16 -22
  157. package/dist/runtime/MockRuntime.js.map +1 -1
  158. package/dist/runtime/types/MockState.d.ts +4 -0
  159. package/dist/runtime/types/MockState.d.ts.map +1 -1
  160. package/dist/runtime/types/MockState.js.map +1 -1
  161. package/dist/server/buildX402Server.d.ts +131 -0
  162. package/dist/server/buildX402Server.d.ts.map +1 -0
  163. package/dist/server/buildX402Server.js +151 -0
  164. package/dist/server/buildX402Server.js.map +1 -0
  165. package/dist/server/index.d.ts +33 -0
  166. package/dist/server/index.d.ts.map +1 -0
  167. package/dist/server/index.js +36 -0
  168. package/dist/server/index.js.map +1 -0
  169. package/dist/types/adapter.d.ts +42 -12
  170. package/dist/types/adapter.d.ts.map +1 -1
  171. package/dist/types/adapter.js +6 -1
  172. package/dist/types/adapter.js.map +1 -1
  173. package/dist/types/eip712.d.ts +20 -0
  174. package/dist/types/eip712.d.ts.map +1 -1
  175. package/dist/types/x402.d.ts +8 -8
  176. package/dist/utils/security.d.ts.map +1 -1
  177. package/dist/utils/security.js +4 -6
  178. package/dist/utils/security.js.map +1 -1
  179. package/dist/wallet/AutoWalletProvider.d.ts +45 -1
  180. package/dist/wallet/AutoWalletProvider.d.ts.map +1 -1
  181. package/dist/wallet/AutoWalletProvider.js +154 -1
  182. package/dist/wallet/AutoWalletProvider.js.map +1 -1
  183. package/dist/wallet/EOAWalletProvider.d.ts +13 -1
  184. package/dist/wallet/EOAWalletProvider.d.ts.map +1 -1
  185. package/dist/wallet/EOAWalletProvider.js +24 -0
  186. package/dist/wallet/EOAWalletProvider.js.map +1 -1
  187. package/dist/wallet/IWalletProvider.d.ts +34 -0
  188. package/dist/wallet/IWalletProvider.d.ts.map +1 -1
  189. package/dist/wallet/SmartWalletRouter.d.ts.map +1 -1
  190. package/dist/wallet/SmartWalletRouter.js +3 -1
  191. package/dist/wallet/SmartWalletRouter.js.map +1 -1
  192. package/dist/wallet/aa/BundlerClient.js +8 -4
  193. package/dist/wallet/aa/BundlerClient.js.map +1 -1
  194. package/dist/wallet/aa/DualNonceManager.d.ts +4 -1
  195. package/dist/wallet/aa/DualNonceManager.d.ts.map +1 -1
  196. package/dist/wallet/aa/DualNonceManager.js +3 -0
  197. package/dist/wallet/aa/DualNonceManager.js.map +1 -1
  198. package/dist/wallet/keystore.d.ts.map +1 -1
  199. package/dist/wallet/keystore.js +6 -4
  200. package/dist/wallet/keystore.js.map +1 -1
  201. package/package.json +16 -3
  202. package/dist/adapters/BeginnerAdapter.d.ts +0 -152
  203. package/dist/adapters/BeginnerAdapter.d.ts.map +0 -1
  204. package/dist/adapters/BeginnerAdapter.js +0 -168
  205. package/dist/adapters/BeginnerAdapter.js.map +0 -1
  206. package/dist/adapters/IntermediateAdapter.d.ts +0 -211
  207. package/dist/adapters/IntermediateAdapter.d.ts.map +0 -1
  208. package/dist/adapters/IntermediateAdapter.js +0 -260
  209. package/dist/adapters/IntermediateAdapter.js.map +0 -1
@@ -1,249 +1,211 @@
1
1
  /**
2
- * X402Adapter - HTTP 402 Payment Required Protocol (Atomic Payments)
2
+ * X402Adapter real x402 v2 protocol support.
3
3
  *
4
- * Implements the x402 protocol for atomic, instant API payments.
5
- * NO escrow, NO state machine, NO disputes - just pay and receive.
4
+ * Thin wrapper around official @x402/fetch + @x402/evm + @x402/core packages.
5
+ * Replaces the legacy custom `x-payment-*` HTTP flow (which was never real x402)
6
+ * with proper EIP-3009 / Permit2 wire format for full interoperability with
7
+ * any x402 v2 seller (Coinbase demo, third-party servers, AGIRAILS sellers).
6
8
  *
7
- * This is fundamentally different from ACTP:
8
- * - ACTP: escrow state machine disputes → explicit release
9
- * - x402: atomic payment instant settlement done
9
+ * Architecture:
10
+ * - Buyer signs EIP-3009 authorization or Permit2 witness OFF-CHAIN
11
+ * - Facilitator (server-configured) submits on-chain tx and pays gas
12
+ * - Buyer is always gassless for x402 by protocol design
13
+ * - Smart Wallet buyers use Permit2 path (ERC-1271 + ERC-6492 via viem)
14
+ * - EOA buyers use either path
10
15
  *
11
- * Use x402 for:
12
- * - Simple API calls (pay-per-request)
13
- * - Instant delivery (response IS the delivery)
14
- * - Low-value, high-frequency transactions
16
+ * Zero fee layer: payTo goes directly to seller. X402Relay is never used.
17
+ * Zero reputation hooks: ERC-8004 registry never touched on x402 payments.
15
18
  *
16
- * Use ACTP for:
17
- * - Complex services requiring verification
18
- * - High-value transactions needing dispute protection
19
- * - Multi-step deliveries
19
+ * Architecture rationale and Smart Wallet signing flow are documented in
20
+ * the project's internal x402 v2 implementation notes.
20
21
  *
21
22
  * @module adapters/X402Adapter
22
23
  */
23
- import { BaseAdapter } from './BaseAdapter';
24
24
  import { IAdapter, TransactionStatus } from './IAdapter';
25
- import { AdapterMetadata, UnifiedPayParams, UnifiedPayResult } from '../types/adapter';
26
- import { X402Network } from '../types/x402';
27
- /** Type for fetch function (cross-platform compatible) */
28
- export type FetchFunction = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
25
+ import { UnifiedPayParams, UnifiedPayResult, AdapterMetadata } from '../types/adapter';
26
+ import { IWalletProvider } from '../wallet/IWalletProvider';
29
27
  /**
30
- * Transaction-like receipt returned by wallet abstractions.
28
+ * Configuration for X402Adapter.
31
29
  *
32
- * `success` is optional for backward compatibility with legacy transfer fns
33
- * that only return a hash string.
34
- */
35
- export interface TransferReceiptLike {
36
- hash: string;
37
- success?: boolean;
38
- }
39
- /**
40
- * Transfer function for atomic USDC payments.
41
- *
42
- * @param to - Recipient address
43
- * @param amount - Amount in USDC wei (string)
44
- * @returns Transaction hash string OR receipt-like object with hash/success
45
- */
46
- export type TransferFunction = (to: string, amount: string) => Promise<string | TransferReceiptLike>;
47
- /**
48
- * Approve function for USDC allowance (used with X402Relay).
49
- *
50
- * @param spender - Spender address (relay contract)
51
- * @param amount - Amount in USDC wei (string)
52
- * @returns Transaction hash
53
- */
54
- export type ApproveFunction = (spender: string, amount: string) => Promise<string>;
55
- /**
56
- * Relay pay function — calls X402Relay.payWithFee().
57
- *
58
- * @param provider - Provider address
59
- * @param grossAmount - Gross USDC amount (string)
60
- * @param serviceId - Service identifier (bytes32 hex)
61
- * @returns Transaction hash
62
- */
63
- export type RelayPayFunction = (provider: string, grossAmount: string, serviceId: string) => Promise<string>;
64
- /** Supported HTTP methods for x402 requests */
65
- export type X402HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
66
- /**
67
- * Extended payment parameters for x402 with full HTTP support.
68
- */
69
- export interface X402PayParams extends UnifiedPayParams {
70
- /** HTTP method (default: GET) */
71
- method?: X402HttpMethod;
72
- /** Custom request headers */
73
- headers?: Record<string, string>;
74
- /** Request body (string or object, will be JSON.stringify'd if object) */
75
- body?: string | Record<string, unknown>;
76
- /** Content-Type header (default: application/json for POST/PUT/PATCH with body) */
77
- contentType?: string;
78
- }
79
- /**
80
- * Configuration options for X402Adapter.
81
- *
82
- * Fee collection is required (since v2.6.0). Two modes:
83
- * - Relay (preferred): relayAddress + approveFn + relayPayFn — atomic on-chain split
84
- * - feeCollector (fallback): feeCollector address — client-side two-transfer split
30
+ * Auto-registered by ACTPClient when walletProvider implements signTypedData.
31
+ * Manual instantiation is supported but rarely needed — in most cases use
32
+ * ACTPClient auto-registration defaults or register a custom adapter instance.
85
33
  */
86
34
  export interface X402AdapterConfig {
87
- /** Expected network for validation (must match server's X-Payment-Network) */
88
- expectedNetwork: X402Network;
89
- /** Transfer function for USDC payments (used in feeCollector path for provider + fee transfers) */
90
- transferFn: TransferFunction;
91
- /** Request timeout in milliseconds (default: 30000) */
92
- requestTimeout?: number;
93
- /** Custom fetch function for testing (default: global fetch) */
94
- fetchFn?: FetchFunction;
95
- /** Default headers to include in all requests */
96
- defaultHeaders?: Record<string, string>;
97
- /** X402Relay contract address for on-chain fee splitting (preferred) */
98
- relayAddress?: string;
99
- /** USDC approve function — required when relayAddress is set */
100
- approveFn?: ApproveFunction;
101
- /** Relay payWithFee function — required when relayAddress is set */
102
- relayPayFn?: RelayPayFunction;
103
- /** Fee collector address for client-side fee splitting (fallback when relay not available) */
104
- feeCollector?: string;
105
- /** Platform fee in basis points (default: 100 = 1%). Read-only display hint. */
106
- platformFeeBps?: number;
107
- }
108
- /**
109
- * X402Adapter - Atomic HTTP payment protocol.
110
- *
111
- * Key characteristics:
112
- * - usesEscrow: false (direct payment)
113
- * - supportsDisputes: false (atomic = final)
114
- * - settlementMode: 'atomic' (instant)
115
- * - releaseRequired: false (no escrow to release)
116
- *
117
- * @example
118
- * ```typescript
119
- * const adapter = new X402Adapter(requesterAddress, {
120
- * expectedNetwork: 'base-sepolia',
121
- * transferFn: async (to, amount) => {
122
- * const tx = await usdcContract.transfer(to, amount);
123
- * return tx.hash;
124
- * },
125
- * feeCollector: '0x...treasury', // Required: AGIRAILS fee recipient
126
- * });
127
- *
128
- * const result = await adapter.pay({
129
- * to: 'https://api.provider.com/service',
130
- * amount: '10', // Hint only, actual amount from 402
131
- * });
132
- *
133
- * // That's it! No release() needed.
134
- * console.log(result.response?.status); // 200
135
- * console.log(result.releaseRequired); // false
136
- * ```
137
- */
138
- export declare class X402Adapter extends BaseAdapter implements IAdapter {
139
- private config;
140
35
  /**
141
- * Adapter metadata - atomic, no escrow.
36
+ * Wallet provider for signing payment authorizations.
37
+ * Both `EOAWalletProvider` (Tier 2) and `AutoWalletProvider` (Tier 1 Smart Wallet)
38
+ * are supported as long as the provider implements the optional
39
+ * `signTypedData` method.
142
40
  */
143
- readonly metadata: AdapterMetadata;
144
- private readonly timeout;
145
- private readonly fetchFn;
146
- private readonly defaultHeaders;
147
- private readonly transferFn;
148
- /** Local cache of payments for status lookups */
149
- private readonly payments;
41
+ walletProvider: IWalletProvider;
150
42
  /**
151
- * Creates a new X402Adapter instance.
43
+ * Optional CAIP-2 network allowlist (e.g. `["eip155:8453", "eip155:84532"]`).
152
44
  *
153
- * @param requesterAddress - The requester's Ethereum address
154
- * @param config - X402-specific configuration
45
+ * Leave undefined (default) to allow ANY EVM network @x402/evm supports —
46
+ * this is the "works with anyone" interop default. Set an explicit list
47
+ * only if you want to restrict your agent to specific chains.
155
48
  */
156
- constructor(requesterAddress: string, config: X402AdapterConfig);
49
+ allowedNetworks?: ReadonlyArray<string>;
157
50
  /**
158
- * Check if this adapter can handle the given parameters.
159
- *
160
- * X402Adapter handles HTTPS URLs only (security requirement).
51
+ * Per-transaction safety cap in human-readable USD (e.g. "1" for $1 USDC).
52
+ * Protects against accidentally paying unexpectedly high prices.
53
+ * Default: "1"
161
54
  */
162
- canHandle(params: UnifiedPayParams): boolean;
55
+ maxAmountPerTx?: string;
163
56
  /**
164
- * Validate parameters before execution.
57
+ * Automatically run one-time Permit2 USDC approve on first Smart Wallet
58
+ * x402 payment. The approve is sponsored by the existing paymaster and
59
+ * costs nothing to the user in gas. Default: true.
165
60
  */
166
- validate(params: UnifiedPayParams): void;
61
+ autoApprovePermit2?: boolean;
167
62
  /**
168
- * Execute atomic x402 payment flow with full HTTP support.
169
- *
170
- * 1. Request endpoint get 402
171
- * 2. Parse payment headers
172
- * 3. Execute atomic USDC transfer
173
- * 4. Retry with tx hash as proof (same method/headers/body)
174
- * 5. Return response (settlement complete!)
175
- *
176
- * @param params - Payment parameters with optional HTTP method, headers, body
63
+ * MEV hard cap on signed authorization validity window in seconds.
64
+ * Facilitator/server may propose longer `maxTimeoutSeconds`, but we clamp
65
+ * to this value before signing. Default: 300 (5 minutes).
177
66
  */
178
- pay(params: UnifiedPayParams | X402PayParams): Promise<UnifiedPayResult>;
67
+ maxAuthorizationValidSec?: number;
179
68
  /**
180
- * Serialize request body to string.
69
+ * Allowlist of asset token contract addresses the adapter will pay.
70
+ *
71
+ * Undefined (default) = all canonical USDC addresses on the configured
72
+ * `allowedNetworks` (see `DEFAULT_USDC_BY_NETWORK`). Set to a specific
73
+ * list to restrict further, or pass an empty array to allow any asset
74
+ * (NOT recommended — removes the safety check entirely).
75
+ *
76
+ * P1-1: prevents a server from advertising a different token (e.g., USDT
77
+ * on the same network, or a scam token) and having the adapter sign a
78
+ * payment for it. The cap check in `parseUsdcAmount` / `formatUsdcAmount`
79
+ * assumes 6 decimals, which is only accurate for USDC-family stables.
80
+ * Honoring a non-USDC asset with different decimals would also break the
81
+ * `maxAmountPerTx` cap.
82
+ *
83
+ * Addresses are compared case-insensitively.
181
84
  */
182
- private serializeBody;
85
+ allowedAssets?: ReadonlyArray<string>;
183
86
  /**
184
- * Get payment status by transaction hash.
87
+ * Allowlist of HTTPS hosts the adapter will pay without requiring explicit
88
+ * opt-in via `metadata.paymentMethod === 'x402'`.
89
+ *
90
+ * Undefined or empty (default) = no host allowlist; callers must always
91
+ * opt in explicitly unless they trust every HTTPS URL their code hits.
92
+ * Set to specific hostnames (e.g. `['x402.org', 'api.mycoinbase.com']`) to
93
+ * whitelist trusted servers for auto-pay.
185
94
  *
186
- * For atomic payments, status is simple:
187
- * - If tx exists SETTLED (atomic = instant settlement)
95
+ * P1-3: prevents accidental `client.pay({ to: 'https://unrelated.com' })`
96
+ * from triggering a silent x402 charge. See `routeHttpsWithOptIn` flow in
97
+ * selectRequirements gate.
188
98
  */
189
- getStatus(txId: string): Promise<TransactionStatus>;
99
+ allowedHosts?: ReadonlyArray<string>;
190
100
  /**
191
- * Not applicable for atomic payments.
192
- * @throws {Error} Always - x402 has no lifecycle
101
+ * Optional fetch override for tests. Defaults to global fetch.
193
102
  */
194
- startWork(_txId: string): Promise<void>;
103
+ fetchImpl?: typeof fetch;
104
+ }
105
+ export declare class X402Adapter implements IAdapter {
106
+ private readonly config;
107
+ readonly metadata: AdapterMetadata;
108
+ private readonly x402;
109
+ private readonly fetchWithPayment;
110
+ private readonly maxAmountPerTx;
111
+ private readonly maxAuthorizationValidSec;
195
112
  /**
196
- * Not applicable for atomic payments.
197
- * @throws {Error} Always - x402 has no lifecycle
113
+ * Cached resolved allowed-network list. Computed once at construction; used
114
+ * on every selectRequirements call without re-running resolveAllowedNetworks.
198
115
  */
199
- deliver(_txId: string, _proof?: string): Promise<void>;
116
+ private readonly allowedNetworks;
200
117
  /**
201
- * Not applicable for atomic payments.
202
- * @throws {Error} Always - x402 has no escrow
118
+ * Cached lowercase set of allowed asset (token contract) addresses.
119
+ * Undefined means user explicitly passed an empty array, which is our
120
+ * sentinel for "any asset" (NOT recommended — skips the safety check).
203
121
  */
204
- release(_escrowId: string, _attestationUID?: string): Promise<void>;
122
+ private readonly allowedAssetsLc;
205
123
  /**
206
- * Make an HTTP request with full options support.
207
- *
208
- * @param url - Request URL
209
- * @param method - HTTP method
210
- * @param customHeaders - Custom headers from request params
211
- * @param body - Request body (optional)
212
- * @param contentType - Content-Type header (optional)
213
- * @param proofHeaders - Payment proof headers for retry (optional)
124
+ * Cached lowercase set of allowed host names. Empty means no host allowlist
125
+ * (user must always opt in via metadata.paymentMethod for every URL).
214
126
  */
215
- private makeRequest;
127
+ private readonly allowedHostsLc;
128
+ /** network:tokenAddress → cached approved state */
129
+ private readonly permit2ApprovedCache;
130
+ /** network:tokenAddress → in-flight approve promise (coalesces concurrent callers) */
131
+ private readonly permit2InflightApprovals;
132
+ /** Completed payment records for getStatus() lookups. Capped to prevent unbounded growth. */
133
+ private readonly payments;
134
+ private static readonly MAX_PAYMENT_RECORDS;
135
+ constructor(config: X402AdapterConfig);
216
136
  /**
217
- * Parse X-Payment-* headers from 402 response.
137
+ * STRICT HTTPS ONLY. `http://` is rejected at the canHandle level to prevent
138
+ * MITM interception of signed payment payloads. Integration tests that need
139
+ * localhost use a dedicated test flag (not exposed to end users).
140
+ *
141
+ * P1-3: canHandle returns true for any HTTPS URL so the router can select
142
+ * this adapter, but `validate()` enforces explicit opt-in before payment
143
+ * actually executes. This keeps the declarative "any HTTPS is x402-capable"
144
+ * shape while protecting against accidental auto-pay.
218
145
  */
219
- private parsePaymentHeaders;
146
+ canHandle(params: UnifiedPayParams): boolean;
147
+ validate(params: UnifiedPayParams): void;
148
+ pay(params: UnifiedPayParams): Promise<UnifiedPayResult>;
149
+ getStatus(txId: string): Promise<TransactionStatus>;
150
+ startWork(_txId: string): Promise<void>;
151
+ deliver(_txId: string, _proof?: string): Promise<void>;
152
+ release(_escrowId: string, _attestationUID?: string): Promise<void>;
220
153
  /**
221
- * Validate payment address from header.
154
+ * Registered as `onBeforePaymentCreation` hook on the x402Client in the
155
+ * constructor. Runs AFTER selectRequirements has chosen a target and BEFORE
156
+ * the scheme client signs the payload.
157
+ *
158
+ * For Smart Wallet + Permit2 flow, this is where we ensure the one-time
159
+ * Permit2 approve has been submitted and confirmed. The hook is awaited by
160
+ * @x402/core's createPaymentPayload, so we can block signing until the
161
+ * approve lands — no double roundtrip, no race.
162
+ *
163
+ * Return `{ abort: true, reason }` to cancel the payment cleanly.
222
164
  */
223
- private validatePaymentAddress;
165
+ private beforePaymentCreationHook;
224
166
  /**
225
- * Execute atomic payment with fee splitting.
167
+ * Registered as `paymentRequirementsSelector` on the x402Client.
168
+ * Called after server's payment-required is parsed, before signing.
169
+ *
170
+ * Picks the best requirement from `accepts[]` based on:
171
+ * 1. scheme === "exact" AND network in our allowlist
172
+ * 2. Wallet tier: Smart Wallet prefers Permit2, EOA prefers EIP-3009
173
+ * 3. Amount within maxAmountPerTx safety cap
174
+ * 4. Clamps maxTimeoutSeconds to maxAuthorizationValidSec (MEV cap)
175
+ */
176
+ private selectRequirements;
177
+ private ensurePermit2Approved;
178
+ /**
179
+ * P1-2: Read `USDC.allowance(smartWallet, PERMIT2_ADDRESS)` via the wallet
180
+ * provider's read provider and return true if already >= a sensible threshold
181
+ * (half of max uint256 — Permit2 approves are typically MAX_UINT256).
226
182
  *
227
- * Priority: relay (atomic, 1 tx) > feeCollector (2 tx) > error
228
- * Relay flow: approve relay relay.payWithFee(provider, gross, serviceId)
229
- * feeCollector flow: transferFn(provider, net) + transferFn(feeCollector, fee)
183
+ * Returns false if the wallet provider doesn't expose a read provider
184
+ * (older wallet implementations) callers then fall back to submitting
185
+ * the approve unconditionally, which is the safe (but slightly wasteful)
186
+ * default.
187
+ *
188
+ * Uses eth_call with the standard ERC-20 allowance ABI selector to avoid
189
+ * pulling in additional contract ABIs.
230
190
  */
231
- private executeAtomicPayment;
191
+ private readPermit2AllowanceIsSet;
232
192
  /**
233
- * Retry request with payment proof (tx hash).
234
- * Uses the same HTTP method, headers, and body as the original request.
235
- *
236
- * @param endpoint - Request URL
237
- * @param txHash - Payment transaction hash as proof
238
- * @param method - Original HTTP method
239
- * @param customHeaders - Original custom headers
240
- * @param body - Original request body
241
- * @param contentType - Original content-type
193
+ * Check if the Smart Wallet is deployed on-chain (has code).
194
+ * Returns true for EOA wallets (they're always "deployed" in a loose sense)
195
+ * and for deployed Smart Wallets. Returns false for counterfactual wallets.
242
196
  */
243
- private retryWithProof;
197
+ private isWalletDeployed;
198
+ private mapToPayResult;
244
199
  /**
245
- * Create result for free services (200 on initial request).
200
+ * Bridge our IWalletProvider.signTypedData to @x402/evm's ClientEvmSigner
201
+ * structural type. Only `address` + `signTypedData` are required for the
202
+ * `exact` scheme flow we use.
203
+ *
204
+ * B3: no outer try/catch here — each IWalletProvider implementation is the
205
+ * error-converting boundary and already throws X402SignatureFailedError on
206
+ * failure. Wrapping here would produce double-nested error messages like
207
+ * "walletProvider.signTypedData failed: EOA signTypedData failed: ...".
246
208
  */
247
- private createFreeServiceResult;
209
+ private walletProviderToClientEvmSigner;
248
210
  }
249
211
  //# sourceMappingURL=X402Adapter.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"X402Adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/X402Adapter.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"X402Adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/X402Adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAgBH,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAA2B,MAAM,YAAY,CAAC;AAClF,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EAChB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAmB,MAAM,2BAA2B,CAAC;AAkB7E;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,cAAc,EAAE,eAAe,CAAC;IAEhC;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAExC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAElC;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAEtC;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAErC;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAqDD,qBAAa,WAAY,YAAW,QAAQ;IA4C9B,OAAO,CAAC,QAAQ,CAAC,MAAM;IA3CnC,SAAgB,QAAQ,EAAE,eAAe,CAQvC;IAEF,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkC;IACvD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAe;IAChD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAS;IAClD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAwB;IAExD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkC;IAElE;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAsB;IAErD,mDAAmD;IACnD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAqB;IAE1D,sFAAsF;IACtF,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAoC;IAE7E,6FAA6F;IAC7F,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwC;IACjE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAU;gBAExB,MAAM,EAAE,iBAAiB;IAgEtD;;;;;;;;;OASG;IACH,SAAS,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO;IAI5C,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAsClC,GAAG,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA0CxD,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA6BnD,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOvC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOtD,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWzE;;;;;;;;;;;OAWG;YACW,yBAAyB;IA2CvC;;;;;;;;;OASG;IACH,OAAO,CAAC,kBAAkB;YAyEZ,qBAAqB;IAyEnC;;;;;;;;;;;;OAYG;YACW,yBAAyB;IAkCvC;;;;OAIG;YACW,gBAAgB;YAqBhB,cAAc;IAsG5B;;;;;;;;;OASG;IACH,OAAO,CAAC,+BAA+B;CAkBxC"}