feat(storage): add use_hashed_state storage setting (#21997)

crates/cli/commands/src/db/settings.rs

@@ -74,6 +74,18 @@ pub enum SetCommand {
         #[clap(action(ArgAction::Set))]
         value: bool,
     },
+    /// Use hashed state tables (HashedAccounts/HashedStorages) as canonical state
+    ///
+    /// When enabled, execution writes directly to hashed tables, eliminating need for
+    /// separate hashing stages. State reads come from hashed tables.
+    ///
+    /// WARNING: Changing this setting in either direction requires re-syncing the database.
+    /// Enabling on an existing plain-state database leaves hashed tables empty.
+    /// Disabling on an existing hashed-state database leaves plain tables empty.
+    UseHashedState {
+        #[clap(action(ArgAction::Set))]
+        value: bool,
+    },
 }
 
 impl Command {
@@ -121,6 +133,7 @@ impl Command {
             account_history_in_rocksdb: _,
             account_changesets_in_static_files: _,
             storage_changesets_in_static_files: _,
+            use_hashed_state: _,
         } = settings.unwrap_or_else(StorageSettings::v1);
 
         // Update the setting based on the key
@@ -181,6 +194,19 @@ impl Command {
                 settings.storage_changesets_in_static_files = value;
                 println!("Set storage_changesets_in_static_files = {}", value);
             }
+            SetCommand::UseHashedState { value } => {
+                if settings.use_hashed_state == value {
+                    println!("use_hashed_state is already set to {}", value);
+                    return Ok(());
+                }
+                if settings.use_hashed_state && !value {
+                    println!("WARNING: Disabling use_hashed_state on an existing hashed-state database requires a full resync.");
+                } else {
+                    println!("WARNING: Enabling use_hashed_state on an existing plain-state database requires a full resync.");
+                }
+                settings.use_hashed_state = value;
+                println!("Set use_hashed_state = {}", value);
+            }
         }
 
         // Write updated settings

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

@@ -23,6 +23,16 @@ pub struct StorageArgs {
     /// flags.
     #[arg(long = "storage.v2", action = ArgAction::SetTrue)]
     pub v2: bool,
+
+    /// Use hashed state tables (`HashedAccounts`/`HashedStorages`) as canonical state
+    /// representation instead of plain state tables.
+    ///
+    /// When enabled, execution writes directly to hashed tables, eliminating the need for
+    /// separate hashing stages. This should only be enabled for new databases.
+    ///
+    /// WARNING: Changing this setting on an existing database requires a full resync.
+    #[arg(long = "storage.use-hashed-state", default_value_t = false)]
+    pub use_hashed_state: bool,
 }
 
 #[cfg(test)]

crates/node/core/src/node_config.rs

@@ -408,6 +408,8 @@ impl<ChainSpec> NodeConfig<ChainSpec> {
             s = s.with_account_history_in_rocksdb(v);
         }
 
+        s = s.with_use_hashed_state(self.storage.use_hashed_state);
+
         s
     }
 

crates/storage/db-api/src/models/metadata.rs

@@ -34,6 +34,10 @@ pub struct StorageSettings {
     /// Whether this node should read and write storage changesets from static files.
     #[serde(default)]
     pub storage_changesets_in_static_files: bool,
+    /// Whether to use hashed state tables (`HashedAccounts`/`HashedStorages`) as the canonical
+    /// state representation instead of plain state tables.
+    #[serde(default)]
+    pub use_hashed_state: bool,
 }
 
 impl StorageSettings {
@@ -61,6 +65,7 @@ impl StorageSettings {
             storages_history_in_rocksdb: true,
             transaction_hash_numbers_in_rocksdb: true,
             account_history_in_rocksdb: true,
+            use_hashed_state: false,
         }
     }
 
@@ -78,6 +83,7 @@ impl StorageSettings {
             account_history_in_rocksdb: false,
             account_changesets_in_static_files: false,
             storage_changesets_in_static_files: false,
+            use_hashed_state: false,
         }
     }
 
@@ -123,6 +129,12 @@ impl StorageSettings {
         self
     }
 
+    /// Sets the `use_hashed_state` flag to the provided value.
+    pub const fn with_use_hashed_state(mut self, value: bool) -> Self {
+        self.use_hashed_state = value;
+        self
+    }
+
     /// Returns `true` if any tables are configured to be stored in `RocksDB`.
     pub const fn any_in_rocksdb(&self) -> bool {
         self.transaction_hash_numbers_in_rocksdb ||