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.
- package/README.md +264 -19
- package/dist/bridge/client.d.ts +17 -49
- package/dist/bridge/client.d.ts.map +1 -1
- package/dist/bridge/client.js +94 -124
- package/dist/bridge/client.js.map +1 -1
- package/dist/bridge/index.d.ts +4 -2
- package/dist/bridge/index.d.ts.map +1 -1
- package/dist/bridge/index.js +8 -2
- package/dist/bridge/index.js.map +1 -1
- package/dist/bridge/types.d.ts +100 -19
- package/dist/bridge/types.d.ts.map +1 -1
- package/dist/bridge/types.js +167 -18
- package/dist/bridge/types.js.map +1 -1
- package/dist/bridge/unified.d.ts +101 -0
- package/dist/bridge/unified.d.ts.map +1 -0
- package/dist/bridge/unified.js +284 -0
- package/dist/bridge/unified.js.map +1 -0
- package/dist/chains.d.ts +62 -0
- package/dist/chains.d.ts.map +1 -0
- package/dist/chains.js +108 -0
- package/dist/chains.js.map +1 -0
- package/dist/index.d.ts +15 -506
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +13 -3
- package/dist/index.js.map +1 -1
- package/dist/solana/bridge.d.ts +144 -0
- package/dist/solana/bridge.d.ts.map +1 -0
- package/dist/solana/bridge.js +352 -0
- package/dist/solana/bridge.js.map +1 -0
- package/dist/solana/index.d.ts +8 -0
- package/dist/solana/index.d.ts.map +1 -0
- package/dist/solana/index.js +6 -0
- package/dist/solana/index.js.map +1 -0
- package/dist/solana/swap.d.ts +85 -0
- package/dist/solana/swap.d.ts.map +1 -0
- package/dist/solana/swap.js +173 -0
- package/dist/solana/swap.js.map +1 -0
- package/dist/solana/types.d.ts +126 -0
- package/dist/solana/types.d.ts.map +1 -0
- package/dist/solana/types.js +10 -0
- package/dist/solana/types.js.map +1 -0
- package/dist/solana/wallet.d.ts +83 -0
- package/dist/solana/wallet.d.ts.map +1 -0
- package/dist/solana/wallet.js +164 -0
- package/dist/solana/wallet.js.map +1 -0
- package/dist/solana/x402.d.ts +69 -0
- package/dist/solana/x402.d.ts.map +1 -0
- package/dist/solana/x402.js +154 -0
- package/dist/solana/x402.js.map +1 -0
- package/dist/swap/SwapModule.d.ts +4 -1
- package/dist/swap/SwapModule.d.ts.map +1 -1
- package/dist/swap/SwapModule.js +7 -2
- package/dist/swap/SwapModule.js.map +1 -1
- package/dist/swap/types.d.ts +4 -2
- package/dist/swap/types.d.ts.map +1 -1
- package/dist/swap/types.js.map +1 -1
- package/dist/types.d.ts +2 -1
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +1 -0
- package/dist/types.js.map +1 -1
- package/dist/x402/index.d.ts +1 -1
- package/dist/x402/index.d.ts.map +1 -1
- package/dist/x402/index.js +1 -1
- package/dist/x402/index.js.map +1 -1
- package/dist/x402/types.d.ts +5 -3
- package/dist/x402/types.d.ts.map +1 -1
- package/dist/x402/types.js +17 -2
- package/dist/x402/types.js.map +1 -1
- package/package.json +30 -10
- package/dist/bridge/__tests__/bridge.test.d.ts +0 -2
- package/dist/bridge/__tests__/bridge.test.d.ts.map +0 -1
- package/dist/bridge/__tests__/bridge.test.js +0 -508
- package/dist/bridge/__tests__/bridge.test.js.map +0 -1
- package/dist/swap/__tests__/swap.test.d.ts +0 -2
- package/dist/swap/__tests__/swap.test.d.ts.map +0 -1
- package/dist/swap/__tests__/swap.test.js +0 -272
- package/dist/swap/__tests__/swap.test.js.map +0 -1
- package/dist/x402/__tests__/budget.test.d.ts +0 -2
- package/dist/x402/__tests__/budget.test.d.ts.map +0 -1
- package/dist/x402/__tests__/budget.test.js +0 -114
- package/dist/x402/__tests__/budget.test.js.map +0 -1
- package/dist/x402/__tests__/client.test.d.ts +0 -2
- package/dist/x402/__tests__/client.test.d.ts.map +0 -1
- package/dist/x402/__tests__/client.test.js +0 -107
- 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
|
package/dist/bridge/client.d.ts
CHANGED
|
@@ -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'
|
|
10
|
-
* const result = await bridge.bridge(1_000_000n, '
|
|
11
|
-
* console.log('Minted on
|
|
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
|
|
25
|
+
* Bridge USDC from the source chain to any of the 16 supported EVM destination chains.
|
|
24
26
|
*
|
|
25
|
-
*
|
|
26
|
-
*
|
|
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
|
|
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
|
|
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
|
-
|
|
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;
|
|
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"}
|