fix(persistence): use unwind commit order for remove_blocks_above

The persistence service was using `database_provider_rw()` for unwind
operations, which uses normal commit order (SF → RocksDB → MDBX).

This could cause crash-recovery issues:
1. Blocks are persisted to RocksDB history shards
2. Unwind is triggered (RemoveBlocksAbove)
3. RocksDB shards are truncated and committed
4. Crash occurs before MDBX commit
5. On restart, MDBX checkpoints show old state
6. Same blocks are re-persisted
7. append_storage_history_shard fails with UnsortedInput because
   the shard already contains those block numbers

Fix: Use `unwind_provider_rw()` which ensures MDBX is committed first,
so on crash recovery MDBX checkpoints correctly reflect the unwind state.

.github/CODEOWNERS

@@ -1,45 +1,52 @@
 *                           @gakonst
-crates/blockchain-tree-api/ @rakita @mattsse @Rjected
-crates/blockchain-tree/     @rakita @mattsse @Rjected
 crates/chain-state/         @fgimenez @mattsse
 crates/chainspec/           @Rjected @joshieDo @mattsse
 crates/cli/                 @mattsse
+crates/config/              @shekhirin @mattsse @Rjected 
 crates/consensus/           @mattsse @Rjected
 crates/e2e-test-utils/      @mattsse @Rjected @klkvr @fgimenez
-crates/engine/              @mattsse @Rjected @fgimenez @mediocregopher @yongkangc
-crates/era/                 @mattsse @RomanHodulak
+crates/engine/              @mattsse @Rjected @mediocregopher @yongkangc
+crates/era/                 @mattsse
+crates/era-downloader/      @mattsse
+crates/era-utils/           @mattsse
 crates/errors/              @mattsse
-crates/ethereum-forks/      @mattsse @Rjected
 crates/ethereum/            @mattsse @Rjected
 crates/etl/                 @joshieDo @shekhirin
-crates/evm/                 @rakita @mattsse @Rjected
+crates/evm/                 @mattsse @Rjected @klkvr
 crates/exex/                @shekhirin
+crates/fs-util/             @mattsse
+crates/metrics/             @mattsse @Rjected 
 crates/net/                 @mattsse @Rjected
 crates/net/downloaders/     @Rjected
 crates/node/                @mattsse @Rjected @klkvr
-crates/optimism/            @mattsse @Rjected @fgimenez
+crates/optimism/            @mattsse @Rjected
 crates/payload/             @mattsse @Rjected
-crates/primitives-traits/   @Rjected @RomanHodulak @mattsse @klkvr
+crates/primitives-traits/   @Rjected @mattsse @klkvr
 crates/primitives/          @Rjected @mattsse @klkvr
 crates/prune/               @shekhirin @joshieDo
-crates/ress                 @shekhirin @Rjected
-crates/revm/                @mattsse @rakita
-crates/rpc/                 @mattsse @Rjected @RomanHodulak
+crates/ress/                @shekhirin @Rjected
+crates/revm/                @mattsse
+crates/rpc/                 @mattsse @Rjected
 crates/stages/              @shekhirin @mediocregopher
 crates/static-file/         @joshieDo @shekhirin
+crates/stateless/           @mattsse
 crates/storage/codecs/      @joshieDo
-crates/storage/db-api/      @joshieDo @rakita
+crates/storage/db-api/      @joshieDo
 crates/storage/db-common/   @Rjected
-crates/storage/db/          @joshieDo @rakita
-crates/storage/errors/      @rakita
-crates/storage/libmdbx-rs/  @rakita @shekhirin
+crates/storage/db/          @joshieDo
+crates/storage/errors/      @joshieDo
+crates/storage/libmdbx-rs/  @shekhirin
 crates/storage/nippy-jar/   @joshieDo @shekhirin
-crates/storage/provider/    @rakita @joshieDo @shekhirin
+crates/storage/provider/    @joshieDo @shekhirin @yongkangc
 crates/storage/storage-api/ @joshieDo
 crates/tasks/               @mattsse
-crates/tokio-util/          @fgimenez
+crates/tokio-util/          @mattsse 
+crates/tracing/             @mattsse @shekhirin
+crates/tracing-otlp/        @mattsse @Rjected 
 crates/transaction-pool/    @mattsse @yongkangc
-crates/trie/                @Rjected @shekhirin @mediocregopher
+crates/trie/                @Rjected @shekhirin @mediocregopher @yongkangc
+bin/reth/                   @mattsse @shekhirin @Rjected 
+bin/reth-bench/             @mattsse @Rjected @shekhirin @yongkangc 
 bin/reth-bench-compare/     @mediocregopher @shekhirin @yongkangc
 etc/                        @Rjected @shekhirin
 .github/                    @gakonst @DaniPopes

.github/scripts/codspeed-build.sh

@@ -1,14 +0,0 @@
-#!/usr/bin/env bash
-set -eo pipefail
-
-# TODO: Benchmarks run WAY too slow due to excessive amount of iterations.
-
-cmd=(cargo codspeed build --profile profiling)
-crates=(
-    -p reth-primitives
-    -p reth-trie
-    -p reth-trie-common
-    -p reth-trie-sparse
-)
-
-"${cmd[@]}" --features test-utils "${crates[@]}"

.github/scripts/hive/build_simulators.sh

@@ -38,6 +38,6 @@ for pid in "${saving_pids[@]}"; do
 done
 
 # Make sure we don't rebuild images on the CI jobs
-git apply ../.github/assets/hive/no_sim_build.diff
+git apply ../.github/scripts/hive/no_sim_build.diff
 go build .
 mv ./hive ../hive_assets/

.github/workflows/bench.yml

@@ -17,6 +17,16 @@ name: bench
 jobs:
   codspeed:
     runs-on: depot-ubuntu-latest
+    strategy:
+      matrix:
+        partition: [1, 2]
+        total_partitions: [2]
+        include:
+          - partition: 1
+            crates: "-p reth-primitives -p reth-trie-common -p reth-trie-sparse"
+          - partition: 2
+            crates: "-p reth-trie"
+    name: codspeed (${{ matrix.partition }}/${{ matrix.total_partitions }})
     steps:
       - uses: actions/checkout@v6
         with:
@@ -32,10 +42,10 @@ jobs:
         with:
           tool: cargo-codspeed
       - name: Build the benchmark target(s)
-        run: ./.github/scripts/codspeed-build.sh
+        run: cargo codspeed build --profile profiling --features test-utils ${{ matrix.crates }}
       - name: Run the benchmarks
         uses: CodSpeedHQ/action@v4
         with:
-          run: cargo codspeed run --workspace
+          run: cargo codspeed run ${{ matrix.crates }}
           mode: instrumentation
           token: ${{ secrets.CODSPEED_TOKEN }}

.github/workflows/check-alloy.yml

@@ -0,0 +1,65 @@
+# Checks reth compilation against alloy branches to detect breaking changes.
+# Run on-demand via workflow_dispatch.
+
+name: Check Alloy Breaking Changes
+
+on:
+  workflow_dispatch:
+    inputs:
+      alloy_branch:
+        description: 'Branch/rev for alloy-rs/alloy (leave empty to skip)'
+        required: false
+        type: string
+      alloy_evm_branch:
+        description: 'Branch/rev for alloy-rs/evm (alloy-evm, alloy-op-evm) (leave empty to skip)'
+        required: false
+        type: string
+      op_alloy_branch:
+        description: 'Branch/rev for alloy-rs/op-alloy (leave empty to skip)'
+        required: false
+        type: string
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  check:
+    name: Check compilation with patched alloy
+    runs-on: depot-ubuntu-latest-16
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-on-failure: true
+
+      - name: Apply alloy patches
+        run: |
+          ARGS=""
+          if [ -n "${{ inputs.alloy_branch }}" ]; then
+            ARGS="$ARGS --alloy ${{ inputs.alloy_branch }}"
+          fi
+          if [ -n "${{ inputs.alloy_evm_branch }}" ]; then
+            ARGS="$ARGS --evm ${{ inputs.alloy_evm_branch }}"
+          fi
+          if [ -n "${{ inputs.op_alloy_branch }}" ]; then
+            ARGS="$ARGS --op ${{ inputs.op_alloy_branch }}"
+          fi
+          
+          if [ -z "$ARGS" ]; then
+            echo "No branches specified, nothing to patch"
+            exit 1
+          fi
+          
+          ./scripts/patch-alloy.sh $ARGS
+          
+          echo "=== Final patch section ==="
+          tail -50 Cargo.toml
+
+      - name: Check workspace
+        run: cargo clippy --workspace --lib --examples --tests --benches --all-features --locked
+        env:
+          RUSTFLAGS: -D warnings

.github/workflows/docker-git.yml

@@ -1,54 +0,0 @@
-# Publishes the Docker image, only to be used with `workflow_dispatch`. The
-# images from this workflow will be tagged with the git sha of the branch used
-# and will NOT tag it as `latest`.
-
-name: docker-git
-
-on:
-  workflow_dispatch: {}
-
-env:
-  REPO_NAME: ${{ github.repository_owner }}/reth
-  IMAGE_NAME: ${{ github.repository_owner }}/reth
-  OP_IMAGE_NAME: ${{ github.repository_owner }}/op-reth
-  CARGO_TERM_COLOR: always
-  DOCKER_IMAGE_NAME: ghcr.io/${{ github.repository_owner }}/reth
-  OP_DOCKER_IMAGE_NAME: ghcr.io/${{ github.repository_owner }}/op-reth
-  DOCKER_USERNAME: ${{ github.actor }}
-  GIT_SHA: ${{ github.sha }}
-
-jobs:
-  build:
-    name: build and push
-    runs-on: ubuntu-24.04
-    permissions:
-      packages: write
-      contents: read
-    strategy:
-      fail-fast: false
-      matrix:
-        build:
-          - name: 'Build and push the git-sha-tagged reth image'
-            command: 'make PROFILE=maxperf GIT_SHA=$GIT_SHA docker-build-push-git-sha'
-          - name: 'Build and push the git-sha-tagged op-reth image'
-            command: 'make IMAGE_NAME=$OP_IMAGE_NAME DOCKER_IMAGE_NAME=$OP_DOCKER_IMAGE_NAME GIT_SHA=$GIT_SHA PROFILE=maxperf op-docker-build-push-git-sha'
-    steps:
-      - uses: actions/checkout@v6
-      - uses: rui314/setup-mold@v1
-      - uses: dtolnay/rust-toolchain@stable
-      - uses: Swatinem/rust-cache@v2
-        with:
-          cache-on-failure: true
-      - name: Install cross main
-        id: cross_main
-        run: |
-          cargo install cross --git https://github.com/cross-rs/cross
-      - name: Log in to Docker
-        run: |
-          echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io --username ${DOCKER_USERNAME} --password-stdin
-      - name: Set up Docker builder
-        run: |
-          docker run --privileged --rm tonistiigi/binfmt --install arm64,amd64
-          docker buildx create --use --name cross-builder
-      - name: Build and push ${{ matrix.build.name }}
-        run: ${{ matrix.build.command }}

.github/workflows/docker-nightly.yml

@@ -1,65 +0,0 @@
-# Publishes the nightly Docker image.
-
-name: docker-nightly
-
-on:
-  workflow_dispatch:
-  schedule:
-    - cron: "0 1 * * *"
-env:
-  REPO_NAME: ${{ github.repository_owner }}/reth
-  IMAGE_NAME: ${{ github.repository_owner }}/reth
-  OP_IMAGE_NAME: ${{ github.repository_owner }}/op-reth
-  CARGO_TERM_COLOR: always
-  DOCKER_IMAGE_NAME: ghcr.io/${{ github.repository_owner }}/reth
-  OP_DOCKER_IMAGE_NAME: ghcr.io/${{ github.repository_owner }}/op-reth
-  DOCKER_USERNAME: ${{ github.actor }}
-
-jobs:
-  build:
-    name: build and push
-    runs-on: ubuntu-24.04
-    permissions:
-      packages: write
-      contents: read
-    strategy:
-      fail-fast: false
-      matrix:
-        build:
-          - name: 'Build and push the nightly reth image'
-            command: 'make PROFILE=maxperf docker-build-push-nightly'
-          - name: 'Build and push the nightly edge profiling reth image'
-            command: 'make PROFILE=profiling docker-build-push-nightly-edge-profiling'
-          - name: 'Build and push the nightly profiling reth image'
-            command: 'make PROFILE=profiling docker-build-push-nightly-profiling'
-          - name: 'Build and push the nightly op-reth image'
-            command: 'make IMAGE_NAME=$OP_IMAGE_NAME DOCKER_IMAGE_NAME=$OP_DOCKER_IMAGE_NAME PROFILE=maxperf op-docker-build-push-nightly'
-          - name: 'Build and push the nightly edge profiling op-reth image'
-            command: 'make IMAGE_NAME=$OP_IMAGE_NAME DOCKER_IMAGE_NAME=$OP_DOCKER_IMAGE_NAME PROFILE=profiling op-docker-build-push-nightly-edge-profiling'
-          - name: 'Build and push the nightly profiling op-reth image'
-            command: 'make IMAGE_NAME=$OP_IMAGE_NAME DOCKER_IMAGE_NAME=$OP_DOCKER_IMAGE_NAME PROFILE=profiling op-docker-build-push-nightly-profiling'
-    steps:
-      - uses: actions/checkout@v6
-      - name: Remove bloatware
-        uses: laverdet/remove-bloatware@v1.0.0
-        with:
-          docker: true
-          lang: rust
-      - uses: rui314/setup-mold@v1
-      - uses: dtolnay/rust-toolchain@stable
-      - uses: Swatinem/rust-cache@v2
-        with:
-          cache-on-failure: true
-      - name: Install cross main
-        id: cross_main
-        run: |
-          cargo install cross --git https://github.com/cross-rs/cross
-      - name: Log in to Docker
-        run: |
-          echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io --username ${DOCKER_USERNAME} --password-stdin
-      - name: Set up Docker builder
-        run: |
-          docker run --privileged --rm tonistiigi/binfmt --install arm64,amd64
-          docker buildx create --use --name cross-builder
-      - name: Build and push ${{ matrix.build.name }}
-        run: ${{ matrix.build.command }}

.github/workflows/docker.yml

@@ -1,4 +1,9 @@
-# Publishes the Docker image.
+# Publishes Docker images.
+#
+# Triggers:
+#   - Push tag v*: builds release (RC or latest)
+#   - Schedule: builds nightly + profiling
+#   - Manual: builds git-sha or nightly
 
 name: docker
 
@@ -6,84 +11,94 @@ on:
   push:
     tags:
       - v*
-
-env:
-  IMAGE_NAME: ${{ github.repository_owner }}/reth
-  OP_IMAGE_NAME: ${{ github.repository_owner }}/op-reth
-  CARGO_TERM_COLOR: always
-  DOCKER_IMAGE_NAME: ghcr.io/${{ github.repository_owner }}/reth
-  OP_DOCKER_IMAGE_NAME: ghcr.io/${{ github.repository_owner }}/op-reth
-  DOCKER_USERNAME: ${{ github.actor }}
+  schedule:
+    - cron: "0 1 * * *"
+  workflow_dispatch:
+    inputs:
+      build_type:
+        description: "Build type"
+        required: true
+        type: choice
+        options:
+          - git-sha
+          - nightly
+        default: git-sha
+      dry_run:
+        description: "Skip pushing images (dry run)"
+        required: false
+        type: boolean
+        default: false
 
 jobs:
-  build-rc:
-    if: contains(github.ref, '-rc')
-    name: build and push as release candidate
-    runs-on: ubuntu-24.04
-    permissions:
-      packages: write
-      contents: read
-    strategy:
-      fail-fast: false
-      matrix:
-        build:
-          - name: "Build and push reth image"
-            command: "make IMAGE_NAME=$IMAGE_NAME DOCKER_IMAGE_NAME=$DOCKER_IMAGE_NAME PROFILE=maxperf docker-build-push"
-          - name: "Build and push op-reth image"
-            command: "make IMAGE_NAME=$OP_IMAGE_NAME DOCKER_IMAGE_NAME=$OP_DOCKER_IMAGE_NAME PROFILE=maxperf op-docker-build-push"
-    steps:
-      - uses: actions/checkout@v6
-      - uses: rui314/setup-mold@v1
-      - uses: dtolnay/rust-toolchain@stable
-      - uses: Swatinem/rust-cache@v2
-        with:
-          cache-on-failure: true
-      - name: Install cross main
-        id: cross_main
-        run: |
-          cargo install cross --git https://github.com/cross-rs/cross
-      - name: Log in to Docker
-        run: |
-          echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io --username ${DOCKER_USERNAME} --password-stdin
-      - name: Set up Docker builder
-        run: |
-          docker run --privileged --rm tonistiigi/binfmt --install arm64,amd64
-          docker buildx create --use --name cross-builder
-      - name: Build and push ${{ matrix.build.name }}
-        run: ${{ matrix.build.command }}
-
   build:
-    if: ${{ !contains(github.ref, '-rc') }}
-    name: build and push as latest
+    name: Build Docker images
     runs-on: ubuntu-24.04
     permissions:
       packages: write
       contents: read
-    strategy:
-      fail-fast: false
-      matrix:
-        build:
-          - name: "Build and push reth image"
-            command: "make IMAGE_NAME=$IMAGE_NAME DOCKER_IMAGE_NAME=$DOCKER_IMAGE_NAME PROFILE=maxperf docker-build-push-latest"
-          - name: "Build and push op-reth image"
-            command: "make IMAGE_NAME=$OP_IMAGE_NAME DOCKER_IMAGE_NAME=$OP_DOCKER_IMAGE_NAME PROFILE=maxperf op-docker-build-push-latest"
+      id-token: write
     steps:
       - uses: actions/checkout@v6
-      - uses: rui314/setup-mold@v1
-      - uses: dtolnay/rust-toolchain@stable
-      - uses: Swatinem/rust-cache@v2
+
+      - name: Set up Depot CLI
+        uses: depot/setup-action@v1
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
         with:
-          cache-on-failure: true
-      - name: Install cross main
-        id: cross_main
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Get git info for vergen
+        id: git
         run: |
-          cargo install cross --git https://github.com/cross-rs/cross
-      - name: Log in to Docker
+          echo "sha=${{ github.sha }}" >> "$GITHUB_OUTPUT"
+          echo "describe=$(git describe --always --tags)" >> "$GITHUB_OUTPUT"
+          echo "dirty=false" >> "$GITHUB_OUTPUT"
+
+      - name: Determine build parameters
+        id: params
         run: |
-          echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io --username ${DOCKER_USERNAME} --password-stdin
-      - name: Set up Docker builder
-        run: |
-          docker run --privileged --rm tonistiigi/binfmt --install arm64,amd64
-          docker buildx create --use --name cross-builder
-      - name: Build and push ${{ matrix.build.name }}
-        run: ${{ matrix.build.command }}
+          REGISTRY="ghcr.io/${{ github.repository_owner }}"
+
+          if [[ "${{ github.event_name }}" == "push" ]]; then
+            VERSION="${GITHUB_REF#refs/tags/}"
+            echo "targets=ethereum optimism" >> "$GITHUB_OUTPUT"
+
+            # Add 'latest' tag for non-RC releases
+            if [[ ! "$VERSION" =~ -rc ]]; then
+              echo "ethereum_tags=${REGISTRY}/reth:${VERSION},${REGISTRY}/reth:latest" >> "$GITHUB_OUTPUT"
+              echo "optimism_tags=${REGISTRY}/op-reth:${VERSION},${REGISTRY}/op-reth:latest" >> "$GITHUB_OUTPUT"
+            else
+              echo "ethereum_tags=${REGISTRY}/reth:${VERSION}" >> "$GITHUB_OUTPUT"
+              echo "optimism_tags=${REGISTRY}/op-reth:${VERSION}" >> "$GITHUB_OUTPUT"
+            fi
+
+          elif [[ "${{ github.event_name }}" == "schedule" ]] || [[ "${{ inputs.build_type }}" == "nightly" ]]; then
+            echo "targets=nightly" >> "$GITHUB_OUTPUT"
+            echo "ethereum_tags=${REGISTRY}/reth:nightly" >> "$GITHUB_OUTPUT"
+            echo "optimism_tags=${REGISTRY}/op-reth:nightly" >> "$GITHUB_OUTPUT"
+
+          else
+            # git-sha build
+            echo "targets=ethereum optimism" >> "$GITHUB_OUTPUT"
+            echo "ethereum_tags=${REGISTRY}/reth:${{ github.sha }}" >> "$GITHUB_OUTPUT"
+            echo "optimism_tags=${REGISTRY}/op-reth:${{ github.sha }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build and push images
+        uses: depot/bake-action@v1
+        env:
+          VERGEN_GIT_SHA: ${{ steps.git.outputs.sha }}
+          VERGEN_GIT_DESCRIBE: ${{ steps.git.outputs.describe }}
+          VERGEN_GIT_DIRTY: ${{ steps.git.outputs.dirty }}
+          DEPOT_TOKEN: ${{ secrets.DEPOT_TOKEN }}
+        with:
+          project: ${{ vars.DEPOT_PROJECT_ID }}
+          files: docker-bake.hcl
+          targets: ${{ steps.params.outputs.targets }}
+          push: ${{ !(github.event_name == 'workflow_dispatch' && inputs.dry_run) }}
+          set: |
+            ethereum.tags=${{ steps.params.outputs.ethereum_tags }}
+            optimism.tags=${{ steps.params.outputs.optimism_tags }}

.github/workflows/e2e.yml

@@ -44,3 +44,24 @@ jobs:
             --exclude 'op-reth' \
             --exclude 'reth' \
             -E 'binary(e2e_testsuite)'
+
+  rocksdb:
+    name: e2e-rocksdb
+    runs-on: depot-ubuntu-latest-4
+    env:
+      RUST_BACKTRACE: 1
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v6
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: mozilla-actions/sccache-action@v0.0.9
+      - uses: taiki-e/install-action@nextest
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-on-failure: true
+      - name: Run RocksDB e2e tests
+        run: |
+          cargo nextest run \
+            --locked --features "edge" \
+            -p reth-e2e-test-utils \
+            -E 'binary(rocksdb)'

.github/workflows/hive.yml

@@ -58,11 +58,11 @@ jobs:
         uses: actions/cache@v5
         with:
           path: ./hive_assets
-          key: hive-assets-${{ steps.hive-commit.outputs.hash }}-${{ hashFiles('.github/assets/hive/build_simulators.sh') }}
+          key: hive-assets-${{ steps.hive-commit.outputs.hash }}-${{ hashFiles('.github/scripts/hive/build_simulators.sh') }}
 
       - name: Build hive assets
         if: steps.cache-hive.outputs.cache-hit != 'true'
-        run: .github/assets/hive/build_simulators.sh
+        run: .github/scripts/hive/build_simulators.sh
 
       - name: Load cached Docker images
         if: steps.cache-hive.outputs.cache-hit == 'true'
@@ -213,7 +213,7 @@ jobs:
           path: /tmp
 
       - name: Load Docker images
-        run: .github/assets/hive/load_images.sh
+        run: .github/scripts/hive/load_images.sh
 
       - name: Move hive binary
         run: |
@@ -241,11 +241,11 @@ jobs:
             FILTER="/"
           fi
           echo "filter: $FILTER"
-          .github/assets/hive/run_simulator.sh "${{ matrix.scenario.sim }}" "$FILTER"
+          .github/scripts/hive/run_simulator.sh "${{ matrix.scenario.sim }}" "$FILTER"
 
       - name: Parse hive output
         run: |
-          find hivetests/workspace/logs -type f -name "*.json" ! -name "hive.json" | xargs -I {} python .github/assets/hive/parse.py {} --exclusion .github/assets/hive/expected_failures.yaml --ignored .github/assets/hive/ignored_tests.yaml
+          find hivetests/workspace/logs -type f -name "*.json" ! -name "hive.json" | xargs -I {} python .github/scripts/hive/parse.py {} --exclusion .github/scripts/hive/expected_failures.yaml --ignored .github/scripts/hive/ignored_tests.yaml
 
       - name: Print simulator output
         if: ${{ failure() }}

.github/workflows/integration.yml

@@ -22,7 +22,7 @@ concurrency:
 
 jobs:
   test:
-    name: test / ${{ matrix.network }}
+    name: test / ${{ matrix.network }} / ${{ matrix.storage }}
     if: github.event_name != 'schedule'
     runs-on: depot-ubuntu-latest-4
     env:
@@ -30,13 +30,17 @@ jobs:
     strategy:
       matrix:
         network: ["ethereum", "optimism"]
+        storage: ["stable", "edge"]
+        exclude:
+          - network: optimism
+            storage: edge
     timeout-minutes: 60
     steps:
       - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@stable
       - name: Install Geth
-        run: .github/assets/install_geth.sh
+        run: .github/scripts/install_geth.sh
       - uses: taiki-e/install-action@nextest
       - uses: mozilla-actions/sccache-action@v0.0.9
       - uses: Swatinem/rust-cache@v2
@@ -46,7 +50,7 @@ jobs:
         name: Run tests
         run: |
           cargo nextest run \
-            --locked --features "asm-keccak ${{ matrix.network }}" \
+            --locked --features "asm-keccak ${{ matrix.network }} ${{ matrix.storage == 'edge' && 'edge' || '' }}" \
             --workspace --exclude ef-tests \
             -E "kind(test) and not binary(e2e_testsuite)"
       - if: matrix.network == 'optimism'

.github/workflows/label-pr.yml

@@ -19,5 +19,5 @@ jobs:
         uses: actions/github-script@v8
         with:
           script: |
-            const label_pr = require('./.github/assets/label_pr.js')
+            const label_pr = require('./.github/scripts/label_pr.js')
             await label_pr({github, context})

.github/workflows/lint.yml

@@ -76,7 +76,7 @@ jobs:
       - name: Run Wasm checks
         run: |
           sudo apt update && sudo apt install gcc-multilib
-          .github/assets/check_wasm.sh
+          .github/scripts/check_wasm.sh
 
   riscv:
     runs-on: depot-ubuntu-latest
@@ -94,7 +94,7 @@ jobs:
           cache-on-failure: true
       - uses: dcarbone/install-jq-action@v3
       - name: Run RISC-V checks
-        run: .github/assets/check_rv32imac.sh
+        run: .github/scripts/check_rv32imac.sh
 
   crate-checks:
     name: crate-checks (${{ matrix.partition }}/${{ matrix.total_partitions }})

.github/workflows/prepare-reth.yml

@@ -43,7 +43,7 @@ jobs:
         uses: docker/build-push-action@v6
         with:
           context: .
-          file: .github/assets/hive/Dockerfile
+          file: .github/scripts/hive/Dockerfile
           tags: ${{ inputs.image_tag }}
           outputs: type=docker,dest=./artifacts/reth_image.tar
           build-args: |

CLAUDE.md

@@ -38,7 +38,7 @@ Reth is a high-performance Ethereum execution client written in Rust, focusing o
 
 2. **Linting**: Run clippy with all features
    ```bash
-   RUSTFLAGS="-D warnings" cargo +nightly clippy --workspace --lib --examples --tests --benches --all-features --locked
+   cargo +nightly clippy --workspace --lib --examples --tests --benches --all-features 
    ```
 
 3. **Testing**: Use nextest for faster test execution
@@ -169,12 +169,11 @@ Based on PR patterns, avoid:
 Before submitting changes, ensure:
 
 1. **Format Check**: `cargo +nightly fmt --all --check`
-2. **Clippy**: No warnings with `RUSTFLAGS="-D warnings"`
+2. **Clippy**: No warnings
 3. **Tests Pass**: All unit and integration tests
 4. **Documentation**: Update relevant docs and add doc comments with `cargo docs --document-private-items`
 5. **Commit Messages**: Follow conventional format (feat:, fix:, chore:, etc.)
 
-
 ### Opening PRs against <https://github.com/paradigmxyz/reth>
 
 Label PRs appropriately, first check the available labels and then apply the relevant ones:
@@ -349,10 +348,10 @@ Let's say you want to fix a bug where external IP resolution fails on startup:
    }
    ```
 
-5. **Run checks**:
+5. **Run checks** (IMPORTANT!):
    ```bash
    cargo +nightly fmt --all
-   cargo clippy --all-features
+   cargo clippy --workspace --all-features # Make sure WHOLE WORKSPACE compiles!
    cargo test -p reth-discv4
    ```
 
@@ -374,7 +373,7 @@ Let's say you want to fix a bug where external IP resolution fails on startup:
 cargo +nightly fmt --all
 
 # Run lints
-RUSTFLAGS="-D warnings" cargo +nightly clippy --workspace --all-features --locked
+cargo +nightly clippy --workspace --all-features
 
 # Run tests
 cargo nextest run --workspace

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace.package]
-version = "1.10.1"
+version = "1.10.2"
 edition = "2024"
 rust-version = "1.88"
 license = "MIT OR Apache-2.0"
@@ -77,6 +77,10 @@ members = [
     "crates/optimism/cli",
     "crates/optimism/consensus",
     "crates/optimism/evm/",
+    "crates/optimism/examples/custom-node",
+    "crates/optimism/examples/engine-api-access",
+    "crates/optimism/examples/exex-hello-world",
+    "crates/optimism/examples/op-db-access",
     "crates/optimism/flashblocks/",
     "crates/optimism/hardforks/",
     "crates/optimism/node/",
@@ -145,7 +149,6 @@ members = [
     "examples/beacon-api-sse/",
     "examples/bsc-p2p",
     "examples/custom-dev-node/",
-    "examples/custom-node/",
     "examples/custom-engine-types/",
     "examples/custom-evm/",
     "examples/custom-hardforks/",
@@ -154,10 +157,7 @@ members = [
     "examples/custom-payload-builder/",
     "examples/custom-rlpx-subprotocol",
     "examples/custom-rpc-middleware",
-    "examples/custom-node",
     "examples/db-access",
-    "examples/engine-api-access",
-    "examples/exex-hello-world",
     "examples/exex-subscription",
     "examples/exex-test",
     "examples/full-contract-state",
@@ -168,7 +168,6 @@ members = [
     "examples/node-builder-api/",
     "examples/node-custom-rpc/",
     "examples/node-event-hooks/",
-    "examples/op-db-access/",
     "examples/polygon-p2p/",
     "examples/rpc-db/",
     "examples/precompile-cache/",
@@ -481,52 +480,52 @@ revm-primitives = { version = "22.0.0", default-features = false }
 revm-interpreter = { version = "32.0.0", default-features = false }
 revm-database-interface = { version = "9.0.0", default-features = false }
 op-revm = { version = "15.0.0", default-features = false }
-revm-inspectors = "0.34.0"
+revm-inspectors = "0.34.1"
 
 # eth
+alloy-dyn-abi = "1.5.4"
+alloy-primitives = { version = "1.5.4", default-features = false, features = ["map-foldhash"] }
+alloy-sol-types = { version = "1.5.4", default-features = false }
+
 alloy-chains = { version = "0.2.5", default-features = false }
-alloy-dyn-abi = "1.4.3"
 alloy-eip2124 = { version = "0.2.0", default-features = false }
 alloy-eip7928 = { version = "0.3.0", default-features = false }
-alloy-evm = { version = "0.26.3", default-features = false }
-alloy-primitives = { version = "1.5.0", default-features = false, features = ["map-foldhash"] }
+alloy-evm = { version = "0.27.0", default-features = false }
 alloy-rlp = { version = "0.3.10", default-features = false, features = ["core-net"] }
-alloy-sol-macro = "1.5.0"
-alloy-sol-types = { version = "1.5.0", default-features = false }
 alloy-trie = { version = "0.9.1", default-features = false }
 
 alloy-hardforks = "0.4.5"
 
-alloy-consensus = { version = "1.4.3", default-features = false }
-alloy-contract = { version = "1.4.3", default-features = false }
-alloy-eips = { version = "1.4.3", default-features = false }
-alloy-genesis = { version = "1.4.3", default-features = false }
-alloy-json-rpc = { version = "1.4.3", default-features = false }
-alloy-network = { version = "1.4.3", default-features = false }
-alloy-network-primitives = { version = "1.4.3", default-features = false }
-alloy-provider = { version = "1.4.3", features = ["reqwest", "debug-api"], default-features = false }
-alloy-pubsub = { version = "1.4.3", default-features = false }
-alloy-rpc-client = { version = "1.4.3", default-features = false }
-alloy-rpc-types = { version = "1.4.3", features = ["eth"], default-features = false }
-alloy-rpc-types-admin = { version = "1.4.3", default-features = false }
-alloy-rpc-types-anvil = { version = "1.4.3", default-features = false }
-alloy-rpc-types-beacon = { version = "1.4.3", default-features = false }
-alloy-rpc-types-debug = { version = "1.4.3", default-features = false }
-alloy-rpc-types-engine = { version = "1.4.3", default-features = false }
-alloy-rpc-types-eth = { version = "1.4.3", default-features = false }
-alloy-rpc-types-mev = { version = "1.4.3", default-features = false }
-alloy-rpc-types-trace = { version = "1.4.3", default-features = false }
-alloy-rpc-types-txpool = { version = "1.4.3", default-features = false }
-alloy-serde = { version = "1.4.3", default-features = false }
-alloy-signer = { version = "1.4.3", default-features = false }
-alloy-signer-local = { version = "1.4.3", default-features = false }
-alloy-transport = { version = "1.4.3" }
-alloy-transport-http = { version = "1.4.3", features = ["reqwest-rustls-tls"], default-features = false }
-alloy-transport-ipc = { version = "1.4.3", default-features = false }
-alloy-transport-ws = { version = "1.4.3", default-features = false }
+alloy-consensus = { version = "1.5.2", default-features = false }
+alloy-contract = { version = "1.5.2", default-features = false }
+alloy-eips = { version = "1.5.2", default-features = false }
+alloy-genesis = { version = "1.5.2", default-features = false }
+alloy-json-rpc = { version = "1.5.2", default-features = false }
+alloy-network = { version = "1.5.2", default-features = false }
+alloy-network-primitives = { version = "1.5.2", default-features = false }
+alloy-provider = { version = "1.5.2", features = ["reqwest", "debug-api"], default-features = false }
+alloy-pubsub = { version = "1.5.2", default-features = false }
+alloy-rpc-client = { version = "1.5.2", default-features = false }
+alloy-rpc-types = { version = "1.5.2", features = ["eth"], default-features = false }
+alloy-rpc-types-admin = { version = "1.5.2", default-features = false }
+alloy-rpc-types-anvil = { version = "1.5.2", default-features = false }
+alloy-rpc-types-beacon = { version = "1.5.2", default-features = false }
+alloy-rpc-types-debug = { version = "1.5.2", default-features = false }
+alloy-rpc-types-engine = { version = "1.5.2", default-features = false }
+alloy-rpc-types-eth = { version = "1.5.2", default-features = false }
+alloy-rpc-types-mev = { version = "1.5.2", default-features = false }
+alloy-rpc-types-trace = { version = "1.5.2", default-features = false }
+alloy-rpc-types-txpool = { version = "1.5.2", default-features = false }
+alloy-serde = { version = "1.5.2", default-features = false }
+alloy-signer = { version = "1.5.2", default-features = false }
+alloy-signer-local = { version = "1.5.2", default-features = false }
+alloy-transport = { version = "1.5.2" }
+alloy-transport-http = { version = "1.5.2", features = ["reqwest-rustls-tls"], default-features = false }
+alloy-transport-ipc = { version = "1.5.2", default-features = false }
+alloy-transport-ws = { version = "1.5.2", default-features = false }
 
 # op
-alloy-op-evm = { version = "0.26.3", default-features = false }
+alloy-op-evm = { version = "0.27.0", default-features = false }
 alloy-op-hardforks = "0.4.4"
 op-alloy-rpc-types = { version = "0.23.1", default-features = false }
 op-alloy-rpc-types-engine = { version = "0.23.1", default-features = false }
@@ -561,7 +560,7 @@ humantime-serde = "1.1"
 itertools = { version = "0.14", default-features = false }
 linked_hash_set = "0.1"
 lz4 = "1.28.1"
-modular-bitfield = "0.11.2"
+modular-bitfield = "0.13.1"
 notify = { version = "8.0.0", default-features = false, features = ["macos_fsevent"] }
 nybbles = { version = "0.4.2", default-features = false }
 once_cell = { version = "1.19", default-features = false, features = ["critical-section"] }
@@ -588,15 +587,15 @@ tracing-appender = "0.2"
 url = { version = "2.3", default-features = false }
 zstd = "0.13"
 byteorder = "1"
-mini-moka = "0.10"
+fixed-cache = { version = "0.1.7", features = ["stats"] }
 moka = "0.12"
-tar-no-std = { version = "0.3.2", default-features = false }
-miniz_oxide = { version = "0.8.4", default-features = false }
+tar-no-std = { version = "0.4.2", default-features = false }
+miniz_oxide = { version = "0.9.0", default-features = false }
 chrono = "0.4.41"
 
 # metrics
 metrics = "0.24.0"
-metrics-derive = "0.1"
+metrics-derive = "0.1.1"
 metrics-exporter-prometheus = { version = "0.18.0", default-features = false }
 metrics-process = "2.1.0"
 metrics-util = { default-features = false, version = "0.20.0" }
@@ -608,7 +607,7 @@ quote = "1.0"
 # tokio
 tokio = { version = "1.44.2", default-features = false }
 tokio-stream = "0.1.11"
-tokio-tungstenite = "0.26.2"
+tokio-tungstenite = "0.28.0"
 tokio-util = { version = "0.7.4", features = ["codec"] }
 
 # async
@@ -621,7 +620,7 @@ futures-util = { version = "0.3", default-features = false }
 hyper = "1.3"
 hyper-util = "0.1.5"
 pin-project = "1.0.12"
-reqwest = { version = "0.12", default-features = false }
+reqwest = { version = "0.12", default-features = false, features = ["rustls-tls", "rustls-tls-native-roots", "stream"] }
 tracing-futures = "0.2"
 tower = "0.5"
 tower-http = "0.6"
@@ -641,7 +640,6 @@ jsonrpsee-types = "0.26.0"
 http = "1.0"
 http-body = "1.0"
 http-body-util = "0.1.2"
-jsonwebtoken = "9"
 proptest-arbitrary-interop = "0.1.0"
 
 # crypto
@@ -655,7 +653,7 @@ rand_08 = { package = "rand", version = "0.8" }
 c-kzg = "2.1.5"
 
 # config
-toml = "0.8"
+toml = "0.9"
 
 # rocksdb
 rocksdb = { version = "0.24" }
@@ -671,19 +669,19 @@ tracing-opentelemetry = "0.32"
 # misc-testing
 arbitrary = "1.3"
 assert_matches = "1.5.0"
-criterion = { package = "codspeed-criterion-compat", version = "2.7" }
+criterion = { package = "codspeed-criterion-compat", version = "4.3" }
 insta = "1.41"
 proptest = "1.7"
-proptest-derive = "0.5"
+proptest-derive = "0.7"
 similar-asserts = { version = "1.5.0", features = ["serde"] }
 tempfile = "3.20"
 test-fuzz = "7"
-rstest = "0.24.0"
+rstest = "0.26.1"
 test-case = "3"
 
 # ssz encoding
-ethereum_ssz = "0.9.0"
-ethereum_ssz_derive = "0.9.0"
+ethereum_ssz = "0.10.1"
+ethereum_ssz_derive = "0.10.1"
 
 # allocators
 jemalloc_pprof = { version = "0.8", default-features = false }
@@ -695,14 +693,14 @@ snmalloc-rs = { version = "0.3.7", features = ["build_cc"] }
 aes = "0.8.1"
 ahash = "0.8"
 anyhow = "1.0"
-bindgen = { version = "0.71", default-features = false }
-block-padding = "0.3.2"
+bindgen = { version = "0.72", default-features = false }
+block-padding = "0.3"
 cc = "1.2.15"
 cipher = "0.4.3"
 comfy-table = "7.0"
 concat-kdf = "0.1.0"
 crossbeam-channel = "0.5.13"
-crossterm = "0.28.0"
+crossterm = "0.29.0"
 csv = "1.3.0"
 ctrlc = "3.4"
 ctr = "0.9.2"
@@ -715,7 +713,7 @@ hmac = "0.12.1"
 human_bytes = "0.4.1"
 indexmap = "2"
 interprocess = "2.2.0"
-lz4_flex = { version = "0.11", default-features = false }
+lz4_flex = { version = "0.12", default-features = false }
 memmap2 = "0.9.4"
 mev-share-sse = { version = "0.5.0", default-features = false }
 num-traits = "0.2.15"
@@ -723,17 +721,17 @@ page_size = "0.6.0"
 parity-scale-codec = "3.2.1"
 plain_hasher = "0.2"
 pretty_assertions = "1.4"
-ratatui = { version = "0.29", default-features = false }
-ringbuffer = "0.15.0"
+ratatui = { version = "0.30", default-features = false }
+ringbuffer = "0.16.0"
 rmp-serde = "1.3"
-roaring = "0.10.2"
+roaring = "0.11.3"
 rolling-file = "0.2.0"
 sha3 = "0.10.5"
 snap = "1.1.1"
-socket2 = { version = "0.5", default-features = false }
-sysinfo = { version = "0.33", default-features = false }
+socket2 = { version = "0.6", default-features = false }
+sysinfo = { version = "0.38", default-features = false }
 tracing-journald = "0.3"
-tracing-logfmt = "0.3.3"
+tracing-logfmt = "=0.3.5"
 tracing-samply = "0.1"
 tracing-subscriber = { version = "0.3", default-features = false }
 tracing-tracy = "0.11"
@@ -790,8 +788,8 @@ ipnet = "2.11"
 # jsonrpsee-http-client = { git = "https://github.com/paradigmxyz/jsonrpsee", branch = "matt/make-rpc-service-pub" }
 # jsonrpsee-types = { git = "https://github.com/paradigmxyz/jsonrpsee", branch = "matt/make-rpc-service-pub" }
 
-# alloy-evm = { git = "https://github.com/alloy-rs/evm", rev = "a69f0b45a6b0286e16072cb8399e02ce6ceca353" }
-# alloy-op-evm = { git = "https://github.com/alloy-rs/evm", rev = "a69f0b45a6b0286e16072cb8399e02ce6ceca353" }
+# alloy-evm = { git = "https://github.com/alloy-rs/evm", rev = "df124c0" }
+# alloy-op-evm = { git = "https://github.com/alloy-rs/evm", rev = "df124c0" }
 
 # revm-inspectors = { git = "https://github.com/paradigmxyz/revm-inspectors", rev = "3020ea8" }
 

Dockerfile.cross

@@ -1,15 +0,0 @@
-# This image is meant to enable cross-architecture builds.
-# It assumes the reth binary has already been compiled for `$TARGETPLATFORM` and is
-# locatable in `./dist/bin/$TARGETARCH`
-FROM --platform=$TARGETPLATFORM ubuntu:22.04
-
-LABEL org.opencontainers.image.source=https://github.com/paradigmxyz/reth
-LABEL org.opencontainers.image.licenses="MIT OR Apache-2.0"
-
-# Filled by docker buildx
-ARG TARGETARCH
-
-COPY ./dist/bin/$TARGETARCH/reth /usr/local/bin/reth
-
-EXPOSE 30303 30303/udp 9001 8545 8546
-ENTRYPOINT ["/usr/local/bin/reth"]

Dockerfile.depot

@@ -0,0 +1,84 @@
+# syntax=docker/dockerfile:1
+
+# Unified Dockerfile for reth and op-reth, optimized for Depot builds
+# Usage:
+#   reth:    --build-arg BINARY=reth
+#   op-reth: --build-arg BINARY=op-reth --build-arg MANIFEST_PATH=crates/optimism/bin
+
+FROM rust:1 AS builder
+WORKDIR /app
+
+LABEL org.opencontainers.image.source=https://github.com/paradigmxyz/reth
+LABEL org.opencontainers.image.licenses="MIT OR Apache-2.0"
+
+RUN apt-get update && apt-get install -y libclang-dev pkg-config
+
+# Install sccache for compilation caching
+RUN cargo install sccache --locked
+ENV RUSTC_WRAPPER=sccache
+ENV SCCACHE_DIR=/sccache
+ENV SCCACHE_WEBDAV_ENDPOINT=https://cache.depot.dev
+
+# Binary to build (reth or op-reth)
+ARG BINARY=reth
+
+# Manifest path for the binary
+ARG MANIFEST_PATH=bin/reth
+
+# Build profile, release by default
+ARG BUILD_PROFILE=release
+ENV BUILD_PROFILE=$BUILD_PROFILE
+
+# Extra Cargo flags
+ARG RUSTFLAGS=""
+ENV RUSTFLAGS="$RUSTFLAGS"
+
+# Extra Cargo features
+ARG FEATURES=""
+ENV FEATURES=$FEATURES
+
+# Git info for vergen (since .git is excluded from Docker context)
+ARG VERGEN_GIT_SHA=""
+ARG VERGEN_GIT_DESCRIBE=""
+ARG VERGEN_GIT_DIRTY="false"
+ENV VERGEN_GIT_SHA=$VERGEN_GIT_SHA
+ENV VERGEN_GIT_DESCRIBE=$VERGEN_GIT_DESCRIBE
+ENV VERGEN_GIT_DIRTY=$VERGEN_GIT_DIRTY
+
+# Build application
+COPY --exclude=.git . .
+RUN --mount=type=secret,id=DEPOT_TOKEN,env=SCCACHE_WEBDAV_TOKEN \
+    --mount=type=cache,target=/usr/local/cargo/registry,sharing=shared \
+    --mount=type=cache,target=/usr/local/cargo/git,sharing=shared \
+    --mount=type=cache,target=$SCCACHE_DIR,sharing=shared \
+    cargo build --profile $BUILD_PROFILE --features "$FEATURES" --locked --bin $BINARY --manifest-path $MANIFEST_PATH/Cargo.toml
+
+RUN sccache --show-stats || true
+
+# Copy binary to a known location (ARG not resolved in COPY)
+# Note: Custom profiles like maxperf/profiling output to target/<profile>/, not target/release/
+RUN cp /app/target/$BUILD_PROFILE/$BINARY /app/binary || \
+    cp /app/target/release/$BINARY /app/binary
+
+FROM ubuntu:24.04 AS runtime
+WORKDIR /app
+
+# Binary name for entrypoint
+ARG BINARY=reth
+
+# Install runtime dependencies
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends ca-certificates && \
+    rm -rf /var/lib/apt/lists/*
+
+# Copy binary from build stage and create canonical symlink for entrypoint
+COPY --from=builder /app/binary /usr/local/bin/
+RUN mv /usr/local/bin/binary /usr/local/bin/$BINARY && \
+    ln -s /usr/local/bin/$BINARY /usr/local/bin/reth-binary && \
+    chmod +x /usr/local/bin/$BINARY
+
+# Copy licenses
+COPY LICENSE-* ./
+
+EXPOSE 30303 30303/udp 9001 8545 8546
+ENTRYPOINT ["/usr/local/bin/reth-binary"]

DockerfileOp.cross

@@ -1,15 +0,0 @@
-# This image is meant to enable cross-architecture builds.
-# It assumes the reth binary has already been compiled for `$TARGETPLATFORM` and is
-# locatable in `./dist/bin/$TARGETARCH`
-FROM --platform=$TARGETPLATFORM ubuntu:22.04
-
-LABEL org.opencontainers.image.source=https://github.com/paradigmxyz/reth
-LABEL org.opencontainers.image.licenses="MIT OR Apache-2.0"
-
-# Filled by docker buildx
-ARG TARGETARCH
-
-COPY ./dist/bin/$TARGETARCH/op-reth /usr/local/bin/op-reth
-
-EXPOSE 30303 30303/udp 9001 8545 8546
-ENTRYPOINT ["/usr/local/bin/op-reth"]

Makefile

@@ -35,9 +35,6 @@ EEST_TESTS_TAG := v4.5.0
 EEST_TESTS_URL := https://github.com/ethereum/execution-spec-tests/releases/download/$(EEST_TESTS_TAG)/fixtures_stable.tar.gz
 EEST_TESTS_DIR := ./testing/ef-tests/execution-spec-tests
 
-# The docker image name
-DOCKER_IMAGE_NAME ?= ghcr.io/paradigmxyz/reth
-
 ##@ Help
 
 .PHONY: help
@@ -242,137 +239,6 @@ install-reth-bench: ## Build and install the reth binary under `$(CARGO_HOME)/bi
 		--features "$(FEATURES)" \
 		--profile "$(PROFILE)"
 
-##@ Docker
-
-# Note: This requires a buildx builder with emulation support. For example:
-#
-# `docker run --privileged --rm tonistiigi/binfmt --install amd64,arm64`
-# `docker buildx create --use --driver docker-container --name cross-builder`
-.PHONY: docker-build-push
-docker-build-push: ## Build and push a cross-arch Docker image tagged with the latest git tag.
-	$(call docker_build_push,$(GIT_TAG),$(GIT_TAG))
-
-# Note: This requires a buildx builder with emulation support. For example:
-#
-# `docker run --privileged --rm tonistiigi/binfmt --install amd64,arm64`
-# `docker buildx create --use --driver docker-container --name cross-builder`
-.PHONY: docker-build-push-git-sha
-docker-build-push-git-sha: ## Build and push a cross-arch Docker image tagged with the latest git sha.
-	$(call docker_build_push,$(GIT_SHA),$(GIT_SHA))
-
-# Note: This requires a buildx builder with emulation support. For example:
-#
-# `docker run --privileged --rm tonistiigi/binfmt --install amd64,arm64`
-# `docker buildx create --use --driver docker-container --name cross-builder`
-.PHONY: docker-build-push-latest
-docker-build-push-latest: ## Build and push a cross-arch Docker image tagged with the latest git tag and `latest`.
-	$(call docker_build_push,$(GIT_TAG),latest)
-
-# Note: This requires a buildx builder with emulation support. For example:
-#
-# `docker run --privileged --rm tonistiigi/binfmt --install amd64,arm64`
-# `docker buildx create --use --name cross-builder`
-.PHONY: docker-build-push-nightly
-docker-build-push-nightly: ## Build and push cross-arch Docker image tagged with the latest git tag with a `-nightly` suffix, and `latest-nightly`.
-	$(call docker_build_push,nightly,nightly)
-
-.PHONY: docker-build-push-nightly-edge-profiling
-docker-build-push-nightly-edge-profiling: FEATURES := $(FEATURES) edge
-docker-build-push-nightly-edge-profiling: ## Build and push cross-arch Docker image with edge features tagged with `nightly-edge-profiling`.
-	$(call docker_build_push,nightly-edge-profiling,nightly-edge-profiling)
-
-# Create a cross-arch Docker image with the given tags and push it
-define docker_build_push
-	$(MAKE) FEATURES="$(FEATURES)" build-x86_64-unknown-linux-gnu
-	mkdir -p $(BIN_DIR)/amd64
-	cp $(CARGO_TARGET_DIR)/x86_64-unknown-linux-gnu/$(PROFILE)/reth $(BIN_DIR)/amd64/reth
-
-	$(MAKE) FEATURES="$(FEATURES)" build-aarch64-unknown-linux-gnu
-	mkdir -p $(BIN_DIR)/arm64
-	cp $(CARGO_TARGET_DIR)/aarch64-unknown-linux-gnu/$(PROFILE)/reth $(BIN_DIR)/arm64/reth
-
-	docker buildx build --file ./Dockerfile.cross . \
-		--platform linux/amd64,linux/arm64 \
-		--tag $(DOCKER_IMAGE_NAME):$(1) \
-		--tag $(DOCKER_IMAGE_NAME):$(2) \
-		--provenance=false \
-		--push
-endef
-
-##@ Optimism docker
-
-# Note: This requires a buildx builder with emulation support. For example:
-#
-# `docker run --privileged --rm tonistiigi/binfmt --install amd64,arm64`
-# `docker buildx create --use --driver docker-container --name cross-builder`
-.PHONY: op-docker-build-push
-op-docker-build-push: ## Build and push a cross-arch Docker image tagged with the latest git tag.
-	$(call op_docker_build_push,$(GIT_TAG),$(GIT_TAG))
-
-# Note: This requires a buildx builder with emulation support. For example:
-#
-# `docker run --privileged --rm tonistiigi/binfmt --install amd64,arm64`
-# `docker buildx create --use --driver docker-container --name cross-builder`
-.PHONY: op-docker-build-push-git-sha
-op-docker-build-push-git-sha: ## Build and push a cross-arch Docker image tagged with the latest git sha.
-	$(call op_docker_build_push,$(GIT_SHA),$(GIT_SHA))
-
-# Note: This requires a buildx builder with emulation support. For example:
-#
-# `docker run --privileged --rm tonistiigi/binfmt --install amd64,arm64`
-# `docker buildx create --use --driver docker-container --name cross-builder`
-.PHONY: op-docker-build-push-latest
-op-docker-build-push-latest: ## Build and push a cross-arch Docker image tagged with the latest git tag and `latest`.
-	$(call op_docker_build_push,$(GIT_TAG),latest)
-
-# Note: This requires a buildx builder with emulation support. For example:
-#
-# `docker run --privileged --rm tonistiigi/binfmt --install amd64,arm64`
-# `docker buildx create --use --name cross-builder`
-.PHONY: op-docker-build-push-nightly
-op-docker-build-push-nightly: ## Build and push cross-arch Docker image tagged with the latest git tag with a `-nightly` suffix, and `latest-nightly`.
-	$(call op_docker_build_push,nightly,nightly)
-
-.PHONY: op-docker-build-push-nightly-edge-profiling
-op-docker-build-push-nightly-edge-profiling: FEATURES := $(FEATURES) edge
-op-docker-build-push-nightly-edge-profiling: ## Build and push cross-arch Docker image with edge features tagged with `nightly-edge-profiling`.
-	$(call op_docker_build_push,nightly-edge-profiling,nightly-edge-profiling)
-
-# Note: This requires a buildx builder with emulation support. For example:
-#
-# `docker run --privileged --rm tonistiigi/binfmt --install amd64,arm64`
-# `docker buildx create --use --name cross-builder`
-.PHONY: docker-build-push-nightly-profiling
-docker-build-push-nightly-profiling: ## Build and push cross-arch Docker image with profiling profile tagged with nightly-profiling.
-	$(call docker_build_push,nightly-profiling,nightly-profiling)
-
-	# Note: This requires a buildx builder with emulation support. For example:
-#
-# `docker run --privileged --rm tonistiigi/binfmt --install amd64,arm64`
-# `docker buildx create --use --name cross-builder`
-.PHONY: op-docker-build-push-nightly-profiling
-op-docker-build-push-nightly-profiling: ## Build and push cross-arch Docker image tagged with the latest git tag with a `-nightly` suffix, and `latest-nightly`.
-	$(call op_docker_build_push,nightly-profiling,nightly-profiling)
-
-
-# Create a cross-arch Docker image with the given tags and push it
-define op_docker_build_push
-	$(MAKE) FEATURES="$(FEATURES)" op-build-x86_64-unknown-linux-gnu
-	mkdir -p $(BIN_DIR)/amd64
-	cp $(CARGO_TARGET_DIR)/x86_64-unknown-linux-gnu/$(PROFILE)/op-reth $(BIN_DIR)/amd64/op-reth
-
-	$(MAKE) FEATURES="$(FEATURES)" op-build-aarch64-unknown-linux-gnu
-	mkdir -p $(BIN_DIR)/arm64
-	cp $(CARGO_TARGET_DIR)/aarch64-unknown-linux-gnu/$(PROFILE)/op-reth $(BIN_DIR)/arm64/op-reth
-
-	docker buildx build --file ./DockerfileOp.cross . \
-		--platform linux/amd64,linux/arm64 \
-		--tag $(DOCKER_IMAGE_NAME):$(1) \
-		--tag $(DOCKER_IMAGE_NAME):$(2) \
-		--provenance=false \
-		--push
-endef
-
 ##@ Other
 
 .PHONY: clean

bin/reth-bench-compare/Cargo.toml

@@ -56,7 +56,7 @@ ctrlc.workspace = true
 shlex.workspace = true
 
 [target.'cfg(unix)'.dependencies]
-nix = { version = "0.29", features = ["signal", "process"] }
+nix = { version = "0.31", features = ["signal", "process"] }
 
 [features]
 default = ["jemalloc"]

bin/reth-bench-compare/src/cli.rs

@@ -274,10 +274,10 @@ impl Args {
     /// Get the default RPC URL for a given chain
     const fn get_default_rpc_url(chain: &Chain) -> &'static str {
         match chain.id() {
-            8453 => "https://base-mainnet.rpc.ithaca.xyz",  // base
+            8453 => "https://base.reth.rs/rpc",             // base
             84532 => "https://base-sepolia.rpc.ithaca.xyz", // base-sepolia
             27082 => "https://rpc.hoodi.ethpandaops.io",    // hoodi
-            _ => "https://reth-ethereum.ithaca.xyz/rpc",    // mainnet and fallback
+            _ => "https://ethereum.reth.rs/rpc",            // mainnet and fallback
         }
     }
 

bin/reth-bench/Cargo.toml

@@ -32,7 +32,7 @@ alloy-eips.workspace = true
 alloy-json-rpc.workspace = true
 alloy-consensus.workspace = true
 alloy-network.workspace = true
-alloy-primitives.workspace = true
+alloy-primitives = { workspace = true, features = ["rand"] }
 alloy-provider = { workspace = true, features = ["engine-api", "pubsub", "reqwest-rustls-tls"], default-features = false }
 alloy-pubsub.workspace = true
 alloy-rpc-client = { workspace = true, features = ["pubsub"] }
@@ -45,7 +45,7 @@ op-alloy-consensus = { workspace = true, features = ["alloy-compat"] }
 op-alloy-rpc-types-engine = { workspace = true, features = ["serde"] }
 
 # reqwest
-reqwest = { workspace = true, default-features = false, features = ["rustls-tls-native-roots"] }
+reqwest.workspace = true
 
 # tower
 tower.workspace = true

bin/reth-bench/src/bench/gas_limit_ramp.rs

@@ -3,7 +3,7 @@
 use crate::{
     authenticated_transport::AuthenticatedTransportConnect,
     bench::{
-        helpers::{build_payload, prepare_payload_request, rpc_block_to_header},
+        helpers::{build_payload, parse_gas_limit, prepare_payload_request, rpc_block_to_header},
         output::GasRampPayloadFile,
     },
     valid_payload::{call_forkchoice_updated, call_new_payload, payload_to_new_payload},
@@ -25,9 +25,16 @@ use tracing::info;
 /// `reth benchmark gas-limit-ramp` command.
 #[derive(Debug, Parser)]
 pub struct Command {
-    /// Number of blocks to generate.
-    #[arg(long, value_name = "BLOCKS")]
-    blocks: u64,
+    /// Number of blocks to generate. Mutually exclusive with --target-gas-limit.
+    #[arg(long, value_name = "BLOCKS", conflicts_with = "target_gas_limit")]
+    blocks: Option<u64>,
+
+    /// Target gas limit to ramp up to. The benchmark will generate blocks until the gas limit
+    /// reaches or exceeds this value. Mutually exclusive with --blocks.
+    /// Accepts short notation: K for thousand, M for million, G for billion (e.g., 2G = 2
+    /// billion).
+    #[arg(long, value_name = "TARGET_GAS_LIMIT", conflicts_with = "blocks", value_parser = parse_gas_limit)]
+    target_gas_limit: Option<u64>,
 
     /// The Engine API RPC URL.
     #[arg(long = "engine-rpc-url", value_name = "ENGINE_RPC_URL")]
@@ -42,12 +49,37 @@ pub struct Command {
     output: PathBuf,
 }
 
+/// Mode for determining when to stop ramping.
+#[derive(Debug, Clone, Copy)]
+enum RampMode {
+    /// Ramp for a fixed number of blocks.
+    Blocks(u64),
+    /// Ramp until reaching or exceeding target gas limit.
+    TargetGasLimit(u64),
+}
+
 impl Command {
     /// Execute `benchmark gas-limit-ramp` command.
     pub async fn execute(self, _ctx: CliContext) -> eyre::Result<()> {
-        if self.blocks == 0 {
-            return Err(eyre::eyre!("--blocks must be greater than 0"));
-        }
+        let mode = match (self.blocks, self.target_gas_limit) {
+            (Some(blocks), None) => {
+                if blocks == 0 {
+                    return Err(eyre::eyre!("--blocks must be greater than 0"));
+                }
+                RampMode::Blocks(blocks)
+            }
+            (None, Some(target)) => {
+                if target == 0 {
+                    return Err(eyre::eyre!("--target-gas-limit must be greater than 0"));
+                }
+                RampMode::TargetGasLimit(target)
+            }
+            _ => {
+                return Err(eyre::eyre!(
+                    "Exactly one of --blocks or --target-gas-limit must be specified"
+                ));
+            }
+        };
 
         // Ensure output directory exists
         if self.output.is_file() {
@@ -84,14 +116,31 @@ impl Command {
 
         let canonical_parent = parent_header.number;
         let start_block = canonical_parent + 1;
-        let end_block = start_block + self.blocks - 1;
 
-        info!(canonical_parent, start_block, end_block, "Starting gas limit ramp benchmark");
+        match mode {
+            RampMode::Blocks(blocks) => {
+                info!(
+                    canonical_parent,
+                    start_block,
+                    end_block = start_block + blocks - 1,
+                    "Starting gas limit ramp benchmark (block count mode)"
+                );
+            }
+            RampMode::TargetGasLimit(target) => {
+                info!(
+                    canonical_parent,
+                    start_block,
+                    current_gas_limit = parent_header.gas_limit,
+                    target_gas_limit = target,
+                    "Starting gas limit ramp benchmark (target gas limit mode)"
+                );
+            }
+        }
 
-        let mut next_block_number = start_block;
+        let mut blocks_processed = 0u64;
         let total_benchmark_duration = Instant::now();
 
-        while next_block_number <= end_block {
+        while !should_stop(mode, blocks_processed, parent_header.gas_limit) {
             let timestamp = parent_header.timestamp.saturating_add(1);
 
             let request = prepare_payload_request(&chain_spec, timestamp, parent_hash);
@@ -140,13 +189,13 @@ impl Command {
 
             parent_header = block.header;
             parent_hash = block_hash;
-            next_block_number += 1;
+            blocks_processed += 1;
         }
 
         let final_gas_limit = parent_header.gas_limit;
         info!(
             total_duration=?total_benchmark_duration.elapsed(),
-            blocks_processed = self.blocks,
+            blocks_processed,
             final_gas_limit,
             "Benchmark complete"
         );
@@ -158,3 +207,10 @@ impl Command {
 const fn max_gas_limit_increase(parent_gas_limit: u64) -> u64 {
     (parent_gas_limit / GAS_LIMIT_BOUND_DIVISOR).saturating_sub(1)
 }
+
+const fn should_stop(mode: RampMode, blocks_processed: u64, current_gas_limit: u64) -> bool {
+    match mode {
+        RampMode::Blocks(target_blocks) => blocks_processed >= target_blocks,
+        RampMode::TargetGasLimit(target) => current_gas_limit >= target,
+    }
+}

bin/reth-bench/src/bench/generate_big_block.rs

@@ -3,7 +3,9 @@
 //! This command fetches transactions from existing blocks and packs them into a single
 //! large block using the `testing_buildBlockV1` RPC endpoint.
 
-use crate::authenticated_transport::AuthenticatedTransportConnect;
+use crate::{
+    authenticated_transport::AuthenticatedTransportConnect, bench::helpers::parse_gas_limit,
+};
 use alloy_eips::{BlockNumberOrTag, Typed2718};
 use alloy_primitives::{Bytes, B256};
 use alloy_provider::{ext::EngineApi, network::AnyNetwork, Provider, RootProvider};
@@ -130,13 +132,24 @@ impl<S: TransactionSource> TransactionCollector<S> {
     /// Collect transactions starting from the given block number.
     ///
     /// Skips blob transactions (type 3) and collects until target gas is reached.
-    /// Returns the collected raw transaction bytes, total gas used, and the next block number.
-    pub async fn collect(&self, start_block: u64) -> eyre::Result<(Vec<Bytes>, u64, u64)> {
-        let mut transactions: Vec<Bytes> = Vec::new();
+    /// Returns a `CollectionResult` with transactions, gas info, and next block.
+    pub async fn collect(&self, start_block: u64) -> eyre::Result<CollectionResult> {
+        self.collect_gas(start_block, self.target_gas).await
+    }
+
+    /// Collect transactions up to a specific gas target.
+    ///
+    /// This is used both for initial collection and for retry top-ups.
+    pub async fn collect_gas(
+        &self,
+        start_block: u64,
+        gas_target: u64,
+    ) -> eyre::Result<CollectionResult> {
+        let mut transactions: Vec<RawTransaction> = Vec::new();
         let mut total_gas: u64 = 0;
         let mut current_block = start_block;
 
-        while total_gas < self.target_gas {
+        while total_gas < gas_target {
             let Some((block_txs, _)) = self.source.fetch_block_transactions(current_block).await?
             else {
                 warn!(block = current_block, "Block not found, stopping");
@@ -149,12 +162,12 @@ impl<S: TransactionSource> TransactionCollector<S> {
                     continue;
                 }
 
-                if total_gas + tx.gas_used <= self.target_gas {
-                    transactions.push(tx.raw);
+                if total_gas + tx.gas_used <= gas_target {
                     total_gas += tx.gas_used;
+                    transactions.push(tx);
                 }
 
-                if total_gas >= self.target_gas {
+                if total_gas >= gas_target {
                     break;
                 }
             }
@@ -162,7 +175,7 @@ impl<S: TransactionSource> TransactionCollector<S> {
             current_block += 1;
 
             // Stop early if remaining gas is under 1M (close enough to target)
-            let remaining_gas = self.target_gas.saturating_sub(total_gas);
+            let remaining_gas = gas_target.saturating_sub(total_gas);
             if remaining_gas < 1_000_000 {
                 break;
             }
@@ -170,12 +183,12 @@ impl<S: TransactionSource> TransactionCollector<S> {
 
         info!(
             total_txs = transactions.len(),
-            total_gas,
+            gas_sent = total_gas,
             next_block = current_block,
             "Finished collecting transactions"
         );
 
-        Ok((transactions, total_gas, current_block))
+        Ok(CollectionResult { transactions, gas_sent: total_gas, next_block: current_block })
     }
 }
 
@@ -202,13 +215,26 @@ pub struct Command {
     jwt_secret: std::path::PathBuf,
 
     /// Target gas to pack into the block.
-    #[arg(long, value_name = "TARGET_GAS", default_value = "30000000")]
+    /// Accepts short notation: K for thousand, M for million, G for billion (e.g., 1G = 1
+    /// billion).
+    #[arg(long, value_name = "TARGET_GAS", default_value = "30000000", value_parser = parse_gas_limit)]
     target_gas: u64,
 
-    /// Starting block number to fetch transactions from.
-    /// If not specified, starts from the engine's latest block.
+    /// Block number to start fetching transactions from (required).
+    ///
+    /// This must be the last canonical block BEFORE any gas limit ramping was performed.
+    /// The command collects transactions from historical blocks starting at this number
+    /// to pack into large blocks.
+    ///
+    /// How to determine this value:
+    /// - If starting from a fresh node (no gas limit ramp yet): use the current chain tip
+    /// - If gas limit ramping has already been performed: use the block number that was the chain
+    ///   tip BEFORE ramping began (you must track this yourself)
+    ///
+    /// Using a block after ramping started will cause transaction collection to fail
+    /// because those blocks contain synthetic transactions that cannot be replayed.
     #[arg(long, value_name = "FROM_BLOCK")]
-    from_block: Option<u64>,
+    from_block: u64,
 
     /// Execute the payload (call newPayload + forkchoiceUpdated).
     /// If false, only builds the payload and prints it.
@@ -237,6 +263,80 @@ struct BuiltPayload {
     envelope: ExecutionPayloadEnvelopeV4,
     block_hash: B256,
     timestamp: u64,
+    /// The actual gas used in the built block.
+    gas_used: u64,
+}
+
+/// Result of collecting transactions from blocks.
+#[derive(Debug)]
+pub struct CollectionResult {
+    /// Collected transactions with their gas info.
+    pub transactions: Vec<RawTransaction>,
+    /// Total gas sent (sum of historical `gas_used` for all collected txs).
+    pub gas_sent: u64,
+    /// Next block number to continue collecting from.
+    pub next_block: u64,
+}
+
+/// Constants for retry logic.
+const MAX_BUILD_RETRIES: u32 = 5;
+/// Maximum retries for fetching a transaction batch.
+const MAX_FETCH_RETRIES: u32 = 5;
+/// Tolerance: if `gas_used` is within 1M of target, don't retry.
+const MIN_TARGET_SLACK: u64 = 1_000_000;
+/// Maximum gas to request in retries (10x target as safety cap).
+const MAX_ADDITIONAL_GAS_MULTIPLIER: u64 = 10;
+
+/// Fetches a batch of transactions with retry logic.
+///
+/// Returns `None` if all retries are exhausted.
+async fn fetch_batch_with_retry<S: TransactionSource>(
+    collector: &TransactionCollector<S>,
+    block: u64,
+) -> Option<CollectionResult> {
+    for attempt in 1..=MAX_FETCH_RETRIES {
+        match collector.collect(block).await {
+            Ok(result) => return Some(result),
+            Err(e) => {
+                if attempt == MAX_FETCH_RETRIES {
+                    warn!(attempt, error = %e, "Failed to fetch transactions after max retries");
+                    return None;
+                }
+                warn!(attempt, error = %e, "Failed to fetch transactions, retrying...");
+                tokio::time::sleep(std::time::Duration::from_secs(1)).await;
+            }
+        }
+    }
+    None
+}
+
+/// Outcome of a build attempt check.
+enum RetryOutcome {
+    /// Payload is close enough to target gas.
+    Success,
+    /// Max retries reached, accept what we have.
+    MaxRetries,
+    /// Need more transactions with the specified gas amount.
+    NeedMore(u64),
+}
+
+/// Buffer for receiving transaction batches from the fetcher.
+///
+/// This abstracts over the channel to allow the main loop to request
+/// batches on demand, including for retries.
+struct TxBuffer {
+    receiver: mpsc::Receiver<CollectionResult>,
+}
+
+impl TxBuffer {
+    const fn new(receiver: mpsc::Receiver<CollectionResult>) -> Self {
+        Self { receiver }
+    }
+
+    /// Take the next available batch from the fetcher.
+    async fn take_batch(&mut self) -> Option<CollectionResult> {
+        self.receiver.recv().await
+    }
 }
 
 impl Command {
@@ -284,7 +384,7 @@ impl Command {
             format!("Failed to create output directory: {:?}", self.output_dir)
         })?;
 
-        let start_block = self.from_block.unwrap_or(parent_number);
+        let start_block = self.from_block;
 
         // Use pipelined execution when generating multiple payloads
         if self.count > 1 {
@@ -297,19 +397,20 @@ impl Command {
             )
             .await?;
         } else {
-            // Single payload - collect transactions and build
+            // Single payload - collect transactions and build with retry
             let tx_source = RpcTransactionSource::from_url(&self.rpc_url)?;
             let collector = TransactionCollector::new(tx_source, self.target_gas);
-            let (transactions, _total_gas, _next_block) = collector.collect(start_block).await?;
+            let result = collector.collect(start_block).await?;
 
-            if transactions.is_empty() {
+            if result.transactions.is_empty() {
                 return Err(eyre::eyre!("No transactions collected"));
             }
 
-            self.execute_sequential(
+            self.execute_sequential_with_retry(
                 &auth_provider,
                 &testing_provider,
-                transactions,
+                &collector,
+                result,
                 parent_hash,
                 parent_timestamp,
             )
@@ -320,32 +421,34 @@ impl Command {
         Ok(())
     }
 
-    /// Sequential execution path for single payload or no-execute mode.
-    async fn execute_sequential(
+    /// Sequential execution path with retry logic for underfilled payloads.
+    async fn execute_sequential_with_retry<S: TransactionSource>(
         &self,
         auth_provider: &RootProvider<AnyNetwork>,
         testing_provider: &RootProvider<AnyNetwork>,
-        transactions: Vec<Bytes>,
+        collector: &TransactionCollector<S>,
+        initial_result: CollectionResult,
         mut parent_hash: B256,
         mut parent_timestamp: u64,
     ) -> eyre::Result<()> {
-        for i in 0..self.count {
-            info!(
-                payload = i + 1,
-                total = self.count,
-                parent_hash = %parent_hash,
-                parent_timestamp = parent_timestamp,
-                "Building payload via testing_buildBlockV1"
-            );
+        let mut current_result = initial_result;
 
+        for i in 0..self.count {
             let built = self
-                .build_payload(testing_provider, &transactions, i, parent_hash, parent_timestamp)
+                .build_with_retry(
+                    testing_provider,
+                    collector,
+                    &mut current_result,
+                    i,
+                    parent_hash,
+                    parent_timestamp,
+                )
                 .await?;
 
             self.save_payload(&built)?;
 
             if self.execute || self.count > 1 {
-                info!(payload = i + 1, block_hash = %built.block_hash, "Executing payload (newPayload + FCU)");
+                info!(payload = i + 1, block_hash = %built.block_hash, gas_used = built.gas_used, "Executing payload (newPayload + FCU)");
                 self.execute_payload_v4(auth_provider, built.envelope, parent_hash).await?;
                 info!(payload = i + 1, "Payload executed successfully");
             }
@@ -356,7 +459,62 @@ impl Command {
         Ok(())
     }
 
-    /// Pipelined execution - fetches transactions and builds payloads in background.
+    /// Build a payload with retry logic when `gas_used` is below target.
+    ///
+    /// Uses the ratio of `gas_used/gas_sent` to estimate how many more transactions
+    /// are needed to hit the target gas.
+    async fn build_with_retry<S: TransactionSource>(
+        &self,
+        testing_provider: &RootProvider<AnyNetwork>,
+        collector: &TransactionCollector<S>,
+        result: &mut CollectionResult,
+        index: u64,
+        parent_hash: B256,
+        parent_timestamp: u64,
+    ) -> eyre::Result<BuiltPayload> {
+        for attempt in 1..=MAX_BUILD_RETRIES {
+            let tx_bytes: Vec<Bytes> = result.transactions.iter().map(|t| t.raw.clone()).collect();
+            let gas_sent = result.gas_sent;
+
+            info!(
+                payload = index + 1,
+                attempt,
+                tx_count = tx_bytes.len(),
+                gas_sent,
+                parent_hash = %parent_hash,
+                "Building payload via testing_buildBlockV1"
+            );
+
+            let built = Self::build_payload_static(
+                testing_provider,
+                &tx_bytes,
+                index,
+                parent_hash,
+                parent_timestamp,
+            )
+            .await?;
+
+            match self.check_retry_outcome(&built, index, attempt, gas_sent) {
+                RetryOutcome::Success | RetryOutcome::MaxRetries => return Ok(built),
+                RetryOutcome::NeedMore(additional_gas) => {
+                    let additional =
+                        collector.collect_gas(result.next_block, additional_gas).await?;
+                    result.transactions.extend(additional.transactions);
+                    result.gas_sent = result.gas_sent.saturating_add(additional.gas_sent);
+                    result.next_block = additional.next_block;
+                }
+            }
+        }
+
+        warn!(payload = index + 1, "Retry loop exited without returning a payload");
+        Err(eyre::eyre!("build_with_retry exhausted retries without result"))
+    }
+
+    /// Pipelined execution - fetches transactions in background, builds with retry.
+    ///
+    /// The fetcher continuously produces transaction batches. The main loop consumes them,
+    /// builds payloads with retry logic (requesting more transactions if underfilled),
+    /// and executes each payload before moving to the next.
     async fn execute_pipelined(
         &self,
         auth_provider: &RootProvider<AnyNetwork>,
@@ -365,167 +523,229 @@ impl Command {
         initial_parent_hash: B256,
         initial_parent_timestamp: u64,
     ) -> eyre::Result<()> {
-        // Create channel for transaction batches (one batch per payload)
-        let (tx_sender, mut tx_receiver) = mpsc::channel::<Vec<Bytes>>(self.prefetch_buffer);
+        // Create channel for transaction batches - fetcher sends CollectionResult
+        let (tx_sender, tx_receiver) = mpsc::channel::<CollectionResult>(self.prefetch_buffer);
 
         // Spawn background task to continuously fetch transaction batches
         let rpc_url = self.rpc_url.clone();
         let target_gas = self.target_gas;
-        let count = self.count;
 
         let fetcher_handle = tokio::spawn(async move {
             let tx_source = match RpcTransactionSource::from_url(&rpc_url) {
                 Ok(source) => source,
                 Err(e) => {
                     warn!(error = %e, "Failed to create transaction source");
-                    return;
+                    return None;
                 }
             };
 
             let collector = TransactionCollector::new(tx_source, target_gas);
             let mut current_block = start_block;
 
-            for payload_idx in 0..count {
-                match collector.collect(current_block).await {
-                    Ok((transactions, total_gas, next_block)) => {
-                        info!(
-                            payload = payload_idx + 1,
-                            tx_count = transactions.len(),
-                            total_gas,
-                            blocks = format!("{}..{}", current_block, next_block),
-                            "Fetched transactions"
-                        );
-                        current_block = next_block;
-
-                        if tx_sender.send(transactions).await.is_err() {
-                            break;
-                        }
-                    }
-                    Err(e) => {
-                        warn!(payload = payload_idx + 1, error = %e, "Failed to fetch transactions");
-                        break;
-                    }
-                }
-            }
-        });
-
-        let mut parent_hash = initial_parent_hash;
-        let mut parent_timestamp = initial_parent_timestamp;
-        let mut pending_build: Option<tokio::task::JoinHandle<eyre::Result<BuiltPayload>>> = None;
-
-        for i in 0..self.count {
-            let is_last = i == self.count - 1;
-
-            // Get current payload (either from pending build or build now)
-            let current_payload = if let Some(handle) = pending_build.take() {
-                handle.await??
-            } else {
-                // First payload - wait for transactions and build synchronously
-                let transactions = tx_receiver
-                    .recv()
-                    .await
-                    .ok_or_else(|| eyre::eyre!("Transaction fetcher stopped unexpectedly"))?;
-
-                if transactions.is_empty() {
-                    return Err(eyre::eyre!("No transactions collected for payload {}", i + 1));
+            while let Some(batch) = fetch_batch_with_retry(&collector, current_block).await {
+                if batch.transactions.is_empty() {
+                    info!(block = current_block, "Reached chain tip, stopping fetcher");
+                    break;
                 }
 
                 info!(
-                    payload = i + 1,
-                    total = self.count,
-                    parent_hash = %parent_hash,
-                    parent_timestamp = parent_timestamp,
-                    tx_count = transactions.len(),
-                    "Building payload via testing_buildBlockV1"
+                    tx_count = batch.transactions.len(),
+                    gas_sent = batch.gas_sent,
+                    blocks = format!("{}..{}", current_block, batch.next_block),
+                    "Fetched transaction batch"
                 );
-                self.build_payload(
+                current_block = batch.next_block;
+
+                if tx_sender.send(batch).await.is_err() {
+                    break;
+                }
+            }
+
+            Some(current_block)
+        });
+
+        // Transaction buffer: holds transactions from batches + any extras from retries
+        let mut tx_buffer = TxBuffer::new(tx_receiver);
+
+        let mut parent_hash = initial_parent_hash;
+        let mut parent_timestamp = initial_parent_timestamp;
+
+        for i in 0..self.count {
+            // Get initial batch of transactions for this payload
+            let Some(mut result) = tx_buffer.take_batch().await else {
+                info!(
+                    payloads_built = i,
+                    payloads_requested = self.count,
+                    "Transaction source exhausted, stopping"
+                );
+                break;
+            };
+
+            if result.transactions.is_empty() {
+                info!(
+                    payloads_built = i,
+                    payloads_requested = self.count,
+                    "No more transactions available, stopping"
+                );
+                break;
+            }
+
+            // Build with retry - may need to request more transactions
+            let built = self
+                .build_with_retry_buffered(
                     testing_provider,
-                    &transactions,
+                    &mut tx_buffer,
+                    &mut result,
                     i,
                     parent_hash,
                     parent_timestamp,
                 )
-                .await?
-            };
+                .await?;
 
-            self.save_payload(&current_payload)?;
+            self.save_payload(&built)?;
 
-            let current_block_hash = current_payload.block_hash;
-            let current_timestamp = current_payload.timestamp;
+            let current_block_hash = built.block_hash;
+            let current_timestamp = built.timestamp;
 
-            // Execute current payload first
-            info!(payload = i + 1, block_hash = %current_block_hash, "Executing payload (newPayload + FCU)");
-            self.execute_payload_v4(auth_provider, current_payload.envelope, parent_hash).await?;
+            // Execute payload
+            info!(payload = i + 1, block_hash = %current_block_hash, gas_used = built.gas_used, "Executing payload (newPayload + FCU)");
+            self.execute_payload_v4(auth_provider, built.envelope, parent_hash).await?;
             info!(payload = i + 1, "Payload executed successfully");
 
-            // Start building next payload in background (if not last) - AFTER execution
-            if !is_last {
-                // Get transactions for next payload (should already be fetched or fetching)
-                let next_transactions = tx_receiver
-                    .recv()
-                    .await
-                    .ok_or_else(|| eyre::eyre!("Transaction fetcher stopped unexpectedly"))?;
-
-                if next_transactions.is_empty() {
-                    return Err(eyre::eyre!("No transactions collected for payload {}", i + 2));
-                }
-
-                let testing_provider = testing_provider.clone();
-                let next_index = i + 1;
-                let total = self.count;
-
-                pending_build = Some(tokio::spawn(async move {
-                    info!(
-                        payload = next_index + 1,
-                        total = total,
-                        parent_hash = %current_block_hash,
-                        parent_timestamp = current_timestamp,
-                        tx_count = next_transactions.len(),
-                        "Building payload via testing_buildBlockV1"
-                    );
-
-                    Self::build_payload_static(
-                        &testing_provider,
-                        &next_transactions,
-                        next_index,
-                        current_block_hash,
-                        current_timestamp,
-                    )
-                    .await
-                }));
-            }
-
             parent_hash = current_block_hash;
             parent_timestamp = current_timestamp;
         }
 
         // Clean up the fetcher task
-        drop(tx_receiver);
+        drop(tx_buffer);
         let _ = fetcher_handle.await;
 
         Ok(())
     }
 
-    /// Build a single payload via `testing_buildBlockV1`.
-    async fn build_payload(
+    /// Build a payload with retry logic, using the buffered transaction source.
+    async fn build_with_retry_buffered(
         &self,
         testing_provider: &RootProvider<AnyNetwork>,
-        transactions: &[Bytes],
+        tx_buffer: &mut TxBuffer,
+        result: &mut CollectionResult,
         index: u64,
         parent_hash: B256,
         parent_timestamp: u64,
     ) -> eyre::Result<BuiltPayload> {
-        Self::build_payload_static(
-            testing_provider,
-            transactions,
-            index,
-            parent_hash,
-            parent_timestamp,
-        )
-        .await
+        for attempt in 1..=MAX_BUILD_RETRIES {
+            let tx_bytes: Vec<Bytes> = result.transactions.iter().map(|t| t.raw.clone()).collect();
+            let gas_sent = result.gas_sent;
+
+            info!(
+                payload = index + 1,
+                attempt,
+                tx_count = tx_bytes.len(),
+                gas_sent,
+                parent_hash = %parent_hash,
+                "Building payload via testing_buildBlockV1"
+            );
+
+            let built = Self::build_payload_static(
+                testing_provider,
+                &tx_bytes,
+                index,
+                parent_hash,
+                parent_timestamp,
+            )
+            .await?;
+
+            match self.check_retry_outcome(&built, index, attempt, gas_sent) {
+                RetryOutcome::Success | RetryOutcome::MaxRetries => return Ok(built),
+                RetryOutcome::NeedMore(additional_gas) => {
+                    let mut collected_gas = 0u64;
+                    while collected_gas < additional_gas {
+                        if let Some(batch) = tx_buffer.take_batch().await {
+                            collected_gas += batch.gas_sent;
+                            result.transactions.extend(batch.transactions);
+                            result.gas_sent = result.gas_sent.saturating_add(batch.gas_sent);
+                            result.next_block = batch.next_block;
+                        } else {
+                            warn!("Transaction fetcher exhausted, proceeding with available transactions");
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+
+        warn!(payload = index + 1, "Retry loop exited without returning a payload");
+        Err(eyre::eyre!("build_with_retry_buffered exhausted retries without result"))
     }
 
-    /// Static version for use in spawned tasks.
+    /// Determines the outcome of a build attempt.
+    fn check_retry_outcome(
+        &self,
+        built: &BuiltPayload,
+        index: u64,
+        attempt: u32,
+        gas_sent: u64,
+    ) -> RetryOutcome {
+        let gas_used = built.gas_used;
+
+        if gas_used + MIN_TARGET_SLACK >= self.target_gas {
+            info!(
+                payload = index + 1,
+                gas_used,
+                target_gas = self.target_gas,
+                attempts = attempt,
+                "Payload built successfully"
+            );
+            return RetryOutcome::Success;
+        }
+
+        if attempt == MAX_BUILD_RETRIES {
+            warn!(
+                payload = index + 1,
+                gas_used,
+                target_gas = self.target_gas,
+                gas_sent,
+                "Underfilled after max retries, accepting payload"
+            );
+            return RetryOutcome::MaxRetries;
+        }
+
+        if gas_used == 0 {
+            warn!(
+                payload = index + 1,
+                "Zero gas used in payload, requesting fixed chunk of additional transactions"
+            );
+            return RetryOutcome::NeedMore(self.target_gas);
+        }
+
+        let gas_sent_needed_total =
+            (self.target_gas as u128 * gas_sent as u128).div_ceil(gas_used as u128) as u64;
+        let additional = gas_sent_needed_total.saturating_sub(gas_sent);
+        let additional = additional.min(self.target_gas * MAX_ADDITIONAL_GAS_MULTIPLIER);
+
+        if additional == 0 {
+            info!(
+                payload = index + 1,
+                gas_used,
+                target_gas = self.target_gas,
+                "No additional transactions needed based on ratio"
+            );
+            return RetryOutcome::Success;
+        }
+
+        let ratio = gas_used as f64 / gas_sent as f64;
+        info!(
+            payload = index + 1,
+            gas_used,
+            gas_sent,
+            ratio = format!("{:.4}", ratio),
+            additional_gas = additional,
+            "Underfilled, collecting more transactions for retry"
+        );
+        RetryOutcome::NeedMore(additional)
+    }
+
+    /// Build a single payload via `testing_buildBlockV1`.
     async fn build_payload_static(
         testing_provider: &RootProvider<AnyNetwork>,
         transactions: &[Bytes],
@@ -563,8 +783,9 @@ impl Command {
         let block_hash = inner.block_hash;
         let block_number = inner.block_number;
         let timestamp = inner.timestamp;
+        let gas_used = inner.gas_used;
 
-        Ok(BuiltPayload { block_number, envelope: v4_envelope, block_hash, timestamp })
+        Ok(BuiltPayload { block_number, envelope: v4_envelope, block_hash, timestamp, gas_used })
     }
 
     /// Save a payload to disk.

bin/reth-bench/src/bench/helpers.rs

@@ -1,6 +1,56 @@
 //! Common helpers for reth-bench commands.
 
 use crate::valid_payload::call_forkchoice_updated;
+use eyre::Result;
+use std::io::{BufReader, Read};
+
+/// Read input from either a file path or stdin.
+pub(crate) fn read_input(path: Option<&str>) -> Result<String> {
+    Ok(match path {
+        Some(path) => reth_fs_util::read_to_string(path)?,
+        None => String::from_utf8(
+            BufReader::new(std::io::stdin()).bytes().collect::<Result<Vec<_>, _>>()?,
+        )?,
+    })
+}
+
+/// Load JWT secret from either a file or use the provided string directly.
+pub(crate) fn load_jwt_secret(jwt_secret: Option<&str>) -> Result<Option<String>> {
+    match jwt_secret {
+        Some(secret) => {
+            // Try to read as file first
+            match std::fs::read_to_string(secret) {
+                Ok(contents) => Ok(Some(contents.trim().to_string())),
+                // If file read fails, use the string directly
+                Err(_) => Ok(Some(secret.to_string())),
+            }
+        }
+        None => Ok(None),
+    }
+}
+
+/// Parses a gas limit value with optional suffix: K for thousand, M for million, G for billion.
+///
+/// Examples: "30000000", "30M", "1G", "2G"
+pub(crate) fn parse_gas_limit(s: &str) -> eyre::Result<u64> {
+    let s = s.trim();
+    if s.is_empty() {
+        return Err(eyre::eyre!("empty value"));
+    }
+
+    let (num_str, multiplier) = if let Some(prefix) = s.strip_suffix(['G', 'g']) {
+        (prefix, 1_000_000_000u64)
+    } else if let Some(prefix) = s.strip_suffix(['M', 'm']) {
+        (prefix, 1_000_000u64)
+    } else if let Some(prefix) = s.strip_suffix(['K', 'k']) {
+        (prefix, 1_000u64)
+    } else {
+        (s, 1u64)
+    };
+
+    let base: u64 = num_str.trim().parse()?;
+    base.checked_mul(multiplier).ok_or_else(|| eyre::eyre!("value overflow"))
+}
 use alloy_consensus::Header;
 use alloy_eips::eip4844::kzg_to_versioned_hash;
 use alloy_primitives::{Address, B256};
@@ -194,3 +244,50 @@ pub(crate) async fn get_payload_with_sidecar(
         _ => panic!("This tool does not support getPayload versions past v5"),
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_parse_gas_limit_plain_number() {
+        assert_eq!(parse_gas_limit("30000000").unwrap(), 30_000_000);
+        assert_eq!(parse_gas_limit("1").unwrap(), 1);
+        assert_eq!(parse_gas_limit("0").unwrap(), 0);
+    }
+
+    #[test]
+    fn test_parse_gas_limit_k_suffix() {
+        assert_eq!(parse_gas_limit("1K").unwrap(), 1_000);
+        assert_eq!(parse_gas_limit("30k").unwrap(), 30_000);
+        assert_eq!(parse_gas_limit("100K").unwrap(), 100_000);
+    }
+
+    #[test]
+    fn test_parse_gas_limit_m_suffix() {
+        assert_eq!(parse_gas_limit("1M").unwrap(), 1_000_000);
+        assert_eq!(parse_gas_limit("30m").unwrap(), 30_000_000);
+        assert_eq!(parse_gas_limit("100M").unwrap(), 100_000_000);
+    }
+
+    #[test]
+    fn test_parse_gas_limit_g_suffix() {
+        assert_eq!(parse_gas_limit("1G").unwrap(), 1_000_000_000);
+        assert_eq!(parse_gas_limit("2g").unwrap(), 2_000_000_000);
+        assert_eq!(parse_gas_limit("10G").unwrap(), 10_000_000_000);
+    }
+
+    #[test]
+    fn test_parse_gas_limit_with_whitespace() {
+        assert_eq!(parse_gas_limit(" 1G ").unwrap(), 1_000_000_000);
+        assert_eq!(parse_gas_limit("2 M").unwrap(), 2_000_000);
+    }
+
+    #[test]
+    fn test_parse_gas_limit_errors() {
+        assert!(parse_gas_limit("").is_err());
+        assert!(parse_gas_limit("abc").is_err());
+        assert!(parse_gas_limit("G").is_err());
+        assert!(parse_gas_limit("-1G").is_err());
+    }
+}

bin/reth-bench/src/bench/mod.rs

@@ -15,7 +15,9 @@ pub use generate_big_block::{
 mod new_payload_fcu;
 mod new_payload_only;
 mod output;
+mod persistence_waiter;
 mod replay_payloads;
+mod send_invalid_payload;
 mod send_payload;
 
 /// `reth bench` command
@@ -74,6 +76,18 @@ pub enum Subcommands {
     /// `reth-bench replay-payloads --payload-dir ./payloads --engine-rpc-url
     /// http://localhost:8551 --jwt-secret ~/.local/share/reth/mainnet/jwt.hex`
     ReplayPayloads(replay_payloads::Command),
+
+    /// Generate and send an invalid `engine_newPayload` request for testing.
+    ///
+    /// Takes a valid block and modifies fields to make it invalid, allowing you to test
+    /// Engine API rejection behavior. Block hash is recalculated after modifications
+    /// unless `--invalid-block-hash` or `--skip-hash-recalc` is used.
+    ///
+    /// Example:
+    ///
+    /// `cast block latest --full --json | reth-bench send-invalid-payload --rpc-url localhost:5000
+    /// --jwt-secret $(cat ~/.local/share/reth/mainnet/jwt.hex) --invalid-state-root`
+    SendInvalidPayload(Box<send_invalid_payload::Command>),
 }
 
 impl BenchmarkCommand {
@@ -89,6 +103,7 @@ impl BenchmarkCommand {
             Subcommands::SendPayload(command) => command.execute(ctx).await,
             Subcommands::GenerateBigBlock(command) => command.execute(ctx).await,
             Subcommands::ReplayPayloads(command) => command.execute(ctx).await,
+            Subcommands::SendInvalidPayload(command) => (*command).execute(ctx).await,
         }
     }
 

bin/reth-bench/src/bench/new_payload_fcu.rs

@@ -15,28 +15,23 @@ use crate::{
         output::{
             write_benchmark_results, CombinedResult, NewPayloadResult, TotalGasOutput, TotalGasRow,
         },
+        persistence_waiter::{
+            derive_ws_rpc_url, setup_persistence_subscription, PersistenceWaiter,
+            PERSISTENCE_CHECKPOINT_TIMEOUT,
+        },
     },
     valid_payload::{block_to_new_payload, call_forkchoice_updated, call_new_payload},
 };
-use alloy_eips::BlockNumHash;
-use alloy_network::Ethereum;
-use alloy_provider::{Provider, RootProvider};
-use alloy_pubsub::SubscriptionStream;
-use alloy_rpc_client::RpcClient;
+use alloy_provider::Provider;
 use alloy_rpc_types_engine::ForkchoiceState;
-use alloy_transport_ws::WsConnect;
 use clap::Parser;
 use eyre::{Context, OptionExt};
-use futures::StreamExt;
 use humantime::parse_duration;
 use reth_cli_runner::CliContext;
 use reth_engine_primitives::config::DEFAULT_PERSISTENCE_THRESHOLD;
 use reth_node_core::args::BenchmarkArgs;
 use std::time::{Duration, Instant};
 use tracing::{debug, info};
-use url::Url;
-
-const PERSISTENCE_CHECKPOINT_TIMEOUT: Duration = Duration::from_secs(60);
 
 /// `reth benchmark new-payload-fcu` command
 #[derive(Debug, Parser)]
@@ -105,7 +100,11 @@ impl Command {
         let mut waiter = match (self.wait_time, self.wait_for_persistence) {
             (Some(duration), _) => Some(PersistenceWaiter::with_duration(duration)),
             (None, true) => {
-                let sub = self.setup_persistence_subscription().await?;
+                let ws_url = derive_ws_rpc_url(
+                    self.benchmark.ws_rpc_url.as_deref(),
+                    &self.benchmark.engine_rpc_url,
+                )?;
+                let sub = setup_persistence_subscription(ws_url).await?;
                 Some(PersistenceWaiter::with_subscription(
                     sub,
                     self.persistence_threshold,
@@ -245,293 +244,22 @@ impl Command {
             results.into_iter().unzip();
 
         if let Some(ref path) = self.benchmark.output {
-            write_benchmark_results(path, &gas_output_results, combined_results)?;
+            write_benchmark_results(path, &gas_output_results, &combined_results)?;
         }
 
-        let gas_output = TotalGasOutput::new(gas_output_results)?;
+        let gas_output =
+            TotalGasOutput::with_combined_results(gas_output_results, &combined_results)?;
 
         info!(
-            total_duration=?gas_output.total_duration,
-            total_gas_used=?gas_output.total_gas_used,
-            blocks_processed=?gas_output.blocks_processed,
-            "Total Ggas/s: {:.4}",
-            gas_output.total_gigagas_per_second()
+            total_gas_used = gas_output.total_gas_used,
+            total_duration = ?gas_output.total_duration,
+            execution_duration = ?gas_output.execution_duration,
+            blocks_processed = gas_output.blocks_processed,
+            wall_clock_ggas_per_second = format_args!("{:.4}", gas_output.total_gigagas_per_second()),
+            execution_ggas_per_second = format_args!("{:.4}", gas_output.execution_gigagas_per_second()),
+            "Benchmark complete"
         );
 
         Ok(())
     }
-
-    /// Returns the websocket RPC URL used for the persistence subscription.
-    ///
-    /// Preference:
-    /// - If `--ws-rpc-url` is provided, use it directly.
-    /// - Otherwise, derive a WS RPC URL from `--engine-rpc-url`.
-    ///
-    /// The persistence subscription endpoint (`reth_subscribePersistedBlock`) is exposed on
-    /// the regular RPC server (WS port, usually 8546), not on the engine API port (usually 8551).
-    /// Since `BenchmarkArgs` only has the engine URL by default, we convert the scheme
-    /// (http→ws, https→wss) and force the port to 8546.
-    fn derive_ws_rpc_url(&self) -> eyre::Result<Url> {
-        if let Some(ref ws_url) = self.benchmark.ws_rpc_url {
-            let parsed: Url = ws_url
-                .parse()
-                .wrap_err_with(|| format!("Failed to parse WebSocket RPC URL: {ws_url}"))?;
-            info!(target: "reth-bench", ws_url = %parsed, "Using provided WebSocket RPC URL");
-            Ok(parsed)
-        } else {
-            let derived = engine_url_to_ws_url(&self.benchmark.engine_rpc_url)?;
-            debug!(
-                target: "reth-bench",
-                engine_url = %self.benchmark.engine_rpc_url,
-                %derived,
-                "Derived WebSocket RPC URL from engine RPC URL"
-            );
-            Ok(derived)
-        }
-    }
-
-    /// Establishes a websocket connection and subscribes to `reth_subscribePersistedBlock`.
-    async fn setup_persistence_subscription(&self) -> eyre::Result<PersistenceSubscription> {
-        let ws_url = self.derive_ws_rpc_url()?;
-
-        info!("Connecting to WebSocket at {} for persistence subscription", ws_url);
-
-        let ws_connect = WsConnect::new(ws_url.to_string());
-        let client = RpcClient::connect_pubsub(ws_connect)
-            .await
-            .wrap_err("Failed to connect to WebSocket RPC endpoint")?;
-        let provider: RootProvider<Ethereum> = RootProvider::new(client);
-
-        let subscription = provider
-            .subscribe_to::<BlockNumHash>("reth_subscribePersistedBlock")
-            .await
-            .wrap_err("Failed to subscribe to persistence notifications")?;
-
-        info!("Subscribed to persistence notifications");
-
-        Ok(PersistenceSubscription::new(provider, subscription.into_stream()))
-    }
-}
-
-/// Converts an engine API URL to the default RPC websocket URL.
-///
-/// Transformations:
-/// - `http`  → `ws`
-/// - `https` → `wss`
-/// - `ws` / `wss` keep their scheme
-/// - Port is always set to `8546`, reth's default RPC websocket port.
-///
-/// This is used when we only know the engine API URL (typically `:8551`) but
-/// need to connect to the node's WS RPC endpoint for persistence events.
-fn engine_url_to_ws_url(engine_url: &str) -> eyre::Result<Url> {
-    let url: Url = engine_url
-        .parse()
-        .wrap_err_with(|| format!("Failed to parse engine RPC URL: {engine_url}"))?;
-
-    let mut ws_url = url.clone();
-
-    match ws_url.scheme() {
-        "http" => ws_url
-            .set_scheme("ws")
-            .map_err(|_| eyre::eyre!("Failed to set WS scheme for URL: {url}"))?,
-        "https" => ws_url
-            .set_scheme("wss")
-            .map_err(|_| eyre::eyre!("Failed to set WSS scheme for URL: {url}"))?,
-        "ws" | "wss" => {}
-        scheme => {
-            return Err(eyre::eyre!(
-            "Unsupported URL scheme '{scheme}' for URL: {url}. Expected http, https, ws, or wss."
-        ))
-        }
-    }
-
-    ws_url.set_port(Some(8546)).map_err(|_| eyre::eyre!("Failed to set port for URL: {url}"))?;
-
-    Ok(ws_url)
-}
-
-/// Waits until the persistence subscription reports that `target` has been persisted.
-///
-/// Consumes subscription events until `last_persisted >= target`, or returns an error if:
-/// - the subscription stream ends unexpectedly, or
-/// - `timeout` elapses before `target` is observed.
-async fn wait_for_persistence(
-    stream: &mut SubscriptionStream<BlockNumHash>,
-    target: u64,
-    last_persisted: &mut u64,
-    timeout: Duration,
-) -> eyre::Result<()> {
-    tokio::time::timeout(timeout, async {
-        while *last_persisted < target {
-            match stream.next().await {
-                Some(persisted) => {
-                    *last_persisted = persisted.number;
-                    debug!(
-                        target: "reth-bench",
-                        persisted_block = ?last_persisted,
-                        "Received persistence notification"
-                    );
-                }
-                None => {
-                    return Err(eyre::eyre!("Persistence subscription closed unexpectedly"));
-                }
-            }
-        }
-        Ok(())
-    })
-    .await
-    .map_err(|_| {
-        eyre::eyre!(
-            "Persistence timeout: target block {} not persisted within {:?}. Last persisted: {}",
-            target,
-            timeout,
-            last_persisted
-        )
-    })?
-}
-
-/// Wrapper that keeps both the subscription stream and the underlying provider alive.
-/// The provider must be kept alive for the subscription to continue receiving events.
-struct PersistenceSubscription {
-    _provider: RootProvider<Ethereum>,
-    stream: SubscriptionStream<BlockNumHash>,
-}
-
-impl PersistenceSubscription {
-    const fn new(
-        provider: RootProvider<Ethereum>,
-        stream: SubscriptionStream<BlockNumHash>,
-    ) -> Self {
-        Self { _provider: provider, stream }
-    }
-
-    const fn stream_mut(&mut self) -> &mut SubscriptionStream<BlockNumHash> {
-        &mut self.stream
-    }
-}
-
-/// Encapsulates the block waiting logic.
-///
-/// Provides a simple `on_block()` interface that handles both:
-/// - Fixed duration waits (when `wait_time` is set)
-/// - Persistence-based waits (when `subscription` is set)
-///
-/// For persistence mode, waits after every `(threshold + 1)` blocks.
-struct PersistenceWaiter {
-    wait_time: Option<Duration>,
-    subscription: Option<PersistenceSubscription>,
-    blocks_sent: u64,
-    last_persisted: u64,
-    threshold: u64,
-    timeout: Duration,
-}
-
-impl PersistenceWaiter {
-    const fn with_duration(wait_time: Duration) -> Self {
-        Self {
-            wait_time: Some(wait_time),
-            subscription: None,
-            blocks_sent: 0,
-            last_persisted: 0,
-            threshold: 0,
-            timeout: Duration::ZERO,
-        }
-    }
-
-    const fn with_subscription(
-        subscription: PersistenceSubscription,
-        threshold: u64,
-        timeout: Duration,
-    ) -> Self {
-        Self {
-            wait_time: None,
-            subscription: Some(subscription),
-            blocks_sent: 0,
-            last_persisted: 0,
-            threshold,
-            timeout,
-        }
-    }
-
-    /// Called once per block. Waits based on the configured mode.
-    #[allow(clippy::manual_is_multiple_of)]
-    async fn on_block(&mut self, block_number: u64) -> eyre::Result<()> {
-        if let Some(wait_time) = self.wait_time {
-            tokio::time::sleep(wait_time).await;
-            return Ok(());
-        }
-
-        let Some(ref mut subscription) = self.subscription else {
-            return Ok(());
-        };
-
-        self.blocks_sent += 1;
-
-        if self.blocks_sent % (self.threshold + 1) == 0 {
-            debug!(
-                target: "reth-bench",
-                target_block = ?block_number,
-                last_persisted = self.last_persisted,
-                blocks_sent = self.blocks_sent,
-                "Waiting for persistence"
-            );
-
-            wait_for_persistence(
-                subscription.stream_mut(),
-                block_number,
-                &mut self.last_persisted,
-                self.timeout,
-            )
-            .await?;
-
-            debug!(
-                target: "reth-bench",
-                persisted = self.last_persisted,
-                "Persistence caught up"
-            );
-        }
-
-        Ok(())
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn test_engine_url_to_ws_url() {
-        // http -> ws, always uses port 8546
-        let result = engine_url_to_ws_url("http://localhost:8551").unwrap();
-        assert_eq!(result.as_str(), "ws://localhost:8546/");
-
-        // https -> wss
-        let result = engine_url_to_ws_url("https://localhost:8551").unwrap();
-        assert_eq!(result.as_str(), "wss://localhost:8546/");
-
-        // Custom engine port still maps to 8546
-        let result = engine_url_to_ws_url("http://localhost:9551").unwrap();
-        assert_eq!(result.port(), Some(8546));
-
-        // Already ws passthrough
-        let result = engine_url_to_ws_url("ws://localhost:8546").unwrap();
-        assert_eq!(result.scheme(), "ws");
-
-        // Invalid inputs
-        assert!(engine_url_to_ws_url("ftp://localhost:8551").is_err());
-        assert!(engine_url_to_ws_url("not a valid url").is_err());
-    }
-
-    #[tokio::test]
-    async fn test_waiter_with_duration() {
-        let mut waiter = PersistenceWaiter::with_duration(Duration::from_millis(1));
-
-        let start = Instant::now();
-        waiter.on_block(1).await.unwrap();
-        waiter.on_block(2).await.unwrap();
-        waiter.on_block(3).await.unwrap();
-
-        // Should have waited ~3ms total
-        assert!(start.elapsed() >= Duration::from_millis(3));
-    }
 }

bin/reth-bench/src/bench/output.rs

@@ -6,7 +6,7 @@ use csv::Writer;
 use eyre::OptionExt;
 use reth_primitives_traits::constants::GIGAGAS;
 use serde::{ser::SerializeStruct, Deserialize, Serialize};
-use std::{path::Path, time::Duration};
+use std::{fs, path::Path, time::Duration};
 use tracing::info;
 
 /// This is the suffix for gas output csv files.
@@ -158,29 +158,58 @@ pub(crate) struct TotalGasRow {
 pub(crate) struct TotalGasOutput {
     /// The total gas used in the benchmark.
     pub(crate) total_gas_used: u64,
-    /// The total duration of the benchmark.
+    /// The total wall-clock duration of the benchmark (includes wait times).
     pub(crate) total_duration: Duration,
-    /// The total gas used per second.
-    pub(crate) total_gas_per_second: f64,
+    /// The total execution-only duration (excludes wait times).
+    pub(crate) execution_duration: Duration,
     /// The number of blocks processed.
     pub(crate) blocks_processed: u64,
 }
 
 impl TotalGasOutput {
-    /// Create a new [`TotalGasOutput`] from a list of [`TotalGasRow`].
+    /// Create a new [`TotalGasOutput`] from gas rows only.
+    ///
+    /// Use this when execution-only timing is not available (e.g., `new_payload_only`).
+    /// `execution_duration` will equal `total_duration`.
     pub(crate) fn new(rows: Vec<TotalGasRow>) -> eyre::Result<Self> {
-        // the duration is obtained from the last row
         let total_duration = rows.last().map(|row| row.time).ok_or_eyre("empty results")?;
         let blocks_processed = rows.len() as u64;
         let total_gas_used: u64 = rows.into_iter().map(|row| row.gas_used).sum();
-        let total_gas_per_second = total_gas_used as f64 / total_duration.as_secs_f64();
 
-        Ok(Self { total_gas_used, total_duration, total_gas_per_second, blocks_processed })
+        Ok(Self {
+            total_gas_used,
+            total_duration,
+            execution_duration: total_duration,
+            blocks_processed,
+        })
     }
 
-    /// Return the total gigagas per second.
+    /// Create a new [`TotalGasOutput`] from gas rows and combined results.
+    ///
+    /// - `rows`: Used for total gas and wall-clock duration
+    /// - `combined_results`: Used for execution-only duration (sum of `total_latency`)
+    pub(crate) fn with_combined_results(
+        rows: Vec<TotalGasRow>,
+        combined_results: &[CombinedResult],
+    ) -> eyre::Result<Self> {
+        let total_duration = rows.last().map(|row| row.time).ok_or_eyre("empty results")?;
+        let blocks_processed = rows.len() as u64;
+        let total_gas_used: u64 = rows.into_iter().map(|row| row.gas_used).sum();
+
+        // Sum execution-only time from combined results
+        let execution_duration: Duration = combined_results.iter().map(|r| r.total_latency).sum();
+
+        Ok(Self { total_gas_used, total_duration, execution_duration, blocks_processed })
+    }
+
+    /// Return the total gigagas per second based on wall-clock time.
     pub(crate) fn total_gigagas_per_second(&self) -> f64 {
-        self.total_gas_per_second / GIGAGAS as f64
+        self.total_gas_used as f64 / self.total_duration.as_secs_f64() / GIGAGAS as f64
+    }
+
+    /// Return the execution-only gigagas per second (excludes wait times).
+    pub(crate) fn execution_gigagas_per_second(&self) -> f64 {
+        self.total_gas_used as f64 / self.execution_duration.as_secs_f64() / GIGAGAS as f64
     }
 }
 
@@ -192,8 +221,10 @@ impl TotalGasOutput {
 pub(crate) fn write_benchmark_results(
     output_dir: &Path,
     gas_results: &[TotalGasRow],
-    combined_results: Vec<CombinedResult>,
+    combined_results: &[CombinedResult],
 ) -> eyre::Result<()> {
+    fs::create_dir_all(output_dir)?;
+
     let output_path = output_dir.join(COMBINED_OUTPUT_SUFFIX);
     info!("Writing engine api call latency output to file: {:?}", output_path);
     let mut writer = Writer::from_path(&output_path)?;

bin/reth-bench/src/bench/persistence_waiter.rs

@@ -0,0 +1,304 @@
+//! Persistence waiting utilities for benchmarks.
+//!
+//! Provides waiting behavior to control benchmark pacing:
+//! - **Fixed duration waits**: Sleep for a fixed time between blocks
+//! - **Persistence-based waits**: Wait for blocks to be persisted using
+//!   `reth_subscribePersistedBlock` subscription
+
+use alloy_eips::BlockNumHash;
+use alloy_network::Ethereum;
+use alloy_provider::{Provider, RootProvider};
+use alloy_pubsub::SubscriptionStream;
+use alloy_rpc_client::RpcClient;
+use alloy_transport_ws::WsConnect;
+use eyre::Context;
+use futures::StreamExt;
+use std::time::Duration;
+use tracing::{debug, info};
+
+/// Default `WebSocket` RPC port for reth.
+const DEFAULT_WS_RPC_PORT: u16 = 8546;
+use url::Url;
+
+/// Default timeout for waiting on persistence.
+pub(crate) const PERSISTENCE_CHECKPOINT_TIMEOUT: Duration = Duration::from_secs(60);
+
+/// Returns the websocket RPC URL used for the persistence subscription.
+///
+/// Preference:
+/// - If `ws_rpc_url` is provided, use it directly.
+/// - Otherwise, derive a WS RPC URL from `engine_rpc_url`.
+///
+/// The persistence subscription endpoint (`reth_subscribePersistedBlock`) is exposed on
+/// the regular RPC server (WS port, usually 8546), not on the engine API port (usually 8551).
+/// Since we may only have the engine URL by default, we convert the scheme
+/// (http→ws, https→wss) and force the port to 8546.
+pub(crate) fn derive_ws_rpc_url(
+    ws_rpc_url: Option<&str>,
+    engine_rpc_url: &str,
+) -> eyre::Result<Url> {
+    if let Some(ws_url) = ws_rpc_url {
+        let parsed: Url = ws_url
+            .parse()
+            .wrap_err_with(|| format!("Failed to parse WebSocket RPC URL: {ws_url}"))?;
+        info!(target: "reth-bench", ws_url = %parsed, "Using provided WebSocket RPC URL");
+        Ok(parsed)
+    } else {
+        let derived = engine_url_to_ws_url(engine_rpc_url)?;
+        debug!(
+            target: "reth-bench",
+            engine_url = %engine_rpc_url,
+            %derived,
+            "Derived WebSocket RPC URL from engine RPC URL"
+        );
+        Ok(derived)
+    }
+}
+
+/// Converts an engine API URL to the default RPC websocket URL.
+///
+/// Transformations:
+/// - `http`  → `ws`
+/// - `https` → `wss`
+/// - `ws` / `wss` keep their scheme
+/// - Port is always set to `8546`, reth's default RPC websocket port.
+///
+/// This is used when we only know the engine API URL (typically `:8551`) but
+/// need to connect to the node's WS RPC endpoint for persistence events.
+fn engine_url_to_ws_url(engine_url: &str) -> eyre::Result<Url> {
+    let url: Url = engine_url
+        .parse()
+        .wrap_err_with(|| format!("Failed to parse engine RPC URL: {engine_url}"))?;
+
+    let mut ws_url = url.clone();
+
+    match ws_url.scheme() {
+        "http" => ws_url
+            .set_scheme("ws")
+            .map_err(|_| eyre::eyre!("Failed to set WS scheme for URL: {url}"))?,
+        "https" => ws_url
+            .set_scheme("wss")
+            .map_err(|_| eyre::eyre!("Failed to set WSS scheme for URL: {url}"))?,
+        "ws" | "wss" => {}
+        scheme => {
+            return Err(eyre::eyre!(
+            "Unsupported URL scheme '{scheme}' for URL: {url}. Expected http, https, ws, or wss."
+        ))
+        }
+    }
+
+    ws_url
+        .set_port(Some(DEFAULT_WS_RPC_PORT))
+        .map_err(|_| eyre::eyre!("Failed to set port for URL: {url}"))?;
+
+    Ok(ws_url)
+}
+
+/// Waits until the persistence subscription reports that `target` has been persisted.
+///
+/// Consumes subscription events until `last_persisted >= target`, or returns an error if:
+/// - the subscription stream ends unexpectedly, or
+/// - `timeout` elapses before `target` is observed.
+async fn wait_for_persistence(
+    stream: &mut SubscriptionStream<BlockNumHash>,
+    target: u64,
+    last_persisted: &mut u64,
+    timeout: Duration,
+) -> eyre::Result<()> {
+    tokio::time::timeout(timeout, async {
+        while *last_persisted < target {
+            match stream.next().await {
+                Some(persisted) => {
+                    *last_persisted = persisted.number;
+                    debug!(
+                        target: "reth-bench",
+                        persisted_block = ?last_persisted,
+                        "Received persistence notification"
+                    );
+                }
+                None => {
+                    return Err(eyre::eyre!("Persistence subscription closed unexpectedly"));
+                }
+            }
+        }
+        Ok(())
+    })
+    .await
+    .map_err(|_| {
+        eyre::eyre!(
+            "Persistence timeout: target block {} not persisted within {:?}. Last persisted: {}",
+            target,
+            timeout,
+            last_persisted
+        )
+    })?
+}
+
+/// Wrapper that keeps both the subscription stream and the underlying provider alive.
+/// The provider must be kept alive for the subscription to continue receiving events.
+pub(crate) struct PersistenceSubscription {
+    _provider: RootProvider<Ethereum>,
+    stream: SubscriptionStream<BlockNumHash>,
+}
+
+impl PersistenceSubscription {
+    const fn new(
+        provider: RootProvider<Ethereum>,
+        stream: SubscriptionStream<BlockNumHash>,
+    ) -> Self {
+        Self { _provider: provider, stream }
+    }
+
+    const fn stream_mut(&mut self) -> &mut SubscriptionStream<BlockNumHash> {
+        &mut self.stream
+    }
+}
+
+/// Establishes a websocket connection and subscribes to `reth_subscribePersistedBlock`.
+pub(crate) async fn setup_persistence_subscription(
+    ws_url: Url,
+) -> eyre::Result<PersistenceSubscription> {
+    info!("Connecting to WebSocket at {} for persistence subscription", ws_url);
+
+    let ws_connect = WsConnect::new(ws_url.to_string());
+    let client = RpcClient::connect_pubsub(ws_connect)
+        .await
+        .wrap_err("Failed to connect to WebSocket RPC endpoint")?;
+    let provider: RootProvider<Ethereum> = RootProvider::new(client);
+
+    let subscription = provider
+        .subscribe_to::<BlockNumHash>("reth_subscribePersistedBlock")
+        .await
+        .wrap_err("Failed to subscribe to persistence notifications")?;
+
+    info!("Subscribed to persistence notifications");
+
+    Ok(PersistenceSubscription::new(provider, subscription.into_stream()))
+}
+
+/// Encapsulates the block waiting logic.
+///
+/// Provides a simple `on_block()` interface that handles both:
+/// - Fixed duration waits (when `wait_time` is set)
+/// - Persistence-based waits (when `subscription` is set)
+///
+/// For persistence mode, waits after every `(threshold + 1)` blocks.
+pub(crate) struct PersistenceWaiter {
+    wait_time: Option<Duration>,
+    subscription: Option<PersistenceSubscription>,
+    blocks_sent: u64,
+    last_persisted: u64,
+    threshold: u64,
+    timeout: Duration,
+}
+
+impl PersistenceWaiter {
+    pub(crate) const fn with_duration(wait_time: Duration) -> Self {
+        Self {
+            wait_time: Some(wait_time),
+            subscription: None,
+            blocks_sent: 0,
+            last_persisted: 0,
+            threshold: 0,
+            timeout: Duration::ZERO,
+        }
+    }
+
+    pub(crate) const fn with_subscription(
+        subscription: PersistenceSubscription,
+        threshold: u64,
+        timeout: Duration,
+    ) -> Self {
+        Self {
+            wait_time: None,
+            subscription: Some(subscription),
+            blocks_sent: 0,
+            last_persisted: 0,
+            threshold,
+            timeout,
+        }
+    }
+
+    /// Called once per block. Waits based on the configured mode.
+    #[allow(clippy::manual_is_multiple_of)]
+    pub(crate) async fn on_block(&mut self, block_number: u64) -> eyre::Result<()> {
+        if let Some(wait_time) = self.wait_time {
+            tokio::time::sleep(wait_time).await;
+            return Ok(());
+        }
+
+        let Some(ref mut subscription) = self.subscription else {
+            return Ok(());
+        };
+
+        self.blocks_sent += 1;
+
+        if self.blocks_sent % (self.threshold + 1) == 0 {
+            debug!(
+                target: "reth-bench",
+                target_block = ?block_number,
+                last_persisted = self.last_persisted,
+                blocks_sent = self.blocks_sent,
+                "Waiting for persistence"
+            );
+
+            wait_for_persistence(
+                subscription.stream_mut(),
+                block_number,
+                &mut self.last_persisted,
+                self.timeout,
+            )
+            .await?;
+
+            debug!(
+                target: "reth-bench",
+                persisted = self.last_persisted,
+                "Persistence caught up"
+            );
+        }
+
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::time::Instant;
+
+    #[test]
+    fn test_engine_url_to_ws_url() {
+        // http -> ws, always uses port 8546
+        let result = engine_url_to_ws_url("http://localhost:8551").unwrap();
+        assert_eq!(result.as_str(), "ws://localhost:8546/");
+
+        // https -> wss
+        let result = engine_url_to_ws_url("https://localhost:8551").unwrap();
+        assert_eq!(result.as_str(), "wss://localhost:8546/");
+
+        // Custom engine port still maps to 8546
+        let result = engine_url_to_ws_url("http://localhost:9551").unwrap();
+        assert_eq!(result.port(), Some(8546));
+
+        // Already ws passthrough
+        let result = engine_url_to_ws_url("ws://localhost:8546").unwrap();
+        assert_eq!(result.scheme(), "ws");
+
+        // Invalid inputs
+        assert!(engine_url_to_ws_url("ftp://localhost:8551").is_err());
+        assert!(engine_url_to_ws_url("not a valid url").is_err());
+    }
+
+    #[tokio::test]
+    async fn test_waiter_with_duration() {
+        let mut waiter = PersistenceWaiter::with_duration(Duration::from_millis(1));
+
+        let start = Instant::now();
+        waiter.on_block(1).await.unwrap();
+        waiter.on_block(2).await.unwrap();
+        waiter.on_block(3).await.unwrap();
+
+        // Should have waited ~3ms total
+        assert!(start.elapsed() >= Duration::from_millis(3));
+    }
+}

bin/reth-bench/src/bench/replay_payloads.rs

@@ -2,10 +2,27 @@
 //!
 //! This command reads `ExecutionPayloadEnvelopeV4` files from a directory and replays them
 //! in sequence using `newPayload` followed by `forkchoiceUpdated`.
+//!
+//! Supports configurable waiting behavior:
+//! - **`--wait-time`**: Fixed sleep interval between blocks.
+//! - **`--wait-for-persistence`**: Waits for every Nth block to be persisted using the
+//!   `reth_subscribePersistedBlock` subscription, where N matches the engine's persistence
+//!   threshold. This ensures the benchmark doesn't outpace persistence.
+//!
+//! Both options can be used together or independently.
 
 use crate::{
     authenticated_transport::AuthenticatedTransportConnect,
-    bench::output::GasRampPayloadFile,
+    bench::{
+        output::{
+            write_benchmark_results, CombinedResult, GasRampPayloadFile, NewPayloadResult,
+            TotalGasOutput, TotalGasRow,
+        },
+        persistence_waiter::{
+            derive_ws_rpc_url, setup_persistence_subscription, PersistenceWaiter,
+            PERSISTENCE_CHECKPOINT_TIMEOUT,
+        },
+    },
     valid_payload::{call_forkchoice_updated, call_new_payload},
 };
 use alloy_primitives::B256;
@@ -14,11 +31,16 @@ use alloy_rpc_client::ClientBuilder;
 use alloy_rpc_types_engine::{ExecutionPayloadEnvelopeV4, ForkchoiceState, JwtSecret};
 use clap::Parser;
 use eyre::Context;
-use reqwest::Url;
+use humantime::parse_duration;
 use reth_cli_runner::CliContext;
+use reth_engine_primitives::config::DEFAULT_PERSISTENCE_THRESHOLD;
 use reth_node_api::EngineApiMessageVersion;
-use std::path::PathBuf;
+use std::{
+    path::PathBuf,
+    time::{Duration, Instant},
+};
 use tracing::{debug, info};
+use url::Url;
 
 /// `reth bench replay-payloads` command
 ///
@@ -51,6 +73,42 @@ pub struct Command {
     /// These are replayed before the main payloads to warm up the gas limit.
     #[arg(long, value_name = "GAS_RAMP_DIR")]
     gas_ramp_dir: Option<PathBuf>,
+
+    /// Optional output directory for benchmark results (CSV files).
+    #[arg(long, value_name = "OUTPUT")]
+    output: Option<PathBuf>,
+
+    /// How long to wait after a forkchoice update before sending the next payload.
+    #[arg(long, value_name = "WAIT_TIME", value_parser = parse_duration, verbatim_doc_comment)]
+    wait_time: Option<Duration>,
+
+    /// Wait for blocks to be persisted before sending the next batch.
+    ///
+    /// When enabled, waits for every Nth block to be persisted using the
+    /// `reth_subscribePersistedBlock` subscription. This ensures the benchmark
+    /// doesn't outpace persistence.
+    ///
+    /// The subscription uses the regular RPC websocket endpoint (no JWT required).
+    #[arg(long, default_value = "false", verbatim_doc_comment)]
+    wait_for_persistence: bool,
+
+    /// Engine persistence threshold used for deciding when to wait for persistence.
+    ///
+    /// The benchmark waits after every `(threshold + 1)` blocks. By default this
+    /// matches the engine's `DEFAULT_PERSISTENCE_THRESHOLD` (2), so waits occur
+    /// at blocks 3, 6, 9, etc.
+    #[arg(
+        long = "persistence-threshold",
+        value_name = "PERSISTENCE_THRESHOLD",
+        default_value_t = DEFAULT_PERSISTENCE_THRESHOLD,
+        verbatim_doc_comment
+    )]
+    persistence_threshold: u64,
+
+    /// Optional `WebSocket` RPC URL for persistence subscription.
+    /// If not provided, derives from engine RPC URL by changing scheme to ws and port to 8546.
+    #[arg(long, value_name = "WS_RPC_URL", verbatim_doc_comment)]
+    ws_rpc_url: Option<String>,
 }
 
 /// A loaded payload ready for execution.
@@ -78,6 +136,33 @@ impl Command {
     pub async fn execute(self, _ctx: CliContext) -> eyre::Result<()> {
         info!(payload_dir = %self.payload_dir.display(), "Replaying payloads");
 
+        // Log mode configuration
+        if let Some(duration) = self.wait_time {
+            info!("Using wait-time mode with {}ms delay between blocks", duration.as_millis());
+        }
+        if self.wait_for_persistence {
+            info!(
+                "Persistence waiting enabled (waits after every {} blocks to match engine gap > {} behavior)",
+                self.persistence_threshold + 1,
+                self.persistence_threshold
+            );
+        }
+
+        // Set up waiter based on configured options (duration takes precedence)
+        let mut waiter = match (self.wait_time, self.wait_for_persistence) {
+            (Some(duration), _) => Some(PersistenceWaiter::with_duration(duration)),
+            (None, true) => {
+                let ws_url = derive_ws_rpc_url(self.ws_rpc_url.as_deref(), &self.engine_rpc_url)?;
+                let sub = setup_persistence_subscription(ws_url).await?;
+                Some(PersistenceWaiter::with_subscription(
+                    sub,
+                    self.persistence_threshold,
+                    PERSISTENCE_CHECKPOINT_TIMEOUT,
+                ))
+            }
+            (None, false) => None,
+        };
+
         // Set up authenticated engine provider
         let jwt =
             std::fs::read_to_string(&self.jwt_secret).wrap_err("Failed to read JWT secret file")?;
@@ -144,6 +229,11 @@ impl Command {
             call_forkchoice_updated(&auth_provider, payload.version, fcu_state, None).await?;
 
             info!(gas_ramp_payload = i + 1, "Gas ramp payload executed successfully");
+
+            if let Some(w) = &mut waiter {
+                w.on_block(payload.block_number).await?;
+            }
+
             parent_hash = payload.file.block_hash;
         }
 
@@ -151,22 +241,112 @@ impl Command {
             info!(count = gas_ramp_payloads.len(), "All gas ramp payloads replayed");
         }
 
+        let mut results = Vec::new();
+        let total_benchmark_duration = Instant::now();
+
         for (i, payload) in payloads.iter().enumerate() {
-            info!(
+            let envelope = &payload.envelope;
+            let block_hash = payload.block_hash;
+            let execution_payload = &envelope.envelope_inner.execution_payload;
+            let inner_payload = &execution_payload.payload_inner.payload_inner;
+
+            let gas_used = inner_payload.gas_used;
+            let gas_limit = inner_payload.gas_limit;
+            let block_number = inner_payload.block_number;
+            let transaction_count =
+                execution_payload.payload_inner.payload_inner.transactions.len() as u64;
+
+            debug!(
                 payload = i + 1,
                 total = payloads.len(),
                 index = payload.index,
-                block_hash = %payload.block_hash,
+                block_hash = %block_hash,
                 "Executing payload (newPayload + FCU)"
             );
 
-            self.execute_payload_v4(&auth_provider, &payload.envelope, parent_hash).await?;
+            let start = Instant::now();
 
-            info!(payload = i + 1, "Payload executed successfully");
-            parent_hash = payload.block_hash;
+            debug!(
+                method = "engine_newPayloadV4",
+                block_hash = %block_hash,
+                "Sending newPayload"
+            );
+
+            let status = auth_provider
+                .new_payload_v4(
+                    execution_payload.clone(),
+                    vec![],
+                    B256::ZERO,
+                    envelope.execution_requests.to_vec(),
+                )
+                .await?;
+
+            let new_payload_result = NewPayloadResult { gas_used, latency: start.elapsed() };
+
+            if !status.is_valid() {
+                return Err(eyre::eyre!("Payload rejected: {:?}", status));
+            }
+
+            let fcu_state = ForkchoiceState {
+                head_block_hash: block_hash,
+                safe_block_hash: parent_hash,
+                finalized_block_hash: parent_hash,
+            };
+
+            debug!(method = "engine_forkchoiceUpdatedV3", ?fcu_state, "Sending forkchoiceUpdated");
+
+            let fcu_result = auth_provider.fork_choice_updated_v3(fcu_state, None).await?;
+
+            let total_latency = start.elapsed();
+            let fcu_latency = total_latency - new_payload_result.latency;
+
+            let combined_result = CombinedResult {
+                block_number,
+                gas_limit,
+                transaction_count,
+                new_payload_result,
+                fcu_latency,
+                total_latency,
+            };
+
+            let current_duration = total_benchmark_duration.elapsed();
+            info!(%combined_result);
+
+            if let Some(w) = &mut waiter {
+                w.on_block(block_number).await?;
+            }
+
+            let gas_row =
+                TotalGasRow { block_number, transaction_count, gas_used, time: current_duration };
+            results.push((gas_row, combined_result));
+
+            debug!(?status, ?fcu_result, "Payload executed successfully");
+            parent_hash = block_hash;
         }
 
-        info!(count = payloads.len(), "All payloads replayed successfully");
+        // Drop waiter - we don't need to wait for final blocks to persist
+        // since the benchmark goal is measuring Ggas/s of newPayload/FCU, not persistence.
+        drop(waiter);
+
+        let (gas_output_results, combined_results): (Vec<TotalGasRow>, Vec<CombinedResult>) =
+            results.into_iter().unzip();
+
+        if let Some(ref path) = self.output {
+            write_benchmark_results(path, &gas_output_results, &combined_results)?;
+        }
+
+        let gas_output =
+            TotalGasOutput::with_combined_results(gas_output_results, &combined_results)?;
+        info!(
+            total_gas_used = gas_output.total_gas_used,
+            total_duration = ?gas_output.total_duration,
+            execution_duration = ?gas_output.execution_duration,
+            blocks_processed = gas_output.blocks_processed,
+            wall_clock_ggas_per_second = format_args!("{:.4}", gas_output.total_gigagas_per_second()),
+            execution_ggas_per_second = format_args!("{:.4}", gas_output.execution_gigagas_per_second()),
+            "Benchmark complete"
+        );
+
         Ok(())
     }
 
@@ -180,7 +360,7 @@ impl Command {
             .filter_map(|e| e.ok())
             .filter(|e| {
                 e.path().extension().and_then(|s| s.to_str()) == Some("json") &&
-                    e.file_name().to_string_lossy().starts_with("payload_")
+                    e.file_name().to_string_lossy().starts_with("payload_block_")
             })
             .collect();
 
@@ -191,7 +371,7 @@ impl Command {
                 let name = e.file_name();
                 let name_str = name.to_string_lossy();
                 // Extract index from "payload_NNN.json"
-                let index_str = name_str.strip_prefix("payload_")?.strip_suffix(".json")?;
+                let index_str = name_str.strip_prefix("payload_block_")?.strip_suffix(".json")?;
                 let index: u64 = index_str.parse().ok()?;
                 Some((index, e.path()))
             })
@@ -284,49 +464,4 @@ impl Command {
 
         Ok(payloads)
     }
-
-    async fn execute_payload_v4(
-        &self,
-        provider: &RootProvider<AnyNetwork>,
-        envelope: &ExecutionPayloadEnvelopeV4,
-        parent_hash: B256,
-    ) -> eyre::Result<()> {
-        let block_hash =
-            envelope.envelope_inner.execution_payload.payload_inner.payload_inner.block_hash;
-
-        debug!(
-            method = "engine_newPayloadV4",
-            block_hash = %block_hash,
-            "Sending newPayload"
-        );
-
-        let status = provider
-            .new_payload_v4(
-                envelope.envelope_inner.execution_payload.clone(),
-                vec![],
-                B256::ZERO,
-                envelope.execution_requests.to_vec(),
-            )
-            .await?;
-
-        info!(?status, "newPayloadV4 response");
-
-        if !status.is_valid() {
-            return Err(eyre::eyre!("Payload rejected: {:?}", status));
-        }
-
-        let fcu_state = ForkchoiceState {
-            head_block_hash: block_hash,
-            safe_block_hash: parent_hash,
-            finalized_block_hash: parent_hash,
-        };
-
-        debug!(method = "engine_forkchoiceUpdatedV3", ?fcu_state, "Sending forkchoiceUpdated");
-
-        let fcu_result = provider.fork_choice_updated_v3(fcu_state, None).await?;
-
-        info!(?fcu_result, "forkchoiceUpdatedV3 response");
-
-        Ok(())
-    }
 }

bin/reth-bench/src/bench/send_invalid_payload/invalidation.rs

@@ -0,0 +1,219 @@
+use alloy_eips::eip4895::Withdrawal;
+use alloy_primitives::{Address, Bloom, Bytes, B256, U256};
+use alloy_rpc_types_engine::{ExecutionPayloadV1, ExecutionPayloadV2, ExecutionPayloadV3};
+
+/// Configuration for invalidating payload fields
+#[derive(Debug, Default)]
+pub(super) struct InvalidationConfig {
+    // Explicit value overrides (Option<T>)
+    pub(super) parent_hash: Option<B256>,
+    pub(super) fee_recipient: Option<Address>,
+    pub(super) state_root: Option<B256>,
+    pub(super) receipts_root: Option<B256>,
+    pub(super) logs_bloom: Option<Bloom>,
+    pub(super) prev_randao: Option<B256>,
+    pub(super) block_number: Option<u64>,
+    pub(super) gas_limit: Option<u64>,
+    pub(super) gas_used: Option<u64>,
+    pub(super) timestamp: Option<u64>,
+    pub(super) extra_data: Option<Bytes>,
+    pub(super) base_fee_per_gas: Option<u64>,
+    pub(super) block_hash: Option<B256>,
+    pub(super) blob_gas_used: Option<u64>,
+    pub(super) excess_blob_gas: Option<u64>,
+
+    // Auto-invalidation flags
+    pub(super) invalidate_parent_hash: bool,
+    pub(super) invalidate_state_root: bool,
+    pub(super) invalidate_receipts_root: bool,
+    pub(super) invalidate_gas_used: bool,
+    pub(super) invalidate_block_number: bool,
+    pub(super) invalidate_timestamp: bool,
+    pub(super) invalidate_base_fee: bool,
+    pub(super) invalidate_transactions: bool,
+    pub(super) invalidate_block_hash: bool,
+    pub(super) invalidate_withdrawals: bool,
+    pub(super) invalidate_blob_gas_used: bool,
+    pub(super) invalidate_excess_blob_gas: bool,
+}
+
+impl InvalidationConfig {
+    /// Returns true if `block_hash` is being explicitly set or auto-invalidated.
+    /// When true, the caller should skip recalculating the block hash since it will be overwritten.
+    pub(super) const fn should_skip_hash_recalc(&self) -> bool {
+        self.block_hash.is_some() || self.invalidate_block_hash
+    }
+
+    /// Applies invalidations to a V1 payload, returns list of what was changed.
+    pub(super) fn apply_to_payload_v1(&self, payload: &mut ExecutionPayloadV1) -> Vec<String> {
+        let mut changes = Vec::new();
+
+        // Explicit value overrides
+        if let Some(parent_hash) = self.parent_hash {
+            payload.parent_hash = parent_hash;
+            changes.push(format!("parent_hash = {parent_hash}"));
+        }
+
+        if let Some(fee_recipient) = self.fee_recipient {
+            payload.fee_recipient = fee_recipient;
+            changes.push(format!("fee_recipient = {fee_recipient}"));
+        }
+
+        if let Some(state_root) = self.state_root {
+            payload.state_root = state_root;
+            changes.push(format!("state_root = {state_root}"));
+        }
+
+        if let Some(receipts_root) = self.receipts_root {
+            payload.receipts_root = receipts_root;
+            changes.push(format!("receipts_root = {receipts_root}"));
+        }
+
+        if let Some(logs_bloom) = self.logs_bloom {
+            payload.logs_bloom = logs_bloom;
+            changes.push("logs_bloom = <custom>".to_string());
+        }
+
+        if let Some(prev_randao) = self.prev_randao {
+            payload.prev_randao = prev_randao;
+            changes.push(format!("prev_randao = {prev_randao}"));
+        }
+
+        if let Some(block_number) = self.block_number {
+            payload.block_number = block_number;
+            changes.push(format!("block_number = {block_number}"));
+        }
+
+        if let Some(gas_limit) = self.gas_limit {
+            payload.gas_limit = gas_limit;
+            changes.push(format!("gas_limit = {gas_limit}"));
+        }
+
+        if let Some(gas_used) = self.gas_used {
+            payload.gas_used = gas_used;
+            changes.push(format!("gas_used = {gas_used}"));
+        }
+
+        if let Some(timestamp) = self.timestamp {
+            payload.timestamp = timestamp;
+            changes.push(format!("timestamp = {timestamp}"));
+        }
+
+        if let Some(ref extra_data) = self.extra_data {
+            payload.extra_data = extra_data.clone();
+            changes.push(format!("extra_data = {} bytes", extra_data.len()));
+        }
+
+        if let Some(base_fee_per_gas) = self.base_fee_per_gas {
+            payload.base_fee_per_gas = U256::from_limbs([base_fee_per_gas, 0, 0, 0]);
+            changes.push(format!("base_fee_per_gas = {base_fee_per_gas}"));
+        }
+
+        if let Some(block_hash) = self.block_hash {
+            payload.block_hash = block_hash;
+            changes.push(format!("block_hash = {block_hash}"));
+        }
+
+        // Auto-invalidation flags
+        if self.invalidate_parent_hash {
+            let random_hash = B256::random();
+            payload.parent_hash = random_hash;
+            changes.push(format!("parent_hash = {random_hash} (auto-invalidated: random)"));
+        }
+
+        if self.invalidate_state_root {
+            payload.state_root = B256::ZERO;
+            changes.push("state_root = ZERO (auto-invalidated: empty trie root)".to_string());
+        }
+
+        if self.invalidate_receipts_root {
+            payload.receipts_root = B256::ZERO;
+            changes.push("receipts_root = ZERO (auto-invalidated)".to_string());
+        }
+
+        if self.invalidate_gas_used {
+            let invalid_gas = payload.gas_limit + 1;
+            payload.gas_used = invalid_gas;
+            changes.push(format!("gas_used = {invalid_gas} (auto-invalidated: exceeds gas_limit)"));
+        }
+
+        if self.invalidate_block_number {
+            let invalid_number = payload.block_number + 999;
+            payload.block_number = invalid_number;
+            changes.push(format!("block_number = {invalid_number} (auto-invalidated: huge gap)"));
+        }
+
+        if self.invalidate_timestamp {
+            payload.timestamp = 0;
+            changes.push("timestamp = 0 (auto-invalidated: impossibly old)".to_string());
+        }
+
+        if self.invalidate_base_fee {
+            payload.base_fee_per_gas = U256::ZERO;
+            changes
+                .push("base_fee_per_gas = 0 (auto-invalidated: invalid post-London)".to_string());
+        }
+
+        if self.invalidate_transactions {
+            let invalid_tx = Bytes::from_static(&[0xff, 0xff, 0xff]);
+            payload.transactions.insert(0, invalid_tx);
+            changes.push("transactions = prepended invalid RLP (auto-invalidated)".to_string());
+        }
+
+        if self.invalidate_block_hash {
+            let random_hash = B256::random();
+            payload.block_hash = random_hash;
+            changes.push(format!("block_hash = {random_hash} (auto-invalidated: random)"));
+        }
+
+        changes
+    }
+
+    /// Applies invalidations to a V2 payload, returns list of what was changed.
+    pub(super) fn apply_to_payload_v2(&self, payload: &mut ExecutionPayloadV2) -> Vec<String> {
+        let mut changes = self.apply_to_payload_v1(&mut payload.payload_inner);
+
+        // Handle withdrawals invalidation (V2+)
+        if self.invalidate_withdrawals {
+            let fake_withdrawal = Withdrawal {
+                index: u64::MAX,
+                validator_index: u64::MAX,
+                address: Address::ZERO,
+                amount: u64::MAX,
+            };
+            payload.withdrawals.push(fake_withdrawal);
+            changes.push("withdrawals = added fake withdrawal (auto-invalidated)".to_string());
+        }
+
+        changes
+    }
+
+    /// Applies invalidations to a V3 payload, returns list of what was changed.
+    pub(super) fn apply_to_payload_v3(&self, payload: &mut ExecutionPayloadV3) -> Vec<String> {
+        let mut changes = self.apply_to_payload_v2(&mut payload.payload_inner);
+
+        // Explicit overrides for V3 fields
+        if let Some(blob_gas_used) = self.blob_gas_used {
+            payload.blob_gas_used = blob_gas_used;
+            changes.push(format!("blob_gas_used = {blob_gas_used}"));
+        }
+
+        if let Some(excess_blob_gas) = self.excess_blob_gas {
+            payload.excess_blob_gas = excess_blob_gas;
+            changes.push(format!("excess_blob_gas = {excess_blob_gas}"));
+        }
+
+        // Auto-invalidation for V3 fields
+        if self.invalidate_blob_gas_used {
+            payload.blob_gas_used = u64::MAX;
+            changes.push("blob_gas_used = MAX (auto-invalidated)".to_string());
+        }
+
+        if self.invalidate_excess_blob_gas {
+            payload.excess_blob_gas = u64::MAX;
+            changes.push("excess_blob_gas = MAX (auto-invalidated)".to_string());
+        }
+
+        changes
+    }
+}

bin/reth-bench/src/bench/send_invalid_payload/mod.rs

@@ -0,0 +1,347 @@
+//! Command for sending invalid payloads to test Engine API rejection.
+
+mod invalidation;
+use invalidation::InvalidationConfig;
+
+use super::helpers::{load_jwt_secret, read_input};
+use alloy_primitives::{Address, B256};
+use alloy_provider::network::AnyRpcBlock;
+use alloy_rpc_types_engine::ExecutionPayload;
+use clap::Parser;
+use eyre::{OptionExt, Result};
+use op_alloy_consensus::OpTxEnvelope;
+use reth_cli_runner::CliContext;
+use std::io::Write;
+
+/// Command for generating and sending an invalid `engine_newPayload` request.
+///
+/// Takes a valid block and modifies fields to make it invalid for testing
+/// Engine API rejection behavior. Block hash is recalculated after modifications
+/// unless `--invalidate-block-hash` or `--skip-hash-recalc` is used.
+#[derive(Debug, Parser)]
+pub struct Command {
+    // ==================== Input Options ====================
+    /// Path to the JSON file containing the block. If not specified, stdin will be used.
+    #[arg(short, long, help_heading = "Input Options")]
+    path: Option<String>,
+
+    /// The engine RPC URL to use.
+    #[arg(
+        short,
+        long,
+        help_heading = "Input Options",
+        required_if_eq_any([("mode", "execute"), ("mode", "cast")]),
+        required_unless_present("mode")
+    )]
+    rpc_url: Option<String>,
+
+    /// The JWT secret to use. Can be either a path to a file containing the secret or the secret
+    /// itself.
+    #[arg(short, long, help_heading = "Input Options")]
+    jwt_secret: Option<String>,
+
+    /// The newPayload version to use (3 or 4).
+    #[arg(long, default_value_t = 3, help_heading = "Input Options")]
+    new_payload_version: u8,
+
+    /// The output mode to use.
+    #[arg(long, value_enum, default_value = "execute", help_heading = "Input Options")]
+    mode: Mode,
+
+    // ==================== Explicit Value Overrides ====================
+    /// Override the parent hash with a specific value.
+    #[arg(long, value_name = "HASH", help_heading = "Explicit Value Overrides")]
+    parent_hash: Option<B256>,
+
+    /// Override the fee recipient (coinbase) with a specific address.
+    #[arg(long, value_name = "ADDR", help_heading = "Explicit Value Overrides")]
+    fee_recipient: Option<Address>,
+
+    /// Override the state root with a specific value.
+    #[arg(long, value_name = "HASH", help_heading = "Explicit Value Overrides")]
+    state_root: Option<B256>,
+
+    /// Override the receipts root with a specific value.
+    #[arg(long, value_name = "HASH", help_heading = "Explicit Value Overrides")]
+    receipts_root: Option<B256>,
+
+    /// Override the block number with a specific value.
+    #[arg(long, value_name = "U64", help_heading = "Explicit Value Overrides")]
+    block_number: Option<u64>,
+
+    /// Override the gas limit with a specific value.
+    #[arg(long, value_name = "U64", help_heading = "Explicit Value Overrides")]
+    gas_limit: Option<u64>,
+
+    /// Override the gas used with a specific value.
+    #[arg(long, value_name = "U64", help_heading = "Explicit Value Overrides")]
+    gas_used: Option<u64>,
+
+    /// Override the timestamp with a specific value.
+    #[arg(long, value_name = "U64", help_heading = "Explicit Value Overrides")]
+    timestamp: Option<u64>,
+
+    /// Override the base fee per gas with a specific value.
+    #[arg(long, value_name = "U64", help_heading = "Explicit Value Overrides")]
+    base_fee_per_gas: Option<u64>,
+
+    /// Override the block hash with a specific value (skips hash recalculation).
+    #[arg(long, value_name = "HASH", help_heading = "Explicit Value Overrides")]
+    block_hash: Option<B256>,
+
+    /// Override the blob gas used with a specific value.
+    #[arg(long, value_name = "U64", help_heading = "Explicit Value Overrides")]
+    blob_gas_used: Option<u64>,
+
+    /// Override the excess blob gas with a specific value.
+    #[arg(long, value_name = "U64", help_heading = "Explicit Value Overrides")]
+    excess_blob_gas: Option<u64>,
+
+    /// Override the parent beacon block root with a specific value.
+    #[arg(long, value_name = "HASH", help_heading = "Explicit Value Overrides")]
+    parent_beacon_block_root: Option<B256>,
+
+    /// Override the requests hash with a specific value (EIP-7685).
+    #[arg(long, value_name = "HASH", help_heading = "Explicit Value Overrides")]
+    requests_hash: Option<B256>,
+
+    // ==================== Auto-Invalidation Flags ====================
+    /// Invalidate the parent hash by setting it to a random value.
+    #[arg(long, default_value_t = false, help_heading = "Auto-Invalidation Flags")]
+    invalidate_parent_hash: bool,
+
+    /// Invalidate the state root by setting it to a random value.
+    #[arg(long, default_value_t = false, help_heading = "Auto-Invalidation Flags")]
+    invalidate_state_root: bool,
+
+    /// Invalidate the receipts root by setting it to a random value.
+    #[arg(long, default_value_t = false, help_heading = "Auto-Invalidation Flags")]
+    invalidate_receipts_root: bool,
+
+    /// Invalidate the gas used by setting it to an incorrect value.
+    #[arg(long, default_value_t = false, help_heading = "Auto-Invalidation Flags")]
+    invalidate_gas_used: bool,
+
+    /// Invalidate the block number by setting it to an incorrect value.
+    #[arg(long, default_value_t = false, help_heading = "Auto-Invalidation Flags")]
+    invalidate_block_number: bool,
+
+    /// Invalidate the timestamp by setting it to an incorrect value.
+    #[arg(long, default_value_t = false, help_heading = "Auto-Invalidation Flags")]
+    invalidate_timestamp: bool,
+
+    /// Invalidate the base fee by setting it to an incorrect value.
+    #[arg(long, default_value_t = false, help_heading = "Auto-Invalidation Flags")]
+    invalidate_base_fee: bool,
+
+    /// Invalidate the transactions by modifying them.
+    #[arg(long, default_value_t = false, help_heading = "Auto-Invalidation Flags")]
+    invalidate_transactions: bool,
+
+    /// Invalidate the block hash by not recalculating it after modifications.
+    #[arg(long, default_value_t = false, help_heading = "Auto-Invalidation Flags")]
+    invalidate_block_hash: bool,
+
+    /// Invalidate the withdrawals by modifying them.
+    #[arg(long, default_value_t = false, help_heading = "Auto-Invalidation Flags")]
+    invalidate_withdrawals: bool,
+
+    /// Invalidate the blob gas used by setting it to an incorrect value.
+    #[arg(long, default_value_t = false, help_heading = "Auto-Invalidation Flags")]
+    invalidate_blob_gas_used: bool,
+
+    /// Invalidate the excess blob gas by setting it to an incorrect value.
+    #[arg(long, default_value_t = false, help_heading = "Auto-Invalidation Flags")]
+    invalidate_excess_blob_gas: bool,
+
+    /// Invalidate the requests hash by setting it to a random value (EIP-7685).
+    #[arg(long, default_value_t = false, help_heading = "Auto-Invalidation Flags")]
+    invalidate_requests_hash: bool,
+
+    // ==================== Meta Flags ====================
+    /// Skip block hash recalculation after modifications.
+    #[arg(long, default_value_t = false, help_heading = "Meta Flags")]
+    skip_hash_recalc: bool,
+
+    /// Print what would be done without actually sending the payload.
+    #[arg(long, default_value_t = false, help_heading = "Meta Flags")]
+    dry_run: bool,
+}
+
+#[derive(Debug, Clone, clap::ValueEnum)]
+enum Mode {
+    /// Execute the `cast` command. This works with blocks of any size, because it pipes the
+    /// payload into the `cast` command.
+    Execute,
+    /// Print the `cast` command. Caution: this may not work with large blocks because of the
+    /// command length limit.
+    Cast,
+    /// Print the JSON payload. Can be piped into `cast` command if the block is small enough.
+    Json,
+}
+
+impl Command {
+    /// Build `InvalidationConfig` from command flags
+    const fn build_invalidation_config(&self) -> InvalidationConfig {
+        InvalidationConfig {
+            parent_hash: self.parent_hash,
+            fee_recipient: self.fee_recipient,
+            state_root: self.state_root,
+            receipts_root: self.receipts_root,
+            logs_bloom: None,
+            prev_randao: None,
+            block_number: self.block_number,
+            gas_limit: self.gas_limit,
+            gas_used: self.gas_used,
+            timestamp: self.timestamp,
+            extra_data: None,
+            base_fee_per_gas: self.base_fee_per_gas,
+            block_hash: self.block_hash,
+            blob_gas_used: self.blob_gas_used,
+            excess_blob_gas: self.excess_blob_gas,
+            invalidate_parent_hash: self.invalidate_parent_hash,
+            invalidate_state_root: self.invalidate_state_root,
+            invalidate_receipts_root: self.invalidate_receipts_root,
+            invalidate_gas_used: self.invalidate_gas_used,
+            invalidate_block_number: self.invalidate_block_number,
+            invalidate_timestamp: self.invalidate_timestamp,
+            invalidate_base_fee: self.invalidate_base_fee,
+            invalidate_transactions: self.invalidate_transactions,
+            invalidate_block_hash: self.invalidate_block_hash,
+            invalidate_withdrawals: self.invalidate_withdrawals,
+            invalidate_blob_gas_used: self.invalidate_blob_gas_used,
+            invalidate_excess_blob_gas: self.invalidate_excess_blob_gas,
+        }
+    }
+
+    /// Execute the command
+    pub async fn execute(self, _ctx: CliContext) -> Result<()> {
+        let block_json = read_input(self.path.as_deref())?;
+        let jwt_secret = load_jwt_secret(self.jwt_secret.as_deref())?;
+
+        let block = serde_json::from_str::<AnyRpcBlock>(&block_json)?
+            .into_inner()
+            .map_header(|header| header.map(|h| h.into_header_with_defaults()))
+            .try_map_transactions(|tx| tx.try_into_either::<OpTxEnvelope>())?
+            .into_consensus();
+
+        let config = self.build_invalidation_config();
+
+        let parent_beacon_block_root =
+            self.parent_beacon_block_root.or(block.header.parent_beacon_block_root);
+        let blob_versioned_hashes =
+            block.body.blob_versioned_hashes_iter().copied().collect::<Vec<_>>();
+        let use_v4 = block.header.requests_hash.is_some();
+        let requests_hash = self.requests_hash.or(block.header.requests_hash);
+
+        let mut execution_payload = ExecutionPayload::from_block_slow(&block).0;
+
+        let changes = match &mut execution_payload {
+            ExecutionPayload::V1(p) => config.apply_to_payload_v1(p),
+            ExecutionPayload::V2(p) => config.apply_to_payload_v2(p),
+            ExecutionPayload::V3(p) => config.apply_to_payload_v3(p),
+        };
+
+        let skip_recalc = self.skip_hash_recalc || config.should_skip_hash_recalc();
+        if !skip_recalc {
+            let new_hash = match execution_payload.clone().into_block_raw() {
+                Ok(block) => block.header.hash_slow(),
+                Err(e) => {
+                    eprintln!(
+                        "Warning: Could not recalculate block hash: {e}. Using original hash."
+                    );
+                    match &execution_payload {
+                        ExecutionPayload::V1(p) => p.block_hash,
+                        ExecutionPayload::V2(p) => p.payload_inner.block_hash,
+                        ExecutionPayload::V3(p) => p.payload_inner.payload_inner.block_hash,
+                    }
+                }
+            };
+
+            match &mut execution_payload {
+                ExecutionPayload::V1(p) => p.block_hash = new_hash,
+                ExecutionPayload::V2(p) => p.payload_inner.block_hash = new_hash,
+                ExecutionPayload::V3(p) => p.payload_inner.payload_inner.block_hash = new_hash,
+            }
+        }
+
+        if self.dry_run {
+            println!("=== Dry Run ===");
+            println!("Changes that would be applied:");
+            for change in &changes {
+                println!("  - {}", change);
+            }
+            if changes.is_empty() {
+                println!("  (no changes)");
+            }
+            if skip_recalc {
+                println!("  - Block hash recalculation: SKIPPED");
+            } else {
+                println!("  - Block hash recalculation: PERFORMED");
+            }
+            println!("\nResulting payload JSON:");
+            let json = serde_json::to_string_pretty(&execution_payload)?;
+            println!("{}", json);
+            return Ok(());
+        }
+
+        let json_request = if use_v4 {
+            serde_json::to_string(&(
+                execution_payload,
+                blob_versioned_hashes,
+                parent_beacon_block_root,
+                requests_hash.unwrap_or_default(),
+            ))?
+        } else {
+            serde_json::to_string(&(
+                execution_payload,
+                blob_versioned_hashes,
+                parent_beacon_block_root,
+            ))?
+        };
+
+        match self.mode {
+            Mode::Execute => {
+                let mut command = std::process::Command::new("cast");
+                let method = if use_v4 { "engine_newPayloadV4" } else { "engine_newPayloadV3" };
+                command.arg("rpc").arg(method).arg("--raw");
+                if let Some(rpc_url) = self.rpc_url {
+                    command.arg("--rpc-url").arg(rpc_url);
+                }
+                if let Some(secret) = &jwt_secret {
+                    command.arg("--jwt-secret").arg(secret);
+                }
+
+                let mut process = command.stdin(std::process::Stdio::piped()).spawn()?;
+
+                process
+                    .stdin
+                    .take()
+                    .ok_or_eyre("stdin not available")?
+                    .write_all(json_request.as_bytes())?;
+
+                process.wait()?;
+            }
+            Mode::Cast => {
+                let mut cmd = format!(
+                    "cast rpc engine_newPayloadV{} --raw '{}'",
+                    self.new_payload_version, json_request
+                );
+
+                if let Some(rpc_url) = self.rpc_url {
+                    cmd += &format!(" --rpc-url {rpc_url}");
+                }
+                if let Some(secret) = &jwt_secret {
+                    cmd += &format!(" --jwt-secret {secret}");
+                }
+
+                println!("{cmd}");
+            }
+            Mode::Json => {
+                println!("{json_request}");
+            }
+        }
+
+        Ok(())
+    }
+}

bin/reth-bench/src/bench/send_payload.rs

@@ -1,10 +1,11 @@
+use super::helpers::{load_jwt_secret, read_input};
 use alloy_provider::network::AnyRpcBlock;
 use alloy_rpc_types_engine::ExecutionPayload;
 use clap::Parser;
 use eyre::{OptionExt, Result};
 use op_alloy_consensus::OpTxEnvelope;
 use reth_cli_runner::CliContext;
-use std::io::{BufReader, Read, Write};
+use std::io::Write;
 
 /// Command for generating and sending an `engine_newPayload` request constructed from an RPC
 /// block.
@@ -51,38 +52,13 @@ enum Mode {
 }
 
 impl Command {
-    /// Read input from either a file or stdin
-    fn read_input(&self) -> Result<String> {
-        Ok(match &self.path {
-            Some(path) => reth_fs_util::read_to_string(path)?,
-            None => String::from_utf8(
-                BufReader::new(std::io::stdin()).bytes().collect::<Result<Vec<_>, _>>()?,
-            )?,
-        })
-    }
-
-    /// Load JWT secret from either a file or use the provided string directly
-    fn load_jwt_secret(&self) -> Result<Option<String>> {
-        match &self.jwt_secret {
-            Some(secret) => {
-                // Try to read as file first
-                match std::fs::read_to_string(secret) {
-                    Ok(contents) => Ok(Some(contents.trim().to_string())),
-                    // If file read fails, use the string directly
-                    Err(_) => Ok(Some(secret.clone())),
-                }
-            }
-            None => Ok(None),
-        }
-    }
-
     /// Execute the generate payload command
     pub async fn execute(self, _ctx: CliContext) -> Result<()> {
         // Load block
-        let block_json = self.read_input()?;
+        let block_json = read_input(self.path.as_deref())?;
 
         // Load JWT secret
-        let jwt_secret = self.load_jwt_secret()?;
+        let jwt_secret = load_jwt_secret(self.jwt_secret.as_deref())?;
 
         // Parse the block
         let block = serde_json::from_str::<AnyRpcBlock>(&block_json)?

bin/reth-bench/src/valid_payload.rs

@@ -260,7 +260,9 @@ pub(crate) async fn call_new_payload<N: Network, P: Provider<N>>(
     while !status.is_valid() {
         if status.is_invalid() {
             error!(?status, ?params, "Invalid {method}",);
-            panic!("Invalid {method}: {status:?}");
+            return Err(alloy_json_rpc::RpcError::LocalUsageError(Box::new(std::io::Error::other(
+                format!("Invalid {method}: {status:?}"),
+            ))))
         }
         if status.is_syncing() {
             return Err(alloy_json_rpc::RpcError::UnsupportedFeature(

bin/reth/src/lib.rs

@@ -25,8 +25,8 @@
 //! - `jemalloc-unprefixed`: Uses unprefixed jemalloc symbols.
 //! - `tracy-allocator`: Enables [Tracy](https://github.com/wolfpld/tracy) profiler allocator
 //!   integration for memory profiling.
-//! - `snmalloc`: Uses [snmalloc](https://github.com/snmalloc/snmalloc) as the global allocator. Use
-//!   `--no-default-features` when enabling this, as jemalloc takes precedence.
+//! - `snmalloc`: Uses [snmalloc](https://github.com/microsoft/snmalloc) as the global allocator.
+//!   Use `--no-default-features` when enabling this, as jemalloc takes precedence.
 //! - `snmalloc-native`: Uses snmalloc with native CPU optimizations. Use `--no-default-features`
 //!   when enabling this.
 //!

crates/chain-state/Cargo.toml

@@ -41,6 +41,7 @@ derive_more.workspace = true
 metrics.workspace = true
 parking_lot.workspace = true
 pin-project.workspace = true
+rayon = { workspace = true, optional = true }
 serde = { workspace = true, optional = true }
 
 # optional deps for test-utils
@@ -84,6 +85,7 @@ test-utils = [
     "reth-trie/test-utils",
     "reth-ethereum-primitives/test-utils",
 ]
+rayon = ["dep:rayon"]
 
 [[bench]]
 name = "canonical_hashes_range"

crates/chain-state/src/deferred_trie.rs

@@ -163,14 +163,29 @@ impl DeferredTrieData {
         anchor_hash: B256,
         ancestors: &[Self],
     ) -> ComputedTrieData {
-        let sorted_hashed_state = match Arc::try_unwrap(hashed_state) {
-            Ok(state) => state.into_sorted(),
-            Err(arc) => arc.clone_into_sorted(),
-        };
-        let sorted_trie_updates = match Arc::try_unwrap(trie_updates) {
-            Ok(updates) => updates.into_sorted(),
-            Err(arc) => arc.clone_into_sorted(),
-        };
+        #[cfg(feature = "rayon")]
+        let (sorted_hashed_state, sorted_trie_updates) = rayon::join(
+            || match Arc::try_unwrap(hashed_state) {
+                Ok(state) => state.into_sorted(),
+                Err(arc) => arc.clone_into_sorted(),
+            },
+            || match Arc::try_unwrap(trie_updates) {
+                Ok(updates) => updates.into_sorted(),
+                Err(arc) => arc.clone_into_sorted(),
+            },
+        );
+
+        #[cfg(not(feature = "rayon"))]
+        let (sorted_hashed_state, sorted_trie_updates) = (
+            match Arc::try_unwrap(hashed_state) {
+                Ok(state) => state.into_sorted(),
+                Err(arc) => arc.clone_into_sorted(),
+            },
+            match Arc::try_unwrap(trie_updates) {
+                Ok(updates) => updates.into_sorted(),
+                Err(arc) => arc.clone_into_sorted(),
+            },
+        );
 
         // Reuse parent's overlay if available and anchors match.
         // We can only reuse the parent's overlay if it was built on top of the same
@@ -191,11 +206,33 @@ impl DeferredTrieData {
                         Default::default(), // prefix_sets are per-block, not cumulative
                     );
                     // Only trigger COW clone if there's actually data to add.
-                    if !sorted_hashed_state.is_empty() {
-                        Arc::make_mut(&mut overlay.state).extend_ref_and_sort(&sorted_hashed_state);
+                    #[cfg(feature = "rayon")]
+                    {
+                        rayon::join(
+                            || {
+                                if !sorted_hashed_state.is_empty() {
+                                    Arc::make_mut(&mut overlay.state)
+                                        .extend_ref_and_sort(&sorted_hashed_state);
+                                }
+                            },
+                            || {
+                                if !sorted_trie_updates.is_empty() {
+                                    Arc::make_mut(&mut overlay.nodes)
+                                        .extend_ref_and_sort(&sorted_trie_updates);
+                                }
+                            },
+                        );
                     }
-                    if !sorted_trie_updates.is_empty() {
-                        Arc::make_mut(&mut overlay.nodes).extend_ref_and_sort(&sorted_trie_updates);
+                    #[cfg(not(feature = "rayon"))]
+                    {
+                        if !sorted_hashed_state.is_empty() {
+                            Arc::make_mut(&mut overlay.state)
+                                .extend_ref_and_sort(&sorted_hashed_state);
+                        }
+                        if !sorted_trie_updates.is_empty() {
+                            Arc::make_mut(&mut overlay.nodes)
+                                .extend_ref_and_sort(&sorted_trie_updates);
+                        }
                     }
                     overlay
                 }
@@ -247,8 +284,17 @@ impl DeferredTrieData {
         }
 
         // Extend with current block's sorted data last (takes precedence)
-        state_mut.extend_ref_and_sort(sorted_hashed_state);
-        nodes_mut.extend_ref_and_sort(sorted_trie_updates);
+        #[cfg(feature = "rayon")]
+        rayon::join(
+            || state_mut.extend_ref_and_sort(sorted_hashed_state),
+            || nodes_mut.extend_ref_and_sort(sorted_trie_updates),
+        );
+
+        #[cfg(not(feature = "rayon"))]
+        {
+            state_mut.extend_ref_and_sort(sorted_hashed_state);
+            nodes_mut.extend_ref_and_sort(sorted_trie_updates);
+        }
 
         overlay
     }

crates/chain-state/src/in_memory.rs

@@ -17,7 +17,10 @@ use reth_primitives_traits::{
     SignedTransaction,
 };
 use reth_storage_api::StateProviderBox;
-use reth_trie::{updates::TrieUpdatesSorted, HashedPostStateSorted, LazyTrieData, TrieInputSorted};
+use reth_trie::{
+    updates::TrieUpdatesSorted, HashedPostStateSorted, LazyTrieData, SortedTrieData,
+    TrieInputSorted,
+};
 use std::{collections::BTreeMap, sync::Arc, time::Instant};
 use tokio::sync::{broadcast, watch};
 
@@ -948,22 +951,36 @@ impl<N: NodePrimitives<SignedTx: SignedTransaction>> NewCanonicalChain<N> {
         match blocks {
             [] => Chain::default(),
             [first, rest @ ..] => {
+                let trie_data_handle = first.trie_data_handle();
                 let mut chain = Chain::from_block(
                     first.recovered_block().clone(),
                     ExecutionOutcome::from((
                         first.execution_outcome().clone(),
                         first.block_number(),
                     )),
-                    LazyTrieData::ready(first.hashed_state(), first.trie_updates()),
+                    LazyTrieData::deferred(move || {
+                        let trie_data = trie_data_handle.wait_cloned();
+                        SortedTrieData {
+                            hashed_state: trie_data.hashed_state,
+                            trie_updates: trie_data.trie_updates,
+                        }
+                    }),
                 );
                 for exec in rest {
+                    let trie_data_handle = exec.trie_data_handle();
                     chain.append_block(
                         exec.recovered_block().clone(),
                         ExecutionOutcome::from((
                             exec.execution_outcome().clone(),
                             exec.block_number(),
                         )),
-                        LazyTrieData::ready(exec.hashed_state(), exec.trie_updates()),
+                        LazyTrieData::deferred(move || {
+                            let trie_data = trie_data_handle.wait_cloned();
+                            SortedTrieData {
+                                hashed_state: trie_data.hashed_state,
+                                trie_updates: trie_data.trie_updates,
+                            }
+                        }),
                     );
                 }
                 chain

crates/chain-state/src/lazy_overlay.rs

@@ -123,60 +123,18 @@ impl LazyOverlay {
 
     /// Merge all blocks' trie data into a single [`TrieInputSorted`].
     ///
-    /// Blocks are ordered newest to oldest. Uses hybrid merge algorithm that
-    /// switches between `extend_ref` (small batches) and k-way merge (large batches).
+    /// Blocks are ordered newest to oldest.
     fn merge_blocks(blocks: &[DeferredTrieData]) -> TrieInputSorted {
-        const MERGE_BATCH_THRESHOLD: usize = 64;
-
         if blocks.is_empty() {
             return TrieInputSorted::default();
         }
 
-        // Single block: use its data directly (no allocation)
-        if blocks.len() == 1 {
-            let data = blocks[0].wait_cloned();
-            return TrieInputSorted {
-                state: data.hashed_state,
-                nodes: data.trie_updates,
-                prefix_sets: Default::default(),
-            };
-        }
+        let state =
+            HashedPostStateSorted::merge_batch(blocks.iter().map(|b| b.wait_cloned().hashed_state));
+        let nodes =
+            TrieUpdatesSorted::merge_batch(blocks.iter().map(|b| b.wait_cloned().trie_updates));
 
-        if blocks.len() < MERGE_BATCH_THRESHOLD {
-            // Small k: extend_ref loop with Arc::make_mut is faster.
-            // Uses copy-on-write - only clones inner data if Arc has multiple refs.
-            // Iterate oldest->newest so newer values override older ones.
-            let mut blocks_iter = blocks.iter().rev();
-            let first = blocks_iter.next().expect("blocks is non-empty");
-            let data = first.wait_cloned();
-
-            let mut state = data.hashed_state;
-            let mut nodes = data.trie_updates;
-
-            for block in blocks_iter {
-                let block_data = block.wait_cloned();
-                Arc::make_mut(&mut state).extend_ref_and_sort(block_data.hashed_state.as_ref());
-                Arc::make_mut(&mut nodes).extend_ref_and_sort(block_data.trie_updates.as_ref());
-            }
-
-            TrieInputSorted { state, nodes, prefix_sets: Default::default() }
-        } else {
-            // Large k: k-way merge is faster (O(n log k)).
-            // Collect is unavoidable here - we need all data materialized for k-way merge.
-            let trie_data: Vec<_> = blocks.iter().map(|b| b.wait_cloned()).collect();
-
-            let merged_state = HashedPostStateSorted::merge_batch(
-                trie_data.iter().map(|d| d.hashed_state.as_ref()),
-            );
-            let merged_nodes =
-                TrieUpdatesSorted::merge_batch(trie_data.iter().map(|d| d.trie_updates.as_ref()));
-
-            TrieInputSorted {
-                state: Arc::new(merged_state),
-                nodes: Arc::new(merged_nodes),
-                prefix_sets: Default::default(),
-            }
-        }
+        TrieInputSorted { state, nodes, prefix_sets: Default::default() }
     }
 }
 

crates/chainspec/src/lib.rs

@@ -25,6 +25,7 @@ pub use alloy_chains::{Chain, ChainKind, NamedChain};
 /// Re-export for convenience
 pub use reth_ethereum_forks::*;
 
+pub use alloy_evm::EvmLimitParams;
 pub use api::EthChainSpec;
 pub use info::ChainInfo;
 #[cfg(any(test, feature = "test-utils"))]

crates/chainspec/src/spec.rs

@@ -278,6 +278,7 @@ pub fn create_chain_config(
     // Check if DAO fork is supported (it has an activation block)
     let dao_fork_support = hardforks.fork(EthereumHardfork::Dao) != ForkCondition::Never;
 
+    #[allow(clippy::needless_update)]
     ChainConfig {
         chain_id: chain.map(|c| c.id()).unwrap_or(0),
         homestead_block: block_num(EthereumHardfork::Homestead),
@@ -313,6 +314,7 @@ pub fn create_chain_config(
         extra_fields: Default::default(),
         deposit_contract_address,
         blob_schedule,
+        ..Default::default()
     }
 }
 
@@ -539,7 +541,7 @@ impl<H: BlockHeader> ChainSpec<H> {
                     }
                 }
 
-                bf_params.first().map(|(_, params)| *params).unwrap_or(BaseFeeParams::ethereum())
+                bf_params.first().map(|(_, params)| *params).unwrap_or_else(BaseFeeParams::ethereum)
             }
         }
     }

crates/cli/commands/Cargo.toml

@@ -50,6 +50,7 @@ reth-stages-types = { workspace = true, optional = true }
 reth-static-file-types = { workspace = true, features = ["clap"] }
 reth-static-file.workspace = true
 reth-tasks.workspace = true
+reth-storage-api.workspace = true
 reth-trie = { workspace = true, features = ["metrics"] }
 reth-trie-db = { workspace = true, features = ["metrics"] }
 reth-trie-common.workspace = true
@@ -77,6 +78,7 @@ lz4.workspace = true
 zstd.workspace = true
 serde.workspace = true
 serde_json.workspace = true
+parking_lot.workspace = true
 tar.workspace = true
 tracing.workspace = true
 backon.workspace = true
@@ -131,4 +133,4 @@ arbitrary = [
     "reth-ethereum-primitives/arbitrary",
 ]
 
-edge = ["reth-db-common/edge", "reth-stages/rocksdb"]
+edge = ["reth-db-common/edge", "reth-stages/rocksdb", "reth-provider/rocksdb"]

crates/cli/commands/src/common.rs

@@ -19,7 +19,7 @@ use reth_node_builder::{
     Node, NodeComponents, NodeComponentsBuilder, NodeTypes, NodeTypesWithDBAdapter,
 };
 use reth_node_core::{
-    args::{DatabaseArgs, DatadirArgs, StaticFilesArgs},
+    args::{DatabaseArgs, DatadirArgs, RocksDbArgs, StaticFilesArgs},
     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;
@@ -66,9 +66,24 @@ pub struct EnvironmentArgs<C: ChainSpecParser> {
     /// All static files related arguments
     #[command(flatten)]
     pub static_files: StaticFilesArgs,
+
+    /// All `RocksDB` related arguments
+    #[command(flatten)]
+    pub rocksdb: RocksDbArgs,
 }
 
 impl<C: ChainSpecParser> EnvironmentArgs<C> {
+    /// Returns the effective storage settings derived from static-file and `RocksDB` CLI args.
+    pub fn storage_settings(&self) -> StorageSettings {
+        StorageSettings::base()
+            .with_receipts_in_static_files(self.static_files.receipts)
+            .with_transaction_senders_in_static_files(self.static_files.transaction_senders)
+            .with_account_changesets_in_static_files(self.static_files.account_changesets)
+            .with_transaction_hash_numbers_in_rocksdb(self.rocksdb.all || self.rocksdb.tx_hash)
+            .with_storages_history_in_rocksdb(self.rocksdb.all || self.rocksdb.storages_history)
+            .with_account_history_in_rocksdb(self.rocksdb.all || self.rocksdb.account_history)
+    }
+
     /// Initializes environment according to [`AccessRights`] and returns an instance of
     /// [`Environment`].
     pub fn init<N: CliNodeTypes>(&self, access: AccessRights) -> eyre::Result<Environment<N>>
@@ -106,13 +121,13 @@ impl<C: ChainSpecParser> EnvironmentArgs<C> {
         let genesis_block_number = self.chain.genesis().number.unwrap_or_default();
         let (db, sfp) = match access {
             AccessRights::RW => (
-                Arc::new(init_db(db_path, self.db.database_args())?),
+                init_db(db_path, self.db.database_args())?,
                 StaticFileProviderBuilder::read_write(sf_path)
                     .with_genesis_block_number(genesis_block_number)
                     .build()?,
             ),
             AccessRights::RO | AccessRights::RoInconsistent => {
-                (Arc::new(open_db_read_only(&db_path, self.db.database_args())?), {
+                (open_db_read_only(&db_path, self.db.database_args())?, {
                     let provider = StaticFileProviderBuilder::read_only(sf_path)
                         .with_genesis_block_number(genesis_block_number)
                         .build()?;
@@ -121,17 +136,17 @@ impl<C: ChainSpecParser> EnvironmentArgs<C> {
                 })
             }
         };
-        // TransactionDB only support read-write mode
         let rocksdb_provider = RocksDBProvider::builder(data_dir.rocksdb())
             .with_default_tables()
             .with_database_log_level(self.db.log_level)
+            .with_read_only(!access.is_read_write())
             .build()?;
 
         let provider_factory =
             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())?;
+            init_genesis_with_settings(&provider_factory, self.storage_settings())?;
         }
 
         Ok(Environment { config, provider_factory, data_dir })
@@ -145,16 +160,16 @@ impl<C: ChainSpecParser> EnvironmentArgs<C> {
     fn create_provider_factory<N: CliNodeTypes>(
         &self,
         config: &Config,
-        db: Arc<DatabaseEnv>,
+        db: DatabaseEnv,
         static_file_provider: StaticFileProvider<N::Primitives>,
         rocksdb_provider: RocksDBProvider,
         access: AccessRights,
-    ) -> eyre::Result<ProviderFactory<NodeTypesWithDBAdapter<N, Arc<DatabaseEnv>>>>
+    ) -> eyre::Result<ProviderFactory<NodeTypesWithDBAdapter<N, DatabaseEnv>>>
     where
         C: ChainSpecParser<ChainSpec = N::ChainSpec>,
     {
         let prune_modes = config.prune.segments.clone();
-        let factory = ProviderFactory::<NodeTypesWithDBAdapter<N, Arc<DatabaseEnv>>>::new(
+        let factory = ProviderFactory::<NodeTypesWithDBAdapter<N, DatabaseEnv>>::new(
             db,
             self.chain.clone(),
             static_file_provider,
@@ -185,7 +200,7 @@ impl<C: ChainSpecParser> EnvironmentArgs<C> {
             let (_tip_tx, tip_rx) = watch::channel(B256::ZERO);
 
             // Builds and executes an unwind-only pipeline
-            let mut pipeline = Pipeline::<NodeTypesWithDBAdapter<N, Arc<DatabaseEnv>>>::builder()
+            let mut pipeline = Pipeline::<NodeTypesWithDBAdapter<N, DatabaseEnv>>::builder()
                 .add_stages(DefaultStages::new(
                     factory.clone(),
                     tip_rx,
@@ -214,7 +229,7 @@ pub struct Environment<N: NodeTypes> {
     /// Configuration for reth node
     pub config: Config,
     /// Provider factory.
-    pub provider_factory: ProviderFactory<NodeTypesWithDBAdapter<N, Arc<DatabaseEnv>>>,
+    pub provider_factory: ProviderFactory<NodeTypesWithDBAdapter<N, DatabaseEnv>>,
     /// Datadir path.
     pub data_dir: ChainPath<DataDirPath>,
 }
@@ -246,8 +261,8 @@ impl AccessRights {
 /// Helper alias to satisfy `FullNodeTypes` bound on [`Node`] trait generic.
 type FullTypesAdapter<T> = FullNodeTypesAdapter<
     T,
-    Arc<DatabaseEnv>,
-    BlockchainProvider<NodeTypesWithDBAdapter<T, Arc<DatabaseEnv>>>,
+    DatabaseEnv,
+    BlockchainProvider<NodeTypesWithDBAdapter<T, DatabaseEnv>>,
 >;
 
 /// Helper trait with a common set of requirements for the

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

@@ -1,145 +0,0 @@
-use crate::{
-    common::CliNodeTypes,
-    db::get::{maybe_json_value_parser, table_key},
-};
-use alloy_primitives::map::foldhash::fast::FixedState;
-use clap::Parser;
-use reth_chainspec::EthereumHardforks;
-use reth_db::DatabaseEnv;
-use reth_db_api::{
-    cursor::DbCursorRO, table::Table, transaction::DbTx, RawKey, RawTable, RawValue, TableViewer,
-    Tables,
-};
-use reth_db_common::DbTool;
-use reth_node_builder::{NodeTypesWithDB, NodeTypesWithDBAdapter};
-use reth_provider::{providers::ProviderNodeTypes, DBProvider};
-use std::{
-    hash::{BuildHasher, Hasher},
-    sync::Arc,
-    time::{Duration, Instant},
-};
-use tracing::{info, warn};
-
-#[derive(Parser, Debug)]
-/// The arguments for the `reth db checksum` command
-pub struct Command {
-    /// The table name
-    table: Tables,
-
-    /// The start of the range to checksum.
-    #[arg(long, value_parser = maybe_json_value_parser)]
-    start_key: Option<String>,
-
-    /// The end of the range to checksum.
-    #[arg(long, value_parser = maybe_json_value_parser)]
-    end_key: Option<String>,
-
-    /// The maximum number of records that are queried and used to compute the
-    /// checksum.
-    #[arg(long)]
-    limit: Option<usize>,
-}
-
-impl Command {
-    /// Execute `db checksum` command
-    pub fn execute<N: CliNodeTypes<ChainSpec: EthereumHardforks>>(
-        self,
-        tool: &DbTool<NodeTypesWithDBAdapter<N, Arc<DatabaseEnv>>>,
-    ) -> eyre::Result<()> {
-        warn!("This command should be run without the node running!");
-        self.table.view(&ChecksumViewer {
-            tool,
-            start_key: self.start_key,
-            end_key: self.end_key,
-            limit: self.limit,
-        })?;
-        Ok(())
-    }
-}
-
-pub(crate) struct ChecksumViewer<'a, N: NodeTypesWithDB> {
-    tool: &'a DbTool<N>,
-    start_key: Option<String>,
-    end_key: Option<String>,
-    limit: Option<usize>,
-}
-
-impl<N: NodeTypesWithDB> ChecksumViewer<'_, N> {
-    pub(crate) const fn new(tool: &'_ DbTool<N>) -> ChecksumViewer<'_, N> {
-        ChecksumViewer { tool, start_key: None, end_key: None, limit: None }
-    }
-}
-
-impl<N: ProviderNodeTypes> TableViewer<(u64, Duration)> for ChecksumViewer<'_, N> {
-    type Error = eyre::Report;
-
-    fn view<T: Table>(&self) -> Result<(u64, Duration), Self::Error> {
-        let provider =
-            self.tool.provider_factory.provider()?.disable_long_read_transaction_safety();
-        let tx = provider.tx_ref();
-        info!(
-            "Start computing checksum, start={:?}, end={:?}, limit={:?}",
-            self.start_key, self.end_key, self.limit
-        );
-
-        let mut cursor = tx.cursor_read::<RawTable<T>>()?;
-        let walker = match (self.start_key.as_deref(), self.end_key.as_deref()) {
-            (Some(start), Some(end)) => {
-                let start_key = table_key::<T>(start).map(RawKey::new)?;
-                let end_key = table_key::<T>(end).map(RawKey::new)?;
-                cursor.walk_range(start_key..=end_key)?
-            }
-            (None, Some(end)) => {
-                let end_key = table_key::<T>(end).map(RawKey::new)?;
-
-                cursor.walk_range(..=end_key)?
-            }
-            (Some(start), None) => {
-                let start_key = table_key::<T>(start).map(RawKey::new)?;
-                cursor.walk_range(start_key..)?
-            }
-            (None, None) => cursor.walk_range(..)?,
-        };
-
-        let start_time = Instant::now();
-        let mut hasher = FixedState::with_seed(u64::from_be_bytes(*b"RETHRETH")).build_hasher();
-        let mut total = 0;
-
-        let limit = self.limit.unwrap_or(usize::MAX);
-        let mut enumerate_start_key = None;
-        let mut enumerate_end_key = None;
-        for (index, entry) in walker.enumerate() {
-            let (k, v): (RawKey<T::Key>, RawValue<T::Value>) = entry?;
-
-            if index.is_multiple_of(100_000) {
-                info!("Hashed {index} entries.");
-            }
-
-            hasher.write(k.raw_key());
-            hasher.write(v.raw_value());
-
-            if enumerate_start_key.is_none() {
-                enumerate_start_key = Some(k.clone());
-            }
-            enumerate_end_key = Some(k);
-
-            total = index + 1;
-            if total >= limit {
-                break
-            }
-        }
-
-        info!("Hashed {total} entries.");
-        if let (Some(s), Some(e)) = (enumerate_start_key, enumerate_end_key) {
-            info!("start-key: {}", serde_json::to_string(&s.key()?).unwrap_or_default());
-            info!("end-key: {}", serde_json::to_string(&e.key()?).unwrap_or_default());
-        }
-
-        let checksum = hasher.finish();
-        let elapsed = start_time.elapsed();
-
-        info!("Checksum for table `{}`: {:#x} (elapsed: {:?})", T::NAME, checksum, elapsed);
-
-        Ok((checksum, elapsed))
-    }
-}

crates/cli/commands/src/db/checksum/mod.rs

@@ -0,0 +1,287 @@
+use crate::{
+    common::CliNodeTypes,
+    db::get::{maybe_json_value_parser, table_key},
+};
+use alloy_primitives::map::foldhash::fast::FixedState;
+use clap::Parser;
+use itertools::Itertools;
+use reth_chainspec::EthereumHardforks;
+use reth_db::{static_file::iter_static_files, DatabaseEnv};
+use reth_db_api::{
+    cursor::DbCursorRO, table::Table, transaction::DbTx, RawKey, RawTable, RawValue, TableViewer,
+    Tables,
+};
+use reth_db_common::DbTool;
+use reth_node_builder::{NodeTypesWithDB, NodeTypesWithDBAdapter};
+use reth_provider::{providers::ProviderNodeTypes, DBProvider, StaticFileProviderFactory};
+use reth_static_file_types::StaticFileSegment;
+use std::{
+    hash::{BuildHasher, Hasher},
+    time::{Duration, Instant},
+};
+use tracing::{info, warn};
+
+#[cfg(all(unix, feature = "edge"))]
+mod rocksdb;
+
+/// Interval for logging progress during checksum computation.
+const PROGRESS_LOG_INTERVAL: usize = 100_000;
+
+#[derive(Parser, Debug)]
+/// The arguments for the `reth db checksum` command
+pub struct Command {
+    #[command(subcommand)]
+    subcommand: Subcommand,
+}
+
+#[derive(clap::Subcommand, Debug)]
+enum Subcommand {
+    /// Calculates the checksum of a database table
+    Mdbx {
+        /// The table name
+        table: Tables,
+
+        /// The start of the range to checksum.
+        #[arg(long, value_parser = maybe_json_value_parser)]
+        start_key: Option<String>,
+
+        /// The end of the range to checksum.
+        #[arg(long, value_parser = maybe_json_value_parser)]
+        end_key: Option<String>,
+
+        /// The maximum number of records that are queried and used to compute the
+        /// checksum.
+        #[arg(long)]
+        limit: Option<usize>,
+    },
+    /// Calculates the checksum of a static file segment
+    StaticFile {
+        /// The static file segment
+        #[arg(value_enum)]
+        segment: StaticFileSegment,
+
+        /// The block number to start from (inclusive).
+        #[arg(long)]
+        start_block: Option<u64>,
+
+        /// The block number to end at (inclusive).
+        #[arg(long)]
+        end_block: Option<u64>,
+
+        /// The maximum number of rows to checksum.
+        #[arg(long)]
+        limit: Option<usize>,
+    },
+    /// Calculates the checksum of a RocksDB table
+    #[cfg(all(unix, feature = "edge"))]
+    Rocksdb {
+        /// The RocksDB table
+        #[arg(value_enum)]
+        table: rocksdb::RocksDbTable,
+
+        /// The maximum number of records to checksum.
+        #[arg(long)]
+        limit: Option<usize>,
+    },
+}
+
+impl Command {
+    /// Execute `db checksum` command
+    pub fn execute<N: CliNodeTypes<ChainSpec: EthereumHardforks>>(
+        self,
+        tool: &DbTool<NodeTypesWithDBAdapter<N, DatabaseEnv>>,
+    ) -> eyre::Result<()> {
+        warn!("This command should be run without the node running!");
+
+        match self.subcommand {
+            Subcommand::Mdbx { table, start_key, end_key, limit } => {
+                table.view(&ChecksumViewer { tool, start_key, end_key, limit })?;
+            }
+            Subcommand::StaticFile { segment, start_block, end_block, limit } => {
+                checksum_static_file(tool, segment, start_block, end_block, limit)?;
+            }
+            #[cfg(all(unix, feature = "edge"))]
+            Subcommand::Rocksdb { table, limit } => {
+                rocksdb::checksum_rocksdb(tool, table, limit)?;
+            }
+        }
+
+        Ok(())
+    }
+}
+
+/// Creates a new hasher with the standard seed used for checksum computation.
+fn checksum_hasher() -> impl Hasher {
+    FixedState::with_seed(u64::from_be_bytes(*b"RETHRETH")).build_hasher()
+}
+
+fn checksum_static_file<N: CliNodeTypes<ChainSpec: EthereumHardforks>>(
+    tool: &DbTool<NodeTypesWithDBAdapter<N, DatabaseEnv>>,
+    segment: StaticFileSegment,
+    start_block: Option<u64>,
+    end_block: Option<u64>,
+    limit: Option<usize>,
+) -> eyre::Result<()> {
+    let static_file_provider = tool.provider_factory.static_file_provider();
+    if let Err(err) = static_file_provider.check_consistency(&tool.provider_factory.provider()?) {
+        warn!("Error checking consistency of static files: {err}");
+    }
+
+    let static_files = iter_static_files(static_file_provider.directory())?;
+
+    let ranges = static_files
+        .get(segment)
+        .ok_or_else(|| eyre::eyre!("No static files found for segment: {}", segment))?;
+
+    let start_time = Instant::now();
+    let mut hasher = checksum_hasher();
+    let mut total = 0usize;
+    let limit = limit.unwrap_or(usize::MAX);
+
+    let start_block = start_block.unwrap_or(0);
+    let end_block = end_block.unwrap_or(u64::MAX);
+
+    info!(
+        "Computing checksum for {} static files, start_block={}, end_block={}, limit={:?}",
+        segment,
+        start_block,
+        end_block,
+        if limit == usize::MAX { None } else { Some(limit) }
+    );
+
+    'outer: for (block_range, _header) in ranges.iter().sorted_by_key(|(range, _)| range.start()) {
+        if block_range.end() < start_block || block_range.start() > end_block {
+            continue;
+        }
+
+        let fixed_block_range = static_file_provider.find_fixed_range(segment, block_range.start());
+        let jar_provider = static_file_provider
+            .get_segment_provider_for_range(segment, || Some(fixed_block_range), None)?
+            .ok_or_else(|| {
+                eyre::eyre!(
+                    "Failed to get segment provider for segment {} at range {}",
+                    segment,
+                    block_range
+                )
+            })?;
+
+        let mut cursor = jar_provider.cursor()?;
+
+        while let Ok(Some(row)) = cursor.next_row() {
+            for col_data in row.iter() {
+                hasher.write(col_data);
+            }
+
+            total += 1;
+
+            if total.is_multiple_of(PROGRESS_LOG_INTERVAL) {
+                info!("Hashed {total} entries.");
+            }
+
+            if total >= limit {
+                break 'outer;
+            }
+        }
+
+        // Explicitly drop provider before removing from cache to avoid deadlock
+        drop(jar_provider);
+        static_file_provider.remove_cached_provider(segment, fixed_block_range.end());
+    }
+
+    let checksum = hasher.finish();
+    let elapsed = start_time.elapsed();
+
+    info!(
+        "Checksum for static file segment `{}`: {:#x} ({} entries, elapsed: {:?})",
+        segment, checksum, total, elapsed
+    );
+
+    Ok(())
+}
+
+pub(crate) struct ChecksumViewer<'a, N: NodeTypesWithDB> {
+    tool: &'a DbTool<N>,
+    start_key: Option<String>,
+    end_key: Option<String>,
+    limit: Option<usize>,
+}
+
+impl<N: NodeTypesWithDB> ChecksumViewer<'_, N> {
+    pub(crate) const fn new(tool: &'_ DbTool<N>) -> ChecksumViewer<'_, N> {
+        ChecksumViewer { tool, start_key: None, end_key: None, limit: None }
+    }
+}
+
+impl<N: ProviderNodeTypes> TableViewer<(u64, Duration)> for ChecksumViewer<'_, N> {
+    type Error = eyre::Report;
+
+    fn view<T: Table>(&self) -> Result<(u64, Duration), Self::Error> {
+        let provider =
+            self.tool.provider_factory.provider()?.disable_long_read_transaction_safety();
+        let tx = provider.tx_ref();
+        info!(
+            "Start computing checksum, start={:?}, end={:?}, limit={:?}",
+            self.start_key, self.end_key, self.limit
+        );
+
+        let mut cursor = tx.cursor_read::<RawTable<T>>()?;
+        let walker = match (self.start_key.as_deref(), self.end_key.as_deref()) {
+            (Some(start), Some(end)) => {
+                let start_key = table_key::<T>(start).map(RawKey::new)?;
+                let end_key = table_key::<T>(end).map(RawKey::new)?;
+                cursor.walk_range(start_key..=end_key)?
+            }
+            (None, Some(end)) => {
+                let end_key = table_key::<T>(end).map(RawKey::new)?;
+
+                cursor.walk_range(..=end_key)?
+            }
+            (Some(start), None) => {
+                let start_key = table_key::<T>(start).map(RawKey::new)?;
+                cursor.walk_range(start_key..)?
+            }
+            (None, None) => cursor.walk_range(..)?,
+        };
+
+        let start_time = Instant::now();
+        let mut hasher = checksum_hasher();
+        let mut total = 0;
+
+        let limit = self.limit.unwrap_or(usize::MAX);
+        let mut enumerate_start_key = None;
+        let mut enumerate_end_key = None;
+        for (index, entry) in walker.enumerate() {
+            let (k, v): (RawKey<T::Key>, RawValue<T::Value>) = entry?;
+
+            if index.is_multiple_of(PROGRESS_LOG_INTERVAL) {
+                info!("Hashed {index} entries.");
+            }
+
+            hasher.write(k.raw_key());
+            hasher.write(v.raw_value());
+
+            if enumerate_start_key.is_none() {
+                enumerate_start_key = Some(k.clone());
+            }
+            enumerate_end_key = Some(k);
+
+            total = index + 1;
+            if total >= limit {
+                break
+            }
+        }
+
+        info!("Hashed {total} entries.");
+        if let (Some(s), Some(e)) = (enumerate_start_key, enumerate_end_key) {
+            info!("start-key: {}", serde_json::to_string(&s.key()?).unwrap_or_default());
+            info!("end-key: {}", serde_json::to_string(&e.key()?).unwrap_or_default());
+        }
+
+        let checksum = hasher.finish();
+        let elapsed = start_time.elapsed();
+
+        info!("Checksum for table `{}`: {:#x} (elapsed: {:?})", T::NAME, checksum, elapsed);
+
+        Ok((checksum, elapsed))
+    }
+}

crates/cli/commands/src/db/checksum/rocksdb.rs

@@ -0,0 +1,106 @@
+//! RocksDB checksum implementation.
+
+use super::{checksum_hasher, PROGRESS_LOG_INTERVAL};
+use crate::common::CliNodeTypes;
+use clap::ValueEnum;
+use reth_chainspec::EthereumHardforks;
+use reth_db::{tables, DatabaseEnv};
+use reth_db_api::table::Table;
+use reth_db_common::DbTool;
+use reth_node_builder::NodeTypesWithDBAdapter;
+use reth_provider::RocksDBProviderFactory;
+use std::{hash::Hasher, time::Instant};
+use tracing::info;
+
+/// RocksDB tables that can be checksummed.
+#[derive(Debug, Clone, Copy, ValueEnum)]
+pub enum RocksDbTable {
+    /// Transaction hash to transaction number mapping
+    TransactionHashNumbers,
+    /// Account history indices
+    AccountsHistory,
+    /// Storage history indices
+    StoragesHistory,
+}
+
+impl RocksDbTable {
+    /// Returns the table name as a string
+    const fn name(&self) -> &'static str {
+        match self {
+            Self::TransactionHashNumbers => tables::TransactionHashNumbers::NAME,
+            Self::AccountsHistory => tables::AccountsHistory::NAME,
+            Self::StoragesHistory => tables::StoragesHistory::NAME,
+        }
+    }
+}
+
+/// Computes a checksum for a RocksDB table.
+pub fn checksum_rocksdb<N: CliNodeTypes<ChainSpec: EthereumHardforks>>(
+    tool: &DbTool<NodeTypesWithDBAdapter<N, DatabaseEnv>>,
+    table: RocksDbTable,
+    limit: Option<usize>,
+) -> eyre::Result<()> {
+    let rocksdb = tool.provider_factory.rocksdb_provider();
+
+    let start_time = Instant::now();
+    let limit = limit.unwrap_or(usize::MAX);
+
+    info!(
+        "Computing checksum for RocksDB table `{}`, limit={:?}",
+        table.name(),
+        if limit == usize::MAX { None } else { Some(limit) }
+    );
+
+    let (checksum, total) = match table {
+        RocksDbTable::TransactionHashNumbers => {
+            checksum_rocksdb_table::<tables::TransactionHashNumbers>(&rocksdb, limit)?
+        }
+        RocksDbTable::AccountsHistory => {
+            checksum_rocksdb_table::<tables::AccountsHistory>(&rocksdb, limit)?
+        }
+        RocksDbTable::StoragesHistory => {
+            checksum_rocksdb_table::<tables::StoragesHistory>(&rocksdb, limit)?
+        }
+    };
+
+    let elapsed = start_time.elapsed();
+
+    info!(
+        "Checksum for RocksDB table `{}`: {:#x} ({} entries, elapsed: {:?})",
+        table.name(),
+        checksum,
+        total,
+        elapsed
+    );
+
+    Ok(())
+}
+
+/// Computes checksum for a specific RocksDB table by iterating over rows.
+fn checksum_rocksdb_table<T: Table>(
+    rocksdb: &reth_provider::providers::RocksDBProvider,
+    limit: usize,
+) -> eyre::Result<(u64, usize)> {
+    let iter = rocksdb.raw_iter::<T>()?;
+    let mut hasher = checksum_hasher();
+    let mut total = 0usize;
+
+    for entry in iter {
+        let (key_bytes, value_bytes) = entry?;
+
+        hasher.write(&key_bytes);
+        hasher.write(&value_bytes);
+
+        total += 1;
+
+        if total.is_multiple_of(PROGRESS_LOG_INTERVAL) {
+            info!("Hashed {total} entries.");
+        }
+
+        if total >= limit {
+            break;
+        }
+    }
+
+    Ok((hasher.finish(), total))
+}

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

@@ -16,7 +16,6 @@ use std::{
     hash::Hash,
     io::Write,
     path::{Path, PathBuf},
-    sync::Arc,
 };
 use tracing::{info, warn};
 
@@ -56,7 +55,7 @@ impl Command {
     /// then written to a file in the output directory.
     pub fn execute<T: NodeTypes>(
         self,
-        tool: &DbTool<NodeTypesWithDBAdapter<T, Arc<DatabaseEnv>>>,
+        tool: &DbTool<NodeTypesWithDBAdapter<T, DatabaseEnv>>,
     ) -> eyre::Result<()> {
         warn!("Make sure the node is not running when running `reth db diff`!");
         // open second db

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

@@ -21,6 +21,7 @@ use reth_node_builder::NodeTypesWithDB;
 use reth_primitives_traits::ValueWithSubKey;
 use reth_provider::{providers::ProviderNodeTypes, ChangeSetReader, StaticFileProviderFactory};
 use reth_static_file_types::StaticFileSegment;
+use reth_storage_api::StorageChangeSetReader;
 use tracing::error;
 
 /// The arguments for the `reth db get` command
@@ -82,6 +83,33 @@ impl Command {
                 table.view(&GetValueViewer { tool, key, subkey, end_key, end_subkey, raw })?
             }
             Subcommand::StaticFile { segment, key, subkey, raw } => {
+                if let StaticFileSegment::StorageChangeSets = segment {
+                    let storage_key =
+                        table_subkey::<tables::StorageChangeSets>(subkey.as_deref()).ok();
+                    let key = table_key::<tables::StorageChangeSets>(&key)?;
+
+                    let provider = tool.provider_factory.static_file_provider();
+
+                    if let Some(storage_key) = storage_key {
+                        let entry = provider.get_storage_before_block(
+                            key.block_number(),
+                            key.address(),
+                            storage_key,
+                        )?;
+
+                        if let Some(entry) = entry {
+                            println!("{}", serde_json::to_string_pretty(&entry)?);
+                        } else {
+                            error!(target: "reth::cli", "No content for the given table key.");
+                        }
+                        return Ok(());
+                    }
+
+                    let changesets = provider.storage_changeset(key.block_number())?;
+                    println!("{}", serde_json::to_string_pretty(&changesets)?);
+                    return Ok(());
+                }
+
                 let (key, subkey, mask): (u64, _, _) = match segment {
                     StaticFileSegment::Headers => (
                         table_key::<tables::Headers>(&key)?,
@@ -112,6 +140,9 @@ impl Command {
                             AccountChangesetMask::MASK,
                         )
                     }
+                    StaticFileSegment::StorageChangeSets => {
+                        unreachable!("storage changesets handled above");
+                    }
                 };
 
                 // handle account changesets differently if a subkey is provided.
@@ -190,6 +221,9 @@ impl Command {
                                 StaticFileSegment::AccountChangeSets => {
                                     unreachable!("account changeset static files are special cased before this match")
                                 }
+                                StaticFileSegment::StorageChangeSets => {
+                                    unreachable!("storage changeset static files are special cased before this match")
+                                }
                             }
                         }
                     }

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

@@ -7,7 +7,7 @@ use reth_db::{transaction::DbTx, DatabaseEnv};
 use reth_db_api::{database::Database, table::Table, RawValue, TableViewer, Tables};
 use reth_db_common::{DbTool, ListFilter};
 use reth_node_builder::{NodeTypes, NodeTypesWithDBAdapter};
-use std::{cell::RefCell, sync::Arc};
+use std::cell::RefCell;
 use tracing::error;
 
 #[derive(Parser, Debug)]
@@ -55,25 +55,27 @@ impl Command {
     /// Execute `db list` command
     pub fn execute<N: NodeTypes<ChainSpec: EthereumHardforks>>(
         self,
-        tool: &DbTool<NodeTypesWithDBAdapter<N, Arc<DatabaseEnv>>>,
+        tool: &DbTool<NodeTypesWithDBAdapter<N, DatabaseEnv>>,
     ) -> eyre::Result<()> {
         self.table.view(&ListTableViewer { tool, args: &self })
     }
 
     /// Generate [`ListFilter`] from command.
-    pub fn list_filter(&self) -> ListFilter {
-        let search = self
-            .search
-            .as_ref()
-            .map(|search| {
+    pub fn list_filter(&self) -> eyre::Result<ListFilter> {
+        let search = match self.search.as_deref() {
+            Some(search) => {
                 if let Some(search) = search.strip_prefix("0x") {
-                    return hex::decode(search).unwrap()
+                    hex::decode(search).wrap_err(
+                        "Invalid hex content after 0x prefix in --search (expected valid hex like 0xdeadbeef).",
+                    )?
+                } else {
+                    search.as_bytes().to_vec()
                 }
-                search.as_bytes().to_vec()
-            })
-            .unwrap_or_default();
+            }
+            None => Vec::new(),
+        };
 
-        ListFilter {
+        Ok(ListFilter {
             skip: self.skip,
             len: self.len,
             search,
@@ -82,12 +84,12 @@ impl Command {
             min_value_size: self.min_value_size,
             reverse: self.reverse,
             only_count: self.count,
-        }
+        })
     }
 }
 
 struct ListTableViewer<'a, N: NodeTypes> {
-    tool: &'a DbTool<NodeTypesWithDBAdapter<N, Arc<DatabaseEnv>>>,
+    tool: &'a DbTool<NodeTypesWithDBAdapter<N, DatabaseEnv>>,
     args: &'a Command,
 }
 
@@ -99,8 +101,8 @@ impl<N: NodeTypes> TableViewer<()> for ListTableViewer<'_, N> {
             // We may be using the tui for a long time
             tx.disable_long_read_transaction_safety();
 
-            let table_db = tx.inner.open_db(Some(self.args.table.name())).wrap_err("Could not open db.")?;
-            let stats = tx.inner.db_stat(table_db.dbi()).wrap_err(format!("Could not find table: {}", self.args.table.name()))?;
+            let table_db = tx.inner().open_db(Some(self.args.table.name())).wrap_err("Could not open db.")?;
+                    let stats = tx.inner().db_stat(table_db.dbi()).wrap_err(format!("Could not find table: {}", self.args.table.name()))?;
             let total_entries = stats.entries();
             let final_entry_idx = total_entries.saturating_sub(1);
             if self.args.skip > final_entry_idx {
@@ -115,7 +117,7 @@ impl<N: NodeTypes> TableViewer<()> for ListTableViewer<'_, N> {
             }
 
 
-            let list_filter = self.args.list_filter();
+            let list_filter = self.args.list_filter()?;
 
             if self.args.json || self.args.count {
                 let (list, count) = self.tool.list::<T>(&list_filter)?;

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

@@ -17,6 +17,7 @@ mod get;
 mod list;
 mod repair_trie;
 mod settings;
+mod state;
 mod static_file_header;
 mod stats;
 /// DB List TUI
@@ -39,7 +40,7 @@ pub enum Subcommands {
     Stats(stats::Command),
     /// Lists the contents of a table
     List(list::Command),
-    /// Calculates the content checksum of a table
+    /// Calculates the content checksum of a table or static file segment
     Checksum(checksum::Command),
     /// Create a diff between two database tables or two entire databases.
     Diff(diff::Command),
@@ -65,6 +66,8 @@ pub enum Subcommands {
     Settings(settings::Command),
     /// Gets storage size information for an account
     AccountStorage(account_storage::Command),
+    /// Gets account state and storage at a specific block
+    State(state::Command),
 }
 
 /// Initializes a provider factory with specified access rights, and then execute with the provided
@@ -162,7 +165,7 @@ impl<C: ChainSpecParser<ChainSpec: EthChainSpec + EthereumHardforks>> Command<C>
                 let access_rights =
                     if command.dry_run { AccessRights::RO } else { AccessRights::RW };
                 db_exec!(self.env, tool, N, access_rights, {
-                    command.execute(&tool, ctx.task_executor.clone(), &data_dir)?;
+                    command.execute(&tool, ctx.task_executor, &data_dir)?;
                 });
             }
             Subcommands::StaticFileHeader(command) => {
@@ -198,6 +201,11 @@ impl<C: ChainSpecParser<ChainSpec: EthChainSpec + EthereumHardforks>> Command<C>
                     command.execute(&tool)?;
                 });
             }
+            Subcommands::State(command) => {
+                db_exec!(self.env, tool, N, AccessRights::RO, {
+                    command.execute(&tool)?;
+                });
+            }
         }
 
         Ok(())

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

@@ -69,6 +69,11 @@ pub enum SetCommand {
         #[clap(action(ArgAction::Set))]
         value: bool,
     },
+    /// Store storage changesets in static files instead of the database
+    StorageChangesets {
+        #[clap(action(ArgAction::Set))]
+        value: bool,
+    },
 }
 
 impl Command {
@@ -115,6 +120,7 @@ impl Command {
             transaction_hash_numbers_in_rocksdb: _,
             account_history_in_rocksdb: _,
             account_changesets_in_static_files: _,
+            storage_changesets_in_static_files: _,
         } = settings.unwrap_or_else(StorageSettings::legacy);
 
         // Update the setting based on the key
@@ -167,6 +173,14 @@ impl Command {
                 settings.account_history_in_rocksdb = value;
                 println!("Set account_history_in_rocksdb = {}", value);
             }
+            SetCommand::StorageChangesets { value } => {
+                if settings.storage_changesets_in_static_files == value {
+                    println!("storage_changesets_in_static_files is already set to {}", value);
+                    return Ok(());
+                }
+                settings.storage_changesets_in_static_files = value;
+                println!("Set storage_changesets_in_static_files = {}", value);
+            }
         }
 
         // Write updated settings

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

@@ -0,0 +1,412 @@
+use alloy_primitives::{Address, BlockNumber, B256, U256};
+use clap::Parser;
+use parking_lot::Mutex;
+use reth_db_api::{
+    cursor::{DbCursorRO, DbDupCursorRO},
+    database::Database,
+    tables,
+    transaction::DbTx,
+};
+use reth_db_common::DbTool;
+use reth_node_builder::NodeTypesWithDB;
+use reth_provider::providers::ProviderNodeTypes;
+use reth_storage_api::{BlockNumReader, StateProvider, StorageSettingsCache};
+use std::{
+    collections::BTreeSet,
+    thread,
+    time::{Duration, Instant},
+};
+use tracing::{error, info};
+
+/// Log progress every 5 seconds
+const LOG_INTERVAL: Duration = Duration::from_secs(30);
+
+/// The arguments for the `reth db state` command
+#[derive(Parser, Debug)]
+pub struct Command {
+    /// The account address to get state for
+    address: Address,
+
+    /// Block number to query state at (uses current state if not provided)
+    #[arg(long, short)]
+    block: Option<BlockNumber>,
+
+    /// Maximum number of storage slots to display
+    #[arg(long, short, default_value = "100")]
+    limit: usize,
+
+    /// Output format (table, json, csv)
+    #[arg(long, short, default_value = "table")]
+    format: OutputFormat,
+}
+
+impl Command {
+    /// Execute `db state` command
+    pub fn execute<N: NodeTypesWithDB + ProviderNodeTypes>(
+        self,
+        tool: &DbTool<N>,
+    ) -> eyre::Result<()> {
+        let address = self.address;
+        let limit = self.limit;
+
+        if let Some(block) = self.block {
+            self.execute_historical(tool, address, block, limit)
+        } else {
+            self.execute_current(tool, address, limit)
+        }
+    }
+
+    fn execute_current<N: NodeTypesWithDB + ProviderNodeTypes>(
+        &self,
+        tool: &DbTool<N>,
+        address: Address,
+        limit: usize,
+    ) -> eyre::Result<()> {
+        let entries = tool.provider_factory.db_ref().view(|tx| {
+            // Get account info
+            let account = tx.get::<tables::PlainAccountState>(address)?;
+
+            // Get storage entries
+            let mut cursor = tx.cursor_dup_read::<tables::PlainStorageState>()?;
+            let mut entries = Vec::new();
+            let mut last_log = Instant::now();
+
+            let walker = cursor.walk_dup(Some(address), None)?;
+            for (idx, entry) in walker.enumerate() {
+                let (_, storage_entry) = entry?;
+
+                if storage_entry.value != U256::ZERO {
+                    entries.push((storage_entry.key, storage_entry.value));
+                }
+
+                if entries.len() >= limit {
+                    break;
+                }
+
+                if last_log.elapsed() >= LOG_INTERVAL {
+                    info!(
+                        target: "reth::cli",
+                        address = %address,
+                        slots_scanned = idx,
+                        "Scanning storage slots"
+                    );
+                    last_log = Instant::now();
+                }
+            }
+
+            Ok::<_, eyre::Report>((account, entries))
+        })??;
+
+        let (account, storage_entries) = entries;
+
+        self.print_results(address, None, account, &storage_entries);
+
+        Ok(())
+    }
+
+    fn execute_historical<N: NodeTypesWithDB + ProviderNodeTypes>(
+        &self,
+        tool: &DbTool<N>,
+        address: Address,
+        block: BlockNumber,
+        limit: usize,
+    ) -> eyre::Result<()> {
+        let provider = tool.provider_factory.history_by_block_number(block)?;
+
+        // Get account info at that block
+        let account = provider.basic_account(&address)?;
+
+        // Check storage settings to determine where history is stored
+        let storage_settings = tool.provider_factory.cached_storage_settings();
+        let history_in_rocksdb = storage_settings.storages_history_in_rocksdb;
+
+        // For historical queries, enumerate keys from history indices only
+        // (not PlainStorageState, which reflects current state)
+        let mut storage_keys = BTreeSet::new();
+
+        if history_in_rocksdb {
+            error!(
+                target: "reth::cli",
+                "Historical storage queries with RocksDB backend are not yet supported. \
+                 Use MDBX for storage history or query current state without --block."
+            );
+            return Ok(());
+        }
+
+        // Collect keys from MDBX StorageChangeSets using parallel scanning
+        self.collect_mdbx_storage_keys_parallel(tool, address, &mut storage_keys)?;
+
+        info!(
+            target: "reth::cli",
+            address = %address,
+            block = block,
+            total_keys = storage_keys.len(),
+            "Found storage keys to query"
+        );
+
+        // Now query each key at the historical block using the StateProvider
+        // This handles both MDBX and RocksDB backends transparently
+        let mut entries = Vec::new();
+        let mut last_log = Instant::now();
+
+        for (idx, key) in storage_keys.iter().enumerate() {
+            match provider.storage(address, *key) {
+                Ok(Some(value)) if value != U256::ZERO => {
+                    entries.push((*key, value));
+                }
+                _ => {}
+            }
+
+            if entries.len() >= limit {
+                break;
+            }
+
+            if last_log.elapsed() >= LOG_INTERVAL {
+                info!(
+                    target: "reth::cli",
+                    address = %address,
+                    block = block,
+                    keys_total = storage_keys.len(),
+                    slots_scanned = idx,
+                    slots_found = entries.len(),
+                    "Scanning historical storage slots"
+                );
+                last_log = Instant::now();
+            }
+        }
+
+        self.print_results(address, Some(block), account, &entries);
+
+        Ok(())
+    }
+
+    /// Collects storage keys from MDBX StorageChangeSets using parallel block range scanning.
+    fn collect_mdbx_storage_keys_parallel<N: NodeTypesWithDB + ProviderNodeTypes>(
+        &self,
+        tool: &DbTool<N>,
+        address: Address,
+        keys: &mut BTreeSet<B256>,
+    ) -> eyre::Result<()> {
+        const CHUNK_SIZE: u64 = 500_000; // 500k blocks per thread
+        let num_threads = std::thread::available_parallelism()
+            .map(|p| p.get().saturating_sub(1).max(1))
+            .unwrap_or(4);
+
+        // Get the current tip block
+        let tip = tool.provider_factory.provider()?.best_block_number()?;
+
+        if tip == 0 {
+            return Ok(());
+        }
+
+        info!(
+            target: "reth::cli",
+            address = %address,
+            tip,
+            chunk_size = CHUNK_SIZE,
+            num_threads,
+            "Starting parallel MDBX changeset scan"
+        );
+
+        // Shared state for collecting keys
+        let collected_keys: Mutex<BTreeSet<B256>> = Mutex::new(BTreeSet::new());
+        let total_entries_scanned = Mutex::new(0usize);
+
+        // Create chunk ranges
+        let mut chunks: Vec<(u64, u64)> = Vec::new();
+        let mut start = 0u64;
+        while start <= tip {
+            let end = (start + CHUNK_SIZE - 1).min(tip);
+            chunks.push((start, end));
+            start = end + 1;
+        }
+
+        let chunks_ref = &chunks;
+        let next_chunk = Mutex::new(0usize);
+        let next_chunk_ref = &next_chunk;
+        let collected_keys_ref = &collected_keys;
+        let total_entries_ref = &total_entries_scanned;
+
+        thread::scope(|s| {
+            let handles: Vec<_> = (0..num_threads)
+                .map(|thread_id| {
+                    s.spawn(move || {
+                        loop {
+                            // Get next chunk to process
+                            let chunk_idx = {
+                                let mut idx = next_chunk_ref.lock();
+                                if *idx >= chunks_ref.len() {
+                                    return Ok::<_, eyre::Report>(());
+                                }
+                                let current = *idx;
+                                *idx += 1;
+                                current
+                            };
+
+                            let (chunk_start, chunk_end) = chunks_ref[chunk_idx];
+
+                            // Open a new read transaction for this chunk
+                            tool.provider_factory.db_ref().view(|tx| {
+                                tx.disable_long_read_transaction_safety();
+
+                                let mut changeset_cursor =
+                                    tx.cursor_read::<tables::StorageChangeSets>()?;
+                                let start_key =
+                                    reth_db_api::models::BlockNumberAddress((chunk_start, address));
+                                let end_key =
+                                    reth_db_api::models::BlockNumberAddress((chunk_end, address));
+
+                                let mut local_keys = BTreeSet::new();
+                                let mut entries_in_chunk = 0usize;
+
+                                if let Ok(walker) = changeset_cursor.walk_range(start_key..=end_key)
+                                {
+                                    for (block_addr, storage_entry) in walker.flatten() {
+                                        if block_addr.address() == address {
+                                            local_keys.insert(storage_entry.key);
+                                        }
+                                        entries_in_chunk += 1;
+                                    }
+                                }
+
+                                // Merge into global state
+                                collected_keys_ref.lock().extend(local_keys);
+                                *total_entries_ref.lock() += entries_in_chunk;
+
+                                info!(
+                                    target: "reth::cli",
+                                    thread_id,
+                                    chunk_start,
+                                    chunk_end,
+                                    entries_in_chunk,
+                                    "Thread completed chunk"
+                                );
+
+                                Ok::<_, eyre::Report>(())
+                            })??;
+                        }
+                    })
+                })
+                .collect();
+
+            for handle in handles {
+                handle.join().map_err(|_| eyre::eyre!("Thread panicked"))??;
+            }
+
+            Ok::<_, eyre::Report>(())
+        })?;
+
+        let final_keys = collected_keys.into_inner();
+        let total = *total_entries_scanned.lock();
+
+        info!(
+            target: "reth::cli",
+            address = %address,
+            total_entries = total,
+            unique_keys = final_keys.len(),
+            "Finished parallel MDBX changeset scan"
+        );
+
+        keys.extend(final_keys);
+        Ok(())
+    }
+
+    fn print_results(
+        &self,
+        address: Address,
+        block: Option<BlockNumber>,
+        account: Option<reth_primitives_traits::Account>,
+        storage: &[(alloy_primitives::B256, U256)],
+    ) {
+        match self.format {
+            OutputFormat::Table => {
+                println!("Account: {address}");
+                if let Some(b) = block {
+                    println!("Block: {b}");
+                } else {
+                    println!("Block: latest");
+                }
+                println!();
+
+                if let Some(acc) = account {
+                    println!("Nonce: {}", acc.nonce);
+                    println!("Balance: {} wei", acc.balance);
+                    if let Some(code_hash) = acc.bytecode_hash {
+                        println!("Code hash: {code_hash}");
+                    }
+                } else {
+                    println!("Account not found");
+                }
+
+                println!();
+                println!("Storage ({} slots):", storage.len());
+                println!("{:-<130}", "");
+                println!("{:<66} | {:<64}", "Slot", "Value");
+                println!("{:-<130}", "");
+                for (key, value) in storage {
+                    println!("{key} | {value:#066x}");
+                }
+            }
+            OutputFormat::Json => {
+                let output = serde_json::json!({
+                    "address": address.to_string(),
+                    "block": block,
+                    "account": account.map(|a| serde_json::json!({
+                        "nonce": a.nonce,
+                        "balance": a.balance.to_string(),
+                        "code_hash": a.bytecode_hash.map(|h| h.to_string()),
+                    })),
+                    "storage": storage.iter().map(|(k, v)| {
+                        serde_json::json!({
+                            "key": k.to_string(),
+                            "value": format!("{v:#066x}"),
+                        })
+                    }).collect::<Vec<_>>(),
+                });
+                println!("{}", serde_json::to_string_pretty(&output).unwrap());
+            }
+            OutputFormat::Csv => {
+                println!("slot,value");
+                for (key, value) in storage {
+                    println!("{key},{value:#066x}");
+                }
+            }
+        }
+    }
+}
+
+#[derive(Debug, Clone, Default, clap::ValueEnum)]
+pub enum OutputFormat {
+    #[default]
+    Table,
+    Json,
+    Csv,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_state_args() {
+        let cmd = Command::try_parse_from([
+            "state",
+            "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+            "--block",
+            "1000000",
+        ])
+        .unwrap();
+        assert_eq!(
+            cmd.address,
+            "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045".parse::<Address>().unwrap()
+        );
+        assert_eq!(cmd.block, Some(1000000));
+    }
+
+    #[test]
+    fn parse_state_args_no_block() {
+        let cmd = Command::try_parse_from(["state", "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"])
+            .unwrap();
+        assert_eq!(cmd.block, None);
+    }
+}

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

@@ -11,9 +11,12 @@ use reth_db_common::DbTool;
 use reth_fs_util as fs;
 use reth_node_builder::{NodePrimitives, NodeTypesWithDB, NodeTypesWithDBAdapter};
 use reth_node_core::dirs::{ChainPath, DataDirPath};
-use reth_provider::providers::{ProviderNodeTypes, StaticFileProvider};
+use reth_provider::{
+    providers::{ProviderNodeTypes, StaticFileProvider},
+    RocksDBProviderFactory,
+};
 use reth_static_file_types::SegmentRangeInclusive;
-use std::{sync::Arc, time::Duration};
+use std::time::Duration;
 
 #[derive(Parser, Debug)]
 /// The arguments for the `reth db stats` command
@@ -45,7 +48,7 @@ impl Command {
     pub fn execute<N: CliNodeTypes<ChainSpec: EthereumHardforks>>(
         self,
         data_dir: ChainPath<DataDirPath>,
-        tool: &DbTool<NodeTypesWithDBAdapter<N, Arc<DatabaseEnv>>>,
+        tool: &DbTool<NodeTypesWithDBAdapter<N, DatabaseEnv>>,
     ) -> eyre::Result<()> {
         if self.checksum {
             let checksum_report = self.checksum_report(tool)?;
@@ -61,10 +64,15 @@ impl Command {
         let db_stats_table = self.db_stats_table(tool)?;
         println!("{db_stats_table}");
 
+        println!("\n");
+
+        let rocksdb_stats_table = self.rocksdb_stats_table(tool);
+        println!("{rocksdb_stats_table}");
+
         Ok(())
     }
 
-    fn db_stats_table<N: NodeTypesWithDB<DB = Arc<DatabaseEnv>>>(
+    fn db_stats_table<N: NodeTypesWithDB<DB = DatabaseEnv>>(
         &self,
         tool: &DbTool<N>,
     ) -> eyre::Result<ComfyTable> {
@@ -84,10 +92,10 @@ impl Command {
             db_tables.sort();
             let mut total_size = 0;
             for db_table in db_tables {
-                let table_db = tx.inner.open_db(Some(db_table)).wrap_err("Could not open db.")?;
+                let table_db = tx.inner().open_db(Some(db_table)).wrap_err("Could not open db.")?;
 
                 let stats = tx
-                    .inner
+                    .inner()
                     .db_stat(table_db.dbi())
                     .wrap_err(format!("Could not find table: {db_table}"))?;
 
@@ -128,9 +136,9 @@ impl Command {
                 .add_cell(Cell::new(human_bytes(total_size as f64)));
             table.add_row(row);
 
-            let freelist = tx.inner.env().freelist()?;
+            let freelist = tx.inner().env().freelist()?;
             let pagesize =
-                tx.inner.db_stat(mdbx::Database::freelist_db().dbi())?.page_size() as usize;
+                tx.inner().db_stat(mdbx::Database::freelist_db().dbi())?.page_size() as usize;
             let freelist_size = freelist * pagesize;
 
             let mut row = Row::new();
@@ -148,6 +156,70 @@ impl Command {
         Ok(table)
     }
 
+    fn rocksdb_stats_table<N: NodeTypesWithDB>(&self, tool: &DbTool<N>) -> ComfyTable {
+        let mut table = ComfyTable::new();
+        table.load_preset(comfy_table::presets::ASCII_MARKDOWN);
+        table.set_header([
+            "RocksDB Table Name",
+            "# Entries",
+            "SST Size",
+            "Memtable Size",
+            "Total Size",
+            "Pending Compaction",
+        ]);
+
+        let stats = tool.provider_factory.rocksdb_provider().table_stats();
+        let mut total_sst: u64 = 0;
+        let mut total_memtable: u64 = 0;
+        let mut total_size: u64 = 0;
+        let mut total_pending: u64 = 0;
+
+        for stat in &stats {
+            total_sst += stat.sst_size_bytes;
+            total_memtable += stat.memtable_size_bytes;
+            total_size += stat.estimated_size_bytes;
+            total_pending += stat.pending_compaction_bytes;
+            let mut row = Row::new();
+            row.add_cell(Cell::new(&stat.name))
+                .add_cell(Cell::new(stat.estimated_num_keys))
+                .add_cell(Cell::new(human_bytes(stat.sst_size_bytes as f64)))
+                .add_cell(Cell::new(human_bytes(stat.memtable_size_bytes as f64)))
+                .add_cell(Cell::new(human_bytes(stat.estimated_size_bytes as f64)))
+                .add_cell(Cell::new(human_bytes(stat.pending_compaction_bytes as f64)));
+            table.add_row(row);
+        }
+
+        if !stats.is_empty() {
+            let max_widths = table.column_max_content_widths();
+            let mut separator = Row::new();
+            for width in max_widths {
+                separator.add_cell(Cell::new("-".repeat(width as usize)));
+            }
+            table.add_row(separator);
+
+            let mut row = Row::new();
+            row.add_cell(Cell::new("RocksDB Total"))
+                .add_cell(Cell::new(""))
+                .add_cell(Cell::new(human_bytes(total_sst as f64)))
+                .add_cell(Cell::new(human_bytes(total_memtable as f64)))
+                .add_cell(Cell::new(human_bytes(total_size as f64)))
+                .add_cell(Cell::new(human_bytes(total_pending as f64)));
+            table.add_row(row);
+
+            let wal_size = tool.provider_factory.rocksdb_provider().wal_size_bytes();
+            let mut row = Row::new();
+            row.add_cell(Cell::new("WAL"))
+                .add_cell(Cell::new(""))
+                .add_cell(Cell::new(""))
+                .add_cell(Cell::new(""))
+                .add_cell(Cell::new(human_bytes(wal_size as f64)))
+                .add_cell(Cell::new(""));
+            table.add_row(row);
+        }
+
+        table
+    }
+
     fn static_files_stats_table<N: NodePrimitives>(
         &self,
         data_dir: ChainPath<DataDirPath>,

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

@@ -227,8 +227,9 @@ where
 
         // Handle errors
         if let Err(err) = res {
-            error!("{:?}", err)
+            error!("{err}");
         }
+
         Ok(())
     }
 }
@@ -241,6 +242,7 @@ fn event_loop<B: Backend, F, T: Table>(
 ) -> io::Result<()>
 where
     F: FnMut(usize, usize) -> Vec<TableRow<T>>,
+    io::Error: From<B::Error>,
 {
     let mut last_tick = Instant::now();
     let mut running = true;

crates/cli/commands/src/import.rs

@@ -26,6 +26,14 @@ pub struct ImportCommand<C: ChainSpecParser> {
     #[arg(long, value_name = "CHUNK_LEN", verbatim_doc_comment)]
     chunk_len: Option<u64>,
 
+    /// Fail immediately when an invalid block is encountered.
+    ///
+    /// By default, the import will stop at the last valid block if an invalid block is
+    /// encountered during execution or validation, leaving the database at the last valid
+    /// block state. When this flag is set, the import will instead fail with an error.
+    #[arg(long, verbatim_doc_comment)]
+    fail_on_invalid_block: bool,
+
     /// The path(s) to block file(s) for import.
     ///
     /// The online stages (headers and bodies) are replaced by a file import, after which the
@@ -52,7 +60,11 @@ impl<C: ChainSpecParser<ChainSpec: EthChainSpec + EthereumHardforks>> ImportComm
 
         info!(target: "reth::cli", "Starting import of {} file(s)", self.paths.len());
 
-        let import_config = ImportConfig { no_state: self.no_state, chunk_len: self.chunk_len };
+        let import_config = ImportConfig {
+            no_state: self.no_state,
+            chunk_len: self.chunk_len,
+            fail_on_invalid_block: self.fail_on_invalid_block,
+        };
 
         let executor = components.evm_config().clone();
         let consensus = Arc::new(components.consensus().clone());
@@ -81,7 +93,20 @@ impl<C: ChainSpecParser<ChainSpec: EthChainSpec + EthereumHardforks>> ImportComm
             total_decoded_blocks += result.total_decoded_blocks;
             total_decoded_txns += result.total_decoded_txns;
 
-            if !result.is_complete() {
+            // Check if we stopped due to an invalid block
+            if result.stopped_on_invalid_block {
+                info!(target: "reth::cli",
+                      "Stopped at last valid block {} due to invalid block {} in file: {}. Imported {} blocks, {} transactions",
+                      result.last_valid_block.unwrap_or(0),
+                      result.bad_block.unwrap_or(0),
+                      path.display(),
+                      result.total_imported_blocks,
+                      result.total_imported_txns);
+                // Stop importing further files and exit successfully
+                break;
+            }
+
+            if !result.is_successful() {
                 return Err(eyre::eyre!(
                     "Chain was partially imported from file: {}. Imported {}/{} blocks, {}/{} transactions",
                     path.display(),
@@ -98,7 +123,7 @@ impl<C: ChainSpecParser<ChainSpec: EthChainSpec + EthereumHardforks>> ImportComm
         }
 
         info!(target: "reth::cli",
-              "All files imported successfully. Total: {}/{} blocks, {}/{} transactions",
+              "Import complete. Total: {}/{} blocks, {}/{} transactions",
               total_imported_blocks, total_decoded_blocks, total_imported_txns, total_decoded_txns);
 
         Ok(())
@@ -139,4 +164,20 @@ mod tests {
         assert_eq!(args.paths[1], PathBuf::from("file2.rlp"));
         assert_eq!(args.paths[2], PathBuf::from("file3.rlp"));
     }
+
+    #[test]
+    fn parse_import_command_with_fail_on_invalid_block() {
+        let args: ImportCommand<EthereumChainSpecParser> =
+            ImportCommand::parse_from(["reth", "--fail-on-invalid-block", "chain.rlp"]);
+        assert!(args.fail_on_invalid_block);
+        assert_eq!(args.paths.len(), 1);
+        assert_eq!(args.paths[0], PathBuf::from("chain.rlp"));
+    }
+
+    #[test]
+    fn parse_import_command_default_stops_on_invalid_block() {
+        let args: ImportCommand<EthereumChainSpecParser> =
+            ImportCommand::parse_from(["reth", "chain.rlp"]);
+        assert!(!args.fail_on_invalid_block);
+    }
 }

crates/cli/commands/src/import_core.rs

@@ -22,11 +22,11 @@ use reth_provider::{
     StageCheckpointReader,
 };
 use reth_prune::PruneModes;
-use reth_stages::{prelude::*, Pipeline, StageId, StageSet};
+use reth_stages::{prelude::*, ControlFlow, Pipeline, StageId, StageSet};
 use reth_static_file::StaticFileProducer;
 use std::{path::Path, sync::Arc};
 use tokio::sync::watch;
-use tracing::{debug, error, info};
+use tracing::{debug, error, info, warn};
 
 /// Configuration for importing blocks from RLP files.
 #[derive(Debug, Clone, Default)]
@@ -35,6 +35,9 @@ pub struct ImportConfig {
     pub no_state: bool,
     /// Chunk byte length to read from file.
     pub chunk_len: Option<u64>,
+    /// If true, fail immediately when an invalid block is encountered.
+    /// By default (false), the import stops at the last valid block and exits successfully.
+    pub fail_on_invalid_block: bool,
 }
 
 /// Result of an import operation.
@@ -48,6 +51,12 @@ pub struct ImportResult {
     pub total_imported_blocks: usize,
     /// Total number of transactions imported into the database.
     pub total_imported_txns: usize,
+    /// Whether the import was stopped due to an invalid block.
+    pub stopped_on_invalid_block: bool,
+    /// The block number that was invalid, if any.
+    pub bad_block: Option<u64>,
+    /// The last valid block number when stopped due to invalid block.
+    pub last_valid_block: Option<u64>,
 }
 
 impl ImportResult {
@@ -56,6 +65,14 @@ impl ImportResult {
         self.total_decoded_blocks == self.total_imported_blocks &&
             self.total_decoded_txns == self.total_imported_txns
     }
+
+    /// Returns true if the import was successful, considering stop-on-invalid-block mode.
+    ///
+    /// In stop-on-invalid-block mode, a partial import is considered successful if we
+    /// stopped due to an invalid block (leaving the DB at the last valid block).
+    pub fn is_successful(&self) -> bool {
+        self.is_complete() || self.stopped_on_invalid_block
+    }
 }
 
 /// Imports blocks from an RLP-encoded file into the database.
@@ -103,6 +120,11 @@ where
     let static_file_producer =
         StaticFileProducer::new(provider_factory.clone(), PruneModes::default());
 
+    // Track if we stopped due to an invalid block
+    let mut stopped_on_invalid_block = false;
+    let mut bad_block_number: Option<u64> = None;
+    let mut last_valid_block_number: Option<u64> = None;
+
     while let Some(file_client) =
         reader.next_chunk::<BlockTy<N>>(consensus.clone(), Some(sealed_header)).await?
     {
@@ -137,12 +159,51 @@ where
 
         // Run pipeline
         info!(target: "reth::import", "Starting sync pipeline");
-        tokio::select! {
-            res = pipeline.run() => res?,
-            _ = tokio::signal::ctrl_c() => {
-                info!(target: "reth::import", "Import interrupted by user");
-                break;
-            },
+        if import_config.fail_on_invalid_block {
+            // Original behavior: fail on unwind
+            tokio::select! {
+                res = pipeline.run() => res?,
+                _ = tokio::signal::ctrl_c() => {
+                    info!(target: "reth::import", "Import interrupted by user");
+                    break;
+                },
+            }
+        } else {
+            // Default behavior: Use run_loop() to handle unwinds gracefully
+            let result = tokio::select! {
+                res = pipeline.run_loop() => res,
+                _ = tokio::signal::ctrl_c() => {
+                    info!(target: "reth::import", "Import interrupted by user");
+                    break;
+                },
+            };
+
+            match result {
+                Ok(ControlFlow::Unwind { target, bad_block }) => {
+                    // An invalid block was encountered; stop at last valid block
+                    let bad = bad_block.block.number;
+                    warn!(
+                        target: "reth::import",
+                        bad_block = bad,
+                        last_valid_block = target,
+                        "Invalid block encountered during import; stopping at last valid block"
+                    );
+                    stopped_on_invalid_block = true;
+                    bad_block_number = Some(bad);
+                    last_valid_block_number = Some(target);
+                    break;
+                }
+                Ok(ControlFlow::Continue { block_number }) => {
+                    debug!(target: "reth::import", block_number, "Pipeline chunk completed");
+                }
+                Ok(ControlFlow::NoProgress { block_number }) => {
+                    debug!(target: "reth::import", ?block_number, "Pipeline made no progress");
+                }
+                Err(e) => {
+                    // Propagate other pipeline errors
+                    return Err(e.into());
+                }
+            }
         }
 
         sealed_header = provider_factory
@@ -160,9 +221,20 @@ where
         total_decoded_txns,
         total_imported_blocks,
         total_imported_txns,
+        stopped_on_invalid_block,
+        bad_block: bad_block_number,
+        last_valid_block: last_valid_block_number,
     };
 
-    if !result.is_complete() {
+    if result.stopped_on_invalid_block {
+        info!(target: "reth::import",
+            total_imported_blocks,
+            total_imported_txns,
+            bad_block = ?result.bad_block,
+            last_valid_block = ?result.last_valid_block,
+            "Import stopped at last valid block due to invalid block"
+        );
+    } else if !result.is_complete() {
         error!(target: "reth::import",
             total_decoded_blocks,
             total_imported_blocks,

crates/cli/commands/src/launcher.rs

@@ -2,7 +2,7 @@ use futures::Future;
 use reth_cli::chainspec::ChainSpecParser;
 use reth_db::DatabaseEnv;
 use reth_node_builder::{NodeBuilder, WithLaunchContext};
-use std::{fmt, sync::Arc};
+use std::fmt;
 
 /// A trait for launching a reth node with custom configuration strategies.
 ///
@@ -30,7 +30,7 @@ where
     /// * `builder_args` - Extension arguments for configuration
     fn entrypoint(
         self,
-        builder: WithLaunchContext<NodeBuilder<Arc<DatabaseEnv>, C::ChainSpec>>,
+        builder: WithLaunchContext<NodeBuilder<DatabaseEnv, C::ChainSpec>>,
         builder_args: Ext,
     ) -> impl Future<Output = eyre::Result<()>>;
 }
@@ -58,7 +58,7 @@ impl<F> FnLauncher<F> {
     where
         C: ChainSpecParser,
         F: AsyncFnOnce(
-            WithLaunchContext<NodeBuilder<Arc<DatabaseEnv>, C::ChainSpec>>,
+            WithLaunchContext<NodeBuilder<DatabaseEnv, C::ChainSpec>>,
             Ext,
         ) -> eyre::Result<()>,
     {
@@ -77,13 +77,13 @@ where
     C: ChainSpecParser,
     Ext: clap::Args + fmt::Debug,
     F: AsyncFnOnce(
-        WithLaunchContext<NodeBuilder<Arc<DatabaseEnv>, C::ChainSpec>>,
+        WithLaunchContext<NodeBuilder<DatabaseEnv, C::ChainSpec>>,
         Ext,
     ) -> eyre::Result<()>,
 {
     fn entrypoint(
         self,
-        builder: WithLaunchContext<NodeBuilder<Arc<DatabaseEnv>, C::ChainSpec>>,
+        builder: WithLaunchContext<NodeBuilder<DatabaseEnv, C::ChainSpec>>,
         builder_args: Ext,
     ) -> impl Future<Output = eyre::Result<()>> {
         (self.func)(builder, builder_args)

crates/cli/commands/src/node.rs

@@ -10,7 +10,8 @@ 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, RocksDbArgs, RpcServerArgs, StaticFilesArgs,
+        TxPoolArgs,
     },
     node_config::NodeConfig,
     version,
@@ -102,6 +103,10 @@ pub struct NodeCommand<C: ChainSpecParser, Ext: clap::Args + fmt::Debug = NoArgs
     #[command(flatten)]
     pub pruning: PruningArgs,
 
+    /// All `RocksDB` table routing arguments
+    #[command(flatten)]
+    pub rocksdb: RocksDbArgs,
+
     /// Engine cli arguments
     #[command(flatten, next_help_heading = "Engine")]
     pub engine: EngineArgs,
@@ -166,12 +171,16 @@ where
             db,
             dev,
             pruning,
+            rocksdb,
             engine,
             era,
             static_files,
             ext,
         } = self;
 
+        // Validate RocksDB arguments
+        rocksdb.validate()?;
+
         // set up node config
         let mut node_config = NodeConfig {
             datadir,
@@ -187,6 +196,7 @@ where
             db,
             dev,
             pruning,
+            rocksdb,
             engine,
             era,
             static_files,
@@ -196,7 +206,7 @@ where
         let db_path = data_dir.db();
 
         tracing::info!(target: "reth::cli", path = ?db_path, "Opening database");
-        let database = Arc::new(init_db(db_path.clone(), self.db.database_args())?.with_metrics());
+        let database = init_db(db_path.clone(), self.db.database_args())?.with_metrics();
 
         if with_unused_ports {
             node_config = node_config.with_unused_ports();

crates/cli/commands/src/p2p/enode.rs

@@ -0,0 +1,34 @@
+//! Enode identifier command
+
+use clap::Parser;
+use reth_cli_util::get_secret_key;
+use reth_network_peers::NodeRecord;
+use std::{
+    net::{IpAddr, Ipv4Addr, SocketAddr},
+    path::PathBuf,
+};
+
+/// Print the enode identifier for a given secret key.
+#[derive(Parser, Debug)]
+pub struct Command {
+    /// Path to the secret key file for discovery.
+    pub discovery_secret: PathBuf,
+
+    /// Optional IP address to include in the enode URL.
+    ///
+    /// If not provided, defaults to 0.0.0.0.
+    #[arg(long)]
+    pub ip: Option<IpAddr>,
+}
+
+impl Command {
+    /// Execute the enode command.
+    pub fn execute(self) -> eyre::Result<()> {
+        let sk = get_secret_key(&self.discovery_secret)?;
+        let ip = self.ip.unwrap_or(IpAddr::V4(Ipv4Addr::UNSPECIFIED));
+        let addr = SocketAddr::new(ip, 30303);
+        let enr = NodeRecord::from_secret_key(addr, &sk);
+        println!("{enr}");
+        Ok(())
+    }
+}

crates/cli/commands/src/p2p/mod.rs

@@ -18,6 +18,7 @@ use reth_node_core::{
 };
 
 pub mod bootnode;
+pub mod enode;
 pub mod rlpx;
 
 /// `reth p2p` command
@@ -85,6 +86,9 @@ impl<C: ChainSpecParser<ChainSpec: EthChainSpec + Hardforks + EthereumHardforks>
             Subcommands::Bootnode(command) => {
                 command.execute().await?;
             }
+            Subcommands::Enode(command) => {
+                command.execute()?;
+            }
         }
 
         Ok(())
@@ -99,6 +103,7 @@ impl<C: ChainSpecParser> Command<C> {
             Subcommands::Body { args, .. } => Some(&args.chain),
             Subcommands::Rlpx(_) => None,
             Subcommands::Bootnode(_) => None,
+            Subcommands::Enode(_) => None,
         }
     }
 }
@@ -126,6 +131,8 @@ pub enum Subcommands<C: ChainSpecParser> {
     Rlpx(rlpx::Command),
     /// Bootnode command
     Bootnode(bootnode::Command),
+    /// Print enode identifier
+    Enode(enode::Command),
 }
 
 #[derive(Debug, Clone, Parser)]
@@ -225,4 +232,16 @@ mod tests {
         let _args: Command<EthereumChainSpecParser> =
             Command::parse_from(["reth", "body", "--chain", "mainnet", "1000"]);
     }
+
+    #[test]
+    fn parse_enode_cmd() {
+        let _args: Command<EthereumChainSpecParser> =
+            Command::parse_from(["reth", "enode", "/tmp/secret"]);
+    }
+
+    #[test]
+    fn parse_enode_cmd_with_ip() {
+        let _args: Command<EthereumChainSpecParser> =
+            Command::parse_from(["reth", "enode", "/tmp/secret", "--ip", "192.168.1.1"]);
+    }
 }

crates/cli/commands/src/prune.rs

@@ -1,26 +1,62 @@
-//! Command that runs pruning without any limits.
+//! Command that runs pruning.
 use crate::common::{AccessRights, CliNodeTypes, EnvironmentArgs};
 use clap::Parser;
-use reth_chainspec::{EthChainSpec, EthereumHardforks};
+use reth_chainspec::{ChainSpecProvider, EthChainSpec, EthereumHardforks};
 use reth_cli::chainspec::ChainSpecParser;
+use reth_cli_runner::CliContext;
+use reth_node_builder::common::metrics_hooks;
+use reth_node_core::{args::MetricArgs, version::version_metadata};
+use reth_node_metrics::{
+    chain::ChainSpecInfo,
+    server::{MetricServer, MetricServerConfig},
+    version::VersionInfo,
+};
 use reth_prune::PrunerBuilder;
 use reth_static_file::StaticFileProducer;
 use std::sync::Arc;
 use tracing::info;
 
-/// Prunes according to the configuration without any limits
+/// Prunes according to the configuration
 #[derive(Debug, Parser)]
 pub struct PruneCommand<C: ChainSpecParser> {
     #[command(flatten)]
     env: EnvironmentArgs<C>,
+
+    /// Prometheus metrics configuration.
+    #[command(flatten)]
+    metrics: MetricArgs,
 }
 
 impl<C: ChainSpecParser<ChainSpec: EthChainSpec + EthereumHardforks>> PruneCommand<C> {
     /// Execute the `prune` command
-    pub async fn execute<N: CliNodeTypes<ChainSpec = C::ChainSpec>>(self) -> eyre::Result<()> {
+    pub async fn execute<N: CliNodeTypes<ChainSpec = C::ChainSpec>>(
+        self,
+        ctx: CliContext,
+    ) -> eyre::Result<()> {
         let env = self.env.init::<N>(AccessRights::RW)?;
         let provider_factory = env.provider_factory;
         let config = env.config.prune;
+        let data_dir = env.data_dir;
+
+        if let Some(listen_addr) = self.metrics.prometheus {
+            let config = MetricServerConfig::new(
+                listen_addr,
+                VersionInfo {
+                    version: version_metadata().cargo_pkg_version.as_ref(),
+                    build_timestamp: version_metadata().vergen_build_timestamp.as_ref(),
+                    cargo_features: version_metadata().vergen_cargo_features.as_ref(),
+                    git_sha: version_metadata().vergen_git_sha.as_ref(),
+                    target_triple: version_metadata().vergen_cargo_target_triple.as_ref(),
+                    build_profile: version_metadata().build_profile_name.as_ref(),
+                },
+                ChainSpecInfo { name: provider_factory.chain_spec().chain().to_string() },
+                ctx.task_executor,
+                metrics_hooks(&provider_factory),
+                data_dir.pprof_dumps(),
+            );
+
+            MetricServer::new(config).serve().await?;
+        }
 
         // Copy data from database to static files
         info!(target: "reth::cli", "Copying data from database to static files...");
@@ -33,13 +69,43 @@ impl<C: ChainSpecParser<ChainSpec: EthChainSpec + EthereumHardforks>> PruneComma
         // Delete data which has been copied to static files.
         if let Some(prune_tip) = lowest_static_file_height {
             info!(target: "reth::cli", ?prune_tip, ?config, "Pruning data from database...");
-            // Run the pruner according to the configuration, and don't enforce any limits on it
+
+            // Use batched pruning with a limit to bound memory, running in a loop until complete.
+            const DELETE_LIMIT: usize = 200_000;
             let mut pruner = PrunerBuilder::new(config)
-                .delete_limit(usize::MAX)
+                .delete_limit(DELETE_LIMIT)
                 .build_with_provider_factory(provider_factory);
 
-            pruner.run(prune_tip)?;
-            info!(target: "reth::cli", "Pruned data from database");
+            let mut total_pruned = 0usize;
+            loop {
+                let output = pruner.run(prune_tip)?;
+                let batch_pruned: usize = output.segments.iter().map(|(_, seg)| seg.pruned).sum();
+                total_pruned = total_pruned.saturating_add(batch_pruned);
+
+                // Check if all segments are finished (not just the overall progress,
+                // since the pruner sets overall progress from the last segment only)
+                let all_segments_finished =
+                    output.segments.iter().all(|(_, seg)| seg.progress.is_finished());
+
+                if all_segments_finished {
+                    break;
+                }
+
+                if batch_pruned == 0 {
+                    return Err(eyre::eyre!(
+                        "pruner made no progress but reported more data remaining; \
+                         aborting to prevent infinite loop"
+                    ));
+                }
+
+                info!(
+                    target: "reth::cli",
+                    batch_pruned,
+                    total_pruned,
+                    "Pruning batch complete, continuing..."
+                );
+            }
+            info!(target: "reth::cli", total_pruned, "Pruned data from database");
         }
 
         Ok(())

crates/cli/commands/src/stage/drop.rs

@@ -15,7 +15,8 @@ use reth_db_common::{
 use reth_node_api::{HeaderTy, ReceiptTy, TxTy};
 use reth_node_core::args::StageEnum;
 use reth_provider::{
-    DBProvider, DatabaseProviderFactory, StaticFileProviderFactory, StaticFileWriter,
+    DBProvider, RocksDBProviderFactory, StaticFileProviderFactory, StaticFileWriter,
+    StorageSettingsCache,
 };
 use reth_prune::PruneSegment;
 use reth_stages::StageId;
@@ -90,11 +91,14 @@ impl<C: ChainSpecParser> Command<C> {
                     StaticFileSegment::AccountChangeSets => {
                         writer.prune_account_changesets(highest_block)?;
                     }
+                    StaticFileSegment::StorageChangeSets => {
+                        writer.prune_storage_changesets(highest_block)?;
+                    }
                 }
             }
         }
 
-        let provider_rw = tool.provider_factory.database_provider_rw()?;
+        let provider_rw = tool.provider_factory.unwind_provider_rw()?;
         let tx = provider_rw.tx_ref();
 
         match self.stage {
@@ -168,8 +172,20 @@ impl<C: ChainSpecParser> Command<C> {
                 )?;
             }
             StageEnum::AccountHistory | StageEnum::StorageHistory => {
-                tx.clear::<tables::AccountsHistory>()?;
-                tx.clear::<tables::StoragesHistory>()?;
+                let settings = provider_rw.cached_storage_settings();
+                let rocksdb = tool.provider_factory.rocksdb_provider();
+
+                if settings.account_history_in_rocksdb {
+                    rocksdb.clear::<tables::AccountsHistory>()?;
+                } else {
+                    tx.clear::<tables::AccountsHistory>()?;
+                }
+
+                if settings.storages_history_in_rocksdb {
+                    rocksdb.clear::<tables::StoragesHistory>()?;
+                } else {
+                    tx.clear::<tables::StoragesHistory>()?;
+                }
 
                 reset_stage_checkpoint(tx, StageId::IndexAccountHistory)?;
                 reset_stage_checkpoint(tx, StageId::IndexStorageHistory)?;
@@ -177,7 +193,14 @@ impl<C: ChainSpecParser> Command<C> {
                 insert_genesis_history(&provider_rw, self.env.chain.genesis().alloc.iter())?;
             }
             StageEnum::TxLookup => {
-                tx.clear::<tables::TransactionHashNumbers>()?;
+                if provider_rw.cached_storage_settings().transaction_hash_numbers_in_rocksdb {
+                    tool.provider_factory
+                        .rocksdb_provider()
+                        .clear::<tables::TransactionHashNumbers>()?;
+                } else {
+                    tx.clear::<tables::TransactionHashNumbers>()?;
+                }
+
                 reset_prune_checkpoint(tx, PruneSegment::TransactionLookup)?;
 
                 reset_stage_checkpoint(tx, StageId::TransactionLookup)?;

crates/cli/commands/src/stage/dump/execution.rs

@@ -26,7 +26,7 @@ pub(crate) async fn dump_execution_stage<N, E, C>(
     consensus: C,
 ) -> eyre::Result<()>
 where
-    N: ProviderNodeTypes<DB = Arc<DatabaseEnv>>,
+    N: ProviderNodeTypes<DB = DatabaseEnv>,
     E: ConfigureEvm<Primitives = N::Primitives> + 'static,
     C: FullConsensus<E::Primitives> + 'static,
 {
@@ -39,7 +39,7 @@ where
     if should_run {
         dry_run(
             ProviderFactory::<N>::new(
-                Arc::new(output_db),
+                output_db,
                 db_tool.chain(),
                 StaticFileProvider::read_write(output_datadir.static_files())?,
                 RocksDBProvider::builder(output_datadir.rocksdb()).build()?,

crates/cli/commands/src/stage/dump/hashing_account.rs

@@ -10,10 +10,9 @@ use reth_provider::{
     DatabaseProviderFactory, ProviderFactory,
 };
 use reth_stages::{stages::AccountHashingStage, Stage, StageCheckpoint, UnwindInput};
-use std::sync::Arc;
 use tracing::info;
 
-pub(crate) async fn dump_hashing_account_stage<N: ProviderNodeTypes<DB = Arc<DatabaseEnv>>>(
+pub(crate) async fn dump_hashing_account_stage<N: ProviderNodeTypes<DB = DatabaseEnv>>(
     db_tool: &DbTool<N>,
     from: BlockNumber,
     to: BlockNumber,
@@ -36,7 +35,7 @@ pub(crate) async fn dump_hashing_account_stage<N: ProviderNodeTypes<DB = Arc<Dat
     if should_run {
         dry_run(
             ProviderFactory::<N>::new(
-                Arc::new(output_db),
+                output_db,
                 db_tool.chain(),
                 StaticFileProvider::read_write(output_datadir.static_files())?,
                 RocksDBProvider::builder(output_datadir.rocksdb()).build()?,

crates/cli/commands/src/stage/dump/hashing_storage.rs

@@ -9,10 +9,9 @@ use reth_provider::{
     DatabaseProviderFactory, ProviderFactory,
 };
 use reth_stages::{stages::StorageHashingStage, Stage, StageCheckpoint, UnwindInput};
-use std::sync::Arc;
 use tracing::info;
 
-pub(crate) async fn dump_hashing_storage_stage<N: ProviderNodeTypes<DB = Arc<DatabaseEnv>>>(
+pub(crate) async fn dump_hashing_storage_stage<N: ProviderNodeTypes<DB = DatabaseEnv>>(
     db_tool: &DbTool<N>,
     from: u64,
     to: u64,
@@ -26,7 +25,7 @@ pub(crate) async fn dump_hashing_storage_stage<N: ProviderNodeTypes<DB = Arc<Dat
     if should_run {
         dry_run(
             ProviderFactory::<N>::new(
-                Arc::new(output_db),
+                output_db,
                 db_tool.chain(),
                 StaticFileProvider::read_write(output_datadir.static_files())?,
                 RocksDBProvider::builder(output_datadir.rocksdb()).build()?,

crates/cli/commands/src/stage/dump/merkle.rs

@@ -34,7 +34,7 @@ pub(crate) async fn dump_merkle_stage<N>(
     consensus: impl FullConsensus<N::Primitives> + 'static,
 ) -> Result<()>
 where
-    N: ProviderNodeTypes<DB = Arc<DatabaseEnv>>,
+    N: ProviderNodeTypes<DB = DatabaseEnv>,
 {
     let (output_db, tip_block_number) = setup(from, to, &output_datadir.db(), db_tool)?;
 
@@ -59,7 +59,7 @@ where
     if should_run {
         dry_run(
             ProviderFactory::<N>::new(
-                Arc::new(output_db),
+                output_db,
                 db_tool.chain(),
                 StaticFileProvider::read_write(output_datadir.static_files())?,
                 RocksDBProvider::builder(output_datadir.rocksdb()).build()?,

crates/cli/commands/src/stage/unwind.rs

@@ -158,7 +158,7 @@ enum Subcommands {
 
 impl Subcommands {
     /// Returns the block to unwind to. The returned block will stay in database.
-    fn unwind_target<N: ProviderNodeTypes<DB = Arc<DatabaseEnv>>>(
+    fn unwind_target<N: ProviderNodeTypes<DB = DatabaseEnv>>(
         &self,
         factory: ProviderFactory<N>,
     ) -> eyre::Result<u64> {

crates/cli/util/src/sigsegv_handler.rs

@@ -121,7 +121,16 @@ pub fn install() {
     unsafe {
         let alt_stack_size: usize = min_sigstack_size() + 64 * 1024;
         let mut alt_stack: libc::stack_t = mem::zeroed();
-        alt_stack.ss_sp = alloc(Layout::from_size_align(alt_stack_size, 1).unwrap()).cast();
+        // Both SysV AMD64 ABI and aarch64 ABI require 16 bytes alignment. We are going to be
+        // generous here and just use a size of a page.
+        let raw_page_sz = libc::sysconf(libc::_SC_PAGESIZE);
+        let page_sz = if raw_page_sz == -1 {
+            // Fallback alignment in case sysconf fails.
+            4096_usize
+        } else {
+            raw_page_sz as usize
+        };
+        alt_stack.ss_sp = alloc(Layout::from_size_align(alt_stack_size, page_sz).unwrap()).cast();
         alt_stack.ss_size = alt_stack_size;
         libc::sigaltstack(&raw const alt_stack, ptr::null_mut());
 

crates/config/src/config.rs

@@ -438,6 +438,8 @@ pub struct BlocksPerFileConfig {
     pub transaction_senders: Option<u64>,
     /// Number of blocks per file for the account changesets segment.
     pub account_change_sets: Option<u64>,
+    /// Number of blocks per file for the storage changesets segment.
+    pub storage_change_sets: Option<u64>,
 }
 
 impl StaticFilesConfig {
@@ -451,6 +453,7 @@ impl StaticFilesConfig {
             receipts,
             transaction_senders,
             account_change_sets,
+            storage_change_sets,
         } = self.blocks_per_file;
         eyre::ensure!(headers != Some(0), "Headers segment blocks per file must be greater than 0");
         eyre::ensure!(
@@ -469,6 +472,10 @@ impl StaticFilesConfig {
             account_change_sets != Some(0),
             "Account changesets segment blocks per file must be greater than 0"
         );
+        eyre::ensure!(
+            storage_change_sets != Some(0),
+            "Storage changesets segment blocks per file must be greater than 0"
+        );
         Ok(())
     }
 
@@ -480,6 +487,7 @@ impl StaticFilesConfig {
             receipts,
             transaction_senders,
             account_change_sets,
+            storage_change_sets,
         } = self.blocks_per_file;
 
         let mut map = StaticFileMap::default();
@@ -492,6 +500,7 @@ impl StaticFilesConfig {
                 StaticFileSegment::Receipts => receipts,
                 StaticFileSegment::TransactionSenders => transaction_senders,
                 StaticFileSegment::AccountChangeSets => account_change_sets,
+                StaticFileSegment::StorageChangeSets => storage_change_sets,
             };
 
             if let Some(blocks_per_file) = blocks_per_file {

crates/consensus/common/src/validation.rs

@@ -1,14 +1,11 @@
 //! Collection of methods for block validation.
 
-use alloy_consensus::{BlockHeader as _, Transaction, EMPTY_OMMER_ROOT_HASH};
+use alloy_consensus::{BlockHeader as _, EMPTY_OMMER_ROOT_HASH};
 use alloy_eips::{eip4844::DATA_GAS_PER_BLOB, eip7840::BlobParams};
 use reth_chainspec::{EthChainSpec, EthereumHardfork, EthereumHardforks};
-use reth_consensus::{ConsensusError, TxGasLimitTooHighErr};
+use reth_consensus::ConsensusError;
 use reth_primitives_traits::{
-    constants::{
-        GAS_LIMIT_BOUND_DIVISOR, MAXIMUM_GAS_LIMIT_BLOCK, MAX_TX_GAS_LIMIT_OSAKA, MINIMUM_GAS_LIMIT,
-    },
-    transaction::TxHashRef,
+    constants::{GAS_LIMIT_BOUND_DIVISOR, MAXIMUM_GAS_LIMIT_BLOCK, MINIMUM_GAS_LIMIT},
     Block, BlockBody, BlockHeader, GotExpected, SealedBlock, SealedHeader,
 };
 
@@ -146,7 +143,7 @@ pub fn validate_block_pre_execution<B, ChainSpec>(
 ) -> Result<(), ConsensusError>
 where
     B: Block,
-    ChainSpec: EthereumHardforks,
+    ChainSpec: EthChainSpec + EthereumHardforks,
 {
     post_merge_hardfork_fields(block, chain_spec)?;
 
@@ -154,19 +151,6 @@ where
     if let Err(error) = block.ensure_transaction_root_valid() {
         return Err(ConsensusError::BodyTransactionRootDiff(error.into()))
     }
-    // EIP-7825 validation
-    if chain_spec.is_osaka_active_at_timestamp(block.timestamp()) {
-        for tx in block.body().transactions() {
-            if tx.gas_limit() > MAX_TX_GAS_LIMIT_OSAKA {
-                return Err(TxGasLimitTooHighErr {
-                    tx_hash: *tx.tx_hash(),
-                    gas_limit: tx.gas_limit(),
-                    max_allowed: MAX_TX_GAS_LIMIT_OSAKA,
-                }
-                .into());
-            }
-        }
-    }
 
     Ok(())
 }

crates/consensus/debug-client/Cargo.toml

@@ -29,7 +29,7 @@ auto_impl.workspace = true
 derive_more.workspace = true
 futures.workspace = true
 eyre.workspace = true
-reqwest = { workspace = true, features = ["rustls-tls"] }
+reqwest.workspace = true
 serde = { workspace = true, features = ["derive"] }
 tokio = { workspace = true, features = ["time"] }
 serde_json.workspace = true

crates/consensus/debug-client/src/client.rs

@@ -38,12 +38,8 @@ pub trait BlockProvider: Send + Sync + 'static {
         offset: usize,
     ) -> impl Future<Output = eyre::Result<B256>> + Send {
         async move {
-            let stored_hash = previous_block_hashes
-                .len()
-                .checked_sub(offset)
-                .and_then(|index| previous_block_hashes.get(index));
-            if let Some(hash) = stored_hash {
-                return Ok(*hash);
+            if let Some(hash) = get_hash_at_offset(previous_block_hashes, offset) {
+                return Ok(hash);
             }
 
             // Return zero hash if the chain isn't long enough to have the block at the offset.
@@ -83,7 +79,7 @@ where
     /// Spawn the client to start sending FCUs and new payloads by periodically fetching recent
     /// blocks.
     pub async fn run(self) {
-        let mut previous_block_hashes = AllocRingBuffer::new(64);
+        let mut previous_block_hashes = AllocRingBuffer::new(65);
         let mut block_stream = {
             let (tx, rx) = mpsc::channel::<P::Block>(64);
             let block_provider = self.block_provider.clone();
@@ -99,7 +95,7 @@ where
             let block_hash = payload.block_hash();
             let block_number = payload.block_number();
 
-            previous_block_hashes.push(block_hash);
+            previous_block_hashes.enqueue(block_hash);
 
             // Send new events to execution client
             let _ = self.engine_handle.new_payload(payload).await;
@@ -142,3 +138,60 @@ where
         }
     }
 }
+
+/// Looks up a block hash from the ring buffer at the given offset from the most recent entry.
+///
+/// Returns `None` if the buffer doesn't have enough entries to satisfy the offset.
+fn get_hash_at_offset(buffer: &AllocRingBuffer<B256>, offset: usize) -> Option<B256> {
+    buffer.len().checked_sub(offset + 1).and_then(|index| buffer.get(index).copied())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_get_hash_at_offset() {
+        let mut buffer: AllocRingBuffer<B256> = AllocRingBuffer::new(65);
+
+        // Empty buffer returns None for any offset
+        assert_eq!(get_hash_at_offset(&buffer, 0), None);
+        assert_eq!(get_hash_at_offset(&buffer, 1), None);
+
+        // Push hashes 0..65
+        for i in 0..65u8 {
+            buffer.enqueue(B256::with_last_byte(i));
+        }
+
+        // offset=0 should return the most recent (64)
+        assert_eq!(get_hash_at_offset(&buffer, 0), Some(B256::with_last_byte(64)));
+
+        // offset=32 (safe block) should return hash 32
+        assert_eq!(get_hash_at_offset(&buffer, 32), Some(B256::with_last_byte(32)));
+
+        // offset=64 (finalized block) should return hash 0 (the oldest)
+        assert_eq!(get_hash_at_offset(&buffer, 64), Some(B256::with_last_byte(0)));
+
+        // offset=65 exceeds buffer, should return None
+        assert_eq!(get_hash_at_offset(&buffer, 65), None);
+    }
+
+    #[test]
+    fn test_get_hash_at_offset_insufficient_entries() {
+        let mut buffer: AllocRingBuffer<B256> = AllocRingBuffer::new(65);
+
+        // With only 1 entry, only offset=0 works
+        buffer.enqueue(B256::with_last_byte(1));
+        assert_eq!(get_hash_at_offset(&buffer, 0), Some(B256::with_last_byte(1)));
+        assert_eq!(get_hash_at_offset(&buffer, 1), None);
+        assert_eq!(get_hash_at_offset(&buffer, 32), None);
+        assert_eq!(get_hash_at_offset(&buffer, 64), None);
+
+        // With 33 entries, offset=32 works but offset=64 doesn't
+        for i in 2..=33u8 {
+            buffer.enqueue(B256::with_last_byte(i));
+        }
+        assert_eq!(get_hash_at_offset(&buffer, 32), Some(B256::with_last_byte(1)));
+        assert_eq!(get_hash_at_offset(&buffer, 64), None);
+    }
+}

crates/e2e-test-utils/Cargo.toml

@@ -72,3 +72,11 @@ derive_more.workspace = true
 [[test]]
 name = "e2e_testsuite"
 path = "tests/e2e-testsuite/main.rs"
+
+[[test]]
+name = "rocksdb"
+path = "tests/rocksdb/main.rs"
+required-features = ["edge"]
+
+[features]
+edge = ["reth-node-core/edge", "reth-provider/rocksdb", "reth-cli-commands/edge"]

crates/e2e-test-utils/src/lib.rs

@@ -103,7 +103,10 @@ where
     N: NodeBuilderHelper,
 {
     E2ETestSetupBuilder::new(num_nodes, chain_spec, attributes_generator)
-        .with_tree_config_modifier(move |_| tree_config.clone())
+        .with_tree_config_modifier(move |base| {
+            // Apply caller's tree_config but preserve the small cache size from base
+            tree_config.clone().with_cross_block_cache_size(base.cross_block_cache_size())
+        })
         .with_node_config_modifier(move |config| config.set_dev(is_dev))
         .with_connect_nodes(connect_nodes)
         .build()

crates/e2e-test-utils/src/setup_builder.rs

@@ -112,11 +112,13 @@ where
             ..NetworkArgs::default()
         };
 
-        // Apply tree config modifier if present
+        // Apply tree config modifier if present, with test-appropriate defaults
+        let base_tree_config =
+            reth_node_api::TreeConfig::default().with_cross_block_cache_size(1024 * 1024);
         let tree_config = if let Some(modifier) = self.tree_config_modifier {
-            modifier(reth_node_api::TreeConfig::default())
+            modifier(base_tree_config)
         } else {
-            reth_node_api::TreeConfig::default()
+            base_tree_config
         };
 
         let mut nodes = (0..self.num_nodes)

crates/e2e-test-utils/src/setup_import.rs

@@ -114,19 +114,22 @@ pub async fn setup_engine_with_chain_import(
 
         // Initialize the database using init_db (same as CLI import command)
         let db_args = reth_node_core::args::DatabaseArgs::default().database_args();
-        let db_env = reth_db::init_db(&db_path, db_args)?;
-        let db = Arc::new(db_env);
+        let db = reth_db::init_db(&db_path, db_args)?;
 
         // Create a provider factory with the initialized database (use regular DB, not
         // TempDatabase) We need to specify the node types properly for the adapter
-        let provider_factory = ProviderFactory::<
-            NodeTypesWithDBAdapter<EthereumNode, Arc<DatabaseEnv>>,
-        >::new(
-            db.clone(),
-            chain_spec.clone(),
-            reth_provider::providers::StaticFileProvider::read_write(static_files_path.clone())?,
-            reth_provider::providers::RocksDBProvider::builder(rocksdb_dir_path).build().unwrap(),
-        )?;
+        let provider_factory =
+            ProviderFactory::<NodeTypesWithDBAdapter<EthereumNode, DatabaseEnv>>::new(
+                db.clone(),
+                chain_spec.clone(),
+                reth_provider::providers::StaticFileProvider::read_write(
+                    static_files_path.clone(),
+                )?,
+                reth_provider::providers::RocksDBProvider::builder(rocksdb_dir_path)
+                    .with_default_tables()
+                    .build()
+                    .unwrap(),
+            )?;
 
         // Initialize genesis if needed
         reth_db_common::init::init_genesis(&provider_factory)?;
@@ -317,17 +320,17 @@ mod tests {
         // Import the chain
         {
             let db_args = reth_node_core::args::DatabaseArgs::default().database_args();
-            let db_env = reth_db::init_db(&db_path, db_args).unwrap();
-            let db = Arc::new(db_env);
+            let db = reth_db::init_db(&db_path, db_args).unwrap();
 
             let provider_factory: ProviderFactory<
-                NodeTypesWithDBAdapter<reth_node_ethereum::EthereumNode, Arc<DatabaseEnv>>,
+                NodeTypesWithDBAdapter<reth_node_ethereum::EthereumNode, DatabaseEnv>,
             > = ProviderFactory::new(
                 db.clone(),
                 chain_spec.clone(),
                 reth_provider::providers::StaticFileProvider::read_write(static_files_path.clone())
                     .unwrap(),
                 reth_provider::providers::RocksDBProvider::builder(rocksdb_dir_path.clone())
+                    .with_default_tables()
                     .build()
                     .unwrap(),
             )
@@ -381,17 +384,17 @@ mod tests {
 
         // Now reopen the database and verify checkpoints are still there
         {
-            let db_env = reth_db::init_db(&db_path, DatabaseArguments::default()).unwrap();
-            let db = Arc::new(db_env);
+            let db = reth_db::init_db(&db_path, DatabaseArguments::default()).unwrap();
 
             let provider_factory: ProviderFactory<
-                NodeTypesWithDBAdapter<reth_node_ethereum::EthereumNode, Arc<DatabaseEnv>>,
+                NodeTypesWithDBAdapter<reth_node_ethereum::EthereumNode, DatabaseEnv>,
             > = ProviderFactory::new(
                 db,
                 chain_spec.clone(),
                 reth_provider::providers::StaticFileProvider::read_only(static_files_path, false)
                     .unwrap(),
                 reth_provider::providers::RocksDBProvider::builder(rocksdb_dir_path)
+                    .with_default_tables()
                     .build()
                     .unwrap(),
             )
@@ -490,7 +493,10 @@ mod tests {
             db.clone(),
             chain_spec.clone(),
             reth_provider::providers::StaticFileProvider::read_write(static_files_path).unwrap(),
-            reth_provider::providers::RocksDBProvider::builder(rocksdb_dir_path).build().unwrap(),
+            reth_provider::providers::RocksDBProvider::builder(rocksdb_dir_path)
+                .with_default_tables()
+                .build()
+                .unwrap(),
         )
         .expect("failed to create provider factory");
 

crates/e2e-test-utils/src/transaction.rs

@@ -38,6 +38,18 @@ impl TransactionTestContext {
         signed.encoded_2718().into()
     }
 
+    /// Creates a transfer with a specific nonce and signs it, returning bytes.
+    /// Uses high `max_fee_per_gas` (1000 gwei) to ensure tx acceptance regardless of basefee.
+    pub async fn transfer_tx_bytes_with_nonce(
+        chain_id: u64,
+        wallet: PrivateKeySigner,
+        nonce: u64,
+    ) -> Bytes {
+        let tx = tx(chain_id, 21000, None, None, nonce, Some(1000e9 as u128));
+        let signed = Self::sign_tx(wallet, tx).await;
+        signed.encoded_2718().into()
+    }
+
     /// Creates a deployment transaction and signs it, returning an envelope.
     pub async fn deploy_tx(
         chain_id: u64,

crates/e2e-test-utils/tests/rocksdb/main.rs

@@ -0,0 +1,591 @@
+//! E2E tests for `RocksDB` provider functionality.
+
+#![cfg(all(feature = "edge", unix))]
+
+use alloy_consensus::BlockHeader;
+use alloy_primitives::B256;
+use alloy_rpc_types_eth::{Transaction, TransactionReceipt};
+use eyre::Result;
+use jsonrpsee::core::client::ClientT;
+use reth_chainspec::{ChainSpec, ChainSpecBuilder, MAINNET};
+use reth_db::tables;
+use reth_e2e_test_utils::{transaction::TransactionTestContext, wallet, E2ETestSetupBuilder};
+use reth_node_core::args::RocksDbArgs;
+use reth_node_ethereum::EthereumNode;
+use reth_payload_builder::EthPayloadBuilderAttributes;
+use reth_provider::{RocksDBProviderFactory, StorageSettings};
+use std::{sync::Arc, time::Duration};
+
+const ROCKSDB_POLL_TIMEOUT: Duration = Duration::from_secs(60);
+const ROCKSDB_POLL_INTERVAL: Duration = Duration::from_millis(50);
+
+/// Polls RPC until the given `tx_hash` is visible as pending (not yet mined).
+/// Prevents race conditions where `advance_block` is called before txs are in the pool.
+/// Returns the pending transaction.
+async fn wait_for_pending_tx<C: ClientT>(client: &C, tx_hash: B256) -> Transaction {
+    let start = std::time::Instant::now();
+    loop {
+        let tx: Option<Transaction> = client
+            .request("eth_getTransactionByHash", [tx_hash])
+            .await
+            .expect("RPC request failed");
+        if let Some(tx) = tx {
+            assert!(
+                tx.block_number.is_none(),
+                "Expected pending tx but tx_hash={tx_hash:?} is already mined in block {:?}",
+                tx.block_number
+            );
+            return tx;
+        }
+        assert!(
+            start.elapsed() < ROCKSDB_POLL_TIMEOUT,
+            "Timed out after {:?} waiting for tx_hash={tx_hash:?} to appear in pending pool",
+            start.elapsed()
+        );
+        tokio::time::sleep(ROCKSDB_POLL_INTERVAL).await;
+    }
+}
+
+/// Polls `RocksDB` until the given `tx_hash` appears in `TransactionHashNumbers`.
+/// Returns the `tx_number` on success, or panics on timeout.
+async fn poll_tx_in_rocksdb<P: RocksDBProviderFactory>(provider: &P, tx_hash: B256) -> u64 {
+    let start = std::time::Instant::now();
+    let mut interval = ROCKSDB_POLL_INTERVAL;
+    loop {
+        // Re-acquire handle each iteration to avoid stale snapshot reads
+        let rocksdb = provider.rocksdb_provider();
+        let tx_number: Option<u64> =
+            rocksdb.get::<tables::TransactionHashNumbers>(tx_hash).expect("RocksDB get failed");
+        if let Some(n) = tx_number {
+            return n;
+        }
+        assert!(
+            start.elapsed() < ROCKSDB_POLL_TIMEOUT,
+            "Timed out after {:?} waiting for tx_hash={tx_hash:?} in RocksDB",
+            start.elapsed()
+        );
+        tokio::time::sleep(interval).await;
+        // Simple backoff: 50ms -> 100ms -> 200ms (capped)
+        interval = std::cmp::min(interval * 2, Duration::from_millis(200));
+    }
+}
+
+/// Returns the test chain spec for `RocksDB` tests.
+fn test_chain_spec() -> Arc<ChainSpec> {
+    Arc::new(
+        ChainSpecBuilder::default()
+            .chain(MAINNET.chain)
+            .genesis(
+                serde_json::from_str(include_str!("../../src/testsuite/assets/genesis.json"))
+                    .expect("failed to parse genesis.json"),
+            )
+            .cancun_activated()
+            .build(),
+    )
+}
+
+/// Returns test payload attributes for the given timestamp.
+fn test_attributes_generator(timestamp: u64) -> EthPayloadBuilderAttributes {
+    let attributes = alloy_rpc_types_engine::PayloadAttributes {
+        timestamp,
+        prev_randao: B256::ZERO,
+        suggested_fee_recipient: alloy_primitives::Address::ZERO,
+        withdrawals: Some(vec![]),
+        parent_beacon_block_root: Some(B256::ZERO),
+    };
+    EthPayloadBuilderAttributes::new(B256::ZERO, attributes)
+}
+
+/// Verifies that `RocksDB` CLI defaults match `StorageSettings::base()`.
+#[test]
+fn test_rocksdb_defaults_match_storage_settings() {
+    let args = RocksDbArgs::default();
+    let settings = StorageSettings::base();
+
+    assert_eq!(
+        args.tx_hash, settings.transaction_hash_numbers_in_rocksdb,
+        "tx_hash default should match StorageSettings::base()"
+    );
+    assert_eq!(
+        args.storages_history, settings.storages_history_in_rocksdb,
+        "storages_history default should match StorageSettings::base()"
+    );
+    assert_eq!(
+        args.account_history, settings.account_history_in_rocksdb,
+        "account_history default should match StorageSettings::base()"
+    );
+}
+
+/// Smoke test: node boots with `RocksDB` routing enabled.
+#[tokio::test]
+async fn test_rocksdb_node_startup() -> Result<()> {
+    reth_tracing::init_test_tracing();
+
+    let chain_spec = test_chain_spec();
+
+    let (nodes, _tasks, _wallet) =
+        E2ETestSetupBuilder::<EthereumNode, _>::new(1, chain_spec, test_attributes_generator)
+            .build()
+            .await?;
+
+    assert_eq!(nodes.len(), 1);
+
+    // Verify RocksDB provider is functional (can query without error)
+    let rocksdb = nodes[0].inner.provider.rocksdb_provider();
+    let missing_hash = B256::from([0xab; 32]);
+    let result: Option<u64> = rocksdb.get::<tables::TransactionHashNumbers>(missing_hash)?;
+    assert!(result.is_none(), "Missing hash should return None");
+
+    let genesis_hash = nodes[0].block_hash(0);
+    assert_ne!(genesis_hash, B256::ZERO);
+
+    Ok(())
+}
+
+/// Block mining works with `RocksDB` storage.
+#[tokio::test]
+async fn test_rocksdb_block_mining() -> Result<()> {
+    reth_tracing::init_test_tracing();
+
+    let chain_spec = test_chain_spec();
+    let chain_id = chain_spec.chain().id();
+
+    let (mut nodes, _tasks, _wallet) =
+        E2ETestSetupBuilder::<EthereumNode, _>::new(1, chain_spec, test_attributes_generator)
+            .build()
+            .await?;
+
+    assert_eq!(nodes.len(), 1);
+
+    let genesis_hash = nodes[0].block_hash(0);
+    assert_ne!(genesis_hash, B256::ZERO);
+
+    // Mine 3 blocks with transactions
+    let wallets = wallet::Wallet::new(1).with_chain_id(chain_id).wallet_gen();
+    let signer = wallets[0].clone();
+    let client = nodes[0].rpc_client().expect("RPC client should be available");
+
+    for i in 1..=3u64 {
+        let raw_tx =
+            TransactionTestContext::transfer_tx_bytes_with_nonce(chain_id, signer.clone(), i - 1)
+                .await;
+        let tx_hash = nodes[0].rpc.inject_tx(raw_tx).await?;
+
+        // Wait for tx to enter pending pool before mining
+        wait_for_pending_tx(&client, tx_hash).await;
+
+        let payload = nodes[0].advance_block().await?;
+        let block = payload.block();
+        assert_eq!(block.number(), i);
+        assert_ne!(block.hash(), B256::ZERO);
+
+        // Verify tx was actually included in the block
+        let receipt: Option<TransactionReceipt> =
+            client.request("eth_getTransactionReceipt", [tx_hash]).await?;
+        let receipt = receipt.expect("Receipt should exist after mining");
+        assert_eq!(receipt.block_number, Some(i), "Tx should be in block {i}");
+    }
+
+    // Verify all blocks are stored
+    for i in 0..=3 {
+        let block_hash = nodes[0].block_hash(i);
+        assert_ne!(block_hash, B256::ZERO);
+    }
+
+    Ok(())
+}
+
+/// Tx hash lookup exercises `TransactionHashNumbers` table.
+#[tokio::test]
+async fn test_rocksdb_transaction_queries() -> Result<()> {
+    reth_tracing::init_test_tracing();
+
+    let chain_spec = test_chain_spec();
+    let chain_id = chain_spec.chain().id();
+
+    let (mut nodes, _tasks, _) = E2ETestSetupBuilder::<EthereumNode, _>::new(
+        1,
+        chain_spec.clone(),
+        test_attributes_generator,
+    )
+    .with_tree_config_modifier(|config| config.with_persistence_threshold(0))
+    .build()
+    .await?;
+
+    assert_eq!(nodes.len(), 1);
+
+    // Inject and mine a transaction
+    let wallets = wallet::Wallet::new(1).with_chain_id(chain_id).wallet_gen();
+    let signer = wallets[0].clone();
+    let client = nodes[0].rpc_client().expect("RPC client should be available");
+
+    let raw_tx = TransactionTestContext::transfer_tx_bytes(chain_id, signer).await;
+    let tx_hash = nodes[0].rpc.inject_tx(raw_tx).await?;
+
+    // Wait for tx to enter pending pool before mining
+    wait_for_pending_tx(&client, tx_hash).await;
+
+    let payload = nodes[0].advance_block().await?;
+    assert_eq!(payload.block().number(), 1);
+
+    // Query each transaction by hash
+    let tx: Option<Transaction> = client.request("eth_getTransactionByHash", [tx_hash]).await?;
+    let tx = tx.expect("Transaction should be found");
+    assert_eq!(tx.block_number, Some(1));
+
+    let receipt: Option<TransactionReceipt> =
+        client.request("eth_getTransactionReceipt", [tx_hash]).await?;
+    let receipt = receipt.expect("Receipt should be found");
+    assert_eq!(receipt.block_number, Some(1));
+    assert!(receipt.status());
+
+    // Direct RocksDB assertion - poll with timeout since persistence is async
+    let tx_number = poll_tx_in_rocksdb(&nodes[0].inner.provider, tx_hash).await;
+    assert_eq!(tx_number, 0, "First tx should have TxNumber 0");
+
+    // Verify missing hash returns None
+    let missing_hash = B256::from([0xde; 32]);
+    let rocksdb = nodes[0].inner.provider.rocksdb_provider();
+    let missing_tx_number: Option<u64> =
+        rocksdb.get::<tables::TransactionHashNumbers>(missing_hash)?;
+    assert!(missing_tx_number.is_none());
+
+    let missing_tx: Option<Transaction> =
+        client.request("eth_getTransactionByHash", [missing_hash]).await?;
+    assert!(missing_tx.is_none(), "expected no transaction for missing hash");
+
+    let missing_receipt: Option<TransactionReceipt> =
+        client.request("eth_getTransactionReceipt", [missing_hash]).await?;
+    assert!(missing_receipt.is_none(), "expected no receipt for missing hash");
+
+    Ok(())
+}
+
+/// Multiple transactions in the same block are correctly persisted to `RocksDB`.
+#[tokio::test]
+async fn test_rocksdb_multi_tx_same_block() -> Result<()> {
+    reth_tracing::init_test_tracing();
+
+    let chain_spec = test_chain_spec();
+    let chain_id = chain_spec.chain().id();
+
+    let (mut nodes, _tasks, _) = E2ETestSetupBuilder::<EthereumNode, _>::new(
+        1,
+        chain_spec.clone(),
+        test_attributes_generator,
+    )
+    .with_tree_config_modifier(|config| config.with_persistence_threshold(0))
+    .build()
+    .await?;
+
+    // Create 3 txs from the same wallet with sequential nonces
+    let wallets = wallet::Wallet::new(1).with_chain_id(chain_id).wallet_gen();
+    let signer = wallets[0].clone();
+    let client = nodes[0].rpc_client().expect("RPC client");
+
+    let mut tx_hashes = Vec::new();
+    for nonce in 0..3 {
+        let raw_tx =
+            TransactionTestContext::transfer_tx_bytes_with_nonce(chain_id, signer.clone(), nonce)
+                .await;
+        let tx_hash = nodes[0].rpc.inject_tx(raw_tx).await?;
+        tx_hashes.push(tx_hash);
+    }
+
+    // Wait for all txs to appear in pending pool before mining
+    for tx_hash in &tx_hashes {
+        wait_for_pending_tx(&client, *tx_hash).await;
+    }
+
+    // Mine one block containing all 3 txs
+    let payload = nodes[0].advance_block().await?;
+    assert_eq!(payload.block().number(), 1);
+
+    // Verify block contains all 3 txs
+    let block: Option<alloy_rpc_types_eth::Block> =
+        client.request("eth_getBlockByNumber", ("0x1", true)).await?;
+    let block = block.expect("Block 1 should exist");
+    assert_eq!(block.transactions.len(), 3, "Block should contain 3 txs");
+
+    // Verify each tx via RPC
+    for tx_hash in &tx_hashes {
+        let tx: Option<Transaction> = client.request("eth_getTransactionByHash", [tx_hash]).await?;
+        let tx = tx.expect("Transaction should be found");
+        assert_eq!(tx.block_number, Some(1), "All txs should be in block 1");
+    }
+
+    // Poll RocksDB for all tx hashes and collect tx_numbers
+    let mut tx_numbers = Vec::new();
+    for tx_hash in &tx_hashes {
+        let n = poll_tx_in_rocksdb(&nodes[0].inner.provider, *tx_hash).await;
+        tx_numbers.push(n);
+    }
+
+    // Verify tx_numbers form the set {0, 1, 2}
+    tx_numbers.sort();
+    assert_eq!(tx_numbers, vec![0, 1, 2], "TxNumbers should be 0, 1, 2");
+
+    Ok(())
+}
+
+/// Transactions across multiple blocks have globally continuous `tx_numbers`.
+#[tokio::test]
+async fn test_rocksdb_txs_across_blocks() -> Result<()> {
+    reth_tracing::init_test_tracing();
+
+    let chain_spec = test_chain_spec();
+    let chain_id = chain_spec.chain().id();
+
+    let (mut nodes, _tasks, _) = E2ETestSetupBuilder::<EthereumNode, _>::new(
+        1,
+        chain_spec.clone(),
+        test_attributes_generator,
+    )
+    .with_tree_config_modifier(|config| config.with_persistence_threshold(0))
+    .build()
+    .await?;
+
+    let wallets = wallet::Wallet::new(1).with_chain_id(chain_id).wallet_gen();
+    let signer = wallets[0].clone();
+    let client = nodes[0].rpc_client().expect("RPC client");
+
+    // Block 1: 2 transactions
+    let tx_hash_0 = nodes[0]
+        .rpc
+        .inject_tx(
+            TransactionTestContext::transfer_tx_bytes_with_nonce(chain_id, signer.clone(), 0).await,
+        )
+        .await?;
+    let tx_hash_1 = nodes[0]
+        .rpc
+        .inject_tx(
+            TransactionTestContext::transfer_tx_bytes_with_nonce(chain_id, signer.clone(), 1).await,
+        )
+        .await?;
+
+    // Wait for both txs to appear in pending pool
+    wait_for_pending_tx(&client, tx_hash_0).await;
+    wait_for_pending_tx(&client, tx_hash_1).await;
+
+    let payload1 = nodes[0].advance_block().await?;
+    assert_eq!(payload1.block().number(), 1);
+
+    // Block 2: 1 transaction
+    let tx_hash_2 = nodes[0]
+        .rpc
+        .inject_tx(
+            TransactionTestContext::transfer_tx_bytes_with_nonce(chain_id, signer.clone(), 2).await,
+        )
+        .await?;
+
+    wait_for_pending_tx(&client, tx_hash_2).await;
+
+    let payload2 = nodes[0].advance_block().await?;
+    assert_eq!(payload2.block().number(), 2);
+
+    // Verify block contents via RPC
+    let tx0: Option<Transaction> = client.request("eth_getTransactionByHash", [tx_hash_0]).await?;
+    let tx1: Option<Transaction> = client.request("eth_getTransactionByHash", [tx_hash_1]).await?;
+    let tx2: Option<Transaction> = client.request("eth_getTransactionByHash", [tx_hash_2]).await?;
+
+    assert_eq!(tx0.expect("tx0").block_number, Some(1));
+    assert_eq!(tx1.expect("tx1").block_number, Some(1));
+    assert_eq!(tx2.expect("tx2").block_number, Some(2));
+
+    // Poll RocksDB and verify global tx_number continuity
+    let all_tx_hashes = [tx_hash_0, tx_hash_1, tx_hash_2];
+    let mut tx_numbers = Vec::new();
+    for tx_hash in &all_tx_hashes {
+        let n = poll_tx_in_rocksdb(&nodes[0].inner.provider, *tx_hash).await;
+        tx_numbers.push(n);
+    }
+
+    // Verify they form a continuous sequence {0, 1, 2}
+    tx_numbers.sort();
+    assert_eq!(tx_numbers, vec![0, 1, 2], "TxNumbers should be globally continuous: 0, 1, 2");
+
+    // Re-query block 1 txs after block 2 is mined (regression guard)
+    let tx0_again: Option<Transaction> =
+        client.request("eth_getTransactionByHash", [tx_hash_0]).await?;
+    assert!(tx0_again.is_some(), "Block 1 tx should still be queryable after block 2");
+
+    Ok(())
+}
+
+/// Pending transactions should NOT appear in `RocksDB` until mined.
+#[tokio::test]
+async fn test_rocksdb_pending_tx_not_in_storage() -> Result<()> {
+    reth_tracing::init_test_tracing();
+
+    let chain_spec = test_chain_spec();
+    let chain_id = chain_spec.chain().id();
+
+    let (mut nodes, _tasks, _) = E2ETestSetupBuilder::<EthereumNode, _>::new(
+        1,
+        chain_spec.clone(),
+        test_attributes_generator,
+    )
+    .with_tree_config_modifier(|config| config.with_persistence_threshold(0))
+    .build()
+    .await?;
+
+    let wallets = wallet::Wallet::new(1).with_chain_id(chain_id).wallet_gen();
+    let signer = wallets[0].clone();
+
+    // Inject tx but do NOT mine
+    let raw_tx = TransactionTestContext::transfer_tx_bytes(chain_id, signer).await;
+    let tx_hash = nodes[0].rpc.inject_tx(raw_tx).await?;
+
+    // Verify tx is in pending pool via RPC
+    let client = nodes[0].rpc_client().expect("RPC client");
+    wait_for_pending_tx(&client, tx_hash).await;
+
+    let pending_tx: Option<Transaction> =
+        client.request("eth_getTransactionByHash", [tx_hash]).await?;
+    assert!(pending_tx.is_some(), "Pending tx should be visible via RPC");
+    assert!(pending_tx.unwrap().block_number.is_none(), "Pending tx should have no block_number");
+
+    // Assert tx is NOT in RocksDB before mining (single check - tx is confirmed pending)
+    let rocksdb = nodes[0].inner.provider.rocksdb_provider();
+    let tx_number: Option<u64> = rocksdb.get::<tables::TransactionHashNumbers>(tx_hash)?;
+    assert!(
+        tx_number.is_none(),
+        "Pending tx should NOT be in RocksDB before mining, but found tx_number={:?}",
+        tx_number
+    );
+
+    // Now mine the block
+    let payload = nodes[0].advance_block().await?;
+    assert_eq!(payload.block().number(), 1);
+
+    // Poll until tx appears in RocksDB
+    let tx_number = poll_tx_in_rocksdb(&nodes[0].inner.provider, tx_hash).await;
+    assert_eq!(tx_number, 0, "First tx should have tx_number 0");
+
+    // Verify tx is now mined via RPC
+    let mined_tx: Option<Transaction> =
+        client.request("eth_getTransactionByHash", [tx_hash]).await?;
+    assert_eq!(mined_tx.expect("mined tx").block_number, Some(1));
+
+    Ok(())
+}
+
+/// Reorg with `RocksDB`: verifies that unwind correctly reads changesets from
+/// storage-aware locations (static files vs MDBX) rather than directly from MDBX.
+///
+/// This test exercises `unwind_trie_state_from` which previously failed with
+/// `UnsortedInput` errors because it read changesets directly from MDBX tables
+/// instead of using storage-aware methods that check `storage_changesets_in_static_files`.
+#[tokio::test]
+async fn test_rocksdb_reorg_unwind() -> Result<()> {
+    reth_tracing::init_test_tracing();
+
+    let chain_spec = test_chain_spec();
+    let chain_id = chain_spec.chain().id();
+
+    let (mut nodes, _tasks, _) = E2ETestSetupBuilder::<EthereumNode, _>::new(
+        1,
+        chain_spec.clone(),
+        test_attributes_generator,
+    )
+    .with_tree_config_modifier(|config| config.with_persistence_threshold(0))
+    .build()
+    .await?;
+
+    assert_eq!(nodes.len(), 1);
+
+    // Use two separate wallets to avoid nonce conflicts during reorg
+    let wallets = wallet::Wallet::new(2).with_chain_id(chain_id).wallet_gen();
+    let signer1 = wallets[0].clone();
+    let signer2 = wallets[1].clone();
+    let client = nodes[0].rpc_client().expect("RPC client");
+
+    // Mine block 1 with a transaction from signer1
+    let raw_tx1 =
+        TransactionTestContext::transfer_tx_bytes_with_nonce(chain_id, signer1.clone(), 0).await;
+    let tx_hash1 = nodes[0].rpc.inject_tx(raw_tx1).await?;
+    wait_for_pending_tx(&client, tx_hash1).await;
+
+    let payload1 = nodes[0].advance_block().await?;
+    let block1_hash = payload1.block().hash();
+    assert_eq!(payload1.block().number(), 1);
+
+    // Poll until tx1 appears in RocksDB (ensures persistence happened)
+    let tx_number1 = poll_tx_in_rocksdb(&nodes[0].inner.provider, tx_hash1).await;
+    assert_eq!(tx_number1, 0, "First tx should have tx_number 0");
+
+    // Mine block 2 with transaction from signer1 (nonce 1)
+    let raw_tx2 =
+        TransactionTestContext::transfer_tx_bytes_with_nonce(chain_id, signer1.clone(), 1).await;
+    let tx_hash2 = nodes[0].rpc.inject_tx(raw_tx2).await?;
+    wait_for_pending_tx(&client, tx_hash2).await;
+
+    let payload2 = nodes[0].advance_block().await?;
+    assert_eq!(payload2.block().number(), 2);
+
+    // Poll until tx2 appears in RocksDB
+    let tx_number2 = poll_tx_in_rocksdb(&nodes[0].inner.provider, tx_hash2).await;
+    assert_eq!(tx_number2, 1, "Second tx should have tx_number 1");
+
+    // Mine block 3 with transaction from signer1 (nonce 2)
+    let raw_tx3 =
+        TransactionTestContext::transfer_tx_bytes_with_nonce(chain_id, signer1.clone(), 2).await;
+    let tx_hash3 = nodes[0].rpc.inject_tx(raw_tx3).await?;
+    wait_for_pending_tx(&client, tx_hash3).await;
+
+    let payload3 = nodes[0].advance_block().await?;
+    assert_eq!(payload3.block().number(), 3);
+
+    // Poll until tx3 appears in RocksDB
+    let tx_number3 = poll_tx_in_rocksdb(&nodes[0].inner.provider, tx_hash3).await;
+    assert_eq!(tx_number3, 2, "Third tx should have tx_number 2");
+
+    // Now create an alternate block 2 using signer2 (different wallet, avoids nonce conflict)
+    // Inject a tx from signer2 (nonce 0) before building the alternate block
+    let raw_alt_tx =
+        TransactionTestContext::transfer_tx_bytes_with_nonce(chain_id, signer2.clone(), 0).await;
+    let alt_tx_hash = nodes[0].rpc.inject_tx(raw_alt_tx).await?;
+    wait_for_pending_tx(&client, alt_tx_hash).await;
+
+    // Build an alternate payload (this builds on top of the current head, i.e., block 3)
+    // But we want to reorg back to block 1, so we'll use the payload and then FCU to it
+    let alt_payload = nodes[0].new_payload().await?;
+    let alt_block_hash = nodes[0].submit_payload(alt_payload.clone()).await?;
+
+    // Trigger reorg: make the alternate chain canonical by sending FCU pointing to block 1's hash
+    // as finalized, which should trigger an unwind of blocks 2 and 3
+    // The alt block becomes the new head
+    nodes[0].update_forkchoice(block1_hash, alt_block_hash).await?;
+
+    // Give time for the reorg to complete
+    tokio::time::sleep(Duration::from_millis(500)).await;
+
+    // Verify we can still query transactions and the chain is consistent
+    // If unwind_trie_state_from failed, this would have errored during reorg
+    let latest: Option<alloy_rpc_types_eth::Block> =
+        client.request("eth_getBlockByNumber", ("latest", false)).await?;
+    let latest = latest.expect("Latest block should exist");
+    // The alt block is at height 4 (on top of block 3)
+    assert!(latest.header.number >= 3, "Should be at height >= 3 after operation");
+
+    // tx1 from block 1 should still be there
+    let tx1: Option<Transaction> = client.request("eth_getTransactionByHash", [tx_hash1]).await?;
+    assert!(tx1.is_some(), "tx1 from block 1 should still be queryable");
+    assert_eq!(tx1.unwrap().block_number, Some(1));
+
+    // Mine another block to verify the chain can continue
+    let raw_tx_final =
+        TransactionTestContext::transfer_tx_bytes_with_nonce(chain_id, signer2.clone(), 1).await;
+    let tx_hash_final = nodes[0].rpc.inject_tx(raw_tx_final).await?;
+    wait_for_pending_tx(&client, tx_hash_final).await;
+
+    let final_payload = nodes[0].advance_block().await?;
+    assert!(final_payload.block().number() > 3, "Should be able to mine block after reorg");
+
+    // Verify tx_final is included
+    let tx_final: Option<Transaction> =
+        client.request("eth_getTransactionByHash", [tx_hash_final]).await?;
+    assert!(tx_final.is_some(), "final tx should be in latest block");
+
+    Ok(())
+}

crates/engine/local/Cargo.toml

@@ -32,9 +32,7 @@ futures-util.workspace = true
 # misc
 eyre.workspace = true
 tracing.workspace = true
-
 op-alloy-rpc-types-engine = { workspace = true, optional = true }
-reth-optimism-chainspec = { workspace = true, optional = true }
 
 [lints]
 workspace = true
@@ -42,7 +40,6 @@ workspace = true
 [features]
 op = [
     "dep:op-alloy-rpc-types-engine",
-    "dep:reth-optimism-chainspec",
     "reth-payload-primitives/op",
     "reth-primitives-traits/op",
 ]

crates/engine/local/src/payload.rs

@@ -72,13 +72,18 @@ where
         &self,
         parent: &SealedHeader<ChainSpec::Header>,
     ) -> op_alloy_rpc_types_engine::OpPayloadAttributes {
+        /// Dummy system transaction for dev mode.
+        /// OP Mainnet transaction at index 0 in block 124665056.
+        ///
+        /// <https://optimistic.etherscan.io/tx/0x312e290cf36df704a2217b015d6455396830b0ce678b860ebfcc30f41403d7b1>
+        const TX_SET_L1_BLOCK_OP_MAINNET_BLOCK_124665056: [u8; 251] = alloy_primitives::hex!(
+            "7ef8f8a0683079df94aa5b9cf86687d739a60a9b4f0835e520ec4d664e2e415dca17a6df94deaddeaddeaddeaddeaddeaddeaddeaddead00019442000000000000000000000000000000000000158080830f424080b8a4440a5e200000146b000f79c500000000000000040000000066d052e700000000013ad8a3000000000000000000000000000000000000000000000000000000003ef1278700000000000000000000000000000000000000000000000000000000000000012fdf87b89884a61e74b322bbcf60386f543bfae7827725efaaf0ab1de2294a590000000000000000000000006887246668a3b87f54deb3b94ba47a6f63f32985"
+        );
+
         op_alloy_rpc_types_engine::OpPayloadAttributes {
             payload_attributes: self.build(parent),
             // Add dummy system transaction
-            transactions: Some(vec![
-                reth_optimism_chainspec::constants::TX_SET_L1_BLOCK_OP_MAINNET_BLOCK_124665056
-                    .into(),
-            ]),
+            transactions: Some(vec![TX_SET_L1_BLOCK_OP_MAINNET_BLOCK_124665056.into()]),
             no_tx_pool: None,
             gas_limit: None,
             eip_1559_params: None,

crates/engine/primitives/src/config.rs

@@ -34,6 +34,11 @@ fn default_account_worker_count() -> usize {
 /// The size of proof targets chunk to spawn in one multiproof calculation.
 pub const DEFAULT_MULTIPROOF_TASK_CHUNK_SIZE: usize = 60;
 
+/// The size of proof targets chunk to spawn in one multiproof calculation when V2 proofs are
+/// enabled. This is 4x the default chunk size to take advantage of more efficient V2 proof
+/// computation.
+pub const DEFAULT_MULTIPROOF_TASK_CHUNK_SIZE_V2: usize = DEFAULT_MULTIPROOF_TASK_CHUNK_SIZE * 4;
+
 /// Default number of reserved CPU cores for non-reth processes.
 ///
 /// This will be deducted from the thread count of main reth global threadpool.
@@ -42,10 +47,31 @@ pub const DEFAULT_RESERVED_CPU_CORES: usize = 1;
 /// Default maximum concurrency for prewarm task.
 pub const DEFAULT_PREWARM_MAX_CONCURRENCY: usize = 16;
 
+/// Default depth for sparse trie pruning.
+///
+/// Nodes at this depth and below are converted to hash stubs to reduce memory.
+/// Depth 4 means we keep roughly 16^4 = 65536 potential branch paths at most.
+pub const DEFAULT_SPARSE_TRIE_PRUNE_DEPTH: usize = 4;
+
+/// Default maximum number of storage tries to keep after pruning.
+///
+/// Storage tries beyond this limit are cleared (but allocations preserved).
+pub const DEFAULT_SPARSE_TRIE_MAX_STORAGE_TRIES: usize = 100;
+
 const DEFAULT_BLOCK_BUFFER_LIMIT: u32 = EPOCH_SLOTS as u32 * 2;
 const DEFAULT_MAX_INVALID_HEADER_CACHE_LENGTH: u32 = 256;
 const DEFAULT_MAX_EXECUTE_BLOCK_BATCH_SIZE: usize = 4;
-const DEFAULT_CROSS_BLOCK_CACHE_SIZE: u64 = 4 * 1024 * 1024 * 1024;
+const DEFAULT_CROSS_BLOCK_CACHE_SIZE: usize = default_cross_block_cache_size();
+
+const fn default_cross_block_cache_size() -> usize {
+    if cfg!(test) {
+        1024 * 1024 // 1 MB in tests
+    } else if cfg!(target_pointer_width = "32") {
+        usize::MAX // max possible on wasm32 / 32-bit
+    } else {
+        4 * 1024 * 1024 * 1024 // 4 GB on 64-bit
+    }
+}
 
 /// Determines if the host has enough parallelism to run the payload processor.
 ///
@@ -95,12 +121,10 @@ pub struct TreeConfig {
     disable_state_cache: bool,
     /// Whether to disable parallel prewarming.
     disable_prewarming: bool,
-    /// Whether to disable the parallel sparse trie state root algorithm.
-    disable_parallel_sparse_trie: bool,
     /// Whether to enable state provider metrics.
     state_provider_metrics: bool,
     /// Cross-block cache size in bytes.
-    cross_block_cache_size: u64,
+    cross_block_cache_size: usize,
     /// Whether the host has enough parallelism to run state root task.
     has_enough_parallelism: bool,
     /// Whether multiproof task should chunk proof targets.
@@ -135,8 +159,16 @@ pub struct TreeConfig {
     storage_worker_count: usize,
     /// Number of account proof worker threads.
     account_worker_count: usize,
-    /// Whether to enable V2 storage proofs.
-    enable_proof_v2: bool,
+    /// Whether to disable V2 storage proofs.
+    disable_proof_v2: bool,
+    /// Whether to disable cache metrics recording (can be expensive with large cached state).
+    disable_cache_metrics: bool,
+    /// Whether to enable sparse trie as cache.
+    enable_sparse_trie_as_cache: bool,
+    /// Depth for sparse trie pruning after state root computation.
+    sparse_trie_prune_depth: usize,
+    /// Maximum number of storage tries to retain after pruning.
+    sparse_trie_max_storage_tries: usize,
 }
 
 impl Default for TreeConfig {
@@ -151,7 +183,6 @@ impl Default for TreeConfig {
             always_compare_trie_updates: false,
             disable_state_cache: false,
             disable_prewarming: false,
-            disable_parallel_sparse_trie: false,
             state_provider_metrics: false,
             cross_block_cache_size: DEFAULT_CROSS_BLOCK_CACHE_SIZE,
             has_enough_parallelism: has_enough_parallelism(),
@@ -165,7 +196,11 @@ impl Default for TreeConfig {
             allow_unwind_canonical_header: false,
             storage_worker_count: default_storage_worker_count(),
             account_worker_count: default_account_worker_count(),
-            enable_proof_v2: false,
+            disable_proof_v2: false,
+            disable_cache_metrics: false,
+            enable_sparse_trie_as_cache: false,
+            sparse_trie_prune_depth: DEFAULT_SPARSE_TRIE_PRUNE_DEPTH,
+            sparse_trie_max_storage_tries: DEFAULT_SPARSE_TRIE_MAX_STORAGE_TRIES,
         }
     }
 }
@@ -183,9 +218,8 @@ impl TreeConfig {
         always_compare_trie_updates: bool,
         disable_state_cache: bool,
         disable_prewarming: bool,
-        disable_parallel_sparse_trie: bool,
         state_provider_metrics: bool,
-        cross_block_cache_size: u64,
+        cross_block_cache_size: usize,
         has_enough_parallelism: bool,
         multiproof_chunking_enabled: bool,
         multiproof_chunk_size: usize,
@@ -197,7 +231,10 @@ impl TreeConfig {
         allow_unwind_canonical_header: bool,
         storage_worker_count: usize,
         account_worker_count: usize,
-        enable_proof_v2: bool,
+        disable_proof_v2: bool,
+        disable_cache_metrics: bool,
+        sparse_trie_prune_depth: usize,
+        sparse_trie_max_storage_tries: usize,
     ) -> Self {
         Self {
             persistence_threshold,
@@ -209,7 +246,6 @@ impl TreeConfig {
             always_compare_trie_updates,
             disable_state_cache,
             disable_prewarming,
-            disable_parallel_sparse_trie,
             state_provider_metrics,
             cross_block_cache_size,
             has_enough_parallelism,
@@ -223,7 +259,11 @@ impl TreeConfig {
             allow_unwind_canonical_header,
             storage_worker_count,
             account_worker_count,
-            enable_proof_v2,
+            disable_proof_v2,
+            disable_cache_metrics,
+            enable_sparse_trie_as_cache: false,
+            sparse_trie_prune_depth,
+            sparse_trie_max_storage_tries,
         }
     }
 
@@ -262,6 +302,18 @@ impl TreeConfig {
         self.multiproof_chunk_size
     }
 
+    /// Return the multiproof task chunk size, using the V2 default if V2 proofs are enabled
+    /// and the chunk size is at the default value.
+    pub const fn effective_multiproof_chunk_size(&self) -> usize {
+        if !self.disable_proof_v2 &&
+            self.multiproof_chunk_size == DEFAULT_MULTIPROOF_TASK_CHUNK_SIZE
+        {
+            DEFAULT_MULTIPROOF_TASK_CHUNK_SIZE_V2
+        } else {
+            self.multiproof_chunk_size
+        }
+    }
+
     /// Return the number of reserved CPU cores for non-reth processes
     pub const fn reserved_cpu_cores(&self) -> usize {
         self.reserved_cpu_cores
@@ -278,11 +330,6 @@ impl TreeConfig {
         self.state_provider_metrics
     }
 
-    /// Returns whether or not the parallel sparse trie is disabled.
-    pub const fn disable_parallel_sparse_trie(&self) -> bool {
-        self.disable_parallel_sparse_trie
-    }
-
     /// Returns whether or not state cache is disabled.
     pub const fn disable_state_cache(&self) -> bool {
         self.disable_state_cache
@@ -300,7 +347,7 @@ impl TreeConfig {
     }
 
     /// Returns the cross-block cache size.
-    pub const fn cross_block_cache_size(&self) -> u64 {
+    pub const fn cross_block_cache_size(&self) -> usize {
         self.cross_block_cache_size
     }
 
@@ -403,7 +450,7 @@ impl TreeConfig {
     }
 
     /// Setter for cross block cache size.
-    pub const fn with_cross_block_cache_size(mut self, cross_block_cache_size: u64) -> Self {
+    pub const fn with_cross_block_cache_size(mut self, cross_block_cache_size: usize) -> Self {
         self.cross_block_cache_size = cross_block_cache_size;
         self
     }
@@ -420,15 +467,6 @@ impl TreeConfig {
         self
     }
 
-    /// Setter for whether to disable the parallel sparse trie
-    pub const fn with_disable_parallel_sparse_trie(
-        mut self,
-        disable_parallel_sparse_trie: bool,
-    ) -> Self {
-        self.disable_parallel_sparse_trie = disable_parallel_sparse_trie;
-        self
-    }
-
     /// Setter for whether multiproof task should chunk proof targets.
     pub const fn with_multiproof_chunking_enabled(
         mut self,
@@ -490,8 +528,12 @@ impl TreeConfig {
     }
 
     /// Setter for the number of storage proof worker threads.
-    pub fn with_storage_worker_count(mut self, storage_worker_count: usize) -> Self {
-        self.storage_worker_count = storage_worker_count.max(MIN_WORKER_COUNT);
+    ///
+    /// No-op if it's [`None`].
+    pub fn with_storage_worker_count_opt(mut self, storage_worker_count: Option<usize>) -> Self {
+        if let Some(count) = storage_worker_count {
+            self.storage_worker_count = count.max(MIN_WORKER_COUNT);
+        }
         self
     }
 
@@ -501,19 +543,67 @@ impl TreeConfig {
     }
 
     /// Setter for the number of account proof worker threads.
-    pub fn with_account_worker_count(mut self, account_worker_count: usize) -> Self {
-        self.account_worker_count = account_worker_count.max(MIN_WORKER_COUNT);
+    ///
+    /// No-op if it's [`None`].
+    pub fn with_account_worker_count_opt(mut self, account_worker_count: Option<usize>) -> Self {
+        if let Some(count) = account_worker_count {
+            self.account_worker_count = count.max(MIN_WORKER_COUNT);
+        }
         self
     }
 
-    /// Return whether V2 storage proofs are enabled.
-    pub const fn enable_proof_v2(&self) -> bool {
-        self.enable_proof_v2
+    /// Return whether V2 storage proofs are disabled.
+    pub const fn disable_proof_v2(&self) -> bool {
+        self.disable_proof_v2
     }
 
-    /// Setter for whether to enable V2 storage proofs.
-    pub const fn with_enable_proof_v2(mut self, enable_proof_v2: bool) -> Self {
-        self.enable_proof_v2 = enable_proof_v2;
+    /// Setter for whether to disable V2 storage proofs.
+    pub const fn with_disable_proof_v2(mut self, disable_proof_v2: bool) -> Self {
+        self.disable_proof_v2 = disable_proof_v2;
+        self
+    }
+
+    /// Returns whether cache metrics recording is disabled.
+    pub const fn disable_cache_metrics(&self) -> bool {
+        self.disable_cache_metrics
+    }
+
+    /// Setter for whether to disable cache metrics recording.
+    pub const fn without_cache_metrics(mut self, disable_cache_metrics: bool) -> Self {
+        self.disable_cache_metrics = disable_cache_metrics;
+        self
+    }
+
+    /// Returns whether sparse trie as cache is enabled.
+    pub const fn enable_sparse_trie_as_cache(&self) -> bool {
+        self.enable_sparse_trie_as_cache
+    }
+
+    /// Setter for whether to enable sparse trie as cache.
+    pub const fn with_enable_sparse_trie_as_cache(mut self, value: bool) -> Self {
+        self.enable_sparse_trie_as_cache = value;
+        self
+    }
+
+    /// Returns the sparse trie prune depth.
+    pub const fn sparse_trie_prune_depth(&self) -> usize {
+        self.sparse_trie_prune_depth
+    }
+
+    /// Setter for sparse trie prune depth.
+    pub const fn with_sparse_trie_prune_depth(mut self, depth: usize) -> Self {
+        self.sparse_trie_prune_depth = depth;
+        self
+    }
+
+    /// Returns the maximum number of storage tries to retain after pruning.
+    pub const fn sparse_trie_max_storage_tries(&self) -> usize {
+        self.sparse_trie_max_storage_tries
+    }
+
+    /// Setter for maximum storage tries to retain.
+    pub const fn with_sparse_trie_max_storage_tries(mut self, max_tries: usize) -> Self {
+        self.sparse_trie_max_storage_tries = max_tries;
         self
     }
 }

crates/engine/primitives/src/lib.rs

@@ -62,7 +62,8 @@ pub trait EngineTypes:
                           + TryInto<Self::ExecutionPayloadEnvelopeV2>
                           + TryInto<Self::ExecutionPayloadEnvelopeV3>
                           + TryInto<Self::ExecutionPayloadEnvelopeV4>
-                          + TryInto<Self::ExecutionPayloadEnvelopeV5>,
+                          + TryInto<Self::ExecutionPayloadEnvelopeV5>
+                          + TryInto<Self::ExecutionPayloadEnvelopeV6>,
     > + DeserializeOwned
     + Serialize
 {
@@ -106,6 +107,14 @@ pub trait EngineTypes:
         + Send
         + Sync
         + 'static;
+    /// Execution Payload V6 envelope type.
+    type ExecutionPayloadEnvelopeV6: DeserializeOwned
+        + Serialize
+        + Clone
+        + Unpin
+        + Send
+        + Sync
+        + 'static;
 }
 
 /// Type that validates the payloads processed by the engine API.

crates/engine/service/Cargo.toml

@@ -17,7 +17,6 @@ reth-engine-tree.workspace = true
 reth-evm.workspace = true
 reth-network-p2p.workspace = true
 reth-payload-builder.workspace = true
-reth-ethereum-primitives.workspace = true
 reth-provider.workspace = true
 reth-prune.workspace = true
 reth-stages-api.workspace = true

crates/engine/service/src/service.rs

@@ -14,7 +14,6 @@ pub use reth_engine_tree::{
     chain::{ChainEvent, ChainOrchestrator},
     engine::EngineApiEvent,
 };
-use reth_ethereum_primitives::EthPrimitives;
 use reth_evm::ConfigureEvm;
 use reth_network_p2p::BlockClient;
 use reth_node_types::{BlockTy, NodeTypes};
@@ -97,11 +96,11 @@ where
         let downloader = BasicBlockDownloader::new(client, consensus.clone());
 
         let persistence_handle =
-            PersistenceHandle::<EthPrimitives>::spawn_service(provider, pruner, sync_metrics_tx);
+            PersistenceHandle::<N::Primitives>::spawn_service(provider, pruner, sync_metrics_tx);
 
         let canonical_in_memory_state = blockchain_db.canonical_in_memory_state();
 
-        let (to_tree_tx, from_tree) = EngineApiTreeHandler::<N::Primitives, _, _, _, _>::spawn_new(
+        let (to_tree_tx, from_tree) = EngineApiTreeHandler::spawn_new(
             blockchain_db,
             consensus,
             payload_validator,

crates/engine/tree/Cargo.toml

@@ -12,7 +12,7 @@ workspace = true
 
 [dependencies]
 # reth
-reth-chain-state.workspace = true
+reth-chain-state = { workspace = true, features = ["rayon"] }
 reth-chainspec = { workspace = true, optional = true }
 reth-consensus.workspace = true
 reth-db.workspace = true
@@ -23,7 +23,7 @@ reth-evm = { workspace = true, features = ["metrics"] }
 reth-network-p2p.workspace = true
 reth-payload-builder.workspace = true
 reth-payload-primitives.workspace = true
-reth-primitives-traits.workspace = true
+reth-primitives-traits = { workspace = true, features = ["rayon"] }
 reth-ethereum-primitives.workspace = true
 reth-provider.workspace = true
 reth-prune.workspace = true
@@ -53,7 +53,7 @@ revm-primitives.workspace = true
 futures.workspace = true
 thiserror.workspace = true
 tokio = { workspace = true, features = ["rt", "rt-multi-thread", "sync", "macros"] }
-mini-moka = { workspace = true, features = ["sync"] }
+fixed-cache.workspace = true
 moka = { workspace = true, features = ["sync"] }
 smallvec.workspace = true
 

crates/engine/tree/src/metrics.rs

@@ -20,7 +20,7 @@ pub(crate) struct PersistenceMetrics {
     /// How long it took for blocks to be saved
     pub(crate) save_blocks_duration_seconds: Histogram,
     /// How many blocks we persist at once.
-    pub(crate) save_blocks_block_count: Histogram,
+    pub(crate) save_blocks_batch_size: Histogram,
     /// How long it took for blocks to be pruned
     pub(crate) prune_before_duration_seconds: Histogram,
 }

crates/engine/tree/src/persistence.rs

@@ -12,7 +12,11 @@ use reth_provider::{
 use reth_prune::{PrunerError, PrunerOutput, PrunerWithFactory};
 use reth_stages_api::{MetricEvent, MetricEventsSender};
 use std::{
-    sync::mpsc::{Receiver, SendError, Sender},
+    sync::{
+        mpsc::{Receiver, SendError, Sender},
+        Arc,
+    },
+    thread::JoinHandle,
     time::Instant,
 };
 use thiserror::Error;
@@ -40,6 +44,12 @@ where
     metrics: PersistenceMetrics,
     /// Sender for sync metrics - we only submit sync metrics for persisted blocks
     sync_metrics_tx: MetricEventsSender,
+    /// Pending finalized block number to be committed with the next block save.
+    /// This avoids triggering a separate fsync for each finalized block update.
+    pending_finalized_block: Option<u64>,
+    /// Pending safe block number to be committed with the next block save.
+    /// This avoids triggering a separate fsync for each safe block update.
+    pending_safe_block: Option<u64>,
 }
 
 impl<N> PersistenceService<N>
@@ -53,7 +63,15 @@ where
         pruner: PrunerWithFactory<ProviderFactory<N>>,
         sync_metrics_tx: MetricEventsSender,
     ) -> Self {
-        Self { provider, incoming, pruner, metrics: PersistenceMetrics::default(), sync_metrics_tx }
+        Self {
+            provider,
+            incoming,
+            pruner,
+            metrics: PersistenceMetrics::default(),
+            sync_metrics_tx,
+            pending_finalized_block: None,
+            pending_safe_block: None,
+        }
     }
 
     /// Prunes block data before the given block number according to the configured prune
@@ -106,14 +124,10 @@ where
                     }
                 }
                 PersistenceAction::SaveFinalizedBlock(finalized_block) => {
-                    let provider = self.provider.database_provider_rw()?;
-                    provider.save_finalized_block_number(finalized_block)?;
-                    provider.commit()?;
+                    self.pending_finalized_block = Some(finalized_block);
                 }
                 PersistenceAction::SaveSafeBlock(safe_block) => {
-                    let provider = self.provider.database_provider_rw()?;
-                    provider.save_safe_block_number(safe_block)?;
-                    provider.commit()?;
+                    self.pending_safe_block = Some(safe_block);
                 }
             }
         }
@@ -126,7 +140,10 @@ where
     ) -> Result<Option<BlockNumHash>, PersistenceError> {
         debug!(target: "engine::persistence", ?new_tip_num, "Removing blocks");
         let start_time = Instant::now();
-        let provider_rw = self.provider.database_provider_rw()?;
+        // Use unwind provider to ensure correct commit order (MDBX → RocksDB → SF).
+        // This prevents crash-recovery issues where RocksDB is committed but MDBX is not,
+        // which would leave stale block numbers in RocksDB history shards.
+        let provider_rw = self.provider.unwind_provider_rw()?;
 
         let new_tip_hash = provider_rw.block_hash(new_tip_num)?;
         provider_rw.remove_block_and_execution_above(new_tip_num)?;
@@ -138,26 +155,39 @@ where
     }
 
     fn on_save_blocks(
-        &self,
+        &mut self,
         blocks: Vec<ExecutedBlock<N::Primitives>>,
     ) -> Result<Option<BlockNumHash>, PersistenceError> {
         let first_block = blocks.first().map(|b| b.recovered_block.num_hash());
         let last_block = blocks.last().map(|b| b.recovered_block.num_hash());
         let block_count = blocks.len();
+
+        // Take any pending finalized/safe block updates to commit together
+        let pending_finalized = self.pending_finalized_block.take();
+        let pending_safe = self.pending_safe_block.take();
+
         debug!(target: "engine::persistence", ?block_count, first=?first_block, last=?last_block, "Saving range of blocks");
 
         let start_time = Instant::now();
 
         if last_block.is_some() {
             let provider_rw = self.provider.database_provider_rw()?;
-
             provider_rw.save_blocks(blocks, SaveBlocksMode::Full)?;
+
+            // Commit pending finalized/safe block updates in the same transaction
+            if let Some(finalized) = pending_finalized {
+                provider_rw.save_finalized_block_number(finalized)?;
+            }
+            if let Some(safe) = pending_safe {
+                provider_rw.save_safe_block_number(safe)?;
+            }
+
             provider_rw.commit()?;
         }
 
         debug!(target: "engine::persistence", first=?first_block, last=?last_block, "Saved range of blocks");
 
-        self.metrics.save_blocks_block_count.record(block_count as f64);
+        self.metrics.save_blocks_batch_size.record(block_count as f64);
         self.metrics.save_blocks_duration_seconds.record(start_time.elapsed());
 
         Ok(last_block)
@@ -204,15 +234,25 @@ pub enum PersistenceAction<N: NodePrimitives = EthPrimitives> {
 pub struct PersistenceHandle<N: NodePrimitives = EthPrimitives> {
     /// The channel used to communicate with the persistence service
     sender: Sender<PersistenceAction<N>>,
+    /// Guard that joins the service thread when all handles are dropped.
+    /// Uses `Arc` so the handle remains `Clone`.
+    _service_guard: Arc<ServiceGuard>,
 }
 
 impl<T: NodePrimitives> PersistenceHandle<T> {
     /// Create a new [`PersistenceHandle`] from a [`Sender<PersistenceAction>`].
-    pub const fn new(sender: Sender<PersistenceAction<T>>) -> Self {
-        Self { sender }
+    ///
+    /// This is intended for testing purposes where you want to mock the persistence service.
+    /// For production use, prefer [`spawn_service`](Self::spawn_service).
+    pub fn new(sender: Sender<PersistenceAction<T>>) -> Self {
+        Self { sender, _service_guard: Arc::new(ServiceGuard(None)) }
     }
 
     /// Create a new [`PersistenceHandle`], and spawn the persistence service.
+    ///
+    /// The returned handle can be cloned and shared. When all clones are dropped, the service
+    /// thread will be joined, ensuring graceful shutdown before resources (like `RocksDB`) are
+    /// released.
     pub fn spawn_service<N>(
         provider_factory: ProviderFactory<N>,
         pruner: PrunerWithFactory<ProviderFactory<N>>,
@@ -224,13 +264,10 @@ impl<T: NodePrimitives> PersistenceHandle<T> {
         // create the initial channels
         let (db_service_tx, db_service_rx) = std::sync::mpsc::channel();
 
-        // construct persistence handle
-        let persistence_handle = PersistenceHandle::new(db_service_tx);
-
         // spawn the persistence service
         let db_service =
             PersistenceService::new(provider_factory, db_service_rx, pruner, sync_metrics_tx);
-        std::thread::Builder::new()
+        let join_handle = std::thread::Builder::new()
             .name("Persistence Service".to_string())
             .spawn(|| {
                 if let Err(err) = db_service.run() {
@@ -239,7 +276,10 @@ impl<T: NodePrimitives> PersistenceHandle<T> {
             })
             .unwrap();
 
-        persistence_handle
+        PersistenceHandle {
+            sender: db_service_tx,
+            _service_guard: Arc::new(ServiceGuard(Some(join_handle))),
+        }
     }
 
     /// Sends a specific [`PersistenceAction`] in the contained channel. The caller is responsible
@@ -267,7 +307,10 @@ impl<T: NodePrimitives> PersistenceHandle<T> {
         self.send_action(PersistenceAction::SaveBlocks(blocks, tx))
     }
 
-    /// Persists the finalized block number on disk.
+    /// Queues the finalized block number to be persisted on disk.
+    ///
+    /// The update is deferred and will be committed together with the next [`Self::save_blocks`]
+    /// call to avoid triggering a separate fsync for each update.
     pub fn save_finalized_block_number(
         &self,
         finalized_block: u64,
@@ -275,7 +318,10 @@ impl<T: NodePrimitives> PersistenceHandle<T> {
         self.send_action(PersistenceAction::SaveFinalizedBlock(finalized_block))
     }
 
-    /// Persists the safe block number on disk.
+    /// Queues the safe block number to be persisted on disk.
+    ///
+    /// The update is deferred and will be committed together with the next [`Self::save_blocks`]
+    /// call to avoid triggering a separate fsync for each update.
     pub fn save_safe_block_number(
         &self,
         safe_block: u64,
@@ -297,6 +343,27 @@ impl<T: NodePrimitives> PersistenceHandle<T> {
     }
 }
 
+/// Guard that joins the persistence service thread when dropped.
+///
+/// This ensures graceful shutdown - the service thread completes before resources like
+/// `RocksDB` are released. Stored in an `Arc` inside [`PersistenceHandle`] so the handle
+/// can be cloned while sharing the same guard.
+struct ServiceGuard(Option<JoinHandle<()>>);
+
+impl std::fmt::Debug for ServiceGuard {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_tuple("ServiceGuard").field(&self.0.as_ref().map(|_| "...")).finish()
+    }
+}
+
+impl Drop for ServiceGuard {
+    fn drop(&mut self) {
+        if let Some(join_handle) = self.0.take() {
+            let _ = join_handle.join();
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -323,12 +390,12 @@ mod tests {
     #[test]
     fn test_save_blocks_empty() {
         reth_tracing::init_test_tracing();
-        let persistence_handle = default_persistence_handle();
+        let handle = default_persistence_handle();
 
         let blocks = vec![];
         let (tx, rx) = crossbeam_channel::bounded(1);
 
-        persistence_handle.save_blocks(blocks, tx).unwrap();
+        handle.save_blocks(blocks, tx).unwrap();
 
         let hash = rx.recv().unwrap();
         assert_eq!(hash, None);
@@ -337,7 +404,7 @@ mod tests {
     #[test]
     fn test_save_blocks_single_block() {
         reth_tracing::init_test_tracing();
-        let persistence_handle = default_persistence_handle();
+        let handle = default_persistence_handle();
         let block_number = 0;
         let mut test_block_builder = TestBlockBuilder::eth();
         let executed =
@@ -347,7 +414,7 @@ mod tests {
         let blocks = vec![executed];
         let (tx, rx) = crossbeam_channel::bounded(1);
 
-        persistence_handle.save_blocks(blocks, tx).unwrap();
+        handle.save_blocks(blocks, tx).unwrap();
 
         let BlockNumHash { hash: actual_hash, number: _ } = rx
             .recv_timeout(std::time::Duration::from_secs(10))
@@ -360,14 +427,14 @@ mod tests {
     #[test]
     fn test_save_blocks_multiple_blocks() {
         reth_tracing::init_test_tracing();
-        let persistence_handle = default_persistence_handle();
+        let handle = default_persistence_handle();
 
         let mut test_block_builder = TestBlockBuilder::eth();
         let blocks = test_block_builder.get_executed_blocks(0..5).collect::<Vec<_>>();
         let last_hash = blocks.last().unwrap().recovered_block().hash();
         let (tx, rx) = crossbeam_channel::bounded(1);
 
-        persistence_handle.save_blocks(blocks, tx).unwrap();
+        handle.save_blocks(blocks, tx).unwrap();
         let BlockNumHash { hash: actual_hash, number: _ } = rx.recv().unwrap().unwrap();
         assert_eq!(last_hash, actual_hash);
     }
@@ -375,7 +442,7 @@ mod tests {
     #[test]
     fn test_save_blocks_multiple_calls() {
         reth_tracing::init_test_tracing();
-        let persistence_handle = default_persistence_handle();
+        let handle = default_persistence_handle();
 
         let ranges = [0..1, 1..2, 2..4, 4..5];
         let mut test_block_builder = TestBlockBuilder::eth();
@@ -384,7 +451,7 @@ mod tests {
             let last_hash = blocks.last().unwrap().recovered_block().hash();
             let (tx, rx) = crossbeam_channel::bounded(1);
 
-            persistence_handle.save_blocks(blocks, tx).unwrap();
+            handle.save_blocks(blocks, tx).unwrap();
 
             let BlockNumHash { hash: actual_hash, number: _ } = rx.recv().unwrap().unwrap();
             assert_eq!(last_hash, actual_hash);