int4js
SYNOPSIS
ETHEREUMJS-COMMON
Resources common to all Ethereum implementations
Succeeds the old ethereum/common library.
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.
Here are some simple usage examples:
const Common = require('ethereumjs-common')
// Instantiate with only the chain
let c = new Common('ropsten')
c.param('gasPrices', 'ecAddGas', 'byzantium') // 500
// Chain and hardfork provided
c = new Common('ropsten', 'byzantium')
c.param('pow', 'minerReward') // 3000000000000000000
// Access genesis data for Ropsten network
c.genesis().hash // 0x41941023680923e0fe4d74a34bdac8141f2540e3ae90623718e47d66d1ca4a2d
// Get bootstrap nodes for chain/network
c.bootstrapNodes() // Array with current nodesIt is encouraged to also explicitly set the supportedHardforks if the initializing library
only supports a certain range of hardforks:
let c = new Common('ropsten', null, ['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.
Hardfork Params
Active Hardforks
There are currently parameter changes by the following past and future hardfork by the library supported:
chainstarthomesteaddaotangerineWhistlespuriousDragonbyzantiumconstantinoplepetersburg(akaconstantinopleFix, apply together withconstantinople)istanbulmuirGlacier
Future Hardforks
The muirGlacier HF delaying the difficulty bomb and scheduled for January 2020
is supported by the library since v1.5.0.
Parameter Access
For hardfork-specific parameter access with the param() and paramByBlock() functions
you can use the following topics:
gasConfiggasPricesvmpowcaspersharding
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.
Note: The list of gasPrices and gas price changes on hardforks is consistent
but not complete, so there are currently gas price values missing (PRs welcome!).
Chain Params
Supported chains:
mainnetropstenrinkebykovangoerli(final configuration sincev1.1.0)- Private/custom chain parameters
The following chain-specific parameters are provided:
namechainIdnetworkIdgenesisblock header valueshardforksblock numbersbootstrapNodeslist
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:
You can pass a dictionary - conforming to the parameter format described above - with your custom values in the constructor or the
setChain()method for thechainparameter.You can base your custom chain's config in a standard one, using the
Common.forCustomChainmethod.
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 IdEthereumJS
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.