@ethereumjs/e2store NPM

@ethereumjs/e2store `v10`

A collection of utility functions for Ethereum data storage formats.

@ethereumjs/e2store provides utilities for working with Ethereum data storage formats, including E2HS, Era1, and Era files. These formats are commonly used for storing historical blockchain data, beacon states, and block data in an efficient, provable, and standardized way.

@ethereumjs/e2store v10

Installation

To obtain the latest version, simply require the project using npm:

npm install @ethereumjs/e2store

Usage

All helpers are re-exported from the root level and deep imports are not necessary. So an import can be done like this:

import { formatEntry } from "@ethereumjs/e2store"

E2HS

E2HS is a format for storing historical blockchain data along with proofs. It provides efficient access to block headers, bodies, and receipts, and can be used to bootstrap a Portal History Network DB.

Format E2HS

import { formatE2HS } from "@ethereumjs/e2store"

// Format data into E2HS format
// data is an array of block tuple data and an epoch index
const e2hs = await formatE2HS(data)

Read Tuples from E2HS

import { readTuplesFromE2HS, parseEH2SBlockTuple } from "@ethereumjs/e2store"

// Read all tuples from an E2HS file
const tuples = await readTuplesFromE2HS(filePath)
for await (const tuple of tuples) {
  const { headerWithProof, body, receipts } = parseEH2SBlockTuple(tuple)
  console.log(headerWithProof)
  console.log(body)
  console.log(receipts)
}

Read E2HS Tuple at Index

import { readE2HSTupleAtIndex, parseEH2SBlockTuple } from "@ethereumjs/e2store"

// Read a specific tuple by index
const tuple = await readE2HSTupleAtIndex(filePath, index)
const { headerWithProof, body, receipts } = parseEH2SBlockTuple(tuple)
console.log(headerWithProof)
console.log(body)
console.log(receipts)

Era1

Era1 files store historical data in epochs of 8192 blocks, making it efficient to access large ranges of historical data. Era1 block tuples contain a header, body, receipts, and total difficulty. The data can be verified by reconstructing the epoch accumulator, and validating again the accumulator root, also contained in the era1 file.

Export History as Era1

Export history from an EthereumJS client DB in epochs of 8192 blocks as Era1 files:

import { exportEpochAsEra1 } from "@ethereumjs/e2store"

const dataDir = PATH_TO_ETHEREUMJS_CLIENT_DB
const epoch = 0

// Generates ${dataDir}/era1/epoch-0.era1
await exportEpochAsEra1(epoch, dataDir)

Read Era1 file

readERA1 returns an async iterator of block tuples (header + body + receipts + totalDifficulty):

import {
  readBinaryFile,
  validateERA1,
  readERA1,
  parseBlockTuple,
  blockFromTuple,
  getHeaderRecords,
  EpochAccumulator,
} from "@ethereumjs/e2store"

const era1File = readBinaryFile(PATH_TO_ERA1_FILE)

// Validate era1 file
// Rebuilds epoch accumulator and validates the accumulator root
const isValid = validateERA1(era1File)
if (!isValid) {
  throw new Error('Invalid Era1 file')
}

// Read blocks from era1 file
const blocks = readERA1(era1File)

for await (const blockTuple of blocks) {
  const { header, body, receipts } = await parseBlockTuple(blockTuple)
  const block = blockFromTuple({ header, body })
  console.log(`Block number: ${block.header.number}`)
}

// Reconstruct epoch accumulator
const headerRecords = await getHeaderRecords(era1File)
const epochAccumulator = EpochAccumulator.encode(headerRecords)
const epochAccumulatorRoot = EpochAccumulator.merkleRoot(headerRecords)

Era

Era files are used to store beacon chain data, including beacon states and blocks.

Read Era file

import { readBeaconState, readBlocksFromEra } from "@ethereumjs/e2store"

const eraFile = readBinaryFile(PATH_TO_ERA_FILE)

// Extract BeaconState
const state = await readBeaconState(eraFile)
console.log(`Current slot: ${state.slot}`)

// Read Beacon Blocks from era file
let count = 0
for await (const block of readBlocksFromEra(eraFile)) {
  console.log(`Block slot: ${block.message.slot}`)
  count++
  if (count > 10) break
}

Common Use Cases

Historical Data Access: Use E2HS and Era1 formats to efficiently access historical blockchain data
Beacon Chain Analysis: Read and analyze beacon chain states and blocks using Era files
Data Export: Export historical data in standardized formats for analysis or archival
Portal History Network: Bootstrap a Portal History Network DB using E2HS
Execution Client Sync: Sync an execution client without devp2p using Era1 or E2HS files

EthereumJS

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.