@atomiqlabs/sdk 8.1.8 → 8.3.5

package/src/swaps/escrow_swaps/IEscrowSwap.ts

@@ -22,20 +22,33 @@ export function isIEscrowSwapInit<T extends SwapData>(obj: any): obj is IEscrowS
         isISwapInit(obj);
 }
 
+/**
+ * Base class for escrow-based swaps (i.e. swaps utilizing PrTLC and HTLC primitives)
+ *
+ * @category Swaps/Abstract
+ */
 export abstract class IEscrowSwap<
     T extends ChainType = ChainType,
     D extends IEscrowSwapDefinition<T, IEscrowSwapWrapper<T, D>, IEscrowSwap<T, D, S>> = IEscrowSwapDefinition<T, IEscrowSwapWrapper<T, any>, IEscrowSwap<T, any, any>>,
     S extends number = number
 > extends ISwap<T, D, S> {
-
-    data?: T["Data"];
-
+    /**
+     * @internal
+     */
+    _data?: T["Data"];
     /**
      * Transaction IDs for the swap on the smart chain side
+     * @internal
      */
-    commitTxId?: string;
-    refundTxId?: string;
-    claimTxId?: string;
+    _commitTxId?: string;
+    /**
+     * @internal
+     */
+    _refundTxId?: string;
+    /**
+     * @internal
+     */
+    _claimTxId?: string;
 
     protected constructor(wrapper: D["Wrapper"], obj: any);
     protected constructor(wrapper: D["Wrapper"], swapInit: IEscrowSwapInit<T["Data"]>);
@@ -46,16 +59,21 @@ export abstract class IEscrowSwap<
         super(wrapper, swapInitOrObj);
 
         if(isIEscrowSwapInit(swapInitOrObj)) {
-            this.data = swapInitOrObj.data;
+            this._data = swapInitOrObj.data;
         } else {
-            if(swapInitOrObj.data!=null) this.data = new wrapper.swapDataDeserializer(swapInitOrObj.data);
+            if(swapInitOrObj.data!=null) this._data = new wrapper._swapDataDeserializer(swapInitOrObj.data);
 
-            this.commitTxId = swapInitOrObj.commitTxId;
-            this.claimTxId = swapInitOrObj.claimTxId;
-            this.refundTxId = swapInitOrObj.refundTxId;
+            this._commitTxId = swapInitOrObj.commitTxId;
+            this._claimTxId = swapInitOrObj.claimTxId;
+            this._refundTxId = swapInitOrObj.refundTxId;
         }
     }
 
+    /**
+     * Returns the swap escrow data for this swap
+     *
+     * @internal
+     */
     protected abstract getSwapData(): T["Data"];
 
     //////////////////////////////
@@ -64,24 +82,32 @@ export abstract class IEscrowSwap<
     /**
      * Returns the identification hash of the swap, usually claim data hash, but can be overriden, e.g. for
      *  lightning swaps the identifier hash is used instead of claim data hash
+     *
+     * @internal
      */
     protected getIdentifierHash(): Buffer {
         const claimHashBuffer = Buffer.from(this.getClaimHash(), "hex");
-        if(this.randomNonce==null) return claimHashBuffer;
-        return Buffer.concat([claimHashBuffer, Buffer.from(this.randomNonce, "hex")]);
+        if(this._randomNonce==null) return claimHashBuffer;
+        return Buffer.concat([claimHashBuffer, Buffer.from(this._randomNonce, "hex")]);
     }
 
     /**
      * Returns the identification hash of the swap, usually claim data hash, but can be overriden, e.g. for
      *  lightning swaps the identifier hash is used instead of claim data hash
+     *
+     * @internal
      */
     protected getIdentifierHashString(): string {
         const identifierHash = this.getIdentifierHash();
         return identifierHash.toString("hex");
     }
 
+    /**
+     * @inheritDoc
+     * @internal
+     */
     _getEscrowHash(): string | null {
-        return this.data?.getEscrowHash() ?? null;
+        return this._data?.getEscrowHash() ?? null;
     }
 
     /**
@@ -92,12 +118,15 @@ export abstract class IEscrowSwap<
     }
 
     /**
-     * Returns the claim data hash - i.e. hash passed to the claim handler
+     * Returns the claim data hash specifying the claim path of the escrow - i.e. hash passed to the claim handler
      */
     getClaimHash(): string {
         return this.getSwapData().getClaimHash();
     }
 
+    /**
+     * @inheritDoc
+     */
     getId(): string {
         return this.getIdentifierHashString();
     }
@@ -111,17 +140,17 @@ export abstract class IEscrowSwap<
      *
      * @param intervalSeconds How often to check (in seconds), default to 5s
      * @param abortSignal
-     * @protected
+     * @internal
      */
     protected async watchdogWaitTillCommited(intervalSeconds?: number, abortSignal?: AbortSignal): Promise<boolean> {
-        if(this.data==null) throw new Error("Tried to await commitment but data is null, invalid state?");
+        if(this._data==null) throw new Error("Tried to await commitment but data is null, invalid state?");
 
         intervalSeconds ??= 5;
         let status: SwapCommitState = {type: SwapCommitStateType.NOT_COMMITED};
         while(status?.type===SwapCommitStateType.NOT_COMMITED) {
             await timeoutPromise(intervalSeconds*1000, abortSignal);
             try {
-                status = await this.wrapper.contract.getCommitStatus(this._getInitiator(), this.data);
+                status = await this.wrapper._contract.getCommitStatus(this._getInitiator(), this._data);
                 if(
                     status?.type===SwapCommitStateType.NOT_COMMITED &&
                     await this._verifyQuoteDefinitelyExpired()
@@ -139,19 +168,19 @@ export abstract class IEscrowSwap<
      *
      * @param intervalSeconds How often to check (in seconds), default to 5s
      * @param abortSignal
-     * @protected
+     * @internal
      */
     protected async watchdogWaitTillResult(intervalSeconds?: number, abortSignal?: AbortSignal): Promise<
         SwapPaidState | SwapExpiredState | SwapNotCommitedState
     > {
-        if(this.data==null) throw new Error("Tried to await result but data is null, invalid state?");
+        if(this._data==null) throw new Error("Tried to await result but data is null, invalid state?");
 
         intervalSeconds ??= 5;
         let status: SwapCommitState = {type: SwapCommitStateType.COMMITED};
         while(status?.type===SwapCommitStateType.COMMITED || status?.type===SwapCommitStateType.REFUNDABLE) {
             await timeoutPromise(intervalSeconds*1000, abortSignal);
             try {
-                status = await this.wrapper.contract.getCommitStatus(this._getInitiator(), this.data);
+                status = await this.wrapper._contract.getCommitStatus(this._getInitiator(), this._data);
             } catch (e) {
                 this.logger.error("watchdogWaitTillResult(): Error when fetching commit status: ", e);
             }
@@ -162,35 +191,52 @@ export abstract class IEscrowSwap<
 
 
     //////////////////////////////
-    //// Quote verification
+    //// Helpers for batched swap checks
 
     /**
-     * Checks if the swap's quote is expired for good (i.e. the swap strictly cannot be committed on-chain anymore)
+     * Whether on-chain state should be fetched for this swap
+     * @internal
      */
-    abstract _verifyQuoteDefinitelyExpired(): Promise<boolean>;
+    abstract _shouldFetchOnchainState(): boolean;
 
     /**
-     * Checks if the swap's quote is still valid
+     * Whether expiration status of the swap quote should be checked for this swap
+     * @internal
      */
-    abstract verifyQuoteValid(): Promise<boolean>;
-
-
-    //////////////////////////////
-    //// Helpers for batched swap checks
-
-    abstract _shouldFetchCommitStatus(): boolean;
-
     abstract _shouldFetchExpiryStatus(): boolean;
 
+    /**
+     * @inheritDoc
+     *
+     * @param save Whether to save the new swap state or not
+     * @param quoteDefinitelyExpired Optionally pass whether the quote is definitely expired from a batch pre-fetch,
+     *  fetched on-demand if not provided
+     * @param commitStatus Optionally pass the quote on-chain state from a batch pre-fetch, fetched on-demand if
+     *  not provided
+     *
+     * @internal
+     */
     abstract _sync(save?: boolean, quoteDefinitelyExpired?: boolean, commitStatus?: SwapCommitState): Promise<boolean>;
 
+    /**
+     * Forcibly overrides current swap state from fetched on-chain swap state
+     *
+     * @param commitStatus Swap state fetched from the smart chain
+     *
+     * @internal
+     */
+    abstract _forciblySetOnchainState(commitStatus: SwapCommitState): Promise<boolean>;
+
+    /**
+     * @inheritDoc
+     */
     serialize(): any {
         return {
             ...super.serialize(),
-            data: this.data!=null ? this.data.serialize() : null,
-            commitTxId: this.commitTxId,
-            claimTxId: this.claimTxId,
-            refundTxId: this.refundTxId
+            data: this._data!=null ? this._data.serialize() : null,
+            commitTxId: this._commitTxId,
+            claimTxId: this._claimTxId,
+            refundTxId: this._refundTxId
         }
     };
 

package/src/swaps/escrow_swaps/IEscrowSwapWrapper.ts

@@ -5,7 +5,6 @@ import {
     InitializeEvent,
     RefundEvent,
     SignatureData,
-    SignatureVerificationError,
     SwapCommitState,
     SwapEvent
 } from "@atomiqlabs/base";
@@ -20,6 +19,11 @@ import {Intermediary} from "../../intermediaries/Intermediary";
 
 export type IEscrowSwapDefinition<T extends ChainType, W extends IEscrowSwapWrapper<T, any>, S extends IEscrowSwap<T>> = SwapTypeDefinition<T, W, S>;
 
+/**
+ * Base class for wrappers of escrow-based swaps (i.e. swaps utilizing PrTLC and HTLC primitives)
+ *
+ * @category Swaps/Abstract
+ */
 export abstract class IEscrowSwapWrapper<
     T extends ChainType,
     D extends IEscrowSwapDefinition<T, IEscrowSwapWrapper<T, D>, IEscrowSwap<T, D>>,
@@ -27,8 +31,14 @@ export abstract class IEscrowSwapWrapper<
 > extends ISwapWrapper<T, D, O> {
     readonly abstract TYPE: SwapType;
 
-    readonly contract: T["Contract"];
-    readonly swapDataDeserializer: new (data: any) => T["Data"];
+    /**
+     * @internal
+     */
+    readonly _contract: T["Contract"];
+    /**
+     * @internal
+     */
+    readonly _swapDataDeserializer: new (data: any) => T["Data"];
 
     constructor(
         chainIdentifier: string,
@@ -43,22 +53,23 @@ export abstract class IEscrowSwapWrapper<
         events?: EventEmitter<{swapState: [ISwap]}>
     ) {
         super(chainIdentifier, unifiedStorage, unifiedChainEvents, chain, prices, tokens, options, events);
-        this.swapDataDeserializer = swapDataDeserializer;
-        this.contract = contract;
+        this._swapDataDeserializer = swapDataDeserializer;
+        this._contract = contract;
     }
 
     /**
      * Pre-fetches signature verification data from the server's pre-sent promise, doesn't throw, instead returns null
      *
      * @param signDataPrefetch Promise that resolves when we receive "signDataPrefetch" from the LP in streaming mode
-     * @protected
      * @returns Pre-fetched signature verification data or null if failed
+     *
+     * @internal
      */
     protected preFetchSignData(signDataPrefetch: Promise<any | null>): Promise<T["PreFetchVerification"] | undefined> {
-        if(this.contract.preFetchForInitSignatureVerification==null) return Promise.resolve(undefined);
+        if(this._contract.preFetchForInitSignatureVerification==null) return Promise.resolve(undefined);
         return signDataPrefetch.then(obj => {
             if(obj==null) return undefined;
-            return this.contract.preFetchForInitSignatureVerification!(obj);
+            return this._contract.preFetchForInitSignatureVerification!(obj);
         }).catch(e => {
             this.logger.error("preFetchSignData(): Error: ", e);
         });
@@ -73,9 +84,10 @@ export abstract class IEscrowSwapWrapper<
      * @param feeRatePromise Pre-fetched fee rate promise
      * @param preFetchSignatureVerificationData Pre-fetched signature verification data
      * @param abortSignal
-     * @protected
      * @returns Swap initialization signature expiry
      * @throws {SignatureVerificationError} when swap init signature is invalid
+     *
+     * @internal
      */
     protected async verifyReturnedSignature(
         initiator: string,
@@ -86,16 +98,17 @@ export abstract class IEscrowSwapWrapper<
         abortSignal?: AbortSignal
     ): Promise<number> {
         const [feeRate, preFetchedSignatureData] = await Promise.all([feeRatePromise, preFetchSignatureVerificationData]);
-        await this.contract.isValidInitAuthorization(initiator, data, signature, feeRate, preFetchedSignatureData);
-        return await this.contract.getInitAuthorizationExpiry(data, signature, preFetchedSignatureData);
+        await this._contract.isValidInitAuthorization(initiator, data, signature, feeRate, preFetchedSignatureData);
+        return await this._contract.getInitAuthorizationExpiry(data, signature, preFetchedSignatureData);
     }
 
     /**
      * Processes InitializeEvent for a given swap
      * @param swap
      * @param event
-     * @protected
      * @returns Whether the swap was updated/changed
+     *
+     * @internal
      */
     protected abstract processEventInitialize(swap: D["Swap"], event: InitializeEvent<T["Data"]>): Promise<boolean>;
 
@@ -103,8 +116,9 @@ export abstract class IEscrowSwapWrapper<
      * Processes ClaimEvent for a given swap
      * @param swap
      * @param event
-     * @protected
      * @returns Whether the swap was updated/changed
+     *
+     * @internal
      */
     protected abstract processEventClaim(swap: D["Swap"], event: ClaimEvent<T["Data"]>): Promise<boolean>;
 
@@ -112,16 +126,18 @@ export abstract class IEscrowSwapWrapper<
      * Processes RefundEvent for a given swap
      * @param swap
      * @param event
-     * @protected
      * @returns Whether the swap was updated/changed
+     *
+     * @internal
      */
     protected abstract processEventRefund(swap: D["Swap"], event: RefundEvent<T["Data"]>): Promise<boolean>;
 
     /**
      * Processes a single SC on-chain event
-     * @private
      * @param event
      * @param swap
+     *
+     * @internal
      */
     protected async processEvent(event: SwapEvent<T["Data"]>, swap: D["Swap"]): Promise<void> {
         if(swap==null) return;
@@ -129,22 +145,22 @@ export abstract class IEscrowSwapWrapper<
         let swapChanged: boolean = false;
         if(event instanceof InitializeEvent) {
             swapChanged = await this.processEventInitialize(swap, event);
-            if(event.meta?.txId!=null && swap.commitTxId!==event.meta.txId) {
-                swap.commitTxId = event.meta.txId;
+            if(event.meta?.txId!=null && swap._commitTxId!==event.meta.txId) {
+                swap._commitTxId = event.meta.txId;
                 swapChanged ||= true;
             }
         }
         if(event instanceof ClaimEvent) {
             swapChanged = await this.processEventClaim(swap, event);
-            if(event.meta?.txId!=null && swap.claimTxId!==event.meta.txId) {
-                swap.claimTxId = event.meta.txId;
+            if(event.meta?.txId!=null && swap._claimTxId!==event.meta.txId) {
+                swap._claimTxId = event.meta.txId;
                 swapChanged ||= true;
             }
         }
         if(event instanceof RefundEvent) {
             swapChanged = await this.processEventRefund(swap, event);
-            if(event.meta?.txId!=null && swap.refundTxId!==event.meta.txId) {
-                swap.refundTxId = event.meta.txId;
+            if(event.meta?.txId!=null && swap._refundTxId!==event.meta.txId) {
+                swap._refundTxId = event.meta.txId;
                 swapChanged ||= true;
             }
         }
@@ -156,26 +172,30 @@ export abstract class IEscrowSwapWrapper<
         }
     }
 
+    /**
+     * @inheritDoc
+     * @internal
+     */
     protected async _checkPastSwaps(pastSwaps: D["Swap"][]): Promise<{ changedSwaps: D["Swap"][]; removeSwaps: D["Swap"][] }> {
         const changedSwaps: D["Swap"][] = [];
         const removeSwaps: D["Swap"][] = [];
 
         const swapExpiredStatus: {[id: string]: boolean} = {};
 
-        const checkStatusSwaps: (D["Swap"] & {data: T["Data"]})[] = [];
+        const checkStatusSwaps: (D["Swap"] & {_data: T["Data"]})[] = [];
 
         for(let pastSwap of pastSwaps) {
             if(pastSwap._shouldFetchExpiryStatus()) {
                 //Check expiry
                 swapExpiredStatus[pastSwap.getId()] = await pastSwap._verifyQuoteDefinitelyExpired();
             }
-            if(pastSwap._shouldFetchCommitStatus()) {
+            if(pastSwap._shouldFetchOnchainState()) {
                 //Add to swaps for which status should be checked
-                if(pastSwap.data!=null) checkStatusSwaps.push(pastSwap as (D["Swap"] & {data: T["Data"]}));
+                if(pastSwap._data!=null) checkStatusSwaps.push(pastSwap as (D["Swap"] & {_data: T["Data"]}));
             }
         }
 
-        const swapStatuses = await this.contract.getCommitStatuses(checkStatusSwaps.map(val => ({signer: val._getInitiator(), swapData: val.data})));
+        const swapStatuses = await this._contract.getCommitStatuses(checkStatusSwaps.map(val => ({signer: val._getInitiator(), swapData: val._data})));
 
         for(let pastSwap of checkStatusSwaps) {
             const escrowHash = pastSwap.getEscrowHash();
@@ -199,12 +219,23 @@ export abstract class IEscrowSwapWrapper<
         };
     }
 
-    recoverFromSwapDataAndState(
-        init: {data: T["Data"], getInitTxId: () => Promise<string>, getTxBlock: () => Promise<{blockTime: number, blockHeight: number}>},
+    /**
+     * Recovers a swap from smart chain on-chain data, please note that not all values for the recovered
+     *  swaps might be populated, as some data is purely off-chain and can never be recovered purely
+     *  from on-chain data.
+     *
+     * @param init Swap escrow initialization transaction and swap data
+     * @param state Current on-chain state of the swap
+     * @param lp Intermediary (LP) used as a counterparty for the swap
+     */
+    public abstract recoverFromSwapDataAndState(
+        init: {
+            data: T["Data"],
+            getInitTxId: () => Promise<string>,
+            getTxBlock: () => Promise<{blockTime: number, blockHeight: number}>
+        },
         state: SwapCommitState,
         lp?: Intermediary
-    ): Promise<D["Swap"] | null> {
-        return Promise.resolve(null);
-    }
+    ): Promise<D["Swap"] | null>;
 
 }

package/src/swaps/escrow_swaps/frombtc/IFromBTCLNWrapper.ts

@@ -18,12 +18,19 @@ import {LNURLWithdrawParamsWithUrl} from "../../../types/lnurl/LNURLWithdraw";
 
 export type IFromBTCLNDefinition<T extends ChainType, W extends IFromBTCLNWrapper<T, any>, S extends IEscrowSwap<T>> = IFromBTCDefinition<T, W, S>;
 
+/**
+ * Base class for wrappers of escrow-based Lightning -> Smart chain swaps
+ *
+ * @category Swaps/Abstract
+ */
 export abstract class IFromBTCLNWrapper<
     T extends ChainType,
     D extends IFromBTCLNDefinition<T, IFromBTCLNWrapper<T, D>, IEscrowSwap<T, D>>,
     O extends ISwapWrapperOptions = ISwapWrapperOptions
 > extends IFromBTCWrapper<T, D, O> {
-
+    /**
+     * @internal
+     */
     protected readonly lnApi: LightningNetworkApi;
 
     /**
@@ -55,20 +62,13 @@ export abstract class IFromBTCLNWrapper<
         super(chainIdentifier, unifiedStorage, unifiedChainEvents, chain, contract, prices, tokens, swapDataDeserializer, options, events);
         this.lnApi = lnApi;
     }
-    /**
-     * Returns the swap expiry, leaving enough time for the user to claim the HTLC
-     *
-     * @param data Parsed swap data
-     */
-    getHtlcTimeout(data: SwapData): bigint {
-        return data.getExpiry() - 600n;
-    }
 
     /**
-     * Generates a new 32-byte secret to be used as pre-image for lightning network invoice & HTLC swap\
+     * Generates a new 32-byte secret to be used as pre-image for lightning network invoice & HTLC swap
      *
-     * @private
      * @returns Hash pre-image & payment hash
+     *
+     * @internal
      */
     protected getSecretAndHash(): {secret: Buffer, paymentHash: Buffer} {
         const secret = randomBytes(32);
@@ -79,10 +79,12 @@ export abstract class IFromBTCLNWrapper<
     /**
      * Pre-fetches intermediary's LN node capacity, doesn't throw, instead returns null
      *
-     * @param pubkeyPromise Promise that resolves when we receive "lnPublicKey" param from the intermediary thorugh
+     * @param pubkeyPromise Promise that resolves when we receive "lnPublicKey" param from the intermediary through
      *  streaming
-     * @private
+     *
      * @returns LN Node liquidity
+     *
+     * @internal
      */
     protected preFetchLnCapacity(pubkeyPromise: Promise<string | null>): Promise<LNNodeLiquidity | null> {
         return pubkeyPromise.then(pubkey => {
@@ -99,13 +101,14 @@ export abstract class IFromBTCLNWrapper<
      *
      * @param lp Intermediary
      * @param decodedPr Decoded bolt11 lightning network invoice
-     * @param amountIn Amount to be paid for the swap in sats
      * @param lnCapacityPrefetchPromise Pre-fetch for LN node capacity, preFetchLnCapacity()
-     * @param abortSignal
-     * @private
+     * @param abortSignal Abort signal
+     *
      * @throws {IntermediaryError} if the lightning network node doesn't have enough inbound liquidity
      * @throws {Error} if the lightning network node's inbound liquidity might be enough, but the swap would
      *  deplete more than half of the liquidity
+     *
+     * @internal
      */
     protected async verifyLnNodeCapacity(
         lp: Intermediary,
@@ -119,6 +122,8 @@ export abstract class IFromBTCLNWrapper<
         const _result = await lnCapacityPrefetchPromise ?? await this.lnApi.getLNNodeLiquidity(decodedPr.payeeNodeKey);
         if(_result===null) throw new IntermediaryError("LP's lightning node not found in the lightning network graph!");
 
+        if(abortSignal!=null) abortSignal.throwIfAborted();
+
         lp.lnData = _result;
 
         if(decodedPr.payeeNodeKey!==_result.publicKey) throw new IntermediaryError("Invalid pr returned - payee pubkey");
@@ -133,17 +138,30 @@ export abstract class IFromBTCLNWrapper<
      * Parses and fetches lnurl withdraw params from the specified lnurl
      *
      * @param lnurl LNURL to be parsed and fetched
-     * @param abortSignal
-     * @private
+     * @param abortSignal Abort signal
+     *
      * @throws {UserError} if the LNURL is invalid or if it's not a LNURL-withdraw
+     *
+     * @internal
      */
     protected async getLNURLWithdraw(lnurl: string | LNURLWithdrawParamsWithUrl, abortSignal: AbortSignal): Promise<LNURLWithdrawParamsWithUrl> {
         if(typeof(lnurl)!=="string") return lnurl;
 
-        const res = await LNURL.getLNURL(lnurl, true, this.options.getRequestTimeout, abortSignal);
+        const res = await LNURL.getLNURL(lnurl, true, this._options.getRequestTimeout, abortSignal);
         if(res==null) throw new UserError("Invalid LNURL");
         if(res.tag!=="withdrawRequest") throw new UserError("Not a LNURL-withdrawal");
         return res;
     }
 
+    /**
+     * Returns the swap expiry, leaving enough time for the user to claim the HTLC
+     *
+     * @param data Parsed swap data
+     *
+     * @internal
+     */
+    _getHtlcTimeout(data: SwapData): bigint {
+        return data.getExpiry() - 600n;
+    }
+
 }