@arkade-os/boltz-swap 0.1.8 → 0.2.0-alpha.1

package/README.md

@@ -24,8 +24,11 @@ npm install @arkade-os/sdk @arkade-os/boltz-swap
 ### Initializing the Lightning Swap Provider
 
 ```typescript
-import { Wallet } from '@arkade-os/sdk';
-import { ArkadeLightning, BoltzSwapProvider, StorageProvider } from '@arkade-os/boltz-swap';
+import { Wallet, SingleKey } from '@arkade-os/sdk';
+import { ArkadeLightning, BoltzSwapProvider } from '@arkade-os/boltz-swap';
+
+// Create an identity
+const identity = SingleKey.fromHex('your_private_key_in_hex');
 
 // Initialize your Arkade wallet
 const wallet = await Wallet.create({
@@ -39,22 +42,14 @@ const swapProvider = new BoltzSwapProvider({
   network: 'mutinynet',
 });
 
-// Optionally: initialize a storage provider
-const storageProvider = await StorageProvider.create();
-
 // Create the ArkadeLightning instance
 const arkadeLightning = new ArkadeLightning({
   wallet,
   swapProvider,
-  storageProvider, // optional
 });
 ```
 
-## Wallet class Compatibility
-
-This library supports both wallet interface patterns:
-
-### Wallet (with optional nested identity and providers)
+### Create your Wallet
 
 ```typescript
 import { Wallet } from '@arkade-os/sdk';
@@ -62,57 +57,149 @@ import { Wallet } from '@arkade-os/sdk';
 const wallet = await Wallet.create({
   identity,
   arkServerUrl: 'https://mutinynet.arkade.sh',
+  // storage defaults to in-memory
 });
 
 // Wallet may have built-in providers
 const arkadeLightning = new ArkadeLightning({
   wallet,
-  swapProvider,
-  // arkProvider and indexerProvider can be provided here if wallet doesn't have them
+  swapProvider
 });
 ```
 
-### ServiceWorkerWallet (legacy interface)
+### ServiceWorkerWallet with IndexDB
 
 ```typescript
-import { RestArkProvider, RestIndexerProvider } from '@arkade-os/sdk';
+import { ServiceWorkerWallet, SingleKey, RestArkProvider, RestIndexerProvider } from '@arkade-os/sdk';
+import { IndexedDBStorageAdapter } from '@arkade-os/sdk/storage';
 
-// ServiceWorkerWallet has identity methods spread directly (no nested identity)
-const serviceWorkerWallet = new ServiceWorkerWallet(serviceWorker);
-await serviceWorkerWallet.init({
-  privateKey: 'your_private_key_hex',
-  arkServerUrl: 'https://ark.example.com'
+// Create your identity
+const identity = SingleKey.fromHex('your_private_key_hex');
+// Or generate a new one:
+// const identity = SingleKey.fromRandomBytes();
+
+// Configure IndexedDB storage adapter for ServiceWorker
+const storage = new IndexedDBStorageAdapter('arkade-service-worker-wallet', 1);
+
+const wallet = await ServiceWorkerWallet.setup({
+  serviceWorkerPath: '/service-worker.js',
+  arkServerUrl: 'https://mutinynet.arkade.sh',
+  identity,
+  storage, // Pass the IndexedDB storage adapter
 });
 
 // Must provide external providers for ServiceWorkerWallet (it doesn't have them)
 const arkadeLightning = new ArkadeLightning({
   wallet: serviceWorkerWallet,
-  arkProvider: new RestArkProvider('https://ark.example.com'),
-  indexerProvider: new RestIndexerProvider('https://indexer.example.com'),
+  arkProvider: new RestArkProvider('https://mutinynet.arkade.sh'),
+  indexerProvider: new RestIndexerProvider('https://mutinynet.arkade.sh'),
   swapProvider,
 });
 ```
 
-## Storage
+**Storage Adapters**: The Arkade SDK provides various storage adapters for different environments. For ServiceWorker environments, use `IndexedDBStorageAdapter`. For more storage options and adapters, see the [Arkade SDK storage adapters documentation](https://github.com/arkade-os/ts-sdk).
 
-By default this library doesn't store pending swaps.
+## Checking Swap Limits
 
-If you need it you must initialize a storageProvider:
+Before creating Lightning invoices or sending payments, you can check the minimum and maximum swap amounts supported by the Boltz service. This is useful to validate that your invoice amount is within the acceptable range.
 
 ```typescript
-const storageProvider = await StorageProvider.create({ storagePath: './storage.json' });
+// Get current swap limits (in satoshis)
+const limits = await arkadeLightning.getLimits();
 
-const arkadeLightning = new ArkadeLightning({
-  wallet,
-  swapProvider,
-  storageProvider,
-});
+if (limits) {
+  console.log('Minimum swap amount:', limits.min, 'sats');
+  console.log('Maximum swap amount:', limits.max, 'sats');
+
+  // Example: Validate invoice amount before creating
+  const invoiceAmount = 50000; // 50,000 sats
+
+  if (invoiceAmount < limits.min) {
+    console.error(`Amount ${invoiceAmount} is below minimum ${limits.min} sats`);
+  } else if (invoiceAmount > limits.max) {
+    console.error(`Amount ${invoiceAmount} is above maximum ${limits.max} sats`);
+  } else {
+    console.log('Amount is within valid range');
+    // Safe to proceed with creating invoice or payment
+  }
+} else {
+  console.log('Unable to fetch limits - no swap provider configured');
+}
+```
+
+### Validating Lightning Invoice Amounts
+
+```typescript
+import { decodeInvoice } from '@arkade-os/boltz-swap';
+
+// Decode an incoming Lightning invoice to check its amount
+const invoice = 'lnbc500u1pj...'; // Lightning invoice string
+const decodedInvoice = decodeInvoice(invoice);
+
+console.log('Invoice amount:', decodedInvoice.amountSats, 'sats');
+
+// Check if the invoice amount is within swap limits
+const limits = await arkadeLightning.getLimits();
+
+if (limits && decodedInvoice.amountSats >= limits.min && decodedInvoice.amountSats <= limits.max) {
+  // Amount is valid for swaps
+  const paymentResult = await arkadeLightning.sendLightningPayment({
+    invoice: invoice,
+    maxFeeSats: 1000,
+  });
+  console.log('Payment successful!');
+} else {
+  console.error('Invoice amount is outside supported swap limits');
+}
+```
+
+## Checking Swap Fees
+
+You can check the fee to pay for different swap amounts supported by the Boltz service.
+This is useful to validate the user is willing to pay the fees.
+
+```typescript
+// Get current swap fees
+const fees: FeesResponse | null = await arkadeLightning.getFees();
+if (!fees) throw new Error('something went wrong');
+
+const calcSubmarineSwapFee = (satoshis: number): number => {
+  if (!satoshis) return 0;
+  const { percentage, minerFees } = fees.submarine;
+  return Math.ceil((satoshis * percentage) / 100 + minerFees);
+};
+
+const calcReverseSwapFee = (satoshis: number): number => {
+  if (!satoshis) return 0;
+  const { percentage, minerFees } = fees.reverse;
+  return Math.ceil((satoshis * percentage) / 100 + minerFees.claim + minerFees.lockup);
+};
+```
+
+## Checking swap status
+
+```typescript
+const response = await arkadeLightning.getSwapStatus('swap_id');
+console.log('swap status = ', response.status);
+```
+
+## Storage
+
+This library automatically stores pending swaps using the wallet's built-in contract repository. All swap data is persisted automatically and can be retrieved using the following methods:
+
+```typescript
+// Get all pending submarine swaps (those waiting for Lightning payment)
+const pendingPaymentsToLightning = await arkadeLightning.getPendingSubmarineSwaps();
+
+// Get all pending reverse swaps (those waiting for claim)
+const pendingPaymentsFromLightning = await arkadeLightning.getPendingReverseSwaps();
 
-// you now are able to use the following methods
-const pendingPaymentsToLightning = arkadeLightning.getPendingSubmarineSwaps();
-const pendingPaymentsFromLightning = arkadeLightning.getPendingReverseSwaps();
+// Get complete swap history (both completed and pending)
+const swapHistory = await arkadeLightning.getSwapHistory();
 ```
 
+**Note**: All swap data is automatically persisted and retrieved through the wallet's contract repository. No additional storage configuration is required.
+
 ## Receiving Lightning Payments
 
 To receive a Lightning payment into your Arkade wallet: