@arkade-os/boltz-swap 0.3.0 → 0.3.1

package/dist/{arkade-swaps-Brpa88Fg.d.cts → arkade-swaps-DHjneVaF.d.ts}

@@ -1,14 +1,47 @@
 import { IWallet, ArkProvider, IndexerProvider, ArkInfo, Identity, ArkTxInput, VHTLC } from '@arkade-os/sdk';
-import { l as BoltzSwapProvider, V as SwapManager, i as SwapRepository, A as ArkadeSwapsConfig, j as SwapManagerClient, C as CreateLightningInvoiceRequest, e as CreateLightningInvoiceResponse, b as PendingReverseSwap, S as SendLightningPaymentRequest, f as SendLightningPaymentResponse, c as PendingSubmarineSwap, h as ArkToBtcResponse, a as PendingChainSwap, B as BtcToArkResponse, d as Chain, F as FeesResponse, g as ChainFeesResponse, L as LimitsResponse, G as GetSwapStatusResponse, P as PendingSwap } from './types-BRYTZH1Z.cjs';
+import { l as BoltzSwapProvider, V as SwapManager, i as SwapRepository, X as ArkadeSwapsCreateConfig, A as ArkadeSwapsConfig, j as SwapManagerClient, C as CreateLightningInvoiceRequest, e as CreateLightningInvoiceResponse, b as PendingReverseSwap, S as SendLightningPaymentRequest, f as SendLightningPaymentResponse, c as PendingSubmarineSwap, h as ArkToBtcResponse, a as PendingChainSwap, B as BtcToArkResponse, d as Chain, F as FeesResponse, g as ChainFeesResponse, L as LimitsResponse, G as GetSwapStatusResponse, P as PendingSwap } from './types-t0r41rlw.js';
 import { TransactionOutput } from '@scure/btc-signer/psbt.js';
 
+/**
+ * Unified entry point for Lightning and chain swaps between Arkade, Lightning Network, and Bitcoin.
+ *
+ * Orchestrates submarine swaps (Arkade → Lightning), reverse swaps (Lightning → Arkade),
+ * and chain swaps (ARK ↔ BTC) through the Boltz swap protocol.
+ *
+ * Optionally integrates SwapManager for autonomous background monitoring, auto-claiming,
+ * and auto-refunding of swaps.
+ */
 declare class ArkadeSwaps {
+    /** The Arkade wallet instance used for signing and address generation. */
     readonly wallet: IWallet;
+    /** Provider for Ark protocol operations (VTXO management, batch joining). */
     readonly arkProvider: ArkProvider;
+    /** Boltz API client for creating and monitoring swaps. */
     readonly swapProvider: BoltzSwapProvider;
+    /** Provider for querying VTXO state on the Ark indexer. */
     readonly indexerProvider: IndexerProvider;
+    /** Background swap monitor, or null if not enabled. */
     readonly swapManager: SwapManager | null;
+    /** Storage backend for persisting swap data. */
     readonly swapRepository: SwapRepository;
+    /**
+     * Creates an ArkadeSwaps instance, auto-detecting the network from the wallet's Ark server.
+     * If no `swapProvider` is given, one is created automatically using the detected network.
+     *
+     * This is the recommended way to initialize ArkadeSwaps.
+     *
+     * @param config - Configuration options. swapProvider is auto-created from the wallet's network if omitted.
+     * @returns A fully initialized ArkadeSwaps instance.
+     *
+     * @example
+     * ```ts
+     * const swaps = await ArkadeSwaps.create({
+     *   wallet,
+     *   swapManager: true,
+     * });
+     * ```
+     */
+    static create(config: ArkadeSwapsCreateConfig): Promise<ArkadeSwaps>;
     constructor(config: ArkadeSwapsConfig);
     private savePendingReverseSwap;
     private savePendingSubmarineSwap;
@@ -41,59 +74,80 @@ declare class ArkadeSwaps {
      */
     [Symbol.asyncDispose](): Promise<void>;
     /**
-     * Creates a Lightning invoice.
-     * @param args - The arguments for creating a Lightning invoice.
-     * @returns The response containing the created Lightning invoice.
+     * Creates a Lightning invoice via a reverse swap (Lightning → Arkade).
+     * @param args.amount - Invoice amount in satoshis.
+     * @param args.description - Optional description for the BOLT11 invoice.
+     * @returns Object containing the BOLT11 invoice, payment hash, preimage, and pending swap for monitoring.
+     * @throws {SwapError} If amount is <= 0 or wallet key retrieval fails.
      */
     createLightningInvoice(args: CreateLightningInvoiceRequest): Promise<CreateLightningInvoiceResponse>;
     /**
-     * Creates a reverse swap.
-     * @param args - The arguments for creating a reverse swap.
-     * @returns The created pending reverse swap.
+     * Creates a reverse swap (Lightning → Arkade) and saves it to storage.
+     * @param args.amount - Amount in satoshis for the reverse swap.
+     * @param args.description - Optional invoice description.
+     * @returns The pending reverse swap, added to SwapManager if enabled.
+     * @throws {SwapError} If amount is <= 0 or key retrieval fails.
      */
     createReverseSwap(args: CreateLightningInvoiceRequest): Promise<PendingReverseSwap>;
     /**
-     * Claims the VHTLC for a pending reverse swap.
-     * @param pendingSwap - The pending reverse swap to claim the VHTLC.
+     * Claims the VHTLC for a pending reverse swap, transferring locked funds to the wallet.
+     * @param pendingSwap - The reverse swap whose VHTLC should be claimed.
+     * @throws {Error} If preimage is missing, VHTLC script creation fails, or no spendable VTXOs found.
      */
     claimVHTLC(pendingSwap: PendingReverseSwap): Promise<void>;
     /**
-     * Waits for the swap to be confirmed and claims the VHTLC.
-     * @param pendingSwap - The pending reverse swap.
+     * Waits for a reverse swap to be confirmed and claims the VHTLC.
+     * Delegates to SwapManager if enabled, otherwise monitors via WebSocket.
+     * @param pendingSwap - The reverse swap to monitor and claim.
      * @returns The transaction ID of the claimed VHTLC.
+     * @throws {InvoiceExpiredError} If the Lightning invoice expires.
+     * @throws {SwapExpiredError} If the swap exceeds its time limit.
+     * @throws {TransactionFailedError} If the on-chain transaction fails.
      */
     waitAndClaim(pendingSwap: PendingReverseSwap): Promise<{
         txid: string;
     }>;
     /**
-     * Sends a Lightning payment.
-     * @param args - The arguments for sending a Lightning payment.
-     * @returns The result of the payment.
+     * Sends a Lightning payment via a submarine swap (Arkade → Lightning).
+     * Creates the swap, sends funds, and waits for settlement. Auto-refunds on failure.
+     * @param args.invoice - BOLT11 Lightning invoice to pay.
+     * @returns The amount paid, preimage (proof of payment), and transaction ID.
+     * @throws {TransactionFailedError} If the payment fails (auto-refunds if possible).
      */
     sendLightningPayment(args: SendLightningPaymentRequest): Promise<SendLightningPaymentResponse>;
     /**
-     * Creates a submarine swap.
-     * @param args - The arguments for creating a submarine swap.
-     * @returns The created pending submarine swap.
+     * Creates a submarine swap (Arkade → Lightning) and saves it to storage.
+     * @param args.invoice - BOLT11 Lightning invoice to pay.
+     * @returns The pending submarine swap, added to SwapManager if enabled.
+     * @throws {SwapError} If invoice is missing or key retrieval fails.
      */
     createSubmarineSwap(args: SendLightningPaymentRequest): Promise<PendingSubmarineSwap>;
     /**
-     * Claims the VHTLC for a pending submarine swap (aka refund).
-     * @param pendingSwap - The pending submarine swap to refund the VHTLC.
+     * Refunds the VHTLC for a failed submarine swap, returning locked funds to the wallet.
+     * Uses multi-party signatures (user + Boltz + server) for non-recoverable VTXOs.
+     * @param pendingSwap - The submarine swap to refund.
+     * @throws {Error} If preimage hash is unavailable, VHTLC not found, or already spent.
      */
     refundVHTLC(pendingSwap: PendingSubmarineSwap): Promise<void>;
     /**
-     * Waits for the swap settlement.
-     * @param pendingSwap - The pending submarine swap.
-     * @returns The status of the swap settlement.
+     * Waits for a submarine swap's Lightning payment to settle.
+     * @param pendingSwap - The submarine swap to monitor.
+     * @returns The preimage from the settled Lightning payment (proof of payment).
+     * @throws {SwapExpiredError} If the swap expires.
+     * @throws {InvoiceFailedToPayError} If Boltz fails to route the payment.
+     * @throws {TransactionLockupFailedError} If the lockup transaction fails.
      */
     waitForSwapSettlement(pendingSwap: PendingSubmarineSwap): Promise<{
         preimage: string;
     }>;
     /**
      * Creates a chain swap from ARK to BTC.
-     * @param args - Swap arguments.
-     * @returns The payment details and pending chain swap.
+     * @param args.btcAddress - Destination Bitcoin address.
+     * @param args.senderLockAmount - Exact amount sender locks (receiver gets less after fees). Specify this OR receiverLockAmount.
+     * @param args.receiverLockAmount - Exact amount receiver gets (sender pays more). Specify this OR senderLockAmount.
+     * @param args.feeSatsPerByte - Fee rate for the BTC claim transaction (default: 1).
+     * @returns The ARK lockup address, amount to pay, and pending swap.
+     * @throws {SwapError} If chain swap verification fails.
      */
     arkToBtc(args: {
         btcAddress: string;
@@ -121,8 +175,11 @@ declare class ArkadeSwaps {
     refundArk(pendingSwap: PendingChainSwap): Promise<void>;
     /**
      * Creates a chain swap from BTC to ARK.
-     * @param args - Swap arguments.
-     * @returns The pending chain swap and payment details.
+     * @param args.feeSatsPerByte - Fee rate for BTC transactions (default: 1).
+     * @param args.senderLockAmount - Exact BTC amount to lock. Specify this OR receiverLockAmount.
+     * @param args.receiverLockAmount - Exact ARK amount to receive. Specify this OR senderLockAmount.
+     * @returns The BTC lockup address, amount to pay, and pending swap.
+     * @throws {SwapError} If chain swap verification fails.
      */
     btcToArk(args: {
         feeSatsPerByte?: number;
@@ -266,6 +323,7 @@ declare class ArkadeSwaps {
      * display/monitoring and are not automatically wired into the SwapManager.
      */
     restoreSwaps(boltzFees?: FeesResponse): Promise<{
+        chainSwaps: PendingChainSwap[];
         reverseSwaps: PendingReverseSwap[];
         submarineSwaps: PendingSubmarineSwap[];
     }>;
@@ -278,6 +336,7 @@ declare class ArkadeSwaps {
      */
     enrichSubmarineSwapInvoice(swap: PendingSubmarineSwap, invoice: string): PendingSubmarineSwap;
 }
+/** Public interface for ArkadeSwaps, defining all swap operations available to consumers. */
 interface IArkadeSwaps extends AsyncDisposable {
     startSwapManager(): Promise<void>;
     stopSwapManager(): Promise<void>;
@@ -295,6 +354,7 @@ interface IArkadeSwaps extends AsyncDisposable {
         preimage: string;
     }>;
     restoreSwaps(boltzFees?: FeesResponse): Promise<{
+        chainSwaps: PendingChainSwap[];
         reverseSwaps: PendingReverseSwap[];
         submarineSwaps: PendingSubmarineSwap[];
     }>;

package/dist/{arkade-swaps-DnvQayY0.d.ts → arkade-swaps-w-cm-cPg.d.cts}

@@ -1,14 +1,47 @@
 import { IWallet, ArkProvider, IndexerProvider, ArkInfo, Identity, ArkTxInput, VHTLC } from '@arkade-os/sdk';
-import { l as BoltzSwapProvider, V as SwapManager, i as SwapRepository, A as ArkadeSwapsConfig, j as SwapManagerClient, C as CreateLightningInvoiceRequest, e as CreateLightningInvoiceResponse, b as PendingReverseSwap, S as SendLightningPaymentRequest, f as SendLightningPaymentResponse, c as PendingSubmarineSwap, h as ArkToBtcResponse, a as PendingChainSwap, B as BtcToArkResponse, d as Chain, F as FeesResponse, g as ChainFeesResponse, L as LimitsResponse, G as GetSwapStatusResponse, P as PendingSwap } from './types-BRYTZH1Z.js';
+import { l as BoltzSwapProvider, V as SwapManager, i as SwapRepository, X as ArkadeSwapsCreateConfig, A as ArkadeSwapsConfig, j as SwapManagerClient, C as CreateLightningInvoiceRequest, e as CreateLightningInvoiceResponse, b as PendingReverseSwap, S as SendLightningPaymentRequest, f as SendLightningPaymentResponse, c as PendingSubmarineSwap, h as ArkToBtcResponse, a as PendingChainSwap, B as BtcToArkResponse, d as Chain, F as FeesResponse, g as ChainFeesResponse, L as LimitsResponse, G as GetSwapStatusResponse, P as PendingSwap } from './types-t0r41rlw.cjs';
 import { TransactionOutput } from '@scure/btc-signer/psbt.js';
 
+/**
+ * Unified entry point for Lightning and chain swaps between Arkade, Lightning Network, and Bitcoin.
+ *
+ * Orchestrates submarine swaps (Arkade → Lightning), reverse swaps (Lightning → Arkade),
+ * and chain swaps (ARK ↔ BTC) through the Boltz swap protocol.
+ *
+ * Optionally integrates SwapManager for autonomous background monitoring, auto-claiming,
+ * and auto-refunding of swaps.
+ */
 declare class ArkadeSwaps {
+    /** The Arkade wallet instance used for signing and address generation. */
     readonly wallet: IWallet;
+    /** Provider for Ark protocol operations (VTXO management, batch joining). */
     readonly arkProvider: ArkProvider;
+    /** Boltz API client for creating and monitoring swaps. */
     readonly swapProvider: BoltzSwapProvider;
+    /** Provider for querying VTXO state on the Ark indexer. */
     readonly indexerProvider: IndexerProvider;
+    /** Background swap monitor, or null if not enabled. */
     readonly swapManager: SwapManager | null;
+    /** Storage backend for persisting swap data. */
     readonly swapRepository: SwapRepository;
+    /**
+     * Creates an ArkadeSwaps instance, auto-detecting the network from the wallet's Ark server.
+     * If no `swapProvider` is given, one is created automatically using the detected network.
+     *
+     * This is the recommended way to initialize ArkadeSwaps.
+     *
+     * @param config - Configuration options. swapProvider is auto-created from the wallet's network if omitted.
+     * @returns A fully initialized ArkadeSwaps instance.
+     *
+     * @example
+     * ```ts
+     * const swaps = await ArkadeSwaps.create({
+     *   wallet,
+     *   swapManager: true,
+     * });
+     * ```
+     */
+    static create(config: ArkadeSwapsCreateConfig): Promise<ArkadeSwaps>;
     constructor(config: ArkadeSwapsConfig);
     private savePendingReverseSwap;
     private savePendingSubmarineSwap;
@@ -41,59 +74,80 @@ declare class ArkadeSwaps {
      */
     [Symbol.asyncDispose](): Promise<void>;
     /**
-     * Creates a Lightning invoice.
-     * @param args - The arguments for creating a Lightning invoice.
-     * @returns The response containing the created Lightning invoice.
+     * Creates a Lightning invoice via a reverse swap (Lightning → Arkade).
+     * @param args.amount - Invoice amount in satoshis.
+     * @param args.description - Optional description for the BOLT11 invoice.
+     * @returns Object containing the BOLT11 invoice, payment hash, preimage, and pending swap for monitoring.
+     * @throws {SwapError} If amount is <= 0 or wallet key retrieval fails.
      */
     createLightningInvoice(args: CreateLightningInvoiceRequest): Promise<CreateLightningInvoiceResponse>;
     /**
-     * Creates a reverse swap.
-     * @param args - The arguments for creating a reverse swap.
-     * @returns The created pending reverse swap.
+     * Creates a reverse swap (Lightning → Arkade) and saves it to storage.
+     * @param args.amount - Amount in satoshis for the reverse swap.
+     * @param args.description - Optional invoice description.
+     * @returns The pending reverse swap, added to SwapManager if enabled.
+     * @throws {SwapError} If amount is <= 0 or key retrieval fails.
      */
     createReverseSwap(args: CreateLightningInvoiceRequest): Promise<PendingReverseSwap>;
     /**
-     * Claims the VHTLC for a pending reverse swap.
-     * @param pendingSwap - The pending reverse swap to claim the VHTLC.
+     * Claims the VHTLC for a pending reverse swap, transferring locked funds to the wallet.
+     * @param pendingSwap - The reverse swap whose VHTLC should be claimed.
+     * @throws {Error} If preimage is missing, VHTLC script creation fails, or no spendable VTXOs found.
      */
     claimVHTLC(pendingSwap: PendingReverseSwap): Promise<void>;
     /**
-     * Waits for the swap to be confirmed and claims the VHTLC.
-     * @param pendingSwap - The pending reverse swap.
+     * Waits for a reverse swap to be confirmed and claims the VHTLC.
+     * Delegates to SwapManager if enabled, otherwise monitors via WebSocket.
+     * @param pendingSwap - The reverse swap to monitor and claim.
      * @returns The transaction ID of the claimed VHTLC.
+     * @throws {InvoiceExpiredError} If the Lightning invoice expires.
+     * @throws {SwapExpiredError} If the swap exceeds its time limit.
+     * @throws {TransactionFailedError} If the on-chain transaction fails.
      */
     waitAndClaim(pendingSwap: PendingReverseSwap): Promise<{
         txid: string;
     }>;
     /**
-     * Sends a Lightning payment.
-     * @param args - The arguments for sending a Lightning payment.
-     * @returns The result of the payment.
+     * Sends a Lightning payment via a submarine swap (Arkade → Lightning).
+     * Creates the swap, sends funds, and waits for settlement. Auto-refunds on failure.
+     * @param args.invoice - BOLT11 Lightning invoice to pay.
+     * @returns The amount paid, preimage (proof of payment), and transaction ID.
+     * @throws {TransactionFailedError} If the payment fails (auto-refunds if possible).
      */
     sendLightningPayment(args: SendLightningPaymentRequest): Promise<SendLightningPaymentResponse>;
     /**
-     * Creates a submarine swap.
-     * @param args - The arguments for creating a submarine swap.
-     * @returns The created pending submarine swap.
+     * Creates a submarine swap (Arkade → Lightning) and saves it to storage.
+     * @param args.invoice - BOLT11 Lightning invoice to pay.
+     * @returns The pending submarine swap, added to SwapManager if enabled.
+     * @throws {SwapError} If invoice is missing or key retrieval fails.
      */
     createSubmarineSwap(args: SendLightningPaymentRequest): Promise<PendingSubmarineSwap>;
     /**
-     * Claims the VHTLC for a pending submarine swap (aka refund).
-     * @param pendingSwap - The pending submarine swap to refund the VHTLC.
+     * Refunds the VHTLC for a failed submarine swap, returning locked funds to the wallet.
+     * Uses multi-party signatures (user + Boltz + server) for non-recoverable VTXOs.
+     * @param pendingSwap - The submarine swap to refund.
+     * @throws {Error} If preimage hash is unavailable, VHTLC not found, or already spent.
      */
     refundVHTLC(pendingSwap: PendingSubmarineSwap): Promise<void>;
     /**
-     * Waits for the swap settlement.
-     * @param pendingSwap - The pending submarine swap.
-     * @returns The status of the swap settlement.
+     * Waits for a submarine swap's Lightning payment to settle.
+     * @param pendingSwap - The submarine swap to monitor.
+     * @returns The preimage from the settled Lightning payment (proof of payment).
+     * @throws {SwapExpiredError} If the swap expires.
+     * @throws {InvoiceFailedToPayError} If Boltz fails to route the payment.
+     * @throws {TransactionLockupFailedError} If the lockup transaction fails.
      */
     waitForSwapSettlement(pendingSwap: PendingSubmarineSwap): Promise<{
         preimage: string;
     }>;
     /**
      * Creates a chain swap from ARK to BTC.
-     * @param args - Swap arguments.
-     * @returns The payment details and pending chain swap.
+     * @param args.btcAddress - Destination Bitcoin address.
+     * @param args.senderLockAmount - Exact amount sender locks (receiver gets less after fees). Specify this OR receiverLockAmount.
+     * @param args.receiverLockAmount - Exact amount receiver gets (sender pays more). Specify this OR senderLockAmount.
+     * @param args.feeSatsPerByte - Fee rate for the BTC claim transaction (default: 1).
+     * @returns The ARK lockup address, amount to pay, and pending swap.
+     * @throws {SwapError} If chain swap verification fails.
      */
     arkToBtc(args: {
         btcAddress: string;
@@ -121,8 +175,11 @@ declare class ArkadeSwaps {
     refundArk(pendingSwap: PendingChainSwap): Promise<void>;
     /**
      * Creates a chain swap from BTC to ARK.
-     * @param args - Swap arguments.
-     * @returns The pending chain swap and payment details.
+     * @param args.feeSatsPerByte - Fee rate for BTC transactions (default: 1).
+     * @param args.senderLockAmount - Exact BTC amount to lock. Specify this OR receiverLockAmount.
+     * @param args.receiverLockAmount - Exact ARK amount to receive. Specify this OR senderLockAmount.
+     * @returns The BTC lockup address, amount to pay, and pending swap.
+     * @throws {SwapError} If chain swap verification fails.
      */
     btcToArk(args: {
         feeSatsPerByte?: number;
@@ -266,6 +323,7 @@ declare class ArkadeSwaps {
      * display/monitoring and are not automatically wired into the SwapManager.
      */
     restoreSwaps(boltzFees?: FeesResponse): Promise<{
+        chainSwaps: PendingChainSwap[];
         reverseSwaps: PendingReverseSwap[];
         submarineSwaps: PendingSubmarineSwap[];
     }>;
@@ -278,6 +336,7 @@ declare class ArkadeSwaps {
      */
     enrichSubmarineSwapInvoice(swap: PendingSubmarineSwap, invoice: string): PendingSubmarineSwap;
 }
+/** Public interface for ArkadeSwaps, defining all swap operations available to consumers. */
 interface IArkadeSwaps extends AsyncDisposable {
     startSwapManager(): Promise<void>;
     stopSwapManager(): Promise<void>;
@@ -295,6 +354,7 @@ interface IArkadeSwaps extends AsyncDisposable {
         preimage: string;
     }>;
     restoreSwaps(boltzFees?: FeesResponse): Promise<{
+        chainSwaps: PendingChainSwap[];
         reverseSwaps: PendingReverseSwap[];
         submarineSwaps: PendingSubmarineSwap[];
     }>;

package/dist/{background-OI6ONB3C.js → background-2UJPEKEU.js}

@@ -2,8 +2,8 @@ import {
   defineExpoSwapBackgroundTask,
   registerExpoSwapBackgroundTask,
   unregisterExpoSwapBackgroundTask
-} from "./chunk-WNTQXNGX.js";
-import "./chunk-XVJ47GNJ.js";
+} from "./chunk-LKAPZQDE.js";
+import "./chunk-Y7C7NJ5D.js";
 import "./chunk-3RG5ZIWI.js";
 export {
   defineExpoSwapBackgroundTask,

package/dist/{chunk-WNTQXNGX.js → chunk-LKAPZQDE.js}

@@ -8,7 +8,7 @@ import {
   isSubmarineFinalStatus,
   isSubmarineSwapRefundable,
   logger
-} from "./chunk-XVJ47GNJ.js";
+} from "./chunk-Y7C7NJ5D.js";
 import {
   __require
 } from "./chunk-3RG5ZIWI.js";