@atomiqlabs/base 12.0.4 → 13.1.2

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/lightning/LightningNetworkApi.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A type defining total capacity of a given lightning network node
+ *
+ * @category Bitcoin
+ */
+export type LNNodeLiquidity = {
+    publicKey: string;
+    capacity: bigint;
+    numChannels: number;
+};
+/**
+ * An interface for Lightning API, provides view of the public lightning network data like channel graph
+ *
+ * @category Bitcoin
+ */
+export interface LightningNetworkApi {
+    /**
+     * Returns the lightning network's node liquidity as identified by an identity public key
+     *
+     * @param pubkey
+     */
+    getLNNodeLiquidity(pubkey: string): Promise<LNNodeLiquidity | null>;
+}

package/dist/btc/lightning/LightningNetworkApi.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -1,68 +1,235 @@
 /// <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;
         feeRate: number;
     }>;
+    /**
+     * Parses a bitcoin address from the passed output script in hexadecimal format
+     *
+     * @param outputScriptHex
+     */
+    outputScriptToAddress?(outputScriptHex: string): Promise<string>;
 }

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

@@ -0,0 +1,112 @@
+/// <reference types="node" />
+import { Buffer } from "buffer";
+import { BitcoinRpc, BtcTx } from "./BitcoinRpc";
+import { BtcBlock } from "../../btcrelay/types/BtcBlock";
+/**
+ * A type defining a bitcoin transaction with its blockheight and optional input addresses populated
+ *
+ * @category Bitcoin
+ */
+export type BtcTxWithBlockheight = BtcTx & {
+    blockheight?: number;
+    inputAddresses?: string[];
+};
+/**
+ * A type defining a single UTXO belonging to an address
+ *
+ * @category Bitcoin
+ */
+export type BtcAddressUtxo = {
+    txid: string;
+    vout: number;
+    confirmed: boolean;
+    block_height: number;
+    block_hash: string;
+    block_time: number;
+    value: bigint;
+};
+/**
+ * An extended interface for Bitcoin, that allows querying balances and UTXOs of any address + other utilities
+ *
+ * @category Bitcoin
+ */
+export interface BitcoinRpcWithAddressIndex<T extends BtcBlock> extends BitcoinRpc<T> {
+    /**
+     * Returns the current fee rate required for submitted bitcoin transactions in sats/vB
+     */
+    getFeeRate(): Promise<number>;
+    /**
+     * Returns confirmed & unconfirmed balances for a given wallet address
+     *
+     * @param address
+     */
+    getAddressBalances(address: string): Promise<{
+        confirmedBalance: bigint;
+        unconfirmedBalance: bigint;
+    }>;
+    /**
+     * Returns UTXOs owned by the given wallet address
+     * @param address
+     */
+    getAddressUTXOs(address: string): Promise<BtcAddressUtxo[]>;
+    /**
+     * Returns CPFP (children-pay-for-parent) data for a given transaction, or null if transaction is not found
+     *  or already confirmed
+     *
+     * @param txId
+     */
+    getCPFPData(txId: string): Promise<{
+        effectiveFeePerVsize: number;
+        adjustedVsize: number;
+    } | null>;
+    /**
+     * @inheritDoc
+     */
+    getTransaction(txId: string): Promise<BtcTxWithBlockheight | null>;
+    /**
+     * Awaits till the given transaction gets confirmed
+     *
+     * @param txId Transaction ID to monitor
+     * @param requiredConfirmations Required number of confirmations
+     * @param stateUpdateCbk Optional update callback called with the current status of the bitcoin transaction
+     * @param abortSignal
+     * @param intervalSeconds How often to poll
+     */
+    waitForTransaction(txId: string, requiredConfirmations: number, stateUpdateCbk?: (btcTx?: BtcTxWithBlockheight, txEtaMS?: number) => void, abortSignal?: AbortSignal, intervalSeconds?: number): Promise<BtcTxWithBlockheight>;
+    /**
+     * Returns an estimate after which time the tx will confirm with the required amount of confirmations,
+     *  confirmationDelay of -1 means the transaction won't confirm in the near future
+     *
+     * @param tx
+     * @param requiredConfirmations
+     *
+     * @returns estimated confirmation delay, -1 if the transaction won't confirm in the near future, null if the
+     *  transaction was replaced or was confirmed in the meantime
+     */
+    getConfirmationDelay(tx: BtcTx, requiredConfirmations: number): Promise<number | null>;
+    /**
+     * Checks if an address received the transaction with the required txoHash, returns info about that
+     *  specific transaction if found, or null if not found
+     *
+     * @param address Address that should receive the transaction
+     * @param txoHash Required output txoHash
+     */
+    checkAddressTxos(address: string, txoHash: Buffer): Promise<{
+        tx: Omit<BtcTxWithBlockheight, "hex" | "raw">;
+        vout: number;
+    } | null>;
+    /**
+     * Waits till the address receives a transaction containing a specific txoHash
+     *
+     * @param address Address that should receive the transaction
+     * @param txoHash Required output txoHash
+     * @param requiredConfirmations Required confirmations of the transaction
+     * @param stateUpdateCbk Callback for transaction state updates
+     * @param abortSignal Abort signal
+     * @param intervalSeconds How often to check new transaction
+     */
+    waitForAddressTxo(address: string, txoHash: Buffer, requiredConfirmations: number, stateUpdateCbk: (btcTx?: Omit<BtcTxWithBlockheight, "hex" | "raw">, vout?: number, txEtaMS?: number) => void, abortSignal?: AbortSignal, intervalSeconds?: number): Promise<{
+        tx: Omit<BtcTxWithBlockheight, "hex" | "raw">;
+        vout: number;
+    }>;
+}

package/dist/btc/rpc/BitcoinRpcWithAddressIndex.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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