feat(cli): make storage v2 default for new nodes

.changelog/odd-frogs-break.md

@@ -0,0 +1,7 @@
+---
+reth-cli-commands: minor
+reth-node-core: minor
+reth: patch
+---
+
+Made v2 storage the default for all new databases, deprecating the `--storage.v2` flag to a hidden no-op kept for backwards compatibility. Updated CLI reference docs to remove the now-hidden flag from all command help pages.

crates/cli/commands/src/common.rs

@@ -73,17 +73,12 @@ pub struct EnvironmentArgs<C: ChainSpecParser> {
 }
 
 impl<C: ChainSpecParser> EnvironmentArgs<C> {
-    /// Returns the effective storage settings derived from `--storage.v2`.
+    /// Returns the storage settings for new database initialization.
     ///
-    /// The base storage mode is determined by `--storage.v2`:
-    /// - When `--storage.v2` is set: uses [`StorageSettings::v2()`] defaults
-    /// - Otherwise: uses [`StorageSettings::base()`] defaults
+    /// Always returns [`StorageSettings::v2()`] — v2 is the default for all new
+    /// databases. Existing databases use the settings persisted in their metadata.
     pub fn storage_settings(&self) -> StorageSettings {
-        if self.storage.v2 {
-            StorageSettings::v2()
-        } else {
-            StorageSettings::base()
-        }
+        StorageSettings::v2()
     }
 
     /// Initializes environment according to [`AccessRights`] and returns an instance of

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

@@ -4,26 +4,20 @@ use clap::{ArgAction, Args};
 
 /// Parameters for storage configuration.
 ///
-/// This controls whether the node uses v2 storage defaults (with `RocksDB` and static file
-/// optimizations) or v1/legacy storage defaults.
+/// V2 storage is now the default for all new databases. The `--storage.v2` flag is
+/// accepted for backwards compatibility but has no effect — v2 is always used.
+///
+/// Existing databases always use the settings persisted in their metadata.
 ///
 /// Individual storage settings can be overridden with `--static-files.*` and `--rocksdb.*` flags.
 #[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.
+    /// Deprecated no-op: v2 storage is now always enabled for new databases.
     ///
-    /// Individual settings can still be overridden with `--static-files.*` and `--rocksdb.*`
-    /// flags.
-    #[arg(long = "storage.v2", action = ArgAction::SetTrue)]
+    /// Kept for backwards compatibility with existing scripts and configurations.
+    /// Existing databases always use the settings persisted in their metadata.
+    #[arg(long = "storage.v2", action = ArgAction::SetTrue, hide = true)]
     pub v2: bool,
 }
 
@@ -41,14 +35,13 @@ mod tests {
 
     #[test]
     fn test_default_storage_args() {
-        let default_args = StorageArgs::default();
         let args = CommandParser::<StorageArgs>::parse_from(["reth"]).args;
-        assert_eq!(args, default_args);
-        assert!(!args.v2);
+        assert_eq!(args, StorageArgs::default());
     }
 
     #[test]
-    fn test_parse_v2_flag() {
+    fn test_parse_v2_flag_accepted() {
+        // Flag is accepted for backwards compatibility but is a no-op
         let args = CommandParser::<StorageArgs>::parse_from(["reth", "--storage.v2"]).args;
         assert!(args.v2);
     }

crates/node/core/src/node_config.rs

@@ -371,17 +371,16 @@ impl<ChainSpec> NodeConfig<ChainSpec> {
         self.pruning.prune_config(&self.chain)
     }
 
-    /// Returns the effective storage settings derived from `--storage.v2`.
+    /// Returns the effective storage settings for this node.
     ///
-    /// The base storage mode is determined by `--storage.v2`:
-    /// - When `--storage.v2` is set: uses [`StorageSettings::v2()`] defaults
-    /// - Otherwise: uses [`StorageSettings::base()`] defaults
+    /// Always returns [`StorageSettings::v2()`] — v2 storage is the default for
+    /// new nodes. Existing nodes retain whatever settings are persisted in their
+    /// database metadata (checked during genesis init).
+    ///
+    /// Existing databases retain whatever settings are persisted in their
+    /// metadata (checked during genesis init).
     pub const fn storage_settings(&self) -> StorageSettings {
-        if self.storage.v2 {
-            StorageSettings::v2()
-        } else {
-            StorageSettings::base()
-        }
+        StorageSettings::v2()
     }
 
     /// Returns the max block that the node should run to, looking it up from the network if

docs/vocs/docs/pages/cli/reth/db.mdx

@@ -131,16 +131,6 @@ Static Files:
       --static-files.blocks-per-file.storage-change-sets <BLOCKS_PER_FILE_STORAGE_CHANGE_SETS>
           Number of blocks per file for the storage changesets segment
 
-Storage:
-      --storage.v2
-          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.
-
 Logging:
       --log.stdout.format <FORMAT>
           The format to use for logs written to stdout

docs/vocs/docs/pages/cli/reth/download.mdx

@@ -112,15 +112,6 @@ Static Files:
           Number of blocks per file for the storage changesets segment
 
 Storage:
-      --storage.v2
-          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.
-
   -u, --url <URL>
           Specify a snapshot URL or let the command propose a default one.
 

docs/vocs/docs/pages/cli/reth/export-era.mdx

@@ -112,15 +112,6 @@ Static Files:
           Number of blocks per file for the storage changesets segment
 
 Storage:
-      --storage.v2
-          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.
-
       --first-block-number <first-block-number>
           Optional first block number to export from the db.
           It is by default 0.

docs/vocs/docs/pages/cli/reth/import-era.mdx

@@ -112,15 +112,6 @@ Static Files:
           Number of blocks per file for the storage changesets segment
 
 Storage:
-      --storage.v2
-          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.
-
       --path <IMPORT_ERA_PATH>
           The path to a directory for import.
 

docs/vocs/docs/pages/cli/reth/import.mdx

@@ -112,15 +112,6 @@ Static Files:
           Number of blocks per file for the storage changesets segment
 
 Storage:
-      --storage.v2
-          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.
-
       --no-state
           Disables stages that require state.
 

docs/vocs/docs/pages/cli/reth/init-state.mdx

@@ -112,15 +112,6 @@ Static Files:
           Number of blocks per file for the storage changesets segment
 
 Storage:
-      --storage.v2
-          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.
-
       --without-evm
           Specifies whether to initialize the state without relying on EVM historical data.
 

docs/vocs/docs/pages/cli/reth/init.mdx

@@ -111,16 +111,6 @@ Static Files:
       --static-files.blocks-per-file.storage-change-sets <BLOCKS_PER_FILE_STORAGE_CHANGE_SETS>
           Number of blocks per file for the storage changesets segment
 
-Storage:
-      --storage.v2
-          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.
-
 Logging:
       --log.stdout.format <FORMAT>
           The format to use for logs written to stdout

docs/vocs/docs/pages/cli/reth/node.mdx

@@ -1051,16 +1051,6 @@ Static Files:
       --static-files.blocks-per-file.storage-change-sets <BLOCKS_PER_FILE_STORAGE_CHANGE_SETS>
           Number of blocks per file for the storage changesets segment
 
-Storage:
-      --storage.v2
-          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.
-
 Logging:
       --log.stdout.format <FORMAT>
           The format to use for logs written to stdout

docs/vocs/docs/pages/cli/reth/prune.mdx

@@ -111,16 +111,6 @@ Static Files:
       --static-files.blocks-per-file.storage-change-sets <BLOCKS_PER_FILE_STORAGE_CHANGE_SETS>
           Number of blocks per file for the storage changesets segment
 
-Storage:
-      --storage.v2
-          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.
-
 Metrics:
       --metrics <PROMETHEUS>
           Enable Prometheus metrics.

docs/vocs/docs/pages/cli/reth/re-execute.mdx

@@ -112,15 +112,6 @@ Static Files:
           Number of blocks per file for the storage changesets segment
 
 Storage:
-      --storage.v2
-          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.
-
       --from <FROM>
           The height to start at
 

docs/vocs/docs/pages/cli/reth/stage/drop.mdx

@@ -112,15 +112,6 @@ Static Files:
           Number of blocks per file for the storage changesets segment
 
 Storage:
-      --storage.v2
-          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.
-
   <STAGE>
           Possible values:
           - headers:         The headers stage within the pipeline

docs/vocs/docs/pages/cli/reth/stage/dump.mdx

@@ -118,16 +118,6 @@ Static Files:
       --static-files.blocks-per-file.storage-change-sets <BLOCKS_PER_FILE_STORAGE_CHANGE_SETS>
           Number of blocks per file for the storage changesets segment
 
-Storage:
-      --storage.v2
-          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.
-
 Logging:
       --log.stdout.format <FORMAT>
           The format to use for logs written to stdout

docs/vocs/docs/pages/cli/reth/stage/run.mdx

@@ -112,15 +112,6 @@ Static Files:
           Number of blocks per file for the storage changesets segment
 
 Storage:
-      --storage.v2
-          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.
-
       --metrics <SOCKET>
           Enable Prometheus metrics.
 

docs/vocs/docs/pages/cli/reth/stage/unwind.mdx

@@ -117,15 +117,6 @@ Static Files:
           Number of blocks per file for the storage changesets segment
 
 Storage:
-      --storage.v2
-          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.
-
       --offline
           If this is enabled, then all stages except headers, bodies, and sender recovery will be unwound