@atomiqlabs/base 12.0.4 → 13.0.4

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);