@atomiqlabs/base 12.0.4 → 13.1.2

package/src/swaps/SwapContract.ts

@@ -6,6 +6,9 @@ import {Buffer} from "buffer";
 import {AbstractSigner, TransactionConfirmationOptions} from "../chains/ChainInterface";
 import {SwapCommitState} from "./SwapCommitState";
 
+/**
+ * Represents intermediary (LP) reputation across different swap types
+ */
 export type IntermediaryReputationType = {
     [key in ChainSwapType]: {
         successVolume: bigint,
@@ -17,20 +20,46 @@ export type IntermediaryReputationType = {
     }
 };
 
+/**
+ * Signature authorization data
+ */
 export type SignatureData = {
     prefix: string,
     timeout: string,
     signature: string
 };
 
+/**
+ * Simplified bitcoin transaction data
+ */
 export type BitcoinTransactionData = {
+    /**
+     * Blockhash of a block which contains this transaction
+     */
     blockhash: string,
+    /**
+     * The number of confirmations of a block containing this transaction
+     */
     confirmations: number,
+    /**
+     * Transaction ID identifier of the transaction
+     */
     txid: string,
+    /**
+     * A hexadecimal serialized representation of the transaction with witness data stripped (legacy transaction format)
+     */
     hex: string,
+    /**
+     * The blockheight of a block containing this transaction
+     */
     height: number
 };
 
+/**
+ * A contract for interacting with escrow manager swaps - escrow based swaps like HTLCs and PrTLCs
+ *
+ * @category Swaps
+ */
 export interface SwapContract<
     T extends SwapData = SwapData,
     TX = any,
@@ -40,10 +69,28 @@ export interface SwapContract<
     ChainId extends string = string
 > {
 
+    /**
+     * Chain identifier string
+     */
     readonly chainId: ChainId;
+    /**
+     * A timeout to be used when claiming the escrow with a secret (HTLC), recommended to wait at least this long after
+     *  sending a transaction before considering it a failure
+     */
     readonly claimWithSecretTimeout: number;
+    /**
+     * A timeout to be used when claiming the escrow with bitcoin transaction data (PrTLC), recommended to wait at
+     *  least this long after sending a transaction before considering it a failure
+     */
     readonly claimWithTxDataTimeout: number;
+    /**
+     * A timeout to be used when refunding the escrow, recommended to wait at
+     *  least this long after sending a transaction before considering it a failure
+     */
     readonly refundTimeout: number;
+    /**
+     * Whether this chain supports sending initialization without a direct authorization by the claimer
+     */
     readonly supportsInitWithoutClaimer?: boolean;
 
     /**
@@ -265,7 +312,7 @@ export interface SwapContract<
                 state: SwapCommitState
             }
         },
-        latestBlockheight: number
+        latestBlockheight?: number
     }>;
 
     /**
@@ -410,7 +457,7 @@ export interface SwapContract<
      * @param address
      * @param token
      */
-    getIntermediaryReputation(address: string, token: string): Promise<IntermediaryReputationType>;
+    getIntermediaryReputation(address: string, token: string): Promise<IntermediaryReputationType | null>;
 
     /**
      * Returns the fee in native token base units to commit (initiate) the swap
@@ -501,6 +548,15 @@ export interface SwapContract<
      */
     getClaimFeeRate(signer: string, swapData: T): Promise<string>;
 
+    /**
+     * Returns additional data to be included in the data-carrier (extra data) part of the PrTLC escrow initialization
+     *  this provides helpers for 3rd party claimers
+     *
+     * @param outputScript A bitcoin output script required in the bitcoin transaction to claim the escrow
+     * @param amount An amount of bitcoin (in satoshis) required in the bitcoin transaction to claim the escrow
+     * @param confirmations Confirmations of the bitcoin transaction required for claiming the escrow
+     * @param nonce An optional nonce applied to the transaction
+     */
     getExtraData(outputScript: Buffer, amount: bigint, confirmations: number, nonce?: bigint): Buffer;
 
     /**

package/src/swaps/SwapData.ts

@@ -1,12 +1,25 @@
 import {ChainSwapType} from "./ChainSwapType";
 import {StorageObject} from "../storage/StorageObject";
 
+/**
+ * Represents full escrow swap data and parameters
+ *
+ * @category Swaps
+ */
 export abstract class SwapData implements StorageObject {
 
+    /**
+     * A mapping of deserializers for different escrow swap data types coming from different smart chain implementations
+     */
     static deserializers: {
         [type: string]: new (serialized: any) => any,
     } = {};
 
+    /**
+     * Deserializer parsing the chain-specific escrow swap data from a JSON-compatible object representation
+     *
+     * @param data
+     */
     static deserialize<T extends SwapData>(data: any): T {
         const deserializer = SwapData.deserializers[data.type];
         if(deserializer != null) {
@@ -14,56 +27,196 @@ export abstract class SwapData implements StorageObject {
         }
         throw new Error(`No deserializer found for swap data type: ${data.type}`);
     }
+
+    /**
+     * Gets the offerer, which funds the escrow
+     */
     abstract getOfferer(): string;
+
+    /**
+     * Sets the offerer to fund the escrow
+     *
+     * @param newOfferer
+     */
     abstract setOfferer(newOfferer: string): void;
+
+    /**
+     * Checks whether the provided address is an offerer for this escrow
+     *
+     * @param address
+     */
     abstract isOfferer(address: string): boolean;
 
+    /**
+     * Gets the claim, which receives funds from the escrow
+     */
     abstract getClaimer(): string;
+
+    /**
+     * Sets the claimer which receives funds from the escrow
+     *
+     * @param newClaimer
+     */
     abstract setClaimer(newClaimer: string): void;
+
+    /**
+     * Checks whether the provided address is a claimer for this escrow
+     *
+     * @param address
+     */
     abstract isClaimer(address: string): boolean;
 
+    /**
+     * @inheritDoc
+     */
     abstract serialize(): any;
 
+    /**
+     * Returns the type of this escrow
+     */
     abstract getType(): ChainSwapType;
 
+    /**
+     * Gets the amount of token deposited into the vault by the offerer
+     */
     abstract getAmount(): bigint;
 
+    /**
+     * Gets the address of the deposited token in a vault
+     */
     abstract getToken(): string;
 
+    /**
+     * Checks whether the provided token address is the actual token used by this escrow
+     *
+     * @param token
+     */
     abstract isToken(token: string): boolean;
 
+    /**
+     * Returns the expiration time of this escrow, after the timeout an offerer is able to refund unilaterally.
+     *  taking back funds from the escrow
+     */
     abstract getExpiry(): bigint;
 
+    /**
+     * Whether this escrow will pay out the claimer, when `true` it pays out normally to the claimer's address, when
+     *  `false` it instead keeps the funds inside the contract and assigns them to the claimer's vault inside the
+     *  contract
+     */
     abstract isPayOut(): boolean;
 
+    /**
+     * Whether this escrow will be funded from the offerer's wallet or from the offerer's vault inside the contract,
+     *  when `true` it takes funds normally from the offerer's address, when `false` it pulls the funds from the
+     *  offerer's vault inside the contract
+     */
     abstract isPayIn(): boolean;
 
+    /**
+     * Whether the outcome of this escrow should be used to track reputation of the claimer
+     */
+    abstract isTrackingReputation(): boolean;
+
+    /**
+     * Returns the claim hash of the escrow, this specifies a condition that needs to be satisfied to claim
+     *  the funds from the escrow
+     */
     abstract getClaimHash(): string;
 
+    /**
+     * Returns a unique hash of this escrow
+     */
     abstract getEscrowHash(): string;
 
-    abstract getSequence?(): bigint;
-
-    abstract getExtraData(): string;
-    abstract getConfirmationsHint(): number;
-    abstract getNonceHint(): bigint;
-    abstract getTxoHashHint(): string;
-    getHTLCHashHint(): string {
+    /**
+     * Returns a random variable sequence of this vault, used to ensure the escrow hash is always different
+     */
+    abstract getSequence(): bigint;
+
+    /**
+     * Gets the extraneous data specified when creating this escrow, this provides helpers for 3rd party claimers
+     */
+    abstract getExtraData(): string | null;
+
+    /**
+     * Retrieves required number of confirmations as a hint from the extra data provided, or `null` if no extra
+     *  data has been provided when creating the escrow
+     */
+    abstract getConfirmationsHint(): number | null;
+
+    /**
+     * Retrieves the PrTLC transaction nonce as a hint from the extra data provided, or `null` if no extra
+     *  data has been provided when creating the escrow
+     */
+    abstract getNonceHint(): bigint | null;
+
+    /**
+     * Retrieves the PrTLC transaction txo (transaction output) hash as a hint from the extra data provided,
+     *  or `null` if no extra data has been provided when creating the escrow
+     */
+    abstract getTxoHashHint(): string | null;
+
+    /**
+     * Retrieves a hint providing an HTLC hash from the extra data provided, or `null` if no extra data
+     *  has been provided when creating the escrow
+     */
+    getHTLCHashHint(): string | null {
         return null;
     }
+
+    /**
+     * Sets the extra data with hints for this escrow
+     *
+     * @param extraData
+     */
     abstract setExtraData(extraData: string): void;
 
+    /**
+     * Gets the security deposit, which is an amount of native tokens deposited by the caller (initiator) on
+     *  escrow initialization to guarantee the execution, this acts as a compensation for offerer if he has
+     *  to refund the escrow, otherwise it is returned back to claimer after a successful claim of the escrow
+     */
     abstract getSecurityDeposit(): bigint;
 
+    /**
+     * Gets the claimer bounty, an amount of native tokens deposited by the caller (initiator) on escrow
+     *  initialization, that is paid out to a caller which claims the escrow as a reward, otherwise
+     *  returned to the claimer if escrow is refunded
+     */
     abstract getClaimerBounty(): bigint;
 
+    /**
+     * Returns the total deposit in native token to be deposited by the caller (initiator) on escrow initialization,
+     *  due to how claimer bounty and security deposits work, this is basically a max(claimer bounty, security deposit),
+     *  because either a swap is claimed (and claimer bounty is paid) or a swap is refunded (and security deposit is paid),
+     *  never both!
+     */
     abstract getTotalDeposit(): bigint;
 
+    /**
+     * Returns the token used for the deposit (security deposit & claimer bounty) (usually a native token of the
+     *  underlying smart chain)
+     */
     abstract getDepositToken(): string;
+
+    /**
+     * Checks whether a provided token is used as a deposit token (security deposit & claimer bounty) for the escrow
+     *
+     * @param token
+     */
     abstract isDepositToken(token: string): boolean;
 
+    /**
+     * Checks equality between 2 swap data objects
+     *
+     * @param other
+     */
     abstract equals(other: SwapData): boolean;
 
+    /**
+     * Checks whether the escrow contains an execution action (swap+)
+     */
     hasSuccessAction(): boolean {
         return false;
     }

package/src/utils/BigIntBufferUtils.ts

@@ -1,10 +1,15 @@
 import {Buffer} from "buffer";
 
+/**
+ * A helper for serializing and deserializing bigints from/to buffers
+ *
+ * @internal
+ */
 export const BigIntBufferUtils: {
     toBuffer: (value: bigint, endianness?: "be" | "le", length?: number) => Buffer
     fromBuffer: (value: Buffer, endianness?: "be" | "le") => bigint
 } = {
-    toBuffer: (value: bigint, endianness: "be" | "le" = "be", length: number) => {
+    toBuffer: (value: bigint, endianness: "be" | "le" = "be", length: number = 32) => {
         let values: number[] = Array(length);
         for(let i=0;i<length;i++) {
             values[i] = Number(value & 0xffn);

package/src/utils/Logger.ts

@@ -0,0 +1,25 @@
+/**
+ * Type of the logger
+ *
+ * @internal
+ */
+export type LoggerType = {
+    debug: (msg: string, ...args: any[]) => void,
+    info: (msg: string, ...args: any[]) => void,
+    warn: (msg: string, ...args: any[]) => void,
+    error: (msg: string, ...args: any[]) => void
+};
+
+/**
+ * Getter function to create a logger instance
+ *
+ * @internal
+ */
+export function getLogger(prefix: string): LoggerType {
+    return {
+        debug: (msg, ...args) => (global as any).atomiqLogLevel >= 3 && console.debug(prefix + msg, ...args),
+        info: (msg, ...args) => (global as any).atomiqLogLevel >= 2 && console.info(prefix + msg, ...args),
+        warn: (msg, ...args) => ((global as any).atomiqLogLevel == null || (global as any).atomiqLogLevel >= 1) && console.warn(prefix + msg, ...args),
+        error: (msg, ...args) => ((global as any).atomiqLogLevel == null || (global as any).atomiqLogLevel >= 0) && console.error(prefix + msg, ...args)
+    };
+}

package/src/utils/RetryUtils.ts

@@ -0,0 +1,73 @@
+import {getLogger} from "./Logger";
+import {timeoutPromise} from "./TimeoutUtils";
+
+const logger = getLogger("RetryUtils: ");
+
+type Constructor<T = any> = new (...args: any[]) => T;
+
+function isConstructor(fn: any): fn is Constructor {
+    return (
+        typeof fn === 'function' &&
+        fn.prototype != null &&
+        fn.prototype.constructor === fn
+    );
+}
+
+function isConstructorArray(fnArr: any): fnArr is Constructor[] {
+    return Array.isArray(fnArr) && fnArr.every(isConstructor);
+}
+
+/**
+ * Checks whether the passed error is allowed to pass through
+ *
+ * @param e Error in question
+ * @param errorAllowed Allowed errors as defined as a callback function, specific error type, or an array of error types
+ */
+function checkError(e: any, errorAllowed: ((e: any) => boolean) | Constructor<Error> | Constructor<Error>[]) {
+    if (isConstructorArray(errorAllowed)) return errorAllowed.find(error => e instanceof error) != null;
+    if (isConstructor(errorAllowed)) return e instanceof errorAllowed;
+    return errorAllowed(e);
+}
+
+/**
+ * Runs the passed function multiple times if it fails
+ *
+ * @param func A callback for executing the action
+ * @param func.retryCount Count of the current retry, starting from 0 for original request and increasing
+ * @param retryPolicy Retry policy
+ * @param retryPolicy.maxRetries How many retries to attempt in total
+ * @param retryPolicy.delay How long should the delay be
+ * @param retryPolicy.exponential Whether to use exponentially increasing delays
+ * @param errorAllowed A callback for determining whether a given error is allowed, and we should therefore not retry
+ * @param abortSignal
+ *
+ * @returns Result of the action executing callback
+ *
+ * @internal
+ */
+export async function tryWithRetries<T>(func: (retryCount: number) => Promise<T>, retryPolicy?: {
+    maxRetries?: number, delay?: number, exponential?: boolean
+}, errorAllowed?: ((e: any) => boolean) | Constructor<Error> | Constructor<Error>[], abortSignal?: AbortSignal): Promise<T> {
+    retryPolicy = retryPolicy || {};
+    retryPolicy.maxRetries = retryPolicy.maxRetries || 5;
+    retryPolicy.delay = retryPolicy.delay || 500;
+    retryPolicy.exponential = retryPolicy.exponential == null ? true : retryPolicy.exponential;
+
+    let err = null;
+
+    for (let i = 0; i < retryPolicy.maxRetries; i++) {
+        try {
+            return await func(i);
+        } catch (e) {
+            if (errorAllowed != null && checkError(e, errorAllowed)) throw e;
+            err = e;
+            logger.warn("tryWithRetries(): Error on try number: " + i, e);
+        }
+        if (abortSignal != null && abortSignal.aborted) throw (abortSignal.reason || new Error("Aborted"));
+        if (i !== retryPolicy.maxRetries - 1) {
+            await timeoutPromise(retryPolicy.exponential ? retryPolicy.delay * Math.pow(2, i) : retryPolicy.delay, abortSignal);
+        }
+    }
+
+    throw err;
+}

package/src/utils/TimeoutUtils.ts

@@ -0,0 +1,52 @@
+/**
+ * Returns a promise that resolves after given amount seconds
+ *
+ * @param timeout how many milliseconds to wait for
+ * @param abortSignal
+ *
+ * @internal
+ */
+export function timeoutPromise(timeout: number, abortSignal?: AbortSignal): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+        if (abortSignal != null && abortSignal.aborted) {
+            reject(abortSignal.reason);
+            return;
+        }
+
+        let abortSignalListener: () => void;
+        let timeoutHandle: any | null = setTimeout(() => {
+            if (abortSignalListener != null && abortSignal != null) abortSignal.removeEventListener("abort", abortSignalListener);
+            resolve();
+        }, timeout);
+
+        if (abortSignal != null) {
+            abortSignal.addEventListener("abort", abortSignalListener = () => {
+                if (timeoutHandle != null) clearTimeout(timeoutHandle);
+                timeoutHandle = null;
+                reject(abortSignal.reason);
+            });
+        }
+    });
+}
+
+/**
+ * Returns an abort signal that aborts after a specified timeout in milliseconds
+ *
+ * @param timeout Milliseconds to wait
+ * @param abortReason Abort with this abort reason
+ * @param abortSignal Abort signal to extend
+ *
+ * @internal
+ */
+export function timeoutSignal(timeout: number, abortReason?: any, abortSignal?: AbortSignal): AbortSignal {
+    if (timeout == null) throw new Error("Timeout seconds cannot be null!");
+    const abortController = new AbortController();
+    const timeoutHandle = setTimeout(() => abortController.abort(abortReason || new Error("Timed out")), timeout);
+    if (abortSignal != null) {
+        abortSignal.addEventListener("abort", () => {
+            clearTimeout(timeoutHandle);
+            abortController.abort(abortSignal.reason);
+        });
+    }
+    return abortController.signal;
+}