@ethereumjs/blockchain / Blockchain
This class stores and interacts with blocks.
• Readonly common: Common
• consensus: Consensus
• db: DB<string | Uint8Array, string | Uint8Array | DBObject>
• dbManager: DBManager
• events: AsyncEventEmitter<BlockchainEvents>
Optional events emitter
• get genesisBlock(): Block
The genesis Block for the blockchain.
Block
▸ checkAndTransitionHardForkByNumber(number, td?, timestamp?): Promise<void>
| Name | Type |
|---|---|
number |
BigIntLike |
td? |
BigIntLike |
timestamp? |
BigIntLike |
Promise<void>
▸ createGenesisBlock(stateRoot): Block
Creates a genesis Block for the blockchain with params from Common.genesis
| Name | Type | Description |
|---|---|---|
stateRoot |
Uint8Array |
The genesis stateRoot |
Block
▸ delBlock(blockHash): Promise<void>
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).
| Name | Type | Description |
|---|---|---|
blockHash |
Uint8Array |
The hash of the block to be deleted |
Promise<void>
▸ getBlock(blockId): Promise<Block>
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
| Name | Type | Description |
|---|---|---|
blockId |
number | bigint | Uint8Array |
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 |
Promise<Block>
▸ getBlocks(blockId, maxBlocks, skip, reverse): Promise<Block[]>
Looks up many blocks relative to blockId Note: due to GetBlockHeaders
(0x03) (ETH wire protocol) we have to support skip/reverse as well.
| Name | Type | Description |
|---|---|---|
blockId |
number | bigint | Uint8Array |
The block’s hash or number |
maxBlocks |
number |
Max number of blocks to return |
skip |
number |
Number of blocks to skip apart |
reverse |
boolean |
Fetch blocks in reverse |
Promise<Block[]>
▸ getCanonicalHeadBlock(): Promise<Block>
Returns the latest full block in the canonical chain.
Promise<Block>
BlockchainInterface.getCanonicalHeadBlock
▸ getCanonicalHeadHeader(): Promise<BlockHeader>
Returns the latest header in the canonical chain.
Promise<BlockHeader>
▸ getCanonicalHeader(number): Promise<BlockHeader>
Gets a header by number. Header must be in the canonical chain
| Name | Type |
|---|---|
number |
bigint |
Promise<BlockHeader>
▸ getIteratorHead(name?): Promise<Block>
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 iterator.
| Name | Type | Default value | Description |
|---|---|---|---|
name |
string |
'vm' |
Optional name of the iterator head (default: ‘vm’) |
Promise<Block>
BlockchainInterface.getIteratorHead
▸ getIteratorHeadSafe(name?): Promise<undefined | Block>
This method differs from getIteratorHead. If the head is not found, it returns undefined.
| Name | Type | Default value | Description |
|---|---|---|---|
name |
string |
'vm' |
Optional name of the iterator head (default: ‘vm’) |
Promise<undefined | Block>
▸ getParentTD(header): Promise<bigint>
Gets total difficulty for a header’s parent, helpful for determining terminal block
| Name | Type | Description |
|---|---|---|
header |
BlockHeader |
Block header whose parent td is desired |
Promise<bigint>
▸ getTotalDifficulty(hash, number?): Promise<bigint>
Gets total difficulty for a block specified by hash and number
| Name | Type |
|---|---|
hash |
Uint8Array |
number? |
bigint |
Promise<bigint>
BlockchainInterface.getTotalDifficulty
▸ iterator(name, onBlock, maxBlocks?, releaseLockOnCallback?): Promise<number>
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 getIteratorHead.
| Name | Type | Description |
|---|---|---|
name |
string |
Name of the state root head |
onBlock |
OnBlock |
Function called on each block with params (block, reorg) |
maxBlocks? |
number |
How many blocks to run. By default, run all unprocessed blocks in the canonical chain. |
releaseLockOnCallback? |
boolean |
Do not lock the blockchain for running the callback (default: false) |
Promise<number>
number of blocks actually iterated
▸ putBlock(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.
| Name | Type | Description |
|---|---|---|
block |
Block |
The block to be added to the blockchain |
Promise<void>
▸ putBlocks(blocks): Promise<void>
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.
| Name | Type | Description |
|---|---|---|
blocks |
Block[] |
The blocks to be added to the blockchain |
Promise<void>
▸ putHeader(header): 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.
| Name | Type | Description |
|---|---|---|
header |
BlockHeader |
The header to be added to the blockchain |
Promise<void>
▸ putHeaders(headers): 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.
| Name | Type | Description |
|---|---|---|
headers |
any[] |
The headers to be added to the blockchain |
Promise<void>
▸ resetCanonicalHead(canonicalHead): 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
| Name | Type | Description |
|---|---|---|
canonicalHead |
bigint |
The number to which chain should be reset to |
Promise<void>
▸ safeNumberToHash(number): Promise<false | Uint8Array>
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.
| Name | Type |
|---|---|
number |
bigint |
Promise<false | Uint8Array>
▸ selectNeededHashes(hashes): Promise<Uint8Array[]>
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.
| Name | Type | Description |
|---|---|---|
hashes |
Uint8Array[] |
Ordered array of hashes (ordered on number). |
Promise<Uint8Array[]>
▸ setIteratorHead(tag, headHash): Promise<void>
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.
| Name | Type | Description |
|---|---|---|
tag |
string |
The tag to save the headHash to |
headHash |
Uint8Array |
The head hash to save |
Promise<void>
BlockchainInterface.setIteratorHead
▸ shallowCopy(): Blockchain
Returns a deep copy of this 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 db of this returned instance to a copy of the original.
BlockchainInterface.shallowCopy
▸ validateBlock(block): Promise<void>
Validates a block, by validating the header against the current chain, any uncle headers, and then whether the block is internally consistent
| Name | Type | Description |
|---|---|---|
block |
Block |
block to be validated |
Promise<void>
▸ validateHeader(header, height?): Promise<void>
Validates a block header, throwing if invalid. It is being validated against the reported parentHash.
It verifies the current block against the parentHash:
parentHash is part of the blockchain (it is a valid header)| Name | Type | Description |
|---|---|---|
header |
BlockHeader |
header to be validated |
height? |
bigint |
If this is an uncle header, this is the height of the block that is including it |
Promise<void>
BlockchainInterface.validateHeader
▸ Static create(opts?): Promise<Blockchain>
Safe creation of a new Blockchain object awaiting the initialization function, encouraged method to use when creating a blockchain object.
| Name | Type | Description |
|---|---|---|
opts |
BlockchainOptions |
Constructor options, see BlockchainOptions |
Promise<Blockchain>
▸ Static fromBlocksData(blocksData, opts?): Promise<Blockchain>
Creates a blockchain from a list of block objects, objects must be readable by Block.fromBlockData
| Name | Type | Description |
|---|---|---|
blocksData |
BlockData[] |
- |
opts |
BlockchainOptions |
Constructor options, see BlockchainOptions |
Promise<Blockchain>