@ethereumjs/blockchain / Blockchain
Defined in: blockchain.ts:60
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:
new Blockchain(
opts?):Blockchain
Defined in: blockchain.ts:114
Creates new Blockchain object.
BlockchainOptions = {}
An object with the options that this constructor takes. See BlockchainOptions.
Blockchain
The direct usage of this constructor is discouraged since non-finalized async initialization might lead to side effects. Please use the async createBlockchain constructor instead (same API).
readonlycommon:Common
Defined in: blockchain.ts:88
db:
DB<string|Uint8Array<ArrayBufferLike>,string|Uint8Array<ArrayBufferLike> |DBObject>
Defined in: blockchain.ts:61
dbManager:
DBManager
Defined in: blockchain.ts:62
events:
EventEmitter<BlockchainEvent>
Defined in: blockchain.ts:63
Optional events emitter
get consensus():
Consensus|undefined
Defined in: blockchain.ts:169
Returns an eventual consensus object matching the current consensus algorithm from Common or undefined if non available
Consensus | undefined
get genesisBlock():
Block
Defined in: blockchain.ts:1313
The genesis Block for the blockchain.
checkAndTransitionHardForkByNumber(
number,timestamp?):Promise<void>
Defined in: blockchain.ts:1272
BigIntLike
BigIntLike
Promise<void>
createGenesisBlock(
stateRoot):Block
Defined in: blockchain.ts:1323
Creates a genesis Block for the blockchain with params from Common.genesis
Uint8Array
The genesis stateRoot
delBlock(
blockHash):Promise<void>
Defined in: blockchain.ts:838
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).
Uint8Array
The hash of the block to be deleted
Promise<void>
getBlock(
blockId):Promise<Block>
Defined in: blockchain.ts:706
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
number | bigint | Uint8Array<ArrayBufferLike>
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[]>
Defined in: blockchain.ts:755
Looks up many blocks relative to blockId Note: due to GetBlockHeaders
(0x03) (ETH wire protocol) we have to support skip/reverse as well.
number | bigint | Uint8Array<ArrayBufferLike>
The block’s hash or number
number
Max number of blocks to return
number
Number of blocks to skip apart
boolean
Fetch blocks in reverse
Promise<Block[]>
getCanonicalHeadBlock():
Promise<Block>
Defined in: blockchain.ts:261
Returns the latest full block in the canonical chain.
Promise<Block>
BlockchainInterface.getCanonicalHeadBlock
getCanonicalHeader(
number):Promise<BlockHeader>
Defined in: blockchain.ts:1289
Gets a header by number. Header must be in the canonical chain
bigint
Promise<BlockHeader>
getCanonicalHeadHeader():
Promise<BlockHeader>
Defined in: blockchain.ts:250
Returns the latest header in the canonical chain.
Promise<BlockHeader>
getIteratorHead(
name?):Promise<Block>
Defined in: blockchain.ts:220
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 Blockchain.iterator.
string = 'vm'
Optional name of the iterator head (default: ‘vm’)
Promise<Block>
BlockchainInterface.getIteratorHead
getIteratorHeadSafe(
name?):Promise<Block|undefined>
Defined in: blockchain.ts:231
This method differs from getIteratorHead. If the head is not found, it returns undefined.
string = 'vm'
Optional name of the iterator head (default: ‘vm’)
Promise<Block | undefined>
getParentTD(
header):Promise<bigint>
Defined in: blockchain.ts:741
Gets total difficulty for a header’s parent, helpful for determining terminal block
Block header whose parent td is desired
Promise<bigint>
getTotalDifficulty(
hash,number?):Promise<bigint>
Defined in: blockchain.ts:727
Gets total difficulty for a block specified by hash and number
Uint8Array
bigint
Promise<bigint>
BlockchainInterface.getTotalDifficulty
iterator(
name,onBlock,maxBlocks?,releaseLockOnCallback?):Promise<number>
Defined in: blockchain.ts:949
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 Blockchain.getIteratorHead.
string
Name of the state root head
Function called on each block with params (block, reorg)
number
How many blocks to run. By default, run all unprocessed blocks in the canonical chain.
boolean
Do not lock the blockchain for running the callback (default: false)
Promise<number>
number of blocks actually iterated
putBlock(
block):Promise<void>
Defined in: blockchain.ts:293
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.
The block to be added to the blockchain
Promise<void>
putBlocks(
blocks):Promise<void>
Defined in: blockchain.ts:277
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.
Block[]
The blocks to be added to the blockchain
Promise<void>
putHeader(
header):Promise<void>
Defined in: blockchain.ts:322
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.
The header to be added to the blockchain
Promise<void>
putHeaders(
headers):Promise<void>
Defined in: blockchain.ts:306
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.
any[]
The headers to be added to the blockchain
Promise<void>
resetCanonicalHead(
canonicalHead):Promise<void>
Defined in: blockchain.ts:334
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
bigint
The number to which chain should be reset to
Promise<void>
safeNumberToHash(
number):Promise<false|Uint8Array<ArrayBufferLike>>
Defined in: blockchain.ts:1305
Look up a canonical block hash by number without throwing when absent.
bigint
Canonical block height to resolve
Promise<false | Uint8Array<ArrayBufferLike>>
Block hash bytes, or false when not in the canonical chain
If the DB returns an unexpected error
selectNeededHashes(
hashes):Promise<Uint8Array<ArrayBufferLike>[]>
Defined in: blockchain.ts:797
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.
Uint8Array<ArrayBufferLike>[]
Ordered array of hashes (ordered on number).
Promise<Uint8Array<ArrayBufferLike>[]>
setIteratorHead(
tag,headHash):Promise<void>
Defined in: blockchain.ts:1032
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.
string
The tag to save the headHash to
Uint8Array
The head hash to save
Promise<void>
BlockchainInterface.setIteratorHead
shallowCopy():
Blockchain
Defined in: blockchain.ts:184
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.
Blockchain
BlockchainInterface.shallowCopy
validateBlock(
block):Promise<void>
Defined in: blockchain.ts:605
Validates a block, by validating the header against the current chain, any uncle headers, and then whether the block is internally consistent
block to be validated
Promise<void>
validateHeader(
header,height?):Promise<void>
Defined in: blockchain.ts:528
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)header to be validated
bigint
If this is an uncle header, this is the height of the block that is including it
Promise<void>