agentwallet-sdk 2.4.1 → 3.0.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 (85) hide show
  1. package/README.md +264 -19
  2. package/dist/bridge/client.d.ts +17 -49
  3. package/dist/bridge/client.d.ts.map +1 -1
  4. package/dist/bridge/client.js +94 -124
  5. package/dist/bridge/client.js.map +1 -1
  6. package/dist/bridge/index.d.ts +4 -2
  7. package/dist/bridge/index.d.ts.map +1 -1
  8. package/dist/bridge/index.js +8 -2
  9. package/dist/bridge/index.js.map +1 -1
  10. package/dist/bridge/types.d.ts +100 -19
  11. package/dist/bridge/types.d.ts.map +1 -1
  12. package/dist/bridge/types.js +167 -18
  13. package/dist/bridge/types.js.map +1 -1
  14. package/dist/bridge/unified.d.ts +101 -0
  15. package/dist/bridge/unified.d.ts.map +1 -0
  16. package/dist/bridge/unified.js +284 -0
  17. package/dist/bridge/unified.js.map +1 -0
  18. package/dist/chains.d.ts +62 -0
  19. package/dist/chains.d.ts.map +1 -0
  20. package/dist/chains.js +108 -0
  21. package/dist/chains.js.map +1 -0
  22. package/dist/index.d.ts +15 -506
  23. package/dist/index.d.ts.map +1 -1
  24. package/dist/index.js +13 -3
  25. package/dist/index.js.map +1 -1
  26. package/dist/solana/bridge.d.ts +144 -0
  27. package/dist/solana/bridge.d.ts.map +1 -0
  28. package/dist/solana/bridge.js +352 -0
  29. package/dist/solana/bridge.js.map +1 -0
  30. package/dist/solana/index.d.ts +8 -0
  31. package/dist/solana/index.d.ts.map +1 -0
  32. package/dist/solana/index.js +6 -0
  33. package/dist/solana/index.js.map +1 -0
  34. package/dist/solana/swap.d.ts +85 -0
  35. package/dist/solana/swap.d.ts.map +1 -0
  36. package/dist/solana/swap.js +173 -0
  37. package/dist/solana/swap.js.map +1 -0
  38. package/dist/solana/types.d.ts +126 -0
  39. package/dist/solana/types.d.ts.map +1 -0
  40. package/dist/solana/types.js +10 -0
  41. package/dist/solana/types.js.map +1 -0
  42. package/dist/solana/wallet.d.ts +83 -0
  43. package/dist/solana/wallet.d.ts.map +1 -0
  44. package/dist/solana/wallet.js +164 -0
  45. package/dist/solana/wallet.js.map +1 -0
  46. package/dist/solana/x402.d.ts +69 -0
  47. package/dist/solana/x402.d.ts.map +1 -0
  48. package/dist/solana/x402.js +154 -0
  49. package/dist/solana/x402.js.map +1 -0
  50. package/dist/swap/SwapModule.d.ts +4 -1
  51. package/dist/swap/SwapModule.d.ts.map +1 -1
  52. package/dist/swap/SwapModule.js +7 -2
  53. package/dist/swap/SwapModule.js.map +1 -1
  54. package/dist/swap/types.d.ts +4 -2
  55. package/dist/swap/types.d.ts.map +1 -1
  56. package/dist/swap/types.js.map +1 -1
  57. package/dist/types.d.ts +2 -1
  58. package/dist/types.d.ts.map +1 -1
  59. package/dist/types.js +1 -0
  60. package/dist/types.js.map +1 -1
  61. package/dist/x402/index.d.ts +1 -1
  62. package/dist/x402/index.d.ts.map +1 -1
  63. package/dist/x402/index.js +1 -1
  64. package/dist/x402/index.js.map +1 -1
  65. package/dist/x402/types.d.ts +5 -3
  66. package/dist/x402/types.d.ts.map +1 -1
  67. package/dist/x402/types.js +17 -2
  68. package/dist/x402/types.js.map +1 -1
  69. package/package.json +30 -10
  70. package/dist/bridge/__tests__/bridge.test.d.ts +0 -2
  71. package/dist/bridge/__tests__/bridge.test.d.ts.map +0 -1
  72. package/dist/bridge/__tests__/bridge.test.js +0 -508
  73. package/dist/bridge/__tests__/bridge.test.js.map +0 -1
  74. package/dist/swap/__tests__/swap.test.d.ts +0 -2
  75. package/dist/swap/__tests__/swap.test.d.ts.map +0 -1
  76. package/dist/swap/__tests__/swap.test.js +0 -272
  77. package/dist/swap/__tests__/swap.test.js.map +0 -1
  78. package/dist/x402/__tests__/budget.test.d.ts +0 -2
  79. package/dist/x402/__tests__/budget.test.d.ts.map +0 -1
  80. package/dist/x402/__tests__/budget.test.js +0 -114
  81. package/dist/x402/__tests__/budget.test.js.map +0 -1
  82. package/dist/x402/__tests__/client.test.d.ts +0 -2
  83. package/dist/x402/__tests__/client.test.d.ts.map +0 -1
  84. package/dist/x402/__tests__/client.test.js +0 -107
  85. package/dist/x402/__tests__/client.test.js.map +0 -1
package/README.md CHANGED
@@ -4,11 +4,24 @@
4
4
 
5
5
  Agent Wallet gives AI agents autonomous spending power with hard on-chain limits. No more choosing between "agent can drain everything" and "every transaction needs manual approval."
6
6
 
7
- ```
7
+ ```text
8
8
  Agent wants to spend $15 → ✅ Auto-approved (under $25 limit)
9
9
  Agent wants to spend $500 → ⏳ Queued for your approval
10
10
  Agent spent $490 today → 🛑 Next tx queued ($500/day limit hit)
11
- ```
11
+ ```text
12
+
13
+ ## How We Compare
14
+
15
+ | | **agentwallet-sdk** | **Coinbase Agentic Wallet** | **MoonPay Agents** |
16
+ |---|---|---|---|
17
+ | **Custody** | Non-custodial (keys on device) | Semi-custodial (TEE) | Non-custodial (claimed) |
18
+ | **Spend Limits** | On-chain (smart contract) | API-enforced | Not documented |
19
+ | **Chains** | 5 (Base, ETH, Arb, Polygon, Sepolia) | Base only | Unclear |
20
+ | **Agent Identity** | ERC-8004 + ERC-6551 | None | None |
21
+ | **Open Source** | MIT | Partial | Closed |
22
+ | **x402 Payments** | Native | Supported | "Compatible" |
23
+
24
+ > On-chain spend limits can't be bypassed even if the API layer is compromised. That's the difference between policy and math.
12
25
 
13
26
  ## Why Agent Wallet?
14
27
 
@@ -25,7 +38,7 @@ Built on **ERC-6551** (token-bound accounts). Your agent's wallet is tied to an
25
38
 
26
39
  ```bash
27
40
  npm install @agentwallet/sdk viem
28
- ```
41
+ ```text
29
42
 
30
43
  ```typescript
31
44
  import {
@@ -76,11 +89,12 @@ for (const tx of pending) {
76
89
  console.log(`Pending #${tx.txId}: ${tx.amount} to ${tx.to}`);
77
90
  await approveTransaction(wallet, tx.txId);
78
91
  }
79
- ```
92
+ ```text
80
93
 
81
94
  ## API Reference
82
95
 
83
96
  ### `createWallet(config)`
97
+
84
98
  Connect to an existing AgentAccountV2 contract.
85
99
 
86
100
  | Param | Type | Description |
@@ -91,6 +105,7 @@ Connect to an existing AgentAccountV2 contract.
91
105
  | `rpcUrl?` | `string` | Custom RPC URL |
92
106
 
93
107
  ### `setSpendPolicy(wallet, policy)` — Owner only
108
+
94
109
  Set per-token spending limits.
95
110
 
96
111
  | Field | Type | Description |
@@ -101,31 +116,39 @@ Set per-token spending limits.
101
116
  | `periodLength` | `number` | Window in seconds (default: 86400 = 24h) |
102
117
 
103
118
  ### `agentExecute(wallet, { to, value?, data? })`
119
+
104
120
  Execute a native ETH transaction. Auto-approves if within limits, queues if over.
105
121
 
106
122
  **Returns:** `{ executed: boolean, txHash: Hash, pendingTxId?: bigint }`
107
123
 
108
124
  ### `agentTransferToken(wallet, { token, to, amount })`
125
+
109
126
  Transfer ERC20 tokens, respecting spend limits.
110
127
 
111
128
  ### `checkBudget(wallet, token?)`
129
+
112
130
  Check remaining autonomous spending budget.
113
131
 
114
132
  **Returns:** `{ token, perTxLimit, remainingInPeriod }`
115
133
 
116
134
  ### `getPendingApprovals(wallet, fromId?, toId?)`
135
+
117
136
  List all pending (unexecuted, uncancelled) transactions awaiting owner approval.
118
137
 
119
138
  ### `approveTransaction(wallet, txId)` — Owner only
139
+
120
140
  Approve and execute a queued transaction.
121
141
 
122
142
  ### `cancelTransaction(wallet, txId)` — Owner only
143
+
123
144
  Cancel a queued transaction.
124
145
 
125
146
  ### `setOperator(wallet, operator, authorized)` — Owner only
147
+
126
148
  Add or remove an agent operator address.
127
149
 
128
150
  ### `getBudgetForecast(wallet, token?, now?)`
151
+
129
152
  **[MAX-ADDED]** Time-aware budget forecast — know not just what's left, but when it refills.
130
153
 
131
154
  **Returns:** `BudgetForecast` — includes `remainingInPeriod`, `secondsUntilReset`, `utilizationPercent`, full period metadata.
@@ -133,9 +156,10 @@ Add or remove an agent operator address.
133
156
  ```typescript
134
157
  const forecast = await getBudgetForecast(wallet, NATIVE_TOKEN);
135
158
  console.log(`${forecast.utilizationPercent}% used, resets in ${forecast.secondsUntilReset}s`);
136
- ```
159
+ ```text
137
160
 
138
161
  ### `getWalletHealth(wallet, operators?, tokens?, now?)`
162
+
139
163
  **[MAX-ADDED]** Single-call diagnostic snapshot for agent self-monitoring.
140
164
 
141
165
  **Returns:** `WalletHealth` — address, NFT binding, operator epoch, active operator statuses, pending queue depth, budget forecasts.
@@ -144,9 +168,10 @@ console.log(`${forecast.utilizationPercent}% used, resets in ${forecast.secondsU
144
168
  const health = await getWalletHealth(wallet, [agentHotWallet], [NATIVE_TOKEN, usdcAddress]);
145
169
  if (health.pendingQueueDepth > 5) console.warn('Queue backing up!');
146
170
  if (!health.activeOperators[0].active) console.error('Agent operator deactivated!');
147
- ```
171
+ ```text
148
172
 
149
173
  ### `batchAgentTransfer(wallet, transfers)`
174
+
150
175
  **[MAX-ADDED]** Execute multiple token transfers sequentially — reduces boilerplate for multi-recipient payments.
151
176
 
152
177
  ```typescript
@@ -154,9 +179,10 @@ const hashes = await batchAgentTransfer(wallet, [
154
179
  { token: USDC, to: serviceA, amount: 100n },
155
180
  { token: USDC, to: serviceB, amount: 200n },
156
181
  ]);
157
- ```
182
+ ```text
158
183
 
159
184
  ### `getActivityHistory(wallet, { fromBlock?, toBlock? })`
185
+
160
186
  **[MAX-ADDED]** Query on-chain event history for self-auditing — no external indexer needed.
161
187
 
162
188
  **Returns:** `ActivityEntry[]` — sorted by block number, covers executions, queued txs, approvals, cancellations, policy updates, operator changes.
@@ -166,10 +192,12 @@ const history = await getActivityHistory(wallet, { fromBlock: 10000n });
166
192
  for (const entry of history) {
167
193
  console.log(`[${entry.type}] block ${entry.blockNumber}: ${JSON.stringify(entry.args)}`);
168
194
  }
169
- ```
195
+ ```text
170
196
 
171
197
  ## Supported Chains
172
198
 
199
+ ### Wallet / Execution Chains
200
+
173
201
  | Chain | Status | Best For |
174
202
  |-------|--------|----------|
175
203
  | **Base** | ✅ Primary | Low gas, USDC native |
@@ -178,6 +206,108 @@ for (const entry of history) {
178
206
  | **Arbitrum** | ✅ | DeFi agents |
179
207
  | **Polygon** | ✅ | Micropayments |
180
208
 
209
+ ### CCTP V2 Bridge — 17 Chains (v3.1.0)
210
+
211
+ Bridge USDC between any two supported chains via Circle's Cross-Chain Transfer Protocol V2. **0.1% platform fee.** Uses the same non-custodial, agent-native architecture.
212
+
213
+ ```typescript
214
+ import { UnifiedBridge } from 'agentwallet-sdk';
215
+
216
+ const bridge = new UnifiedBridge({ evmSigner, solanaWallet });
217
+
218
+ // Bridge 1 USDC from Solana to Base (~20s fast transfer)
219
+ const result = await bridge.bridge({
220
+ amount: 1_000_000n, // 1 USDC (6 decimals)
221
+ sourceChain: 'solana',
222
+ destinationChain: 'base',
223
+ destinationAddress: '0x...',
224
+ });
225
+ console.log('Minted on Base:', result.mintTxHash);
226
+
227
+ // Bridge from Polygon to Arbitrum
228
+ const result2 = await bridge.bridge({
229
+ amount: 5_000_000n, // 5 USDC
230
+ sourceChain: 'polygon',
231
+ destinationChain: 'arbitrum',
232
+ destinationAddress: '0x...',
233
+ });
234
+
235
+ // Get a fee quote
236
+ const quote = bridge.getQuote({
237
+ amount: 1_000_000n,
238
+ sourceChain: 'base',
239
+ destinationChain: 'sonic',
240
+ });
241
+ console.log(`Fee: ${quote.platformFee} USDC (0.1%)`);
242
+ console.log(`Est. time: ${quote.estimatedTimeSeconds}s`);
243
+ console.log(`Output: ${quote.outputAmount} USDC`);
244
+
245
+ // All 17 chains
246
+ console.log(bridge.getSupportedChains());
247
+ // ['ethereum','avalanche','optimism','arbitrum','base','polygon',
248
+ // 'unichain','linea','codex','sonic','worldchain','sei','xdc',
249
+ // 'hyperevm','ink','plume','solana']
250
+ ```
251
+
252
+ #### Supported Bridge Chains
253
+
254
+ | Chain | CCTP Domain | Chain ID | Fast Transfer |
255
+ |-------|-------------|----------|---------------|
256
+ | Ethereum | 0 | 1 | ✅ ~20s |
257
+ | Avalanche | 1 | 43114 | ⏱ ~15min |
258
+ | OP Mainnet | 2 | 10 | ✅ ~20s |
259
+ | Arbitrum | 3 | 42161 | ✅ ~20s |
260
+ | **Solana** | 5 | — | ✅ ~20s |
261
+ | Base | 6 | 8453 | ✅ ~20s |
262
+ | Polygon PoS | 7 | 137 | ⏱ ~15min |
263
+ | Unichain | 10 | 130 | ✅ ~20s |
264
+ | Linea | 11 | 59144 | ✅ ~20s |
265
+ | Codex | 12 | 812 | ✅ ~20s |
266
+ | Sonic | 13 | 146 | ⏱ ~15min |
267
+ | World Chain | 14 | 480 | ✅ ~20s |
268
+ | Sei | 16 | 1329 | ⏱ ~15min |
269
+ | XDC | 18 | 50 | ⏱ ~15min |
270
+ | HyperEVM | 19 | 999 | ⏱ ~15min |
271
+ | Ink | 21 | 57073 | ✅ ~20s |
272
+ | Plume | 22 | 98866 | ✅ ~20s |
273
+
274
+ Contract addresses verified from Circle's official docs:
275
+ - **TokenMessengerV2**: `0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d` (all EVM chains)
276
+ - **MessageTransmitterV2**: `0x81D40F21F12A8F0E3252Bccb954D722d4c464B64` (all EVM chains)
277
+
278
+ #### EVM-Only Bridge (BridgeModule)
279
+
280
+ For EVM→EVM routes you can use `BridgeModule` directly (no Solana dependency):
281
+
282
+ ```typescript
283
+ import { BridgeModule } from 'agentwallet-sdk';
284
+
285
+ const bridge = new BridgeModule(walletClient, 'base');
286
+ const result = await bridge.bridge(1_000_000n, 'polygon');
287
+ console.log('Minted on Polygon:', result.mintTxHash);
288
+ ```
289
+
290
+ #### Solana-Side Operations (SolanaCCTPBridge)
291
+
292
+ ```typescript
293
+ import { SolanaCCTPBridge } from 'agentwallet-sdk';
294
+ import { Connection, Keypair } from '@solana/web3.js';
295
+
296
+ const solanaBridge = new SolanaCCTPBridge({
297
+ connection: new Connection('https://api.mainnet-beta.solana.com'),
298
+ payer: keypair,
299
+ });
300
+
301
+ // Burn USDC on Solana → receive on Base
302
+ const burnResult = await solanaBridge.depositForBurn({
303
+ amount: 1_000_000n,
304
+ destinationChain: 'base',
305
+ destinationAddress: '0x...',
306
+ });
307
+ const attestation = await solanaBridge.waitForAttestation(burnResult.messageHash);
308
+ // ... then call receiveMessage on Base
309
+ ```
310
+
181
311
  ## x402 Protocol Support
182
312
 
183
313
  Agent Wallet natively supports the [x402 protocol](https://x402.org) — the open standard for HTTP 402 machine payments. Your agent can automatically pay any x402-enabled API (Stripe, Coinbase, etc.) using USDC on Base, while respecting on-chain spend limits.
@@ -207,7 +337,7 @@ const data = await response.json();
207
337
  // - Checked your budget (client-side + on-chain)
208
338
  // - Paid USDC via your AgentWallet contract
209
339
  // - Retried the request with payment proof
210
- ```
340
+ ```text
211
341
 
212
342
  ### Drop-in Fetch Replacement
213
343
 
@@ -218,7 +348,7 @@ const x402Fetch = createX402Fetch(wallet, { globalDailyLimit: 100_000_000n });
218
348
 
219
349
  // Use exactly like fetch()
220
350
  const res = await x402Fetch('https://any-x402-api.com/endpoint');
221
- ```
351
+ ```text
222
352
 
223
353
  ### Budget Controls
224
354
 
@@ -236,7 +366,7 @@ client.budgetTracker.setServiceBudget({
236
366
  maxPerRequest: 2_000_000n,
237
367
  dailyLimit: 20_000_000n,
238
368
  });
239
- ```
369
+ ```text
240
370
 
241
371
  ### Payment Approval Callback
242
372
 
@@ -250,11 +380,11 @@ const client = createX402Client(wallet, {
250
380
  console.log(`Paid ${log.amount} via tx ${log.txHash}`);
251
381
  },
252
382
  });
253
- ```
383
+ ```text
254
384
 
255
385
  ### How x402 Works
256
386
 
257
- ```
387
+ ```text
258
388
  Agent → GET /api/data → Server returns 402 + PAYMENT-REQUIRED header
259
389
 
260
390
  Client parses payment requirements (amount, token, recipient, network)
@@ -266,7 +396,7 @@ AgentWallet executes USDC transfer on Base
266
396
  Client retries request with X-PAYMENT header (payment proof)
267
397
 
268
398
  Server verifies payment → returns 200 + data
269
- ```
399
+ ```text
270
400
 
271
401
  Your agent's keys never leave the non-custodial wallet. All payments respect on-chain spend limits set by the wallet owner.
272
402
 
@@ -275,6 +405,7 @@ Your agent's keys never leave the non-custodial wallet. All payments respect on-
275
405
  Give your AI agent a portable, censorship-resistant identity on Ethereum via [ERC-8004 Trustless Agents](https://eips.ethereum.org/EIPS/eip-8004).
276
406
 
277
407
  ERC-8004 provides three things:
408
+
278
409
  - **Identity Registry** — ERC-721 NFT that resolves to an agent's registration file (name, description, services, capabilities)
279
410
  - **Reputation Registry** — On-chain feedback signals (composable scoring)
280
411
  - **Validation Registry** — Hooks for stakers, zkML verifiers, and TEE oracles
@@ -324,21 +455,21 @@ console.log(agentData.owner); // NFT owner address
324
455
  // Validate a registration file before publishing
325
456
  const errors = validateRegistrationFile(agentData.registrationFile!);
326
457
  if (errors.length === 0) console.log('Valid ERC-8004 registration ✅');
327
- ```
458
+ ```text
328
459
 
329
460
  ### Agent Registry Identifier
330
461
 
331
462
  Each agent is globally identified by a namespaced string:
332
463
 
333
- ```
464
+ ```text
334
465
  eip155:8453:0xRegistryAddress ← namespace:chainId:contractAddress
335
- ```
466
+ ```text
336
467
 
337
468
  ```typescript
338
469
  import { formatAgentRegistry } from '@agentwallet/sdk';
339
470
  const id = formatAgentRegistry(8453, '0xYOUR_REGISTRY');
340
471
  // → "eip155:8453:0xYOUR_REGISTRY"
341
- ```
472
+ ```text
342
473
 
343
474
  ### Fully On-Chain Storage (No IPFS Required)
344
475
 
@@ -351,7 +482,7 @@ const uri = buildDataURI({ name: 'MyAgent', description: '...', type: '...' });
351
482
 
352
483
  // Decode it back
353
484
  const file = parseDataURI(uri);
354
- ```
485
+ ```text
355
486
 
356
487
  ---
357
488
 
@@ -366,6 +497,120 @@ const file = parseDataURI(uri);
366
497
 
367
498
  All limits enforced on-chain. No off-chain dependencies. Fully auditable.
368
499
 
500
+ ## Solana Support (v3.0.0)
501
+
502
+ Solana is now a first-class chain in the SDK. Unlike EVM chains, Solana uses Ed25519 keys, SPL tokens, and Jupiter for swaps — all fully supported.
503
+
504
+ ### Install
505
+
506
+ ```bash
507
+ npm install agentwallet-sdk @solana/web3.js @solana/spl-token
508
+ ```
509
+
510
+ ### SolanaWallet — Non-Custodial Agent Wallet
511
+
512
+ ```typescript
513
+ import { SolanaWallet, SOLANA_USDC_MINT } from 'agentwallet-sdk';
514
+
515
+ // Generate a fresh keypair (ephemeral agent wallet)
516
+ const wallet = SolanaWallet.generate('https://api.mainnet-beta.solana.com');
517
+
518
+ // Or load from existing base58 private key
519
+ const wallet2 = SolanaWallet.fromBase58(process.env.SOLANA_PRIVATE_KEY!, 'https://api.mainnet-beta.solana.com');
520
+
521
+ // Get address (base58 public key)
522
+ console.log(wallet.getAddress());
523
+
524
+ // Check SOL balance (in lamports)
525
+ const lamports = await wallet.getBalance();
526
+ console.log(`${Number(lamports) / 1e9} SOL`);
527
+
528
+ // Check USDC balance (6 decimals)
529
+ const usdc = await wallet.getBalance(SOLANA_USDC_MINT);
530
+ console.log(`${Number(usdc) / 1e6} USDC`);
531
+
532
+ // Transfer SOL
533
+ const sig = await wallet.transfer({
534
+ recipient: 'RecipientPubkey...',
535
+ amount: 500_000_000n, // 0.5 SOL in lamports
536
+ });
537
+
538
+ // Transfer USDC
539
+ const sig2 = await wallet.transfer({
540
+ recipient: 'RecipientPubkey...',
541
+ amount: 5_000_000n, // 5 USDC (6 decimals)
542
+ mint: SOLANA_USDC_MINT,
543
+ });
544
+ ```
545
+
546
+ ### JupiterSwapClient — DEX Aggregator (Solana's Uniswap)
547
+
548
+ ```typescript
549
+ import { SolanaWallet, JupiterSwapClient, SOLANA_USDC_MINT, SOL_NATIVE_MINT } from 'agentwallet-sdk';
550
+
551
+ const wallet = SolanaWallet.fromBase58(process.env.SOLANA_KEY!, 'https://api.mainnet-beta.solana.com');
552
+ const jupiter = new JupiterSwapClient({ wallet });
553
+
554
+ // Get a quote: SOL → USDC
555
+ const quote = await jupiter.getQuote(SOL_NATIVE_MINT, SOLANA_USDC_MINT, 1_000_000_000n);
556
+ console.log(`1 SOL ≈ ${Number(quote.outAmount) / 1e6} USDC`);
557
+
558
+ // Execute swap (0.875% platform fee, 0.5% default slippage)
559
+ const result = await jupiter.swapSolToUsdc(500_000_000n); // 0.5 SOL
560
+ console.log(`Swapped → tx: ${result.txSignature}`);
561
+
562
+ // Reverse: USDC → SOL
563
+ const result2 = await jupiter.swapUsdcToSol(100_000_000n); // 100 USDC
564
+ ```
565
+
566
+ ### SolanaX402Client — x402 Payments on Solana
567
+
568
+ ```typescript
569
+ import { SolanaWallet, SolanaX402Client } from 'agentwallet-sdk';
570
+
571
+ const wallet = SolanaWallet.fromBase58(process.env.SOLANA_KEY!, 'https://api.mainnet-beta.solana.com');
572
+ const x402 = new SolanaX402Client(wallet);
573
+
574
+ // Check if this client can handle a network
575
+ x402.canHandle('solana:mainnet'); // true
576
+ x402.canHandle('base:8453'); // false
577
+
578
+ // Validate payment requirements before paying
579
+ const requirements = {
580
+ scheme: 'exact',
581
+ network: 'solana:mainnet' as const,
582
+ asset: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
583
+ amount: '1000000', // 1 USDC
584
+ payTo: 'RecipientPubkey...',
585
+ maxTimeoutSeconds: 300,
586
+ extra: {},
587
+ };
588
+
589
+ const { valid, reason } = x402.validateRequirements(requirements, { maxAmount: 5_000_000n });
590
+ if (!valid) throw new Error(reason);
591
+
592
+ // Build signed proof (without broadcasting)
593
+ const proof = await x402.buildPaymentProof(requirements);
594
+ // proof.signedTransaction — base64 signed tx for x402 header
595
+
596
+ // Or pay directly (sign + broadcast)
597
+ const paidProof = await x402.pay(requirements);
598
+ console.log(`Paid! tx: ${paidProof.txSignature}`);
599
+ ```
600
+
601
+ ### Solana Chain Config
602
+
603
+ ```typescript
604
+ import { SOLANA_CONFIG, getSolanaConfig } from 'agentwallet-sdk';
605
+
606
+ const mainnet = getSolanaConfig('solana');
607
+ // { cluster: 'mainnet-beta', rpcUrl: '...', usdcMint: 'EPjFWdd5...', x402Network: 'solana:mainnet' }
608
+
609
+ const devnet = getSolanaConfig('solana-devnet');
610
+ ```
611
+
612
+ ---
613
+
369
614
  ## License
370
615
 
371
616
  MIT
@@ -1,14 +1,16 @@
1
1
  import { type Hash, type Hex, type WalletClient } from 'viem';
2
2
  import type { BridgeChain, BridgeOptions, BurnResult, BridgeResult } from './types.js';
3
- import { CCTP_DOMAIN_IDS, BRIDGE_CHAIN_IDS, USDC_CONTRACT, TOKEN_MESSENGER_V2, MESSAGE_TRANSMITTER_V2, FINALITY_THRESHOLD } from './types.js';
3
+ import { CCTP_DOMAIN_IDS, BRIDGE_CHAIN_IDS, BRIDGE_RPC_URLS, USDC_CONTRACT, TOKEN_MESSENGER_V2, MESSAGE_TRANSMITTER_V2, FINALITY_THRESHOLD } from './types.js';
4
4
  /**
5
- * BridgeModule — CCTP V2 cross-chain USDC bridge.
5
+ * BridgeModule — CCTP V2 cross-chain USDC bridge (16 EVM chains).
6
+ *
7
+ * For EVM↔Solana bridges, use UnifiedBridge instead.
6
8
  *
7
9
  * Usage:
8
10
  * ```ts
9
- * const bridge = new BridgeModule(walletClient, 'base', { rpcUrl: '...' });
10
- * const result = await bridge.bridge(1_000_000n, 'optimism');
11
- * console.log('Minted on Optimism:', result.mintTxHash);
11
+ * const bridge = new BridgeModule(walletClient, 'base');
12
+ * const result = await bridge.bridge(1_000_000n, 'polygon');
13
+ * console.log('Minted on Polygon:', result.mintTxHash);
12
14
  * ```
13
15
  */
14
16
  export declare class BridgeModule {
@@ -20,87 +22,53 @@ export declare class BridgeModule {
20
22
  rpcUrl?: string;
21
23
  });
22
24
  /**
23
- * Bridge USDC from the source chain to the destination chain.
25
+ * Bridge USDC from the source chain to any of the 16 supported EVM destination chains.
24
26
  *
25
- * This is the primary method. It orchestrates the full CCTP V2 flow:
26
- * approve burn attest mint.
27
+ * Full CCTP V2 flow: approve burn attest mint.
28
+ * Platform fee: 0.1% of amount (collected on source chain).
27
29
  *
28
30
  * @param amount - Amount in USDC base units (6 decimals). e.g. 1_000_000n = 1 USDC
29
- * @param toChain - Destination chain ('ethereum' | 'optimism' | 'arbitrum')
31
+ * @param toChain - Destination EVM chain
30
32
  * @param options - Optional overrides (finality, fees, destination address)
31
- *
32
- * @throws BridgeError with actionable message if anything fails
33
33
  */
34
34
  bridge(amount: bigint, toChain: BridgeChain, options?: BridgeOptions): Promise<BridgeResult>;
35
35
  /**
36
36
  * Step 1 of 3: Burn USDC on the source chain.
37
- * Returns the burn result including message bytes needed for minting.
38
- * Use this for manual/split-phase bridging.
37
+ * Returns burn result for manual/split-phase bridging.
39
38
  */
40
39
  burn(amount: bigint, toChain: BridgeChain, options?: BridgeOptions): Promise<BurnResult>;
41
40
  /**
42
41
  * Step 2 of 3: Poll Circle IRIS API for attestation.
43
- * Returns the attestation bytes once Circle confirms the message.
44
42
  */
45
43
  waitForAttestation(messageHash: Hex, apiUrl?: string): Promise<Hex>;
46
44
  /**
47
45
  * Step 3 of 3: Mint USDC on the destination chain using the attestation.
48
46
  */
49
47
  mint(messageBytes: Hex, attestation: Hex, toChain: BridgeChain, destinationRpcUrl?: string): Promise<Hash>;
50
- /**
51
- * Fetch the current USDC balance on the source chain for the signer's address.
52
- */
48
+ /** Get USDC balance on the source chain */
53
49
  getUsdcBalance(): Promise<bigint>;
54
- /**
55
- * Fetch the current USDC allowance for the TokenMessengerV2 on source chain.
56
- */
50
+ /** Get USDC allowance for the TokenMessengerV2 on source chain */
57
51
  getUsdcAllowance(): Promise<bigint>;
58
- /**
59
- * Approve TokenMessengerV2 to spend USDC on behalf of the signer.
60
- * Skips if existing allowance is sufficient.
61
- */
52
+ /** Get the source chain name */
53
+ getFromChain(): BridgeChain;
62
54
  private approveUsdc;
63
- /**
64
- * Call TokenMessengerV2.depositForBurn and extract MessageSent data.
65
- */
66
55
  private depositForBurn;
67
56
  /**
68
57
  * Extract the CCTP MessageSent event from a transaction receipt.
69
- * The MessageTransmitter emits this event during depositForBurn.
70
58
  */
71
59
  private extractMessageSent;
72
- /**
73
- * Poll the Circle IRIS API until the attestation is ready.
74
- * Fast finality: ~12 seconds. Full finality: ~15 minutes on Ethereum.
75
- */
76
60
  private pollForAttestation;
77
- /**
78
- * Call MessageTransmitterV2.receiveMessage on the destination chain to mint USDC.
79
- */
80
61
  private receiveMessage;
81
62
  private validateBridgeParams;
82
63
  private sleep;
83
64
  }
84
- /**
85
- * Structured bridge error with actionable messages and error codes.
86
- */
87
65
  export declare class BridgeError extends Error {
88
66
  readonly code: string;
89
67
  constructor(code: string, message: string);
90
68
  }
91
- /**
92
- * Create a BridgeModule from an existing AgentWallet object.
93
- * Convenience wrapper for wallet.bridge() integration.
94
- *
95
- * @example
96
- * ```ts
97
- * const bridge = createBridge(wallet.walletClient, 'base', { rpcUrl: BASE_RPC });
98
- * const result = await bridge.bridge(5_000_000n, 'optimism');
99
- * ```
100
- */
101
69
  export declare function createBridge(walletClient: WalletClient, fromChain?: BridgeChain, options?: {
102
70
  rpcUrl?: string;
103
71
  }): BridgeModule;
104
72
  export type { BridgeChain, BridgeOptions, BurnResult, BridgeResult };
105
- export { CCTP_DOMAIN_IDS, BRIDGE_CHAIN_IDS, USDC_CONTRACT, TOKEN_MESSENGER_V2, MESSAGE_TRANSMITTER_V2, FINALITY_THRESHOLD, };
73
+ export { CCTP_DOMAIN_IDS, BRIDGE_CHAIN_IDS, USDC_CONTRACT, TOKEN_MESSENGER_V2, MESSAGE_TRANSMITTER_V2, BRIDGE_RPC_URLS, FINALITY_THRESHOLD, };
106
74
  //# sourceMappingURL=client.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/bridge/client.ts"],"names":[],"mappings":"AAYA,OAAO,EASL,KAAK,IAAI,EACT,KAAK,GAAG,EAER,KAAK,YAAY,EAElB,MAAM,MAAM,CAAC;AAQd,OAAO,KAAK,EACV,WAAW,EACX,aAAa,EACb,UAAU,EACV,YAAY,EAGb,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAInB,MAAM,YAAY,CAAC;AAUpB;;;;;;;;;GASG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;gBAG9C,YAAY,EAAE,YAAY,EAC1B,SAAS,GAAE,WAAoB,EAC/B,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO;IAsBnC;;;;;;;;;;;OAWG;IACG,MAAM,CACV,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC;IAmDxB;;;;OAIG;IACG,IAAI,CACR,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,UAAU,CAAC;IAYtB;;;OAGG;IACG,kBAAkB,CACtB,WAAW,EAAE,GAAG,EAChB,MAAM,GAAE,MAA+B,GACtC,OAAO,CAAC,GAAG,CAAC;IAIf;;OAEG;IACG,IAAI,CACR,YAAY,EAAE,GAAG,EACjB,WAAW,EAAE,GAAG,EAChB,OAAO,EAAE,WAAW,EACpB,iBAAiB,CAAC,EAAE,MAAM,GACzB,OAAO,CAAC,IAAI,CAAC;IAIhB;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAUvC;;OAEG;IACG,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IAezC;;;OAGG;YACW,WAAW;IA2CzB;;OAEG;YACW,cAAc;IAuE5B;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IA8C1B;;;OAGG;YACW,kBAAkB;IAmEhC;;OAEG;YACW,cAAc;IAsD5B,OAAO,CAAC,oBAAoB;IA6B5B,OAAO,CAAC,KAAK;CAGd;AAID;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;aAElB,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM;CAKlB;AAID;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,YAAY,EAAE,YAAY,EAC1B,SAAS,GAAE,WAAoB,EAC/B,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAChC,YAAY,CAEd;AAGD,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;AACrE,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,GACnB,CAAC"}
1
+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/bridge/client.ts"],"names":[],"mappings":"AAYA,OAAO,EASL,KAAK,IAAI,EACT,KAAK,GAAG,EAER,KAAK,YAAY,EAElB,MAAM,MAAM,CAAC;AAYd,OAAO,KAAK,EACV,WAAW,EACX,aAAa,EACb,UAAU,EACV,YAAY,EAEb,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAKnB,MAAM,YAAY,CAAC;AAqCpB;;;;;;;;;;;GAWG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;gBAG9C,YAAY,EAAE,YAAY,EAC1B,SAAS,GAAE,WAAoB,EAC/B,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO;IA6BnC;;;;;;;;;OASG;IACG,MAAM,CACV,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC;IAmDxB;;;OAGG;IACG,IAAI,CACR,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,UAAU,CAAC;IAYtB;;OAEG;IACG,kBAAkB,CACtB,WAAW,EAAE,GAAG,EAChB,MAAM,GAAE,MAA+B,GACtC,OAAO,CAAC,GAAG,CAAC;IAIf;;OAEG;IACG,IAAI,CACR,YAAY,EAAE,GAAG,EACjB,WAAW,EAAE,GAAG,EAChB,OAAO,EAAE,WAAW,EACpB,iBAAiB,CAAC,EAAE,MAAM,GACzB,OAAO,CAAC,IAAI,CAAC;IAIhB,2CAA2C;IACrC,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAUvC,kEAAkE;IAC5D,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IAazC,gCAAgC;IAChC,YAAY,IAAI,WAAW;YAMb,WAAW;YAsCX,cAAc;IAkE5B;;OAEG;IACH,OAAO,CAAC,kBAAkB;YAsCZ,kBAAkB;YA0DlB,cAAc;IAmD5B,OAAO,CAAC,oBAAoB;IA2B5B,OAAO,CAAC,KAAK;CAGd;AAID,qBAAa,WAAY,SAAQ,KAAK;aAElB,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM;CAKlB;AAID,wBAAgB,YAAY,CAC1B,YAAY,EAAE,YAAY,EAC1B,SAAS,GAAE,WAAoB,EAC/B,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAChC,YAAY,CAEd;AAGD,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;AACrE,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,sBAAsB,EACtB,eAAe,EACf,kBAAkB,GACnB,CAAC"}