From 676ad5dbba5d03abbc83f88ea92cba5403fbd77b Mon Sep 17 00:00:00 2001
From: dapplion <35266934+dapplion@users.noreply.github.com>
Date: Sun, 8 Mar 2026 19:45:34 -0500
Subject: [PATCH] Add module-level documentation to ERA consumer and producer

---
 beacon_node/beacon_chain/src/era/consumer.rs | 9 +++++++++
 beacon_node/beacon_chain/src/era/producer.rs | 9 +++++++++
 2 files changed, 18 insertions(+)

diff --git a/beacon_node/beacon_chain/src/era/consumer.rs b/beacon_node/beacon_chain/src/era/consumer.rs
index a4f8b7f296..2674905405 100644
--- a/beacon_node/beacon_chain/src/era/consumer.rs
+++ b/beacon_node/beacon_chain/src/era/consumer.rs
@@ -1,3 +1,12 @@
+//! Import ERA files into a Lighthouse database.
+//!
+//! `EraFileDir` reads a directory of ERA files and imports them sequentially into the cold DB.
+//! Each ERA file is verified against `historical_roots` / `historical_summaries` from the
+//! highest-numbered ERA state, ensuring block and state integrity without trusting the files.
+//!
+//! Block roots are cross-checked against the ERA boundary state's `block_roots` vector.
+//! Block signatures are NOT verified — ERA files are trusted at that level.
+
 use bls::FixedBytesExtended;
 use rayon::prelude::*;
 use reth_era::common::file_ops::StreamReader;
diff --git a/beacon_node/beacon_chain/src/era/producer.rs b/beacon_node/beacon_chain/src/era/producer.rs
index a5695c59f5..b4165fc25c 100644
--- a/beacon_node/beacon_chain/src/era/producer.rs
+++ b/beacon_node/beacon_chain/src/era/producer.rs
@@ -1,3 +1,12 @@
+//! Export ERA files from a Lighthouse database.
+//!
+//! Reads blocks and states from the cold DB and writes them into the standardized ERA format.
+//! ERA files are produced either during historical reconstruction (backfilling) or upon
+//! finalization of new eras. Each file is named `{network}-{era_number}-{short_root}.era`.
+//!
+//! Files are written atomically (temp file + rename) so partial writes never appear as valid
+//! ERA files. Existing files are skipped, making production idempotent.
+
 use rand::random;
 use reth_era::common::file_ops::{EraFileFormat, EraFileId, StreamWriter};
 use reth_era::era::file::{EraFile, EraWriter};