ethereumjs-monorepo

EthereumJS

EthereumJS package layers: execution, state, protocol, configuration, codec

EthereumJS Monorepo

Modular TypeScript libraries for Ethereum execution-layer protocol work.

Composable, spec-tested building blocks for the Ethereum execution layer: EVM execution, transactions, blocks, state, tries, and chain configuration. Use them in Node.js or the browser — tree-shakeable, Noble crypto by default, WASM-free unless you opt in.

Spec-tested execution — tracks mainnet hardforks (status ↓)
Composable primitives — mix tx, block, mpt, statemanager, and friends instead of pulling in a full client
Browser-ready — controlled dependency set; package READMEs cover bundler and KZG setup where needed

Maintained by former members of the Ethereum Foundation JavaScript team and the broader Ethereum community.

Hardfork status

Fork	Status
Osaka	Mainnet today — stable on npm
Amsterdam	In development - see status here

What do you want to do?

Goal	Start here	npm package
Run a signed tx, replay a block, or build a block	packages/vm	`@ethereumjs/vm`
Execute bytecode, custom opcodes, or precompiles	packages/evm	`@ethereumjs/evm`
Create, sign, or parse transactions	packages/tx	`@ethereumjs/tx`
Blocks, headers, withdrawals	packages/block	`@ethereumjs/block`
Persistent chain storage	packages/blockchain	`@ethereumjs/blockchain`
Merkle proofs and trie tooling	packages/mpt	`@ethereumjs/mpt`
Chain config and hardfork parameters	packages/common	`@ethereumjs/common`

flowchart TD
  start[What_are_you_building]
  start --> txRules[Tx_and_block_rules]
  start --> bytecode[Bytecode_only]
  start --> chainData[Chain_storage_or_types]

  txRules --> vmPkg["@ethereumjs/vm"]
  bytecode --> evmPkg["@ethereumjs/evm"]
  chainData --> blockPkg["@ethereumjs/block / blockchain"]

Quick start

Install the VM (includes EVM, tx, and state wiring):

npm install @ethereumjs/vm @ethereumjs/common @ethereumjs/tx @ethereumjs/util

Run a simple signed transfer against an in-memory state (adapted from packages/vm/examples/runTx.ts):

import { Common, Hardfork, Mainnet } from '@ethereumjs/common'
import { createLegacyTx } from '@ethereumjs/tx'
import {
  createAccount,
  createAddressFromPrivateKey,
  createZeroAddress,
  hexToBytes,
} from '@ethereumjs/util'
import { createVM, runTx } from '@ethereumjs/vm'

const common = new Common({ chain: Mainnet, hardfork: Hardfork.Prague })
const vm = await createVM({ common })

const senderKey = hexToBytes(`0x${'20'.repeat(32)}`)
const sender = createAddressFromPrivateKey(senderKey)
await vm.stateManager.putAccount(sender, createAccount({ nonce: 0n, balance: BigInt(1e18) }))

const tx = createLegacyTx({
  gasLimit: 21000n,
  gasPrice: 1_000_000_000n,
  value: 1n,
  to: createZeroAddress(),
}).sign(senderKey)

const res = await runTx(vm, { tx })
console.log(res.totalGasSpent) // 21000n

For bytecode-only execution use @ethereumjs/evm (examples). For blob (EIP-4844) transactions you need a separate KZG library — see KZG setup in the tx README.

Package map

Active packages (published in sync on v10; see scripts/release-npm.ts):

Codec and primitives

Package	Role	Docs
`@ethereumjs/rlp`	RLP encode/decode	README
`@ethereumjs/util`	Bytes, accounts, addresses, signatures	README

Configuration

Package	Role	Docs
`@ethereumjs/common`	Chains, hardforks, EIP parameters	README
`@ethereumjs/genesis`	Genesis state for known chains	README

Protocol types

Package	Role	Docs
`@ethereumjs/tx`	Legacy, 1559, 2930, 4844, 7702 transactions	README
`@ethereumjs/block`	Blocks, headers, withdrawals	README

State

Package	Role	Docs
`@ethereumjs/mpt`	Merkle Patricia Trie and proofs	README
`@ethereumjs/binarytree`	EIP-7864 binary tree	README
`@ethereumjs/statemanager`	Merkle, RPC, and binary-tree state backends	README

Execution

Package	Role	Docs
`@ethereumjs/evm`	EVM interpreter, opcodes, precompiles	README
`@ethereumjs/vm`	`runTx`, `runBlock`, block building	README

Chain storage

Package	Role	Docs
`@ethereumjs/blockchain`	Canonical chain storage and validation	README

Other packages

Package	Role	Notes
`@ethereumjs/e2store`	Era / Era1 / E2HS archive formats	Deprecation under consideration
`@ethereumjs/ethash`	Ethash PoW verification	Maintained for deps; not in active release round

How packages fit together

flowchart BT
  rlp --> util --> common
  common --> tx & block & mpt & genesis
  mpt --> block & statemanager
  tx --> block --> vm
  statemanager --> evm --> vm
  block --> blockchain

Full responsibility matrix, execution flow (runBlock → runTx → evm), and release notes: ARCHITECTURE.md.

Contribute

Releases: active development on master (v10). Maintenance branches and breaking-release policy: DEVELOPER.md § Releases.

Clone and build:

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

Tooling, CI, conventions, and release process: DEVELOPER.md · CONTRIBUTING.md.

Deprecated packages (no longer updated)

| Package | Role | | ------- | ---- | | [`@ethereumjs/client`](./packages/client) | Full execution client (deprecated) | | [`@ethereumjs/devp2p`](./packages/devp2p) | devp2p networking (deprecated) | | [`@ethereumjs/wallet`](./packages/wallet) | Key management helpers (deprecated) | Still on npm for migration reference; do not start new projects on these packages.

Community

The EthereumJS GitHub organization is maintained by the former Ethereum Foundation JavaScript team and contributors. Join Discord for questions and follow the Code of Conduct.

Related: Lodestar — TypeScript consensus client and SSZ tooling for the Ethereum consensus layer.

License

Most packages are MPL-2.0 licensed; see each package folder for its license file.