@atomiqlabs/sdk 8.1.8 → 8.3.5

package/src/swaps/ISwapWrapper.ts

@@ -13,7 +13,8 @@ import {PriceInfoType} from "../types/PriceInfoType";
 
 /**
  * Options for swap wrapper configuration
- * @category Swaps
+ *
+ * @category Swaps/Base
  */
 export type ISwapWrapperOptions = {
     getRequestTimeout?: number,
@@ -22,7 +23,8 @@ export type ISwapWrapperOptions = {
 
 /**
  * Token configuration for wrapper constructors
- * @category Swaps
+ *
+ * @category Swaps/Base
  */
 export type WrapperCtorTokens<T extends MultiChain = MultiChain> = {
     ticker: string,
@@ -36,7 +38,8 @@ export type WrapperCtorTokens<T extends MultiChain = MultiChain> = {
 
 /**
  * Type definition linking wrapper and swap types
- * @category Swaps
+ *
+ * @category Swaps/Base
  */
 export type SwapTypeDefinition<T extends ChainType, W extends ISwapWrapper<T, any>, S extends ISwap<T>> = {
     Wrapper: W;
@@ -44,45 +47,105 @@ export type SwapTypeDefinition<T extends ChainType, W extends ISwapWrapper<T, an
 };
 
 /**
- * Base abstract class for swap wrapper implementations
- * @category Swaps
+ * Base abstract class for swap handler implementations
+ *
+ * @category Swaps/Base
  */
 export abstract class ISwapWrapper<
     T extends ChainType,
     D extends SwapTypeDefinition<T, ISwapWrapper<T, D>, ISwap<T, D>>,
     O extends ISwapWrapperOptions = ISwapWrapperOptions
 > {
+    /**
+     * Swap type
+     */
     abstract readonly TYPE: SwapType;
+    /**
+     * Function for deserializing swaps
+     * @internal
+     */
+    abstract readonly _swapDeserializer: new (wrapper: D["Wrapper"], data: any) => D["Swap"];
+
+
+    /**
+     * Logger instance
+     * @internal
+     */
     protected readonly logger = getLogger(this.constructor.name+": ");
+    /**
+     * Persistent storage backend for the swaps
+     * @internal
+     */
+    protected readonly unifiedStorage: UnifiedSwapStorage<T>;
+    /**
+     * Smart chain events listener for listening to and parsing of on-chain events
+     * @internal
+     */
+    protected readonly unifiedChainEvents: UnifiedSwapEventListener<T>;
+    /**
+     * States of the swaps where {@link ISwap._tick} should be called every second
+     * @internal
+     */
+    protected readonly tickSwapState?: Array<D["Swap"]["_state"]>;
+    /**
+     * In-memory mapping of pending (not initiated) swaps, utilizing weak references to automatically
+     *  free memory when swaps are dereferenced in not initiated state
+     * @internal
+     */
+    protected readonly pendingSwaps: Map<string, WeakRef<D["Swap"]>> = new Map();
+
 
-    public readonly abstract swapDeserializer: new (wrapper: D["Wrapper"], data: any) => D["Swap"];
+    /**
+     * Whether this wrapper is initialized (have to call {@link init} to initialize a wrapper)
+     * @internal
+     */
+    protected isInitialized: boolean = false;
+    /**
+     * An interval for calling tick functions on the underlying swaps
+     * @internal
+     */
+    protected tickInterval?: NodeJS.Timeout;
 
-    readonly unifiedStorage: UnifiedSwapStorage<T>;
-    readonly unifiedChainEvents: UnifiedSwapEventListener<T>;
 
-    readonly chainIdentifier: T["ChainId"];
-    readonly chain: T["ChainInterface"];
-    readonly prices: ISwapPrice;
-    readonly events: EventEmitter<{swapState: [D["Swap"]]}>;
-    readonly options: O;
-    readonly tokens: {
+    /**
+     * States of the swaps in pending (non-final state), these are checked automatically on initial swap synchronization
+     * @internal
+     */
+    abstract readonly _pendingSwapStates: Array<D["Swap"]["_state"]>;
+    /**
+     * Chain interface of the underlying smart chain
+     * @internal
+     */
+    readonly _chain: T["ChainInterface"];
+    /**
+     * Pricing API
+     * @internal
+     */
+    readonly _prices: ISwapPrice;
+    /**
+     * Wrapper options
+     * @internal
+     */
+    readonly _options: O;
+    /**
+     * Tokens indexed by their token address
+     * @internal
+     */
+    readonly _tokens: {
         [tokenAddress: string]: SCToken<T["ChainId"]>
     };
-    readonly pendingSwaps: Map<string, WeakRef<D["Swap"]>> = new Map();
 
-    isInitialized: boolean = false;
-    tickInterval?: NodeJS.Timeout;
 
     /**
-     * @param chainIdentifier
-     * @param unifiedStorage
-     * @param unifiedChainEvents
-     * @param chain
-     * @param prices Swap pricing handler
-     * @param tokens Chain specific token data
-     * @param options
-     * @param events Instance to use for emitting events
+     * Chain identifier string of this wrapper
+     */
+    readonly chainIdentifier: T["ChainId"];
+    /**
+     * Event emitter emitting `"swapState"` event when swap's state changes
      */
+    readonly events: EventEmitter<{swapState: [D["Swap"]]}>;
+
+
     constructor(
         chainIdentifier: T["ChainId"],
         unifiedStorage: UnifiedSwapStorage<T>,
@@ -97,15 +160,15 @@ export abstract class ISwapWrapper<
         this.unifiedChainEvents = unifiedChainEvents;
 
         this.chainIdentifier = chainIdentifier;
-        this.chain = chain;
-        this.prices = prices;
+        this._chain = chain;
+        this._prices = prices;
         this.events = events || new EventEmitter();
-        this.options = options;
-        this.tokens = {};
+        this._options = options;
+        this._tokens = {};
         for(let tokenData of tokens) {
             const chainData = tokenData.chains[chainIdentifier];
             if(chainData==null) continue;
-            this.tokens[chainData.address] = {
+            this._tokens[chainData.address] = {
                 chain: "SC",
                 chainId: this.chainIdentifier,
                 address: chainData.address,
@@ -117,16 +180,17 @@ export abstract class ISwapWrapper<
         }
     }
 
+
     /**
      * Pre-fetches swap price for a given swap
      *
-     * @param amountData
-     * @param abortSignal
-     * @protected
+     * @param amountData Amount data
+     * @param abortSignal Abort signal
      * @returns Price of the token in uSats (micro sats)
+     * @internal
      */
     protected preFetchPrice(amountData: { token: string }, abortSignal?: AbortSignal): Promise<bigint | undefined> {
-        return this.prices.preFetchPrice(this.chainIdentifier, amountData.token, abortSignal).catch(e => {
+        return this._prices.preFetchPrice(this.chainIdentifier, amountData.token, abortSignal).catch(e => {
             this.logger.error("preFetchPrice.token(): Error: ", e);
             return undefined;
         });
@@ -135,31 +199,32 @@ export abstract class ISwapWrapper<
     /**
      * Pre-fetches bitcoin's USD price
      *
-     * @param abortSignal
-     * @protected
+     * @param abortSignal Abort signal
+     * @internal
      */
     protected preFetchUsdPrice(abortSignal?: AbortSignal): Promise<number | undefined> {
-        return this.prices.preFetchUsdPrice(abortSignal).catch(e => {
+        return this._prices.preFetchUsdPrice(abortSignal).catch(e => {
             this.logger.error("preFetchPrice.usd(): Error: ", e);
             return undefined;
         })
     }
 
     /**
-     * Verifies returned  price for swaps
+     * Verifies returned price for swaps
      *
      * @param lpServiceData Service data for the service in question (TO_BTCLN, TO_BTC, etc.) of the given intermediary
-     * @param send Whether this is a send (SOL -> SC) or receive (BTC -> SC) swap
+     * @param send Whether this is a send (Smart chain -> Bitcoin) or receive (Bitcoin -> Smart chain) swap
      * @param amountSats Amount in BTC
      * @param amountToken Amount in token
      * @param token Token used in the swap
      * @param feeData Fee data as returned by the intermediary
-     * @param pricePrefetchPromise Price pre-fetch promise
-     * @param usdPricePrefetchPromise
-     * @param abortSignal
-     * @protected
+     * @param pricePrefetchPromise Optional price pre-fetch promise
+     * @param usdPricePrefetchPromise Optiona USD price pre-fetch promise
+     * @param abortSignal Abort signal
      * @returns Price info object
      * @throws {IntermediaryError} if the calculated fee is too high
+     *
+     * @internal
      */
     protected async verifyReturnedPrice(
         lpServiceData: {swapBaseFee: number, swapFeePPM: number},
@@ -180,11 +245,11 @@ export abstract class ISwapWrapper<
 
         const [isValidAmount, usdPrice] = await Promise.all([
             send ?
-                this.prices.isValidAmountSend(this.chainIdentifier, amountSats, swapBaseFee, swapFeePPM, amountToken, token, abortSignal, await pricePrefetchPromise) :
-                this.prices.isValidAmountReceive(this.chainIdentifier, amountSats, swapBaseFee, swapFeePPM, amountToken, token, abortSignal, await pricePrefetchPromise),
+                this._prices.isValidAmountSend(this.chainIdentifier, amountSats, swapBaseFee, swapFeePPM, amountToken, token, abortSignal, await pricePrefetchPromise) :
+                this._prices.isValidAmountReceive(this.chainIdentifier, amountSats, swapBaseFee, swapFeePPM, amountToken, token, abortSignal, await pricePrefetchPromise),
             usdPricePrefetchPromise.then(value => {
                 if(value!=null) return value;
-                return this.prices.preFetchUsdPrice(abortSignal);
+                return this._prices.preFetchUsdPrice(abortSignal);
             })
         ]);
         if(!isValidAmount.isValid) throw new IntermediaryError("Fee too high");
@@ -193,19 +258,58 @@ export abstract class ISwapWrapper<
         return isValidAmount;
     }
 
-    public abstract readonly pendingSwapStates: Array<D["Swap"]["state"]>;
-    public abstract readonly tickSwapState?: Array<D["Swap"]["state"]>;
-
     /**
-     * Processes a single SC on-chain event
-     * @private
-     * @param event
-     * @param swap
+     * Processes a single smart chain on-chain event
+     *
+     * @param event Smart chain event to process
+     * @param swap A swap related to the event
+     * @internal
      */
     protected abstract processEvent?(event: ChainEvent<T["Data"]>, swap: D["Swap"]): Promise<void>;
 
+    /**
+     * Starts the interval calling the {@link ISwap._tick} on all the known swaps in tick-enabled states
+     * @internal
+     */
+    protected startTickInterval(): void {
+        if(this.tickSwapState==null || this.tickSwapState.length===0) return;
+        this.tickInterval = setInterval(() => {
+            this.tick();
+        }, 1000);
+    }
+
+    /**
+     * Runs checks on passed swaps, syncing their state from on-chain data
+     *
+     * @param pastSwaps Swaps to check
+     * @internal
+     */
+    protected async _checkPastSwaps(pastSwaps: D["Swap"][]): Promise<{changedSwaps: D["Swap"][], removeSwaps: D["Swap"][]}> {
+        const changedSwaps: D["Swap"][] = [];
+        const removeSwaps: D["Swap"][] = [];
+
+        await Promise.all(pastSwaps.map((swap: D["Swap"]) =>
+            swap._sync(false).then(changed => {
+                if(swap.isQuoteExpired()) {
+                    removeSwaps.push(swap);
+                    this.logger.debug("_checkPastSwaps(): Removing expired swap: "+swap.getId());
+                } else {
+                    if(changed) changedSwaps.push(swap);
+                }
+            }).catch(e => this.logger.error("_checkPastSwaps(): Error when checking swap "+swap.getId()+": ", e))
+        ));
+
+        return {changedSwaps, removeSwaps};
+    }
+
+
     /**
      * Initializes the swap wrapper, needs to be called before any other action can be taken
+     *
+     * @param noTimers Whether to skip scheduling a tick timer for the swaps, if the tick timer is not initiated
+     *  the swap states depending on e.g. expiry can be out of sync with the actual expiration of the swap
+     * @param noCheckPastSwaps Whether to skip checking past swaps on initialization (by default all pending swaps
+     *  are re-checked on init, and their state is synchronized from the on-chain data)
      */
     public async init(noTimers: boolean = false, noCheckPastSwaps: boolean = false): Promise<void> {
         if(this.isInitialized) return;
@@ -221,7 +325,7 @@ export abstract class ISwapWrapper<
                 eventQueue.push({event, swap});
                 return Promise.resolve();
             }
-            if(this.processEvent!=null) this.unifiedChainEvents.registerListener(this.TYPE, initListener, this.swapDeserializer.bind(null, this));
+            if(this.processEvent!=null) this.unifiedChainEvents.registerListener(this.TYPE, initListener, this._swapDeserializer.bind(null, this));
 
             await this.checkPastSwaps();
 
@@ -236,7 +340,7 @@ export abstract class ISwapWrapper<
             }
         }
 
-        if(this.processEvent!=null) this.unifiedChainEvents.registerListener(this.TYPE, this.processEvent.bind(this), this.swapDeserializer.bind(null, this));
+        if(this.processEvent!=null) this.unifiedChainEvents.registerListener(this.TYPE, this.processEvent.bind(this), this._swapDeserializer.bind(null, this));
 
         if(!noTimers) this.startTickInterval();
 
@@ -245,35 +349,27 @@ export abstract class ISwapWrapper<
         this.isInitialized = true;
     }
 
-    protected startTickInterval(): void {
-        if(this.tickSwapState==null || this.tickSwapState.length===0) return;
-        this.tickInterval = setInterval(() => {
-            this.tick();
-        }, 1000);
-    }
-
-    protected async _checkPastSwaps(pastSwaps: D["Swap"][]): Promise<{changedSwaps: D["Swap"][], removeSwaps: D["Swap"][]}> {
-        const changedSwaps: D["Swap"][] = [];
-        const removeSwaps: D["Swap"][] = [];
-
-        await Promise.all(pastSwaps.map((swap: D["Swap"]) =>
-            swap._sync(false).then(changed => {
-                if(swap.isQuoteExpired()) {
-                    removeSwaps.push(swap);
-                    this.logger.debug("_checkPastSwaps(): Removing expired swap: "+swap.getId());
-                } else {
-                    if(changed) changedSwaps.push(swap);
-                }
-            }).catch(e => this.logger.error("_checkPastSwaps(): Error when checking swap "+swap.getId()+": ", e))
-        ));
-
-        return {changedSwaps, removeSwaps};
+    /**
+     * Un-subscribes from event listeners on the smart chain, terminates the tick interval and stops this wrapper
+     */
+    public async stop() {
+        this.isInitialized = false;
+        this.unifiedChainEvents.unregisterListener(this.TYPE);
+        this.logger.info("stop(): Swap wrapper stopped");
+        if(this.tickInterval!=null) clearInterval(this.tickInterval);
     }
 
-    async checkPastSwaps(pastSwaps?: D["Swap"][], noSave?: boolean): Promise<{ removeSwaps: D["Swap"][], changedSwaps: D["Swap"][] }> {
+    /**
+     * Runs checks on all the known pending swaps, syncing their state from on-chain data
+     *
+     * @param pastSwaps Optional array of past swaps to check, otherwise all relevant swaps will be fetched
+     *  from the persistent storage
+     * @param noSave Whether to skip saving the swap changes in the persistent storage
+     */
+    public async checkPastSwaps(pastSwaps?: D["Swap"][], noSave?: boolean): Promise<{ removeSwaps: D["Swap"][], changedSwaps: D["Swap"][] }> {
         if (pastSwaps == null) pastSwaps = await this.unifiedStorage.query<D["Swap"]>(
-            [[{key: "type", value: this.TYPE}, {key: "state", value: this.pendingSwapStates}]],
-            (val: any) => new this.swapDeserializer(this, val)
+            [[{key: "type", value: this.TYPE}, {key: "state", value: this._pendingSwapStates}]],
+            (val: any) => new this._swapDeserializer(this, val)
         );
 
         const {removeSwaps, changedSwaps} = await this._checkPastSwaps(pastSwaps);
@@ -291,10 +387,16 @@ export abstract class ISwapWrapper<
         }
     }
 
-    async tick(swaps?: D["Swap"][]): Promise<void> {
+    /**
+     * Invokes {@link ISwap._tick} on all the known swaps
+     *
+     * @param swaps Optional array of swaps to invoke `_tick()` on, otherwise all relevant swaps will be fetched
+     *  from the persistent storage
+     */
+    public async tick(swaps?: D["Swap"][]): Promise<void> {
         if(swaps==null) swaps = await this.unifiedStorage.query<D["Swap"]>(
             [[{key: "type", value: this.TYPE}, {key: "state", value: this.tickSwapState}]],
-            (val: any) => new this.swapDeserializer(this, val)
+            (val: any) => new this._swapDeserializer(this, val)
         );
 
         for(let pendingSwap of this.pendingSwaps.values()) {
@@ -307,7 +409,22 @@ export abstract class ISwapWrapper<
         });
     }
 
-    saveSwapData(swap: D["Swap"]): Promise<void> {
+    /**
+     * Returns the smart chain's native token used to pay for fees
+     * @internal
+     */
+    _getNativeToken(): SCToken<T["ChainId"]> {
+        return this._tokens[this._chain.getNativeCurrencyAddress()];
+    }
+
+    /**
+     * Saves the swap, if it is not initiated it is only saved to pending swaps
+     *
+     * @param swap Swap to save
+     *
+     * @internal
+     */
+    _saveSwapData(swap: D["Swap"]): Promise<void> {
         if(!swap.isInitiated()) {
             this.logger.debug("saveSwapData(): Swap "+swap.getId()+" not initiated, saving to pending swaps");
             this.pendingSwaps.set(swap.getId(), new WeakRef<D["Swap"]>(swap));
@@ -318,27 +435,28 @@ export abstract class ISwapWrapper<
         return this.unifiedStorage.save(swap);
     }
 
-    removeSwapData(swap: D["Swap"]): Promise<void> {
+    /**
+     * Removes the swap from the persistent storage and pending swaps
+     *
+     * @param swap Swap to remove
+     *
+     * @internal
+     */
+    _removeSwapData(swap: D["Swap"]): Promise<void> {
         this.pendingSwaps.delete(swap.getId());
         if(!swap.isInitiated()) return Promise.resolve();
         return this.unifiedStorage.remove(swap);
     }
 
     /**
-     * Un-subscribes from event listeners on Solana
-     */
-    public async stop() {
-        this.isInitialized = false;
-        this.unifiedChainEvents.unregisterListener(this.TYPE);
-        this.logger.info("stop(): Swap wrapper stopped");
-        if(this.tickInterval!=null) clearInterval(this.tickInterval);
-    }
-
-    /**
-     * Returns the smart chain's native token used to pay for fees
+     * Retrieves a swap by its ID from the pending swap mapping
+     *
+     * @param id
+     *
+     * @internal
      */
-    public getNativeToken(): SCToken<T["ChainId"]> {
-        return this.tokens[this.chain.getNativeCurrencyAddress()];
+    _getPendingSwap(id: string): D["Swap"] | null {
+        return this.pendingSwaps.get(id)?.deref() ?? null;
     }
 
 }

package/src/swaps/escrow_swaps/IEscrowSelfInitSwap.ts

@@ -25,14 +25,29 @@ export function isIEscrowSelfInitSwapInit<T extends SwapData>(obj: any): obj is
 
 export type IEscrowSelfInitSwapDefinition<T extends ChainType, W extends IEscrowSwapWrapper<T, any>, S extends IEscrowSelfInitSwap<T>> = SwapTypeDefinition<T, W, S>;
 
+/**
+ * Base class for escrow-based swaps (i.e. swaps utilizing PrTLC and HTLC primitives) where the
+ *  user needs to initiate the escrow on the smart chain side
+ *
+ * @category Swaps/Abstract
+ */
 export abstract class IEscrowSelfInitSwap<
     T extends ChainType = ChainType,
     D extends IEscrowSelfInitSwapDefinition<T, IEscrowSwapWrapper<T, D>, IEscrowSelfInitSwap<T, D, S>> = IEscrowSwapDefinition<T, IEscrowSwapWrapper<T, any>, IEscrowSelfInitSwap<T, any, any>>,
     S extends number = number
 > extends IEscrowSwap<T, D, S> {
 
-    feeRate: string;
-    signatureData?: SignatureData;
+    /**
+     * Fee rate to be used for the escrow initiation transaction
+     * @internal
+     */
+    protected readonly feeRate: string;
+    /**
+     * Signature data received from the intermediary (LP) allowing the user
+     *  to initiate the swap escrow
+     * @internal
+     */
+    protected signatureData?: SignatureData;
 
     protected constructor(wrapper: D["Wrapper"], obj: any);
     protected constructor(wrapper: D["Wrapper"], swapInit: IEscrowSelfInitSwapInit<T["Data"]>);
@@ -63,10 +78,10 @@ export abstract class IEscrowSelfInitSwap<
      *
      * @param intervalSeconds How often to check (in seconds), default to 5s
      * @param abortSignal
-     * @protected
+     * @internal
      */
     protected async watchdogWaitTillSignatureExpiry(intervalSeconds?: number, abortSignal?: AbortSignal): Promise<void> {
-        if(this.data==null || this.signatureData==null)
+        if(this._data==null || this.signatureData==null)
             throw new Error("Tried to await signature expiry but data or signature is null, invalid state?");
 
         intervalSeconds ??= 5;
@@ -74,7 +89,7 @@ export abstract class IEscrowSelfInitSwap<
         while(!expired) {
             await timeoutPromise(intervalSeconds*1000, abortSignal);
             try {
-                expired = await this.wrapper.contract.isInitAuthorizationExpired(this.data, this.signatureData);
+                expired = await this.wrapper._contract.isInitAuthorizationExpired(this._data, this.signatureData);
             } catch (e) {
                 this.logger.error("watchdogWaitTillSignatureExpiry(): Error when checking signature expiry: ", e);
             }
@@ -88,29 +103,31 @@ export abstract class IEscrowSelfInitSwap<
 
     /**
      * Get the estimated smart chain fee of the commit transaction
+     * @internal
      */
     protected getCommitFee(): Promise<bigint> {
-        return this.wrapper.contract.getCommitFee(this._getInitiator(), this.getSwapData(), this.feeRate);
+        return this.wrapper._contract.getCommitFee(this._getInitiator(), this.getSwapData(), this.feeRate);
     }
 
     /**
-     * Returns the transaction fee paid on the smart chain
+     * Returns the transaction fee paid on the smart chain side to initiate the escrow
      */
     async getSmartChainNetworkFee(): Promise<TokenAmount<T["ChainId"], SCToken<T["ChainId"]>, true>> {
-        const swapContract: T["Contract"] = this.wrapper.contract;
+        const swapContract: T["Contract"] = this.wrapper._contract;
         return toTokenAmount(
             await (
                 swapContract.getRawCommitFee!=null ?
                     swapContract.getRawCommitFee(this._getInitiator(), this.getSwapData(), this.feeRate) :
                     swapContract.getCommitFee(this._getInitiator(), this.getSwapData(), this.feeRate)
             ),
-            this.wrapper.getNativeToken(),
-            this.wrapper.prices
+            this.wrapper._getNativeToken(),
+            this.wrapper._prices
         );
     }
 
     /**
-     * Checks if the initiator/sender has enough balance to cover the transaction fee for processing the swap
+     * Checks if the initiator/sender has enough balance on the smart chain side
+     *  to cover the transaction fee for processing the swap
      */
     abstract hasEnoughForTxFees(): Promise<{
         enoughBalance: boolean,
@@ -122,9 +139,35 @@ export abstract class IEscrowSelfInitSwap<
     //////////////////////////////
     //// Commit and claim
 
+    /**
+     * Returns transactions for initiating (committing) the escrow on the smart chain side. After sending the
+     *  transactions manually be sure to call the {@link waitTillCommited} function to wait till the initiation
+     *  transaction is observed, processed by the SDK and state of the swap properly updated.
+     *
+     * @param 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`)
+     */
     abstract txsCommit(skipChecks?: boolean): Promise<T["TX"][]>;
+
+    /**
+     * Initiates (commits) the escrow on the smart chain side
+     *
+     * @param _signer Signer to sign the transactions with, must be the same as used in the initialization
+     * @param abortSignal Abort signal
+     * @param 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 onBeforeTxSent Callback called before the transactions are broadcasted
+     */
     abstract commit(_signer: T["Signer"] | T["NativeSigner"], abortSignal?: AbortSignal, skipChecks?: boolean, onBeforeTxSent?: (txId: string) => void): Promise<string>;
 
+    /**
+     * Waits till a swap is initiated (committed) on-chain, should be called after sending the commit
+     *  transactions ({@link txsCommit}) manually to wait till the SDK processes the escrow
+     *  initialization and updates the swap state accordingly
+     *
+     * @param abortSignal AbortSignal
+     */
+    abstract waitTillCommited(abortSignal?: AbortSignal): Promise<void>
 
     //////////////////////////////
     //// Quote verification
@@ -133,22 +176,22 @@ export abstract class IEscrowSelfInitSwap<
      * Checks if the swap's quote is expired for good (i.e. the swap strictly cannot be committed on-chain anymore)
      */
     async _verifyQuoteDefinitelyExpired(): Promise<boolean> {
-        if(this.data==null || this.signatureData==null) throw new Error("data or signature data are null!");
+        if(this._data==null || this.signatureData==null) throw new Error("data or signature data are null!");
 
-        return this.wrapper.contract.isInitAuthorizationExpired(
-            this.data!, this.signatureData!
+        return this.wrapper._contract.isInitAuthorizationExpired(
+            this._data!, this.signatureData!
         );
     }
 
     /**
      * Checks if the swap's quote is still valid
      */
-    async verifyQuoteValid(): Promise<boolean> {
-        if(this.data==null || this.signatureData==null) throw new Error("data or signature data are null!");
+    async _verifyQuoteValid(): Promise<boolean> {
+        if(this._data==null || this.signatureData==null) throw new Error("data or signature data are null!");
 
         try {
-            await this.wrapper.contract.isValidInitAuthorization(
-                this._getInitiator(), this.data!, this.signatureData!, this.feeRate
+            await this.wrapper._contract.isValidInitAuthorization(
+                this._getInitiator(), this._data!, this.signatureData!, this.feeRate
             );
             return true;
         } catch (e) {
@@ -159,6 +202,9 @@ export abstract class IEscrowSelfInitSwap<
         }
     }
 
+    /**
+     * @inheritDoc
+     */
     serialize(): any {
         return {
             ...super.serialize(),