@lendasat/lendaswap-sdk-pure 0.0.1

package/README.md

@@ -0,0 +1,297 @@
+# Lendaswap Pure TypeScript SDK
+
+A pure TypeScript SDK for interacting with the Lendaswap API. This SDK is designed to work in all JavaScript
+environments, including React Native.
+
+## Installation
+
+```bash
+npm install @lendasat/lendaswap-sdk-pure
+```
+
+## Supported Swaps
+
+This SDK currently supports the following swap directions:
+
+| Source       | Target                | Status    |
+| ------------ | --------------------- | --------- |
+| Lightning    | Polygon (USDC, USDT)  | Supported |
+| Lightning    | Arbitrum (USDC, USDT) | Supported |
+| Arkade       | Polygon (USDC, USDT)  | Supported |
+| Arkade       | Arbitrum (USDC, USDT) | Supported |
+| On-chain BTC | Polygon (USDC, USDT)  | Supported |
+| On-chain BTC | Arbitrum (USDC, USDT) | Supported |
+
+**Refund support:**
+
+- Lightning swaps: Auto-expire, no refund needed
+- Arkade swaps: Off-chain refund via Arkade protocol
+- On-chain BTC swaps: On-chain refund transaction after timelock
+
+> More swap directions (e.g., EVM to BTC) will be added in future versions.
+
+## Usage
+
+### Setup
+
+```typescript
+import { Client, IdbWalletStorage, IdbSwapStorage } from "@lendasat/lendaswap-sdk-pure";
+
+// Create a client with persistent storage (browser)
+const client = await Client.builder()
+  .withSignerStorage(new IdbWalletStorage())
+  .withSwapStorage(new IdbSwapStorage())
+  .withApiKey("your-api-key")
+  .build();
+
+// Or import an existing wallet
+const client = await Client.builder()
+  .withSignerStorage(new IdbWalletStorage())
+  .withSwapStorage(new IdbSwapStorage())
+  .withMnemonic("abandon abandon abandon ...")
+  .build();
+
+// Get the mnemonic (for backup)
+const mnemonic = client.getMnemonic();
+```
+
+### Get a Quote
+
+```typescript
+// Get available asset pairs
+const pairs = await client.getAssetPairs();
+
+// Get a quote for swapping 100k sats to USDC on Polygon
+const quote = await client.getQuote("btc_arkade", "usdc_pol", 100000);
+console.log(`You'll receive: ${quote.target_amount} USDC`);
+```
+
+### Create a Swap
+
+#### Lightning to EVM
+
+```typescript
+const result = await client.createLightningToEvmSwap({
+  targetAddress: "0x1234567890abcdef1234567890abcdef12345678",
+  targetToken: "usdc_pol",    // or "usdc_arb", "usdt_pol", "usdt_arb"
+  targetChain: "polygon",      // or "arbitrum"
+  sourceAmount: 100000,        // Amount in sats
+});
+
+// Pay the Lightning invoice to complete the swap
+console.log(`Pay this invoice: ${result.response.ln_invoice}`);
+console.log(`Swap ID: ${result.response.id}`);
+```
+
+#### Arkade to EVM
+
+```typescript
+const result = await client.createArkadeToEvmSwap({
+  targetAddress: "0x1234567890abcdef1234567890abcdef12345678",
+  targetToken: "usdc_arb",
+  targetChain: "arbitrum",
+  sourceAmount: 100000,
+});
+
+// Send BTC to the Arkade VHTLC address
+console.log(`Send BTC to: ${result.response.htlc_address_arkade}`);
+console.log(`Swap ID: ${result.response.id}`);
+```
+
+#### On-chain BTC to EVM
+
+```typescript
+const result = await client.createBitcoinToEvmSwap({
+  targetAddress: "0x1234567890abcdef1234567890abcdef12345678",
+  targetToken: "usdc_pol",
+  targetChain: "polygon",
+  sourceAmount: 100000,
+});
+
+// Send BTC to the on-chain HTLC address
+console.log(`Send BTC to: ${result.response.btc_htlc_address}`);
+console.log(`Swap ID: ${result.response.id}`);
+```
+
+### Monitor Swap Status
+
+```typescript
+// Get current swap status
+const swap = await client.getSwap("swap-uuid");
+console.log(`Status: ${swap.status}`);
+
+// Status flow: pending -> clientfunded -> serverfunded -> clientredeemed -> serverredeemed
+```
+
+### Claim EVM Tokens
+
+Once the server has funded the EVM HTLC (`serverfunded` status), claim your tokens:
+
+```typescript
+const claimResult = await client.claimEvmSwap("swap-uuid");
+console.log(`Claim tx: ${claimResult.tx_hash}`);
+```
+
+### Refund (if swap times out)
+
+```typescript
+// For on-chain BTC swaps
+const refundResult = await client.refundSwap("swap-uuid", {
+  destinationAddress: "bc1q...",  // Your Bitcoin address
+  feeRateSatPerVb: 5,
+});
+
+// For Arkade swaps
+const refundResult = await client.refundSwap("swap-uuid", {
+  destinationAddress: "ark1...",  // Your Arkade address
+});
+```
+
+### Storage
+
+The SDK provides pluggable storage interfaces for persisting wallet and swap data.
+Browser storage uses [Dexie](https://dexie.org/) for IndexedDB access with the database name `lendaswap-v3`.
+
+**Storage Types:**
+
+- `WalletStorage` - Stores mnemonic and key derivation index
+- `SwapStorage` - Stores `StoredSwap` records (API response + client-side params)
+
+**StoredSwap Structure:**
+
+Each swap is stored with both the API response and client-side parameters needed for claim/refund operations:
+
+```typescript
+interface StoredSwap {
+  version: number;        // Schema version for migrations
+  swapId: string;         // Primary key
+  keyIndex: number;       // Key derivation index
+  response: GetSwapResponse;  // Full API response
+  publicKey: string;      // Hex-encoded compressed public key
+  preimage: string;       // Hex-encoded preimage for claiming HTLCs
+  preimageHash: string;   // Hex-encoded hash lock
+  secretKey: string;      // Hex-encoded secret key for signing
+  storedAt: number;       // Timestamp when first stored
+  updatedAt: number;      // Timestamp when last updated
+}
+```
+
+**Usage:**
+
+```typescript
+import {
+  InMemoryWalletStorage,
+  InMemorySwapStorage,
+  IdbWalletStorage,     // Browser only (IndexedDB via Dexie)
+  IdbSwapStorage,       // Browser only (IndexedDB via Dexie)
+  idbStorageFactory,    // Factory for creating IDB storage
+  inMemoryStorageFactory,
+  SWAP_STORAGE_VERSION,
+  type StoredSwap,
+} from "@lendasat/lendaswap-sdk-pure";
+
+// In-memory storage (for testing or temporary sessions)
+const walletStorage = new InMemoryWalletStorage();
+const swapStorage = new InMemorySwapStorage();
+
+// IndexedDB storage (for browser persistence)
+// Uses shared "lendaswap-v3" database with "wallet" and "swaps" tables
+const walletStorage = new IdbWalletStorage();
+const swapStorage = new IdbSwapStorage();
+
+// Store a swap
+await swapStorage.store({
+  version: SWAP_STORAGE_VERSION,
+  swapId: "uuid",
+  keyIndex: 0,
+  response: apiResponse,
+  publicKey: "02...",
+  preimage: "...",
+  preimageHash: "...",
+  secretKey: "...",
+  storedAt: Date.now(),
+  updatedAt: Date.now(),
+});
+
+// Update swap response (e.g., after polling for status)
+await swapStorage.update("uuid", newApiResponse);
+
+// Custom storage (implement the WalletStorage/SwapStorage interfaces)
+// For React Native, you might use AsyncStorage or SQLite
+```
+
+## Development
+
+### Project Structure
+
+```
+src/
+├── api/
+│   └── client.ts       # Low-level API client wrapper
+├── generated/
+│   └── api.ts          # Auto-generated types from OpenAPI spec
+├── signer/
+│   └── index.ts        # HD wallet key derivation (BIP39/BIP32)
+├── storage/
+│   ├── index.ts        # Storage interfaces and in-memory implementations
+│   ├── idb.ts          # IndexedDB storage for browsers
+│   └── types.ts        # StoredSwap type definition
+├── client.ts           # High-level Client class with convenience methods
+└── index.ts            # Public exports
+```
+
+### Auto-generated API Types
+
+The TypeScript types in `src/generated/api.ts` are **auto-generated** from the OpenAPI specification. Do not edit this
+file manually.
+
+#### How it works
+
+1. The Lendaswap backend generates an OpenAPI 3.0 specification (`openapi.json`)
+   using [utoipa](https://github.com/juhaku/utoipa)
+2. We use [openapi-typescript](https://github.com/openapi-ts/openapi-typescript) to generate TypeScript types from the
+   spec
+3. The [openapi-fetch](https://github.com/openapi-ts/openapi-typescript/tree/main/packages/openapi-fetch) library
+   provides a type-safe HTTP client
+
+#### Regenerating the API client
+
+When the backend API changes:
+
+1. Download the latest OpenAPI spec from the backend:
+   ```bash
+   curl -o openapi.json https://apilendaswap.lendasat.com/api-docs/openapi.json
+   ```
+
+2. Run the generate command:
+   ```bash
+   npm run generate:api
+   ```
+
+This will regenerate `src/generated/api.ts` with the updated types.
+
+### Scripts
+
+| Command                | Description                            |
+| ---------------------- | -------------------------------------- |
+| `npm run build`        | Compile TypeScript to JavaScript       |
+| `npm run test`         | Run tests with Vitest                  |
+| `npm run lint`         | Run Biome linter                       |
+| `npm run lint:fix`     | Fix linting issues                     |
+| `npm run generate:api` | Regenerate API types from OpenAPI spec |
+
+### Adding New Features
+
+When adding new functionality:
+
+1. **API methods**: Add convenience methods to `src/client.ts` that wrap the low-level API calls
+2. **New types**: If the backend adds new endpoints, regenerate the API types first
+3. **Exports**: Update `src/index.ts` to export any new public types or classes
+
+### Dependencies
+
+- `openapi-fetch` - Type-safe HTTP client for OpenAPI specs
+- `@noble/hashes` - Cryptographic hash functions
+- `@scure/bip32` - BIP32 HD wallet derivation
+- `@scure/bip39` - BIP39 mnemonic phrase handling
+- `dexie` - IndexedDB wrapper for browser storage

package/dist/api/client.d.ts

@@ -0,0 +1,34 @@
+import createClient from "openapi-fetch";
+import type { components, paths } from "../generated/api.js";
+export type ApiClient = ReturnType<typeof createClient<paths>>;
+export type { paths, components };
+export type TokenId = components["schemas"]["TokenId"];
+export type TokenInfo = components["schemas"]["TokenInfo"];
+export type AssetPair = components["schemas"]["AssetPair"];
+export type SwapStatus = components["schemas"]["SwapStatus"];
+export type QuoteResponse = components["schemas"]["QuoteResponse"];
+export type GetSwapResponse = components["schemas"]["GetSwapResponse"];
+export type BtcToEvmSwapResponse = components["schemas"]["BtcToEvmSwapResponse"];
+export type OnchainToEvmSwapResponse = components["schemas"]["OnchainToEvmSwapResponse"];
+export type EvmToBtcSwapResponse = components["schemas"]["EvmToBtcSwapResponse"];
+export type BtcToArkadeSwapResponse = components["schemas"]["BtcToArkadeSwapResponse"];
+export type ArkadeToPolygonSwapRequest = components["schemas"]["ArkadeToPolygonSwapRequest"];
+export type ArkadeToEthereumSwapRequest = components["schemas"]["ArkadeToEthereumSwapRequest"];
+export type ArkadeToArbitrumSwapRequest = components["schemas"]["ArkadeToArbitrumSwapRequest"];
+export type LightningToPolygonSwapRequest = components["schemas"]["LightningToPolygonSwapRequest"];
+export type LightningToEthereumSwapRequest = components["schemas"]["LightningToEthereumSwapRequest"];
+export type LightningToArbitrumSwapRequest = components["schemas"]["LightningToArbitrumSwapRequest"];
+export type BitcoinToPolygonSwapRequest = components["schemas"]["BitcoinToPolygonSwapRequest"];
+export type BitcoinToEthereumSwapRequest = components["schemas"]["BitcoinToEthereumSwapRequest"];
+export type BitcoinToArbitrumSwapRequest = components["schemas"]["BitcoinToArbitrumSwapRequest"];
+export type PolygonToArkadeSwapRequest = components["schemas"]["PolygonToArkadeSwapRequest"];
+export type ArbitrumToArkadeSwapRequest = components["schemas"]["ArbitrumToArkadeSwapRequest"];
+export type EthereumToArkadeSwapRequest = components["schemas"]["EthereumToArkadeSwapRequest"];
+export type ClaimGelatoRequest = components["schemas"]["ClaimGelatoRequest"];
+export type ClaimGelatoResponse = components["schemas"]["ClaimGelatoResponse"];
+export interface ApiClientOptions {
+    baseUrl: string;
+    apiKey?: string;
+}
+export declare function createApiClient(options: ApiClientOptions): ApiClient;
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"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"}

package/dist/api/client.js

@@ -0,0 +1,12 @@
+import createClient from "openapi-fetch";
+export function createApiClient(options) {
+    const headers = {};
+    if (options.apiKey) {
+        headers["X-API-Key"] = options.apiKey;
+    }
+    return createClient({
+        baseUrl: options.baseUrl,
+        headers,
+    });
+}
+//# sourceMappingURL=client.js.map

package/dist/api/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,eAAe,CAAC;AA2DzC,MAAM,UAAU,eAAe,CAAC,OAAyB;IACvD,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,OAAO,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IACxC,CAAC;IAED,OAAO,YAAY,CAAQ;QACzB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,OAAO;KACR,CAAC,CAAC;AACL,CAAC"}