Fix blocks persistence

Signed-off-by: bakhtin <a@bakhtin.net>

Author: bakhtin

crates/engine/primitives/src/config.rs

@@ -9,6 +9,10 @@ pub const DEFAULT_PERSISTENCE_THRESHOLD: u64 = 2;
 /// How close to the canonical head we persist blocks.
 pub const DEFAULT_MEMORY_BLOCK_BUFFER_TARGET: u64 = 0;
 
+/// Default maximum number of entries the persistence pruner may delete per run.
+/// Caps MDBX dirty page accumulation to ~400 MB (100k entries × ~4 KB pages).
+pub const DEFAULT_PERSISTENCE_PRUNER_DELETE_LIMIT: usize = 100_000;
+
 /// Returns the default number of storage worker threads based on available parallelism.
 fn default_storage_worker_count() -> usize {
     #[cfg(feature = "std")]
@@ -186,6 +190,13 @@ pub struct TreeConfig {
     /// computation is spawned in parallel and whichever finishes first is used.
     /// If `None`, the timeout fallback is disabled.
     state_root_task_timeout: Option<Duration>,
+    /// Maximum number of entries the persistence pruner may delete in a single run.
+    /// Limits MDBX dirty page accumulation to prevent OOM during the first prune after startup.
+    persistence_pruner_delete_limit: usize,
+    /// Timeout for the persistence pruner per run. Prevents a single prune from blocking
+    /// block persistence for too long. Account and Storage History segments treat this as
+    /// a soft limit.
+    persistence_pruner_timeout: Option<Duration>,
 }
 
 impl Default for TreeConfig {
@@ -220,6 +231,8 @@ impl Default for TreeConfig {
             sparse_trie_max_storage_tries: DEFAULT_SPARSE_TRIE_MAX_STORAGE_TRIES,
             disable_sparse_trie_cache_pruning: false,
             state_root_task_timeout: Some(DEFAULT_STATE_ROOT_TASK_TIMEOUT),
+            persistence_pruner_delete_limit: DEFAULT_PERSISTENCE_PRUNER_DELETE_LIMIT,
+            persistence_pruner_timeout: None,
         }
     }
 }
@@ -286,6 +299,8 @@ impl TreeConfig {
             sparse_trie_max_storage_tries,
             disable_sparse_trie_cache_pruning: false,
             state_root_task_timeout,
+            persistence_pruner_delete_limit: DEFAULT_PERSISTENCE_PRUNER_DELETE_LIMIT,
+            persistence_pruner_timeout: None,
         }
     }
 
@@ -656,4 +671,26 @@ impl TreeConfig {
         self.state_root_task_timeout = timeout;
         self
     }
+
+    /// Returns the persistence pruner delete limit.
+    pub const fn persistence_pruner_delete_limit(&self) -> usize {
+        self.persistence_pruner_delete_limit
+    }
+
+    /// Setter for persistence pruner delete limit.
+    pub const fn with_persistence_pruner_delete_limit(mut self, limit: usize) -> Self {
+        self.persistence_pruner_delete_limit = limit;
+        self
+    }
+
+    /// Returns the persistence pruner timeout.
+    pub const fn persistence_pruner_timeout(&self) -> Option<Duration> {
+        self.persistence_pruner_timeout
+    }
+
+    /// Setter for persistence pruner timeout.
+    pub const fn with_persistence_pruner_timeout(mut self, timeout: Option<Duration>) -> Self {
+        self.persistence_pruner_timeout = timeout;
+        self
+    }
 }

crates/engine/tree/src/persistence.rs

@@ -154,6 +154,11 @@ where
         let start_time = Instant::now();
 
         if let Some(last) = last_block {
+            // Commit block data immediately so persistence is not blocked by pruning.
+            // The pruner can take hours on the first run after startup (its
+            // previous_tip_block_number starts at None, triggering a full segment scan
+            // even when the pipeline already pruned). Running it in a separate transaction
+            // ensures blocks become durable on disk without waiting for pruning to finish.
             let provider_rw = self.provider.database_provider_rw()?;
             provider_rw.save_blocks(blocks, SaveBlocksMode::Full)?;
 
@@ -164,14 +169,16 @@ where
                 provider_rw.save_safe_block_number(safe)?;
             }
 
+            provider_rw.commit()?;
+
             if self.pruner.is_pruning_needed(last.number) {
                 debug!(target: "engine::persistence", block_num=?last.number, "Running pruner");
                 let prune_start = Instant::now();
+                let provider_rw = self.provider.database_provider_rw()?;
                 let _ = self.pruner.run_with_provider(&provider_rw, last.number)?;
+                provider_rw.commit()?;
                 self.metrics.prune_before_duration_seconds.record(prune_start.elapsed());
             }
-
-            provider_rw.commit()?;
         }
 
         debug!(target: "engine::persistence", first=?first_block, last=?last_block, "Saved range of blocks");

crates/engine/tree/src/tree/mod.rs

@@ -1292,6 +1292,17 @@ where
             } else if self.should_persist() {
                 let blocks_to_persist =
                     self.get_canonical_blocks_to_persist(PersistTarget::Threshold)?;
+                if blocks_to_persist.is_empty() {
+                    // This indicates the canonical head block is not in blocks_by_hash,
+                    // which prevents the chain walk from collecting blocks to persist.
+                    warn!(
+                        target: "engine::tree",
+                        canonical_head = ?self.state.tree_state.canonical_head(),
+                        last_persisted = ?self.persistence_state.last_persisted_block,
+                        "should_persist=true but no blocks found to persist; \
+                         canonical head may not be in memory"
+                    );
+                }
                 self.persist_blocks(blocks_to_persist);
             }
         }

crates/node/builder/src/launch/engine.rs

@@ -170,6 +170,11 @@ impl EngineNodeLauncher {
             pruner_builder =
                 pruner_builder.finished_exex_height(exex_manager_handle.finished_height());
         }
+        pruner_builder =
+            pruner_builder.delete_limit(engine_tree_config.persistence_pruner_delete_limit());
+        if let Some(timeout) = engine_tree_config.persistence_pruner_timeout() {
+            pruner_builder = pruner_builder.timeout(timeout);
+        }
         let pruner = pruner_builder.build_with_provider_factory(ctx.provider_factory().clone());
         let pruner_events = pruner.events();
         info!(target: "reth::cli", prune_config=?ctx.prune_config(), "Pruner initialized");

crates/node/core/src/args/engine.rs

@@ -2,8 +2,8 @@
 
 use clap::{builder::Resettable, Args};
 use reth_engine_primitives::{
-    TreeConfig, DEFAULT_MULTIPROOF_TASK_CHUNK_SIZE, DEFAULT_SPARSE_TRIE_MAX_STORAGE_TRIES,
-    DEFAULT_SPARSE_TRIE_PRUNE_DEPTH,
+    TreeConfig, DEFAULT_MULTIPROOF_TASK_CHUNK_SIZE, DEFAULT_PERSISTENCE_PRUNER_DELETE_LIMIT,
+    DEFAULT_SPARSE_TRIE_MAX_STORAGE_TRIES, DEFAULT_SPARSE_TRIE_PRUNE_DEPTH,
 };
 use std::{sync::OnceLock, time::Duration};
 
@@ -400,6 +400,25 @@ pub struct EngineArgs {
         default_value = DefaultEngineValues::get_global().state_root_task_timeout.as_deref().unwrap_or("1s"),
     )]
     pub state_root_task_timeout: Option<Duration>,
+
+    /// Maximum number of entries the persistence pruner may delete in a single run.
+    /// Limits MDBX dirty page accumulation to prevent OOM when the pruner runs for the
+    /// first time after startup on a large database.
+    ///
+    /// Set to 0 to disable the limit (unlimited).
+    #[arg(long = "engine.persistence-pruner-delete-limit", default_value_t = DEFAULT_PERSISTENCE_PRUNER_DELETE_LIMIT)]
+    pub persistence_pruner_delete_limit: usize,
+
+    /// Timeout for the persistence pruner per run. Prevents a single prune from blocking
+    /// block persistence for too long.
+    ///
+    /// CAUTION: Account and Storage History segments treat this as a soft limit.
+    ///
+    /// Set to 0s to disable.
+    ///
+    /// --engine.persistence-pruner-timeout 30s
+    #[arg(long = "engine.persistence-pruner-timeout", value_parser = humantime::parse_duration)]
+    pub persistence_pruner_timeout: Option<Duration>,
 }
 
 #[allow(deprecated)]
@@ -464,6 +483,8 @@ impl Default for EngineArgs {
             state_root_task_timeout: state_root_task_timeout
                 .as_deref()
                 .map(|s| humantime::parse_duration(s).expect("valid default duration")),
+            persistence_pruner_delete_limit: DEFAULT_PERSISTENCE_PRUNER_DELETE_LIMIT,
+            persistence_pruner_timeout: None,
         }
     }
 }
@@ -498,6 +519,14 @@ impl EngineArgs {
             .with_sparse_trie_max_storage_tries(self.sparse_trie_max_storage_tries)
             .with_disable_sparse_trie_cache_pruning(self.disable_sparse_trie_cache_pruning)
             .with_state_root_task_timeout(self.state_root_task_timeout.filter(|d| !d.is_zero()))
+            .with_persistence_pruner_delete_limit(if self.persistence_pruner_delete_limit == 0 {
+                usize::MAX
+            } else {
+                self.persistence_pruner_delete_limit
+            })
+            .with_persistence_pruner_timeout(
+                self.persistence_pruner_timeout.filter(|d| !d.is_zero()),
+            )
     }
 }
 
@@ -553,6 +582,8 @@ mod tests {
             sparse_trie_max_storage_tries: 100,
             disable_sparse_trie_cache_pruning: true,
             state_root_task_timeout: Some(Duration::from_secs(2)),
+            persistence_pruner_delete_limit: 100_000,
+            persistence_pruner_timeout: Some(Duration::from_secs(30)),
         };
 
         let parsed_args = CommandParser::<EngineArgs>::parse_from([
@@ -591,6 +622,10 @@ mod tests {
             "--engine.disable-sparse-trie-cache-pruning",
             "--engine.state-root-task-timeout",
             "2s",
+            "--engine.persistence-pruner-delete-limit",
+            "100000",
+            "--engine.persistence-pruner-timeout",
+            "30s",
         ])
         .args;