@lendasat/lendaswap-sdk 0.1.65 → 0.1.68

package/README.md

@@ -5,7 +5,10 @@ TypeScript/JavaScript SDK for Lendaswap - Bitcoin-to-stablecoin atomic swaps.
 ## Overview
 
 This SDK provides a high-level interface for interacting with the Lendaswap API, enabling atomic swaps between Bitcoin (
-Lightning/Arkade) and EVM stablecoins (USDC, USDT on Polygon/Ethereum).
+Lightning/Arkade/On-chain) and EVM stablecoins (USDC, USDT on Polygon/Ethereum). Built with WebAssembly for browser
+environments and IndexedDB for persistent storage.
+
+**For Node.js server-side applications**, use `@lendasat/lendaswap-sdk-native` instead.
 
 ## Installation
 
@@ -29,7 +32,7 @@ pnpm add -D vite-plugin-wasm vite-plugin-top-level-await
 // vite.config.ts
 import wasm from 'vite-plugin-wasm';
 import topLevelAwait from 'vite-plugin-top-level-await';
-import { defineConfig } from 'vite';
+import {defineConfig} from 'vite';
 
 export default defineConfig({
   plugins: [wasm(), topLevelAwait()],
@@ -45,17 +48,17 @@ pnpm add -D wasm-loader
 ```javascript
 // webpack.config.js
 module.exports = {
-  experiments: {
-    asyncWebAssembly: true,
-  },
-  module: {
-    rules: [
-      {
-        test: /\.wasm$/,
-        type: 'webassembly/async',
-      },
-    ],
-  },
+    experiments: {
+        asyncWebAssembly: true,
+    },
+    module: {
+        rules: [
+            {
+                test: /\.wasm$/,
+                type: 'webassembly/async',
+            },
+        ],
+    },
 };
 ```
 
@@ -64,42 +67,50 @@ module.exports = {
 ```javascript
 // next.config.js
 module.exports = {
-  webpack: (config) => {
-    config.experiments = {
-      ...config.experiments,
-      asyncWebAssembly: true,
-    };
-    return config;
-  },
+    webpack: (config) => {
+        config.experiments = {
+            ...config.experiments,
+            asyncWebAssembly: true,
+        };
+        return config;
+    },
 };
 ```
 
 ## Quick Start
 
-### Get Asset Pairs and Quote
+### Create a Client
 
 ```typescript
-import {
-  Client,
-  createDexieWalletStorage,
-  createDexieSwapStorage,
-} from '@lendasat/lendaswap-sdk';
+import { Client } from '@lendasat/lendaswap-sdk';
 
-// Create storage providers (uses IndexedDB via Dexie)
-const walletStorage = createDexieWalletStorage();
-const swapStorage = createDexieSwapStorage();
-
-// Create client
-const client = await Client.create(
-  'https://apilendaswap.lendasat.com',
-  walletStorage,
-  swapStorage,
-  'bitcoin',
-  'https://arkade.computer'
-);
+// Create client using the builder pattern
+const client = await Client.builder()
+  .url('https://apilendaswap.lendasat.com')
+  .withIdbStorage()  // Uses IndexedDB for browser storage
+  .network('bitcoin')
+  .arkadeUrl('https://arkade.computer')
+  .esploraUrl('https://mempool.space/api')
+  .build();
 
 // Initialize wallet (generates or loads mnemonic)
 await client.init();
+```
+
+### Get Asset Pairs and Quote
+
+```typescript
+import { Client } from '@lendasat/lendaswap-sdk';
+
+const client = await Client.builder()
+  .url('https://apilendaswap.lendasat.com')
+  .withIdbStorage()
+  .network('bitcoin')
+  .arkadeUrl('https://arkade.computer')
+  .esploraUrl('https://mempool.space/api')
+  .build();
+
+await client.init();
 
 // Get available trading pairs
 const pairs = await client.getAssetPairs();
@@ -112,28 +123,57 @@ console.log('You receive:', quote.min_amount, 'USDC');
 console.log('Protocol fee:', quote.protocol_fee);
 ```
 
+### Lightning to USDC (Polygon) Swap
+
+This example shows how to swap BTC via Lightning to USDC on Polygon.
+
+```typescript
+import { Client } from '@lendasat/lendaswap-sdk';
+
+const client = await Client.builder()
+  .url('https://apilendaswap.lendasat.com')
+  .withIdbStorage()
+  .network('bitcoin')
+  .arkadeUrl('https://arkade.computer')
+  .esploraUrl('https://mempool.space/api')
+  .build();
+
+await client.init();
+
+// Create Lightning → USDC (Polygon) swap
+const swap = await client.createLightningToEvmSwap(
+  {
+    target_address: '0xYourPolygonAddress',
+    source_amount: 100000n, // 100,000 sats
+    target_token: 'usdc_pol',
+  },
+  'polygon'
+);
+
+console.log('Swap created:', swap.id);
+console.log('Pay this Lightning invoice:', swap.lnInvoice);
+console.log('You will receive:', swap.assetAmount, 'USDC');
+
+// After paying the invoice, claim via Gelato (gasless)
+await client.claimGelato(swap.id);
+console.log('Swap claimed via Gelato relay!');
+```
+
 ### Arkade to Polygon Swap (with Gelato Auto-Redeem)
 
 This example shows how to swap BTC from Arkade to USDC on Polygon. The swap uses Gelato relay for gasless claiming on
 the EVM side.
 
 ```typescript
-import {
-  Client,
-  createDexieWalletStorage,
-  createDexieSwapStorage,
-} from '@lendasat/lendaswap-sdk';
-
-const walletStorage = createDexieWalletStorage();
-const swapStorage = createDexieSwapStorage();
+import { Client } from '@lendasat/lendaswap-sdk';
 
-const client = await Client.create(
-  'https://apilendaswap.lendasat.com',
-  walletStorage,
-  swapStorage,
-  'bitcoin',
-  'https://arkade.computer'
-);
+const client = await Client.builder()
+  .url('https://apilendaswap.lendasat.com')
+  .withIdbStorage()
+  .network('bitcoin')
+  .arkadeUrl('https://arkade.computer')
+  .esploraUrl('https://mempool.space/api')
+  .build();
 
 await client.init();
 
@@ -147,12 +187,12 @@ const swap = await client.createArkadeToEvmSwap(
   'polygon'
 );
 
-console.log('Swap created:', swap.swap_id);
+console.log('Swap created:', swap.id);
 console.log('Send BTC to Arkade VHTLC to proceed');
 
 // After sending BTC, claim via Gelato (gasless)
 // The secret is automatically derived from your wallet
-await client.claimGelato(swap.swap_id);
+await client.claimGelato(swap.id);
 console.log('Swap claimed via Gelato relay!');
 ```
 
@@ -165,22 +205,15 @@ We recommend using [wagmi](https://wagmi.sh/) with [viem](https://viem.sh/) for
 or [ethers.js](https://docs.ethers.org/) for vanilla JS/TS.
 
 ```typescript
-import {
-  Client,
-  createDexieWalletStorage,
-  createDexieSwapStorage,
-} from '@lendasat/lendaswap-sdk';
+import { Client } from '@lendasat/lendaswap-sdk';
 
-const walletStorage = createDexieWalletStorage();
-const swapStorage = createDexieSwapStorage();
-
-const client = await Client.create(
-  'https://apilendaswap.lendasat.com',
-  walletStorage,
-  swapStorage,
-  'bitcoin',
-  'https://arkade.computer'
-);
+const client = await Client.builder()
+  .url('https://apilendaswap.lendasat.com')
+  .withIdbStorage()
+  .network('bitcoin')
+  .arkadeUrl('https://arkade.computer')
+  .esploraUrl('https://mempool.space/api')
+  .build();
 
 await client.init();
 
@@ -194,9 +227,9 @@ const swap = await client.createEvmToLightningSwap(
   'ethereum'
 );
 
-console.log('Swap created:', swap.swap_id);
-console.log('Contract address:', swap.contract_address);
-console.log('Amount to send:', swap.source_amount);
+console.log('Swap created:', swap.id);
+console.log('Contract address:', swap.contractAddress);
+console.log('Amount to send:', swap.sourceAmount);
 
 // Now use your wallet to send the transaction to the HTLC contract
 // Example with wagmi/viem:
@@ -205,18 +238,18 @@ console.log('Amount to send:', swap.source_amount);
 // const { writeContract } = useWriteContract();
 //
 // await writeContract({
-//   address: swap.contract_address,
+//   address: swap.contractAddress,
 //   abi: htlcAbi,
 //   functionName: 'deposit',
-//   args: [swap.hash_lock, swap.timelock, ...],
-//   value: swap.source_amount,
+//   args: [swap.hashLock, swap.timelock, ...],
+//   value: swap.sourceAmount,
 // });
 //
 // Example with ethers.js:
 //
 // const signer = await provider.getSigner();
-// const contract = new ethers.Contract(swap.contract_address, htlcAbi, signer);
-// await contract.deposit(swap.hash_lock, swap.timelock, ...);
+// const contract = new ethers.Contract(swap.contractAddress, htlcAbi, signer);
+// await contract.deposit(swap.hashLock, swap.timelock, ...);
 ```
 
 ### Real-time Price Feed (WebSocket)
@@ -224,7 +257,7 @@ console.log('Amount to send:', swap.source_amount);
 Subscribe to real-time price updates via WebSocket:
 
 ```typescript
-import {PriceFeedService} from '@lendasat/lendaswap-sdk';
+import { PriceFeedService } from '@lendasat/lendaswap-sdk';
 
 const priceFeed = new PriceFeedService('https://apilendaswap.lendasat.com');
 
@@ -254,7 +287,9 @@ unsubscribe();
 - **Client** - Full-featured client for the Lendaswap API with WASM-powered cryptography
 - **Wallet Management** - HD wallet derivation for swap parameters
 - **Price Feed** - Real-time WebSocket price updates with auto-reconnection
-- **Storage Providers** - Dexie (IndexedDB) storage for wallet and swap data
+- **Price Calculations** - Helper functions for computing exchange rates and amounts
+- **USD Prices** - Fetch current USD prices from CoinGecko
+- **IndexedDB Storage** - Automatic storage via native Rust IndexedDB implementation
 - **Configurable Logging** - Set log level via code or localStorage
 
 ## API Reference
@@ -262,33 +297,53 @@ unsubscribe();
 ### Client
 
 ```typescript
-const client = await Client.create(
-  baseUrl,
-  walletStorage,
-  swapStorage,
-  network,
-  arkadeUrl
-);
+// Create client using builder pattern
+const client = await Client.builder()
+  .url('https://apilendaswap.lendasat.com')
+  .withIdbStorage()
+  .network('bitcoin')
+  .arkadeUrl('https://arkade.computer')
+  .esploraUrl('https://mempool.space/api')
+  .build();
 
 // Initialize wallet
 await client.init();
 await client.init('your mnemonic phrase'); // Or with existing mnemonic
 
-// Trading pairs and quotes
+// Trading pairs, tokens, and quotes
 await client.getAssetPairs();
+await client.getTokens();
 await client.getQuote(from, to, amount);
+await client.getVersion();
 
 // Swap operations
 await client.createArkadeToEvmSwap(request, targetNetwork);
+await client.createLightningToEvmSwap(request, targetNetwork);
 await client.createEvmToArkadeSwap(request, sourceNetwork);
 await client.createEvmToLightningSwap(request, sourceNetwork);
 await client.getSwap(id);
 await client.listAllSwaps();
+await client.deleteSwap(id);
+await client.clearSwapStorage();
 
 // Claiming and refunding
 await client.claimGelato(swapId);        // Gasless EVM claim via Gelato
 await client.claimVhtlc(swapId);         // Claim Arkade VHTLC
 await client.refundVhtlc(swapId, addr);  // Refund expired VHTLC
+await client.amountsForSwap(swapId);     // Get VHTLC amounts
+
+// On-chain Bitcoin to Arkade swaps
+await client.createBitcoinToArkadeSwap(request);
+await client.claimBtcToArkadeVhtlc(swapId);
+await client.refundOnchainHtlc(swapId, refundAddress);
+
+// VTXO swaps (refresh VTXOs)
+await client.estimateVtxoSwap(vtxos);
+await client.createVtxoSwap(vtxos);
+await client.getVtxoSwap(id);
+await client.claimVtxoSwap(swap, swapParams, claimAddress);
+await client.refundVtxoSwap(swapId, refundAddress);
+await client.listAllVtxoSwaps();
 
 // Recovery
 await client.recoverSwaps();
@@ -298,47 +353,10 @@ await client.getMnemonic();
 await client.getUserIdXpub();
 ```
 
-### Storage Providers
-
-```typescript
-import {
-  createDexieWalletStorage,
-  createDexieSwapStorage,
-} from '@lendasat/lendaswap-sdk';
-
-// Pre-built Dexie (IndexedDB) storage providers
-const walletStorage = createDexieWalletStorage();
-const swapStorage = createDexieSwapStorage();
-```
-
-Or implement custom storage:
-
-```typescript
-import type {
-  WalletStorageProvider,
-  SwapStorageProvider,
-} from '@lendasat/lendaswap-sdk';
-
-const walletStorage: WalletStorageProvider = {
-  getMnemonic: async () => localStorage.getItem('mnemonic'),
-  setMnemonic: async (m) => localStorage.setItem('mnemonic', m),
-  getKeyIndex: async () => parseInt(localStorage.getItem('idx') ?? '0'),
-  setKeyIndex: async (i) => localStorage.setItem('idx', i.toString()),
-};
-
-const swapStorage: SwapStorageProvider = {
-  get: async (id) => /* fetch from your storage */,
-  store: async (id, data) => /* store to your storage */,
-  delete: async (id) => /* delete from your storage */,
-  list: async () => /* return all swap IDs */,
-  getAll: async () => /* return all swap data */,
-};
-```
-
 ### PriceFeedService
 
 ```typescript
-import {PriceFeedService} from '@lendasat/lendaswap-sdk';
+import { PriceFeedService } from '@lendasat/lendaswap-sdk';
 
 const priceFeed = new PriceFeedService('https://apilendaswap.lendasat.com');
 
@@ -371,16 +389,72 @@ localStorage.setItem('lendaswap_log_level', 'debug');
 // Reload page for changes to take effect
 ```
 
+### Price Calculations
+
+```typescript
+import {
+  calculateSourceAmount,
+  calculateTargetAmount,
+  computeExchangeRate,
+  selectTierRate,
+} from '@lendasat/lendaswap-sdk';
+
+// Select the appropriate tier rate based on amount
+const rate = selectTierRate(priceTiers, amount);
+
+// Calculate target amount from source
+const targetAmount = calculateTargetAmount(sourceAmount, exchangeRate);
+
+// Calculate source amount from target
+const sourceAmount = calculateSourceAmount(targetAmount, exchangeRate);
+
+// Compute exchange rate from price tiers
+const exchangeRate = computeExchangeRate(priceTiers, amount);
+```
+
+### USD Prices
+
+```typescript
+import {
+  getUsdPrice,
+  getUsdPrices,
+  getSupportedTokensForUsdPrice,
+} from '@lendasat/lendaswap-sdk';
+
+// Get USD price for a single token
+const btcPrice = await getUsdPrice('btc_arkade');
+console.log('BTC price:', btcPrice.usd);
+
+// Get USD prices for multiple tokens
+const prices = await getUsdPrices(['btc_arkade', 'usdc_pol']);
+
+// Get list of supported tokens for USD price lookup
+const supported = getSupportedTokensForUsdPrice();
+```
+
 ## Supported Tokens
 
 | Token | Chain     | ID              |
 | ----- | --------- | --------------- |
 | BTC   | Lightning | `btc_lightning` |
 | BTC   | Arkade    | `btc_arkade`    |
+| BTC   | On-chain  | `btc_onchain`   |
 | USDC  | Polygon   | `usdc_pol`      |
 | USDT  | Polygon   | `usdt0_pol`     |
 | USDC  | Ethereum  | `usdc_eth`      |
 | USDT  | Ethereum  | `usdt_eth`      |
+| XAUT  | Ethereum  | `xaut_eth`      |
+
+## Comparison with Native SDK
+
+| Feature  | This SDK (Browser)        | Native SDK (Node.js)             |
+| -------- | ------------------------- | -------------------------------- |
+| Storage  | IndexedDB                 | SQLite                           |
+| Platform | Browser                   | Node.js                          |
+| Use case | Web apps, frontends       | Servers, CLI, backends           |
+| Package  | `@lendasat/lendaswap-sdk` | `@lendasat/lendaswap-sdk-native` |
+
+For server-side applications, CLI tools, or backends requiring SQLite storage, use `@lendasat/lendaswap-sdk-native`.
 
 ## License