@atomiqlabs/base 12.0.3 → 13.0.4

package/dist/btc/BitcoinNetwork.d.ts

@@ -1,3 +1,8 @@
+/**
+ * An enum for various bitcoin network types
+ *
+ * @category Bitcoin
+ */
 export declare enum BitcoinNetwork {
     MAINNET = 0,
     TESTNET = 1,

package/dist/btc/BitcoinNetwork.js

@@ -1,6 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BitcoinNetwork = void 0;
+/**
+ * An enum for various bitcoin network types
+ *
+ * @category Bitcoin
+ */
 var BitcoinNetwork;
 (function (BitcoinNetwork) {
     BitcoinNetwork[BitcoinNetwork["MAINNET"] = 0] = "MAINNET";

package/dist/btc/rpc/BitcoinRpc.d.ts

@@ -1,65 +1,226 @@
 /// <reference types="node" />
 import { BtcBlock } from "../../btcrelay/types/BtcBlock";
 import { Buffer } from "buffer";
+/**
+ * A type defining a bitcoin transaction output
+ *
+ * @category Bitcoin
+ */
 export type BtcVout = {
+    /**
+     * Value of the output in satoshis
+     */
     value: number;
+    /**
+     * Position of the output in the transaction
+     */
     n: number;
+    /**
+     * Public key script defining spend conditions of the output
+     */
     scriptPubKey: {
         asm?: string;
         hex: string;
     };
 };
+/**
+ * A type defining a bitcoin transaction input
+ *
+ * @category Bitcoin
+ */
 export type BtcVin = {
+    /**
+     * Spent UTXO's transaction id
+     */
     txid: string;
+    /**
+     * Spent UTXO's output position in the transaction
+     */
     vout: number;
+    /**
+     * Signature scripting satisfying the spend conditions
+     */
     scriptSig: {
         asm?: string;
         hex: string;
     };
+    /**
+     * Input nSequence value
+     */
     sequence: number;
+    /**
+     * Witness data pushes in hexadecimal format
+     */
     txinwitness: string[];
 };
+/**
+ * A type defining a bitcoin transaction
+ *
+ * @category Bitcoin
+ */
 export type BtcTx = {
-    blockhash: string;
-    confirmations: number;
+    /**
+     * A blockhash which includes this transaction, or undefined for unconfirmed txns
+     */
+    blockhash?: string;
+    /**
+     * A number of confirmation that the block containing the transaction has, or undefined for unconfirmed txns
+     */
+    confirmations?: number;
+    /**
+     * Transaction size in vBytes (virtual bytes)
+     */
     vsize: number;
+    /**
+     * Transactions txId (reversed double sha256 hash of the transaction data excluding witness)
+     */
     txid: string;
+    /**
+     * Transaction encoded in hexadecimal format, without witness data (so the transaction is in legacy format)
+     */
     hex: string;
+    /**
+     * Full transaction encoded in hexadecimal format, with witness data
+     */
     raw: string;
+    /**
+     * Transaction's locktime field
+     */
     locktime: number;
+    /**
+     * Transaction's version
+     */
     version: number;
+    /**
+     * An array of outputs in the transactions
+     */
     outs: BtcVout[];
+    /**
+     * An array of inputs in the transaction
+     */
     ins: BtcVin[];
 };
+/**
+ * Representing a bitcoin block with all the transactions included
+ *
+ * @category Bitcoin
+ */
 export type BtcBlockWithTxs = {
     height: number;
     hash: string;
     tx: BtcTx[];
 };
+/**
+ * Information about the bitcoin RPCs synchronization status
+ *
+ * @category Bitcoin
+ */
 export type BtcSyncInfo = {
+    /**
+     * Whether the RPC is doing an IBD (initial block download)
+     */
     ibd: boolean;
+    /**
+     * How many blockheaders are available
+     */
     headers: number;
+    /**
+     * How many full bitcoin blocks are available
+     */
     blocks: number;
+    /**
+     * Progress of the full chain verification in percentages (0..100)
+     */
     verificationProgress: number;
 };
+/**
+ * An interface for Bitcoin RPC, providing access to Bitcoin on-chain data
+ *
+ * @category Bitcoin
+ */
 export interface BitcoinRpc<T extends BtcBlock> {
+    /**
+     * Checks whether a given blockhash is part of the canonical chain
+     *
+     * @param blockhash
+     */
     isInMainChain(blockhash: string): Promise<boolean>;
-    getBlockHeader(blockhash: string): Promise<T>;
+    /**
+     * Gets the bitcoin blockheader as identifier by the passed blockhash
+     *
+     * @param blockhash
+     */
+    getBlockHeader(blockhash: string): Promise<T | null>;
+    /**
+     * Returns a merkle proof for a given transaction
+     *
+     * @param txId Identifies the transaction
+     * @param blockhash The blockhash in which the transaction was included
+     */
     getMerkleProof(txId: string, blockhash: string): Promise<{
         reversedTxId: Buffer;
         pos: number;
         merkle: Buffer[];
         blockheight: number;
-    }>;
-    getTransaction(txId: string): Promise<BtcTx>;
-    getBlockhash(height: number): Promise<string>;
-    getBlockWithTransactions(blockhash: string): Promise<BtcBlockWithTxs>;
+    } | null>;
+    /**
+     * Returns the bitcoin transaction as identified by its txId
+     *
+     * @param txId
+     */
+    getTransaction(txId: string): Promise<BtcTx | null>;
+    /**
+     * Returns blockhash of a block at a given block height
+     *
+     * @param height
+     */
+    getBlockhash(height: number): Promise<string | null>;
+    /**
+     * Returns Bitcoin block with all the transactions based on blockhash
+     *
+     * @param blockhash
+     */
+    getBlockWithTransactions(blockhash: string): Promise<BtcBlockWithTxs | null>;
+    /**
+     * Sends a single raw transaction
+     *
+     * @param rawTx A hexadecimal-encoded bitcoin transaction
+     */
     sendRawTransaction(rawTx: string): Promise<string>;
+    /**
+     * Sends a Bitcoin transaction package composed of multiple individual transactions at the same time
+     *
+     * @param rawTx An array of hexadecimal-encoded bitcoin transactions
+     */
     sendRawPackage(rawTx: string[]): Promise<string[]>;
+    /**
+     * Returns the current tip blockheight of bitcoin
+     */
     getTipHeight(): Promise<number>;
+    /**
+     * Returns the synchronization information of the underlying bitcoin RPC
+     */
     getSyncInfo(): Promise<BtcSyncInfo>;
+    /**
+     * Parses a raw bitcoin transaction
+     *
+     * @param rawTx Hexadecimal-encoded bitcoin transaction
+     */
     parseTransaction(rawTx: string): Promise<BtcTx>;
+    /**
+     * Returns whether a given UTXO is spent or not, returns `false` for non-existing UTXOs
+     *
+     * @param utxo The UTXO to check, should be in format [txId]:[vout]
+     * @param confirmed Whether the spent has to be confirmed or can also be in the mempool
+     */
     isSpent(utxo: string, confirmed?: boolean): Promise<boolean>;
+    /**
+     * Returns an effective fee rate of the provided bitcoin transaction, this takes into consideration
+     *  the current fee rates of the potential unconfirmed inputs of the transaction that are already
+     *  in the mempool
+     *
+     * @param btcTx
+     */
     getEffectiveFeeRate(btcTx: BtcTx): Promise<{
         vsize: number;
         fee: number;

package/dist/btcrelay/BtcRelay.d.ts

@@ -3,59 +3,168 @@ import { BtcStoredHeader } from "./types/BtcStoredHeader";
 import { BtcBlock } from "./types/BtcBlock";
 import { Buffer } from "buffer";
 import { AbstractSigner } from "../chains/ChainInterface";
+/**
+ * Represents a BTC relay bitcoin light client contract, which verifies the bitcoin blockheaders on smart chains
+ *
+ * @category BTC Relay
+ */
 export interface BtcRelay<V extends BtcStoredHeader<any>, T, B extends BtcBlock, Signer extends AbstractSigner = AbstractSigner> {
+    /**
+     * Maximum blockheaders that fit in a single transaction
+     */
     maxHeadersPerTx: number;
+    /**
+     * Maximum amount of fork headers that fit in a single transactions
+     */
     maxForkHeadersPerTx: number;
+    /**
+     * Maximum amount of fork headers that can be submitted at once using the short fork method
+     */
     maxShortForkHeadersPerTx?: number;
+    /**
+     * Returns data about current main chain tip stored in the btc relay
+     */
     getTipData(): Promise<{
         blockheight: number;
         blockhash: string;
         commitHash: string;
         chainWork: Buffer;
-    }>;
+    } | null>;
+    /**
+     * Retrieves blockheader with a specific blockhash, returns null if `requiredBlockheight` is provided and
+     *  btc relay contract is not synced up to the desired blockheight
+     *
+     * @param blockData
+     * @param requiredBlockheight
+     */
     retrieveLogAndBlockheight(blockData: {
         blockhash: string;
         height: number;
     }, requiredBlockheight?: number): Promise<{
         header: V;
         height: number;
-    }>;
+    } | null>;
+    /**
+     * Retrieves stored bitcoin blockheader data by blockheader's commit hash and provided
+     *  blockhash from `blockData`
+     *
+     * @param commitHash
+     * @param blockData
+     */
     retrieveLogByCommitHash(commitHash: string, blockData: {
         blockhash: string;
         height: number;
-    }): Promise<V>;
+    }): Promise<V | null>;
+    /**
+     * Retrieves latest known bitcoin blockheader stored in the BTC Relay and also known to the bitcoin RPC
+     */
     retrieveLatestKnownBlockLog(): Promise<{
         resultStoredHeader: V;
         resultBitcoinHeader: B;
-    }>;
+    } | null>;
+    /**
+     * Initializes the underlying BTC Relay contract
+     *
+     * @param signer A signer's address to use for the transaction
+     * @param header Main chain blockheader to use as a genesis
+     * @param epochStart Timestamp of the first block in this difficulty epoch
+     * @param pastBlocksTimestamps Timestamps of the last 11 blockheaders, for median block time rule
+     * @param feeRate Optional fee rate for the transaction
+     */
     saveInitialHeader(signer: string, header: B, epochStart: number, pastBlocksTimestamps: number[], feeRate?: string): Promise<T>;
+    /**
+     * Returns a transaction that submits bitcoin blockheaders as a bitcoin main chain to the btc relay
+     *
+     * @param signer A signer's address for the transaction
+     * @param mainHeaders New bitcoin blockheaders to submit
+     * @param storedHeader Latest committed and stored bitcoin blockheader in the BTC relay
+     * @param feeRate Optional fee rate for the transaction
+     */
     saveMainHeaders(signer: string, mainHeaders: B[], storedHeader: V, feeRate?: string): Promise<{
         forkId: number;
         lastStoredHeader: V;
         tx: T;
         computedCommitedHeaders: V[];
     }>;
+    /**
+     * Returns a transaction that submits a new long fork and submits the first headers to it
+     *
+     * @param signer A signer's address for the transaction
+     * @param forkHeaders New fork bitcoin blockheaders to submit
+     * @param storedHeader Committed and stored bitcoin blockheader in the BTC relay from which to fork
+     * @param tipWork Chainwork of the current BTC Relay main chain tip
+     * @param feeRate Optional fee rate for the transaction
+     */
     saveNewForkHeaders(signer: string, forkHeaders: B[], storedHeader: V, tipWork: Buffer, feeRate?: string): Promise<{
         forkId: number;
         lastStoredHeader: V;
         tx: T;
         computedCommitedHeaders: V[];
     }>;
+    /**
+     * Returns a transaction that continues submitting blockheaders to an existing long fork
+     *
+     * @param signer A signer's address for the transaction
+     * @param forkHeaders New fork bitcoin blockheaders to submit
+     * @param storedHeader Committed and stored bitcoin blockheader in the BTC relay from which to fork
+     * @param forkId Fork ID to submit the blockheaders to
+     * @param tipWork Chainwork of the current BTC Relay main chain tip
+     * @param feeRate Optional fee rate for the transaction
+     */
     saveForkHeaders(signer: string, forkHeaders: B[], storedHeader: V, forkId: number, tipWork: Buffer, feeRate?: string): Promise<{
         forkId: number;
         lastStoredHeader: V;
         tx: T;
         computedCommitedHeaders: V[];
     }>;
+    /**
+     * Returns a transaction that submits a short fork with the provided blockheaders
+     *
+     * @param signer A signer's address for the transaction
+     * @param forkHeaders New fork bitcoin blockheaders to submit
+     * @param storedHeader Committed and stored bitcoin blockheader in the BTC relay from which to fork
+     * @param tipWork Chainwork of the current BTC Relay main chain tip
+     * @param feeRate Optional fee rate for the transaction
+     */
     saveShortForkHeaders?(signer: string, forkHeaders: B[], storedHeader: V, tipWork: Buffer, feeRate?: string): Promise<{
         forkId: number;
         lastStoredHeader: V;
         tx: T;
         computedCommitedHeaders: V[];
     }>;
-    getMainFeeRate?(signer: string): Promise<string>;
-    getForkFeeRate?(signer: string, forkId: number): Promise<string>;
+    /**
+     * Gets fee rate required for submitting blockheaders to the main chain
+     *
+     * @param signer A signer's address to use for the estimation
+     */
+    getMainFeeRate(signer: string): Promise<string>;
+    /**
+     * Gets fee rate required for submitting blockheaders to the specific fork
+     *
+     * @param signer A signer's address to use for the estimation
+     * @param forkId A fork ID to use for estimation
+     */
+    getForkFeeRate(signer: string, forkId: number): Promise<string>;
+    /**
+     * Estimate required synchronization fee (worst case) to synchronize btc relay to the required blockheight
+     *
+     * @param requiredBlockheight Blockheight to which to synchronize
+     * @param feeRate Optional fee rate to use for the estimation
+     */
     estimateSynchronizeFee(requiredBlockheight: number, feeRate?: string): Promise<bigint>;
+    /**
+     * Returns required fee in native token to synchronize a single block to btc relay
+     *
+     * @param feeRate Optional fee rate to use for the estimation
+     */
     getFeePerBlock(feeRate?: any): Promise<bigint>;
+    /**
+     * Checks and sweeps data accounts which contain yet unused fork data (use for Solana's PDAs)
+     *
+     * @param signer A signer's address to check account for
+     * @param lastSweepTimestamp Timestamp of the last sweep
+     *
+     * @returns A number of data accounts swept
+     */
     sweepForkData?(signer: Signer, lastSweepTimestamp?: number): Promise<number | null>;
 }

package/dist/btcrelay/synchronizer/RelaySynchronizer.d.ts

@@ -1,18 +1,59 @@
 import { BtcStoredHeader } from "../types/BtcStoredHeader";
 import { BtcBlock } from "../types/BtcBlock";
+export type SynchronizationResponse<V extends BtcStoredHeader<any>, T, B extends BtcBlock> = {
+    /**
+     * Transactions required to synchronize the btc relay
+     */
+    txs: T[];
+    /**
+     * Latest committed header after synchronization
+     */
+    targetCommitedHeader: V;
+    /**
+     * Latest block header after synchronization
+     */
+    latestBlockHeader: B;
+    /**
+     * Mapping of synchronized committed headers, based on blockheight
+     */
+    computedHeaderMap: {
+        [blockheight: number]: V;
+    };
+    /**
+     * Mapping of synchronized block headers, based on blockheight
+     */
+    blockHeaderMap: {
+        [blockheight: number]: B;
+    };
+    /**
+     * Tip committed header of the btc relay before synchronization
+     */
+    btcRelayTipCommitedHeader: V;
+    /**
+     * Tip block header of the btc relay before synchronization
+     */
+    btcRelayTipBlockHeader: B;
+    /**
+     * A fork ID that was used to re-org the chain to the current canonical chain
+     */
+    startForkId?: number;
+};
+/**
+ * An interface for a synchronizer of the BTC relay bitcoin light client contract, produces transactions
+ *  necessary to synchronize the underlying relay contract to the current tip of the canonical chain,
+ *  automatically handles forking if necessary
+ *
+ * @category BTC Relay
+ */
 export interface RelaySynchronizer<V extends BtcStoredHeader<any>, T, B extends BtcBlock> {
-    syncToLatestTxs(signer: string, feeRate?: string): Promise<{
-        txs: T[];
-        targetCommitedHeader: V;
-        latestBlockHeader: B;
-        computedHeaderMap: {
-            [blockheight: number]: V;
-        };
-        blockHeaderMap: {
-            [blockheight: number]: B;
-        };
-        btcRelayTipCommitedHeader: V;
-        btcRelayTipBlockHeader: B;
-        startForkId?: number;
-    }>;
+    /**
+     * Returns the transactions necessary to synchronize the BTC relay contract to the
+     *  tip of the canonical chain. Also returns the various bitcoin blockheaders that
+     *  are to-be-synced to the relay, such that they can be used to already pre-create
+     *  transactions, which require the stored blockheaders
+     *
+     * @param signer Transactions signer's address
+     * @param feeRate Optional fee rate to use for the transactions
+     */
+    syncToLatestTxs(signer: string, feeRate?: string): Promise<SynchronizationResponse<V, T, B>>;
 }

package/dist/btcrelay/types/BtcBlock.d.ts

@@ -1,13 +1,45 @@
 /// <reference types="node" />
 import { Buffer } from "buffer";
+/**
+ * Represents a bitcoin block header as fetched from the RPC
+ *
+ * @category Bitcoin
+ */
 export interface BtcBlock {
+    /**
+     * Block's version field
+     */
     getVersion(): number;
+    /**
+     * Previous block hash
+     */
     getPrevBlockhash(): string;
+    /**
+     * Merkle root of the transactions tree
+     */
     getMerkleRoot(): string;
+    /**
+     * Timestamp of the block
+     */
     getTimestamp(): number;
+    /**
+     * nBits field of the block
+     */
     getNbits(): number;
+    /**
+     * Nonce of the block
+     */
     getNonce(): number;
+    /**
+     * Block hash of this block
+     */
     getHash(): string;
+    /**
+     * Height at which this block was mined
+     */
     getHeight(): number;
+    /**
+     * Total accumulated chainwork at this block
+     */
     getChainWork(): Buffer;
 }

package/dist/btcrelay/types/BtcHeader.d.ts

@@ -1,10 +1,33 @@
 /// <reference types="node" />
 import { Buffer } from "buffer";
+/**
+ * Represents a raw bitcoin header (80-bytes) that can be synchronized to the underlying BTC relay light client contract
+ *
+ * @category BTC Relay
+ */
 export interface BtcHeader {
+    /**
+     * Version of the block
+     */
     getVersion(): number;
+    /**
+     * Hash of the previous block in little-endian representation
+     */
     getReversedPrevBlockhash(): Buffer;
+    /**
+     * Merkle root of the transactions tree
+     */
     getMerkleRoot(): Buffer;
+    /**
+     * Timestamp of the block
+     */
     getTimestamp(): number;
+    /**
+     * nBits field of the block
+     */
     getNbits(): number;
+    /**
+     * Nonce of the block
+     */
     getNonce(): number;
 }

package/dist/btcrelay/types/BtcStoredHeader.d.ts

@@ -1,11 +1,37 @@
 /// <reference types="node" />
 import { BtcHeader } from "./BtcHeader";
 import { Buffer } from "buffer";
+/**
+ * Represents a bitcoin blockheader that has already been synchronized and saved (committed) in the BTC relay
+ *  contract
+ *
+ * @category BTC Relay
+ */
 export interface BtcStoredHeader<T extends BtcHeader> {
+    /**
+     * Total accumulated chainwork at this block
+     */
     getChainWork(): Buffer;
+    /**
+     * The actual blockheader that was saved
+     */
     getHeader(): T;
+    /**
+     * UNIX seconds timestamp of the last difficulty adjustment
+     */
     getLastDiffAdjustment(): number;
+    /**
+     * Blockheight of the current block
+     */
     getBlockheight(): number;
+    /**
+     * UNIX seconds timestamps of the last 11 blocks, used for checking the median block time rule
+     */
     getPrevBlockTimestamps(): number[];
+    /**
+     * Computes and returns a new stored blockheader after adding a new blockheader on top of it
+     *
+     * @param header The new blockheader to append to the chain
+     */
     computeNext(header: T): BtcStoredHeader<T>;
 }

package/dist/btcrelay/utils/StatePredictorUtils.d.ts

@@ -1,5 +1,10 @@
 /// <reference types="node" />
 import { Buffer } from "buffer";
+/**
+ * Big integer arithmetic helpers for block difficulty calculations
+ *
+ * @internal
+ */
 export declare class StatePredictorUtils {
     static readonly DIFF_ADJUSTMENT_PERIOD = 2016;
     static gtBuffer(a: Buffer, b: Buffer): boolean;

package/dist/btcrelay/utils/StatePredictorUtils.js

@@ -3,6 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.StatePredictorUtils = void 0;
 const buffer_1 = require("buffer");
 const BigIntBufferUtils_1 = require("../../utils/BigIntBufferUtils");
+/**
+ * Big integer arithmetic helpers for block difficulty calculations
+ *
+ * @internal
+ */
 class StatePredictorUtils {
     static gtBuffer(a, b) {
         for (let i = 0; i < a.length; i++) {