@ethereumjs/block

Implements schema and functions related to Ethereum's block.

Note: this README reflects the state of the library from v3.0.0 onwards. See README from the standalone repository for an introduction on the last preceding release.

INSTALL

npm install @ethereumjs/block

USAGE

Introduction

There are three static factories to instantiate a Block:

Block.fromBlockData(blockData: BlockData = {}, opts?: BlockOptions)
Block.fromRLPSerializedBlock(serialized: Buffer, opts?: BlockOptions)
Block.fromValuesArray(values: BlockBuffer, opts?: BlockOptions)

For BlockHeader instantiation analog factory methods exists, see API docs linked below.

Instantiation Example:

import { BlockHeader } from '@ethereumjs/block'

const headerData = {
  number: 15,
  parentHash: '0x6bfee7294bf44572b7266358e627f3c35105e1c3851f3de09e6d646f955725a7',
  difficulty: 131072,
  gasLimit: 8000000,
  timestamp: 1562422144,
}
const header = BlockHeader.fromHeaderData(headerData)

Properties of a Block or BlockHeader object are frozen with Object.freeze() which gives you enhanced security and consistency properties when working with the instantiated object. This behavior can be modified using the freeze option in the constructor if needed.

API Usage Example:

try {
  await block.validate(blockchain)
  // Block validation has passed
} catch (err) {
  // handle errors appropriately
}

EIP-1559 Blocks

This library supports the creation of EIP-1559 compatible blocks starting with v3.3.0.

To instantiate an EIP-1559 block, the hardfork parameter on the Common instance needs to be set to london (this is now the default hardfork):

import { Block } from '@ethereumjs/block'
import Common, { Chain, Hardfork } from '@ethereumjs/common'
const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.London })

const block = Block.fromBlockData({
  header: {
    baseFeePerGas: BigInt(10),
    gasLimit: BigInt(100),
    gasUsed: BigInt(60)
  }
}, { common })

// Base fee will increase for next block since the
// gas used is greater than half the gas limit
block.header.calcNextBaseFee().toNumber() // 11

// So for creating a block with a matching base fee in a certain
// chain context you can do:

const blockWithMatchingBaseFee = Block.fromBlockData({
  header: {
    baseFeePerGas: parentHeader.calcNextBaseFee(),
    gasLimit: BigInt(100),
    gasUsed: BigInt(60)
  }
}, { common })

EIP-1559 blocks have an extra baseFeePerGas field (default: BigInt(7)) and can encompass FeeMarketEIP1559Transaction txs (type 2) (supported by @ethereumjs/tx v3.2.0 or higher) as well as Transaction legacy txs (internal type 0) and AccessListEIP2930Transaction txs (type 1).

Consensus Types

The block library supports the creation as well as format and consensus validation of PoW ethash and PoA clique blocks.

Ethash/PoW

An Ethash/PoW block can be instantiated as follows:

import { Block } from '@ethereumjs/block'
import Common, { Chain } from '@ethereumjs/common'
const common = new Common({ chain: Chain.Mainnet })
console.log(common.consensusType()) // 'pow'
console.log(common.consensusAlgorithm()) // 'ethash'
const block = Block.fromBlockData({}, { common })

To validate that the difficulty of the block matches the canonical difficulty use block.validate(blockchain).

To calculate the difficulty when creating the block pass in the block option calcDifficultyFromHeader with the preceding (parent) BlockHeader.

Clique/PoA (since v3.1.0)

A clique block can be instantiated as follows:

import { Block } from '@ethereumjs/block'
import Common, { Chain } from '@ethereumjs/common'
const common = new Common({ chain: Chain.Goerli })
console.log(common.consensusType()) // 'poa'
console.log(common.consensusAlgorithm()) // 'clique'
const block = Block.fromBlockData({}, { common })

For clique PoA BlockHeader.validate() function validates the various Clique/PoA-specific properties (extraData checks and others, see API documentation) and BlockHeader.validateConsensus() can be used to properly validate that a Clique/PoA block has the correct signature.

For sealing a block on instantiation you can use the cliqueSigner constructor option:

const cliqueSigner = Buffer.from('PRIVATE_KEY_HEX_STRING', 'hex')
const block = Block.fromHeaderData(headerData, { cliqueSigner })

Additionally there are the following utility methods for Clique/PoA related functionality in the BlockHeader class:

BlockHeader.validateCliqueDifficulty(blockchain: Blockchain): boolean
BlockHeader.cliqueSigHash()
BlockHeader.cliqueIsEpochTransition(): boolean
BlockHeader.cliqueExtraVanity(): Buffer
BlockHeader.cliqueExtraSeal(): Buffer
BlockHeader.cliqueEpochTransitionSigners(): Address[]
BlockHeader.cliqueVerifySignature(signerList: Address[]): boolean
BlockHeader.cliqueSigner(): Address

See the API docs for detailed documentation. Note that these methods will throw if called in a non-Clique/PoA context.

Casper/PoS (since v3.5.0) (experimental)

Merge-friendly Casper/PoS blocks have been introduced along with the v3.5.0 release. Proof-of-Stake compatible execution blocks come with their own set of header field simplifications and associated validation rules. The difficulty is set to 0 since not relevant anymore, just to name an example. For a full list of changes see EIP-3675.

You can instantiate a Merge/PoS block like this:

import { Block } from '@ethereumjs/block'
import Common, { Chain, Hardfork } from '@ethereumjs/common'
const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge, })
const block = Block.fromBlockData({
  // Provide your block data here or use default values
}, { common })

Note that all Merge respectively Casper/PoS related functionality is still considered experimental.

API

Documentation

TESTING

Tests in the tests directory are partly outdated and testing is primarily done by running the BlockchainTests from within the @ethereumjs/vm package.

To avoid bloating this repository with ethereum/tests JSON files, we usually copy specific JSON files and wrap them with some metadata (source, date, commit hash). There's a helper to aid in that process and can be found at wrap-ethereum-test.sh.

EthereumJS

See our organizational documentation for an introduction to EthereumJS as well as information on current standards and best practices.

If you want to join for work or do improvements on the libraries have a look at our contribution guidelines.

LICENSE

MPL-2.0

Current Tags

6.0.0-alpha.1 ... alpha (a month ago)
4.0.0-beta.3 ... beta (2 years ago)
5.3.0 ... latest (3 months ago)
5.0.0-rc.1 ... rc (a year ago)

34 Versions

6.0.0-alpha.1 ... a month ago
5.3.0 ... 3 months ago
5.2.0 ... 8 months ago
5.1.1 ... 9 months ago
5.1.0 ... 9 months ago
5.0.1 ... a year ago
5.0.0 ... a year ago
5.0.0-rc.1 ... a year ago
4.3.0 ... a year ago
4.2.2 ... 2 years ago
4.2.1 ... 2 years ago
4.2.0 ... 2 years ago
4.1.0 ... 2 years ago
4.0.1 ... 2 years ago
4.0.0 ... 2 years ago
4.0.0-rc.1 ... 2 years ago
4.0.0-beta.3 ... 2 years ago
4.0.0-beta.2 ... 2 years ago
4.0.0-beta.1 ... 2 years ago
3.6.3 ... 2 years ago
3.6.2 ... 3 years ago
3.6.1 ... 3 years ago
3.6.0 ... 3 years ago
3.5.1 ... 3 years ago
3.5.0 ... 3 years ago
3.4.0 ... 3 years ago
3.3.0 ... 3 years ago
3.2.1 ... 4 years ago
3.2.0 ... 4 years ago
3.1.0 ... 4 years ago
3.0.0 ... 4 years ago
3.0.0-rc.1 ... 4 years ago
3.0.0-beta.2 ... 4 years ago
3.0.0-beta.1 ... 4 years ago