@atomiqlabs/sdk 8.1.7 → 8.3.1

package/dist/swaps/ISwap.d.ts

@@ -14,6 +14,7 @@ import { LoggerType } from "../utils/Logger";
 import { PriceInfoType } from "../types/PriceInfoType";
 /**
  * Initialization data for creating a swap
+ *
  * @category Swaps
  */
 export type ISwapInit = {
@@ -26,56 +27,132 @@ export type ISwapInit = {
 };
 /**
  * Type guard to check if an object is an ISwapInit
+ *
  * @category Swaps
  */
 export declare function isISwapInit(obj: any): obj is ISwapInit;
 /**
  * Base abstract class for all swap types
+ *
  * @category Swaps
  */
 export declare abstract class ISwap<T extends ChainType = ChainType, 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;
+    /**
+     * 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;
-    state: 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;
     /**
      * 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<{
+    readonly events: EventEmitter<{
         swapState: [D["Swap"]];
     }>;
+    /**
+     * 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);
+    /**
+     * Called when swap is deserialized to potentially update the version of the data for the swap
+     *
+     * @internal
+     */
     protected abstract upgradeVersion(): void;
     /**
      * Waits till the swap reaches a specific state
      *
      * @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", abortSignal?: AbortSignal): Promise<void>;
+    /**
+     * Returns a list of steps or transactions required to finish and settle the swap
+     *
+     * @param options Additional options for executing the swap
+     */
     abstract txsExecute(options?: any): Promise<SwapExecutionAction<T>[]>;
+    /**
+     * This attempts to populate missing fields in the pricing info based on the swap amounts
+     *
+     * @internal
+     */
     protected tryRecomputeSwapPrice(): void;
     /**
-     * Re-fetches & revalidates the price data
+     * Re-fetches & revalidates the price data based on the current market prices
      */
     refreshPriceData(): Promise<void>;
     /**
@@ -90,22 +167,58 @@ export declare abstract class ISwap<T extends ChainType = ChainType, D extends S
         swapPrice: number;
         difference: PercentagePPM;
     };
-    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;
+    /**
+     * 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>;
+    /**
+     * Returns the intiator address of the swap - address that created this swap
+     * @internal
+     */
+    abstract _getInitiator(): string;
+    /**
+     * Sets this swap as initiated
+     * @internal
+     */
+    _setInitiated(): void;
+    /**
+     * Returns source address of the swap
      */
-    abstract verifyQuoteValid(): Promise<boolean>;
     abstract getInputAddress(): string | null;
+    /**
+     * Returns destination address of the swap
+     */
     abstract getOutputAddress(): string | null;
+    /**
+     * Returns swap input transaction ID on the source chain
+     */
     abstract getInputTxId(): string | null;
+    /**
+     * Returns swap output transaction ID on the destination chain
+     */
     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;
     /**
@@ -134,11 +247,12 @@ export declare abstract class ISwap<T extends ChainType = ChainType, D extends S
      */
     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;
-    _setInitiated(): void;
     /**
      * Returns quote expiry in UNIX millis
      */
@@ -172,7 +286,7 @@ export declare abstract class ISwap<T extends ChainType = ChainType, D extends S
      */
     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;
     /**
@@ -184,9 +298,29 @@ export declare abstract class ISwap<T extends ChainType = ChainType, D extends S
      * Returns the breakdown of all the fees paid
      */
     abstract getFeeBreakdown(): FeeBreakdown<T["ChainId"]>;
-    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>;
+    /**
+     * 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
+     */
     _saveAndEmit(state?: S): Promise<void>;
+    /**
+     * Serializes the swap to a JSON stringifiable representation (i.e. no bigints, buffers etc.)
+     */
+    serialize(): any;
+    /**
+     * Emits a `swapState` event with the current swap
+     *
+     * @internal
+     */
     _emitEvent(): void;
     /**
      * Synchronizes swap state from chain and/or LP node, usually ran on startup
@@ -194,6 +328,8 @@ export declare abstract class ISwap<T extends ChainType = ChainType, D extends S
      * @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>;
     /**
@@ -202,6 +338,8 @@ export declare abstract class ISwap<T extends ChainType = ChainType, D extends S
      * @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/dist/swaps/ISwap.js

@@ -10,6 +10,7 @@ const Token_1 = require("../types/Token");
 const PriceInfoType_1 = require("../types/PriceInfoType");
 /**
  * Type guard to check if an object is an ISwapInit
+ *
  * @category Swaps
  */
 function isISwapInit(obj) {
@@ -25,15 +26,31 @@ function isISwapInit(obj) {
 exports.isISwapInit = isISwapInit;
 /**
  * Base abstract class for all swap types
+ *
  * @category Swaps
  */
 class ISwap {
     constructor(wrapper, swapInitOrObj) {
+        /**
+         * Current newest defined version of the swap
+         * @internal
+         */
         this.currentVersion = 1;
+        /**
+         * 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
+         */
         this.initiated = false;
-        this.state = 0;
         /**
-         * Event emitter emitting "swapState" event when swap's state changes
+         * Swap state
+         * @internal
+         */
+        this._state = 0;
+        /**
+         * Event emitter emitting `"swapState"` event when swap's state changes
          */
         this.events = new events_1.EventEmitter();
         this.chainIdentifier = wrapper.chainIdentifier;
@@ -47,12 +64,12 @@ class ISwap {
             this.exactIn = swapInitOrObj.exactIn;
             this.version = this.currentVersion;
             this.createdAt = Date.now();
-            this.randomNonce = (0, Utils_1.randomBytes)(16).toString("hex");
+            this._randomNonce = (0, Utils_1.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 &&
                 swapInitOrObj._feePPM != null && swapInitOrObj._swapPriceUSatPerToken != null) {
                 this.pricingInfo = {
@@ -71,7 +88,7 @@ class ISwap {
             this.initiated = swapInitOrObj.initiated;
             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();
@@ -84,14 +101,14 @@ 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
      */
     waitTillState(targetState, type = "eq", abortSignal) {
         return new Promise((resolve, reject) => {
             let listener;
             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);
                 }
@@ -106,6 +123,11 @@ class ISwap {
     }
     //////////////////////////////
     //// Pricing
+    /**
+     * This attempts to populate missing fields in the pricing info based on the swap amounts
+     *
+     * @internal
+     */
     tryRecomputeSwapPrice() {
         if (this.pricingInfo == null)
             return;
@@ -116,17 +138,17 @@ class ISwap {
             if (input.isUnknown || output.isUnknown)
                 return;
             if ((0, Token_1.isSCToken)(input.token) && this.getDirection() === SwapDirection_1.SwapDirection.TO_BTC) {
-                this.pricingInfo = this.wrapper.prices.recomputePriceInfoSend(this.chainIdentifier, output.rawAmount, this.pricingInfo.satsBaseFee, this.pricingInfo.feePPM, input.rawAmount, input.token.address);
+                this.pricingInfo = this.wrapper._prices.recomputePriceInfoSend(this.chainIdentifier, output.rawAmount, this.pricingInfo.satsBaseFee, this.pricingInfo.feePPM, input.rawAmount, input.token.address);
                 this.pricingInfo.realPriceUsdPerBitcoin = priceUsdPerBtc;
             }
             else if ((0, Token_1.isSCToken)(output.token) && this.getDirection() === SwapDirection_1.SwapDirection.FROM_BTC) {
-                this.pricingInfo = this.wrapper.prices.recomputePriceInfoReceive(this.chainIdentifier, input.rawAmount, this.pricingInfo.satsBaseFee, this.pricingInfo.feePPM, output.rawAmount, output.token.address);
+                this.pricingInfo = this.wrapper._prices.recomputePriceInfoReceive(this.chainIdentifier, input.rawAmount, this.pricingInfo.satsBaseFee, this.pricingInfo.feePPM, output.rawAmount, output.token.address);
                 this.pricingInfo.realPriceUsdPerBitcoin = priceUsdPerBtc;
             }
         }
     }
     /**
-     * Re-fetches & revalidates the price data
+     * Re-fetches & revalidates the price data based on the current market prices
      */
     async refreshPriceData() {
         if (this.pricingInfo == null)
@@ -137,11 +159,11 @@ class ISwap {
         if (input.isUnknown || output.isUnknown)
             return;
         if ((0, Token_1.isSCToken)(input.token) && this.getDirection() === SwapDirection_1.SwapDirection.TO_BTC) {
-            this.pricingInfo = await this.wrapper.prices.isValidAmountSend(this.chainIdentifier, output.rawAmount, this.pricingInfo.satsBaseFee, this.pricingInfo.feePPM, input.rawAmount, input.token.address);
+            this.pricingInfo = await this.wrapper._prices.isValidAmountSend(this.chainIdentifier, output.rawAmount, this.pricingInfo.satsBaseFee, this.pricingInfo.feePPM, input.rawAmount, input.token.address);
             this.pricingInfo.realPriceUsdPerBitcoin = priceUsdPerBtc;
         }
         else if ((0, Token_1.isSCToken)(output.token) && this.getDirection() === SwapDirection_1.SwapDirection.FROM_BTC) {
-            this.pricingInfo = await this.wrapper.prices.isValidAmountReceive(this.chainIdentifier, input.rawAmount, this.pricingInfo.satsBaseFee, this.pricingInfo.feePPM, output.rawAmount, output.token.address);
+            this.pricingInfo = await this.wrapper._prices.isValidAmountReceive(this.chainIdentifier, input.rawAmount, this.pricingInfo.satsBaseFee, this.pricingInfo.feePPM, output.rawAmount, output.token.address);
             this.pricingInfo.realPriceUsdPerBitcoin = priceUsdPerBtc;
         }
     }
@@ -173,20 +195,35 @@ class ISwap {
             difference: (0, PercentagePPM_1.ppmToPercentage)(this.pricingInfo.differencePPM)
         };
     }
+    //////////////////////////////
+    //// Getters & utils
     /**
+     * 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
      */
     checkSigner(signer) {
         if ((typeof (signer) === "string" ? signer : signer.getAddress()) !== this._getInitiator())
             throw new Error("Invalid signer provided!");
     }
-    isInitiated() {
-        return this.initiated;
-    }
+    /**
+     * Sets this swap as initiated
+     * @internal
+     */
     _setInitiated() {
         this.initiated = true;
     }
+    /**
+     * 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})
+     */
+    isInitiated() {
+        return this.initiated;
+    }
     /**
      * Returns quote expiry in UNIX millis
      */
@@ -209,10 +246,39 @@ class ISwap {
      * Returns the current state of the swap
      */
     getState() {
-        return this.state;
+        return this._state;
     }
     //////////////////////////////
     //// Storage
+    /**
+     * Saves the swap data to the underlying storage, or removes it if it is in a quote expired state
+     *
+     * @internal
+     */
+    _save() {
+        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) {
+        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.)
+     */
     serialize() {
         if (this.pricingInfo == null)
             return {};
@@ -228,7 +294,7 @@ 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),
@@ -237,25 +303,16 @@ class ISwap {
             initiated: this.initiated,
             exactIn: this.exactIn,
             createdAt: this.createdAt,
-            randomNonce: this.randomNonce
+            randomNonce: this._randomNonce
         };
     }
-    _save() {
-        if (this.isQuoteExpired()) {
-            return this.wrapper.removeSwapData(this);
-        }
-        else {
-            return this.wrapper.saveSwapData(this);
-        }
-    }
-    async _saveAndEmit(state) {
-        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);

package/dist/swaps/ISwapWithGasDrop.d.ts

@@ -3,13 +3,19 @@ import { TokenAmount } from "../types/TokenAmount";
 import { SCToken } from "../types/Token";
 /**
  * Type guard to check if a swap has gas drop functionality
+ *
  * @category Swaps
  */
 export declare 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"]>>;
 }

package/dist/swaps/ISwapWithGasDrop.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isSwapWithGasDrop = void 0;
 /**
  * Type guard to check if a swap has gas drop functionality
+ *
  * @category Swaps
  */
 function isSwapWithGasDrop(swap) {