Security News
Cloudflare Adds Security.txt Setup Wizard
Cloudflare has launched a setup wizard allowing users to easily create and manage a security.txt file for vulnerability disclosure on their websites.
@ethereumjs/common
Advanced tools
@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.
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
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.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 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.
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.
npm install @ethereumjs/common
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:
const 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.
For an improved developer experience, there are Chain
and Hardfork
enums available:
import Common, { Chain, Hardfork } from '@ethereumjs/common'
// Chain provided by Chain enum
const c = new Common({ chain: Chain.Mainnet })
// Chain provided by Chain enum, hardfork provided by Hardfork enum
const c = new Common({ chain: Chain.Ropsten, hardfork: Hardfork.Byzantium })
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.
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: 'ropsten' })
Or optionally with the Chain
enum:
import Common, { Chain } from '@ethereumjs/common'
const c = new Common({ chain: Chain.Ropsten })
Supported chains:
mainnet
(Chain.Mainnet
)ropsten
(Chain.Ropsten
)rinkeby
(Chain.Rinkeby
)kovan
(Chain.Kovan
)goerli
(Chain.Goerli
)The following chain-specific parameters are provided:
name
chainId
networkId
consensusType
(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.
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 })
If you just want to change certain parameters on a chain configuration it can also be convenient to use
the Common.forCustomChain()
method. With this method you can base your custom chain configuration with
a standard one (so using all the values from baseChain
as the default values) and then just provide the
parameters you want to override:
const customChainParams = { name: 'custom', chainId: 123, networkId: 678 }
const customChainCommon = Common.forCustomChain('mainnet', customChainParams, 'byzantium')
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 ] })
It is also possible (v2.5.0
+) to pass in a custom genesis state file (see e.g. src/genesisStates/goerli.json
for an example on the format needed) along with the custom chain configuration:
import myCustomChain1 from '[PATH_TO_MY_CHAINS]/myCustomChain1.json'
import chain1GenesisState from '[PATH_TO_GENESIS_STATES]/chain1GenesisState.json'
const common = new Common({ chain: 'myCustomChain1', customChains: [ [ myCustomChain1, chain1GenesisState ] ]})
Accessing the genesis state can be done as follows:
const genesisState = common.genesisState()
This now also provides direct access to custom genesis states passed into Common
as described above. The old Common-separate genesisStateByName()
and genesisStateById()
functions are now deprecated
and usage should be avoided.
The hardfork
can be set in constructor like this:
const c = new Common({ chain: 'ropsten', hardfork: 'byzantium' })
Or optionally with the Hardfork
enum:
import Common, { Chain, 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
) (DEFAULT_HARDFORK
(v2.0.0
release series))muirGlacier
(Hardfork.MuirGlacier
)berlin
(Hardfork.Berlin
) (since v2.2.0
)london
(Hardfork.London
) (since v2.4.0
)merge
(Hardfork.Merge
) (since v2.5.0
, experimental
)The next upcoming HF 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
:
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.
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
)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 do improvements on the libraries have a look at our contribution guidelines.
FAQs
Resources common to all Ethereum implementations
The npm package @ethereumjs/common receives a total of 594,449 weekly downloads. As such, @ethereumjs/common popularity was classified as popular.
We found that @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
Cloudflare has launched a setup wizard allowing users to easily create and manage a security.txt file for vulnerability disclosure on their websites.
Security News
The Socket Research team breaks down a malicious npm package targeting the legitimate DOMPurify library. It uses obfuscated code to hide that it is exfiltrating browser and crypto wallet data.
Security News
ENISA’s 2024 report highlights the EU’s top cybersecurity threats, including rising DDoS attacks, ransomware, supply chain vulnerabilities, and weaponized AI.