@atomiqlabs/chain-evm 2.1.12 → 2.2.0

package/dist/chains/goat/GoatInitializer.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GoatInitializer = exports.initializeGoat = exports.GoatAssets = void 0;
+exports.GoatInitializer = exports.initializeGoat = void 0;
 const base_1 = require("@atomiqlabs/base");
 const ethers_1 = require("ethers");
 const EVMChainInterface_1 = require("../../evm/chain/EVMChainInterface");
@@ -88,7 +88,7 @@ const chainTypeMapping = {
  * Default GOAT Network token assets configuration
  * @category Networks/GOAT
  */
-exports.GoatAssets = {
+const GoatAssets = {
     BTC: {
         address: "0x0000000000000000000000000000000000000000",
         decimals: 18,
@@ -166,6 +166,6 @@ exports.GoatInitializer = {
     chainId: "GOAT",
     chainType: null,
     initializer: initializeGoat,
-    tokens: exports.GoatAssets,
+    tokens: GoatAssets,
     options: null
 };

package/dist/evm/btcrelay/EVMBtcRelay.d.ts

@@ -1,7 +1,6 @@
 /// <reference types="node" />
 /// <reference types="node" />
 import { BitcoinNetwork, BitcoinRpc, BtcBlock, BtcRelay, RelaySynchronizer } from "@atomiqlabs/base";
-import { EVMBtcHeader } from "./headers/EVMBtcHeader";
 import { EVMContractBase } from "../contract/EVMContractBase";
 import { BtcRelay as BtcRelayTypechain } from "./BtcRelayTypechain";
 import { EVMBtcStoredHeader } from "./headers/EVMBtcStoredHeader";
@@ -9,27 +8,59 @@ import { EVMSigner } from "../wallet/EVMSigner";
 import { EVMTx } from "../chain/modules/EVMTransactions";
 import { EVMChainInterface } from "../chain/EVMChainInterface";
 /**
+ * EVM BTC Relay bitcoin light client contract representation.
+ *
  * @category BTC Relay
  */
 export declare class EVMBtcRelay<B extends BtcBlock> extends EVMContractBase<BtcRelayTypechain> implements BtcRelay<EVMBtcStoredHeader, EVMTx, B, EVMSigner> {
-    static GasCosts: {
+    /**
+     * @internal
+     */
+    static _GasCosts: {
         GAS_PER_BLOCKHEADER: number;
         GAS_BASE_MAIN: number;
         GAS_PER_BLOCKHEADER_FORK: number;
         GAS_PER_BLOCKHEADER_FORKED: number;
         GAS_BASE_FORK: number;
     };
-    SaveMainHeaders(signer: string, mainHeaders: EVMBtcHeader[], storedHeader: EVMBtcStoredHeader, feeRate: string): Promise<EVMTx>;
-    SaveShortForkHeaders(signer: string, forkHeaders: EVMBtcHeader[], storedHeader: EVMBtcStoredHeader, feeRate: string): Promise<EVMTx>;
-    SaveLongForkHeaders(signer: string, forkId: number, forkHeaders: EVMBtcHeader[], storedHeader: EVMBtcStoredHeader, feeRate: string, totalForkHeaders?: number): Promise<EVMTx>;
-    bitcoinRpc: BitcoinRpc<B>;
+    /**
+     * 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 SaveMainHeaders;
+    /**
+     * 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 SaveShortForkHeaders;
+    /**
+     * 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 SaveLongForkHeaders;
+    readonly _bitcoinRpc: BitcoinRpc<B>;
     readonly maxHeadersPerTx: number;
     readonly maxForkHeadersPerTx: number;
     readonly maxShortForkHeadersPerTx: number;
     constructor(chainInterface: EVMChainInterface<any>, bitcoinRpc: BitcoinRpc<B>, bitcoinNetwork: BitcoinNetwork, contractAddress: string, contractDeploymentHeight?: number);
     /**
-     * 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
@@ -149,8 +180,8 @@ export declare class EVMBtcRelay<B extends BtcBlock> extends EVMContractBase<Btc
      * @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/dist/evm/btcrelay/EVMBtcRelay.js

@@ -23,34 +23,63 @@ function serializeBlockHeader(e) {
 }
 const logger = (0, Utils_1.getLogger)("EVMBtcRelay: ");
 /**
+ * EVM BTC Relay bitcoin light client contract representation.
+ *
  * @category BTC Relay
  */
 class EVMBtcRelay extends EVMContractBase_1.EVMContractBase {
+    /**
+     * 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
+     */
     async SaveMainHeaders(signer, mainHeaders, storedHeader, feeRate) {
         const tx = await this.contract.submitMainBlockheaders.populateTransaction(Buffer.concat([
             storedHeader.serialize(),
             Buffer.concat(mainHeaders.map(header => header.serializeCompact()))
         ]));
         tx.from = signer;
-        EVMFees_1.EVMFees.applyFeeRate(tx, EVMBtcRelay.GasCosts.GAS_BASE_MAIN + (EVMBtcRelay.GasCosts.GAS_PER_BLOCKHEADER * mainHeaders.length), feeRate);
+        EVMFees_1.EVMFees.applyFeeRate(tx, EVMBtcRelay._GasCosts.GAS_BASE_MAIN + (EVMBtcRelay._GasCosts.GAS_PER_BLOCKHEADER * mainHeaders.length), feeRate);
         return tx;
     }
+    /**
+     * 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
+     */
     async SaveShortForkHeaders(signer, forkHeaders, storedHeader, feeRate) {
         const tx = await this.contract.submitShortForkBlockheaders.populateTransaction(Buffer.concat([
             storedHeader.serialize(),
             Buffer.concat(forkHeaders.map(header => header.serializeCompact()))
         ]));
         tx.from = signer;
-        EVMFees_1.EVMFees.applyFeeRate(tx, EVMBtcRelay.GasCosts.GAS_BASE_MAIN + (EVMBtcRelay.GasCosts.GAS_PER_BLOCKHEADER * forkHeaders.length), feeRate);
+        EVMFees_1.EVMFees.applyFeeRate(tx, EVMBtcRelay._GasCosts.GAS_BASE_MAIN + (EVMBtcRelay._GasCosts.GAS_PER_BLOCKHEADER * forkHeaders.length), feeRate);
         return tx;
     }
+    /**
+     * 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
+     */
     async SaveLongForkHeaders(signer, forkId, forkHeaders, storedHeader, feeRate, totalForkHeaders = 100) {
         const tx = await this.contract.submitForkBlockheaders.populateTransaction(forkId, Buffer.concat([
             storedHeader.serialize(),
             Buffer.concat(forkHeaders.map(header => header.serializeCompact()))
         ]));
         tx.from = signer;
-        EVMFees_1.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_1.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;
     }
     constructor(chainInterface, bitcoinRpc, bitcoinNetwork, contractAddress, contractDeploymentHeight) {
@@ -60,11 +89,11 @@ class EVMBtcRelay extends EVMContractBase_1.EVMContractBase {
         this.maxShortForkHeadersPerTx = 100;
         this.commitHashCache = new promise_cache_ts_1.PromiseLruCache(1000);
         this.blockHashCache = new promise_cache_ts_1.PromiseLruCache(1000);
-        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
@@ -153,7 +182,7 @@ class EVMBtcRelay extends EVMContractBase_1.EVMContractBase {
     }
     getBlock(commitHash, blockHash) {
         const blockHashString = blockHash == null ? null : "0x" + Buffer.from([...blockHash]).reverse().toString("hex");
-        const generator = () => this.Events.findInContractEvents(["StoreHeader", "StoreForkHeader"], [
+        const generator = () => this._Events.findInContractEvents(["StoreHeader", "StoreForkHeader"], [
             commitHash ?? null,
             blockHashString
         ], async (event) => {
@@ -206,7 +235,7 @@ class EVMBtcRelay extends EVMContractBase_1.EVMContractBase {
             return null;
         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," +
@@ -222,24 +251,24 @@ class EVMBtcRelay extends EVMContractBase_1.EVMContractBase {
             return null;
         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;
     }
     /**
      * @inheritDoc
      */
     async retrieveLatestKnownBlockLog() {
-        const data = await this.Events.findInContractEvents(["StoreHeader", "StoreForkHeader"], null, async (event) => {
+        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()))
@@ -324,7 +353,7 @@ class EVMBtcRelay extends EVMContractBase_1.EVMContractBase {
         if (blockheightDelta <= 0)
             return 0n;
         const synchronizationFee = (BigInt(blockheightDelta) * await this.getFeePerBlock(feeRate))
-            + EVMFees_1.EVMFees.getGasFee(EVMBtcRelay.GasCosts.GAS_BASE_MAIN * Math.ceil(blockheightDelta / this.maxHeadersPerTx), feeRate);
+            + EVMFees_1.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));
         return synchronizationFee;
@@ -334,7 +363,7 @@ class EVMBtcRelay extends EVMContractBase_1.EVMContractBase {
      */
     async getFeePerBlock(feeRate) {
         feeRate ?? (feeRate = await this.Chain.Fees.getFeeRate());
-        return EVMFees_1.EVMFees.getGasFee(EVMBtcRelay.GasCosts.GAS_PER_BLOCKHEADER, feeRate);
+        return EVMFees_1.EVMFees.getGasFee(EVMBtcRelay._GasCosts.GAS_PER_BLOCKHEADER, feeRate);
     }
     /**
      * @inheritDoc
@@ -363,8 +392,8 @@ class EVMBtcRelay extends EVMContractBase_1.EVMContractBase {
      * @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
@@ -410,7 +439,10 @@ class EVMBtcRelay extends EVMContractBase_1.EVMContractBase {
     }
 }
 exports.EVMBtcRelay = EVMBtcRelay;
-EVMBtcRelay.GasCosts = {
+/**
+ * @internal
+ */
+EVMBtcRelay._GasCosts = {
     GAS_PER_BLOCKHEADER: 30000,
     GAS_BASE_MAIN: 15000 + 21000,
     GAS_PER_BLOCKHEADER_FORK: 65000,

package/dist/evm/btcrelay/headers/EVMBtcHeader.d.ts

@@ -2,6 +2,11 @@
 /// <reference types="node" />
 import { BtcHeader } from "@atomiqlabs/base";
 import { Buffer } from "buffer";
+/**
+ * Constructor payload for EVM bitcoin blockheader representation.
+ *
+ * @category BTC Relay
+ */
 export type EVMBtcHeaderType = {
     version: number;
     previousBlockhash?: Buffer;
@@ -12,25 +17,66 @@ export type EVMBtcHeaderType = {
     hash?: Buffer;
 };
 /**
+ * Representation of a bitcoin blockheader submitted to EVM BTC relay contracts.
+ *
  * @category BTC Relay
  */
 export declare class EVMBtcHeader implements BtcHeader {
-    version: number;
-    previousBlockhash?: Buffer;
-    merkleRoot: Buffer;
-    timestamp: number;
-    nbits: number;
-    nonce: number;
-    hash?: Buffer;
+    private readonly version;
+    private readonly merkleRoot;
+    private readonly timestamp;
+    private readonly nbits;
+    private readonly nonce;
+    private readonly hash?;
+    /**
+     * @internal
+     */
+    _previousBlockhash?: Buffer;
+    /**
+     * @internal
+     */
     constructor(data: EVMBtcHeaderType);
+    /**
+     * @inheritDoc
+     */
     getMerkleRoot(): Buffer;
+    /**
+     * @inheritDoc
+     */
     getNbits(): number;
+    /**
+     * @inheritDoc
+     */
     getNonce(): number;
+    /**
+     * @inheritDoc
+     */
     getReversedPrevBlockhash(): Buffer;
+    /**
+     * @inheritDoc
+     */
     getTimestamp(): number;
+    /**
+     * @inheritDoc
+     */
     getVersion(): number;
+    /**
+     * @inheritDoc
+     */
     getHash(): Buffer;
+    /**
+     * Serializes the bitcoin blockheader into compact 48-byte representation
+     * (without previous blockhash).
+     */
     serializeCompact(): Buffer;
+    /**
+     * Serializes the bitcoin blockheader into full 80-byte representation.
+     */
     serialize(): Buffer;
+    /**
+     * Deserializes a bitcoin blockheader from 80-byte full or 48-byte compact representation.
+     *
+     * @param rawData Serialized blockheader bytes
+     */
     static deserialize(rawData: Buffer): EVMBtcHeader;
 }

package/dist/evm/btcrelay/headers/EVMBtcHeader.js

@@ -4,41 +4,71 @@ exports.EVMBtcHeader = void 0;
 const buffer_1 = require("buffer");
 const sha2_1 = require("@noble/hashes/sha2");
 /**
+ * Representation of a bitcoin blockheader submitted to EVM BTC relay contracts.
+ *
  * @category BTC Relay
  */
 class EVMBtcHeader {
+    /**
+     * @internal
+     */
     constructor(data) {
         this.version = data.version;
-        this.previousBlockhash = data.previousBlockhash;
+        this._previousBlockhash = data.previousBlockhash;
         this.merkleRoot = data.merkleRoot;
         this.timestamp = data.timestamp;
         this.nbits = data.nbits;
         this.nonce = data.nonce;
         this.hash = data.hash;
     }
+    /**
+     * @inheritDoc
+     */
     getMerkleRoot() {
         return this.merkleRoot;
     }
+    /**
+     * @inheritDoc
+     */
     getNbits() {
         return this.nbits;
     }
+    /**
+     * @inheritDoc
+     */
     getNonce() {
         return this.nonce;
     }
+    /**
+     * @inheritDoc
+     */
     getReversedPrevBlockhash() {
-        if (this.previousBlockhash == null)
+        if (this._previousBlockhash == null)
             throw new Error("Previous blockhash is not known from compact blockheader!");
-        return this.previousBlockhash;
+        return this._previousBlockhash;
     }
+    /**
+     * @inheritDoc
+     */
     getTimestamp() {
         return this.timestamp;
     }
+    /**
+     * @inheritDoc
+     */
     getVersion() {
         return this.version;
     }
+    /**
+     * @inheritDoc
+     */
     getHash() {
         return buffer_1.Buffer.from((0, sha2_1.sha256)((0, sha2_1.sha256)(this.serialize())));
     }
+    /**
+     * Serializes the bitcoin blockheader into compact 48-byte representation
+     * (without previous blockhash).
+     */
     serializeCompact() {
         const buffer = buffer_1.Buffer.alloc(48);
         buffer.writeUInt32LE(this.version, 0);
@@ -48,18 +78,26 @@ class EVMBtcHeader {
         buffer.writeUInt32LE(this.nonce, 44);
         return buffer;
     }
+    /**
+     * Serializes the bitcoin blockheader into full 80-byte representation.
+     */
     serialize() {
-        if (this.previousBlockhash == null)
+        if (this._previousBlockhash == null)
             throw new Error("Cannot serialize compact blockheader without previous blockhash!");
         const buffer = buffer_1.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);
         buffer.writeUInt32LE(this.nonce, 76);
         return buffer;
     }
+    /**
+     * Deserializes a bitcoin blockheader from 80-byte full or 48-byte compact representation.
+     *
+     * @param rawData Serialized blockheader bytes
+     */
     static deserialize(rawData) {
         if (rawData.length === 80) {
             //Regular blockheader

package/dist/evm/btcrelay/headers/EVMBtcStoredHeader.d.ts

@@ -3,7 +3,12 @@
 import { BtcStoredHeader } from "@atomiqlabs/base";
 import { EVMBtcHeader, EVMBtcHeaderType } from "./EVMBtcHeader";
 import { Buffer } from "buffer";
-export type StarknetBtcStoredHeaderType = {
+/**
+ * Constructor payload for a stored bitcoin header committed in EVM BTC relay contract state.
+ *
+ * @category BTC Relay
+ */
+export type EVMBtcStoredHeaderType = {
     blockheader: EVMBtcHeader | EVMBtcHeaderType;
     blockHash: Buffer;
     chainWork: bigint;
@@ -12,21 +17,44 @@ export type StarknetBtcStoredHeaderType = {
     prevBlockTimestamps: number[];
 };
 /**
+ * Represents a bitcoin header already committed inside EVM BTC relay contract state.
+ *
  * @category BTC Relay
  */
 export declare class EVMBtcStoredHeader implements BtcStoredHeader<EVMBtcHeader> {
-    blockheader: EVMBtcHeader;
-    blockHash: Buffer;
-    chainWork: bigint;
-    blockHeight: number;
-    lastDiffAdjustment: number;
-    prevBlockTimestamps: number[];
-    constructor(obj: StarknetBtcStoredHeaderType);
+    private readonly blockheader;
+    private readonly blockHash;
+    private readonly chainWork;
+    private readonly blockHeight;
+    private readonly lastDiffAdjustment;
+    private readonly prevBlockTimestamps;
+    /**
+     * @internal
+     */
+    constructor(obj: EVMBtcStoredHeaderType);
+    /**
+     * @inheritDoc
+     */
     getBlockheight(): number;
+    /**
+     * @inheritDoc
+     */
     getChainWork(): Buffer;
+    /**
+     * @inheritDoc
+     */
     getHeader(): EVMBtcHeader;
+    /**
+     * @inheritDoc
+     */
     getLastDiffAdjustment(): number;
+    /**
+     * @inheritDoc
+     */
     getPrevBlockTimestamps(): number[];
+    /**
+     * @inheritDoc
+     */
     getBlockHash(): Buffer;
     /**
      * Computes prevBlockTimestamps for a next block, shifting the old block timestamps to the left & appending
@@ -49,11 +77,28 @@ export declare class EVMBtcStoredHeader implements BtcStoredHeader<EVMBtcHeader>
      * @private
      */
     private computeNextLastDiffAdjustment;
+    /**
+     * @inheritDoc
+     */
     computeNext(header: EVMBtcHeader): EVMBtcStoredHeader;
+    /**
+     * Returns the commitment of this stored head (keccak256 hash), this is what's actually stored on-chain
+     */
     getCommitHash(): string;
+    /**
+     * Serializes the stored blockheader into the 160-byte binary layout used by the EVM contracts.
+     */
     serialize(): Buffer;
+    /**
+     * Serializes the stored blockheader into the contract tuple form (`bytes32[5]` payload).
+     */
     serializeToStruct(): {
         data: [string, string, string, string, string];
     };
+    /**
+     * Deserializes a stored blockheader from the 160-byte binary representation.
+     *
+     * @param data Serialized stored blockheader bytes
+     */
     static deserialize(data: Buffer): EVMBtcStoredHeader;
 }

package/dist/evm/btcrelay/headers/EVMBtcStoredHeader.js

@@ -6,9 +6,14 @@ const EVMBtcHeader_1 = require("./EVMBtcHeader");
 const buffer_1 = require("buffer");
 const ethers_1 = require("ethers");
 /**
+ * Represents a bitcoin header already committed inside EVM BTC relay contract state.
+ *
  * @category BTC Relay
  */
 class EVMBtcStoredHeader {
+    /**
+     * @internal
+     */
     constructor(obj) {
         this.blockheader = obj.blockheader instanceof EVMBtcHeader_1.EVMBtcHeader ? obj.blockheader : new EVMBtcHeader_1.EVMBtcHeader(obj.blockheader);
         this.blockHash = obj.blockHash;
@@ -17,21 +22,39 @@ class EVMBtcStoredHeader {
         this.lastDiffAdjustment = obj.lastDiffAdjustment;
         this.prevBlockTimestamps = obj.prevBlockTimestamps;
     }
+    /**
+     * @inheritDoc
+     */
     getBlockheight() {
         return this.blockHeight;
     }
+    /**
+     * @inheritDoc
+     */
     getChainWork() {
         return buffer_1.Buffer.from(this.chainWork.toString(16).padStart(64, "0"), "hex");
     }
+    /**
+     * @inheritDoc
+     */
     getHeader() {
         return this.blockheader;
     }
+    /**
+     * @inheritDoc
+     */
     getLastDiffAdjustment() {
         return this.lastDiffAdjustment;
     }
+    /**
+     * @inheritDoc
+     */
     getPrevBlockTimestamps() {
         return this.prevBlockTimestamps;
     }
+    /**
+     * @inheritDoc
+     */
     getBlockHash() {
         return buffer_1.Buffer.from([...this.blockHash]).reverse();
     }
@@ -72,8 +95,11 @@ class EVMBtcStoredHeader {
         }
         return lastDiffAdjustment;
     }
+    /**
+     * @inheritDoc
+     */
     computeNext(header) {
-        header.previousBlockhash = this.blockHash;
+        header._previousBlockhash = this.blockHash;
         return new EVMBtcStoredHeader({
             chainWork: this.computeNextChainWork(header.getNbits()),
             prevBlockTimestamps: this.computeNextBlockTimestamps(),
@@ -83,9 +109,15 @@ class EVMBtcStoredHeader {
             blockheader: header
         });
     }
+    /**
+     * Returns the commitment of this stored head (keccak256 hash), this is what's actually stored on-chain
+     */
     getCommitHash() {
         return (0, ethers_1.keccak256)(this.serialize());
     }
+    /**
+     * Serializes the stored blockheader into the 160-byte binary layout used by the EVM contracts.
+     */
     serialize() {
         const buffer = buffer_1.Buffer.alloc(160);
         this.blockheader.serialize().copy(buffer, 0, 0, 80);
@@ -97,6 +129,9 @@ class EVMBtcStoredHeader {
         }
         return buffer;
     }
+    /**
+     * Serializes the stored blockheader into the contract tuple form (`bytes32[5]` payload).
+     */
     serializeToStruct() {
         const buffer = this.serialize();
         const result = [];
@@ -105,6 +140,11 @@ class EVMBtcStoredHeader {
         }
         return { data: result };
     }
+    /**
+     * Deserializes a stored blockheader from the 160-byte binary representation.
+     *
+     * @param data Serialized stored blockheader bytes
+     */
     static deserialize(data) {
         if (data.length !== 160)
             throw new Error(`Invalid size Expected 160, got: ${data.length}!`);