@arkade-os/boltz-swap 0.1.5 → 0.2.0-alpha.0

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,37 +42,164 @@ 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
 });
 ```
 
-## Storage
+### Create your Wallet
+
+```typescript
+import { Wallet } from '@arkade-os/sdk';
+
+const wallet = await Wallet.create({
+  identity,
+  arkServerUrl: 'https://mutinynet.arkade.sh',
+  // storage defaults to in-memory
+});
 
-By default this library doesn't store pending swaps.
+// Wallet may have built-in providers
+const arkadeLightning = new ArkadeLightning({
+  wallet,
+  swapProvider
+});
+```
 
-If you need it you must initialize a storageProvider:
+### ServiceWorkerWallet with IndexDB
 
 ```typescript
-const storageProvider = await StorageProvider.create({ storagePath: './storage.json' });
+import { ServiceWorkerWallet, SingleKey, RestArkProvider, RestIndexerProvider } from '@arkade-os/sdk';
+import { IndexedDBStorageAdapter } from '@arkade-os/sdk/storage';
 
+// 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,
+  wallet: serviceWorkerWallet,
+  arkProvider: new RestArkProvider('https://mutinynet.arkade.sh'),
+  indexerProvider: new RestIndexerProvider('https://mutinynet.arkade.sh'),
   swapProvider,
-  storageProvider,
 });
+```
 
-// you now are able to use the following methods
-const pendingPaymentsToLightning = arkadeLightning.getPendingSubmarineSwaps();
-const pendingPaymentsFromLightning = arkadeLightning.getPendingReverseSwaps();
+**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).
+
+## Checking Swap Limits
+
+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
+// Get current swap limits (in satoshis)
+const limits = await arkadeLightning.getLimits();
+
+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();
+
+// 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: