@atomiqlabs/chain-evm 2.1.11 → 2.1.14

package/src/chains/citrea/CitreaBtcRelay.ts

@@ -5,6 +5,11 @@ import {CitreaFees} from "./CitreaFees";
 
 const logger = getLogger("CitreaBtcRelay: ");
 
+/**
+ * Citrea BTC relay wrapper with fee estimation that includes Citrea state-diff costs.
+ *
+ * @category Networks/Citrea
+ */
 export class CitreaBtcRelay<B extends BtcBlock> extends EVMBtcRelay<B> {
 
     public static StateDiffSize = {
@@ -32,7 +37,7 @@ export class CitreaBtcRelay<B extends BtcBlock> extends EVMBtcRelay<B> {
 
         const synchronizationFee = (BigInt(blockheightDelta) * await this.getFeePerBlock(feeRate))
             + CitreaFees.getGasFee(
-                EVMBtcRelay.GasCosts.GAS_BASE_MAIN * numTxs,
+                EVMBtcRelay._GasCosts.GAS_BASE_MAIN * numTxs,
                 feeRate,
                 CitreaBtcRelay.StateDiffSize.STATE_DIFF_BASE * numTxs
             );
@@ -50,10 +55,10 @@ export class CitreaBtcRelay<B extends BtcBlock> extends EVMBtcRelay<B> {
     public async getFeePerBlock(feeRate?: string): Promise<bigint> {
         feeRate ??= await this.Chain.Fees.getFeeRate();
         return CitreaFees.getGasFee(
-            EVMBtcRelay.GasCosts.GAS_PER_BLOCKHEADER,
+            EVMBtcRelay._GasCosts.GAS_PER_BLOCKHEADER,
             feeRate,
             CitreaBtcRelay.StateDiffSize.STATE_DIFF_PER_BLOCKHEADER
         );
     }
 
-}
+}

package/src/chains/citrea/CitreaFees.ts

@@ -6,10 +6,9 @@ import {getLogger} from "../../utils/Utils";
  */
 export class CitreaFees extends EVMFees {
 
-    public static readonly StateDiffSize = {
-        APPROVE_DIFF_SIZE: 40,
-    };
-
+    /**
+     * @internal
+     */
     protected readonly logger = getLogger("CitreaFees: ");
 
     private _blockFeeCache?: {
@@ -35,8 +34,6 @@ export class CitreaFees extends EVMFees {
 
     /**
      * Gets the gas price with caching, format: <gas price in Wei>;<transaction version: v1/v3>
-     *
-     * @private
      */
     public async getFeeRate(): Promise<string> {
         if(this._blockFeeCache==null || Date.now() - this._blockFeeCache.timestamp > this.MAX_FEE_AGE) {

package/src/chains/citrea/CitreaInitializer.ts

@@ -1,6 +1,6 @@
 import {BaseTokenType, BitcoinNetwork, BitcoinRpc, ChainData, ChainInitializer, ChainSwapType} from "@atomiqlabs/base";
-import {JsonRpcApiProvider, JsonRpcProvider, WebSocketProvider} from "ethers";
-import {EVMChainInterface, EVMConfiguration, EVMRetryPolicy} from "../../evm/chain/EVMChainInterface";
+import {JsonRpcProvider, WebSocketProvider} from "ethers";
+import {EVMChainInterface} from "../../evm/chain/EVMChainInterface";
 import {CitreaChainType} from "./CitreaChainType";
 import {EVMChainEventsBrowser} from "../../evm/events/EVMChainEventsBrowser";
 import {EVMSwapData} from "../../evm/swaps/EVMSwapData";
@@ -11,6 +11,7 @@ import {CitreaBtcRelay} from "./CitreaBtcRelay";
 import {CitreaSwapContract} from "./CitreaSwapContract";
 import {CitreaTokens} from "./CitreaTokens";
 import {CitreaSpvVaultContract} from "./CitreaSpvVaultContract";
+import {EVMOptions} from "../EVMOptions";
 
 const CitreaChainIds = {
     MAINNET: 4114,
@@ -75,7 +76,7 @@ export type CitreaAssetsType = BaseTokenType<"CBTC" | "WBTC" | "USDC">;
  * Default Citrea token assets configuration
  * @category Networks/Citrea
  */
-export const CitreaAssets: CitreaAssetsType = {
+const CitreaAssets: CitreaAssetsType = {
     CBTC: {
         address: "0x0000000000000000000000000000000000000000",
         decimals: 18,
@@ -97,30 +98,7 @@ export const CitreaAssets: CitreaAssetsType = {
  * Configuration options for initializing Citrea chain
  * @category Networks/Citrea
  */
-export type CitreaOptions = {
-    rpcUrl: string | JsonRpcApiProvider,
-    retryPolicy?: EVMRetryPolicy,
-    chainType?: "MAINNET" | "TESTNET4",
-
-    swapContract?: string,
-    swapContractDeploymentHeight?: number,
-    btcRelayContract?: string,
-    btcRelayDeploymentHeight?: number,
-    spvVaultContract?: string,
-    spvVaultDeploymentHeight?: number,
-    handlerContracts?: {
-        refund?: {
-            timelock?: string
-        },
-        claim?: {
-            [type in ChainSwapType]?: string
-        }
-    }
-
-    fees?: CitreaFees,
-
-    evmConfig?: Partial<Omit<EVMConfiguration, "safeBlockTag" | "finalizedBlockTag" | "finalityCheckStrategy">>
-}
+export type CitreaOptions = EVMOptions<"MAINNET" | "TESTNET4", CitreaFees>;
 
 /**
  * Initialize Citrea chain integration

package/src/chains/citrea/CitreaSpvVaultContract.ts

@@ -6,6 +6,11 @@ import {CitreaFees} from "./CitreaFees";
 import {EVMAddresses} from "../../evm/chain/modules/EVMAddresses";
 
 
+/**
+ * Citrea SPV vault wrapper with fee estimation adjusted by expected state-diff size.
+ *
+ * @category Networks/Citrea
+ */
 export class CitreaSpvVaultContract extends EVMSpvVaultContract<"CITREA"> {
 
     public static readonly StateDiffSize = {
@@ -30,7 +35,7 @@ export class CitreaSpvVaultContract extends EVMSpvVaultContract<"CITREA"> {
     }
 
     async getClaimFee(signer: string, vault?: EVMSpvVaultData, data?: EVMSpvWithdrawalData, feeRate?: string): Promise<bigint> {
-        vault ??= EVMSpvVaultData.randomVault();
+        vault ??= EVMSpvVaultData._randomVault();
         feeRate ??= await this.Chain.Fees.getFeeRate();
         const tokenStateChanges: Set<string> = new Set();
 
@@ -56,7 +61,7 @@ export class CitreaSpvVaultContract extends EVMSpvVaultContract<"CITREA"> {
     }
 
     async getFrontFee(signer: string, vault?: EVMSpvVaultData, data?: EVMSpvWithdrawalData, feeRate?: string): Promise<bigint> {
-        vault ??= EVMSpvVaultData.randomVault();
+        vault ??= EVMSpvVaultData._randomVault();
         feeRate ??= await this.Chain.Fees.getFeeRate();
         const tokenStateChanges: Set<string> = new Set();
 

package/src/chains/citrea/CitreaSwapContract.ts

@@ -2,6 +2,11 @@ import {EVMSwapContract} from "../../evm/swaps/EVMSwapContract";
 import {EVMSwapData} from "../../evm/swaps/EVMSwapData";
 import {CitreaFees} from "./CitreaFees";
 
+/**
+ * Citrea swap contract wrapper with fee estimation adjusted by expected state-diff size.
+ *
+ * @category Networks/Citrea
+ */
 export class CitreaSwapContract extends EVMSwapContract<"CITREA"> {
 
     public static readonly StateDiffSize = {
@@ -27,7 +32,7 @@ export class CitreaSwapContract extends EVMSwapContract<"CITREA"> {
     }
 
     /**
-     * Get the estimated solana fee of the commit transaction
+     * Returns estimated fee of the commit transaction, including Citrea state-diff overhead.
      */
     async getCommitFee(signer: string, swapData: EVMSwapData, feeRate?: string): Promise<bigint> {
         feeRate ??= await this.Chain.Fees.getFeeRate();
@@ -45,7 +50,7 @@ export class CitreaSwapContract extends EVMSwapContract<"CITREA"> {
         }
         diffSize += this.calculateStateDiff(signer, tokenStateChanges);
 
-        const gasFee = await this.Init.getInitFee(swapData, feeRate);
+        const gasFee = await this._Init.getInitFee(swapData, feeRate);
         return gasFee + CitreaFees.getGasFee(0, feeRate, diffSize);
     }
 
@@ -69,12 +74,12 @@ export class CitreaSwapContract extends EVMSwapContract<"CITREA"> {
         }
         diffSize += this.calculateStateDiff(signer, tokenStateChanges);
 
-        const gasFee = await this.Claim.getClaimFee(swapData, feeRate);
+        const gasFee = await this._Claim.getClaimFee(swapData, feeRate);
         return gasFee + CitreaFees.getGasFee(0, feeRate, diffSize);
     }
 
     /**
-     * Get the estimated solana transaction fee of the refund transaction
+     * Returns estimated fee of the refund transaction, including Citrea state-diff overhead.
      */
     async getRefundFee(signer: string, swapData: EVMSwapData, feeRate?: string): Promise<bigint> {
         feeRate ??= await this.Chain.Fees.getFeeRate();
@@ -96,8 +101,8 @@ export class CitreaSwapContract extends EVMSwapContract<"CITREA"> {
         }
         diffSize += this.calculateStateDiff(signer, tokenStateChanges);
 
-        const gasFee = await this.Refund.getRefundFee(swapData, feeRate);
+        const gasFee = await this._Refund.getRefundFee(swapData, feeRate);
         return gasFee + CitreaFees.getGasFee(0, feeRate, diffSize);
     }
 
-}
+}

package/src/chains/citrea/CitreaTokens.ts

@@ -2,6 +2,11 @@ import {EVMTokens} from "../../evm/chain/modules/EVMTokens";
 import {CitreaFees} from "./CitreaFees";
 
 
+/**
+ * Citrea-specific token module that augments fee estimation with state-diff costs.
+ *
+ * @category Networks/Citrea
+ */
 export class CitreaTokens extends EVMTokens {
 
     public static readonly StateDiffSize = {
@@ -19,4 +24,4 @@ export class CitreaTokens extends EVMTokens {
         return CitreaFees.getGasFee(EVMTokens.GasCosts.APPROVE, feeRate, CitreaTokens.StateDiffSize.TRANSFER_DIFF_SIZE);
     }
 
-}
+}

package/src/chains/goat/GoatChainType.ts

@@ -12,11 +12,11 @@ import {EVMBtcRelay} from "../../evm/btcrelay/EVMBtcRelay";
 import {EVMSpvVaultContract} from "../../evm/spv_swap/EVMSpvVaultContract";
 import {Signer} from "ethers";
 
-/**
- * Type definition for the GOAT Network chain implementation
- * @category Networks/GOAT
- */
-export type GoatChainType = ChainType<
+/**
+ * Type definition for the GOAT Network chain implementation
+ * @category Networks/GOAT
+ */
+export type GoatChainType = ChainType<
     "GOAT",
     never,
     EVMPreFetchVerification,

package/src/chains/goat/GoatInitializer.ts

@@ -10,6 +10,7 @@ import {EVMSwapData} from "../../evm/swaps/EVMSwapData";
 import {EVMSpvVaultData} from "../../evm/spv_swap/EVMSpvVaultData";
 import {EVMSpvWithdrawalData} from "../../evm/spv_swap/EVMSpvWithdrawalData";
 import {GoatChainType} from "./GoatChainType";
+import {EVMOptions} from "../EVMOptions";
 
 const GoatChainIds = {
     MAINNET: 2345,
@@ -96,7 +97,7 @@ export type GoatAssetsType = BaseTokenType<"BTC" | "PBTC" | "_PBTC_DEV">;
  * Default GOAT Network token assets configuration
  * @category Networks/GOAT
  */
-export const GoatAssets: GoatAssetsType = {
+const GoatAssets: GoatAssetsType = {
     BTC: {
         address: "0x0000000000000000000000000000000000000000",
         decimals: 18,
@@ -118,30 +119,7 @@ export const GoatAssets: GoatAssetsType = {
  * Configuration options for initializing GOAT Network chain
  * @category Networks/GOAT
  */
-export type GoatOptions = {
-    rpcUrl: string | JsonRpcApiProvider,
-    retryPolicy?: EVMRetryPolicy,
-    chainType?: "MAINNET" | "TESTNET" | "TESTNET4",
-
-    swapContract?: string,
-    swapContractDeploymentHeight?: number,
-    btcRelayContract?: string,
-    btcRelayDeploymentHeight?: number,
-    spvVaultContract?: string,
-    spvVaultDeploymentHeight?: number,
-    handlerContracts?: {
-        refund?: {
-            timelock?: string
-        },
-        claim?: {
-            [type in ChainSwapType]?: string
-        }
-    }
-
-    fees?: EVMFees,
-
-    evmConfig?: Partial<Omit<EVMConfiguration, "safeBlockTag" | "finalizedBlockTag" | "finalityCheckStrategy">>
-}
+export type GoatOptions = EVMOptions<"MAINNET" | "TESTNET" | "TESTNET4">;
 
 /**
  * Initialize GOAT Network chain integration

package/src/evm/btcrelay/EVMBtcRelay.ts

@@ -27,13 +27,18 @@ function serializeBlockHeader(e: BtcBlock): EVMBtcHeader {
 const logger = getLogger("EVMBtcRelay: ");
 
 /**
+ * EVM BTC Relay bitcoin light client contract representation.
+ *
  * @category BTC Relay
  */
 export class EVMBtcRelay<B extends BtcBlock>
     extends EVMContractBase<BtcRelayTypechain>
     implements BtcRelay<EVMBtcStoredHeader, EVMTx, B, EVMSigner> {
 
-    public static GasCosts = {
+    /**
+     * @internal
+     */
+    static _GasCosts = {
         GAS_PER_BLOCKHEADER: 30_000,
         GAS_BASE_MAIN: 15_000 + 21_000,
         GAS_PER_BLOCKHEADER_FORK: 65_000,
@@ -41,37 +46,64 @@ export class EVMBtcRelay<B extends BtcBlock>
         GAS_BASE_FORK: 25_000 + 21_000
     }
 
-    public async SaveMainHeaders(signer: string, mainHeaders: EVMBtcHeader[], storedHeader: EVMBtcStoredHeader, feeRate: string): Promise<EVMTx> {
+    /**
+     * Returns a transaction that submits new main-chain bitcoin blockheaders to the light client.
+     *
+     * @param signer EVM signer address
+     * @param mainHeaders New bitcoin blockheaders to submit
+     * @param storedHeader Current latest committed and stored bitcoin blockheader in the light client
+     * @param feeRate Fee rate to apply to the transaction
+     */
+    private async SaveMainHeaders(signer: string, mainHeaders: EVMBtcHeader[], storedHeader: EVMBtcStoredHeader, feeRate: string): Promise<EVMTx> {
         const tx = await this.contract.submitMainBlockheaders.populateTransaction(Buffer.concat([
             storedHeader.serialize(),
             Buffer.concat(mainHeaders.map(header => header.serializeCompact()))
         ]));
         tx.from = signer;
-        EVMFees.applyFeeRate(tx, EVMBtcRelay.GasCosts.GAS_BASE_MAIN + (EVMBtcRelay.GasCosts.GAS_PER_BLOCKHEADER * mainHeaders.length), feeRate);
+        EVMFees.applyFeeRate(tx, EVMBtcRelay._GasCosts.GAS_BASE_MAIN + (EVMBtcRelay._GasCosts.GAS_PER_BLOCKHEADER * mainHeaders.length), feeRate);
         return tx;
     }
 
-    public async SaveShortForkHeaders(signer: string, forkHeaders: EVMBtcHeader[], storedHeader: EVMBtcStoredHeader, feeRate: string): Promise<EVMTx> {
+    /**
+     * Returns a transaction that submits a short competing branch.
+     * If the submitted chain has higher total chainwork than the current canonical chain, it becomes canonical.
+     *
+     * @param signer EVM signer address
+     * @param forkHeaders Fork bitcoin blockheaders to submit
+     * @param storedHeader Committed and stored bitcoin blockheader from which to fork the light client
+     * @param feeRate Fee rate to apply to the transaction
+     */
+    private async SaveShortForkHeaders(signer: string, forkHeaders: EVMBtcHeader[], storedHeader: EVMBtcStoredHeader, feeRate: string): Promise<EVMTx> {
         const tx = await this.contract.submitShortForkBlockheaders.populateTransaction(Buffer.concat([
             storedHeader.serialize(),
             Buffer.concat(forkHeaders.map(header => header.serializeCompact()))
         ]));
         tx.from = signer;
-        EVMFees.applyFeeRate(tx, EVMBtcRelay.GasCosts.GAS_BASE_MAIN + (EVMBtcRelay.GasCosts.GAS_PER_BLOCKHEADER * forkHeaders.length), feeRate);
+        EVMFees.applyFeeRate(tx, EVMBtcRelay._GasCosts.GAS_BASE_MAIN + (EVMBtcRelay._GasCosts.GAS_PER_BLOCKHEADER * forkHeaders.length), feeRate);
         return tx;
     }
 
-    public async SaveLongForkHeaders(signer: string, forkId: number, forkHeaders: EVMBtcHeader[], storedHeader: EVMBtcStoredHeader, feeRate: string, totalForkHeaders: number = 100): Promise<EVMTx> {
+    /**
+     * Returns a transaction that submits blockheaders to an existing long fork.
+     *
+     * @param signer EVM signer address
+     * @param forkId Fork ID to submit the fork blockheaders to
+     * @param forkHeaders Fork bitcoin blockheaders to submit
+     * @param storedHeader Either a committed and stored blockheader from which to fork, or the current fork tip
+     * @param feeRate Fee rate to apply to the transaction
+     * @param totalForkHeaders Total blockheaders in the fork, used for gas estimation when reorg happens
+     */
+    private async SaveLongForkHeaders(signer: string, forkId: number, forkHeaders: EVMBtcHeader[], storedHeader: EVMBtcStoredHeader, feeRate: string, totalForkHeaders: number = 100): Promise<EVMTx> {
         const tx = await this.contract.submitForkBlockheaders.populateTransaction(forkId, Buffer.concat([
             storedHeader.serialize(),
             Buffer.concat(forkHeaders.map(header => header.serializeCompact()))
         ]));
         tx.from = signer;
-        EVMFees.applyFeeRate(tx, EVMBtcRelay.GasCosts.GAS_BASE_FORK + (EVMBtcRelay.GasCosts.GAS_PER_BLOCKHEADER_FORK * forkHeaders.length) + (EVMBtcRelay.GasCosts.GAS_PER_BLOCKHEADER_FORKED * totalForkHeaders), feeRate);
+        EVMFees.applyFeeRate(tx, EVMBtcRelay._GasCosts.GAS_BASE_FORK + (EVMBtcRelay._GasCosts.GAS_PER_BLOCKHEADER_FORK * forkHeaders.length) + (EVMBtcRelay._GasCosts.GAS_PER_BLOCKHEADER_FORKED * totalForkHeaders), feeRate);
         return tx;
     }
 
-    bitcoinRpc: BitcoinRpc<B>;
+    readonly _bitcoinRpc: BitcoinRpc<B>;
 
     readonly maxHeadersPerTx: number = 100;
     readonly maxForkHeadersPerTx: number = 50;
@@ -85,12 +117,12 @@ export class EVMBtcRelay<B extends BtcBlock>
         contractDeploymentHeight?: number
     ) {
         super(chainInterface, contractAddress, BtcRelayAbi, contractDeploymentHeight);
-        this.bitcoinRpc = bitcoinRpc;
+        this._bitcoinRpc = bitcoinRpc;
     }
 
     /**
-     * Computes subsequent commited headers as they will appear on the blockchain when transactions
-     *  are submitted & confirmed
+     * Computes subsequent committed headers as they will appear on-chain once transactions
+     * are submitted and confirmed.
      *
      * @param initialStoredHeader
      * @param syncedHeaders
@@ -198,7 +230,7 @@ export class EVMBtcRelay<B extends BtcBlock>
     private getBlock(commitHash?: string, blockHash?: Buffer): Promise<[EVMBtcStoredHeader, string] | null> {
         const blockHashString = blockHash==null ? null : "0x"+Buffer.from([...blockHash]).reverse().toString("hex");
 
-        const generator = () => this.Events.findInContractEvents<[EVMBtcStoredHeader, string] | null, "StoreHeader" | "StoreForkHeader">(
+        const generator = () => this._Events.findInContractEvents<[EVMBtcStoredHeader, string] | null, "StoreHeader" | "StoreForkHeader">(
             ["StoreHeader", "StoreForkHeader"],
             [
                 commitHash ?? null,
@@ -263,7 +295,7 @@ export class EVMBtcRelay<B extends BtcBlock>
         const [storedBlockHeader, commitHash] = result;
 
         //Check if block is part of the main chain
-        const chainCommitment = await this.contract.getCommitHash(storedBlockHeader.blockHeight);
+        const chainCommitment = await this.contract.getCommitHash(storedBlockHeader.getBlockheight());
         if(chainCommitment!==commitHash) return null;
 
         logger.debug("retrieveLogAndBlockheight(): block found," +
@@ -282,11 +314,11 @@ export class EVMBtcRelay<B extends BtcBlock>
         const [storedBlockHeader, commitHash] = result;
 
         //Check if block is part of the main chain
-        const chainCommitment = await this.contract.getCommitHash(storedBlockHeader.blockHeight);
+        const chainCommitment = await this.contract.getCommitHash(storedBlockHeader.getBlockheight());
         if(chainCommitment!==commitHash) return null;
 
         logger.debug("retrieveLogByCommitHash(): block found," +
-            " commit hash: "+commitmentHashStr+" blockhash: "+blockData.blockhash+" height: "+storedBlockHeader.blockHeight);
+            " commit hash: "+commitmentHashStr+" blockhash: "+blockData.blockhash+" height: "+storedBlockHeader.getBlockheight());
 
         return storedBlockHeader;
     }
@@ -298,17 +330,17 @@ export class EVMBtcRelay<B extends BtcBlock>
         resultStoredHeader: EVMBtcStoredHeader,
         resultBitcoinHeader: B
     } | null> {
-        const data = await this.Events.findInContractEvents(
+        const data = await this._Events.findInContractEvents(
             ["StoreHeader", "StoreForkHeader"],
             null,
             async (event) => {
                 const blockHashHex = Buffer.from(event.args.blockHash.substring(2), "hex").reverse().toString("hex");
                 const commitHash = event.args.commitHash;
 
-                const isInBtcMainChain = await this.bitcoinRpc.isInMainChain(blockHashHex).catch(() => false);
+                const isInBtcMainChain = await this._bitcoinRpc.isInMainChain(blockHashHex).catch(() => false);
                 if(!isInBtcMainChain) return null;
 
-                const blockHeader = await this.bitcoinRpc.getBlockHeader(blockHashHex);
+                const blockHeader = await this._bitcoinRpc.getBlockHeader(blockHashHex);
                 if(blockHeader==null) return null;
 
                 if(commitHash !== await this.contract.getCommitHash(blockHeader.getHeight())) return null;
@@ -408,7 +440,7 @@ export class EVMBtcRelay<B extends BtcBlock>
         if(blockheightDelta<=0) return 0n;
 
         const synchronizationFee = (BigInt(blockheightDelta) * await this.getFeePerBlock(feeRate))
-            + EVMFees.getGasFee(EVMBtcRelay.GasCosts.GAS_BASE_MAIN * Math.ceil(blockheightDelta / this.maxHeadersPerTx), feeRate);
+            + EVMFees.getGasFee(EVMBtcRelay._GasCosts.GAS_BASE_MAIN * Math.ceil(blockheightDelta / this.maxHeadersPerTx), feeRate);
         logger.debug("estimateSynchronizeFee(): required blockheight: "+requiredBlockheight+
             " blockheight delta: "+blockheightDelta+" fee: "+synchronizationFee.toString(10));
 
@@ -420,7 +452,7 @@ export class EVMBtcRelay<B extends BtcBlock>
      */
     public async getFeePerBlock(feeRate?: string): Promise<bigint> {
         feeRate ??= await this.Chain.Fees.getFeeRate();
-        return EVMFees.getGasFee(EVMBtcRelay.GasCosts.GAS_PER_BLOCKHEADER, feeRate);
+        return EVMFees.getGasFee(EVMBtcRelay._GasCosts.GAS_PER_BLOCKHEADER, feeRate);
     }
 
     /**
@@ -453,8 +485,8 @@ export class EVMBtcRelay<B extends BtcBlock>
      * @param signer
      * @param btcRelay
      * @param btcTxs
-     * @param txs solana transaction array, in case we need to synchronize the btc relay ourselves the synchronization
-     *  txns are added here
+     * @param txs EVM transaction array. If BTC relay synchronization is needed, synchronization
+     * transactions are appended here.
      * @param synchronizer optional synchronizer to use to synchronize the btc relay in case it is not yet synchronized
      *  to the required blockheight
      * @param feeRate Fee rate to use for synchronization transactions

package/src/evm/btcrelay/headers/EVMBtcHeader.ts

@@ -2,6 +2,11 @@ import {BtcHeader} from "@atomiqlabs/base";
 import {Buffer} from "buffer";
 import {sha256} from "@noble/hashes/sha2";
 
+/**
+ * Constructor payload for EVM bitcoin blockheader representation.
+ *
+ * @category BTC Relay
+ */
 export type EVMBtcHeaderType = {
     version: number;
     previousBlockhash?: Buffer;
@@ -13,21 +18,30 @@ export type EVMBtcHeaderType = {
 };
 
 /**
+ * Representation of a bitcoin blockheader submitted to EVM BTC relay contracts.
+ *
  * @category BTC Relay
  */
 export class EVMBtcHeader implements BtcHeader {
 
-    version: number;
-    previousBlockhash?: Buffer;
-    merkleRoot: Buffer;
-    timestamp: number;
-    nbits: number;
-    nonce: number;
-    hash?: Buffer;
+    private readonly version: number;
+    private readonly merkleRoot: Buffer;
+    private readonly timestamp: number;
+    private readonly nbits: number;
+    private readonly nonce: number;
+    private readonly hash?: Buffer;
+
+    /**
+     * @internal
+     */
+    _previousBlockhash?: Buffer;
 
+    /**
+     * @internal
+     */
     constructor(data: EVMBtcHeaderType) {
         this.version = data.version;
-        this.previousBlockhash = data.previousBlockhash;
+        this._previousBlockhash = data.previousBlockhash;
         this.merkleRoot = data.merkleRoot;
         this.timestamp = data.timestamp;
         this.nbits = data.nbits;
@@ -35,35 +49,60 @@ export class EVMBtcHeader implements BtcHeader {
         this.hash = data.hash;
     }
 
+    /**
+     * @inheritDoc
+     */
     getMerkleRoot(): Buffer {
         return this.merkleRoot;
     }
 
+    /**
+     * @inheritDoc
+     */
     getNbits(): number {
         return this.nbits;
     }
 
+    /**
+     * @inheritDoc
+     */
     getNonce(): number {
         return this.nonce;
     }
 
+    /**
+     * @inheritDoc
+     */
     getReversedPrevBlockhash(): Buffer {
-        if(this.previousBlockhash==null) throw new Error("Previous blockhash is not known from compact blockheader!");
-        return this.previousBlockhash;
+        if(this._previousBlockhash==null) throw new Error("Previous blockhash is not known from compact blockheader!");
+        return this._previousBlockhash;
     }
 
+    /**
+     * @inheritDoc
+     */
     getTimestamp(): number {
         return this.timestamp;
     }
 
+    /**
+     * @inheritDoc
+     */
     getVersion(): number {
         return this.version;
     }
 
+    /**
+     * @inheritDoc
+     */
     getHash(): Buffer {
         return Buffer.from(sha256(sha256(this.serialize())));
     }
 
+    /**
+     * Serializes the bitcoin blockheader into compact 48-byte representation
+     * (without previous blockhash).
+     */
     serializeCompact(): Buffer {
         const buffer = Buffer.alloc(48);
         buffer.writeUInt32LE(this.version, 0);
@@ -74,11 +113,14 @@ export class EVMBtcHeader implements BtcHeader {
         return buffer;
     }
 
+    /**
+     * Serializes the bitcoin blockheader into full 80-byte representation.
+     */
     serialize(): Buffer {
-        if(this.previousBlockhash==null) throw new Error("Cannot serialize compact blockheader without previous blockhash!");
+        if(this._previousBlockhash==null) throw new Error("Cannot serialize compact blockheader without previous blockhash!");
         const buffer = Buffer.alloc(80);
         buffer.writeUInt32LE(this.version, 0);
-        this.previousBlockhash.copy(buffer, 4);
+        this._previousBlockhash.copy(buffer, 4);
         this.merkleRoot.copy(buffer, 36);
         buffer.writeUInt32LE(this.timestamp, 68);
         buffer.writeUInt32LE(this.nbits, 72);
@@ -86,6 +128,11 @@ export class EVMBtcHeader implements BtcHeader {
         return buffer;
     }
 
+    /**
+     * Deserializes a bitcoin blockheader from 80-byte full or 48-byte compact representation.
+     *
+     * @param rawData Serialized blockheader bytes
+     */
     static deserialize(rawData: Buffer): EVMBtcHeader {
         if(rawData.length===80) {
             //Regular blockheader
@@ -112,4 +159,4 @@ export class EVMBtcHeader implements BtcHeader {
         }
     }
 
-}
+}