@ethereumjs/common

What is @ethereumjs/common?

@ethereumjs/common is a JavaScript library that provides common Ethereum constants, parameters, and functions. It is used to define and manage chain and hardfork parameters, making it easier to work with different Ethereum networks and their respective upgrades.

What are @ethereumjs/common's main functionalities?

Chain and Hardfork Parameters

This feature allows you to define and manage chain and hardfork parameters. The code sample demonstrates how to create a Common instance for the Ethereum mainnet with the 'istanbul' hardfork.

const Common = require('@ethereumjs/common').default;
const mainnetCommon = new Common({ chain: 'mainnet', hardfork: 'istanbul' });
console.log(mainnetCommon.chainName()); // 'mainnet'
console.log(mainnetCommon.hardfork()); // 'istanbul'

Custom Chains

This feature allows you to define custom chain parameters. The code sample demonstrates how to create a Common instance for a custom chain with specific chain and network IDs.

const Common = require('@ethereumjs/common').default;
const customChainParams = { name: 'custom', chainId: 1234, networkId: 1234 };
const customCommon = Common.forCustomChain('mainnet', customChainParams, 'istanbul');
console.log(customCommon.chainId()); // 1234

EIP Activation

This feature allows you to check if a specific Ethereum Improvement Proposal (EIP) is activated for a given hardfork. The code sample demonstrates how to check if EIP-1559 is activated for the 'berlin' hardfork.

const Common = require('@ethereumjs/common').default;
const common = new Common({ chain: 'mainnet', hardfork: 'berlin' });
console.log(common.isActivatedEIP(1559)); // true or false depending on the EIP and hardfork

Other packages similar to @ethereumjs/common

web3

web3.js is a collection of libraries that allow you to interact with a local or remote Ethereum node using HTTP, IPC, or WebSocket. While it provides broader functionality for interacting with the Ethereum blockchain, it does not focus specifically on chain and hardfork parameters like @ethereumjs/common.

ethers

ethers.js is a library for interacting with the Ethereum blockchain and its ecosystem. It provides utilities for signing transactions, interacting with smart contracts, and more. Similar to web3.js, it offers a broader range of functionalities but does not specialize in chain and hardfork parameters.

ethjs

ethjs is a highly modular, lightweight library for interacting with the Ethereum blockchain. It provides basic functionalities for sending transactions, interacting with contracts, and more. However, it does not offer the same level of detail for chain and hardfork parameters as @ethereumjs/common.

README

@ethereumjs/common

Resources common to all EthereumJS implementations.

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

INSTALL

npm install @ethereumjs/common

USAGE

All parameters can be accessed through the Common class which can be required through the main package and instantiated either with just the chain (e.g. 'mainnet') or the chain together with a specific hardfork provided.

If no hardfork is provided the common is initialized with the default hardfork.

Current DEFAULT_HARDFORK: istanbul

Here are some simple usage examples:

import Common from '@ethereumjs/common'

// Instantiate with the chain (and the default hardfork)
const c = new Common({ chain: 'ropsten' })
c.param('gasPrices', 'ecAddGas') // 500

// Chain and hardfork provided
c = new Common({ chain: 'ropsten', hardfork: 'byzantium' })
c.param('pow', 'minerReward') // 3000000000000000000

// Instantiate with an EIP activated
const c = new Common({ chain: 'mainnet', eips: [2537] })

// Access genesis data for Ropsten network
c.genesis().hash // 0x41941023680923e0fe4d74a34bdac8141f2540e3ae90623718e47d66d1ca4a2d

// Get bootstrap nodes for chain/network
c.bootstrapNodes() // Array with current nodes

If the initializing library only supports a certain range of hardforks you can use the supportedHardforks option to restrict hardfork access on the Common instance:

let c = new Common({
  chain: 'ropsten',
  supportedHardforks: ['byzantium', 'constantinople', 'petersburg'],
})

This will e.g. throw an error when a param is requested for an unsupported hardfork and like this prevents unpredicted behaviour.

API

See the API documentation for a full list of functions for accessing specific chain and depending hardfork parameters. There are also additional helper functions like paramByBlock (topic, name, blockNumber) or hardforkIsActiveOnBlock (hardfork, blockNumber) to ease blockNumber based access to parameters.

• API Docs

SETUP

Chains

The chain can be set in the constructor like this:

const c = new Common({ chain: 'ropsten' })

Supported chains:

• mainnet
• ropsten
• rinkeby
• kovan
• goerli
• Private/custom chain parameters

The following chain-specific parameters are provided:

• name
• chainId
• networkId
• consensusType (e.g. pow or poa)
• consensusAlgorithm (e.g. ethash or clique)
• genesis block header values
• hardforks block numbers
• bootstrapNodes list

To get an overview of the different parameters have a look at one of the chain-specifc files like mainnet.json in the chains directory, or to the Chain type in ./src/types.ts.

Working with private/custom chains

There are two ways to set up a common instance with parameters for a private/custom chain:

1. You can pass a dictionary - conforming to the parameter format described above - with your custom values in the constructor or the setChain() method for the chain parameter.

2. You can base your custom chain's config in a standard one, using the Common.forCustomChain method.

Hardforks

The hardfork can be set in constructor like this:

const c = new Common({ chain: 'ropsten', hardfork: 'byzantium' })

Active Hardforks

There are currently parameter changes by the following past and future hardfork by the library supported:

• chainstart
• homestead
• dao
• tangerineWhistle
• spuriousDragon
• byzantium
• constantinople
• petersburg (aka constantinopleFix, apply together with constantinople)
• istanbul (DEFAULT_HARDFORK (v2.0.0 release series))
• muirGlacier (since v1.5.0)

Future Hardforks

General support for the berlin hardfork has been added along v2.0.0, specification of the hardfork regarding EIPs included was not finalized upon release date.

Currently supported berlin EIPs:

• EIP-2315

Parameter Access

For hardfork-specific parameter access with the param() and paramByBlock() functions you can use the following topics:

• gasConfig
• gasPrices
• vm
• pow

See one of the hardfork files like byzantium.json in the hardforks directory for an overview. For consistency, the chain start (chainstart) is considered an own hardfork.

The hardfork-specific json files only contain the deltas from chainstart and shouldn't be accessed directly until you have a specific reason for it.

EIPs

Starting with the v2.0.0 release of the library, EIPs are now native citizens within the library and can be activated like this:

const c = new Common({ chain: 'mainnet', eips: [2537] })

The following EIPs are currently supported:

• EIP-2537: BLS precompiles
• EIP-2929: gas cost increases for state access opcodes

Bootstrap Nodes

There is no separate config file for bootstrap nodes like in the old ethereum-common library. Instead use the common.bootstrapNodes() function to get nodes for a specific chain/network.

Genesis States

Network-specific genesis files are located in the genesisStates folder.

Due to the large file sizes genesis states are not directly included in the index.js file but have to be accessed directly, e.g.:

const mainnetGenesisState = require('@ethereumjs/common/dist/genesisStates/mainnet')

Or by accessing dynamically:

const genesisStates = require('@ethereumjs/common/dist/genesisStates')
const mainnetGenesisState = genesisStates.genesisStateByName('mainnet')
const mainnetGenesisState = genesisStates.genesisStateById(1) // alternative via network Id

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

MIT