@arkade-os/boltz-swap 0.3.0 → 0.3.1

package/dist/{chunk-XVJ47GNJ.js → chunk-Y7C7NJ5D.js}

@@ -1,7 +1,10 @@
 // src/errors.ts
 var SwapError = class extends Error {
+  /** Whether the swap can still be claimed (default: false). */
   isClaimable;
+  /** Whether the swap can be refunded (default: false). */
   isRefundable;
+  /** The pending swap associated with this error, if available. */
   pendingSwap;
   constructor(options = {}) {
     super(options.message ?? "Error during swap.");
@@ -33,7 +36,9 @@ var InsufficientFundsError = class extends SwapError {
   }
 };
 var NetworkError = class extends Error {
+  /** HTTP status code from the failed request, if available. */
   statusCode;
+  /** Raw error payload from the Boltz API, if available. */
   errorData;
   constructor(message, statusCode, errorData) {
     super(message);
@@ -272,7 +277,10 @@ var isTree = (data) => {
   return data && typeof data === "object" && isLeaf(data.claimLeaf) && isLeaf(data.refundLeaf) && isLeaf(data.refundWithoutBoltzLeaf) && isLeaf(data.unilateralClaimLeaf) && isLeaf(data.unilateralRefundLeaf) && isLeaf(data.unilateralRefundWithoutBoltzLeaf);
 };
 var isDetails = (data) => {
-  return data && typeof data === "object" && isTree(data.tree) && (data.amount === void 0 || typeof data.amount === "number") && typeof data.keyIndex === "number" && (data.transaction === void 0 || data.transaction && typeof data.transaction === "object" && typeof data.transaction.id === "string" && typeof data.transaction.vout === "number") && typeof data.lockupAddress === "string" && typeof data.serverPublicKey === "string" && typeof data.timeoutBlockHeight === "number" && isTimeoutBlockHeights(data.timeoutBlockHeights) && (data.preimageHash === void 0 || typeof data.preimageHash === "string");
+  return data && typeof data === "object" && isTree(data.tree) && (data.amount === void 0 || typeof data.amount === "number") && typeof data.keyIndex === "number" && (data.transaction === void 0 || data.transaction && typeof data.transaction === "object" && typeof data.transaction.id === "string" && typeof data.transaction.vout === "number") && typeof data.lockupAddress === "string" && typeof data.serverPublicKey === "string" && typeof data.timeoutBlockHeight === "number" && (data.timeoutBlockHeights === void 0 || isTimeoutBlockHeights(data.timeoutBlockHeights)) && (data.preimageHash === void 0 || typeof data.preimageHash === "string");
+};
+var isRestoredChainSwap = (data) => {
+  return data && typeof data === "object" && typeof data.id === "string" && data.type === "chain" && typeof data.status === "string" && typeof data.createdAt === "number" && (data.from === "ARK" || data.from === "BTC") && (data.to === "ARK" || data.to === "BTC") && typeof data.preimageHash === "string" && data.refundDetails && typeof data.refundDetails === "object" && isTree(data.refundDetails.tree) && typeof data.refundDetails.amount === "number" && typeof data.refundDetails.keyIndex === "number" && (data.refundDetails.transaction === void 0 || data.refundDetails.transaction && typeof data.refundDetails.transaction === "object" && typeof data.refundDetails.transaction.id === "string" && typeof data.refundDetails.transaction.vout === "number") && typeof data.refundDetails.lockupAddress === "string" && typeof data.refundDetails.serverPublicKey === "string" && typeof data.refundDetails.timeoutBlockHeight === "number";
 };
 var isRestoredSubmarineSwap = (data) => {
   return data && typeof data === "object" && data.to === "BTC" && typeof data.id === "string" && data.from === "ARK" && data.type === "submarine" && typeof data.createdAt === "number" && typeof data.preimageHash === "string" && typeof data.status === "string" && isDetails(data.refundDetails);
@@ -282,10 +290,11 @@ var isRestoredReverseSwap = (data) => {
 };
 var isCreateSwapsRestoreResponse = (data) => {
   return Array.isArray(data) && data.every(
-    (item) => isRestoredReverseSwap(item) || isRestoredSubmarineSwap(item)
+    (item) => isRestoredChainSwap(item) || isRestoredReverseSwap(item) || isRestoredSubmarineSwap(item)
   );
 };
 var BASE_URLS = {
+  bitcoin: "https://api.ark.boltz.exchange",
   mutinynet: "https://api.boltz.mutinynet.arkade.sh",
   regtest: "http://localhost:9069"
 };
@@ -294,6 +303,7 @@ var BoltzSwapProvider = class {
   apiUrl;
   network;
   referralId;
+  /** @param config Provider configuration with network and optional API URL. */
   constructor(config) {
     this.network = config.network;
     this.referralId = config.referralId;
@@ -305,15 +315,19 @@ var BoltzSwapProvider = class {
     this.apiUrl = apiUrl;
     this.wsUrl = this.apiUrl.replace(/^http(s)?:\/\//, "ws$1://").replace("9069", "9004") + "/v2/ws";
   }
+  /** Returns the Boltz API base URL. */
   getApiUrl() {
     return this.apiUrl;
   }
+  /** Returns the Boltz WebSocket URL (derived from apiUrl). */
   getWsUrl() {
     return this.wsUrl;
   }
+  /** Returns the configured network. */
   getNetwork() {
     return this.network;
   }
+  /** Returns current Lightning swap fees (submarine + reverse) from Boltz. */
   async getFees() {
     const [submarine, reverse] = await Promise.all([
       this.request(
@@ -337,6 +351,7 @@ var BoltzSwapProvider = class {
       }
     };
   }
+  /** Returns current Lightning swap min/max limits from Boltz. */
   async getLimits() {
     const response = await this.request(
       "/v2/swap/submarine",
@@ -349,6 +364,7 @@ var BoltzSwapProvider = class {
       max: response.ARK.BTC.limits.maximal
     };
   }
+  /** Gets the lockup transaction ID for a reverse swap. */
   async getReverseSwapTxId(id) {
     const res = await this.request(
       `/v2/swap/reverse/${id}/transaction`,
@@ -360,6 +376,7 @@ var BoltzSwapProvider = class {
       });
     return res;
   }
+  /** Queries the current status of a swap by ID. */
   async getSwapStatus(id) {
     const response = await this.request(
       `/v2/swap/${id}`,
@@ -371,6 +388,7 @@ var BoltzSwapProvider = class {
       });
     return response;
   }
+  /** Gets the preimage for a settled submarine swap (proof of payment). */
   async getSwapPreimage(id) {
     const res = await this.request(
       `/v2/swap/submarine/${id}/preimage`,
@@ -382,6 +400,7 @@ var BoltzSwapProvider = class {
       });
     return res;
   }
+  /** Creates a submarine swap (Arkade → Lightning) on Boltz. */
   async createSubmarineSwap({
     invoice,
     refundPublicKey
@@ -407,6 +426,7 @@ var BoltzSwapProvider = class {
       throw new SchemaError({ message: "Error creating submarine swap" });
     return response;
   }
+  /** Creates a reverse swap (Lightning → Arkade) on Boltz. */
   async createReverseSwap({
     invoiceAmount,
     claimPublicKey,
@@ -436,6 +456,7 @@ var BoltzSwapProvider = class {
       throw new SchemaError({ message: "Error creating reverse swap" });
     return response;
   }
+  /** Creates a chain swap (ARK ↔ BTC) on Boltz. */
   async createChainSwap({
     to,
     from,
@@ -494,6 +515,7 @@ var BoltzSwapProvider = class {
       throw new SchemaError({ message: "Error creating chain swap" });
     return response;
   }
+  /** Requests Boltz co-signature for a submarine swap refund. Returns signed transaction + checkpoint. */
   async refundSubmarineSwap(swapId, transaction, checkpoint) {
     const requestBody = {
       checkpoint: base64.encode(checkpoint.toPSBT()),
@@ -517,6 +539,7 @@ var BoltzSwapProvider = class {
       )
     };
   }
+  /** Requests Boltz co-signature for a chain swap refund. Returns signed transaction + checkpoint. */
   async refundChainSwap(swapId, transaction, checkpoint) {
     const requestBody = {
       checkpoint: base64.encode(checkpoint.toPSBT()),
@@ -540,6 +563,7 @@ var BoltzSwapProvider = class {
       )
     };
   }
+  /** Monitors swap status updates via WebSocket. Calls update callback on each status change. Resolves when terminal. */
   async monitorSwap(swapId, update) {
     return new Promise((resolve, reject) => {
       const webSocket = new globalThis.WebSocket(this.wsUrl);
@@ -607,6 +631,7 @@ var BoltzSwapProvider = class {
       };
     });
   }
+  /** Returns current chain swap fees for a given pair (e.g. ARK→BTC). */
   async getChainFees(from, to) {
     if (from === to) {
       throw new SwapError({ message: "Invalid chain pair" });
@@ -624,6 +649,7 @@ var BoltzSwapProvider = class {
     }
     return response[from][to].fees;
   }
+  /** Returns current chain swap min/max limits for a given pair. */
   async getChainLimits(from, to) {
     if (from === to) {
       throw new SwapError({ message: "Invalid chain pair" });
@@ -644,6 +670,7 @@ var BoltzSwapProvider = class {
       max: response[from][to].limits.maximal
     };
   }
+  /** Gets claim details (pubNonce, publicKey, transactionHash) for cooperative chain swap claiming. */
   async getChainClaimDetails(swapId) {
     const response = await this.request(
       `/v2/swap/chain/${swapId}/claim`,
@@ -655,6 +682,7 @@ var BoltzSwapProvider = class {
       });
     return response;
   }
+  /** Gets a renegotiated quote for a chain swap when lockup amount differs from expected. */
   async getChainQuote(swapId) {
     const response = await this.request(
       `/v2/swap/chain/${swapId}/quote`,
@@ -666,6 +694,7 @@ var BoltzSwapProvider = class {
       });
     return response;
   }
+  /** Accepts a renegotiated quote amount for a chain swap. */
   async postChainQuote(swapId, request) {
     const response = await this.request(
       `/v2/swap/chain/${swapId}/quote`,
@@ -678,6 +707,7 @@ var BoltzSwapProvider = class {
       });
     return response;
   }
+  /** Broadcasts a raw BTC transaction through Boltz. */
   async postBtcTransaction(hex9) {
     const requestBody = { hex: hex9 };
     const response = await this.request(
@@ -691,6 +721,7 @@ var BoltzSwapProvider = class {
       });
     return response;
   }
+  /** Posts claim details (preimage + signing data) or cooperative signature for a chain swap. */
   async postChainClaimDetails(swapId, request) {
     const response = await this.request(
       `/v2/swap/chain/${swapId}/claim`,
@@ -703,6 +734,7 @@ var BoltzSwapProvider = class {
       });
     return response;
   }
+  /** Restores swaps from Boltz API using the wallet's public key. */
   async restoreSwaps(publicKey) {
     const requestBody = {
       publicKey
@@ -2798,24 +2830,61 @@ var validFinalArkTx = (finalArkTx, _pubkey, _tapLeaves) => {
 };
 
 // src/arkade-swaps.ts
-var ArkadeSwaps = class {
+var ArkadeSwaps = class _ArkadeSwaps {
+  /** The Arkade wallet instance used for signing and address generation. */
   wallet;
+  /** Provider for Ark protocol operations (VTXO management, batch joining). */
   arkProvider;
+  /** Boltz API client for creating and monitoring swaps. */
   swapProvider;
+  /** Provider for querying VTXO state on the Ark indexer. */
   indexerProvider;
+  /** Background swap monitor, or null if not enabled. */
   swapManager = null;
+  /** Storage backend for persisting swap data. */
   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 async create(config) {
+    if (config.swapProvider) {
+      return new _ArkadeSwaps(config);
+    }
+    const arkProvider = config.arkProvider ?? config.wallet.arkProvider;
+    if (!arkProvider)
+      throw new Error(
+        "Ark provider is required either in wallet or config."
+      );
+    const arkInfo = await arkProvider.getInfo();
+    const network = arkInfo.network;
+    const swapProvider = new BoltzSwapProvider({ network });
+    return new _ArkadeSwaps({ ...config, swapProvider });
+  }
   constructor(config) {
     if (!config.wallet) throw new Error("Wallet is required.");
     if (!config.swapProvider) throw new Error("Swap provider is required.");
     this.wallet = config.wallet;
-    const arkProvider = config.wallet.arkProvider ?? config.arkProvider;
+    const arkProvider = config.arkProvider ?? config.wallet.arkProvider;
     if (!arkProvider)
       throw new Error(
         "Ark provider is required either in wallet or config."
       );
     this.arkProvider = arkProvider;
-    const indexerProvider = config.wallet.indexerProvider ?? config.indexerProvider;
+    const indexerProvider = config.indexerProvider ?? config.wallet.indexerProvider;
     if (!indexerProvider)
       throw new Error(
         "Indexer provider is required either in wallet or config."
@@ -2827,8 +2896,8 @@ var ArkadeSwaps = class {
     } else {
       this.swapRepository = new IndexedDbSwapRepository();
     }
-    if (config.swapManager) {
-      const swapManagerConfig = config.swapManager === true ? {} : config.swapManager;
+    if (config.swapManager !== false) {
+      const swapManagerConfig = !config.swapManager || config.swapManager === true ? {} : config.swapManager;
       const shouldAutostart = swapManagerConfig.autoStart ?? true;
       this.swapManager = new SwapManager(
         this.swapProvider,
@@ -2945,9 +3014,11 @@ var ArkadeSwaps = class {
   // Lightning: Reverse swaps (receive Lightning -> Arkade)
   // =========================================================================
   /**
-   * 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.
    */
   async createLightningInvoice(args) {
     const pendingSwap = await this.createReverseSwap(args);
@@ -2962,9 +3033,11 @@ var ArkadeSwaps = class {
     };
   }
   /**
-   * 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.
    */
   async createReverseSwap(args) {
     if (args.amount <= 0)
@@ -3003,8 +3076,9 @@ var ArkadeSwaps = class {
     return pendingSwap;
   }
   /**
-   * 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.
    */
   async claimVHTLC(pendingSwap) {
     if (!pendingSwap.preimage)
@@ -3084,9 +3158,13 @@ var ArkadeSwaps = class {
     );
   }
   /**
-   * 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.
    */
   async waitAndClaim(pendingSwap) {
     if (this.swapManager && await this.swapManager.hasSwap(pendingSwap.id)) {
@@ -3166,9 +3244,11 @@ var ArkadeSwaps = class {
   // Lightning: Submarine swaps (send Arkade -> Lightning)
   // =========================================================================
   /**
-   * 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).
    */
   async sendLightningPayment(args) {
     const pendingSwap = await this.createSubmarineSwap(args);
@@ -3198,9 +3278,10 @@ var ArkadeSwaps = class {
     }
   }
   /**
-   * 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.
    */
   async createSubmarineSwap(args) {
     const refundPublicKey = hex8.encode(
@@ -3232,8 +3313,10 @@ var ArkadeSwaps = class {
     return pendingSwap;
   }
   /**
-   * 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.
    */
   async refundVHTLC(pendingSwap) {
     const preimageHash = pendingSwap.request.invoice ? getInvoicePaymentHash(pendingSwap.request.invoice) : pendingSwap.preimageHash;
@@ -3317,9 +3400,12 @@ var ArkadeSwaps = class {
     );
   }
   /**
-   * 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.
    */
   async waitForSwapSettlement(pendingSwap) {
     return new Promise((resolve, reject) => {
@@ -3390,8 +3476,12 @@ var ArkadeSwaps = class {
   // =========================================================================
   /**
    * 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.
    */
   async arkToBtc(args) {
     const pendingSwap = await this.createChainSwap({
@@ -3683,8 +3773,11 @@ var ArkadeSwaps = class {
   // =========================================================================
   /**
    * 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.
    */
   async btcToArk(args) {
     const pendingSwap = await this.createChainSwap({
@@ -4226,6 +4319,7 @@ var ArkadeSwaps = class {
     );
     if (!publicKey) throw new Error("Failed to get public key from wallet");
     const fees = boltzFees ?? await this.swapProvider.getFees();
+    const chainSwaps = [];
     const reverseSwaps = [];
     const submarineSwaps = [];
     const restoredSwaps = await this.swapProvider.restoreSwaps(publicKey);
@@ -4318,9 +4412,45 @@ var ArkadeSwaps = class {
             }
           }
         });
+      } else if (isRestoredChainSwap(swap)) {
+        const {
+          amount,
+          lockupAddress,
+          serverPublicKey,
+          timeoutBlockHeight
+        } = swap.refundDetails;
+        chainSwaps.push({
+          id,
+          type: "chain",
+          createdAt,
+          preimage: "",
+          ephemeralKey: "",
+          feeSatsPerByte: 1,
+          amount,
+          status,
+          request: {
+            to: swap.to,
+            from: swap.from,
+            preimageHash: swap.preimageHash,
+            claimPublicKey: "",
+            feeSatsPerByte: 1,
+            refundPublicKey: "",
+            serverLockAmount: amount,
+            userLockAmount: amount
+          },
+          response: {
+            id,
+            lockupDetails: {
+              amount,
+              lockupAddress,
+              serverPublicKey,
+              timeoutBlockHeight
+            }
+          }
+        });
       }
     }
-    return { reverseSwaps, submarineSwaps };
+    return { chainSwaps, reverseSwaps, submarineSwaps };
   }
   /**
    * Enrich a restored reverse swap with its preimage.