fix: regenerate CLI docs and fix clippy doc_markdown lint

- Regenerate CLI documentation after Option<bool> change for RocksDB flags - Add backticks around RocksDB in doc comment for clippy::doc_markdown
feat(storage): add init_genesis_with_overrides for startup validation
2026-04-30 03:01:58 -04:00 · 2026-01-19 15:24:57 +00:00 · 2026-01-19 14:17:44 +00:00 · 2026-01-19 14:12:30 +00:00 · 2026-01-19 14:12:23 +00:00 · 2026-01-19 09:49:18 +00:00
37 changed files with 878 additions and 71 deletions
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2125,9 +2125,9 @@ dependencies = [

 [[package]]
 name = "cc"
-version = "1.2.52"
+version = "1.2.53"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cd4932aefd12402b36c60956a4fe0035421f544799057659ff86f923657aada3"
+checksum = "755d2fce177175ffca841e9a06afdb2c4ab0f593d53b4dee48147dfaade85932"
 dependencies = [
 "find-msvc-tools",
 "jobserver",
@@ -4075,9 +4075,9 @@ dependencies = [

 [[package]]
 name = "find-msvc-tools"
-version = "0.1.7"
+version = "0.1.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f449e6c6c08c865631d4890cfacf252b3d396c9bcc83adb6623cdb02a8336c41"
+checksum = "8591b0bcc8a98a64310a2fae1bb3e9b8564dd10e381e6e28010fde8e8e8568db"

 [[package]]
 name = "fixed-cache"
@@ -5122,9 +5122,9 @@ dependencies = [

 [[package]]
 name = "insta"
-version = "1.46.0"
+version = "1.46.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1b66886d14d18d420ab5052cbff544fc5d34d0b2cdd35eb5976aaa10a4a472e5"
+checksum = "248b42847813a1550dafd15296fd9748c651d0c32194559dbc05d804d54b21e8"
 dependencies = [
 "console",
 "once_cell",
@@ -5307,9 +5307,9 @@ dependencies = [

 [[package]]
 name = "js-sys"
-version = "0.3.83"
+version = "0.3.85"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "464a3709c7f55f1f721e5389aa6ea4e3bc6aba669353300af094b29ffbdde1d8"
+checksum = "8c942ebf8e95485ca0d52d97da7c5a2c387d0e7f0ba4c35e93bfcaee045955b3"
 dependencies = [
 "once_cell",
 "wasm-bindgen",
@@ -11724,9 +11724,9 @@ checksum = "48fd7bd8a6377e15ad9d42a8ec25371b94ddc67abe7c8b9127bec79bebaaae18"

 [[package]]
 name = "rustc-demangle"
-version = "0.1.26"
+version = "0.1.27"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "56f7d92ca342cea22a06f2121d944b4fd82af56988c270852495420f961d4ace"
+checksum = "b50b8869d9fc858ce7266cce0194bd74df58b9d0e3f6df3a9fc8eb470d95c09d"

 [[package]]
 name = "rustc-hash"
@@ -11825,9 +11825,9 @@ dependencies = [

 [[package]]
 name = "rustls-pki-types"
-version = "1.13.2"
+version = "1.14.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "21e6f2ab2928ca4291b86736a8bd920a277a399bba1589409d72154ff87c1282"
+checksum = "be040f8b0a225e40375822a563fa9524378b9d63112f53e19ffff34df5d33fdd"
 dependencies = [
 "web-time",
 "zeroize",
@@ -11862,9 +11862,9 @@ checksum = "f87165f0995f63a9fbeea62b64d10b4d9d8e78ec6d7d51fb2125fda7bb36788f"

 [[package]]
 name = "rustls-webpki"
-version = "0.103.8"
+version = "0.103.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2ffdfa2f5286e2247234e03f680868ac2815974dc39e00ea15adc445d0aafe52"
+checksum = "d7df23109aa6c1567d1c575b9952556388da57401e4ace1d15f79eedad0d8f53"
 dependencies = [
 "ring",
 "rustls-pki-types",
@@ -13753,18 +13753,18 @@ checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"

 [[package]]
 name = "wasip2"
-version = "1.0.1+wasi-0.2.4"
+version = "1.0.2+wasi-0.2.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0562428422c63773dad2c345a1882263bbf4d65cf3f42e90921f787ef5ad58e7"
+checksum = "9517f9239f02c069db75e65f174b3da828fe5f5b945c4dd26bd25d89c03ebcf5"
 dependencies = [
 "wit-bindgen",
 ]

 [[package]]
 name = "wasm-bindgen"
-version = "0.2.106"
+version = "0.2.108"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0d759f433fa64a2d763d1340820e46e111a7a5ab75f993d1852d70b03dbb80fd"
+checksum = "64024a30ec1e37399cf85a7ffefebdb72205ca1c972291c51512360d90bd8566"
 dependencies = [
 "cfg-if",
 "once_cell",
@@ -13775,11 +13775,12 @@ dependencies = [

 [[package]]
 name = "wasm-bindgen-futures"
-version = "0.4.56"
+version = "0.4.58"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "836d9622d604feee9e5de25ac10e3ea5f2d65b41eac0d9ce72eb5deae707ce7c"
+checksum = "70a6e77fd0ae8029c9ea0063f87c46fde723e7d887703d74ad2616d792e51e6f"
 dependencies = [
 "cfg-if",
+ "futures-util",
 "js-sys",
 "once_cell",
 "wasm-bindgen",
@@ -13788,9 +13789,9 @@ dependencies = [

 [[package]]
 name = "wasm-bindgen-macro"
-version = "0.2.106"
+version = "0.2.108"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "48cb0d2638f8baedbc542ed444afc0644a29166f1595371af4fecf8ce1e7eeb3"
+checksum = "008b239d9c740232e71bd39e8ef6429d27097518b6b30bdf9086833bd5b6d608"
 dependencies = [
 "quote",
 "wasm-bindgen-macro-support",
@@ -13798,9 +13799,9 @@ dependencies = [

 [[package]]
 name = "wasm-bindgen-macro-support"
-version = "0.2.106"
+version = "0.2.108"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cefb59d5cd5f92d9dcf80e4683949f15ca4b511f4ac0a6e14d4e1ac60c6ecd40"
+checksum = "5256bae2d58f54820e6490f9839c49780dff84c65aeab9e772f15d5f0e913a55"
 dependencies = [
 "bumpalo",
 "proc-macro2",
@@ -13811,9 +13812,9 @@ dependencies = [

 [[package]]
 name = "wasm-bindgen-shared"
-version = "0.2.106"
+version = "0.2.108"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cbc538057e648b67f72a982e708d485b2efa771e1ac05fec311f9f63e5800db4"
+checksum = "1f01b580c9ac74c8d8f0c0e4afb04eeef2acf145458e52c03845ee9cd23e3d12"
 dependencies = [
 "unicode-ident",
 ]
@@ -13847,9 +13848,9 @@ dependencies = [

 [[package]]
 name = "web-sys"
-version = "0.3.83"
+version = "0.3.85"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9b32828d774c412041098d182a8b38b16ea816958e07cf40eec2bc080ae137ac"
+checksum = "312e32e551d92129218ea9a2452120f4aabc03529ef03e4d0d82fb2780608598"
 dependencies = [
 "js-sys",
 "wasm-bindgen",
@@ -14419,9 +14420,9 @@ dependencies = [

 [[package]]
 name = "wit-bindgen"
-version = "0.46.0"
+version = "0.51.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f17a85883d4e6d00e8a97c586de764dabcc06133f7f1d55dce5cdc070ad7fe59"
+checksum = "d7249219f66ced02969388cf2bb044a09756a083d0fab1e566056b04d9fbcaa5"

 [[package]]
 name = "write16"
@@ -14605,9 +14606,9 @@ dependencies = [

 [[package]]
 name = "zmij"
-version = "1.0.14"
+version = "1.0.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bd8f3f50b848df28f887acb68e41201b5aea6bc8a8dacc00fb40635ff9a72fea"
+checksum = "94f63c051f4fe3c1509da62131a678643c5b6fbdc9273b2b79d4378ebda003d2"

 [[package]]
 name = "zstd"
--- a/crates/cli/commands/src/common.rs
+++ b/crates/cli/commands/src/common.rs
@@ -9,7 +9,7 @@ use reth_cli::chainspec::ChainSpecParser;
 use reth_config::{config::EtlConfig, Config};
 use reth_consensus::noop::NoopConsensus;
 use reth_db::{init_db, open_db_read_only, DatabaseEnv};
-use reth_db_common::init::init_genesis_with_settings;
+use reth_db_common::init::init_genesis_with_overrides;
 use reth_downloaders::{bodies::noop::NoopBodiesDownloader, headers::noop::NoopHeaderDownloader};
 use reth_eth_wire::NetPrimitivesFor;
 use reth_evm::{noop::NoopEvmConfig, ConfigureEvm};
@@ -19,7 +19,7 @@ use reth_node_builder::{
    Node, NodeComponents, NodeComponentsBuilder, NodeTypes, NodeTypesWithDBAdapter,
 };
 use reth_node_core::{
-    args::{DatabaseArgs, DatadirArgs, StaticFilesArgs},
+    args::{DatabaseArgs, DatadirArgs, StorageArgs},
    dirs::{ChainPath, DataDirPath},
 };
 use reth_provider::{
@@ -27,7 +27,7 @@ use reth_provider::{
        BlockchainProvider, NodeTypesForProvider, RocksDBProvider, StaticFileProvider,
        StaticFileProviderBuilder,
    },
-    ProviderFactory, StaticFileProviderFactory,
+    ProviderFactory, StaticFileProviderFactory, StorageSettings,
 };
 use reth_stages::{sets::DefaultStages, Pipeline, PipelineTarget};
 use reth_static_file::StaticFileProducer;
@@ -63,9 +63,9 @@ pub struct EnvironmentArgs<C: ChainSpecParser> {
    #[command(flatten)]
    pub db: DatabaseArgs,

-    /// All static files related arguments
+    /// All storage related arguments (static files + RocksDB tables)
    #[command(flatten)]
-    pub static_files: StaticFilesArgs,
+    pub storage: StorageArgs,
 }

 impl<C: ChainSpecParser> EnvironmentArgs<C> {
@@ -131,7 +131,9 @@ impl<C: ChainSpecParser> EnvironmentArgs<C> {
            self.create_provider_factory(&config, db, sfp, rocksdb_provider, access)?;
        if access.is_read_write() {
            debug!(target: "reth::cli", chain=%self.chain.chain(), genesis=?self.chain.genesis_hash(), "Initializing genesis");
-            init_genesis_with_settings(&provider_factory, self.static_files.to_settings())?;
+            let overrides = self.storage.to_overrides();
+            let settings = self.storage.to_settings(StorageSettings::legacy());
+            init_genesis_with_overrides(&provider_factory, settings, overrides)?;
        }

        Ok(Environment { config, provider_factory, data_dir })
--- a/crates/cli/commands/src/node.rs
+++ b/crates/cli/commands/src/node.rs
@@ -10,7 +10,7 @@ use reth_node_builder::NodeBuilder;
 use reth_node_core::{
    args::{
        DatabaseArgs, DatadirArgs, DebugArgs, DevArgs, EngineArgs, EraArgs, MetricArgs,
-        NetworkArgs, PayloadBuilderArgs, PruningArgs, RpcServerArgs, StaticFilesArgs, TxPoolArgs,
+        NetworkArgs, PayloadBuilderArgs, PruningArgs, RpcServerArgs, StorageArgs, TxPoolArgs,
    },
    node_config::NodeConfig,
    version,
@@ -110,9 +110,9 @@ pub struct NodeCommand<C: ChainSpecParser, Ext: clap::Args + fmt::Debug = NoArgs
    #[command(flatten, next_help_heading = "ERA")]
    pub era: EraArgs,

-    /// All static files related arguments
-    #[command(flatten, next_help_heading = "Static Files")]
-    pub static_files: StaticFilesArgs,
+    /// All storage related arguments (static files + RocksDB tables)
+    #[command(flatten)]
+    pub storage: StorageArgs,

    /// Additional cli arguments
    #[command(flatten, next_help_heading = "Extension")]
@@ -168,7 +168,7 @@ where
            pruning,
            engine,
            era,
-            static_files,
+            storage,
            ext,
        } = self;

@@ -189,7 +189,7 @@ where
            pruning,
            engine,
            era,
-            static_files,
+            storage,
        };

        let data_dir = node_config.datadir();
--- a/crates/node/builder/src/launch/common.rs
+++ b/crates/node/builder/src/launch/common.rs
@@ -42,7 +42,7 @@ use reth_chainspec::{Chain, EthChainSpec, EthereumHardforks};
 use reth_config::{config::EtlConfig, PruneConfig};
 use reth_consensus::noop::NoopConsensus;
 use reth_db_api::{database::Database, database_metrics::DatabaseMetrics};
-use reth_db_common::init::{init_genesis_with_settings, InitStorageError};
+use reth_db_common::init::{init_genesis_with_overrides, InitStorageError};
 use reth_downloaders::{bodies::noop::NoopBodiesDownloader, headers::noop::NoopHeaderDownloader};
 use reth_engine_local::MiningMode;
 use reth_evm::{noop::NoopEvmConfig, ConfigureEvm};
@@ -68,7 +68,7 @@ use reth_provider::{
    providers::{NodeTypesForProvider, ProviderNodeTypes, RocksDBProvider, StaticFileProvider},
    BlockHashReader, BlockNumReader, DatabaseProviderFactory, ProviderError, ProviderFactory,
    ProviderResult, RocksDBProviderFactory, StageCheckpointReader, StaticFileProviderBuilder,
-    StaticFileProviderFactory,
+    StaticFileProviderFactory, StorageSettings,
 };
 use reth_prune::{PruneModes, PrunerBuilder};
 use reth_rpc_builder::config::RethRpcServerConfig;
@@ -171,8 +171,10 @@ impl LaunchContext {
        toml_config.peers.trusted_nodes_only = config.network.trusted_only;

        // Merge static file CLI arguments with config file, giving priority to CLI
-        toml_config.static_files =
-            config.static_files.merge_with_config(toml_config.static_files, config.pruning.minimal);
+        toml_config.static_files = config
+            .storage
+            .static_files
+            .merge_with_config(toml_config.static_files, config.pruning.minimal);

        Ok(toml_config)
    }
@@ -676,19 +678,19 @@ where

    /// Convenience function to [`Self::init_genesis`]
    pub fn with_genesis(self) -> Result<Self, InitStorageError> {
-        init_genesis_with_settings(
-            self.provider_factory(),
-            self.node_config().static_files.to_settings(),
-        )?;
+        self.init_genesis()?;
        Ok(self)
    }

-    /// Write the genesis block and state if it has not already been written
+    /// Write the genesis block and state if it has not already been written.
+    ///
+    /// Validates that any explicitly set CLI storage flags match the stored settings.
    pub fn init_genesis(&self) -> Result<B256, InitStorageError> {
-        init_genesis_with_settings(
-            self.provider_factory(),
-            self.node_config().static_files.to_settings(),
-        )
+        let storage_args = &self.node_config().storage;
+        let overrides = storage_args.to_overrides();
+        let settings = storage_args.to_settings(StorageSettings::legacy());
+
+        init_genesis_with_overrides(self.provider_factory(), settings, overrides)
    }

    /// Creates a new `WithMeteredProvider` container and attaches it to the
--- a/crates/node/core/src/args/mod.rs
+++ b/crates/node/core/src/args/mod.rs
@@ -80,5 +80,9 @@ pub use era::{DefaultEraHost, EraArgs, EraSourceArgs};
 mod static_files;
 pub use static_files::{StaticFilesArgs, MINIMAL_BLOCKS_PER_FILE};

+/// `StorageArgs` for configuring storage (static files + RocksDB tables).
+mod storage;
+pub use storage::StorageArgs;
+
 mod error;
 pub mod types;
--- a/crates/node/core/src/args/storage.rs
+++ b/crates/node/core/src/args/storage.rs
@@ -0,0 +1,71 @@
+//! clap [Args](clap::Args) for storage configuration (static files + RocksDB tables)
+
+use clap::{ArgAction, Args};
+use reth_provider::{StorageSettings, StorageSettingsOverrides};
+
+use super::StaticFilesArgs;
+
+/// Parameters for storage configuration
+#[derive(Debug, Args, PartialEq, Eq, Default, Clone, Copy)]
+#[command(next_help_heading = "Storage")]
+pub struct StorageArgs {
+    /// Static files related flags.
+    #[command(flatten)]
+    pub static_files: StaticFilesArgs,
+
+    /// Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+    ///
+    /// 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 = "storage.tx-hash-in-rocksdb", action = ArgAction::Set)]
+    pub tx_hash_in_rocksdb: Option<bool>,
+
+    /// Store storages history in `RocksDB` instead of MDBX.
+    ///
+    /// 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 = "storage.storages-history-in-rocksdb", action = ArgAction::Set)]
+    pub storages_history_in_rocksdb: Option<bool>,
+
+    /// Store account history in `RocksDB` instead of MDBX.
+    ///
+    /// 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 = "storage.account-history-in-rocksdb", action = ArgAction::Set)]
+    pub account_history_in_rocksdb: Option<bool>,
+}
+
+impl StorageArgs {
+    /// Converts CLI storage arguments into [`StorageSettings`].
+    ///
+    /// Uses the provided default settings for any flags not explicitly set.
+    pub const fn to_settings(&self, defaults: StorageSettings) -> StorageSettings {
+        let base = self.static_files.to_settings();
+
+        let tx_hash = match self.tx_hash_in_rocksdb {
+            Some(v) => v,
+            None => defaults.transaction_hash_numbers_in_rocksdb,
+        };
+        let storages_history = match self.storages_history_in_rocksdb {
+            Some(v) => v,
+            None => defaults.storages_history_in_rocksdb,
+        };
+        let account_history = match self.account_history_in_rocksdb {
+            Some(v) => v,
+            None => defaults.account_history_in_rocksdb,
+        };
+
+        base.with_transaction_hash_numbers_in_rocksdb(tx_hash)
+            .with_storages_history_in_rocksdb(storages_history)
+            .with_account_history_in_rocksdb(account_history)
+    }
+
+    /// Returns the overrides for `RocksDB` settings that were explicitly set via CLI.
+    pub const fn to_overrides(&self) -> StorageSettingsOverrides {
+        StorageSettingsOverrides {
+            transaction_hash_numbers_in_rocksdb: self.tx_hash_in_rocksdb,
+            storages_history_in_rocksdb: self.storages_history_in_rocksdb,
+            account_history_in_rocksdb: self.account_history_in_rocksdb,
+        }
+    }
+}
--- a/crates/node/core/src/node_config.rs
+++ b/crates/node/core/src/node_config.rs
@@ -3,7 +3,7 @@
 use crate::{
    args::{
        DatabaseArgs, DatadirArgs, DebugArgs, DevArgs, EngineArgs, NetworkArgs, PayloadBuilderArgs,
-        PruningArgs, RpcServerArgs, StaticFilesArgs, TxPoolArgs,
+        PruningArgs, RpcServerArgs, StorageArgs, TxPoolArgs,
    },
    dirs::{ChainPath, DataDirPath},
    utils::get_single_header,
@@ -148,8 +148,8 @@ pub struct NodeConfig<ChainSpec> {
    /// All ERA import related arguments with --era prefix
    pub era: EraArgs,

-    /// All static files related arguments
-    pub static_files: StaticFilesArgs,
+    /// All storage related arguments (static files + `RocksDB` tables)
+    pub storage: StorageArgs,
 }

 impl NodeConfig<ChainSpec> {
@@ -180,7 +180,7 @@ impl<ChainSpec> NodeConfig<ChainSpec> {
            datadir: DatadirArgs::default(),
            engine: EngineArgs::default(),
            era: EraArgs::default(),
-            static_files: StaticFilesArgs::default(),
+            storage: StorageArgs::default(),
        }
    }

@@ -254,7 +254,7 @@ impl<ChainSpec> NodeConfig<ChainSpec> {
            pruning,
            engine,
            era,
-            static_files,
+            storage,
            ..
        } = self;
        NodeConfig {
@@ -273,7 +273,7 @@ impl<ChainSpec> NodeConfig<ChainSpec> {
            pruning,
            engine,
            era,
-            static_files,
+            storage,
        }
    }

@@ -543,7 +543,7 @@ impl<ChainSpec> NodeConfig<ChainSpec> {
            pruning: self.pruning,
            engine: self.engine,
            era: self.era,
-            static_files: self.static_files,
+            storage: self.storage,
        }
    }

@@ -584,7 +584,7 @@ impl<ChainSpec> Clone for NodeConfig<ChainSpec> {
            datadir: self.datadir.clone(),
            engine: self.engine.clone(),
            era: self.era.clone(),
-            static_files: self.static_files,
+            storage: self.storage,
        }
    }
 }
--- a/crates/storage/db-api/src/models/metadata.rs
+++ b/crates/storage/db-api/src/models/metadata.rs
@@ -108,4 +108,120 @@ impl StorageSettings {
            self.account_history_in_rocksdb ||
            self.storages_history_in_rocksdb
    }
+
+    /// Validates that the given overrides match this settings.
+    ///
+    /// Returns `Ok(())` if all explicitly set overrides match, or an error describing
+    /// the mismatches.
+    pub fn validate_overrides(
+        &self,
+        overrides: &StorageSettingsOverrides,
+    ) -> Result<(), StorageSettingsMismatch> {
+        let mut mismatches = Vec::new();
+
+        if let Some(cli_value) = overrides
+            .transaction_hash_numbers_in_rocksdb
+            .filter(|&v| v != self.transaction_hash_numbers_in_rocksdb)
+        {
+            mismatches.push(SettingMismatch {
+                name: "transaction_hash_numbers_in_rocksdb",
+                flag: "--storage.tx-hash-in-rocksdb",
+                db_value: self.transaction_hash_numbers_in_rocksdb,
+                cli_value,
+            });
+        }
+
+        if let Some(cli_value) =
+            overrides.storages_history_in_rocksdb.filter(|&v| v != self.storages_history_in_rocksdb)
+        {
+            mismatches.push(SettingMismatch {
+                name: "storages_history_in_rocksdb",
+                flag: "--storage.storages-history-in-rocksdb",
+                db_value: self.storages_history_in_rocksdb,
+                cli_value,
+            });
+        }
+
+        if let Some(cli_value) =
+            overrides.account_history_in_rocksdb.filter(|&v| v != self.account_history_in_rocksdb)
+        {
+            mismatches.push(SettingMismatch {
+                name: "account_history_in_rocksdb",
+                flag: "--storage.account-history-in-rocksdb",
+                db_value: self.account_history_in_rocksdb,
+                cli_value,
+            });
+        }
+
+        if mismatches.is_empty() {
+            Ok(())
+        } else {
+            Err(StorageSettingsMismatch { mismatches })
+        }
+    }
 }
+
+/// Overrides for storage settings that were explicitly set via CLI.
+///
+/// `None` means the flag was not provided (use DB value), `Some(v)` means the user
+/// explicitly requested this value.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub struct StorageSettingsOverrides {
+    /// Override for `transaction_hash_numbers_in_rocksdb`.
+    pub transaction_hash_numbers_in_rocksdb: Option<bool>,
+    /// Override for `storages_history_in_rocksdb`.
+    pub storages_history_in_rocksdb: Option<bool>,
+    /// Override for `account_history_in_rocksdb`.
+    pub account_history_in_rocksdb: Option<bool>,
+}
+
+impl StorageSettingsOverrides {
+    /// Returns `true` if any override is set.
+    pub const fn any_set(&self) -> bool {
+        self.transaction_hash_numbers_in_rocksdb.is_some() ||
+            self.storages_history_in_rocksdb.is_some() ||
+            self.account_history_in_rocksdb.is_some()
+    }
+}
+
+/// A single setting mismatch between CLI and DB.
+#[derive(Debug, Clone)]
+pub struct SettingMismatch {
+    /// The setting name.
+    pub name: &'static str,
+    /// The CLI flag name.
+    pub flag: &'static str,
+    /// The value stored in the database.
+    pub db_value: bool,
+    /// The value provided via CLI.
+    pub cli_value: bool,
+}
+
+/// Error when CLI storage settings don't match database settings.
+#[derive(Debug, Clone)]
+pub struct StorageSettingsMismatch {
+    /// The list of mismatched settings.
+    pub mismatches: Vec<SettingMismatch>,
+}
+
+impl std::fmt::Display for StorageSettingsMismatch {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        writeln!(
+            f,
+            "Storage settings mismatch: database was initialized with different RocksDB storage layout."
+        )?;
+        writeln!(f)?;
+        writeln!(f, "Conflicts:")?;
+        for m in &self.mismatches {
+            writeln!(f, "  - {} {}: db={}, cli={}", m.flag, m.name, m.db_value, m.cli_value)?;
+        }
+        writeln!(f)?;
+        writeln!(f, "These flags are genesis-only. To proceed:")?;
+        writeln!(f, "  1) Remove the conflicting CLI flags (recommended), or")?;
+        writeln!(f, "  2) Wipe the database and re-sync with the desired flags.")?;
+        writeln!(f)?;
+        write!(f, "Inspect current DB settings: `reth db settings get`")
+    }
+}
+
+impl std::error::Error for StorageSettingsMismatch {}
--- a/crates/storage/db-common/src/init.rs
+++ b/crates/storage/db-common/src/init.rs
@@ -15,9 +15,10 @@ use reth_primitives_traits::{
 use reth_provider::{
    errors::provider::ProviderResult, providers::StaticFileWriter, BlockHashReader, BlockNumReader,
    BundleStateInit, ChainSpecProvider, DBProvider, DatabaseProviderFactory, ExecutionOutcome,
-    HashingWriter, HeaderProvider, HistoryWriter, MetadataWriter, OriginalValuesKnown,
-    ProviderError, RevertsInit, StageCheckpointReader, StageCheckpointWriter, StateWriteConfig,
-    StateWriter, StaticFileProviderFactory, StorageSettings, StorageSettingsCache, TrieWriter,
+    HashingWriter, HeaderProvider, HistoryWriter, MetadataProvider, MetadataWriter,
+    OriginalValuesKnown, ProviderError, RevertsInit, StageCheckpointReader, StageCheckpointWriter,
+    StateWriteConfig, StateWriter, StaticFileProviderFactory, StorageSettings,
+    StorageSettingsCache, StorageSettingsMismatch, StorageSettingsOverrides, TrieWriter,
 };
 use reth_stages_types::{StageCheckpoint, StageId};
 use reth_static_file_types::StaticFileSegment;
@@ -75,6 +76,15 @@ pub enum InitStorageError {
    /// State root doesn't match the expected one.
    #[error("state root mismatch: {_0}")]
    StateRootMismatch(GotExpected<B256>),
+    /// CLI storage settings don't match the stored database settings.
+    #[error("{_0}")]
+    StorageSettingsMismatch(StorageSettingsMismatch),
+}
+
+impl From<StorageSettingsMismatch> for InitStorageError {
+    fn from(error: StorageSettingsMismatch) -> Self {
+        Self::StorageSettingsMismatch(error)
+    }
 }

 impl From<DatabaseError> for InitStorageError {
@@ -92,6 +102,7 @@ where
        + StageCheckpointReader
        + BlockHashReader
        + StorageSettingsCache,
+    PF::Provider: MetadataProvider,
    PF::ProviderRW: StaticFileProviderFactory<Primitives = PF::Primitives>
        + StageCheckpointWriter
        + HistoryWriter
@@ -100,6 +111,7 @@ where
        + StateWriter
        + TrieWriter
        + MetadataWriter
+        + MetadataProvider
        + ChainSpecProvider
        + AsRef<PF::ProviderRW>,
    PF::ChainSpec: EthChainSpec<Header = <PF::Primitives as NodePrimitives>::BlockHeader>,
@@ -115,6 +127,9 @@ where
 }

 /// Write the genesis block if it has not already been written with [`StorageSettings`].
+///
+/// This is a convenience wrapper around [`init_genesis_with_overrides`] that does not validate
+/// any CLI overrides against stored settings.
 pub fn init_genesis_with_settings<PF>(
    factory: &PF,
    genesis_storage_settings: StorageSettings,
@@ -126,6 +141,7 @@ where
        + StageCheckpointReader
        + BlockHashReader
        + StorageSettingsCache,
+    PF::Provider: MetadataProvider,
    PF::ProviderRW: StaticFileProviderFactory<Primitives = PF::Primitives>
        + StageCheckpointWriter
        + HistoryWriter
@@ -134,6 +150,44 @@ where
        + StateWriter
        + TrieWriter
        + MetadataWriter
+        + MetadataProvider
+        + ChainSpecProvider
+        + AsRef<PF::ProviderRW>,
+    PF::ChainSpec: EthChainSpec<Header = <PF::Primitives as NodePrimitives>::BlockHeader>,
+{
+    init_genesis_with_overrides(
+        factory,
+        genesis_storage_settings,
+        StorageSettingsOverrides::default(),
+    )
+}
+
+/// Write the genesis block if it has not already been written with [`StorageSettings`].
+///
+/// If the genesis block already exists, validates that any explicitly set CLI overrides
+/// match the stored settings. Returns an error if there's a mismatch.
+pub fn init_genesis_with_overrides<PF>(
+    factory: &PF,
+    genesis_storage_settings: StorageSettings,
+    overrides: StorageSettingsOverrides,
+) -> Result<B256, InitStorageError>
+where
+    PF: DatabaseProviderFactory
+        + StaticFileProviderFactory<Primitives: NodePrimitives<BlockHeader: Compact>>
+        + ChainSpecProvider
+        + StageCheckpointReader
+        + BlockHashReader
+        + StorageSettingsCache,
+    PF::Provider: MetadataProvider,
+    PF::ProviderRW: StaticFileProviderFactory<Primitives = PF::Primitives>
+        + StageCheckpointWriter
+        + HistoryWriter
+        + HeaderProvider
+        + HashingWriter
+        + StateWriter
+        + TrieWriter
+        + MetadataWriter
+        + MetadataProvider
        + ChainSpecProvider
        + AsRef<PF::ProviderRW>,
    PF::ChainSpec: EthChainSpec<Header = <PF::Primitives as NodePrimitives>::BlockHeader>,
@@ -159,6 +213,14 @@ where
                    return Err(InitStorageError::UninitializedDatabase)
                }

+                // Validate CLI overrides against stored settings if any are explicitly set
+                if overrides.any_set() {
+                    let provider = factory.database_provider_ro()?;
+                    let stored_settings =
+                        provider.storage_settings()?.unwrap_or_else(StorageSettings::legacy);
+                    stored_settings.validate_overrides(&overrides)?;
+                }
+
                debug!("Genesis already written, skipping.");
                return Ok(hash)
            }
--- a/crates/storage/provider/src/lib.rs
+++ b/crates/storage/provider/src/lib.rs
@@ -45,8 +45,9 @@ pub use revm_database::states::OriginalValuesKnown;
 // reexport traits to avoid breaking changes
 pub use reth_static_file_types as static_file;
 pub use reth_storage_api::{
-    HistoryWriter, MetadataProvider, MetadataWriter, StateWriteConfig, StatsReader,
-    StorageSettings, StorageSettingsCache,
+    HistoryWriter, MetadataProvider, MetadataWriter, SettingMismatch, StateWriteConfig,
+    StatsReader, StorageSettings, StorageSettingsCache, StorageSettingsMismatch,
+    StorageSettingsOverrides,
 };
 /// Re-export provider error.
 pub use reth_storage_errors::provider::{ProviderError, ProviderResult};
--- a/crates/storage/storage-api/src/lib.rs
+++ b/crates/storage/storage-api/src/lib.rs
@@ -101,7 +101,9 @@ pub mod metadata;
 #[cfg(feature = "db-api")]
 pub use metadata::{MetadataProvider, MetadataWriter, StorageSettingsCache};
 #[cfg(feature = "db-api")]
-pub use reth_db_api::models::StorageSettings;
+pub use reth_db_api::models::{
+    SettingMismatch, StorageSettings, StorageSettingsMismatch, StorageSettingsOverrides,
+};

 mod full;
 pub use full::*;
--- a/docs/vocs/docs/pages/cli/op-reth/db.mdx
+++ b/docs/vocs/docs/pages/cli/op-reth/db.mdx
@@ -145,6 +145,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
 Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout
--- a/docs/vocs/docs/pages/cli/op-reth/import-op.mdx
+++ b/docs/vocs/docs/pages/cli/op-reth/import-op.mdx
@@ -129,6 +129,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
      --chunk-len <CHUNK_LEN>
          Chunk byte length to read from file.

--- a/docs/vocs/docs/pages/cli/op-reth/import-receipts-op.mdx
+++ b/docs/vocs/docs/pages/cli/op-reth/import-receipts-op.mdx
@@ -129,6 +129,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
      --chunk-len <CHUNK_LEN>
          Chunk byte length to read from file.

--- a/docs/vocs/docs/pages/cli/op-reth/init-state.mdx
+++ b/docs/vocs/docs/pages/cli/op-reth/init-state.mdx
@@ -129,6 +129,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
      --without-evm
          Specifies whether to initialize the state without relying on EVM historical data.

--- a/docs/vocs/docs/pages/cli/op-reth/init.mdx
+++ b/docs/vocs/docs/pages/cli/op-reth/init.mdx
@@ -129,6 +129,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
 Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout
--- a/docs/vocs/docs/pages/cli/op-reth/node.mdx
+++ b/docs/vocs/docs/pages/cli/op-reth/node.mdx
@@ -1024,6 +1024,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
 Rollup:
      --rollup.sequencer <SEQUENCER>
          Endpoint for the sequencer mempool (can be both HTTP and WS)
--- a/docs/vocs/docs/pages/cli/op-reth/prune.mdx
+++ b/docs/vocs/docs/pages/cli/op-reth/prune.mdx
@@ -129,6 +129,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
 Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout
--- a/docs/vocs/docs/pages/cli/op-reth/re-execute.mdx
+++ b/docs/vocs/docs/pages/cli/op-reth/re-execute.mdx
@@ -129,6 +129,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
      --from <FROM>
          The height to start at

--- a/docs/vocs/docs/pages/cli/op-reth/stage/drop.mdx
+++ b/docs/vocs/docs/pages/cli/op-reth/stage/drop.mdx
@@ -129,6 +129,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
  <STAGE>
          Possible values:
          - headers:         The headers stage within the pipeline
--- a/docs/vocs/docs/pages/cli/op-reth/stage/dump.mdx
+++ b/docs/vocs/docs/pages/cli/op-reth/stage/dump.mdx
@@ -136,6 +136,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
 Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout
--- a/docs/vocs/docs/pages/cli/op-reth/stage/run.mdx
+++ b/docs/vocs/docs/pages/cli/op-reth/stage/run.mdx
@@ -129,6 +129,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
      --metrics <SOCKET>
          Enable Prometheus metrics.

--- a/docs/vocs/docs/pages/cli/op-reth/stage/unwind.mdx
+++ b/docs/vocs/docs/pages/cli/op-reth/stage/unwind.mdx
@@ -134,6 +134,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
      --offline
          If this is enabled, then all stages except headers, bodies, and sender recovery will be unwound

--- a/docs/vocs/docs/pages/cli/reth/db.mdx
+++ b/docs/vocs/docs/pages/cli/reth/db.mdx
@@ -145,6 +145,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
 Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout
--- a/docs/vocs/docs/pages/cli/reth/download.mdx
+++ b/docs/vocs/docs/pages/cli/reth/download.mdx
@@ -129,6 +129,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
  -u, --url <URL>
          Specify a snapshot URL or let the command propose a default one.

--- a/docs/vocs/docs/pages/cli/reth/export-era.mdx
+++ b/docs/vocs/docs/pages/cli/reth/export-era.mdx
@@ -129,6 +129,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
      --first-block-number <first-block-number>
          Optional first block number to export from the db.
          It is by default 0.
--- a/docs/vocs/docs/pages/cli/reth/import-era.mdx
+++ b/docs/vocs/docs/pages/cli/reth/import-era.mdx
@@ -129,6 +129,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
      --path <IMPORT_ERA_PATH>
          The path to a directory for import.

--- a/docs/vocs/docs/pages/cli/reth/import.mdx
+++ b/docs/vocs/docs/pages/cli/reth/import.mdx
@@ -129,6 +129,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
      --no-state
          Disables stages that require state.

--- a/docs/vocs/docs/pages/cli/reth/init-state.mdx
+++ b/docs/vocs/docs/pages/cli/reth/init-state.mdx
@@ -129,6 +129,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
      --without-evm
          Specifies whether to initialize the state without relying on EVM historical data.

--- a/docs/vocs/docs/pages/cli/reth/init.mdx
+++ b/docs/vocs/docs/pages/cli/reth/init.mdx
@@ -129,6 +129,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
 Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout
--- a/docs/vocs/docs/pages/cli/reth/node.mdx
+++ b/docs/vocs/docs/pages/cli/reth/node.mdx
@@ -1024,6 +1024,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
 Ress:
      --ress.enable
          Enable support for `ress` subprotocol
--- a/docs/vocs/docs/pages/cli/reth/prune.mdx
+++ b/docs/vocs/docs/pages/cli/reth/prune.mdx
@@ -129,6 +129,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
 Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout
--- a/docs/vocs/docs/pages/cli/reth/re-execute.mdx
+++ b/docs/vocs/docs/pages/cli/reth/re-execute.mdx
@@ -129,6 +129,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
      --from <FROM>
          The height to start at

--- a/docs/vocs/docs/pages/cli/reth/stage/drop.mdx
+++ b/docs/vocs/docs/pages/cli/reth/stage/drop.mdx
@@ -129,6 +129,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
  <STAGE>
          Possible values:
          - headers:         The headers stage within the pipeline
--- a/docs/vocs/docs/pages/cli/reth/stage/dump.mdx
+++ b/docs/vocs/docs/pages/cli/reth/stage/dump.mdx
@@ -136,6 +136,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
 Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout
--- a/docs/vocs/docs/pages/cli/reth/stage/run.mdx
+++ b/docs/vocs/docs/pages/cli/reth/stage/run.mdx
@@ -129,6 +129,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
      --metrics <SOCKET>
          Enable Prometheus metrics.

--- a/docs/vocs/docs/pages/cli/reth/stage/unwind.mdx
+++ b/docs/vocs/docs/pages/cli/reth/stage/unwind.mdx
@@ -134,6 +134,27 @@ Static Files:

          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.

+      --storage.tx-hash-in-rocksdb <TX_HASH_IN_ROCKSDB>
+          Store transaction hash -> number mapping in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.storages-history-in-rocksdb <STORAGES_HISTORY_IN_ROCKSDB>
+          Store storages history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
+      --storage.account-history-in-rocksdb <ACCOUNT_HISTORY_IN_ROCKSDB>
+          Store account history in `RocksDB` instead of MDBX.
+
+          Note: This setting can only be configured at genesis initialization. Once the node has been initialized, changing this flag requires re-syncing from scratch.
+
+          [possible values: true, false]
+
      --offline
          If this is enabled, then all stages except headers, bodies, and sender recovery will be unwound
Author	SHA1	Message	Date
Georgios Konstantopoulos	512039fc67	fix: regenerate CLI docs and fix clippy doc_markdown lint - Regenerate CLI documentation after Option<bool> change for RocksDB flags - Add backticks around RocksDB in doc comment for clippy::doc_markdown	2026-01-19 15:24:57 +00:00
yongkangc	8f861da4fd	feat(storage): add init_genesis_with_overrides for startup validation Add validation that CLI-provided RocksDB storage flags match the settings stored in the database metadata at startup. Changes: - Add init_genesis_with_overrides() function in db-common - Update launch/common.rs to use the new validation flow - Update cli/commands/common.rs to use the new validation flow The validation only triggers when the user explicitly passes a flag that differs from what's stored in the database. Existing nodes that don't pass any new flags will continue to work without changes. Closes #20482	2026-01-19 14:17:44 +00:00
yongkangc	fa72fa3104	refactor(cli): change StorageArgs bool fields to Option<bool> Change RocksDB storage flags from bool to Option<bool> to distinguish between explicitly set CLI flags and defaults: - tx_hash_in_rocksdb: bool -> Option<bool> - storages_history_in_rocksdb: bool -> Option<bool> - account_history_in_rocksdb: bool -> Option<bool> Add to_overrides() method to extract explicit CLI settings. Update to_settings() to take defaults parameter for unset flags. This enables detecting when a user explicitly passes a flag vs using defaults, which is required for startup validation.	2026-01-19 14:12:30 +00:00
yongkangc	c4b8d38d79	feat(storage): add StorageSettingsOverrides and validation Add support for validating CLI-provided storage flags against database settings: - Add StorageSettingsOverrides struct to represent explicit CLI overrides - Add StorageSettings::validate_overrides() method to detect mismatches - Add StorageSettingsMismatch error with user-facing guidance - Re-export new types from storage-api and provider crates This prepares for startup validation that prevents accidental misconfiguration of RocksDB storage flags after genesis initialization.	2026-01-19 14:12:23 +00:00
yongkangc	dbdbc6b56b	docs: regenerate CLI documentation for storage flags	2026-01-19 09:49:18 +00:00
yongkangc	1f5653634c	feat(cli): add RocksDB storage startup flags Add CLI flags to enable storing tables in RocksDB at genesis initialization: - --storage.tx-hash-in-rocksdb - --storage.storages-history-in-rocksdb - --storage.account-history-in-rocksdb Introduces StorageArgs that flattens StaticFilesArgs and adds the new RocksDB flags. Updates all callsites to use storage.to_settings(). Closes #20393	2026-01-19 09:41:54 +00:00
github-actions[bot]	be3234d848	chore(deps): weekly `cargo update` (#21167 ) Co-authored-by: github-merge-queue <118344674+github-merge-queue@users.noreply.github.com>	2026-01-18 14:57:20 +00:00