@atomiqlabs/sdk 8.3.6 → 8.4.4

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

@@ -66,6 +66,16 @@ var FromBTCLNSwapState;
      */
     FromBTCLNSwapState[FromBTCLNSwapState["CLAIM_CLAIMED"] = 3] = "CLAIM_CLAIMED";
 })(FromBTCLNSwapState = exports.FromBTCLNSwapState || (exports.FromBTCLNSwapState = {}));
+const FromBTCLNSwapStateDescription = {
+    [FromBTCLNSwapState.FAILED]: "Swap has failed as the user didn't settle the HTLC on the destination before expiration",
+    [FromBTCLNSwapState.QUOTE_EXPIRED]: "Swap has expired for good and there is no way how it can be executed anymore",
+    [FromBTCLNSwapState.QUOTE_SOFT_EXPIRED]: "Swap is expired, though there is still a chance that it will be processed",
+    [FromBTCLNSwapState.EXPIRED]: "Swap HTLC on the destination chain has expired, it is not safe anymore to settle (claim) the swap on the destination smart chain.",
+    [FromBTCLNSwapState.PR_CREATED]: "Swap quote was created, pay the bolt11 lightning network invoice to initiate the swap, then use the wait till the lightning network payment is received by the intermediary (LP)",
+    [FromBTCLNSwapState.PR_PAID]: "Lightning network payment has been received by the intermediary (LP), the user can now settle the swap on the destination smart chain side.",
+    [FromBTCLNSwapState.CLAIM_COMMITED]: "Swap escrow HTLC has been created on the destination chain. Continue by claiming it.",
+    [FromBTCLNSwapState.CLAIM_CLAIMED]: "Swap successfully settled and funds received on the destination chain"
+};
 function isFromBTCLNSwapInit(obj) {
     return (obj.pr == null || typeof obj.pr === "string") &&
         (obj.secret == null || typeof obj.secret === "string") &&
@@ -97,6 +107,14 @@ class FromBTCLNSwap extends IFromBTCSelfInitSwap_1.IFromBTCSelfInitSwap {
             initOrObject.url += "/frombtcln";
         super(wrapper, initOrObject);
         this.TYPE = SwapType_1.SwapType.FROM_BTCLN;
+        /**
+         * @internal
+         */
+        this.swapStateName = (state) => FromBTCLNSwapState[state];
+        /**
+         * @internal
+         */
+        this.swapStateDescription = FromBTCLNSwapStateDescription;
         /**
          * @internal
          */
@@ -303,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
      */
@@ -384,6 +411,24 @@ class FromBTCLNSwap extends IFromBTCSelfInitSwap_1.IFromBTCSelfInitSwap {
         const claimHash = this.wrapper._contract.getHashForHtlc(paymentHash).toString("hex");
         return this.getSwapData().getClaimHash() === claimHash;
     }
+    /**
+     * Sets the secret preimage for the swap, in case it is not known already
+     *
+     * @param secret Secret preimage that matches the expected payment hash
+     *
+     * @throws {Error} If an invalid secret preimage is provided
+     */
+    setSecretPreimage(secret) {
+        if (!this.isValidSecretPreimage(secret))
+            throw new Error("Invalid secret preimage provided, hash doesn't match!");
+        this.secret = secret;
+    }
+    /**
+     * Returns whether the secret preimage for this swap is known
+     */
+    hasSecretPreimage() {
+        return this.secret != null;
+    }
     //////////////////////////////
     //// Execution
     /**
@@ -396,10 +441,10 @@ class FromBTCLNSwap extends IFromBTCSelfInitSwap_1.IFromBTCSelfInitSwap {
      *  link, wallet is not required and the LN invoice can be paid externally as well (just pass null or undefined here)
      * @param callbacks Callbacks to track the progress of the swap
      * @param options Optional options for the swap like feeRate, AbortSignal, and timeouts/intervals
-     * @param secret A swap secret to use for the claim transaction, generally only needed if the swap
+     * @param options.secret A swap secret to use for the claim transaction, generally only needed if the swap
      *  was recovered from on-chain data, or the pre-image was generated outside the SDK
      */
-    async execute(dstSigner, walletOrLnurlWithdraw, callbacks, options, secret) {
+    async execute(dstSigner, walletOrLnurlWithdraw, callbacks, options) {
         if (this._state === FromBTCLNSwapState.FAILED)
             throw new Error("Swap failed!");
         if (this._state === FromBTCLNSwapState.EXPIRED)
@@ -431,7 +476,7 @@ class FromBTCLNSwap extends IFromBTCSelfInitSwap_1.IFromBTCSelfInitSwap {
         }
         if (this._state === FromBTCLNSwapState.PR_PAID || this._state === FromBTCLNSwapState.CLAIM_COMMITED) {
             if (this.canCommitAndClaimInOneShot()) {
-                await this.commitAndClaim(dstSigner, options?.abortSignal, undefined, callbacks?.onDestinationCommitSent, callbacks?.onDestinationClaimSent, secret);
+                await this.commitAndClaim(dstSigner, options?.abortSignal, undefined, callbacks?.onDestinationCommitSent, callbacks?.onDestinationClaimSent, options?.secret);
             }
             else {
                 if (this._state === FromBTCLNSwapState.PR_PAID) {
@@ -440,7 +485,7 @@ class FromBTCLNSwap extends IFromBTCSelfInitSwap_1.IFromBTCSelfInitSwap {
                         await (0, TimeoutUtils_1.timeoutPromise)(options.delayBetweenCommitAndClaimSeconds * 1000, options?.abortSignal);
                 }
                 if (this._state === FromBTCLNSwapState.CLAIM_COMMITED) {
-                    await this.claim(dstSigner, options?.abortSignal, callbacks?.onDestinationClaimSent, secret);
+                    await this.claim(dstSigner, options?.abortSignal, callbacks?.onDestinationClaimSent, options?.secret);
                 }
             }
         }
@@ -449,6 +494,7 @@ class FromBTCLNSwap extends IFromBTCSelfInitSwap_1.IFromBTCSelfInitSwap {
             if (callbacks?.onSwapSettled != null)
                 callbacks.onSwapSettled(this.getOutputTxId());
         }
+        return true;
     }
     /**
      * @inheritDoc
@@ -457,10 +503,10 @@ class FromBTCLNSwap extends IFromBTCSelfInitSwap_1.IFromBTCSelfInitSwap {
      * @param options.skipChecks Skip checks like making sure init signature is still valid and swap
      *  wasn't commited yet (this is handled on swap creation, if you commit right after quoting, you
      *  can use `skipChecks=true`)
-     * @param secret A swap secret to use for the claim transaction, generally only needed if the swap
+     * @param options.secret A swap secret to use for the claim transaction, generally only needed if the swap
      *  was recovered from on-chain data, or the pre-image was generated outside the SDK
      */
-    async txsExecute(options, secret) {
+    async txsExecute(options) {
         if (this._state === FromBTCLNSwapState.PR_CREATED) {
             if (!await this._verifyQuoteValid())
                 throw new Error("Quote already expired or close to expiry!");
@@ -483,7 +529,7 @@ class FromBTCLNSwap extends IFromBTCSelfInitSwap_1.IFromBTCSelfInitSwap {
             if (!await this._verifyQuoteValid())
                 throw new Error("Quote already expired or close to expiry!");
             const txsCommit = await this.txsCommit(options?.skipChecks);
-            const txsClaim = await this._txsClaim(undefined, secret);
+            const txsClaim = await this._txsClaim(undefined, options?.secret);
             return [
                 {
                     name: "Commit",
@@ -500,7 +546,7 @@ class FromBTCLNSwap extends IFromBTCSelfInitSwap_1.IFromBTCSelfInitSwap {
             ];
         }
         if (this._state === FromBTCLNSwapState.CLAIM_COMMITED) {
-            const txsClaim = await this.txsClaim(undefined, secret);
+            const txsClaim = await this.txsClaim(undefined, options?.secret);
             return [
                 {
                     name: "Claim",
@@ -512,6 +558,24 @@ class FromBTCLNSwap extends IFromBTCSelfInitSwap_1.IFromBTCSelfInitSwap {
         }
         throw new Error("Invalid swap state to obtain execution txns, required PR_CREATED, PR_PAID or CLAIM_COMMITED");
     }
+    /**
+     * @inheritDoc
+     *
+     * @param options
+     * @param options.skipChecks Skip checks like making sure init signature is still valid and swap
+     *  wasn't commited yet (this is handled on swap creation, if you commit right after quoting, you
+     *  can use `skipChecks=true`)
+     * @param options.secret A swap secret to use for the claim transaction, generally only needed if the swap
+     *  was recovered from on-chain data, or the pre-image was generated outside the SDK
+     */
+    async getCurrentActions(options) {
+        try {
+            return await this.txsExecute(options);
+        }
+        catch (e) {
+            return [];
+        }
+    }
     //////////////////////////////
     //// Payment
     /**

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

@@ -18,6 +18,8 @@ import { AmountData } from "../../../../types/AmountData";
 import { LNURLWithdrawParamsWithUrl } from "../../../../types/lnurl/LNURLWithdraw";
 import { AllOptional } from "../../../../utils/TypeUtils";
 export type FromBTCLNOptions = {
+    paymentHash?: Buffer;
+    description?: string;
     descriptionHash?: Buffer;
     unsafeSkipLnNodeCheck?: boolean;
 };
@@ -130,10 +132,11 @@ export declare class FromBTCLNWrapper<T extends ChainType> extends IFromBTCLNWra
      * @param lnurl LNURL-withdraw link to pull the funds from
      * @param amountData Amount, token and exact input/output data for to swap
      * @param lps An array of intermediaries (LPs) to get the quotes from
+     * @param options Optional additional quote options
      * @param additionalParams Optional additional parameters sent to the LP when creating the swap
      * @param abortSignal Abort signal
      */
-    createViaLNURL(recipient: string, lnurl: string | LNURLWithdrawParamsWithUrl, amountData: AmountData, lps: Intermediary[], additionalParams?: Record<string, any>, abortSignal?: AbortSignal): Promise<{
+    createViaLNURL(recipient: string, lnurl: string | LNURLWithdrawParamsWithUrl, amountData: AmountData, lps: Intermediary[], options?: FromBTCLNOptions, additionalParams?: Record<string, any>, abortSignal?: AbortSignal): Promise<{
         quote: Promise<FromBTCLNSwap<T>>;
         intermediary: Intermediary;
     }[]>;

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

@@ -121,6 +121,8 @@ class FromBTCLNWrapper extends IFromBTCLNWrapper_1.IFromBTCLNWrapper {
             throw new IntermediaryError_1.IntermediaryError("Invalid intermediary address/pubkey");
         if (options.descriptionHash != null && decodedPr.tagsObject.purpose_commit_hash !== options.descriptionHash.toString("hex"))
             throw new IntermediaryError_1.IntermediaryError("Invalid pr returned - description hash");
+        if (options.description != null && decodedPr.tagsObject.description !== options.description)
+            throw new IntermediaryError_1.IntermediaryError("Invalid pr returned - description");
         if (decodedPr.tagsObject.payment_hash == null ||
             !buffer_1.Buffer.from(decodedPr.tagsObject.payment_hash, "hex").equals(paymentHash))
             throw new IntermediaryError_1.IntermediaryError("Invalid pr returned - payment hash");
@@ -151,12 +153,25 @@ class FromBTCLNWrapper extends IFromBTCLNWrapper_1.IFromBTCLNWrapper {
      * @param preFetches Optional pre-fetches for speeding up the quoting process (mainly used internally)
      */
     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");
-        const { secret, paymentHash } = this.getSecretAndHash();
+        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;
+        }
+        else {
+            ({ secret, paymentHash } = this.getSecretAndHash());
+        }
         const claimHash = this._contract.getHashForHtlc(paymentHash);
         const nativeTokenAddress = this._chain.getNativeCurrencyAddress();
         const _abortController = (0, Utils_1.extendAbortController)(abortSignal);
@@ -179,6 +194,7 @@ class FromBTCLNWrapper extends IFromBTCLNWrapper_1.IFromBTCLNWrapper {
                             amount: amountData.amount,
                             claimer: recipient,
                             token: amountData.token.toString(),
+                            description: options?.description,
                             descriptionHash: options?.descriptionHash,
                             exactOut: !amountData.exactIn,
                             feeRate: (0, Utils_1.throwIfUndefined)(_preFetches.feeRatePromise),
@@ -211,7 +227,7 @@ class FromBTCLNWrapper extends IFromBTCLNWrapper_1.IFromBTCLNWrapper {
                             feeRate: (await _preFetches.feeRatePromise),
                             initialSwapData: await this._contract.createSwapData(base_1.ChainSwapType.HTLC, lp.getAddress(this.chainIdentifier), recipient, amountData.token, resp.total, claimHash.toString("hex"), this.getRandomSequence(), BigInt(Math.floor(Date.now() / 1000)), false, true, resp.securityDeposit, 0n, nativeTokenAddress),
                             pr: resp.pr,
-                            secret: secret.toString("hex"),
+                            secret: secret?.toString("hex"),
                             exactIn: amountData.exactIn ?? true
                         });
                         await quote._save();
@@ -236,12 +252,15 @@ class FromBTCLNWrapper extends IFromBTCLNWrapper_1.IFromBTCLNWrapper {
      * @param lnurl LNURL-withdraw link to pull the funds from
      * @param amountData Amount, token and exact input/output data for to swap
      * @param lps An array of intermediaries (LPs) to get the quotes from
+     * @param options Optional additional quote options
      * @param additionalParams Optional additional parameters sent to the LP when creating the swap
      * @param abortSignal Abort signal
      */
-    async createViaLNURL(recipient, lnurl, amountData, lps, additionalParams, abortSignal) {
+    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 abortController = (0, Utils_1.extendAbortController)(abortSignal);
         const preFetches = {
             pricePrefetchPromise: this.preFetchPrice(amountData, abortController.signal),
@@ -270,7 +289,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, undefined, 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

@@ -16,18 +16,52 @@ import { BtcToken, SCToken } from "../../../../types/Token";
 import { LoggerType } from "../../../../utils/Logger";
 import { LNURLWithdraw } from "../../../../types/lnurl/LNURLWithdraw";
 import { PriceInfoType } from "../../../../types/PriceInfoType";
+import { SwapExecutionAction } from "../../../../types/SwapExecutionAction";
 /**
  * State enum for FromBTCLNAuto swaps
  * @category Swaps/Lightning → Smart chain
  */
 export declare enum FromBTCLNAutoSwapState {
+    /**
+     * Swap has failed as the user didn't settle the HTLC on the destination before expiration
+     */
     FAILED = -4,
+    /**
+     * Swap has expired for good and there is no way how it can be executed anymore
+     */
     QUOTE_EXPIRED = -3,
+    /**
+     * A swap is almost expired, and it should be presented to the user as expired, though
+     *  there is still a chance that it will be processed
+     */
     QUOTE_SOFT_EXPIRED = -2,
+    /**
+     * Swap HTLC on the destination chain has expired, it is not safe anymore to settle (claim) the
+     *  swap on the destination smart chain.
+     */
     EXPIRED = -1,
+    /**
+     * Swap quote was created, use {@link FromBTCLNAutoSwap.getAddress} or {@link FromBTCLNAutoSwap.getHyperlink}
+     *  to get the bolt11 lightning network invoice to pay to initiate the swap, then use the
+     *  {@link FromBTCLNAutoSwap.waitForPayment} to wait till the lightning network payment is received
+     *  by the intermediary (LP) and the destination HTLC escrow is created
+     */
     PR_CREATED = 0,
+    /**
+     * Lightning network payment has been received by the intermediary (LP), but the destination chain
+     *  HTLC escrow hasn't been created yet. Use {@link FromBTCLNAutoSwap.waitForPayment} to continue waiting
+     *  till the destination HTLC escrow is created.
+     */
     PR_PAID = 1,
+    /**
+     * Swap escrow HTLC has been created on the destination chain, wait for automatic settlement by the watchtowers
+     *  using the {@link FromBTCLNAutoSwap.waitTillClaimed} function or settle manually using the
+     *  {@link FromBTCLNAutoSwap.claim} or {@link FromBTCLNAutoSwap.txsClaim} function.
+     */
     CLAIM_COMMITED = 2,
+    /**
+     * Swap successfully settled and funds received on the destination chain
+     */
     CLAIM_CLAIMED = 3
 }
 export type FromBTCLNAutoSwapInit<T extends SwapData> = IEscrowSwapInit<T> & {
@@ -54,6 +88,23 @@ export declare function isFromBTCLNAutoSwapInit<T extends SwapData>(obj: any): o
  */
 export declare class FromBTCLNAutoSwap<T extends ChainType = ChainType> extends IEscrowSwap<T, FromBTCLNAutoDefinition<T>> implements IAddressSwap, ISwapWithGasDrop<T>, IClaimableSwap<T, FromBTCLNAutoDefinition<T>, FromBTCLNAutoSwapState> {
     protected readonly TYPE: SwapType.FROM_BTCLN_AUTO;
+    /**
+     * @internal
+     */
+    protected readonly swapStateName: (state: number) => string;
+    /**
+     * @internal
+     */
+    protected readonly swapStateDescription: {
+        [-4]: string;
+        [-3]: string;
+        [-2]: string;
+        [-1]: string;
+        0: string;
+        1: string;
+        2: string;
+        3: string;
+    };
     /**
      * @internal
      */
@@ -62,6 +113,11 @@ export declare class FromBTCLNAutoSwap<T extends ChainType = ChainType> extends
      * @internal
      */
     protected readonly inputToken: BtcToken<true>;
+    /**
+     * Timestamp at which the HTLC was commited on the smart chain side
+     * @internal
+     */
+    _commitedAt?: number;
     private readonly lnurlFailSignal;
     private readonly usesClaimHashAsId;
     private readonly initialSwapData;
@@ -189,6 +245,10 @@ export declare class FromBTCLNAutoSwap<T extends ChainType = ChainType> extends
      * @inheritDoc
      */
     isFailed(): boolean;
+    /**
+     * @inheritDoc
+     */
+    isInProgress(): boolean;
     /**
      * @inheritDoc
      */
@@ -301,14 +361,26 @@ export declare class FromBTCLNAutoSwap<T extends ChainType = ChainType> extends
         }
     ];
     private isValidSecretPreimage;
+    /**
+     * Sets the secret preimage for the swap, in case it is not known already
+     *
+     * @param secret Secret preimage that matches the expected payment hash
+     *
+     * @throws {Error} If an invalid secret preimage is provided
+     */
+    setSecretPreimage(secret: string): void;
+    /**
+     * Returns whether the secret preimage for this swap is known
+     */
+    hasSecretPreimage(): boolean;
     /**
      * Executes the swap with the provided bitcoin lightning network wallet or LNURL
      *
      * @param walletOrLnurlWithdraw Bitcoin lightning wallet to use to pay the lightning network invoice, or an LNURL-withdraw
      *  link, wallet is not required and the LN invoice can be paid externally as well (just pass null or undefined here)
      * @param callbacks Callbacks to track the progress of the swap
-     * @param options Optional options for the swap like feeRate, AbortSignal, and timeouts/intervals
-     * @param secret A swap secret to broadcast to watchtowers, generally only needed if the swap
+     * @param options Optional options for the swap like AbortSignal, and timeouts/intervals
+     * @param options.secret A swap secret to broadcast to watchtowers, generally only needed if the swap
      *  was recovered from on-chain data, or the pre-image was generated outside the SDK
      *
      * @returns {boolean} Whether a swap was settled automatically by swap watchtowers or requires manual claim by the
@@ -321,7 +393,8 @@ export declare class FromBTCLNAutoSwap<T extends ChainType = ChainType> extends
         abortSignal?: AbortSignal;
         lightningTxCheckIntervalSeconds?: number;
         maxWaitTillAutomaticSettlementSeconds?: number;
-    }, secret?: string): Promise<boolean>;
+        secret?: string;
+    }): Promise<boolean>;
     /**
      * @inheritDoc
      */
@@ -335,6 +408,19 @@ export declare class FromBTCLNAutoSwap<T extends ChainType = ChainType> extends
             hyperlink: string;
         }[];
     }[]>;
+    /**
+     *
+     * @param options.manualSettlementSmartChainSigner Optional smart chain signer to create a manual claim (settlement) transaction
+     * @param options.maxWaitTillAutomaticSettlementSeconds Maximum time to wait for an automatic settlement after
+     *  the bitcoin transaction is confirmed (defaults to 60 seconds)
+     * @param options.secret A swap secret to broadcast to watchtowers, generally only needed if the swap
+     *  was recovered from on-chain data, or the pre-image was generated outside the SDK
+     */
+    getCurrentActions(options?: {
+        manualSettlementSmartChainSigner?: string | T["Signer"] | T["NativeSigner"];
+        maxWaitTillAutomaticSettlementSeconds?: number;
+        secret?: string;
+    }): Promise<SwapExecutionAction<T>[]>;
     /**
      * Checks whether the LP received the LN payment
      *

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

@@ -26,15 +26,58 @@ const sha2_1 = require("@noble/hashes/sha2");
  */
 var FromBTCLNAutoSwapState;
 (function (FromBTCLNAutoSwapState) {
+    /**
+     * Swap has failed as the user didn't settle the HTLC on the destination before expiration
+     */
     FromBTCLNAutoSwapState[FromBTCLNAutoSwapState["FAILED"] = -4] = "FAILED";
+    /**
+     * Swap has expired for good and there is no way how it can be executed anymore
+     */
     FromBTCLNAutoSwapState[FromBTCLNAutoSwapState["QUOTE_EXPIRED"] = -3] = "QUOTE_EXPIRED";
+    /**
+     * A swap is almost expired, and it should be presented to the user as expired, though
+     *  there is still a chance that it will be processed
+     */
     FromBTCLNAutoSwapState[FromBTCLNAutoSwapState["QUOTE_SOFT_EXPIRED"] = -2] = "QUOTE_SOFT_EXPIRED";
+    /**
+     * Swap HTLC on the destination chain has expired, it is not safe anymore to settle (claim) the
+     *  swap on the destination smart chain.
+     */
     FromBTCLNAutoSwapState[FromBTCLNAutoSwapState["EXPIRED"] = -1] = "EXPIRED";
+    /**
+     * Swap quote was created, use {@link FromBTCLNAutoSwap.getAddress} or {@link FromBTCLNAutoSwap.getHyperlink}
+     *  to get the bolt11 lightning network invoice to pay to initiate the swap, then use the
+     *  {@link FromBTCLNAutoSwap.waitForPayment} to wait till the lightning network payment is received
+     *  by the intermediary (LP) and the destination HTLC escrow is created
+     */
     FromBTCLNAutoSwapState[FromBTCLNAutoSwapState["PR_CREATED"] = 0] = "PR_CREATED";
+    /**
+     * Lightning network payment has been received by the intermediary (LP), but the destination chain
+     *  HTLC escrow hasn't been created yet. Use {@link FromBTCLNAutoSwap.waitForPayment} to continue waiting
+     *  till the destination HTLC escrow is created.
+     */
     FromBTCLNAutoSwapState[FromBTCLNAutoSwapState["PR_PAID"] = 1] = "PR_PAID";
+    /**
+     * Swap escrow HTLC has been created on the destination chain, wait for automatic settlement by the watchtowers
+     *  using the {@link FromBTCLNAutoSwap.waitTillClaimed} function or settle manually using the
+     *  {@link FromBTCLNAutoSwap.claim} or {@link FromBTCLNAutoSwap.txsClaim} function.
+     */
     FromBTCLNAutoSwapState[FromBTCLNAutoSwapState["CLAIM_COMMITED"] = 2] = "CLAIM_COMMITED";
+    /**
+     * Swap successfully settled and funds received on the destination chain
+     */
     FromBTCLNAutoSwapState[FromBTCLNAutoSwapState["CLAIM_CLAIMED"] = 3] = "CLAIM_CLAIMED";
 })(FromBTCLNAutoSwapState = exports.FromBTCLNAutoSwapState || (exports.FromBTCLNAutoSwapState = {}));
+const FromBTCLNAutoSwapStateDescription = {
+    [FromBTCLNAutoSwapState.FAILED]: "Swap has failed as the user didn't settle the HTLC on the destination before expiration",
+    [FromBTCLNAutoSwapState.QUOTE_EXPIRED]: "Swap has expired for good and there is no way how it can be executed anymore",
+    [FromBTCLNAutoSwapState.QUOTE_SOFT_EXPIRED]: "A swap is expired, though there is still a chance that it will be processed",
+    [FromBTCLNAutoSwapState.EXPIRED]: "Swap HTLC on the destination chain has expired, it is not safe anymore to settle (claim) the swap on the destination smart chain.",
+    [FromBTCLNAutoSwapState.PR_CREATED]: "Swap quote was created, pay the bolt11 lightning network invoice to initiate the swap, then wait till the lightning network payment is received by the intermediary (LP) and the destination HTLC escrow is created",
+    [FromBTCLNAutoSwapState.PR_PAID]: "Lightning network payment has been received by the intermediary (LP), but the destination chain HTLC escrow hasn't been created yet. Continue waiting till the destination HTLC escrow is created.",
+    [FromBTCLNAutoSwapState.CLAIM_COMMITED]: "Swap escrow HTLC has been created on the destination chain, wait for automatic settlement by the watchtowers or settle manually.",
+    [FromBTCLNAutoSwapState.CLAIM_CLAIMED]: "Swap successfully settled and funds received on the destination chain"
+};
 function isFromBTCLNAutoSwapInit(obj) {
     return (obj.pr == null || typeof obj.pr === "string") &&
         (obj.secret == null || typeof obj.secret === "string") &&
@@ -73,6 +116,14 @@ class FromBTCLNAutoSwap extends IEscrowSwap_1.IEscrowSwap {
             initOrObject.url += "/frombtcln_auto";
         super(wrapper, initOrObject);
         this.TYPE = SwapType_1.SwapType.FROM_BTCLN_AUTO;
+        /**
+         * @internal
+         */
+        this.swapStateName = (state) => FromBTCLNAutoSwapState[state];
+        /**
+         * @internal
+         */
+        this.swapStateDescription = FromBTCLNAutoSwapStateDescription;
         /**
          * @internal
          */
@@ -111,6 +162,7 @@ class FromBTCLNAutoSwap extends IEscrowSwap_1.IEscrowSwap {
             this.gasPricingInfo = (0, PriceInfoType_1.deserializePriceInfoType)(initOrObject.gasPricingInfo);
             this._commitTxId = initOrObject.commitTxId;
             this._claimTxId = initOrObject.claimTxId;
+            this._commitedAt = initOrObject.commitedAt;
             this.lnurl = initOrObject.lnurl;
             this.lnurlK1 = initOrObject.lnurlK1;
             this.lnurlCallback = initOrObject.lnurlCallback;
@@ -300,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
      */
@@ -518,6 +579,24 @@ class FromBTCLNAutoSwap extends IEscrowSwap_1.IEscrowSwap {
         const claimHash = this.wrapper._contract.getHashForHtlc(paymentHash).toString("hex");
         return this.getSwapData().getClaimHash() === claimHash;
     }
+    /**
+     * Sets the secret preimage for the swap, in case it is not known already
+     *
+     * @param secret Secret preimage that matches the expected payment hash
+     *
+     * @throws {Error} If an invalid secret preimage is provided
+     */
+    setSecretPreimage(secret) {
+        if (!this.isValidSecretPreimage(secret))
+            throw new Error("Invalid secret preimage provided, hash doesn't match!");
+        this.secret = secret;
+    }
+    /**
+     * Returns whether the secret preimage for this swap is known
+     */
+    hasSecretPreimage() {
+        return this.secret != null;
+    }
     //////////////////////////////
     //// Execution
     /**
@@ -526,14 +605,14 @@ class FromBTCLNAutoSwap extends IEscrowSwap_1.IEscrowSwap {
      * @param walletOrLnurlWithdraw Bitcoin lightning wallet to use to pay the lightning network invoice, or an LNURL-withdraw
      *  link, wallet is not required and the LN invoice can be paid externally as well (just pass null or undefined here)
      * @param callbacks Callbacks to track the progress of the swap
-     * @param options Optional options for the swap like feeRate, AbortSignal, and timeouts/intervals
-     * @param secret A swap secret to broadcast to watchtowers, generally only needed if the swap
+     * @param options Optional options for the swap like AbortSignal, and timeouts/intervals
+     * @param options.secret A swap secret to broadcast to watchtowers, generally only needed if the swap
      *  was recovered from on-chain data, or the pre-image was generated outside the SDK
      *
      * @returns {boolean} Whether a swap was settled automatically by swap watchtowers or requires manual claim by the
      *  user, in case `false` is returned the user should call `swap.claim()` to settle the swap on the destination manually
      */
-    async execute(walletOrLnurlWithdraw, callbacks, options, secret) {
+    async execute(walletOrLnurlWithdraw, callbacks, options) {
         if (this._state === FromBTCLNAutoSwapState.FAILED)
             throw new Error("Swap failed!");
         if (this._state === FromBTCLNAutoSwapState.EXPIRED)
@@ -568,9 +647,9 @@ class FromBTCLNAutoSwap extends IEscrowSwap_1.IEscrowSwap {
         if (this._state === FromBTCLNAutoSwapState.CLAIM_CLAIMED)
             return true;
         if (this._state === FromBTCLNAutoSwapState.CLAIM_COMMITED) {
-            if (this.secret == null && secret == null)
+            if (this.secret == null && options?.secret == null)
                 throw new Error("Tried to wait till settlement, but no secret pre-image is known, please pass the secret pre-image as an argument!");
-            const success = await this.waitTillClaimed(options?.maxWaitTillAutomaticSettlementSeconds ?? 60, options?.abortSignal, secret);
+            const success = await this.waitTillClaimed(options?.maxWaitTillAutomaticSettlementSeconds ?? 60, options?.abortSignal, options?.secret);
             if (success && callbacks?.onSwapSettled != null)
                 callbacks.onSwapSettled(this.getOutputTxId());
             return success;
@@ -601,6 +680,37 @@ class FromBTCLNAutoSwap extends IEscrowSwap_1.IEscrowSwap {
         }
         throw new Error("Invalid swap state to obtain execution txns, required PR_CREATED");
     }
+    /**
+     *
+     * @param options.manualSettlementSmartChainSigner Optional smart chain signer to create a manual claim (settlement) transaction
+     * @param options.maxWaitTillAutomaticSettlementSeconds Maximum time to wait for an automatic settlement after
+     *  the bitcoin transaction is confirmed (defaults to 60 seconds)
+     * @param options.secret A swap secret to broadcast to watchtowers, generally only needed if the swap
+     *  was recovered from on-chain data, or the pre-image was generated outside the SDK
+     */
+    async getCurrentActions(options) {
+        if (options?.secret != null)
+            this.setSecretPreimage(options.secret);
+        if (this._state === FromBTCLNAutoSwapState.PR_CREATED) {
+            try {
+                return await this.txsExecute();
+            }
+            catch (e) { }
+        }
+        if (this.isClaimable()) {
+            if (this._commitedAt == null ||
+                options?.maxWaitTillAutomaticSettlementSeconds === 0 ||
+                (Date.now() - this._commitedAt) > (options?.maxWaitTillAutomaticSettlementSeconds ?? 60) * 1000) {
+                return [{
+                        name: "Claim",
+                        description: "Manually settle (claim) the swap on the destination smart chain",
+                        chain: this.chainIdentifier,
+                        txs: await this.txsClaim(options?.manualSettlementSmartChainSigner)
+                    }];
+            }
+        }
+        return [];
+    }
     //////////////////////////////
     //// Payment
     /**
@@ -828,6 +938,7 @@ class FromBTCLNAutoSwap extends IEscrowSwap_1.IEscrowSwap {
             return;
         }
         if (this._state === FromBTCLNAutoSwapState.PR_PAID) {
+            this._commitedAt ??= Date.now();
             await this._saveAndEmit(FromBTCLNAutoSwapState.CLAIM_COMMITED);
         }
         if (result === 0)
@@ -1021,6 +1132,7 @@ class FromBTCLNAutoSwap extends IEscrowSwap_1.IEscrowSwap {
             data: this._data == null ? null : this._data.serialize(),
             commitTxId: this._commitTxId,
             claimTxId: this._claimTxId,
+            commitedAt: this._commitedAt,
             btcAmountSwap: this.btcAmountSwap == null ? null : this.btcAmountSwap.toString(10),
             btcAmountGas: this.btcAmountGas == null ? null : this.btcAmountGas.toString(10),
             gasSwapFeeBtc: this.gasSwapFeeBtc == null ? null : this.gasSwapFeeBtc.toString(10),
@@ -1159,6 +1271,7 @@ class FromBTCLNAutoSwap extends IEscrowSwap_1.IEscrowSwap {
                 return true;
             case base_1.SwapCommitStateType.COMMITED:
                 if (this._state !== FromBTCLNAutoSwapState.CLAIM_COMMITED && this._state !== FromBTCLNAutoSwapState.EXPIRED) {
+                    this._commitedAt ??= Date.now();
                     this._state = FromBTCLNAutoSwapState.CLAIM_COMMITED;
                     return true;
                 }

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

@@ -18,6 +18,8 @@ import { AmountData } from "../../../../types/AmountData";
 import { LNURLWithdrawParamsWithUrl } from "../../../../types/lnurl/LNURLWithdraw";
 import { AllOptional } from "../../../../utils/TypeUtils";
 export type FromBTCLNAutoOptions = {
+    paymentHash?: Buffer;
+    description?: string;
     descriptionHash?: Buffer;
     unsafeSkipLnNodeCheck?: boolean;
     gasAmount?: bigint;