@atomiqlabs/chain-starknet 1.0.0-beta.0

package/dist/starknet/btcrelay/StarknetBtcRelay.js

@@ -0,0 +1,323 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StarknetBtcRelay = void 0;
+const buffer_1 = require("buffer");
+const StarknetBtcHeader_1 = require("./headers/StarknetBtcHeader");
+const base_1 = require("@atomiqlabs/base");
+const Utils_1 = require("../../utils/Utils");
+const StarknetContractBase_1 = require("../contract/StarknetContractBase");
+const StarknetBtcStoredHeader_1 = require("./headers/StarknetBtcStoredHeader");
+const BtcRelayAbi_1 = require("./BtcRelayAbi");
+const starknet_1 = require("starknet");
+const StarknetFees_1 = require("../base/modules/StarknetFees");
+const StarknetAction_1 = require("../base/StarknetAction");
+function serializeBlockHeader(e) {
+    return new StarknetBtcHeader_1.StarknetBtcHeader({
+        reversed_version: (0, Utils_1.u32ReverseEndianness)(e.getVersion()),
+        previous_blockhash: (0, Utils_1.bufferToU32Array)(buffer_1.Buffer.from(e.getPrevBlockhash(), "hex").reverse()),
+        merkle_root: (0, Utils_1.bufferToU32Array)(buffer_1.Buffer.from(e.getMerkleRoot(), "hex").reverse()),
+        reversed_timestamp: (0, Utils_1.u32ReverseEndianness)(e.getTimestamp()),
+        nbits: (0, Utils_1.u32ReverseEndianness)(e.getNbits()),
+        nonce: (0, Utils_1.u32ReverseEndianness)(e.getNonce()),
+        hash: buffer_1.Buffer.from(e.getHash(), "hex").reverse()
+    });
+}
+const GAS_PER_BLOCKHEADER = 750;
+const GAS_PER_BLOCKHEADER_FORK = 750;
+const btcRelayAddreses = {
+    [starknet_1.constants.StarknetChainId.SN_SEPOLIA]: "0x032afcea912ba13f6a1878fe38af23eaec3e6b4c7db31a3571550d3cf80d3e31",
+    [starknet_1.constants.StarknetChainId.SN_MAIN]: "0x05cc69b09e8c53520f9e328f6eca72cf02fe46ce290b757d42414e2238001603"
+};
+function serializeCalldata(headers, storedHeader, span) {
+    span.push((0, Utils_1.toHex)(headers.length));
+    headers.forEach(header => {
+        span.push(...header.serialize());
+    });
+    span.push(...storedHeader.serialize());
+    return span;
+}
+class StarknetBtcRelay extends StarknetContractBase_1.StarknetContractBase {
+    SaveMainHeaders(signer, mainHeaders, storedHeader) {
+        return new StarknetAction_1.StarknetAction(signer, this, {
+            contractAddress: this.contract.address,
+            entrypoint: "submit_main_blockheaders",
+            calldata: serializeCalldata(mainHeaders, storedHeader, [])
+        }, { l1: GAS_PER_BLOCKHEADER * mainHeaders.length, l2: 0 });
+    }
+    SaveShortForkHeaders(signer, forkHeaders, storedHeader) {
+        return new StarknetAction_1.StarknetAction(signer, this, {
+            contractAddress: this.contract.address,
+            entrypoint: "submit_short_fork_blockheaders",
+            calldata: serializeCalldata(forkHeaders, storedHeader, [])
+        }, { l1: GAS_PER_BLOCKHEADER * forkHeaders.length, l2: 0 });
+    }
+    SaveLongForkHeaders(signer, forkId, forkHeaders, storedHeader, totalForkHeaders = 100) {
+        return new StarknetAction_1.StarknetAction(signer, this, {
+            contractAddress: this.contract.address,
+            entrypoint: "submit_fork_blockheaders",
+            calldata: serializeCalldata(forkHeaders, storedHeader, [(0, Utils_1.toHex)(forkId)])
+        }, { l1: (GAS_PER_BLOCKHEADER * forkHeaders.length) + (GAS_PER_BLOCKHEADER_FORK * totalForkHeaders), l2: 0 });
+    }
+    constructor(chainId, provider, bitcoinRpc, contractAddress = btcRelayAddreses[chainId], retryPolicy, solanaFeeEstimator = new StarknetFees_1.StarknetFees(provider)) {
+        super(chainId, provider, contractAddress, BtcRelayAbi_1.BtcRelayAbi, retryPolicy, solanaFeeEstimator);
+        this.maxHeadersPerTx = 100;
+        this.maxForkHeadersPerTx = 100;
+        this.maxShortForkHeadersPerTx = 100;
+        this.bitcoinRpc = bitcoinRpc;
+    }
+    /**
+     * Computes subsequent commited headers as they will appear on the blockchain when transactions
+     *  are submitted & confirmed
+     *
+     * @param initialStoredHeader
+     * @param syncedHeaders
+     * @private
+     */
+    computeCommitedHeaders(initialStoredHeader, syncedHeaders) {
+        const computedCommitedHeaders = [initialStoredHeader];
+        for (let blockHeader of syncedHeaders) {
+            computedCommitedHeaders.push(computedCommitedHeaders[computedCommitedHeaders.length - 1].computeNext(blockHeader));
+        }
+        return computedCommitedHeaders;
+    }
+    /**
+     * A common logic for submitting blockheaders in a transaction
+     *
+     * @param signer
+     * @param headers headers to sync to the btc relay
+     * @param storedHeader current latest stored block header for a given fork
+     * @param tipWork work of the current tip in a given fork
+     * @param forkId forkId to submit to, forkId=0 means main chain, forkId=-1 means short fork
+     * @param feeRate feeRate for the transaction
+     * @private
+     */
+    async _saveHeaders(signer, headers, storedHeader, tipWork, forkId, feeRate) {
+        const blockHeaderObj = headers.map(serializeBlockHeader);
+        let starknetAction;
+        switch (forkId) {
+            case -1:
+                starknetAction = this.SaveShortForkHeaders(signer, blockHeaderObj, storedHeader);
+                break;
+            case 0:
+                starknetAction = this.SaveMainHeaders(signer, blockHeaderObj, storedHeader);
+                break;
+            default:
+                starknetAction = this.SaveLongForkHeaders(signer, forkId, blockHeaderObj, storedHeader);
+                break;
+        }
+        const tx = await starknetAction.tx(feeRate);
+        const computedCommitedHeaders = this.computeCommitedHeaders(storedHeader, blockHeaderObj);
+        const lastStoredHeader = computedCommitedHeaders[computedCommitedHeaders.length - 1];
+        if (forkId !== 0 && base_1.StatePredictorUtils.gtBuffer(lastStoredHeader.getBlockHash(), tipWork)) {
+            //Fork's work is higher than main chain's work, this fork will become a main chain
+            forkId = 0;
+        }
+        return {
+            forkId: forkId,
+            lastStoredHeader,
+            tx,
+            computedCommitedHeaders
+        };
+    }
+    getBlock(commitHash, blockHash) {
+        const keys = [commitHash == null ? null : (0, Utils_1.toHex)(commitHash)];
+        if (blockHash != null) {
+            const starknetBlockHash = starknet_1.hash.computePoseidonHashOnElements((0, Utils_1.bufferToU32Array)(buffer_1.Buffer.from([...blockHash]).reverse()));
+            keys.push(starknetBlockHash);
+        }
+        return this.Events.findInContractEvents(["btc_relay::events::StoreHeader", "btc_relay::events::StoreForkHeader"], keys, (event) => {
+            return Promise.resolve([StarknetBtcStoredHeader_1.StarknetBtcStoredHeader.fromSerializedFeltArray(event.data), BigInt(event.params.commit_hash)]);
+        });
+    }
+    async getBlockHeight() {
+        return Number(await this.contract.get_blockheight());
+    }
+    /**
+     * Returns data about current main chain tip stored in the btc relay
+     */
+    async getTipData() {
+        const commitHash = await this.contract.get_tip_commit_hash();
+        if (commitHash == null || BigInt(commitHash) === BigInt(0))
+            return null;
+        const result = await this.getBlock(commitHash);
+        if (result == null)
+            return null;
+        const [storedBlockHeader] = result;
+        return {
+            blockheight: storedBlockHeader.getBlockheight(),
+            commitHash: (0, Utils_1.bigNumberishToBuffer)(commitHash, 32).toString("hex"),
+            blockhash: storedBlockHeader.getBlockHash().toString("hex"),
+            chainWork: storedBlockHeader.getChainWork()
+        };
+    }
+    /**
+     * 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
+     */
+    async retrieveLogAndBlockheight(blockData, requiredBlockheight) {
+        //TODO: we can fetch the blockheight and events in parallel
+        const blockHeight = await this.getBlockHeight();
+        if (requiredBlockheight != null && blockHeight < requiredBlockheight) {
+            return null;
+        }
+        const result = await this.getBlock(null, buffer_1.Buffer.from(blockData.blockhash, "hex"));
+        if (result == null)
+            return null;
+        const [storedBlockHeader, commitHash] = result;
+        //Check if block is part of the main chain
+        const chainCommitment = await this.contract.get_commit_hash(storedBlockHeader.block_height);
+        if (BigInt(chainCommitment) !== BigInt(commitHash))
+            return null;
+        this.logger.debug("retrieveLogAndBlockheight(): block found," +
+            " commit hash: " + (0, Utils_1.toHex)(commitHash) + " blockhash: " + blockData.blockhash + " current btc relay height: " + blockHeight);
+        return { header: storedBlockHeader, height: blockHeight };
+    }
+    /**
+     * Retrieves blockheader data by blockheader's commit hash,
+     *
+     * @param commitmentHashStr
+     * @param blockData
+     */
+    async retrieveLogByCommitHash(commitmentHashStr, blockData) {
+        const result = await this.getBlock(commitmentHashStr, buffer_1.Buffer.from(blockData.blockhash, "hex"));
+        if (result == null)
+            return null;
+        const [storedBlockHeader, commitHash] = result;
+        //Check if block is part of the main chain
+        const chainCommitment = await this.contract.get_commit_hash(storedBlockHeader.block_height);
+        if (BigInt(chainCommitment) !== BigInt(commitHash))
+            return null;
+        this.logger.debug("retrieveLogByCommitHash(): block found," +
+            " commit hash: " + commitmentHashStr + " blockhash: " + blockData.blockhash + " height: " + storedBlockHeader.block_height);
+        return storedBlockHeader;
+    }
+    /**
+     * Retrieves latest known stored blockheader & blockheader from bitcoin RPC that is in the main chain
+     */
+    async retrieveLatestKnownBlockLog() {
+        const data = await this.Events.findInContractEvents(["btc_relay::events::StoreHeader", "btc_relay::events::StoreForkHeader"], null, async (event) => {
+            const storedHeader = StarknetBtcStoredHeader_1.StarknetBtcStoredHeader.fromSerializedFeltArray(event.data);
+            const blockHashHex = storedHeader.getBlockHash().toString("hex");
+            const commitHash = event.params.commit_hash;
+            const [isInBtcMainChain, btcRelayCommitHash] = await Promise.all([
+                this.bitcoinRpc.isInMainChain(blockHashHex).catch(() => false),
+                this.contract.get_commit_hash(storedHeader.block_height)
+            ]);
+            if (!isInBtcMainChain)
+                return null;
+            if (BigInt(commitHash) !== BigInt(btcRelayCommitHash))
+                return null;
+            return {
+                resultStoredHeader: storedHeader,
+                resultBitcoinHeader: await this.bitcoinRpc.getBlockHeader(blockHashHex),
+                commitHash: commitHash
+            };
+        });
+        if (data != null)
+            this.logger.debug("retrieveLatestKnownBlockLog(): block found," +
+                " commit hash: " + (0, Utils_1.toHex)(data.commitHash) + " blockhash: " + data.resultBitcoinHeader.getHash() +
+                " height: " + data.resultStoredHeader.getBlockheight());
+        return data;
+    }
+    /**
+     * Saves blockheaders as a bitcoin main chain to the btc relay
+     *
+     * @param signer
+     * @param mainHeaders
+     * @param storedHeader
+     * @param feeRate
+     */
+    saveMainHeaders(signer, mainHeaders, storedHeader, feeRate) {
+        this.logger.debug("saveMainHeaders(): submitting main blockheaders, count: " + mainHeaders.length);
+        return this._saveHeaders(signer, mainHeaders, storedHeader, null, 0, feeRate);
+    }
+    /**
+     * Creates a new long fork and submits the headers to it
+     *
+     * @param signer
+     * @param forkHeaders
+     * @param storedHeader
+     * @param tipWork
+     * @param feeRate
+     */
+    async saveNewForkHeaders(signer, forkHeaders, storedHeader, tipWork, feeRate) {
+        let forkId = Math.floor(Math.random() * 0xFFFFFFFFFFFF);
+        this.logger.debug("saveNewForkHeaders(): submitting new fork & blockheaders," +
+            " count: " + forkHeaders.length + " forkId: 0x" + forkId.toString(16));
+        return await this._saveHeaders(signer, forkHeaders, storedHeader, tipWork, forkId, feeRate);
+    }
+    /**
+     * Continues submitting blockheaders to a given fork
+     *
+     * @param signer
+     * @param forkHeaders
+     * @param storedHeader
+     * @param forkId
+     * @param tipWork
+     * @param feeRate
+     */
+    saveForkHeaders(signer, forkHeaders, storedHeader, forkId, tipWork, feeRate) {
+        this.logger.debug("saveForkHeaders(): submitting blockheaders to existing fork," +
+            " count: " + forkHeaders.length + " forkId: 0x" + forkId.toString(16));
+        return this._saveHeaders(signer, forkHeaders, storedHeader, tipWork, forkId, feeRate);
+    }
+    /**
+     * Submits short fork with given blockheaders
+     *
+     * @param signer
+     * @param forkHeaders
+     * @param storedHeader
+     * @param tipWork
+     * @param feeRate
+     */
+    saveShortForkHeaders(signer, forkHeaders, storedHeader, tipWork, feeRate) {
+        this.logger.debug("saveShortForkHeaders(): submitting short fork blockheaders," +
+            " count: " + forkHeaders.length);
+        return this._saveHeaders(signer, forkHeaders, storedHeader, tipWork, -1, feeRate);
+    }
+    /**
+     * Estimate required synchronization fee (worst case) to synchronize btc relay to the required blockheight
+     *
+     * @param requiredBlockheight
+     * @param feeRate
+     */
+    async estimateSynchronizeFee(requiredBlockheight, feeRate) {
+        const tipData = await this.getTipData();
+        const currBlockheight = tipData.blockheight;
+        const blockheightDelta = requiredBlockheight - currBlockheight;
+        if (blockheightDelta <= 0)
+            return 0n;
+        const synchronizationFee = BigInt(blockheightDelta) * await this.getFeePerBlock(feeRate);
+        this.logger.debug("estimateSynchronizeFee(): required blockheight: " + requiredBlockheight +
+            " blockheight delta: " + blockheightDelta + " fee: " + synchronizationFee.toString(10));
+        return synchronizationFee;
+    }
+    /**
+     * Returns fee required (in SOL) to synchronize a single block to btc relay
+     *
+     * @param feeRate
+     */
+    async getFeePerBlock(feeRate) {
+        feeRate ?? (feeRate = await this.Fees.getFeeRate());
+        return StarknetFees_1.StarknetFees.getGasFee(GAS_PER_BLOCKHEADER, feeRate);
+    }
+    /**
+     * Gets fee rate required for submitting blockheaders to the main chain
+     */
+    getMainFeeRate(signer) {
+        return this.Fees.getFeeRate();
+    }
+    /**
+     * Gets fee rate required for submitting blockheaders to the specific fork
+     */
+    getForkFeeRate(signer, forkId) {
+        return this.Fees.getFeeRate();
+    }
+    saveInitialHeader(signer, header, epochStart, pastBlocksTimestamps, feeRate) {
+        throw new Error("Not supported, starknet contract is initialized with constructor!");
+    }
+}
+exports.StarknetBtcRelay = StarknetBtcRelay;

package/dist/starknet/btcrelay/headers/StarknetBtcHeader.d.ts

@@ -0,0 +1,32 @@
+/// <reference types="node" />
+import { BtcHeader } from "@atomiqlabs/base";
+import { Buffer } from "buffer";
+import { BigNumberish } from "starknet";
+export type StarknetBtcHeaderType = {
+    reversed_version: BigNumberish;
+    previous_blockhash: BigNumberish[];
+    merkle_root: BigNumberish[];
+    reversed_timestamp: BigNumberish;
+    nbits: BigNumberish;
+    nonce: BigNumberish;
+    hash?: Buffer;
+};
+export declare class StarknetBtcHeader implements BtcHeader {
+    reversed_version: number;
+    previous_blockhash: number[];
+    merkle_root: number[];
+    reversed_timestamp: number;
+    nbits: number;
+    nonce: number;
+    hash?: Buffer;
+    constructor(obj: StarknetBtcHeaderType);
+    getMerkleRoot(): Buffer;
+    getNbits(): number;
+    getNonce(): number;
+    getReversedPrevBlockhash(): Buffer;
+    getTimestamp(): number;
+    getVersion(): number;
+    getHash(): Buffer;
+    serialize(): BigNumberish[];
+    static fromSerializedFeltArray(span: BigNumberish[]): StarknetBtcHeader;
+}

package/dist/starknet/btcrelay/headers/StarknetBtcHeader.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StarknetBtcHeader = void 0;
+const buffer_1 = require("buffer");
+const Utils_1 = require("../../../utils/Utils");
+const createHash = require("create-hash");
+class StarknetBtcHeader {
+    constructor(obj) {
+        this.reversed_version = Number(obj.reversed_version);
+        this.previous_blockhash = obj.previous_blockhash.map(val => Number(val));
+        this.merkle_root = obj.merkle_root.map(val => Number(val));
+        this.reversed_timestamp = Number(obj.reversed_timestamp);
+        this.nbits = Number(obj.nbits);
+        this.nonce = Number(obj.nonce);
+        this.hash = obj.hash;
+    }
+    getMerkleRoot() {
+        return (0, Utils_1.u32ArrayToBuffer)(this.merkle_root);
+    }
+    getNbits() {
+        return (0, Utils_1.u32ReverseEndianness)(this.nbits);
+    }
+    getNonce() {
+        return (0, Utils_1.u32ReverseEndianness)(this.nonce);
+    }
+    getReversedPrevBlockhash() {
+        return (0, Utils_1.u32ArrayToBuffer)(this.previous_blockhash);
+    }
+    getTimestamp() {
+        return (0, Utils_1.u32ReverseEndianness)(this.reversed_timestamp);
+    }
+    getVersion() {
+        return (0, Utils_1.u32ReverseEndianness)(this.reversed_version);
+    }
+    getHash() {
+        if (this.hash != null)
+            return this.hash;
+        const buffer = buffer_1.Buffer.alloc(80);
+        buffer.writeUInt32BE(this.reversed_version);
+        (0, Utils_1.u32ArrayToBuffer)(this.previous_blockhash).copy(buffer, 4);
+        (0, Utils_1.u32ArrayToBuffer)(this.merkle_root).copy(buffer, 36);
+        buffer.writeUInt32BE(this.reversed_timestamp, 68);
+        buffer.writeUInt32BE(this.nbits, 72);
+        buffer.writeUInt32BE(this.nonce, 76);
+        return createHash("sha256").update(createHash("sha256").update(buffer).digest()).digest();
+    }
+    serialize() {
+        return [
+            this.reversed_version,
+            ...this.previous_blockhash,
+            ...this.merkle_root,
+            this.reversed_timestamp,
+            this.nbits,
+            this.nonce
+        ];
+    }
+    static fromSerializedFeltArray(span) {
+        const reversed_version = (0, Utils_1.toHex)(span.shift());
+        const previous_blockhash = span.splice(0, 8).map(Utils_1.toHex);
+        const merkle_root = span.splice(0, 8).map(Utils_1.toHex);
+        const reversed_timestamp = (0, Utils_1.toHex)(span.shift());
+        const nbits = (0, Utils_1.toHex)(span.shift());
+        const nonce = (0, Utils_1.toHex)(span.shift());
+        return new StarknetBtcHeader({
+            reversed_version,
+            previous_blockhash,
+            merkle_root,
+            reversed_timestamp,
+            nbits,
+            nonce
+        });
+    }
+}
+exports.StarknetBtcHeader = StarknetBtcHeader;

package/dist/starknet/btcrelay/headers/StarknetBtcStoredHeader.d.ts

@@ -0,0 +1,52 @@
+/// <reference types="node" />
+import { BtcStoredHeader } from "@atomiqlabs/base";
+import { StarknetBtcHeader, StarknetBtcHeaderType } from "./StarknetBtcHeader";
+import { Buffer } from "buffer";
+import { BigNumberish, Uint256 } from "starknet";
+export type StarknetBtcStoredHeaderType = {
+    blockheader: StarknetBtcHeader | StarknetBtcHeaderType;
+    block_hash: BigNumberish[];
+    chain_work: BigNumberish | Uint256;
+    block_height: BigNumberish;
+    last_diff_adjustment: BigNumberish;
+    prev_block_timestamps: BigNumberish[];
+};
+export declare class StarknetBtcStoredHeader implements BtcStoredHeader<StarknetBtcHeader> {
+    blockheader: StarknetBtcHeader;
+    block_hash: number[];
+    chain_work: Uint256;
+    block_height: number;
+    last_diff_adjustment: number;
+    prev_block_timestamps: number[];
+    constructor(obj: StarknetBtcStoredHeaderType);
+    getBlockheight(): number;
+    getChainWork(): Buffer;
+    getHeader(): StarknetBtcHeader;
+    getLastDiffAdjustment(): number;
+    getPrevBlockTimestamps(): number[];
+    getBlockHash(): Buffer;
+    /**
+     * Computes prevBlockTimestamps for a next block, shifting the old block timestamps to the left & appending
+     *  this block's timestamp to the end
+     *
+     * @private
+     */
+    private computeNextBlockTimestamps;
+    /**
+     * Computes total chain work after a new header with "nbits" is added to the chain
+     *
+     * @param nbits
+     * @private
+     */
+    private computeNextChainWork;
+    /**
+     * Computes lastDiffAdjustment, this changes only once every DIFF_ADJUSTMENT_PERIOD blocks
+     *
+     * @param headerTimestamp
+     * @private
+     */
+    private computeNextLastDiffAdjustment;
+    computeNext(header: StarknetBtcHeader): StarknetBtcStoredHeader;
+    serialize(): BigNumberish[];
+    static fromSerializedFeltArray(span: BigNumberish[]): StarknetBtcStoredHeader;
+}

package/dist/starknet/btcrelay/headers/StarknetBtcStoredHeader.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StarknetBtcStoredHeader = void 0;
+const base_1 = require("@atomiqlabs/base");
+const StarknetBtcHeader_1 = require("./StarknetBtcHeader");
+const buffer_1 = require("buffer");
+const starknet_1 = require("starknet");
+const Utils_1 = require("../../../utils/Utils");
+class StarknetBtcStoredHeader {
+    constructor(obj) {
+        this.blockheader = obj.blockheader instanceof StarknetBtcHeader_1.StarknetBtcHeader ? obj.blockheader : new StarknetBtcHeader_1.StarknetBtcHeader(obj.blockheader);
+        this.block_hash = obj.block_hash.map(val => Number(val));
+        this.chain_work = (0, Utils_1.isUint256)(obj.chain_work) ? obj.chain_work : starknet_1.cairo.uint256(obj.chain_work);
+        this.block_height = Number(obj.block_height);
+        this.last_diff_adjustment = Number(obj.last_diff_adjustment);
+        this.prev_block_timestamps = obj.prev_block_timestamps.map(val => Number(val));
+    }
+    getBlockheight() {
+        return this.block_height;
+    }
+    getChainWork() {
+        return (0, Utils_1.bigNumberishToBuffer)(this.chain_work, 32);
+    }
+    getHeader() {
+        return this.blockheader;
+    }
+    getLastDiffAdjustment() {
+        return this.last_diff_adjustment;
+    }
+    getPrevBlockTimestamps() {
+        return this.prev_block_timestamps;
+    }
+    getBlockHash() {
+        return (0, Utils_1.u32ArrayToBuffer)(this.block_hash).reverse();
+    }
+    /**
+     * Computes prevBlockTimestamps for a next block, shifting the old block timestamps to the left & appending
+     *  this block's timestamp to the end
+     *
+     * @private
+     */
+    computeNextBlockTimestamps() {
+        const prevBlockTimestamps = [...this.prev_block_timestamps];
+        for (let i = 1; i < 10; i++) {
+            prevBlockTimestamps[i - 1] = prevBlockTimestamps[i];
+        }
+        prevBlockTimestamps[9] = this.blockheader.getTimestamp();
+        return prevBlockTimestamps;
+    }
+    /**
+     * Computes total chain work after a new header with "nbits" is added to the chain
+     *
+     * @param nbits
+     * @private
+     */
+    computeNextChainWork(nbits) {
+        const chainWork = [...this.getChainWork()];
+        base_1.StatePredictorUtils.addInPlace(chainWork, [...base_1.StatePredictorUtils.getChainwork(nbits)]);
+        return buffer_1.Buffer.from(chainWork);
+    }
+    /**
+     * Computes lastDiffAdjustment, this changes only once every DIFF_ADJUSTMENT_PERIOD blocks
+     *
+     * @param headerTimestamp
+     * @private
+     */
+    computeNextLastDiffAdjustment(headerTimestamp) {
+        const blockheight = this.block_height + 1;
+        let lastDiffAdjustment = this.last_diff_adjustment;
+        if (blockheight % base_1.StatePredictorUtils.DIFF_ADJUSTMENT_PERIOD === 0) {
+            lastDiffAdjustment = headerTimestamp;
+        }
+        return lastDiffAdjustment;
+    }
+    computeNext(header) {
+        return new StarknetBtcStoredHeader({
+            chain_work: "0x" + this.computeNextChainWork(header.getNbits()).toString("hex"),
+            prev_block_timestamps: this.computeNextBlockTimestamps(),
+            block_height: this.block_height + 1,
+            last_diff_adjustment: this.computeNextLastDiffAdjustment(header.getTimestamp()),
+            block_hash: (0, Utils_1.bufferToU32Array)(header.getHash()),
+            blockheader: header
+        });
+    }
+    serialize() {
+        return [
+            ...this.blockheader.serialize(),
+            ...this.block_hash,
+            this.chain_work.low,
+            this.chain_work.high,
+            this.block_height,
+            this.last_diff_adjustment,
+            ...this.prev_block_timestamps
+        ];
+    }
+    static fromSerializedFeltArray(span) {
+        const blockheader = StarknetBtcHeader_1.StarknetBtcHeader.fromSerializedFeltArray(span);
+        const block_hash = span.splice(0, 8).map(Utils_1.toHex);
+        const chain_work = { low: span.shift(), high: span.shift() };
+        const block_height = (0, Utils_1.toHex)(span.shift());
+        const last_diff_adjustment = (0, Utils_1.toHex)(span.shift());
+        const prev_block_timestamps = span.splice(0, 10).map(Utils_1.toHex);
+        return new StarknetBtcStoredHeader({
+            blockheader,
+            block_hash,
+            chain_work,
+            block_height,
+            last_diff_adjustment,
+            prev_block_timestamps
+        });
+    }
+}
+exports.StarknetBtcStoredHeader = StarknetBtcStoredHeader;

package/dist/starknet/contract/StarknetContractBase.d.ts

@@ -0,0 +1,13 @@
+import { StarknetBase, StarknetRetryPolicy } from "../base/StarknetBase";
+import { constants, Provider, TypedContractV2 } from "starknet";
+import { StarknetFees } from "../base/modules/StarknetFees";
+import { Abi } from "abi-wan-kanabi";
+import { StarknetContractEvents } from "./modules/StarknetContractEvents";
+/**
+ * Base class providing program specific utilities
+ */
+export declare class StarknetContractBase<T extends Abi> extends StarknetBase {
+    contract: TypedContractV2<T>;
+    readonly Events: StarknetContractEvents<T>;
+    constructor(chainId: constants.StarknetChainId, provider: Provider, contractAddress: string, contractAbi: T, retryPolicy?: StarknetRetryPolicy, solanaFeeEstimator?: StarknetFees);
+}

package/dist/starknet/contract/StarknetContractBase.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StarknetContractBase = void 0;
+const StarknetBase_1 = require("../base/StarknetBase");
+const starknet_1 = require("starknet");
+const StarknetFees_1 = require("../base/modules/StarknetFees");
+const StarknetContractEvents_1 = require("./modules/StarknetContractEvents");
+/**
+ * Base class providing program specific utilities
+ */
+class StarknetContractBase extends StarknetBase_1.StarknetBase {
+    constructor(chainId, provider, contractAddress, contractAbi, retryPolicy, solanaFeeEstimator = new StarknetFees_1.StarknetFees(provider)) {
+        super(chainId, provider, retryPolicy, solanaFeeEstimator);
+        this.contract = new starknet_1.Contract(contractAbi, contractAddress, provider).typedv2(contractAbi);
+        this.Events = new StarknetContractEvents_1.StarknetContractEvents(this, contractAbi);
+    }
+}
+exports.StarknetContractBase = StarknetContractBase;

package/dist/starknet/contract/modules/StarknetContractEvents.d.ts

@@ -0,0 +1,40 @@
+import { Abi } from "abi-wan-kanabi";
+import { EventToPrimitiveType, ExtractAbiEventNames } from "abi-wan-kanabi/dist/kanabi";
+import { StarknetEvents } from "../../base/modules/StarknetEvents";
+import { StarknetContractBase } from "../StarknetContractBase";
+export type StarknetAbiEvent<TAbi extends Abi, TEventName extends ExtractAbiEventNames<TAbi>> = {
+    name: TEventName;
+    params: EventToPrimitiveType<TAbi, TEventName>;
+    txHash: string;
+    blockHash: string;
+    blockNumber: number;
+    keys: string[];
+    data: string[];
+};
+export declare class StarknetContractEvents<TAbi extends Abi> extends StarknetEvents {
+    readonly root: StarknetContractBase<TAbi>;
+    readonly abi: TAbi;
+    constructor(root: StarknetContractBase<TAbi>, abi: TAbi);
+    private toStarknetAbiEvents;
+    private toFilter;
+    /**
+     * Returns the events occuring in a range of starknet block as identified by the contract and keys,
+     *  returns pending events if no startHeight & endHeight is passed
+     *
+     * @param events
+     * @param keys
+     * @param startBlockHeight
+     * @param endBlockHeight
+     */
+    getContractBlockEvents<T extends ExtractAbiEventNames<TAbi>>(events: T[], keys: string[], startBlockHeight?: number, endBlockHeight?: number): Promise<StarknetAbiEvent<TAbi, T>[]>;
+    /**
+     * Runs a search forawrds in time, processing the events for a specific topic public key
+     *
+     * @param events
+     * @param keys
+     * @param processor called for every event, should return a value if the correct event was found, or null
+     *  if the search should continue
+     * @param abortSignal
+     */
+    findInContractEvents<T, TEvent extends ExtractAbiEventNames<TAbi>>(events: TEvent[], keys: string[], processor: (event: StarknetAbiEvent<TAbi, TEvent>) => Promise<T>, abortSignal?: AbortSignal): Promise<T>;
+}