@nomicfoundation/ethereumjs-common
Advanced tools
Resources common to all Ethereum implementations
@nomicfoundation/ethereumjs-common is a library that provides common Ethereum constants, parameters, and functions for various Ethereum networks. It is useful for developers working on Ethereum-based projects who need to handle different network configurations and parameters.
Network Configuration
This feature allows you to create a custom network configuration. The code sample demonstrates how to create a custom network configuration for a network with a specific networkId and chainId.
const Common = require('@nomicfoundation/ethereumjs-common').default;
const mainnetCommon = Common.forCustomChain('mainnet', {
name: 'custom-network',
networkId: 1234,
chainId: 1234,
}, 'istanbul');
console.log(mainnetCommon.chainName());Hardfork Support
This feature allows you to specify and work with different Ethereum hardforks. The code sample shows how to create a Common instance for the mainnet with the Berlin hardfork.
const Common = require('@nomicfoundation/ethereumjs-common').default;
const common = new Common({ chain: 'mainnet', hardfork: 'berlin' });
console.log(common.hardfork());Chain Parameters
This feature provides access to various chain parameters such as genesis block information. The code sample demonstrates how to retrieve the genesis block parameters for the Ropsten test network.
const Common = require('@nomicfoundation/ethereumjs-common').default;
const common = new Common({ chain: 'ropsten' });
console.log(common.genesis());web3 is a comprehensive library for interacting with the Ethereum blockchain. It provides functionalities for sending transactions, interacting with smart contracts, and more. While it offers some network configuration capabilities, it is more focused on general blockchain interactions compared to the specialized network configuration focus of @nomicfoundation/ethereumjs-common.
ethers is another popular library for interacting with the Ethereum blockchain. It provides utilities for sending transactions, interacting with smart contracts, and managing wallets. Similar to web3, it includes some network configuration features but is more broadly focused on Ethereum interactions rather than the specific network configuration and parameter management provided by @nomicfoundation/ethereumjs-common.
ethereumjs-tx is a library for creating and signing Ethereum transactions. It is part of the ethereumjs suite of libraries and focuses on transaction creation and signing. While it can be used in conjunction with @nomicfoundation/ethereumjs-common, it does not provide the same level of network configuration and parameter management.
| 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 preceding release.
To obtain the latest version, simply require the project using npm:
npm install @ethereumjs/common
import (ESM, TypeScript):
import { Chain, Common, Hardfork } from '@ethereumjs/common
require (CommonJS, Node.js):
const { Common, Chain, Hardfork } = require('@ethereumjs/common')
All parameters can be accessed through the Common class, instantiated with an object containing either the chain (e.g. 'Chain.Mainnet') or the chain together with a specific hardfork provided:
// With enums:
const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.London })
// (also possible with directly passing in strings:)
const common = new Common({ chain: 'mainnet', hardfork: 'london' })
If no hardfork is provided, the common is initialized with the default hardfork.
Current DEFAULT_HARDFORK: Hardfork.Merge
Here are some simple usage examples:
// Instantiate with the chain (and the default hardfork)
let c = new Common({ chain: Chain.Ropsten })
c.param('gasPrices', 'ecAddGas') // 500
// Chain and hardfork provided
c = new Common({ chain: Chain.Ropsten, hardfork: Hardfork.Byzantium })
c.param('pow', 'minerReward') // 3000000000000000000
// Get bootstrap nodes for chain/network
c.bootstrapNodes() // Array with current nodes
// Instantiate with an EIP activated
c = new Common({ chain: Chain.Mainnet, eips: [2537] })
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.
Generated TypeDoc API Documentation
Starting with v4 the usage of BN.js for big numbers has been removed from the library and replaced with the usage of the native JS BigInt data type (introduced in ES2020).
Please note that number-related API signatures have changed along with this version update and the minimal build target has been updated to ES2020.
The Common class is implemented as an EventEmitter and is emitting the following events
on which you can react within your code:
| Event | Description |
|---|---|
hardforkChanged | Emitted when a hardfork change occurs in the Common object |
The chain can be set in the constructor like this:
const c = new Common({ chain: Chain.Ropsten })
Supported chains:
mainnet (Chain.Mainnet)ropsten (Chain.Ropsten)rinkeby (Chain.Rinkeby)goerli (Chain.Goerli)sepolia (Chain.Sepolia) (v2.6.1+)The following chain-specific parameters are provided:
namechainIdnetworkIdconsensusType (e.g. pow or poa)consensusAlgorithm (e.g. ethash or clique)consensusConfig (depends on consensusAlgorithm, e.g. period and epoch for clique)genesis block header valueshardforks block numbersbootstrapNodes listdnsNetworks list (EIP-1459-compliant list of DNS networks for peer discovery)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.
There are two distinct APIs available for setting up custom(ized) chains.
There is a dedicated Common.custom() static constructor which allows for an easy instantiation of a Common instance with somewhat adopted chain parameters, with the main use case to adopt on instantiating with a deviating chain ID (you can use this to adopt other chain parameters as well though). Instantiating a custom common instance with its own chain ID and inheriting all other parameters from mainnet can now be as easily done as:
const common = Common.custom({ chainId: 1234 })
The custom() method also takes a string as a first input (instead of a dictionary). This can be used in combination with the CustomChain enum dict which allows for the selection of predefined supported custom chains for an easier Common setup of these supported chains:
const common = Common.custom(CustomChain.ArbitrumRinkebyTestnet)
The following custom chains are currently supported:
PolygonMainnetPolygonMumbaiArbitrumRinkebyTestnetxDaiChainOptimisticKovanOptimisticEthereumCommon instances created with this simplified custom() constructor can't be used in all usage contexts (the HF configuration is very likely not matching the actual chain) but can be useful for specific use cases, e.g. for sending a tx with @ethereumjs/tx to an L2 network (see the Tx library README for a complete usage example).
If you want to initialize a Common instance with a single custom chain which is then directly activated
you can pass a dictionary - conforming to the parameter format described above - with your custom chain
values to the constructor using the chain parameter or the setChain() method, here is some example:
import myCustomChain from './[PATH]/myCustomChain.json'
const common = new Common({ chain: myCustomChain })
A second way for custom chain initialization is to use the customChains constructor option. This
option comes with more flexibility and allows for an arbitrary number of custom chains to be initialized on
a common instance in addition to the already supported ones. It also allows for an activation-independent
initialization, so you can add your chains by adding to the customChains array and either directly
use the chain option to activate one of the custom chains passed or activate a build in chain
(e.g. mainnet) and switch to other chains - including the custom ones - by using Common.setChain().
import myCustomChain1 from './[PATH]/myCustomChain1.json'
import myCustomChain2 from './[PATH]/myCustomChain2.json'
// Add two custom chains, initial mainnet activation
const common1 = new Common({ chain: 'mainnet', customChains: [myCustomChain1, myCustomChain2] })
// Somewhat later down the road...
common1.setChain('customChain1')
// Add two custom chains, activate customChain1
const common1 = new Common({
chain: 'customChain1',
customChains: [myCustomChain1, myCustomChain2],
})
Starting with v3 custom genesis states should be passed to the Blockchain library directly.
The hardfork can be set in constructor like this:
import { Chain, Common, Hardfork } from '@ethereumjs/common'
const c = new Common({ chain: Chain.Ropsten, hardfork: Hardfork.Byzantium })
There are currently parameter changes by the following past and future hardfork by the library supported:
chainstart (Hardfork.Chainstart)homestead (Hardfork.Homestead)dao (Hardfork.Dao)tangerineWhistle (Hardfork.TangerineWhistle)spuriousDragon (Hardfork.SpuriousDragon)byzantium (Hardfork.Byzantium)constantinople (Hardfork.Constantinople)petersburg (Hardfork.Petersburg) (aka constantinopleFix, apply together with constantinople)istanbul (Hardfork.Instanbul)muirGlacier (Hardfork.MuirGlacier)berlin (Hardfork.Berlin) (since v2.2.0)london (Hardfork.London) (since v2.4.0)merge (Hardfork.Merge) (DEFAULT_HARDFORK) (since v2.5.0)The next upcoming HF Hardfork.Shanghai is currently not yet supported by this library.
For hardfork-specific parameter access with the param() and paramByBlock() functions
you can use the following topics:
gasConfiggasPricesvmpowSee 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.
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: Chain.Mainnet, eips: [2537] })
The following EIPs are currently supported:
experimental)experimental)experimental)experimental)v2.6.1+)experimental)experimental)You can use common.bootstrapNodes() function to get nodes for a specific chain/network.
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 carry out improvements on the libraries, please review our contribution guidelines first.
FAQs
Resources common to all Ethereum implementations
We found that @nomicfoundation/ethereumjs-common demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.