@atomiqlabs/base 12.0.4 → 13.0.4

package/src/btcrelay/BtcRelay.ts

@@ -3,6 +3,11 @@ 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,
@@ -10,48 +15,126 @@ export interface BtcRelay<
     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
-    }>;
-    retrieveLogByCommitHash(commitHash: string, blockData: {blockhash: string, height: number}): Promise<V>;
+    } | 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 | null>;
 
+    /**
+     * Retrieves latest known bitcoin blockheader stored in the BTC Relay and also known to the bitcoin RPC
+     */
     retrieveLatestKnownBlockLog(): Promise<{
         resultStoredHeader: V,
         resultBitcoinHeader: B
-    }>;
-    //retrieveOnchainTip(): Promise<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,
@@ -59,13 +142,44 @@ export interface BtcRelay<
         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/src/btcrelay/synchronizer/RelaySynchronizer.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[], //Transactions required to synchronize the btc relay
-        targetCommitedHeader: V, //Latest committed header after synchronization
-        latestBlockHeader: B, //Latest block header after synchronization
-        computedHeaderMap: {[blockheight: number]: V}, //Mapping of synchronized committed headers
-        blockHeaderMap: {[blockheight: number]: B}, //Mapping of synchronized block headers
-        btcRelayTipCommitedHeader: V, //Tip committed header of the btc relay before synchronization
-        btcRelayTipBlockHeader: B, //Tip block header of the btc relay before synchronization
-        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/src/btcrelay/types/BtcBlock.ts

@@ -1,15 +1,55 @@
 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/src/btcrelay/types/BtcHeader.ts

@@ -1,12 +1,40 @@
 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,
-    getTimestamp(): number,
-    getNbits(): number,
-    getNonce(): number
+
+    /**
+     * Timestamp of the block
+     */
+    getTimestamp(): number;
+
+    /**
+     * nBits field of the block
+     */
+    getNbits(): number;
+
+    /**
+     * Nonce of the block
+     */
+    getNonce(): number;
 
 }

package/src/btcrelay/types/BtcStoredHeader.ts

@@ -1,13 +1,44 @@
 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/src/btcrelay/utils/StatePredictorUtils.ts

@@ -1,6 +1,11 @@
 import {Buffer} from "buffer";
 import {BigIntBufferUtils} from "../../utils/BigIntBufferUtils";
 
+/**
+ * Big integer arithmetic helpers for block difficulty calculations
+ *
+ * @internal
+ */
 export class StatePredictorUtils {
 
     static readonly DIFF_ADJUSTMENT_PERIOD = 2016;

package/src/chains/ChainData.ts

@@ -4,6 +4,11 @@ import {BitcoinNetwork} from "../btc/BitcoinNetwork";
 import {IStorageManager} from "../storage/IStorageManager";
 import {StorageObject} from "../storage/StorageObject";
 
+/**
+ * A type defining tokens available on the selected chain, indexed by ticker
+ *
+ * @category Tokens
+ */
 export type BaseTokenType<T extends string = string> = {
     [ticker in T]: {
         address: string,
@@ -12,6 +17,11 @@ export type BaseTokenType<T extends string = string> = {
     }
 };
 
+/**
+ * A comprehensive chain data type for a specific chain
+ *
+ * @category Chains
+ */
 export type ChainData<T extends ChainType> = {
     chainId: ChainType["ChainId"],
     chainInterface: T["ChainInterface"],
@@ -24,6 +34,12 @@ export type ChainData<T extends ChainType> = {
     spvVaultWithdrawalDataConstructor: new (data: any) => T["SpvVaultWithdrawalData"]
 };
 
+/**
+ * An initializer function that returns populated {@link ChainData} for a given chain based on the passed
+ *  arguments
+ *
+ * @category Chains
+ */
 export type ChainInitializerFn<O, C extends ChainType> = (
     options: O,
     bitcoinRpc: BitcoinRpc<any>,
@@ -31,10 +47,34 @@ export type ChainInitializerFn<O, C extends ChainType> = (
     storageCtor: <T extends StorageObject>(name: string) => IStorageManager<T>
 ) => ChainData<C>;
 
+/**
+ * Chain definition containing
+ *
+ * @category Chains
+ */
 export type ChainInitializer<O, C extends ChainType, T extends BaseTokenType> = {
+    /**
+     * Chain identifier string
+     */
     chainId: C["ChainId"],
-    chainType: C,
+    /**
+     * Initializer function returning the {@link ChainData}
+     */
     initializer: ChainInitializerFn<O, C>,
+    /**
+     * Available tokens on the chain
+     */
     tokens: T,
+    /**
+     * Chain type
+     *
+     * NOTE: This is just a type reference, should not be used as value
+     */
+    chainType: C,
+    /**
+     * The type of the options to be passed to the initializer function
+     *
+     * NOTE: This is just a type reference, should not be used as value
+     */
     options: O
 }

package/src/chains/ChainInterface.ts

@@ -1,9 +1,18 @@
+/**
+ * @category Chain
+ */
 export type TransactionConfirmationOptions = {
     waitForConfirmation?: boolean,
     abortSignal?: AbortSignal,
     feeRate?: string
 };
 
+/**
+ * Defines of a signer, contains an address getter and optionally init() & stop() functions
+ *  to initiate internal processes inside the signer (if required and exposed)
+ *
+ * @category Signer
+ */
 export type AbstractSigner = {
     type: "AtomiqAbstractSigner",
     getAddress: () => string,
@@ -11,17 +20,29 @@ export type AbstractSigner = {
     stop?: () => Promise<void>
 };
 
+/**
+ * Type guard for the {@link AbstractSigner} type
+ *
+ * @param val
+ */
 export function isAbstractSigner(val: any): val is AbstractSigner {
     return typeof(val)==="object" && val.type==="AtomiqAbstractSigner" && typeof(val.getAddress)==="function";
 }
 
+/**
+ * An interface representing a smart chain, allowing basic operations on the chain and reading chain data
+ */
 export interface ChainInterface<
     TX = any,
+    SignedTX = any,
     Signer extends AbstractSigner = AbstractSigner,
     ChainId extends string = string,
     NativeSigner = any
 > {
 
+    /**
+     * Chain identifier string
+     */
     readonly chainId: ChainId;
 
     /**
@@ -95,6 +116,20 @@ export interface ChainInterface<
      */
     deserializeTx(txData: string): Promise<TX>;
 
+    /**
+     * Serializes a given transaction to a string
+     *
+     * @param signedTX Transaction to serialize
+     */
+    serializeSignedTx(signedTX: SignedTX): Promise<string>;
+
+    /**
+     * Deserializes a transaction from string
+     *
+     * @param txData Serialized transaction data string
+     */
+    deserializeSignedTx(txData: string): Promise<SignedTX>;
+
     /**
      * Returns the status of the given serialized transaction
      *
@@ -128,6 +163,18 @@ export interface ChainInterface<
      */
     sendAndConfirm(signer: Signer, txs: TX[], waitForConfirmation?: boolean, abortSignal?: AbortSignal, parallel?: boolean, onBeforePublish?: (txId: string, rawTx: string) => Promise<void>): Promise<string[]>;
 
+    /**
+     * Sends already signed transactions and optionally waits for their confirmation
+     *
+     * @param signedTxs Signed transactions to be sent
+     * @param waitForConfirmation Whether to wait for transaction confirmation (if parallel is not specified,
+     *  every transaction's confirmation except the last one is awaited)
+     * @param abortSignal Abort signal
+     * @param parallel Whether to send all transactions in parallel or one by one (always waiting for the previous TX to confirm)
+     * @param onBeforePublish Callback called before a tx is broadcast
+     */
+    sendSignedAndConfirm(signedTxs: SignedTX[], waitForConfirmation?: boolean, abortSignal?: AbortSignal, parallel?: boolean, onBeforePublish?: (txId: string, rawTx: string) => Promise<void>): Promise<string[]>;
+
     /**
      * Callback called when transaction is being replaced (used for EVM, when fee is bumped on an unconfirmed tx)
      *

package/src/chains/ChainType.ts

@@ -7,26 +7,33 @@ import {SpvVaultData} from "../spv_swap/SpvVaultData";
 import {SpvVaultContract} from "../spv_swap/SpvVaultContract";
 import {SpvWithdrawalTransactionData} from "../spv_swap/SpvWithdrawalTransactionData";
 
+/**
+ * A comprehensive unified type struct for a given chain, contains all the type definitions of a given chain
+ *
+ * @category Chains
+ */
 export type ChainType<
     ChainId extends string = string,
     PreFetchData = any,
     PreFetchVerification = any,
     TXType = any,
+    SignedTXType = any,
     Signer extends AbstractSigner = AbstractSigner,
     NativeSigner = any,
     T extends SwapData = SwapData,
     C extends SwapContract<T, TXType, PreFetchData, PreFetchVerification, Signer, ChainId> = SwapContract<T, TXType, PreFetchData, PreFetchVerification, Signer, ChainId>,
-    I extends ChainInterface<TXType, Signer, ChainId, NativeSigner> = ChainInterface<TXType, Signer, ChainId, NativeSigner>,
+    I extends ChainInterface<TXType, SignedTXType, Signer, ChainId, NativeSigner> = ChainInterface<TXType, SignedTXType, Signer, ChainId, NativeSigner>,
     E extends ChainEvents<T> = ChainEvents<T>,
     B extends BtcRelay<any, TXType, any, Signer> = BtcRelay<any, TXType, any, Signer>,
-    SpvData extends SpvVaultData = SpvVaultData,
     SpvWithdrawalData extends SpvWithdrawalTransactionData = SpvWithdrawalTransactionData,
-    SpvContract extends SpvVaultContract<TXType, Signer, ChainId, SpvData, SpvWithdrawalData> = SpvVaultContract<TXType, Signer, ChainId, SpvData, SpvWithdrawalData>
+    SpvData extends SpvVaultData<SpvWithdrawalData> = SpvVaultData<SpvWithdrawalData>,
+    SpvContract extends SpvVaultContract<TXType, Signer, ChainId, SpvWithdrawalData, SpvData> = SpvVaultContract<TXType, Signer, ChainId, SpvWithdrawalData, SpvData>
 > = {
     ChainId: ChainId,
     PreFetchData: PreFetchData,
     PreFetchVerification: PreFetchVerification,
     TX: TXType,
+    SignedTXType: SignedTXType,
     Signer: Signer,
     ChainInterface: I,
     Data: T,

package/src/errors/CannotInitializeATAError.ts

@@ -1,4 +1,8 @@
-
+/**
+ * Represents a Solana-specific error when an ATA (associated token account) couldn't be initialized
+ *
+ * @category Errors
+ */
 export class CannotInitializeATAError extends Error {
 
     constructor(msg: string) {

package/src/errors/SignatureVerificationError.ts

@@ -1,4 +1,8 @@
-
+/**
+ * Represents a signature verification error
+ *
+ * @category Errors
+ */
 export class SignatureVerificationError extends Error {
 
     constructor(msg: string) {

package/src/errors/SwapDataVerificationError.ts

@@ -1,4 +1,8 @@
-
+/**
+ * Represents an error or inconsistency when verifying {@link SwapData}
+ *
+ * @category Errors
+ */
 export class SwapDataVerificationError extends Error {
 
     constructor(msg: string) {

package/src/errors/TransactionRevertedError.ts

@@ -1,4 +1,8 @@
-
+/**
+ * Indicates that the sent transaction has reverted (i.e. was confirmed but the execution failed)
+ *
+ * @category Errors
+ */
 export class TransactionRevertedError extends Error {
 
     constructor(msg: string) {