chore: introduce v2 storage flag and remove edge flag (#21868)

Co-authored-by: Georgios Konstantopoulos <me@gakonst.com>
Co-authored-by: yongkangc <chiayongkang@hotmail.com>

crates/node/core/Cargo.toml

@@ -90,8 +90,11 @@ min-info-logs = ["tracing/release_max_level_info"]
 min-debug-logs = ["tracing/release_max_level_debug"]
 min-trace-logs = ["tracing/release_max_level_trace"]
 
-# Marker feature for edge/unstable builds - captured by vergen in build.rs
-edge = ["reth-storage-api/edge"]
+# Route supported tables to RocksDB instead of MDBX
+rocksdb = ["reth-storage-api/rocksdb"]
+
+# Marker feature for edge/unstable builds - enables rocksdb and sets v2 defaults
+edge = ["rocksdb"]
 
 [build-dependencies]
 vergen = { workspace = true, features = ["build", "cargo", "emit_and_set"] }

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

@@ -84,5 +84,9 @@ pub use static_files::{StaticFilesArgs, MINIMAL_BLOCKS_PER_FILE};
 mod rocksdb;
 pub use rocksdb::{RocksDbArgs, RocksDbArgsError};
 
+/// `StorageArgs` for configuring storage mode (v2 vs v1/legacy).
+mod storage;
+pub use storage::StorageArgs;
+
 mod error;
 pub mod types;

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

@@ -1,34 +1,15 @@
 //! clap [Args](clap::Args) for `RocksDB` table routing configuration
 
 use clap::{ArgAction, Args};
-use reth_storage_api::StorageSettings;
-
-/// Default value for `tx_hash` routing flag.
-///
-/// Derived from [`StorageSettings::base()`] to ensure CLI defaults match storage defaults.
-const fn default_tx_hash_in_rocksdb() -> bool {
-    StorageSettings::base().transaction_hash_numbers_in_rocksdb
-}
-
-/// Default value for `storages_history` routing flag.
-///
-/// Derived from [`StorageSettings::base()`] to ensure CLI defaults match storage defaults.
-const fn default_storages_history_in_rocksdb() -> bool {
-    StorageSettings::base().storages_history_in_rocksdb
-}
-
-/// Default value for `account_history` routing flag.
-///
-/// Derived from [`StorageSettings::base()`] to ensure CLI defaults match storage defaults.
-const fn default_account_history_in_rocksdb() -> bool {
-    StorageSettings::base().account_history_in_rocksdb
-}
 
 /// Parameters for `RocksDB` table routing configuration.
 ///
 /// These flags control which database tables are stored in `RocksDB` instead of MDBX.
 /// All flags are genesis-initialization-only: changing them after genesis requires a re-sync.
-#[derive(Debug, Args, PartialEq, Eq, Clone, Copy)]
+///
+/// When `--storage.v2` is used, the defaults for these flags change to enable `RocksDB` routing.
+/// Individual flags can still override those defaults when explicitly set.
+#[derive(Debug, Args, PartialEq, Eq, Clone, Copy, Default)]
 #[command(next_help_heading = "RocksDB")]
 pub struct RocksDbArgs {
     /// Route all supported tables to `RocksDB` instead of MDBX.
@@ -41,49 +22,39 @@ pub struct RocksDbArgs {
     /// Route tx hash -> number table to `RocksDB` instead of MDBX.
     ///
     /// This is a genesis-initialization-only flag: changing it after genesis requires a re-sync.
-    /// Defaults to `true` when the `edge` feature is enabled, `false` otherwise.
-    #[arg(long = "rocksdb.tx-hash", default_value_t = default_tx_hash_in_rocksdb(), action = ArgAction::Set)]
-    pub tx_hash: bool,
+    /// Defaults to the base storage mode (v1: false, v2: true).
+    #[arg(long = "rocksdb.tx-hash", action = ArgAction::Set)]
+    pub tx_hash: Option<bool>,
 
     /// Route storages history tables to `RocksDB` instead of MDBX.
     ///
     /// This is a genesis-initialization-only flag: changing it after genesis requires a re-sync.
-    /// Defaults to `false`.
-    #[arg(long = "rocksdb.storages-history", default_value_t = default_storages_history_in_rocksdb(), action = ArgAction::Set)]
-    pub storages_history: bool,
+    /// Defaults to the base storage mode (v1: false, v2: true).
+    #[arg(long = "rocksdb.storages-history", action = ArgAction::Set)]
+    pub storages_history: Option<bool>,
 
     /// Route account history tables to `RocksDB` instead of MDBX.
     ///
     /// This is a genesis-initialization-only flag: changing it after genesis requires a re-sync.
-    /// Defaults to `false`.
-    #[arg(long = "rocksdb.account-history", default_value_t = default_account_history_in_rocksdb(), action = ArgAction::Set)]
-    pub account_history: bool,
-}
-
-impl Default for RocksDbArgs {
-    fn default() -> Self {
-        Self {
-            all: false,
-            tx_hash: default_tx_hash_in_rocksdb(),
-            storages_history: default_storages_history_in_rocksdb(),
-            account_history: default_account_history_in_rocksdb(),
-        }
-    }
+    /// Defaults to the base storage mode (v1: false, v2: true).
+    #[arg(long = "rocksdb.account-history", action = ArgAction::Set)]
+    pub account_history: Option<bool>,
 }
 
 impl RocksDbArgs {
     /// Validates the `RocksDB` arguments.
     ///
-    /// Returns an error if `--rocksdb.all` is used with any individual flag set to `false`.
+    /// Returns an error if `--rocksdb.all` is used with any individual flag explicitly set to
+    /// `false`.
     pub const fn validate(&self) -> Result<(), RocksDbArgsError> {
         if self.all {
-            if !self.tx_hash {
+            if matches!(self.tx_hash, Some(false)) {
                 return Err(RocksDbArgsError::ConflictingFlags("tx-hash"));
             }
-            if !self.storages_history {
+            if matches!(self.storages_history, Some(false)) {
                 return Err(RocksDbArgsError::ConflictingFlags("storages-history"));
             }
-            if !self.account_history {
+            if matches!(self.account_history, Some(false)) {
                 return Err(RocksDbArgsError::ConflictingFlags("account-history"));
             }
         }
@@ -114,31 +85,17 @@ mod tests {
     fn test_default_rocksdb_args() {
         let args = CommandParser::<RocksDbArgs>::parse_from(["reth"]).args;
         assert_eq!(args, RocksDbArgs::default());
+        assert!(!args.all);
+        assert!(args.tx_hash.is_none());
+        assert!(args.storages_history.is_none());
+        assert!(args.account_history.is_none());
     }
 
     #[test]
     fn test_parse_all_flag() {
         let args = CommandParser::<RocksDbArgs>::parse_from(["reth", "--rocksdb.all"]).args;
         assert!(args.all);
-        assert_eq!(args.tx_hash, default_tx_hash_in_rocksdb());
-    }
-
-    #[test]
-    fn test_defaults_match_storage_settings() {
-        let args = RocksDbArgs::default();
-        let settings = StorageSettings::base();
-        assert_eq!(
-            args.tx_hash, settings.transaction_hash_numbers_in_rocksdb,
-            "tx_hash default should match StorageSettings::base()"
-        );
-        assert_eq!(
-            args.storages_history, settings.storages_history_in_rocksdb,
-            "storages_history default should match StorageSettings::base()"
-        );
-        assert_eq!(
-            args.account_history, settings.account_history_in_rocksdb,
-            "account_history default should match StorageSettings::base()"
-        );
+        assert!(args.tx_hash.is_none());
     }
 
     #[test]
@@ -151,15 +108,26 @@ mod tests {
         ])
         .args;
         assert!(!args.all);
-        assert!(args.tx_hash);
-        assert!(!args.storages_history);
-        assert!(args.account_history);
+        assert_eq!(args.tx_hash, Some(true));
+        assert_eq!(args.storages_history, Some(false));
+        assert_eq!(args.account_history, Some(true));
+    }
+
+    #[test]
+    fn test_validate_all_with_none_ok() {
+        let args =
+            RocksDbArgs { all: true, tx_hash: None, storages_history: None, account_history: None };
+        assert!(args.validate().is_ok());
     }
 
     #[test]
     fn test_validate_all_with_true_ok() {
-        let args =
-            RocksDbArgs { all: true, tx_hash: true, storages_history: true, account_history: true };
+        let args = RocksDbArgs {
+            all: true,
+            tx_hash: Some(true),
+            storages_history: Some(true),
+            account_history: Some(true),
+        };
         assert!(args.validate().is_ok());
     }
 
@@ -167,25 +135,25 @@ mod tests {
     fn test_validate_all_with_false_errors() {
         let args = RocksDbArgs {
             all: true,
-            tx_hash: false,
-            storages_history: true,
-            account_history: true,
+            tx_hash: Some(false),
+            storages_history: None,
+            account_history: None,
         };
         assert_eq!(args.validate(), Err(RocksDbArgsError::ConflictingFlags("tx-hash")));
 
         let args = RocksDbArgs {
             all: true,
-            tx_hash: true,
-            storages_history: false,
-            account_history: true,
+            tx_hash: None,
+            storages_history: Some(false),
+            account_history: None,
         };
         assert_eq!(args.validate(), Err(RocksDbArgsError::ConflictingFlags("storages-history")));
 
         let args = RocksDbArgs {
             all: true,
-            tx_hash: true,
-            storages_history: true,
-            account_history: false,
+            tx_hash: None,
+            storages_history: None,
+            account_history: Some(false),
         };
         assert_eq!(args.validate(), Err(RocksDbArgsError::ConflictingFlags("account-history")));
     }

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

@@ -2,23 +2,17 @@
 
 use clap::Args;
 use reth_config::config::{BlocksPerFileConfig, StaticFilesConfig};
-use reth_storage_api::StorageSettings;
 
 /// Blocks per static file when running in `--minimal` node.
 ///
 /// 10000 blocks per static file allows us to prune all history every 10k blocks.
 pub const MINIMAL_BLOCKS_PER_FILE: u64 = 10000;
 
-/// Default value for static file storage flags.
-///
-/// When the `edge` feature is enabled, defaults to `true` to enable edge storage features.
-/// Otherwise defaults to `false` for legacy behavior.
-const fn default_static_file_flag() -> bool {
-    cfg!(feature = "edge")
-}
-
 /// Parameters for static files configuration
-#[derive(Debug, Args, PartialEq, Eq, Clone, Copy)]
+///
+/// When `--storage.v2` is used, the defaults for the storage flags change to enable static file
+/// storage. Individual flags can still override those defaults when explicitly set.
+#[derive(Debug, Args, PartialEq, Eq, Clone, Copy, Default)]
 #[command(next_help_heading = "Static Files")]
 pub struct StaticFilesArgs {
     /// Number of blocks per file for the headers segment.
@@ -51,8 +45,10 @@ pub struct StaticFilesArgs {
     ///
     /// Note: This setting can only be configured at genesis initialization. Once
     /// the node has been initialized, changing this flag requires re-syncing from scratch.
-    #[arg(long = "static-files.receipts", default_value_t = default_static_file_flag(), action = clap::ArgAction::Set)]
-    pub receipts: bool,
+    ///
+    /// Defaults to the base storage mode (v1: false, v2: true).
+    #[arg(long = "static-files.receipts", action = clap::ArgAction::Set)]
+    pub receipts: Option<bool>,
 
     /// Store transaction senders in static files instead of the database.
     ///
@@ -61,8 +57,10 @@ pub struct StaticFilesArgs {
     ///
     /// Note: This setting can only be configured at genesis initialization. Once
     /// the node has been initialized, changing this flag requires re-syncing from scratch.
-    #[arg(long = "static-files.transaction-senders", default_value_t = default_static_file_flag(), action = clap::ArgAction::Set)]
-    pub transaction_senders: bool,
+    ///
+    /// Defaults to the base storage mode (v1: false, v2: true).
+    #[arg(long = "static-files.transaction-senders", action = clap::ArgAction::Set)]
+    pub transaction_senders: Option<bool>,
 
     /// Store account changesets in static files.
     ///
@@ -71,8 +69,10 @@ pub struct StaticFilesArgs {
     ///
     /// Note: This setting can only be configured at genesis initialization. Once
     /// the node has been initialized, changing this flag requires re-syncing from scratch.
-    #[arg(long = "static-files.account-change-sets", default_value_t = default_static_file_flag(), action = clap::ArgAction::Set)]
-    pub account_changesets: bool,
+    ///
+    /// Defaults to the base storage mode (v1: false, v2: true).
+    #[arg(long = "static-files.account-change-sets", action = clap::ArgAction::Set)]
+    pub account_changesets: Option<bool>,
 
     /// Store storage changesets in static files.
     ///
@@ -81,8 +81,10 @@ pub struct StaticFilesArgs {
     ///
     /// Note: This setting can only be configured at genesis initialization. Once
     /// the node has been initialized, changing this flag requires re-syncing from scratch.
-    #[arg(long = "static-files.storage-change-sets", default_value_t = default_static_file_flag(), action = clap::ArgAction::Set)]
-    pub storage_changesets: bool,
+    ///
+    /// Defaults to the base storage mode (v1: false, v2: true).
+    #[arg(long = "static-files.storage-change-sets", action = clap::ArgAction::Set)]
+    pub storage_changesets: Option<bool>,
 }
 
 impl StaticFilesArgs {
@@ -122,34 +124,4 @@ impl StaticFilesArgs {
             },
         }
     }
-
-    /// Converts the static files arguments into [`StorageSettings`].
-    pub const fn to_settings(&self) -> StorageSettings {
-        #[cfg(feature = "edge")]
-        let base = StorageSettings::edge();
-        #[cfg(not(feature = "edge"))]
-        let base = StorageSettings::legacy();
-
-        base.with_receipts_in_static_files(self.receipts)
-            .with_transaction_senders_in_static_files(self.transaction_senders)
-            .with_account_changesets_in_static_files(self.account_changesets)
-            .with_storage_changesets_in_static_files(self.storage_changesets)
-    }
-}
-
-impl Default for StaticFilesArgs {
-    fn default() -> Self {
-        Self {
-            blocks_per_file_headers: None,
-            blocks_per_file_transactions: None,
-            blocks_per_file_receipts: None,
-            blocks_per_file_transaction_senders: None,
-            blocks_per_file_account_change_sets: None,
-            blocks_per_file_storage_change_sets: None,
-            receipts: default_static_file_flag(),
-            transaction_senders: default_static_file_flag(),
-            account_changesets: default_static_file_flag(),
-            storage_changesets: default_static_file_flag(),
-        }
-    }
 }

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

@@ -0,0 +1,50 @@
+//! clap [Args](clap::Args) for storage mode configuration
+
+use clap::{ArgAction, Args};
+
+/// Parameters for storage mode configuration.
+///
+/// This controls whether the node uses v2 storage defaults (with `RocksDB` and static file
+/// optimizations) or v1/legacy storage defaults.
+#[derive(Debug, Args, PartialEq, Eq, Clone, Copy, Default)]
+#[command(next_help_heading = "Storage")]
+pub struct StorageArgs {
+    /// Enable v2 storage defaults (static files + `RocksDB` routing).
+    ///
+    /// When enabled, the node uses optimized storage settings:
+    /// - Receipts and transaction senders in static files
+    /// - History indices in `RocksDB` (accounts, storages, transaction hashes)
+    /// - Account and storage changesets in static files
+    ///
+    /// This is a genesis-initialization-only setting: changing it after genesis requires a
+    /// re-sync.
+    ///
+    /// Individual settings can still be overridden with `--static-files.*` and `--rocksdb.*`
+    /// flags.
+    #[arg(long = "storage.v2", action = ArgAction::SetTrue)]
+    pub v2: bool,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use clap::Parser;
+
+    #[derive(Parser)]
+    struct CommandParser {
+        #[command(flatten)]
+        args: StorageArgs,
+    }
+
+    #[test]
+    fn test_default_storage_args() {
+        let args = CommandParser::parse_from(["reth"]).args;
+        assert!(!args.v2);
+    }
+
+    #[test]
+    fn test_parse_v2_flag() {
+        let args = CommandParser::parse_from(["reth", "--storage.v2"]).args;
+        assert!(args.v2);
+    }
+}

crates/node/core/src/node_config.rs

@@ -3,7 +3,7 @@
 use crate::{
     args::{
         DatabaseArgs, DatadirArgs, DebugArgs, DevArgs, EngineArgs, NetworkArgs, PayloadBuilderArgs,
-        PruningArgs, RocksDbArgs, RpcServerArgs, StaticFilesArgs, TxPoolArgs,
+        PruningArgs, RocksDbArgs, RpcServerArgs, StaticFilesArgs, StorageArgs, TxPoolArgs,
     },
     dirs::{ChainPath, DataDirPath},
     utils::get_single_header,
@@ -154,6 +154,9 @@ pub struct NodeConfig<ChainSpec> {
 
     /// All `RocksDB` table routing arguments
     pub rocksdb: RocksDbArgs,
+
+    /// Storage mode configuration (v2 vs v1/legacy)
+    pub storage: StorageArgs,
 }
 
 impl NodeConfig<ChainSpec> {
@@ -186,6 +189,7 @@ impl<ChainSpec> NodeConfig<ChainSpec> {
             era: EraArgs::default(),
             static_files: StaticFilesArgs::default(),
             rocksdb: RocksDbArgs::default(),
+            storage: StorageArgs::default(),
         }
     }
 
@@ -261,6 +265,7 @@ impl<ChainSpec> NodeConfig<ChainSpec> {
             era,
             static_files,
             rocksdb,
+            storage,
             ..
         } = self;
         NodeConfig {
@@ -281,6 +286,7 @@ impl<ChainSpec> NodeConfig<ChainSpec> {
             era,
             static_files,
             rocksdb,
+            storage,
         }
     }
 
@@ -357,16 +363,52 @@ impl<ChainSpec> NodeConfig<ChainSpec> {
         self.pruning.prune_config(&self.chain)
     }
 
-    /// Returns the effective storage settings derived from static-file and `RocksDB` CLI args.
+    /// Returns the effective storage settings derived from `--storage.v2`, static-file, and
+    /// `RocksDB` CLI args.
+    ///
+    /// The base storage mode is determined by `--storage.v2`:
+    /// - When `--storage.v2` is set: uses [`StorageSettings::v2()`] defaults
+    /// - Otherwise: uses [`StorageSettings::v1()`] defaults
+    ///
+    /// Individual `--static-files.*` and `--rocksdb.*` flags override the base when explicitly set.
     pub const fn storage_settings(&self) -> StorageSettings {
-        StorageSettings::base()
-            .with_receipts_in_static_files(self.static_files.receipts)
-            .with_transaction_senders_in_static_files(self.static_files.transaction_senders)
-            .with_account_changesets_in_static_files(self.static_files.account_changesets)
-            .with_storage_changesets_in_static_files(self.static_files.storage_changesets)
-            .with_transaction_hash_numbers_in_rocksdb(self.rocksdb.all || self.rocksdb.tx_hash)
-            .with_storages_history_in_rocksdb(self.rocksdb.all || self.rocksdb.storages_history)
-            .with_account_history_in_rocksdb(self.rocksdb.all || self.rocksdb.account_history)
+        let mut s = if self.storage.v2 { StorageSettings::v2() } else { StorageSettings::base() };
+
+        // Apply static files overrides (only when explicitly set)
+        if let Some(v) = self.static_files.receipts {
+            s = s.with_receipts_in_static_files(v);
+        }
+        if let Some(v) = self.static_files.transaction_senders {
+            s = s.with_transaction_senders_in_static_files(v);
+        }
+        if let Some(v) = self.static_files.account_changesets {
+            s = s.with_account_changesets_in_static_files(v);
+        }
+        if let Some(v) = self.static_files.storage_changesets {
+            s = s.with_storage_changesets_in_static_files(v);
+        }
+
+        // Apply rocksdb overrides
+        // --rocksdb.all sets all rocksdb flags to true
+        if self.rocksdb.all {
+            s = s
+                .with_transaction_hash_numbers_in_rocksdb(true)
+                .with_storages_history_in_rocksdb(true)
+                .with_account_history_in_rocksdb(true);
+        }
+
+        // Individual rocksdb flags override --rocksdb.all when explicitly set
+        if let Some(v) = self.rocksdb.tx_hash {
+            s = s.with_transaction_hash_numbers_in_rocksdb(v);
+        }
+        if let Some(v) = self.rocksdb.storages_history {
+            s = s.with_storages_history_in_rocksdb(v);
+        }
+        if let Some(v) = self.rocksdb.account_history {
+            s = s.with_account_history_in_rocksdb(v);
+        }
+
+        s
     }
 
     /// Returns the max block that the node should run to, looking it up from the network if
@@ -564,6 +606,7 @@ impl<ChainSpec> NodeConfig<ChainSpec> {
             era: self.era,
             static_files: self.static_files,
             rocksdb: self.rocksdb,
+            storage: self.storage,
         }
     }
 
@@ -606,6 +649,7 @@ impl<ChainSpec> Clone for NodeConfig<ChainSpec> {
             era: self.era.clone(),
             static_files: self.static_files,
             rocksdb: self.rocksdb,
+            storage: self.storage,
         }
     }
 }