This repository holds various protocol building blocks of the Ethereum blockchain execution layer and is managed by the Ethereum Foundation JavaScript team. There is a TypeScript implementation of the Ethereum Virtual Machine (EVM) ready to be used in Node.js or a browser environment, implementations of core structural blockchain building blocks like an Ethereum Tx, Block or Blockchain as well as a MPT (Merkle Patricia Tree) and devp2p (execution networking layer) implementation.
All libraries are bound together by the core Common library keeping track of chain specifics and hardfork changes. They are complemented by helper packages like RLP for data encoding/decoding or Util, providing helper functionalities like (byte) conversion, signatures, types and others.
Finally, the EthereumJS Execution Client (EthereumJS) has been in active development for some time now. It already serves a variety of purposes like testing, research (e.g. EIPs) and developer tooling to engage with the protocol.
Also to note: on the Ethereum Consensus side, the ChainSafe Lodestar repository complements this repository with an Ethereum Consensus Client implementation as well as various protocol implementations (like an SSZ library) developed in the context of Ethereum Consensus layer evolution.
Below you can find a list of the packages included in this repository.
If you're new to the EthereumJS monorepo, this section will help you get up and running quickly.
- Node.js (v18 or higher)
- npm (v8 or higher)
- Git
- Clone the repository and initialize submodules:
git clone https://github.com/ethereumjs/ethereumjs-monorepo.git
cd ethereumjs-monorepo
git submodule init
git submodule update- Install dependencies:
npm install- Build all packages:
npm run build --workspacesThe monorepo uses npm workspaces to link local packages together, making development easier.
- Clean the workspace:
npm run clean- Removes build artifacts and node_modules - Lint code:
npm run lint --workspaces- Check code style with ESLint v9 and Biome - Fix linting issues:
npm run lint:fix --workspaces- Automatically fix style issues - Build documentation:
npm run docs:build --workspaces- Generate documentation for all packages
To focus on a single package (e.g., VM):
- Navigate to the package directory:
cd packages/vm - Run tests:
npm test - Run a specific test:
npx vitest test/path/to/test.spec.ts - Build just that package:
npm run build --workspace=@ethereumjs/vm
All packages include a typescript entry in the exports map that allows direct use of TypeScript sources without recompilation:
- Run tests with TypeScript sources:
npx vitest --config ../../config/vitest.config.mts test/myTest.spec.ts - Run TypeScript scripts:
tsx --conditions=typescript myScript.ts - Set environment variable for bash scripts:
NODE_OPTIONS='--conditions=typescript'
We use vitest with playwright to run browser tests. When running browser tests with npm run test:browser, ensure you have a version of the Chromium browser installed. If not, you can run npx playwright install --with-deps to install a supported version.
To test changes locally before publishing, use npm link:
- Build the package you want to test:
cd packages/vm # Or another package
npm run build- Link the package globally:
npm link- In your test project, link to the local package:
cd path/to/your/project
npm link @ethereumjs/vm # Use the appropriate package name- When you're done, unlink the package:
# In your test project
npm unlink @ethereumjs/vm
# In the package directory
npm unlinkWhen making changes to the linked package, rebuild it for the changes to be reflected in your test project.
Windows users might encounter errors with script paths. To fix, configure Git bash as the script shell:
npm config set script-shell "C:\\Program Files (x86)\\git\\bin\\bash.exe"To reset this setting:
npm config delete script-shellThe config folder gives an overview on shared configuration and scripts between packages.
You can find more detailed information on the configuration of different tooling and language parts (TypeScript, linting, testing,...) in the specific Configuration Guide.
The following are our currently active branches:
| Branch | Release Series | Status | Â Description |
|---|---|---|---|
| master | Upcoming (Spring 2025) | Develop |
Breaking release work |
| maintenance-v8 | v7/v8 | Maintenance |
Maintenance for v8 releases (v7 also included) |
| maintenance-v6 | v6 | Maintenance |
Maintenance for v6 releases |
Breaking releases are mostly done in sync for all libraries (latest exceptions: VM v8, EVM v3). Starting with the spring 2025 release series, we have aligned all package versions to have the same major version number. This makes it easier to clearly identify package versions compatible with each other as well as reason about functionality or bugs for a certain release series.
Old release cycles up to the VM v7/v8 version were named after the @ethereumjs/vm version. In most cases PRs should be opened towards the current working branch. If there is no current working branch, please ask! 🙂
To inspect code related to a specific package version, refer to the tags.
graph TD
vm{vm}
client{client}
ethash --> blockchain
ethash --> client
devp2p --> client
block --> client
block --> blockchain
block --> ethash
block --> vm
blockchain --> client
mpt --> client
mpt --> vm
mpt --> blockchain
mpt --> block
mpt --> statemanager
verkle --> vm
verkle --> evm
verkle --> statemanager
binarytree --> vm
binarytree --> statemanager
util --> common
common --> block
common --> statemanager
common --> tx
common --> blockchain
common --> vm
common --> evm
common --> client
common --> devp2p
common --> genesis
evm --> vm
evm --> client
genesis --> client
genesis --> statemanager
genesis --> mpt
tx --> block
tx --> vm
tx --> client
vm --> client
rlp --> util
statemanager --> evm
statemanager --> vm
statemanager --> client
To update the diagram above edit the README file and open a new PR with the changes.
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.
Most packages are MPL-2.0 licensed, see package folder for the respective license.