EthereumJS Monorepo

Table of Contents

• Introduction
• Active Packages
• Deprecated Packages
• Getting Started
• Branches
• Packages Relationships
• EthereumJS
• License

Introduction

This repository holds various protocol building blocks of the Ethereum blockchain execution layer. It is managed and maintained by former members of the Ethereum Foundation JavaScript team as well as the broader Ethereum community. 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 an MPT (Merkle Patricia Tree) 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.

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.

Active Packages

Below you can find a list of the active packages included in this repository.

package	npm	issues	tests	coverage
@ethereumjs/binarytree
@ethereumjs/block
@ethereumjs/blockchain
@ethereumjs/common
@ethereumjs/evm
@ethereumjs/genesis
@ethereumjs/mpt
@ethereumjs/rlp
@ethereumjs/statemanager
@ethereumjs/tx
@ethereumjs/util
@ethereumjs/vm

Deprecated Packages

The following packages are deprecated and will not be updated.

package	npm	issues	tests	coverage
@ethereumjs/client
@ethereumjs/devp2p
@ethereumjs/ethash
@ethereumjs/wallet

Getting Started

If you're new to the EthereumJS monorepo, this section will help you get up and running quickly.

Prerequisites

• Node.js (v20 or higher)
• npm (v9 or higher)
• Git

Initial Setup

1. Clone the repository and initialize submodules:

git clone https://github.com/ethereumjs/ethereumjs-monorepo.git
cd ethereumjs-monorepo
git submodule init
git submodule update

2. Install dependencies:

npm install

Development

See our Development docs for an overview on things like tooling or configuration if you want to contribute to the EthereumJS monorepo. 🙂

Branches

Overview

The following are our currently relevant main branches for active and former release series:

Branch	Release Series	Status	Description
master	v10 (new versioning scheme)	Active	Working branch
maintenance-v8	v7/v8	Maintenance	Maintenance for v8 releases (v7 also included)
maintenance-v6	v6	Maintenance	Maintenance for v6 releases

Breaking 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.

Packages Relationships

 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
   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
   rlp --> e2store
   util --> e2store
   block --> e2store
   blockchain --> e2store
   statemanager --> evm
   statemanager --> vm
   statemanager --> client

To update the diagram above edit the README file and open a new PR with the changes.

EthereumJS

The EthereumJS GitHub organization and its repositories are managed by members of the former Ethereum Foundation JavaScript team and the broader Ethereum community. If you want to join for work or carry out improvements on the libraries see the developer docs for an overview of current standards and tools and review our code of conduct.

License

Most packages are MPL-2.0 licensed, see package folder for the respective license.