Improve /lighthouse/database/reconstruct API: return informative error if backfill not enabled

beacon_node/beacon_chain/src/migrate.rs

@@ -215,13 +215,15 @@ impl<E: EthSpec, Hot: ItemStore<E>, Cold: ItemStore<E>> BackgroundMigrator<E, Ho
         }
     }
 
-    pub fn process_reconstruction(&self) {
+    pub fn process_reconstruction(&self) -> Result<(), Error> {
         if let Some(Notification::Reconstruction) =
             self.send_background_notification(Notification::Reconstruction)
         {
             // If we are running in foreground mode (as in tests), then this will just run a single
             // batch. We may need to tweak this in future.
-            Self::run_reconstruction(self.db.clone(), None, &self.log);
+            Self::run_reconstruction(self.db.clone(), None, &self.log)
+        } else {
+            Ok(())
         }
     }
 
@@ -237,7 +239,7 @@ impl<E: EthSpec, Hot: ItemStore<E>, Cold: ItemStore<E>> BackgroundMigrator<E, Ho
         db: Arc<HotColdDB<E, Hot, Cold>>,
         opt_tx: Option<mpsc::Sender<Notification>>,
         log: &Logger,
-    ) {
+    ) -> Result<(), Error> {
         match db.reconstruct_historic_states(Some(BLOCKS_PER_RECONSTRUCTION)) {
             Ok(()) => {
                 // Schedule another reconstruction batch if required and we have access to the
@@ -253,13 +255,15 @@ impl<E: EthSpec, Hot: ItemStore<E>, Cold: ItemStore<E>> BackgroundMigrator<E, Ho
                         }
                     }
                 }
+                Ok(())
             }
             Err(e) => {
                 error!(
                     log,
                     "State reconstruction failed";
                     "error" => ?e,
                 );
+                Err(e)
             }
         }
     }

beacon_node/http_api/src/lib.rs

@@ -4631,8 +4631,20 @@ pub fn serve<T: BeaconChainTypes>(
              chain: Arc<BeaconChain<T>>| {
                 task_spawner.blocking_json_task(Priority::P1, move || {
                     not_synced_filter?;
-                    chain.store_migrator.process_reconstruction();
-                    Ok("success")
+                    match chain.store_migrator.process_reconstruction() {
+                        Ok(()) => Ok(serde_json::json!({"status": "success"})),
+                        Err(e) => {
+                            use beacon_chain::store::Error;
+                            if let Error::MissingHistoricBlocks { oldest_block_slot } = e {
+                                let msg = format!(
+                                    "State reconstruction cannot start: not all historic blocks are available (oldest_block_slot: {oldest_block_slot}). Please restart the Beacon Node with --reconstruct-historic-states."
+                                );
+                                Err(warp::reject::custom(warp_utils::reject::custom_bad_request(msg)))
+                            } else {
+                                Err(warp::reject::custom(warp_utils::reject::custom_server_error(format!("State reconstruction failed: {e}"))))
+                            }
+                        }
+                    }
                 })
             },
         );

book/src/api-lighthouse.md

@@ -818,3 +818,30 @@ An open port will return:
 {
   "data": true
 }
+
+```
+
+## `/lighthouse/database/reconstruct`
+
+Initiates historic state reconstruction in the database. This is only available if all historic blocks are present (i.e., backfill sync is complete and `oldest_block_slot` is 0).
+
+- **POST** `/lighthouse/database/reconstruct`
+
+If the node was not started with backfill enabled (e.g., without `--genesis-backfill` or `--reconstruct-historic-states`), this endpoint will return an error:
+
+```json
+{
+  "code": 400,
+  "message": "State reconstruction cannot start: not all historic blocks are available (oldest_block_slot: <slot>). Please restart the Beacon Node with --reconstruct-historic-states."
+}
+```
+
+If reconstruction is possible, the endpoint will return:
+
+```json
+{
+  "status": "success"
+}
+```
+
+See [Checkpoint Sync: Reconstructing States](./checkpoint-sync.md#reconstructing-states) for more details.