@atomiqlabs/sdk 8.1.8 → 8.3.1

package/src/swaps/IRefundableSwap.ts

@@ -3,7 +3,8 @@ import {ISwap} from "./ISwap";
 import {ISwapWrapper, SwapTypeDefinition} from "./ISwapWrapper";
 
 /**
- * Type guard to check if an object is an IRefundableSwap
+ * Type guard to check if an object is an {@link IRefundableSwap}
+ *
  * @category Swaps
  */
 export function isIRefundableSwap(obj: any): obj is IRefundableSwap {
@@ -13,7 +14,8 @@ export function isIRefundableSwap(obj: any): obj is IRefundableSwap {
 }
 
 /**
- * Interface for swaps that can be refunded
+ * Interface for swaps that can be refunded in case of failure
+ *
  * @category Swaps
  */
 export interface IRefundableSwap<
@@ -22,8 +24,35 @@ export interface IRefundableSwap<
     S extends number = number
 > extends ISwap<T, D, S> {
 
+    /**
+     * Checks whether a swap is currently refundable
+     */
     isRefundable(): boolean;
-    txsRefund(_signer?: T["Signer"] | T["NativeSigner"]): Promise<T["TX"][]>;
+
+    /**
+     * Returns transactions for refunding the swap if the swap is in refundable state, you can check so with
+     *  {@link isRefundable}. After sending the transaction manually be sure to call the {@link waitTillRefunded}
+     *  function to wait till the refund transaction is observed, processed by the SDK and state of the swap
+     *  properly updated.
+     *
+     * @param _signer Address of the signer to create the refund transactions for
+     */
+    txsRefund(_signer?: string): Promise<T["TX"][]>;
+
+    /**
+     * Refunds the swap if the swap is in refundable state, you can check so with {@link isRefundable}
+     *
+     * @param _signer Signer to sign the transactions with, must be the same as used in the initialization
+     * @param abortSignal Abort signal
+     */
     refund(_signer?: T["Signer"] | T["NativeSigner"], abortSignal?: AbortSignal): Promise<string>;
 
+    /**
+     * Waits till a swap is refunded, should be called after sending the refund transactions manually to
+     *  wait till the SDK processes the refund and updates the swap state accordingly
+     *
+     * @param abortSignal AbortSignal
+     */
+    waitTillRefunded(abortSignal?: AbortSignal): Promise<void>;
+
 }

package/src/swaps/ISwap.ts

@@ -15,6 +15,7 @@ import {isPriceInfoType, PriceInfoType} from "../types/PriceInfoType";
 
 /**
  * Initialization data for creating a swap
+ *
  * @category Swaps
  */
 export type ISwapInit = {
@@ -28,6 +29,7 @@ export type ISwapInit = {
 
 /**
  * Type guard to check if an object is an ISwapInit
+ *
  * @category Swaps
  */
 export function isISwapInit(obj: any): obj is ISwapInit {
@@ -43,6 +45,7 @@ export function isISwapInit(obj: any): obj is ISwapInit {
 
 /**
  * Base abstract class for all swap types
+ *
  * @category Swaps
  */
 export abstract class ISwap<
@@ -50,38 +53,95 @@ export abstract class ISwap<
     D extends SwapTypeDefinition<T, ISwapWrapper<T, D>, ISwap<T, D, S>> = SwapTypeDefinition<T, ISwapWrapper<T, any>, ISwap<T, any, any>>,
     S extends number = number
 > {
+    /**
+     * Swap type
+     */
     protected readonly abstract TYPE: SwapType;
+    /**
+     * Swap logger
+     * @internal
+     */
     protected readonly abstract logger: LoggerType;
-
+    /**
+     * Current newest defined version of the swap
+     * @internal
+     */
     protected readonly currentVersion: number = 1;
+    /**
+     * Wrapper instance holding this swap
+     * @internal
+     */
     protected readonly wrapper: D["Wrapper"];
 
-    readonly url?: string;
-
-    readonly chainIdentifier: T["ChainId"];
-    readonly exactIn: boolean;
-    createdAt: number;
 
+    /**
+     * The current version of the swap
+     * @internal
+     */
     protected version: number;
+    /**
+     * Whether a swap was initialized, a swap is considered initialize on first interaction with it, i.e.
+     *  calling commit() on a Smart chain -> Bitcoin swaps, calling waitForPayment() or similar on the other
+     *  direction. Not initiated swaps are not saved to the persistent storage by default (see
+     *  {@link SwapperOptions.saveUninitializedSwaps})
+     * @internal
+     */
     protected initiated: boolean = false;
-
-    state: S = 0 as S;
-    expiry: number;
-    pricingInfo?: PriceInfoType;
-
+    /**
+     * Expiration of the swap quote
+     * @internal
+     */
+    protected expiry: number;
+    /**
+     * Pricing information of the swap
+     * @internal
+     */
+    protected pricingInfo?: PriceInfoType;
+    /**
+     * Swap fee in the non-bitcoin token
+     * @internal
+     */
     protected swapFee: bigint;
+    /**
+     * Swap fee in bitcoin satoshis
+     * @internal
+     */
     protected swapFeeBtc: bigint;
 
+
+    /**
+     * Swap state
+     * @internal
+     */
+    _state: S = 0 as S;
     /**
      * Random nonce to differentiate the swap from others with the same identifier hash (i.e. when quoting the same swap
      *  from multiple LPs)
+     * @internal
      */
-    randomNonce: string;
+    _randomNonce: string;
+
 
     /**
-     * Event emitter emitting "swapState" event when swap's state changes
+     * Event emitter emitting `"swapState"` event when swap's state changes
      */
-    events: EventEmitter<{swapState: [D["Swap"]]}> = new EventEmitter();
+    readonly events: EventEmitter<{swapState: [D["Swap"]]}> = new EventEmitter();
+    /**
+     * URL of the intermediary (LP) used for this swap, already has the swap service specific path appended
+     */
+    readonly url?: string;
+    /**
+     * Smart chain identifier string corresponding to this swap
+     */
+    readonly chainIdentifier: T["ChainId"];
+    /**
+     * Whether a swap is an exact input swap
+     */
+    readonly exactIn: boolean;
+    /**
+     * A UNIX milliseconds timestamps of when this swap was created
+     */
+    createdAt: number;
 
     protected constructor(wrapper: D["Wrapper"], obj: any);
     protected constructor(wrapper: D["Wrapper"], swapInit: ISwapInit);
@@ -100,12 +160,12 @@ export abstract class ISwap<
             this.exactIn = swapInitOrObj.exactIn;
             this.version = this.currentVersion;
             this.createdAt = Date.now();
-            this.randomNonce = randomBytes(16).toString("hex");
+            this._randomNonce = randomBytes(16).toString("hex");
         } else {
             this.expiry = swapInitOrObj.expiry;
             this.url = swapInitOrObj.url;
 
-            this.state = swapInitOrObj.state;
+            this._state = swapInitOrObj.state;
 
             if(
                 swapInitOrObj._isValid!=null && swapInitOrObj._differencePPM!=null && swapInitOrObj._satsBaseFee!=null &&
@@ -130,7 +190,7 @@ export abstract class ISwap<
             this.exactIn = swapInitOrObj.exactIn;
             this.createdAt = swapInitOrObj.createdAt ?? swapInitOrObj.expiry;
 
-            this.randomNonce = swapInitOrObj.randomNonce;
+            this._randomNonce = swapInitOrObj.randomNonce;
         }
         if(this.version!==this.currentVersion) {
             this.upgradeVersion();
@@ -138,6 +198,11 @@ export abstract class ISwap<
         if(this.initiated==null) this.initiated = true;
     }
 
+    /**
+     * Called when swap is deserialized to potentially update the version of the data for the swap
+     *
+     * @internal
+     */
     protected abstract upgradeVersion(): void;
 
     /**
@@ -145,14 +210,14 @@ export abstract class ISwap<
      *
      * @param targetState The state to wait for
      * @param type Whether to wait for the state exactly or also to a state with a higher number
-     * @param abortSignal
-     * @protected
+     * @param abortSignal Abort signal
+     * @internal
      */
     protected waitTillState(targetState: S, type: "eq" | "gte" | "neq" = "eq", abortSignal?: AbortSignal): Promise<void> {
         return new Promise((resolve, reject) => {
             let listener: (swap: D["Swap"]) => void;
             listener = (swap) => {
-                if(type==="eq" ? swap.state===targetState : type==="gte" ? swap.state>=targetState : swap.state!=targetState) {
+                if(type==="eq" ? swap._state===targetState : type==="gte" ? swap._state>=targetState : swap._state!=targetState) {
                     resolve();
                     this.events.removeListener("swapState", listener);
                 }
@@ -165,11 +230,21 @@ export abstract class ISwap<
         });
     }
 
-    abstract txsExecute(options?: any): Promise<SwapExecutionAction<T>[]>;
+    /**
+     * Returns a list of steps or transactions required to finish and settle the swap
+     *
+     * @param options Additional options for executing the swap
+     */
+    public abstract txsExecute(options?: any): Promise<SwapExecutionAction<T>[]>;
 
     //////////////////////////////
     //// Pricing
 
+    /**
+     * This attempts to populate missing fields in the pricing info based on the swap amounts
+     *
+     * @internal
+     */
     protected tryRecomputeSwapPrice(): void {
         if(this.pricingInfo==null) return;
         if(this.pricingInfo.swapPriceUSatPerToken==null) {
@@ -178,7 +253,7 @@ export abstract class ISwap<
             const output = this.getOutput();
             if(input.isUnknown || output.isUnknown) return;
             if(isSCToken(input.token) && this.getDirection()===SwapDirection.TO_BTC) {
-                this.pricingInfo = this.wrapper.prices.recomputePriceInfoSend(
+                this.pricingInfo = this.wrapper._prices.recomputePriceInfoSend(
                     this.chainIdentifier,
                     output.rawAmount!,
                     this.pricingInfo.satsBaseFee,
@@ -188,7 +263,7 @@ export abstract class ISwap<
                 );
                 this.pricingInfo.realPriceUsdPerBitcoin = priceUsdPerBtc;
             } else if(isSCToken(output.token) && this.getDirection()===SwapDirection.FROM_BTC) {
-                this.pricingInfo = this.wrapper.prices.recomputePriceInfoReceive(
+                this.pricingInfo = this.wrapper._prices.recomputePriceInfoReceive(
                     this.chainIdentifier,
                     input.rawAmount!,
                     this.pricingInfo.satsBaseFee,
@@ -202,9 +277,9 @@ export abstract class ISwap<
     }
 
     /**
-     * Re-fetches & revalidates the price data
+     * Re-fetches & revalidates the price data based on the current market prices
      */
-    async refreshPriceData(): Promise<void> {
+    public async refreshPriceData(): Promise<void> {
         if(this.pricingInfo==null) return;
         const priceUsdPerBtc = this.pricingInfo.realPriceUsdPerBitcoin;
         const input = this.getInput();
@@ -212,7 +287,7 @@ export abstract class ISwap<
         if(input.isUnknown || output.isUnknown) return;
 
         if(isSCToken(input.token) && this.getDirection()===SwapDirection.TO_BTC) {
-            this.pricingInfo = await this.wrapper.prices.isValidAmountSend(
+            this.pricingInfo = await this.wrapper._prices.isValidAmountSend(
                 this.chainIdentifier,
                 output.rawAmount!,
                 this.pricingInfo.satsBaseFee,
@@ -222,7 +297,7 @@ export abstract class ISwap<
             );
             this.pricingInfo.realPriceUsdPerBitcoin = priceUsdPerBtc;
         } else if(isSCToken(output.token) && this.getDirection()===SwapDirection.FROM_BTC) {
-            this.pricingInfo = await this.wrapper.prices.isValidAmountReceive(
+            this.pricingInfo = await this.wrapper._prices.isValidAmountReceive(
                 this.chainIdentifier,
                 input.rawAmount!,
                 this.pricingInfo.satsBaseFee,
@@ -237,7 +312,7 @@ export abstract class ISwap<
     /**
      * Checks if the pricing for the swap is valid, according to max allowed price difference set in the ISwapPrice
      */
-    hasValidPrice(): boolean {
+    public hasValidPrice(): boolean {
         if(this.pricingInfo==null) throw new Error("Pricing info not found, cannot check price validity!");
         return this.pricingInfo.isValid;
     }
@@ -245,7 +320,7 @@ export abstract class ISwap<
     /**
      * Returns pricing info about the swap
      */
-    getPriceInfo(): {
+    public getPriceInfo(): {
         marketPrice?: number,
         swapPrice: number,
         difference: PercentagePPM
@@ -273,102 +348,142 @@ export abstract class ISwap<
     //////////////////////////////
     //// Getters & utils
 
-    abstract _getEscrowHash(): string | null;
-
     /**
+     * Asserts a given signer is the initiator of this swap
+     *
      * @param signer Signer to check with this swap's initiator
      * @throws {Error} When signer's address doesn't match with the swap's initiator one
+     * @internal
      */
     protected checkSigner(signer: T["Signer"] | string): void {
         if((typeof(signer)==="string" ? signer : signer.getAddress())!==this._getInitiator()) throw new Error("Invalid signer provided!");
     }
 
+    /**
+     * Returns an escrow hash of the swap
+     *
+     * @internal
+     */
+    abstract _getEscrowHash(): string | null;
+
+    /**
+     * Checks if the swap's quote is expired for good (i.e. the swap strictly cannot be initiated anymore)
+     * @internal
+     */
+    abstract _verifyQuoteDefinitelyExpired(): Promise<boolean>;
+
     /**
      * Checks if the swap's quote is still valid
+     * @internal
      */
-    abstract verifyQuoteValid(): Promise<boolean>;
+    abstract _verifyQuoteValid(): Promise<boolean>;
 
-    abstract getInputAddress(): string | null;
-    abstract getOutputAddress(): string | null;
+    /**
+     * Returns the intiator address of the swap - address that created this swap
+     * @internal
+     */
+    abstract _getInitiator(): string;
+
+    /**
+     * Sets this swap as initiated
+     * @internal
+     */
+    _setInitiated(): void {
+        this.initiated = true;
+    }
+
+    /**
+     * Returns source address of the swap
+     */
+    public abstract getInputAddress(): string | null;
+
+    /**
+     * Returns destination address of the swap
+     */
+    public abstract getOutputAddress(): string | null;
 
-    abstract getInputTxId(): string | null;
-    abstract getOutputTxId(): string | null;
+    /**
+     * Returns swap input transaction ID on the source chain
+     */
+    public abstract getInputTxId(): string | null;
+
+    /**
+     * Returns swap output transaction ID on the destination chain
+     */
+    public abstract getOutputTxId(): string | null;
 
     /**
-     * Returns the ID of the swap, as used in the storage and getSwapById function
+     * Returns the ID of the swap, as used in the storage
      */
-    abstract getId(): string;
+    public abstract getId(): string;
 
     /**
      * Checks whether there is some action required from the user for this swap - can mean either refundable or claimable
      */
-    abstract requiresAction(): boolean;
+    public abstract requiresAction(): boolean;
 
     /**
      * Returns whether the swap is finished and in its terminal state (this can mean successful, refunded or failed)
      */
-    abstract isFinished(): boolean;
+    public abstract isFinished(): boolean;
 
     /**
      * Checks whether the swap's quote has definitely expired and cannot be committed anymore, we can remove such swap
      */
-    abstract isQuoteExpired(): boolean;
+    public abstract isQuoteExpired(): boolean;
 
     /**
      * Checks whether the swap's quote is soft expired (this means there is not enough time buffer for it to commit,
      *  but it still can happen)
      */
-    abstract isQuoteSoftExpired(): boolean;
+    public abstract isQuoteSoftExpired(): boolean;
 
     /**
      * Returns whether the swap finished successful
      */
-    abstract isSuccessful(): boolean;
+    public abstract isSuccessful(): boolean;
 
     /**
      * Returns whether the swap failed (e.g. was refunded)
      */
-    abstract isFailed(): boolean;
+    public abstract isFailed(): boolean;
 
     /**
-     * Returns the intiator address of the swap - address that created this swap
+     * 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
+     *  direction. Not initiated swaps are not saved to the persistent storage by default (see
+     *  {@link SwapperOptions.saveUninitializedSwaps})
      */
-    abstract _getInitiator(): string;
-
-    isInitiated(): boolean {
+    public isInitiated(): boolean {
         return this.initiated;
     }
 
-    _setInitiated(): void {
-        this.initiated = true;
-    }
-
     /**
      * Returns quote expiry in UNIX millis
      */
-    getQuoteExpiry(): number {
+    public getQuoteExpiry(): number {
         return this.expiry;
     }
 
     /**
      * Returns the type of the swap
      */
-    getType(): SwapType {
+    public getType(): SwapType {
         return this.TYPE;
     }
 
     /**
      * Returns the direction of the swap
      */
-    getDirection(): SwapDirection {
+    public getDirection(): SwapDirection {
         return this.TYPE===SwapType.TO_BTC || this.TYPE===SwapType.TO_BTCLN ? SwapDirection.TO_BTC : SwapDirection.FROM_BTC;
     }
 
     /**
      * Returns the current state of the swap
      */
-    getState(): S {
-        return this.state;
+    public getState(): S {
+        return this._state;
     }
 
     //////////////////////////////
@@ -377,44 +492,73 @@ export abstract class ISwap<
     /**
      * Returns output amount of the swap, user receives this much
      */
-    abstract getOutput(): TokenAmount;
+    public abstract getOutput(): TokenAmount;
 
     /**
      * Returns the output token of the swap
      */
-    abstract getOutputToken(): Token<T["ChainId"]>;
+    public abstract getOutputToken(): Token<T["ChainId"]>;
 
     /**
      * Returns input amount of the swap, user needs to pay this much
      */
-    abstract getInput(): TokenAmount;
+    public abstract getInput(): TokenAmount;
 
     /**
      * Returns the input token of the swap
      */
-    abstract getInputToken(): Token<T["ChainId"]>;
+    public abstract getInputToken(): Token<T["ChainId"]>;
 
     /**
-     * Returns input amount if the swap without the fees (swap fee, network fee)
+     * Returns input amount of the swap without the fees (swap fee, network fee)
      */
-    abstract getInputWithoutFee(): TokenAmount;
+    public abstract getInputWithoutFee(): TokenAmount;
 
     /**
      * Returns total fee for the swap, the fee is represented in source currency & destination currency, but is
      *  paid only once
      */
-    abstract getFee(): Fee;
+    public abstract getFee(): Fee;
 
     /**
      * Returns the breakdown of all the fees paid
      */
-    abstract getFeeBreakdown(): FeeBreakdown<T["ChainId"]>;
+    public abstract getFeeBreakdown(): FeeBreakdown<T["ChainId"]>;
 
 
     //////////////////////////////
     //// Storage
 
-    serialize(): any {
+    /**
+     * Saves the swap data to the underlying storage, or removes it if it is in a quote expired state
+     *
+     * @internal
+     */
+    _save(): Promise<void> {
+        if(this.isQuoteExpired()) {
+            return this.wrapper._removeSwapData(this);
+        } else {
+            return this.wrapper._saveSwapData(this);
+        }
+    }
+
+    /**
+     * Saves the swap data and also emits a swap state change
+     *
+     * @param state Optional state to set before the swap is saved an event emitted
+     *
+     * @internal
+     */
+    async _saveAndEmit(state?: S): Promise<void> {
+        if(state!=null) this._state = state;
+        await this._save();
+        this._emitEvent();
+    }
+
+    /**
+     * Serializes the swap to a JSON stringifiable representation (i.e. no bigints, buffers etc.)
+     */
+    public serialize(): any {
         if(this.pricingInfo==null) return {};
         return {
             id: this.getId(),
@@ -429,7 +573,7 @@ export abstract class ISwap<
             _realPriceUSatPerToken: this.pricingInfo.realPriceUSatPerToken==null ? null :this.pricingInfo.realPriceUSatPerToken.toString(10),
             _realPriceUsdPerBitcoin: this.pricingInfo.realPriceUsdPerBitcoin,
             _swapPriceUSatPerToken: this.pricingInfo.swapPriceUSatPerToken==null ? null :this.pricingInfo.swapPriceUSatPerToken.toString(10),
-            state: this.state,
+            state: this._state,
             url: this.url,
             swapFee: this.swapFee==null ? null : this.swapFee.toString(10),
             swapFeeBtc: this.swapFeeBtc==null ? null : this.swapFeeBtc.toString(10),
@@ -438,28 +582,19 @@ export abstract class ISwap<
             initiated: this.initiated,
             exactIn: this.exactIn,
             createdAt: this.createdAt,
-            randomNonce: this.randomNonce
+            randomNonce: this._randomNonce
         }
     }
 
-    _save(): Promise<void> {
-        if(this.isQuoteExpired()) {
-            return this.wrapper.removeSwapData(this);
-        } else {
-            return this.wrapper.saveSwapData(this);
-        }
-    }
-
-    async _saveAndEmit(state?: S): Promise<void> {
-        if(state!=null) this.state = state;
-        await this._save();
-        this._emitEvent();
-    }
-
 
     //////////////////////////////
     //// Events
 
+    /**
+     * Emits a `swapState` event with the current swap
+     *
+     * @internal
+     */
     _emitEvent() {
         this.wrapper.events.emit("swapState", this);
         this.events.emit("swapState", this);
@@ -475,6 +610,8 @@ export abstract class ISwap<
      * @param save whether to save the new swap state or not
      *
      * @returns {boolean} true if the swap changed, false if the swap hasn't changed
+     *
+     * @internal
      */
     abstract _sync(save?: boolean): Promise<boolean>;
 
@@ -484,6 +621,8 @@ export abstract class ISwap<
      * @param save whether to save the new swap state or not
      *
      * @returns {boolean} true if the swap changed, false if the swap hasn't changed
+     *
+     * @internal
      */
     abstract _tick(save?: boolean): Promise<boolean>;
 

package/src/swaps/ISwapWithGasDrop.ts

@@ -4,6 +4,7 @@ import {SCToken} from "../types/Token";
 
 /**
  * Type guard to check if a swap has gas drop functionality
+ *
  * @category Swaps
  */
 export function isSwapWithGasDrop(swap: any): swap is ISwapWithGasDrop<any> {
@@ -12,8 +13,13 @@ export function isSwapWithGasDrop(swap: any): swap is ISwapWithGasDrop<any> {
 
 /**
  * Interface for swaps with gas drop functionality
+ *
  * @category Swaps
  */
 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"]>>;
 }