Skip to content

README.md

Latest commit

 

History

History
192 lines (138 loc) · 9.49 KB

README.md

File metadata and controls

192 lines (138 loc) · 9.49 KB
Raw

EthereumJS

EthereumJS package layers

EthereumJS Monorepo

Modular TypeScript libraries for Ethereum execution-layer protocol work.

Code Coverage Discord

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 — @ethereumjs/vm and @ethereumjs/evm track mainnet hardforks (Osaka today; Amsterdam in development)
  • 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.

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"]
Loading

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 npm RLP encode/decode README
@ethereumjs/util npm Bytes, accounts, addresses, signatures README

Configuration

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

Protocol types

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

State

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

Execution

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

Chain storage

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

Other packages

Package Role Notes
@ethereumjs/e2store npm Era / Era1 / E2HS archive formats Deprecation under consideration
@ethereumjs/ethash npm 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
Loading

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 Full execution client (deprecated)
@ethereumjs/devp2p devp2p networking (deprecated)
@ethereumjs/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.