@lodestar/era 1.36.0

package/lib/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,cAAc,EAAC,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAC,sBAAsB,EAAE,YAAY,EAAC,MAAM,yBAAyB,CAAC;AAE7E,4DAA4D;AAC5D,MAAM,UAAU,SAAS,CAAC,KAAiB,EAAE,MAAc;IACzD,OAAO,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,UAAU,CAAC,KAAiB,EAAE,MAAc;IAC1D,OAAO,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;AAC5D,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,UAAU,CAAC,KAAiB,EAAE,MAAc;IAC1D,OAAO,MAAM,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AAC3D,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,UAAU,CAAC,KAAiB,EAAE,MAAc;IAC1D,OAAO,MAAM,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AAC3D,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,UAAU,CAAC,MAAkB,EAAE,MAAc,EAAE,CAAS;IACtE,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;AACzD,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,WAAW,CAAC,MAAkB,EAAE,MAAc,EAAE,CAAS;IACvE,MAAM,CAAC,SAAS,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;AACzD,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,WAAW,CAAC,MAAkB,EAAE,MAAc,EAAE,CAAS;IACvE,MAAM,CAAC,SAAS,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;AACzD,CAAC;AAED,qCAAqC;AACrC,MAAM,UAAU,gBAAgB,CAAC,cAA0B;IACzD,MAAM,YAAY,GAAG,IAAI,sBAAsB,EAAE,CAAC;IAElD,MAAM,KAAK,GAAG,IAAI,cAAc,CAAC,cAAc,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,YAAY,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IAE9C,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;IACpE,CAAC;IAED,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAC;AAC3B,CAAC;AAED,yCAAyC;AACzC,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAgB;IACnD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;QACnG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AAChC,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@lodestar/era",
+  "description": "Era file handling module for Lodestar",
+  "license": "Apache-2.0",
+  "author": "ChainSafe Systems",
+  "homepage": "https://github.com/ChainSafe/lodestar#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ChainSafe/lodestar.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ChainSafe/lodestar/issues"
+  },
+  "version": "1.36.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "lib",
+    "!**/*.tsbuildinfo"
+  ],
+  "scripts": {
+    "clean": "rm -rf lib && rm -f *.tsbuildinfo",
+    "build": "tsc -p tsconfig.build.json",
+    "build:watch": "yarn run build --watch",
+    "build:release": "yarn clean && yarn run build",
+    "check-build": "node -e \"(async function() { await import('./lib/index.js') })()\"",
+    "check-types": "tsc",
+    "lint": "biome check src/ test/",
+    "lint:fix": "yarn run lint --write",
+    "test": "yarn test:unit",
+    "test:unit": "vitest run --project unit --project unit-minimal",
+    "check-readme": "typescript-docs-verifier"
+  },
+  "dependencies": {
+    "@chainsafe/blst": "^2.2.0",
+    "@lodestar/config": "^1.36.0",
+    "@lodestar/params": "^1.36.0",
+    "@lodestar/reqresp": "^1.36.0",
+    "@lodestar/types": "^1.36.0",
+    "uint8arraylist": "^2.4.7"
+  }
+}

package/src/e2s.ts

@@ -0,0 +1,178 @@
+import type {FileHandle} from "node:fs/promises";
+import {Slot} from "@lodestar/types";
+import {readInt48, readUint16, readUint32, writeInt48, writeUint16, writeUint32} from "./util.ts";
+
+/**
+ * Known entry types in an E2Store (.e2s) file along with their exact 2-byte codes.
+ */
+export enum EntryType {
+  Empty = 0,
+  CompressedSignedBeaconBlock = 1,
+  CompressedBeaconState = 2,
+  Version = 0x65 | (0x32 << 8), // "e2" in ASCII
+  SlotIndex = 0x69 | (0x32 << 8),
+}
+/**
+ * Logical, parsed entry from an E2Store file.
+ */
+export interface Entry {
+  type: EntryType;
+  data: Uint8Array;
+}
+
+/**
+ * Maps slots to file positions in an era file.
+ * - Block index: count = SLOTS_PER_HISTORICAL_ROOT, maps slots to blocks
+ * - State index: count = 1, points to the era state
+ * - Zero offset = empty slot (no block)
+ */
+export interface SlotIndex {
+  type: EntryType.SlotIndex;
+  /** First slot covered by this index (era * SLOTS_PER_HISTORICAL_ROOT) */
+  startSlot: Slot;
+  /** File positions where data can be found. Length varies by index type. */
+  offsets: number[];
+  /** File position where this index record starts */
+  recordStart: number;
+}
+
+/**
+ * The complete version record (8 bytes total).
+ */
+export const VERSION_RECORD_BYTES = new Uint8Array([0x65, 0x32, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]);
+
+/**
+ * E2Store header size in bytes
+ */
+export const E2STORE_HEADER_SIZE = 8;
+
+/**
+ * Helper to read entry at a specific offset from an open file handle.
+ * Reads header first to determine data length, then reads the complete entry.
+ */
+export async function readEntry(fh: FileHandle, offset: number): Promise<Entry> {
+  // Read header (8 bytes)
+  const header = new Uint8Array(E2STORE_HEADER_SIZE);
+  await fh.read(header, 0, E2STORE_HEADER_SIZE, offset);
+  const {type, length} = parseEntryHeader(header);
+
+  // Read entry payload/data
+  const data = new Uint8Array(length);
+  await fh.read(data, 0, data.length, offset + E2STORE_HEADER_SIZE);
+
+  return {type, data};
+}
+
+/**
+ * Read an e2Store entry (header + data)
+ * Header: 2 bytes type + 4 bytes length (LE) + 2 bytes reserved (must be 0)
+ */
+export function parseEntryHeader(header: Uint8Array): {type: EntryType; length: number} {
+  if (header.length < E2STORE_HEADER_SIZE) {
+    throw new Error(`Buffer too small for E2Store header: need ${E2STORE_HEADER_SIZE} bytes, got ${header.length}`);
+  }
+
+  // validate entry type from first 2 bytes
+  const typeCode = readUint16(header, 0);
+  if (!(typeCode in EntryType)) {
+    throw new Error(`Unknown E2Store entry type: 0x${typeCode.toString(16)}`);
+  }
+  const type = typeCode as EntryType;
+
+  // Parse data length from next 4 bytes (offset 2, little endian)
+  const length = readUint32(header, 2);
+
+  // Validate reserved bytes are zero (offset 6-7)
+  const reserved = readUint16(header, 6);
+  if (reserved !== 0) {
+    throw new Error(`E2Store reserved bytes must be zero, got: ${reserved}`);
+  }
+
+  return {type, length};
+}
+
+export async function readVersion(fh: FileHandle, offset: number): Promise<void> {
+  const versionHeader = new Uint8Array(E2STORE_HEADER_SIZE);
+  await fh.read(versionHeader, 0, E2STORE_HEADER_SIZE, offset);
+  if (Buffer.compare(versionHeader, VERSION_RECORD_BYTES) !== 0) {
+    throw new Error("Invalid E2Store version record");
+  }
+}
+
+/**
+ * Read a SlotIndex from a file handle.
+ */
+export async function readSlotIndex(fh: FileHandle, offset: number): Promise<SlotIndex> {
+  const recordEnd = offset;
+  const countBuffer = new Uint8Array(8);
+  await fh.read(countBuffer, 0, 8, recordEnd - 8);
+  const count = readInt48(countBuffer, 0);
+
+  const recordStart = recordEnd - (8 * count + 24);
+
+  // Validate index position is within file bounds
+  if (recordStart < 0) {
+    throw new Error(`SlotIndex position ${recordStart} is invalid - file too small for count=${count}`);
+  }
+
+  // Read and validate the slot index entry
+  const entry = await readEntry(fh, recordStart);
+  if (entry.type !== EntryType.SlotIndex) {
+    throw new Error(`Expected SlotIndex entry, got ${entry.type}`);
+  }
+
+  // Size: startSlot(8) + offsets(count*8) + count(8) = count*8 + 16
+  const expectedSize = 8 * count + 16;
+  if (entry.data.length !== expectedSize) {
+    throw new Error(`SlotIndex payload size must be exactly ${expectedSize} bytes, got ${entry.data.length}`);
+  }
+
+  // Parse start slot from payload
+  const startSlot = readInt48(entry.data, 0);
+
+  const offsets: number[] = [];
+  for (let i = 0; i < count; i++) {
+    offsets.push(readInt48(entry.data, 8 * i + 8));
+  }
+
+  return {
+    type: EntryType.SlotIndex,
+    startSlot,
+    offsets,
+    recordStart,
+  };
+}
+
+/**
+ * Write a single E2Store TLV entry (header + payload)
+ * Header layout: type[2] | length u32 LE | reserved u16(=0)
+ */
+export async function writeEntry(fh: FileHandle, offset: number, type: EntryType, payload: Uint8Array): Promise<void> {
+  const header = new Uint8Array(E2STORE_HEADER_SIZE);
+  writeUint16(header, 0, type); // type (2 bytes)
+  writeUint32(header, 2, payload.length); // length (4 bytes)
+  // reserved bytes (6-7) remain 0
+  await fh.writev([header, payload], offset);
+}
+
+export async function writeVersion(fh: FileHandle, offset: number): Promise<void> {
+  await fh.write(VERSION_RECORD_BYTES, 0, VERSION_RECORD_BYTES.length, offset);
+}
+
+export function serializeSlotIndex(slotIndex: SlotIndex): Uint8Array {
+  const count = slotIndex.offsets.length;
+  const payload = new Uint8Array(count * 8 + 16);
+
+  // startSlot
+  writeInt48(payload, 0, slotIndex.startSlot);
+
+  // offsets
+  let off = 8;
+  for (let i = 0; i < count; i++, off += 8) {
+    writeInt48(payload, off, slotIndex.offsets[i]);
+  }
+
+  // trailing count
+  writeInt48(payload, 8 + count * 8, count);
+  return payload;
+}

package/src/era/index.ts

@@ -0,0 +1,3 @@
+export * from "./reader.js";
+export * from "./util.js";
+export * from "./writer.js";

package/src/era/reader.ts

@@ -0,0 +1,196 @@
+import {type FileHandle, open} from "node:fs/promises";
+import {basename} from "node:path";
+import {PublicKey, Signature, verify} from "@chainsafe/blst";
+import {ChainForkConfig, createCachedGenesis} from "@lodestar/config";
+import {DOMAIN_BEACON_PROPOSER, SLOTS_PER_HISTORICAL_ROOT} from "@lodestar/params";
+import {BeaconState, SignedBeaconBlock, Slot, ssz} from "@lodestar/types";
+import {E2STORE_HEADER_SIZE, EntryType, readEntry, readVersion} from "../e2s.ts";
+import {snappyUncompress} from "../util.ts";
+import {
+  EraIndices,
+  computeEraNumberFromBlockSlot,
+  parseEraName,
+  readAllEraIndices,
+  readSlotFromBeaconStateBytes,
+} from "./util.ts";
+
+/**
+ * EraReader is responsible for reading and validating ERA files.
+ *
+ * See https://github.com/eth-clients/e2store-format-specs/blob/main/formats/era.md
+ */
+export class EraReader {
+  readonly config: ChainForkConfig;
+  /** The underlying file handle */
+  readonly fh: FileHandle;
+  /** The era number retrieved from the file name */
+  readonly eraNumber: number;
+  /** The short historical root retrieved from the file name */
+  readonly shortHistoricalRoot: string;
+  /** An array of state and block indices, one per group */
+  readonly groups: EraIndices[];
+
+  constructor(
+    config: ChainForkConfig,
+    fh: FileHandle,
+    eraNumber: number,
+    shortHistoricalRoot: string,
+    indices: EraIndices[]
+  ) {
+    this.config = config;
+    this.fh = fh;
+    this.eraNumber = eraNumber;
+    this.shortHistoricalRoot = shortHistoricalRoot;
+    this.groups = indices;
+  }
+
+  static async open(config: ChainForkConfig, path: string): Promise<EraReader> {
+    const fh = await open(path, "r");
+    const name = basename(path);
+    const {configName, eraNumber, shortHistoricalRoot} = parseEraName(name);
+    if (config.CONFIG_NAME !== configName) {
+      throw new Error(`Config name mismatch: expected ${config.CONFIG_NAME}, got ${configName}`);
+    }
+    const indices = await readAllEraIndices(fh);
+    return new EraReader(config, fh, eraNumber, shortHistoricalRoot, indices);
+  }
+
+  /**
+   * Close the underlying file descriptor
+   *
+   * No further actions can be taken after this operation
+   */
+  async close(): Promise<void> {
+    await this.fh.close();
+  }
+
+  async readCompressedState(eraNumber?: number): Promise<Uint8Array> {
+    eraNumber = eraNumber ?? this.eraNumber;
+    const index = this.groups.at(eraNumber - this.eraNumber);
+    if (!index) {
+      throw new Error(`No index found for era number ${eraNumber}`);
+    }
+    const entry = await readEntry(this.fh, index.stateIndex.recordStart + index.stateIndex.offsets[0]);
+
+    if (entry.type !== EntryType.CompressedBeaconState) {
+      throw new Error(`Expected CompressedBeaconState, got ${entry.type}`);
+    }
+
+    return entry.data;
+  }
+
+  async readSerializedState(eraNumber?: number): Promise<Uint8Array> {
+    const compressed = await this.readCompressedState(eraNumber);
+    return snappyUncompress(compressed);
+  }
+
+  async readState(eraNumber?: number): Promise<BeaconState> {
+    const serialized = await this.readSerializedState(eraNumber);
+    const stateSlot = readSlotFromBeaconStateBytes(serialized);
+    return this.config.getForkTypes(stateSlot).BeaconState.deserialize(serialized);
+  }
+
+  async readCompressedBlock(slot: Slot): Promise<Uint8Array | null> {
+    const slotEra = computeEraNumberFromBlockSlot(slot);
+    const index = this.groups.at(slotEra - this.eraNumber);
+    if (!index) {
+      throw new Error(`Slot ${slot} is out of range`);
+    }
+    if (!index.blocksIndex) {
+      throw new Error(`No block index found for era number ${slotEra}`);
+    }
+    // Calculate offset within the index
+    const indexOffset = slot - index.blocksIndex.startSlot;
+    const offset = index.blocksIndex.recordStart + index.blocksIndex.offsets[indexOffset];
+    if (offset === 0) {
+      return null; // Empty slot
+    }
+
+    const entry = await readEntry(this.fh, offset);
+    if (entry.type !== EntryType.CompressedSignedBeaconBlock) {
+      throw new Error(`Expected CompressedSignedBeaconBlock, got ${EntryType[entry.type] ?? "unknown"}`);
+    }
+    return entry.data;
+  }
+
+  async readSerializedBlock(slot: Slot): Promise<Uint8Array | null> {
+    const compressed = await this.readCompressedBlock(slot);
+    if (compressed === null) return null;
+    return snappyUncompress(compressed);
+  }
+
+  async readBlock(slot: Slot): Promise<SignedBeaconBlock | null> {
+    const serialized = await this.readSerializedBlock(slot);
+    if (serialized === null) return null;
+    return this.config.getForkTypes(slot).SignedBeaconBlock.deserialize(serialized);
+  }
+
+  /**
+   * Validate the era file.
+   * - e2s format correctness
+   * - era range correctness
+   * - network correctness for state and blocks
+   * - block root and signature matches
+   */
+  async validate(): Promise<void> {
+    for (let groupIndex = 0; groupIndex < this.groups.length; groupIndex++) {
+      const eraNumber = this.eraNumber + groupIndex;
+      const index = this.groups[groupIndex];
+
+      // validate version entry
+      const start = index.blocksIndex
+        ? index.blocksIndex.recordStart + index.blocksIndex.offsets[0] - E2STORE_HEADER_SIZE
+        : index.stateIndex.recordStart + index.stateIndex.offsets[0] - E2STORE_HEADER_SIZE;
+      await readVersion(this.fh, start);
+
+      // validate state
+      // the state is loadable and consistent with the given runtime configuration
+      const state = await this.readState(eraNumber);
+      const cachedGenesis = createCachedGenesis(this.config, state.genesisValidatorsRoot);
+
+      if (eraNumber === 0 && index.blocksIndex) {
+        throw new Error("Genesis era (era 0) should not have blocks index");
+      }
+      if (eraNumber !== 0) {
+        if (!index.blocksIndex) {
+          throw new Error(`Era ${eraNumber} is missing blocks index`);
+        }
+
+        // validate blocks
+        for (
+          let slot = index.blocksIndex.startSlot;
+          slot < index.blocksIndex.startSlot + index.blocksIndex.offsets.length;
+          slot++
+        ) {
+          const block = await this.readBlock(slot);
+          if (block === null) {
+            if (slot === index.blocksIndex.startSlot) continue; // first slot in the era can't be easily validated
+            if (
+              Buffer.compare(
+                state.blockRoots[(slot - 1) % SLOTS_PER_HISTORICAL_ROOT],
+                state.blockRoots[slot % SLOTS_PER_HISTORICAL_ROOT]
+              ) !== 0
+            ) {
+              throw new Error(`Block root mismatch at slot ${slot} for empty slot`);
+            }
+            continue;
+          }
+
+          const blockRoot = this.config.getForkTypes(slot).BeaconBlock.hashTreeRoot(block.message);
+          if (Buffer.compare(blockRoot, state.blockRoots[slot % SLOTS_PER_HISTORICAL_ROOT]) !== 0) {
+            throw new Error(`Block root mismatch at slot ${slot}`);
+          }
+          const msg = ssz.phase0.SigningData.hashTreeRoot({
+            objectRoot: blockRoot,
+            domain: cachedGenesis.getDomain(slot, DOMAIN_BEACON_PROPOSER),
+          });
+          const pk = PublicKey.fromBytes(state.validators[block.message.proposerIndex].pubkey);
+          const sig = Signature.fromBytes(block.signature);
+          if (!verify(msg, pk, sig, true, true)) {
+            throw new Error(`Block signature verification failed at slot ${slot}`);
+          }
+        }
+      }
+    }
+  }
+}

package/src/era/util.ts

@@ -0,0 +1,134 @@
+import type {FileHandle} from "node:fs/promises";
+import {ChainForkConfig} from "@lodestar/config";
+import {SLOTS_PER_HISTORICAL_ROOT, isForkPostCapella} from "@lodestar/params";
+import {BeaconState, Slot, capella, ssz} from "@lodestar/types";
+import {E2STORE_HEADER_SIZE, SlotIndex, readSlotIndex} from "../e2s.ts";
+import {readUint48} from "../util.ts";
+
+/**
+ * Parsed components of an .era file name.
+ * Format: <config-name>-<era-number>-<short-historical-root>.era
+ */
+export interface EraFileName {
+  /** CONFIG_NAME field of runtime config (mainnet, sepolia, holesky, etc.) */
+  configName: string;
+  /** Number of the first era stored in file, 5-digit zero-padded (00000, 00001, etc.) */
+  eraNumber: number;
+  /** First 4 bytes of last historical root, lower-case hex-encoded (8 chars) */
+  shortHistoricalRoot: string;
+}
+
+export interface EraIndices {
+  stateIndex: SlotIndex;
+  blocksIndex?: SlotIndex;
+}
+
+/** Return true if `slot` is within the era range */
+export function isSlotInRange(slot: Slot, eraNumber: number): boolean {
+  return computeEraNumberFromBlockSlot(slot) === eraNumber;
+}
+
+export function isValidEraStateSlot(slot: Slot, eraNumber: number): boolean {
+  return slot % SLOTS_PER_HISTORICAL_ROOT === 0 && slot / SLOTS_PER_HISTORICAL_ROOT === eraNumber;
+}
+
+export function computeEraNumberFromBlockSlot(slot: Slot): number {
+  return Math.floor(slot / SLOTS_PER_HISTORICAL_ROOT) + 1;
+}
+
+export function computeStartBlockSlotFromEraNumber(eraNumber: number): Slot {
+  if (eraNumber === 0) {
+    throw new Error("Genesis era (era 0) does not contain blocks");
+  }
+  return (eraNumber - 1) * SLOTS_PER_HISTORICAL_ROOT;
+}
+
+/**
+ * Parse era filename.
+ *
+ * Format: `<config-name>-<era-number>-<short-historical-root>.era`
+ */
+export function parseEraName(filename: string): {configName: string; eraNumber: number; shortHistoricalRoot: string} {
+  const match = filename.match(/^(.*)-(\d{5})-([0-9a-f]{8})\.era$/);
+  if (!match) {
+    throw new Error(`Invalid era filename format: ${filename}`);
+  }
+  return {
+    configName: match[1],
+    eraNumber: parseInt(match[2], 10),
+    shortHistoricalRoot: match[3],
+  };
+}
+
+/**
+ * Read all indices from an era file.
+ */
+export async function readAllEraIndices(fh: FileHandle): Promise<EraIndices[]> {
+  let end = (await fh.stat()).size;
+
+  const indices: EraIndices[] = [];
+  while (end > E2STORE_HEADER_SIZE) {
+    const index = await readEraIndexes(fh, end);
+    indices.push(index);
+    end = index.blocksIndex
+      ? index.blocksIndex.recordStart + index.blocksIndex.offsets[0] - E2STORE_HEADER_SIZE
+      : index.stateIndex.recordStart + index.stateIndex.offsets[0] - E2STORE_HEADER_SIZE;
+  }
+  return indices;
+}
+
+/**
+ * Read state and block SlotIndex entries from an era file and validate alignment.
+ */
+export async function readEraIndexes(fh: FileHandle, end: number): Promise<EraIndices> {
+  const stateIndex = await readSlotIndex(fh, end);
+  if (stateIndex.offsets.length !== 1) {
+    throw new Error(`State SlotIndex must have exactly one offset, got ${stateIndex.offsets.length}`);
+  }
+
+  // Read block index if not genesis era (era 0)
+  let blocksIndex: SlotIndex | undefined;
+  if (stateIndex.startSlot > 0) {
+    blocksIndex = await readSlotIndex(fh, stateIndex.recordStart);
+    if (blocksIndex.offsets.length !== SLOTS_PER_HISTORICAL_ROOT) {
+      throw new Error(
+        `Block SlotIndex must have exactly ${SLOTS_PER_HISTORICAL_ROOT} offsets, got ${blocksIndex.offsets.length}`
+      );
+    }
+
+    // Validate block and state indices are properly aligned
+    const expectedBlockStartSlot = stateIndex.startSlot - SLOTS_PER_HISTORICAL_ROOT;
+    if (blocksIndex.startSlot !== expectedBlockStartSlot) {
+      throw new Error(
+        `Block index alignment error: expected startSlot=${expectedBlockStartSlot}, ` +
+          `got startSlot=${blocksIndex.startSlot} (should be exactly one era before state)`
+      );
+    }
+  }
+
+  return {stateIndex, blocksIndex};
+}
+
+export function readSlotFromBeaconStateBytes(beaconStateBytes: Uint8Array): Slot {
+  // not technically a Uint48, but for practical purposes fits within 6 bytes
+  return readUint48(
+    beaconStateBytes,
+    // slot is at offset 40: 8 (genesisTime) + 32 (genesisValidatorsRoot)
+    40
+  );
+}
+
+export function getShortHistoricalRoot(config: ChainForkConfig, state: BeaconState): string {
+  return Buffer.from(
+    state.slot === 0
+      ? state.genesisValidatorsRoot
+      : // Post-Capella, historical_roots is replaced by historical_summaries
+        isForkPostCapella(config.getForkName(state.slot))
+        ? ssz.capella.HistoricalSummary.hashTreeRoot(
+            (state as capella.BeaconState).historicalSummaries.at(-1) as capella.BeaconState["historicalSummaries"][0]
+          )
+        : (state.historicalRoots.at(-1) as Uint8Array)
+  )
+    .subarray(0, 4)
+    .toString("hex");
+}