@atomiqlabs/sdk 8.3.6 → 8.4.4

package/src/intermediaries/apis/IntermediaryAPI.ts

@@ -226,6 +226,7 @@ export type FromBTCLNResponseType = RequestSchemaResult<typeof FromBTCLNResponse
 
 export type FromBTCLNInit = BaseFromBTCSwapInit & {
     paymentHash: Buffer,
+    description?: string,
     descriptionHash?: Buffer
 }
 
@@ -258,6 +259,7 @@ export type FromBTCLNAutoResponseType = RequestSchemaResult<typeof FromBTCLNAuto
 export type FromBTCLNAutoInit = Omit<BaseFromBTCSwapInit, "feeRate"> & {
     paymentHash: Buffer,
     gasToken: string,
+    description?: string,
     descriptionHash?: Buffer,
     gasAmount?: bigint,
     claimerBounty?: Promise<bigint>
@@ -597,6 +599,7 @@ export class IntermediaryAPI {
                 amount: init.amount.toString(),
                 address: init.claimer,
                 token: init.token,
+                description: init.description ?? null,
                 descriptionHash: init.descriptionHash==null ? null : init.descriptionHash.toString("hex"),
                 exactOut: init.exactOut,
                 feeRate: init.feeRate
@@ -658,6 +661,7 @@ export class IntermediaryAPI {
                 amount: init.amount.toString(),
                 address: init.claimer,
                 token: init.token,
+                description: init.description ?? null,
                 descriptionHash: init.descriptionHash==null ? null : init.descriptionHash.toString("hex"),
                 exactOut: init.exactOut,
                 gasToken: init.gasToken,
@@ -937,4 +941,4 @@ export class IntermediaryAPI {
         });
     }
 
-}
+}

package/src/swapper/Swapper.ts

@@ -1185,6 +1185,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
      * @param amount Amount to send in satoshis (if `exactOut=false`) or receive in token based units (if `exactOut=true`)
      * @param exactOut Whether to use a exact out instead of exact in
      * @param additionalParams Additional parameters sent to the LP when creating the swap
+     * @param options Additional options for the swap
      */
     async createFromBTCLNSwapViaLNURL<ChainIdentifier extends ChainIds<T>>(
         chainIdentifier: ChainIdentifier,
@@ -1193,7 +1194,8 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
         lnurl: string | LNURLWithdraw,
         amount: bigint,
         exactOut: boolean = false,
-        additionalParams: Record<string, any> | undefined = this.options.defaultAdditionalParameters
+        additionalParams: Record<string, any> | undefined = this.options.defaultAdditionalParameters,
+        options?: FromBTCLNOptions
     ): Promise<FromBTCLNSwap<T[ChainIdentifier]>> {
         if(this._chains[chainIdentifier]==null) throw new Error("Invalid chain identifier! Unknown chain: "+chainIdentifier);
         if(typeof(lnurl)==="string" && !this.Utils.isValidLNURL(lnurl)) throw new Error("Invalid LNURL-withdraw link");
@@ -1211,6 +1213,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
                 typeof(lnurl)==="string" ? (lnurl.startsWith("lightning:") ? lnurl.substring(10): lnurl) : lnurl.params,
                 amountData,
                 candidates,
+                options,
                 additionalParams,
                 abortSignal
             ),
@@ -1477,7 +1480,7 @@ export class Swapper<T extends MultiChain> extends EventEmitter<{
                         if(typeof(src)!=="string" && !isLNURLWithdraw(src)) throw new Error("LNURL must be a string or LNURLWithdraw object!");
                         return this.supportsSwapType(dstToken.chainId, SwapType.FROM_BTCLN_AUTO) ?
                             this.createFromBTCLNSwapNewViaLNURL(dstToken.chainId, dst, dstToken.address, src, amount, !exactIn, undefined, options as any) :
-                            this.createFromBTCLNSwapViaLNURL(dstToken.chainId, dst, dstToken.address, src, amount, !exactIn);
+                            this.createFromBTCLNSwapViaLNURL(dstToken.chainId, dst, dstToken.address, src, amount, !exactIn, undefined, options as any);
                     } else {
                         return this.supportsSwapType(dstToken.chainId, SwapType.FROM_BTCLN_AUTO) ?
                             this.createFromBTCLNSwapNew(dstToken.chainId, dst, dstToken.address, amount, !exactIn, undefined, options as any):

package/src/swaps/ISwap.ts

@@ -12,6 +12,7 @@ import {isSCToken, Token} from "../types/Token";
 import {SwapExecutionAction} from "../types/SwapExecutionAction";
 import {LoggerType} from "../utils/Logger";
 import {isPriceInfoType, PriceInfoType} from "../types/PriceInfoType";
+import {SwapStateInfo} from "../types/SwapStateInfo";
 
 /**
  * Initialization data for creating a swap
@@ -57,6 +58,17 @@ export abstract class ISwap<
      * Swap type
      */
     protected readonly abstract TYPE: SwapType;
+
+    /**
+     * Description for the states
+     * @internal
+     */
+    protected readonly abstract swapStateDescription: Record<S, string>;
+    /**
+     * Name of the states
+     * @internal
+     */
+    protected readonly abstract swapStateName: (state: number) => string;
     /**
      * Swap logger
      * @internal
@@ -237,6 +249,17 @@ export abstract class ISwap<
      */
     public 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
+     */
+    public abstract execute(...args: any[]): Promise<boolean>;
+
     //////////////////////////////
     //// Pricing
 
@@ -448,6 +471,11 @@ export abstract class ISwap<
      */
     public abstract isFailed(): boolean;
 
+    /**
+     * Returns whether the swap is currently being processed
+     */
+    public 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
@@ -486,6 +514,23 @@ export abstract class ISwap<
         return this._state;
     }
 
+    /**
+     * Returns the current state of the swap along with the human-readable description of the state
+     */
+    public getStateInfo(): SwapStateInfo<S> {
+        return {
+            state: this._state,
+            name: this.swapStateName(this._state),
+            description: this.swapStateDescription[this._state]
+        }
+    }
+
+    /**
+     * Returns a state-dependent set of actions for the user to execute, or empty array if there is currently
+     *  no action required from the user to execute.
+     */
+    public abstract getCurrentActions(): Promise<SwapExecutionAction<T>[]>;
+
     //////////////////////////////
     //// Amounts & fees
 

package/src/swaps/escrow_swaps/IEscrowSwap.ts

@@ -131,6 +131,26 @@ export abstract class IEscrowSwap<
         return this.getIdentifierHashString();
     }
 
+    /**
+     * Returns the smart chain transaction ID of the tx that initiated the escrow
+     */
+    getEscrowInitTxId(): string | undefined {
+        return this._commitTxId;
+    }
+
+    /**
+     * Returns the smart chain transaction ID of the tx that claimed (settled) the escrow
+     */
+    getEscrowClaimTxId(): string | undefined {
+        return this._claimTxId;
+    }
+
+    /**
+     * Returns the smart chain transaction ID of the tx that refunded the escrow
+     */
+    getEscrowRefundTxId(): string | undefined {
+        return this._refundTxId;
+    }
 
     //////////////////////////////
     //// Watchdogs

package/src/swaps/escrow_swaps/frombtc/ln/FromBTCLNSwap.ts

@@ -31,6 +31,7 @@ import {getLogger, LoggerType} from "../../../../utils/Logger";
 import {timeoutPromise} from "../../../../utils/TimeoutUtils";
 import {isLNURLWithdraw, LNURLWithdraw, LNURLWithdrawParamsWithUrl} from "../../../../types/lnurl/LNURLWithdraw";
 import {sha256} from "@noble/hashes/sha2";
+import {SwapExecutionAction} from "../../../../types/SwapExecutionAction";
 
 /**
  * State enum for legacy Lightning -> Smart chain swaps
@@ -80,6 +81,17 @@ export enum FromBTCLNSwapState {
     CLAIM_CLAIMED = 3
 }
 
+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"
+};
+
 export type FromBTCLNSwapInit<T extends SwapData> = IEscrowSelfInitSwapInit<T> & {
     pr?: string,
     secret?: string,
@@ -109,6 +121,14 @@ export class FromBTCLNSwap<T extends ChainType = ChainType>
     implements IAddressSwap, IClaimableSwap<T, FromBTCLNDefinition<T>, FromBTCLNSwapState> {
 
     protected readonly TYPE = SwapType.FROM_BTCLN;
+    /**
+     * @internal
+     */
+    protected readonly swapStateName = (state: number) => FromBTCLNSwapState[state];
+    /**
+     * @internal
+     */
+    protected readonly swapStateDescription = FromBTCLNSwapStateDescription;
     /**
      * @internal
      */
@@ -365,6 +385,16 @@ export class FromBTCLNSwap<T extends ChainType = ChainType>
         return this._state===FromBTCLNSwapState.FAILED || this._state===FromBTCLNSwapState.EXPIRED;
     }
 
+    /**
+     * @inheritDoc
+     */
+    isInProgress(): boolean {
+        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
      */
@@ -468,6 +498,25 @@ export class FromBTCLNSwap<T extends ChainType = ChainType>
         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: string) {
+        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(): boolean {
+        return this.secret != null;
+    }
+
 
     //////////////////////////////
     //// Execution
@@ -482,7 +531,7 @@ export class FromBTCLNSwap<T extends ChainType = ChainType>
      *  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(
@@ -496,11 +545,11 @@ export class FromBTCLNSwap<T extends ChainType = ChainType>
         },
         options?: {
             abortSignal?: AbortSignal,
+            secret?: string,
             lightningTxCheckIntervalSeconds?: number,
             delayBetweenCommitAndClaimSeconds?: number
-        },
-        secret?: string
-    ): Promise<void> {
+        }
+    ): Promise<boolean> {
         if(this._state===FromBTCLNSwapState.FAILED) throw new Error("Swap failed!");
         if(this._state===FromBTCLNSwapState.EXPIRED) throw new Error("Swap HTLC expired!");
         if(this._state===FromBTCLNSwapState.QUOTE_EXPIRED || this._state===FromBTCLNSwapState.QUOTE_SOFT_EXPIRED) throw new Error("Swap quote expired!");
@@ -530,14 +579,14 @@ export class FromBTCLNSwap<T extends ChainType = ChainType>
 
         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) {
                     await this.commit(dstSigner, options?.abortSignal, undefined, callbacks?.onDestinationCommitSent);
                     if(options?.delayBetweenCommitAndClaimSeconds!=null) await 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);
                 }
             }
         }
@@ -546,6 +595,8 @@ export class FromBTCLNSwap<T extends ChainType = ChainType>
         if(this._state===FromBTCLNSwapState.CLAIM_CLAIMED) {
             if(callbacks?.onSwapSettled!=null) callbacks.onSwapSettled(this.getOutputTxId()!);
         }
+
+        return true;
     }
 
     /**
@@ -555,10 +606,13 @@ export class FromBTCLNSwap<T extends ChainType = ChainType>
      * @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?: { skipChecks?: boolean }, secret?: string) {
+    async txsExecute(options?: {
+        skipChecks?: boolean,
+        secret?: string
+    }) {
         if(this._state===FromBTCLNSwapState.PR_CREATED) {
             if(!await this._verifyQuoteValid()) throw new Error("Quote already expired or close to expiry!");
             return [
@@ -580,7 +634,7 @@ export class FromBTCLNSwap<T extends ChainType = ChainType>
         if(this._state===FromBTCLNSwapState.PR_PAID) {
             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" as const,
@@ -598,7 +652,7 @@ export class FromBTCLNSwap<T extends ChainType = ChainType>
         }
 
         if(this._state===FromBTCLNSwapState.CLAIM_COMMITED) {
-            const txsClaim = await this.txsClaim(undefined, secret);
+            const txsClaim = await this.txsClaim(undefined, options?.secret);
             return [
                 {
                     name: "Claim" as const,
@@ -612,6 +666,27 @@ export class FromBTCLNSwap<T extends ChainType = ChainType>
         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?: {
+        skipChecks?: boolean,
+        secret?: string
+    }): Promise<SwapExecutionAction<T>[]> {
+        try {
+            return await this.txsExecute(options);
+        } catch (e) {
+            return [];
+        }
+    }
+
 
     //////////////////////////////
     //// Payment
@@ -1387,4 +1462,4 @@ export class FromBTCLNSwap<T extends ChainType = ChainType>
         }
     }
 
-}
+}

package/src/swaps/escrow_swaps/frombtc/ln/FromBTCLNWrapper.ts

@@ -33,6 +33,8 @@ import {AllOptional} from "../../../../utils/TypeUtils";
 import {sha256} from "@noble/hashes/sha2";
 
 export type FromBTCLNOptions = {
+    paymentHash?: Buffer,
+    description?: string,
     descriptionHash?: Buffer,
     unsafeSkipLnNodeCheck?: boolean
 };
@@ -186,6 +188,9 @@ export class FromBTCLNWrapper<
         if(options.descriptionHash!=null && decodedPr.tagsObject.purpose_commit_hash!==options.descriptionHash.toString("hex"))
             throw new IntermediaryError("Invalid pr returned - description hash");
 
+        if(options.description!=null && decodedPr.tagsObject.description!==options.description)
+            throw new IntermediaryError("Invalid pr returned - description");
+
         if(
             decodedPr.tagsObject.payment_hash==null ||
             !Buffer.from(decodedPr.tagsObject.payment_hash, "hex").equals(paymentHash)
@@ -231,13 +236,27 @@ export class FromBTCLNWrapper<
         quote: Promise<FromBTCLNSwap<T>>,
         intermediary: Intermediary
     }[] {
+        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("Invalid payment hash length, must be exactly 32 bytes!");
+
         if(options.descriptionHash!=null && options.descriptionHash.length!==32)
             throw new UserError("Invalid description hash length");
 
-        const {secret, paymentHash} = this.getSecretAndHash();
+        if(options.description!=null && Buffer.byteLength(options.description, "utf8") > 500)
+            throw new UserError("Invalid description length");
+
+        let secret: Buffer | undefined;
+        let paymentHash: Buffer;
+        if(options?.paymentHash!=null) {
+            paymentHash = options.paymentHash;
+        } else {
+            ({secret, paymentHash} = this.getSecretAndHash());
+        }
         const claimHash = this._contract.getHashForHtlc(paymentHash);
 
         const nativeTokenAddress = this._chain.getNativeCurrencyAddress();
@@ -267,6 +286,7 @@ export class FromBTCLNWrapper<
                                 amount: amountData.amount,
                                 claimer: recipient,
                                 token: amountData.token.toString(),
+                                description: options?.description,
                                 descriptionHash: options?.descriptionHash,
                                 exactOut: !amountData.exactIn,
                                 feeRate: throwIfUndefined(_preFetches.feeRatePromise),
@@ -311,7 +331,7 @@ export class FromBTCLNWrapper<
                                 resp.securityDeposit, 0n, nativeTokenAddress
                             ),
                             pr: resp.pr,
-                            secret: secret.toString("hex"),
+                            secret: secret?.toString("hex"),
                             exactIn: amountData.exactIn ?? true
                         } as FromBTCLNSwapInit<T["Data"]>);
                         await quote._save();
@@ -336,6 +356,7 @@ export class FromBTCLNWrapper<
      * @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
      */
@@ -344,6 +365,7 @@ export class FromBTCLNWrapper<
         lnurl: string | LNURLWithdrawParamsWithUrl,
         amountData: AmountData,
         lps: Intermediary[],
+        options?: FromBTCLNOptions,
         additionalParams?: Record<string, any>,
         abortSignal?: AbortSignal
     ): Promise<{
@@ -352,6 +374,9 @@ export class FromBTCLNWrapper<
     }[]> {
         if(!this.isInitialized) throw new Error("Not initialized, call init() first!");
 
+        if(options?.paymentHash!=null && options.paymentHash.length!==32)
+            throw new UserError("Invalid payment hash length, must be exactly 32 bytes!");
+
         const abortController = extendAbortController(abortSignal);
         const preFetches = {
             pricePrefetchPromise: this.preFetchPrice(amountData, abortController.signal),
@@ -383,7 +408,7 @@ export class FromBTCLNWrapper<
                 if((amount * 105n / 100n) > max) throw new 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(