@relai-fi/x402 0.5.26 → 0.5.28

package/README.md

@@ -544,6 +544,118 @@ const mgmt = createManagementClient({ serviceKey });
 
 ---
 
+## x402 Bridge
+
+Bridge USDC between **Solana** and **SKALE Base** using the x402 protocol. The bridge uses a liquidity network model — instant payouts, no canonical bridge delays.
+
+> Requires a service key (`sk_live_...`). Get one via `bootstrapAgentKeySolana` or the RelAI dashboard.
+
+### How it works
+
+```
+Agent pays USDC on Solana (x402)
+  ↓ facilitator verifies payment
+Bridge pays out USDC on SKALE Base from its liquidity pool  ← instant
+  ↓ async in background
+Rebalance via Circle CCTP restores liquidity
+```
+
+### Quick start
+
+```typescript
+import { createManagementClient } from '@relai-fi/x402/management';
+import { createX402Client } from '@relai-fi/x402/client';
+import { Keypair } from '@solana/web3.js';
+
+const serviceKey = process.env.RELAI_SERVICE_KEY!;
+const mgmt = createManagementClient({ serviceKey });
+
+// 1. Check liquidity before bridging
+const balances = await mgmt.getBridgeBalances();
+console.log(`SKALE Base liquidity: $${balances.skaleBase.usd} USDC`);
+
+// 2. Get a quote
+const quote = await mgmt.getBridgeQuote(10.0, 'solana');
+// { inputUsd: 10, outputUsd: 9.99, feeBps: 10, direction: 'solana-to-skale' }
+
+// 3. Bridge Solana → SKALE Base
+const keypair = Keypair.fromSecretKey(Buffer.from(process.env.SOLANA_PRIVATE_KEY!, 'base64'));
+const solanaWallet = {
+  publicKey: keypair.publicKey,
+  signTransaction: async (tx: any) => { tx.sign([keypair]); return tx; },
+};
+
+const x402 = createX402Client({
+  wallets: { solana: solanaWallet },
+  solanaRpcUrl: process.env.SOLANA_RPC_URL,
+  defaultHeaders: { 'X-Service-Key': serviceKey },
+});
+
+const result = await mgmt.bridgeSolanaToSkale(
+  10.0,                    // $10 USDC
+  '0xYourSkaleAddress',    // destination EVM address on SKALE Base
+  x402,
+);
+// { success: true, txHash: '0x...', amountOutUsd: 9.99, explorerUrl: '...' }
+```
+
+### Bridge SKALE Base → Solana
+
+```typescript
+import { ethers } from 'ethers';
+
+const provider = new ethers.JsonRpcProvider(process.env.SKALE_RPC_URL);
+const signer = new ethers.Wallet(process.env.EVM_PRIVATE_KEY!, provider);
+
+const evmWallet = {
+  address: signer.address,
+  signTypedData: (params: any) => signer.signTypedData(
+    params.domain, params.types, params.message
+  ),
+};
+
+const x402 = createX402Client({
+  wallets: { evm: evmWallet },
+  defaultHeaders: { 'X-Service-Key': serviceKey },
+});
+
+const result = await mgmt.bridgeSkaleToSolana(
+  5.0,                        // $5 USDC
+  'YourSolanaPublicKey',      // destination Solana address (base58)
+  x402,
+);
+// { success: true, txHash: '...', amountOutUsd: 4.995, explorerUrl: '...' }
+```
+
+### Bridge API reference
+
+| Method | Description |
+|--------|-------------|
+| `getBridgeQuote(amount, from?)` | Fee and net output for a given amount |
+| `getBridgeBalances()` | Current USDC liquidity on Solana / SKALE Base / Base |
+| `bridgeSolanaToSkale(amount, dest, x402Client)` | Bridge Solana → SKALE Base |
+| `bridgeSkaleToSolana(amount, dest, x402Client)` | Bridge SKALE Base → Solana |
+
+### Error handling
+
+```typescript
+try {
+  const result = await mgmt.bridgeSolanaToSkale(100.0, '0x...', x402);
+} catch (err) {
+  if (err.message.includes('insufficient_liquidity')) {
+    // Bridge temporarily unavailable — check balances and retry later
+    const { skaleBase } = await mgmt.getBridgeBalances();
+    console.log(`Available: $${skaleBase.usd} USDC`);
+  }
+}
+```
+
+**Fee:** 0.1% (10 bps) deducted from output amount. Check `getBridgeQuote` for exact amounts.
+
+**Limits:** min $0.000001, max $10,000 per transaction.
+
+---
+
 ## Utilities
 
 ```typescript

package/dist/client.cjs

@@ -31,6 +31,7 @@ var import_spl_token = require("@solana/spl-token");
 var RELAI_FACILITATOR_URL = "https://facilitator.x402.fi";
 var NETWORK_CAIP2 = {
   "solana": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+  "solana-devnet": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
   "base": "eip155:8453",
   "avalanche": "eip155:43114",
   "skale-base": "eip155:1187947933",
@@ -62,6 +63,14 @@ var NETWORK_TOKENS = {
       decimals: 6
     }
   ],
+  "solana-devnet": [
+    {
+      address: "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
+      symbol: "USDC",
+      name: "USD Coin (Devnet)",
+      decimals: 6
+    }
+  ],
   "base": [
     { address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", symbol: "USDC", name: "USD Coin", decimals: 6, domainVersion: "2", isStableUsd: true }
   ],
@@ -186,6 +195,7 @@ var NETWORK_TOKENS = {
 };
 var USDC_ADDRESSES = {
   "solana": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+  "solana-devnet": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
   "base": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
   "avalanche": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
   "skale-base": "0x85889c8c714505E0c94b30fcfcF64fE3Ac8FCb20",
@@ -201,6 +211,7 @@ var USDC_SOLANA = USDC_ADDRESSES["solana"];
 var USDC_BASE = USDC_ADDRESSES["base"];
 var RELAI_NETWORKS = [
   "solana",
+  "solana-devnet",
   "base",
   "avalanche",
   "skale-base",
@@ -211,7 +222,7 @@ var RELAI_NETWORKS = [
   "telos"
 ];
 function isSolana(network) {
-  return network === "solana" || network.startsWith("solana:");
+  return network === "solana" || network === "solana-devnet" || network.startsWith("solana:");
 }
 function isEvm(network) {
   return ["base", "avalanche", "skale-base", "skale-base-sepolia", "skale-bite", "polygon", "ethereum", "telos"].includes(network) || network.startsWith("eip155:");
@@ -986,11 +997,19 @@ function createX402Client(config) {
       [],
       programId
     );
+    const createDestAtaIx = (0, import_spl_token.createAssociatedTokenAccountIdempotentInstruction)(
+      feePayerPubkey,
+      // payer (feePayer covers this)
+      destinationAta,
+      merchantPubkey,
+      mintPubkey,
+      programId
+    );
     const { blockhash } = await connection.getLatestBlockhash("confirmed");
     const message = new import_web3.TransactionMessage({
       payerKey: feePayerPubkey,
       recentBlockhash: blockhash,
-      instructions: [transferIx]
+      instructions: [createDestAtaIx, transferIx]
     }).compileToV0Message();
     const transaction = new import_web3.VersionedTransaction(message);
     const signedTx = await solWallet.signTransaction(transaction);