@atomiqlabs/sdk 7.0.12 → 8.0.8

package/src/swaps/escrow_swaps/IEscrowSwap.ts

@@ -0,0 +1,197 @@
+import {isISwapInit, ISwap, ISwapInit} from "../ISwap";
+import {
+    ChainType,
+    SwapCommitState,
+    SwapCommitStateType,
+    SwapData,
+    SwapExpiredState,
+    SwapNotCommitedState,
+    SwapPaidState
+} from "@atomiqlabs/base";
+import {IEscrowSwapDefinition, IEscrowSwapWrapper} from "./IEscrowSwapWrapper";
+import {Buffer} from "buffer";
+import {timeoutPromise} from "../../utils/TimeoutUtils";
+
+export type IEscrowSwapInit<T extends SwapData> = ISwapInit & {
+    data?: T,
+};
+
+export function isIEscrowSwapInit<T extends SwapData>(obj: any): obj is IEscrowSwapInit<T> {
+    return typeof obj === 'object' &&
+        (obj.data == null || typeof obj.data === 'object') &&
+        isISwapInit(obj);
+}
+
+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"];
+
+    /**
+     * Transaction IDs for the swap on the smart chain side
+     */
+    commitTxId?: string;
+    refundTxId?: string;
+    claimTxId?: string;
+
+    protected constructor(wrapper: D["Wrapper"], obj: any);
+    protected constructor(wrapper: D["Wrapper"], swapInit: IEscrowSwapInit<T["Data"]>);
+    protected constructor(
+        wrapper: D["Wrapper"],
+        swapInitOrObj: IEscrowSwapInit<T["Data"]> | any,
+    ) {
+        super(wrapper, swapInitOrObj);
+
+        if(isIEscrowSwapInit(swapInitOrObj)) {
+            this.data = swapInitOrObj.data;
+        } else {
+            if(swapInitOrObj.data!=null) this.data = new wrapper.swapDataDeserializer(swapInitOrObj.data);
+
+            this.commitTxId = swapInitOrObj.commitTxId;
+            this.claimTxId = swapInitOrObj.claimTxId;
+            this.refundTxId = swapInitOrObj.refundTxId;
+        }
+    }
+
+    protected abstract getSwapData(): T["Data"];
+
+    //////////////////////////////
+    //// Identifiers
+
+    /**
+     * 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
+     */
+    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")]);
+    }
+
+    /**
+     * 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
+     */
+    protected getIdentifierHashString(): string {
+        const identifierHash = this.getIdentifierHash();
+        return identifierHash.toString("hex");
+    }
+
+    _getEscrowHash(): string | null {
+        return this.data?.getEscrowHash() ?? null;
+    }
+
+    /**
+     * Returns the escrow hash - i.e. hash of the escrow data
+     */
+    getEscrowHash(): string | null {
+        return this._getEscrowHash();
+    }
+
+    /**
+     * Returns the claim data hash - i.e. hash passed to the claim handler
+     */
+    getClaimHash(): string {
+        return this.getSwapData().getClaimHash();
+    }
+
+    getId(): string {
+        return this.getIdentifierHashString();
+    }
+
+
+    //////////////////////////////
+    //// Watchdogs
+
+    /**
+     * Periodically checks the chain to see whether the swap is committed
+     *
+     * @param intervalSeconds How often to check (in seconds), default to 5s
+     * @param abortSignal
+     * @protected
+     */
+    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?");
+
+        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);
+                if(
+                    status?.type===SwapCommitStateType.NOT_COMMITED &&
+                    await this._verifyQuoteDefinitelyExpired()
+                ) return false;
+            } catch (e) {
+                this.logger.error("watchdogWaitTillCommited(): Error when fetching commit status or signature expiry: ", e);
+            }
+        }
+        if(abortSignal!=null) abortSignal.throwIfAborted();
+        return status?.type!==SwapCommitStateType.EXPIRED;
+    }
+
+    /**
+     * Periodically checks the chain to see whether the swap was finished (claimed or refunded)
+     *
+     * @param intervalSeconds How often to check (in seconds), default to 5s
+     * @param abortSignal
+     * @protected
+     */
+    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?");
+
+        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);
+            } catch (e) {
+                this.logger.error("watchdogWaitTillResult(): Error when fetching commit status: ", e);
+            }
+        }
+        if(abortSignal!=null) abortSignal.throwIfAborted();
+        return status;
+    }
+
+
+    //////////////////////////////
+    //// Quote verification
+
+    /**
+     * Checks if the swap's quote is expired for good (i.e. the swap strictly cannot be committed on-chain anymore)
+     */
+    abstract _verifyQuoteDefinitelyExpired(): Promise<boolean>;
+
+    /**
+     * Checks if the swap's quote is still valid
+     */
+    abstract verifyQuoteValid(): Promise<boolean>;
+
+
+    //////////////////////////////
+    //// Helpers for batched swap checks
+
+    abstract _shouldFetchCommitStatus(): boolean;
+
+    abstract _shouldFetchExpiryStatus(): boolean;
+
+    abstract _sync(save?: boolean, quoteDefinitelyExpired?: boolean, commitStatus?: SwapCommitState): Promise<boolean>;
+
+    serialize(): any {
+        return {
+            ...super.serialize(),
+            data: this.data!=null ? this.data.serialize() : null,
+            commitTxId: this.commitTxId,
+            claimTxId: this.claimTxId,
+            refundTxId: this.refundTxId
+        }
+    };
+
+}

package/src/swaps/escrow_swaps/IEscrowSwapWrapper.ts

@@ -0,0 +1,210 @@
+import {ISwapWrapper, ISwapWrapperOptions, SwapTypeDefinition, WrapperCtorTokens} from "../ISwapWrapper";
+import {
+    ChainType,
+    ClaimEvent,
+    InitializeEvent,
+    RefundEvent,
+    SignatureData,
+    SignatureVerificationError,
+    SwapCommitState,
+    SwapEvent
+} from "@atomiqlabs/base";
+import {ISwap} from "../ISwap";
+import {UnifiedSwapStorage} from "../../storage/UnifiedSwapStorage";
+import {UnifiedSwapEventListener} from "../../events/UnifiedSwapEventListener";
+import {ISwapPrice} from "../../prices/abstract/ISwapPrice";
+import {EventEmitter} from "events";
+import {SwapType} from "../../enums/SwapType";
+import {IEscrowSwap} from "./IEscrowSwap";
+import {Intermediary} from "../../intermediaries/Intermediary";
+
+export type IEscrowSwapDefinition<T extends ChainType, W extends IEscrowSwapWrapper<T, any>, S extends IEscrowSwap<T>> = SwapTypeDefinition<T, W, S>;
+
+export abstract class IEscrowSwapWrapper<
+    T extends ChainType,
+    D extends IEscrowSwapDefinition<T, IEscrowSwapWrapper<T, D>, IEscrowSwap<T, D>>,
+    O extends ISwapWrapperOptions = ISwapWrapperOptions
+> extends ISwapWrapper<T, D, O> {
+    readonly abstract TYPE: SwapType;
+
+    readonly contract: T["Contract"];
+    readonly swapDataDeserializer: new (data: any) => T["Data"];
+
+    constructor(
+        chainIdentifier: string,
+        unifiedStorage: UnifiedSwapStorage<T>,
+        unifiedChainEvents: UnifiedSwapEventListener<T>,
+        chain: T["ChainInterface"],
+        contract: T["Contract"],
+        prices: ISwapPrice,
+        tokens: WrapperCtorTokens,
+        swapDataDeserializer: new (data: any) => T["Data"],
+        options: O,
+        events?: EventEmitter<{swapState: [ISwap]}>
+    ) {
+        super(chainIdentifier, unifiedStorage, unifiedChainEvents, chain, prices, tokens, options, events);
+        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
+     */
+    protected preFetchSignData(signDataPrefetch: Promise<any | null>): Promise<T["PreFetchVerification"] | undefined> {
+        if(this.contract.preFetchForInitSignatureVerification==null) return Promise.resolve(undefined);
+        return signDataPrefetch.then(obj => {
+            if(obj==null) return undefined;
+            return this.contract.preFetchForInitSignatureVerification!(obj);
+        }).catch(e => {
+            this.logger.error("preFetchSignData(): Error: ", e);
+        });
+    }
+
+    /**
+     * Verifies swap initialization signature returned by the intermediary
+     *
+     * @param initiator A smart chain account initiating the swap
+     * @param data Parsed swap data from the intermediary
+     * @param signature Response of the intermediary
+     * @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
+     */
+    protected async verifyReturnedSignature(
+        initiator: string,
+        data: T["Data"],
+        signature: SignatureData,
+        feeRatePromise: Promise<any>,
+        preFetchSignatureVerificationData: Promise<any>,
+        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);
+    }
+
+    /**
+     * Processes InitializeEvent for a given swap
+     * @param swap
+     * @param event
+     * @protected
+     * @returns Whether the swap was updated/changed
+     */
+    protected abstract processEventInitialize(swap: D["Swap"], event: InitializeEvent<T["Data"]>): Promise<boolean>;
+
+    /**
+     * Processes ClaimEvent for a given swap
+     * @param swap
+     * @param event
+     * @protected
+     * @returns Whether the swap was updated/changed
+     */
+    protected abstract processEventClaim(swap: D["Swap"], event: ClaimEvent<T["Data"]>): Promise<boolean>;
+
+    /**
+     * Processes RefundEvent for a given swap
+     * @param swap
+     * @param event
+     * @protected
+     * @returns Whether the swap was updated/changed
+     */
+    protected abstract processEventRefund(swap: D["Swap"], event: RefundEvent<T["Data"]>): Promise<boolean>;
+
+    /**
+     * Processes a single SC on-chain event
+     * @private
+     * @param event
+     * @param swap
+     */
+    protected async processEvent(event: SwapEvent<T["Data"]>, swap: D["Swap"]): Promise<void> {
+        if(swap==null) return;
+
+        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;
+                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;
+                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;
+                swapChanged ||= true;
+            }
+        }
+
+        this.logger.info("processEvents(): "+event.constructor.name+" processed for "+swap.getId()+" swap: ", swap);
+
+        if(swapChanged) {
+            await swap._saveAndEmit();
+        }
+    }
+
+    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"]})[] = [];
+
+        for(let pastSwap of pastSwaps) {
+            if(pastSwap._shouldFetchExpiryStatus()) {
+                //Check expiry
+                swapExpiredStatus[pastSwap.getId()] = await pastSwap._verifyQuoteDefinitelyExpired();
+            }
+            if(pastSwap._shouldFetchCommitStatus()) {
+                //Add to swaps for which status should be checked
+                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})));
+
+        for(let pastSwap of checkStatusSwaps) {
+            const escrowHash = pastSwap.getEscrowHash();
+            const shouldSave = await pastSwap._sync(
+                false,
+                swapExpiredStatus[pastSwap.getId()],
+                escrowHash==null ? undefined : swapStatuses[escrowHash]
+            );
+            if(shouldSave) {
+                if(pastSwap.isQuoteExpired()) {
+                    removeSwaps.push(pastSwap);
+                } else {
+                    changedSwaps.push(pastSwap);
+                }
+            }
+        }
+
+        return {
+            changedSwaps,
+            removeSwaps
+        };
+    }
+
+    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);
+    }
+
+}

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

@@ -0,0 +1,150 @@
+import {ChainType, SwapData} from "@atomiqlabs/base";
+import {IFromBTCDefinition, IFromBTCWrapper} from "./IFromBTCWrapper";
+import {ISwapWrapperOptions, WrapperCtorTokens} from "../../ISwapWrapper";
+import {LightningNetworkApi, LNNodeLiquidity} from "../../../bitcoin/LightningNetworkApi";
+import {UnifiedSwapStorage} from "../../../storage/UnifiedSwapStorage";
+import {UnifiedSwapEventListener} from "../../../events/UnifiedSwapEventListener";
+import {ISwapPrice} from "../../../prices/abstract/ISwapPrice";
+import {EventEmitter} from "events";
+import {Buffer} from "buffer";
+import {randomBytes} from "../../../utils/Utils";
+import {Intermediary} from "../../../intermediaries/Intermediary";
+import {PaymentRequestObject, TagsObject} from "@atomiqlabs/bolt11";
+import {IntermediaryError} from "../../../errors/IntermediaryError";
+import {LNURL} from "../../../lnurl/LNURL";
+import {UserError} from "../../../errors/UserError";
+import { sha256 } from "@noble/hashes/sha256";
+import {IEscrowSwap} from "../IEscrowSwap";
+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>;
+
+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> {
+
+    protected readonly lnApi: LightningNetworkApi;
+
+    /**
+     * @param chainIdentifier
+     * @param unifiedStorage Storage interface for the current environment
+     * @param unifiedChainEvents On-chain event listener
+     * @param chain
+     * @param contract Underlying contract handling the swaps
+     * @param prices Swap pricing handler
+     * @param tokens
+     * @param swapDataDeserializer Deserializer for SwapData
+     * @param lnApi
+     * @param options
+     * @param events Instance to use for emitting events
+     */
+    constructor(
+        chainIdentifier: string,
+        unifiedStorage: UnifiedSwapStorage<T>,
+        unifiedChainEvents: UnifiedSwapEventListener<T>,
+        chain: T["ChainInterface"],
+        contract: T["Contract"],
+        prices: ISwapPrice,
+        tokens: WrapperCtorTokens,
+        swapDataDeserializer: new (data: any) => T["Data"],
+        lnApi: LightningNetworkApi,
+        options: O,
+        events?: EventEmitter<{swapState: [IEscrowSwap]}>
+    ) {
+        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\
+     *
+     * @private
+     * @returns Hash pre-image & payment hash
+     */
+    protected getSecretAndHash(): {secret: Buffer, paymentHash: Buffer} {
+        const secret = randomBytes(32);
+        const paymentHash = Buffer.from(sha256(secret));
+        return {secret, paymentHash};
+    }
+
+    /**
+     * 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
+     *  streaming
+     * @private
+     * @returns LN Node liquidity
+     */
+    protected preFetchLnCapacity(pubkeyPromise: Promise<string | null>): Promise<LNNodeLiquidity | null> {
+        return pubkeyPromise.then(pubkey => {
+            if(pubkey==null) return null;
+            return this.lnApi.getLNNodeLiquidity(pubkey)
+        }).catch(e => {
+            this.logger.warn("preFetchLnCapacity(): Error: ", e);
+            return null;
+        })
+    }
+
+    /**
+     * Verifies whether the intermediary's lightning node has enough inbound capacity to receive the LN payment
+     *
+     * @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
+     * @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
+     */
+    protected async verifyLnNodeCapacity(
+        lp: Intermediary,
+        decodedPr: PaymentRequestObject & {tagsObject: TagsObject},
+        lnCapacityPrefetchPromise?: Promise<LNNodeLiquidity | null>,
+        abortSignal?: AbortSignal
+    ): Promise<void> {
+        if(decodedPr.payeeNodeKey==null) throw new Error("Unable to extract payee pubkey from the swap invoice!");
+        if(decodedPr.millisatoshis==null) throw new Error("Swap invoice doesn't contains msat amount field!");
+
+        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!");
+
+        lp.lnData = _result;
+
+        if(decodedPr.payeeNodeKey!==_result.publicKey) throw new IntermediaryError("Invalid pr returned - payee pubkey");
+        const amountIn = (BigInt(decodedPr.millisatoshis) + 999n) / 1000n;
+        if(_result.capacity < amountIn)
+            throw new IntermediaryError("LP's lightning node doesn't have enough inbound capacity for the swap!");
+        if((_result.capacity / 2n) < amountIn)
+            throw new Error("LP's lightning node probably doesn't have enough inbound capacity for the swap!");
+    }
+
+    /**
+     * Parses and fetches lnurl withdraw params from the specified lnurl
+     *
+     * @param lnurl LNURL to be parsed and fetched
+     * @param abortSignal
+     * @private
+     * @throws {UserError} if the LNURL is invalid or if it's not a LNURL-withdraw
+     */
+    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);
+        if(res==null) throw new UserError("Invalid LNURL");
+        if(res.tag!=="withdrawRequest") throw new UserError("Not a LNURL-withdrawal");
+        return res;
+    }
+
+}