@atomiqlabs/base 12.0.4 → 13.0.4

package/dist/events/types/swap/InitializeEvent.d.ts

@@ -1,9 +1,20 @@
 import { SwapEvent, SwapEventType } from "./SwapEvent";
 import { SwapData } from "../../../swaps/SwapData";
 import { ChainSwapType } from "../../../swaps/ChainSwapType";
+/**
+ * Escrow swap Initialization event representation, emitted when an escrow is created
+ *
+ * @category Events
+ */
 export declare class InitializeEvent<T extends SwapData> extends SwapEvent<T, SwapEventType.INITIALIZE> {
     readonly eventType: SwapEventType.INITIALIZE;
+    /**
+     * Type of the escrow swap that was created (depends on the claim handler)
+     */
     swapType: ChainSwapType;
-    swapData: () => Promise<T>;
-    constructor(escrowHash: string, swapType: ChainSwapType, swapData: () => Promise<T>);
+    /**
+     * A getter for the actual full swap data that was used to initialize the escrow swap
+     */
+    swapData: () => Promise<T | null>;
+    constructor(escrowHash: string, swapType: ChainSwapType, swapData: () => Promise<T | null>);
 }

package/dist/events/types/swap/InitializeEvent.js

@@ -2,9 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InitializeEvent = void 0;
 const SwapEvent_1 = require("./SwapEvent");
+/**
+ * Escrow swap Initialization event representation, emitted when an escrow is created
+ *
+ * @category Events
+ */
 class InitializeEvent extends SwapEvent_1.SwapEvent {
     constructor(escrowHash, swapType, swapData) {
         super(escrowHash);
+        this.eventType = SwapEvent_1.SwapEventType.INITIALIZE;
         this.swapType = swapType;
         this.swapData = swapData;
     }

package/dist/events/types/swap/RefundEvent.d.ts

@@ -1,5 +1,10 @@
 import { SwapEvent, SwapEventType } from "./SwapEvent";
 import { SwapData } from "../../../swaps/SwapData";
+/**
+ * Escrow swap Refund event representation, offerer refunded funds from the escrow
+ *
+ * @category Events
+ */
 export declare class RefundEvent<T extends SwapData> extends SwapEvent<T, SwapEventType.REFUND> {
     readonly eventType: SwapEventType.REFUND;
 }

package/dist/events/types/swap/RefundEvent.js

@@ -2,6 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RefundEvent = void 0;
 const SwapEvent_1 = require("./SwapEvent");
+/**
+ * Escrow swap Refund event representation, offerer refunded funds from the escrow
+ *
+ * @category Events
+ */
 class RefundEvent extends SwapEvent_1.SwapEvent {
+    constructor() {
+        super(...arguments);
+        this.eventType = SwapEvent_1.SwapEventType.REFUND;
+    }
 }
 exports.RefundEvent = RefundEvent;

package/dist/events/types/swap/SwapEvent.d.ts

@@ -1,12 +1,25 @@
 import { SwapData } from "../../../swaps/SwapData";
 import { ChainEvent } from "../ChainEvent";
+/**
+ * Enum of the different types of escrow-swap specific events
+ *
+ * @category Events
+ */
 export declare enum SwapEventType {
     INITIALIZE = 0,
     REFUND = 1,
     CLAIM = 2
 }
-export declare class SwapEvent<T extends SwapData, C extends SwapEventType = SwapEventType> extends ChainEvent<T> {
-    readonly eventType: C;
+/**
+ * Represents an escrow-specific event
+ *
+ * @category Events
+ */
+export declare abstract class SwapEvent<T extends SwapData, C extends SwapEventType = SwapEventType> extends ChainEvent<T> {
+    abstract readonly eventType: C;
+    /**
+     * Identifier of the escrow, usually a hash of the full escrow swap data
+     */
     escrowHash: string;
     constructor(escrowHash: string);
 }

package/dist/events/types/swap/SwapEvent.js

@@ -2,12 +2,22 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SwapEvent = exports.SwapEventType = void 0;
 const ChainEvent_1 = require("../ChainEvent");
+/**
+ * Enum of the different types of escrow-swap specific events
+ *
+ * @category Events
+ */
 var SwapEventType;
 (function (SwapEventType) {
     SwapEventType[SwapEventType["INITIALIZE"] = 0] = "INITIALIZE";
     SwapEventType[SwapEventType["REFUND"] = 1] = "REFUND";
     SwapEventType[SwapEventType["CLAIM"] = 2] = "CLAIM";
 })(SwapEventType = exports.SwapEventType || (exports.SwapEventType = {}));
+/**
+ * Represents an escrow-specific event
+ *
+ * @category Events
+ */
 class SwapEvent extends ChainEvent_1.ChainEvent {
     constructor(escrowHash) {
         super();

package/dist/lockable/Lockable.d.ts

@@ -1,6 +1,24 @@
+/**
+ * A helper class for create an object based lock, ensuring only one lock on the object
+ *  can be acquired along with a given timeout
+ *
+ * @internal
+ * @category Utils
+ */
 export declare class Lockable {
     private lockedTill;
     private lockNonce;
+    /**
+     * Attempts to lock an object with a given timeout, returns null if the object is already locked and an unlock
+     *  callback function that unlocks this object.
+     *
+     * @param timeoutSeconds A timeout in seconds after which this object should be unlocked even if the unlock
+     *  function isn't called sooner
+     * @returns A callback, which shall be called to unlock an object, or `null` if the object is locked
+     */
     lock(timeoutSeconds: number): (() => boolean) | null;
+    /**
+     * Checks whether the object is currently locked
+     */
     isLocked(): boolean;
 }

package/dist/lockable/Lockable.js

@@ -1,11 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Lockable = void 0;
+/**
+ * A helper class for create an object based lock, ensuring only one lock on the object
+ *  can be acquired along with a given timeout
+ *
+ * @internal
+ * @category Utils
+ */
 class Lockable {
     constructor() {
         this.lockedTill = 0;
         this.lockNonce = 0;
     }
+    /**
+     * Attempts to lock an object with a given timeout, returns null if the object is already locked and an unlock
+     *  callback function that unlocks this object.
+     *
+     * @param timeoutSeconds A timeout in seconds after which this object should be unlocked even if the unlock
+     *  function isn't called sooner
+     * @returns A callback, which shall be called to unlock an object, or `null` if the object is locked
+     */
     lock(timeoutSeconds) {
         if (this.isLocked()) {
             return null;
@@ -21,6 +36,9 @@ class Lockable {
             return true;
         };
     }
+    /**
+     * Checks whether the object is currently locked
+     */
     isLocked() {
         return this.lockedTill > Date.now();
     }

package/dist/messaging/Messenger.d.ts

@@ -1,9 +1,41 @@
 import { Message } from "./messages/Message";
+/**
+ * An interface of a messenger, this is a generic data propagation layer, where parties can broadcast messages
+ *  and others can listen to these broadcasted messages
+ *
+ * @category Messenger
+ */
 export interface Messenger {
+    /**
+     * Initializes the messenger instance
+     */
     init(): Promise<void>;
+    /**
+     * The messenger implementation can expose a warmup function that warms up the connection before
+     *  an actual broadcast takes place (this is useful for browsers environments where you might
+     *  want to warmup the connection before the tab is backgrounded)
+     */
     warmup?(): Promise<void>;
+    /**
+     * Broadcast a message to the data propagation layer
+     *
+     * @param msg
+     */
     broadcast(msg: Message): Promise<void>;
+    /**
+     * Adds a listener to listen to broadcasted messages
+     *
+     * @param callback
+     */
     subscribe(callback: (msg: Message) => void): Promise<void>;
+    /**
+     * Removes a listener
+     *
+     * @param callback
+     */
     unsubscribe(callback: (msg: Message) => void): Promise<boolean>;
+    /**
+     * Stops the instance, releasing any resources used by it
+     */
     stop(): Promise<void>;
 }

package/dist/messaging/messages/Message.d.ts

@@ -1,11 +1,34 @@
+/**
+ * Currently defined types of the data propagation messages
+ *
+ * @category Messenger
+ */
 export declare enum MessageType {
     SWAP_CLAIM_WITNESS = 0
 }
+/**
+ * Representation of an abstract message in a data propagation layer
+ *
+ * @category Messenger
+ */
 export declare abstract class Message {
-    abstract type: MessageType;
+    abstract readonly type: MessageType;
+    /**
+     * A mapping of deserializers for different message types
+     *
+     * @internal
+     */
     static deserializers: {
         [type: number]: (obj: any) => Message;
     };
+    /**
+     * Serializes the message to a format that can be JSON serialized (i.e. no bigints, functions, etc.)
+     */
     serialize(): any;
+    /**
+     * Deserializer that parses the message from it's JSON compatible representation
+     *
+     * @param message
+     */
     static deserialize(message: any): Message;
 }

package/dist/messaging/messages/Message.js

@@ -1,16 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Message = exports.MessageType = void 0;
+/**
+ * Currently defined types of the data propagation messages
+ *
+ * @category Messenger
+ */
 var MessageType;
 (function (MessageType) {
     MessageType[MessageType["SWAP_CLAIM_WITNESS"] = 0] = "SWAP_CLAIM_WITNESS";
 })(MessageType = exports.MessageType || (exports.MessageType = {}));
+/**
+ * Representation of an abstract message in a data propagation layer
+ *
+ * @category Messenger
+ */
 class Message {
+    /**
+     * Serializes the message to a format that can be JSON serialized (i.e. no bigints, functions, etc.)
+     */
     serialize() {
         return {
             type: this.type
         };
     }
+    /**
+     * Deserializer that parses the message from it's JSON compatible representation
+     *
+     * @param message
+     */
     static deserialize(message) {
         const deserializer = Message.deserializers[message.type];
         if (deserializer == null)
@@ -19,4 +37,9 @@ class Message {
     }
 }
 exports.Message = Message;
+/**
+ * A mapping of deserializers for different message types
+ *
+ * @internal
+ */
 Message.deserializers = {};

package/dist/messaging/messages/SwapClaimWitnessMessage.d.ts

@@ -1,10 +1,28 @@
 import { SwapData } from "../../swaps/SwapData";
 import { Message, MessageType } from "./Message";
+/**
+ * Representation of an HTLC claim message, providing a swap pre-image in the `witness` field for a specific
+ *  escrow {@link SwapData}
+ *
+ * @category Messenger
+ */
 export declare class SwapClaimWitnessMessage<T extends SwapData> extends Message {
-    type: MessageType;
-    swapData: T;
-    witness: string;
+    readonly type = MessageType.SWAP_CLAIM_WITNESS;
+    /**
+     * Swap data of the escrow to claim
+     */
+    readonly swapData: T;
+    /**
+     * A witness allowing the claim of the escrow (i.e. a hash pre-image)
+     */
+    readonly witness: string;
     constructor(swapData: T, witness: string);
+    /**
+     * @inheritDoc
+     */
     serialize(): any;
-    static deserialize(obj: any): SwapClaimWitnessMessage<SwapData>;
+    /**
+     * @internal
+     */
+    static deserialize<T extends SwapData>(obj: any): SwapClaimWitnessMessage<T>;
 }

package/dist/messaging/messages/SwapClaimWitnessMessage.js

@@ -3,6 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SwapClaimWitnessMessage = void 0;
 const SwapData_1 = require("../../swaps/SwapData");
 const Message_1 = require("./Message");
+/**
+ * Representation of an HTLC claim message, providing a swap pre-image in the `witness` field for a specific
+ *  escrow {@link SwapData}
+ *
+ * @category Messenger
+ */
 class SwapClaimWitnessMessage extends Message_1.Message {
     constructor(swapData, witness) {
         super();
@@ -10,6 +16,9 @@ class SwapClaimWitnessMessage extends Message_1.Message {
         this.swapData = swapData;
         this.witness = witness;
     }
+    /**
+     * @inheritDoc
+     */
     serialize() {
         return {
             ...super.serialize(),
@@ -17,6 +26,9 @@ class SwapClaimWitnessMessage extends Message_1.Message {
             witness: this.witness
         };
     }
+    /**
+     * @internal
+     */
     static deserialize(obj) {
         if (obj == null || typeof (obj.witness) !== "string" || typeof (obj.swapData) !== "object") {
             throw new Error("Invalid format!");

package/dist/spv_swap/SpvVaultContract.d.ts

@@ -7,7 +7,15 @@ import { RelaySynchronizer } from "../btcrelay/synchronizer/RelaySynchronizer";
 import { SpvWithdrawalState } from "./SpvWithdrawalState";
 import { Buffer } from "buffer";
 import { BtcTx } from "../btc/rpc/BitcoinRpc";
-export interface SpvVaultContract<TX = any, Signer extends AbstractSigner = AbstractSigner, ChainId extends string = string, Data extends SpvVaultData = SpvVaultData, WithdrawalTX extends SpvWithdrawalTransactionData = SpvWithdrawalTransactionData> {
+/**
+ * Represents an SPV vault (UTXO-controlled vault) contract, exposes operations on the vaults
+ *
+ * @category Swaps
+ */
+export interface SpvVaultContract<TX = any, Signer extends AbstractSigner = AbstractSigner, ChainId extends string = string, WithdrawalTX extends SpvWithdrawalTransactionData = SpvWithdrawalTransactionData, Data extends SpvVaultData<WithdrawalTX> = SpvVaultData<WithdrawalTX>> {
+    /**
+     * Chain identifier string
+     */
     readonly chainId: ChainId;
     /**
      * Signs & sends transactions for opening a specific spv vault
@@ -129,7 +137,7 @@ export interface SpvVaultContract<TX = any, Signer extends AbstractSigner = Abst
      * @param owner Owner of the vault
      * @param vaultId Vault ID
      */
-    getVaultData(owner: string, vaultId: bigint): Promise<Data>;
+    getVaultData(owner: string, vaultId: bigint): Promise<Data | null>;
     /**
      * Returns current vault data for multiple vaults
      *
@@ -140,7 +148,7 @@ export interface SpvVaultContract<TX = any, Signer extends AbstractSigner = Abst
         vaultId: bigint;
     }[]): Promise<{
         [owner: string]: {
-            [vaultId: string]: Data;
+            [vaultId: string]: Data | null;
         };
     }>;
     /**
@@ -175,7 +183,7 @@ export interface SpvVaultContract<TX = any, Signer extends AbstractSigner = Abst
      * @param withdrawalTx
      * @param scStartBlockheight
      */
-    getWithdrawalState(withdrawalTx: WithdrawalTX, scStartBlockheight?: number): Promise<SpvWithdrawalState>;
+    getWithdrawalState(withdrawalTx: WithdrawalTX, scStartBlockheight?: number): Promise<SpvWithdrawalState | null>;
     /**
      * Returns current state of the withdrawals, optionally
      *  only check withdrawals from the provided block height
@@ -186,7 +194,7 @@ export interface SpvVaultContract<TX = any, Signer extends AbstractSigner = Abst
         withdrawal: WithdrawalTX;
         scStartBlockheight?: number;
     }[]): Promise<{
-        [btcTxId: string]: SpvWithdrawalState;
+        [btcTxId: string]: SpvWithdrawalState | null;
     }>;
     /**
      * Parses withdrawal data from the parsed bitcoin transaction
@@ -217,7 +225,7 @@ export interface SpvVaultContract<TX = any, Signer extends AbstractSigner = Abst
     fromOpReturnData(data: Buffer): {
         recipient: string;
         rawAmounts: bigint[];
-        executionHash: string;
+        executionHash?: string;
     };
     /**
      * Returns the fee in native token base units to claim the swap
@@ -227,7 +235,7 @@ export interface SpvVaultContract<TX = any, Signer extends AbstractSigner = Abst
      * @param withdrawalData Withdrawal to claim
      * @param feeRate Optional fee rate (fetched on-demand if not provided)
      */
-    getClaimFee(signer: string, vault: Data, withdrawalData: WithdrawalTX, feeRate?: string): Promise<bigint>;
+    getClaimFee(signer: string, vault?: Data, withdrawalData?: WithdrawalTX, feeRate?: string): Promise<bigint>;
     /**
      * Returns raw fee (not including any refunds we might get that would make the getClaimFee negative) for claiming the swap
      *
@@ -236,7 +244,7 @@ export interface SpvVaultContract<TX = any, Signer extends AbstractSigner = Abst
      * @param withdrawalData Withdrawal to claim
      * @param feeRate Optional fee rate (fetched on-demand if not provided)
      */
-    getRawClaimFee?(signer: string, vault: Data, withdrawalData: WithdrawalTX, feeRate?: string): Promise<bigint>;
+    getRawClaimFee?(signer: string, vault?: Data, withdrawalData?: WithdrawalTX, feeRate?: string): Promise<bigint>;
     /**
      * Returns the fee in native token base units to claim the swap
      *
@@ -245,7 +253,7 @@ export interface SpvVaultContract<TX = any, Signer extends AbstractSigner = Abst
      * @param withdrawalData Withdrawal to claim
      * @param feeRate Optional fee rate (fetched on-demand if not provided)
      */
-    getFrontFee(signer: string, vault: Data, withdrawalData: WithdrawalTX, feeRate?: string): Promise<bigint>;
+    getFrontFee(signer: string, vault?: Data, withdrawalData?: WithdrawalTX, feeRate?: string): Promise<bigint>;
     /**
      * Returns raw fee (not including any refunds we might get that would make the getClaimFee negative) for claiming the swap
      *
@@ -254,5 +262,5 @@ export interface SpvVaultContract<TX = any, Signer extends AbstractSigner = Abst
      * @param withdrawalData Withdrawal to claim
      * @param feeRate Optional fee rate (fetched on-demand if not provided)
      */
-    getRawFrontFee?(signer: string, vault: Data, withdrawalData: WithdrawalTX, feeRate?: string): Promise<bigint>;
+    getRawFrontFee?(signer: string, vault?: Data, withdrawalData?: WithdrawalTX, feeRate?: string): Promise<bigint>;
 }

package/dist/spv_swap/SpvVaultData.d.ts

@@ -4,30 +4,106 @@ import { SpvVaultClaimEvent } from "../events/types/spv_vault/SpvVaultClaimEvent
 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 declare 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;
+    /**
+     * @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[];

package/dist/spv_swap/SpvVaultData.js

@@ -1,12 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SpvVaultData = void 0;
+/**
+ * Represents the state of a single SPV vault (UTXO-controlled vault)
+ *
+ * @category Swaps
+ */
 class SpvVaultData {
+    /**
+     * Deserializer parsing the chain-specific spv vault data from a JSON-compatible object representation
+     *
+     * @param data
+     */
     static deserialize(data) {
         if (SpvVaultData.deserializers[data.type] != null) {
             return new SpvVaultData.deserializers[data.type](data);
         }
+        throw new Error(`No deserializer found for spv vault data type: ${data.type}`);
     }
+    /**
+     * A helper function which calculates the vault balances after processing an array of claims (withdrawals)
+     *
+     * @param priorWithdrawalTxs
+     */
     calculateStateAfter(priorWithdrawalTxs) {
         const balances = [...this.getBalances()];
         let withdrawalCount = this.getWithdrawalCount();
@@ -34,4 +50,7 @@ class SpvVaultData {
     }
 }
 exports.SpvVaultData = SpvVaultData;
+/**
+ * A mapping of deserializers for different spv vault data types coming from different smart chain implementations
+ */
 SpvVaultData.deserializers = {};