fix(core+tool): epochs_v2 backfill and formal-restore cleanup (#11870)

# Description of change

Some cleanup for #11697 

- **Local epoch backfill: only missing data counts as pruned
(`iota-core`, `iota-types`).** Real storage failures were swallowed as
"data pruned, retry once a newer snapshot is published". Absent-data
errors now carry `Kind::Missing` (was `custom`) and only those end the
best-effort replay; anything else propagates. Nothing else reads the
kind.
- **Operator doc fixes (`iota-config`, `docs`).** The config doc still
described the removed background task (the backfill is synchronous and
gates startup); the snapshots guide now documents the refuse-to-start
case when even the latest snapshot is older than the node's pruned-away
history.

## How the change has been tested

- [x] Basic tests (linting, compilation, formatting, unit/integration
tests)
- [ ] Patch-specific tests (correctness, functionality coverage)
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have checked that new and existing unit tests pass locally with
my changes

Author: bingyanglin

crates/iota-config/src/node.rs

@@ -193,9 +193,11 @@ pub struct NodeConfig {
     #[serde(default)]
     pub state_snapshot_write_config: StateSnapshotConfig,
 
-    /// Read-side formal-snapshot source. When set, a running fullnode
-    /// background-backfills its gRPC `epochs_v2` table from the snapshot's
-    /// `EPOCH_INFO`. Disabled when `None` (the default).
+    /// Read-side formal-snapshot source. When set, a fullnode whose gRPC
+    /// `epochs_v2` table is incomplete backfills it from the snapshot's
+    /// `EPOCH_INFO` synchronously at startup; with a gap and no source
+    /// configured, the node refuses to start. Disabled when `None` (the
+    /// default).
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub state_snapshot_read_config: Option<ObjectStoreConfig>,
 

crates/iota-core/src/grpc_indexes.rs

@@ -26,7 +26,8 @@ use iota_types::{
     storage::{
         AccountOwnedObjectInfo, DynamicFieldKey, EpochInfo, EpochInfoV2, OwnedObjectCursor,
         OwnedObjectIteratorItem, PackageVersionInfo, PackageVersionIteratorItem, PackageVersionKey,
-        TransactionInfo, error::Error as StorageError,
+        TransactionInfo,
+        error::{Error as StorageError, Kind as StorageErrorKind},
     },
 };
 use serde::{Deserialize, Serialize};
@@ -943,9 +944,14 @@ impl IndexStoreTables {
                 else {
                     return Ok(None);
                 };
-                // Errors are "transaction/effects/objects already pruned" on
-                // a healthy store.
-                Ok(assemble_sparse_checkpoint_data(authority_store, summary, contents).ok())
+                match assemble_sparse_checkpoint_data(authority_store, summary, contents) {
+                    Ok(data) => Ok(Some(data)),
+                    // Pruned-away transactions/effects/objects are the
+                    // expected end of what can be rebuilt locally; anything
+                    // else is a real storage failure and must propagate.
+                    Err(e) if e.kind() == StorageErrorKind::Missing => Ok(None),
+                    Err(e) => Err(e),
+                }
             })()?;
             let Some(checkpoint_data) = checkpoint_data else {
                 warn!(
@@ -1776,14 +1782,14 @@ fn assemble_sparse_checkpoint_data(
         .multi_get_transaction_blocks(&transaction_digests)?
         .into_iter()
         .map(|maybe_transaction| {
-            maybe_transaction.ok_or_else(|| StorageError::custom("missing transaction"))
+            maybe_transaction.ok_or_else(|| StorageError::missing("missing transaction"))
         })
         .collect::<Result<Vec<_>, _>>()?;
 
     let effects = authority_store
         .multi_get_executed_effects(&transaction_digests)?
         .into_iter()
-        .map(|maybe_effects| maybe_effects.ok_or_else(|| StorageError::custom("missing effects")))
+        .map(|maybe_effects| maybe_effects.ok_or_else(|| StorageError::missing("missing effects")))
         .collect::<Result<Vec<_>, _>>()?;
 
     let mut full_transactions = Vec::with_capacity(transactions.len());

crates/iota-types/src/storage/mod.rs

@@ -593,7 +593,7 @@ pub fn get_transaction_input_objects(
         .enumerate()
         .map(|(idx, maybe_object)| {
             maybe_object.ok_or_else(|| {
-                StorageError::custom(format!(
+                StorageError::missing(format!(
                     "missing input object key {:?} from tx {}",
                     input_object_keys[idx],
                     effects.transaction_digest()
@@ -620,7 +620,7 @@ pub fn get_transaction_output_objects(
         .enumerate()
         .map(|(idx, maybe_object)| {
             maybe_object.ok_or_else(|| {
-                StorageError::custom(format!(
+                StorageError::missing(format!(
                     "missing output object key {:?} from tx {}",
                     output_object_keys[idx],
                     effects.transaction_digest()

docs/content/operator/common/snapshots.mdx

@@ -249,7 +249,7 @@ state-snapshot-read-config:
 
 </Tabs>
 
-With this set, the node downloads the per-epoch metadata from the latest formal snapshot at startup (a few seconds; the large object files are not downloaded) and then starts normally.
+With this set, the node downloads the per-epoch metadata from the latest formal snapshot at startup (a few seconds; the large object files are not downloaded) and then starts normally. If even the latest snapshot is older than the node's executed history and the missing epochs' data is already pruned locally, the node still refuses to start: wait for a newer snapshot, restore from a formal snapshot, or disable the gRPC API.
 
 ## IOTA Foundation managed snapshots