@atomiqlabs/sdk 8.4.3 → 8.5.0

package/dist/swaps/ISwap.d.ts

@@ -156,6 +156,16 @@ export declare abstract class ISwap<T extends ChainType = ChainType, D extends S
      * @param options Additional options for executing the swap
      */
     abstract txsExecute(options?: any): Promise<SwapExecutionAction<T>[]>;
+    /**
+     * Executes the swap with the provided wallet, the exact arguments for this functions differ for various swap
+     *  types. Check the `execute()` function signature in the respective swap class to see the required arguments.
+     *
+     * @param args Execution arguments, usually contains a source wallet object, callbacks and options, for exact
+     *  syntax check the respective swap class.
+     *
+     * @returns Whether a swap was successfully executed or not, if it wasn't the user can refund or claim manually
+     */
+    abstract execute(...args: any[]): Promise<boolean>;
     /**
      * This attempts to populate missing fields in the pricing info based on the swap amounts
      *
@@ -257,6 +267,10 @@ export declare abstract class ISwap<T extends ChainType = ChainType, D extends S
      * Returns whether the swap failed (e.g. was refunded)
      */
     abstract isFailed(): boolean;
+    /**
+     * Returns whether the swap is currently being processed
+     */
+    abstract isInProgress(): boolean;
     /**
      * Whether a swap was initialized, a swap is considered initialized on first interaction with it, i.e.
      *  calling commit() on a Smart chain -> Bitcoin swaps, calling waitForPayment() or similar on the other

package/dist/swaps/ISwap.js

@@ -105,6 +105,8 @@ class ISwap {
      * @internal
      */
     waitTillState(targetState, type = "eq", abortSignal) {
+        //TODO: This doesn't hold strong reference to the swap, hence if no other strong reference to the
+        // swap exists, it will just never resolve!
         return new Promise((resolve, reject) => {
             let listener;
             listener = (swap) => {

package/dist/swaps/ISwapWithGasDrop.d.ts

@@ -17,5 +17,5 @@ export interface ISwapWithGasDrop<T extends ChainType> {
      * Returns the output of the "gas drop", additional native token received by the user on
      *  the destination chain
      */
-    getGasDropOutput(): TokenAmount<T["ChainId"], SCToken<T["ChainId"]>>;
+    getGasDropOutput(): TokenAmount<SCToken<T["ChainId"]>>;
 }

package/dist/swaps/ISwapWrapper.d.ts

@@ -4,7 +4,6 @@ import { ChainEvent, ChainType } from "@atomiqlabs/base";
 import { EventEmitter } from "events";
 import { ISwap } from "./ISwap";
 import { ISwapPrice } from "../prices/abstract/ISwapPrice";
-import { ChainIds, MultiChain } from "../swapper/Swapper";
 import { UnifiedSwapEventListener } from "../events/UnifiedSwapEventListener";
 import { SwapType } from "../enums/SwapType";
 import { UnifiedSwapStorage } from "../storage/UnifiedSwapStorage";
@@ -24,17 +23,9 @@ export type ISwapWrapperOptions = {
  *
  * @category Swaps/Base
  */
-export type WrapperCtorTokens<T extends MultiChain = MultiChain> = {
-    ticker: string;
-    name: string;
-    chains: {
-        [chainId in ChainIds<T>]?: {
-            address: string;
-            decimals: number;
-            displayDecimals?: number;
-        };
-    };
-}[];
+export type WrapperCtorTokens<T extends ChainType = ChainType> = {
+    [tokenAddress: string]: SCToken<T["ChainId"]>;
+};
 /**
  * Type definition linking wrapper and swap types
  *
@@ -135,6 +126,15 @@ export declare abstract class ISwapWrapper<T extends ChainType, D extends SwapTy
     constructor(chainIdentifier: T["ChainId"], unifiedStorage: UnifiedSwapStorage<T>, unifiedChainEvents: UnifiedSwapEventListener<T>, chain: T["ChainInterface"], prices: ISwapPrice, tokens: WrapperCtorTokens, options: O, events?: EventEmitter<{
         swapState: [ISwap];
     }>);
+    /**
+     * Parses the provided gas amount from its `string` or `bigint` representation to `bigint` base units.
+     *
+     * Defaults to `0n` if no gasAmount is provided
+     *
+     * @param gasAmount
+     * @internal
+     */
+    protected parseGasAmount(gasAmount?: string | bigint): bigint;
     /**
      * Pre-fetches swap price for a given swap
      *

package/dist/swaps/ISwapWrapper.js

@@ -4,6 +4,8 @@ exports.ISwapWrapper = void 0;
 const events_1 = require("events");
 const IntermediaryError_1 = require("../errors/IntermediaryError");
 const Logger_1 = require("../utils/Logger");
+const TokenUtils_1 = require("../utils/TokenUtils");
+const UserError_1 = require("../errors/UserError");
 /**
  * Base abstract class for swap handler implementations
  *
@@ -34,21 +36,27 @@ class ISwapWrapper {
         this._prices = prices;
         this.events = events || new events_1.EventEmitter();
         this._options = options;
-        this._tokens = {};
-        for (let tokenData of tokens) {
-            const chainData = tokenData.chains[chainIdentifier];
-            if (chainData == null)
-                continue;
-            this._tokens[chainData.address] = {
-                chain: "SC",
-                chainId: this.chainIdentifier,
-                address: chainData.address,
-                decimals: chainData.decimals,
-                ticker: tokenData.ticker,
-                name: tokenData.name,
-                displayDecimals: chainData.displayDecimals
-            };
+        this._tokens = tokens;
+    }
+    /**
+     * Parses the provided gas amount from its `string` or `bigint` representation to `bigint` base units.
+     *
+     * Defaults to `0n` if no gasAmount is provided
+     *
+     * @param gasAmount
+     * @internal
+     */
+    parseGasAmount(gasAmount) {
+        let result;
+        if (typeof (gasAmount) === "string") {
+            result = (0, TokenUtils_1.fromHumanReadableString)(gasAmount, this._getNativeToken());
+            if (result == null)
+                throw new UserError_1.UserError("Invalid `gasAmount` option provided, not a numerical string!");
+        }
+        else {
+            result = gasAmount;
         }
+        return result ?? 0n;
     }
     /**
      * Pre-fetches swap price for a given swap

package/dist/swaps/escrow_swaps/IEscrowSelfInitSwap.d.ts

@@ -46,15 +46,15 @@ export declare abstract class IEscrowSelfInitSwap<T extends ChainType = ChainTyp
     /**
      * Returns the transaction fee paid on the smart chain side to initiate the escrow
      */
-    getSmartChainNetworkFee(): Promise<TokenAmount<T["ChainId"], SCToken<T["ChainId"]>, true>>;
+    getSmartChainNetworkFee(): Promise<TokenAmount<SCToken<T["ChainId"]>, true>>;
     /**
      * Checks if the initiator/sender has enough balance on the smart chain side
      *  to cover the transaction fee for processing the swap
      */
     abstract hasEnoughForTxFees(): Promise<{
         enoughBalance: boolean;
-        balance: TokenAmount<T["ChainId"], SCToken<T["ChainId"]>, true>;
-        required: TokenAmount<T["ChainId"], SCToken<T["ChainId"]>, true>;
+        balance: TokenAmount<SCToken<T["ChainId"]>, true>;
+        required: TokenAmount<SCToken<T["ChainId"]>, true>;
     }>;
     /**
      * Returns transactions for initiating (committing) the escrow on the smart chain side. After sending the

package/dist/swaps/escrow_swaps/frombtc/IFromBTCSelfInitSwap.d.ts

@@ -91,35 +91,35 @@ export declare abstract class IFromBTCSelfInitSwap<T extends ChainType = ChainTy
     /**
      * @inheritDoc
      */
-    getOutput(): TokenAmount<T["ChainId"], SCToken<T["ChainId"]>, true>;
+    getOutput(): TokenAmount<SCToken<T["ChainId"]>, true>;
     /**
      * @inheritDoc
      */
-    abstract getInput(): TokenAmount<T["ChainId"], BtcToken>;
+    abstract getInput(): TokenAmount<BtcToken>;
     /**
      * @inheritDoc
      */
-    getInputWithoutFee(): TokenAmount<T["ChainId"], BtcToken>;
+    getInputWithoutFee(): TokenAmount<BtcToken>;
     /**
      * @inheritDoc
      */
     hasEnoughForTxFees(): Promise<{
         enoughBalance: boolean;
-        balance: TokenAmount<T["ChainId"], SCToken<T["ChainId"]>, true>;
-        required: TokenAmount<T["ChainId"], SCToken<T["ChainId"]>, true>;
+        balance: TokenAmount<SCToken<T["ChainId"]>, true>;
+        required: TokenAmount<SCToken<T["ChainId"]>, true>;
     }>;
     /**
      * Returns the amount of native token of the destination chain locked up during initialization of the escrow
      *  to act as a security deposit that can be taken by the intermediary (LP) if the user doesn't go through
      *  with the swap
      */
-    getSecurityDeposit(): TokenAmount<T["ChainId"], SCToken<T["ChainId"]>, true>;
+    getSecurityDeposit(): TokenAmount<SCToken<T["ChainId"]>, true>;
     /**
      * Returns the total amount of native token of the destination chain locked up during initialization of the escrow.
      *  This covers the security deposit and the watchtower fee (if applicable), it is calculated a maximum of those
      *  two values.
      */
-    getTotalDeposit(): TokenAmount<T["ChainId"], SCToken<T["ChainId"]>, true>;
+    getTotalDeposit(): TokenAmount<SCToken<T["ChainId"]>, true>;
     /**
      * Returns transactions for initiating (committing) the escrow on the destination smart chain side, pre-locking the
      *  tokens from the intermediary (LP) into an escrow.
@@ -146,7 +146,7 @@ export declare abstract class IFromBTCSelfInitSwap<T extends ChainType = ChainTy
      * Returns the transaction fee required for the claim transaction to settle the escrow on the destination
      *  smart chain
      */
-    getClaimNetworkFee(): Promise<TokenAmount<T["ChainId"], SCToken<T["ChainId"]>, true>>;
+    getClaimNetworkFee(): Promise<TokenAmount<SCToken<T["ChainId"]>, true>>;
     /**
      * @inheritDoc
      */

package/dist/swaps/escrow_swaps/frombtc/ln/FromBTCLNSwap.d.ts

@@ -208,6 +208,10 @@ export declare class FromBTCLNSwap<T extends ChainType = ChainType> extends IFro
      * @inheritDoc
      */
     isFailed(): boolean;
+    /**
+     * @inheritDoc
+     */
+    isInProgress(): boolean;
     /**
      * @inheritDoc
      */
@@ -233,18 +237,18 @@ export declare class FromBTCLNSwap<T extends ChainType = ChainType> extends IFro
     /**
      * @inheritDoc
      */
-    getInput(): TokenAmount<T["ChainId"], BtcToken<true>>;
+    getInput(): TokenAmount<BtcToken<true>>;
     /**
      * @inheritDoc
      */
-    getSmartChainNetworkFee(): Promise<TokenAmount<T["ChainId"], SCToken<T["ChainId"]>, true>>;
+    getSmartChainNetworkFee(): Promise<TokenAmount<SCToken<T["ChainId"]>, true>>;
     /**
      * @inheritDoc
      */
     hasEnoughForTxFees(): Promise<{
         enoughBalance: boolean;
-        balance: TokenAmount<T["ChainId"], SCToken<T["ChainId"]>, true>;
-        required: TokenAmount<T["ChainId"], SCToken<T["ChainId"]>, true>;
+        balance: TokenAmount<SCToken<T["ChainId"]>, true>;
+        required: TokenAmount<SCToken<T["ChainId"]>, true>;
     }>;
     private isValidSecretPreimage;
     /**
@@ -282,7 +286,7 @@ export declare class FromBTCLNSwap<T extends ChainType = ChainType> extends IFro
         secret?: string;
         lightningTxCheckIntervalSeconds?: number;
         delayBetweenCommitAndClaimSeconds?: number;
-    }): Promise<void>;
+    }): Promise<boolean>;
     /**
      * @inheritDoc
      *
@@ -418,7 +422,7 @@ export declare class FromBTCLNSwap<T extends ChainType = ChainType> extends IFro
      * Estimated transaction fee for commit & claim transactions combined, required
      *  to settle the swap on the smart chain destination side.
      */
-    getCommitAndClaimNetworkFee(): Promise<TokenAmount<T["ChainId"], SCToken<T["ChainId"]>, true>>;
+    getCommitAndClaimNetworkFee(): Promise<TokenAmount<SCToken<T["ChainId"]>, true>>;
     /**
      * Returns whether the underlying chain supports calling commit and claim in a single call,
      *  such that you can use the {@link commitAndClaim} function. If not you have to manually

package/dist/swaps/escrow_swaps/frombtc/ln/FromBTCLNSwap.js

@@ -321,6 +321,15 @@ class FromBTCLNSwap extends IFromBTCSelfInitSwap_1.IFromBTCSelfInitSwap {
     isFailed() {
         return this._state === FromBTCLNSwapState.FAILED || this._state === FromBTCLNSwapState.EXPIRED;
     }
+    /**
+     * @inheritDoc
+     */
+    isInProgress() {
+        return (this._state === FromBTCLNSwapState.PR_CREATED && this.initiated) ||
+            (this._state === FromBTCLNSwapState.QUOTE_SOFT_EXPIRED && this.initiated) ||
+            this._state === FromBTCLNSwapState.PR_PAID ||
+            this._state === FromBTCLNSwapState.CLAIM_COMMITED;
+    }
     /**
      * @inheritDoc
      */
@@ -485,6 +494,7 @@ class FromBTCLNSwap extends IFromBTCSelfInitSwap_1.IFromBTCSelfInitSwap {
             if (callbacks?.onSwapSettled != null)
                 callbacks.onSwapSettled(this.getOutputTxId());
         }
+        return true;
     }
     /**
      * @inheritDoc

package/dist/swaps/escrow_swaps/frombtc/ln/FromBTCLNWrapper.d.ts

@@ -18,9 +18,30 @@ import { AmountData } from "../../../../types/AmountData";
 import { LNURLWithdrawParamsWithUrl } from "../../../../types/lnurl/LNURLWithdraw";
 import { AllOptional } from "../../../../utils/TypeUtils";
 export type FromBTCLNOptions = {
-    paymentHash?: Buffer;
+    /**
+     * Instead of letting the SDK generate the preimage/paymentHash pair internally you can pass your computed
+     *  paymentHash here, this will create the swap with the provided payment hash. Note that you would then
+     *  have to reveal the preimage by passing it to the {@link FromBTCLNSwap.claim} or {@link FromBTCLNSwap.txsClaim}
+     *  functions
+     *
+     * Accepts both, a {@link Buffer} and a hexadecimal `string`
+     */
+    paymentHash?: Buffer | string;
+    /**
+     * Optional description to use for the swap lightning network invoice, keep the invoice length below 500 characters
+     */
     description?: string;
-    descriptionHash?: Buffer;
+    /**
+     * Optional description hash to use for the lightning network invoice, useful when returning the invoice as part of
+     *  an LNURL-pay service endpoint.
+     *
+     * Accepts both, a {@link Buffer} and a hexadecimal `string`
+     */
+    descriptionHash?: Buffer | string;
+    /**
+     * A flag to skip checking whether the lightning network node of the LP has enough channel liquidity to facilitate
+     *  the swap.
+     */
     unsafeSkipLnNodeCheck?: boolean;
 };
 export type FromBTCLNWrapperOptions = ISwapWrapperOptions & {

package/dist/swaps/escrow_swaps/frombtc/ln/FromBTCLNWrapper.js

@@ -155,19 +155,18 @@ class FromBTCLNWrapper extends IFromBTCLNWrapper_1.IFromBTCLNWrapper {
     create(recipient, amountData, lps, options, additionalParams, abortSignal, preFetches) {
         if (!this.isInitialized)
             throw new Error("Not initialized, call init() first!");
-        if (options == null)
-            options = {};
-        options.unsafeSkipLnNodeCheck ??= this._options.unsafeSkipLnNodeCheck;
-        if (options.paymentHash != null && options.paymentHash.length !== 32)
-            throw new UserError_1.UserError("Invalid payment hash length, must be exactly 32 bytes!");
-        if (options.descriptionHash != null && options.descriptionHash.length !== 32)
-            throw new UserError_1.UserError("Invalid description hash length");
-        if (options.description != null && buffer_1.Buffer.byteLength(options.description, "utf8") > 500)
+        const _options = {
+            paymentHash: (0, Utils_1.parseHashValueExact32Bytes)(options?.paymentHash, "payment hash"),
+            description: options?.description,
+            descriptionHash: (0, Utils_1.parseHashValueExact32Bytes)(options?.descriptionHash, "description hash"),
+            unsafeSkipLnNodeCheck: options?.unsafeSkipLnNodeCheck ?? this._options.unsafeSkipLnNodeCheck
+        };
+        if (_options.description != null && buffer_1.Buffer.byteLength(_options.description, "utf8") > 500)
             throw new UserError_1.UserError("Invalid description length");
         let secret;
         let paymentHash;
-        if (options?.paymentHash != null) {
-            paymentHash = options.paymentHash;
+        if (_options.paymentHash != null) {
+            paymentHash = _options.paymentHash;
         }
         else {
             ({ secret, paymentHash } = this.getSecretAndHash());
@@ -194,14 +193,14 @@ class FromBTCLNWrapper extends IFromBTCLNWrapper_1.IFromBTCLNWrapper {
                             amount: amountData.amount,
                             claimer: recipient,
                             token: amountData.token.toString(),
-                            description: options?.description,
-                            descriptionHash: options?.descriptionHash,
+                            description: _options.description,
+                            descriptionHash: _options.descriptionHash,
                             exactOut: !amountData.exactIn,
                             feeRate: (0, Utils_1.throwIfUndefined)(_preFetches.feeRatePromise),
                             additionalParams
                         }, this._options.postRequestTimeout, abortController.signal, retryCount > 0 ? false : undefined);
                         return {
-                            lnCapacityPromise: options?.unsafeSkipLnNodeCheck ? null : this.preFetchLnCapacity(lnPublicKey),
+                            lnCapacityPromise: _options.unsafeSkipLnNodeCheck ? null : this.preFetchLnCapacity(lnPublicKey),
                             resp: await response
                         };
                     }, undefined, RequestError_1.RequestError, abortController.signal);
@@ -212,7 +211,7 @@ class FromBTCLNWrapper extends IFromBTCLNWrapper_1.IFromBTCLNWrapper {
                         throw new IntermediaryError_1.IntermediaryError("Invalid returned swap invoice, no expiry date field");
                     const amountIn = (BigInt(decodedPr.millisatoshis) + 999n) / 1000n;
                     try {
-                        this.verifyReturnedData(resp, amountData, lp, options ?? {}, decodedPr, paymentHash);
+                        this.verifyReturnedData(resp, amountData, lp, _options, decodedPr, paymentHash);
                         const [pricingInfo] = await Promise.all([
                             this.verifyReturnedPrice(lp.services[SwapType_1.SwapType.FROM_BTCLN], false, amountIn, resp.total, amountData.token, {}, _preFetches.pricePrefetchPromise, _preFetches.usdPricePrefetchPromise, abortController.signal),
                             this.verifyIntermediaryLiquidity(resp.total, (0, Utils_1.throwIfUndefined)(liquidityPromise)),
@@ -259,8 +258,12 @@ class FromBTCLNWrapper extends IFromBTCLNWrapper_1.IFromBTCLNWrapper {
     async createViaLNURL(recipient, lnurl, amountData, lps, options, additionalParams, abortSignal) {
         if (!this.isInitialized)
             throw new Error("Not initialized, call init() first!");
-        if (options?.paymentHash != null && options.paymentHash.length !== 32)
-            throw new UserError_1.UserError("Invalid payment hash length, must be exactly 32 bytes!");
+        const _options = {
+            paymentHash: (0, Utils_1.parseHashValueExact32Bytes)(options?.paymentHash, "payment hash"),
+            description: options?.description,
+            descriptionHash: (0, Utils_1.parseHashValueExact32Bytes)(options?.descriptionHash, "description hash"),
+            unsafeSkipLnNodeCheck: options?.unsafeSkipLnNodeCheck ?? this._options.unsafeSkipLnNodeCheck
+        };
         const abortController = (0, Utils_1.extendAbortController)(abortSignal);
         const preFetches = {
             pricePrefetchPromise: this.preFetchPrice(amountData, abortController.signal),
@@ -289,7 +292,7 @@ class FromBTCLNWrapper extends IFromBTCLNWrapper_1.IFromBTCLNWrapper {
                 if ((amount * 105n / 100n) > max)
                     throw new UserError_1.UserError("Amount more than LNURL-withdraw maximum");
             }
-            return this.create(recipient, amountData, lps, options, additionalParams, abortSignal, preFetches).map(data => {
+            return this.create(recipient, amountData, lps, _options, additionalParams, abortSignal, preFetches).map(data => {
                 return {
                     quote: data.quote.then(quote => {
                         quote._setLNURLData(withdrawRequest.url, withdrawRequest.k1, withdrawRequest.callback);

package/dist/swaps/escrow_swaps/frombtc/ln_auto/FromBTCLNAutoSwap.d.ts

@@ -245,6 +245,10 @@ export declare class FromBTCLNAutoSwap<T extends ChainType = ChainType> extends
      * @inheritDoc
      */
     isFailed(): boolean;
+    /**
+     * @inheritDoc
+     */
+    isInProgress(): boolean;
     /**
      * @inheritDoc
      */
@@ -309,11 +313,11 @@ export declare class FromBTCLNAutoSwap<T extends ChainType = ChainType> extends
     /**
      * @inheritDoc
      */
-    getInput(): TokenAmount<T["ChainId"], BtcToken<true>>;
+    getInput(): TokenAmount<BtcToken<true>>;
     /**
      * @inheritDoc
      */
-    getInputWithoutFee(): TokenAmount<T["ChainId"], BtcToken<true>>;
+    getInputWithoutFee(): TokenAmount<BtcToken<true>>;
     /**
      * @inheritDoc
      */
@@ -321,11 +325,11 @@ export declare class FromBTCLNAutoSwap<T extends ChainType = ChainType> extends
     /**
      * @inheritDoc
      */
-    getOutput(): TokenAmount<T["ChainId"], SCToken<T["ChainId"]>, true>;
+    getOutput(): TokenAmount<SCToken<T["ChainId"]>, true>;
     /**
      * @inheritDoc
      */
-    getGasDropOutput(): TokenAmount<T["ChainId"], SCToken<T["ChainId"]>, true>;
+    getGasDropOutput(): TokenAmount<SCToken<T["ChainId"]>, true>;
     /**
      * Returns the swap fee charged by the intermediary (LP) on this swap
      *

package/dist/swaps/escrow_swaps/frombtc/ln_auto/FromBTCLNAutoSwap.js

@@ -352,6 +352,15 @@ class FromBTCLNAutoSwap extends IEscrowSwap_1.IEscrowSwap {
     isFailed() {
         return this._state === FromBTCLNAutoSwapState.FAILED || this._state === FromBTCLNAutoSwapState.EXPIRED;
     }
+    /**
+     * @inheritDoc
+     */
+    isInProgress() {
+        return (this._state === FromBTCLNAutoSwapState.PR_CREATED && this.initiated) ||
+            (this._state === FromBTCLNAutoSwapState.QUOTE_SOFT_EXPIRED && this.initiated) ||
+            this._state === FromBTCLNAutoSwapState.PR_PAID ||
+            this._state === FromBTCLNAutoSwapState.CLAIM_COMMITED;
+    }
     /**
      * @inheritDoc
      */

package/dist/swaps/escrow_swaps/frombtc/ln_auto/FromBTCLNAutoWrapper.d.ts

@@ -18,12 +18,53 @@ import { AmountData } from "../../../../types/AmountData";
 import { LNURLWithdrawParamsWithUrl } from "../../../../types/lnurl/LNURLWithdraw";
 import { AllOptional } from "../../../../utils/TypeUtils";
 export type FromBTCLNAutoOptions = {
-    paymentHash?: Buffer;
+    /**
+     * Instead of letting the SDK generate the preimage/paymentHash pair internally you can pass your computed
+     *  paymentHash here, this will create the swap with the provided payment hash. Note that swaps created this way
+     *  won't settle automatically (as the SDK is missing the preimage). Once the HTLC towards the user is created in
+     *  the {@link FromBTCLNAutoSwapState.CLAIM_COMMITED} state, you should pass the secret preimage manually in the
+     *  {@link FromBTCLNAutoSwap.waitTillClaimed}, {@link FromBTCLNAutoSwap.claim} or {@link FromBTCLNAutoSwap.txsClaim}
+     *  functions.
+     *
+     * Accepts both, a {@link Buffer} and a hexadecimal `string`
+     */
+    paymentHash?: Buffer | string;
+    /**
+     * Optional description to use for the swap lightning network invoice, keep the invoice length below 500 characters
+     */
     description?: string;
-    descriptionHash?: Buffer;
+    /**
+     * Optional description hash to use for the lightning network invoice, useful when returning the invoice as part of
+     *  an LNURL-pay service endpoint.
+     *
+     * Accepts both, a {@link Buffer} and a hexadecimal `string`
+     */
+    descriptionHash?: Buffer | string;
+    /**
+     * Optional additional native token to receive as an output of the swap (e.g. STRK on Starknet or cBTC on Citrea).
+     *  When passed as a `bigint` it is specified in base units of the token and in `string` it is the human readable
+     *  decimal format.
+     */
+    gasAmount?: bigint | string;
+    /**
+     * A flag to skip checking whether the lightning network node of the LP has enough channel liquidity to facilitate
+     *  the swap.
+     */
     unsafeSkipLnNodeCheck?: boolean;
-    gasAmount?: bigint;
+    /**
+     * A flag to attach 0 watchtower fee to the swap, this would make the settlement unattractive for the watchtowers
+     *  and therefore automatic settlement for such swaps will not be possible, you will have to settle manually
+     *  with {@link FromBTCLNSwap.claim} or {@link FromBTCLNSwap.txsClaim} functions.
+     */
     unsafeZeroWatchtowerFee?: boolean;
+    /**
+     * A safety factor to use when estimating the watchtower fee to attach to the swap (this has to cover the gas fee
+     *  of watchtowers settling the swap). A higher multiple here would mean that a swap is more attractive for
+     *  watchtowers to settle automatically.
+     *
+     * Uses a `1.25` multiple by default (i.e. the current network fee is multiplied by 1.25 and then used to estimate
+     *  the settlement gas fee cost)
+     */
     feeSafetyFactor?: number;
 };
 export type FromBTCLNAutoWrapperOptions = ISwapWrapperOptions & {

package/dist/swaps/escrow_swaps/frombtc/ln_auto/FromBTCLNAutoWrapper.js

@@ -221,22 +221,18 @@ class FromBTCLNAutoWrapper extends IFromBTCLNWrapper_1.IFromBTCLNWrapper {
         if (!this.isInitialized)
             throw new Error("Not initialized, call init() first!");
         const _options = {
-            paymentHash: options?.paymentHash,
+            paymentHash: (0, Utils_1.parseHashValueExact32Bytes)(options?.paymentHash, "payment hash"),
             unsafeSkipLnNodeCheck: options?.unsafeSkipLnNodeCheck ?? this._options.unsafeSkipLnNodeCheck,
-            gasAmount: options?.gasAmount ?? 0n,
+            gasAmount: this.parseGasAmount(options?.gasAmount),
             feeSafetyFactor: options?.feeSafetyFactor ?? 1.25,
             unsafeZeroWatchtowerFee: options?.unsafeZeroWatchtowerFee ?? false,
             description: options?.description,
-            descriptionHash: options?.descriptionHash
+            descriptionHash: (0, Utils_1.parseHashValueExact32Bytes)(options?.descriptionHash, "description hash")
         };
-        if (_options.paymentHash != null && _options.paymentHash.length !== 32)
-            throw new UserError_1.UserError("Invalid payment hash length, must be exactly 32 bytes!");
-        if (_options.descriptionHash != null && _options.descriptionHash.length !== 32)
-            throw new UserError_1.UserError("Invalid description hash length");
+        if (amountData.token === this._chain.getNativeCurrencyAddress() && _options.gasAmount !== 0n)
+            throw new UserError_1.UserError("Cannot specify `gasAmount` for swaps to a native token!");
         if (_options.description != null && buffer_1.Buffer.byteLength(_options.description, "utf8") > 500)
             throw new UserError_1.UserError("Invalid description length");
-        if (preFetches == null)
-            preFetches = {};
         let secret;
         let paymentHash;
         if (_options?.paymentHash != null) {
@@ -248,6 +244,7 @@ class FromBTCLNAutoWrapper extends IFromBTCLNWrapper_1.IFromBTCLNWrapper {
         const claimHash = this._contract.getHashForHtlc(paymentHash);
         const nativeTokenAddress = this._chain.getNativeCurrencyAddress();
         const _abortController = (0, Utils_1.extendAbortController)(abortSignal);
+        preFetches ??= {};
         const _preFetches = {
             pricePrefetchPromise: preFetches?.pricePrefetchPromise ?? this.preFetchPrice(amountData, _abortController.signal),
             usdPricePrefetchPromise: preFetches?.usdPricePrefetchPromise ?? this.preFetchUsdPrice(_abortController.signal),
@@ -348,16 +345,14 @@ class FromBTCLNAutoWrapper extends IFromBTCLNWrapper_1.IFromBTCLNWrapper {
         if (!this.isInitialized)
             throw new Error("Not initialized, call init() first!");
         const _options = {
-            paymentHash: options?.paymentHash,
+            paymentHash: (0, Utils_1.parseHashValueExact32Bytes)(options?.paymentHash, "payment hash"),
             unsafeSkipLnNodeCheck: options?.unsafeSkipLnNodeCheck ?? this._options.unsafeSkipLnNodeCheck,
-            gasAmount: options?.gasAmount ?? 0n,
+            gasAmount: this.parseGasAmount(options?.gasAmount),
             feeSafetyFactor: options?.feeSafetyFactor ?? 1.25,
             unsafeZeroWatchtowerFee: options?.unsafeZeroWatchtowerFee ?? false,
             description: options?.description,
-            descriptionHash: options?.descriptionHash
+            descriptionHash: (0, Utils_1.parseHashValueExact32Bytes)(options?.descriptionHash, "description hash")
         };
-        if (_options.paymentHash != null && _options.paymentHash.length !== 32)
-            throw new UserError_1.UserError("Invalid payment hash length, must be exactly 32 bytes!");
         const abortController = (0, Utils_1.extendAbortController)(abortSignal);
         const preFetches = {
             pricePrefetchPromise: this.preFetchPrice(amountData, abortController.signal),

package/dist/swaps/escrow_swaps/frombtc/onchain/FromBTCSwap.d.ts

@@ -175,6 +175,10 @@ export declare class FromBTCSwap<T extends ChainType = ChainType> extends IFromB
      * @inheritDoc
      */
     isFailed(): boolean;
+    /**
+     * @inheritDoc
+     */
+    isInProgress(): boolean;
     /**
      * @inheritDoc
      */
@@ -195,13 +199,13 @@ export declare class FromBTCSwap<T extends ChainType = ChainType> extends IFromB
     /**
      * @inheritDoc
      */
-    getInput(): TokenAmount<T["ChainId"], BtcToken<false>>;
+    getInput(): TokenAmount<BtcToken<false>>;
     /**
      * Returns claimer bounty, acting as a reward for watchtowers to claim the swap automatically,
      *  this amount is pre-funded by the user on the destination chain when the swap escrow
      *  is initiated. For total pre-funded deposit amount see {@link getTotalDeposit}.
      */
-    getClaimerBounty(): TokenAmount<T["ChainId"], SCToken<T["ChainId"]>, true>;
+    getClaimerBounty(): TokenAmount<SCToken<T["ChainId"]>, true>;
     /**
      * If the required number of confirmations is not known, this function tries to infer it by looping through
      *  possible confirmation targets and comparing the claim hashes
@@ -277,7 +281,7 @@ export declare class FromBTCSwap<T extends ChainType = ChainType> extends IFromB
     /**
      * @inheritDoc
      */
-    estimateBitcoinFee(_bitcoinWallet: IBitcoinWallet | MinimalBitcoinWalletInterface, feeRate?: number): Promise<TokenAmount<any, BtcToken<false>, true> | null>;
+    estimateBitcoinFee(_bitcoinWallet: IBitcoinWallet | MinimalBitcoinWalletInterface, feeRate?: number): Promise<TokenAmount<BtcToken<false>, true> | null>;
     /**
      * @inheritDoc
      */

package/dist/swaps/escrow_swaps/frombtc/onchain/FromBTCSwap.js

@@ -237,6 +237,13 @@ class FromBTCSwap extends IFromBTCSelfInitSwap_1.IFromBTCSelfInitSwap {
     isFailed() {
         return this._state === FromBTCSwapState.FAILED || this._state === FromBTCSwapState.EXPIRED;
     }
+    /**
+     * @inheritDoc
+     */
+    isInProgress() {
+        return this._state === FromBTCSwapState.CLAIM_COMMITED ||
+            this._state === FromBTCSwapState.BTC_TX_CONFIRMED;
+    }
     /**
      * @inheritDoc
      */