@ethereumjs/blockchain / Blockchain
This class stores and interacts with blocks.
- copy
- createGenesisBlock
- delBlock
- genesisState
- getBlock
- getBlocks
- getCanonicalHeadBlock
- getCanonicalHeadHeader
- getCanonicalHeader
- getHead
- getIteratorHead
- getTotalDifficulty
- iterator
- putBlock
- putBlocks
- putHeader
- putHeaders
- safeNumberToHash
- selectNeededHashes
- setIteratorHead
- validateBlock
- validateHeader
- create
- fromBlocksData
• _common: Common
• consensus: Consensus
• db: AbstractLevel<string | Uint8Array | Buffer, string | Buffer, string | Buffer>
• dbManager: DBManager
• get genesisBlock(): Block
The genesis Block for the blockchain.
Block
▸ copy(): 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.
▸ createGenesisBlock(stateRoot): Block
Creates a genesis Block for the blockchain with params from Common.genesis
| Name | Type | Description |
|---|---|---|
stateRoot |
Buffer |
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 |
Buffer |
The hash of the block to be deleted |
Promise<void>
▸ genesisState(): GenesisState
Returns the genesis state of the blockchain. All values are provided as hex-prefixed strings.
GenesisState
BlockchainInterface.genesisState
▸ getBlock(blockId): Promise<Block>
Gets a block by its hash.
| Name | Type | Description |
|---|---|---|
blockId |
number | bigint | Buffer |
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 | Buffer |
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>
▸ getHead(name?): Promise<Block>
Returns the specified iterator head.
Deprecated
use getIteratorHead instead.
Note that getIteratorHead doesn't return
the headHeader but the genesis hash as an initial iterator
head value (now matching the behavior of iterator
on a first run)
| Name | Type | Default value | Description |
|---|---|---|---|
name |
string |
'vm' |
Optional name of the iterator head (default: 'vm') |
Promise<Block>
▸ getIteratorHead(name?): Promise<Block>
Returns the specified iterator head.
This function replaces the old 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
▸ getTotalDifficulty(hash, number?): Promise<bigint>
Gets total difficulty for a block specified by hash and number
| Name | Type |
|---|---|
hash |
Buffer |
number? |
bigint |
Promise<bigint>
BlockchainInterface.getTotalDifficulty
▸ iterator(name, onBlock, maxBlocks?): 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. |
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>
▸ safeNumberToHash(number): Promise<false | Buffer>
This method either returns a Buffer if there exists one in the DB or if it
does not exist (DB throws a NotFoundError) then return false If DB throws
any other error, this function throws.
| Name | Type |
|---|---|
number |
bigint |
Promise<false | Buffer>
▸ selectNeededHashes(hashes): Promise<Buffer[]>
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 |
Buffer[] |
Ordered array of hashes (ordered on number). |
Promise<Buffer[]>
▸ 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 |
Buffer |
The head hash to save |
Promise<void>
▸ 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:
- The
parentHashis 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
| 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>