agentwallet-sdk 2.5.0 → 3.0.0

package/README.md

@@ -196,6 +196,8 @@ for (const entry of history) {
 
 ## Supported Chains
 
+### Wallet / Execution Chains
+
 | Chain | Status | Best For |
 |-------|--------|----------|
 | **Base** | ✅ Primary | Low gas, USDC native |
@@ -204,6 +206,108 @@ for (const entry of history) {
 | **Arbitrum** | ✅ | DeFi agents |
 | **Polygon** | ✅ | Micropayments |
 
+### CCTP V2 Bridge — 17 Chains (v3.1.0)
+
+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.
+
+```typescript
+import { UnifiedBridge } from 'agentwallet-sdk';
+
+const bridge = new UnifiedBridge({ evmSigner, solanaWallet });
+
+// Bridge 1 USDC from Solana to Base (~20s fast transfer)
+const result = await bridge.bridge({
+  amount: 1_000_000n,       // 1 USDC (6 decimals)
+  sourceChain: 'solana',
+  destinationChain: 'base',
+  destinationAddress: '0x...',
+});
+console.log('Minted on Base:', result.mintTxHash);
+
+// Bridge from Polygon to Arbitrum
+const result2 = await bridge.bridge({
+  amount: 5_000_000n,       // 5 USDC
+  sourceChain: 'polygon',
+  destinationChain: 'arbitrum',
+  destinationAddress: '0x...',
+});
+
+// Get a fee quote
+const quote = bridge.getQuote({
+  amount: 1_000_000n,
+  sourceChain: 'base',
+  destinationChain: 'sonic',
+});
+console.log(`Fee: ${quote.platformFee} USDC (0.1%)`);
+console.log(`Est. time: ${quote.estimatedTimeSeconds}s`);
+console.log(`Output: ${quote.outputAmount} USDC`);
+
+// All 17 chains
+console.log(bridge.getSupportedChains());
+// ['ethereum','avalanche','optimism','arbitrum','base','polygon',
+//  'unichain','linea','codex','sonic','worldchain','sei','xdc',
+//  'hyperevm','ink','plume','solana']
+```
+
+#### Supported Bridge Chains
+
+| Chain | CCTP Domain | Chain ID | Fast Transfer |
+|-------|-------------|----------|---------------|
+| Ethereum | 0 | 1 | ✅ ~20s |
+| Avalanche | 1 | 43114 | ⏱ ~15min |
+| OP Mainnet | 2 | 10 | ✅ ~20s |
+| Arbitrum | 3 | 42161 | ✅ ~20s |
+| **Solana** | 5 | — | ✅ ~20s |
+| Base | 6 | 8453 | ✅ ~20s |
+| Polygon PoS | 7 | 137 | ⏱ ~15min |
+| Unichain | 10 | 130 | ✅ ~20s |
+| Linea | 11 | 59144 | ✅ ~20s |
+| Codex | 12 | 812 | ✅ ~20s |
+| Sonic | 13 | 146 | ⏱ ~15min |
+| World Chain | 14 | 480 | ✅ ~20s |
+| Sei | 16 | 1329 | ⏱ ~15min |
+| XDC | 18 | 50 | ⏱ ~15min |
+| HyperEVM | 19 | 999 | ⏱ ~15min |
+| Ink | 21 | 57073 | ✅ ~20s |
+| Plume | 22 | 98866 | ✅ ~20s |
+
+Contract addresses verified from Circle's official docs:
+- **TokenMessengerV2**: `0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d` (all EVM chains)
+- **MessageTransmitterV2**: `0x81D40F21F12A8F0E3252Bccb954D722d4c464B64` (all EVM chains)
+
+#### EVM-Only Bridge (BridgeModule)
+
+For EVM→EVM routes you can use `BridgeModule` directly (no Solana dependency):
+
+```typescript
+import { BridgeModule } from 'agentwallet-sdk';
+
+const bridge = new BridgeModule(walletClient, 'base');
+const result = await bridge.bridge(1_000_000n, 'polygon');
+console.log('Minted on Polygon:', result.mintTxHash);
+```
+
+#### Solana-Side Operations (SolanaCCTPBridge)
+
+```typescript
+import { SolanaCCTPBridge } from 'agentwallet-sdk';
+import { Connection, Keypair } from '@solana/web3.js';
+
+const solanaBridge = new SolanaCCTPBridge({
+  connection: new Connection('https://api.mainnet-beta.solana.com'),
+  payer: keypair,
+});
+
+// Burn USDC on Solana → receive on Base
+const burnResult = await solanaBridge.depositForBurn({
+  amount: 1_000_000n,
+  destinationChain: 'base',
+  destinationAddress: '0x...',
+});
+const attestation = await solanaBridge.waitForAttestation(burnResult.messageHash);
+// ... then call receiveMessage on Base
+```
+
 ## x402 Protocol Support
 
 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.
@@ -393,6 +497,120 @@ const file = parseDataURI(uri);
 
 All limits enforced on-chain. No off-chain dependencies. Fully auditable.
 
+## Solana Support (v3.0.0)
+
+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.
+
+### Install
+
+```bash
+npm install agentwallet-sdk @solana/web3.js @solana/spl-token
+```
+
+### SolanaWallet — Non-Custodial Agent Wallet
+
+```typescript
+import { SolanaWallet, SOLANA_USDC_MINT } from 'agentwallet-sdk';
+
+// Generate a fresh keypair (ephemeral agent wallet)
+const wallet = SolanaWallet.generate('https://api.mainnet-beta.solana.com');
+
+// Or load from existing base58 private key
+const wallet2 = SolanaWallet.fromBase58(process.env.SOLANA_PRIVATE_KEY!, 'https://api.mainnet-beta.solana.com');
+
+// Get address (base58 public key)
+console.log(wallet.getAddress());
+
+// Check SOL balance (in lamports)
+const lamports = await wallet.getBalance();
+console.log(`${Number(lamports) / 1e9} SOL`);
+
+// Check USDC balance (6 decimals)
+const usdc = await wallet.getBalance(SOLANA_USDC_MINT);
+console.log(`${Number(usdc) / 1e6} USDC`);
+
+// Transfer SOL
+const sig = await wallet.transfer({
+  recipient: 'RecipientPubkey...',
+  amount: 500_000_000n, // 0.5 SOL in lamports
+});
+
+// Transfer USDC
+const sig2 = await wallet.transfer({
+  recipient: 'RecipientPubkey...',
+  amount: 5_000_000n,  // 5 USDC (6 decimals)
+  mint: SOLANA_USDC_MINT,
+});
+```
+
+### JupiterSwapClient — DEX Aggregator (Solana's Uniswap)
+
+```typescript
+import { SolanaWallet, JupiterSwapClient, SOLANA_USDC_MINT, SOL_NATIVE_MINT } from 'agentwallet-sdk';
+
+const wallet = SolanaWallet.fromBase58(process.env.SOLANA_KEY!, 'https://api.mainnet-beta.solana.com');
+const jupiter = new JupiterSwapClient({ wallet });
+
+// Get a quote: SOL → USDC
+const quote = await jupiter.getQuote(SOL_NATIVE_MINT, SOLANA_USDC_MINT, 1_000_000_000n);
+console.log(`1 SOL ≈ ${Number(quote.outAmount) / 1e6} USDC`);
+
+// Execute swap (0.875% platform fee, 0.5% default slippage)
+const result = await jupiter.swapSolToUsdc(500_000_000n); // 0.5 SOL
+console.log(`Swapped → tx: ${result.txSignature}`);
+
+// Reverse: USDC → SOL
+const result2 = await jupiter.swapUsdcToSol(100_000_000n); // 100 USDC
+```
+
+### SolanaX402Client — x402 Payments on Solana
+
+```typescript
+import { SolanaWallet, SolanaX402Client } from 'agentwallet-sdk';
+
+const wallet = SolanaWallet.fromBase58(process.env.SOLANA_KEY!, 'https://api.mainnet-beta.solana.com');
+const x402 = new SolanaX402Client(wallet);
+
+// Check if this client can handle a network
+x402.canHandle('solana:mainnet'); // true
+x402.canHandle('base:8453');      // false
+
+// Validate payment requirements before paying
+const requirements = {
+  scheme: 'exact',
+  network: 'solana:mainnet' as const,
+  asset: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
+  amount: '1000000', // 1 USDC
+  payTo: 'RecipientPubkey...',
+  maxTimeoutSeconds: 300,
+  extra: {},
+};
+
+const { valid, reason } = x402.validateRequirements(requirements, { maxAmount: 5_000_000n });
+if (!valid) throw new Error(reason);
+
+// Build signed proof (without broadcasting)
+const proof = await x402.buildPaymentProof(requirements);
+// proof.signedTransaction — base64 signed tx for x402 header
+
+// Or pay directly (sign + broadcast)
+const paidProof = await x402.pay(requirements);
+console.log(`Paid! tx: ${paidProof.txSignature}`);
+```
+
+### Solana Chain Config
+
+```typescript
+import { SOLANA_CONFIG, getSolanaConfig } from 'agentwallet-sdk';
+
+const mainnet = getSolanaConfig('solana');
+// { cluster: 'mainnet-beta', rpcUrl: '...', usdcMint: 'EPjFWdd5...', x402Network: 'solana:mainnet' }
+
+const devnet = getSolanaConfig('solana-devnet');
+```
+
+---
+
 ## License
 
 MIT

package/dist/bridge/client.d.ts

@@ -1,14 +1,16 @@
 import { type Hash, type Hex, type WalletClient } from 'viem';
 import type { BridgeChain, BridgeOptions, BurnResult, BridgeResult } from './types.js';
-import { CCTP_DOMAIN_IDS, BRIDGE_CHAIN_IDS, USDC_CONTRACT, TOKEN_MESSENGER_V2, MESSAGE_TRANSMITTER_V2, FINALITY_THRESHOLD } from './types.js';
+import { CCTP_DOMAIN_IDS, BRIDGE_CHAIN_IDS, BRIDGE_RPC_URLS, USDC_CONTRACT, TOKEN_MESSENGER_V2, MESSAGE_TRANSMITTER_V2, FINALITY_THRESHOLD } from './types.js';
 /**
- * BridgeModule — CCTP V2 cross-chain USDC bridge.
+ * BridgeModule — CCTP V2 cross-chain USDC bridge (16 EVM chains).
+ *
+ * For EVM↔Solana bridges, use UnifiedBridge instead.
  *
  * Usage:
  * ```ts
- * const bridge = new BridgeModule(walletClient, 'base', { rpcUrl: '...' });
- * const result = await bridge.bridge(1_000_000n, 'optimism');
- * console.log('Minted on Optimism:', result.mintTxHash);
+ * const bridge = new BridgeModule(walletClient, 'base');
+ * const result = await bridge.bridge(1_000_000n, 'polygon');
+ * console.log('Minted on Polygon:', result.mintTxHash);
  * ```
  */
 export declare class BridgeModule {
@@ -20,87 +22,53 @@ export declare class BridgeModule {
         rpcUrl?: string;
     });
     /**
-     * Bridge USDC from the source chain to the destination chain.
+     * Bridge USDC from the source chain to any of the 16 supported EVM destination chains.
      *
-     * This is the primary method. It orchestrates the full CCTP V2 flow:
-     * approve → burn → attest → mint.
+     * Full CCTP V2 flow: approve → burn → attest → mint.
+     * Platform fee: 0.1% of amount (collected on source chain).
      *
      * @param amount - Amount in USDC base units (6 decimals). e.g. 1_000_000n = 1 USDC
-     * @param toChain - Destination chain ('ethereum' | 'optimism' | 'arbitrum')
+     * @param toChain - Destination EVM chain
      * @param options - Optional overrides (finality, fees, destination address)
-     *
-     * @throws BridgeError with actionable message if anything fails
      */
     bridge(amount: bigint, toChain: BridgeChain, options?: BridgeOptions): Promise<BridgeResult>;
     /**
      * Step 1 of 3: Burn USDC on the source chain.
-     * Returns the burn result including message bytes needed for minting.
-     * Use this for manual/split-phase bridging.
+     * Returns burn result for manual/split-phase bridging.
      */
     burn(amount: bigint, toChain: BridgeChain, options?: BridgeOptions): Promise<BurnResult>;
     /**
      * Step 2 of 3: Poll Circle IRIS API for attestation.
-     * Returns the attestation bytes once Circle confirms the message.
      */
     waitForAttestation(messageHash: Hex, apiUrl?: string): Promise<Hex>;
     /**
      * Step 3 of 3: Mint USDC on the destination chain using the attestation.
      */
     mint(messageBytes: Hex, attestation: Hex, toChain: BridgeChain, destinationRpcUrl?: string): Promise<Hash>;
-    /**
-     * Fetch the current USDC balance on the source chain for the signer's address.
-     */
+    /** Get USDC balance on the source chain */
     getUsdcBalance(): Promise<bigint>;
-    /**
-     * Fetch the current USDC allowance for the TokenMessengerV2 on source chain.
-     */
+    /** Get USDC allowance for the TokenMessengerV2 on source chain */
     getUsdcAllowance(): Promise<bigint>;
-    /**
-     * Approve TokenMessengerV2 to spend USDC on behalf of the signer.
-     * Skips if existing allowance is sufficient.
-     */
+    /** Get the source chain name */
+    getFromChain(): BridgeChain;
     private approveUsdc;
-    /**
-     * Call TokenMessengerV2.depositForBurn and extract MessageSent data.
-     */
     private depositForBurn;
     /**
      * Extract the CCTP MessageSent event from a transaction receipt.
-     * The MessageTransmitter emits this event during depositForBurn.
      */
     private extractMessageSent;
-    /**
-     * Poll the Circle IRIS API until the attestation is ready.
-     * Fast finality: ~12 seconds. Full finality: ~15 minutes on Ethereum.
-     */
     private pollForAttestation;
-    /**
-     * Call MessageTransmitterV2.receiveMessage on the destination chain to mint USDC.
-     */
     private receiveMessage;
     private validateBridgeParams;
     private sleep;
 }
-/**
- * Structured bridge error with actionable messages and error codes.
- */
 export declare class BridgeError extends Error {
     readonly code: string;
     constructor(code: string, message: string);
 }
-/**
- * Create a BridgeModule from an existing AgentWallet object.
- * Convenience wrapper for wallet.bridge() integration.
- *
- * @example
- * ```ts
- * const bridge = createBridge(wallet.walletClient, 'base', { rpcUrl: BASE_RPC });
- * const result = await bridge.bridge(5_000_000n, 'optimism');
- * ```
- */
 export declare function createBridge(walletClient: WalletClient, fromChain?: BridgeChain, options?: {
     rpcUrl?: string;
 }): BridgeModule;
 export type { BridgeChain, BridgeOptions, BurnResult, BridgeResult };
-export { CCTP_DOMAIN_IDS, BRIDGE_CHAIN_IDS, USDC_CONTRACT, TOKEN_MESSENGER_V2, MESSAGE_TRANSMITTER_V2, FINALITY_THRESHOLD, };
+export { CCTP_DOMAIN_IDS, BRIDGE_CHAIN_IDS, USDC_CONTRACT, TOKEN_MESSENGER_V2, MESSAGE_TRANSMITTER_V2, BRIDGE_RPC_URLS, FINALITY_THRESHOLD, };
 //# sourceMappingURL=client.d.ts.map

package/dist/bridge/client.d.ts.map

@@ -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"}
+{"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"}