fix: start static file tests from block 0, remove unused imports

Amp-Thread-ID: https://ampcode.com/threads/T-019be7bf-0e67-770d-9c38-45c6b5b286ae

.config/nextest.toml

@@ -15,3 +15,12 @@ slow-timeout = { period = "2m", terminate-after = 10 }
 [[profile.default.overrides]]
 filter = "binary(e2e_testsuite)"
 slow-timeout = { period = "2m", terminate-after = 3 }
+
+[[profile.default.overrides]]
+filter = "package(reth-era) and binary(it)"
+slow-timeout = { period = "2m", terminate-after = 10 }
+
+# Allow slower ethereum node e2e tests (p2p + blobs) to run up to 5 minutes.
+[[profile.default.overrides]]
+filter = "package(reth-node-ethereum) and binary(e2e)"
+slow-timeout = { period = "1m", terminate-after = 5 }

.config/zepter.yaml

@@ -12,7 +12,7 @@ workflows:
         # Check that `A` activates the features of `B`.
         "propagate-feature",
         # These are the features to check:
-        "--features=std,op,dev,asm-keccak,jemalloc,jemalloc-prof,tracy-allocator,serde-bincode-compat,serde,test-utils,arbitrary,bench,alloy-compat,min-error-logs,min-warn-logs,min-info-logs,min-debug-logs,min-trace-logs,otlp,js-tracer",
+        "--features=std,op,dev,asm-keccak,jemalloc,jemalloc-prof,tracy-allocator,tracy,serde-bincode-compat,serde,test-utils,arbitrary,bench,alloy-compat,min-error-logs,min-warn-logs,min-info-logs,min-debug-logs,min-trace-logs,otlp,otlp-logs,js-tracer,portable,keccak-cache-global",
         # Do not try to add a new section to `[features]` of `A` only because `B` exposes that feature. There are edge-cases where this is still needed, but we can add them manually.
         "--left-side-feature-missing=ignore",
         # Ignore the case that `A` it outside of the workspace. Otherwise it will report errors in external dependencies that we have no influence on.

.dockerignore

@@ -4,6 +4,7 @@
 # include source files
 !/bin
 !/crates
+!/pkg
 !/testing
 !book.toml
 !Cargo.lock
@@ -11,6 +12,7 @@
 !Cross.toml
 !deny.toml
 !Makefile
+!README.md
 
 # include for vergen constants
 !/.git

.github/CODEOWNERS

@@ -1,44 +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
 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/actionlint.yaml

@@ -0,0 +1,7 @@
+self-hosted-runner:
+  labels:
+    - depot-ubuntu-latest
+    - depot-ubuntu-latest-2
+    - depot-ubuntu-latest-4
+    - depot-ubuntu-latest-8
+    - depot-ubuntu-latest-16

.github/assets/hive/run_simulator.sh

@@ -7,7 +7,7 @@ sim="${1}"
 limit="${2}"
 
 run_hive() {
-    hive --sim "${sim}" --sim.limit "${limit}" --sim.parallelism 8 --client reth 2>&1 | tee /tmp/log || true
+    hive --sim "${sim}" --sim.limit "${limit}" --sim.parallelism 16 --client reth 2>&1 | tee /tmp/log || true
 }
 
 check_log() {

.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/workflows/bench.yml

@@ -11,18 +11,29 @@ env:
   CARGO_TERM_COLOR: always
   BASELINE: base
   SEED: reth
+  RUSTC_WRAPPER: "sccache"
 
 name: bench
 jobs:
   codspeed:
-    runs-on:
-      group: Reth
+    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@v5
+      - uses: actions/checkout@v6
         with:
           submodules: true
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@stable
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - uses: Swatinem/rust-cache@v2
         with:
           cache-on-failure: true
@@ -31,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/book.yml

@@ -10,13 +10,16 @@ on:
     types: [opened, reopened, synchronize, closed]
   merge_group:
 
+env:
+  RUSTC_WRAPPER: "sccache"
+
 jobs:
   build:
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-latest-8
     timeout-minutes: 90
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
 
       - name: Install bun
         uses: oven-sh/setup-bun@v2
@@ -33,6 +36,8 @@ jobs:
       - name: Install Rust nightly
         uses: dtolnay/rust-toolchain@nightly
 
+      - uses: mozilla-actions/sccache-action@v0.0.9
+
       - name: Build docs
         run: cd docs/vocs && bash scripts/build-cargo-docs.sh
 

.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/compact.yml

@@ -13,12 +13,12 @@ on:
 
 env:
   CARGO_TERM_COLOR: always
+  RUSTC_WRAPPER: "sccache"
 
 name: compact-codec
 jobs:
   compact-codec:
-    runs-on:
-      group: Reth
+    runs-on: depot-ubuntu-latest
     strategy:
       matrix:
         bin:
@@ -27,11 +27,12 @@ jobs:
     steps:
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@stable
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - uses: Swatinem/rust-cache@v2
         with:
           cache-on-failure: true
       - name: Checkout base
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           ref: ${{ github.base_ref || 'main' }}
       # On `main` branch, generates test vectors and serializes them to disk using `Compact`.
@@ -39,7 +40,7 @@ jobs:
         run: |
           ${{ matrix.bin }} -- test-vectors compact --write
       - name: Checkout PR
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           clean: false
       # On incoming merge try to read and decode previously generated vectors with `Compact`

.github/workflows/dependencies.yml

@@ -15,6 +15,6 @@ permissions:
 
 jobs:
   update:
-    uses: ithacaxyz/ci/.github/workflows/cargo-update-pr.yml@main
+    uses: tempoxyz/ci/.github/workflows/cargo-update-pr.yml@main
     secrets:
       token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/docker-git.yml

@@ -33,7 +33,7 @@ jobs:
           - 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@v5
+      - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2

.github/workflows/docker-nightly.yml

@@ -28,14 +28,18 @@ jobs:
         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@v5
+      - uses: actions/checkout@v6
       - name: Remove bloatware
         uses: laverdet/remove-bloatware@v1.0.0
         with:

.github/workflows/docker-tag-latest.yml

@@ -0,0 +1,73 @@
+# Tag a specific Docker release version as latest
+
+name: docker-tag-latest
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Release version to tag as latest (e.g., v1.8.4)'
+        required: true
+        type: string
+      tag_reth:
+        description: 'Tag reth image as latest'
+        required: false
+        type: boolean
+        default: true
+      tag_op_reth:
+        description: 'Tag op-reth image as latest'
+        required: false
+        type: boolean
+        default: false
+
+env:
+  DOCKER_USERNAME: ${{ github.actor }}
+
+jobs:
+  tag-reth-latest:
+    name: Tag reth as latest
+    runs-on: ubuntu-24.04
+    if: ${{ inputs.tag_reth }}
+    permissions:
+      packages: write
+      contents: read
+    steps:
+      - name: Log in to Docker
+        run: |
+          echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io --username ${DOCKER_USERNAME} --password-stdin
+
+      - name: Pull reth release image
+        run: |
+          docker pull ghcr.io/${{ github.repository_owner }}/reth:${{ inputs.version }}
+
+      - name: Tag reth as latest
+        run: |
+          docker tag ghcr.io/${{ github.repository_owner }}/reth:${{ inputs.version }} ghcr.io/${{ github.repository_owner }}/reth:latest
+
+      - name: Push reth latest tag
+        run: |
+          docker push ghcr.io/${{ github.repository_owner }}/reth:latest
+
+  tag-op-reth-latest:
+    name: Tag op-reth as latest
+    runs-on: ubuntu-24.04
+    if: ${{ inputs.tag_op_reth }}
+    permissions:
+      packages: write
+      contents: read
+    steps:
+      - name: Log in to Docker
+        run: |
+          echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io --username ${DOCKER_USERNAME} --password-stdin
+
+      - name: Pull op-reth release image
+        run: |
+          docker pull ghcr.io/${{ github.repository_owner }}/op-reth:${{ inputs.version }}
+
+      - name: Tag op-reth as latest
+        run: |
+          docker tag ghcr.io/${{ github.repository_owner }}/op-reth:${{ inputs.version }} ghcr.io/${{ github.repository_owner }}/op-reth:latest
+
+      - name: Push op-reth latest tag
+        run: |
+          docker push ghcr.io/${{ github.repository_owner }}/op-reth:latest

.github/workflows/docker.yml

@@ -32,7 +32,7 @@ jobs:
           - 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@v5
+      - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
@@ -68,7 +68,7 @@ jobs:
           - 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"
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2

.github/workflows/e2e.yml

@@ -11,6 +11,7 @@ on:
 env:
   CARGO_TERM_COLOR: always
   SEED: rustethereumethereumrust
+  RUSTC_WRAPPER: "sccache"
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
@@ -19,14 +20,14 @@ concurrency:
 jobs:
   test:
     name: e2e-testsuite
-    runs-on:
-      group: Reth
+    runs-on: depot-ubuntu-latest-4
     env:
       RUST_BACKTRACE: 1
     timeout-minutes: 90
     steps:
-      - uses: actions/checkout@v5
+      - 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:
@@ -43,4 +44,3 @@ jobs:
             --exclude 'op-reth' \
             --exclude 'reth' \
             -E 'binary(e2e_testsuite)'
-

.github/workflows/grafana.yml

@@ -0,0 +1,21 @@
+name: grafana
+
+on:
+  pull_request:
+  merge_group:
+  push:
+    branches: [main]
+
+jobs:
+  check-dashboard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Check for ${DS_PROMETHEUS} in overview.json
+        run: |
+          if grep -Fn '${DS_PROMETHEUS}' etc/grafana/dashboards/overview.json; then
+            echo "Error: overview.json contains '\${DS_PROMETHEUS}' placeholder"
+            echo "Please replace it with '\${datasource}'"
+            exit 1
+          fi
+          echo "✓ overview.json does not contain '\${DS_PROMETHEUS}' placeholder"

.github/workflows/hive.yml

@@ -15,11 +15,21 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  prepare-reth:
+  prepare-reth-stable:
     uses: ./.github/workflows/prepare-reth.yml
     with:
       image_tag: ghcr.io/paradigmxyz/reth:latest
       binary_name: reth
+      cargo_features: "asm-keccak"
+      artifact_name: "reth-stable"
+
+  prepare-reth-edge:
+    uses: ./.github/workflows/prepare-reth.yml
+    with:
+      image_tag: ghcr.io/paradigmxyz/reth:latest
+      binary_name: reth
+      cargo_features: "asm-keccak edge"
+      artifact_name: "reth-edge"
 
   prepare-hive:
     if: github.repository == 'paradigmxyz/reth'
@@ -27,9 +37,9 @@ jobs:
     runs-on:
       group: Reth
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - name: Checkout hive tests
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           repository: ethereum/hive
           path: hivetests
@@ -45,7 +55,7 @@ jobs:
 
       - name: Restore hive assets cache
         id: cache-hive
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: ./hive_assets
           key: hive-assets-${{ steps.hive-commit.outputs.hash }}-${{ hashFiles('.github/assets/hive/build_simulators.sh') }}
@@ -68,7 +78,7 @@ jobs:
           chmod +x hive
 
       - name: Upload hive assets
-        uses: actions/upload-artifact@v5
+        uses: actions/upload-artifact@v6
         with:
           name: hive_assets
           path: ./hive_assets
@@ -77,6 +87,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
+        storage: [stable, edge]
         # ethereum/rpc to be deprecated:
         # https://github.com/ethereum/hive/pull/1117
         scenario:
@@ -86,7 +97,7 @@ jobs:
           - sim: devp2p
             limit: discv4
           # started failing after https://github.com/ethereum/go-ethereum/pull/31843, no
-          # action on our side, remove from here when we get unxpected passes on these tests
+          # action on our side, remove from here when we get unexpected passes on these tests
           # - sim: devp2p
           #  limit: eth
           #  include:
@@ -176,28 +187,29 @@ jobs:
           - sim: ethereum/eels/consume-rlp
             limit: .*tests/paris.*
     needs:
-      - prepare-reth
+      - prepare-reth-stable
+      - prepare-reth-edge
       - prepare-hive
-    name: run ${{ matrix.scenario.sim }}${{ matrix.scenario.limit && format(' - {0}', matrix.scenario.limit) }}
+    name: ${{ matrix.storage }} / ${{ matrix.scenario.sim }}${{ matrix.scenario.limit && format(' - {0}', matrix.scenario.limit) }}
     runs-on:
       group: Reth
     permissions:
       issues: write
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: Download hive assets
-        uses: actions/download-artifact@v6
+        uses: actions/download-artifact@v7
         with:
           name: hive_assets
           path: /tmp
 
       - name: Download reth image
-        uses: actions/download-artifact@v6
+        uses: actions/download-artifact@v7
         with:
-          name: artifacts
+          name: reth-${{ matrix.storage }}
           path: /tmp
 
       - name: Load Docker images
@@ -209,7 +221,7 @@ jobs:
           chmod +x /usr/local/bin/hive
 
       - name: Checkout hive tests
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           repository: ethereum/hive
           ref: master
@@ -247,8 +259,7 @@ jobs:
   notify-on-error:
     needs: test
     if: failure()
-    runs-on:
-      group: Reth
+    runs-on: ubuntu-latest
     steps:
       - name: Slack Webhook Action
         uses: rtCamp/action-slack-notify@v2

.github/workflows/integration.yml

@@ -14,6 +14,7 @@ on:
 env:
   CARGO_TERM_COLOR: always
   SEED: rustethereumethereumrust
+  RUSTC_WRAPPER: "sccache"
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
@@ -23,8 +24,7 @@ jobs:
   test:
     name: test / ${{ matrix.network }}
     if: github.event_name != 'schedule'
-    runs-on:
-      group: Reth
+    runs-on: depot-ubuntu-latest-4
     env:
       RUST_BACKTRACE: 1
     strategy:
@@ -32,12 +32,13 @@ jobs:
         network: ["ethereum", "optimism"]
     timeout-minutes: 60
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@stable
       - name: Install Geth
         run: .github/assets/install_geth.sh
       - uses: taiki-e/install-action@nextest
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - uses: Swatinem/rust-cache@v2
         with:
           cache-on-failure: true
@@ -71,12 +72,13 @@ jobs:
     if: github.event_name == 'schedule'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@stable
       - uses: taiki-e/install-action@nextest
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - uses: Swatinem/rust-cache@v2
         with:
           cache-on-failure: true
       - name: run era1 files integration tests
-        run: cargo nextest run --package reth-era --test it -- --ignored
+        run: cargo nextest run --release --package reth-era --test it -- --ignored

.github/workflows/kurtosis-op.yml

@@ -9,7 +9,7 @@ on:
 
   push:
     tags:
-      - '*'
+      - "*"
 
 env:
   CARGO_TERM_COLOR: always
@@ -32,17 +32,16 @@ jobs:
     strategy:
       fail-fast: false
     name: run kurtosis
-    runs-on:
-      group: Reth
+    runs-on: depot-ubuntu-latest
     needs:
       - prepare-reth
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: Download reth image
-        uses: actions/download-artifact@v6
+        uses: actions/download-artifact@v7
         with:
           name: artifacts
           path: /tmp
@@ -83,12 +82,10 @@ jobs:
           kurtosis service logs -a op-devnet op-cl-2151908-2-op-node-op-reth-op-kurtosis
           exit 1
 
-
   notify-on-error:
     needs: test
     if: failure()
-    runs-on:
-      group: Reth
+    runs-on: ubuntu-latest
     steps:
       - name: Slack Webhook Action
         uses: rtCamp/action-slack-notify@v2

.github/workflows/kurtosis.yml

@@ -9,7 +9,7 @@ on:
 
   push:
     tags:
-      - '*'
+      - "*"
 
 env:
   CARGO_TERM_COLOR: always
@@ -30,17 +30,16 @@ jobs:
     strategy:
       fail-fast: false
     name: run kurtosis
-    runs-on:
-      group: Reth
+    runs-on: depot-ubuntu-latest
     needs:
       - prepare-reth
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: Download reth image
-        uses: actions/download-artifact@v6
+        uses: actions/download-artifact@v7
         with:
           name: artifacts
           path: /tmp
@@ -54,13 +53,12 @@ jobs:
       - name: Run kurtosis
         uses: ethpandaops/kurtosis-assertoor-github-action@v1
         with:
-          ethereum_package_args: '.github/assets/kurtosis_network_params.yaml'
+          ethereum_package_args: ".github/assets/kurtosis_network_params.yaml"
 
   notify-on-error:
     needs: test
     if: failure()
-    runs-on:
-      group: Reth
+    runs-on: ubuntu-latest
     steps:
       - name: Slack Webhook Action
         uses: rtCamp/action-slack-notify@v2

.github/workflows/label-pr.yml

@@ -11,7 +11,7 @@ jobs:
       issues: write
       pull-requests: write
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 

.github/workflows/lint-actions.yml

@@ -12,7 +12,7 @@ jobs:
   actionlint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - name: Download actionlint
         id: get_actionlint
         run: bash <(curl https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)

.github/workflows/lint.yml

@@ -8,11 +8,12 @@ on:
 
 env:
   CARGO_TERM_COLOR: always
+  RUSTC_WRAPPER: "sccache"
 
 jobs:
   clippy-binaries:
     name: clippy binaries / ${{ matrix.type }}
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-latest
     timeout-minutes: 30
     strategy:
       matrix:
@@ -21,11 +22,12 @@ jobs:
             args: --workspace --lib --examples --tests --benches --locked
             features: "ethereum asm-keccak jemalloc jemalloc-prof min-error-logs min-warn-logs min-info-logs min-debug-logs min-trace-logs"
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@clippy
         with:
           components: clippy
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - uses: Swatinem/rust-cache@v2
         with:
           cache-on-failure: true
@@ -40,14 +42,15 @@ jobs:
 
   clippy:
     name: clippy
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-latest
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@nightly
         with:
           components: clippy
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - uses: Swatinem/rust-cache@v2
         with:
           cache-on-failure: true
@@ -56,15 +59,16 @@ jobs:
           RUSTFLAGS: -D warnings
 
   wasm:
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-latest
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@stable
         with:
           target: wasm32-wasip1
       - uses: taiki-e/install-action@cargo-hack
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - uses: Swatinem/rust-cache@v2
         with:
           cache-on-failure: true
@@ -75,15 +79,16 @@ jobs:
           .github/assets/check_wasm.sh
 
   riscv:
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-latest
     timeout-minutes: 60
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@stable
         with:
           target: riscv32imac-unknown-none-elf
       - uses: taiki-e/install-action@cargo-hack
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - uses: Swatinem/rust-cache@v2
         with:
           cache-on-failure: true
@@ -92,21 +97,27 @@ jobs:
         run: .github/assets/check_rv32imac.sh
 
   crate-checks:
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
+    name: crate-checks (${{ matrix.partition }}/${{ matrix.total_partitions }})
+    runs-on: depot-ubuntu-latest-4
+    strategy:
+      matrix:
+        partition: [1, 2, 3]
+        total_partitions: [3]
+    timeout-minutes: 60
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@stable
       - uses: taiki-e/install-action@cargo-hack
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - uses: Swatinem/rust-cache@v2
         with:
           cache-on-failure: true
-      - run: cargo hack check --workspace
+      - run: cargo hack check --workspace --partition ${{ matrix.partition }}/${{ matrix.total_partitions }}
 
   msrv:
     name: MSRV
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-latest
     timeout-minutes: 30
     strategy:
       matrix:
@@ -114,11 +125,12 @@ jobs:
           - binary: reth
           - binary: op-reth
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@master
         with:
           toolchain: "1.88" # MSRV
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - uses: Swatinem/rust-cache@v2
         with:
           cache-on-failure: true
@@ -128,12 +140,13 @@ jobs:
 
   docs:
     name: docs
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-latest-4
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@nightly
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - uses: Swatinem/rust-cache@v2
         with:
           cache-on-failure: true
@@ -145,25 +158,27 @@ jobs:
 
   fmt:
     name: fmt
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-latest
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@nightly
         with:
           components: rustfmt
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - name: Run fmt
         run: cargo fmt --all --check
 
   udeps:
     name: udeps
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-latest
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@nightly
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - uses: Swatinem/rust-cache@v2
         with:
           cache-on-failure: true
@@ -172,19 +187,21 @@ jobs:
 
   book:
     name: book
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-latest
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@nightly
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - uses: Swatinem/rust-cache@v2
         with:
           cache-on-failure: true
-      - run: cargo build --bin reth --workspace --features ethereum
+      - run: cargo build --bin reth --workspace
+      - run: cargo build --bin op-reth --workspace
         env:
           RUSTFLAGS: -D warnings
-      - run: ./docs/cli/update.sh target/debug/reth
+      - run: ./docs/cli/update.sh target/debug/reth target/debug/op-reth
       - name: Check docs changes
         run: git diff --exit-code
 
@@ -192,7 +209,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: crate-ci/typos@v1
 
   check-toml:
@@ -200,7 +217,7 @@ jobs:
     timeout-minutes: 30
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
       - name: Run dprint
         uses: dprint/check@v2.3
         with:
@@ -210,7 +227,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - name: Check dashboard JSON with jq
         uses: sergeysova/jq-action@v2
         with:
@@ -220,39 +237,47 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@stable
       - name: Ensure no arbitrary or proptest dependency on default build
         run: cargo tree --package reth -e=features,no-dev | grep -Eq "arbitrary|proptest" && exit 1 || exit 0
 
-  # Checks that selected rates can compile with power set of features
+  # Checks that selected crates can compile with power set of features
   features:
     name: features
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-latest
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@clippy
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - uses: Swatinem/rust-cache@v2
         with:
           cache-on-failure: true
       - name: cargo install cargo-hack
         uses: taiki-e/install-action@cargo-hack
-      - run: make check-features
+      - run: |
+          cargo hack check \
+            --package reth-codecs \
+            --package reth-primitives-traits \
+            --package reth-primitives \
+            --feature-powerset \
+            --depth 2
         env:
           RUSTFLAGS: -D warnings
 
   # Check crates correctly propagate features
   feature-propagation:
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-latest
     timeout-minutes: 20
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: dtolnay/rust-toolchain@stable
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - uses: rui314/setup-mold@v1
-      - uses: taiki-e/cache-cargo-install-action@v2
+      - uses: taiki-e/cache-cargo-install-action@v3
         with:
           tool: zepter
       - name: Eagerly pull dependencies
@@ -260,7 +285,7 @@ jobs:
       - run: zepter run check
 
   deny:
-    uses: ithacaxyz/ci/.github/workflows/deny.yml@main
+    uses: tempoxyz/ci/.github/workflows/deny.yml@main
 
   lint-success:
     name: lint success

.github/workflows/prepare-reth.yml

@@ -21,15 +21,19 @@ on:
         required: false
         type: string
         description: "Optional cargo package path"
+      artifact_name:
+        required: false
+        type: string
+        default: "artifacts"
+        description: "Name for the uploaded artifact"
 
 jobs:
   prepare-reth:
     if: github.repository == 'paradigmxyz/reth'
     timeout-minutes: 45
-    runs-on:
-      group: Reth
+    runs-on: depot-ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - run: mkdir artifacts
 
       - name: Set up Docker Buildx
@@ -51,7 +55,7 @@ jobs:
 
       - name: Upload reth image
         id: upload
-        uses: actions/upload-artifact@v5
+        uses: actions/upload-artifact@v6
         with:
-          name: artifacts
+          name: ${{ inputs.artifact_name }}
           path: ./artifacts

.github/workflows/release-dist.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Update Homebrew formula
-        uses: dawidd6/action-homebrew-bump-formula@v5
+        uses: dawidd6/action-homebrew-bump-formula@v7
         with:
           token: ${{ secrets.HOMEBREW }}
           no_fork: true

.github/workflows/release-reproducible.yml

@@ -1,11 +1,11 @@
-# This workflow is for building and pushing reproducible Docker images for releases.
+# This workflow is for building and pushing reproducible artifacts for releases
 
 name: release-reproducible
 
 on:
-  push:
-    tags:
-      - v*
+  workflow_run:
+    workflows: [release]
+    types: [completed]
 
 env:
   DOCKER_REPRODUCIBLE_IMAGE_NAME: ghcr.io/${{ github.repository_owner }}/reth-reproducible
@@ -13,23 +13,41 @@ env:
 jobs:
   extract-version:
     name: extract version
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
     runs-on: ubuntu-latest
     steps:
-      - name: Extract version
-        run: echo "VERSION=$(echo ${GITHUB_REF#refs/tags/})" >> $GITHUB_OUTPUT
+      - name: Extract version from triggering tag
         id: extract_version
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Get the tag that points to the head SHA of the triggering workflow
+          TAG=$(gh api /repos/${{ github.repository }}/git/refs/tags \
+            --jq '.[] | select(.object.sha == "${{ github.event.workflow_run.head_sha }}") | .ref' \
+            | head -1 \
+            | sed 's|refs/tags/||')
+
+          if [ -z "$TAG" ]; then
+            echo "No tag found for SHA ${{ github.event.workflow_run.head_sha }}"
+            exit 1
+          fi
+
+          echo "VERSION=$TAG" >> $GITHUB_OUTPUT
     outputs:
       VERSION: ${{ steps.extract_version.outputs.VERSION }}
 
   build-reproducible:
-    name: build and push reproducible image
+    name: build and push reproducible image and binaries
     runs-on: ubuntu-latest
-    needs: extract-version
+    needs: [extract-version]
     permissions:
       packages: write
-      contents: read
+      contents: write
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ needs.extract-version.outputs.VERSION }}
+
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
@@ -40,12 +58,37 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Build and push reproducible image
+      - name: Extract Rust version
+        id: rust_version
+        run: |
+          RUST_TOOLCHAIN=$(rustc --version | cut -d' ' -f2)
+          echo "RUST_TOOLCHAIN=$RUST_TOOLCHAIN" >> $GITHUB_OUTPUT
+
+      - name: Build reproducible artifacts
+        uses: docker/build-push-action@v6
+        id: docker_build
+        with:
+          context: .
+          file: ./Dockerfile.reproducible
+          build-args: |
+            RUST_TOOLCHAIN=${{ steps.rust_version.outputs.RUST_TOOLCHAIN }}
+            VERSION=${{ needs.extract-version.outputs.VERSION }}
+          target: artifacts
+          outputs: type=local,dest=./docker-artifacts
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+        env:
+          DOCKER_BUILD_RECORD_UPLOAD: false
+
+      - name: Build and push final image
         uses: docker/build-push-action@v6
         with:
           context: .
           file: ./Dockerfile.reproducible
           push: true
+          build-args: |
+            RUST_TOOLCHAIN=${{ steps.rust_version.outputs.RUST_TOOLCHAIN }}
+            VERSION=${{ needs.extract-version.outputs.VERSION }}
           tags: |
             ${{ env.DOCKER_REPRODUCIBLE_IMAGE_NAME }}:${{ needs.extract-version.outputs.VERSION }}
             ${{ env.DOCKER_REPRODUCIBLE_IMAGE_NAME }}:latest
@@ -54,3 +97,30 @@ jobs:
           provenance: false
         env:
           DOCKER_BUILD_RECORD_UPLOAD: false
+
+      - name: Prepare artifacts from Docker build
+        run: |
+          mkdir reproducible-artifacts
+          cp docker-artifacts/reth reproducible-artifacts/reth-reproducible-${{ needs.extract-version.outputs.VERSION }}-x86_64-unknown-linux-gnu
+          cp docker-artifacts/*.deb reproducible-artifacts/reth-${{ needs.extract-version.outputs.VERSION }}-x86_64-unknown-linux-gnu-reproducible.deb
+
+      - name: Configure GPG and create artifacts
+        env:
+          GPG_SIGNING_KEY: ${{ secrets.GPG_SIGNING_KEY }}
+          GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
+        run: |
+          export GPG_TTY=$(tty)
+          echo -n "$GPG_SIGNING_KEY" | base64 --decode | gpg --batch --import
+
+          cd reproducible-artifacts
+          tar -czf reth-reproducible-${{ needs.extract-version.outputs.VERSION }}-x86_64-unknown-linux-gnu.tar.gz reth-reproducible-${{ needs.extract-version.outputs.VERSION }}-x86_64-unknown-linux-gnu --remove-files
+          echo "$GPG_PASSPHRASE" | gpg --passphrase-fd 0 --pinentry-mode loopback --batch -ab reth-reproducible-${{ needs.extract-version.outputs.VERSION }}-x86_64-unknown-linux-gnu.tar.gz
+          echo "$GPG_PASSPHRASE" | gpg --passphrase-fd 0 --pinentry-mode loopback --batch -ab reth-${{ needs.extract-version.outputs.VERSION }}-x86_64-unknown-linux-gnu-reproducible.deb
+
+      - name: Upload reproducible artifacts to release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release upload ${{ needs.extract-version.outputs.VERSION }} \
+            reproducible-artifacts/*
+

.github/workflows/release.yml

@@ -22,6 +22,7 @@ env:
   CARGO_TERM_COLOR: always
   DOCKER_IMAGE_NAME_URL: https://ghcr.io/${{ github.repository_owner }}/reth
   DOCKER_OP_IMAGE_NAME_URL: https://ghcr.io/${{ github.repository_owner }}/op-reth
+  RUSTC_WRAPPER: "sccache"
 
 jobs:
   dry-run:
@@ -49,8 +50,9 @@ jobs:
     needs: extract-version
     if: ${{ github.event.inputs.dry_run != 'true' }}
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: dtolnay/rust-toolchain@stable
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - name: Verify crate version matches tag
         # Check that the Cargo version starts with the tag,
         # so that Cargo version 1.4.8 can be matched against both v1.4.8 and v1.4.8-rc.1
@@ -78,7 +80,7 @@ jobs:
             profile: maxperf
             allow_fail: false
           - target: x86_64-apple-darwin
-            os: macos-13
+            os: macos-14
             profile: maxperf
             allow_fail: false
           - target: aarch64-apple-darwin
@@ -99,11 +101,12 @@ jobs:
           - command: op-build
             binary: op-reth
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@stable
         with:
           target: ${{ matrix.configs.target }}
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - name: Install cross main
         id: cross_main
         run: |
@@ -141,14 +144,14 @@ jobs:
 
       - name: Upload artifact
         if: ${{ github.event.inputs.dry_run != 'true' }}
-        uses: actions/upload-artifact@v5
+        uses: actions/upload-artifact@v6
         with:
           name: ${{ matrix.build.binary }}-${{ needs.extract-version.outputs.VERSION }}-${{ matrix.configs.target }}.tar.gz
           path: ${{ matrix.build.binary }}-${{ needs.extract-version.outputs.VERSION }}-${{ matrix.configs.target }}.tar.gz
 
       - name: Upload signature
         if: ${{ github.event.inputs.dry_run != 'true' }}
-        uses: actions/upload-artifact@v5
+        uses: actions/upload-artifact@v6
         with:
           name: ${{ matrix.build.binary }}-${{ needs.extract-version.outputs.VERSION }}-${{ matrix.configs.target }}.tar.gz.asc
           path: ${{ matrix.build.binary }}-${{ needs.extract-version.outputs.VERSION }}-${{ matrix.configs.target }}.tar.gz.asc
@@ -166,11 +169,11 @@ jobs:
     steps:
       # This is necessary for generating the changelog.
       # It has to come before "Download Artifacts" or else it deletes the artifacts.
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
       - name: Download artifacts
-        uses: actions/download-artifact@v6
+        uses: actions/download-artifact@v7
       - name: Generate full changelog
         id: changelog
         run: |

.github/workflows/reproducible-build.yml

@@ -8,31 +8,73 @@ on:
 jobs:
   build:
     name: build reproducible binaries
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      matrix:
+        include:
+          - runner: ubuntu-latest
+            machine: machine-1
+          - runner: ubuntu-22.04
+            machine: machine-2
     steps:
-      - uses: actions/checkout@v5
-      - uses: rui314/setup-mold@v1
+      - uses: actions/checkout@v6
+
       - uses: dtolnay/rust-toolchain@stable
         with:
           target: x86_64-unknown-linux-gnu
-      - name: Install cross main
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build reproducible binary with Docker
         run: |
-          cargo install cross --git https://github.com/cross-rs/cross
-      - name: Install cargo-cache
+          RUST_TOOLCHAIN=$(rustc --version | cut -d' ' -f2)
+          docker build \
+            --build-arg "RUST_TOOLCHAIN=${RUST_TOOLCHAIN}" \
+            -f Dockerfile.reproducible -t reth:release \
+            --target artifacts \
+            --output type=local,dest=./target .
+
+      - name: Calculate SHA256
+        id: sha256
         run: |
-          cargo install cargo-cache
-      - uses: Swatinem/rust-cache@v2
+          sha256sum target/reth > checksum.sha256
+          echo "Binaries SHA256 on ${{ matrix.machine }}: $(cat checksum.sha256)"
+
+      - name: Upload the hash
+        uses: actions/upload-artifact@v6
         with:
-          cache-on-failure: true
-      - name: Build Reth
+          name: checksum-${{ matrix.machine }}
+          path: |
+            checksum.sha256
+          retention-days: 1
+
+  compare:
+    name: compare reproducible binaries
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download artifacts from machine-1
+        uses: actions/download-artifact@v7
+        with:
+          name: checksum-machine-1
+          path: machine-1/
+      - name: Download artifacts from machine-2
+        uses: actions/download-artifact@v7
+        with:
+          name: checksum-machine-2
+          path: machine-2/
+      - name: Compare SHA256 hashes
         run: |
-          make build-reproducible
-          mv target/x86_64-unknown-linux-gnu/release/reth reth-build-1
-      - name: Clean cache
-        run: make clean && cargo cache -a
-      - name: Build Reth again
-        run: |
-          make build-reproducible
-          mv target/x86_64-unknown-linux-gnu/release/reth reth-build-2
-      - name: Compare binaries
-        run: cmp reth-build-1 reth-build-2
+          echo "=== SHA256 Comparison ==="
+          echo "Machine 1 hash:"
+          cat machine-1/checksum.sha256
+          echo "Machine 2 hash:"
+          cat machine-2/checksum.sha256
+
+          if cmp -s machine-1/checksum.sha256 machine-2/checksum.sha256; then
+            echo "✅ SUCCESS: Binaries are identical (reproducible build verified)"
+          else
+            echo "❌ FAILURE: Binaries differ (reproducible build failed)"
+            exit 1
+          fi

.github/workflows/stage.yml

@@ -12,6 +12,7 @@ env:
   CARGO_TERM_COLOR: always
   FROM_BLOCK: 0
   TO_BLOCK: 50000
+  RUSTC_WRAPPER: "sccache"
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
@@ -22,16 +23,16 @@ jobs:
     name: stage-run-test
     # Only run stage commands test in merge groups
     if: github.event_name == 'merge_group'
-    runs-on:
-      group: Reth
+    runs-on: depot-ubuntu-latest
     env:
       RUST_LOG: info,sync=error
       RUST_BACKTRACE: 1
     timeout-minutes: 60
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@stable
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - uses: Swatinem/rust-cache@v2
         with:
           cache-on-failure: true

.github/workflows/sync-era.yml

@@ -9,6 +9,7 @@ on:
 
 env:
   CARGO_TERM_COLOR: always
+  RUSTC_WRAPPER: "sccache"
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
@@ -17,8 +18,7 @@ concurrency:
 jobs:
   sync:
     name: sync (${{ matrix.chain.bin }})
-    runs-on:
-      group: Reth
+    runs-on: depot-ubuntu-latest
     env:
       RUST_LOG: info,sync=error
       RUST_BACKTRACE: 1
@@ -39,9 +39,10 @@ jobs:
             block: 10000
             unwind-target: "0x118a6e922a8c6cab221fc5adfe5056d2b72d58c6580e9c5629de55299e2cf8de"
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@stable
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - uses: Swatinem/rust-cache@v2
         with:
           cache-on-failure: true
@@ -64,4 +65,4 @@ jobs:
           ${{ matrix.chain.bin }} stage unwind num-blocks 100 --chain ${{ matrix.chain.chain }}
       - name: Run stage unwind to block hash
         run: |
-          ${{ matrix.chain.bin }} stage unwind to-block ${{ matrix.chain.unwind-target }} --chain ${{ matrix.chain.chain }} 
+          ${{ matrix.chain.bin }} stage unwind to-block ${{ matrix.chain.unwind-target }} --chain ${{ matrix.chain.chain }}

.github/workflows/sync.yml

@@ -9,6 +9,7 @@ on:
 
 env:
   CARGO_TERM_COLOR: always
+  RUSTC_WRAPPER: "sccache"
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
@@ -17,8 +18,7 @@ concurrency:
 jobs:
   sync:
     name: sync (${{ matrix.chain.bin }})
-    runs-on:
-      group: Reth
+    runs-on: depot-ubuntu-latest
     env:
       RUST_LOG: info,sync=error
       RUST_BACKTRACE: 1
@@ -39,9 +39,10 @@ jobs:
             block: 10000
             unwind-target: "0x118a6e922a8c6cab221fc5adfe5056d2b72d58c6580e9c5629de55299e2cf8de"
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@stable
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - uses: Swatinem/rust-cache@v2
         with:
           cache-on-failure: true
@@ -63,4 +64,4 @@ jobs:
           ${{ matrix.chain.bin }} stage unwind num-blocks 100 --chain ${{ matrix.chain.chain }}
       - name: Run stage unwind to block hash
         run: |
-          ${{ matrix.chain.bin }} stage unwind to-block ${{ matrix.chain.unwind-target }} --chain ${{ matrix.chain.chain }} 
+          ${{ matrix.chain.bin }} stage unwind to-block ${{ matrix.chain.unwind-target }} --chain ${{ matrix.chain.chain }}

.github/workflows/unit.yml

@@ -11,6 +11,7 @@ on:
 env:
   CARGO_TERM_COLOR: always
   SEED: rustethereumethereumrust
+  RUSTC_WRAPPER: "sccache"
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
@@ -18,35 +19,28 @@ concurrency:
 
 jobs:
   test:
-    name: test / ${{ matrix.type }} (${{ matrix.partition }}/${{ matrix.total_partitions }})
-    runs-on:
-      group: Reth
+    name: test / ${{ matrix.type }} / ${{ matrix.storage }}
+    runs-on: depot-ubuntu-latest-4
     env:
       RUST_BACKTRACE: 1
+      EDGE_FEATURES: ${{ matrix.storage == 'edge' && 'edge' || '' }}
     strategy:
       matrix:
+        type: [ethereum, optimism]
+        storage: [stable, edge]
         include:
           - type: ethereum
-            args: --features "asm-keccak ethereum" --locked
-            partition: 1
-            total_partitions: 2
-          - type: ethereum
-            args: --features "asm-keccak ethereum" --locked
-            partition: 2
-            total_partitions: 2
+            features: asm-keccak ethereum
+            exclude_args: ""
           - type: optimism
-            args: --features "asm-keccak" --locked --exclude reth --exclude reth-bench --exclude "example-*" --exclude "reth-ethereum-*" --exclude "*-ethereum"
-            partition: 1
-            total_partitions: 2
-          - type: optimism
-            args: --features "asm-keccak" --locked --exclude reth --exclude reth-bench --exclude "example-*" --exclude "reth-ethereum-*" --exclude "*-ethereum"
-            partition: 2
-            total_partitions: 2
+            features: asm-keccak
+            exclude_args: --exclude reth --exclude reth-bench --exclude "example-*" --exclude "reth-ethereum-*" --exclude "*-ethereum"
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@stable
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - uses: Swatinem/rust-cache@v2
         with:
           cache-on-failure: true
@@ -58,23 +52,22 @@ jobs:
       - name: Run tests
         run: |
           cargo nextest run \
-            ${{ matrix.args }} --workspace \
+            --features "${{ matrix.features }} $EDGE_FEATURES" --locked \
+            ${{ matrix.exclude_args }} --workspace \
             --exclude ef-tests --no-tests=warn \
-            --partition hash:${{ matrix.partition }}/2 \
             -E "!kind(test) and not binary(e2e_testsuite)"
 
   state:
     name: Ethereum state tests
-    runs-on:
-      group: Reth
+    runs-on: depot-ubuntu-latest-4
     env:
       RUST_LOG: info,sync=error
       RUST_BACKTRACE: 1
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - name: Checkout ethereum/tests
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           repository: ethereum/tests
           ref: 81862e4848585a438d64f911a19b3825f0f4cd95
@@ -93,6 +86,7 @@ jobs:
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@stable
       - uses: taiki-e/install-action@nextest
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - uses: Swatinem/rust-cache@v2
         with:
           cache-on-failure: true
@@ -100,15 +94,15 @@ jobs:
 
   doc:
     name: doc tests
-    runs-on:
-      group: Reth
+    runs-on: depot-ubuntu-latest
     env:
       RUST_BACKTRACE: 1
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@stable
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - uses: Swatinem/rust-cache@v2
         with:
           cache-on-failure: true

.github/workflows/update-superchain.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
 
       - name: Install required tools
         run: |
@@ -27,7 +27,7 @@ jobs:
           ./fetch_superchain_config.sh
 
       - name: Create Pull Request
-        uses: peter-evans/create-pull-request@v7
+        uses: peter-evans/create-pull-request@v8
         with:
           commit-message: "chore: update superchain config"
           title: "chore: update superchain config"

.github/workflows/windows.yml

@@ -9,18 +9,22 @@ on:
     branches: [main]
   merge_group:
 
+env:
+  RUSTC_WRAPPER: "sccache"
+
 jobs:
   check-reth:
-    runs-on: ubuntu-24.04
+    runs-on: depot-ubuntu-latest
     timeout-minutes: 60
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@stable
         with:
           target: x86_64-pc-windows-gnu
       - uses: taiki-e/install-action@cross
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - uses: Swatinem/rust-cache@v2
         with:
           cache-on-failure: true
@@ -30,16 +34,17 @@ jobs:
         run: cargo check --target x86_64-pc-windows-gnu
 
   check-op-reth:
-    runs-on: ubuntu-24.04
+    runs-on: depot-ubuntu-latest
     timeout-minutes: 60
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@stable
         with:
           target: x86_64-pc-windows-gnu
       - uses: taiki-e/install-action@cross
+      - uses: mozilla-actions/sccache-action@v0.0.9
       - uses: Swatinem/rust-cache@v2
         with:
           cache-on-failure: true

.gitignore

@@ -12,6 +12,9 @@ target/
 # Generated by Intellij-based IDEs.
 .idea
 
+# ck-search metadata
+.ck
+
 # Generated by MacOS
 .DS_Store
 

CLAUDE.md

@@ -18,7 +18,7 @@ Reth is a high-performance Ethereum execution client written in Rust, focusing o
 6. **Pipeline (`crates/stages/`)**: Staged sync architecture for blockchain synchronization
 7. **Trie (`crates/trie/`)**: Merkle Patricia Trie implementation with parallel state root computation
 8. **Node Builder (`crates/node/`)**: High-level node orchestration and configuration
-9  **The Consensus Engine (`crates/engine/`)**: Handles processing blocks received from the consensus layer with the Engine API (newPayload, forkchoiceUpdated)
+9. **The Consensus Engine (`crates/engine/`)**: Handles processing blocks received from the consensus layer with the Engine API (newPayload, forkchoiceUpdated)
 
 ### Key Design Principles
 
@@ -249,7 +249,7 @@ Write comments that remain valuable after the PR is merged. Future readers won't
 unsafe impl GlobalAlloc for LimitedAllocator { ... }
 
 // Binary search requires sorted input. Panics on unsorted slices.
-fn find_index(items: &[Item], target: &Item) -> Option
+fn find_index(items: &[Item], target: &Item) -> Option<usize>
 
 // Timeout set to 5s to match EVM block processing limits
 const TRACER_TIMEOUT: Duration = Duration::from_secs(5);

CONTRIBUTING.md

@@ -51,9 +51,7 @@ elsewhere.
 <!-- -   **Asking in the support Telegram:** The [Foundry Support Telegram][support-tg] is a fast and easy way to ask questions. -->
 <!-- -   **Opening a discussion:** This repository comes with a discussions board where you can also ask for help. Click the "Discussions" tab at the top. -->
 
-If you have reviewed existing documentation and still have questions, or you are having problems, you can get help by *
-*opening a discussion**. This repository comes with a discussions board where you can also ask for help. Click the "
-Discussions" tab at the top.
+If you have reviewed existing documentation and still have questions, or you are having problems, you can get help by **opening a discussion**. This repository comes with a discussions board where you can also ask for help. Click the "Discussions" tab at the top.
 
 As Reth is still in heavy development, the documentation can be a bit scattered. The [Reth Docs][reth-docs] is our
 current best-effort attempt at keeping up-to-date information.

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace.package]
-version = "1.9.0"
+version = "1.10.2"
 edition = "2024"
 rust-version = "1.88"
 license = "MIT OR Apache-2.0"
@@ -153,6 +153,7 @@ members = [
     "examples/custom-node-components/",
     "examples/custom-payload-builder/",
     "examples/custom-rlpx-subprotocol",
+    "examples/custom-rpc-middleware",
     "examples/custom-node",
     "examples/db-access",
     "examples/engine-api-access",
@@ -328,6 +329,12 @@ inherits = "release"
 lto = "fat"
 codegen-units = 1
 
+[profile.reproducible]
+inherits = "release"
+panic = "abort"
+codegen-units = 1
+incremental = false
+
 [workspace.dependencies]
 # reth
 op-reth = { path = "crates/optimism/bin" }
@@ -369,11 +376,11 @@ reth-era-utils = { path = "crates/era-utils" }
 reth-errors = { path = "crates/errors" }
 reth-eth-wire = { path = "crates/net/eth-wire" }
 reth-eth-wire-types = { path = "crates/net/eth-wire-types" }
+reth-ethereum-payload-builder = { path = "crates/ethereum/payload" }
 reth-ethereum-cli = { path = "crates/ethereum/cli", default-features = false }
 reth-ethereum-consensus = { path = "crates/ethereum/consensus", default-features = false }
 reth-ethereum-engine-primitives = { path = "crates/ethereum/engine-primitives", default-features = false }
 reth-ethereum-forks = { path = "crates/ethereum/hardforks", default-features = false }
-reth-ethereum-payload-builder = { path = "crates/ethereum/payload" }
 reth-ethereum-primitives = { path = "crates/ethereum/primitives", default-features = false }
 reth-ethereum = { path = "crates/ethereum/reth" }
 reth-etl = { path = "crates/etl" }
@@ -466,68 +473,66 @@ reth-ress-protocol = { path = "crates/ress/protocol" }
 reth-ress-provider = { path = "crates/ress/provider" }
 
 # revm
-revm = { version = "31.0.0", default-features = false }
-revm-bytecode = { version = "7.1.0", default-features = false }
-revm-database = { version = "9.0.3", default-features = false }
-revm-state = { version = "8.1.0", default-features = false }
-revm-primitives = { version = "21.0.1", default-features = false }
-revm-interpreter = { version = "29.0.0", default-features = false }
-revm-inspector = { version = "12.0.0", default-features = false }
-revm-context = { version = "11.0.0", default-features = false }
-revm-context-interface = { version = "12.0.0", default-features = false }
-revm-database-interface = { version = "8.0.4", default-features = false }
-op-revm = { version = "12.0.0", default-features = false }
-revm-inspectors = "0.32.0"
+revm = { version = "34.0.0", default-features = false }
+revm-bytecode = { version = "8.0.0", default-features = false }
+revm-database = { version = "10.0.0", default-features = false }
+revm-state = { version = "9.0.0", default-features = false }
+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"
 
 # eth
 alloy-chains = { version = "0.2.5", default-features = false }
-alloy-dyn-abi = "1.4.1"
+alloy-dyn-abi = "1.5.2"
 alloy-eip2124 = { version = "0.2.0", default-features = false }
-alloy-evm = { version = "0.23.0", default-features = false }
-alloy-primitives = { version = "1.4.1", default-features = false, features = ["map-foldhash"] }
+alloy-eip7928 = { version = "0.3.0", default-features = false }
+alloy-evm = { version = "0.27.0", default-features = false }
+alloy-primitives = { version = "1.5.0", default-features = false, features = ["map-foldhash"] }
 alloy-rlp = { version = "0.3.10", default-features = false, features = ["core-net"] }
-alloy-sol-macro = "1.4.1"
-alloy-sol-types = { version = "1.4.1", default-features = false }
+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.4"
+alloy-hardforks = "0.4.5"
 
-alloy-consensus = { version = "1.0.41", default-features = false }
-alloy-contract = { version = "1.0.41", default-features = false }
-alloy-eips = { version = "1.0.41", default-features = false }
-alloy-genesis = { version = "1.0.41", default-features = false }
-alloy-json-rpc = { version = "1.0.41", default-features = false }
-alloy-network = { version = "1.0.41", default-features = false }
-alloy-network-primitives = { version = "1.0.41", default-features = false }
-alloy-provider = { version = "1.0.41", features = ["reqwest"], default-features = false }
-alloy-pubsub = { version = "1.0.41", default-features = false }
-alloy-rpc-client = { version = "1.0.41", default-features = false }
-alloy-rpc-types = { version = "1.0.41", features = ["eth"], default-features = false }
-alloy-rpc-types-admin = { version = "1.0.41", default-features = false }
-alloy-rpc-types-anvil = { version = "1.0.41", default-features = false }
-alloy-rpc-types-beacon = { version = "1.0.41", default-features = false }
-alloy-rpc-types-debug = { version = "1.0.41", default-features = false }
-alloy-rpc-types-engine = { version = "1.0.41", default-features = false }
-alloy-rpc-types-eth = { version = "1.0.41", default-features = false }
-alloy-rpc-types-mev = { version = "1.0.41", default-features = false }
-alloy-rpc-types-trace = { version = "1.0.41", default-features = false }
-alloy-rpc-types-txpool = { version = "1.0.41", default-features = false }
-alloy-serde = { version = "1.0.41", default-features = false }
-alloy-signer = { version = "1.0.41", default-features = false }
-alloy-signer-local = { version = "1.0.41", default-features = false }
-alloy-transport = { version = "1.0.41" }
-alloy-transport-http = { version = "1.0.41", features = ["reqwest-rustls-tls"], default-features = false }
-alloy-transport-ipc = { version = "1.0.41", default-features = false }
-alloy-transport-ws = { version = "1.0.41", 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.23.0", 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.22.0", default-features = false }
-op-alloy-rpc-types-engine = { version = "0.22.0", default-features = false }
-op-alloy-network = { version = "0.22.0", default-features = false }
-op-alloy-consensus = { version = "0.22.0", default-features = false }
-op-alloy-rpc-jsonrpsee = { version = "0.22.0", default-features = false }
+op-alloy-rpc-types = { version = "0.23.1", default-features = false }
+op-alloy-rpc-types-engine = { version = "0.23.1", default-features = false }
+op-alloy-network = { version = "0.23.1", default-features = false }
+op-alloy-consensus = { version = "0.23.1", default-features = false }
+op-alloy-rpc-jsonrpsee = { version = "0.23.1", default-features = false }
 op-alloy-flz = { version = "0.13.1", default-features = false }
 
 # misc
@@ -543,14 +548,14 @@ bytes = { version = "1.5", default-features = false }
 brotli = "8"
 cfg-if = "1.0"
 clap = "4"
+color-eyre = "0.6"
 dashmap = "6.0"
 derive_more = { version = "2", default-features = false, features = ["full"] }
 dirs-next = "2.0.0"
 dyn-clone = "1.0.17"
 eyre = "0.6"
 fdlimit = "0.3.0"
-# pinned until downstream crypto libs migrate to 1.0 because 0.14.8 marks all types as deprecated
-generic-array = "=0.14.7"
+fixed-map = { version = "0.9", default-features = false }
 humantime = "2.1"
 humantime-serde = "1.1"
 itertools = { version = "0.14", default-features = false }
@@ -584,6 +589,7 @@ url = { version = "2.3", default-features = false }
 zstd = "0.13"
 byteorder = "1"
 mini-moka = "0.10"
+moka = "0.12"
 tar-no-std = { version = "0.3.2", default-features = false }
 miniz_oxide = { version = "0.8.4", default-features = false }
 chrono = "0.4.41"
@@ -591,9 +597,9 @@ chrono = "0.4.41"
 # metrics
 metrics = "0.24.0"
 metrics-derive = "0.1"
-metrics-exporter-prometheus = { version = "0.16.0", default-features = false }
+metrics-exporter-prometheus = { version = "0.18.0", default-features = false }
 metrics-process = "2.1.0"
-metrics-util = { default-features = false, version = "0.19.0" }
+metrics-util = { default-features = false, version = "0.20.0" }
 
 # proc-macros
 proc-macro2 = "1.0"
@@ -651,17 +657,22 @@ c-kzg = "2.1.5"
 # config
 toml = "0.8"
 
+# rocksdb
+rocksdb = { version = "0.24" }
+
 # otlp obs
 opentelemetry_sdk = "0.31"
 opentelemetry = "0.31"
 opentelemetry-otlp = "0.31"
 opentelemetry-semantic-conventions = "0.31"
+opentelemetry-appender-tracing = "0.31"
 tracing-opentelemetry = "0.32"
 
 # misc-testing
 arbitrary = "1.3"
 assert_matches = "1.5.0"
 criterion = { package = "codspeed-criterion-compat", version = "2.7" }
+insta = "1.41"
 proptest = "1.7"
 proptest-derive = "0.5"
 similar-asserts = { version = "1.5.0", features = ["serde"] }
@@ -675,6 +686,7 @@ ethereum_ssz = "0.9.0"
 ethereum_ssz_derive = "0.9.0"
 
 # allocators
+jemalloc_pprof = { version = "0.8", default-features = false }
 tikv-jemalloc-ctl = "0.6"
 tikv-jemallocator = "0.6"
 tracy-client = "0.18.0"
@@ -685,7 +697,7 @@ ahash = "0.8"
 anyhow = "1.0"
 bindgen = { version = "0.71", default-features = false }
 block-padding = "0.3.2"
-cc = "=1.2.15"
+cc = "1.2.15"
 cipher = "0.4.3"
 comfy-table = "7.0"
 concat-kdf = "0.1.0"
@@ -722,15 +734,20 @@ socket2 = { version = "0.5", default-features = false }
 sysinfo = { version = "0.33", default-features = false }
 tracing-journald = "0.3"
 tracing-logfmt = "0.3.3"
+tracing-samply = "0.1"
 tracing-subscriber = { version = "0.3", default-features = false }
+tracing-tracy = "0.11"
 triehash = "0.8"
 typenum = "1.15.0"
-vergen = "9.0.4"
+vergen = "9.1.0"
 visibility = "0.1.1"
 walkdir = "2.3.3"
-vergen-git2 = "1.0.5"
+vergen-git2 = "9.1.0"
 
-# [patch.crates-io]
+# networking
+ipnet = "2.11"
+
+[patch.crates-io]
 # alloy-consensus = { git = "https://github.com/alloy-rs/alloy", rev = "3049f232fbb44d1909883e154eb38ec5962f53a3" }
 # alloy-contract = { git = "https://github.com/alloy-rs/alloy", rev = "3049f232fbb44d1909883e154eb38ec5962f53a3" }
 # alloy-eips = { git = "https://github.com/alloy-rs/alloy", rev = "3049f232fbb44d1909883e154eb38ec5962f53a3" }
@@ -773,5 +790,10 @@ vergen-git2 = "1.0.5"
 # 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" }
+
+# alloy-evm = { git = "https://github.com/alloy-rs/evm", rev = "072c248" }
+# alloy-op-evm = { git = "https://github.com/alloy-rs/evm", rev = "072c248" }

Dockerfile

@@ -18,7 +18,7 @@ FROM chef AS builder
 COPY --from=planner /app/recipe.json recipe.json
 
 # Build profile, release by default
-ARG BUILD_PROFILE=release
+ARG BUILD_PROFILE=maxperf
 ENV BUILD_PROFILE=$BUILD_PROFILE
 
 # Extra Cargo flags

Dockerfile.reproducible

@@ -1,20 +1,25 @@
-# Use the Rust 1.88 image based on Debian Bookworm
-FROM rust:1.88-bookworm AS builder
+ARG RUST_TOOLCHAIN=1.89.0
+FROM docker.io/rust:$RUST_TOOLCHAIN-trixie AS builder
 
-# Install specific version of libclang-dev
-RUN apt-get update && apt-get install -y libclang-dev=1:14.0-55.7~deb12u1
-
-# Copy the project to the container
-COPY ./ /app
+ARG PROFILE
+ARG VERSION
+# Switch to snapshot repository to pin dependencies
+RUN sed -i '/^# http/{N;s|^# \(http[^ ]*\)\nURIs: .*|# \1\nURIs: \1|}' /etc/apt/sources.list.d/debian.sources
+RUN apt-get -o Acquire::Check-Valid-Until=false update && \
+    apt-get install -y \
+        libjemalloc-dev \
+        libclang-dev \
+        mold
 WORKDIR /app
+COPY . .
+RUN RUSTFLAGS_REPRODUCIBLE_EXTRA="-Clink-arg=-fuse-ld=mold" make build-reth-reproducible && \
+  PROFILE=${PROFILE:-reproducible} VERSION=$VERSION make build-deb-x86_64-unknown-linux-gnu
 
-# Build the project with the reproducible settings
-RUN make build-reproducible
+FROM scratch AS artifacts
+COPY --from=builder /app/target/x86_64-unknown-linux-gnu/reproducible/reth /reth
+COPY --from=builder /app/target/x86_64-unknown-linux-gnu/reproducible/*.deb /
 
-RUN mv /app/target/x86_64-unknown-linux-gnu/release/reth /reth
-
-# Create a minimal final image with just the binary
-FROM gcr.io/distroless/cc-debian12:nonroot-6755e21ccd99ddead6edc8106ba03888cbeed41a
-COPY --from=builder /reth /reth
+FROM gcr.io/distroless/cc-debian13:nonroot-239cdd2c8a6b275b6a6f6ed1428c57de2fff3e50
+COPY --from=artifacts /reth /reth
 EXPOSE 30303 30303/udp 9001 8545 8546
 ENTRYPOINT [ "/reth" ]

DockerfileOp

@@ -14,7 +14,7 @@ RUN cargo chef prepare --recipe-path recipe.json
 FROM chef AS builder
 COPY --from=planner /app/recipe.json recipe.json
 
-ARG BUILD_PROFILE=release
+ARG BUILD_PROFILE=maxperf
 ENV BUILD_PROFILE=$BUILD_PROFILE
 
 ARG RUSTFLAGS=""

LICENSE-APACHE

@@ -186,7 +186,7 @@ APPENDIX: How to apply the Apache License to your work.
    same "printed page" as the copyright notice for easier
    identification within third-party archives.
 
-Copyright 2022-2025 Reth Contributors
+Copyright 2022-2026 Reth Contributors
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

LICENSE-MIT

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2022-2025 Reth Contributors
+Copyright (c) 2022-2026 Reth Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Makefile

@@ -65,37 +65,31 @@ build: ## Build the reth binary into `target` directory.
 	cargo build --bin reth --features "$(FEATURES)" --profile "$(PROFILE)"
 
 # Environment variables for reproducible builds
-# Initialize RUSTFLAGS
-RUST_BUILD_FLAGS =
-# Enable static linking to ensure reproducibility across builds
-RUST_BUILD_FLAGS += --C target-feature=+crt-static
-# Set the linker to use static libgcc to ensure reproducibility across builds
-RUST_BUILD_FLAGS += -C link-arg=-static-libgcc
-# Remove build ID from the binary to ensure reproducibility across builds
-RUST_BUILD_FLAGS += -C link-arg=-Wl,--build-id=none
-# Remove metadata hash from symbol names to ensure reproducible builds
-RUST_BUILD_FLAGS += -C metadata=''
 # Set timestamp from last git commit for reproducible builds
 SOURCE_DATE ?= $(shell git log -1 --pretty=%ct)
-# Disable incremental compilation to avoid non-deterministic artifacts
-CARGO_INCREMENTAL_VAL = 0
-# Set C locale for consistent string handling and sorting
-LOCALE_VAL = C
-# Set UTC timezone for consistent time handling across builds
-TZ_VAL = UTC
 
-.PHONY: build-reproducible
-build-reproducible: ## Build the reth binary into `target` directory with reproducible builds. Only works for x86_64-unknown-linux-gnu currently
+# Extra RUSTFLAGS for reproducible builds. Can be overridden via the environment.
+RUSTFLAGS_REPRODUCIBLE_EXTRA ?=
+
+# `reproducible` only supports reth on x86_64-unknown-linux-gnu
+build-%-reproducible:
+	@if [ "$*" != "reth" ]; then \
+		echo "Error: Reproducible builds are only supported for reth, not $*"; \
+		exit 1; \
+	fi
 	SOURCE_DATE_EPOCH=$(SOURCE_DATE) \
-	RUSTFLAGS="${RUST_BUILD_FLAGS} --remap-path-prefix $$(pwd)=." \
-	CARGO_INCREMENTAL=${CARGO_INCREMENTAL_VAL} \
-	LC_ALL=${LOCALE_VAL} \
-	TZ=${TZ_VAL} \
-	cargo build --bin reth --features "$(FEATURES)" --profile "release" --locked --target x86_64-unknown-linux-gnu
+	RUSTFLAGS="-C symbol-mangling-version=v0 -C strip=none -C link-arg=-Wl,--build-id=none -C metadata='' --remap-path-prefix $$(pwd)=. $(RUSTFLAGS_REPRODUCIBLE_EXTRA)" \
+	LC_ALL=C \
+	TZ=UTC \
+	JEMALLOC_OVERRIDE=/usr/lib/x86_64-linux-gnu/libjemalloc.a \
+	cargo build --bin reth --features "$(FEATURES) jemalloc-unprefixed" --profile "reproducible" --locked --target x86_64-unknown-linux-gnu
 
 .PHONY: build-debug
 build-debug: ## Build the reth binary into `target/debug` directory.
 	cargo build --bin reth --features "$(FEATURES)"
+.PHONY: build-debug-op
+build-debug-op: ## Build the op-reth binary into `target/debug` directory.
+	cargo build --bin op-reth --features "$(FEATURES)" --manifest-path crates/optimism/bin/Cargo.toml
 
 .PHONY: build-op
 build-op: ## Build the op-reth binary into `target` directory.
@@ -155,6 +149,22 @@ op-build-x86_64-apple-darwin:
 op-build-aarch64-apple-darwin:
 	$(MAKE) op-build-native-aarch64-apple-darwin
 
+build-deb-%:
+	@case "$*" in \
+		x86_64-unknown-linux-gnu|aarch64-unknown-linux-gnu|riscv64gc-unknown-linux-gnu) \
+			echo "Building debian package for $*"; \
+			;; \
+		*) \
+			echo "Error: Debian packages are only supported for x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, and riscv64gc-unknown-linux-gnu, not $*"; \
+			exit 1; \
+			;; \
+	esac
+	cargo install cargo-deb@3.6.0 --locked
+	cargo deb --profile $(PROFILE) --no-build --no-dbgsym --no-strip \
+		--target $* \
+		$(if $(VERSION),--deb-version "1~$(VERSION)") \
+		$(if $(VERSION),--output "target/$*/$(PROFILE)/reth-$(VERSION)-$*-$(PROFILE).deb")
+
 # Create a `.tar.gz` containing a binary for a specific target.
 define tarball_release_binary
 	cp $(CARGO_TARGET_DIR)/$(1)/$(PROFILE)/$(2) $(BIN_DIR)/$(2)
@@ -266,13 +276,18 @@ docker-build-push-latest: ## Build and push a cross-arch Docker image tagged wit
 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) build-x86_64-unknown-linux-gnu
+	$(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) build-aarch64-unknown-linux-gnu
+	$(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
 
@@ -318,6 +333,11 @@ op-docker-build-push-latest: ## Build and push a cross-arch Docker image tagged
 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`
@@ -337,11 +357,11 @@ op-docker-build-push-nightly-profiling: ## Build and push cross-arch Docker imag
 
 # Create a cross-arch Docker image with the given tags and push it
 define op_docker_build_push
-	$(MAKE) op-build-x86_64-unknown-linux-gnu
+	$(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) op-build-aarch64-unknown-linux-gnu
+	$(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
 
@@ -380,9 +400,9 @@ db-tools: ## Compile MDBX debugging tools.
 	@echo "Run \"$(DB_TOOLS_DIR)/mdbx_chk\" for the MDBX db file integrity check."
 
 .PHONY: update-book-cli
-update-book-cli: build-debug ## Update book cli documentation.
+update-book-cli: build-debug build-debug-op## Update book cli documentation.
 	@echo "Updating book cli doc..."
-	@./docs/cli/update.sh $(CARGO_TARGET_DIR)/debug/reth
+	@./docs/cli/update.sh $(CARGO_TARGET_DIR)/debug/reth $(CARGO_TARGET_DIR)/debug/op-reth
 
 .PHONY: profiling
 profiling: ## Builds `reth` with optimisations, but also symbols.
@@ -511,10 +531,3 @@ pr:
 	make update-book-cli && \
 	cargo docs --document-private-items && \
 	make test
-
-check-features:
-	cargo hack check \
-		--package reth-codecs \
-		--package reth-primitives-traits \
-		--package reth-primitives \
-		--feature-powerset

README.md

@@ -44,7 +44,7 @@ More historical context below:
 -   We released 1.0 "production-ready" stable Reth in June 2024.
     -   Reth completed an audit with [Sigma Prime](https://sigmaprime.io/), the developers of [Lighthouse](https://github.com/sigp/lighthouse), the Rust Consensus Layer implementation. Find it [here](./audit/sigma_prime_audit_v2.pdf).
     -   Revm (the EVM used in Reth) underwent an audit with [Guido Vranken](https://x.com/guidovranken) (#1 [Ethereum Bug Bounty](https://ethereum.org/en/bug-bounty)). We will publish the results soon.
--   We released multiple iterative beta versions, up to [beta.9](https://github.com/paradigmxyz/reth/releases/tag/v0.2.0-beta.9) on Monday June 3, 2024,the last beta release.
+-   We released multiple iterative beta versions, up to [beta.9](https://github.com/paradigmxyz/reth/releases/tag/v0.2.0-beta.9) on Monday June 3, 2024, the last beta release.
 -   We released [beta](https://github.com/paradigmxyz/reth/releases/tag/v0.2.0-beta.1) on Monday March 4, 2024, our first breaking change to the database model, providing faster query speed, smaller database footprint, and allowing "history" to be mounted on separate drives.
 -   We shipped iterative improvements until the last alpha release on February 28, 2024, [0.1.0-alpha.21](https://github.com/paradigmxyz/reth/releases/tag/v0.1.0-alpha.21).
 -   We [initially announced](https://www.paradigm.xyz/2023/06/reth-alpha) [0.1.0-alpha.1](https://github.com/paradigmxyz/reth/releases/tag/v0.1.0-alpha.1) on June 20, 2023.

bin/reth-bench-compare/Cargo.toml

@@ -25,7 +25,9 @@ reth-chainspec.workspace = true
 
 # alloy
 alloy-provider = { workspace = true, features = ["reqwest-rustls-tls"], default-features = false }
+alloy-rpc-client = { workspace = true, features = ["pubsub"] }
 alloy-rpc-types-eth.workspace = true
+alloy-transport-ws.workspace = true
 alloy-primitives.workspace = true
 
 # CLI and argument parsing
@@ -69,7 +71,11 @@ jemalloc = [
     "reth-node-core/jemalloc",
 ]
 jemalloc-prof = ["reth-cli-util/jemalloc-prof"]
-tracy-allocator = ["reth-cli-util/tracy-allocator"]
+tracy-allocator = ["reth-cli-util/tracy-allocator", "tracy"]
+tracy = [
+    "reth-node-core/tracy",
+    "reth-tracing/tracy",
+]
 
 min-error-logs = [
     "tracing/release_max_level_error",

bin/reth-bench-compare/README.md

@@ -0,0 +1,50 @@
+# reth-bench-compare
+
+Compare reth performance between two git references.
+
+## Usage
+
+```bash
+reth-bench-compare \
+  --baseline-ref main \
+  --feature-ref my-feature \
+  --blocks 100 \
+  --wait-for-persistence
+```
+
+## Arguments
+
+| Argument | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `--baseline-ref <REF>` | Git reference for baseline | - | Yes |
+| `--feature-ref <REF>` | Git reference to compare | - | Yes |
+| `--blocks <N>` | Number of blocks to benchmark | `100` | No |
+| `--chain <CHAIN>` | Chain to benchmark | `mainnet` | No |
+| `--datadir <PATH>` | Data directory path | OS-specific | No |
+| `--rpc-url <URL>` | RPC endpoint for block data | Chain default | No |
+| `--output-dir <PATH>` | Output directory | `./reth-bench-compare` | No |
+| `--wait-for-persistence` | Wait for block persistence | `false` | No |
+| `--persistence-threshold <N>` | Wait after every N+1 blocks | `2` | No |
+| `--wait-time <DURATION>` | Fixed delay (legacy) | - | No |
+| `--warmup-blocks <N>` | Cache warmup blocks | Same as `--blocks` | No |
+| `--draw` | Generate charts (needs Python/uv) | `false` | No |
+| `--profile` | Enable CPU profiling (needs samply) | `false` | No |
+| `-vvvv` | Debug logging | Info | No |
+| `--features <FEATURES>` | Rust features for both builds | `jemalloc,asm-keccak` | No |
+| `--rustflags <FLAGS>` | RUSTFLAGS for both builds | `-C target-cpu=native` | No |
+| `--baseline-features <FEATURES>` | Features for baseline only | Inherits `--features` | No |
+| `--feature-features <FEATURES>` | Features for feature only | Inherits `--features` | No |
+| `--baseline-rustflags <FLAGS>` | RUSTFLAGS for baseline only | Inherits `--rustflags` | No |
+| `--feature-rustflags <FLAGS>` | RUSTFLAGS for feature only | Inherits `--rustflags` | No |
+| `--baseline-args <ARGS>` | Extra args for baseline node | - | No |
+| `--feature-args <ARGS>` | Extra args for feature node | - | No |
+| `--metrics-port <PORT>` | Metrics endpoint port | `5005` | No |
+| `--sudo` | Run with elevated privileges | `false` | No |
+
+## Output
+
+Results in `./reth-bench-compare/results/<timestamp>/`:
+- `comparison_report.json` - Metrics comparison
+- `per_block_comparison.csv` - Per-block statistics
+- `baseline/` and `feature/` - Individual run results
+- `latency_comparison.png` - Chart (if `--draw` used)

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

@@ -18,6 +18,8 @@ pub(crate) struct BenchmarkRunner {
     rpc_url: String,
     jwt_secret: String,
     wait_time: Option<String>,
+    wait_for_persistence: bool,
+    persistence_threshold: Option<u64>,
     warmup_blocks: u64,
 }
 
@@ -28,6 +30,8 @@ impl BenchmarkRunner {
             rpc_url: args.get_rpc_url(),
             jwt_secret: args.jwt_secret_path().to_string_lossy().to_string(),
             wait_time: args.wait_time.clone(),
+            wait_for_persistence: args.wait_for_persistence,
+            persistence_threshold: args.persistence_threshold,
             warmup_blocks: args.get_warmup_blocks(),
         }
     }
@@ -96,14 +100,11 @@ impl BenchmarkRunner {
             &from_block.to_string(),
             "--to",
             &to_block.to_string(),
+            "--wait-time=0ms", // Warmup should avoid persistence waits.
         ]);
 
-        // Add wait-time argument if provided
-        if let Some(ref wait_time) = self.wait_time {
-            cmd.args(["--wait-time", wait_time]);
-        }
-
-        cmd.stdout(std::process::Stdio::piped())
+        cmd.env("RUST_LOG_STYLE", "never")
+            .stdout(std::process::Stdio::piped())
             .stderr(std::process::Stdio::piped())
             .kill_on_drop(true);
 
@@ -185,12 +186,20 @@ impl BenchmarkRunner {
             &output_dir.to_string_lossy(),
         ]);
 
-        // Add wait-time argument if provided
+        // Configure wait mode: wait-time takes precedence over persistence-based flow
         if let Some(ref wait_time) = self.wait_time {
             cmd.args(["--wait-time", wait_time]);
+        } else if self.wait_for_persistence {
+            cmd.arg("--wait-for-persistence");
+
+            // Add persistence threshold if specified
+            if let Some(threshold) = self.persistence_threshold {
+                cmd.args(["--persistence-threshold", &threshold.to_string()]);
+            }
         }
 
-        cmd.stdout(std::process::Stdio::piped())
+        cmd.env("RUST_LOG_STYLE", "never")
+            .stdout(std::process::Stdio::piped())
             .stderr(std::process::Stdio::piped())
             .kill_on_drop(true);
 

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

@@ -5,7 +5,7 @@ use clap::Parser;
 use eyre::{eyre, Result, WrapErr};
 use reth_chainspec::Chain;
 use reth_cli_runner::CliContext;
-use reth_node_core::args::{DatadirArgs, LogArgs};
+use reth_node_core::args::{DatadirArgs, LogArgs, TraceArgs};
 use reth_tracing::FileWorkerGuard;
 use std::{net::TcpListener, path::PathBuf, str::FromStr};
 use tokio::process::Command;
@@ -114,10 +114,29 @@ pub(crate) struct Args {
     #[arg(long)]
     pub profile: bool,
 
-    /// Wait time between engine API calls (passed to reth-bench)
-    #[arg(long, value_name = "DURATION")]
+    /// Optional fixed delay between engine API calls (passed to reth-bench).
+    ///
+    /// When set, reth-bench uses wait-time mode and disables persistence-based flow.
+    /// This flag remains for compatibility with older scripts.
+    #[arg(long, value_name = "DURATION", hide = true)]
     pub wait_time: Option<String>,
 
+    /// Wait for blocks to be persisted before sending the next batch (passed to reth-bench).
+    ///
+    /// When enabled, waits for every Nth block to be persisted using the
+    /// `reth_subscribePersistedBlock` subscription. This ensures the benchmark
+    /// doesn't outpace persistence.
+    #[arg(long)]
+    pub wait_for_persistence: bool,
+
+    /// Engine persistence threshold (passed to reth-bench).
+    ///
+    /// 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, value_name = "PERSISTENCE_THRESHOLD")]
+    pub persistence_threshold: Option<u64>,
+
     /// Number of blocks to run for cache warmup after clearing caches.
     /// If not specified, defaults to the same as --blocks
     #[arg(long, value_name = "N")]
@@ -128,9 +147,27 @@ pub(crate) struct Args {
     #[arg(long)]
     pub no_clear_cache: bool,
 
+    /// Skip waiting for the node to sync before starting benchmarks.
+    /// When enabled, assumes the node is already synced and skips the initial tip check.
+    #[arg(long)]
+    pub skip_wait_syncing: bool,
+
     #[command(flatten)]
     pub logs: LogArgs,
 
+    #[command(flatten)]
+    pub traces: TraceArgs,
+
+    /// Maximum queue size for OTLP Batch Span Processor (traces).
+    /// Higher values prevent trace drops when benchmarking many blocks.
+    #[arg(
+        long,
+        value_name = "OTLP_BUFFER_SIZE",
+        default_value = "32768",
+        help_heading = "Tracing"
+    )]
+    pub otlp_max_queue_size: usize,
+
     /// Additional arguments to pass to baseline reth node command
     ///
     /// Example: `--baseline-args "--debug.tip 0xabc..."`
@@ -151,12 +188,42 @@ pub(crate) struct Args {
     #[arg(trailing_var_arg = true, allow_hyphen_values = true)]
     pub reth_args: Vec<String>,
 
-    /// Comma-separated list of features to enable during reth compilation
+    /// Comma-separated list of features to enable during reth compilation (applied to both builds)
     ///
     /// Example: `jemalloc,asm-keccak`
     #[arg(long, value_name = "FEATURES", default_value = "jemalloc,asm-keccak")]
     pub features: String,
 
+    /// Comma-separated list of features to enable only for baseline build (overrides --features)
+    ///
+    /// Example: `--baseline-features jemalloc`
+    #[arg(long, value_name = "FEATURES")]
+    pub baseline_features: Option<String>,
+
+    /// Comma-separated list of features to enable only for feature build (overrides --features)
+    ///
+    /// Example: `--feature-features jemalloc,asm-keccak`
+    #[arg(long, value_name = "FEATURES")]
+    pub feature_features: Option<String>,
+
+    /// RUSTFLAGS to use for both baseline and feature builds
+    ///
+    /// Example: `--rustflags "-C target-cpu=native"`
+    #[arg(long, value_name = "FLAGS", default_value = "-C target-cpu=native")]
+    pub rustflags: String,
+
+    /// RUSTFLAGS to use only for baseline build (overrides --rustflags)
+    ///
+    /// Example: `--baseline-rustflags "-C target-cpu=native -C lto"`
+    #[arg(long, value_name = "FLAGS")]
+    pub baseline_rustflags: Option<String>,
+
+    /// RUSTFLAGS to use only for feature build (overrides --rustflags)
+    ///
+    /// Example: `--feature-rustflags "-C target-cpu=native -C lto"`
+    #[arg(long, value_name = "FLAGS")]
+    pub feature_rustflags: Option<String>,
+
     /// Disable automatic --debug.startup-sync-state-idle flag for specific runs.
     /// Can be "baseline", "feature", or "all".
     /// By default, the flag is passed to warmup, baseline, and feature runs.
@@ -315,7 +382,6 @@ pub(crate) async fn run_comparison(args: Args, _ctx: CliContext) -> Result<()> {
         git_manager.repo_root().to_string(),
         output_dir.clone(),
         git_manager.clone(),
-        args.features.clone(),
     )?;
     // Initialize node manager
     let mut node_manager = NodeManager::new(&args);
@@ -435,6 +501,18 @@ async fn run_compilation_phase(
         let ref_type = ref_types[i];
         let commit = &ref_commits[git_ref];
 
+        // Get per-build features and rustflags
+        let features = match ref_type {
+            "baseline" => args.baseline_features.as_ref().unwrap_or(&args.features),
+            "feature" => args.feature_features.as_ref().unwrap_or(&args.features),
+            _ => &args.features,
+        };
+        let rustflags = match ref_type {
+            "baseline" => args.baseline_rustflags.as_ref().unwrap_or(&args.rustflags),
+            "feature" => args.feature_rustflags.as_ref().unwrap_or(&args.rustflags),
+            _ => &args.rustflags,
+        };
+
         info!(
             "Compiling {} binary for reference: {} (commit: {})",
             ref_type,
@@ -446,7 +524,7 @@ async fn run_compilation_phase(
         git_manager.switch_ref(git_ref)?;
 
         // Compile reth (with caching)
-        compilation_manager.compile_reth(commit, is_optimism)?;
+        compilation_manager.compile_reth(commit, is_optimism, features, rustflags)?;
 
         info!("Completed compilation for {} reference", ref_type);
     }
@@ -458,6 +536,7 @@ async fn run_compilation_phase(
     Ok((baseline_commit, feature_commit))
 }
 
+#[allow(clippy::too_many_arguments)]
 /// Run warmup phase to warm up caches before benchmarking
 async fn run_warmup_phase(
     git_manager: &GitManager,
@@ -467,9 +546,15 @@ async fn run_warmup_phase(
     args: &Args,
     is_optimism: bool,
     baseline_commit: &str,
+    starting_tip: u64,
 ) -> Result<()> {
     info!("=== Running warmup phase ===");
 
+    // Unwind to starting block minus warmup blocks, so we end up back at starting_tip
+    let warmup_blocks = args.get_warmup_blocks();
+    let unwind_target = starting_tip.saturating_sub(warmup_blocks);
+    node_manager.unwind_to_block(unwind_target).await?;
+
     // Use baseline for warmup
     let warmup_ref = &args.baseline_ref;
 
@@ -493,17 +578,18 @@ async fn run_warmup_phase(
     // Build additional args with conditional --debug.startup-sync-state-idle flag
     let additional_args = args.build_additional_args("warmup", args.baseline_args.as_ref());
 
-    // Start reth node for warmup
-    let mut node_process =
+    // Start reth node for warmup (command is not stored for warmup phase)
+    let (mut node_process, _warmup_command) =
         node_manager.start_node(&binary_path, warmup_ref, "warmup", &additional_args).await?;
 
     // Wait for node to be ready and get its current tip
-    let current_tip = node_manager.wait_for_node_ready_and_get_tip().await?;
+    let current_tip = if args.skip_wait_syncing {
+        node_manager.wait_for_rpc_and_get_tip(&mut node_process).await?
+    } else {
+        node_manager.wait_for_node_ready_and_get_tip(&mut node_process).await?
+    };
     info!("Warmup node is ready at tip: {}", current_tip);
 
-    // Store the tip we'll unwind back to
-    let original_tip = current_tip;
-
     // Clear filesystem caches before warmup run only (unless disabled)
     if args.no_clear_cache {
         info!("Skipping filesystem cache clearing (--no-clear-cache flag set)");
@@ -514,12 +600,9 @@ async fn run_warmup_phase(
     // Run warmup to warm up caches
     benchmark_runner.run_warmup(current_tip).await?;
 
-    // Stop node before unwinding (node must be stopped to release database lock)
+    // Stop node after warmup
     node_manager.stop_node(&mut node_process).await?;
 
-    // Unwind back to starting block after warmup
-    node_manager.unwind_to_block(original_tip).await?;
-
     info!("Warmup phase completed");
     Ok(())
 }
@@ -541,6 +624,31 @@ async fn run_benchmark_workflow(
     let (baseline_commit, feature_commit) =
         run_compilation_phase(git_manager, compilation_manager, args, is_optimism).await?;
 
+    // Switch to baseline reference and get the starting tip
+    git_manager.switch_ref(&args.baseline_ref)?;
+    let binary_path =
+        compilation_manager.get_cached_binary_path_for_commit(&baseline_commit, is_optimism);
+    if !binary_path.exists() {
+        return Err(eyre!(
+            "Cached baseline binary not found at {:?}. Compilation phase should have created it.",
+            binary_path
+        ));
+    }
+
+    // Start node briefly to get the current tip, then stop it
+    info!("=== Determining initial block height ===");
+    let additional_args = args.build_additional_args("baseline", args.baseline_args.as_ref());
+    let (mut node_process, _) = node_manager
+        .start_node(&binary_path, &args.baseline_ref, "baseline", &additional_args)
+        .await?;
+    let starting_tip = if args.skip_wait_syncing {
+        node_manager.wait_for_rpc_and_get_tip(&mut node_process).await?
+    } else {
+        node_manager.wait_for_node_ready_and_get_tip(&mut node_process).await?
+    };
+    info!("Node starting tip: {}", starting_tip);
+    node_manager.stop_node(&mut node_process).await?;
+
     // Run warmup phase before benchmarking (skip if warmup_blocks is 0)
     if args.get_warmup_blocks() > 0 {
         run_warmup_phase(
@@ -551,6 +659,7 @@ async fn run_benchmark_workflow(
             args,
             is_optimism,
             &baseline_commit,
+            starting_tip,
         )
         .await?;
     } else {
@@ -566,6 +675,10 @@ async fn run_benchmark_workflow(
         let commit = commits[i];
         info!("=== Processing {} reference: {} ===", ref_type, git_ref);
 
+        // Unwind to starting block minus benchmark blocks, so we end up back at starting_tip
+        let unwind_target = starting_tip.saturating_sub(args.blocks);
+        node_manager.unwind_to_block(unwind_target).await?;
+
         // Switch to target reference
         git_manager.switch_ref(git_ref)?;
 
@@ -594,22 +707,23 @@ async fn run_benchmark_workflow(
         // Build additional args with conditional --debug.startup-sync-state-idle flag
         let additional_args = args.build_additional_args(ref_type, base_args_str);
 
-        // Start reth node
-        let mut node_process =
+        // Start reth node and capture the command for reporting
+        let (mut node_process, reth_command) =
             node_manager.start_node(&binary_path, git_ref, ref_type, &additional_args).await?;
 
         // Wait for node to be ready and get its current tip (wherever it is)
-        let current_tip = node_manager.wait_for_node_ready_and_get_tip().await?;
+        let current_tip = if args.skip_wait_syncing {
+            node_manager.wait_for_rpc_and_get_tip(&mut node_process).await?
+        } else {
+            node_manager.wait_for_node_ready_and_get_tip(&mut node_process).await?
+        };
         info!("Node is ready at tip: {}", current_tip);
 
-        // Store the tip we'll unwind back to
-        let original_tip = current_tip;
-
         // Calculate benchmark range
         // Note: reth-bench has an off-by-one error where it consumes the first block
         // of the range, so we add 1 to compensate and get exactly args.blocks blocks
-        let from_block = original_tip;
-        let to_block = original_tip + args.blocks;
+        let from_block = current_tip;
+        let to_block = current_tip + args.blocks;
 
         // Run benchmark
         let output_dir = comparison_generator.get_ref_output_dir(ref_type);
@@ -626,14 +740,12 @@ async fn run_benchmark_workflow(
         // Stop node
         node_manager.stop_node(&mut node_process).await?;
 
-        // Unwind back to original tip
-        node_manager.unwind_to_block(original_tip).await?;
-
         // Store results for comparison
         comparison_generator.add_ref_results(ref_type, &output_dir)?;
 
-        // Set the benchmark run timestamps
+        // Set the benchmark run timestamps and reth command
         comparison_generator.set_ref_timestamps(ref_type, benchmark_start, benchmark_end)?;
+        comparison_generator.set_ref_command(ref_type, reth_command)?;
 
         info!("Completed {} reference benchmark", ref_type);
     }

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

@@ -6,6 +6,7 @@ use csv::Reader;
 use eyre::{eyre, Result, WrapErr};
 use serde::{Deserialize, Serialize};
 use std::{
+    cmp::Ordering,
     collections::HashMap,
     fs,
     path::{Path, PathBuf},
@@ -20,6 +21,8 @@ pub(crate) struct ComparisonGenerator {
     feature_ref_name: String,
     baseline_results: Option<BenchmarkResults>,
     feature_results: Option<BenchmarkResults>,
+    baseline_command: Option<String>,
+    feature_command: Option<String>,
 }
 
 /// Represents the results from a single benchmark run
@@ -36,6 +39,8 @@ pub(crate) struct BenchmarkResults {
 #[derive(Debug, Clone, Deserialize, Serialize)]
 pub(crate) struct CombinedLatencyRow {
     pub block_number: u64,
+    #[serde(default)]
+    pub transaction_count: Option<u64>,
     pub gas_used: u64,
     pub new_payload_latency: u128,
 }
@@ -44,19 +49,31 @@ pub(crate) struct CombinedLatencyRow {
 #[derive(Debug, Clone, Deserialize, Serialize)]
 pub(crate) struct TotalGasRow {
     pub block_number: u64,
+    #[serde(default)]
+    pub transaction_count: Option<u64>,
     pub gas_used: u64,
     pub time: u128,
 }
 
-/// Summary statistics for a benchmark run
+/// Summary statistics for a benchmark run.
+///
+/// Latencies are derived from per-block `engine_newPayload` timings (converted from µs to ms):
+/// - `mean_new_payload_latency_ms`: arithmetic mean latency across blocks.
+/// - `median_new_payload_latency_ms`: p50 latency across blocks.
+/// - `p90_new_payload_latency_ms` / `p99_new_payload_latency_ms`: tail latencies across blocks.
 #[derive(Debug, Clone, Serialize)]
 pub(crate) struct BenchmarkSummary {
     pub total_blocks: u64,
     pub total_gas_used: u64,
     pub total_duration_ms: u128,
-    pub avg_new_payload_latency_ms: f64,
+    pub mean_new_payload_latency_ms: f64,
+    pub median_new_payload_latency_ms: f64,
+    pub p90_new_payload_latency_ms: f64,
+    pub p99_new_payload_latency_ms: f64,
     pub gas_per_second: f64,
     pub blocks_per_second: f64,
+    pub min_block_number: u64,
+    pub max_block_number: u64,
 }
 
 /// Comparison report between two benchmark runs
@@ -76,12 +93,34 @@ pub(crate) struct RefInfo {
     pub summary: BenchmarkSummary,
     pub start_timestamp: Option<DateTime<Utc>>,
     pub end_timestamp: Option<DateTime<Utc>>,
+    pub reth_command: Option<String>,
 }
 
-/// Summary of the comparison between references
+/// Summary of the comparison between references.
+///
+/// Percent deltas are `(feature - baseline) / baseline * 100`:
+/// - `new_payload_latency_mean_change_percent`: percent changes of the per-block means.
+/// - `new_payload_latency_p50_change_percent` / p90 / p99: percent changes of the respective
+///   per-block percentiles.
+/// - `per_block_latency_change_mean_percent` / `per_block_latency_change_median_percent` are the
+///   mean and median of per-block percent deltas (feature vs baseline), capturing block-level
+///   drift.
+/// - `per_block_latency_change_std_dev_percent`: standard deviation of per-block percent changes,
+///   measuring consistency of performance changes across blocks.
+/// - `new_payload_total_latency_change_percent` is the percent change of the total newPayload time
+///   across the run.
+///
+/// Positive means slower/higher; negative means faster/lower.
 #[derive(Debug, Serialize)]
 pub(crate) struct ComparisonSummary {
-    pub new_payload_latency_change_percent: f64,
+    pub per_block_latency_change_mean_percent: f64,
+    pub per_block_latency_change_median_percent: f64,
+    pub per_block_latency_change_std_dev_percent: f64,
+    pub new_payload_total_latency_change_percent: f64,
+    pub new_payload_latency_mean_change_percent: f64,
+    pub new_payload_latency_p50_change_percent: f64,
+    pub new_payload_latency_p90_change_percent: f64,
+    pub new_payload_latency_p99_change_percent: f64,
     pub gas_per_second_change_percent: f64,
     pub blocks_per_second_change_percent: f64,
 }
@@ -90,6 +129,9 @@ pub(crate) struct ComparisonSummary {
 #[derive(Debug, Serialize)]
 pub(crate) struct BlockComparison {
     pub block_number: u64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub transaction_count: Option<u64>,
+    pub gas_used: u64,
     pub baseline_new_payload_latency: u128,
     pub feature_new_payload_latency: u128,
     pub new_payload_latency_change_percent: f64,
@@ -108,6 +150,8 @@ impl ComparisonGenerator {
             feature_ref_name: args.feature_ref.clone(),
             baseline_results: None,
             feature_results: None,
+            baseline_command: None,
+            feature_command: None,
         }
     }
 
@@ -172,6 +216,21 @@ impl ComparisonGenerator {
         Ok(())
     }
 
+    /// Set the reth command for a reference
+    pub(crate) fn set_ref_command(&mut self, ref_type: &str, command: String) -> Result<()> {
+        match ref_type {
+            "baseline" => {
+                self.baseline_command = Some(command);
+            }
+            "feature" => {
+                self.feature_command = Some(command);
+            }
+            _ => return Err(eyre!("Unknown reference type: {}", ref_type)),
+        }
+
+        Ok(())
+    }
+
     /// Generate the final comparison report
     pub(crate) async fn generate_comparison_report(&self) -> Result<()> {
         info!("Generating comparison report...");
@@ -182,10 +241,12 @@ impl ComparisonGenerator {
         let feature =
             self.feature_results.as_ref().ok_or_else(|| eyre!("Feature results not loaded"))?;
 
-        // Generate comparison
-        let comparison_summary =
-            self.calculate_comparison_summary(&baseline.summary, &feature.summary)?;
         let per_block_comparisons = self.calculate_per_block_comparisons(baseline, feature)?;
+        let comparison_summary = self.calculate_comparison_summary(
+            &baseline.summary,
+            &feature.summary,
+            &per_block_comparisons,
+        )?;
 
         let report = ComparisonReport {
             timestamp: self.timestamp.clone(),
@@ -194,12 +255,14 @@ impl ComparisonGenerator {
                 summary: baseline.summary.clone(),
                 start_timestamp: baseline.start_timestamp,
                 end_timestamp: baseline.end_timestamp,
+                reth_command: self.baseline_command.clone(),
             },
             feature: RefInfo {
                 ref_name: feature.ref_name.clone(),
                 summary: feature.summary.clone(),
                 start_timestamp: feature.start_timestamp,
                 end_timestamp: feature.end_timestamp,
+                reth_command: self.feature_command.clone(),
             },
             comparison_summary,
             per_block_comparisons,
@@ -275,7 +338,11 @@ impl ComparisonGenerator {
         Ok(rows)
     }
 
-    /// Calculate summary statistics for a benchmark run
+    /// Calculate summary statistics for a benchmark run.
+    ///
+    /// Computes latency statistics from per-block `new_payload_latency` values in `combined_data`
+    /// (converting from µs to ms), and throughput metrics using the total run duration from
+    /// `total_gas_data`. Percentiles (p50/p90/p99) use linear interpolation on sorted latencies.
     fn calculate_summary(
         &self,
         combined_data: &[CombinedLatencyRow],
@@ -290,9 +357,16 @@ impl ComparisonGenerator {
 
         let total_duration_ms = total_gas_data.last().unwrap().time / 1000; // Convert microseconds to milliseconds
 
-        let avg_new_payload_latency_ms: f64 =
-            combined_data.iter().map(|r| r.new_payload_latency as f64 / 1000.0).sum::<f64>() /
-                total_blocks as f64;
+        let latencies_ms: Vec<f64> =
+            combined_data.iter().map(|r| r.new_payload_latency as f64 / 1000.0).collect();
+        let mean_new_payload_latency_ms: f64 =
+            latencies_ms.iter().sum::<f64>() / total_blocks as f64;
+
+        let mut sorted_latencies_ms = latencies_ms;
+        sorted_latencies_ms.sort_by(|a, b| a.partial_cmp(b).unwrap_or(Ordering::Equal));
+        let median_new_payload_latency_ms = percentile(&sorted_latencies_ms, 0.5);
+        let p90_new_payload_latency_ms = percentile(&sorted_latencies_ms, 0.9);
+        let p99_new_payload_latency_ms = percentile(&sorted_latencies_ms, 0.99);
 
         let total_duration_seconds = total_duration_ms as f64 / 1000.0;
         let gas_per_second = if total_duration_seconds > f64::EPSILON {
@@ -307,13 +381,21 @@ impl ComparisonGenerator {
             0.0
         };
 
+        let min_block_number = combined_data.first().unwrap().block_number;
+        let max_block_number = combined_data.last().unwrap().block_number;
+
         Ok(BenchmarkSummary {
             total_blocks,
             total_gas_used,
             total_duration_ms,
-            avg_new_payload_latency_ms,
+            mean_new_payload_latency_ms,
+            median_new_payload_latency_ms,
+            p90_new_payload_latency_ms,
+            p99_new_payload_latency_ms,
             gas_per_second,
             blocks_per_second,
+            min_block_number,
+            max_block_number,
         })
     }
 
@@ -322,6 +404,7 @@ impl ComparisonGenerator {
         &self,
         baseline: &BenchmarkSummary,
         feature: &BenchmarkSummary,
+        per_block_comparisons: &[BlockComparison],
     ) -> Result<ComparisonSummary> {
         let calc_percent_change = |baseline: f64, feature: f64| -> f64 {
             if baseline.abs() > f64::EPSILON {
@@ -331,10 +414,54 @@ impl ComparisonGenerator {
             }
         };
 
+        // Calculate per-block statistics. "Per-block" means: for each block, compute the percent
+        // change (feature - baseline) / baseline * 100, then calculate statistics across those
+        // per-block percent changes. This captures how consistently the feature performs relative
+        // to baseline across all blocks.
+        let per_block_percent_changes: Vec<f64> =
+            per_block_comparisons.iter().map(|c| c.new_payload_latency_change_percent).collect();
+        let per_block_latency_change_mean_percent = if per_block_percent_changes.is_empty() {
+            0.0
+        } else {
+            per_block_percent_changes.iter().sum::<f64>() / per_block_percent_changes.len() as f64
+        };
+        let per_block_latency_change_median_percent = if per_block_percent_changes.is_empty() {
+            0.0
+        } else {
+            let mut sorted = per_block_percent_changes.clone();
+            sorted.sort_by(|a, b| a.partial_cmp(b).unwrap_or(Ordering::Equal));
+            percentile(&sorted, 0.5)
+        };
+        let per_block_latency_change_std_dev_percent =
+            calculate_std_dev(&per_block_percent_changes, per_block_latency_change_mean_percent);
+
+        let baseline_total_latency_ms =
+            baseline.mean_new_payload_latency_ms * baseline.total_blocks as f64;
+        let feature_total_latency_ms =
+            feature.mean_new_payload_latency_ms * feature.total_blocks as f64;
+        let new_payload_total_latency_change_percent =
+            calc_percent_change(baseline_total_latency_ms, feature_total_latency_ms);
+
         Ok(ComparisonSummary {
-            new_payload_latency_change_percent: calc_percent_change(
-                baseline.avg_new_payload_latency_ms,
-                feature.avg_new_payload_latency_ms,
+            per_block_latency_change_mean_percent,
+            per_block_latency_change_median_percent,
+            per_block_latency_change_std_dev_percent,
+            new_payload_total_latency_change_percent,
+            new_payload_latency_mean_change_percent: calc_percent_change(
+                baseline.mean_new_payload_latency_ms,
+                feature.mean_new_payload_latency_ms,
+            ),
+            new_payload_latency_p50_change_percent: calc_percent_change(
+                baseline.median_new_payload_latency_ms,
+                feature.median_new_payload_latency_ms,
+            ),
+            new_payload_latency_p90_change_percent: calc_percent_change(
+                baseline.p90_new_payload_latency_ms,
+                feature.p90_new_payload_latency_ms,
+            ),
+            new_payload_latency_p99_change_percent: calc_percent_change(
+                baseline.p99_new_payload_latency_ms,
+                feature.p99_new_payload_latency_ms,
             ),
             gas_per_second_change_percent: calc_percent_change(
                 baseline.gas_per_second,
@@ -371,6 +498,8 @@ impl ComparisonGenerator {
 
                 let comparison = BlockComparison {
                     block_number: feature_row.block_number,
+                    transaction_count: feature_row.transaction_count,
+                    gas_used: feature_row.gas_used,
                     baseline_new_payload_latency: baseline_row.new_payload_latency,
                     feature_new_payload_latency: feature_row.new_payload_latency,
                     new_payload_latency_change_percent: calc_percent_change(
@@ -436,20 +565,66 @@ impl ComparisonGenerator {
         let summary = &report.comparison_summary;
 
         println!("Performance Changes:");
-        println!("  NewPayload Latency: {:+.2}%", summary.new_payload_latency_change_percent);
-        println!("  Gas/Second:         {:+.2}%", summary.gas_per_second_change_percent);
-        println!("  Blocks/Second:      {:+.2}%", summary.blocks_per_second_change_percent);
+        println!(
+            "  NewPayload Latency per-block mean change:   {:+.2}%",
+            summary.per_block_latency_change_mean_percent
+        );
+        println!(
+            "  NewPayload Latency per-block median change: {:+.2}%",
+            summary.per_block_latency_change_median_percent
+        );
+        println!(
+            "  NewPayload Latency per-block std dev:       {:.2}%",
+            summary.per_block_latency_change_std_dev_percent
+        );
+        println!(
+            "  Total newPayload time change:                {:+.2}%",
+            summary.new_payload_total_latency_change_percent
+        );
+        println!(
+            "  NewPayload Latency mean:           {:+.2}%",
+            summary.new_payload_latency_mean_change_percent
+        );
+        println!(
+            "  NewPayload Latency p50:           {:+.2}%",
+            summary.new_payload_latency_p50_change_percent
+        );
+        println!(
+            "  NewPayload Latency p90:           {:+.2}%",
+            summary.new_payload_latency_p90_change_percent
+        );
+        println!(
+            "  NewPayload Latency p99:           {:+.2}%",
+            summary.new_payload_latency_p99_change_percent
+        );
+        println!(
+            "  Gas/Second:                      {:+.2}%",
+            summary.gas_per_second_change_percent
+        );
+        println!(
+            "  Blocks/Second:                   {:+.2}%",
+            summary.blocks_per_second_change_percent
+        );
         println!();
 
         println!("Baseline Summary:");
         let baseline = &report.baseline.summary;
         println!(
-            "  Blocks: {}, Gas: {}, Duration: {:.2}s",
+            "  Blocks: {} (blocks {} to {}), Gas: {}, Duration: {:.2}s",
             baseline.total_blocks,
+            baseline.min_block_number,
+            baseline.max_block_number,
             baseline.total_gas_used,
             baseline.total_duration_ms as f64 / 1000.0
         );
-        println!("  Avg NewPayload: {:.2}ms", baseline.avg_new_payload_latency_ms);
+        println!("  NewPayload latency (ms):");
+        println!(
+            "    mean: {:.2}, p50: {:.2}, p90: {:.2}, p99: {:.2}",
+            baseline.mean_new_payload_latency_ms,
+            baseline.median_new_payload_latency_ms,
+            baseline.p90_new_payload_latency_ms,
+            baseline.p99_new_payload_latency_ms
+        );
         if let (Some(start), Some(end)) =
             (&report.baseline.start_timestamp, &report.baseline.end_timestamp)
         {
@@ -459,17 +634,29 @@ impl ComparisonGenerator {
                 end.format("%Y-%m-%d %H:%M:%S UTC")
             );
         }
+        if let Some(ref cmd) = report.baseline.reth_command {
+            println!("  Command: {}", cmd);
+        }
         println!();
 
         println!("Feature Summary:");
         let feature = &report.feature.summary;
         println!(
-            "  Blocks: {}, Gas: {}, Duration: {:.2}s",
+            "  Blocks: {} (blocks {} to {}), Gas: {}, Duration: {:.2}s",
             feature.total_blocks,
+            feature.min_block_number,
+            feature.max_block_number,
             feature.total_gas_used,
             feature.total_duration_ms as f64 / 1000.0
         );
-        println!("  Avg NewPayload: {:.2}ms", feature.avg_new_payload_latency_ms);
+        println!("  NewPayload latency (ms):");
+        println!(
+            "    mean: {:.2}, p50: {:.2}, p90: {:.2}, p99: {:.2}",
+            feature.mean_new_payload_latency_ms,
+            feature.median_new_payload_latency_ms,
+            feature.p90_new_payload_latency_ms,
+            feature.p99_new_payload_latency_ms
+        );
         if let (Some(start), Some(end)) =
             (&report.feature.start_timestamp, &report.feature.end_timestamp)
         {
@@ -479,6 +666,58 @@ impl ComparisonGenerator {
                 end.format("%Y-%m-%d %H:%M:%S UTC")
             );
         }
+        if let Some(ref cmd) = report.feature.reth_command {
+            println!("  Command: {}", cmd);
+        }
         println!();
     }
 }
+
+/// Calculate standard deviation from a set of values and their mean.
+///
+/// Computes the population standard deviation using the formula:
+/// `sqrt(sum((x - mean)²) / n)`
+///
+/// Returns 0.0 for empty input.
+fn calculate_std_dev(values: &[f64], mean: f64) -> f64 {
+    if values.is_empty() {
+        return 0.0;
+    }
+
+    let variance = values
+        .iter()
+        .map(|x| {
+            let diff = x - mean;
+            diff * diff
+        })
+        .sum::<f64>() /
+        values.len() as f64;
+
+    variance.sqrt()
+}
+
+/// Calculate percentile using linear interpolation on a sorted slice.
+///
+/// Computes `rank = percentile × (n - 1)` where n is the array length. If the rank falls
+/// between two indices, linearly interpolates between those values. For example, with 100 values,
+/// p90 computes rank = 0.9 × 99 = 89.1, then returns `values[89] × 0.9 + values[90] × 0.1`.
+///
+/// Returns 0.0 for empty input.
+fn percentile(sorted_values: &[f64], percentile: f64) -> f64 {
+    if sorted_values.is_empty() {
+        return 0.0;
+    }
+
+    let clamped = percentile.clamp(0.0, 1.0);
+    let max_index = sorted_values.len() - 1;
+    let rank = clamped * max_index as f64;
+    let lower = rank.floor() as usize;
+    let upper = rank.ceil() as usize;
+
+    if lower == upper {
+        sorted_values[lower]
+    } else {
+        let weight = rank - lower as f64;
+        sorted_values[lower].mul_add(1.0 - weight, sorted_values[upper] * weight)
+    }
+}

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

@@ -13,7 +13,6 @@ pub(crate) struct CompilationManager {
     repo_root: String,
     output_dir: PathBuf,
     git_manager: GitManager,
-    features: String,
 }
 
 impl CompilationManager {
@@ -22,9 +21,8 @@ impl CompilationManager {
         repo_root: String,
         output_dir: PathBuf,
         git_manager: GitManager,
-        features: String,
     ) -> Result<Self> {
-        Ok(Self { repo_root, output_dir, git_manager, features })
+        Ok(Self { repo_root, output_dir, git_manager })
     }
 
     /// Detect if the RPC endpoint is an Optimism chain
@@ -68,7 +66,13 @@ impl CompilationManager {
     }
 
     /// Compile reth using cargo build and cache the binary
-    pub(crate) fn compile_reth(&self, commit: &str, is_optimism: bool) -> Result<()> {
+    pub(crate) fn compile_reth(
+        &self,
+        commit: &str,
+        is_optimism: bool,
+        features: &str,
+        rustflags: &str,
+    ) -> Result<()> {
         // Validate that current git commit matches the expected commit
         let current_commit = self.git_manager.get_current_commit()?;
         if current_commit != commit {
@@ -100,9 +104,8 @@ impl CompilationManager {
         let mut cmd = Command::new("cargo");
         cmd.arg("build").arg("--profile").arg("profiling");
 
-        // Add features
-        cmd.arg("--features").arg(&self.features);
-        info!("Using features: {}", self.features);
+        cmd.arg("--features").arg(features);
+        info!("Using features: {features}");
 
         // Add bin-specific arguments for optimism
         if is_optimism {
@@ -114,11 +117,11 @@ impl CompilationManager {
 
         cmd.current_dir(&self.repo_root);
 
-        // Set RUSTFLAGS for native CPU optimization
-        cmd.env("RUSTFLAGS", "-C target-cpu=native");
+        // Set RUSTFLAGS
+        cmd.env("RUSTFLAGS", rustflags);
+        info!("Using RUSTFLAGS: {rustflags}");
 
-        // Debug log the command
-        debug!("Executing cargo command: {:?}", cmd);
+        info!("Compiling {binary_name} with {cmd:?}");
 
         let output = cmd.output().wrap_err("Failed to execute cargo build command")?;
 
@@ -227,8 +230,7 @@ impl CompilationManager {
         let mut cmd = Command::new("cargo");
         cmd.args(["install", "--locked", "samply"]);
 
-        // Debug log the command
-        debug!("Executing cargo command: {:?}", cmd);
+        info!("Installing samply with {cmd:?}");
 
         let output = cmd.output().wrap_err("Failed to execute cargo install samply command")?;
 
@@ -303,8 +305,7 @@ impl CompilationManager {
         let mut cmd = Command::new("make");
         cmd.arg("install-reth-bench").current_dir(&self.repo_root);
 
-        // Debug log the command
-        debug!("Executing make command: {:?}", cmd);
+        info!("Compiling reth-bench with {cmd:?}");
 
         let output = cmd.output().wrap_err("Failed to execute make install-reth-bench command")?;
 

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

@@ -181,45 +181,43 @@ impl GitManager {
     /// Validate that the specified git references exist (branches, tags, or commits)
     pub(crate) fn validate_refs(&self, refs: &[&str]) -> Result<()> {
         for &git_ref in refs {
-            // Try branch first, then tag, then commit
-            let branch_check = Command::new("git")
-                .args(["rev-parse", "--verify", &format!("refs/heads/{git_ref}")])
+            // Try to resolve the ref similar to `git checkout` by peeling to a commit.
+            // First try the ref as-is with ^{commit}, then fall back to origin/{ref}^{commit}.
+            let as_is = format!("{git_ref}^{{commit}}");
+            let ref_check = Command::new("git")
+                .args(["rev-parse", "--verify", &as_is])
                 .current_dir(&self.repo_root)
                 .output();
 
-            let tag_check = Command::new("git")
-                .args(["rev-parse", "--verify", &format!("refs/tags/{git_ref}")])
-                .current_dir(&self.repo_root)
-                .output();
-
-            let commit_check = Command::new("git")
-                .args(["rev-parse", "--verify", &format!("{git_ref}^{{commit}}")])
-                .current_dir(&self.repo_root)
-                .output();
-
-            let found = if let Ok(output) = branch_check &&
+            let found = if let Ok(output) = ref_check &&
                 output.status.success()
             {
-                info!("Validated branch exists: {}", git_ref);
-                true
-            } else if let Ok(output) = tag_check &&
-                output.status.success()
-            {
-                info!("Validated tag exists: {}", git_ref);
-                true
-            } else if let Ok(output) = commit_check &&
-                output.status.success()
-            {
-                info!("Validated commit exists: {}", git_ref);
+                info!("Validated reference exists: {}", git_ref);
                 true
             } else {
-                false
+                // Try remote-only branches via origin/{ref}
+                let origin_ref = format!("origin/{git_ref}^{{commit}}");
+                let origin_check = Command::new("git")
+                    .args(["rev-parse", "--verify", &origin_ref])
+                    .current_dir(&self.repo_root)
+                    .output();
+
+                if let Ok(output) = origin_check &&
+                    output.status.success()
+                {
+                    info!("Validated remote reference exists: origin/{}", git_ref);
+                    true
+                } else {
+                    false
+                }
             };
 
             if !found {
                 return Err(eyre!(
-                    "Git reference '{}' does not exist as branch, tag, or commit",
-                    git_ref
+                    "Git reference '{}' does not exist as branch, tag, or commit (tried '{}' and 'origin/{}^{{commit}}')",
+                    git_ref,
+                    format!("{git_ref}^{{commit}}"),
+                    git_ref,
                 ));
             }
         }

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

@@ -2,7 +2,9 @@
 
 use crate::cli::Args;
 use alloy_provider::{Provider, ProviderBuilder};
+use alloy_rpc_client::RpcClient;
 use alloy_rpc_types_eth::SyncStatus;
+use alloy_transport_ws::WsConnect;
 use eyre::{eyre, OptionExt, Result, WrapErr};
 #[cfg(unix)]
 use nix::sys::signal::{killpg, Signal};
@@ -18,6 +20,9 @@ use tokio::{
 };
 use tracing::{debug, info, warn};
 
+/// Default websocket RPC port used by reth
+const DEFAULT_WS_RPC_PORT: u16 = 8546;
+
 /// Manages reth node lifecycle and operations
 pub(crate) struct NodeManager {
     datadir: Option<String>,
@@ -29,6 +34,8 @@ pub(crate) struct NodeManager {
     output_dir: PathBuf,
     additional_reth_args: Vec<String>,
     comparison_dir: Option<PathBuf>,
+    tracing_endpoint: Option<String>,
+    otlp_max_queue_size: usize,
 }
 
 impl NodeManager {
@@ -42,8 +49,16 @@ impl NodeManager {
             binary_path: None,
             enable_profiling: args.profile,
             output_dir: args.output_dir_path(),
-            additional_reth_args: args.reth_args.clone(),
+            // Filter out empty strings to prevent invalid arguments being passed to reth node
+            additional_reth_args: args
+                .reth_args
+                .iter()
+                .filter(|s| !s.is_empty())
+                .cloned()
+                .collect(),
             comparison_dir: None,
+            tracing_endpoint: args.traces.otlp.as_ref().map(|u| u.to_string()),
+            otlp_max_queue_size: args.otlp_max_queue_size,
         }
     }
 
@@ -119,6 +134,7 @@ impl NodeManager {
         &self,
         binary_path_str: &str,
         additional_args: &[String],
+        ref_type: &str,
     ) -> (Vec<String>, String) {
         let mut reth_args = vec![binary_path_str.to_string(), "node".to_string()];
 
@@ -141,11 +157,22 @@ impl NodeManager {
             metrics_arg,
             "--http".to_string(),
             "--http.api".to_string(),
-            "eth".to_string(),
+            "eth,reth".to_string(),
+            "--ws".to_string(),
+            "--ws.api".to_string(),
+            "eth,reth".to_string(),
             "--disable-discovery".to_string(),
             "--trusted-only".to_string(),
+            "--disable-tx-gossip".to_string(),
         ]);
 
+        // Add tracing arguments if OTLP endpoint is configured
+        if let Some(ref endpoint) = self.tracing_endpoint {
+            info!("Enabling OTLP tracing export to: {} (service: reth-{})", endpoint, ref_type);
+            // Endpoint requires equals per clap settings in reth
+            reth_args.push(format!("--tracing-otlp={}", endpoint));
+        }
+
         // Add any additional arguments passed via command line (common to both baseline and
         // feature)
         reth_args.extend_from_slice(&self.additional_reth_args);
@@ -193,6 +220,14 @@ impl NodeManager {
         cmd.arg("--");
         cmd.args(reth_args);
 
+        // Enable tracing-samply
+        if supports_samply_flags(&reth_args[0]) {
+            cmd.arg("--log.samply");
+        }
+
+        // Set environment variable to disable log styling
+        cmd.env("RUST_LOG_STYLE", "never");
+
         Ok(cmd)
     }
 
@@ -200,32 +235,42 @@ impl NodeManager {
     fn create_direct_command(&self, reth_args: &[String]) -> Command {
         let binary_path = &reth_args[0];
 
-        if self.use_sudo {
+        let mut cmd = if self.use_sudo {
             info!("Starting reth node with sudo...");
-            let mut cmd = Command::new("sudo");
-            cmd.args(reth_args);
-            cmd
+            let mut sudo_cmd = Command::new("sudo");
+            sudo_cmd.args(reth_args);
+            sudo_cmd
         } else {
             info!("Starting reth node...");
-            let mut cmd = Command::new(binary_path);
-            cmd.args(&reth_args[1..]); // Skip the binary path since it's the command
-            cmd
-        }
+            let mut reth_cmd = Command::new(binary_path);
+            reth_cmd.args(&reth_args[1..]); // Skip the binary path since it's the command
+            reth_cmd
+        };
+
+        // Set environment variable to disable log styling
+        cmd.env("RUST_LOG_STYLE", "never");
+
+        cmd
     }
 
     /// Start a reth node using the specified binary path and return the process handle
+    /// along with the formatted reth command string for reporting.
     pub(crate) async fn start_node(
         &mut self,
         binary_path: &std::path::Path,
         _git_ref: &str,
         ref_type: &str,
         additional_args: &[String],
-    ) -> Result<tokio::process::Child> {
+    ) -> Result<(tokio::process::Child, String)> {
         // Store the binary path for later use (e.g., in unwind_to_block)
         self.binary_path = Some(binary_path.to_path_buf());
 
         let binary_path_str = binary_path.to_string_lossy();
-        let (reth_args, _) = self.build_reth_args(&binary_path_str, additional_args);
+        let (reth_args, _) = self.build_reth_args(&binary_path_str, additional_args, ref_type);
+
+        // Format the reth command string for reporting
+        let reth_command = shlex::try_join(reth_args.iter().map(|s| s.as_str()))
+            .wrap_err("Failed to format reth command string")?;
 
         // Log additional arguments if any
         if !self.additional_reth_args.is_empty() {
@@ -247,6 +292,15 @@ impl NodeManager {
             cmd.process_group(0);
         }
 
+        // Set high queue size to prevent trace dropping during benchmarks
+        if self.tracing_endpoint.is_some() {
+            cmd.env("OTEL_BSP_MAX_QUEUE_SIZE", self.otlp_max_queue_size.to_string()); // Traces
+            cmd.env("OTEL_BLRP_MAX_QUEUE_SIZE", "10000"); // Logs
+
+            // Set service name to differentiate baseline vs feature runs in Jaeger
+            cmd.env("OTEL_SERVICE_NAME", format!("reth-{}", ref_type));
+        }
+
         debug!("Executing reth command: {cmd:?}");
 
         let mut child = cmd
@@ -311,11 +365,16 @@ impl NodeManager {
         // Give the node a moment to start up
         sleep(Duration::from_secs(5)).await;
 
-        Ok(child)
+        Ok((child, reth_command))
     }
 
-    /// Wait for the node to be ready and return its current tip
-    pub(crate) async fn wait_for_node_ready_and_get_tip(&self) -> Result<u64> {
+    /// Wait for the node to be ready and return its current tip.
+    ///
+    /// Fails early if the node process exits before becoming ready.
+    pub(crate) async fn wait_for_node_ready_and_get_tip(
+        &self,
+        child: &mut tokio::process::Child,
+    ) -> Result<u64> {
         info!("Waiting for node to be ready and synced...");
 
         let max_wait = Duration::from_secs(120); // 2 minutes to allow for sync
@@ -326,8 +385,23 @@ impl NodeManager {
         let url = rpc_url.parse().map_err(|e| eyre!("Invalid RPC URL '{}': {}", rpc_url, e))?;
         let provider = ProviderBuilder::new().connect_http(url);
 
+        let start_time = tokio::time::Instant::now();
+        let mut iteration = 0;
+
         timeout(max_wait, async {
             loop {
+                iteration += 1;
+                debug!(
+                    "Readiness check iteration {} (elapsed: {:?})",
+                    iteration,
+                    start_time.elapsed()
+                );
+
+                // Check if the node process has exited.
+                if let Some(status) = child.try_wait()? {
+                    return Err(eyre!("Node process exited unexpectedly with {status}"));
+                }
+
                 // First check if RPC is up and node is not syncing
                 match provider.syncing().await {
                     Ok(sync_result) => {
@@ -336,24 +410,48 @@ impl NodeManager {
                                 debug!("Node is still syncing {sync_info:?}, waiting...");
                             }
                             _ => {
+                                debug!("HTTP RPC is up and node is not syncing, checking block number...");
                                 // Node is not syncing, now get the tip
                                 match provider.get_block_number().await {
                                     Ok(tip) => {
-                                        info!("Node is ready and not syncing at block: {}", tip);
-                                        return Ok(tip);
+                                        debug!("HTTP RPC ready at block: {}, checking WebSocket...", tip);
+
+                                        // Verify WebSocket RPC is ready (public endpoint, no JWT required)
+                                        let ws_url = format!("ws://localhost:{}", DEFAULT_WS_RPC_PORT);
+                                        debug!("Attempting WebSocket connection to {} (public endpoint)", ws_url);
+                                        let ws_connect = WsConnect::new(&ws_url);
+
+                                        match RpcClient::connect_pubsub(ws_connect).await
+                                        {
+                                            Ok(_) => {
+                                                info!(
+                                                    "Node is ready (HTTP and WebSocket) at block: {} (took {:?}, {} iterations)",
+                                                    tip, start_time.elapsed(), iteration
+                                                );
+                                                return Ok(tip);
+                                            }
+                                            Err(e) => {
+                                                debug!(
+                                                    "HTTP RPC ready but WebSocket not ready yet (iteration {}): {:?}",
+                                                    iteration, e
+                                                );
+                                                debug!("WebSocket error details: {}", e);
+                                            }
+                                        }
                                     }
                                     Err(e) => {
-                                        debug!("Failed to get block number: {}", e);
+                                        debug!("Failed to get block number (iteration {}): {:?}", iteration, e);
                                     }
                                 }
                             }
                         }
                     }
                     Err(e) => {
-                        debug!("Node RPC not ready yet or failed to check sync status: {}", e);
+                        debug!("Node RPC not ready yet or failed to check sync status (iteration {}): {:?}", iteration, e);
                     }
                 }
 
+                debug!("Sleeping for {:?} before next check", check_interval);
                 sleep(check_interval).await;
             }
         })
@@ -361,9 +459,79 @@ impl NodeManager {
         .wrap_err("Timed out waiting for node to be ready and synced")?
     }
 
+    /// Wait for the node RPC to be ready and return its current tip, without waiting for sync.
+    ///
+    /// This is faster than `wait_for_node_ready_and_get_tip` but may return a tip while
+    /// the node is still syncing.
+    pub(crate) async fn wait_for_rpc_and_get_tip(
+        &self,
+        child: &mut tokio::process::Child,
+    ) -> Result<u64> {
+        info!("Waiting for node RPC to be ready (skipping sync wait)...");
+
+        let max_wait = Duration::from_secs(60);
+        let check_interval = Duration::from_secs(2);
+        let rpc_url = "http://localhost:8545";
+
+        let url = rpc_url.parse().map_err(|e| eyre!("Invalid RPC URL '{}': {}", rpc_url, e))?;
+        let provider = ProviderBuilder::new().connect_http(url);
+
+        let start_time = tokio::time::Instant::now();
+        let mut iteration = 0;
+
+        timeout(max_wait, async {
+            loop {
+                iteration += 1;
+                debug!(
+                    "RPC readiness check iteration {} (elapsed: {:?})",
+                    iteration,
+                    start_time.elapsed()
+                );
+
+                if let Some(status) = child.try_wait()? {
+                    return Err(eyre!("Node process exited unexpectedly with {status}"));
+                }
+
+                match provider.get_block_number().await {
+                    Ok(tip) => {
+                        debug!("HTTP RPC ready at block: {}, checking WebSocket...", tip);
+
+                        let ws_url = format!("ws://localhost:{}", DEFAULT_WS_RPC_PORT);
+                        let ws_connect = WsConnect::new(&ws_url);
+
+                        match RpcClient::connect_pubsub(ws_connect).await {
+                            Ok(_) => {
+                                info!(
+                                    "Node RPC is ready at block: {} (took {:?}, {} iterations)",
+                                    tip,
+                                    start_time.elapsed(),
+                                    iteration
+                                );
+                                return Ok(tip);
+                            }
+                            Err(e) => {
+                                debug!(
+                                    "HTTP RPC ready but WebSocket not ready yet (iteration {}): {:?}",
+                                    iteration, e
+                                );
+                            }
+                        }
+                    }
+                    Err(e) => {
+                        debug!("RPC not ready yet (iteration {}): {:?}", iteration, e);
+                    }
+                }
+
+                sleep(check_interval).await;
+            }
+        })
+        .await
+        .wrap_err("Timed out waiting for node RPC to be ready")?
+    }
+
     /// Stop the reth node gracefully
     pub(crate) async fn stop_node(&self, child: &mut tokio::process::Child) -> Result<()> {
-        let pid = child.id().expect("Child process ID should be available");
+        let pid = child.id().ok_or_eyre("Child process ID should be available")?;
 
         // Check if the process has already exited
         match child.try_wait() {
@@ -468,6 +636,9 @@ impl NodeManager {
 
         cmd.args(["to-block", &block_number.to_string()]);
 
+        // Set environment variable to disable log styling
+        cmd.env("RUST_LOG_STYLE", "never");
+
         // Debug log the command
         debug!("Executing reth unwind command: {:?}", cmd);
 
@@ -509,3 +680,16 @@ impl NodeManager {
         Ok(())
     }
 }
+
+fn supports_samply_flags(bin: &str) -> bool {
+    let mut cmd = std::process::Command::new(bin);
+    // NOTE: The flag to check must come before --help.
+    // We pass --help as a shortcut to not execute any command.
+    cmd.args(["--log.samply", "--help"]);
+    debug!(?cmd, "Checking samply flags support");
+    let Ok(output) = cmd.output() else {
+        return false;
+    };
+    debug!(?output, "Samply flags support check");
+    output.status.success()
+}

bin/reth-bench/Cargo.toml

@@ -16,20 +16,27 @@ workspace = true
 # reth
 reth-cli-runner.workspace = true
 reth-cli-util.workspace = true
+reth-engine-primitives.workspace = true
+reth-ethereum-primitives.workspace = true
 reth-fs-util.workspace = true
 reth-node-api.workspace = true
 reth-node-core.workspace = true
 reth-primitives-traits.workspace = true
+reth-rpc-api.workspace = true
+
 reth-tracing.workspace = true
+reth-chainspec.workspace = true
 
 # alloy
 alloy-eips.workspace = true
 alloy-json-rpc.workspace = true
-alloy-primitives.workspace = true
-alloy-provider = { workspace = true, features = ["engine-api", "reqwest-rustls-tls"], default-features = false }
+alloy-consensus.workspace = true
+alloy-network.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
-alloy-rpc-types-engine.workspace = true
+alloy-rpc-client = { workspace = true, features = ["pubsub"] }
+alloy-rpc-types-engine = { workspace = true, features = ["kzg"] }
 alloy-transport-http.workspace = true
 alloy-transport-ipc.workspace = true
 alloy-transport-ws.workspace = true
@@ -50,6 +57,9 @@ tracing.workspace = true
 serde.workspace = true
 serde_json.workspace = true
 
+# url parsing
+url.workspace = true
+
 # async
 async-trait.workspace = true
 futures.workspace = true
@@ -58,6 +68,7 @@ tokio = { workspace = true, features = ["sync", "macros", "time", "rt-multi-thre
 # misc
 clap = { workspace = true, features = ["derive", "env"] }
 eyre.workspace = true
+color-eyre.workspace = true
 thiserror.workspace = true
 humantime.workspace = true
 
@@ -79,7 +90,11 @@ jemalloc = [
     "reth-node-core/jemalloc",
 ]
 jemalloc-prof = ["reth-cli-util/jemalloc-prof"]
-tracy-allocator = ["reth-cli-util/tracy-allocator"]
+tracy-allocator = ["reth-cli-util/tracy-allocator", "tracy"]
+tracy = [
+    "reth-node-core/tracy",
+    "reth-tracing/tracy",
+]
 
 min-error-logs = [
     "tracing/release_max_level_error",

bin/reth-bench/README.md

@@ -31,6 +31,14 @@ Otherwise, running `make maxperf` at the root of the repo should be sufficient f
 `reth-bench` contains different commands to benchmark different patterns of engine API calls.
 The `reth-bench new-payload-fcu` command is the most representative of ethereum mainnet live sync, alternating between sending `engine_newPayload` calls and `engine_forkchoiceUpdated` calls.
 
+The `new-payload-fcu` command supports two optional waiting modes that can be used together or independently:
+- `--wait-time <duration>`: Fixed sleep interval between blocks (e.g., `--wait-time 100ms`)
+- `--wait-for-persistence`: Waits for blocks to be persisted using the `reth_subscribePersistedBlock` subscription
+
+When using `--wait-for-persistence`, the benchmark waits after every `(threshold + 1)` blocks, where the threshold defaults to the engine's persistence threshold (2). This can be customized with `--persistence-threshold <N>`.
+
+By default, the WebSocket URL for persistence subscriptions is derived from `--engine-rpc-url` (converting to ws:// on port 8546). Use `--ws-rpc-url` to override this.
+
 Below is an overview of how to run a benchmark:
 
 ### Setup
@@ -80,7 +88,7 @@ RUSTFLAGS="-C target-cpu=native" cargo build --profile profiling --no-default-fe
 ### Run the Benchmark:
 First, start the reth node. Here is an example that runs `reth` compiled with the `profiling` profile, runs `samply`, and configures `reth` to run with metrics enabled:
 ```bash
-samply record -p 3001 target/profiling/reth node --metrics localhost:9001 --authrpc.jwt-secret <jwt_file_path>
+samply record -p 3001 target/profiling/reth node --metrics localhost:9001 --authrpc.jwtsecret <jwt_file_path>
 ```
 
 ```bash
@@ -143,5 +151,5 @@ To reproduce the benchmark, first re-set the node to the block that the benchmar
 - **RPC Configuration**: The RPC endpoints should be accessible and configured correctly, specifically the RPC endpoint must support `eth_getBlockByNumber` and support fetching full transactions. The benchmark will make one RPC query per block as fast as possible, so ensure the RPC endpoint does not rate limit or block requests after a certain volume.
 - **Reproducibility**: Ensure that the node is at the same state before attempting to retry a benchmark. The `new-payload-fcu` command specifically will commit to the database, so the node must be rolled back using `reth stage unwind` to reproducibly retry benchmarks.
 - **Profiling tools**: If you are collecting CPU profiles, tools like [`samply`](https://github.com/mstange/samply) and [`perf`](https://perf.wiki.kernel.org/index.php/Main_Page) can be useful for analyzing node performance.
-- **Benchmark Data**: `reth-bench` additionally contains a `--benchmark.output` flag, which will output gas used benchmarks across the benchmark range in CSV format. This may be useful for further data analysis.
+- **Benchmark Data**: `reth-bench` additionally contains a `--output` flag, which will output gas used benchmarks across the benchmark range in CSV format. This may be useful for further data analysis.
 - **Platform Information**: To ensure accurate and reproducible benchmarking, document the platform details, including hardware specifications, OS version, and any other relevant information before publishing any benchmarks.

bin/reth-bench/src/authenticated_transport.rs

@@ -163,7 +163,7 @@ impl AuthenticatedTransport {
 
             // shift the iat forward by one second so there is some buffer time
             let mut shifted_claims = inner_and_claims.1;
-            shifted_claims.iat -= 1;
+            shifted_claims.iat -= 30;
 
             // if the claims are out of date, reset the inner transport
             if !shifted_claims.is_within_time_window() {

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

@@ -103,14 +103,20 @@ impl BenchContext {
             (bench_args.from, bench_args.to)
         };
 
-        // If neither `--from` nor `--to` are provided, we will run the benchmark continuously,
+        // If `--to` are not provided, we will run the benchmark continuously,
         // starting at the latest block.
-        let mut benchmark_mode = BenchMode::new(from, to)?;
+        let latest_block = block_provider
+            .get_block_by_number(BlockNumberOrTag::Latest)
+            .full()
+            .await?
+            .ok_or_else(|| eyre::eyre!("Failed to fetch latest block from RPC"))?;
+        let mut benchmark_mode = BenchMode::new(from, to, latest_block.into_inner().number())?;
 
         let first_block = match benchmark_mode {
-            BenchMode::Continuous => {
-                // fetch Latest block
-                block_provider.get_block_by_number(BlockNumberOrTag::Latest).full().await?.unwrap()
+            BenchMode::Continuous(start) => {
+                block_provider.get_block_by_number(start.into()).full().await?.ok_or_else(|| {
+                    eyre::eyre!("Failed to fetch block {} from RPC for continuous mode", start)
+                })?
             }
             BenchMode::Range(ref mut range) => {
                 match range.next() {
@@ -120,7 +126,9 @@ impl BenchContext {
                             .get_block_by_number(block_number.into())
                             .full()
                             .await?
-                            .unwrap()
+                            .ok_or_else(|| {
+                                eyre::eyre!("Failed to fetch block {} from RPC", block_number)
+                            })?
                     }
                     None => {
                         return Err(eyre::eyre!(

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

@@ -0,0 +1,286 @@
+//! Benchmarks empty block processing by ramping the block gas limit.
+
+use crate::{
+    authenticated_transport::AuthenticatedTransportConnect,
+    bench::{
+        helpers::{build_payload, prepare_payload_request, rpc_block_to_header},
+        output::GasRampPayloadFile,
+    },
+    valid_payload::{call_forkchoice_updated, call_new_payload, payload_to_new_payload},
+};
+use alloy_eips::BlockNumberOrTag;
+use alloy_provider::{network::AnyNetwork, Provider, RootProvider};
+use alloy_rpc_client::ClientBuilder;
+use alloy_rpc_types_engine::{ExecutionPayload, ForkchoiceState, JwtSecret};
+
+use clap::Parser;
+use reqwest::Url;
+use reth_chainspec::ChainSpec;
+use reth_cli_runner::CliContext;
+use reth_ethereum_primitives::TransactionSigned;
+use reth_primitives_traits::constants::{GAS_LIMIT_BOUND_DIVISOR, MAXIMUM_GAS_LIMIT_BLOCK};
+use std::{path::PathBuf, time::Instant};
+use tracing::info;
+
+/// Parses a gas limit value with optional suffix: K for thousand, M for million, G for billion.
+///
+/// Examples: "30000000", "30M", "1G", "2G"
+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"))
+}
+
+/// `reth benchmark gas-limit-ramp` command.
+#[derive(Debug, Parser)]
+pub struct Command {
+    /// 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")]
+    engine_rpc_url: String,
+
+    /// Path to the JWT secret for Engine API authentication.
+    #[arg(long = "jwt-secret", value_name = "JWT_SECRET")]
+    jwt_secret: PathBuf,
+
+    /// Output directory for benchmark results and generated payloads.
+    #[arg(long, value_name = "OUTPUT")]
+    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<()> {
+        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() {
+            return Err(eyre::eyre!("Output path must be a directory"));
+        }
+        if !self.output.exists() {
+            std::fs::create_dir_all(&self.output)?;
+            info!("Created output directory: {:?}", self.output);
+        }
+
+        // Set up authenticated provider (used for both Engine API and eth_ methods)
+        let jwt = std::fs::read_to_string(&self.jwt_secret)?;
+        let jwt = JwtSecret::from_hex(jwt)?;
+        let auth_url = Url::parse(&self.engine_rpc_url)?;
+
+        info!("Connecting to Engine RPC at {}", auth_url);
+        let auth_transport = AuthenticatedTransportConnect::new(auth_url, jwt);
+        let client = ClientBuilder::default().connect_with(auth_transport).await?;
+        let provider = RootProvider::<AnyNetwork>::new(client);
+
+        // Get chain spec - required for fork detection
+        let chain_id = provider.get_chain_id().await?;
+        let chain_spec = ChainSpec::from_chain_id(chain_id)
+            .ok_or_else(|| eyre::eyre!("Unsupported chain id: {chain_id}"))?;
+
+        // Fetch the current head block as parent
+        let parent_block = provider
+            .get_block_by_number(BlockNumberOrTag::Latest)
+            .full()
+            .await?
+            .ok_or_else(|| eyre::eyre!("Failed to fetch latest block"))?;
+
+        let (mut parent_header, mut parent_hash) = rpc_block_to_header(parent_block);
+
+        let canonical_parent = parent_header.number;
+        let start_block = canonical_parent + 1;
+
+        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 blocks_processed = 0u64;
+        let total_benchmark_duration = Instant::now();
+
+        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);
+            let new_payload_version = request.new_payload_version;
+
+            let (payload, sidecar) = build_payload(&provider, request).await?;
+
+            let mut block =
+                payload.clone().try_into_block_with_sidecar::<TransactionSigned>(&sidecar)?;
+
+            let max_increase = max_gas_limit_increase(parent_header.gas_limit);
+            let gas_limit =
+                parent_header.gas_limit.saturating_add(max_increase).min(MAXIMUM_GAS_LIMIT_BLOCK);
+
+            block.header.gas_limit = gas_limit;
+
+            let block_hash = block.header.hash_slow();
+            // Regenerate the payload from the modified block, but keep the original sidecar
+            // which contains the actual execution requests data (not just the hash)
+            let (payload, _) = ExecutionPayload::from_block_unchecked(block_hash, &block);
+            let (version, params) = payload_to_new_payload(
+                payload,
+                sidecar,
+                false,
+                block.header.withdrawals_root,
+                Some(new_payload_version),
+            )?;
+
+            // Save payload to file with version info for replay
+            let payload_path =
+                self.output.join(format!("payload_block_{}.json", block.header.number));
+            let file =
+                GasRampPayloadFile { version: version as u8, block_hash, params: params.clone() };
+            let payload_json = serde_json::to_string_pretty(&file)?;
+            std::fs::write(&payload_path, &payload_json)?;
+            info!(block_number = block.header.number, path = %payload_path.display(), "Saved payload");
+
+            call_new_payload(&provider, version, params).await?;
+
+            let forkchoice_state = ForkchoiceState {
+                head_block_hash: block_hash,
+                safe_block_hash: block_hash,
+                finalized_block_hash: block_hash,
+            };
+            call_forkchoice_updated(&provider, version, forkchoice_state, None).await?;
+
+            parent_header = block.header;
+            parent_hash = block_hash;
+            blocks_processed += 1;
+        }
+
+        let final_gas_limit = parent_header.gas_limit;
+        info!(
+            total_duration=?total_benchmark_duration.elapsed(),
+            blocks_processed,
+            final_gas_limit,
+            "Benchmark complete"
+        );
+
+        Ok(())
+    }
+}
+
+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,
+    }
+}
+
+#[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/generate_big_block.rs

@@ -0,0 +1,617 @@
+//! Command for generating large blocks by packing transactions from real blocks.
+//!
+//! 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 alloy_eips::{BlockNumberOrTag, Typed2718};
+use alloy_primitives::{Bytes, B256};
+use alloy_provider::{ext::EngineApi, network::AnyNetwork, Provider, RootProvider};
+use alloy_rpc_client::ClientBuilder;
+use alloy_rpc_types_engine::{
+    ExecutionPayloadEnvelopeV4, ExecutionPayloadEnvelopeV5, ForkchoiceState, JwtSecret,
+    PayloadAttributes,
+};
+use alloy_transport::layers::RetryBackoffLayer;
+use clap::Parser;
+use eyre::Context;
+use reqwest::Url;
+use reth_cli_runner::CliContext;
+use reth_rpc_api::TestingBuildBlockRequestV1;
+use std::future::Future;
+use tokio::sync::mpsc;
+use tracing::{info, warn};
+
+/// A single transaction with its gas used and raw encoded bytes.
+#[derive(Debug, Clone)]
+pub struct RawTransaction {
+    /// The actual gas used by the transaction (from receipt).
+    pub gas_used: u64,
+    /// The transaction type (e.g., 3 for EIP-4844 blob txs).
+    pub tx_type: u8,
+    /// The raw RLP-encoded transaction bytes.
+    pub raw: Bytes,
+}
+
+/// Abstraction over sources of transactions for big block generation.
+///
+/// Implementors provide transactions from different sources (RPC, database, files, etc.)
+pub trait TransactionSource {
+    /// Fetch transactions from a specific block number.
+    ///
+    /// Returns `Ok(None)` if the block doesn't exist.
+    /// Returns `Ok(Some((transactions, gas_used)))` with the block's transactions and total gas.
+    fn fetch_block_transactions(
+        &self,
+        block_number: u64,
+    ) -> impl Future<Output = eyre::Result<Option<(Vec<RawTransaction>, u64)>>> + Send;
+}
+
+/// RPC-based transaction source that fetches from a remote node.
+#[derive(Debug)]
+pub struct RpcTransactionSource {
+    provider: RootProvider<AnyNetwork>,
+}
+
+impl RpcTransactionSource {
+    /// Create a new RPC transaction source.
+    pub const fn new(provider: RootProvider<AnyNetwork>) -> Self {
+        Self { provider }
+    }
+
+    /// Create from an RPC URL with retry backoff.
+    pub fn from_url(rpc_url: &str) -> eyre::Result<Self> {
+        let client = ClientBuilder::default()
+            .layer(RetryBackoffLayer::new(10, 800, u64::MAX))
+            .http(rpc_url.parse()?);
+        let provider = RootProvider::<AnyNetwork>::new(client);
+        Ok(Self { provider })
+    }
+}
+
+impl TransactionSource for RpcTransactionSource {
+    async fn fetch_block_transactions(
+        &self,
+        block_number: u64,
+    ) -> eyre::Result<Option<(Vec<RawTransaction>, u64)>> {
+        // Fetch block and receipts in parallel
+        let (block, receipts) = tokio::try_join!(
+            self.provider.get_block_by_number(block_number.into()).full(),
+            self.provider.get_block_receipts(block_number.into())
+        )?;
+
+        let Some(block) = block else {
+            return Ok(None);
+        };
+
+        let Some(receipts) = receipts else {
+            return Err(eyre::eyre!("Receipts not found for block {}", block_number));
+        };
+
+        let block_gas_used = block.header.gas_used;
+
+        // Convert cumulative gas from receipts to per-tx gas_used
+        let mut prev_cumulative = 0u64;
+        let transactions: Vec<RawTransaction> = block
+            .transactions
+            .txns()
+            .zip(receipts.iter())
+            .map(|(tx, receipt)| {
+                let cumulative = receipt.inner.inner.inner.receipt.cumulative_gas_used;
+                let gas_used = cumulative - prev_cumulative;
+                prev_cumulative = cumulative;
+
+                let with_encoded = tx.inner.inner.clone().into_encoded();
+                RawTransaction {
+                    gas_used,
+                    tx_type: tx.inner.ty(),
+                    raw: with_encoded.encoded_bytes().clone(),
+                }
+            })
+            .collect();
+
+        Ok(Some((transactions, block_gas_used)))
+    }
+}
+
+/// Collects transactions from a source up to a target gas usage.
+#[derive(Debug)]
+pub struct TransactionCollector<S> {
+    source: S,
+    target_gas: u64,
+}
+
+impl<S: TransactionSource> TransactionCollector<S> {
+    /// Create a new transaction collector.
+    pub const fn new(source: S, target_gas: u64) -> Self {
+        Self { source, target_gas }
+    }
+
+    /// 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();
+        let mut total_gas: u64 = 0;
+        let mut current_block = start_block;
+
+        while total_gas < self.target_gas {
+            let Some((block_txs, _)) = self.source.fetch_block_transactions(current_block).await?
+            else {
+                warn!(block = current_block, "Block not found, stopping");
+                break;
+            };
+
+            for tx in block_txs {
+                // Skip blob transactions (EIP-4844, type 3)
+                if tx.tx_type == 3 {
+                    continue;
+                }
+
+                if total_gas + tx.gas_used <= self.target_gas {
+                    transactions.push(tx.raw);
+                    total_gas += tx.gas_used;
+                }
+
+                if total_gas >= self.target_gas {
+                    break;
+                }
+            }
+
+            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);
+            if remaining_gas < 1_000_000 {
+                break;
+            }
+        }
+
+        info!(
+            total_txs = transactions.len(),
+            total_gas,
+            next_block = current_block,
+            "Finished collecting transactions"
+        );
+
+        Ok((transactions, total_gas, current_block))
+    }
+}
+
+/// `reth bench generate-big-block` command
+///
+/// Generates a large block by fetching transactions from existing blocks and packing them
+/// into a single block using the `testing_buildBlockV1` RPC endpoint.
+#[derive(Debug, Parser)]
+pub struct Command {
+    /// The RPC URL to use for fetching blocks (can be an external archive node).
+    #[arg(long, value_name = "RPC_URL")]
+    rpc_url: String,
+
+    /// The engine RPC URL (with JWT authentication).
+    #[arg(long, value_name = "ENGINE_RPC_URL", default_value = "http://localhost:8551")]
+    engine_rpc_url: String,
+
+    /// The RPC URL for `testing_buildBlockV1` calls (same node as engine, regular RPC port).
+    #[arg(long, value_name = "TESTING_RPC_URL", default_value = "http://localhost:8545")]
+    testing_rpc_url: String,
+
+    /// Path to the JWT secret file for engine API authentication.
+    #[arg(long, value_name = "JWT_SECRET")]
+    jwt_secret: std::path::PathBuf,
+
+    /// Target gas to pack into the block.
+    #[arg(long, value_name = "TARGET_GAS", default_value = "30000000")]
+    target_gas: u64,
+
+    /// Starting block number to fetch transactions from.
+    /// If not specified, starts from the engine's latest block.
+    #[arg(long, value_name = "FROM_BLOCK")]
+    from_block: Option<u64>,
+
+    /// Execute the payload (call newPayload + forkchoiceUpdated).
+    /// If false, only builds the payload and prints it.
+    #[arg(long, default_value = "false")]
+    execute: bool,
+
+    /// Number of payloads to generate. Each payload uses the previous as parent.
+    /// When count == 1, the payload is only generated and saved, not executed.
+    /// When count > 1, each payload is executed before building the next.
+    #[arg(long, default_value = "1")]
+    count: u64,
+
+    /// Number of transaction batches to prefetch in background when count > 1.
+    /// Higher values reduce latency but use more memory.
+    #[arg(long, default_value = "4")]
+    prefetch_buffer: usize,
+
+    /// Output directory for generated payloads. Each payload is saved as `payload_block_N.json`.
+    #[arg(long, value_name = "OUTPUT_DIR")]
+    output_dir: std::path::PathBuf,
+}
+
+/// A built payload ready for execution.
+struct BuiltPayload {
+    block_number: u64,
+    envelope: ExecutionPayloadEnvelopeV4,
+    block_hash: B256,
+    timestamp: u64,
+}
+
+impl Command {
+    /// Execute the `generate-big-block` command
+    pub async fn execute(self, _ctx: CliContext) -> eyre::Result<()> {
+        info!(target_gas = self.target_gas, count = self.count, "Generating big block(s)");
+
+        // Set up authenticated engine provider
+        let jwt =
+            std::fs::read_to_string(&self.jwt_secret).wrap_err("Failed to read JWT secret file")?;
+        let jwt = JwtSecret::from_hex(jwt.trim())?;
+        let auth_url = Url::parse(&self.engine_rpc_url)?;
+
+        info!("Connecting to Engine RPC at {}", auth_url);
+        let auth_transport = AuthenticatedTransportConnect::new(auth_url.clone(), jwt);
+        let auth_client = ClientBuilder::default().connect_with(auth_transport).await?;
+        let auth_provider = RootProvider::<AnyNetwork>::new(auth_client);
+
+        // Set up testing RPC provider (for testing_buildBlockV1)
+        info!("Connecting to Testing RPC at {}", self.testing_rpc_url);
+        let testing_client = ClientBuilder::default()
+            .layer(RetryBackoffLayer::new(10, 800, u64::MAX))
+            .http(self.testing_rpc_url.parse()?);
+        let testing_provider = RootProvider::<AnyNetwork>::new(testing_client);
+
+        // Get the parent block (latest canonical block)
+        info!(endpoint = "engine", method = "eth_getBlockByNumber", block = "latest", "RPC call");
+        let parent_block = auth_provider
+            .get_block_by_number(BlockNumberOrTag::Latest)
+            .await?
+            .ok_or_else(|| eyre::eyre!("Failed to fetch latest block"))?;
+
+        let parent_hash = parent_block.header.hash;
+        let parent_number = parent_block.header.number;
+        let parent_timestamp = parent_block.header.timestamp;
+
+        info!(
+            parent_hash = %parent_hash,
+            parent_number = parent_number,
+            "Using initial parent block"
+        );
+
+        // Create output directory
+        std::fs::create_dir_all(&self.output_dir).wrap_err_with(|| {
+            format!("Failed to create output directory: {:?}", self.output_dir)
+        })?;
+
+        let start_block = self.from_block.unwrap_or(parent_number);
+
+        // Use pipelined execution when generating multiple payloads
+        if self.count > 1 {
+            self.execute_pipelined(
+                &auth_provider,
+                &testing_provider,
+                start_block,
+                parent_hash,
+                parent_timestamp,
+            )
+            .await?;
+        } else {
+            // Single payload - collect transactions and build
+            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?;
+
+            if transactions.is_empty() {
+                return Err(eyre::eyre!("No transactions collected"));
+            }
+
+            self.execute_sequential(
+                &auth_provider,
+                &testing_provider,
+                transactions,
+                parent_hash,
+                parent_timestamp,
+            )
+            .await?;
+        }
+
+        info!(count = self.count, output_dir = %self.output_dir.display(), "All payloads generated");
+        Ok(())
+    }
+
+    /// Sequential execution path for single payload or no-execute mode.
+    async fn execute_sequential(
+        &self,
+        auth_provider: &RootProvider<AnyNetwork>,
+        testing_provider: &RootProvider<AnyNetwork>,
+        transactions: Vec<Bytes>,
+        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 built = self
+                .build_payload(testing_provider, &transactions, 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)");
+                self.execute_payload_v4(auth_provider, built.envelope, parent_hash).await?;
+                info!(payload = i + 1, "Payload executed successfully");
+            }
+
+            parent_hash = built.block_hash;
+            parent_timestamp = built.timestamp;
+        }
+        Ok(())
+    }
+
+    /// Pipelined execution - fetches transactions and builds payloads in background.
+    async fn execute_pipelined(
+        &self,
+        auth_provider: &RootProvider<AnyNetwork>,
+        testing_provider: &RootProvider<AnyNetwork>,
+        start_block: u64,
+        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);
+
+        // 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;
+                }
+            };
+
+            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));
+                }
+
+                info!(
+                    payload = i + 1,
+                    total = self.count,
+                    parent_hash = %parent_hash,
+                    parent_timestamp = parent_timestamp,
+                    tx_count = transactions.len(),
+                    "Building payload via testing_buildBlockV1"
+                );
+                self.build_payload(
+                    testing_provider,
+                    &transactions,
+                    i,
+                    parent_hash,
+                    parent_timestamp,
+                )
+                .await?
+            };
+
+            self.save_payload(&current_payload)?;
+
+            let current_block_hash = current_payload.block_hash;
+            let current_timestamp = current_payload.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?;
+            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);
+        let _ = fetcher_handle.await;
+
+        Ok(())
+    }
+
+    /// Build a single payload via `testing_buildBlockV1`.
+    async fn build_payload(
+        &self,
+        testing_provider: &RootProvider<AnyNetwork>,
+        transactions: &[Bytes],
+        index: u64,
+        parent_hash: B256,
+        parent_timestamp: u64,
+    ) -> eyre::Result<BuiltPayload> {
+        Self::build_payload_static(
+            testing_provider,
+            transactions,
+            index,
+            parent_hash,
+            parent_timestamp,
+        )
+        .await
+    }
+
+    /// Static version for use in spawned tasks.
+    async fn build_payload_static(
+        testing_provider: &RootProvider<AnyNetwork>,
+        transactions: &[Bytes],
+        index: u64,
+        parent_hash: B256,
+        parent_timestamp: u64,
+    ) -> eyre::Result<BuiltPayload> {
+        let request = TestingBuildBlockRequestV1 {
+            parent_block_hash: parent_hash,
+            payload_attributes: PayloadAttributes {
+                timestamp: parent_timestamp + 12,
+                prev_randao: B256::ZERO,
+                suggested_fee_recipient: alloy_primitives::Address::ZERO,
+                withdrawals: Some(vec![]),
+                parent_beacon_block_root: Some(B256::ZERO),
+            },
+            transactions: transactions.to_vec(),
+            extra_data: None,
+        };
+
+        let total_tx_bytes: usize = transactions.iter().map(|tx| tx.len()).sum();
+        info!(
+            payload = index + 1,
+            tx_count = transactions.len(),
+            total_tx_bytes = total_tx_bytes,
+            parent_hash = %parent_hash,
+            "Sending to testing_buildBlockV1"
+        );
+        let envelope: ExecutionPayloadEnvelopeV5 =
+            testing_provider.client().request("testing_buildBlockV1", [request]).await?;
+
+        let v4_envelope = envelope.try_into_v4()?;
+
+        let inner = &v4_envelope.envelope_inner.execution_payload.payload_inner.payload_inner;
+        let block_hash = inner.block_hash;
+        let block_number = inner.block_number;
+        let timestamp = inner.timestamp;
+
+        Ok(BuiltPayload { block_number, envelope: v4_envelope, block_hash, timestamp })
+    }
+
+    /// Save a payload to disk.
+    fn save_payload(&self, payload: &BuiltPayload) -> eyre::Result<()> {
+        let filename = format!("payload_block_{}.json", payload.block_number);
+        let filepath = self.output_dir.join(&filename);
+        let json = serde_json::to_string_pretty(&payload.envelope)?;
+        std::fs::write(&filepath, &json)
+            .wrap_err_with(|| format!("Failed to write payload to {:?}", filepath))?;
+        info!(block_number = payload.block_number, block_hash = %payload.block_hash, path = %filepath.display(), "Payload saved");
+        Ok(())
+    }
+
+    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;
+
+        let status = provider
+            .new_payload_v4(
+                envelope.envelope_inner.execution_payload,
+                vec![],
+                B256::ZERO,
+                envelope.execution_requests.to_vec(),
+            )
+            .await?;
+
+        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,
+        };
+
+        let fcu_result = provider.fork_choice_updated_v3(fcu_state, None).await?;
+
+        if !fcu_result.is_valid() {
+            return Err(eyre::eyre!("FCU rejected: {:?}", fcu_result));
+        }
+
+        Ok(())
+    }
+}

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

@@ -0,0 +1,196 @@
+//! Common helpers for reth-bench commands.
+
+use crate::valid_payload::call_forkchoice_updated;
+use alloy_consensus::Header;
+use alloy_eips::eip4844::kzg_to_versioned_hash;
+use alloy_primitives::{Address, B256};
+use alloy_provider::{ext::EngineApi, network::AnyNetwork, RootProvider};
+use alloy_rpc_types_engine::{
+    CancunPayloadFields, ExecutionPayload, ExecutionPayloadSidecar, ForkchoiceState,
+    PayloadAttributes, PayloadId, PraguePayloadFields,
+};
+use eyre::OptionExt;
+use reth_chainspec::{ChainSpec, EthereumHardforks};
+use reth_node_api::EngineApiMessageVersion;
+use tracing::debug;
+
+/// Prepared payload request data for triggering block building.
+pub(crate) struct PayloadRequest {
+    /// The payload attributes for the new block.
+    pub(crate) attributes: PayloadAttributes,
+    /// The forkchoice state pointing to the parent block.
+    pub(crate) forkchoice_state: ForkchoiceState,
+    /// The engine API version for FCU calls.
+    pub(crate) fcu_version: EngineApiMessageVersion,
+    /// The getPayload version to use (1-5).
+    pub(crate) get_payload_version: u8,
+    /// The newPayload version to use.
+    pub(crate) new_payload_version: EngineApiMessageVersion,
+}
+
+/// Prepare payload attributes and forkchoice state for a new block.
+pub(crate) fn prepare_payload_request(
+    chain_spec: &ChainSpec,
+    timestamp: u64,
+    parent_hash: B256,
+) -> PayloadRequest {
+    let shanghai_active = chain_spec.is_shanghai_active_at_timestamp(timestamp);
+    let cancun_active = chain_spec.is_cancun_active_at_timestamp(timestamp);
+    let prague_active = chain_spec.is_prague_active_at_timestamp(timestamp);
+    let osaka_active = chain_spec.is_osaka_active_at_timestamp(timestamp);
+
+    // FCU version: V3 for Cancun+Prague+Osaka, V2 for Shanghai, V1 otherwise
+    let fcu_version = if cancun_active {
+        EngineApiMessageVersion::V3
+    } else if shanghai_active {
+        EngineApiMessageVersion::V2
+    } else {
+        EngineApiMessageVersion::V1
+    };
+
+    // getPayload version: 5 for Osaka, 4 for Prague, 3 for Cancun, 2 for Shanghai, 1 otherwise
+    // newPayload version: 4 for Prague+Osaka (no V5), 3 for Cancun, 2 for Shanghai, 1 otherwise
+    let (get_payload_version, new_payload_version) = if osaka_active {
+        (5, EngineApiMessageVersion::V4) // Osaka uses getPayloadV5 but newPayloadV4
+    } else if prague_active {
+        (4, EngineApiMessageVersion::V4)
+    } else if cancun_active {
+        (3, EngineApiMessageVersion::V3)
+    } else if shanghai_active {
+        (2, EngineApiMessageVersion::V2)
+    } else {
+        (1, EngineApiMessageVersion::V1)
+    };
+
+    PayloadRequest {
+        attributes: PayloadAttributes {
+            timestamp,
+            prev_randao: B256::ZERO,
+            suggested_fee_recipient: Address::ZERO,
+            withdrawals: shanghai_active.then(Vec::new),
+            parent_beacon_block_root: cancun_active.then_some(B256::ZERO),
+        },
+        forkchoice_state: ForkchoiceState {
+            head_block_hash: parent_hash,
+            safe_block_hash: parent_hash,
+            finalized_block_hash: parent_hash,
+        },
+        fcu_version,
+        get_payload_version,
+        new_payload_version,
+    }
+}
+
+/// Trigger payload building via FCU and retrieve the built payload.
+///
+/// This sends a forkchoiceUpdated with payload attributes to start building,
+/// then calls getPayload to retrieve the result.
+pub(crate) async fn build_payload(
+    provider: &RootProvider<AnyNetwork>,
+    request: PayloadRequest,
+) -> eyre::Result<(ExecutionPayload, ExecutionPayloadSidecar)> {
+    let fcu_result = call_forkchoice_updated(
+        provider,
+        request.fcu_version,
+        request.forkchoice_state,
+        Some(request.attributes.clone()),
+    )
+    .await?;
+
+    let payload_id =
+        fcu_result.payload_id.ok_or_eyre("Payload builder did not return a payload id")?;
+
+    get_payload_with_sidecar(
+        provider,
+        request.get_payload_version,
+        payload_id,
+        request.attributes.parent_beacon_block_root,
+    )
+    .await
+}
+
+/// Convert an RPC block to a consensus header and block hash.
+pub(crate) fn rpc_block_to_header(block: alloy_provider::network::AnyRpcBlock) -> (Header, B256) {
+    let block_hash = block.header.hash;
+    let header = block.header.inner.clone().into_header_with_defaults();
+    (header, block_hash)
+}
+
+/// Compute versioned hashes from KZG commitments.
+fn versioned_hashes_from_commitments(
+    commitments: &[alloy_primitives::FixedBytes<48>],
+) -> Vec<B256> {
+    commitments.iter().map(|c| kzg_to_versioned_hash(c.as_ref())).collect()
+}
+
+/// Fetch an execution payload using the appropriate engine API version.
+pub(crate) async fn get_payload_with_sidecar(
+    provider: &RootProvider<AnyNetwork>,
+    version: u8,
+    payload_id: PayloadId,
+    parent_beacon_block_root: Option<B256>,
+) -> eyre::Result<(ExecutionPayload, ExecutionPayloadSidecar)> {
+    debug!(get_payload_version = ?version, ?payload_id, "Sending getPayload");
+
+    match version {
+        1 => {
+            let payload = provider.get_payload_v1(payload_id).await?;
+            Ok((ExecutionPayload::V1(payload), ExecutionPayloadSidecar::none()))
+        }
+        2 => {
+            let envelope = provider.get_payload_v2(payload_id).await?;
+            let payload = match envelope.execution_payload {
+                alloy_rpc_types_engine::ExecutionPayloadFieldV2::V1(p) => ExecutionPayload::V1(p),
+                alloy_rpc_types_engine::ExecutionPayloadFieldV2::V2(p) => ExecutionPayload::V2(p),
+            };
+            Ok((payload, ExecutionPayloadSidecar::none()))
+        }
+        3 => {
+            let envelope = provider.get_payload_v3(payload_id).await?;
+            let versioned_hashes =
+                versioned_hashes_from_commitments(&envelope.blobs_bundle.commitments);
+            let cancun_fields = CancunPayloadFields {
+                parent_beacon_block_root: parent_beacon_block_root
+                    .ok_or_eyre("parent_beacon_block_root required for V3")?,
+                versioned_hashes,
+            };
+            Ok((
+                ExecutionPayload::V3(envelope.execution_payload),
+                ExecutionPayloadSidecar::v3(cancun_fields),
+            ))
+        }
+        4 => {
+            let envelope = provider.get_payload_v4(payload_id).await?;
+            let versioned_hashes = versioned_hashes_from_commitments(
+                &envelope.envelope_inner.blobs_bundle.commitments,
+            );
+            let cancun_fields = CancunPayloadFields {
+                parent_beacon_block_root: parent_beacon_block_root
+                    .ok_or_eyre("parent_beacon_block_root required for V4")?,
+                versioned_hashes,
+            };
+            let prague_fields = PraguePayloadFields::new(envelope.execution_requests);
+            Ok((
+                ExecutionPayload::V3(envelope.envelope_inner.execution_payload),
+                ExecutionPayloadSidecar::v4(cancun_fields, prague_fields),
+            ))
+        }
+        5 => {
+            // V5 (Osaka) - use raw request since alloy doesn't have get_payload_v5 yet
+            let envelope = provider.get_payload_v5(payload_id).await?;
+            let versioned_hashes =
+                versioned_hashes_from_commitments(&envelope.blobs_bundle.commitments);
+            let cancun_fields = CancunPayloadFields {
+                parent_beacon_block_root: parent_beacon_block_root
+                    .ok_or_eyre("parent_beacon_block_root required for V5")?,
+                versioned_hashes,
+            };
+            let prague_fields = PraguePayloadFields::new(envelope.execution_requests);
+            Ok((
+                ExecutionPayload::V3(envelope.execution_payload),
+                ExecutionPayloadSidecar::v4(cancun_fields, prague_fields),
+            ))
+        }
+        _ => panic!("This tool does not support getPayload versions past v5"),
+    }
+}

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

@@ -6,9 +6,17 @@ use reth_node_core::args::LogArgs;
 use reth_tracing::FileWorkerGuard;
 
 mod context;
+mod gas_limit_ramp;
+mod generate_big_block;
+pub(crate) mod helpers;
+pub use generate_big_block::{
+    RawTransaction, RpcTransactionSource, TransactionCollector, TransactionSource,
+};
 mod new_payload_fcu;
 mod new_payload_only;
 mod output;
+mod replay_payloads;
+mod send_invalid_payload;
 mod send_payload;
 
 /// `reth bench` command
@@ -27,6 +35,9 @@ pub enum Subcommands {
     /// Benchmark which calls `newPayload`, then `forkchoiceUpdated`.
     NewPayloadFcu(new_payload_fcu::Command),
 
+    /// Benchmark which builds empty blocks with a ramped gas limit.
+    GasLimitRamp(gas_limit_ramp::Command),
+
     /// Benchmark which only calls subsequent `newPayload` calls.
     NewPayloadOnly(new_payload_only::Command),
 
@@ -41,6 +52,41 @@ pub enum Subcommands {
     /// `cast block latest --full --json | reth-bench send-payload --rpc-url localhost:5000
     /// --jwt-secret $(cat ~/.local/share/reth/mainnet/jwt.hex)`
     SendPayload(send_payload::Command),
+
+    /// Generate a large block by packing transactions from existing blocks.
+    ///
+    /// This command fetches transactions from real blocks and packs them into a single
+    /// block using the `testing_buildBlockV1` RPC endpoint.
+    ///
+    /// Example:
+    ///
+    /// `reth-bench generate-big-block --rpc-url http://localhost:8545 --engine-rpc-url
+    /// http://localhost:8551 --jwt-secret ~/.local/share/reth/mainnet/jwt.hex --target-gas
+    /// 30000000`
+    GenerateBigBlock(generate_big_block::Command),
+
+    /// Replay pre-generated payloads from a directory.
+    ///
+    /// This command reads payload files from a previous `generate-big-block` run and replays
+    /// them in sequence using `newPayload` followed by `forkchoiceUpdated`.
+    ///
+    /// Example:
+    ///
+    /// `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 {
@@ -51,8 +97,12 @@ impl BenchmarkCommand {
 
         match self.command {
             Subcommands::NewPayloadFcu(command) => command.execute(ctx).await,
+            Subcommands::GasLimitRamp(command) => command.execute(ctx).await,
             Subcommands::NewPayloadOnly(command) => command.execute(ctx).await,
             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

@@ -1,26 +1,42 @@
 //! Runs the `reth bench` command, calling first newPayload for each block, then calling
 //! 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::{
     bench::{
         context::BenchContext,
         output::{
-            CombinedResult, NewPayloadResult, TotalGasOutput, TotalGasRow, COMBINED_OUTPUT_SUFFIX,
-            GAS_OUTPUT_SUFFIX,
+            write_benchmark_results, CombinedResult, NewPayloadResult, TotalGasOutput, TotalGasRow,
         },
     },
     valid_payload::{block_to_new_payload, call_forkchoice_updated, call_new_payload},
 };
-use alloy_provider::Provider;
+use alloy_eips::BlockNumHash;
+use alloy_network::Ethereum;
+use alloy_provider::{Provider, RootProvider};
+use alloy_pubsub::SubscriptionStream;
+use alloy_rpc_client::RpcClient;
 use alloy_rpc_types_engine::ForkchoiceState;
+use alloy_transport_ws::WsConnect;
 use clap::Parser;
-use csv::Writer;
 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)]
@@ -30,8 +46,31 @@ pub struct Command {
     rpc_url: String,
 
     /// How long to wait after a forkchoice update before sending the next payload.
-    #[arg(long, value_name = "WAIT_TIME", value_parser = parse_duration, default_value = "250ms", verbatim_doc_comment)]
-    wait_time: Duration,
+    #[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,
 
     /// The size of the block buffer (channel capacity) for prefetching blocks from the RPC
     /// endpoint.
@@ -50,12 +89,39 @@ pub struct Command {
 impl Command {
     /// Execute `benchmark new-payload-fcu` command
     pub async fn execute(self, _ctx: CliContext) -> eyre::Result<()> {
+        // 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 sub = self.setup_persistence_subscription().await?;
+                Some(PersistenceWaiter::with_subscription(
+                    sub,
+                    self.persistence_threshold,
+                    PERSISTENCE_CHECKPOINT_TIMEOUT,
+                ))
+            }
+            (None, false) => None,
+        };
+
         let BenchContext {
             benchmark_mode,
             block_provider,
             auth_provider,
             mut next_block,
             is_optimism,
+            ..
         } = BenchContext::new(&self.benchmark, self.rpc_url).await?;
 
         let buffer_size = self.rpc_block_buffer_size;
@@ -79,22 +145,13 @@ impl Command {
                         break;
                     }
                 };
-                let header = block.header.clone();
 
-                let (version, params) = match block_to_new_payload(block, is_optimism) {
-                    Ok(result) => result,
-                    Err(e) => {
-                        tracing::error!("Failed to convert block to new payload: {e}");
-                        let _ = error_sender.send(e);
-                        break;
-                    }
-                };
-                let head_block_hash = header.hash;
-                let safe_block_hash =
-                    block_provider.get_block_by_number(header.number.saturating_sub(32).into());
+                let head_block_hash = block.header.hash;
+                let safe_block_hash = block_provider
+                    .get_block_by_number(block.header.number.saturating_sub(32).into());
 
-                let finalized_block_hash =
-                    block_provider.get_block_by_number(header.number.saturating_sub(64).into());
+                let finalized_block_hash = block_provider
+                    .get_block_by_number(block.header.number.saturating_sub(64).into());
 
                 let (safe, finalized) = tokio::join!(safe_block_hash, finalized_block_hash,);
 
@@ -110,14 +167,7 @@ impl Command {
 
                 next_block += 1;
                 if let Err(e) = sender
-                    .send((
-                        header,
-                        version,
-                        params,
-                        head_block_hash,
-                        safe_block_hash,
-                        finalized_block_hash,
-                    ))
+                    .send((block, head_block_hash, safe_block_hash, finalized_block_hash))
                     .await
                 {
                     tracing::error!("Failed to send block data: {e}");
@@ -126,30 +176,30 @@ impl Command {
             }
         });
 
-        // put results in a summary vec so they can be printed at the end
         let mut results = Vec::new();
         let total_benchmark_duration = Instant::now();
         let mut total_wait_time = Duration::ZERO;
 
-        while let Some((header, version, params, head, safe, finalized)) = {
+        while let Some((block, head, safe, finalized)) = {
             let wait_start = Instant::now();
             let result = receiver.recv().await;
             total_wait_time += wait_start.elapsed();
             result
         } {
-            // just put gas used here
-            let gas_used = header.gas_used;
-            let block_number = header.number;
+            let gas_used = block.header.gas_used;
+            let gas_limit = block.header.gas_limit;
+            let block_number = block.header.number;
+            let transaction_count = block.transactions.len() as u64;
 
-            debug!(target: "reth-bench", ?block_number, "Sending payload",);
+            debug!(target: "reth-bench", ?block_number, "Sending payload");
 
-            // construct fcu to call
             let forkchoice_state = ForkchoiceState {
                 head_block_hash: head,
                 safe_block_hash: safe,
                 finalized_block_hash: finalized,
             };
 
+            let (version, params) = block_to_new_payload(block, is_optimism)?;
             let start = Instant::now();
             call_new_payload(&auth_provider, version, params).await?;
 
@@ -157,24 +207,28 @@ impl Command {
 
             call_forkchoice_updated(&auth_provider, version, forkchoice_state, None).await?;
 
-            // calculate the total duration and the fcu latency, record
             let total_latency = start.elapsed();
             let fcu_latency = total_latency - new_payload_result.latency;
-            let combined_result =
-                CombinedResult { block_number, new_payload_result, fcu_latency, total_latency };
+            let combined_result = CombinedResult {
+                block_number,
+                gas_limit,
+                transaction_count,
+                new_payload_result,
+                fcu_latency,
+                total_latency,
+            };
 
-            // current duration since the start of the benchmark minus the time
-            // waiting for blocks
+            // Exclude time spent waiting on the block prefetch channel from the benchmark duration.
+            // We want to measure engine throughput, not RPC fetch latency.
             let current_duration = total_benchmark_duration.elapsed() - total_wait_time;
-
-            // convert gas used to gigagas, then compute gigagas per second
             info!(%combined_result);
 
-            // wait before sending the next payload
-            tokio::time::sleep(self.wait_time).await;
+            if let Some(w) = &mut waiter {
+                w.on_block(block_number).await?;
+            }
 
-            // record the current result
-            let gas_row = TotalGasRow { block_number, gas_used, time: current_duration };
+            let gas_row =
+                TotalGasRow { block_number, transaction_count, gas_used, time: current_duration };
             results.push((gas_row, combined_result));
         }
 
@@ -183,34 +237,19 @@ impl Command {
             return Err(error);
         }
 
-        let (gas_output_results, combined_results): (_, Vec<CombinedResult>) =
+        // 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();
 
-        // write the csv output to files
-        if let Some(path) = self.benchmark.output {
-            // first write the combined results to a file
-            let output_path = path.join(COMBINED_OUTPUT_SUFFIX);
-            info!("Writing engine api call latency output to file: {:?}", output_path);
-            let mut writer = Writer::from_path(output_path)?;
-            for result in combined_results {
-                writer.serialize(result)?;
-            }
-            writer.flush()?;
-
-            // now write the gas output to a file
-            let output_path = path.join(GAS_OUTPUT_SUFFIX);
-            info!("Writing total gas output to file: {:?}", output_path);
-            let mut writer = Writer::from_path(output_path)?;
-            for row in &gas_output_results {
-                writer.serialize(row)?;
-            }
-            writer.flush()?;
-
-            info!("Finished writing benchmark output files to {:?}.", path);
+        if let Some(ref path) = self.benchmark.output {
+            write_benchmark_results(path, &gas_output_results, combined_results)?;
         }
 
-        // accumulate the results and calculate the overall Ggas/s
         let gas_output = TotalGasOutput::new(gas_output_results)?;
+
         info!(
             total_duration=?gas_output.total_duration,
             total_gas_used=?gas_output.total_gas_used,
@@ -221,4 +260,278 @@ impl Command {
 
         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/new_payload_only.rs

@@ -49,6 +49,7 @@ impl Command {
             auth_provider,
             mut next_block,
             is_optimism,
+            ..
         } = BenchContext::new(&self.benchmark, self.rpc_url).await?;
 
         let buffer_size = self.rpc_block_buffer_size;
@@ -72,19 +73,9 @@ impl Command {
                         break;
                     }
                 };
-                let header = block.header.clone();
-
-                let (version, params) = match block_to_new_payload(block, is_optimism) {
-                    Ok(result) => result,
-                    Err(e) => {
-                        tracing::error!("Failed to convert block to new payload: {e}");
-                        let _ = error_sender.send(e);
-                        break;
-                    }
-                };
 
                 next_block += 1;
-                if let Err(e) = sender.send((header, version, params)).await {
+                if let Err(e) = sender.send(block).await {
                     tracing::error!("Failed to send block data: {e}");
                     break;
                 }
@@ -96,22 +87,19 @@ impl Command {
         let total_benchmark_duration = Instant::now();
         let mut total_wait_time = Duration::ZERO;
 
-        while let Some((header, version, params)) = {
+        while let Some(block) = {
             let wait_start = Instant::now();
             let result = receiver.recv().await;
             total_wait_time += wait_start.elapsed();
             result
         } {
-            // just put gas used here
-            let gas_used = header.gas_used;
+            let block_number = block.header.number;
+            let transaction_count = block.transactions.len() as u64;
+            let gas_used = block.header.gas_used;
 
-            let block_number = header.number;
+            debug!(number=?block.header.number, "Sending payload to engine");
 
-            debug!(
-                target: "reth-bench",
-                number=?header.number,
-                "Sending payload to engine",
-            );
+            let (version, params) = block_to_new_payload(block, is_optimism)?;
 
             let start = Instant::now();
             call_new_payload(&auth_provider, version, params).await?;
@@ -124,7 +112,8 @@ impl Command {
             let current_duration = total_benchmark_duration.elapsed() - total_wait_time;
 
             // record the current result
-            let row = TotalGasRow { block_number, gas_used, time: current_duration };
+            let row =
+                TotalGasRow { block_number, transaction_count, gas_used, time: current_duration };
             results.push((row, new_payload_result));
         }
 

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

@@ -1,10 +1,13 @@
 //! Contains various benchmark output formats, either for logging or for
 //! serialization to / from files.
 
+use alloy_primitives::B256;
+use csv::Writer;
 use eyre::OptionExt;
 use reth_primitives_traits::constants::GIGAGAS;
-use serde::{ser::SerializeStruct, Serialize};
-use std::time::Duration;
+use serde::{ser::SerializeStruct, Deserialize, Serialize};
+use std::{path::Path, time::Duration};
+use tracing::info;
 
 /// This is the suffix for gas output csv files.
 pub(crate) const GAS_OUTPUT_SUFFIX: &str = "total_gas.csv";
@@ -15,6 +18,17 @@ pub(crate) const COMBINED_OUTPUT_SUFFIX: &str = "combined_latency.csv";
 /// This is the suffix for new payload output csv files.
 pub(crate) const NEW_PAYLOAD_OUTPUT_SUFFIX: &str = "new_payload_latency.csv";
 
+/// Serialized format for gas ramp payloads on disk.
+#[derive(Debug, Serialize, Deserialize)]
+pub(crate) struct GasRampPayloadFile {
+    /// Engine API version (1-5).
+    pub(crate) version: u8,
+    /// The block hash for FCU.
+    pub(crate) block_hash: B256,
+    /// The params to pass to newPayload.
+    pub(crate) params: serde_json::Value,
+}
+
 /// This represents the results of a single `newPayload` call in the benchmark, containing the gas
 /// used and the `newPayload` latency.
 #[derive(Debug)]
@@ -67,6 +81,10 @@ impl Serialize for NewPayloadResult {
 pub(crate) struct CombinedResult {
     /// The block number of the block being processed.
     pub(crate) block_number: u64,
+    /// The gas limit of the block.
+    pub(crate) gas_limit: u64,
+    /// The number of transactions in the block.
+    pub(crate) transaction_count: u64,
     /// The `newPayload` result.
     pub(crate) new_payload_result: NewPayloadResult,
     /// The latency of the `forkchoiceUpdated` call.
@@ -86,7 +104,7 @@ impl std::fmt::Display for CombinedResult {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         write!(
             f,
-            "Payload {} processed at {:.4} Ggas/s, used {} total gas. Combined gas per second: {:.4} Ggas/s. fcu latency: {:?}, newPayload latency: {:?}",
+            "Block {} processed at {:.4} Ggas/s, used {} total gas. Combined: {:.4} Ggas/s. fcu: {:?}, newPayload: {:?}",
             self.block_number,
             self.new_payload_result.gas_per_second() / GIGAGAS as f64,
             self.new_payload_result.gas_used,
@@ -108,10 +126,12 @@ impl Serialize for CombinedResult {
         let fcu_latency = self.fcu_latency.as_micros();
         let new_payload_latency = self.new_payload_result.latency.as_micros();
         let total_latency = self.total_latency.as_micros();
-        let mut state = serializer.serialize_struct("CombinedResult", 5)?;
+        let mut state = serializer.serialize_struct("CombinedResult", 7)?;
 
         // flatten the new payload result because this is meant for CSV writing
         state.serialize_field("block_number", &self.block_number)?;
+        state.serialize_field("gas_limit", &self.gas_limit)?;
+        state.serialize_field("transaction_count", &self.transaction_count)?;
         state.serialize_field("gas_used", &self.new_payload_result.gas_used)?;
         state.serialize_field("new_payload_latency", &new_payload_latency)?;
         state.serialize_field("fcu_latency", &fcu_latency)?;
@@ -125,6 +145,8 @@ impl Serialize for CombinedResult {
 pub(crate) struct TotalGasRow {
     /// The block number of the block being processed.
     pub(crate) block_number: u64,
+    /// The number of transactions in the block.
+    pub(crate) transaction_count: u64,
     /// The total gas used in the block.
     pub(crate) gas_used: u64,
     /// Time since the start of the benchmark.
@@ -162,6 +184,36 @@ impl TotalGasOutput {
     }
 }
 
+/// Write benchmark results to CSV files.
+///
+/// Writes two files to the output directory:
+/// - `combined_latency.csv`: Per-block latency results
+/// - `total_gas.csv`: Per-block gas usage over time
+pub(crate) fn write_benchmark_results(
+    output_dir: &Path,
+    gas_results: &[TotalGasRow],
+    combined_results: Vec<CombinedResult>,
+) -> eyre::Result<()> {
+    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)?;
+    for result in combined_results {
+        writer.serialize(result)?;
+    }
+    writer.flush()?;
+
+    let output_path = output_dir.join(GAS_OUTPUT_SUFFIX);
+    info!("Writing total gas output to file: {:?}", output_path);
+    let mut writer = Writer::from_path(&output_path)?;
+    for row in gas_results {
+        writer.serialize(row)?;
+    }
+    writer.flush()?;
+
+    info!("Finished writing benchmark output files to {:?}.", output_dir);
+    Ok(())
+}
+
 /// This serializes the `time` field of the [`TotalGasRow`] to microseconds.
 ///
 /// This is essentially just for the csv writer, which would have headers
@@ -172,8 +224,9 @@ impl Serialize for TotalGasRow {
     {
         // convert the time to microseconds
         let time = self.time.as_micros();
-        let mut state = serializer.serialize_struct("TotalGasRow", 3)?;
+        let mut state = serializer.serialize_struct("TotalGasRow", 4)?;
         state.serialize_field("block_number", &self.block_number)?;
+        state.serialize_field("transaction_count", &self.transaction_count)?;
         state.serialize_field("gas_used", &self.gas_used)?;
         state.serialize_field("time", &time)?;
         state.end()
@@ -188,7 +241,12 @@ mod tests {
 
     #[test]
     fn test_write_total_gas_row_csv() {
-        let row = TotalGasRow { block_number: 1, gas_used: 1_000, time: Duration::from_secs(1) };
+        let row = TotalGasRow {
+            block_number: 1,
+            transaction_count: 10,
+            gas_used: 1_000,
+            time: Duration::from_secs(1),
+        };
 
         let mut writer = Writer::from_writer(vec![]);
         writer.serialize(row).unwrap();
@@ -198,11 +256,11 @@ mod tests {
         let mut result = result.as_slice().lines();
 
         // assert header
-        let expected_first_line = "block_number,gas_used,time";
+        let expected_first_line = "block_number,transaction_count,gas_used,time";
         let first_line = result.next().unwrap().unwrap();
         assert_eq!(first_line, expected_first_line);
 
-        let expected_second_line = "1,1000,1000000";
+        let expected_second_line = "1,10,1000,1000000";
         let second_line = result.next().unwrap().unwrap();
         assert_eq!(second_line, expected_second_line);
     }

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

@@ -0,0 +1,332 @@
+//! Command for replaying pre-generated payloads from disk.
+//!
+//! This command reads `ExecutionPayloadEnvelopeV4` files from a directory and replays them
+//! in sequence using `newPayload` followed by `forkchoiceUpdated`.
+
+use crate::{
+    authenticated_transport::AuthenticatedTransportConnect,
+    bench::output::GasRampPayloadFile,
+    valid_payload::{call_forkchoice_updated, call_new_payload},
+};
+use alloy_primitives::B256;
+use alloy_provider::{ext::EngineApi, network::AnyNetwork, Provider, RootProvider};
+use alloy_rpc_client::ClientBuilder;
+use alloy_rpc_types_engine::{ExecutionPayloadEnvelopeV4, ForkchoiceState, JwtSecret};
+use clap::Parser;
+use eyre::Context;
+use reqwest::Url;
+use reth_cli_runner::CliContext;
+use reth_node_api::EngineApiMessageVersion;
+use std::path::PathBuf;
+use tracing::{debug, info};
+
+/// `reth bench replay-payloads` command
+///
+/// Replays pre-generated payloads from a directory by calling `newPayload` followed by
+/// `forkchoiceUpdated` for each payload in sequence.
+#[derive(Debug, Parser)]
+pub struct Command {
+    /// The engine RPC URL (with JWT authentication).
+    #[arg(long, value_name = "ENGINE_RPC_URL", default_value = "http://localhost:8551")]
+    engine_rpc_url: String,
+
+    /// Path to the JWT secret file for engine API authentication.
+    #[arg(long, value_name = "JWT_SECRET")]
+    jwt_secret: PathBuf,
+
+    /// Directory containing payload files (`payload_block_N.json`).
+    #[arg(long, value_name = "PAYLOAD_DIR")]
+    payload_dir: PathBuf,
+
+    /// Optional limit on the number of payloads to replay.
+    /// If not specified, replays all payloads in the directory.
+    #[arg(long, value_name = "COUNT")]
+    count: Option<usize>,
+
+    /// Skip the first N payloads.
+    #[arg(long, value_name = "SKIP", default_value = "0")]
+    skip: usize,
+
+    /// Optional directory containing gas ramp payloads to replay first.
+    /// 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>,
+}
+
+/// A loaded payload ready for execution.
+struct LoadedPayload {
+    /// The index (from filename).
+    index: u64,
+    /// The payload envelope.
+    envelope: ExecutionPayloadEnvelopeV4,
+    /// The block hash.
+    block_hash: B256,
+}
+
+/// A gas ramp payload loaded from disk.
+struct GasRampPayload {
+    /// Block number from filename.
+    block_number: u64,
+    /// Engine API version for newPayload.
+    version: EngineApiMessageVersion,
+    /// The file contents.
+    file: GasRampPayloadFile,
+}
+
+impl Command {
+    /// Execute the `replay-payloads` command.
+    pub async fn execute(self, _ctx: CliContext) -> eyre::Result<()> {
+        info!(payload_dir = %self.payload_dir.display(), "Replaying payloads");
+
+        // Set up authenticated engine provider
+        let jwt =
+            std::fs::read_to_string(&self.jwt_secret).wrap_err("Failed to read JWT secret file")?;
+        let jwt = JwtSecret::from_hex(jwt.trim())?;
+        let auth_url = Url::parse(&self.engine_rpc_url)?;
+
+        info!("Connecting to Engine RPC at {}", auth_url);
+        let auth_transport = AuthenticatedTransportConnect::new(auth_url.clone(), jwt);
+        let auth_client = ClientBuilder::default().connect_with(auth_transport).await?;
+        let auth_provider = RootProvider::<AnyNetwork>::new(auth_client);
+
+        // Get parent block (latest canonical block) - we need this for the first FCU
+        let parent_block = auth_provider
+            .get_block_by_number(alloy_eips::BlockNumberOrTag::Latest)
+            .await?
+            .ok_or_else(|| eyre::eyre!("Failed to fetch latest block"))?;
+
+        let initial_parent_hash = parent_block.header.hash;
+        let initial_parent_number = parent_block.header.number;
+
+        info!(
+            parent_hash = %initial_parent_hash,
+            parent_number = initial_parent_number,
+            "Using initial parent block"
+        );
+
+        // Load all payloads upfront to avoid I/O delays between phases
+        let gas_ramp_payloads = if let Some(ref gas_ramp_dir) = self.gas_ramp_dir {
+            let payloads = self.load_gas_ramp_payloads(gas_ramp_dir)?;
+            if payloads.is_empty() {
+                return Err(eyre::eyre!("No gas ramp payload files found in {:?}", gas_ramp_dir));
+            }
+            info!(count = payloads.len(), "Loaded gas ramp payloads from disk");
+            payloads
+        } else {
+            Vec::new()
+        };
+
+        let payloads = self.load_payloads()?;
+        if payloads.is_empty() {
+            return Err(eyre::eyre!("No payload files found in {:?}", self.payload_dir));
+        }
+        info!(count = payloads.len(), "Loaded main payloads from disk");
+
+        let mut parent_hash = initial_parent_hash;
+
+        // Replay gas ramp payloads first
+        for (i, payload) in gas_ramp_payloads.iter().enumerate() {
+            info!(
+                gas_ramp_payload = i + 1,
+                total = gas_ramp_payloads.len(),
+                block_number = payload.block_number,
+                block_hash = %payload.file.block_hash,
+                "Executing gas ramp payload (newPayload + FCU)"
+            );
+
+            call_new_payload(&auth_provider, payload.version, payload.file.params.clone()).await?;
+
+            let fcu_state = ForkchoiceState {
+                head_block_hash: payload.file.block_hash,
+                safe_block_hash: parent_hash,
+                finalized_block_hash: parent_hash,
+            };
+            call_forkchoice_updated(&auth_provider, payload.version, fcu_state, None).await?;
+
+            info!(gas_ramp_payload = i + 1, "Gas ramp payload executed successfully");
+            parent_hash = payload.file.block_hash;
+        }
+
+        if !gas_ramp_payloads.is_empty() {
+            info!(count = gas_ramp_payloads.len(), "All gas ramp payloads replayed");
+        }
+
+        for (i, payload) in payloads.iter().enumerate() {
+            info!(
+                payload = i + 1,
+                total = payloads.len(),
+                index = payload.index,
+                block_hash = %payload.block_hash,
+                "Executing payload (newPayload + FCU)"
+            );
+
+            self.execute_payload_v4(&auth_provider, &payload.envelope, parent_hash).await?;
+
+            info!(payload = i + 1, "Payload executed successfully");
+            parent_hash = payload.block_hash;
+        }
+
+        info!(count = payloads.len(), "All payloads replayed successfully");
+        Ok(())
+    }
+
+    /// Load and parse all payload files from the directory.
+    fn load_payloads(&self) -> eyre::Result<Vec<LoadedPayload>> {
+        let mut payloads = Vec::new();
+
+        // Read directory entries
+        let entries: Vec<_> = std::fs::read_dir(&self.payload_dir)
+            .wrap_err_with(|| format!("Failed to read directory {:?}", self.payload_dir))?
+            .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_block_")
+            })
+            .collect();
+
+        // Parse filenames to get indices and sort
+        let mut indexed_paths: Vec<(u64, PathBuf)> = entries
+            .into_iter()
+            .filter_map(|e| {
+                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_block_")?.strip_suffix(".json")?;
+                let index: u64 = index_str.parse().ok()?;
+                Some((index, e.path()))
+            })
+            .collect();
+
+        indexed_paths.sort_by_key(|(idx, _)| *idx);
+
+        // Apply skip and count
+        let indexed_paths: Vec<_> = indexed_paths.into_iter().skip(self.skip).collect();
+        let indexed_paths: Vec<_> = match self.count {
+            Some(count) => indexed_paths.into_iter().take(count).collect(),
+            None => indexed_paths,
+        };
+
+        // Load each payload
+        for (index, path) in indexed_paths {
+            let content = std::fs::read_to_string(&path)
+                .wrap_err_with(|| format!("Failed to read {:?}", path))?;
+            let envelope: ExecutionPayloadEnvelopeV4 = serde_json::from_str(&content)
+                .wrap_err_with(|| format!("Failed to parse {:?}", path))?;
+
+            let block_hash =
+                envelope.envelope_inner.execution_payload.payload_inner.payload_inner.block_hash;
+
+            info!(
+                index = index,
+                block_hash = %block_hash,
+                path = %path.display(),
+                "Loaded payload"
+            );
+
+            payloads.push(LoadedPayload { index, envelope, block_hash });
+        }
+
+        Ok(payloads)
+    }
+
+    /// Load and parse gas ramp payload files from a directory.
+    fn load_gas_ramp_payloads(&self, dir: &PathBuf) -> eyre::Result<Vec<GasRampPayload>> {
+        let mut payloads = Vec::new();
+
+        let entries: Vec<_> = std::fs::read_dir(dir)
+            .wrap_err_with(|| format!("Failed to read directory {:?}", dir))?
+            .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_block_")
+            })
+            .collect();
+
+        // Parse filenames to get block numbers and sort
+        let mut indexed_paths: Vec<(u64, PathBuf)> = entries
+            .into_iter()
+            .filter_map(|e| {
+                let name = e.file_name();
+                let name_str = name.to_string_lossy();
+                // Extract block number from "payload_block_NNN.json"
+                let block_str = name_str.strip_prefix("payload_block_")?.strip_suffix(".json")?;
+                let block_number: u64 = block_str.parse().ok()?;
+                Some((block_number, e.path()))
+            })
+            .collect();
+
+        indexed_paths.sort_by_key(|(num, _)| *num);
+
+        for (block_number, path) in indexed_paths {
+            let content = std::fs::read_to_string(&path)
+                .wrap_err_with(|| format!("Failed to read {:?}", path))?;
+            let file: GasRampPayloadFile = serde_json::from_str(&content)
+                .wrap_err_with(|| format!("Failed to parse {:?}", path))?;
+
+            let version = match file.version {
+                1 => EngineApiMessageVersion::V1,
+                2 => EngineApiMessageVersion::V2,
+                3 => EngineApiMessageVersion::V3,
+                4 => EngineApiMessageVersion::V4,
+                5 => EngineApiMessageVersion::V5,
+                v => return Err(eyre::eyre!("Invalid version {} in {:?}", v, path)),
+            };
+
+            info!(
+                block_number,
+                block_hash = %file.block_hash,
+                path = %path.display(),
+                "Loaded gas ramp payload"
+            );
+
+            payloads.push(GasRampPayload { block_number, version, file });
+        }
+
+        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,367 @@
+//! Command for sending invalid payloads to test Engine API rejection.
+
+mod invalidation;
+use invalidation::InvalidationConfig;
+
+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::{BufReader, Read, 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 {
+    /// 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) => match std::fs::read_to_string(secret) {
+                Ok(contents) => Ok(Some(contents.trim().to_string())),
+                Err(_) => Ok(Some(secret.clone())),
+            },
+            None => Ok(None),
+        }
+    }
+
+    /// 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 = self.read_input()?;
+        let jwt_secret = self.load_jwt_secret()?;
+
+        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_mode.rs

@@ -5,9 +5,8 @@ use std::ops::RangeInclusive;
 /// Whether or not the benchmark should run as a continuous stream of payloads.
 #[derive(Debug, PartialEq, Eq)]
 pub enum BenchMode {
-    // TODO: just include the start block in `Continuous`
     /// Run the benchmark as a continuous stream of payloads, until the benchmark is interrupted.
-    Continuous,
+    Continuous(u64),
     /// Run the benchmark for a specific range of blocks.
     Range(RangeInclusive<u64>),
 }
@@ -16,18 +15,19 @@ impl BenchMode {
     /// Check if the block number is in the range
     pub fn contains(&self, block_number: u64) -> bool {
         match self {
-            Self::Continuous => true,
+            Self::Continuous(start) => block_number >= *start,
             Self::Range(range) => range.contains(&block_number),
         }
     }
 
     /// Create a [`BenchMode`] from optional `from` and `to` fields.
-    pub fn new(from: Option<u64>, to: Option<u64>) -> Result<Self, eyre::Error> {
+    pub fn new(from: Option<u64>, to: Option<u64>, latest_block: u64) -> Result<Self, eyre::Error> {
         // If neither `--from` nor `--to` are provided, we will run the benchmark continuously,
         // starting at the latest block.
         match (from, to) {
             (Some(from), Some(to)) => Ok(Self::Range(from..=to)),
-            (None, None) => Ok(Self::Continuous),
+            (None, None) => Ok(Self::Continuous(latest_block)),
+            (Some(start), None) => Ok(Self::Continuous(start)),
             _ => {
                 // both or neither are allowed, everything else is ambiguous
                 Err(eyre::eyre!("`from` and `to` must be provided together, or not at all."))

bin/reth-bench/src/main.rs

@@ -23,7 +23,7 @@ use bench::BenchmarkCommand;
 use clap::Parser;
 use reth_cli_runner::CliRunner;
 
-fn main() {
+fn main() -> eyre::Result<()> {
     // Enable backtraces unless a RUST_BACKTRACE value has already been explicitly provided.
     if std::env::var_os("RUST_BACKTRACE").is_none() {
         unsafe {
@@ -31,12 +31,11 @@ fn main() {
         }
     }
 
+    color_eyre::install()?;
+
     // Run until either exit or sigint or sigterm
-    let runner = CliRunner::try_default_runtime().unwrap();
-    runner
-        .run_command_until_exit(|ctx| {
-            let command = BenchmarkCommand::parse();
-            command.execute(ctx)
-        })
-        .unwrap();
+    let runner = CliRunner::try_default_runtime()?;
+    runner.run_command_until_exit(|ctx| BenchmarkCommand::parse().execute(ctx))?;
+
+    Ok(())
 }

bin/reth-bench/src/valid_payload.rs

@@ -3,15 +3,16 @@
 //! before sending additional calls.
 
 use alloy_eips::eip7685::Requests;
+use alloy_primitives::B256;
 use alloy_provider::{ext::EngineApi, network::AnyRpcBlock, Network, Provider};
 use alloy_rpc_types_engine::{
-    ExecutionPayload, ExecutionPayloadInputV2, ForkchoiceState, ForkchoiceUpdated,
-    PayloadAttributes, PayloadStatus,
+    ExecutionPayload, ExecutionPayloadInputV2, ExecutionPayloadSidecar, ForkchoiceState,
+    ForkchoiceUpdated, PayloadAttributes, PayloadStatus,
 };
 use alloy_transport::TransportResult;
 use op_alloy_rpc_types_engine::OpExecutionPayloadV4;
 use reth_node_api::EngineApiMessageVersion;
-use tracing::error;
+use tracing::{debug, error};
 
 /// An extension trait for providers that implement the engine API, to wait for a VALID response.
 #[async_trait::async_trait]
@@ -52,6 +53,13 @@ where
         fork_choice_state: ForkchoiceState,
         payload_attributes: Option<PayloadAttributes>,
     ) -> TransportResult<ForkchoiceUpdated> {
+        debug!(
+            method = "engine_forkchoiceUpdatedV1",
+            ?fork_choice_state,
+            ?payload_attributes,
+            "Sending forkchoiceUpdated"
+        );
+
         let mut status =
             self.fork_choice_updated_v1(fork_choice_state, payload_attributes.clone()).await?;
 
@@ -82,6 +90,13 @@ where
         fork_choice_state: ForkchoiceState,
         payload_attributes: Option<PayloadAttributes>,
     ) -> TransportResult<ForkchoiceUpdated> {
+        debug!(
+            method = "engine_forkchoiceUpdatedV2",
+            ?fork_choice_state,
+            ?payload_attributes,
+            "Sending forkchoiceUpdated"
+        );
+
         let mut status =
             self.fork_choice_updated_v2(fork_choice_state, payload_attributes.clone()).await?;
 
@@ -112,6 +127,13 @@ where
         fork_choice_state: ForkchoiceState,
         payload_attributes: Option<PayloadAttributes>,
     ) -> TransportResult<ForkchoiceUpdated> {
+        debug!(
+            method = "engine_forkchoiceUpdatedV3",
+            ?fork_choice_state,
+            ?payload_attributes,
+            "Sending forkchoiceUpdated"
+        );
+
         let mut status =
             self.fork_choice_updated_v3(fork_choice_state, payload_attributes.clone()).await?;
 
@@ -148,33 +170,47 @@ pub(crate) fn block_to_new_payload(
 
     // Convert to execution payload
     let (payload, sidecar) = ExecutionPayload::from_block_slow(&block);
+    payload_to_new_payload(payload, sidecar, is_optimism, block.withdrawals_root, None)
+}
 
+pub(crate) fn payload_to_new_payload(
+    payload: ExecutionPayload,
+    sidecar: ExecutionPayloadSidecar,
+    is_optimism: bool,
+    withdrawals_root: Option<B256>,
+    target_version: Option<EngineApiMessageVersion>,
+) -> eyre::Result<(EngineApiMessageVersion, serde_json::Value)> {
     let (version, params) = match payload {
         ExecutionPayload::V3(payload) => {
             let cancun = sidecar.cancun().unwrap();
 
             if let Some(prague) = sidecar.prague() {
+                // Use target version if provided (for Osaka), otherwise default to V4
+                let version = target_version.unwrap_or(EngineApiMessageVersion::V4);
+
                 if is_optimism {
+                    let withdrawals_root = withdrawals_root.ok_or_else(|| {
+                        eyre::eyre!("Missing withdrawals root for Optimism payload")
+                    })?;
                     (
-                        EngineApiMessageVersion::V4,
+                        version,
                         serde_json::to_value((
-                            OpExecutionPayloadV4 {
-                                payload_inner: payload,
-                                withdrawals_root: block.withdrawals_root.unwrap(),
-                            },
+                            OpExecutionPayloadV4 { payload_inner: payload, withdrawals_root },
                             cancun.versioned_hashes.clone(),
                             cancun.parent_beacon_block_root,
                             Requests::default(),
                         ))?,
                     )
                 } else {
+                    // Extract actual Requests from RequestsOrHash
+                    let requests = prague.requests.requests_hash();
                     (
-                        EngineApiMessageVersion::V4,
+                        version,
                         serde_json::to_value((
                             payload,
                             cancun.versioned_hashes.clone(),
                             cancun.parent_beacon_block_root,
-                            prague.requests.requests_hash(),
+                            requests,
                         ))?,
                     )
                 }
@@ -217,6 +253,8 @@ pub(crate) async fn call_new_payload<N: Network, P: Provider<N>>(
 ) -> TransportResult<()> {
     let method = version.method_name();
 
+    debug!(method, "Sending newPayload");
+
     let mut status: PayloadStatus = provider.client().request(method, &params).await?;
 
     while !status.is_valid() {
@@ -237,12 +275,15 @@ pub(crate) async fn call_new_payload<N: Network, P: Provider<N>>(
 /// Calls the correct `engine_forkchoiceUpdated` method depending on the given
 /// `EngineApiMessageVersion`, using the provided forkchoice state and payload attributes for the
 /// actual engine api message call.
+///
+/// Note: For Prague (V4), we still use forkchoiceUpdatedV3 as there is no V4.
 pub(crate) async fn call_forkchoice_updated<N, P: EngineApiValidWaitExt<N>>(
     provider: P,
     message_version: EngineApiMessageVersion,
     forkchoice_state: ForkchoiceState,
     payload_attributes: Option<PayloadAttributes>,
 ) -> TransportResult<ForkchoiceUpdated> {
+    // FCU V3 is used for both Cancun and Prague (there is no FCU V4)
     match message_version {
         EngineApiMessageVersion::V3 | EngineApiMessageVersion::V4 | EngineApiMessageVersion::V5 => {
             provider.fork_choice_updated_v3_wait(forkchoice_state, payload_attributes).await

bin/reth/Cargo.toml

@@ -9,6 +9,20 @@ repository.workspace = true
 description = "Reth node implementation"
 default-run = "reth"
 
+[package.metadata.deb]
+maintainer = "reth team"
+depends = "$auto"
+section = "network"
+priority = "optional"
+maintainer-scripts = "../../pkg/reth/debian/"
+assets = [
+    "$auto",
+    ["../../README.md", "usr/share/doc/reth/", "644"],
+    ["../../LICENSE-APACHE", "usr/share/doc/reth/", "644"],
+    ["../../LICENSE-MIT", "usr/share/doc/reth/", "644"],
+]
+systemd-units = { enable = false, start = false, unit-name = "reth", unit-scripts = "../../pkg/reth/debian" }
+
 [lints]
 workspace = true
 
@@ -67,12 +81,16 @@ backon.workspace = true
 tempfile.workspace = true
 
 [features]
-default = ["jemalloc", "otlp", "reth-revm/portable", "js-tracer"]
+default = ["jemalloc", "otlp", "otlp-logs", "reth-revm/portable", "js-tracer", "keccak-cache-global", "asm-keccak"]
 
 otlp = [
     "reth-ethereum-cli/otlp",
     "reth-node-core/otlp",
 ]
+otlp-logs = [
+    "reth-ethereum-cli/otlp-logs",
+    "reth-node-core/otlp-logs",
+]
 js-tracer = [
     "reth-node-builder/js-tracer",
     "reth-node-ethereum/js-tracer",
@@ -88,7 +106,10 @@ asm-keccak = [
     "reth-ethereum-cli/asm-keccak",
     "reth-node-ethereum/asm-keccak",
 ]
-
+keccak-cache-global = [
+    "reth-node-core/keccak-cache-global",
+    "reth-node-ethereum/keccak-cache-global",
+]
 jemalloc = [
     "reth-cli-util/jemalloc",
     "reth-node-core/jemalloc",
@@ -99,10 +120,26 @@ jemalloc-prof = [
     "reth-cli-util/jemalloc",
     "reth-cli-util/jemalloc-prof",
     "reth-ethereum-cli/jemalloc-prof",
+    "reth-node-metrics/jemalloc-prof",
+]
+jemalloc-symbols = [
+    "jemalloc-prof",
+    "reth-ethereum-cli/jemalloc-symbols",
+]
+jemalloc-unprefixed = [
+    "reth-cli-util/jemalloc-unprefixed",
+    "reth-node-core/jemalloc",
+    "reth-node-metrics/jemalloc",
+    "reth-ethereum-cli/jemalloc",
 ]
 tracy-allocator = [
     "reth-cli-util/tracy-allocator",
     "reth-ethereum-cli/tracy-allocator",
+    "tracy",
+]
+tracy = [
+    "reth-ethereum-cli/tracy",
+    "reth-node-core/tracy",
 ]
 
 # Because jemalloc is default and preferred over snmalloc when both features are
@@ -143,6 +180,8 @@ min-trace-logs = [
     "reth-node-core/min-trace-logs",
 ]
 
+edge = ["reth-ethereum-cli/edge", "reth-node-core/edge"]
+
 [[bin]]
 name = "reth"
 path = "src/main.rs"

bin/reth/src/lib.rs

@@ -2,22 +2,46 @@
 //!
 //! ## Feature Flags
 //!
+//! ### Default Features
+//!
 //! - `jemalloc`: Uses [jemallocator](https://github.com/tikv/jemallocator) as the global allocator.
 //!   This is **not recommended on Windows**. See [here](https://rust-lang.github.io/rfcs/1974-global-allocators.html#jemalloc)
 //!   for more info.
+//! - `otlp`: Enables [OpenTelemetry](https://opentelemetry.io/) metrics export to a configured OTLP
+//!   collector endpoint.
+//! - `js-tracer`: Enables the `JavaScript` tracer for the `debug_trace` endpoints, allowing custom
+//!   `JavaScript`-based transaction tracing.
+//! - `keccak-cache-global`: Enables global caching for Keccak256 hashes to improve performance.
+//! - `asm-keccak`: Replaces the default, pure-Rust implementation of Keccak256 with one implemented
+//!   in assembly; see [the `keccak-asm` crate](https://github.com/DaniPopes/keccak-asm) for more
+//!   details and supported targets.
+//!
+//! ### Allocator Features
+//!
 //! - `jemalloc-prof`: Enables [jemallocator's](https://github.com/tikv/jemallocator) heap profiling
 //!   and leak detection functionality. See [jemalloc's opt.prof](https://jemalloc.net/jemalloc.3.html#opt.prof)
-//!   documentation for usage details. This is **not recommended on Windows**. See [here](https://rust-lang.github.io/rfcs/1974-global-allocators.html#jemalloc)
-//!   for more info.
-//! - `asm-keccak`: replaces the default, pure-Rust implementation of Keccak256 with one implemented
-//!   in assembly; see [the `keccak-asm` crate](https://github.com/DaniPopes/keccak-asm) for more
-//!   details and supported targets
+//!   documentation for usage details. This is **not recommended on Windows**.
+//! - `jemalloc-symbols`: Enables jemalloc symbols for profiling. Includes `jemalloc-prof`.
+//! - `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-native`: Uses snmalloc with native CPU optimizations. Use `--no-default-features`
+//!   when enabling this.
+//!
+//! ### Log Level Features
+//!
 //! - `min-error-logs`: Disables all logs below `error` level.
 //! - `min-warn-logs`: Disables all logs below `warn` level.
 //! - `min-info-logs`: Disables all logs below `info` level. This can speed up the node, since fewer
 //!   calls to the logging component are made.
 //! - `min-debug-logs`: Disables all logs below `debug` level.
 //! - `min-trace-logs`: Disables all logs below `trace` level.
+//!
+//! ### Development Features
+//!
+//! - `dev`: Enables development mode features, including test vector generation commands.
 
 #![doc(
     html_logo_url = "https://raw.githubusercontent.com/paradigmxyz/reth/main/assets/reth-docs.png",
@@ -170,7 +194,7 @@ pub mod rpc {
         pub use reth_rpc::eth::*;
     }
 
-    /// Re-exported from `reth_rpc::rpc`.
+    /// Re-exported from `reth_rpc_server_types::result`.
     pub mod result {
         pub use reth_rpc_server_types::result::*;
     }

bin/reth/src/main.rs

@@ -3,6 +3,10 @@
 #[global_allocator]
 static ALLOC: reth_cli_util::allocator::Allocator = reth_cli_util::allocator::new_allocator();
 
+#[cfg(all(feature = "jemalloc-prof", unix))]
+#[unsafe(export_name = "_rjem_malloc_conf")]
+static MALLOC_CONF: &[u8] = b"prof:true,prof_active:true,lg_prof_sample:19\0";
+
 use clap::Parser;
 use reth::{args::RessArgs, cli::Cli, ress::install_ress_subprotocol};
 use reth_ethereum_cli::chainspec::EthereumChainSpecParser;

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/chain_info.rs

@@ -33,6 +33,7 @@ where
     ) -> Self {
         let (finalized_block, _) = watch::channel(finalized);
         let (safe_block, _) = watch::channel(safe);
+        let (persisted_block, _) = watch::channel(None);
 
         Self {
             inner: Arc::new(ChainInfoInner {
@@ -42,6 +43,7 @@ where
                 canonical_head: RwLock::new(head),
                 safe_block,
                 finalized_block,
+                persisted_block,
             }),
         }
     }
@@ -97,6 +99,11 @@ where
         self.inner.finalized_block.borrow().as_ref().map(SealedHeader::num_hash)
     }
 
+    /// Returns the `BlockNumHash` of the persisted block.
+    pub fn get_persisted_num_hash(&self) -> Option<BlockNumHash> {
+        *self.inner.persisted_block.borrow()
+    }
+
     /// Sets the canonical head of the chain.
     pub fn set_canonical_head(&self, header: SealedHeader<N::BlockHeader>) {
         let number = header.number();
@@ -130,6 +137,18 @@ where
         });
     }
 
+    /// Sets the persisted block of the chain.
+    pub fn set_persisted(&self, num_hash: BlockNumHash) {
+        self.inner.persisted_block.send_if_modified(|current| {
+            if current.map(|b| b.hash) != Some(num_hash.hash) {
+                let _ = current.replace(num_hash);
+                return true
+            }
+
+            false
+        });
+    }
+
     /// Subscribe to the finalized block.
     pub fn subscribe_finalized_block(
         &self,
@@ -141,6 +160,11 @@ where
     pub fn subscribe_safe_block(&self) -> watch::Receiver<Option<SealedHeader<N::BlockHeader>>> {
         self.inner.safe_block.subscribe()
     }
+
+    /// Subscribe to the persisted block.
+    pub fn subscribe_persisted_block(&self) -> watch::Receiver<Option<BlockNumHash>> {
+        self.inner.persisted_block.subscribe()
+    }
 }
 
 /// Container type for all chain info fields
@@ -159,11 +183,14 @@ struct ChainInfoInner<N: NodePrimitives = reth_ethereum_primitives::EthPrimitive
     safe_block: watch::Sender<Option<SealedHeader<N::BlockHeader>>>,
     /// The block that the beacon node considers finalized.
     finalized_block: watch::Sender<Option<SealedHeader<N::BlockHeader>>>,
+    /// The last block that was persisted to disk.
+    persisted_block: watch::Sender<Option<BlockNumHash>>,
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
+    use alloy_primitives::B256;
     use reth_ethereum_primitives::EthPrimitives;
     use reth_testing_utils::{generators, generators::random_header};
 
@@ -338,4 +365,28 @@ mod tests {
         // Assert that the BlockNumHash returned matches the safe header
         assert_eq!(tracker.get_safe_num_hash(), Some(safe_header.num_hash()));
     }
+
+    #[test]
+    fn test_set_persisted() {
+        let mut rng = generators::rng();
+        let header = random_header(&mut rng, 10, None);
+        let tracker: ChainInfoTracker<EthPrimitives> = ChainInfoTracker::new(header, None, None);
+
+        // Initial state: persisted block should be None
+        assert!(tracker.get_persisted_num_hash().is_none());
+
+        // Set a persisted block
+        let num_hash1 = BlockNumHash::new(10, B256::random());
+        tracker.set_persisted(num_hash1);
+        assert_eq!(tracker.get_persisted_num_hash(), Some(num_hash1));
+
+        // Setting the same block again should not change anything
+        tracker.set_persisted(num_hash1);
+        assert_eq!(tracker.get_persisted_num_hash(), Some(num_hash1));
+
+        // Set a different block
+        let num_hash2 = BlockNumHash::new(20, B256::random());
+        tracker.set_persisted(num_hash2);
+        assert_eq!(tracker.get_persisted_num_hash(), Some(num_hash2));
+    }
 }

crates/chain-state/src/deferred_trie.rs

@@ -0,0 +1,936 @@
+use alloy_primitives::B256;
+use parking_lot::Mutex;
+use reth_metrics::{metrics::Counter, Metrics};
+use reth_trie::{
+    updates::{TrieUpdates, TrieUpdatesSorted},
+    HashedPostState, HashedPostStateSorted, TrieInputSorted,
+};
+use std::{
+    fmt,
+    sync::{Arc, LazyLock},
+};
+use tracing::instrument;
+
+/// Shared handle to asynchronously populated trie data.
+///
+/// Uses a try-lock + fallback computation approach for deadlock-free access.
+/// If the deferred task hasn't completed, computes trie data synchronously
+/// from stored unsorted inputs rather than blocking.
+#[derive(Clone)]
+pub struct DeferredTrieData {
+    /// Shared deferred state holding either raw inputs (pending) or computed result (ready).
+    state: Arc<Mutex<DeferredState>>,
+}
+
+/// Sorted trie data computed for an executed block.
+/// These represent the complete set of sorted trie data required to persist
+/// block state for, and generate proofs on top of, a block.
+#[derive(Clone, Debug, Default)]
+pub struct ComputedTrieData {
+    /// Sorted hashed post-state produced by execution.
+    pub hashed_state: Arc<HashedPostStateSorted>,
+    /// Sorted trie updates produced by state root computation.
+    pub trie_updates: Arc<TrieUpdatesSorted>,
+    /// Trie input bundled with its anchor hash, if available.
+    pub anchored_trie_input: Option<AnchoredTrieInput>,
+}
+
+/// Trie input bundled with its anchor hash.
+///
+/// The `trie_input` contains the **cumulative** overlay of all in-memory ancestor blocks,
+/// not just this block's changes. Child blocks reuse the parent's overlay in O(1) by
+/// cloning the Arc-wrapped data.
+///
+/// The `anchor_hash` is metadata indicating which persisted base state this overlay
+/// sits on top of. It is CRITICAL for overlay reuse decisions: an overlay built on top
+/// of Anchor A cannot be reused for a block anchored to Anchor B, as it would result
+/// in an incorrect state.
+#[derive(Clone, Debug)]
+pub struct AnchoredTrieInput {
+    /// The persisted ancestor hash this trie input is anchored to.
+    pub anchor_hash: B256,
+    /// Cumulative trie input overlay from all in-memory ancestors.
+    pub trie_input: Arc<TrieInputSorted>,
+}
+
+/// Metrics for deferred trie computation.
+#[derive(Metrics)]
+#[metrics(scope = "sync.block_validation")]
+struct DeferredTrieMetrics {
+    /// Number of times deferred trie data was ready (async task completed first).
+    deferred_trie_async_ready: Counter,
+    /// Number of times deferred trie data required synchronous computation (fallback path).
+    deferred_trie_sync_fallback: Counter,
+}
+
+static DEFERRED_TRIE_METRICS: LazyLock<DeferredTrieMetrics> =
+    LazyLock::new(DeferredTrieMetrics::default);
+
+/// Internal state for deferred trie data.
+enum DeferredState {
+    /// Data is not yet available; raw inputs stored for fallback computation.
+    /// Wrapped in `Option` to allow taking ownership during computation.
+    Pending(Option<PendingInputs>),
+    /// Data has been computed and is ready.
+    Ready(ComputedTrieData),
+}
+
+/// Inputs kept while a deferred trie computation is pending.
+#[derive(Clone, Debug)]
+struct PendingInputs {
+    /// Unsorted hashed post-state from execution.
+    hashed_state: Arc<HashedPostState>,
+    /// Unsorted trie updates from state root computation.
+    trie_updates: Arc<TrieUpdates>,
+    /// The persisted ancestor hash this trie input is anchored to.
+    anchor_hash: B256,
+    /// Deferred trie data from ancestor blocks for merging.
+    ancestors: Vec<DeferredTrieData>,
+}
+
+impl fmt::Debug for DeferredTrieData {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let state = self.state.lock();
+        match &*state {
+            DeferredState::Pending(_) => {
+                f.debug_struct("DeferredTrieData").field("state", &"pending").finish()
+            }
+            DeferredState::Ready(_) => {
+                f.debug_struct("DeferredTrieData").field("state", &"ready").finish()
+            }
+        }
+    }
+}
+
+impl DeferredTrieData {
+    /// Create a new pending handle with fallback inputs for synchronous computation.
+    ///
+    /// If the async task hasn't completed when `wait_cloned` is called, the trie data
+    /// will be computed synchronously from these inputs. This eliminates deadlock risk.
+    ///
+    /// # Arguments
+    /// * `hashed_state` - Unsorted hashed post-state from execution
+    /// * `trie_updates` - Unsorted trie updates from state root computation
+    /// * `anchor_hash` - The persisted ancestor hash this trie input is anchored to
+    /// * `ancestors` - Deferred trie data from ancestor blocks for merging
+    pub fn pending(
+        hashed_state: Arc<HashedPostState>,
+        trie_updates: Arc<TrieUpdates>,
+        anchor_hash: B256,
+        ancestors: Vec<Self>,
+    ) -> Self {
+        Self {
+            state: Arc::new(Mutex::new(DeferredState::Pending(Some(PendingInputs {
+                hashed_state,
+                trie_updates,
+                anchor_hash,
+                ancestors,
+            })))),
+        }
+    }
+
+    /// Create a handle that is already populated with the given [`ComputedTrieData`].
+    ///
+    /// Useful when trie data is available immediately.
+    /// [`Self::wait_cloned`] will return without any computation.
+    pub fn ready(bundle: ComputedTrieData) -> Self {
+        Self { state: Arc::new(Mutex::new(DeferredState::Ready(bundle))) }
+    }
+
+    /// Sort block execution outputs and build a [`TrieInputSorted`] overlay.
+    ///
+    /// The trie input overlay accumulates sorted hashed state (account/storage changes) and
+    /// trie node updates from all in-memory ancestor blocks. This overlay is required for:
+    /// - Computing state roots on top of in-memory blocks
+    /// - Generating storage/account proofs for unpersisted state
+    ///
+    /// # Process
+    /// 1. Sort the current block's hashed state and trie updates
+    /// 2. Reuse parent's cached overlay if available (O(1) - the common case)
+    /// 3. Otherwise, rebuild overlay from ancestors (rare fallback)
+    /// 4. Extend the overlay with this block's sorted data
+    ///
+    /// Used by both the async background task and the synchronous fallback path.
+    ///
+    /// # Arguments
+    /// * `hashed_state` - Unsorted hashed post-state (account/storage changes) from execution
+    /// * `trie_updates` - Unsorted trie node updates from state root computation
+    /// * `anchor_hash` - The persisted ancestor hash this trie input is anchored to
+    /// * `ancestors` - Deferred trie data from ancestor blocks for merging (oldest -> newest)
+    pub fn sort_and_build_trie_input(
+        hashed_state: Arc<HashedPostState>,
+        trie_updates: Arc<TrieUpdates>,
+        anchor_hash: B256,
+        ancestors: &[Self],
+    ) -> ComputedTrieData {
+        #[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
+        // persisted anchor. If the anchor has changed (e.g., due to persistence),
+        // the parent's overlay is relative to an old state and cannot be used.
+        let overlay = if let Some(parent) = ancestors.last() {
+            let parent_data = parent.wait_cloned();
+
+            match &parent_data.anchored_trie_input {
+                // Case 1: Parent has cached overlay AND anchors match.
+                Some(AnchoredTrieInput { anchor_hash: parent_anchor, trie_input })
+                    if *parent_anchor == anchor_hash =>
+                {
+                    // O(1): Reuse parent's overlay, extend with current block's data.
+                    let mut overlay = TrieInputSorted::new(
+                        Arc::clone(&trie_input.nodes),
+                        Arc::clone(&trie_input.state),
+                        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);
+                    }
+                    if !sorted_trie_updates.is_empty() {
+                        Arc::make_mut(&mut overlay.nodes).extend_ref_and_sort(&sorted_trie_updates);
+                    }
+                    overlay
+                }
+                // Case 2: Parent exists but anchor mismatch or no cached overlay.
+                // We must rebuild from the ancestors list (which only contains unpersisted blocks).
+                _ => Self::merge_ancestors_into_overlay(
+                    ancestors,
+                    &sorted_hashed_state,
+                    &sorted_trie_updates,
+                ),
+            }
+        } else {
+            // Case 3: No in-memory ancestors (first block after persisted anchor).
+            // Build overlay with just this block's data.
+            Self::merge_ancestors_into_overlay(&[], &sorted_hashed_state, &sorted_trie_updates)
+        };
+
+        ComputedTrieData::with_trie_input(
+            Arc::new(sorted_hashed_state),
+            Arc::new(sorted_trie_updates),
+            anchor_hash,
+            Arc::new(overlay),
+        )
+    }
+
+    /// Merge all ancestors and current block's data into a single overlay.
+    ///
+    /// This is a rare fallback path, only used when no ancestor has a cached
+    /// `anchored_trie_input` (e.g., blocks created via alternative constructors).
+    /// In normal operation, the parent always has a cached overlay and this
+    /// function is never called.
+    ///
+    /// When the `rayon` feature is enabled, uses parallel collection and merge:
+    /// 1. Collects ancestor data in parallel (each `wait_cloned()` may compute)
+    /// 2. Merges hashed state and trie updates in parallel with each other
+    /// 3. Uses tree reduction within each merge for O(log n) depth
+    #[cfg(feature = "rayon")]
+    fn merge_ancestors_into_overlay(
+        ancestors: &[Self],
+        sorted_hashed_state: &HashedPostStateSorted,
+        sorted_trie_updates: &TrieUpdatesSorted,
+    ) -> TrieInputSorted {
+        // Early exit: no ancestors means just wrap current block's data
+        if ancestors.is_empty() {
+            return TrieInputSorted::new(
+                Arc::new(sorted_trie_updates.clone()),
+                Arc::new(sorted_hashed_state.clone()),
+                Default::default(),
+            );
+        }
+
+        // Collect ancestor data, unzipping states and updates into Arc slices
+        let (states, updates): (Vec<_>, Vec<_>) = ancestors
+            .iter()
+            .map(|a| {
+                let data = a.wait_cloned();
+                (data.hashed_state, data.trie_updates)
+            })
+            .unzip();
+
+        // Merge state and nodes in parallel with each other using tree reduction
+        let (state, nodes) = rayon::join(
+            || {
+                let mut merged = HashedPostStateSorted::merge_parallel(&states);
+                merged.extend_ref_and_sort(sorted_hashed_state);
+                merged
+            },
+            || {
+                let mut merged = TrieUpdatesSorted::merge_parallel(&updates);
+                merged.extend_ref_and_sort(sorted_trie_updates);
+                merged
+            },
+        );
+
+        TrieInputSorted::new(Arc::new(nodes), Arc::new(state), Default::default())
+    }
+
+    /// Merge all ancestors and current block's data into a single overlay (sequential fallback).
+    #[cfg(not(feature = "rayon"))]
+    fn merge_ancestors_into_overlay(
+        ancestors: &[Self],
+        sorted_hashed_state: &HashedPostStateSorted,
+        sorted_trie_updates: &TrieUpdatesSorted,
+    ) -> TrieInputSorted {
+        let mut overlay = TrieInputSorted::default();
+
+        let state_mut = Arc::make_mut(&mut overlay.state);
+        let nodes_mut = Arc::make_mut(&mut overlay.nodes);
+
+        for ancestor in ancestors {
+            let ancestor_data = ancestor.wait_cloned();
+            state_mut.extend_ref_and_sort(ancestor_data.hashed_state.as_ref());
+            nodes_mut.extend_ref_and_sort(ancestor_data.trie_updates.as_ref());
+        }
+
+        // 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);
+
+        overlay
+    }
+
+    /// Returns trie data, computing synchronously if the async task hasn't completed.
+    ///
+    /// - If the async task has completed (`Ready`), returns the cached result.
+    /// - If pending, computes synchronously from stored inputs.
+    ///
+    /// Deadlock is avoided as long as the provided ancestors form a true ancestor chain (a DAG):
+    /// - Each block only waits on its ancestors (blocks on the path to the persisted root)
+    /// - Sibling blocks (forks) are never in each other's ancestor lists
+    /// - A block never waits on its descendants
+    ///
+    /// Given that invariant, circular wait dependencies are impossible.
+    #[instrument(level = "debug", target = "engine::tree::deferred_trie", skip_all)]
+    pub fn wait_cloned(&self) -> ComputedTrieData {
+        let mut state = self.state.lock();
+        match &mut *state {
+            // If the deferred trie data is ready, return the cached result.
+            DeferredState::Ready(bundle) => {
+                DEFERRED_TRIE_METRICS.deferred_trie_async_ready.increment(1);
+                bundle.clone()
+            }
+            // If the deferred trie data is pending, compute the trie data synchronously and return
+            // the result. This is the fallback path if the async task hasn't completed.
+            DeferredState::Pending(maybe_inputs) => {
+                DEFERRED_TRIE_METRICS.deferred_trie_sync_fallback.increment(1);
+
+                let inputs = maybe_inputs.take().expect("inputs must be present in Pending state");
+
+                let computed = Self::sort_and_build_trie_input(
+                    inputs.hashed_state,
+                    inputs.trie_updates,
+                    inputs.anchor_hash,
+                    &inputs.ancestors,
+                );
+                *state = DeferredState::Ready(computed.clone());
+
+                // Release lock before inputs (and its ancestors) drop to avoid holding it
+                // while their potential last Arc refs drop (which could trigger recursive locking)
+                drop(state);
+
+                computed
+            }
+        }
+    }
+}
+
+impl ComputedTrieData {
+    /// Construct a bundle that includes trie input anchored to a persisted ancestor.
+    pub const fn with_trie_input(
+        hashed_state: Arc<HashedPostStateSorted>,
+        trie_updates: Arc<TrieUpdatesSorted>,
+        anchor_hash: B256,
+        trie_input: Arc<TrieInputSorted>,
+    ) -> Self {
+        Self {
+            hashed_state,
+            trie_updates,
+            anchored_trie_input: Some(AnchoredTrieInput { anchor_hash, trie_input }),
+        }
+    }
+
+    /// Construct a bundle without trie input or anchor information.
+    ///
+    /// Unlike [`Self::with_trie_input`], this constructor omits the accumulated trie input overlay
+    /// and its anchor hash. Use this when the trie input is not needed, such as in block builders
+    /// or sequencers that don't require proof generation on top of in-memory state.
+    ///
+    /// The trie input anchor identifies the persisted block hash from which the in-memory overlay
+    /// was built. Without it, consumers cannot determine which on-disk state to combine with.
+    pub const fn without_trie_input(
+        hashed_state: Arc<HashedPostStateSorted>,
+        trie_updates: Arc<TrieUpdatesSorted>,
+    ) -> Self {
+        Self { hashed_state, trie_updates, anchored_trie_input: None }
+    }
+
+    /// Returns the anchor hash, if present.
+    pub fn anchor_hash(&self) -> Option<B256> {
+        self.anchored_trie_input.as_ref().map(|anchored| anchored.anchor_hash)
+    }
+
+    /// Returns the trie input, if present.
+    pub fn trie_input(&self) -> Option<&Arc<TrieInputSorted>> {
+        self.anchored_trie_input.as_ref().map(|anchored| &anchored.trie_input)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use alloy_primitives::{map::B256Map, U256};
+    use reth_primitives_traits::Account;
+    use reth_trie::updates::TrieUpdates;
+    use std::{
+        sync::Arc,
+        thread,
+        time::{Duration, Instant},
+    };
+
+    fn empty_bundle() -> ComputedTrieData {
+        ComputedTrieData {
+            hashed_state: Arc::default(),
+            trie_updates: Arc::default(),
+            anchored_trie_input: None,
+        }
+    }
+
+    fn empty_pending() -> DeferredTrieData {
+        empty_pending_with_anchor(B256::ZERO)
+    }
+
+    fn empty_pending_with_anchor(anchor: B256) -> DeferredTrieData {
+        DeferredTrieData::pending(
+            Arc::new(HashedPostState::default()),
+            Arc::new(TrieUpdates::default()),
+            anchor,
+            Vec::new(),
+        )
+    }
+
+    /// Verifies that a ready handle returns immediately without computation.
+    #[test]
+    fn ready_returns_immediately() {
+        let bundle = empty_bundle();
+        let deferred = DeferredTrieData::ready(bundle.clone());
+
+        let start = Instant::now();
+        let result = deferred.wait_cloned();
+        let elapsed = start.elapsed();
+
+        assert_eq!(result.hashed_state, bundle.hashed_state);
+        assert_eq!(result.trie_updates, bundle.trie_updates);
+        assert_eq!(result.anchor_hash(), bundle.anchor_hash());
+        assert!(elapsed < Duration::from_millis(20));
+    }
+
+    /// Verifies that a pending handle computes trie data synchronously via fallback.
+    #[test]
+    fn pending_computes_fallback() {
+        let deferred = empty_pending();
+
+        // wait_cloned should compute from inputs without blocking
+        let start = Instant::now();
+        let result = deferred.wait_cloned();
+        let elapsed = start.elapsed();
+
+        // Should return quickly (fallback computation)
+        assert!(elapsed < Duration::from_millis(100));
+        assert!(result.hashed_state.is_empty());
+    }
+
+    /// Verifies that fallback computation result is cached for subsequent calls.
+    #[test]
+    fn fallback_result_is_cached() {
+        let deferred = empty_pending();
+
+        // First call computes and should stash the result
+        let first = deferred.wait_cloned();
+        // Second call should reuse the cached result (same Arc pointer)
+        let second = deferred.wait_cloned();
+
+        assert!(Arc::ptr_eq(&first.hashed_state, &second.hashed_state));
+        assert!(Arc::ptr_eq(&first.trie_updates, &second.trie_updates));
+        assert_eq!(first.anchor_hash(), second.anchor_hash());
+    }
+
+    /// Verifies that concurrent `wait_cloned` calls result in only one computation,
+    /// with all callers receiving the same cached result.
+    #[test]
+    fn concurrent_wait_cloned_computes_once() {
+        let deferred = empty_pending();
+
+        // Spawn multiple threads that all call wait_cloned concurrently
+        let handles: Vec<_> = (0..10)
+            .map(|_| {
+                let d = deferred.clone();
+                thread::spawn(move || d.wait_cloned())
+            })
+            .collect();
+
+        // Collect all results
+        let results: Vec<_> = handles.into_iter().map(|h| h.join().unwrap()).collect();
+
+        // All results should share the same Arc pointers (same computed result)
+        let first = &results[0];
+        for result in &results[1..] {
+            assert!(Arc::ptr_eq(&first.hashed_state, &result.hashed_state));
+            assert!(Arc::ptr_eq(&first.trie_updates, &result.trie_updates));
+        }
+    }
+
+    /// Tests that ancestor trie data is merged during fallback computation and that the
+    /// resulting `ComputedTrieData` uses the current block's anchor hash, not the ancestor's.
+    #[test]
+    fn ancestors_are_merged() {
+        // Create ancestor with some data
+        let ancestor_bundle = ComputedTrieData {
+            hashed_state: Arc::default(),
+            trie_updates: Arc::default(),
+            anchored_trie_input: Some(AnchoredTrieInput {
+                anchor_hash: B256::with_last_byte(1),
+                trie_input: Arc::new(TrieInputSorted::default()),
+            }),
+        };
+        let ancestor = DeferredTrieData::ready(ancestor_bundle);
+
+        // Create pending with ancestor
+        let deferred = DeferredTrieData::pending(
+            Arc::new(HashedPostState::default()),
+            Arc::new(TrieUpdates::default()),
+            B256::with_last_byte(2),
+            vec![ancestor],
+        );
+
+        let result = deferred.wait_cloned();
+        // Should have the current block's anchor, not the ancestor's
+        assert_eq!(result.anchor_hash(), Some(B256::with_last_byte(2)));
+    }
+
+    /// Ensures ancestor overlays are merged oldest -> newest so latest state wins (no overwrite by
+    /// older ancestors).
+    #[test]
+    fn ancestors_merge_in_chronological_order() {
+        let key = B256::with_last_byte(1);
+        // Oldest ancestor sets nonce to 1
+        let oldest_state = HashedPostStateSorted::new(
+            vec![(key, Some(Account { nonce: 1, balance: U256::ZERO, bytecode_hash: None }))],
+            B256Map::default(),
+        );
+        // Newest ancestor overwrites nonce to 2
+        let newest_state = HashedPostStateSorted::new(
+            vec![(key, Some(Account { nonce: 2, balance: U256::ZERO, bytecode_hash: None }))],
+            B256Map::default(),
+        );
+
+        let oldest = ComputedTrieData {
+            hashed_state: Arc::new(oldest_state),
+            trie_updates: Arc::default(),
+            anchored_trie_input: None,
+        };
+        let newest = ComputedTrieData {
+            hashed_state: Arc::new(newest_state),
+            trie_updates: Arc::default(),
+            anchored_trie_input: None,
+        };
+
+        // Pass ancestors oldest -> newest; newest should take precedence
+        let deferred = DeferredTrieData::pending(
+            Arc::new(HashedPostState::default()),
+            Arc::new(TrieUpdates::default()),
+            B256::ZERO,
+            vec![DeferredTrieData::ready(oldest), DeferredTrieData::ready(newest)],
+        );
+
+        let result = deferred.wait_cloned();
+        let overlay_state = &result.anchored_trie_input.as_ref().unwrap().trie_input.state.accounts;
+        assert_eq!(overlay_state.len(), 1);
+        let (_, account) = &overlay_state[0];
+        assert_eq!(account.unwrap().nonce, 2);
+    }
+
+    /// Helper to create a ready block with anchored trie input containing specific state.
+    fn ready_block_with_state(
+        anchor_hash: B256,
+        accounts: Vec<(B256, Option<Account>)>,
+    ) -> DeferredTrieData {
+        let hashed_state = Arc::new(HashedPostStateSorted::new(accounts, B256Map::default()));
+        let trie_updates = Arc::default();
+        let mut overlay = TrieInputSorted::default();
+        Arc::make_mut(&mut overlay.state).extend_ref_and_sort(hashed_state.as_ref());
+
+        DeferredTrieData::ready(ComputedTrieData {
+            hashed_state,
+            trie_updates,
+            anchored_trie_input: Some(AnchoredTrieInput {
+                anchor_hash,
+                trie_input: Arc::new(overlay),
+            }),
+        })
+    }
+
+    /// Verifies that first block after anchor (no ancestors) creates empty base overlay.
+    #[test]
+    fn first_block_after_anchor_creates_empty_base() {
+        let anchor = B256::with_last_byte(1);
+        let key = B256::with_last_byte(42);
+        let account = Account { nonce: 1, balance: U256::ZERO, bytecode_hash: None };
+
+        // First block after anchor - no ancestors
+        let first_block = DeferredTrieData::pending(
+            Arc::new(HashedPostState::default().with_accounts([(key, Some(account))])),
+            Arc::new(TrieUpdates::default()),
+            anchor,
+            vec![], // No ancestors
+        );
+
+        let result = first_block.wait_cloned();
+
+        // Should have overlay with just this block's data
+        let overlay = result.anchored_trie_input.as_ref().unwrap();
+        assert_eq!(overlay.anchor_hash, anchor);
+        assert_eq!(overlay.trie_input.state.accounts.len(), 1);
+        let (found_key, found_account) = &overlay.trie_input.state.accounts[0];
+        assert_eq!(*found_key, key);
+        assert_eq!(found_account.unwrap().nonce, 1);
+    }
+
+    /// Verifies that parent's overlay is reused regardless of anchor.
+    #[test]
+    fn reuses_parent_overlay() {
+        let anchor = B256::with_last_byte(1);
+        let key = B256::with_last_byte(42);
+        let account = Account { nonce: 100, balance: U256::ZERO, bytecode_hash: None };
+
+        // Create parent with anchored trie input
+        let parent = ready_block_with_state(anchor, vec![(key, Some(account))]);
+
+        // Create child - should reuse parent's overlay
+        let child = DeferredTrieData::pending(
+            Arc::new(HashedPostState::default()),
+            Arc::new(TrieUpdates::default()),
+            anchor,
+            vec![parent],
+        );
+
+        let result = child.wait_cloned();
+
+        // Verify parent's account is in the overlay
+        let overlay = result.anchored_trie_input.as_ref().unwrap();
+        assert_eq!(overlay.anchor_hash, anchor);
+        assert_eq!(overlay.trie_input.state.accounts.len(), 1);
+        let (found_key, found_account) = &overlay.trie_input.state.accounts[0];
+        assert_eq!(*found_key, key);
+        assert_eq!(found_account.unwrap().nonce, 100);
+    }
+
+    /// Verifies that parent's overlay is NOT reused when anchor changes (after persist).
+    /// The overlay data is dependent on the anchor, so it must be rebuilt from the
+    /// remaining ancestors.
+    #[test]
+    fn rebuilds_overlay_when_anchor_changes() {
+        let old_anchor = B256::with_last_byte(1);
+        let new_anchor = B256::with_last_byte(2);
+        let key = B256::with_last_byte(42);
+        let account = Account { nonce: 50, balance: U256::ZERO, bytecode_hash: None };
+
+        // Create parent with OLD anchor
+        let parent = ready_block_with_state(old_anchor, vec![(key, Some(account))]);
+
+        // Create child with NEW anchor (simulates after persist)
+        // Should NOT reuse parent's overlay because anchor changed
+        let child = DeferredTrieData::pending(
+            Arc::new(HashedPostState::default()),
+            Arc::new(TrieUpdates::default()),
+            new_anchor,
+            vec![parent],
+        );
+
+        let result = child.wait_cloned();
+
+        // Verify result uses new anchor
+        let overlay = result.anchored_trie_input.as_ref().unwrap();
+        assert_eq!(overlay.anchor_hash, new_anchor);
+
+        // Crucially, since we provided `parent` in ancestors but it has a different anchor,
+        // the code falls back to `merge_ancestors_into_overlay`.
+        // `merge_ancestors_into_overlay` reads `parent.hashed_state` (which has the account).
+        // So the account IS present, but it was obtained via REBUILD, not REUSE.
+        // We can check `DEFERRED_TRIE_METRICS` if we want to be sure, but functionally:
+        assert_eq!(overlay.trie_input.state.accounts.len(), 1);
+        let (found_key, found_account) = &overlay.trie_input.state.accounts[0];
+        assert_eq!(*found_key, key);
+        assert_eq!(found_account.unwrap().nonce, 50);
+    }
+
+    /// Verifies that parent without `anchored_trie_input` triggers rebuild path.
+    #[test]
+    fn rebuilds_when_parent_has_no_anchored_input() {
+        let anchor = B256::with_last_byte(1);
+        let key = B256::with_last_byte(42);
+        let account = Account { nonce: 25, balance: U256::ZERO, bytecode_hash: None };
+
+        // Create parent WITHOUT anchored trie input (e.g., from without_trie_input constructor)
+        let parent_state =
+            HashedPostStateSorted::new(vec![(key, Some(account))], B256Map::default());
+        let parent = DeferredTrieData::ready(ComputedTrieData {
+            hashed_state: Arc::new(parent_state),
+            trie_updates: Arc::default(),
+            anchored_trie_input: None, // No anchored input
+        });
+
+        // Create child - should rebuild from parent's hashed_state
+        let child = DeferredTrieData::pending(
+            Arc::new(HashedPostState::default()),
+            Arc::new(TrieUpdates::default()),
+            anchor,
+            vec![parent],
+        );
+
+        let result = child.wait_cloned();
+
+        // Verify overlay is built and contains parent's data
+        let overlay = result.anchored_trie_input.as_ref().unwrap();
+        assert_eq!(overlay.anchor_hash, anchor);
+        assert_eq!(overlay.trie_input.state.accounts.len(), 1);
+    }
+
+    /// Verifies that a chain of blocks with matching anchors builds correct cumulative overlay.
+    #[test]
+    fn chain_of_blocks_builds_cumulative_overlay() {
+        let anchor = B256::with_last_byte(1);
+        let key1 = B256::with_last_byte(1);
+        let key2 = B256::with_last_byte(2);
+        let key3 = B256::with_last_byte(3);
+
+        // Block 1: sets account at key1
+        let block1 = ready_block_with_state(
+            anchor,
+            vec![(key1, Some(Account { nonce: 1, balance: U256::ZERO, bytecode_hash: None }))],
+        );
+
+        // Block 2: adds account at key2, ancestor is block1
+        let block2_hashed = HashedPostState::default().with_accounts([(
+            key2,
+            Some(Account { nonce: 2, balance: U256::ZERO, bytecode_hash: None }),
+        )]);
+        let block2 = DeferredTrieData::pending(
+            Arc::new(block2_hashed),
+            Arc::new(TrieUpdates::default()),
+            anchor,
+            vec![block1.clone()],
+        );
+        // Compute block2's trie data
+        let block2_computed = block2.wait_cloned();
+        let block2_ready = DeferredTrieData::ready(block2_computed);
+
+        // Block 3: adds account at key3, ancestor is block2 (which includes block1)
+        let block3_hashed = HashedPostState::default().with_accounts([(
+            key3,
+            Some(Account { nonce: 3, balance: U256::ZERO, bytecode_hash: None }),
+        )]);
+        let block3 = DeferredTrieData::pending(
+            Arc::new(block3_hashed),
+            Arc::new(TrieUpdates::default()),
+            anchor,
+            vec![block1, block2_ready],
+        );
+
+        let result = block3.wait_cloned();
+
+        // Verify all three accounts are in the cumulative overlay
+        let overlay = result.anchored_trie_input.as_ref().unwrap();
+        assert_eq!(overlay.trie_input.state.accounts.len(), 3);
+
+        // Accounts should be sorted by key (B256 ordering)
+        let accounts = &overlay.trie_input.state.accounts;
+        assert!(accounts.iter().any(|(k, a)| *k == key1 && a.unwrap().nonce == 1));
+        assert!(accounts.iter().any(|(k, a)| *k == key2 && a.unwrap().nonce == 2));
+        assert!(accounts.iter().any(|(k, a)| *k == key3 && a.unwrap().nonce == 3));
+    }
+
+    /// Verifies that child block's state overwrites parent's state for the same key.
+    #[test]
+    fn child_state_overwrites_parent() {
+        let anchor = B256::with_last_byte(1);
+        let key = B256::with_last_byte(42);
+
+        // Parent sets nonce to 10
+        let parent = ready_block_with_state(
+            anchor,
+            vec![(key, Some(Account { nonce: 10, balance: U256::ZERO, bytecode_hash: None }))],
+        );
+
+        // Child overwrites nonce to 99
+        let child_hashed = HashedPostState::default().with_accounts([(
+            key,
+            Some(Account { nonce: 99, balance: U256::ZERO, bytecode_hash: None }),
+        )]);
+        let child = DeferredTrieData::pending(
+            Arc::new(child_hashed),
+            Arc::new(TrieUpdates::default()),
+            anchor,
+            vec![parent],
+        );
+
+        let result = child.wait_cloned();
+
+        // Verify child's value wins (extend_ref uses later value)
+        let overlay = result.anchored_trie_input.as_ref().unwrap();
+        // Note: extend_ref may result in duplicate keys; check the last occurrence
+        let accounts = &overlay.trie_input.state.accounts;
+        let last_account = accounts.iter().rfind(|(k, _)| *k == key).unwrap();
+        assert_eq!(last_account.1.unwrap().nonce, 99);
+    }
+
+    /// Stress test: verify O(N) behavior by building a chain of many blocks.
+    /// This test ensures the fix doesn't regress - previously this would be O(N²).
+    #[test]
+    fn long_chain_builds_in_linear_time() {
+        let anchor = B256::with_last_byte(1);
+        let num_blocks = 50; // Enough to notice O(N²) vs O(N) difference
+
+        let mut ancestors: Vec<DeferredTrieData> = Vec::new();
+
+        let start = Instant::now();
+
+        for i in 0..num_blocks {
+            let key = B256::with_last_byte(i as u8);
+            let account = Account { nonce: i as u64, balance: U256::ZERO, bytecode_hash: None };
+            let hashed = HashedPostState::default().with_accounts([(key, Some(account))]);
+
+            let block = DeferredTrieData::pending(
+                Arc::new(hashed),
+                Arc::new(TrieUpdates::default()),
+                anchor,
+                ancestors.clone(),
+            );
+
+            // Compute and add to ancestors for next iteration
+            let computed = block.wait_cloned();
+            ancestors.push(DeferredTrieData::ready(computed));
+        }
+
+        let elapsed = start.elapsed();
+
+        // With O(N) fix, 50 blocks should complete quickly (< 1 second)
+        // With O(N²), this would take significantly longer
+        assert!(
+            elapsed < Duration::from_secs(2),
+            "Chain of {num_blocks} blocks took {:?}, possible O(N²) regression",
+            elapsed
+        );
+
+        // Verify final overlay has all accounts
+        let final_result = ancestors.last().unwrap().wait_cloned();
+        let overlay = final_result.anchored_trie_input.as_ref().unwrap();
+        assert_eq!(overlay.trie_input.state.accounts.len(), num_blocks);
+    }
+
+    /// Verifies that a multi-ancestor overlay is rebuilt when anchor changes.
+    /// This simulates the "persist prefix then keep building" scenario where:
+    /// 1. A chain of blocks is built with anchor A
+    /// 2. Some blocks are persisted, changing anchor to B
+    /// 3. New blocks must rebuild the overlay from the remaining ancestors
+    #[test]
+    fn multi_ancestor_overlay_rebuilt_after_anchor_change() {
+        let old_anchor = B256::with_last_byte(1);
+        let new_anchor = B256::with_last_byte(2);
+        let key1 = B256::with_last_byte(1);
+        let key2 = B256::with_last_byte(2);
+        let key3 = B256::with_last_byte(3);
+        let key4 = B256::with_last_byte(4);
+
+        // Build a chain of 3 blocks with old_anchor
+        let block1 = ready_block_with_state(
+            old_anchor,
+            vec![(key1, Some(Account { nonce: 1, balance: U256::ZERO, bytecode_hash: None }))],
+        );
+
+        let block2_hashed = HashedPostState::default().with_accounts([(
+            key2,
+            Some(Account { nonce: 2, balance: U256::ZERO, bytecode_hash: None }),
+        )]);
+        let block2 = DeferredTrieData::pending(
+            Arc::new(block2_hashed),
+            Arc::new(TrieUpdates::default()),
+            old_anchor,
+            vec![block1.clone()],
+        );
+        let block2_ready = DeferredTrieData::ready(block2.wait_cloned());
+
+        let block3_hashed = HashedPostState::default().with_accounts([(
+            key3,
+            Some(Account { nonce: 3, balance: U256::ZERO, bytecode_hash: None }),
+        )]);
+        let block3 = DeferredTrieData::pending(
+            Arc::new(block3_hashed),
+            Arc::new(TrieUpdates::default()),
+            old_anchor,
+            vec![block1.clone(), block2_ready.clone()],
+        );
+        let block3_ready = DeferredTrieData::ready(block3.wait_cloned());
+
+        // Verify block3's overlay has all 3 accounts with old_anchor
+        let block3_overlay = block3_ready.wait_cloned().anchored_trie_input.unwrap();
+        assert_eq!(block3_overlay.anchor_hash, old_anchor);
+        assert_eq!(block3_overlay.trie_input.state.accounts.len(), 3);
+
+        // Now simulate persist: create block4 with NEW anchor but same ancestors.
+        // To verify correct rebuilding, we must provide ALL unpersisted ancestors.
+        // If we only provided block3, the rebuild would only see block3's state.
+        // We pass block1, block2, block3 to simulate that they are all still in memory
+        // but the anchor check forces a rebuild (e.g. artificial anchor change).
+        let block4_hashed = HashedPostState::default().with_accounts([(
+            key4,
+            Some(Account { nonce: 4, balance: U256::ZERO, bytecode_hash: None }),
+        )]);
+        let block4 = DeferredTrieData::pending(
+            Arc::new(block4_hashed),
+            Arc::new(TrieUpdates::default()),
+            new_anchor, // Different anchor - simulates post-persist
+            vec![block1, block2_ready, block3_ready],
+        );
+
+        let result = block4.wait_cloned();
+
+        // Verify:
+        // 1. New anchor is used in result
+        assert_eq!(result.anchor_hash(), Some(new_anchor));
+
+        // 2. All 4 accounts are in the overlay (rebuilt from ancestors + extended)
+        let overlay = result.anchored_trie_input.as_ref().unwrap();
+        assert_eq!(overlay.trie_input.state.accounts.len(), 4);
+
+        // 3. All accounts have correct values
+        let accounts = &overlay.trie_input.state.accounts;
+        assert!(accounts.iter().any(|(k, a)| *k == key1 && a.unwrap().nonce == 1));
+        assert!(accounts.iter().any(|(k, a)| *k == key2 && a.unwrap().nonce == 2));
+        assert!(accounts.iter().any(|(k, a)| *k == key3 && a.unwrap().nonce == 3));
+        assert!(accounts.iter().any(|(k, a)| *k == key4 && a.unwrap().nonce == 4));
+    }
+}

crates/chain-state/src/in_memory.rs

@@ -2,7 +2,7 @@
 
 use crate::{
     CanonStateNotification, CanonStateNotificationSender, CanonStateNotifications,
-    ChainInfoTracker, MemoryOverlayStateProvider,
+    ChainInfoTracker, ComputedTrieData, DeferredTrieData, MemoryOverlayStateProvider,
 };
 use alloy_consensus::{transaction::TransactionMeta, BlockHeader};
 use alloy_eips::{BlockHashOrNumber, BlockNumHash};
@@ -10,14 +10,14 @@ use alloy_primitives::{map::HashMap, BlockNumber, TxHash, B256};
 use parking_lot::RwLock;
 use reth_chainspec::ChainInfo;
 use reth_ethereum_primitives::EthPrimitives;
-use reth_execution_types::{Chain, ExecutionOutcome};
+use reth_execution_types::{BlockExecutionOutput, BlockExecutionResult, Chain, ExecutionOutcome};
 use reth_metrics::{metrics::Gauge, Metrics};
 use reth_primitives_traits::{
     BlockBody as _, IndexedTx, NodePrimitives, RecoveredBlock, SealedBlock, SealedHeader,
     SignedTransaction,
 };
 use reth_storage_api::StateProviderBox;
-use reth_trie::{updates::TrieUpdates, HashedPostState};
+use reth_trie::{updates::TrieUpdatesSorted, HashedPostStateSorted, LazyTrieData, TrieInputSorted};
 use std::{collections::BTreeMap, sync::Arc, time::Instant};
 use tokio::sync::{broadcast, watch};
 
@@ -86,14 +86,20 @@ impl<N: NodePrimitives> InMemoryState<N> {
     ///
     /// This tries to acquire a read lock. Drop any write locks before calling this.
     pub(crate) fn update_metrics(&self) {
-        let numbers = self.numbers.read();
-        if let Some((earliest_block_number, _)) = numbers.first_key_value() {
-            self.metrics.earliest_block.set(*earliest_block_number as f64);
+        let (count, earliest, latest) = {
+            let numbers = self.numbers.read();
+            let count = numbers.len();
+            let earliest = numbers.first_key_value().map(|(number, _)| *number);
+            let latest = numbers.last_key_value().map(|(number, _)| *number);
+            (count, earliest, latest)
+        };
+        if let Some(earliest_block_number) = earliest {
+            self.metrics.earliest_block.set(earliest_block_number as f64);
         }
-        if let Some((latest_block_number, _)) = numbers.last_key_value() {
-            self.metrics.latest_block.set(*latest_block_number as f64);
+        if let Some(latest_block_number) = latest {
+            self.metrics.latest_block.set(latest_block_number as f64);
         }
-        self.metrics.num_blocks.set(numbers.len() as f64);
+        self.metrics.num_blocks.set(count as f64);
     }
 
     /// Returns the state for a given block hash.
@@ -311,6 +317,7 @@ impl<N: NodePrimitives> CanonicalInMemoryState<N> {
     /// This will update the links between blocks and remove all blocks that are [..
     /// `persisted_height`].
     pub fn remove_persisted_blocks(&self, persisted_num_hash: BlockNumHash) {
+        self.set_persisted(persisted_num_hash);
         // if the persisted hash is not in the canonical in memory state, do nothing, because it
         // means canonical blocks were not actually persisted.
         //
@@ -438,6 +445,11 @@ impl<N: NodePrimitives> CanonicalInMemoryState<N> {
         self.inner.chain_info_tracker.set_finalized(header);
     }
 
+    /// Persisted block setter.
+    pub fn set_persisted(&self, num_hash: BlockNumHash) {
+        self.inner.chain_info_tracker.set_persisted(num_hash);
+    }
+
     /// Canonical head getter.
     pub fn get_canonical_head(&self) -> SealedHeader<N::BlockHeader> {
         self.inner.chain_info_tracker.get_canonical_head()
@@ -453,6 +465,11 @@ impl<N: NodePrimitives> CanonicalInMemoryState<N> {
         self.inner.chain_info_tracker.get_safe_header()
     }
 
+    /// Persisted block `BlockNumHash` getter.
+    pub fn get_persisted_num_hash(&self) -> Option<BlockNumHash> {
+        self.inner.chain_info_tracker.get_persisted_num_hash()
+    }
+
     /// Returns the `SealedHeader` corresponding to the pending state.
     pub fn pending_sealed_header(&self) -> Option<SealedHeader<N::BlockHeader>> {
         self.pending_state().map(|h| h.block_ref().recovered_block().clone_sealed_header())
@@ -505,6 +522,11 @@ impl<N: NodePrimitives> CanonicalInMemoryState<N> {
         self.inner.chain_info_tracker.subscribe_finalized_block()
     }
 
+    /// Subscribe to new persisted block events.
+    pub fn subscribe_persisted_block(&self) -> watch::Receiver<Option<BlockNumHash>> {
+        self.inner.chain_info_tracker.subscribe_persisted_block()
+    }
+
     /// Attempts to send a new [`CanonStateNotification`] to all active Receiver handles.
     pub fn notify_canon_state(&self, event: CanonStateNotification<N>) {
         self.inner.canon_state_notification_sender.send(event).ok();
@@ -565,7 +587,7 @@ impl<N: NodePrimitives> CanonicalInMemoryState<N> {
 
 /// State after applying the given block, this block is part of the canonical chain that partially
 /// stored in memory and can be traced back to a canonical block on disk.
-#[derive(Debug, PartialEq, Eq, Clone)]
+#[derive(Debug, Clone)]
 pub struct BlockState<N: NodePrimitives = EthPrimitives> {
     /// The executed block that determines the state after this block has been executed.
     block: ExecutedBlock<N>,
@@ -573,6 +595,12 @@ pub struct BlockState<N: NodePrimitives = EthPrimitives> {
     parent: Option<Arc<Self>>,
 }
 
+impl<N: NodePrimitives> PartialEq for BlockState<N> {
+    fn eq(&self, other: &Self) -> bool {
+        self.block == other.block && self.parent == other.parent
+    }
+}
+
 impl<N: NodePrimitives> BlockState<N> {
     /// [`BlockState`] constructor.
     pub const fn new(block: ExecutedBlock<N>) -> Self {
@@ -620,7 +648,7 @@ impl<N: NodePrimitives> BlockState<N> {
     }
 
     /// Returns the `Receipts` of executed block that determines the state.
-    pub fn receipts(&self) -> &Vec<Vec<N::Receipt>> {
+    pub fn receipts(&self) -> &Vec<N::Receipt> {
         &self.block.execution_outcome().receipts
     }
 
@@ -628,34 +656,28 @@ impl<N: NodePrimitives> BlockState<N> {
     /// We assume that the `Receipts` in the executed block `ExecutionOutcome`
     /// has only one element corresponding to the executed block associated to
     /// the state.
+    ///
+    /// This clones the vector of receipts. To avoid it, use [`Self::executed_block_receipts_ref`].
     pub fn executed_block_receipts(&self) -> Vec<N::Receipt> {
-        let receipts = self.receipts();
-
-        debug_assert!(
-            receipts.len() <= 1,
-            "Expected at most one block's worth of receipts, found {}",
-            receipts.len()
-        );
-
-        receipts.first().cloned().unwrap_or_default()
+        self.receipts().clone()
     }
 
-    /// Returns a vector of __parent__ `BlockStates`.
+    /// Returns a slice of `Receipt` of executed block that determines the state.
+    /// We assume that the `Receipts` in the executed block `ExecutionOutcome`
+    /// has only one element corresponding to the executed block associated to
+    /// the state.
+    pub fn executed_block_receipts_ref(&self) -> &[N::Receipt] {
+        self.receipts()
+    }
+
+    /// Returns an iterator over __parent__ `BlockStates`.
     ///
-    /// The block state order in the output vector is newest to oldest (highest to lowest):
+    /// The block state order is newest to oldest (highest to lowest):
     /// `[5,4,3,2,1]`
     ///
     /// Note: This does not include self.
-    pub fn parent_state_chain(&self) -> Vec<&Self> {
-        let mut parents = Vec::new();
-        let mut current = self.parent.as_deref();
-
-        while let Some(parent) = current {
-            parents.push(parent);
-            current = parent.parent.as_deref();
-        }
-
-        parents
+    pub fn parent_state_chain(&self) -> impl Iterator<Item = &Self> + '_ {
+        std::iter::successors(self.parent.as_deref(), |state| state.parent.as_deref())
     }
 
     /// Returns a vector of `BlockStates` representing the entire in memory chain.
@@ -666,6 +688,11 @@ impl<N: NodePrimitives> BlockState<N> {
     }
 
     /// Appends the parent chain of this [`BlockState`] to the given vector.
+    ///
+    /// Parents are appended in order from newest to oldest (highest to lowest).
+    /// This does not include self, only the parent states.
+    ///
+    /// This is a convenience method equivalent to `chain.extend(self.parent_state_chain())`.
     pub fn append_parent_chain<'a>(&'a self, chain: &mut Vec<&'a Self>) {
         chain.extend(self.parent_state_chain());
     }
@@ -719,30 +746,80 @@ impl<N: NodePrimitives> BlockState<N> {
 }
 
 /// Represents an executed block stored in-memory.
-#[derive(Clone, Debug, PartialEq, Eq)]
+#[derive(Clone, Debug)]
 pub struct ExecutedBlock<N: NodePrimitives = EthPrimitives> {
     /// Recovered Block
     pub recovered_block: Arc<RecoveredBlock<N::Block>>,
     /// Block's execution outcome.
-    pub execution_output: Arc<ExecutionOutcome<N::Receipt>>,
-    /// Block's hashed state.
-    pub hashed_state: Arc<HashedPostState>,
-    /// Trie updates that result from calculating the state root for the block.
-    pub trie_updates: Arc<TrieUpdates>,
+    pub execution_output: Arc<BlockExecutionOutput<N::Receipt>>,
+    /// Deferred trie data produced by execution.
+    ///
+    /// This allows deferring the computation of the trie data which can be expensive.
+    /// The data can be populated asynchronously after the block was validated.
+    pub trie_data: DeferredTrieData,
 }
 
 impl<N: NodePrimitives> Default for ExecutedBlock<N> {
     fn default() -> Self {
         Self {
             recovered_block: Default::default(),
-            execution_output: Default::default(),
-            hashed_state: Default::default(),
-            trie_updates: Default::default(),
+            execution_output: Arc::new(BlockExecutionOutput {
+                result: BlockExecutionResult {
+                    receipts: Default::default(),
+                    requests: Default::default(),
+                    gas_used: 0,
+                    blob_gas_used: 0,
+                },
+                state: Default::default(),
+            }),
+            trie_data: DeferredTrieData::ready(ComputedTrieData::default()),
         }
     }
 }
 
+impl<N: NodePrimitives> PartialEq for ExecutedBlock<N> {
+    fn eq(&self, other: &Self) -> bool {
+        // Trie data is computed asynchronously and doesn't define block identity.
+        self.recovered_block == other.recovered_block &&
+            self.execution_output == other.execution_output
+    }
+}
+
 impl<N: NodePrimitives> ExecutedBlock<N> {
+    /// Create a new [`ExecutedBlock`] with already-computed trie data.
+    ///
+    /// Use this constructor when trie data is available immediately (e.g., sequencers,
+    /// payload builders). This is the safe default path.
+    pub fn new(
+        recovered_block: Arc<RecoveredBlock<N::Block>>,
+        execution_output: Arc<BlockExecutionOutput<N::Receipt>>,
+        trie_data: ComputedTrieData,
+    ) -> Self {
+        Self { recovered_block, execution_output, trie_data: DeferredTrieData::ready(trie_data) }
+    }
+
+    /// Create a new [`ExecutedBlock`] with deferred trie data.
+    ///
+    /// This is useful if the trie data is populated somewhere else, e.g. asynchronously
+    /// after the block was validated.
+    ///
+    /// The [`DeferredTrieData`] handle allows expensive trie operations (sorting hashed state,
+    /// sorting trie updates, and building the accumulated trie input overlay) to be performed
+    /// outside the critical validation path. This can improve latency for time-sensitive
+    /// operations like block validation.
+    ///
+    /// If the data hasn't been populated when [`Self::trie_data()`] is called, computation
+    /// occurs synchronously from stored inputs, so there is no blocking or deadlock risk.
+    ///
+    /// Use [`Self::new()`] instead when trie data is already computed and available immediately.
+    pub const fn with_deferred_trie_data(
+        recovered_block: Arc<RecoveredBlock<N::Block>>,
+        execution_output: Arc<BlockExecutionOutput<N::Receipt>>,
+        trie_data: DeferredTrieData,
+    ) -> Self {
+        Self { recovered_block, execution_output, trie_data }
+    }
+
     /// Returns a reference to an inner [`SealedBlock`]
     #[inline]
     pub fn sealed_block(&self) -> &SealedBlock<N::Block> {
@@ -757,20 +834,59 @@ impl<N: NodePrimitives> ExecutedBlock<N> {
 
     /// Returns a reference to the block's execution outcome
     #[inline]
-    pub fn execution_outcome(&self) -> &ExecutionOutcome<N::Receipt> {
+    pub fn execution_outcome(&self) -> &BlockExecutionOutput<N::Receipt> {
         &self.execution_output
     }
 
-    /// Returns a reference to the hashed state result of the execution outcome
+    /// Returns the trie data, computing it synchronously if not already cached.
+    ///
+    /// Uses `OnceLock::get_or_init` internally:
+    /// - If already computed: returns cached result immediately
+    /// - If not computed: first caller computes, others wait for that result
     #[inline]
-    pub fn hashed_state(&self) -> &HashedPostState {
-        &self.hashed_state
+    #[tracing::instrument(level = "debug", target = "engine::tree", name = "trie_data", skip_all)]
+    pub fn trie_data(&self) -> ComputedTrieData {
+        self.trie_data.wait_cloned()
     }
 
-    /// Returns a reference to the trie updates resulting from the execution outcome
+    /// Returns a clone of the deferred trie data handle.
+    ///
+    /// A handle is a lightweight reference that can be passed to descendants without
+    /// forcing trie data to be computed immediately. The actual work runs when
+    /// `wait_cloned()` is called by a consumer (e.g. when merging overlays).
     #[inline]
-    pub fn trie_updates(&self) -> &TrieUpdates {
-        &self.trie_updates
+    pub fn trie_data_handle(&self) -> DeferredTrieData {
+        self.trie_data.clone()
+    }
+
+    /// Returns the hashed state result of the execution outcome.
+    ///
+    /// May compute trie data synchronously if the deferred task hasn't completed.
+    #[inline]
+    pub fn hashed_state(&self) -> Arc<HashedPostStateSorted> {
+        self.trie_data().hashed_state
+    }
+
+    /// Returns the trie updates resulting from the execution outcome.
+    ///
+    /// May compute trie data synchronously if the deferred task hasn't completed.
+    #[inline]
+    pub fn trie_updates(&self) -> Arc<TrieUpdatesSorted> {
+        self.trie_data().trie_updates
+    }
+
+    /// Returns the trie input anchored to the persisted ancestor.
+    ///
+    /// May compute trie data synchronously if the deferred task hasn't completed.
+    #[inline]
+    pub fn trie_input(&self) -> Option<Arc<TrieInputSorted>> {
+        self.trie_data().trie_input().cloned()
+    }
+
+    /// Returns the anchor hash of the trie input, if present.
+    #[inline]
+    pub fn anchor_hash(&self) -> Option<B256> {
+        self.trie_data().anchor_hash()
     }
 
     /// Returns a [`BlockNumber`] of the block.
@@ -818,31 +934,39 @@ impl<N: NodePrimitives<SignedTx: SignedTransaction>> NewCanonicalChain<N> {
     pub fn to_chain_notification(&self) -> CanonStateNotification<N> {
         match self {
             Self::Commit { new } => {
-                let new = Arc::new(new.iter().fold(Chain::default(), |mut chain, exec| {
-                    chain.append_block(
-                        exec.recovered_block().clone(),
-                        exec.execution_outcome().clone(),
-                    );
-                    chain
-                }));
-                CanonStateNotification::Commit { new }
+                CanonStateNotification::Commit { new: Arc::new(Self::blocks_to_chain(new)) }
             }
-            Self::Reorg { new, old } => {
-                let new = Arc::new(new.iter().fold(Chain::default(), |mut chain, exec| {
+            Self::Reorg { new, old } => CanonStateNotification::Reorg {
+                new: Arc::new(Self::blocks_to_chain(new)),
+                old: Arc::new(Self::blocks_to_chain(old)),
+            },
+        }
+    }
+
+    /// Converts a slice of executed blocks into a [`Chain`].
+    fn blocks_to_chain(blocks: &[ExecutedBlock<N>]) -> Chain<N> {
+        match blocks {
+            [] => Chain::default(),
+            [first, rest @ ..] => {
+                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()),
+                );
+                for exec in rest {
                     chain.append_block(
                         exec.recovered_block().clone(),
-                        exec.execution_outcome().clone(),
+                        ExecutionOutcome::from((
+                            exec.execution_outcome().clone(),
+                            exec.block_number(),
+                        )),
+                        LazyTrieData::ready(exec.hashed_state(), exec.trie_updates()),
                     );
-                    chain
-                }));
-                let old = Arc::new(old.iter().fold(Chain::default(), |mut chain, exec| {
-                    chain.append_block(
-                        exec.recovered_block().clone(),
-                        exec.execution_outcome().clone(),
-                    );
-                    chain
-                }));
-                CanonStateNotification::Reorg { new, old }
+                }
+                chain
             }
         }
     }
@@ -875,8 +999,8 @@ mod tests {
         StateProofProvider, StateProvider, StateRootProvider, StorageRootProvider,
     };
     use reth_trie::{
-        AccountProof, HashedStorage, MultiProof, MultiProofTargets, StorageMultiProof,
-        StorageProof, TrieInput,
+        updates::TrieUpdates, AccountProof, HashedPostState, HashedStorage, MultiProof,
+        MultiProofTargets, StorageMultiProof, StorageProof, TrieInput,
     };
 
     fn create_mock_state(
@@ -1136,7 +1260,7 @@ mod tests {
 
         let state = BlockState::new(block);
 
-        assert_eq!(state.receipts(), &receipts);
+        assert_eq!(state.receipts(), receipts.first().unwrap());
     }
 
     #[test]
@@ -1348,19 +1472,18 @@ mod tests {
         let mut test_block_builder: TestBlockBuilder = TestBlockBuilder::default();
         let chain = create_mock_state_chain(&mut test_block_builder, 4);
 
-        let parents = chain[3].parent_state_chain();
+        let parents: Vec<_> = chain[3].parent_state_chain().collect();
         assert_eq!(parents.len(), 3);
         assert_eq!(parents[0].block().recovered_block().number, 3);
         assert_eq!(parents[1].block().recovered_block().number, 2);
         assert_eq!(parents[2].block().recovered_block().number, 1);
 
-        let parents = chain[2].parent_state_chain();
+        let parents: Vec<_> = chain[2].parent_state_chain().collect();
         assert_eq!(parents.len(), 2);
         assert_eq!(parents[0].block().recovered_block().number, 2);
         assert_eq!(parents[1].block().recovered_block().number, 1);
 
-        let parents = chain[0].parent_state_chain();
-        assert_eq!(parents.len(), 0);
+        assert_eq!(chain[0].parent_state_chain().count(), 0);
     }
 
     #[test]
@@ -1371,8 +1494,7 @@ mod tests {
             create_mock_state(&mut test_block_builder, single_block_number, B256::random());
         let single_block_hash = single_block.block().recovered_block().hash();
 
-        let parents = single_block.parent_state_chain();
-        assert_eq!(parents.len(), 0);
+        assert_eq!(single_block.parent_state_chain().count(), 0);
 
         let block_state_chain = single_block.chain().collect::<Vec<_>>();
         assert_eq!(block_state_chain.len(), 1);
@@ -1415,22 +1537,31 @@ mod tests {
         let block2a =
             test_block_builder.get_executed_block_with_number(2, block1.recovered_block.hash());
 
-        let sample_execution_outcome = ExecutionOutcome {
-            receipts: vec![vec![], vec![]],
-            requests: vec![Requests::default(), Requests::default()],
-            ..Default::default()
-        };
-
         // Test commit notification
         let chain_commit = NewCanonicalChain::Commit { new: vec![block0.clone(), block1.clone()] };
 
+        // Build expected trie data map
+        let mut expected_trie_data = BTreeMap::new();
+        expected_trie_data
+            .insert(0, LazyTrieData::ready(block0.hashed_state(), block0.trie_updates()));
+        expected_trie_data
+            .insert(1, LazyTrieData::ready(block1.hashed_state(), block1.trie_updates()));
+
+        // Build expected execution outcome (first_block matches first block number)
+        let commit_execution_outcome = ExecutionOutcome {
+            receipts: vec![vec![], vec![]],
+            requests: vec![Requests::default(), Requests::default()],
+            first_block: 0,
+            ..Default::default()
+        };
+
         assert_eq!(
             chain_commit.to_chain_notification(),
             CanonStateNotification::Commit {
                 new: Arc::new(Chain::new(
                     vec![block0.recovered_block().clone(), block1.recovered_block().clone()],
-                    sample_execution_outcome.clone(),
-                    None
+                    commit_execution_outcome,
+                    expected_trie_data,
                 ))
             }
         );
@@ -1441,18 +1572,39 @@ mod tests {
             old: vec![block1.clone(), block2.clone()],
         };
 
+        // Build expected trie data for old chain
+        let mut old_trie_data = BTreeMap::new();
+        old_trie_data.insert(1, LazyTrieData::ready(block1.hashed_state(), block1.trie_updates()));
+        old_trie_data.insert(2, LazyTrieData::ready(block2.hashed_state(), block2.trie_updates()));
+
+        // Build expected trie data for new chain
+        let mut new_trie_data = BTreeMap::new();
+        new_trie_data
+            .insert(1, LazyTrieData::ready(block1a.hashed_state(), block1a.trie_updates()));
+        new_trie_data
+            .insert(2, LazyTrieData::ready(block2a.hashed_state(), block2a.trie_updates()));
+
+        // Build expected execution outcome for reorg chains (first_block matches first block
+        // number)
+        let reorg_execution_outcome = ExecutionOutcome {
+            receipts: vec![vec![], vec![]],
+            requests: vec![Requests::default(), Requests::default()],
+            first_block: 1,
+            ..Default::default()
+        };
+
         assert_eq!(
             chain_reorg.to_chain_notification(),
             CanonStateNotification::Reorg {
                 old: Arc::new(Chain::new(
                     vec![block1.recovered_block().clone(), block2.recovered_block().clone()],
-                    sample_execution_outcome.clone(),
-                    None
+                    reorg_execution_outcome.clone(),
+                    old_trie_data,
                 )),
                 new: Arc::new(Chain::new(
                     vec![block1a.recovered_block().clone(), block2a.recovered_block().clone()],
-                    sample_execution_outcome,
-                    None
+                    reorg_execution_outcome,
+                    new_trie_data,
                 ))
             }
         );

crates/chain-state/src/lazy_overlay.rs

@@ -0,0 +1,186 @@
+//! Lazy overlay computation for trie input.
+//!
+//! This module provides [`LazyOverlay`], a type that computes the [`TrieInputSorted`]
+//! lazily on first access. This allows execution to start before the trie overlay
+//! is fully computed.
+
+use crate::DeferredTrieData;
+use alloy_primitives::B256;
+use reth_trie::{updates::TrieUpdatesSorted, HashedPostStateSorted, TrieInputSorted};
+use std::sync::{Arc, OnceLock};
+use tracing::{debug, trace};
+
+/// Inputs captured for lazy overlay computation.
+#[derive(Clone)]
+struct LazyOverlayInputs {
+    /// The persisted ancestor hash (anchor) this overlay should be built on.
+    anchor_hash: B256,
+    /// Deferred trie data handles for all in-memory blocks (newest to oldest).
+    blocks: Vec<DeferredTrieData>,
+}
+
+/// Lazily computed trie overlay.
+///
+/// Captures the inputs needed to compute a [`TrieInputSorted`] and defers the actual
+/// computation until first access. This is conceptually similar to [`DeferredTrieData`]
+/// but for overlay computation.
+///
+/// # Fast Path vs Slow Path
+///
+/// - **Fast path**: If the tip block's cached `anchored_trie_input` is ready and its `anchor_hash`
+///   matches our expected anchor, we can reuse it directly (O(1)).
+/// - **Slow path**: Otherwise, we merge all ancestor blocks' trie data into a new overlay.
+#[derive(Clone)]
+pub struct LazyOverlay {
+    /// Computed result, cached after first access.
+    inner: Arc<OnceLock<TrieInputSorted>>,
+    /// Inputs for lazy computation.
+    inputs: LazyOverlayInputs,
+}
+
+impl std::fmt::Debug for LazyOverlay {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("LazyOverlay")
+            .field("anchor_hash", &self.inputs.anchor_hash)
+            .field("num_blocks", &self.inputs.blocks.len())
+            .field("computed", &self.inner.get().is_some())
+            .finish()
+    }
+}
+
+impl LazyOverlay {
+    /// Create a new lazy overlay with the given anchor hash and block handles.
+    ///
+    /// # Arguments
+    ///
+    /// * `anchor_hash` - The persisted ancestor hash this overlay is built on top of
+    /// * `blocks` - Deferred trie data handles for in-memory blocks (newest to oldest)
+    pub fn new(anchor_hash: B256, blocks: Vec<DeferredTrieData>) -> Self {
+        Self { inner: Arc::new(OnceLock::new()), inputs: LazyOverlayInputs { anchor_hash, blocks } }
+    }
+
+    /// Returns the anchor hash this overlay is built on.
+    pub const fn anchor_hash(&self) -> B256 {
+        self.inputs.anchor_hash
+    }
+
+    /// Returns the number of in-memory blocks this overlay covers.
+    pub const fn num_blocks(&self) -> usize {
+        self.inputs.blocks.len()
+    }
+
+    /// Returns true if the overlay has already been computed.
+    pub fn is_computed(&self) -> bool {
+        self.inner.get().is_some()
+    }
+
+    /// Returns the computed trie input, computing it if necessary.
+    ///
+    /// The first call triggers computation (which may block waiting for deferred data).
+    /// Subsequent calls return the cached result immediately.
+    pub fn get(&self) -> &TrieInputSorted {
+        self.inner.get_or_init(|| self.compute())
+    }
+
+    /// Returns the overlay as (nodes, state) tuple for use with `OverlayStateProviderFactory`.
+    pub fn as_overlay(&self) -> (Arc<TrieUpdatesSorted>, Arc<HashedPostStateSorted>) {
+        let input = self.get();
+        (Arc::clone(&input.nodes), Arc::clone(&input.state))
+    }
+
+    /// Compute the trie input overlay.
+    fn compute(&self) -> TrieInputSorted {
+        let anchor_hash = self.inputs.anchor_hash;
+        let blocks = &self.inputs.blocks;
+
+        if blocks.is_empty() {
+            debug!(target: "chain_state::lazy_overlay", "No in-memory blocks, returning empty overlay");
+            return TrieInputSorted::default();
+        }
+
+        // Fast path: Check if tip block's overlay is ready and anchor matches.
+        // The tip block (first in list) has the cumulative overlay from all ancestors.
+        if let Some(tip) = blocks.first() {
+            let data = tip.wait_cloned();
+            if let Some(anchored) = &data.anchored_trie_input {
+                if anchored.anchor_hash == anchor_hash {
+                    trace!(target: "chain_state::lazy_overlay", %anchor_hash, "Reusing tip block's cached overlay (fast path)");
+                    return (*anchored.trie_input).clone();
+                }
+                debug!(
+                    target: "chain_state::lazy_overlay",
+                    computed_anchor = %anchored.anchor_hash,
+                    %anchor_hash,
+                    "Anchor mismatch, falling back to merge"
+                );
+            }
+        }
+
+        // Slow path: Merge all blocks' trie data into a new overlay.
+        debug!(target: "chain_state::lazy_overlay", num_blocks = blocks.len(), "Merging blocks (slow path)");
+        Self::merge_blocks(blocks)
+    }
+
+    /// Merge all blocks' trie data into a single [`TrieInputSorted`].
+    ///
+    /// Blocks are ordered newest to oldest.
+    fn merge_blocks(blocks: &[DeferredTrieData]) -> TrieInputSorted {
+        if blocks.is_empty() {
+            return TrieInputSorted::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));
+
+        TrieInputSorted { state, nodes, prefix_sets: Default::default() }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use reth_trie::{updates::TrieUpdates, HashedPostState};
+
+    fn empty_deferred(anchor: B256) -> DeferredTrieData {
+        DeferredTrieData::pending(
+            Arc::new(HashedPostState::default()),
+            Arc::new(TrieUpdates::default()),
+            anchor,
+            Vec::new(),
+        )
+    }
+
+    #[test]
+    fn empty_blocks_returns_default() {
+        let overlay = LazyOverlay::new(B256::ZERO, vec![]);
+        let result = overlay.get();
+        assert!(result.state.is_empty());
+        assert!(result.nodes.is_empty());
+    }
+
+    #[test]
+    fn single_block_uses_data_directly() {
+        let anchor = B256::random();
+        let deferred = empty_deferred(anchor);
+        let overlay = LazyOverlay::new(anchor, vec![deferred]);
+
+        assert!(!overlay.is_computed());
+        let _ = overlay.get();
+        assert!(overlay.is_computed());
+    }
+
+    #[test]
+    fn cached_after_first_access() {
+        let overlay = LazyOverlay::new(B256::ZERO, vec![]);
+
+        // First access computes
+        let _ = overlay.get();
+        assert!(overlay.is_computed());
+
+        // Second access uses cache
+        let _ = overlay.get();
+        assert!(overlay.is_computed());
+    }
+}

crates/chain-state/src/lib.rs

@@ -11,6 +11,12 @@
 mod in_memory;
 pub use in_memory::*;
 
+mod deferred_trie;
+pub use deferred_trie::*;
+
+mod lazy_overlay;
+pub use lazy_overlay::*;
+
 mod noop;
 
 mod chain_info;
@@ -20,7 +26,8 @@ mod notifications;
 pub use notifications::{
     CanonStateNotification, CanonStateNotificationSender, CanonStateNotificationStream,
     CanonStateNotifications, CanonStateSubscriptions, ForkChoiceNotifications, ForkChoiceStream,
-    ForkChoiceSubscriptions,
+    ForkChoiceSubscriptions, PersistedBlockNotifications, PersistedBlockSubscriptions,
+    WatchValueStream,
 };
 
 mod memory_overlay;

crates/chain-state/src/memory_overlay.rs

@@ -5,14 +5,14 @@ use reth_errors::ProviderResult;
 use reth_primitives_traits::{Account, Bytecode, NodePrimitives};
 use reth_storage_api::{
     AccountReader, BlockHashReader, BytecodeReader, HashedPostStateProvider, StateProofProvider,
-    StateProvider, StateRootProvider, StorageRootProvider,
+    StateProvider, StateProviderBox, StateRootProvider, StorageRootProvider,
 };
 use reth_trie::{
     updates::TrieUpdates, AccountProof, HashedPostState, HashedStorage, MultiProof,
     MultiProofTargets, StorageMultiProof, TrieInput,
 };
 use revm_database::BundleState;
-use std::sync::OnceLock;
+use std::{borrow::Cow, sync::OnceLock};
 
 /// A state provider that stores references to in-memory blocks along with their state as well as a
 /// reference of the historical state provider for fallback lookups.
@@ -24,15 +24,11 @@ pub struct MemoryOverlayStateProviderRef<
     /// Historical state provider for state lookups that are not found in memory blocks.
     pub(crate) historical: Box<dyn StateProvider + 'a>,
     /// The collection of executed parent blocks. Expected order is newest to oldest.
-    pub(crate) in_memory: Vec<ExecutedBlock<N>>,
+    pub(crate) in_memory: Cow<'a, [ExecutedBlock<N>]>,
     /// Lazy-loaded in-memory trie data.
     pub(crate) trie_input: OnceLock<TrieInput>,
 }
 
-/// A state provider that stores references to in-memory blocks along with their state as well as
-/// the historical state provider for fallback lookups.
-pub type MemoryOverlayStateProvider<N> = MemoryOverlayStateProviderRef<'static, N>;
-
 impl<'a, N: NodePrimitives> MemoryOverlayStateProviderRef<'a, N> {
     /// Create new memory overlay state provider.
     ///
@@ -42,7 +38,7 @@ impl<'a, N: NodePrimitives> MemoryOverlayStateProviderRef<'a, N> {
     /// - `historical` - a historical state provider for the latest ancestor block stored in the
     ///   database.
     pub fn new(historical: Box<dyn StateProvider + 'a>, in_memory: Vec<ExecutedBlock<N>>) -> Self {
-        Self { historical, in_memory, trie_input: OnceLock::new() }
+        Self { historical, in_memory: Cow::Owned(in_memory), trie_input: OnceLock::new() }
     }
 
     /// Turn this state provider into a state provider
@@ -53,12 +49,14 @@ impl<'a, N: NodePrimitives> MemoryOverlayStateProviderRef<'a, N> {
     /// Return lazy-loaded trie state aggregated from in-memory blocks.
     fn trie_input(&self) -> &TrieInput {
         self.trie_input.get_or_init(|| {
-            TrieInput::from_blocks(
-                self.in_memory
-                    .iter()
-                    .rev()
-                    .map(|block| (block.hashed_state.as_ref(), block.trie_updates.as_ref())),
-            )
+            let mut input = TrieInput::default();
+            // Iterate from oldest to newest
+            for block in self.in_memory.iter().rev() {
+                let data = block.trie_data();
+                input.nodes.extend_from_sorted(&data.trie_updates);
+                input.state.extend_from_sorted(&data.hashed_state);
+            }
+            input
         })
     }
 
@@ -72,7 +70,7 @@ impl<'a, N: NodePrimitives> MemoryOverlayStateProviderRef<'a, N> {
 
 impl<N: NodePrimitives> BlockHashReader for MemoryOverlayStateProviderRef<'_, N> {
     fn block_hash(&self, number: BlockNumber) -> ProviderResult<Option<B256>> {
-        for block in &self.in_memory {
+        for block in self.in_memory.iter() {
             if block.recovered_block().number() == number {
                 return Ok(Some(block.recovered_block().hash()));
             }
@@ -91,7 +89,7 @@ impl<N: NodePrimitives> BlockHashReader for MemoryOverlayStateProviderRef<'_, N>
         let mut in_memory_hashes = Vec::with_capacity(range.size_hint().0);
 
         // iterate in ascending order (oldest to newest = low to high)
-        for block in &self.in_memory {
+        for block in self.in_memory.iter() {
             let block_num = block.recovered_block().number();
             if range.contains(&block_num) {
                 in_memory_hashes.push(block.recovered_block().hash());
@@ -113,7 +111,7 @@ impl<N: NodePrimitives> BlockHashReader for MemoryOverlayStateProviderRef<'_, N>
 
 impl<N: NodePrimitives> AccountReader for MemoryOverlayStateProviderRef<'_, N> {
     fn basic_account(&self, address: &Address) -> ProviderResult<Option<Account>> {
-        for block in &self.in_memory {
+        for block in self.in_memory.iter() {
             if let Some(account) = block.execution_output.account(address) {
                 return Ok(account);
             }
@@ -217,7 +215,7 @@ impl<N: NodePrimitives> StateProvider for MemoryOverlayStateProviderRef<'_, N> {
         address: Address,
         storage_key: StorageKey,
     ) -> ProviderResult<Option<StorageValue>> {
-        for block in &self.in_memory {
+        for block in self.in_memory.iter() {
             if let Some(value) = block.execution_output.storage(&address, storage_key.into()) {
                 return Ok(Some(value));
             }
@@ -229,7 +227,7 @@ impl<N: NodePrimitives> StateProvider for MemoryOverlayStateProviderRef<'_, N> {
 
 impl<N: NodePrimitives> BytecodeReader for MemoryOverlayStateProviderRef<'_, N> {
     fn bytecode_by_hash(&self, code_hash: &B256) -> ProviderResult<Option<Bytecode>> {
-        for block in &self.in_memory {
+        for block in self.in_memory.iter() {
             if let Some(contract) = block.execution_output.bytecode(code_hash) {
                 return Ok(Some(contract));
             }
@@ -238,3 +236,46 @@ impl<N: NodePrimitives> BytecodeReader for MemoryOverlayStateProviderRef<'_, N>
         self.historical.bytecode_by_hash(code_hash)
     }
 }
+
+/// An owned state provider that stores references to in-memory blocks along with their state as
+/// well as a reference of the historical state provider for fallback lookups.
+#[expect(missing_debug_implementations)]
+pub struct MemoryOverlayStateProvider<N: NodePrimitives = reth_ethereum_primitives::EthPrimitives> {
+    /// Historical state provider for state lookups that are not found in memory blocks.
+    pub(crate) historical: StateProviderBox,
+    /// The collection of executed parent blocks. Expected order is newest to oldest.
+    pub(crate) in_memory: Vec<ExecutedBlock<N>>,
+    /// Lazy-loaded in-memory trie data.
+    pub(crate) trie_input: OnceLock<TrieInput>,
+}
+
+impl<N: NodePrimitives> MemoryOverlayStateProvider<N> {
+    /// Create new memory overlay state provider.
+    ///
+    /// ## Arguments
+    ///
+    /// - `in_memory` - the collection of executed ancestor blocks in reverse.
+    /// - `historical` - a historical state provider for the latest ancestor block stored in the
+    ///   database.
+    pub fn new(historical: StateProviderBox, in_memory: Vec<ExecutedBlock<N>>) -> Self {
+        Self { historical, in_memory, trie_input: OnceLock::new() }
+    }
+
+    /// Returns a new provider that takes the `TX` as reference
+    #[inline(always)]
+    fn as_ref(&self) -> MemoryOverlayStateProviderRef<'_, N> {
+        MemoryOverlayStateProviderRef {
+            historical: Box::new(self.historical.as_ref()),
+            in_memory: Cow::Borrowed(&self.in_memory),
+            trie_input: self.trie_input.clone(),
+        }
+    }
+
+    /// Wraps the [`Self`] in a `Box`.
+    pub fn boxed(self) -> StateProviderBox {
+        Box::new(self)
+    }
+}
+
+// Delegates all provider impls to [`MemoryOverlayStateProviderRef`]
+reth_storage_api::macros::delegate_provider_impls!(MemoryOverlayStateProvider<N> where [N: NodePrimitives]);

crates/chain-state/src/noop.rs

@@ -2,7 +2,7 @@
 
 use crate::{
     CanonStateNotifications, CanonStateSubscriptions, ForkChoiceNotifications,
-    ForkChoiceSubscriptions,
+    ForkChoiceSubscriptions, PersistedBlockNotifications, PersistedBlockSubscriptions,
 };
 use reth_primitives_traits::NodePrimitives;
 use reth_storage_api::noop::NoopProvider;
@@ -27,3 +27,10 @@ impl<C: Send + Sync, N: NodePrimitives> ForkChoiceSubscriptions for NoopProvider
         ForkChoiceNotifications(rx)
     }
 }
+
+impl<C: Send + Sync, N: NodePrimitives> PersistedBlockSubscriptions for NoopProvider<C, N> {
+    fn subscribe_persisted_block(&self) -> PersistedBlockNotifications {
+        let (_, rx) = watch::channel(None);
+        PersistedBlockNotifications(rx)
+    }
+}

crates/chain-state/src/notifications.rs

@@ -1,6 +1,6 @@
 //! Canonical chain state notification trait and types.
 
-use alloy_eips::eip2718::Encodable2718;
+use alloy_eips::{eip2718::Encodable2718, BlockNumHash};
 use derive_more::{Deref, DerefMut};
 use reth_execution_types::{BlockReceipts, Chain};
 use reth_primitives_traits::{NodePrimitives, RecoveredBlock, SealedHeader};
@@ -205,22 +205,22 @@ pub trait ForkChoiceSubscriptions: Send + Sync {
     }
 }
 
-/// A stream for fork choice watch channels (pending, safe or finalized watchers)
+/// A stream that yields values from a `watch::Receiver<Option<T>>`, filtering out `None` values.
 #[derive(Debug)]
 #[pin_project::pin_project]
-pub struct ForkChoiceStream<T> {
+pub struct WatchValueStream<T> {
     #[pin]
     st: WatchStream<Option<T>>,
 }
 
-impl<T: Clone + Sync + Send + 'static> ForkChoiceStream<T> {
-    /// Creates a new `ForkChoiceStream`
+impl<T: Clone + Sync + Send + 'static> WatchValueStream<T> {
+    /// Creates a new [`WatchValueStream`]
     pub fn new(rx: watch::Receiver<Option<T>>) -> Self {
         Self { st: WatchStream::from_changes(rx) }
     }
 }
 
-impl<T: Clone + Sync + Send + 'static> Stream for ForkChoiceStream<T> {
+impl<T: Clone + Sync + Send + 'static> Stream for WatchValueStream<T> {
     type Item = T;
 
     fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
@@ -234,6 +234,24 @@ impl<T: Clone + Sync + Send + 'static> Stream for ForkChoiceStream<T> {
     }
 }
 
+/// Alias for [`WatchValueStream`] for fork choice watch channels.
+pub type ForkChoiceStream<T> = WatchValueStream<T>;
+
+/// Wrapper around a watch receiver that receives persisted block notifications.
+#[derive(Debug, Deref, DerefMut)]
+pub struct PersistedBlockNotifications(pub watch::Receiver<Option<BlockNumHash>>);
+
+/// A trait that allows subscribing to persisted block events.
+pub trait PersistedBlockSubscriptions: Send + Sync {
+    /// Get notified when a new block is persisted to disk.
+    fn subscribe_persisted_block(&self) -> PersistedBlockNotifications;
+
+    /// Convenience method to get a stream of the persisted blocks.
+    fn persisted_block_stream(&self) -> WatchValueStream<BlockNumHash> {
+        WatchValueStream::new(self.subscribe_persisted_block().0)
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -242,6 +260,7 @@ mod tests {
     use reth_ethereum_primitives::{Receipt, TransactionSigned, TxType};
     use reth_execution_types::ExecutionOutcome;
     use reth_primitives_traits::SealedBlock;
+    use std::collections::BTreeMap;
 
     #[test]
     fn test_commit_notification() {
@@ -260,7 +279,7 @@ mod tests {
         let chain: Arc<Chain> = Arc::new(Chain::new(
             vec![block1.clone(), block2.clone()],
             ExecutionOutcome::default(),
-            None,
+            BTreeMap::new(),
         ));
 
         // Create a commit notification
@@ -295,12 +314,15 @@ mod tests {
         block3.set_block_number(3);
         block3.set_hash(block3_hash);
 
-        let old_chain: Arc<Chain> =
-            Arc::new(Chain::new(vec![block1.clone()], ExecutionOutcome::default(), None));
+        let old_chain: Arc<Chain> = Arc::new(Chain::new(
+            vec![block1.clone()],
+            ExecutionOutcome::default(),
+            BTreeMap::new(),
+        ));
         let new_chain = Arc::new(Chain::new(
             vec![block2.clone(), block3.clone()],
             ExecutionOutcome::default(),
-            None,
+            BTreeMap::new(),
         ));
 
         // Create a reorg notification
@@ -362,8 +384,11 @@ mod tests {
         let execution_outcome = ExecutionOutcome { receipts, ..Default::default() };
 
         // Create a new chain segment with `block1` and `block2` and the execution outcome.
-        let new_chain: Arc<Chain> =
-            Arc::new(Chain::new(vec![block1.clone(), block2.clone()], execution_outcome, None));
+        let new_chain: Arc<Chain> = Arc::new(Chain::new(
+            vec![block1.clone(), block2.clone()],
+            execution_outcome,
+            BTreeMap::new(),
+        ));
 
         // Create a commit notification containing the new chain segment.
         let notification = CanonStateNotification::Commit { new: new_chain };
@@ -421,7 +446,7 @@ mod tests {
 
         // Create an old chain segment to be reverted, containing `old_block1`.
         let old_chain: Arc<Chain> =
-            Arc::new(Chain::new(vec![old_block1.clone()], old_execution_outcome, None));
+            Arc::new(Chain::new(vec![old_block1.clone()], old_execution_outcome, BTreeMap::new()));
 
         // Define block2 for the new chain segment, which will be committed.
         let mut body = BlockBody::<TransactionSigned>::default();
@@ -449,7 +474,8 @@ mod tests {
             ExecutionOutcome { receipts: new_receipts, ..Default::default() };
 
         // Create a new chain segment to be committed, containing `new_block1`.
-        let new_chain = Arc::new(Chain::new(vec![new_block1.clone()], new_execution_outcome, None));
+        let new_chain =
+            Arc::new(Chain::new(vec![new_block1.clone()], new_execution_outcome, BTreeMap::new()));
 
         // Create a reorg notification with both reverted (old) and committed (new) chain segments.
         let notification = CanonStateNotification::Reorg { old: old_chain, new: new_chain };

crates/chain-state/src/test_utils.rs

@@ -1,12 +1,9 @@
 use crate::{
     in_memory::ExecutedBlock, CanonStateNotification, CanonStateNotifications,
-    CanonStateSubscriptions,
+    CanonStateSubscriptions, ComputedTrieData,
 };
 use alloy_consensus::{Header, SignableTransaction, TxEip1559, TxReceipt, EMPTY_ROOT_HASH};
-use alloy_eips::{
-    eip1559::{ETHEREUM_BLOCK_GAS_LIMIT_30M, INITIAL_BASE_FEE},
-    eip7685::Requests,
-};
+use alloy_eips::eip1559::{ETHEREUM_BLOCK_GAS_LIMIT_30M, INITIAL_BASE_FEE};
 use alloy_primitives::{Address, BlockNumber, B256, U256};
 use alloy_signer::SignerSync;
 use alloy_signer_local::PrivateKeySigner;
@@ -16,14 +13,14 @@ use reth_chainspec::{ChainSpec, EthereumHardfork, MIN_TRANSACTION_GAS};
 use reth_ethereum_primitives::{
     Block, BlockBody, EthPrimitives, Receipt, Transaction, TransactionSigned,
 };
-use reth_execution_types::{Chain, ExecutionOutcome};
+use reth_execution_types::{BlockExecutionOutput, BlockExecutionResult, Chain, ExecutionOutcome};
 use reth_primitives_traits::{
     proofs::{calculate_receipt_root, calculate_transaction_root, calculate_withdrawals_root},
     Account, NodePrimitives, Recovered, RecoveredBlock, SealedBlock, SealedHeader,
     SignedTransaction,
 };
 use reth_storage_api::NodePrimitivesProvider;
-use reth_trie::{root::state_root_unhashed, updates::TrieUpdates, HashedPostState};
+use reth_trie::root::state_root_unhashed;
 use revm_database::BundleState;
 use revm_state::AccountInfo;
 use std::{
@@ -92,7 +89,7 @@ impl<N: NodePrimitives> TestBlockBuilder<N> {
         &mut self,
         number: BlockNumber,
         parent_hash: B256,
-    ) -> RecoveredBlock<reth_ethereum_primitives::Block> {
+    ) -> SealedBlock<reth_ethereum_primitives::Block> {
         let mut rng = rand::rng();
 
         let mock_tx = |nonce: u64| -> Recovered<_> {
@@ -117,7 +114,7 @@ impl<N: NodePrimitives> TestBlockBuilder<N> {
             .map(|_| {
                 let tx = mock_tx(self.signer_build_account_info.nonce);
                 self.signer_build_account_info.nonce += 1;
-                self.signer_build_account_info.balance -= signer_balance_decrease;
+                self.signer_build_account_info.balance -= Self::single_tx_cost();
                 tx
             })
             .collect();
@@ -167,17 +164,14 @@ impl<N: NodePrimitives> TestBlockBuilder<N> {
             ..Default::default()
         };
 
-        let block = SealedBlock::from_sealed_parts(
+        SealedBlock::from_sealed_parts(
             SealedHeader::seal_slow(header),
             BlockBody {
                 transactions: transactions.into_iter().map(|tx| tx.into_inner()).collect(),
                 ommers: Vec::new(),
                 withdrawals: Some(vec![].into()),
             },
-        );
-
-        RecoveredBlock::try_recover_sealed_with_senders(block, vec![self.signer; num_txs as usize])
-            .unwrap()
+        )
     }
 
     /// Creates a fork chain with the given base block.
@@ -191,7 +185,9 @@ impl<N: NodePrimitives> TestBlockBuilder<N> {
 
         for _ in 0..length {
             let block = self.generate_random_block(parent.number + 1, parent.hash());
-            parent = block.clone_sealed_block();
+            parent = block.clone();
+            let senders = vec![self.signer; block.body().transactions.len()];
+            let block = block.with_senders(senders);
             fork.push(block);
         }
 
@@ -202,23 +198,25 @@ impl<N: NodePrimitives> TestBlockBuilder<N> {
     fn get_executed_block(
         &mut self,
         block_number: BlockNumber,
-        receipts: Vec<Vec<Receipt>>,
+        mut receipts: Vec<Vec<Receipt>>,
         parent_hash: B256,
     ) -> ExecutedBlock {
-        let block_with_senders = self.generate_random_block(block_number, parent_hash);
-
-        let (block, senders) = block_with_senders.split_sealed();
-        ExecutedBlock {
-            recovered_block: Arc::new(RecoveredBlock::new_sealed(block, senders)),
-            execution_output: Arc::new(ExecutionOutcome::new(
-                BundleState::default(),
-                receipts,
-                block_number,
-                vec![Requests::default()],
-            )),
-            hashed_state: Arc::new(HashedPostState::default()),
-            trie_updates: Arc::new(TrieUpdates::default()),
-        }
+        let block = self.generate_random_block(block_number, parent_hash);
+        let senders = vec![self.signer; block.body().transactions.len()];
+        let trie_data = ComputedTrieData::default();
+        ExecutedBlock::new(
+            Arc::new(RecoveredBlock::new_sealed(block, senders)),
+            Arc::new(BlockExecutionOutput {
+                result: BlockExecutionResult {
+                    receipts: receipts.pop().unwrap_or_default(),
+                    requests: Default::default(),
+                    gas_used: 0,
+                    blob_gas_used: 0,
+                },
+                state: BundleState::default(),
+            }),
+            trie_data,
+        )
     }
 
     /// Generates an [`ExecutedBlock`] that includes the given receipts.

crates/chainspec/src/lib.rs

@@ -30,8 +30,9 @@ pub use info::ChainInfo;
 #[cfg(any(test, feature = "test-utils"))]
 pub use spec::test_fork_ids;
 pub use spec::{
-    make_genesis_header, BaseFeeParams, BaseFeeParamsKind, ChainSpec, ChainSpecBuilder,
-    ChainSpecProvider, DepositContract, ForkBaseFeeParams, DEV, HOLESKY, HOODI, MAINNET, SEPOLIA,
+    blob_params_to_schedule, create_chain_config, mainnet_chain_config, make_genesis_header,
+    BaseFeeParams, BaseFeeParamsKind, ChainSpec, ChainSpecBuilder, ChainSpecProvider,
+    DepositContract, ForkBaseFeeParams, DEV, HOLESKY, HOODI, MAINNET, SEPOLIA,
 };
 
 use reth_primitives_traits::sync::OnceLock;

crates/chainspec/src/spec.rs

@@ -10,7 +10,14 @@ use crate::{
     sepolia::SEPOLIA_PARIS_BLOCK,
     EthChainSpec,
 };
-use alloc::{boxed::Box, format, sync::Arc, vec::Vec};
+use alloc::{
+    boxed::Box,
+    collections::BTreeMap,
+    format,
+    string::{String, ToString},
+    sync::Arc,
+    vec::Vec,
+};
 use alloy_chains::{Chain, NamedChain};
 use alloy_consensus::{
     constants::{
@@ -23,7 +30,7 @@ use alloy_eips::{
     eip1559::INITIAL_BASE_FEE, eip7685::EMPTY_REQUESTS_HASH, eip7840::BlobParams,
     eip7892::BlobScheduleBlobParams,
 };
-use alloy_genesis::Genesis;
+use alloy_genesis::{ChainConfig, Genesis};
 use alloy_primitives::{address, b256, Address, BlockNumber, B256, U256};
 use alloy_trie::root::state_root_ref_unhashed;
 use core::fmt::Debug;
@@ -73,6 +80,8 @@ pub fn make_genesis_header(genesis: &Genesis, hardforks: &ChainHardforks) -> Hea
         .then_some(EMPTY_REQUESTS_HASH);
 
     Header {
+        number: genesis.number.unwrap_or_default(),
+        parent_hash: genesis.parent_hash.unwrap_or_default(),
         gas_limit: genesis.gas_limit,
         difficulty: genesis.difficulty,
         nonce: genesis.nonce.into(),
@@ -240,6 +249,113 @@ pub static DEV: LazyLock<Arc<ChainSpec>> = LazyLock::new(|| {
     .into()
 });
 
+/// Creates a [`ChainConfig`] from the given chain, hardforks, deposit contract address, and blob
+/// schedule.
+pub fn create_chain_config(
+    chain: Option<Chain>,
+    hardforks: &ChainHardforks,
+    deposit_contract_address: Option<Address>,
+    blob_schedule: BTreeMap<String, BlobParams>,
+) -> ChainConfig {
+    // Helper to extract block number from a hardfork condition
+    let block_num = |fork: EthereumHardfork| hardforks.fork(fork).block_number();
+
+    // Helper to extract timestamp from a hardfork condition
+    let timestamp = |fork: EthereumHardfork| -> Option<u64> {
+        match hardforks.fork(fork) {
+            ForkCondition::Timestamp(t) => Some(t),
+            _ => None,
+        }
+    };
+
+    // Extract TTD from Paris fork
+    let (terminal_total_difficulty, terminal_total_difficulty_passed) =
+        match hardforks.fork(EthereumHardfork::Paris) {
+            ForkCondition::TTD { total_difficulty, .. } => (Some(total_difficulty), true),
+            _ => (None, false),
+        };
+
+    // 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),
+        dao_fork_block: block_num(EthereumHardfork::Dao),
+        dao_fork_support,
+        eip150_block: block_num(EthereumHardfork::Tangerine),
+        eip155_block: block_num(EthereumHardfork::SpuriousDragon),
+        eip158_block: block_num(EthereumHardfork::SpuriousDragon),
+        byzantium_block: block_num(EthereumHardfork::Byzantium),
+        constantinople_block: block_num(EthereumHardfork::Constantinople),
+        petersburg_block: block_num(EthereumHardfork::Petersburg),
+        istanbul_block: block_num(EthereumHardfork::Istanbul),
+        muir_glacier_block: block_num(EthereumHardfork::MuirGlacier),
+        berlin_block: block_num(EthereumHardfork::Berlin),
+        london_block: block_num(EthereumHardfork::London),
+        arrow_glacier_block: block_num(EthereumHardfork::ArrowGlacier),
+        gray_glacier_block: block_num(EthereumHardfork::GrayGlacier),
+        merge_netsplit_block: None,
+        shanghai_time: timestamp(EthereumHardfork::Shanghai),
+        cancun_time: timestamp(EthereumHardfork::Cancun),
+        prague_time: timestamp(EthereumHardfork::Prague),
+        osaka_time: timestamp(EthereumHardfork::Osaka),
+        bpo1_time: timestamp(EthereumHardfork::Bpo1),
+        bpo2_time: timestamp(EthereumHardfork::Bpo2),
+        bpo3_time: timestamp(EthereumHardfork::Bpo3),
+        bpo4_time: timestamp(EthereumHardfork::Bpo4),
+        bpo5_time: timestamp(EthereumHardfork::Bpo5),
+        terminal_total_difficulty,
+        terminal_total_difficulty_passed,
+        ethash: None,
+        clique: None,
+        parlia: None,
+        extra_fields: Default::default(),
+        deposit_contract_address,
+        blob_schedule,
+        ..Default::default()
+    }
+}
+
+/// Returns a [`ChainConfig`] for the current Ethereum mainnet chain.
+pub fn mainnet_chain_config() -> ChainConfig {
+    let hardforks: ChainHardforks = EthereumHardfork::mainnet().into();
+    let blob_schedule = blob_params_to_schedule(&MAINNET.blob_params, &hardforks);
+    create_chain_config(
+        Some(Chain::mainnet()),
+        &hardforks,
+        Some(MAINNET_DEPOSIT_CONTRACT.address),
+        blob_schedule,
+    )
+}
+
+/// Converts the given [`BlobScheduleBlobParams`] into blobs schedule.
+pub fn blob_params_to_schedule(
+    params: &BlobScheduleBlobParams,
+    hardforks: &ChainHardforks,
+) -> BTreeMap<String, BlobParams> {
+    let mut schedule = BTreeMap::new();
+    schedule.insert("cancun".to_string(), params.cancun);
+    schedule.insert("prague".to_string(), params.prague);
+    schedule.insert("osaka".to_string(), params.osaka);
+
+    // Map scheduled entries back to bpo fork names by matching timestamps
+    let bpo_forks = EthereumHardfork::bpo_variants();
+    for (timestamp, blob_params) in &params.scheduled {
+        for bpo_fork in bpo_forks {
+            if let ForkCondition::Timestamp(fork_ts) = hardforks.fork(bpo_fork) &&
+                fork_ts == *timestamp
+            {
+                schedule.insert(bpo_fork.name().to_lowercase(), *blob_params);
+                break;
+            }
+        }
+    }
+
+    schedule
+}
+
 /// A wrapper around [`BaseFeeParams`] that allows for specifying constant or dynamic EIP-1559
 /// parameters based on the active [Hardfork].
 #[derive(Clone, Debug, PartialEq, Eq)]
@@ -346,6 +462,18 @@ impl ChainSpec {
     pub fn builder() -> ChainSpecBuilder {
         ChainSpecBuilder::default()
     }
+
+    /// Map a chain ID to a known chain spec, if available.
+    pub fn from_chain_id(chain_id: u64) -> Option<Arc<Self>> {
+        match NamedChain::try_from(chain_id).ok()? {
+            NamedChain::Mainnet => Some(MAINNET.clone()),
+            NamedChain::Sepolia => Some(SEPOLIA.clone()),
+            NamedChain::Holesky => Some(HOLESKY.clone()),
+            NamedChain::Hoodi => Some(HOODI.clone()),
+            NamedChain::Dev => Some(DEV.clone()),
+            _ => None,
+        }
+    }
 }
 
 impl<H: BlockHeader> ChainSpec<H> {
@@ -514,8 +642,15 @@ impl<H: BlockHeader> ChainSpec<H> {
 
     /// Compute the [`ForkId`] for the given [`Head`] following eip-6122 spec.
     ///
-    /// Note: In case there are multiple hardforks activated at the same block or timestamp, only
-    /// the first gets applied.
+    /// The fork hash is computed by starting from the genesis hash and iteratively adding
+    /// block numbers (for block-based forks) or timestamps (for timestamp-based forks) of
+    /// active forks. The `next` field indicates the next fork activation point, or `0` if
+    /// all forks are active.
+    ///
+    /// Block-based forks are processed first, then timestamp-based forks. Multiple hardforks
+    /// activated at the same block or timestamp: only the first one is applied.
+    ///
+    /// See: <https://eips.ethereum.org/EIPS/eip-6122>
     pub fn fork_id(&self, head: &Head) -> ForkId {
         let mut forkhash = ForkHash::from(self.genesis_hash());
 
@@ -572,6 +707,10 @@ impl<H: BlockHeader> ChainSpec<H> {
     }
 
     /// An internal helper function that returns a head block that satisfies a given Fork condition.
+    ///
+    /// Creates a [`Head`] representation for a fork activation point, used by [`Self::fork_id`] to
+    /// compute fork IDs. For timestamp-based forks, includes the last block-based fork number
+    /// before the merge (if any).
     pub(crate) fn satisfy(&self, cond: ForkCondition) -> Head {
         match cond {
             ForkCondition::Block(number) => Head { number, ..Default::default() },
@@ -845,7 +984,7 @@ impl<H: BlockHeader> EthereumHardforks for ChainSpec<H> {
 
 /// A trait for reading the current chainspec.
 #[auto_impl::auto_impl(&, Arc)]
-pub trait ChainSpecProvider: Debug + Send + Sync {
+pub trait ChainSpecProvider: Debug + Send {
     /// The chain spec type.
     type ChainSpec: EthChainSpec + 'static;
 
@@ -925,9 +1064,16 @@ impl ChainSpecBuilder {
         self
     }
 
+    /// Enable Dao at genesis.
+    pub fn dao_activated(mut self) -> Self {
+        self = self.frontier_activated();
+        self.hardforks.insert(EthereumHardfork::Dao, ForkCondition::Block(0));
+        self
+    }
+
     /// Enable Homestead at genesis.
     pub fn homestead_activated(mut self) -> Self {
-        self = self.frontier_activated();
+        self = self.dao_activated();
         self.hardforks.insert(EthereumHardfork::Homestead, ForkCondition::Block(0));
         self
     }
@@ -974,9 +1120,16 @@ impl ChainSpecBuilder {
         self
     }
 
+    /// Enable Muir Glacier at genesis.
+    pub fn muirglacier_activated(mut self) -> Self {
+        self = self.istanbul_activated();
+        self.hardforks.insert(EthereumHardfork::MuirGlacier, ForkCondition::Block(0));
+        self
+    }
+
     /// Enable Berlin at genesis.
     pub fn berlin_activated(mut self) -> Self {
-        self = self.istanbul_activated();
+        self = self.muirglacier_activated();
         self.hardforks.insert(EthereumHardfork::Berlin, ForkCondition::Block(0));
         self
     }
@@ -988,9 +1141,23 @@ impl ChainSpecBuilder {
         self
     }
 
+    /// Enable Arrow Glacier at genesis.
+    pub fn arrowglacier_activated(mut self) -> Self {
+        self = self.london_activated();
+        self.hardforks.insert(EthereumHardfork::ArrowGlacier, ForkCondition::Block(0));
+        self
+    }
+
+    /// Enable Gray Glacier at genesis.
+    pub fn grayglacier_activated(mut self) -> Self {
+        self = self.arrowglacier_activated();
+        self.hardforks.insert(EthereumHardfork::GrayGlacier, ForkCondition::Block(0));
+        self
+    }
+
     /// Enable Paris at genesis.
     pub fn paris_activated(mut self) -> Self {
-        self = self.london_activated();
+        self = self.grayglacier_activated();
         self.hardforks.insert(
             EthereumHardfork::Paris,
             ForkCondition::TTD {
@@ -1363,72 +1530,72 @@ Post-merge hard forks (timestamp based):
             &[
                 (
                     EthereumHardfork::Frontier,
-                    ForkId { hash: ForkHash([0xfc, 0x64, 0xec, 0x04]), next: 1150000 },
+                    ForkId { hash: ForkHash(hex!("0xfc64ec04")), next: 1150000 },
                 ),
                 (
                     EthereumHardfork::Homestead,
-                    ForkId { hash: ForkHash([0x97, 0xc2, 0xc3, 0x4c]), next: 1920000 },
+                    ForkId { hash: ForkHash(hex!("0x97c2c34c")), next: 1920000 },
                 ),
                 (
                     EthereumHardfork::Dao,
-                    ForkId { hash: ForkHash([0x91, 0xd1, 0xf9, 0x48]), next: 2463000 },
+                    ForkId { hash: ForkHash(hex!("0x91d1f948")), next: 2463000 },
                 ),
                 (
                     EthereumHardfork::Tangerine,
-                    ForkId { hash: ForkHash([0x7a, 0x64, 0xda, 0x13]), next: 2675000 },
+                    ForkId { hash: ForkHash(hex!("0x7a64da13")), next: 2675000 },
                 ),
                 (
                     EthereumHardfork::SpuriousDragon,
-                    ForkId { hash: ForkHash([0x3e, 0xdd, 0x5b, 0x10]), next: 4370000 },
+                    ForkId { hash: ForkHash(hex!("0x3edd5b10")), next: 4370000 },
                 ),
                 (
                     EthereumHardfork::Byzantium,
-                    ForkId { hash: ForkHash([0xa0, 0x0b, 0xc3, 0x24]), next: 7280000 },
+                    ForkId { hash: ForkHash(hex!("0xa00bc324")), next: 7280000 },
                 ),
                 (
                     EthereumHardfork::Constantinople,
-                    ForkId { hash: ForkHash([0x66, 0x8d, 0xb0, 0xaf]), next: 9069000 },
+                    ForkId { hash: ForkHash(hex!("0x668db0af")), next: 9069000 },
                 ),
                 (
                     EthereumHardfork::Petersburg,
-                    ForkId { hash: ForkHash([0x66, 0x8d, 0xb0, 0xaf]), next: 9069000 },
+                    ForkId { hash: ForkHash(hex!("0x668db0af")), next: 9069000 },
                 ),
                 (
                     EthereumHardfork::Istanbul,
-                    ForkId { hash: ForkHash([0x87, 0x9d, 0x6e, 0x30]), next: 9200000 },
+                    ForkId { hash: ForkHash(hex!("0x879d6e30")), next: 9200000 },
                 ),
                 (
                     EthereumHardfork::MuirGlacier,
-                    ForkId { hash: ForkHash([0xe0, 0x29, 0xe9, 0x91]), next: 12244000 },
+                    ForkId { hash: ForkHash(hex!("0xe029e991")), next: 12244000 },
                 ),
                 (
                     EthereumHardfork::Berlin,
-                    ForkId { hash: ForkHash([0x0e, 0xb4, 0x40, 0xf6]), next: 12965000 },
+                    ForkId { hash: ForkHash(hex!("0x0eb440f6")), next: 12965000 },
                 ),
                 (
                     EthereumHardfork::London,
-                    ForkId { hash: ForkHash([0xb7, 0x15, 0x07, 0x7d]), next: 13773000 },
+                    ForkId { hash: ForkHash(hex!("0xb715077d")), next: 13773000 },
                 ),
                 (
                     EthereumHardfork::ArrowGlacier,
-                    ForkId { hash: ForkHash([0x20, 0xc3, 0x27, 0xfc]), next: 15050000 },
+                    ForkId { hash: ForkHash(hex!("0x20c327fc")), next: 15050000 },
                 ),
                 (
                     EthereumHardfork::GrayGlacier,
-                    ForkId { hash: ForkHash([0xf0, 0xaf, 0xd0, 0xe3]), next: 1681338455 },
+                    ForkId { hash: ForkHash(hex!("0xf0afd0e3")), next: 1681338455 },
                 ),
                 (
                     EthereumHardfork::Shanghai,
-                    ForkId { hash: ForkHash([0xdc, 0xe9, 0x6c, 0x2d]), next: 1710338135 },
+                    ForkId { hash: ForkHash(hex!("0xdce96c2d")), next: 1710338135 },
                 ),
                 (
                     EthereumHardfork::Cancun,
-                    ForkId { hash: ForkHash([0x9f, 0x3d, 0x22, 0x54]), next: 1746612311 },
+                    ForkId { hash: ForkHash(hex!("0x9f3d2254")), next: 1746612311 },
                 ),
                 (
                     EthereumHardfork::Prague,
                     ForkId {
-                        hash: ForkHash([0xc3, 0x76, 0xcf, 0x8b]),
+                        hash: ForkHash(hex!("0xc376cf8b")),
                         next: mainnet::MAINNET_OSAKA_TIMESTAMP,
                     },
                 ),
@@ -1443,60 +1610,60 @@ Post-merge hard forks (timestamp based):
             &[
                 (
                     EthereumHardfork::Frontier,
-                    ForkId { hash: ForkHash([0xfe, 0x33, 0x66, 0xe7]), next: 1735371 },
+                    ForkId { hash: ForkHash(hex!("0xfe3366e7")), next: 1735371 },
                 ),
                 (
                     EthereumHardfork::Homestead,
-                    ForkId { hash: ForkHash([0xfe, 0x33, 0x66, 0xe7]), next: 1735371 },
+                    ForkId { hash: ForkHash(hex!("0xfe3366e7")), next: 1735371 },
                 ),
                 (
                     EthereumHardfork::Tangerine,
-                    ForkId { hash: ForkHash([0xfe, 0x33, 0x66, 0xe7]), next: 1735371 },
+                    ForkId { hash: ForkHash(hex!("0xfe3366e7")), next: 1735371 },
                 ),
                 (
                     EthereumHardfork::SpuriousDragon,
-                    ForkId { hash: ForkHash([0xfe, 0x33, 0x66, 0xe7]), next: 1735371 },
+                    ForkId { hash: ForkHash(hex!("0xfe3366e7")), next: 1735371 },
                 ),
                 (
                     EthereumHardfork::Byzantium,
-                    ForkId { hash: ForkHash([0xfe, 0x33, 0x66, 0xe7]), next: 1735371 },
+                    ForkId { hash: ForkHash(hex!("0xfe3366e7")), next: 1735371 },
                 ),
                 (
                     EthereumHardfork::Constantinople,
-                    ForkId { hash: ForkHash([0xfe, 0x33, 0x66, 0xe7]), next: 1735371 },
+                    ForkId { hash: ForkHash(hex!("0xfe3366e7")), next: 1735371 },
                 ),
                 (
                     EthereumHardfork::Petersburg,
-                    ForkId { hash: ForkHash([0xfe, 0x33, 0x66, 0xe7]), next: 1735371 },
+                    ForkId { hash: ForkHash(hex!("0xfe3366e7")), next: 1735371 },
                 ),
                 (
                     EthereumHardfork::Istanbul,
-                    ForkId { hash: ForkHash([0xfe, 0x33, 0x66, 0xe7]), next: 1735371 },
+                    ForkId { hash: ForkHash(hex!("0xfe3366e7")), next: 1735371 },
                 ),
                 (
                     EthereumHardfork::Berlin,
-                    ForkId { hash: ForkHash([0xfe, 0x33, 0x66, 0xe7]), next: 1735371 },
+                    ForkId { hash: ForkHash(hex!("0xfe3366e7")), next: 1735371 },
                 ),
                 (
                     EthereumHardfork::London,
-                    ForkId { hash: ForkHash([0xfe, 0x33, 0x66, 0xe7]), next: 1735371 },
+                    ForkId { hash: ForkHash(hex!("0xfe3366e7")), next: 1735371 },
                 ),
                 (
                     EthereumHardfork::Paris,
-                    ForkId { hash: ForkHash([0xb9, 0x6c, 0xbd, 0x13]), next: 1677557088 },
+                    ForkId { hash: ForkHash(hex!("0xb96cbd13")), next: 1677557088 },
                 ),
                 (
                     EthereumHardfork::Shanghai,
-                    ForkId { hash: ForkHash([0xf7, 0xf9, 0xbc, 0x08]), next: 1706655072 },
+                    ForkId { hash: ForkHash(hex!("0xf7f9bc08")), next: 1706655072 },
                 ),
                 (
                     EthereumHardfork::Cancun,
-                    ForkId { hash: ForkHash([0x88, 0xcf, 0x81, 0xd9]), next: 1741159776 },
+                    ForkId { hash: ForkHash(hex!("0x88cf81d9")), next: 1741159776 },
                 ),
                 (
                     EthereumHardfork::Prague,
                     ForkId {
-                        hash: ForkHash([0xed, 0x88, 0xb5, 0xfd]),
+                        hash: ForkHash(hex!("0xed88b5fd")),
                         next: sepolia::SEPOLIA_OSAKA_TIMESTAMP,
                     },
                 ),
@@ -1511,71 +1678,71 @@ Post-merge hard forks (timestamp based):
             &[
                 (
                     Head { number: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0xfc, 0x64, 0xec, 0x04]), next: 1150000 },
+                    ForkId { hash: ForkHash(hex!("0xfc64ec04")), next: 1150000 },
                 ),
                 (
                     Head { number: 1150000, ..Default::default() },
-                    ForkId { hash: ForkHash([0x97, 0xc2, 0xc3, 0x4c]), next: 1920000 },
+                    ForkId { hash: ForkHash(hex!("0x97c2c34c")), next: 1920000 },
                 ),
                 (
                     Head { number: 1920000, ..Default::default() },
-                    ForkId { hash: ForkHash([0x91, 0xd1, 0xf9, 0x48]), next: 2463000 },
+                    ForkId { hash: ForkHash(hex!("0x91d1f948")), next: 2463000 },
                 ),
                 (
                     Head { number: 2463000, ..Default::default() },
-                    ForkId { hash: ForkHash([0x7a, 0x64, 0xda, 0x13]), next: 2675000 },
+                    ForkId { hash: ForkHash(hex!("0x7a64da13")), next: 2675000 },
                 ),
                 (
                     Head { number: 2675000, ..Default::default() },
-                    ForkId { hash: ForkHash([0x3e, 0xdd, 0x5b, 0x10]), next: 4370000 },
+                    ForkId { hash: ForkHash(hex!("0x3edd5b10")), next: 4370000 },
                 ),
                 (
                     Head { number: 4370000, ..Default::default() },
-                    ForkId { hash: ForkHash([0xa0, 0x0b, 0xc3, 0x24]), next: 7280000 },
+                    ForkId { hash: ForkHash(hex!("0xa00bc324")), next: 7280000 },
                 ),
                 (
                     Head { number: 7280000, ..Default::default() },
-                    ForkId { hash: ForkHash([0x66, 0x8d, 0xb0, 0xaf]), next: 9069000 },
+                    ForkId { hash: ForkHash(hex!("0x668db0af")), next: 9069000 },
                 ),
                 (
                     Head { number: 9069000, ..Default::default() },
-                    ForkId { hash: ForkHash([0x87, 0x9d, 0x6e, 0x30]), next: 9200000 },
+                    ForkId { hash: ForkHash(hex!("0x879d6e30")), next: 9200000 },
                 ),
                 (
                     Head { number: 9200000, ..Default::default() },
-                    ForkId { hash: ForkHash([0xe0, 0x29, 0xe9, 0x91]), next: 12244000 },
+                    ForkId { hash: ForkHash(hex!("0xe029e991")), next: 12244000 },
                 ),
                 (
                     Head { number: 12244000, ..Default::default() },
-                    ForkId { hash: ForkHash([0x0e, 0xb4, 0x40, 0xf6]), next: 12965000 },
+                    ForkId { hash: ForkHash(hex!("0x0eb440f6")), next: 12965000 },
                 ),
                 (
                     Head { number: 12965000, ..Default::default() },
-                    ForkId { hash: ForkHash([0xb7, 0x15, 0x07, 0x7d]), next: 13773000 },
+                    ForkId { hash: ForkHash(hex!("0xb715077d")), next: 13773000 },
                 ),
                 (
                     Head { number: 13773000, ..Default::default() },
-                    ForkId { hash: ForkHash([0x20, 0xc3, 0x27, 0xfc]), next: 15050000 },
+                    ForkId { hash: ForkHash(hex!("0x20c327fc")), next: 15050000 },
                 ),
                 (
                     Head { number: 15050000, ..Default::default() },
-                    ForkId { hash: ForkHash([0xf0, 0xaf, 0xd0, 0xe3]), next: 1681338455 },
+                    ForkId { hash: ForkHash(hex!("0xf0afd0e3")), next: 1681338455 },
                 ),
                 // First Shanghai block
                 (
                     Head { number: 20000000, timestamp: 1681338455, ..Default::default() },
-                    ForkId { hash: ForkHash([0xdc, 0xe9, 0x6c, 0x2d]), next: 1710338135 },
+                    ForkId { hash: ForkHash(hex!("0xdce96c2d")), next: 1710338135 },
                 ),
                 // First Cancun block
                 (
                     Head { number: 20000001, timestamp: 1710338135, ..Default::default() },
-                    ForkId { hash: ForkHash([0x9f, 0x3d, 0x22, 0x54]), next: 1746612311 },
+                    ForkId { hash: ForkHash(hex!("0x9f3d2254")), next: 1746612311 },
                 ),
                 // First Prague block
                 (
                     Head { number: 20000004, timestamp: 1746612311, ..Default::default() },
                     ForkId {
-                        hash: ForkHash([0xc3, 0x76, 0xcf, 0x8b]),
+                        hash: ForkHash(hex!("0xc376cf8b")),
                         next: mainnet::MAINNET_OSAKA_TIMESTAMP,
                     },
                 ),
@@ -1602,13 +1769,13 @@ Post-merge hard forks (timestamp based):
             &[
                 (
                     Head { number: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0xbe, 0xf7, 0x1d, 0x30]), next: 1742999832 },
+                    ForkId { hash: ForkHash(hex!("0xbef71d30")), next: 1742999832 },
                 ),
                 // First Prague block
                 (
                     Head { number: 0, timestamp: 1742999833, ..Default::default() },
                     ForkId {
-                        hash: ForkHash([0x09, 0x29, 0xe2, 0x4e]),
+                        hash: ForkHash(hex!("0x0929e24e")),
                         next: hoodi::HOODI_OSAKA_TIMESTAMP,
                     },
                 ),
@@ -1635,43 +1802,43 @@ Post-merge hard forks (timestamp based):
             &[
                 (
                     Head { number: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0xc6, 0x1a, 0x60, 0x98]), next: 1696000704 },
+                    ForkId { hash: ForkHash(hex!("0xc61a6098")), next: 1696000704 },
                 ),
                 // First MergeNetsplit block
                 (
                     Head { number: 123, ..Default::default() },
-                    ForkId { hash: ForkHash([0xc6, 0x1a, 0x60, 0x98]), next: 1696000704 },
+                    ForkId { hash: ForkHash(hex!("0xc61a6098")), next: 1696000704 },
                 ),
                 // Last MergeNetsplit block
                 (
                     Head { number: 123, timestamp: 1696000703, ..Default::default() },
-                    ForkId { hash: ForkHash([0xc6, 0x1a, 0x60, 0x98]), next: 1696000704 },
+                    ForkId { hash: ForkHash(hex!("0xc61a6098")), next: 1696000704 },
                 ),
                 // First Shanghai block
                 (
                     Head { number: 123, timestamp: 1696000704, ..Default::default() },
-                    ForkId { hash: ForkHash([0xfd, 0x4f, 0x01, 0x6b]), next: 1707305664 },
+                    ForkId { hash: ForkHash(hex!("0xfd4f016b")), next: 1707305664 },
                 ),
                 // Last Shanghai block
                 (
                     Head { number: 123, timestamp: 1707305663, ..Default::default() },
-                    ForkId { hash: ForkHash([0xfd, 0x4f, 0x01, 0x6b]), next: 1707305664 },
+                    ForkId { hash: ForkHash(hex!("0xfd4f016b")), next: 1707305664 },
                 ),
                 // First Cancun block
                 (
                     Head { number: 123, timestamp: 1707305664, ..Default::default() },
-                    ForkId { hash: ForkHash([0x9b, 0x19, 0x2a, 0xd0]), next: 1740434112 },
+                    ForkId { hash: ForkHash(hex!("0x9b192ad0")), next: 1740434112 },
                 ),
                 // Last Cancun block
                 (
                     Head { number: 123, timestamp: 1740434111, ..Default::default() },
-                    ForkId { hash: ForkHash([0x9b, 0x19, 0x2a, 0xd0]), next: 1740434112 },
+                    ForkId { hash: ForkHash(hex!("0x9b192ad0")), next: 1740434112 },
                 ),
                 // First Prague block
                 (
                     Head { number: 123, timestamp: 1740434112, ..Default::default() },
                     ForkId {
-                        hash: ForkHash([0xdf, 0xbd, 0x9b, 0xed]),
+                        hash: ForkHash(hex!("0xdfbd9bed")),
                         next: holesky::HOLESKY_OSAKA_TIMESTAMP,
                     },
                 ),
@@ -1698,45 +1865,45 @@ Post-merge hard forks (timestamp based):
             &[
                 (
                     Head { number: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0xfe, 0x33, 0x66, 0xe7]), next: 1735371 },
+                    ForkId { hash: ForkHash(hex!("0xfe3366e7")), next: 1735371 },
                 ),
                 (
                     Head { number: 1735370, ..Default::default() },
-                    ForkId { hash: ForkHash([0xfe, 0x33, 0x66, 0xe7]), next: 1735371 },
+                    ForkId { hash: ForkHash(hex!("0xfe3366e7")), next: 1735371 },
                 ),
                 (
                     Head { number: 1735371, ..Default::default() },
-                    ForkId { hash: ForkHash([0xb9, 0x6c, 0xbd, 0x13]), next: 1677557088 },
+                    ForkId { hash: ForkHash(hex!("0xb96cbd13")), next: 1677557088 },
                 ),
                 (
                     Head { number: 1735372, timestamp: 1677557087, ..Default::default() },
-                    ForkId { hash: ForkHash([0xb9, 0x6c, 0xbd, 0x13]), next: 1677557088 },
+                    ForkId { hash: ForkHash(hex!("0xb96cbd13")), next: 1677557088 },
                 ),
                 // First Shanghai block
                 (
                     Head { number: 1735373, timestamp: 1677557088, ..Default::default() },
-                    ForkId { hash: ForkHash([0xf7, 0xf9, 0xbc, 0x08]), next: 1706655072 },
+                    ForkId { hash: ForkHash(hex!("0xf7f9bc08")), next: 1706655072 },
                 ),
                 // Last Shanghai block
                 (
                     Head { number: 1735374, timestamp: 1706655071, ..Default::default() },
-                    ForkId { hash: ForkHash([0xf7, 0xf9, 0xbc, 0x08]), next: 1706655072 },
+                    ForkId { hash: ForkHash(hex!("0xf7f9bc08")), next: 1706655072 },
                 ),
                 // First Cancun block
                 (
                     Head { number: 1735375, timestamp: 1706655072, ..Default::default() },
-                    ForkId { hash: ForkHash([0x88, 0xcf, 0x81, 0xd9]), next: 1741159776 },
+                    ForkId { hash: ForkHash(hex!("0x88cf81d9")), next: 1741159776 },
                 ),
                 // Last Cancun block
                 (
                     Head { number: 1735376, timestamp: 1741159775, ..Default::default() },
-                    ForkId { hash: ForkHash([0x88, 0xcf, 0x81, 0xd9]), next: 1741159776 },
+                    ForkId { hash: ForkHash(hex!("0x88cf81d9")), next: 1741159776 },
                 ),
                 // First Prague block
                 (
                     Head { number: 1735377, timestamp: 1741159776, ..Default::default() },
                     ForkId {
-                        hash: ForkHash([0xed, 0x88, 0xb5, 0xfd]),
+                        hash: ForkHash(hex!("0xed88b5fd")),
                         next: sepolia::SEPOLIA_OSAKA_TIMESTAMP,
                     },
                 ),
@@ -1762,7 +1929,7 @@ Post-merge hard forks (timestamp based):
             &DEV,
             &[(
                 Head { number: 0, ..Default::default() },
-                ForkId { hash: ForkHash([0x0b, 0x1a, 0x4e, 0xf7]), next: 0 },
+                ForkId { hash: ForkHash(hex!("0x0b1a4ef7")), next: 0 },
             )],
         )
     }
@@ -1778,128 +1945,128 @@ Post-merge hard forks (timestamp based):
             &[
                 (
                     Head { number: 0, timestamp: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0xfc, 0x64, 0xec, 0x04]), next: 1150000 },
+                    ForkId { hash: ForkHash(hex!("0xfc64ec04")), next: 1150000 },
                 ), // Unsynced
                 (
                     Head { number: 1149999, timestamp: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0xfc, 0x64, 0xec, 0x04]), next: 1150000 },
+                    ForkId { hash: ForkHash(hex!("0xfc64ec04")), next: 1150000 },
                 ), // Last Frontier block
                 (
                     Head { number: 1150000, timestamp: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0x97, 0xc2, 0xc3, 0x4c]), next: 1920000 },
+                    ForkId { hash: ForkHash(hex!("0x97c2c34c")), next: 1920000 },
                 ), // First Homestead block
                 (
                     Head { number: 1919999, timestamp: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0x97, 0xc2, 0xc3, 0x4c]), next: 1920000 },
+                    ForkId { hash: ForkHash(hex!("0x97c2c34c")), next: 1920000 },
                 ), // Last Homestead block
                 (
                     Head { number: 1920000, timestamp: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0x91, 0xd1, 0xf9, 0x48]), next: 2463000 },
+                    ForkId { hash: ForkHash(hex!("0x91d1f948")), next: 2463000 },
                 ), // First DAO block
                 (
                     Head { number: 2462999, timestamp: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0x91, 0xd1, 0xf9, 0x48]), next: 2463000 },
+                    ForkId { hash: ForkHash(hex!("0x91d1f948")), next: 2463000 },
                 ), // Last DAO block
                 (
                     Head { number: 2463000, timestamp: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0x7a, 0x64, 0xda, 0x13]), next: 2675000 },
+                    ForkId { hash: ForkHash(hex!("0x7a64da13")), next: 2675000 },
                 ), // First Tangerine block
                 (
                     Head { number: 2674999, timestamp: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0x7a, 0x64, 0xda, 0x13]), next: 2675000 },
+                    ForkId { hash: ForkHash(hex!("0x7a64da13")), next: 2675000 },
                 ), // Last Tangerine block
                 (
                     Head { number: 2675000, timestamp: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0x3e, 0xdd, 0x5b, 0x10]), next: 4370000 },
+                    ForkId { hash: ForkHash(hex!("0x3edd5b10")), next: 4370000 },
                 ), // First Spurious block
                 (
                     Head { number: 4369999, timestamp: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0x3e, 0xdd, 0x5b, 0x10]), next: 4370000 },
+                    ForkId { hash: ForkHash(hex!("0x3edd5b10")), next: 4370000 },
                 ), // Last Spurious block
                 (
                     Head { number: 4370000, timestamp: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0xa0, 0x0b, 0xc3, 0x24]), next: 7280000 },
+                    ForkId { hash: ForkHash(hex!("0xa00bc324")), next: 7280000 },
                 ), // First Byzantium block
                 (
                     Head { number: 7279999, timestamp: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0xa0, 0x0b, 0xc3, 0x24]), next: 7280000 },
+                    ForkId { hash: ForkHash(hex!("0xa00bc324")), next: 7280000 },
                 ), // Last Byzantium block
                 (
                     Head { number: 7280000, timestamp: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0x66, 0x8d, 0xb0, 0xaf]), next: 9069000 },
+                    ForkId { hash: ForkHash(hex!("0x668db0af")), next: 9069000 },
                 ), // First and last Constantinople, first Petersburg block
                 (
                     Head { number: 9068999, timestamp: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0x66, 0x8d, 0xb0, 0xaf]), next: 9069000 },
+                    ForkId { hash: ForkHash(hex!("0x668db0af")), next: 9069000 },
                 ), // Last Petersburg block
                 (
                     Head { number: 9069000, timestamp: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0x87, 0x9d, 0x6e, 0x30]), next: 9200000 },
+                    ForkId { hash: ForkHash(hex!("0x879d6e30")), next: 9200000 },
                 ), // First Istanbul and first Muir Glacier block
                 (
                     Head { number: 9199999, timestamp: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0x87, 0x9d, 0x6e, 0x30]), next: 9200000 },
+                    ForkId { hash: ForkHash(hex!("0x879d6e30")), next: 9200000 },
                 ), // Last Istanbul and first Muir Glacier block
                 (
                     Head { number: 9200000, timestamp: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0xe0, 0x29, 0xe9, 0x91]), next: 12244000 },
+                    ForkId { hash: ForkHash(hex!("0xe029e991")), next: 12244000 },
                 ), // First Muir Glacier block
                 (
                     Head { number: 12243999, timestamp: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0xe0, 0x29, 0xe9, 0x91]), next: 12244000 },
+                    ForkId { hash: ForkHash(hex!("0xe029e991")), next: 12244000 },
                 ), // Last Muir Glacier block
                 (
                     Head { number: 12244000, timestamp: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0x0e, 0xb4, 0x40, 0xf6]), next: 12965000 },
+                    ForkId { hash: ForkHash(hex!("0x0eb440f6")), next: 12965000 },
                 ), // First Berlin block
                 (
                     Head { number: 12964999, timestamp: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0x0e, 0xb4, 0x40, 0xf6]), next: 12965000 },
+                    ForkId { hash: ForkHash(hex!("0x0eb440f6")), next: 12965000 },
                 ), // Last Berlin block
                 (
                     Head { number: 12965000, timestamp: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0xb7, 0x15, 0x07, 0x7d]), next: 13773000 },
+                    ForkId { hash: ForkHash(hex!("0xb715077d")), next: 13773000 },
                 ), // First London block
                 (
                     Head { number: 13772999, timestamp: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0xb7, 0x15, 0x07, 0x7d]), next: 13773000 },
+                    ForkId { hash: ForkHash(hex!("0xb715077d")), next: 13773000 },
                 ), // Last London block
                 (
                     Head { number: 13773000, timestamp: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0x20, 0xc3, 0x27, 0xfc]), next: 15050000 },
+                    ForkId { hash: ForkHash(hex!("0x20c327fc")), next: 15050000 },
                 ), // First Arrow Glacier block
                 (
                     Head { number: 15049999, timestamp: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0x20, 0xc3, 0x27, 0xfc]), next: 15050000 },
+                    ForkId { hash: ForkHash(hex!("0x20c327fc")), next: 15050000 },
                 ), // Last Arrow Glacier block
                 (
                     Head { number: 15050000, timestamp: 0, ..Default::default() },
-                    ForkId { hash: ForkHash([0xf0, 0xaf, 0xd0, 0xe3]), next: 1681338455 },
+                    ForkId { hash: ForkHash(hex!("0xf0afd0e3")), next: 1681338455 },
                 ), // First Gray Glacier block
                 (
                     Head { number: 19999999, timestamp: 1667999999, ..Default::default() },
-                    ForkId { hash: ForkHash([0xf0, 0xaf, 0xd0, 0xe3]), next: 1681338455 },
+                    ForkId { hash: ForkHash(hex!("0xf0afd0e3")), next: 1681338455 },
                 ), // Last Gray Glacier block
                 (
                     Head { number: 20000000, timestamp: 1681338455, ..Default::default() },
-                    ForkId { hash: ForkHash([0xdc, 0xe9, 0x6c, 0x2d]), next: 1710338135 },
+                    ForkId { hash: ForkHash(hex!("0xdce96c2d")), next: 1710338135 },
                 ), // Last Shanghai block
                 (
                     Head { number: 20000001, timestamp: 1710338134, ..Default::default() },
-                    ForkId { hash: ForkHash([0xdc, 0xe9, 0x6c, 0x2d]), next: 1710338135 },
+                    ForkId { hash: ForkHash(hex!("0xdce96c2d")), next: 1710338135 },
                 ), // First Cancun block
                 (
                     Head { number: 20000002, timestamp: 1710338135, ..Default::default() },
-                    ForkId { hash: ForkHash([0x9f, 0x3d, 0x22, 0x54]), next: 1746612311 },
+                    ForkId { hash: ForkHash(hex!("0x9f3d2254")), next: 1746612311 },
                 ), // Last Cancun block
                 (
                     Head { number: 20000003, timestamp: 1746612310, ..Default::default() },
-                    ForkId { hash: ForkHash([0x9f, 0x3d, 0x22, 0x54]), next: 1746612311 },
+                    ForkId { hash: ForkHash(hex!("0x9f3d2254")), next: 1746612311 },
                 ), // First Prague block
                 (
                     Head { number: 20000004, timestamp: 1746612311, ..Default::default() },
                     ForkId {
-                        hash: ForkHash([0xc3, 0x76, 0xcf, 0x8b]),
+                        hash: ForkHash(hex!("0xc376cf8b")),
                         next: mainnet::MAINNET_OSAKA_TIMESTAMP,
                     },
                 ),
@@ -2369,7 +2536,7 @@ Post-merge hard forks (timestamp based):
         let chainspec = ChainSpec::from(genesis);
 
         // make sure we are at ForkHash("bc0c2605") with Head post-cancun
-        let expected_forkid = ForkId { hash: ForkHash([0xbc, 0x0c, 0x26, 0x05]), next: 0 };
+        let expected_forkid = ForkId { hash: ForkHash(hex!("0xbc0c2605")), next: 0 };
         let got_forkid =
             chainspec.fork_id(&Head { number: 73, timestamp: 840, ..Default::default() });
 
@@ -2479,7 +2646,7 @@ Post-merge hard forks (timestamp based):
         assert_eq!(genesis_hash, expected_hash);
 
         // check that the forkhash is correct
-        let expected_forkhash = ForkHash(hex!("8062457a"));
+        let expected_forkhash = ForkHash(hex!("0x8062457a"));
         assert_eq!(ForkHash::from(genesis_hash), expected_forkhash);
     }
 

crates/cli/commands/Cargo.toml

@@ -49,6 +49,8 @@ reth-stages.workspace = true
 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
@@ -82,6 +84,8 @@ backon.workspace = true
 secp256k1 = { workspace = true, features = ["global-context", "std", "recovery"] }
 tokio-stream.workspace = true
 reqwest.workspace = true
+url.workspace = true
+metrics.workspace = true
 
 # io
 fdlimit.workspace = true
@@ -127,3 +131,5 @@ arbitrary = [
     "reth-primitives-traits/arbitrary",
     "reth-ethereum-primitives/arbitrary",
 ]
+
+edge = ["reth-db-common/edge", "reth-stages/rocksdb", "reth-provider/rocksdb"]

crates/cli/commands/src/common.rs

@@ -1,5 +1,7 @@
 //! Contains common `reth` arguments
 
+pub use reth_primitives_traits::header::HeaderMut;
+
 use alloy_primitives::B256;
 use clap::Parser;
 use reth_chainspec::EthChainSpec;
@@ -7,7 +9,7 @@ use reth_cli::chainspec::ChainSpecParser;
 use reth_config::{config::EtlConfig, Config};
 use reth_consensus::noop::NoopConsensus;
 use reth_db::{init_db, open_db_read_only, DatabaseEnv};
-use reth_db_common::init::init_genesis;
+use reth_db_common::init::init_genesis_with_settings;
 use reth_downloaders::{bodies::noop::NoopBodiesDownloader, headers::noop::NoopHeaderDownloader};
 use reth_eth_wire::NetPrimitivesFor;
 use reth_evm::{noop::NoopEvmConfig, ConfigureEvm};
@@ -17,12 +19,15 @@ use reth_node_builder::{
     Node, NodeComponents, NodeComponentsBuilder, NodeTypes, NodeTypesWithDBAdapter,
 };
 use reth_node_core::{
-    args::{DatabaseArgs, DatadirArgs},
+    args::{DatabaseArgs, DatadirArgs, RocksDbArgs, StaticFilesArgs},
     dirs::{ChainPath, DataDirPath},
 };
 use reth_provider::{
-    providers::{BlockchainProvider, NodeTypesForProvider, StaticFileProvider},
-    ProviderFactory, StaticFileProviderFactory,
+    providers::{
+        BlockchainProvider, NodeTypesForProvider, RocksDBProvider, StaticFileProvider,
+        StaticFileProviderBuilder,
+    },
+    ProviderFactory, StaticFileProviderFactory, StorageSettings,
 };
 use reth_stages::{sets::DefaultStages, Pipeline, PipelineTarget};
 use reth_static_file::StaticFileProducer;
@@ -57,9 +62,28 @@ pub struct EnvironmentArgs<C: ChainSpecParser> {
     /// All database related arguments
     #[command(flatten)]
     pub db: DatabaseArgs,
+
+    /// 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>>
@@ -69,10 +93,12 @@ impl<C: ChainSpecParser> EnvironmentArgs<C> {
         let data_dir = self.datadir.clone().resolve_datadir(self.chain.chain());
         let db_path = data_dir.db();
         let sf_path = data_dir.static_files();
+        let rocksdb_path = data_dir.rocksdb();
 
         if access.is_read_write() {
             reth_fs_util::create_dir_all(&db_path)?;
             reth_fs_util::create_dir_all(&sf_path)?;
+            reth_fs_util::create_dir_all(&rocksdb_path)?;
         }
 
         let config_path = self.config.clone().unwrap_or_else(|| data_dir.config());
@@ -92,21 +118,35 @@ impl<C: ChainSpecParser> EnvironmentArgs<C> {
         }
 
         info!(target: "reth::cli", ?db_path, ?sf_path, "Opening storage");
+        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())?),
-                StaticFileProvider::read_write(sf_path)?,
-            ),
-            AccessRights::RO => (
-                Arc::new(open_db_read_only(&db_path, self.db.database_args())?),
-                StaticFileProvider::read_only(sf_path, false)?,
+                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())?), {
+                    let provider = StaticFileProviderBuilder::read_only(sf_path)
+                        .with_genesis_block_number(genesis_block_number)
+                        .build()?;
+                    provider.watch_directory();
+                    provider
+                })
+            }
         };
+        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)?;
+        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(&provider_factory)?;
+            init_genesis_with_settings(&provider_factory, self.storage_settings())?;
         }
 
         Ok(Environment { config, provider_factory, data_dir })
@@ -122,23 +162,25 @@ impl<C: ChainSpecParser> EnvironmentArgs<C> {
         config: &Config,
         db: Arc<DatabaseEnv>,
         static_file_provider: StaticFileProvider<N::Primitives>,
+        rocksdb_provider: RocksDBProvider,
+        access: AccessRights,
     ) -> eyre::Result<ProviderFactory<NodeTypesWithDBAdapter<N, Arc<DatabaseEnv>>>>
     where
         C: ChainSpecParser<ChainSpec = N::ChainSpec>,
     {
-        let has_receipt_pruning = config.prune.has_receipts_pruning();
         let prune_modes = config.prune.segments.clone();
         let factory = ProviderFactory::<NodeTypesWithDBAdapter<N, Arc<DatabaseEnv>>>::new(
             db,
             self.chain.clone(),
             static_file_provider,
-        )
+            rocksdb_provider,
+        )?
         .with_prune_modes(prune_modes.clone());
 
         // Check for consistency between database and static files.
-        if let Some(unwind_target) = factory
-            .static_file_provider()
-            .check_consistency(&factory.provider()?, has_receipt_pruning)?
+        if !access.is_read_only_inconsistent() &&
+            let Some(unwind_target) =
+                factory.static_file_provider().check_consistency(&factory.provider()?)?
         {
             if factory.db_ref().is_read_only()? {
                 warn!(target: "reth::cli", ?unwind_target, "Inconsistent storage. Restart node to heal.");
@@ -199,6 +241,8 @@ pub enum AccessRights {
     RW,
     /// Read-only access
     RO,
+    /// Read-only access with possibly inconsistent data
+    RoInconsistent,
 }
 
 impl AccessRights {
@@ -206,6 +250,12 @@ impl AccessRights {
     pub const fn is_read_write(&self) -> bool {
         matches!(self, Self::RW)
     }
+
+    /// Returns `true` if it requires read-only access to the environment with possibly inconsistent
+    /// data.
+    pub const fn is_read_only_inconsistent(&self) -> bool {
+        matches!(self, Self::RoInconsistent)
+    }
 }
 
 /// Helper alias to satisfy `FullNodeTypes` bound on [`Node`] trait generic.
@@ -215,17 +265,6 @@ type FullTypesAdapter<T> = FullNodeTypesAdapter<
     BlockchainProvider<NodeTypesWithDBAdapter<T, Arc<DatabaseEnv>>>,
 >;
 
-/// Trait for block headers that can be modified through CLI operations.
-pub trait CliHeader {
-    fn set_number(&mut self, number: u64);
-}
-
-impl CliHeader for alloy_consensus::Header {
-    fn set_number(&mut self, number: u64) {
-        self.number = number;
-    }
-}
-
 /// Helper trait with a common set of requirements for the
 /// [`NodeTypes`] in CLI.
 pub trait CliNodeTypes: Node<FullTypesAdapter<Self>> + NodeTypesForProvider {

crates/cli/commands/src/config_cmd.rs

@@ -22,13 +22,14 @@ impl Command {
         let config = if self.default {
             Config::default()
         } else {
-            let path = self.config.clone().unwrap_or_default();
-            // Check if the file exists
+            let path = match self.config.as_ref() {
+                Some(path) => path,
+                None => bail!("No config file provided. Use --config <FILE> or pass --default"),
+            };
             if !path.exists() {
                 bail!("Config file does not exist: {}", path.display());
             }
-            // Read the configuration file
-            Config::from_path(&path)
+            Config::from_path(path)
                 .wrap_err_with(|| format!("Could not load config file: {}", path.display()))?
         };
         println!("{}", toml::to_string_pretty(&config)?);

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

@@ -0,0 +1,92 @@
+use alloy_primitives::{keccak256, Address};
+use clap::Parser;
+use human_bytes::human_bytes;
+use reth_codecs::Compact;
+use reth_db_api::{cursor::DbDupCursorRO, database::Database, tables, transaction::DbTx};
+use reth_db_common::DbTool;
+use reth_node_builder::NodeTypesWithDB;
+use std::time::{Duration, Instant};
+use tracing::info;
+
+/// Log progress every 5 seconds
+const LOG_INTERVAL: Duration = Duration::from_secs(5);
+
+/// The arguments for the `reth db account-storage` command
+#[derive(Parser, Debug)]
+pub struct Command {
+    /// The account address to check storage for
+    address: Address,
+}
+
+impl Command {
+    /// Execute `db account-storage` command
+    pub fn execute<N: NodeTypesWithDB>(self, tool: &DbTool<N>) -> eyre::Result<()> {
+        let address = self.address;
+        let (slot_count, plain_size) = tool.provider_factory.db_ref().view(|tx| {
+            let mut cursor = tx.cursor_dup_read::<tables::PlainStorageState>()?;
+            let mut count = 0usize;
+            let mut total_value_bytes = 0usize;
+            let mut last_log = Instant::now();
+
+            // Walk all storage entries for this address
+            let walker = cursor.walk_dup(Some(address), None)?;
+            for entry in walker {
+                let (_, storage_entry) = entry?;
+                count += 1;
+                // StorageEntry encodes as: 32 bytes (key/subkey uncompressed) + compressed U256
+                let mut buf = Vec::new();
+                let entry_len = storage_entry.to_compact(&mut buf);
+                total_value_bytes += entry_len;
+
+                if last_log.elapsed() >= LOG_INTERVAL {
+                    info!(
+                        target: "reth::cli",
+                        address = %address,
+                        slots = count,
+                        key = %storage_entry.key,
+                        "Processing storage slots"
+                    );
+                    last_log = Instant::now();
+                }
+            }
+
+            // Add 20 bytes for the Address key (stored once per account in dupsort)
+            let total_size = if count > 0 { 20 + total_value_bytes } else { 0 };
+
+            Ok::<_, eyre::Report>((count, total_size))
+        })??;
+
+        // Estimate hashed storage size: 32-byte B256 key instead of 20-byte Address
+        let hashed_size_estimate = if slot_count > 0 { plain_size + 12 } else { 0 };
+        let total_estimate = plain_size + hashed_size_estimate;
+
+        let hashed_address = keccak256(address);
+
+        println!("Account: {address}");
+        println!("Hashed address: {hashed_address}");
+        println!("Storage slots: {slot_count}");
+        println!("Plain storage size: {} (estimated)", human_bytes(plain_size as f64));
+        println!("Hashed storage size: {} (estimated)", human_bytes(hashed_size_estimate as f64));
+        println!("Total estimated size: {}", human_bytes(total_estimate as f64));
+
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_address_arg() {
+        let cmd = Command::try_parse_from([
+            "account-storage",
+            "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+        ])
+        .unwrap();
+        assert_eq!(
+            cmd.address,
+            "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045".parse::<Address>().unwrap()
+        );
+    }
+}

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,288 @@
+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},
+    sync::Arc,
+    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, Arc<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, Arc<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, sync::Arc, 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, Arc<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/clear.rs

@@ -6,8 +6,9 @@ use reth_db_api::{
     transaction::{DbTx, DbTxMut},
     TableViewer, Tables,
 };
+use reth_db_common::DbTool;
 use reth_node_builder::NodeTypesWithDB;
-use reth_provider::{ProviderFactory, StaticFileProviderFactory};
+use reth_provider::StaticFileProviderFactory;
 use reth_static_file_types::StaticFileSegment;
 
 /// The arguments for the `reth db clear` command
@@ -19,19 +20,16 @@ pub struct Command {
 
 impl Command {
     /// Execute `db clear` command
-    pub fn execute<N: NodeTypesWithDB>(
-        self,
-        provider_factory: ProviderFactory<N>,
-    ) -> eyre::Result<()> {
+    pub fn execute<N: NodeTypesWithDB>(self, tool: &DbTool<N>) -> eyre::Result<()> {
         match self.subcommand {
             Subcommands::Mdbx { table } => {
-                table.view(&ClearViewer { db: provider_factory.db_ref() })?
+                table.view(&ClearViewer { db: tool.provider_factory.db_ref() })?
             }
             Subcommands::StaticFile { segment } => {
-                let static_file_provider = provider_factory.static_file_provider();
+                let static_file_provider = tool.provider_factory.static_file_provider();
                 let static_files = iter_static_files(static_file_provider.directory())?;
 
-                if let Some(segment_static_files) = static_files.get(&segment) {
+                if let Some(segment_static_files) = static_files.get(segment) {
                     for (block_range, _) in segment_static_files {
                         static_file_provider.delete_jar(segment, block_range.start())?;
                     }

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

@@ -2,19 +2,26 @@ use alloy_primitives::{hex, BlockHash};
 use clap::Parser;
 use reth_db::{
     static_file::{
-        ColumnSelectorOne, ColumnSelectorTwo, HeaderWithHashMask, ReceiptMask, TransactionMask,
+        AccountChangesetMask, ColumnSelectorOne, ColumnSelectorTwo, HeaderWithHashMask,
+        ReceiptMask, TransactionMask, TransactionSenderMask,
     },
     RawDupSort,
 };
 use reth_db_api::{
-    table::{Decompress, DupSort, Table},
-    tables, RawKey, RawTable, Receipts, TableViewer, Transactions,
+    cursor::{DbCursorRO, DbDupCursorRO},
+    database::Database,
+    table::{Compress, Decompress, DupSort, Table},
+    tables,
+    transaction::DbTx,
+    RawKey, RawTable, Receipts, TableViewer, Transactions,
 };
 use reth_db_common::DbTool;
 use reth_node_api::{HeaderTy, ReceiptTy, TxTy};
 use reth_node_builder::NodeTypesWithDB;
-use reth_provider::{providers::ProviderNodeTypes, StaticFileProviderFactory};
+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
@@ -38,6 +45,14 @@ enum Subcommand {
         #[arg(value_parser = maybe_json_value_parser)]
         subkey: Option<String>,
 
+        /// Optional end key for range query (exclusive upper bound)
+        #[arg(value_parser = maybe_json_value_parser)]
+        end_key: Option<String>,
+
+        /// Optional end subkey for range query (exclusive upper bound)
+        #[arg(value_parser = maybe_json_value_parser)]
+        end_subkey: Option<String>,
+
         /// Output bytes instead of human-readable decoded value
         #[arg(long)]
         raw: bool,
@@ -50,6 +65,10 @@ enum Subcommand {
         #[arg(value_parser = maybe_json_value_parser)]
         key: String,
 
+        /// The subkey to get content for, for example address in changeset
+        #[arg(value_parser = maybe_json_value_parser)]
+        subkey: Option<String>,
+
         /// Output bytes instead of human-readable decoded value
         #[arg(long)]
         raw: bool,
@@ -60,23 +79,99 @@ impl Command {
     /// Execute `db get` command
     pub fn execute<N: ProviderNodeTypes>(self, tool: &DbTool<N>) -> eyre::Result<()> {
         match self.subcommand {
-            Subcommand::Mdbx { table, key, subkey, raw } => {
-                table.view(&GetValueViewer { tool, key, subkey, raw })?
+            Subcommand::Mdbx { table, key, subkey, end_key, end_subkey, raw } => {
+                table.view(&GetValueViewer { tool, key, subkey, end_key, end_subkey, raw })?
             }
-            Subcommand::StaticFile { segment, key, raw } => {
-                let (key, mask): (u64, _) = match segment {
+            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)?,
+                        None,
                         <HeaderWithHashMask<HeaderTy<N>>>::MASK,
                     ),
-                    StaticFileSegment::Transactions => {
-                        (table_key::<tables::Transactions>(&key)?, <TransactionMask<TxTy<N>>>::MASK)
+                    StaticFileSegment::Transactions => (
+                        table_key::<tables::Transactions>(&key)?,
+                        None,
+                        <TransactionMask<TxTy<N>>>::MASK,
+                    ),
+                    StaticFileSegment::Receipts => (
+                        table_key::<tables::Receipts>(&key)?,
+                        None,
+                        <ReceiptMask<ReceiptTy<N>>>::MASK,
+                    ),
+                    StaticFileSegment::TransactionSenders => (
+                        table_key::<tables::TransactionSenders>(&key)?,
+                        None,
+                        TransactionSenderMask::MASK,
+                    ),
+                    StaticFileSegment::AccountChangeSets => {
+                        let subkey =
+                            table_subkey::<tables::AccountChangeSets>(subkey.as_deref()).ok();
+                        (
+                            table_key::<tables::AccountChangeSets>(&key)?,
+                            subkey,
+                            AccountChangesetMask::MASK,
+                        )
                     }
-                    StaticFileSegment::Receipts => {
-                        (table_key::<tables::Receipts>(&key)?, <ReceiptMask<ReceiptTy<N>>>::MASK)
+                    StaticFileSegment::StorageChangeSets => {
+                        unreachable!("storage changesets handled above");
                     }
                 };
 
+                // handle account changesets differently if a subkey is provided.
+                if let StaticFileSegment::AccountChangeSets = segment {
+                    let Some(subkey) = subkey else {
+                        // get all changesets for the block
+                        let changesets = tool
+                            .provider_factory
+                            .static_file_provider()
+                            .account_block_changeset(key)?;
+
+                        println!("{}", serde_json::to_string_pretty(&changesets)?);
+                        return Ok(())
+                    };
+
+                    let account = tool
+                        .provider_factory
+                        .static_file_provider()
+                        .get_account_before_block(key, subkey)?;
+
+                    if let Some(account) = account {
+                        println!("{}", serde_json::to_string_pretty(&account)?);
+                    } else {
+                        error!(target: "reth::cli", "No content for the given table key.");
+                    }
+
+                    return Ok(())
+                }
+
                 let content = tool.provider_factory.static_file_provider().find_static_file(
                     segment,
                     |provider| {
@@ -116,6 +211,19 @@ impl Command {
                                     )?;
                                     println!("{}", serde_json::to_string_pretty(&receipt)?);
                                 }
+                                StaticFileSegment::TransactionSenders => {
+                                    let sender =
+                                        <<tables::TransactionSenders as Table>::Value>::decompress(
+                                            content[0].as_slice(),
+                                        )?;
+                                    println!("{}", serde_json::to_string_pretty(&sender)?);
+                                }
+                                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")
+                                }
                             }
                         }
                     }
@@ -144,6 +252,8 @@ struct GetValueViewer<'a, N: NodeTypesWithDB> {
     tool: &'a DbTool<N>,
     key: String,
     subkey: Option<String>,
+    end_key: Option<String>,
+    end_subkey: Option<String>,
     raw: bool,
 }
 
@@ -153,53 +263,158 @@ impl<N: ProviderNodeTypes> TableViewer<()> for GetValueViewer<'_, N> {
     fn view<T: Table>(&self) -> Result<(), Self::Error> {
         let key = table_key::<T>(&self.key)?;
 
-        let content = if self.raw {
-            self.tool
-                .get::<RawTable<T>>(RawKey::from(key))?
-                .map(|content| hex::encode_prefixed(content.raw_value()))
-        } else {
-            self.tool.get::<T>(key)?.as_ref().map(serde_json::to_string_pretty).transpose()?
-        };
+        // A non-dupsort table cannot have subkeys. The `subkey` arg becomes the `end_key`. First we
+        // check that `end_key` and `end_subkey` weren't previously given, as that wouldn't be
+        // valid.
+        if self.end_key.is_some() || self.end_subkey.is_some() {
+            return Err(eyre::eyre!("Only END_KEY can be given for non-DUPSORT tables"));
+        }
 
-        match content {
-            Some(content) => {
-                println!("{content}");
-            }
-            None => {
-                error!(target: "reth::cli", "No content for the given table key.");
-            }
-        };
+        let end_key = self.subkey.clone();
+
+        // Check if we're doing a range query
+        if let Some(ref end_key_str) = end_key {
+            let end_key = table_key::<T>(end_key_str)?;
+
+            // Use walk_range to iterate over the range
+            self.tool.provider_factory.db_ref().view(|tx| {
+                let mut cursor = tx.cursor_read::<T>()?;
+                let walker = cursor.walk_range(key..end_key)?;
+
+                for result in walker {
+                    let (k, v) = result?;
+                    let json_val = if self.raw {
+                        let raw_key = RawKey::from(k);
+                        serde_json::json!({
+                            "key": hex::encode_prefixed(raw_key.raw_key()),
+                            "val": hex::encode_prefixed(v.compress().as_ref()),
+                        })
+                    } else {
+                        serde_json::json!({
+                            "key": &k,
+                            "val": &v,
+                        })
+                    };
+
+                    println!("{}", serde_json::to_string_pretty(&json_val)?);
+                }
+
+                Ok::<_, eyre::Report>(())
+            })??;
+        } else {
+            // Single key lookup
+            let content = if self.raw {
+                self.tool
+                    .get::<RawTable<T>>(RawKey::from(key))?
+                    .map(|content| hex::encode_prefixed(content.raw_value()))
+            } else {
+                self.tool.get::<T>(key)?.as_ref().map(serde_json::to_string_pretty).transpose()?
+            };
+
+            match content {
+                Some(content) => {
+                    println!("{content}");
+                }
+                None => {
+                    error!(target: "reth::cli", "No content for the given table key.");
+                }
+            };
+        }
 
         Ok(())
     }
 
-    fn view_dupsort<T: DupSort>(&self) -> Result<(), Self::Error> {
+    fn view_dupsort<T: DupSort>(&self) -> Result<(), Self::Error>
+    where
+        T::Value: reth_primitives_traits::ValueWithSubKey<SubKey = T::SubKey>,
+    {
         // get a key for given table
         let key = table_key::<T>(&self.key)?;
 
-        // process dupsort table
-        let subkey = table_subkey::<T>(self.subkey.as_deref())?;
-
-        let content = if self.raw {
-            self.tool
-                .get_dup::<RawDupSort<T>>(RawKey::from(key), RawKey::from(subkey))?
-                .map(|content| hex::encode_prefixed(content.raw_value()))
-        } else {
-            self.tool
-                .get_dup::<T>(key, subkey)?
+        // Check if we're doing a range query
+        if let Some(ref end_key_str) = self.end_key {
+            let end_key = table_key::<T>(end_key_str)?;
+            let start_subkey = table_subkey::<T>(Some(
+                self.subkey.as_ref().expect("must have been given if end_key is given").as_str(),
+            ))?;
+            let end_subkey_parsed = self
+                .end_subkey
                 .as_ref()
-                .map(serde_json::to_string_pretty)
-                .transpose()?
-        };
+                .map(|s| table_subkey::<T>(Some(s.as_str())))
+                .transpose()?;
 
-        match content {
-            Some(content) => {
-                println!("{content}");
-            }
-            None => {
-                error!(target: "reth::cli", "No content for the given table subkey.");
-            }
-        };
+            self.tool.provider_factory.db_ref().view(|tx| {
+                let mut cursor = tx.cursor_dup_read::<T>()?;
+
+                // Seek to the starting key. If there is actually a key at the starting key then
+                // seek to the subkey within it.
+                if let Some((decoded_key, _)) = cursor.seek(key.clone())? &&
+                    decoded_key == key
+                {
+                    cursor.seek_by_key_subkey(key.clone(), start_subkey.clone())?;
+                }
+
+                // Get the current position to start iteration
+                let mut current = cursor.current()?;
+
+                while let Some((decoded_key, decoded_value)) = current {
+                    // Extract the subkey using the ValueWithSubKey trait
+                    let decoded_subkey = decoded_value.get_subkey();
+
+                    // Check if we've reached the end (exclusive)
+                    if (&decoded_key, Some(&decoded_subkey)) >=
+                        (&end_key, end_subkey_parsed.as_ref())
+                    {
+                        break;
+                    }
+
+                    // Output the entry with both key and subkey
+                    let json_val = if self.raw {
+                        let raw_key = RawKey::from(decoded_key.clone());
+                        serde_json::json!({
+                            "key": hex::encode_prefixed(raw_key.raw_key()),
+                            "val": hex::encode_prefixed(decoded_value.compress().as_ref()),
+                        })
+                    } else {
+                        serde_json::json!({
+                            "key": &decoded_key,
+                            "val": &decoded_value,
+                        })
+                    };
+
+                    println!("{}", serde_json::to_string_pretty(&json_val)?);
+
+                    // Move to next entry
+                    current = cursor.next()?;
+                }
+
+                Ok::<_, eyre::Report>(())
+            })??;
+        } else {
+            // Single key/subkey lookup
+            let subkey = table_subkey::<T>(self.subkey.as_deref())?;
+
+            let content = if self.raw {
+                self.tool
+                    .get_dup::<RawDupSort<T>>(RawKey::from(key), RawKey::from(subkey))?
+                    .map(|content| hex::encode_prefixed(content.raw_value()))
+            } else {
+                self.tool
+                    .get_dup::<T>(key, subkey)?
+                    .as_ref()
+                    .map(serde_json::to_string_pretty)
+                    .transpose()?
+            };
+
+            match content {
+                Some(content) => {
+                    println!("{content}");
+                }
+                None => {
+                    error!(target: "reth::cli", "No content for the given table subkey.");
+                }
+            };
+        }
         Ok(())
     }
 }

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

@@ -3,7 +3,7 @@ use alloy_primitives::hex;
 use clap::Parser;
 use eyre::WrapErr;
 use reth_chainspec::EthereumHardforks;
-use reth_db::DatabaseEnv;
+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};
@@ -61,19 +61,21 @@ impl Command {
     }
 
     /// 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,7 +84,7 @@ impl Command {
             min_value_size: self.min_value_size,
             reverse: self.reverse,
             only_count: self.count,
-        }
+        })
     }
 }
 
@@ -96,8 +98,11 @@ impl<N: NodeTypes> TableViewer<()> for ListTableViewer<'_, N> {
 
     fn view<T: Table>(&self) -> Result<(), Self::Error> {
         self.tool.provider_factory.db_ref().view(|tx| {
+            // 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).wrap_err(format!("Could not find table: {}", self.args.table.name()))?;
+            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 {
@@ -112,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

@@ -2,18 +2,22 @@ use crate::common::{AccessRights, CliNodeTypes, Environment, EnvironmentArgs};
 use clap::{Parser, Subcommand};
 use reth_chainspec::{EthChainSpec, EthereumHardforks};
 use reth_cli::chainspec::ChainSpecParser;
+use reth_cli_runner::CliContext;
 use reth_db::version::{get_db_version, DatabaseVersionError, DB_VERSION};
 use reth_db_common::DbTool;
 use std::{
     io::{self, Write},
     sync::Arc,
 };
+mod account_storage;
 mod checksum;
 mod clear;
 mod diff;
 mod get;
 mod list;
 mod repair_trie;
+mod settings;
+mod static_file_header;
 mod stats;
 /// DB List TUI
 mod tui;
@@ -35,7 +39,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),
@@ -51,16 +55,23 @@ pub enum Subcommands {
     Clear(clear::Command),
     /// Verifies trie consistency and outputs any inconsistencies
     RepairTrie(repair_trie::Command),
+    /// Reads and displays the static file segment header
+    StaticFileHeader(static_file_header::Command),
     /// Lists current and local database versions
     Version,
     /// Returns the full database path
     Path,
+    /// Manage storage settings
+    Settings(settings::Command),
+    /// Gets storage size information for an account
+    AccountStorage(account_storage::Command),
 }
 
-/// `db_ro_exec` opens a database in read-only mode, and then execute with the provided command
-macro_rules! db_ro_exec {
-    ($env:expr, $tool:ident, $N:ident, $command:block) => {
-        let Environment { provider_factory, .. } = $env.init::<$N>(AccessRights::RO)?;
+/// Initializes a provider factory with specified access rights, and then execute with the provided
+/// command
+macro_rules! db_exec {
+    ($env:expr, $tool:ident, $N:ident, $access_rights:expr, $command:block) => {
+        let Environment { provider_factory, .. } = $env.init::<$N>($access_rights)?;
 
         let $tool = DbTool::new(provider_factory)?;
         $command;
@@ -69,7 +80,10 @@ macro_rules! db_ro_exec {
 
 impl<C: ChainSpecParser<ChainSpec: EthChainSpec + EthereumHardforks>> Command<C> {
     /// Execute `db` 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 data_dir = self.env.datadir.clone().resolve_datadir(self.env.chain.chain());
         let db_path = data_dir.db();
         let static_files_path = data_dir.static_files();
@@ -88,27 +102,32 @@ impl<C: ChainSpecParser<ChainSpec: EthChainSpec + EthereumHardforks>> Command<C>
         match self.command {
             // TODO: We'll need to add this on the DB trait.
             Subcommands::Stats(command) => {
-                db_ro_exec!(self.env, tool, N, {
+                let access_rights = if command.skip_consistency_checks {
+                    AccessRights::RoInconsistent
+                } else {
+                    AccessRights::RO
+                };
+                db_exec!(self.env, tool, N, access_rights, {
                     command.execute(data_dir, &tool)?;
                 });
             }
             Subcommands::List(command) => {
-                db_ro_exec!(self.env, tool, N, {
+                db_exec!(self.env, tool, N, AccessRights::RO, {
                     command.execute(&tool)?;
                 });
             }
             Subcommands::Checksum(command) => {
-                db_ro_exec!(self.env, tool, N, {
+                db_exec!(self.env, tool, N, AccessRights::RO, {
                     command.execute(&tool)?;
                 });
             }
             Subcommands::Diff(command) => {
-                db_ro_exec!(self.env, tool, N, {
+                db_exec!(self.env, tool, N, AccessRights::RO, {
                     command.execute(&tool)?;
                 });
             }
             Subcommands::Get(command) => {
-                db_ro_exec!(self.env, tool, N, {
+                db_exec!(self.env, tool, N, AccessRights::RO, {
                     command.execute(&tool)?;
                 });
             }
@@ -130,19 +149,26 @@ impl<C: ChainSpecParser<ChainSpec: EthChainSpec + EthereumHardforks>> Command<C>
                     }
                 }
 
-                let Environment { provider_factory, .. } = self.env.init::<N>(AccessRights::RW)?;
-                let tool = DbTool::new(provider_factory)?;
-                tool.drop(db_path, static_files_path, exex_wal_path)?;
+                db_exec!(self.env, tool, N, AccessRights::RW, {
+                    tool.drop(db_path, static_files_path, exex_wal_path)?;
+                });
             }
             Subcommands::Clear(command) => {
-                let Environment { provider_factory, .. } = self.env.init::<N>(AccessRights::RW)?;
-                command.execute(provider_factory)?;
+                db_exec!(self.env, tool, N, AccessRights::RW, {
+                    command.execute(&tool)?;
+                });
             }
             Subcommands::RepairTrie(command) => {
                 let access_rights =
                     if command.dry_run { AccessRights::RO } else { AccessRights::RW };
-                let Environment { provider_factory, .. } = self.env.init::<N>(access_rights)?;
-                command.execute(provider_factory)?;
+                db_exec!(self.env, tool, N, access_rights, {
+                    command.execute(&tool, ctx.task_executor, &data_dir)?;
+                });
+            }
+            Subcommands::StaticFileHeader(command) => {
+                db_exec!(self.env, tool, N, AccessRights::RoInconsistent, {
+                    command.execute(&tool)?;
+                });
             }
             Subcommands::Version => {
                 let local_db_version = match get_db_version(&db_path) {
@@ -162,6 +188,16 @@ impl<C: ChainSpecParser<ChainSpec: EthChainSpec + EthereumHardforks>> Command<C>
             Subcommands::Path => {
                 println!("{}", db_path.display());
             }
+            Subcommands::Settings(command) => {
+                db_exec!(self.env, tool, N, command.access_rights(), {
+                    command.execute(&tool)?;
+                });
+            }
+            Subcommands::AccountStorage(command) => {
+                db_exec!(self.env, tool, N, AccessRights::RO, {
+                    command.execute(&tool)?;
+                });
+            }
         }
 
         Ok(())

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

@@ -1,20 +1,37 @@
 use clap::Parser;
+use metrics::{self, Counter};
+use reth_chainspec::EthChainSpec;
+use reth_cli_util::parse_socket_address;
 use reth_db_api::{
     cursor::{DbCursorRO, DbCursorRW, DbDupCursorRO},
     database::Database,
     tables,
     transaction::{DbTx, DbTxMut},
 };
-use reth_node_builder::NodeTypesWithDB;
-use reth_provider::{providers::ProviderNodeTypes, ProviderFactory, StageCheckpointReader};
+use reth_db_common::DbTool;
+use reth_node_core::{
+    dirs::{ChainPath, DataDirPath},
+    version::version_metadata,
+};
+use reth_node_metrics::{
+    chain::ChainSpecInfo,
+    hooks::Hooks,
+    server::{MetricServer, MetricServerConfig},
+    version::VersionInfo,
+};
+use reth_provider::{providers::ProviderNodeTypes, ChainSpecProvider, StageCheckpointReader};
 use reth_stages::StageId;
+use reth_tasks::TaskExecutor;
 use reth_trie::{
     verify::{Output, Verifier},
     Nibbles,
 };
 use reth_trie_common::{StorageTrieEntry, StoredNibbles, StoredNibblesSubKey};
 use reth_trie_db::{DatabaseHashedCursorFactory, DatabaseTrieCursorFactory};
-use std::time::{Duration, Instant};
+use std::{
+    net::SocketAddr,
+    time::{Duration, Instant},
+};
 use tracing::{info, warn};
 
 const PROGRESS_PERIOD: Duration = Duration::from_secs(5);
@@ -25,27 +42,77 @@ pub struct Command {
     /// Only show inconsistencies without making any repairs
     #[arg(long)]
     pub(crate) dry_run: bool,
+
+    /// Enable Prometheus metrics.
+    ///
+    /// The metrics will be served at the given interface and port.
+    #[arg(long = "metrics", value_name = "ADDR:PORT", value_parser = parse_socket_address)]
+    pub(crate) metrics: Option<SocketAddr>,
 }
 
 impl Command {
     /// Execute `db repair-trie` command
     pub fn execute<N: ProviderNodeTypes>(
         self,
-        provider_factory: ProviderFactory<N>,
+        tool: &DbTool<N>,
+        task_executor: TaskExecutor,
+        data_dir: &ChainPath<DataDirPath>,
     ) -> eyre::Result<()> {
-        if self.dry_run {
-            verify_only(provider_factory)?
+        // Set up metrics server if requested
+        let _metrics_handle = if let Some(listen_addr) = self.metrics {
+            let chain_name = tool.provider_factory.chain_spec().chain().to_string();
+            let executor = task_executor.clone();
+            let pprof_dump_dir = data_dir.pprof_dumps();
+
+            let handle = task_executor.spawn_critical("metrics server", async move {
+                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: chain_name },
+                    executor,
+                    Hooks::builder().build(),
+                    pprof_dump_dir,
+                );
+
+                // Spawn the metrics server
+                if let Err(e) = MetricServer::new(config).serve().await {
+                    tracing::error!("Metrics server error: {}", e);
+                }
+            });
+
+            Some(handle)
         } else {
-            verify_and_repair(provider_factory)?
+            None
+        };
+
+        if self.dry_run {
+            verify_only(tool)?
+        } else {
+            verify_and_repair(tool)?
         }
 
         Ok(())
     }
 }
 
-fn verify_only<N: NodeTypesWithDB>(provider_factory: ProviderFactory<N>) -> eyre::Result<()> {
+fn verify_only<N: ProviderNodeTypes>(tool: &DbTool<N>) -> eyre::Result<()> {
+    // Log the database block tip from Finish stage checkpoint
+    let finish_checkpoint = tool
+        .provider_factory
+        .provider()?
+        .get_stage_checkpoint(StageId::Finish)?
+        .unwrap_or_default();
+    info!("Database block tip: {}", finish_checkpoint.block_number);
+
     // Get a database transaction directly from the database
-    let db = provider_factory.db_ref();
+    let db = tool.provider_factory.db_ref();
     let mut tx = db.tx()?;
     tx.disable_long_read_transaction_safety();
 
@@ -54,6 +121,8 @@ fn verify_only<N: NodeTypesWithDB>(provider_factory: ProviderFactory<N>) -> eyre
     let trie_cursor_factory = DatabaseTrieCursorFactory::new(&tx);
     let verifier = Verifier::new(&trie_cursor_factory, hashed_cursor_factory)?;
 
+    let metrics = RepairTrieMetrics::new();
+
     let mut inconsistent_nodes = 0;
     let start_time = Instant::now();
     let mut last_progress_time = Instant::now();
@@ -70,6 +139,21 @@ fn verify_only<N: NodeTypesWithDB>(provider_factory: ProviderFactory<N>) -> eyre
         } else {
             warn!("Inconsistency found: {output:?}");
             inconsistent_nodes += 1;
+
+            // Record metrics based on output type
+            match output {
+                Output::AccountExtra(_, _) |
+                Output::AccountWrong { .. } |
+                Output::AccountMissing(_, _) => {
+                    metrics.account_inconsistencies.increment(1);
+                }
+                Output::StorageExtra(_, _, _) |
+                Output::StorageWrong { .. } |
+                Output::StorageMissing(_, _, _) => {
+                    metrics.storage_inconsistencies.increment(1);
+                }
+                Output::Progress(_) => unreachable!(),
+            }
         }
     }
 
@@ -114,11 +198,13 @@ fn verify_checkpoints(provider: impl StageCheckpointReader) -> eyre::Result<()>
     Ok(())
 }
 
-fn verify_and_repair<N: ProviderNodeTypes>(
-    provider_factory: ProviderFactory<N>,
-) -> eyre::Result<()> {
+fn verify_and_repair<N: ProviderNodeTypes>(tool: &DbTool<N>) -> eyre::Result<()> {
     // Get a read-write database provider
-    let mut provider_rw = provider_factory.provider_rw()?;
+    let mut provider_rw = tool.provider_factory.provider_rw()?;
+
+    // Log the database block tip from Finish stage checkpoint
+    let finish_checkpoint = provider_rw.get_stage_checkpoint(StageId::Finish)?.unwrap_or_default();
+    info!("Database block tip: {}", finish_checkpoint.block_number);
 
     // Check that a pipeline sync isn't in progress.
     verify_checkpoints(provider_rw.as_ref())?;
@@ -138,6 +224,8 @@ fn verify_and_repair<N: ProviderNodeTypes>(
     // Create the verifier
     let verifier = Verifier::new(&trie_cursor_factory, hashed_cursor_factory)?;
 
+    let metrics = RepairTrieMetrics::new();
+
     let mut inconsistent_nodes = 0;
     let start_time = Instant::now();
     let mut last_progress_time = Instant::now();
@@ -149,6 +237,21 @@ fn verify_and_repair<N: ProviderNodeTypes>(
         if !matches!(output, Output::Progress(_)) {
             warn!("Inconsistency found, will repair: {output:?}");
             inconsistent_nodes += 1;
+
+            // Record metrics based on output type
+            match &output {
+                Output::AccountExtra(_, _) |
+                Output::AccountWrong { .. } |
+                Output::AccountMissing(_, _) => {
+                    metrics.account_inconsistencies.increment(1);
+                }
+                Output::StorageExtra(_, _, _) |
+                Output::StorageWrong { .. } |
+                Output::StorageMissing(_, _, _) => {
+                    metrics.storage_inconsistencies.increment(1);
+                }
+                Output::Progress(_) => {}
+            }
         }
 
         match output {
@@ -204,8 +307,8 @@ fn verify_and_repair<N: ProviderNodeTypes>(
     if inconsistent_nodes == 0 {
         info!("No inconsistencies found");
     } else {
-        info!("Repaired {} inconsistencies, committing changes", inconsistent_nodes);
         provider_rw.commit()?;
+        info!("Repaired {} inconsistencies and committed changes", inconsistent_nodes);
     }
 
     Ok(())
@@ -247,3 +350,25 @@ fn output_progress(last_account: Nibbles, start_time: Instant, inconsistent_node
         "Repairing trie tables",
     );
 }
+
+/// Metrics for tracking trie repair inconsistencies
+#[derive(Debug)]
+struct RepairTrieMetrics {
+    account_inconsistencies: Counter,
+    storage_inconsistencies: Counter,
+}
+
+impl RepairTrieMetrics {
+    fn new() -> Self {
+        Self {
+            account_inconsistencies: metrics::counter!(
+                "db.repair_trie.inconsistencies_found",
+                "type" => "account"
+            ),
+            storage_inconsistencies: metrics::counter!(
+                "db.repair_trie.inconsistencies_found",
+                "type" => "storage"
+            ),
+        }
+    }
+}