@feelyourprotocol/blockchain 8141.0.0

package/README.md

@@ -0,0 +1,269 @@
+# @ethereumjs/blockchain `v10`
+
+[![NPM Package][blockchain-npm-badge]][blockchain-npm-link]
+[![GitHub Issues][blockchain-issues-badge]][blockchain-issues-link]
+[![Actions Status][blockchain-actions-badge]][blockchain-actions-link]
+[![Code Coverage][blockchain-coverage-badge]][blockchain-coverage-link]
+[![Discord][discord-badge]][discord-link]
+
+| A module to store and interact with blocks. |
+| ------------------------------------------- |
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+- [EIP Integrations](#eip-integrations)
+- [Consensus Types](#consensus-types)
+- [Browser](#browser)
+- [API](#api)
+- [Testing](#testing)
+- [EthereumJS](#ethereumjs)
+- [License](#license)
+
+## Installation
+
+To obtain the latest version, simply install the project using `npm`:
+
+```shell
+npm install @ethereumjs/blockchain
+```
+
+**Note:** If you want to work with `EIP-4844` related functionality, you will have additional initialization steps for the **KZG setup**, see related section below.
+
+## Getting Started
+
+### Introduction
+
+The `Blockchain` package represents an Ethereum-compatible blockchain storing a sequential chain of [@ethereumjs/block](../block) blocks and holding information about the current canonical head block as well as the context the chain is operating in (e.g. the hardfork rules the current head block adheres to).
+
+New blocks can be added to the blockchain. Validation ensures that the block format adheres to the given chain rules (with the `Blockchain.validateBlock()` function) and consensus rules (`Blockchain.consensus.validateConsensus()`).
+
+The library also supports reorg scenarios e.g. by allowing to add a new block with `Blockchain.putBlock()` which follows a different canonical path to the head than given by the current canonical head block.
+
+## Examples
+
+The following is an example to instantiate a simple Blockchain object, put blocks into the blockchain and then iterate through the blocks added:
+
+```ts
+// ./examples/simple.ts
+
+import { createBlock } from '@ethereumjs/block'
+import { createBlockchain } from '@ethereumjs/blockchain'
+import { Common, Hardfork, Mainnet } from '@ethereumjs/common'
+import { bytesToHex } from '@ethereumjs/util'
+
+const main = async () => {
+  const common = new Common({ chain: Mainnet, hardfork: Hardfork.London })
+  // Use the safe static constructor which awaits the init method
+  const blockchain = await createBlockchain({
+    validateBlocks: false, // Skipping validation so we can make a simple chain without having to provide complete blocks
+    validateConsensus: false,
+    common,
+  })
+
+  // We use minimal data to provide a sequence of blocks (increasing number, difficulty, and then setting parent hash to previous block)
+  const block = createBlock(
+    {
+      header: {
+        number: 1n,
+        parentHash: blockchain.genesisBlock.hash(),
+        difficulty: blockchain.genesisBlock.header.difficulty + 1n,
+      },
+    },
+    { common, setHardfork: true },
+  )
+  const block2 = createBlock(
+    {
+      header: {
+        number: 2n,
+        parentHash: block.header.hash(),
+        difficulty: block.header.difficulty + 1n,
+      },
+    },
+    { common, setHardfork: true },
+  )
+  // See @ethereumjs/block for more details on how to create a block
+  await blockchain.putBlock(block)
+  await blockchain.putBlock(block2)
+
+  // We iterate over the blocks in the chain to the current head (block 2)
+  await blockchain.iterator('i', (block) => {
+    const blockNumber = block.header.number.toString()
+    const blockHash = bytesToHex(block.hash())
+    console.log(`Block ${blockNumber}: ${blockHash}`)
+  })
+
+  // Block 1: 0xa1a061528d74ba81f560e1ebc4f29d6b58171fc13b72b876cdffe6e43b01bdc5
+  // Block 2: 0x5583be91cf9fb14f5dbeb03ad56e8cef19d1728f267c35a25ba5a355a528f602
+}
+void main()
+```
+
+More examples can be found in the [examples](./examples/) folder.
+
+## Setup
+
+### Block Storage
+
+For storing blocks different backends can be used. The database needs to conform to the [DB](https://github.com/ethereumjs/ethereumjs-monorepo/blob/master/packages/util/src/db.ts) interface provided in the `@ethereumjs/util` package (since this is used in other places as well).
+
+By default the blockchain package uses a [MapDB](https://github.com/ethereumjs/ethereumjs-monorepo/blob/master/packages/util/src/mapDB.ts) non-persistent data storage which is also generically provided in the `@ethereumjs/util` package.
+
+If you need a persistent data store for your use case you can consider using the wrapper we have written within our [client](https://github.com/ethereumjs/ethereumjs-monorepo/blob/master/packages/client/src/execution/level.ts) library.
+
+### Consensus
+
+Starting with v6 there is a dedicated consensus class for each type of supported consensus, `Ethash`, `Clique` and `Casper` (PoS, this one is rather the do-nothing part of `Casper` and letting the respective consensus/beacon client do the hard work! 🙂). Each consensus class adheres to a common interface `Consensus` implementing the following five methods in a consensus-specific way:
+
+- `genesisInit(genesisBlock: Block): Promise<void>`
+- `setup(): Promise<void>`
+- `validateConsensus(block: Block): Promise<void>`
+- `validateDifficulty(header: BlockHeader): Promise<void>`
+- `newBlock(block: Block, commonAncestor?: BlockHeader, ancientHeaders?: BlockHeader[]): Promise<void>`
+
+#### Custom Consensus Algorithms
+
+Also part of V6, you can also create a custom consensus class implementing the above interface and pass it into the `Blockchain` constructor using the `consensus` option at instantiation. See [this test script](https://github.com/ethereumjs/ethereumjs-monorepo/blob/master/packages/blockchain/test/customConsensus.spec.ts) for a complete example of how write and use a custom consensus implementation.
+
+Note, if you construct a blockchain with a custom consensus implementation, transition checks for switching from PoW to PoS are disabled so defining a merge hardfork will have no impact on the consensus mechanism defined for the chain.
+
+## Custom Genesis State
+
+### Genesis State
+
+Genesis state for the 4 supported networks (mainnet, sepolia, hoodi, holesky) is stored in an auxiliary package [@ethereumjs/genesis](https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/genesis), from which it can be included if needed (for most - especially VM - use cases it is not necessary), see PR [#2844](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2844).
+
+
+### Custom genesis from a Geth genesis config
+
+For many custom chains we might come across a genesis configuration, which can be used to build both chain config as well the genesis state (and hence the genesis block as well to start off with)
+
+```ts
+// ./examples/gethGenesis.ts
+
+import { createBlockchain } from '@ethereumjs/blockchain'
+import { createCommonFromGethGenesis, parseGethGenesisState } from '@ethereumjs/common'
+import { postMergeGethGenesis } from '@ethereumjs/testdata'
+import { bytesToHex } from '@ethereumjs/util'
+
+const main = async () => {
+  // Load geth genesis file
+  const common = createCommonFromGethGenesis(postMergeGethGenesis, { chain: 'customChain' })
+  const genesisState = parseGethGenesisState(postMergeGethGenesis)
+  const blockchain = await createBlockchain({
+    genesisState,
+    common,
+  })
+  const genesisBlockHash = blockchain.genesisBlock.hash()
+  common.setForkHashes(genesisBlockHash)
+  console.log(
+    `Genesis hash from geth genesis parameters - ${bytesToHex(blockchain.genesisBlock.hash())}`,
+  )
+}
+
+void main()
+
+```
+
+The genesis block from the initialized `Blockchain` can be retrieved via the `Blockchain.genesisBlock` getter. For creating a genesis block from the params in `@ethereumjs/common`, the `createGenesisBlock(stateRoot: Buffer): Block` method can be used.
+
+## Supported Blocks and Tx Types
+
+### EIP-1559 Support
+
+This library supports the handling of `EIP-1559` blocks and transactions starting with the `v5.3.0` release.
+
+### EIP-4844 Shard Blob Transactions Support
+
+This library supports the blob transaction type introduced with [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844).
+
+The blockchain library now allows for blob transactions to be validated and included in a chain where EIP-4844 activated either by hardfork or standalone EIP.
+
+**Note:** Working with blob transactions needs a manual KZG library installation and global initialization, see [KZG Setup](https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/tx/README.md#kzg-setup) for instructions.
+
+### EIP-7685 Requests Support
+
+This library supports blocks including the [EIP-7685](https://eips.ethereum.org/EIPS/eip-7685) requests to the consensus layer (like e.g. deposit or withdrawal requests).
+
+## Browser
+
+We provide hybrid ESM/CJS builds for all our libraries. With the v10 breaking release round from Spring 2025, all libraries are "pure-JS" by default and we have eliminated all hard-wired WASM code. Additionally we have substantially lowered the bundle sizes, reduced the number of dependencies, and cut out all usages of Node.js-specific primitives (like the Node.js event emitter).
+
+It is easily possible to run a browser build of one of the EthereumJS libraries within a modern browser using the provided ESM build. For a setup example see [./examples/browser.html](./examples/browser.html).
+
+## API
+
+### Docs
+
+Generated TypeDoc API [Documentation](./docs/README.md)
+
+### Hybrid CJS/ESM Builds
+
+With the breaking releases from Summer 2023 we have started to ship our libraries with both CommonJS (`cjs` folder) and ESM builds (`esm` folder), see `package.json` for the detailed setup.
+
+If you use an ES6-style `import` in your code files from the ESM build will be used:
+
+```ts
+import { EthereumJSClass } from '@ethereumjs/[PACKAGE_NAME]'
+```
+
+If you use Node.js specific `require`, the CJS build will be used:
+
+```ts
+const { EthereumJSClass } = require('@ethereumjs/[PACKAGE_NAME]')
+```
+
+Using ESM will give you additional advantages over CJS beyond browser usage like static code analysis / Tree Shaking which CJS can not provide.
+
+## Events
+
+The `Blockchain` class has a public property `events` which contains an `EventEmitter` (using [EventEmitter3](https://github.com/primus/eventemitter3)). Following events are emitted on which you can react within your code:
+
+| Event                    | Description                                 |
+| ------------------------ | ------------------------------------------- |
+| `deletedCanonicalBlocks` | Emitted when blocks are reorged and deleted |
+
+## Debugging
+
+This library uses the [debug](https://github.com/visionmedia/debug) debugging utility package.
+
+The following initial logger is currently available:
+
+| Logger              | Description                                                              |
+| ------------------- | ------------------------------------------------------------------------ |
+| `blockchain:#`      | Core blockchain operations like when a block or header is put or deleted |
+| `blockchain:clique` | Clique consensus operations like updating the vote and/or signer list    |
+| `blockchain:ethash` | Ethash consensus operations like PoW block or header validation          |
+
+The following is an example for a logger run:
+
+Run with the clique logger:
+
+```shell
+DEBUG=ethjs,blockchain:clique tsx test.ts
+```
+
+`ethjs` **must** be included in the `DEBUG` environment variables to enable **any** logs.
+Additional log selections can be added with a comma separated list (no spaces). Logs with extensions can be enabled with a colon `:`, and `*` can be used to include all extensions (currently do not apply for blockchain debugging, example taken from another library).
+
+`DEBUG=ethjs,statemanager:cache:*,trie,statemanager:merkle npx vitest test/statemanager.spec.ts`
+
+## EthereumJS
+
+The `EthereumJS` GitHub organization and its repositories are managed by members of the former Ethereum Foundation JavaScript team and the broader Ethereum community. If you want to join for work or carry out improvements on the libraries see the [developer docs](../../DEVELOPER.md) for an overview of current standards and tools and review our [code of conduct](../../CODE_OF_CONDUCT.md).
+
+## License
+
+[MPL-2.0](<https://tldrlegal.com/license/mozilla-public-license-2.0-(mpl-2)>)
+
+[discord-badge]: https://img.shields.io/static/v1?logo=discord&label=discord&message=Join&color=blue
+[discord-link]: https://discord.gg/TNwARpR
+[blockchain-npm-badge]: https://img.shields.io/npm/v/@ethereumjs/blockchain.svg
+[blockchain-npm-link]: https://www.npmjs.com/package/@ethereumjs/blockchain
+[blockchain-issues-badge]: https://img.shields.io/github/issues/ethereumjs/ethereumjs-monorepo/package:%20blockchain?label=issues
+[blockchain-issues-link]: https://github.com/ethereumjs/ethereumjs-monorepo/issues?q=is%3Aopen+is%3Aissue+label%3A"package%3A+blockchain"
+[blockchain-actions-badge]: https://github.com/ethereumjs/ethereumjs-monorepo/workflows/Blockchain/badge.svg
+[blockchain-actions-link]: https://github.com/ethereumjs/ethereumjs-monorepo/actions?query=workflow%3A%22Blockchain%22
+[blockchain-coverage-badge]: https://codecov.io/gh/ethereumjs/ethereumjs-monorepo/branch/master/graph/badge.svg?flag=blockchain
+[blockchain-coverage-link]: https://codecov.io/gh/ethereumjs/ethereumjs-monorepo/tree/master/packages/blockchain

package/dist/cjs/blockchain.d.ts

@@ -0,0 +1,372 @@
+import { Block, BlockHeader } from '@feelyourprotocol/block';
+import { Common } from '@feelyourprotocol/common';
+import { EventEmitter } from 'eventemitter3';
+import { DBManager } from './db/manager.ts';
+import type { BigIntLike, DB, DBObject } from '@feelyourprotocol/util';
+import type { BlockchainEvent, BlockchainInterface, BlockchainOptions, Consensus, OnBlock } from './types.ts';
+/**
+ * Blockchain implementation to create and maintain a valid canonical chain
+ * of block headers or blocks with support for reorgs and the ability to provide
+ * custom DB backends.
+ *
+ * By default consensus validation is not provided since with the switch to
+ * Proof-of-Stake consensus is validated by the Ethereum consensus layer.
+ * If consensus validation is desired for Ethash or Clique blockchains the
+ * optional `consensusDict` option can be used to pass in validation objects.
+ *
+ * A Blockchain object can be created with the constructor method:
+ *
+ * - {@link createBlockchain}
+ */
+export declare class Blockchain implements BlockchainInterface {
+    db: DB<Uint8Array | string, Uint8Array | string | DBObject>;
+    dbManager: DBManager;
+    events: EventEmitter<BlockchainEvent>;
+    private _genesisBlock?; /** The genesis block of this blockchain */
+    private _customGenesisState?; /** Custom genesis state */
+    /**
+     * The following two heads and the heads stored within the `_heads` always point
+     * to a hash in the canonical chain and never to a stale hash.
+     * With the exception of `_headHeaderHash` this does not necessarily need to be
+     * the hash with the highest total difficulty.
+     */
+    /** The hash of the current head block */
+    private _headBlockHash?;
+    /** The hash of the current head header */
+    private _headHeaderHash?;
+    /**
+     * A Map which stores the head of each key (for instance the "vm" key) which is
+     * updated along a {@link Blockchain.iterator} method run and can be used to (re)run
+     * non-verified blocks (for instance in the VM).
+     */
+    private _heads;
+    private _lock;
+    readonly common: Common;
+    private _hardforkByHeadBlockNumber;
+    private readonly _validateBlocks;
+    private readonly _validateConsensus;
+    private _consensusDict;
+    /**
+     * This is used to track which canonical blocks are deleted. After a method calls
+     * `_deleteCanonicalChainReferences`, if this array has any items, the
+     * `deletedCanonicalBlocks` event is emitted with the array as argument.
+     */
+    private _deletedBlocks;
+    private DEBUG;
+    private _debug;
+    /**
+     * Creates new Blockchain object.
+     *
+     * @deprecated The direct usage of this constructor is discouraged since
+     * non-finalized async initialization might lead to side effects. Please
+     * use the async {@link createBlockchain} constructor instead (same API).
+     *
+     * @param opts An object with the options that this constructor takes. See
+     * {@link BlockchainOptions}.
+     */
+    constructor(opts?: BlockchainOptions);
+    private _consensusCheck;
+    /**
+     * Returns an eventual consensus object matching the current consensus algorithm from Common
+     * or undefined if non available
+     */
+    get consensus(): Consensus | undefined;
+    /**
+     * Returns a deep copy of this {@link Blockchain} instance.
+     *
+     * Note: this does not make a copy of the underlying db
+     * since it is unknown if the source is on disk or in memory.
+     * This should not be a significant issue in most usage since
+     * the queries will only reflect the instance's known data.
+     * If you would like this copied blockchain to use another db
+     * set the {@link db} of this returned instance to a copy of
+     * the original.
+     */
+    shallowCopy(): Blockchain;
+    /**
+     * Run a function after acquiring a lock. It is implied that we have already
+     * initialized the module (or we are calling this from the init function, like
+     * `_setCanonicalGenesisBlock`)
+     * @param action - function to run after acquiring a lock
+     * @hidden
+     */
+    private runWithLock;
+    /**
+     * Returns the specified iterator head.
+     *
+     * This function replaces the old Blockchain.getHead() method. Note that
+     * the function deviates from the old behavior and returns the
+     * genesis hash instead of the current head block if an iterator
+     * has not been run. This matches the behavior of {@link Blockchain.iterator}.
+     *
+     * @param name - Optional name of the iterator head (default: 'vm')
+     */
+    getIteratorHead(name?: string): Promise<Block>;
+    /**
+     * This method differs from `getIteratorHead`. If the head is not found, it returns `undefined`.
+     * @param name - Optional name of the iterator head (default: 'vm')
+     * @returns
+     */
+    getIteratorHeadSafe(name?: string): Promise<Block | undefined>;
+    private getHead;
+    /**
+     * Returns the latest header in the canonical chain.
+     */
+    getCanonicalHeadHeader(): Promise<BlockHeader>;
+    /**
+     * Returns the latest full block in the canonical chain.
+     */
+    getCanonicalHeadBlock(): Promise<Block>;
+    /**
+     * Adds blocks to the blockchain.
+     *
+     * If an invalid block is met the function will throw, blocks before will
+     * nevertheless remain in the DB. If any of the saved blocks has a higher
+     * total difficulty than the current max total difficulty the canonical
+     * chain is rebuilt and any stale heads/hashes are overwritten.
+     * @param blocks - The blocks to be added to the blockchain
+     */
+    putBlocks(blocks: Block[]): Promise<void>;
+    /**
+     * Adds a block to the blockchain.
+     *
+     * If the block is valid and has a higher total difficulty than the current
+     * max total difficulty, the canonical chain is rebuilt and any stale
+     * heads/hashes are overwritten.
+     * @param block - The block to be added to the blockchain
+     */
+    putBlock(block: Block): Promise<void>;
+    /**
+     * Adds many headers to the blockchain.
+     *
+     * If an invalid header is met the function will throw, headers before will
+     * nevertheless remain in the DB. If any of the saved headers has a higher
+     * total difficulty than the current max total difficulty the canonical
+     * chain is rebuilt and any stale heads/hashes are overwritten.
+     * @param headers - The headers to be added to the blockchain
+     */
+    putHeaders(headers: Array<any>): Promise<void>;
+    /**
+     * Adds a header to the blockchain.
+     *
+     * If this header is valid and it has a higher total difficulty than the current
+     * max total difficulty, the canonical chain is rebuilt and any stale
+     * heads/hashes are overwritten.
+     * @param header - The header to be added to the blockchain
+     */
+    putHeader(header: BlockHeader): Promise<void>;
+    /**
+     * Resets the canonical chain to canonicalHead number
+     *
+     * This updates the head hashes (if affected) to the hash corresponding to
+     * canonicalHead and cleans up canonical references greater than canonicalHead
+     * @param canonicalHead - The number to which chain should be reset to
+     */
+    resetCanonicalHead(canonicalHead: bigint): Promise<void>;
+    /**
+     * Entrypoint for putting any block or block header. Verifies this block,
+     * checks the total TD: if this TD is higher than the current highest TD, we
+     * have thus found a new canonical block and have to rewrite the canonical
+     * chain. This also updates the head block hashes. If any of the older known
+     * canonical chains just became stale, then we also reset every _heads header
+     * which points to a stale header to the last verified header which was in the
+     * old canonical chain, but also in the new canonical chain. This thus rolls
+     * back these headers so that these can be updated to the "new" canonical
+     * header using the iterator method.
+     * @hidden
+     */
+    private _putBlockOrHeader;
+    /**
+     * Validates a block header, throwing if invalid. It is being validated against the reported `parentHash`.
+     * It verifies the current block against the `parentHash`:
+     * - The `parentHash` is part of the blockchain (it is a valid header)
+     * - Current block number is parent block number + 1
+     * - Current block has a strictly higher timestamp
+     * - Additional PoW checks ->
+     *   - Current block has valid difficulty and gas limit
+     *   - In case that the header is an uncle header, it should not be too old or young in the chain.
+     * - Additional PoA clique checks ->
+     *   - Checks on coinbase and mixHash
+     *   - Current block has a timestamp diff greater or equal to PERIOD
+     *   - Current block has difficulty correctly marked as INTURN or NOTURN
+     * @param header - header to be validated
+     * @param height - If this is an uncle header, this is the height of the block that is including it
+     */
+    validateHeader(header: BlockHeader, height?: bigint): Promise<void>;
+    /**
+     * Validates a block, by validating the header against the current chain, any uncle headers, and then
+     * whether the block is internally consistent
+     * @param block block to be validated
+     */
+    validateBlock(block: Block): Promise<void>;
+    /**
+     * The following rules are checked in this method:
+     * Uncle Header is a valid header.
+     * Uncle Header is an orphan, i.e. it is not one of the headers of the canonical chain.
+     * Uncle Header has a parentHash which points to the canonical chain. This parentHash is within the last 7 blocks.
+     * Uncle Header is not already included as uncle in another block.
+     * @param block - block for which uncles are being validated
+     */
+    private _validateUncleHeaders;
+    /**
+     * Gets a block by its hash or number.  If a number is provided, the returned
+     * block will be the canonical block at that number in the chain
+     *
+     * @param blockId - The block's hash or number. If a hash is provided, then
+     * this will be immediately looked up, otherwise it will wait until we have
+     * unlocked the DB
+     */
+    getBlock(blockId: Uint8Array | number | bigint): Promise<Block>;
+    /**
+     * Gets total difficulty for a block specified by hash and number
+     */
+    getTotalDifficulty(hash: Uint8Array, number?: bigint): Promise<bigint>;
+    /**
+     * Gets total difficulty for a header's parent, helpful for determining terminal block
+     * @param header - Block header whose parent td is desired
+     */
+    getParentTD(header: BlockHeader): Promise<bigint>;
+    /**
+     * Looks up many blocks relative to blockId Note: due to `GetBlockHeaders
+     * (0x03)` (ETH wire protocol) we have to support skip/reverse as well.
+     * @param blockId - The block's hash or number
+     * @param maxBlocks - Max number of blocks to return
+     * @param skip - Number of blocks to skip apart
+     * @param reverse - Fetch blocks in reverse
+     */
+    getBlocks(blockId: Uint8Array | bigint | number, maxBlocks: number, skip: number, reverse: boolean): Promise<Block[]>;
+    /**
+     * Given an ordered array, returns an array of hashes that are not in the
+     * blockchain yet. Uses binary search to find out what hashes are missing.
+     * Therefore, the array needs to be ordered upon number.
+     * @param hashes - Ordered array of hashes (ordered on `number`).
+     */
+    selectNeededHashes(hashes: Array<Uint8Array>): Promise<Uint8Array[]>;
+    /**
+     * Completely deletes a block from the blockchain including any references to
+     * this block. If this block was in the canonical chain, then also each child
+     * block of this block is deleted Also, if this was a canonical block, each
+     * head header which is part of this now stale chain will be set to the
+     * parentHeader of this block An example reason to execute is when running the
+     * block in the VM invalidates this block: this will then reset the canonical
+     * head to the past block (which has been validated in the past by the VM, so
+     * we can be sure it is correct).
+     * @param blockHash - The hash of the block to be deleted
+     */
+    delBlock(blockHash: Uint8Array): Promise<void>;
+    /**
+     * @hidden
+     */
+    private _delBlock;
+    /**
+     * Updates the `DatabaseOperation` list to delete a block from the DB,
+     * identified by `blockHash` and `blockNumber`. Deletes fields from `Header`,
+     * `Body`, `HashToNumber` and `TotalDifficulty` tables. If child blocks of
+     * this current block are in the canonical chain, delete these as well. Does
+     * not actually commit these changes to the DB. Sets `_headHeaderHash` and
+     * `_headBlockHash` to `headHash` if any of these matches the current child to
+     * be deleted.
+     * @param blockHash - the block hash to delete
+     * @param blockNumber - the number corresponding to the block hash
+     * @param headHash - the current head of the chain (if null, do not update
+     * `_headHeaderHash` and `_headBlockHash`)
+     * @param ops - the `DatabaseOperation` list to add the delete operations to
+     * @hidden
+     */
+    private _delChild;
+    /**
+     * Iterates through blocks starting at the specified iterator head and calls
+     * the onBlock function on each block. The current location of an iterator
+     * head can be retrieved using {@link Blockchain.getIteratorHead}.
+     *
+     * @param name - Name of the state root head
+     * @param onBlock - Function called on each block with params (block, reorg)
+     * @param maxBlocks - How many blocks to run. By default, run all unprocessed blocks in the canonical chain.
+     * @param releaseLockOnCallback - Do not lock the blockchain for running the callback (default: `false`)
+     * @returns number of blocks actually iterated
+     */
+    iterator(name: string, onBlock: OnBlock, maxBlocks?: number, releaseLockOnCallback?: boolean): Promise<number>;
+    /**
+     * Set header hash of a certain `tag`.
+     * When calling the iterator, the iterator will start running the first child block after the header hash currently stored.
+     * @param tag - The tag to save the headHash to
+     * @param headHash - The head hash to save
+     */
+    setIteratorHead(tag: string, headHash: Uint8Array): Promise<void>;
+    /**
+     * Find the common ancestor of the new block and the old block.
+     * @param newHeader - the new block header
+     */
+    private findCommonAncestor;
+    /**
+     * Pushes DB operations to delete canonical number assignments for specified
+     * block number and above. This only deletes `NumberToHash` references and not
+     * the blocks themselves. Note: this does not write to the DB but only pushes
+     * to a DB operations list.
+     * @param blockNumber - the block number from which we start deleting
+     * canonical chain assignments (including this block)
+     * @param headHash - the hash of the current canonical chain head. The _heads
+     * reference matching any hash of any of the deleted blocks will be set to
+     * this
+     * @param ops - the DatabaseOperation list to write DatabaseOperations to
+     * @hidden
+     */
+    private _deleteCanonicalChainReferences;
+    /**
+     * Given a `header`, put all operations to change the canonical chain directly
+     * into `ops`. This walks the supplied `header` backwards. It is thus assumed
+     * that this header should be canonical header. For each header the
+     * corresponding hash corresponding to the current canonical chain in the DB
+     * is checked. If the number => hash reference does not correspond to the
+     * reference in the DB, we overwrite this reference with the implied number =>
+     * hash reference Also, each `_heads` member is checked; if these point to a
+     * stale hash, then the hash which we terminate the loop (i.e. the first hash
+     * which matches the number => hash of the implied chain) is put as this stale
+     * head hash. The same happens to _headBlockHash.
+     * @param header - The canonical header.
+     * @param ops - The database operations list.
+     * @hidden
+     */
+    private _rebuildCanonical;
+    /**
+     * Builds the `DatabaseOperation[]` list which describes the DB operations to
+     * write the heads, head header hash and the head header block to the DB
+     * @hidden
+     */
+    private _saveHeadOps;
+    /**
+     * Gets the `DatabaseOperation[]` list to save `_heads`, `_headHeaderHash` and
+     * `_headBlockHash` and writes these to the DB
+     * @hidden
+     */
+    private _saveHeads;
+    /**
+     * Gets a header by hash and number. Header can exist outside the canonical
+     * chain
+     *
+     * @hidden
+     */
+    private _getHeader;
+    checkAndTransitionHardForkByNumber(number: BigIntLike, timestamp?: BigIntLike): Promise<void>;
+    /**
+     * Gets a header by number. Header must be in the canonical chain
+     */
+    getCanonicalHeader(number: bigint): Promise<BlockHeader>;
+    /**
+     * This method either returns a Uint8Array if there exists one in the DB or if it
+     * does not exist then return false If DB throws
+     * any other error, this function throws.
+     * @param number
+     */
+    safeNumberToHash(number: bigint): Promise<Uint8Array | false>;
+    /**
+     * The genesis {@link Block} for the blockchain.
+     */
+    get genesisBlock(): Block;
+    /**
+     * Creates a genesis {@link Block} for the blockchain with params from {@link Common.genesis}
+     * @param stateRoot The genesis stateRoot
+     */
+    createGenesisBlock(stateRoot: Uint8Array): Block;
+}
+//# sourceMappingURL=blockchain.d.ts.map

package/dist/cjs/blockchain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blockchain.d.ts","sourceRoot":"","sources":["../../src/blockchain.ts"],"names":[],"mappings":"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"}