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 ||

docs/vocs/docs/pages/cli/SUMMARY.mdx

@@ -37,6 +37,7 @@
           - [`reth db settings set transaction_hash_numbers`](./reth/db/settings/set/transaction_hash_numbers.mdx)
           - [`reth db settings set account_history`](./reth/db/settings/set/account_history.mdx)
           - [`reth db settings set storage_changesets`](./reth/db/settings/set/storage_changesets.mdx)
+          - [`reth db settings set use_hashed_state`](./reth/db/settings/set/use_hashed_state.mdx)
       - [`reth db account-storage`](./reth/db/account-storage.mdx)
       - [`reth db state`](./reth/db/state.mdx)
     - [`reth download`](./reth/download.mdx)

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

@@ -209,6 +209,13 @@ Storage:
 
           Individual settings can still be overridden with `--static-files.*` and `--rocksdb.*` flags.
 
+      --storage.use-hashed-state
+          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.
+
 Logging:
       --log.stdout.format <FORMAT>
           The format to use for logs written to stdout

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

@@ -16,6 +16,7 @@ Commands:
   transaction_hash_numbers  Store transaction hash to number mapping in rocksdb instead of MDBX
   account_history           Store account history in rocksdb instead of MDBX
   storage_changesets        Store storage changesets in static files instead of the database
+  use_hashed_state          Use hashed state tables (HashedAccounts/HashedStorages) as canonical state
   help                      Print this message or the help of the given subcommand(s)
 
 Options:

docs/vocs/docs/pages/cli/reth/db/settings/set/use_hashed_state.mdx

@@ -0,0 +1,170 @@
+# reth db settings set use_hashed_state
+
+Use hashed state tables (HashedAccounts/HashedStorages) as canonical state
+
+```bash
+$ reth db settings set use_hashed_state --help
+```
+```txt
+Usage: reth db settings set use_hashed_state [OPTIONS] <VALUE>
+
+Arguments:
+  <VALUE>
+          [possible values: true, false]
+
+Options:
+  -h, --help
+          Print help (see a summary with '-h')
+
+Datadir:
+      --chain <CHAIN_OR_PATH>
+          The chain this node is running.
+          Possible values are either a built-in chain or the path to a chain specification file.
+
+          Built-in chains:
+              mainnet, sepolia, holesky, hoodi, dev
+
+          [default: mainnet]
+
+Logging:
+      --log.stdout.format <FORMAT>
+          The format to use for logs written to stdout
+
+          Possible values:
+          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
+          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
+          - terminal: Represents terminal-friendly formatting for logs
+
+          [default: terminal]
+
+      --log.stdout.filter <FILTER>
+          The filter to use for logs written to stdout
+
+          [default: ]
+
+      --log.file.format <FORMAT>
+          The format to use for logs written to the log file
+
+          Possible values:
+          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
+          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
+          - terminal: Represents terminal-friendly formatting for logs
+
+          [default: terminal]
+
+      --log.file.filter <FILTER>
+          The filter to use for logs written to the log file
+
+          [default: debug]
+
+      --log.file.directory <PATH>
+          The path to put log files in
+
+          [default: <CACHE_DIR>/logs]
+
+      --log.file.name <NAME>
+          The prefix name of the log files
+
+          [default: reth.log]
+
+      --log.file.max-size <SIZE>
+          The maximum size (in MB) of one log file
+
+          [default: 200]
+
+      --log.file.max-files <COUNT>
+          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled
+
+          [default: 5]
+
+      --log.journald
+          Write logs to journald
+
+      --log.journald.filter <FILTER>
+          The filter to use for logs written to journald
+
+          [default: error]
+
+      --color <COLOR>
+          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting
+
+          Possible values:
+          - always: Colors on
+          - auto:   Auto-detect
+          - never:  Colors off
+
+          [default: always]
+
+      --logs-otlp[=<URL>]
+          Enable `Opentelemetry` logs export to an OTLP endpoint.
+
+          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`
+
+          Example: --logs-otlp=http://collector:4318/v1/logs
+
+          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]
+
+      --logs-otlp.filter <FILTER>
+          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.
+
+          Example: --logs-otlp.filter=info,reth=debug
+
+          Defaults to INFO if not specified.
+
+          [default: info]
+
+Display:
+  -v, --verbosity...
+          Set the minimum log level.
+
+          -v      Errors
+          -vv     Warnings
+          -vvv    Info
+          -vvvv   Debug
+          -vvvvv  Traces (warning: very verbose!)
+
+  -q, --quiet
+          Silence all log output
+
+Tracing:
+      --tracing-otlp[=<URL>]
+          Enable `Opentelemetry` tracing export to an OTLP endpoint.
+
+          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`
+
+          Example: --tracing-otlp=http://collector:4318/v1/traces
+
+          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]
+
+      --tracing-otlp-protocol <PROTOCOL>
+          OTLP transport protocol to use for exporting traces and logs.
+
+          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path
+
+          Defaults to HTTP if not specified.
+
+          Possible values:
+          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
+          - grpc: gRPC transport, port 4317
+
+          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
+          [default: http]
+
+      --tracing-otlp.filter <FILTER>
+          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.
+
+          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off
+
+          Defaults to TRACE if not specified.
+
+          [default: debug]
+
+      --tracing-otlp.sample-ratio <RATIO>
+          Trace sampling ratio to control the percentage of traces to export.
+
+          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling
+
+          Example: --tracing-otlp.sample-ratio=0.0.
+
+          [env: OTEL_TRACES_SAMPLER_ARG=]
+```

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

@@ -192,6 +192,13 @@ Storage:
 
           Individual settings can still be overridden with `--static-files.*` and `--rocksdb.*` flags.
 
+      --storage.use-hashed-state
+          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.
+
   -u, --url <URL>
           Specify a snapshot URL or let the command propose a default one.
 

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

@@ -192,6 +192,13 @@ Storage:
 
           Individual settings can still be overridden with `--static-files.*` and `--rocksdb.*` flags.
 
+      --storage.use-hashed-state
+          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.
+
       --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

@@ -192,6 +192,13 @@ Storage:
 
           Individual settings can still be overridden with `--static-files.*` and `--rocksdb.*` flags.
 
+      --storage.use-hashed-state
+          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.
+
       --path <IMPORT_ERA_PATH>
           The path to a directory for import.
 

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

@@ -192,6 +192,13 @@ Storage:
 
           Individual settings can still be overridden with `--static-files.*` and `--rocksdb.*` flags.
 
+      --storage.use-hashed-state
+          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.
+
       --no-state
           Disables stages that require state.
 

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

@@ -192,6 +192,13 @@ Storage:
 
           Individual settings can still be overridden with `--static-files.*` and `--rocksdb.*` flags.
 
+      --storage.use-hashed-state
+          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.
+
       --without-evm
           Specifies whether to initialize the state without relying on EVM historical data.
 

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

@@ -192,6 +192,13 @@ Storage:
 
           Individual settings can still be overridden with `--static-files.*` and `--rocksdb.*` flags.
 
+      --storage.use-hashed-state
+          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.
+
 Logging:
       --log.stdout.format <FORMAT>
           The format to use for logs written to stdout

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

@@ -1110,6 +1110,13 @@ Storage:
 
           Individual settings can still be overridden with `--static-files.*` and `--rocksdb.*` flags.
 
+      --storage.use-hashed-state
+          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.
+
 Ress:
       --ress.enable
           Enable support for `ress` subprotocol

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

@@ -192,6 +192,13 @@ Storage:
 
           Individual settings can still be overridden with `--static-files.*` and `--rocksdb.*` flags.
 
+      --storage.use-hashed-state
+          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.
+
 Metrics:
       --metrics <PROMETHEUS>
           Enable Prometheus metrics.

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

@@ -192,6 +192,13 @@ Storage:
 
           Individual settings can still be overridden with `--static-files.*` and `--rocksdb.*` flags.
 
+      --storage.use-hashed-state
+          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.
+
       --from <FROM>
           The height to start at
 

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

@@ -192,6 +192,13 @@ Storage:
 
           Individual settings can still be overridden with `--static-files.*` and `--rocksdb.*` flags.
 
+      --storage.use-hashed-state
+          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.
+
   <STAGE>
           Possible values:
           - headers:         The headers stage within the pipeline

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

@@ -199,6 +199,13 @@ Storage:
 
           Individual settings can still be overridden with `--static-files.*` and `--rocksdb.*` flags.
 
+      --storage.use-hashed-state
+          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.
+
 Logging:
       --log.stdout.format <FORMAT>
           The format to use for logs written to stdout

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

@@ -192,6 +192,13 @@ Storage:
 
           Individual settings can still be overridden with `--static-files.*` and `--rocksdb.*` flags.
 
+      --storage.use-hashed-state
+          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.
+
       --metrics <SOCKET>
           Enable Prometheus metrics.
 

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

@@ -197,6 +197,13 @@ Storage:
 
           Individual settings can still be overridden with `--static-files.*` and `--rocksdb.*` flags.
 
+      --storage.use-hashed-state
+          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.
+
       --offline
           If this is enabled, then all stages except headers, bodies, and sender recovery will be unwound
 

docs/vocs/sidebar-cli-reth.ts

@@ -171,6 +171,10 @@ export const rethCliSidebar: SidebarItem = {
                                 {
                                     text: "reth db settings set storage_changesets",
                                     link: "/cli/reth/db/settings/set/storage_changesets"
+                                },
+                                {
+                                    text: "reth db settings set use_hashed_state",
+                                    link: "/cli/reth/db/settings/set/use_hashed_state"
                                 }
                             ]
                         }