@atomiqlabs/base 12.0.4 → 13.0.4

package/src/spv_swap/SpvVaultData.ts

@@ -5,43 +5,127 @@ import {SpvVaultCloseEvent} from "../events/types/spv_vault/SpvVaultCloseEvent";
 import {SpvVaultOpenEvent} from "../events/types/spv_vault/SpvVaultOpenEvent";
 import {SpvVaultDepositEvent} from "../events/types/spv_vault/SpvVaultDepositEvent";
 
+/**
+ * Balance for a specific token inside a vault
+ *
+ * @category Swaps
+ */
 export type SpvVaultTokenBalance = SpvVaultTokenData & {
+    /**
+     * A raw amount of the token, exactly as specified in the vault state
+     */
     rawAmount: bigint,
+    /**
+     * An actual amount of funds in the vault, calculated as `rawAmount` * `multiplier`
+     */
     scaledAmount: bigint
 };
 
+/**
+ * Configuration for a specific token inside an SPV vault (UTXO-controlled vault)
+ *
+ * @category Swaps
+ */
 export type SpvVaultTokenData = {
+    /**
+     * Address of the token used
+     */
     token: string,
+    /**
+     * A multiplier to scale the token value with
+     */
     multiplier: bigint
 }
 
+/**
+ * Represents the state of a single SPV vault (UTXO-controlled vault)
+ *
+ * @category Swaps
+ */
 export abstract class SpvVaultData<T extends SpvWithdrawalTransactionData = SpvWithdrawalTransactionData> implements StorageObject {
 
+    /**
+     * A mapping of deserializers for different spv vault data types coming from different smart chain implementations
+     */
     static deserializers: {
         [type: string]: new (serialized: any) => any,
     } = {};
 
+    /**
+     * Deserializer parsing the chain-specific spv vault data from a JSON-compatible object representation
+     *
+     * @param data
+     */
     static deserialize<T extends SpvVaultData>(data: any): T {
         if (SpvVaultData.deserializers[data.type] != null) {
             return new SpvVaultData.deserializers[data.type](data) as unknown as T;
         }
+        throw new Error(`No deserializer found for spv vault data type: ${data.type}`);
     }
 
+    /**
+     * @inheritDoc
+     */
     abstract serialize(): any;
 
+    /**
+     * Gets the owner of the vault
+     */
     abstract getOwner(): string;
+
+    /**
+     * Gets the vault ID, this along with the owner uniquely identifies a vault
+     */
     abstract getVaultId(): bigint;
+
+    /**
+     * Returns the configuration of the tokens supported by the vault
+     */
     abstract getTokenData(): SpvVaultTokenData[];
 
+    /**
+     * Returns the token balance currently available in the vault
+     */
     abstract getBalances(): SpvVaultTokenBalance[];
+
+    /**
+     * Returns the UTXO in [txId]:[vout] format which currently controls the vault
+     */
     abstract getUtxo(): string;
+
+    /**
+     * Gets the required number of confirmations that a bitcoin transaction has to get in order for the
+     *  vault claim (withdrawal) to be authorized
+     */
     abstract getConfirmations(): number;
+
+    /**
+     * Returns the current number of claims (withdrawals) processed by the vault
+     */
     abstract getWithdrawalCount(): number;
+
+    /**
+     * Returns the current number of deposits deposited into the vault
+     */
     abstract getDepositCount(): number;
+
+    /**
+     * Checks whether a vault is opened and available to process claims (withdrawals)
+     */
     abstract isOpened(): boolean;
 
+    /**
+     * Updates the state of the spv vault data from either an on-chain event or a {@link SpvWithdrawalTransactionData}
+     *
+     * @param withdrawalTxOrEvent
+     */
     abstract updateState(withdrawalTxOrEvent: T | SpvVaultClaimEvent | SpvVaultCloseEvent | SpvVaultOpenEvent | SpvVaultDepositEvent): void;
 
+    /**
+     * A helper function which calculates the vault balances after processing an array of claims (withdrawals)
+     *
+     * @param priorWithdrawalTxs
+     */
     calculateStateAfter(priorWithdrawalTxs: T[]): {withdrawalCount: number, balances: SpvVaultTokenBalance[]} {
         const balances = [...this.getBalances()];
         let withdrawalCount = this.getWithdrawalCount();

package/src/spv_swap/SpvWithdrawalState.ts

@@ -1,11 +1,35 @@
-
+/**
+ * Possible states of a vault withdrawal (claim) transaction
+ *
+ * @category Swaps
+ */
 export enum SpvWithdrawalStateType {
+    /**
+     * An SPV vault (UTXO-controlled vault), has been closed as a result of the claim (withdrawal) transaction,
+     *  something probably went wrong with the bitcoin transaction format or parsing
+     */
     CLOSED = -1,
+    /**
+     * The withdrawal is not yet known on the smart chain side, i.e. the transaction on the bitcoin side
+     *  didn't achieve enough confirmations yet, or it was not yet submitted on the smart chain side
+     */
     NOT_FOUND = 0,
+    /**
+     * The withdrawal was successfully processed on the smart chain side
+     */
     CLAIMED = 1,
+    /**
+     * The withdrawal has been fronted by some 3rd party
+     */
     FRONTED = 2
 }
 
+/**
+ * The withdrawal is not yet known on the smart chain side, i.e. the transaction on the bitcoin side
+ *  didn't achieve enough confirmations yet, or it was not yet submitted on the smart chain side
+ *
+ * @category Swaps
+ */
 export type SpvWithdrawalNotFoundState = {
     type: SpvWithdrawalStateType.NOT_FOUND
 };
@@ -16,6 +40,11 @@ type SpvWithdrawalStateCommon = {
     vaultId: bigint,
 };
 
+/**
+ * The withdrawal was successfully processed on the smart chain side
+ *
+ * @category Swaps
+ */
 export type SpvWithdrawalClaimedState = {
     type: SpvWithdrawalStateType.CLAIMED,
     recipient: string,
@@ -23,17 +52,33 @@ export type SpvWithdrawalClaimedState = {
     fronter: string
 } & SpvWithdrawalStateCommon;
 
+/**
+ * The withdrawal has been fronted by some 3rd party
+ *
+ * @category Swaps
+ */
 export type SpvWithdrawalFrontedState = {
     type: SpvWithdrawalStateType.FRONTED,
     recipient: string,
     fronter: string
 } & SpvWithdrawalStateCommon;
 
+/**
+ * An SPV vault (UTXO-controlled vault), has been closed as a result of the claim (withdrawal) transaction,
+ *  something probably went wrong with the bitcoin transaction format or parsing
+ *
+ * @category Swaps
+ */
 export type SpvWithdrawalClosedState = {
     type: SpvWithdrawalStateType.CLOSED,
     error: string
 } & SpvWithdrawalStateCommon;
 
+/**
+ * A union type for the state of the spv vault claim (withdrawal)
+ *
+ * @category Swaps
+ */
 export type SpvWithdrawalState = SpvWithdrawalNotFoundState |
     SpvWithdrawalClaimedState |
     SpvWithdrawalFrontedState |

package/src/spv_swap/SpvWithdrawalTransactionData.ts

@@ -2,24 +2,47 @@ import {BtcTx} from "../btc/rpc/BitcoinRpc";
 import {Buffer} from "buffer";
 import {StorageObject} from "../storage/StorageObject";
 
+/**
+ * Execution data assigned to the withdrawal
+ */
 export type ExecutionData = {
     executionHash: string,
     executionExpiry: number
 };
 
+/**
+ * Represents the data of a single SPV vault (UTXO-controlled) vault withdrawal
+ *
+ * @category Swaps
+ */
 export abstract class SpvWithdrawalTransactionData implements StorageObject {
 
+    /**
+     * A mapping of deserializers for different spv vault withdrawal data types coming from different smart chain implementations
+     */
     static deserializers: {
         [type: string]: new (serialized: any) => any,
     } = {};
 
-    static deserialize<T extends SpvWithdrawalTransactionData>(data: any): T {
+    /**
+     * Deserializer parsing the chain-specific spv vault withdrawal data from a JSON-compatible object representation
+     *
+     * @param data
+     */
+    static deserialize<T extends SpvWithdrawalTransactionData>(data: any): T | null {
         if (SpvWithdrawalTransactionData.deserializers[data.type] != null) {
             return new SpvWithdrawalTransactionData.deserializers[data.type](data) as unknown as T;
         }
+        throw new Error(`No deserializer found for spv withdrawal tx data type: ${data.type}`);
     }
 
-    protected abstract fromOpReturnData(data: Buffer): {recipient: string, rawAmounts: bigint[], executionHash: string};
+    /**
+     * Parses the data from the OP_RETURN script for a specific underlying chain
+     *
+     * @param data
+     * @protected
+     */
+    protected abstract fromOpReturnData(data: Buffer): {recipient: string, rawAmounts: bigint[], executionHash?: string};
 
     readonly recipient: string;
     readonly rawAmounts: bigint[];
@@ -28,11 +51,19 @@ export abstract class SpvWithdrawalTransactionData implements StorageObject {
     readonly executionFeeRate: bigint;
     readonly frontingFeeRate: bigint;
 
-    readonly executionHash: string;
+    readonly executionHash?: string;
     readonly executionExpiry: number;
 
+    /**
+     * A bitcoin transaction which contains this vault withdrawal data
+     */
     readonly btcTx: BtcTx;
 
+    /**
+     * Parses and creates a withdrawal data from the bitcoin transaction
+     *
+     * @throws {Error} If the bitcoin transaction has invalid formatting
+     */
     constructor(btcTx: BtcTx) {
         if(btcTx.ins.length<2) throw new Error("Need at least 2 inputs");
         if(btcTx.outs.length<2) throw new Error("Need at least 2 outputs");
@@ -54,14 +85,17 @@ export abstract class SpvWithdrawalTransactionData implements StorageObject {
         const opReturnData = Buffer.from(opReturnOutput.scriptPubKey.hex, "hex");
         if(opReturnData.length===0) throw new Error("Output 1 empty script");
         if(opReturnData.at(0)!==0x6a) throw new Error("Output 1 is not OP_RETURN");
-        if(opReturnData.at(1)===0) throw new Error("Output 1 OP_RETURN followed by OP_0");
+        const secondByte = opReturnData.at(1);
+        if(secondByte==null) throw new Error("Output 1 OP_RETURN empty");
+        if(secondByte===0) throw new Error("Output 1 OP_RETURN followed by OP_0");
         let data: Buffer;
-        if(opReturnData.at(1) === 0x4c) { //OP_PUSHDATA1
+        if(secondByte === 0x4c) { //OP_PUSHDATA1
             const dataLength = opReturnData.at(2);
+            if(dataLength==null) throw new Error("Output 1 OP_RETURN OP_PUSHDATA1 invalid length!");
             data = opReturnData.subarray(3, 3+dataLength);
             if(data.length !== dataLength) throw new Error("Output 1 OP_RETURN data length mismatch!");
-        } else if(opReturnData.at(1) <= 0x4b) { //OP_PUSH<length>
-            const dataLength = opReturnData.at(1);
+        } else if(secondByte <= 0x4b) { //OP_PUSH<length>
+            const dataLength = secondByte;
             data = opReturnData.subarray(2, 2+dataLength);
             if(data.length !== dataLength) throw new Error("Output 1 OP_RETURN data length mismatch!");
         } else {
@@ -84,34 +118,77 @@ export abstract class SpvWithdrawalTransactionData implements StorageObject {
         this.btcTx = btcTx;
     }
 
+    /**
+     * @inheritDoc
+     */
     serialize(): any {
         return this.btcTx;
     }
 
+    /**
+     * Gets the recipient of the funds for this withdrawal
+     */
     getRecipient(): string {
         return this.recipient;
     }
 
+    /**
+     * Checks if the provided recipient is the actual recipient of the funds in this withdrawal
+     *
+     * @param address
+     */
     abstract isRecipient(address: string): boolean;
 
+    /**
+     * Computes a unique withdrawal fronting ID that is to be used when fronting the withdrawal
+     */
     abstract getFrontingId(): string;
 
+    /**
+     * Returns the amounts of tokens that the recipient is gonna receive (NOTE: This returns raw token amounts,
+     *  which must be scaled by their respective vault configured multiplier to represent the actual amount
+     *  of tokens)
+     */
     getOutputWithoutFees(): bigint[] {
         return this.rawAmounts;
     }
 
+    /**
+     * Returns the fee paid out to the caller which submits the withdrawal transaction data on the smart chain,
+     *  the fee is paid out from all the respective tokens being withdrawn from the vault (NOTE: This returns raw token amounts,
+     *  which must be scaled by their respective vault configured multiplier to represent the actual amount
+     *  of tokens)
+     */
     getCallerFee(): bigint[] {
         return this.rawAmounts.map(val => val * this.callerFeeRate / 100_000n);
     }
 
+    /**
+     * Returns the fee paid out to the fronter which fronts the actual withdrawal on the smart chain,
+     *  the fee is paid out from all the respective tokens being withdrawn from the vault (NOTE: This returns raw token amounts,
+     *  which must be scaled by their respective vault configured multiplier to represent the actual amount
+     *  of tokens)
+     */
     getFrontingFee(): bigint[] {
         return this.rawAmounts.map(val => val * this.frontingFeeRate / 100_000n);
     }
 
+    /**
+     * Returns the fee that is transferred to the execution contract if swap+ execution action is assigned,
+     *  (NOTE: This returns raw token amounts, which must be scaled by their respective vault configured
+     *  multiplier to represent the actual amount of tokens)
+     */
     getExecutionFee(): bigint[] {
         return [this.rawAmounts[0] * this.executionFeeRate / 100_000n];
     }
 
+    /**
+     * Returns the total amount of tokens withdrawn from the vault (including all the fees) (NOTE: This returns
+     *  raw token amounts, which must be scaled by their respective vault configured multiplier to represent
+     *  the actual amount of tokens)
+     *
+     * @throws {Error} In case the amounts overflow
+     */
     getTotalOutput(): bigint[] {
         const amounts = [...this.getOutputWithoutFees()];
         const callerFee = this.getCallerFee();
@@ -138,6 +215,9 @@ export abstract class SpvWithdrawalTransactionData implements StorageObject {
         return amounts;
     }
 
+    /**
+     * Returns the execution action to be scheduled via the execution contract (swap+) or `null` if none specified
+     */
     getExecutionData(): ExecutionData | null {
         if(this.executionHash==null) return null;
         return {
@@ -146,23 +226,38 @@ export abstract class SpvWithdrawalTransactionData implements StorageObject {
         }
     }
 
+    /**
+     * Gets the transaction ID of the bitcoin transaction authorizing the withdrawal
+     */
     getTxId(): string {
         return this.btcTx.txid;
     }
 
+    /**
+     * Gets the vault ownership UTXO that the bitcoin transaction spends
+     */
     getSpentVaultUtxo(): string {
         const in0 = this.btcTx.ins[0];
         return in0.txid+":"+in0.vout;
     }
 
+    /**
+     * Gets the new vault ownership UTXO created by this transaction
+     */
     getCreatedVaultUtxo(): string {
         return this.getTxId()+":0";
     }
 
+    /**
+     * Gets the output locking script used for the new vault ownership UTXO
+     */
     getNewVaultScript(): Buffer {
         return Buffer.from(this.btcTx.outs[0].scriptPubKey.hex, "hex");
     }
 
+    /**
+     * Gets the output btc amount (in satoshis) assigned to the new vault ownership UTXO
+     */
     getNewVaultBtcAmount(): number {
         return this.btcTx.outs[0].value;
     }

package/src/storage/IStorageManager.ts

@@ -1,17 +1,58 @@
 import {StorageObject} from "./StorageObject";
 
+/**
+ * Interface for storage managers that persist StorageObject instances.
+ * Provides basic CRUD operations with in-memory caching via the data property.
+ *
+ * @typeParam T - Type of StorageObject to manage
+ *
+ * @category Storage
+ */
 export interface IStorageManager<T extends StorageObject> {
 
+    /** In-memory cache of stored objects, keyed by hash */
     data: {
         [key: string]: T
     };
 
+    /** Initializes the storage backend */
     init(): Promise<void>;
+
+    /**
+     * Saves an object to storage
+     *
+     * @param hash Unique identifier for the object
+     * @param object Object to save
+     */
     saveData(hash: string, object: T): Promise<void>;
+
+    /**
+     * Removes an object from storage
+     *
+     * @param hash Identifier of the object to remove
+     */
     removeData(hash: string): Promise<void>;
+
+    /**
+     * Loads all stored objects and deserializes them using the provided constructor
+     *
+     * @param type Constructor function to instantiate each object
+     * @returns Array of deserialized objects
+     */
     loadData(type: new(data: any) => T): Promise<T[]>;
 
+    /**
+     * Removes multiple objects from storage (optional batch operation)
+     *
+     * @param keys Array of identifiers to remove
+     */
     removeDataArr?(keys: string[]): Promise<void>;
+
+    /**
+     * Saves multiple objects to storage (optional batch operation)
+     *
+     * @param values Array of id-object pairs to save
+     */
     saveDataArr?(values: {id: string, object: T}[]): Promise<void>;
 
 }

package/src/storage/StorageObject.ts

@@ -1,7 +1,13 @@
-
-
+/**
+ * Represents an object that is serializable down to a JSON-compatible object (i.e. no bigints, functions, etc.)
+ *
+ * @category Storage
+ */
 export interface StorageObject {
 
+    /**
+     * Serializes the object to a JSON-compatible object (i.e. no bigints, functions, etc.)
+     */
     serialize(): any;
 
 }

package/src/swaps/ChainSwapType.ts

@@ -1,6 +1,28 @@
+/**
+ * Smart chain escrow swap types
+ *
+ * @category Swaps
+ */
 export enum ChainSwapType {
+    /**
+     * A hashlock based swap identified by a payment hash `P` requiring a hash preimage witness `s` such that `H(s) = P`,
+     *  actual chain implementations might slightly differ!
+     */
     HTLC = 0,
+    /**
+     * A proof-time locked based swap (PrTLC), which verifies a bitcoin transaction via a light client, and enforces
+     *  that the transaction pays out exactly `x` BTC to a pre-determined output script
+     */
     CHAIN = 1,
+    /**
+     * A proof-time locked based swap (PrTLC), which verifies a bitcoin transaction via a light client, enforces
+     *  that the transaction pays out exactly `x` BTC to a pre-determined output script and also checks the
+     *  transaction nonce to prevent replay attacks (the nonce is composed of transaction input nSequence fields
+     *  and transaction's locktime)
+     */
     CHAIN_NONCED = 2,
+    /**
+     * A simple proof-time locked based swap (PrTLC), which verifies a specific bitcoin transaction ID via a light client
+     */
     CHAIN_TXID = 3
 }

package/src/swaps/SwapCommitState.ts

@@ -1,31 +1,76 @@
+/**
+ * Possible on-chain states of the swap escrow
+ *
+ * @category Swaps
+ */
 export enum SwapCommitStateType {
+    /**
+     * The escrow specified by the swap data isn't currently active and the swap data has already expired
+     */
     EXPIRED=0,
+    /**
+     * The escrow specified by the swap data isn't currently active, could've been refunded already
+     */
     NOT_COMMITED=1,
+    /**
+     * The escrow is active on-chain and can be claimed
+     */
     COMMITED=2,
+    /**
+     * The escrow has been finalized and funds claimed by the claimer
+     */
     PAID=3,
+    /**
+     * The escrow is active on-chain and can be refunded by the offerer
+     */
     REFUNDABLE=4
 }
 
+/**
+ * The escrow specified by the swap data isn't currently active, could've been refunded already
+ *
+ * @category Swaps
+ */
 export type SwapNotCommitedState = {
     type: SwapCommitStateType.NOT_COMMITED,
     getRefundTxId?: () => Promise<string>,
     getTxBlock?: () => Promise<{blockHeight: number, blockTime: number}>
 };
 
+/**
+ * The escrow specified by the swap data isn't currently active and the swap data has already expired
+ *
+ * @category Swaps
+ */
 export type SwapExpiredState = {
     type: SwapCommitStateType.EXPIRED,
     getRefundTxId?: () => Promise<string>,
     getTxBlock?: () => Promise<{blockHeight: number, blockTime: number}>
 };
 
+/**
+ * The escrow is active on-chain and can be refunded by the offerer
+ *
+ * @category Swaps
+ */
 export type SwapRefundableState = {
     type: SwapCommitStateType.REFUNDABLE
 };
 
+/**
+ * The escrow is active on-chain and can be claimed
+ *
+ * @category Swaps
+ */
 export type SwapCommitedState = {
     type: SwapCommitStateType.COMMITED
 };
 
+/**
+ * The escrow has been finalized and funds claimed by the claimer
+ *
+ * @category Swaps
+ */
 export type SwapPaidState = {
     type: SwapCommitStateType.PAID,
     getClaimTxId: () => Promise<string>,
@@ -33,6 +78,11 @@ export type SwapPaidState = {
     getTxBlock: () => Promise<{blockHeight: number, blockTime: number}>
 };
 
+/**
+ * A union type for the state of the escrow
+ *
+ * @category Swaps
+ */
 export type SwapCommitState = SwapNotCommitedState |
     SwapExpiredState |
     SwapRefundableState |