@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:1311
The genesis Block for the blockchain.
Block
checkAndTransitionHardForkByNumber(
number,timestamp?):Promise<void>
Defined in: blockchain.ts:1272
BigIntLike
BigIntLike
Promise<void>
createGenesisBlock(
stateRoot):Block
Defined in: blockchain.ts:1321
Creates a genesis Block for the blockchain with params from Common.genesis
Uint8Array
The genesis stateRoot
Block
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
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
number |
bigint |
Uint8Array<ArrayBufferLike> |
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.
The block’s hash or number
number |
bigint |
Uint8Array<ArrayBufferLike> |
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
BlockHeader
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.
Block
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.
BlockHeader
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:1303
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.
bigint
Promise<false | Uint8Array<ArrayBufferLike>>
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
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)BlockHeader
header to be validated
bigint
If this is an uncle header, this is the height of the block that is including it
Promise<void>