fix(db-common): compute state root when initializing from genesis (#17731)

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Claude <assistant@anthropic.com>

.github/CODEOWNERS

@@ -1,19 +1,19 @@
 *                           @gakonst
 bin/                        @onbjerg
-crates/blockchain-tree/     @rakita @rkrasiuk @mattsse @Rjected
 crates/blockchain-tree-api/ @rakita @rkrasiuk @mattsse @Rjected
-crates/chainspec/           @Rjected @joshieDo @mattsse
+crates/blockchain-tree/     @rakita @rkrasiuk @mattsse @Rjected
 crates/chain-state/         @fgimenez @mattsse @rkrasiuk
+crates/chainspec/           @Rjected @joshieDo @mattsse
 crates/cli/                 @onbjerg @mattsse
 crates/config/              @onbjerg
 crates/consensus/           @rkrasiuk @mattsse @Rjected
-crates/engine               @rkrasiuk @mattsse @Rjected
 crates/e2e-test-utils/      @mattsse @Rjected
+crates/engine               @rkrasiuk @mattsse @Rjected
 crates/engine/              @rkrasiuk @mattsse @Rjected @fgimenez
+crates/era/                 @mattsse @RomanHodulak
 crates/errors/              @mattsse
-crates/era/                 @mattsse
-crates/ethereum/            @mattsse @Rjected
 crates/ethereum-forks/      @mattsse @Rjected
+crates/ethereum/            @mattsse @Rjected
 crates/etl/                 @joshieDo @shekhirin
 crates/evm/                 @rakita @mattsse @Rjected
 crates/exex/                @onbjerg @shekhirin
@@ -24,17 +24,18 @@ crates/net/downloaders/     @onbjerg @rkrasiuk
 crates/node/                @mattsse @Rjected @onbjerg @klkvr
 crates/optimism/            @mattsse @Rjected @fgimenez
 crates/payload/             @mattsse @Rjected
+crates/primitives-traits/   @Rjected @RomanHodulak @mattsse @klkvr
 crates/primitives/          @Rjected @mattsse @klkvr
-crates/primitives-traits/   @Rjected @joshieDo @mattsse @klkvr
 crates/prune/               @shekhirin @joshieDo
+crates/ress                 @rkrasiuk
 crates/revm/                @mattsse @rakita
-crates/rpc/                 @mattsse @Rjected
+crates/rpc/                 @mattsse @Rjected @RomanHodulak
 crates/stages/              @onbjerg @rkrasiuk @shekhirin
 crates/static-file/         @joshieDo @shekhirin
 crates/storage/codecs/      @joshieDo
-crates/storage/db/          @joshieDo @rakita
 crates/storage/db-api/      @joshieDo @rakita
 crates/storage/db-common/   @Rjected @onbjerg
+crates/storage/db/          @joshieDo @rakita
 crates/storage/errors/      @rakita @onbjerg
 crates/storage/libmdbx-rs/  @rakita @shekhirin
 crates/storage/nippy-jar/   @joshieDo @shekhirin
@@ -44,7 +45,6 @@ crates/tasks/               @mattsse
 crates/tokio-util/          @fgimenez
 crates/tracing/             @onbjerg
 crates/transaction-pool/    @mattsse
-crates/trie/                @rkrasiuk @Rjected @shekhirin
-crates/ress                 @rkrasiuk
+crates/trie/                @rkrasiuk @Rjected @shekhirin @mediocregopher
 etc/                        @Rjected @onbjerg @shekhirin
 .github/                    @onbjerg @gakonst @DaniPopes

.github/assets/check_wasm.sh

@@ -58,6 +58,7 @@ exclude_crates=(
   reth-ress-provider
   # The following are not supposed to be working
   reth # all of the crates below
+  reth-alloy-provider
   reth-invalid-block-hooks # reth-provider
   reth-libmdbx # mdbx
   reth-mdbx-sys # mdbx
@@ -69,10 +70,12 @@ exclude_crates=(
   reth-transaction-pool # c-kzg
   reth-payload-util # reth-transaction-pool
   reth-trie-parallel # tokio
+  reth-trie-sparse-parallel # rayon
   reth-testing-utils
   reth-optimism-txpool # reth-transaction-pool
   reth-era-downloader # tokio
   reth-era-utils # tokio
+  reth-tracing-otlp
 )
 
 # Array to hold the results

.github/assets/hive/expected_failures.yaml

@@ -16,6 +16,10 @@ rpc-compat:
   - eth_getTransactionReceipt/get-legacy-input (reth)
   - eth_getTransactionReceipt/get-legacy-receipt (reth)
 
+  # after https://github.com/paradigmxyz/reth/pull/16742 we start the node in
+  # syncing mode, the test expects syncing to be false on start
+  - eth_syncing/check-syncing (reth)
+
 # no fix due to https://github.com/paradigmxyz/reth/issues/8732
 engine-withdrawals:
   - Withdrawals Fork On Genesis (Paris) (reth)
@@ -36,7 +40,9 @@ engine-api: []
 # no fix due to https://github.com/paradigmxyz/reth/issues/8732
 engine-cancun:
   - Invalid PayloadAttributes, Missing BeaconRoot, Syncing=True (Cancun) (reth)
-  - Invalid NewPayload, ExcessBlobGas, Syncing=True, EmptyTxs=False, DynFeeTxs=False (Cancun) (reth)
+  # the test fails with older verions of the code for which it passed before, probably related to changes
+  # in hive or its dependencies
+  - Blob Transaction Ordering, Multiple Clients (Cancun) (reth)
 
 sync: []
 

.github/assets/kurtosis_op_network_params.yaml

@@ -4,7 +4,6 @@ ethereum_package:
       el_extra_params:
         - "--rpc.eth-proof-window=100"
       cl_type: teku
-      cl_image: "consensys/teku:25.4.0"
   network_params:
     preset: minimal
     genesis_delay: 5

.github/workflows/bench.yml

@@ -12,10 +12,6 @@ env:
   BASELINE: base
   SEED: reth
 
-concurrency:
-  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
-  cancel-in-progress: true
-
 name: bench
 jobs:
   codspeed:

.github/workflows/book.yml

@@ -7,115 +7,45 @@ on:
     branches: [main]
   pull_request:
     branches: [main]
+    types: [opened, reopened, synchronize, closed]
   merge_group:
 
 jobs:
-  test:
-    runs-on: ubuntu-latest
-    name: test
-    timeout-minutes: 60
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install mdbook
-        run: |
-          mkdir mdbook
-          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.14/mdbook-v0.4.14-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
-          echo $(pwd)/mdbook >> $GITHUB_PATH
-
-      - name: Install mdbook-template
-        run: |
-          mkdir mdbook-template
-          curl -sSL https://github.com/sgoudham/mdbook-template/releases/latest/download/mdbook-template-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook-template
-          echo $(pwd)/mdbook-template >> $GITHUB_PATH
-
-      - name: Run tests
-        run: mdbook test
-
-  lint:
-    runs-on: ubuntu-latest
-    name: lint
-    timeout-minutes: 60
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install mdbook-linkcheck
-        run: |
-          mkdir mdbook-linkcheck
-          curl -sSL -o mdbook-linkcheck.zip https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases/latest/download/mdbook-linkcheck.x86_64-unknown-linux-gnu.zip
-          unzip mdbook-linkcheck.zip -d ./mdbook-linkcheck
-          chmod +x $(pwd)/mdbook-linkcheck/mdbook-linkcheck
-          echo $(pwd)/mdbook-linkcheck >> $GITHUB_PATH
-
-      - name: Run linkcheck
-        run: mdbook-linkcheck --standalone
-
   build:
     runs-on: ubuntu-latest
     timeout-minutes: 60
     steps:
-      - uses: actions/checkout@v4
-      - uses: rui314/setup-mold@v1
-      - uses: dtolnay/rust-toolchain@nightly
-      - name: Install mdbook
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install Playwright browsers
+        # Required for rehype-mermaid to render Mermaid diagrams during build
         run: |
-          mkdir mdbook
-          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.14/mdbook-v0.4.14-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
-          echo $(pwd)/mdbook >> $GITHUB_PATH
+          cd book/vocs/
+          bun i
+          npx playwright install --with-deps chromium
 
-      - name: Install mdbook-template
+      - name: Build Vocs
         run: |
-          mkdir mdbook-template
-          curl -sSL https://github.com/sgoudham/mdbook-template/releases/latest/download/mdbook-template-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook-template
-          echo $(pwd)/mdbook-template >> $GITHUB_PATH
+          cd book/vocs/ && bun run build
+          echo "Vocs Build Complete"
 
-      - uses: Swatinem/rust-cache@v2
-        with:
-          cache-on-failure: true
-
-      - name: Build book
-        run: mdbook build
-
-      - name: Build docs
-        run: cargo docs --exclude "example-*"
-        env:
-          # Keep in sync with ./ci.yml:jobs.docs
-          RUSTDOCFLAGS: --cfg docsrs --show-type-layout --generate-link-to-definition --enable-index-page -Zunstable-options
-
-      - name: Move docs to book folder
-        run: |
-          mv target/doc target/book/docs
-
-      - name: Archive artifact
-        shell: sh
-        run: |
-          chmod -c -R +rX "target/book" |
-          while read line; do
-             echo "::warning title=Invalid file permissions automatically fixed::$line"
-          done
-          tar \
-            --dereference --hard-dereference \
-            --directory "target/book" \
-            -cvf "$RUNNER_TEMP/artifact.tar" \
-            --exclude=.git \
-            --exclude=.github \
-            .
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
 
       - name: Upload artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-pages-artifact@v3
         with:
-          name: github-pages
-          path: ${{ runner.temp }}/artifact.tar
-          retention-days: 1
-          if-no-files-found: error
+          path: "./book/vocs/docs/dist"
 
   deploy:
     # Only deploy if a push to main
     if: github.ref_name == 'main' && github.event_name == 'push'
     runs-on: ubuntu-latest
-    needs: [test, lint, build]
+    needs: [build]
 
     # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
     permissions:

.github/workflows/build-release-binaries.yml

@@ -1,57 +0,0 @@
-name: build release binaries
-
-on:
-  workflow_dispatch:
-
-env:
-  CARGO_TERM_COLOR: always
-
-jobs:
-  build:
-    name: build release
-    runs-on: ${{ matrix.configs.os }}
-    strategy:
-      matrix:
-        configs:
-          - target: x86_64-unknown-linux-gnu
-            os: ubuntu-24.04
-            profile: maxperf
-          - target: aarch64-unknown-linux-gnu
-            os: ubuntu-24.04
-            profile: maxperf
-          - target: x86_64-apple-darwin
-            os: macos-13
-            profile: maxperf
-          - target: aarch64-apple-darwin
-            os: macos-14
-            profile: maxperf
-          - target: x86_64-pc-windows-gnu
-            os: ubuntu-24.04
-            profile: maxperf
-        build:
-          - command: build
-            binary: reth
-          - command: op-build
-            binary: op-reth
-    steps:
-      - uses: actions/checkout@v4
-      - uses: rui314/setup-mold@v1
-      - uses: dtolnay/rust-toolchain@stable
-        with:
-          target: ${{ matrix.configs.target }}
-      - name: Install cross main
-        id: cross_main
-        run: |
-          cargo install cross --git https://github.com/cross-rs/cross
-      - uses: Swatinem/rust-cache@v2
-        with:
-          cache-on-failure: true
-
-      - name: Apple M1 setup
-        if: matrix.configs.target == 'aarch64-apple-darwin'
-        run: |
-          echo "SDKROOT=$(xcrun -sdk macosx --show-sdk-path)" >> $GITHUB_ENV
-          echo "MACOSX_DEPLOYMENT_TARGET=$(xcrun -sdk macosx --show-sdk-platform-version)" >> $GITHUB_ENV
-
-      - name: Build Reth
-        run: make PROFILE=${{ matrix.configs.profile }} ${{ matrix.build.command }}-${{ matrix.configs.target }}

.github/workflows/docker.yml

@@ -8,7 +8,6 @@ on:
       - v*
 
 env:
-  REPO_NAME: ${{ github.repository_owner }}/reth
   IMAGE_NAME: ${{ github.repository_owner }}/reth
   OP_IMAGE_NAME: ${{ github.repository_owner }}/op-reth
   CARGO_TERM_COLOR: always
@@ -17,8 +16,9 @@ env:
   DOCKER_USERNAME: ${{ github.actor }}
 
 jobs:
-  build:
-    name: build and push
+  build-rc:
+    if: contains(github.ref, '-rc')
+    name: build and push as release candidate
     runs-on: ubuntu-24.04
     permissions:
       packages: write
@@ -27,14 +27,46 @@ jobs:
       fail-fast: false
       matrix:
         build:
-          - name: 'Build and push reth image'
-            command: 'make PROFILE=maxperf docker-build-push'
-          - name: 'Build and push reth image, tag as "latest"'
-            command: 'make PROFILE=maxperf docker-build-push-latest'
-          - name: 'Build and push op-reth image'
-            command: 'make IMAGE_NAME=$OP_IMAGE_NAME DOCKER_IMAGE_NAME=$OP_DOCKER_IMAGE_NAME PROFILE=maxperf op-docker-build-push'
-          - name: 'Build and push op-reth image, tag as "latest"'
-            command: 'make IMAGE_NAME=$OP_IMAGE_NAME DOCKER_IMAGE_NAME=$OP_DOCKER_IMAGE_NAME PROFILE=maxperf op-docker-build-push-latest'
+          - name: "Build and push reth image"
+            command: "make IMAGE_NAME=$IMAGE_NAME DOCKER_IMAGE_NAME=$DOCKER_IMAGE_NAME PROFILE=maxperf docker-build-push"
+          - name: "Build and push op-reth image"
+            command: "make IMAGE_NAME=$OP_IMAGE_NAME DOCKER_IMAGE_NAME=$OP_DOCKER_IMAGE_NAME PROFILE=maxperf op-docker-build-push"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: rui314/setup-mold@v1
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-on-failure: true
+      - name: Install cross main
+        id: cross_main
+        run: |
+          cargo install cross --git https://github.com/cross-rs/cross
+      - name: Log in to Docker
+        run: |
+          echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io --username ${DOCKER_USERNAME} --password-stdin
+      - name: Set up Docker builder
+        run: |
+          docker run --privileged --rm tonistiigi/binfmt --install arm64,amd64
+          docker buildx create --use --name cross-builder
+      - name: Build and push ${{ matrix.build.name }}
+        run: ${{ matrix.build.command }}
+
+  build:
+    if: ${{ !contains(github.ref, '-rc') }}
+    name: build and push as latest
+    runs-on: ubuntu-24.04
+    permissions:
+      packages: write
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        build:
+          - name: "Build and push reth image"
+            command: "make IMAGE_NAME=$IMAGE_NAME DOCKER_IMAGE_NAME=$DOCKER_IMAGE_NAME PROFILE=maxperf docker-build-push-latest"
+          - name: "Build and push op-reth image"
+            command: "make IMAGE_NAME=$OP_IMAGE_NAME DOCKER_IMAGE_NAME=$OP_DOCKER_IMAGE_NAME PROFILE=maxperf op-docker-build-push-latest"
     steps:
       - uses: actions/checkout@v4
       - uses: rui314/setup-mold@v1

.github/workflows/hive.yml

@@ -5,8 +5,7 @@ name: hive
 on:
   workflow_dispatch:
   schedule:
-    # run every 12 hours
-    - cron: "0 */12 * * *"
+    - cron: "0 */6 * * *"
 
 env:
   CARGO_TERM_COLOR: always
@@ -33,7 +32,8 @@ jobs:
         uses: actions/checkout@v4
         with:
           repository: ethereum/hive
-          ref: master
+          # TODO: unpin when https://github.com/ethereum/hive/issues/1306 is fixed
+          ref: edd9969338dd1798ba2e61f049c7e3a15cef53e6
           path: hivetests
 
       - uses: actions/setup-go@v5

.github/workflows/integration.yml

@@ -8,8 +8,8 @@ on:
   push:
     branches: [main]
   schedule:
-  # Run once a day at 3:00 UTC
-  - cron: '0 3 * * *'
+    # Run once a day at 3:00 UTC
+    - cron: "0 3 * * *"
 
 env:
   CARGO_TERM_COLOR: always
@@ -66,17 +66,17 @@ jobs:
         with:
           jobs: ${{ toJSON(needs) }}
 
-  era-files: 
+  era-files:
     name: era1 file integration tests once a day
     if: github.event_name == 'schedule'
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
-    - uses: rui314/setup-mold@v1
-    - uses: dtolnay/rust-toolchain@stable
-    - uses: taiki-e/install-action@nextest
-    - 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
+      - uses: actions/checkout@v4
+      - uses: rui314/setup-mold@v1
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: taiki-e/install-action@nextest
+      - 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

.github/workflows/kurtosis-op.yml

@@ -5,7 +5,7 @@ name: kurtosis-op
 on:
   workflow_dispatch:
   schedule:
-    - cron: "0 */12 * * *"
+    - cron: "0 */6 * * *"
 
   push:
     tags:
@@ -62,7 +62,9 @@ jobs:
           sudo apt update
           sudo apt install kurtosis-cli
           kurtosis engine start
-          kurtosis run --enclave op-devnet github.com/ethpandaops/optimism-package --args-file .github/assets/kurtosis_op_network_params.yaml
+          # TODO: unpin optimism-package when https://github.com/ethpandaops/optimism-package/issues/340 is fixed
+          # kurtosis run --enclave op-devnet github.com/ethpandaops/optimism-package --args-file .github/assets/kurtosis_op_network_params.yaml
+          kurtosis run --enclave op-devnet github.com/ethpandaops/optimism-package@452133367b693e3ba22214a6615c86c60a1efd5e --args-file .github/assets/kurtosis_op_network_params.yaml
           ENCLAVE_ID=$(curl http://127.0.0.1:9779/api/enclaves | jq --raw-output 'keys[0]')
           GETH_PORT=$(curl "http://127.0.0.1:9779/api/enclaves/$ENCLAVE_ID/services" | jq '."op-el-2151908-1-op-geth-op-node-op-kurtosis".public_ports.rpc.number')
           RETH_PORT=$(curl "http://127.0.0.1:9779/api/enclaves/$ENCLAVE_ID/services" | jq '."op-el-2151908-2-op-reth-op-node-op-kurtosis".public_ports.rpc.number')

.github/workflows/kurtosis.yml

@@ -5,7 +5,7 @@ name: kurtosis
 on:
   workflow_dispatch:
   schedule:
-    - cron: "0 */12 * * *"
+    - cron: "0 */6 * * *"
 
   push:
     tags:

.github/workflows/lint.yml

@@ -20,9 +20,6 @@ jobs:
           - type: ethereum
             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"
-          - type: book
-            args: --manifest-path book/sources/Cargo.toml --workspace --bins
-            features: ""
     steps:
       - uses: actions/checkout@v4
       - uses: rui314/setup-mold@v1
@@ -158,8 +155,6 @@ jobs:
           components: rustfmt
       - name: Run fmt
         run: cargo fmt --all --check
-      - name: Run fmt on book sources
-        run: cargo fmt --manifest-path book/sources/Cargo.toml --all --check
 
   udeps:
     name: udeps
@@ -209,7 +204,7 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
       - name: Run dprint
-        uses: dprint/check@v2.2
+        uses: dprint/check@v2.3
         with:
           config-path: dprint.json
 

.github/workflows/pr-title.yml

@@ -30,6 +30,7 @@ jobs:
             fix
             chore
             test
+            bench
             perf
             refactor
             docs
@@ -55,23 +56,24 @@ jobs:
             - `fix`: Patches a bug
             - `chore`: General maintenance tasks or updates
             - `test`: Adding new tests or modifying existing tests
+            - `bench`: Adding new benchmarks or modifying existing benchmarks
             - `perf`: Performance improvements
             - `refactor`: Changes to improve code structure
             - `docs`: Documentation updates
             - `ci`: Changes to CI/CD configurations
             - `revert`: Reverts a previously merged PR
             - `deps`: Updates dependencies
-            
+
             **Breaking Changes**
 
             Breaking changes are noted by using an exclamation mark. For example:
             - `feat!: changed the API`
             - `chore(node)!: Removed unused public function`
-            
+
             **Help**
 
             For more information, follow the guidelines here: https://www.conventionalcommits.org/en/v1.0.0/
-      
+
       - name: Remove Comment for Valid Title
         if: steps.lint_pr_title.outcome == 'success'
         uses: marocchino/sticky-pull-request-comment@v2

.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@v4
+        uses: dawidd6/action-homebrew-bump-formula@v5
         with:
           token: ${{ secrets.HOMEBREW }}
           no_fork: true

.github/workflows/release.yml

@@ -12,7 +12,7 @@ on:
       dry_run:
         description: "Enable dry run mode (builds artifacts but skips uploads and release creation)"
         type: boolean
-        default: true
+        default: false
 
 env:
   REPO_NAME: ${{ github.repository_owner }}/reth
@@ -24,6 +24,15 @@ env:
   DOCKER_OP_IMAGE_NAME_URL: ghcr.io/${{ github.repository_owner }}/op-reth
 
 jobs:
+  dry-run:
+    name: check dry run
+    runs-on: ubuntu-latest
+    steps:
+      - run: |
+          echo "Dry run value: ${{ github.event.inputs.dry_run }}"
+          echo "Dry run enabled: ${{ github.event.inputs.dry_run == 'true'}}"
+          echo "Dry run disabled: ${{ github.event.inputs.dry_run != 'true'}}"
+
   extract-version:
     name: extract version
     runs-on: ubuntu-latest
@@ -34,28 +43,56 @@ jobs:
     outputs:
       VERSION: ${{ steps.extract_version.outputs.VERSION }}
 
+  check-version:
+    name: check version
+    runs-on: ubuntu-latest
+    needs: extract-version
+    if: ${{ github.event.inputs.dry_run != 'true' }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - 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
+        run: |
+          tag="${{ needs.extract-version.outputs.VERSION }}"
+          tag=${tag#v}
+          cargo_ver=$(cargo metadata --no-deps --format-version 1 | jq -r '.packages[0].version')
+          [[ "$tag" == "$cargo_ver"* ]] || { echo "Tag $tag doesn’t match the Cargo version $cargo_ver"; exit 1; }
+
   build:
     name: build release
     runs-on: ${{ matrix.configs.os }}
     needs: extract-version
+    continue-on-error: ${{ matrix.configs.allow_fail }}
     strategy:
+      fail-fast: true
       matrix:
         configs:
           - target: x86_64-unknown-linux-gnu
             os: ubuntu-24.04
             profile: maxperf
+            allow_fail: false
           - target: aarch64-unknown-linux-gnu
             os: ubuntu-24.04
             profile: maxperf
+            allow_fail: false
           - target: x86_64-apple-darwin
             os: macos-13
             profile: maxperf
+            allow_fail: false
           - target: aarch64-apple-darwin
             os: macos-14
             profile: maxperf
+            allow_fail: false
           - target: x86_64-pc-windows-gnu
             os: ubuntu-24.04
             profile: maxperf
+            allow_fail: false
+          - target: riscv64gc-unknown-linux-gnu
+            os: ubuntu-24.04
+            profile: maxperf
+            allow_fail: true
         build:
           - command: build
             binary: reth
@@ -103,14 +140,14 @@ jobs:
         shell: bash
 
       - name: Upload artifact
-        if: ${{ github.event.inputs.dry_run == 'false' }}
+        if: ${{ github.event.inputs.dry_run != 'true' }}
         uses: actions/upload-artifact@v4
         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 == 'false' }}
+        if: ${{ github.event.inputs.dry_run != 'true' }}
         uses: actions/upload-artifact@v4
         with:
           name: ${{ matrix.build.binary }}-${{ needs.extract-version.outputs.VERSION }}-${{ matrix.configs.target }}.tar.gz.asc
@@ -118,9 +155,9 @@ jobs:
 
   draft-release:
     name: draft release
-    needs: [build, extract-version]
     runs-on: ubuntu-latest
-    if: ${{ github.event.inputs.dry_run == 'false' }}
+    needs: [build, extract-version]
+    if: ${{ github.event.inputs.dry_run != 'true' }}
     env:
       VERSION: ${{ needs.extract-version.outputs.VERSION }}
     permissions:
@@ -134,6 +171,12 @@ jobs:
           fetch-depth: 0
       - name: Download artifacts
         uses: actions/download-artifact@v4
+      - name: Generate full changelog
+        id: changelog
+        run: |
+          echo "CHANGELOG<<EOF" >> $GITHUB_OUTPUT
+          echo "$(git log --pretty=format:"- %s" $(git describe --tags --abbrev=0 ${{ env.VERSION }}^)..${{ env.VERSION }})" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
       - name: Create release draft
         env:
           GITHUB_USER: ${{ github.repository_owner }}
@@ -141,6 +184,11 @@ jobs:
         # The formatting here is borrowed from Lighthouse (which is borrowed from OpenEthereum):
         # https://github.com/openethereum/openethereum/blob/6c2d392d867b058ff867c4373e40850ca3f96969/.github/workflows/build.yml
         run: |
+          prerelease_flag=""
+          if [[ "${GITHUB_REF}" == *-rc* ]]; then
+            prerelease_flag="--prerelease"
+          fi
+
           body=$(cat <<- "ENDBODY"
           ![image](https://raw.githubusercontent.com/paradigmxyz/reth/main/assets/reth-prod.png)
 
@@ -177,6 +225,10 @@ jobs:
 
           *See [Update Priorities](https://paradigmxyz.github.io/reth/installation/priorities.html) for more information about this table.*
 
+          ## All Changes
+
+          ${{ steps.changelog.outputs.CHANGELOG }}
+
           ## Binaries
 
           [See pre-built binaries documentation.](https://paradigmxyz.github.io/reth/installation/binaries.html)
@@ -187,23 +239,23 @@ jobs:
 
           | System | Architecture | Binary | PGP Signature |
           |:---:|:---:|:---:|:---|
-          | <img src="https://www.svgrepo.com/download/473700/linux.svg" style="width: 32px;"/> | x86_64 | [reth-${{ env.VERSION }}-x86_64-unknown-linux-gnu.tar.gz](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/reth-${{ env.VERSION }}-x86_64-unknown-linux-gnu.tar.gz) | [PGP Signature](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/reth-${{ env.VERSION }}-x86_64-unknown-linux-gnu.tar.gz.asc) |
-          | <img src="https://www.svgrepo.com/download/473700/linux.svg" style="width: 32px;"/> | aarch64 | [reth-${{ env.VERSION }}-aarch64-unknown-linux-gnu.tar.gz](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/reth-${{ env.VERSION }}-aarch64-unknown-linux-gnu.tar.gz) | [PGP Signature](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/reth-${{ env.VERSION }}-aarch64-unknown-linux-gnu.tar.gz.asc) |
-          | <img src="https://www.svgrepo.com/download/513083/windows-174.svg" style="width: 32px;"/> | x86_64 | [reth-${{ env.VERSION }}-x86_64-pc-windows-gnu.tar.gz](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/reth-${{ env.VERSION }}-x86_64-pc-windows-gnu.tar.gz) | [PGP Signature](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/reth-${{ env.VERSION }}-x86_64-pc-windows-gnu.tar.gz.asc) |
-          | <img src="https://www.svgrepo.com/download/511330/apple-173.svg" style="width: 32px;"/> | x86_64 | [reth-${{ env.VERSION }}-x86_64-apple-darwin.tar.gz](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/reth-${{ env.VERSION }}-x86_64-apple-darwin.tar.gz) | [PGP Signature](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/reth-${{ env.VERSION }}-x86_64-apple-darwin.tar.gz.asc) |
-          | <img src="https://www.svgrepo.com/download/511330/apple-173.svg" style="width: 32px;"/> | aarch64 | [reth-${{ env.VERSION }}-aarch64-apple-darwin.tar.gz](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/reth-${{ env.VERSION }}-aarch64-apple-darwin.tar.gz) | [PGP Signature](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/reth-${{ env.VERSION }}-aarch64-apple-darwin.tar.gz.asc) |
-          | <img src="https://www.svgrepo.com/download/473589/docker.svg" style="width: 32px;"/> | Docker | [${{ env.IMAGE_NAME }}](${{ env.DOCKER_IMAGE_NAME_URL }}) | - |
+          | <img src="https://www.svgrepo.com/download/473700/linux.svg" width="50"/> | x86_64 | [reth-${{ env.VERSION }}-x86_64-unknown-linux-gnu.tar.gz](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/reth-${{ env.VERSION }}-x86_64-unknown-linux-gnu.tar.gz) | [PGP Signature](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/reth-${{ env.VERSION }}-x86_64-unknown-linux-gnu.tar.gz.asc) |
+          | <img src="https://www.svgrepo.com/download/473700/linux.svg" width="50"/> | aarch64 | [reth-${{ env.VERSION }}-aarch64-unknown-linux-gnu.tar.gz](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/reth-${{ env.VERSION }}-aarch64-unknown-linux-gnu.tar.gz) | [PGP Signature](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/reth-${{ env.VERSION }}-aarch64-unknown-linux-gnu.tar.gz.asc) |
+          | <img src="https://www.svgrepo.com/download/513083/windows-174.svg" width="50"/> | x86_64 | [reth-${{ env.VERSION }}-x86_64-pc-windows-gnu.tar.gz](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/reth-${{ env.VERSION }}-x86_64-pc-windows-gnu.tar.gz) | [PGP Signature](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/reth-${{ env.VERSION }}-x86_64-pc-windows-gnu.tar.gz.asc) |
+          | <img src="https://www.svgrepo.com/download/511330/apple-173.svg" width="50"/> | x86_64 | [reth-${{ env.VERSION }}-x86_64-apple-darwin.tar.gz](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/reth-${{ env.VERSION }}-x86_64-apple-darwin.tar.gz) | [PGP Signature](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/reth-${{ env.VERSION }}-x86_64-apple-darwin.tar.gz.asc) |
+          | <img src="https://www.svgrepo.com/download/511330/apple-173.svg" width="50"/> | aarch64 | [reth-${{ env.VERSION }}-aarch64-apple-darwin.tar.gz](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/reth-${{ env.VERSION }}-aarch64-apple-darwin.tar.gz) | [PGP Signature](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/reth-${{ env.VERSION }}-aarch64-apple-darwin.tar.gz.asc) |
+          | <img src="https://www.svgrepo.com/download/473589/docker.svg" width="50"/> | Docker | [${{ env.IMAGE_NAME }}](${{ env.DOCKER_IMAGE_NAME_URL }}) | - |
 
           ### OP-Reth
 
           | System | Architecture | Binary | PGP Signature |
           |:---:|:---:|:---:|:---|
-          | <img src="https://www.svgrepo.com/download/473700/linux.svg" style="width: 32px;"/> | x86_64 | [op-reth-${{ env.VERSION }}-x86_64-unknown-linux-gnu.tar.gz](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/op-reth-${{ env.VERSION }}-x86_64-unknown-linux-gnu.tar.gz) | [PGP Signature](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/op-reth-${{ env.VERSION }}-x86_64-unknown-linux-gnu.tar.gz.asc) |
-          | <img src="https://www.svgrepo.com/download/473700/linux.svg" style="width: 32px;"/> | aarch64 | [op-reth-${{ env.VERSION }}-aarch64-unknown-linux-gnu.tar.gz](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/op-reth-${{ env.VERSION }}-aarch64-unknown-linux-gnu.tar.gz) | [PGP Signature](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/op-reth-${{ env.VERSION }}-aarch64-unknown-linux-gnu.tar.gz.asc) |
-          | <img src="https://www.svgrepo.com/download/513083/windows-174.svg" style="width: 32px;"/> | x86_64 | [op-reth-${{ env.VERSION }}-x86_64-pc-windows-gnu.tar.gz](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/op-reth-${{ env.VERSION }}-x86_64-pc-windows-gnu.tar.gz) | [PGP Signature](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/op-reth-${{ env.VERSION }}-x86_64-pc-windows-gnu.tar.gz.asc) |
-          | <img src="https://www.svgrepo.com/download/511330/apple-173.svg" style="width: 32px;"/> | x86_64 | [op-reth-${{ env.VERSION }}-x86_64-apple-darwin.tar.gz](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/op-reth-${{ env.VERSION }}-x86_64-apple-darwin.tar.gz) | [PGP Signature](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/op-reth-${{ env.VERSION }}-x86_64-apple-darwin.tar.gz.asc) |
-          | <img src="https://www.svgrepo.com/download/511330/apple-173.svg" style="width: 32px;"/> | aarch64 | [op-reth-${{ env.VERSION }}-aarch64-apple-darwin.tar.gz](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/op-reth-${{ env.VERSION }}-aarch64-apple-darwin.tar.gz) | [PGP Signature](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/op-reth-${{ env.VERSION }}-aarch64-apple-darwin.tar.gz.asc) |
-          | <img src="https://www.svgrepo.com/download/473589/docker.svg" style="width: 32px;"/> | Docker | [${{ env.OP_IMAGE_NAME }}](${{ env.DOCKER_OP_IMAGE_NAME_URL }}) | - |
+          | <img src="https://www.svgrepo.com/download/473700/linux.svg" width="50"/> | x86_64 | [op-reth-${{ env.VERSION }}-x86_64-unknown-linux-gnu.tar.gz](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/op-reth-${{ env.VERSION }}-x86_64-unknown-linux-gnu.tar.gz) | [PGP Signature](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/op-reth-${{ env.VERSION }}-x86_64-unknown-linux-gnu.tar.gz.asc) |
+          | <img src="https://www.svgrepo.com/download/473700/linux.svg" width="50"/> | aarch64 | [op-reth-${{ env.VERSION }}-aarch64-unknown-linux-gnu.tar.gz](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/op-reth-${{ env.VERSION }}-aarch64-unknown-linux-gnu.tar.gz) | [PGP Signature](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/op-reth-${{ env.VERSION }}-aarch64-unknown-linux-gnu.tar.gz.asc) |
+          | <img src="https://www.svgrepo.com/download/513083/windows-174.svg" width="50"/> | x86_64 | [op-reth-${{ env.VERSION }}-x86_64-pc-windows-gnu.tar.gz](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/op-reth-${{ env.VERSION }}-x86_64-pc-windows-gnu.tar.gz) | [PGP Signature](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/op-reth-${{ env.VERSION }}-x86_64-pc-windows-gnu.tar.gz.asc) |
+          | <img src="https://www.svgrepo.com/download/511330/apple-173.svg" width="50"/> | x86_64 | [op-reth-${{ env.VERSION }}-x86_64-apple-darwin.tar.gz](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/op-reth-${{ env.VERSION }}-x86_64-apple-darwin.tar.gz) | [PGP Signature](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/op-reth-${{ env.VERSION }}-x86_64-apple-darwin.tar.gz.asc) |
+          | <img src="https://www.svgrepo.com/download/511330/apple-173.svg" width="50"/> | aarch64 | [op-reth-${{ env.VERSION }}-aarch64-apple-darwin.tar.gz](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/op-reth-${{ env.VERSION }}-aarch64-apple-darwin.tar.gz) | [PGP Signature](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/op-reth-${{ env.VERSION }}-aarch64-apple-darwin.tar.gz.asc) |
+          | <img src="https://www.svgrepo.com/download/473589/docker.svg" width="50"/> | Docker | [${{ env.OP_IMAGE_NAME }}](${{ env.DOCKER_OP_IMAGE_NAME_URL }}) | - |
           ENDBODY
           )
           assets=()
@@ -211,12 +263,12 @@ jobs:
               assets+=("$asset/$asset")
           done
           tag_name="${{ env.VERSION }}"
-          echo "$body" | gh release create --draft -t "Reth $tag_name" -F "-" "$tag_name" "${assets[@]}"
+          echo "$body" | gh release create --draft $prerelease_flag -t "Reth $tag_name" -F "-" "$tag_name" "${assets[@]}"
 
   dry-run-summary:
     name: dry run summary
-    needs: [build, extract-version]
     runs-on: ubuntu-latest
+    needs: [build, extract-version]
     if: ${{ github.event.inputs.dry_run == 'true' }}
     env:
       VERSION: ${{ needs.extract-version.outputs.VERSION }}

.github/workflows/sync-era.yml

@@ -0,0 +1,67 @@
+# Runs sync tests with ERA stage enabled.
+
+name: sync-era test
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 */6 * * *"
+
+env:
+  CARGO_TERM_COLOR: always
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  sync:
+    name: sync (${{ matrix.chain.bin }})
+    runs-on:
+      group: Reth
+    env:
+      RUST_LOG: info,sync=error
+      RUST_BACKTRACE: 1
+    timeout-minutes: 60
+    strategy:
+      matrix:
+        chain:
+          - build: install
+            bin: reth
+            chain: mainnet
+            tip: "0x91c90676cab257a59cd956d7cb0bceb9b1a71d79755c23c7277a0697ccfaf8c4"
+            block: 100000
+            unwind-target: "0x52e0509d33a988ef807058e2980099ee3070187f7333aae12b64d4d675f34c5a"
+          - build: install-op
+            bin: op-reth
+            chain: base
+            tip: "0xbb9b85352c7ebca6ba8efc63bd66cecd038c92ec8ebd02e153a3e0b197e672b7"
+            block: 10000
+            unwind-target: "0x118a6e922a8c6cab221fc5adfe5056d2b72d58c6580e9c5629de55299e2cf8de"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: rui314/setup-mold@v1
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-on-failure: true
+      - name: Build ${{ matrix.chain.bin }}
+        run: make ${{ matrix.chain.build }}
+      - name: Run sync with ERA enabled
+        run: |
+          ${{ matrix.chain.bin }} node \
+            --chain ${{ matrix.chain.chain }} \
+            --debug.tip ${{ matrix.chain.tip }} \
+            --debug.max-block ${{ matrix.chain.block }} \
+            --debug.terminate
+            --era.enable
+      - name: Verify the target block hash
+        run: |
+          ${{ matrix.chain.bin }} db --chain ${{ matrix.chain.chain }} get static-file headers ${{ matrix.chain.block }} \
+            | grep ${{ matrix.chain.tip }}
+      - name: Run stage unwind for 100 blocks
+        run: |
+          ${{ 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 }} 

.github/workflows/sync.yml

@@ -3,7 +3,9 @@
 name: sync test
 
 on:
-  merge_group:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 */6 * * *"
 
 env:
   CARGO_TERM_COLOR: always

.github/workflows/unit.yml

@@ -42,10 +42,6 @@ jobs:
             args: --features "asm-keccak" --locked --exclude reth --exclude reth-bench --exclude "example-*" --exclude "reth-ethereum-*" --exclude "*-ethereum"
             partition: 2
             total_partitions: 2
-          - type: book
-            args: --manifest-path book/sources/Cargo.toml
-            partition: 1
-            total_partitions: 1
     timeout-minutes: 30
     steps:
       - uses: actions/checkout@v4

.gitignore

@@ -54,5 +54,8 @@ rustc-ice-*
 # Book sources should be able to build with the latest version
 book/sources/Cargo.lock
 
+# vocs node_modules
+book/vocs/node_modules
+
 # Cargo chef recipe file
 recipe.json

CLAUDE.md

@@ -0,0 +1,312 @@
+# Reth Development Guide for AI Agents
+
+This guide provides comprehensive instructions for AI agents working on the Reth codebase. It covers the architecture, development workflows, and critical guidelines for effective contributions.
+
+## Project Overview
+
+Reth is a high-performance Ethereum execution client written in Rust, focusing on modularity, performance, and contributor-friendliness. The codebase is organized into well-defined crates with clear boundaries and responsibilities.
+
+## Architecture Overview
+
+### Core Components
+
+1. **Consensus (`crates/consensus/`)**: Validates blocks according to Ethereum consensus rules
+2. **Storage (`crates/storage/`)**: Hybrid database using MDBX + static files for optimal performance
+3. **Networking (`crates/net/`)**: P2P networking stack with discovery, sync, and transaction propagation
+4. **RPC (`crates/rpc/`)**: JSON-RPC server supporting all standard Ethereum APIs
+5. **Execution (`crates/evm/`, `crates/ethereum/`)**: Transaction execution and state transitions
+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)
+
+### Key Design Principles
+
+- **Modularity**: Each crate can be used as a standalone library
+- **Performance**: Extensive use of parallelism, memory-mapped I/O, and optimized data structures
+- **Extensibility**: Traits and generic types allow for different implementations (Ethereum, Optimism, etc.)
+- **Type Safety**: Strong typing throughout with minimal use of dynamic dispatch
+
+## Development Workflow
+
+### Code Style and Standards
+
+1. **Formatting**: Always use nightly rustfmt
+   ```bash
+   cargo +nightly fmt --all
+   ```
+
+2. **Linting**: Run clippy with all features
+   ```bash
+   RUSTFLAGS="-D warnings" cargo +nightly clippy --workspace --lib --examples --tests --benches --all-features --locked
+   ```
+
+3. **Testing**: Use nextest for faster test execution
+   ```bash
+   cargo nextest run --workspace
+   ```
+
+### Common Contribution Types
+
+Based on actual recent PRs, here are typical contribution patterns:
+
+#### 1. Small Bug Fixes (1-10 lines)
+Real example: Fixing beacon block root handling ([#16767](https://github.com/paradigmxyz/reth/pull/16767))
+```rust
+// Changed a single line to fix logic error
+- parent_beacon_block_root: parent.parent_beacon_block_root(),
++ parent_beacon_block_root: parent.parent_beacon_block_root().map(|_| B256::ZERO),
+```
+
+#### 2. Integration with Upstream Changes
+Real example: Integrating revm updates ([#16752](https://github.com/paradigmxyz/reth/pull/16752))
+```rust
+// Update code to use new APIs from dependencies
+- if self.fork_tracker.is_shanghai_activated() {
+-     if let Err(err) = transaction.ensure_max_init_code_size(MAX_INIT_CODE_BYTE_SIZE) {
++ if let Some(init_code_size_limit) = self.fork_tracker.max_initcode_size() {
++     if let Err(err) = transaction.ensure_max_init_code_size(init_code_size_limit) {
+```
+
+#### 3. Adding Comprehensive Tests
+Real example: ETH69 protocol tests ([#16759](https://github.com/paradigmxyz/reth/pull/16759))
+```rust
+#[tokio::test(flavor = "multi_thread")]
+async fn test_eth69_peers_can_connect() {
+    // Create test network with specific protocol versions
+    let p0 = PeerConfig::with_protocols(NoopProvider::default(), Some(EthVersion::Eth69.into()));
+    // Test connection and version negotiation
+}
+```
+
+#### 4. Making Components Generic
+Real example: Making EthEvmConfig generic over chainspec ([#16758](https://github.com/paradigmxyz/reth/pull/16758))
+```rust
+// Before: Hardcoded to ChainSpec
+- pub struct EthEvmConfig<EvmFactory = EthEvmFactory> {
+-     pub executor_factory: EthBlockExecutorFactory<RethReceiptBuilder, Arc<ChainSpec>, EvmFactory>,
+
+// After: Generic over any chain spec type
++ pub struct EthEvmConfig<C = ChainSpec, EvmFactory = EthEvmFactory>
++ where
++     C: EthereumHardforks,
++ {
++     pub executor_factory: EthBlockExecutorFactory<RethReceiptBuilder, Arc<C>, EvmFactory>,
+```
+
+#### 5. Resource Management Improvements
+Real example: ETL directory cleanup ([#16770](https://github.com/paradigmxyz/reth/pull/16770))
+```rust
+// Add cleanup logic on startup
++ if let Err(err) = fs::remove_dir_all(&etl_path) {
++     warn!(target: "reth::cli", ?etl_path, %err, "Failed to remove ETL path on launch");
++ }
+```
+
+#### 6. Feature Additions
+Real example: Sharded mempool support ([#16756](https://github.com/paradigmxyz/reth/pull/16756))
+```rust
+// Add new filtering policies for transaction announcements
+pub struct ShardedMempoolAnnouncementFilter<T> {
+    pub inner: T,
+    pub shard_bits: u8,
+    pub node_id: Option<B256>,
+}
+```
+
+### Testing Guidelines
+
+1. **Unit Tests**: Test individual functions and components
+2. **Integration Tests**: Test interactions between components
+3. **Benchmarks**: For performance-critical code
+4. **Fuzz Tests**: For parsing and serialization code
+5. **Property Tests**: For checking component correctness on a wide variety of inputs
+
+Example test structure:
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+    
+    #[test]
+    fn test_component_behavior() {
+        // Arrange
+        let component = Component::new();
+        
+        // Act
+        let result = component.operation();
+        
+        // Assert
+        assert_eq!(result, expected);
+    }
+}
+```
+
+### Performance Considerations
+
+1. **Avoid Allocations in Hot Paths**: Use references and borrowing
+2. **Parallel Processing**: Use rayon for CPU-bound parallel work
+3. **Async/Await**: Use tokio for I/O-bound operations
+4. **File Operations**: Use `reth_fs_util` instead of `std::fs` for better error handling
+
+### Common Pitfalls
+
+1. **Don't Block Async Tasks**: Use `spawn_blocking` for CPU-intensive work or work with lots of blocking I/O
+2. **Handle Errors Properly**: Use `?` operator and proper error types
+
+### What to Avoid
+
+Based on PR patterns, avoid:
+
+1. **Large, sweeping changes**: Keep PRs focused and reviewable
+2. **Mixing unrelated changes**: One logical change per PR
+3. **Ignoring CI failures**: All checks must pass
+4. **Incomplete implementations**: Finish features before submitting
+
+### CI Requirements
+
+Before submitting changes, ensure:
+
+1. **Format Check**: `cargo +nightly fmt --all --check`
+2. **Clippy**: No warnings with `RUSTFLAGS="-D warnings"`
+3. **Tests Pass**: All unit and integration tests
+4. **Documentation**: Update relevant docs and add doc comments with `cargo docs --document-private-items`
+5. **Commit Messages**: Follow conventional format (feat:, fix:, chore:, etc.)
+
+
+### Opening PRs against <https://github.com/paradigmxyz/reth>
+
+Label PRs appropriately, first check the available labels and then apply the relevant ones:
+* when changes are RPC related, add A-rpc label
+* when changes are docs related, add C-docs label
+* when changes are optimism related (e.g. new feature or exclusive changes to crates/optimism), add A-op-reth label
+* ... and so on, check the available labels for more options.
+
+If changes in reth include changes to dependencies, run commands `zepter` and `make lint-toml` before finalizing the pr. Assume `zepter` binary is installed.
+
+### Debugging Tips
+
+1. **Logging**: Use `tracing` crate with appropriate levels
+   ```rust
+   tracing::debug!(target: "reth::component", ?value, "description");
+   ```
+
+2. **Metrics**: Add metrics for monitoring
+   ```rust
+   metrics::counter!("reth_component_operations").increment(1);
+   ```
+
+3. **Test Isolation**: Use separate test databases/directories
+
+### Finding Where to Contribute
+
+1. **Check Issues**: Look for issues labeled `good-first-issue` or `help-wanted`
+2. **Review TODOs**: Search for `TODO` comments in the codebase
+3. **Improve Tests**: Areas with low test coverage are good targets
+4. **Documentation**: Improve code comments and documentation
+5. **Performance**: Profile and optimize hot paths (with benchmarks)
+
+### Common PR Patterns
+
+#### Small, Focused Changes
+Most PRs change only 1-5 files. Examples:
+- Single-line bug fixes
+- Adding a missing trait implementation
+- Updating error messages
+- Adding test cases for edge conditions
+
+#### Integration Work
+When dependencies update (especially revm), code needs updating:
+- Check for breaking API changes
+- Update to use new features (like EIP implementations)
+- Ensure compatibility with new versions
+
+#### Test Improvements
+Tests often need expansion for:
+- New protocol versions (ETH68, ETH69)
+- Edge cases in state transitions
+- Network behavior under specific conditions
+- Concurrent operations
+
+#### Making Code More Generic
+Common refactoring pattern:
+- Replace concrete types with generics
+- Add trait bounds for flexibility
+- Enable reuse across different chain types (Ethereum, Optimism)
+
+### Example Contribution Workflow
+
+Let's say you want to fix a bug where external IP resolution fails on startup:
+
+1. **Create a branch**:
+   ```bash
+   git checkout -b fix-external-ip-resolution
+   ```
+
+2. **Find the relevant code**:
+   ```bash
+   # Search for IP resolution code
+   rg "external.*ip" --type rust
+   ```
+
+3. **Reason about the problem, when the problem is identified, make the fix**:
+   ```rust
+   // In crates/net/discv4/src/lib.rs
+   pub fn resolve_external_ip() -> Option<IpAddr> {
+       // Add fallback mechanism
+       nat::external_ip()
+           .or_else(|| nat::external_ip_from_stun())
+           .or_else(|| Some(DEFAULT_IP))
+   }
+   ```
+
+4. **Add a test**:
+   ```rust
+   #[test]
+   fn test_external_ip_fallback() {
+       // Test that resolution has proper fallbacks
+   }
+   ```
+
+5. **Run checks**:
+   ```bash
+   cargo +nightly fmt --all
+   cargo clippy --all-features
+   cargo test -p reth-discv4
+   ```
+
+6. **Commit with clear message**:
+   ```bash
+   git commit -m "fix: add fallback for external IP resolution
+
+   Previously, node startup could fail if external IP resolution
+   failed. This adds fallback mechanisms to ensure the node can
+   always start with a reasonable default."
+   ```
+
+## Quick Reference
+
+### Essential Commands
+
+```bash
+# Format code
+cargo +nightly fmt --all
+
+# Run lints
+RUSTFLAGS="-D warnings" cargo +nightly clippy --workspace --all-features --locked
+
+# Run tests
+cargo nextest run --workspace
+
+# Run specific benchmark
+cargo bench --bench bench_name
+
+# Build optimized binary
+cargo build --release --features "jemalloc asm-keccak"
+
+# Check compilation for all features
+cargo check --workspace --all-features
+
+# Check documentation
+cargo docs --document-private-items 
+```

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace.package]
-version = "1.4.2"
+version = "1.4.8"
 edition = "2021"
 rust-version = "1.86"
 license = "MIT OR Apache-2.0"
@@ -11,6 +11,7 @@ exclude = [".github/"]
 members = [
     "bin/reth-bench/",
     "bin/reth/",
+    "crates/alloy-provider/",
     "crates/chain-state/",
     "crates/chainspec/",
     "crates/cli/cli/",
@@ -104,7 +105,7 @@ members = [
     "crates/rpc/rpc-layer",
     "crates/rpc/rpc-server-types/",
     "crates/rpc/rpc-testing-util/",
-    "crates/rpc/rpc-types-compat/",
+    "crates/rpc/rpc-convert/",
     "crates/rpc/rpc/",
     "crates/stages/api/",
     "crates/stages/stages/",
@@ -133,6 +134,7 @@ members = [
     "crates/trie/db",
     "crates/trie/parallel/",
     "crates/trie/sparse",
+    "crates/trie/sparse-parallel/",
     "crates/trie/trie",
     "examples/beacon-api-sidecar-fetcher/",
     "examples/beacon-api-sse/",
@@ -147,6 +149,7 @@ members = [
     "examples/custom-rlpx-subprotocol",
     "examples/custom-node",
     "examples/db-access",
+    "examples/engine-api-access",
     "examples/exex-hello-world",
     "examples/exex-subscription",
     "examples/exex-test",
@@ -163,6 +166,7 @@ members = [
     "examples/custom-beacon-withdrawals",
     "testing/ef-tests/",
     "testing/testing-utils",
+    "crates/tracing-otlp",
 ]
 default-members = ["bin/reth"]
 exclude = ["book/sources", "book/cli"]
@@ -317,6 +321,7 @@ codegen-units = 1
 # reth
 op-reth = { path = "crates/optimism/bin" }
 reth = { path = "bin/reth" }
+reth-alloy-provider = { path = "crates/alloy-provider" }
 reth-basic-payload-builder = { path = "crates/payload/basic" }
 reth-bench = { path = "bin/reth-bench" }
 reth-chain-state = { path = "crates/chain-state" }
@@ -420,7 +425,7 @@ reth-rpc-eth-api = { path = "crates/rpc/rpc-eth-api" }
 reth-rpc-eth-types = { path = "crates/rpc/rpc-eth-types", default-features = false }
 reth-rpc-layer = { path = "crates/rpc/rpc-layer" }
 reth-rpc-server-types = { path = "crates/rpc/rpc-server-types" }
-reth-rpc-types-compat = { path = "crates/rpc/rpc-types-compat" }
+reth-rpc-convert = { path = "crates/rpc/rpc-convert" }
 reth-stages = { path = "crates/stages/stages" }
 reth-stages-api = { path = "crates/stages/api" }
 reth-stages-types = { path = "crates/stages/types", default-features = false }
@@ -439,74 +444,75 @@ reth-trie-common = { path = "crates/trie/common", default-features = false }
 reth-trie-db = { path = "crates/trie/db" }
 reth-trie-parallel = { path = "crates/trie/parallel" }
 reth-trie-sparse = { path = "crates/trie/sparse", default-features = false }
+reth-trie-sparse-parallel = { path = "crates/trie/sparse-parallel" }
 reth-zstd-compressors = { path = "crates/storage/zstd-compressors", default-features = false }
 reth-ress-protocol = { path = "crates/ress/protocol" }
 reth-ress-provider = { path = "crates/ress/provider" }
 
 # revm
-revm = { version = "23.1.0", default-features = false }
-revm-bytecode = { version = "4.0.0", default-features = false }
-revm-database = { version = "4.0.0", default-features = false }
-revm-state = { version = "4.0.0", default-features = false }
-revm-primitives = { version = "19.0.0", default-features = false }
-revm-interpreter = { version = "19.0.0", default-features = false }
-revm-inspector = { version = "4.0.0", default-features = false }
-revm-context = { version = "4.0.0", default-features = false }
-revm-context-interface = { version = "4.0.0", default-features = false }
-revm-database-interface = { version = "4.0.0", default-features = false }
-op-revm = { version = "4.0.2", default-features = false }
-revm-inspectors = "0.22.3"
+revm = { version = "26.0.1", default-features = false }
+revm-bytecode = { version = "5.0.0", default-features = false }
+revm-database = { version = "6.0.0", default-features = false }
+revm-state = { version = "6.0.0", default-features = false }
+revm-primitives = { version = "20.0.0", default-features = false }
+revm-interpreter = { version = "22.0.1", default-features = false }
+revm-inspector = { version = "7.0.1", default-features = false }
+revm-context = { version = "7.0.1", default-features = false }
+revm-context-interface = { version = "7.0.0", default-features = false }
+revm-database-interface = { version = "6.0.0", default-features = false }
+op-revm = { version = "7.0.1", default-features = false }
+revm-inspectors = "0.25.0"
 
 # eth
 alloy-chains = { version = "0.2.0", default-features = false }
-alloy-dyn-abi = "1.1.0"
+alloy-dyn-abi = "1.2.0"
 alloy-eip2124 = { version = "0.2.0", default-features = false }
-alloy-evm = { version = "0.8.1", default-features = false }
-alloy-primitives = { version = "1.1.0", default-features = false, features = ["map-foldhash"] }
+alloy-evm = { version = "0.12", default-features = false }
+alloy-primitives = { version = "1.2.0", default-features = false, features = ["map-foldhash"] }
 alloy-rlp = { version = "0.3.10", default-features = false, features = ["core-net"] }
-alloy-sol-macro = "1.1.0"
-alloy-sol-types = { version = "1.1.0", default-features = false }
-alloy-trie = { version = "0.8.1", default-features = false }
+alloy-sol-macro = "1.2.0"
+alloy-sol-types = { version = "1.2.0", default-features = false }
+alloy-trie = { version = "0.9.0", default-features = false }
 
-alloy-hardforks = "0.2.0"
+alloy-hardforks = "0.2.7"
 
-alloy-consensus = { version = "1.0.5", default-features = false }
-alloy-contract = { version = "1.0.5", default-features = false }
-alloy-eips = { version = "1.0.5", default-features = false }
-alloy-genesis = { version = "1.0.5", default-features = false }
-alloy-json-rpc = { version = "1.0.5", default-features = false }
-alloy-network = { version = "1.0.5", default-features = false }
-alloy-network-primitives = { version = "1.0.5", default-features = false }
-alloy-provider = { version = "1.0.5", features = ["reqwest"], default-features = false }
-alloy-pubsub = { version = "1.0.5", default-features = false }
-alloy-rpc-client = { version = "1.0.5", default-features = false }
-alloy-rpc-types = { version = "1.0.5", features = ["eth"], default-features = false }
-alloy-rpc-types-admin = { version = "1.0.5", default-features = false }
-alloy-rpc-types-anvil = { version = "1.0.5", default-features = false }
-alloy-rpc-types-beacon = { version = "1.0.5", default-features = false }
-alloy-rpc-types-debug = { version = "1.0.5", default-features = false }
-alloy-rpc-types-engine = { version = "1.0.5", default-features = false }
-alloy-rpc-types-eth = { version = "1.0.5", default-features = false }
-alloy-rpc-types-mev = { version = "1.0.5", default-features = false }
-alloy-rpc-types-trace = { version = "1.0.5", default-features = false }
-alloy-rpc-types-txpool = { version = "1.0.5", default-features = false }
-alloy-serde = { version = "1.0.5", default-features = false }
-alloy-signer = { version = "1.0.5", default-features = false }
-alloy-signer-local = { version = "1.0.5", default-features = false }
-alloy-transport = { version = "1.0.5" }
-alloy-transport-http = { version = "1.0.5", features = ["reqwest-rustls-tls"], default-features = false }
-alloy-transport-ipc = { version = "1.0.5", default-features = false }
-alloy-transport-ws = { version = "1.0.5", default-features = false }
+alloy-consensus = { version = "1.0.12", default-features = false }
+alloy-contract = { version = "1.0.12", default-features = false }
+alloy-eips = { version = "1.0.12", default-features = false }
+alloy-genesis = { version = "1.0.12", default-features = false }
+alloy-json-rpc = { version = "1.0.12", default-features = false }
+alloy-network = { version = "1.0.12", default-features = false }
+alloy-network-primitives = { version = "1.0.12", default-features = false }
+alloy-provider = { version = "1.0.12", features = ["reqwest"], default-features = false }
+alloy-pubsub = { version = "1.0.12", default-features = false }
+alloy-rpc-client = { version = "1.0.12", default-features = false }
+alloy-rpc-types = { version = "1.0.12", features = ["eth"], default-features = false }
+alloy-rpc-types-admin = { version = "1.0.12", default-features = false }
+alloy-rpc-types-anvil = { version = "1.0.12", default-features = false }
+alloy-rpc-types-beacon = { version = "1.0.12", default-features = false }
+alloy-rpc-types-debug = { version = "1.0.12", default-features = false }
+alloy-rpc-types-engine = { version = "1.0.12", default-features = false }
+alloy-rpc-types-eth = { version = "1.0.12", default-features = false }
+alloy-rpc-types-mev = { version = "1.0.12", default-features = false }
+alloy-rpc-types-trace = { version = "1.0.12", default-features = false }
+alloy-rpc-types-txpool = { version = "1.0.12", default-features = false }
+alloy-serde = { version = "1.0.12", default-features = false }
+alloy-signer = { version = "1.0.12", default-features = false }
+alloy-signer-local = { version = "1.0.12", default-features = false }
+alloy-transport = { version = "1.0.12" }
+alloy-transport-http = { version = "1.0.12", features = ["reqwest-rustls-tls"], default-features = false }
+alloy-transport-ipc = { version = "1.0.12", default-features = false }
+alloy-transport-ws = { version = "1.0.12", default-features = false }
 
 # op
-alloy-op-evm = { version = "0.8.1", default-features = false }
-alloy-op-hardforks = "0.2.0"
-op-alloy-rpc-types = { version = "0.16.0", default-features = false }
-op-alloy-rpc-types-engine = { version = "0.16.0", default-features = false }
-op-alloy-network = { version = "0.16.0", default-features = false }
-op-alloy-consensus = { version = "0.16.0", default-features = false }
-op-alloy-rpc-jsonrpsee = { version = "0.16.0", default-features = false }
-op-alloy-flz = { version = "0.13.0", default-features = false }
+alloy-op-evm = { version = "0.12", default-features = false }
+alloy-op-hardforks = "0.2.2"
+op-alloy-rpc-types = { version = "0.18.6", default-features = false }
+op-alloy-rpc-types-engine = { version = "0.18.6", default-features = false }
+op-alloy-network = { version = "0.18.6", default-features = false }
+op-alloy-consensus = { version = "0.18.6", default-features = false }
+op-alloy-rpc-jsonrpsee = { version = "0.18.6", default-features = false }
+op-alloy-flz = { version = "0.13.1", default-features = false }
 
 # misc
 aquamarine = "0.6"
@@ -533,7 +539,7 @@ linked_hash_set = "0.1"
 lz4 = "1.28.1"
 modular-bitfield = "0.11.2"
 notify = { version = "8.0.0", default-features = false, features = ["macos_fsevent"] }
-nybbles = { version = "0.3.0", default-features = false }
+nybbles = { version = "0.4.0", default-features = false }
 once_cell = { version = "1.19", default-features = false, features = ["critical-section"] }
 parking_lot = "0.12"
 paste = "1.0"
@@ -626,7 +632,7 @@ toml = "0.8"
 arbitrary = "1.3"
 assert_matches = "1.5.0"
 criterion = { package = "codspeed-criterion-compat", version = "2.7" }
-proptest = "1.4"
+proptest = "1.7"
 proptest-derive = "0.5"
 similar-asserts = { version = "1.5.0", features = ["serde"] }
 tempfile = "3.20"
@@ -700,38 +706,50 @@ walkdir = "2.3.3"
 vergen-git2 = "1.0.5"
 
 [patch.crates-io]
-# alloy-consensus = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-contract = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-eips = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-genesis = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-json-rpc = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-network = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-network-primitives = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-provider = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-pubsub = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-rpc-client = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-rpc-types = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-rpc-types-admin = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-rpc-types-anvil = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-rpc-types-beacon = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-rpc-types-debug = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-rpc-types-engine = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-rpc-types-eth = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-rpc-types-mev = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-rpc-types-trace = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-rpc-types-txpool = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-serde = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-signer = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-signer-local = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-transport = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-transport-http = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-transport-ipc = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-# alloy-transport-ws = { git = "https://github.com/alloy-rs/alloy", branch = "main" }
-#
-# op-alloy-consensus = { git = "https://github.com/alloy-rs/op-alloy", rev = "ad607c1" }
-# op-alloy-network = { git = "https://github.com/alloy-rs/op-alloy", rev = "ad607c1" }
-# op-alloy-rpc-types = { git = "https://github.com/alloy-rs/op-alloy", rev = "ad607c1" }
-# op-alloy-rpc-types-engine = { git = "https://github.com/alloy-rs/op-alloy", rev = "ad607c1" }
+alloy-consensus = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-contract = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-eips = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-genesis = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-json-rpc = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-network = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-network-primitives = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-provider = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-pubsub = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-rpc-client = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-rpc-types = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-rpc-types-admin = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-rpc-types-anvil = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-rpc-types-beacon = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-rpc-types-debug = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-rpc-types-engine = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-rpc-types-eth = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-rpc-types-mev = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-rpc-types-trace = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-rpc-types-txpool = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-serde = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-signer = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-signer-local = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-transport = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-transport-http = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-transport-ipc = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+alloy-transport-ws = { git = "https://github.com/alloy-rs/alloy", rev = "08fa016ed950b6e65f810fc9cdef7cf38fbc63f6" }
+
+revm = { git = "https://github.com/bluealloy/revm", branch = "performance-modexp" }
+revm-bytecode = { git = "https://github.com/bluealloy/revm", branch = "performance-modexp" }
+revm-database = { git = "https://github.com/bluealloy/revm", branch = "performance-modexp" }
+revm-state = { git = "https://github.com/bluealloy/revm", branch = "performance-modexp" }
+revm-primitives = { git = "https://github.com/bluealloy/revm", branch = "performance-modexp" }
+revm-interpreter = { git = "https://github.com/bluealloy/revm", branch = "performance-modexp" }
+revm-inspector = { git = "https://github.com/bluealloy/revm", branch = "performance-modexp" }
+revm-context = { git = "https://github.com/bluealloy/revm", branch = "performance-modexp" }
+revm-context-interface = { git = "https://github.com/bluealloy/revm", branch = "performance-modexp" }
+revm-database-interface = { git = "https://github.com/bluealloy/revm", branch = "performance-modexp" }
+
+# op-alloy-consensus = { git = "https://github.com/alloy-rs/op-alloy", rev = "a79d6fc" }
+# op-alloy-network = { git = "https://github.com/alloy-rs/op-alloy", rev = "a79d6fc" }
+# op-alloy-rpc-types = { git = "https://github.com/alloy-rs/op-alloy", rev = "a79d6fc" }
+# op-alloy-rpc-types-engine = { git = "https://github.com/alloy-rs/op-alloy", rev = "a79d6fc" }
+# op-alloy-rpc-jsonrpsee = { git = "https://github.com/alloy-rs/op-alloy", rev = "a79d6fc" }
 #
 # revm-inspectors = { git = "https://github.com/paradigmxyz/revm-inspectors", rev = "1207e33" }
 #

Cross.toml

@@ -1,5 +1,14 @@
 [build]
 pre-build = [
+    # Use HTTPS for package sources
+    "apt-get update && apt-get install --assume-yes --no-install-recommends ca-certificates",
+    "find /etc/apt/ -type f \\( -name '*.list' -o -name '*.sources' \\) -exec sed -i 's|http://|https://|g' {} +",
+
+    # Configure APT retries and timeouts to handle network issues
+    "echo 'Acquire::Retries \"3\";' > /etc/apt/apt.conf.d/80-retries",
+    "echo 'Acquire::http::Timeout \"60\";' >> /etc/apt/apt.conf.d/80-retries",
+    "echo 'Acquire::ftp::Timeout \"60\";' >> /etc/apt/apt.conf.d/80-retries",
+
     # rust-bindgen dependencies: llvm-dev libclang-dev (>= 10) clang (>= 10)
     # See: https://github.com/cross-rs/cross/wiki/FAQ#using-clang--bindgen for
     # recommended clang versions for the given cross and bindgen version.
@@ -15,5 +24,15 @@ pre-build = [
 # Inspired by https://github.com/cross-rs/cross/blob/9e2298e17170655342d3248a9c8ac37ef92ba38f/docker/Dockerfile.x86_64-pc-windows-gnu#L51
 dockerfile = "./Dockerfile.x86_64-pc-windows-gnu"
 
+[target.riscv64gc-unknown-linux-gnu]
+image = "ubuntu:24.04"
+pre-build = [
+    "apt update",
+    "apt install --yes gcc gcc-riscv64-linux-gnu libclang-dev make",
+]
+env.passthrough = [
+    "CARGO_TARGET_RISCV64GC_UNKNOWN_LINUX_GNU_LINKER=riscv64-linux-gnu-gcc",
+]
+
 [build.env]
 passthrough = ["JEMALLOC_SYS_WITH_LG_PAGE"]

Dockerfile

@@ -33,7 +33,7 @@ ENV FEATURES=$FEATURES
 RUN cargo chef cook --profile $BUILD_PROFILE --features "$FEATURES" --recipe-path recipe.json
 
 # Build application
-COPY --exclude=.git --exclude=dist . .
+COPY --exclude=dist . .
 RUN cargo build --profile $BUILD_PROFILE --features "$FEATURES" --locked --bin reth
 
 # ARG is not resolved in COPY so we have to hack around it by copying the

Dockerfile.x86_64-pc-windows-gnu

@@ -1,7 +1,19 @@
 FROM ubuntu:24.04 AS cross-base
 ENV DEBIAN_FRONTEND=noninteractive
 
-RUN apt-get update && apt-get install --assume-yes --no-install-recommends git ca-certificates
+# Use HTTPS for package sources
+RUN apt-get update && apt-get install --assume-yes --no-install-recommends ca-certificates
+RUN find /etc/apt/ -type f \( -name '*.list' -o -name '*.sources' \) -exec sed -i 's|http://|https://|g' {} +
+
+# Configure APT retries and timeouts to handle network issues
+RUN echo 'Acquire::Retries \"3\";' > /etc/apt/apt.conf.d/80-retries && \
+    echo 'Acquire::http::Timeout \"60\";' >> /etc/apt/apt.conf.d/80-retries && \
+    echo 'Acquire::ftp::Timeout \"60\";' >> /etc/apt/apt.conf.d/80-retries
+
+# configure fallback mirrors
+RUN sed -i 's|URIs: https://archive.ubuntu.com/ubuntu/|URIs: https://mirror.cov.ukservers.com/ubuntu/ https://archive.ubuntu.com/ubuntu/ https://mirror.ox.ac.uk/sites/archive.ubuntu.com/ubuntu/|g' /etc/apt/sources.list.d/ubuntu.sources
+
+RUN apt-get update && apt-get install --assume-yes --no-install-recommends git
 
 RUN git clone https://github.com/cross-rs/cross /cross
 WORKDIR /cross/docker
@@ -15,10 +27,15 @@ FROM cross-base AS build
 
 RUN apt-get install --assume-yes --no-install-recommends libz-mingw-w64-dev g++-mingw-w64-x86-64 gfortran-mingw-w64-x86-64
 
+# Install Wine using OpenSUSE repository because official one is often lagging behind
 RUN dpkg --add-architecture i386 && \
     apt-get install --assume-yes --no-install-recommends wget gpg && \
-    mkdir -pm755 /etc/apt/keyrings && wget -O - https://dl.winehq.org/wine-builds/winehq.key | gpg --dearmor -o /etc/apt/keyrings/winehq-archive.key - && \
-    wget -NP /etc/apt/sources.list.d/ https://dl.winehq.org/wine-builds/ubuntu/dists/noble/winehq-noble.sources && \
+    mkdir -pm755 /etc/apt/keyrings && curl -fsSL \
+    https://download.opensuse.org/repositories/Emulators:/Wine:/Debian/xUbuntu_24.04/Release.key \
+    | tee /etc/apt/keyrings/obs-winehq.key >/dev/null && \
+    echo "deb [arch=amd64,i386 signed-by=/etc/apt/keyrings/obs-winehq.key] \
+    https://download.opensuse.org/repositories/Emulators:/Wine:/Debian/xUbuntu_24.04/ ./" \
+    | tee /etc/apt/sources.list.d/obs-winehq.list && \
     apt-get update && apt-get install --assume-yes --install-recommends winehq-stable
 
 # run-detectors are responsible for calling the correct interpreter for exe

HARDFORK-CHECKLIST.md

@@ -35,7 +35,7 @@ Adding a new versioned endpoint requires the same changes as for L1 just for the
 
 ### Hardforks
 
-Opstack has dedicated hardkfors (e.g. Isthmus), that can be entirely opstack specific (e.g. Holocene) or can be an L1
+Opstack has dedicated hardforks (e.g. Isthmus), that can be entirely opstack specific (e.g. Holocene) or can be an L1
 equivalent hardfork. Since opstack sticks to the L1 header primitive, a new L1 equivalent hardfork also requires new
 equivalent consensus checks. For this reason these `OpHardfork` must be mapped to L1 `EthereumHardfork`, for example:
-`OpHardfork::Isthmus` corresponds to `EthereumHardfork::Prague`. These mappings must be defined in the `ChainSpec`.
+`OpHardfork::Isthmus` corresponds to `EthereumHardfork::Prague`. These mappings must be defined in the `ChainSpec`.

Makefile

@@ -206,6 +206,18 @@ $(EF_TESTS_DIR):
 ef-tests: $(EF_TESTS_DIR) ## Runs Ethereum Foundation tests.
 	cargo nextest run -p ef-tests --features ef-tests
 
+##@ reth-bench
+
+.PHONY: reth-bench
+reth-bench: ## Build the reth-bench binary into the `target` directory.
+	cargo build --manifest-path bin/reth-bench/Cargo.toml --features "$(FEATURES)" --profile "$(PROFILE)"
+
+.PHONY: install-reth-bech
+install-reth-bench: ## Build and install the reth binary under `~/.cargo/bin`.
+	cargo install --path bin/reth-bench --bin reth-bench --force --locked \
+		--features "$(FEATURES)" \
+		--profile "$(PROFILE)"
+
 ##@ Docker
 
 # Note: This requires a buildx builder with emulation support. For example:

bin/reth-bench/scripts/compare_newpayload_latency.py

@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+
+# A simple script which plots graphs comparing two combined_latency.csv files
+# output by reth-bench. The graphs which are plotted are:
+#
+# - A histogram of the percent change between latencies, bucketed by 1%
+#   increments.
+#
+# - A simple line graph plotting the latencies of the two files against each
+#   other.
+
+
+import argparse
+import pandas as pd
+import matplotlib.pyplot as plt
+import numpy as np
+import sys
+
+def main():
+    parser = argparse.ArgumentParser(description='Generate histogram of total_latency percent differences between two CSV files')
+    parser.add_argument('baseline_csv', help='First CSV file, used as the baseline/control')
+    parser.add_argument('comparison_csv', help='Second CSV file, which is being compared to the baseline')
+    parser.add_argument('-o', '--output', default='latency.png', help='Output image file (default: latency.png)')
+
+    args = parser.parse_args()
+
+    try:
+        df1 = pd.read_csv(args.baseline_csv)
+        df2 = pd.read_csv(args.comparison_csv)
+    except FileNotFoundError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error reading CSV files: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if 'total_latency' not in df1.columns:
+        print(f"Error: 'total_latency' column not found in {args.baseline_csv}", file=sys.stderr)
+        sys.exit(1)
+
+    if 'total_latency' not in df2.columns:
+        print(f"Error: 'total_latency' column not found in {args.comparison_csv}", file=sys.stderr)
+        sys.exit(1)
+
+    if len(df1) != len(df2):
+        print("Warning: CSV files have different number of rows. Using minimum length.", file=sys.stderr)
+        min_len = min(len(df1), len(df2))
+        df1 = df1.head(min_len)
+        df2 = df2.head(min_len)
+
+    latency1 = df1['total_latency'].values
+    latency2 = df2['total_latency'].values
+
+    # Handle division by zero
+    with np.errstate(divide='ignore', invalid='ignore'):
+        percent_diff = ((latency2 - latency1) / latency1) * 100
+
+    # Remove infinite and NaN values
+    percent_diff = percent_diff[np.isfinite(percent_diff)]
+
+    if len(percent_diff) == 0:
+        print("Error: No valid percent differences could be calculated", file=sys.stderr)
+        sys.exit(1)
+
+    # Create histogram with 1% buckets
+    min_diff = np.floor(percent_diff.min())
+    max_diff = np.ceil(percent_diff.max())
+
+    bins = np.arange(min_diff, max_diff + 1, 1)
+
+    # Create figure with two subplots
+    fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(12, 12))
+
+    # Top subplot: Histogram
+    ax1.hist(percent_diff, bins=bins, edgecolor='black', alpha=0.7)
+    ax1.set_xlabel('Percent Difference (%)')
+    ax1.set_ylabel('Number of Blocks')
+    ax1.set_title(f'Total Latency Percent Difference Histogram\n({args.baseline_csv} vs {args.comparison_csv})')
+    ax1.grid(True, alpha=0.3)
+
+    # Add statistics to the histogram
+    mean_diff = np.mean(percent_diff)
+    median_diff = np.median(percent_diff)
+    ax1.axvline(mean_diff, color='red', linestyle='--', label=f'Mean: {mean_diff:.2f}%')
+    ax1.axvline(median_diff, color='orange', linestyle='--', label=f'Median: {median_diff:.2f}%')
+    ax1.legend()
+
+    # Bottom subplot: Latency vs Block Number
+    if 'block_number' in df1.columns and 'block_number' in df2.columns:
+        block_numbers = df1['block_number'].values[:len(percent_diff)]
+        ax2.plot(block_numbers, latency1[:len(percent_diff)], 'b-', alpha=0.7, label=f'Baseline ({args.baseline_csv})')
+        ax2.plot(block_numbers, latency2[:len(percent_diff)], 'r-', alpha=0.7, label=f'Comparison ({args.comparison_csv})')
+        ax2.set_xlabel('Block Number')
+        ax2.set_ylabel('Total Latency (ms)')
+        ax2.set_title('Total Latency vs Block Number')
+        ax2.grid(True, alpha=0.3)
+        ax2.legend()
+    else:
+        # If no block_number column, use index
+        indices = np.arange(len(percent_diff))
+        ax2.plot(indices, latency1[:len(percent_diff)], 'b-', alpha=0.7, label=f'Baseline ({args.baseline_csv})')
+        ax2.plot(indices, latency2[:len(percent_diff)], 'r-', alpha=0.7, label=f'Comparison ({args.comparison_csv})')
+        ax2.set_xlabel('Block Index')
+        ax2.set_ylabel('Total Latency (ms)')
+        ax2.set_title('Total Latency vs Block Index')
+        ax2.grid(True, alpha=0.3)
+        ax2.legend()
+
+    plt.tight_layout()
+    plt.savefig(args.output, dpi=300, bbox_inches='tight')
+    print(f"Histogram and latency graph saved to {args.output}")
+
+    print(f"\nStatistics:")
+    print(f"Mean percent difference: {mean_diff:.2f}%")
+    print(f"Median percent difference: {median_diff:.2f}%")
+    print(f"Standard deviation: {np.std(percent_diff):.2f}%")
+    print(f"Min: {percent_diff.min():.2f}%")
+    print(f"Max: {percent_diff.max():.2f}%")
+    print(f"Total blocks analyzed: {len(percent_diff)}")
+
+if __name__ == '__main__':
+    main()

bin/reth-bench/src/valid_payload.rs

@@ -16,21 +16,21 @@ use tracing::error;
 /// An extension trait for providers that implement the engine API, to wait for a VALID response.
 #[async_trait::async_trait]
 pub trait EngineApiValidWaitExt<N>: Send + Sync {
-    /// Calls `engine_newPayloadV1` with the given [ExecutionPayloadV1], and waits until the
+    /// Calls `engine_newPayloadV1` with the given [`ExecutionPayloadV1`], and waits until the
     /// response is VALID.
     async fn new_payload_v1_wait(
         &self,
         payload: ExecutionPayloadV1,
     ) -> TransportResult<PayloadStatus>;
 
-    /// Calls `engine_newPayloadV2` with the given [ExecutionPayloadInputV2], and waits until the
+    /// Calls `engine_newPayloadV2` with the given [`ExecutionPayloadInputV2`], and waits until the
     /// response is VALID.
     async fn new_payload_v2_wait(
         &self,
         payload: ExecutionPayloadInputV2,
     ) -> TransportResult<PayloadStatus>;
 
-    /// Calls `engine_newPayloadV3` with the given [ExecutionPayloadV3], parent beacon block root,
+    /// Calls `engine_newPayloadV3` with the given [`ExecutionPayloadV3`], parent beacon block root,
     /// and versioned hashes, and waits until the response is VALID.
     async fn new_payload_v3_wait(
         &self,
@@ -39,7 +39,7 @@ pub trait EngineApiValidWaitExt<N>: Send + Sync {
         parent_beacon_block_root: B256,
     ) -> TransportResult<PayloadStatus>;
 
-    /// Calls `engine_newPayloadV4` with the given [ExecutionPayloadV3], parent beacon block root,
+    /// Calls `engine_newPayloadV4` with the given [`ExecutionPayloadV3`], parent beacon block root,
     /// versioned hashes, and requests hash, and waits until the response is VALID.
     async fn new_payload_v4_wait(
         &self,
@@ -49,24 +49,24 @@ pub trait EngineApiValidWaitExt<N>: Send + Sync {
         requests_hash: B256,
     ) -> TransportResult<PayloadStatus>;
 
-    /// Calls `engine_forkChoiceUpdatedV1` with the given [ForkchoiceState] and optional
-    /// [PayloadAttributes], and waits until the response is VALID.
+    /// Calls `engine_forkChoiceUpdatedV1` with the given [`ForkchoiceState`] and optional
+    /// [`PayloadAttributes`], and waits until the response is VALID.
     async fn fork_choice_updated_v1_wait(
         &self,
         fork_choice_state: ForkchoiceState,
         payload_attributes: Option<PayloadAttributes>,
     ) -> TransportResult<ForkchoiceUpdated>;
 
-    /// Calls `engine_forkChoiceUpdatedV2` with the given [ForkchoiceState] and optional
-    /// [PayloadAttributes], and waits until the response is VALID.
+    /// Calls `engine_forkChoiceUpdatedV2` with the given [`ForkchoiceState`] and optional
+    /// [`PayloadAttributes`], and waits until the response is VALID.
     async fn fork_choice_updated_v2_wait(
         &self,
         fork_choice_state: ForkchoiceState,
         payload_attributes: Option<PayloadAttributes>,
     ) -> TransportResult<ForkchoiceUpdated>;
 
-    /// Calls `engine_forkChoiceUpdatedV3` with the given [ForkchoiceState] and optional
-    /// [PayloadAttributes], and waits until the response is VALID.
+    /// Calls `engine_forkChoiceUpdatedV3` with the given [`ForkchoiceState`] and optional
+    /// [`PayloadAttributes`], and waits until the response is VALID.
     async fn fork_choice_updated_v3_wait(
         &self,
         fork_choice_state: ForkchoiceState,
@@ -296,7 +296,7 @@ pub(crate) async fn call_new_payload<N, P: EngineApiValidWaitExt<N>>(
 ) -> TransportResult<EngineApiMessageVersion> {
     match payload {
         ExecutionPayload::V3(payload) => {
-            // We expect the caller
+            // We expect the caller to provide `parent_beacon_block_root` for V3 payloads.
             let parent_beacon_block_root = parent_beacon_block_root
                 .expect("parent_beacon_block_root is required for V3 payloads and higher");
 

bin/reth/Cargo.toml

@@ -27,7 +27,7 @@ reth-cli-util.workspace = true
 reth-consensus-common.workspace = true
 reth-rpc-builder.workspace = true
 reth-rpc.workspace = true
-reth-rpc-types-compat.workspace = true
+reth-rpc-convert.workspace = true
 reth-rpc-api = { workspace = true, features = ["client"] }
 reth-rpc-eth-types.workspace = true
 reth-rpc-server-types.workspace = true

bin/reth/src/lib.rs

@@ -175,9 +175,9 @@ pub mod rpc {
         pub use reth_rpc_server_types::result::*;
     }
 
-    /// Re-exported from `reth_rpc_types_compat`.
+    /// Re-exported from `reth_rpc_convert`.
     pub mod compat {
-        pub use reth_rpc_types_compat::*;
+        pub use reth_rpc_convert::*;
     }
 }
 

book/SUMMARY.md

@@ -1,84 +0,0 @@
-# Reth Book
-
-- [Introduction](./intro.md)
-- [Installation](./installation/installation.md)
-    - [Pre-Built Binaries](./installation/binaries.md)
-    - [Docker](./installation/docker.md)
-    - [Build from Source](./installation/source.md)
-    - [Build for ARM devices](./installation/build-for-arm-devices.md)
-    - [Update Priorities](./installation/priorities.md)
-- [Run a Node](./run/run-a-node.md)
-    - [Mainnet or official testnets](./run/mainnet.md)
-    - [OP Stack](./run/optimism.md)
-    - [Run an OP Mainnet Node](./run/sync-op-mainnet.md)
-    - [Private testnet](./run/private-testnet.md)
-    - [Metrics](./run/observability.md)
-    - [Configuring Reth](./run/config.md)
-    - [Transaction types](./run/transactions.md)
-    - [Pruning & Full Node](./run/pruning.md)
-    - [Ports](./run/ports.md)
-    - [Troubleshooting](./run/troubleshooting.md)
-- [Interacting with Reth over JSON-RPC](./jsonrpc/intro.md)
-    - [eth](./jsonrpc/eth.md)
-    - [web3](./jsonrpc/web3.md)
-    - [net](./jsonrpc/net.md)
-    - [txpool](./jsonrpc/txpool.md)
-    - [debug](./jsonrpc/debug.md)
-    - [trace](./jsonrpc/trace.md)
-    - [admin](./jsonrpc/admin.md)
-    - [rpc](./jsonrpc/rpc.md)
-- [CLI Reference](./cli/cli.md) <!-- CLI_REFERENCE START -->
-  - [`reth`](./cli/reth.md)
-    - [`reth node`](./cli/reth/node.md)
-    - [`reth init`](./cli/reth/init.md)
-    - [`reth init-state`](./cli/reth/init-state.md)
-    - [`reth import`](./cli/reth/import.md)
-    - [`reth import-era`](./cli/reth/import-era.md)
-    - [`reth dump-genesis`](./cli/reth/dump-genesis.md)
-    - [`reth db`](./cli/reth/db.md)
-      - [`reth db stats`](./cli/reth/db/stats.md)
-      - [`reth db list`](./cli/reth/db/list.md)
-      - [`reth db checksum`](./cli/reth/db/checksum.md)
-      - [`reth db diff`](./cli/reth/db/diff.md)
-      - [`reth db get`](./cli/reth/db/get.md)
-        - [`reth db get mdbx`](./cli/reth/db/get/mdbx.md)
-        - [`reth db get static-file`](./cli/reth/db/get/static-file.md)
-      - [`reth db drop`](./cli/reth/db/drop.md)
-      - [`reth db clear`](./cli/reth/db/clear.md)
-        - [`reth db clear mdbx`](./cli/reth/db/clear/mdbx.md)
-        - [`reth db clear static-file`](./cli/reth/db/clear/static-file.md)
-      - [`reth db version`](./cli/reth/db/version.md)
-      - [`reth db path`](./cli/reth/db/path.md)
-    - [`reth download`](./cli/reth/download.md)
-    - [`reth stage`](./cli/reth/stage.md)
-      - [`reth stage run`](./cli/reth/stage/run.md)
-      - [`reth stage drop`](./cli/reth/stage/drop.md)
-      - [`reth stage dump`](./cli/reth/stage/dump.md)
-        - [`reth stage dump execution`](./cli/reth/stage/dump/execution.md)
-        - [`reth stage dump storage-hashing`](./cli/reth/stage/dump/storage-hashing.md)
-        - [`reth stage dump account-hashing`](./cli/reth/stage/dump/account-hashing.md)
-        - [`reth stage dump merkle`](./cli/reth/stage/dump/merkle.md)
-      - [`reth stage unwind`](./cli/reth/stage/unwind.md)
-        - [`reth stage unwind to-block`](./cli/reth/stage/unwind/to-block.md)
-        - [`reth stage unwind num-blocks`](./cli/reth/stage/unwind/num-blocks.md)
-    - [`reth p2p`](./cli/reth/p2p.md)
-      - [`reth p2p header`](./cli/reth/p2p/header.md)
-      - [`reth p2p body`](./cli/reth/p2p/body.md)
-      - [`reth p2p rlpx`](./cli/reth/p2p/rlpx.md)
-        - [`reth p2p rlpx ping`](./cli/reth/p2p/rlpx/ping.md)
-    - [`reth config`](./cli/reth/config.md)
-    - [`reth debug`](./cli/reth/debug.md)
-      - [`reth debug execution`](./cli/reth/debug/execution.md)
-      - [`reth debug merkle`](./cli/reth/debug/merkle.md)
-      - [`reth debug in-memory-merkle`](./cli/reth/debug/in-memory-merkle.md)
-      - [`reth debug build-block`](./cli/reth/debug/build-block.md)
-    - [`reth recover`](./cli/reth/recover.md)
-      - [`reth recover storage-tries`](./cli/reth/recover/storage-tries.md)
-    - [`reth prune`](./cli/reth/prune.md)
-- [Developers](./developers/developers.md) <!-- CLI_REFERENCE END -->
-    - [Execution Extensions](./developers/exex/exex.md)
-        - [How do ExExes work?](./developers/exex/how-it-works.md)
-        - [Hello World](./developers/exex/hello-world.md)
-        - [Tracking State](./developers/exex/tracking-state.md)
-        - [Remote](./developers/exex/remote.md)
-    - [Contribute](./developers/contribute.md)

book/cli/SUMMARY.md

@@ -1,47 +0,0 @@
-- [`reth`](./reth.md)
-  - [`reth node`](./reth/node.md)
-  - [`reth init`](./reth/init.md)
-  - [`reth init-state`](./reth/init-state.md)
-  - [`reth import`](./reth/import.md)
-  - [`reth import-era`](./reth/import-era.md)
-  - [`reth dump-genesis`](./reth/dump-genesis.md)
-  - [`reth db`](./reth/db.md)
-    - [`reth db stats`](./reth/db/stats.md)
-    - [`reth db list`](./reth/db/list.md)
-    - [`reth db checksum`](./reth/db/checksum.md)
-    - [`reth db diff`](./reth/db/diff.md)
-    - [`reth db get`](./reth/db/get.md)
-      - [`reth db get mdbx`](./reth/db/get/mdbx.md)
-      - [`reth db get static-file`](./reth/db/get/static-file.md)
-    - [`reth db drop`](./reth/db/drop.md)
-    - [`reth db clear`](./reth/db/clear.md)
-      - [`reth db clear mdbx`](./reth/db/clear/mdbx.md)
-      - [`reth db clear static-file`](./reth/db/clear/static-file.md)
-    - [`reth db version`](./reth/db/version.md)
-    - [`reth db path`](./reth/db/path.md)
-  - [`reth download`](./reth/download.md)
-  - [`reth stage`](./reth/stage.md)
-    - [`reth stage run`](./reth/stage/run.md)
-    - [`reth stage drop`](./reth/stage/drop.md)
-    - [`reth stage dump`](./reth/stage/dump.md)
-      - [`reth stage dump execution`](./reth/stage/dump/execution.md)
-      - [`reth stage dump storage-hashing`](./reth/stage/dump/storage-hashing.md)
-      - [`reth stage dump account-hashing`](./reth/stage/dump/account-hashing.md)
-      - [`reth stage dump merkle`](./reth/stage/dump/merkle.md)
-    - [`reth stage unwind`](./reth/stage/unwind.md)
-      - [`reth stage unwind to-block`](./reth/stage/unwind/to-block.md)
-      - [`reth stage unwind num-blocks`](./reth/stage/unwind/num-blocks.md)
-  - [`reth p2p`](./reth/p2p.md)
-    - [`reth p2p header`](./reth/p2p/header.md)
-    - [`reth p2p body`](./reth/p2p/body.md)
-    - [`reth p2p rlpx`](./reth/p2p/rlpx.md)
-      - [`reth p2p rlpx ping`](./reth/p2p/rlpx/ping.md)
-  - [`reth config`](./reth/config.md)
-  - [`reth debug`](./reth/debug.md)
-    - [`reth debug execution`](./reth/debug/execution.md)
-    - [`reth debug merkle`](./reth/debug/merkle.md)
-    - [`reth debug in-memory-merkle`](./reth/debug/in-memory-merkle.md)
-    - [`reth debug build-block`](./reth/debug/build-block.md)
-  - [`reth recover`](./reth/recover.md)
-    - [`reth recover storage-tries`](./reth/recover/storage-tries.md)
-  - [`reth prune`](./reth/prune.md)

book/cli/help.rs

@@ -10,25 +10,28 @@ regex = "1"
 ---
 use clap::Parser;
 use regex::Regex;
-use std::borrow::Cow;
-use std::fs::{self, File};
-use std::io::{self, Write};
-use std::iter::once;
-use std::path::{Path, PathBuf};
-use std::process::{Command, Stdio};
-use std::str;
-use std::sync::LazyLock;
-use std::{fmt, process};
+use std::{
+    borrow::Cow,
+    fmt,
+    fs::{self, File},
+    io::{self, Write},
+    iter::once,
+    path::{Path, PathBuf},
+    process,
+    process::{Command, Stdio},
+    str,
+    sync::LazyLock,
+};
 
-const SECTION_START: &str = "<!-- CLI_REFERENCE START -->";
-const SECTION_END: &str = "<!-- CLI_REFERENCE END -->";
-const README: &str = r#"# CLI Reference
+const SECTION_START: &str = "{/* CLI_REFERENCE START */}";
+const SECTION_END: &str = "{/* CLI_REFERENCE END */";
+const README: &str = r#"import Summary from './SUMMARY.mdx';
 
-<!-- Generated by scripts/gen_output/help.rs -->
+# CLI Reference
 
 Automatically-generated CLI reference from `--help` output.
 
-{{#include ./SUMMARY.md}}
+<Summary />
 "#;
 const TRIM_LINE_END_MARKDOWN: bool = true;
 
@@ -49,7 +52,7 @@ struct Args {
     #[arg(long, default_value_t = String::from("."))]
     root_dir: String,
 
-    /// Indentation for the root SUMMARY.md file
+    /// Indentation for the root SUMMARY.mdx file
     #[arg(long, default_value_t = 2)]
     root_indentation: usize,
 
@@ -61,7 +64,7 @@ struct Args {
     #[arg(long)]
     readme: bool,
 
-    /// Whether to update the root SUMMARY.md file
+    /// Whether to update the root SUMMARY.mdx file
     #[arg(long)]
     root_summary: bool,
 
@@ -76,11 +79,7 @@ struct Args {
 
 fn write_file(file_path: &Path, content: &str) -> io::Result<()> {
     let content = if TRIM_LINE_END_MARKDOWN {
-        content
-            .lines()
-            .map(|line| line.trim_end())
-            .collect::<Vec<_>>()
-            .join("\n")
+        content.lines().map(|line| line.trim_end()).collect::<Vec<_>>().join("\n")
     } else {
         content.to_string()
     };
@@ -106,25 +105,13 @@ fn main() -> io::Result<()> {
     while let Some(cmd) = todo_iter.pop() {
         let (new_subcmds, stdout) = get_entry(&cmd)?;
         if args.verbose && !new_subcmds.is_empty() {
-            println!(
-                "Found subcommands for \"{}\": {:?}",
-                cmd.command_name(),
-                new_subcmds
-            );
+            println!("Found subcommands for \"{}\": {:?}", cmd.command_name(), new_subcmds);
         }
         // Add new subcommands to todo_iter (so that they are processed in the correct order).
         for subcmd in new_subcmds.into_iter().rev() {
-            let new_subcmds: Vec<_> = cmd
-                .subcommands
-                .iter()
-                .cloned()
-                .chain(once(subcmd))
-                .collect();
+            let new_subcmds: Vec<_> = cmd.subcommands.iter().cloned().chain(once(subcmd)).collect();
 
-            todo_iter.push(Cmd {
-                cmd: cmd.cmd,
-                subcommands: new_subcmds,
-            });
+            todo_iter.push(Cmd { cmd: cmd.cmd, subcommands: new_subcmds });
         }
         output.push((cmd, stdout));
     }
@@ -134,25 +121,25 @@ fn main() -> io::Result<()> {
         cmd_markdown(&out_dir, cmd, stdout)?;
     }
 
-    // Generate SUMMARY.md.
+    // Generate SUMMARY.mdx.
     let summary: String = output
         .iter()
         .map(|(cmd, _)| cmd_summary(None, cmd, 0))
         .chain(once("\n".to_string()))
         .collect();
 
-    write_file(&out_dir.clone().join("SUMMARY.md"), &summary)?;
+    write_file(&out_dir.clone().join("SUMMARY.mdx"), &summary)?;
 
     // Generate README.md.
     if args.readme {
-        let path = &out_dir.join("README.md");
+        let path = &out_dir.join("README.mdx");
         if args.verbose {
-            println!("Writing README.md to \"{}\"", path.to_string_lossy());
+            println!("Writing README.mdx to \"{}\"", path.to_string_lossy());
         }
         write_file(path, README)?;
     }
 
-    // Generate root SUMMARY.md.
+    // Generate root SUMMARY.mdx.
     if args.root_summary {
         let root_summary: String = output
             .iter()
@@ -166,7 +153,8 @@ fn main() -> io::Result<()> {
         if args.verbose {
             println!("Updating root summary in \"{}\"", path.to_string_lossy());
         }
-        update_root_summary(path, &root_summary)?;
+        // TODO: This is where we update the cli reference sidebar.ts
+        // update_root_summary(path, &root_summary)?;
     }
 
     Ok(())
@@ -213,8 +201,7 @@ fn parse_sub_commands(s: &str) -> Vec<String> {
                 .lines()
                 .take_while(|line| !line.starts_with("Options:") && !line.starts_with("Arguments:"))
                 .filter_map(|line| {
-                    re.captures(line)
-                        .and_then(|cap| cap.get(1).map(|m| m.as_str().to_string()))
+                    re.captures(line).and_then(|cap| cap.get(1).map(|m| m.as_str().to_string()))
                 })
                 .filter(|cmd| cmd != "help")
                 .map(String::from)
@@ -229,7 +216,7 @@ fn cmd_markdown(out_dir: &Path, cmd: &Cmd, stdout: &str) -> io::Result<()> {
 
     let out_path = out_dir.join(cmd.to_string().replace(" ", "/"));
     fs::create_dir_all(out_path.parent().unwrap())?;
-    write_file(&out_path.with_extension("md"), &out)?;
+    write_file(&out_path.with_extension("mdx"), &out)?;
 
     Ok(())
 }
@@ -265,12 +252,12 @@ fn cmd_summary(md_root: Option<PathBuf>, cmd: &Cmd, indent: usize) -> String {
         Some(md_root) => format!("{}/{}", md_root.to_string_lossy(), cmd_path),
     };
     let indent_string = " ".repeat(indent + (cmd.subcommands.len() * 2));
-    format!("{}- [`{}`](./{}.md)\n", indent_string, cmd_s, full_cmd_path)
+    format!("{}- [`{}`](/cli/{})\n", indent_string, cmd_s, full_cmd_path)
 }
 
-/// Replaces the CLI_REFERENCE section in the root SUMMARY.md file.
+/// Replaces the CLI_REFERENCE section in the root SUMMARY.mdx file.
 fn update_root_summary(root_dir: &Path, root_summary: &str) -> io::Result<()> {
-    let summary_file = root_dir.join("SUMMARY.md");
+    let summary_file = root_dir.join("SUMMARY.mdx");
     let original_summary_content = fs::read_to_string(&summary_file)?;
 
     let section_re = regex!(&format!(r"(?s)\s*{SECTION_START}.*?{SECTION_END}"));
@@ -293,9 +280,8 @@ fn update_root_summary(root_dir: &Path, root_summary: &str) -> io::Result<()> {
     let root_summary_s = root_summary.trim_end().replace("\n\n", "\n");
     let replace_with = format!(" {}\n{}\n{}", SECTION_START, root_summary_s, last_line);
 
-    let new_root_summary = section_re
-        .replace(&original_summary_content, replace_with.as_str())
-        .to_string();
+    let new_root_summary =
+        section_re.replace(&original_summary_content, replace_with.as_str()).to_string();
 
     let mut root_summary_file = File::create(&summary_file)?;
     root_summary_file.write_all(new_root_summary.as_bytes())
@@ -349,17 +335,11 @@ struct Cmd<'a> {
 
 impl<'a> Cmd<'a> {
     fn command_name(&self) -> &str {
-        self.cmd
-            .file_name()
-            .and_then(|os_str| os_str.to_str())
-            .expect("Expect valid command")
+        self.cmd.file_name().and_then(|os_str| os_str.to_str()).expect("Expect valid command")
     }
 
     fn new(cmd: &'a PathBuf) -> Self {
-        Self {
-            cmd,
-            subcommands: Vec::new(),
-        }
+        Self { cmd, subcommands: Vec::new() }
     }
 }
 

book/cli/reth/debug/replay-engine.md

@@ -1,332 +0,0 @@
-# reth debug replay-engine
-
-Debug engine API by replaying stored messages
-
-```bash
-$ reth debug replay-engine --help
-```
-```txt
-Usage: reth debug replay-engine [OPTIONS] --engine-api-store <PATH>
-
-Options:
-      --instance <INSTANCE>
-          Add a new instance of a node.
-
-          Configures the ports of the node to avoid conflicts with the defaults. This is useful for running multiple nodes on the same machine.
-
-          Max number of instances is 200. It is chosen in a way so that it's not possible to have port numbers that conflict with each other.
-
-          Changes to the following port numbers: - `DISCOVERY_PORT`: default + `instance` - 1 - `AUTH_PORT`: default + `instance` * 100 - 100 - `HTTP_RPC_PORT`: default - `instance` + 1 - `WS_RPC_PORT`: default + `instance` * 2 - 2
-
-          [default: 1]
-
-  -h, --help
-          Print help (see a summary with '-h')
-
-Datadir:
-      --datadir <DATA_DIR>
-          The path to the data dir for all reth files and subdirectories.
-
-          Defaults to the OS-specific data directory:
-
-          - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/`
-          - Windows: `{FOLDERID_RoamingAppData}/reth/`
-          - macOS: `$HOME/Library/Application Support/reth/`
-
-          [default: default]
-
-      --datadir.static-files <PATH>
-          The absolute path to store static files in.
-
-      --config <FILE>
-          The path to the configuration file to use
-
-      --chain <CHAIN_OR_PATH>
-          The chain this node is running.
-          Possible values are either a built-in chain or the path to a chain specification file.
-
-          Built-in chains:
-              mainnet, sepolia, holesky, dev
-
-          [default: mainnet]
-
-Database:
-      --db.log-level <LOG_LEVEL>
-          Database logging level. Levels higher than "notice" require a debug build
-
-          Possible values:
-          - fatal:   Enables logging for critical conditions, i.e. assertion failures
-          - error:   Enables logging for error conditions
-          - warn:    Enables logging for warning conditions
-          - notice:  Enables logging for normal but significant condition
-          - verbose: Enables logging for verbose informational
-          - debug:   Enables logging for debug-level messages
-          - trace:   Enables logging for trace debug-level messages
-          - extra:   Enables logging for extra debug-level messages
-
-      --db.exclusive <EXCLUSIVE>
-          Open environment in exclusive/monopolistic mode. Makes it possible to open a database on an NFS volume
-
-          [possible values: true, false]
-
-      --db.max-size <MAX_SIZE>
-          Maximum database size (e.g., 4TB, 8MB)
-
-      --db.growth-step <GROWTH_STEP>
-          Database growth step (e.g., 4GB, 4KB)
-
-      --db.read-transaction-timeout <READ_TRANSACTION_TIMEOUT>
-          Read transaction timeout in seconds, 0 means no timeout
-
-Networking:
-  -d, --disable-discovery
-          Disable the discovery service
-
-      --disable-dns-discovery
-          Disable the DNS discovery
-
-      --disable-discv4-discovery
-          Disable Discv4 discovery
-
-      --enable-discv5-discovery
-          Enable Discv5 discovery
-
-      --disable-nat
-          Disable Nat discovery
-
-      --discovery.addr <DISCOVERY_ADDR>
-          The UDP address to use for devp2p peer discovery version 4
-
-          [default: 0.0.0.0]
-
-      --discovery.port <DISCOVERY_PORT>
-          The UDP port to use for devp2p peer discovery version 4
-
-          [default: 30303]
-
-      --discovery.v5.addr <DISCOVERY_V5_ADDR>
-          The UDP IPv4 address to use for devp2p peer discovery version 5. Overwritten by `RLPx` address, if it's also IPv4
-
-      --discovery.v5.addr.ipv6 <DISCOVERY_V5_ADDR_IPV6>
-          The UDP IPv6 address to use for devp2p peer discovery version 5. Overwritten by `RLPx` address, if it's also IPv6
-
-      --discovery.v5.port <DISCOVERY_V5_PORT>
-          The UDP IPv4 port to use for devp2p peer discovery version 5. Not used unless `--addr` is IPv4, or `--discovery.v5.addr` is set
-
-          [default: 9200]
-
-      --discovery.v5.port.ipv6 <DISCOVERY_V5_PORT_IPV6>
-          The UDP IPv6 port to use for devp2p peer discovery version 5. Not used unless `--addr` is IPv6, or `--discovery.addr.ipv6` is set
-
-          [default: 9200]
-
-      --discovery.v5.lookup-interval <DISCOVERY_V5_LOOKUP_INTERVAL>
-          The interval in seconds at which to carry out periodic lookup queries, for the whole run of the program
-
-          [default: 20]
-
-      --discovery.v5.bootstrap.lookup-interval <DISCOVERY_V5_BOOTSTRAP_LOOKUP_INTERVAL>
-          The interval in seconds at which to carry out boost lookup queries, for a fixed number of times, at bootstrap
-
-          [default: 5]
-
-      --discovery.v5.bootstrap.lookup-countdown <DISCOVERY_V5_BOOTSTRAP_LOOKUP_COUNTDOWN>
-          The number of times to carry out boost lookup queries at bootstrap
-
-          [default: 200]
-
-      --trusted-peers <TRUSTED_PEERS>
-          Comma separated enode URLs of trusted peers for P2P connections.
-
-          --trusted-peers enode://abcd@192.168.0.1:30303
-
-      --trusted-only
-          Connect to or accept from trusted peers only
-
-      --bootnodes <BOOTNODES>
-          Comma separated enode URLs for P2P discovery bootstrap.
-
-          Will fall back to a network-specific default if not specified.
-
-      --dns-retries <DNS_RETRIES>
-          Amount of DNS resolution requests retries to perform when peering
-
-          [default: 0]
-
-      --peers-file <FILE>
-          The path to the known peers file. Connected peers are dumped to this file on nodes
-          shutdown, and read on startup. Cannot be used with `--no-persist-peers`.
-
-      --identity <IDENTITY>
-          Custom node identity
-
-          [default: reth/<VERSION>-<SHA>/<ARCH>]
-
-      --p2p-secret-key <PATH>
-          Secret key to use for this node.
-
-          This will also deterministically set the peer ID. If not specified, it will be set in the data dir for the chain being used.
-
-      --no-persist-peers
-          Do not persist peers.
-
-      --nat <NAT>
-          NAT resolution method (any|none|upnp|publicip|extip:\<IP\>)
-
-          [default: any]
-
-      --addr <ADDR>
-          Network listening address
-
-          [default: 0.0.0.0]
-
-      --port <PORT>
-          Network listening port
-
-          [default: 30303]
-
-      --max-outbound-peers <MAX_OUTBOUND_PEERS>
-          Maximum number of outbound requests. default: 100
-
-      --max-inbound-peers <MAX_INBOUND_PEERS>
-          Maximum number of inbound requests. default: 30
-
-      --max-tx-reqs <COUNT>
-          Max concurrent `GetPooledTransactions` requests.
-
-          [default: 130]
-
-      --max-tx-reqs-peer <COUNT>
-          Max concurrent `GetPooledTransactions` requests per peer.
-
-          [default: 1]
-
-      --max-seen-tx-history <COUNT>
-          Max number of seen transactions to remember per peer.
-
-          Default is 320 transaction hashes.
-
-          [default: 320]
-
-      --max-pending-imports <COUNT>
-          Max number of transactions to import concurrently.
-
-          [default: 4096]
-
-      --pooled-tx-response-soft-limit <BYTES>
-          Experimental, for usage in research. Sets the max accumulated byte size of transactions
-          to pack in one response.
-          Spec'd at 2MiB.
-
-          [default: 2097152]
-
-      --pooled-tx-pack-soft-limit <BYTES>
-          Experimental, for usage in research. Sets the max accumulated byte size of transactions to
-          request in one request.
-
-          Since `RLPx` protocol version 68, the byte size of a transaction is shared as metadata in a
-          transaction announcement (see `RLPx` specs). This allows a node to request a specific size
-          response.
-
-          By default, nodes request only 128 KiB worth of transactions, but should a peer request
-          more, up to 2 MiB, a node will answer with more than 128 KiB.
-
-          Default is 128 KiB.
-
-          [default: 131072]
-
-      --max-tx-pending-fetch <COUNT>
-          Max capacity of cache of hashes for transactions pending fetch.
-
-          [default: 25600]
-
-      --net-if.experimental <IF_NAME>
-          Name of network interface used to communicate with peers.
-
-          If flag is set, but no value is passed, the default interface for docker `eth0` is tried.
-
-      --engine-api-store <PATH>
-          The path to read engine API messages from
-
-      --interval <INTERVAL>
-          The number of milliseconds between Engine API messages
-
-          [default: 1000]
-
-Logging:
-      --log.stdout.format <FORMAT>
-          The format to use for logs written to stdout
-
-          [default: terminal]
-
-          Possible values:
-          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
-          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
-          - terminal: Represents terminal-friendly formatting for logs
-
-      --log.stdout.filter <FILTER>
-          The filter to use for logs written to stdout
-
-          [default: ]
-
-      --log.file.format <FORMAT>
-          The format to use for logs written to the log file
-
-          [default: terminal]
-
-          Possible values:
-          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
-          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
-          - terminal: Represents terminal-friendly formatting for logs
-
-      --log.file.filter <FILTER>
-          The filter to use for logs written to the log file
-
-          [default: debug]
-
-      --log.file.directory <PATH>
-          The path to put log files in
-
-          [default: <CACHE_DIR>/logs]
-
-      --log.file.max-size <SIZE>
-          The maximum size (in MB) of one log file
-
-          [default: 200]
-
-      --log.file.max-files <COUNT>
-          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled
-
-          [default: 5]
-
-      --log.journald
-          Write logs to journald
-
-      --log.journald.filter <FILTER>
-          The filter to use for logs written to journald
-
-          [default: error]
-
-      --color <COLOR>
-          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting
-
-          [default: always]
-
-          Possible values:
-          - always: Colors on
-          - auto:   Colors on
-          - never:  Colors off
-
-Display:
-  -v, --verbosity...
-          Set the minimum log level.
-
-          -v      Errors
-          -vv     Warnings
-          -vvv    Info
-          -vvvv   Debug
-          -vvvvv  Traces (warning: very verbose!)
-
-  -q, --quiet
-          Silence all log output
-```

book/cli/reth/import-op.md

@@ -1,134 +0,0 @@
-# op-reth import
-
-This syncs RLP encoded blocks from a file. Supports import of OVM blocks
-from the Bedrock datadir. Requires blocks, up to same height as receipts
-file, to already be imported.
-
-```bash
-$ op-reth import-op --help
-Usage: op-reth import-op [OPTIONS] <IMPORT_PATH>
-
-Options:
-      --config <FILE>
-          The path to the configuration file to use.
-
-      --datadir <DATA_DIR>
-          The path to the data dir for all reth files and subdirectories.
-
-          Defaults to the OS-specific data directory:
-
-          - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/`
-          - Windows: `{FOLDERID_RoamingAppData}/reth/`
-          - macOS: `$HOME/Library/Application Support/reth/`
-
-          [default: default]
-
-      --chunk-len <CHUNK_LEN>
-          Chunk byte length to read from file.
-
-          [default: 1GB]
-
-  -h, --help
-          Print help (see a summary with '-h')
-
-Database:
-      --db.log-level <LOG_LEVEL>
-          Database logging level. Levels higher than "notice" require a debug build
-
-          Possible values:
-          - fatal:   Enables logging for critical conditions, i.e. assertion failures
-          - error:   Enables logging for error conditions
-          - warn:    Enables logging for warning conditions
-          - notice:  Enables logging for normal but significant condition
-          - verbose: Enables logging for verbose informational
-          - debug:   Enables logging for debug-level messages
-          - trace:   Enables logging for trace debug-level messages
-          - extra:   Enables logging for extra debug-level messages
-
-      --db.exclusive <EXCLUSIVE>
-          Open environment in exclusive/monopolistic mode. Makes it possible to open a database on an NFS volume
-
-          [possible values: true, false]
-
-  <IMPORT_PATH>
-          The path to a `.rlp` block file for import.
-
-          The online sync pipeline stages (headers and bodies) are replaced by a file import. Skips block execution since blocks below Bedrock are built on OVM.
-
-Logging:
-      --log.stdout.format <FORMAT>
-          The format to use for logs written to stdout
-
-          [default: terminal]
-
-          Possible values:
-          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
-          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
-          - terminal: Represents terminal-friendly formatting for logs
-
-      --log.stdout.filter <FILTER>
-          The filter to use for logs written to stdout
-
-          [default: ]
-
-      --log.file.format <FORMAT>
-          The format to use for logs written to the log file
-
-          [default: terminal]
-
-          Possible values:
-          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
-          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
-          - terminal: Represents terminal-friendly formatting for logs
-
-      --log.file.filter <FILTER>
-          The filter to use for logs written to the log file
-
-          [default: debug]
-
-      --log.file.directory <PATH>
-          The path to put log files in
-
-          [default: <CACHE_DIR>/logs]
-
-      --log.file.max-size <SIZE>
-          The maximum size (in MB) of one log file
-
-          [default: 200]
-
-      --log.file.max-files <COUNT>
-          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled
-
-          [default: 5]
-
-      --log.journald
-          Write logs to journald
-
-      --log.journald.filter <FILTER>
-          The filter to use for logs written to journald
-
-          [default: error]
-
-      --color <COLOR>
-          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting
-
-          [default: always]
-
-          Possible values:
-          - always: Colors on
-          - auto:   Colors on
-          - never:  Colors off
-
-Display:
-  -v, --verbosity...
-          Set the minimum log level.
-
-          -v      Errors
-          -vv     Warnings
-          -vvv    Info
-          -vvvv   Debug
-          -vvvvv  Traces (warning: very verbose!)
-
-  -q, --quiet
-          Silence all log output
-```

book/cli/reth/import-receipts-op.md

@@ -1,133 +0,0 @@
-# op-reth import-receipts-op
-
-This imports non-standard RLP encoded receipts from a file.
-The supported RLP encoding, is the non-standard encoding used
-for receipt export in <https://github.com/testinprod-io/op-geth/pull/1>.
-Supports import of OVM receipts from the Bedrock datadir.
-
-```bash
-$ op-reth import-receipts-op --help
-Usage: op-reth import-receipts-op [OPTIONS] <IMPORT_PATH>
-
-Options:
-      --datadir <DATA_DIR>
-          The path to the data dir for all reth files and subdirectories.
-
-          Defaults to the OS-specific data directory:
-
-          - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/`
-          - Windows: `{FOLDERID_RoamingAppData}/reth/`
-          - macOS: `$HOME/Library/Application Support/reth/`
-
-          [default: default]
-
-      --chunk-len <CHUNK_LEN>
-          Chunk byte length to read from file.
-
-          [default: 1GB]
-
-  -h, --help
-          Print help (see a summary with '-h')
-
-Database:
-      --db.log-level <LOG_LEVEL>
-          Database logging level. Levels higher than "notice" require a debug build
-
-          Possible values:
-          - fatal:   Enables logging for critical conditions, i.e. assertion failures
-          - error:   Enables logging for error conditions
-          - warn:    Enables logging for warning conditions
-          - notice:  Enables logging for normal but significant condition
-          - verbose: Enables logging for verbose informational
-          - debug:   Enables logging for debug-level messages
-          - trace:   Enables logging for trace debug-level messages
-          - extra:   Enables logging for extra debug-level messages
-
-      --db.exclusive <EXCLUSIVE>
-          Open environment in exclusive/monopolistic mode. Makes it possible to open a database on an NFS volume
-
-          [possible values: true, false]
-
-  <IMPORT_PATH>
-          The path to a receipts file for import. File must use `OpGethReceiptFileCodec` (used for
-          exporting OP chain segment below Bedrock block via testinprod/op-geth).
-
-          <https://github.com/testinprod-io/op-geth/pull/1>
-
-Logging:
-      --log.stdout.format <FORMAT>
-          The format to use for logs written to stdout
-
-          [default: terminal]
-
-          Possible values:
-          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
-          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
-          - terminal: Represents terminal-friendly formatting for logs
-
-      --log.stdout.filter <FILTER>
-          The filter to use for logs written to stdout
-
-          [default: ]
-
-      --log.file.format <FORMAT>
-          The format to use for logs written to the log file
-
-          [default: terminal]
-
-          Possible values:
-          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
-          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
-          - terminal: Represents terminal-friendly formatting for logs
-
-      --log.file.filter <FILTER>
-          The filter to use for logs written to the log file
-
-          [default: debug]
-
-      --log.file.directory <PATH>
-          The path to put log files in
-
-          [default: <CACHE_DIR>/logs]
-
-      --log.file.max-size <SIZE>
-          The maximum size (in MB) of one log file
-
-          [default: 200]
-
-      --log.file.max-files <COUNT>
-          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled
-
-          [default: 5]
-
-      --log.journald
-          Write logs to journald
-
-      --log.journald.filter <FILTER>
-          The filter to use for logs written to journald
-
-          [default: error]
-
-      --color <COLOR>
-          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting
-
-          [default: always]
-
-          Possible values:
-          - always: Colors on
-          - auto:   Colors on
-          - never:  Colors off
-
-Display:
-  -v, --verbosity...
-          Set the minimum log level.
-
-          -v      Errors
-          -vv     Warnings
-          -vvv    Info
-          -vvvv   Debug
-          -vvvvv  Traces (warning: very verbose!)
-
-  -q, --quiet
-          Silence all log output
-```

book/cli/reth/test-vectors.md

@@ -1,113 +0,0 @@
-# reth test-vectors
-
-Generate Test Vectors
-
-```bash
-$ reth test-vectors --help
-Usage: reth test-vectors [OPTIONS] <COMMAND>
-
-Commands:
-  tables  Generates test vectors for specified tables. If no table is specified, generate for all
-  help    Print this message or the help of the given subcommand(s)
-
-Options:
-      --chain <CHAIN_OR_PATH>
-          The chain this node is running.
-          Possible values are either a built-in chain or the path to a chain specification file.
-
-          Built-in chains:
-              mainnet, sepolia, holesky, dev
-
-          [default: mainnet]
-
-      --instance <INSTANCE>
-          Add a new instance of a node.
-
-          Configures the ports of the node to avoid conflicts with the defaults. This is useful for running multiple nodes on the same machine.
-
-          Max number of instances is 200. It is chosen in a way so that it's not possible to have port numbers that conflict with each other.
-
-          Changes to the following port numbers: - `DISCOVERY_PORT`: default + `instance` - 1 - `AUTH_PORT`: default + `instance` * 100 - 100 - `HTTP_RPC_PORT`: default - `instance` + 1 - `WS_RPC_PORT`: default + `instance` * 2 - 2
-
-          [default: 1]
-
-  -h, --help
-          Print help (see a summary with '-h')
-
-Logging:
-      --log.stdout.format <FORMAT>
-          The format to use for logs written to stdout
-
-          [default: terminal]
-
-          Possible values:
-          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
-          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
-          - terminal: Represents terminal-friendly formatting for logs
-
-      --log.stdout.filter <FILTER>
-          The filter to use for logs written to stdout
-
-          [default: ]
-
-      --log.file.format <FORMAT>
-          The format to use for logs written to the log file
-
-          [default: terminal]
-
-          Possible values:
-          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
-          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
-          - terminal: Represents terminal-friendly formatting for logs
-
-      --log.file.filter <FILTER>
-          The filter to use for logs written to the log file
-
-          [default: debug]
-
-      --log.file.directory <PATH>
-          The path to put log files in
-
-          [default: <CACHE_DIR>/logs]
-
-      --log.file.max-size <SIZE>
-          The maximum size (in MB) of one log file
-
-          [default: 200]
-
-      --log.file.max-files <COUNT>
-          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled
-
-          [default: 5]
-
-      --log.journald
-          Write logs to journald
-
-      --log.journald.filter <FILTER>
-          The filter to use for logs written to journald
-
-          [default: error]
-
-      --color <COLOR>
-          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting
-
-          [default: always]
-
-          Possible values:
-          - always: Colors on
-          - auto:   Colors on
-          - never:  Colors off
-
-Display:
-  -v, --verbosity...
-          Set the minimum log level.
-
-          -v      Errors
-          -vv     Warnings
-          -vvv    Info
-          -vvvv   Debug
-          -vvvvv  Traces (warning: very verbose!)
-
-  -q, --quiet
-          Silence all log output
-```

book/cli/update.sh

@@ -3,13 +3,18 @@ set -eo pipefail
 
 BOOK_ROOT="$(dirname "$(dirname "$0")")"
 RETH=${1:-"$(dirname "$BOOK_ROOT")/target/debug/reth"}
+VOCS_PAGES_ROOT="$BOOK_ROOT/vocs/docs/pages"
+echo "Generating CLI documentation for reth at $RETH"
 
+echo "Using book root: $BOOK_ROOT"
+echo "Using vocs pages root: $VOCS_PAGES_ROOT"
 cmd=(
   "$(dirname "$0")/help.rs"
   --root-dir "$BOOK_ROOT/"
   --root-indentation 2
   --root-summary
-  --out-dir "$BOOK_ROOT/cli/"
+  --verbose
+  --out-dir "$VOCS_PAGES_ROOT/cli/"
   "$RETH"
 )
 echo "Running: $" "${cmd[*]}"

book/developers/contribute.md

@@ -1,9 +0,0 @@
-# Contribute
-
-<!-- TODO: Add various debugging tips and tricks we use, ways to configure logging, unwinding a node etc. -->
-
-Reth has docs specifically geared for developers and contributors, including documentation on the structure and architecture of reth, the general workflow we employ, and other useful tips.
-
-You can find these docs [here](https://github.com/paradigmxyz/reth/tree/main/docs).
-
-Check out our contributing guidelines [here](https://github.com/paradigmxyz/reth/blob/main/CONTRIBUTING.md).

book/developers/developers.md

@@ -1,3 +0,0 @@
-# Developers
-
-Reth is composed of several crates that can be used in standalone projects. If you are interested in using one or more of the crates, you can get an overview of them in the [developer docs](https://github.com/paradigmxyz/reth/tree/main/docs), or take a look at the [crate docs](https://paradigmxyz.github.io/reth/docs).

book/installation/priorities.md

@@ -1,18 +0,0 @@
-# Update Priorities
-
-When publishing releases, reth will include an "Update Priority" section in the release notes, in the same manner Lighthouse does.
-
-The "Update Priority" section will include a table which may appear like so:
-
-| User Class           | Priority        |
-|----------------------|-----------------|
-| Payload Builders     | Medium Priority |
-| Non-Payload Builders | Low Priority    |
-
-To understand this table, the following terms are important:
-
-- *Payload builders* are those who use reth to build and validate payloads.
-- *Non-payload builders* are those who run reth for other purposes (e.g., data analysis, RPC or applications).
-- *High priority* updates should be completed as soon as possible (e.g., hours or days).
-- *Medium priority* updates should be completed at the next convenience (e.g., days or a week).
-- *Low priority* updates should be completed in the next routine update cycle (e.g., two weeks).

book/run/ports.md

@@ -1,38 +0,0 @@
-# Ports
-
-This section provides essential information about the ports used by the system, their primary purposes, and recommendations for exposure settings.
-
-## Peering Ports
-
-- **Port:** 30303
-- **Protocol:** TCP and UDP
-- **Purpose:** Peering with other nodes for synchronization of blockchain data. Nodes communicate through this port to maintain network consensus and share updated information.
-- **Exposure Recommendation:** This port should be exposed to enable seamless interaction and synchronization with other nodes in the network.
-
-## Metrics Port
-
-- **Port:** 9001
-- **Protocol:** TCP
-- **Purpose:** This port is designated for serving metrics related to the system's performance and operation. It allows internal monitoring and data collection for analysis.
-- **Exposure Recommendation:** By default, this port should not be exposed to the public. It is intended for internal monitoring and analysis purposes.
-
-## HTTP RPC Port
-
-- **Port:** 8545
-- **Protocol:** TCP
-- **Purpose:** Port 8545 provides an HTTP-based Remote Procedure Call (RPC) interface. It enables external applications to interact with the blockchain by sending requests over HTTP.
-- **Exposure Recommendation:** Similar to the metrics port, exposing this port to the public is not recommended by default due to security considerations.
-
-## WS RPC Port
-
-- **Port:** 8546
-- **Protocol:** TCP
-- **Purpose:** Port 8546 offers a WebSocket-based Remote Procedure Call (RPC) interface. It allows real-time communication between external applications and the blockchain.
-- **Exposure Recommendation:** As with the HTTP RPC port, the WS RPC port should not be exposed by default for security reasons.
-
-## Engine API Port
-
-- **Port:** 8551
-- **Protocol:** TCP
-- **Purpose:** Port 8551 facilitates communication between specific components, such as "reth" and "CL" (assuming their definitions are understood within the context of the system). It enables essential internal processes.
-- **Exposure Recommendation:** This port is not meant to be exposed to the public by default. It should be reserved for internal communication between vital components of the system.

book/run/run-a-node.md

@@ -1,15 +0,0 @@
-# Run a Node
-
-Congratulations, now that you have installed Reth, it's time to run it!
-
-In this chapter we'll go through a few different topics you'll encounter when running Reth, including:
-1. [Running on mainnet or official testnets](./mainnet.md)
-1. [Running on OP Stack chains](./optimism.md)
-1. [Logs and Observability](./observability.md)
-1. [Configuring reth.toml](./config.md)
-1. [Transaction types](./transactions.md)
-1. [Pruning & Full Node](./pruning.md)
-1. [Ports](./ports.md)
-1. [Troubleshooting](./troubleshooting.md)
-
-In the future, we also intend to support the [OP Stack](https://docs.optimism.io/get-started/superchain), which will allow you to run Reth as a Layer 2 client. More there soon!

book/sources/Cargo.toml

@@ -1,13 +0,0 @@
-[workspace]
-members = ["exex/hello-world", "exex/remote", "exex/tracking-state"]
-
-# Explicitly set the resolver to version 2, which is the default for packages with edition >= 2021
-# https://doc.rust-lang.org/edition-guide/rust-2021/default-cargo-resolver.html
-resolver = "2"
-
-[patch.'https://github.com/paradigmxyz/reth']
-reth = { path = "../../bin/reth" }
-reth-exex = { path = "../../crates/exex/exex" }
-reth-node-ethereum = { path = "../../crates/ethereum/node" }
-reth-tracing = { path = "../../crates/tracing" }
-reth-node-api = { path = "../../crates/node/api" }

book/templates/source_and_github.md

@@ -1,4 +0,0 @@
-[File: [[ #path ]]](https://github.com/paradigmxyz/reth/blob/main/[[ #path ]])
-```rust,no_run,noplayground
-{{#include [[ #path_to_root ]][[ #path ]]:[[ #anchor ]]}}
-```

book/theme/head.hbs

@@ -1,5 +0,0 @@
-<meta name="twitter:card" content="summary">
-<meta property="og:title" content="Reth Book" />
-<meta property="og:description" content="The Reth Book contains all information about using Reth as an infrastructure node operator." />
-<meta name="twitter:image:src" content="https://raw.githubusercontent.com/paradigmxyz/reth/main/assets/reth-prod.png" />
-<meta property="og:image" content="https://raw.githubusercontent.com/paradigmxyz/reth/main/assets/reth-prod.png" />

book/vocs/CLAUDE.md

@@ -0,0 +1,103 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is the **Reth documentation website** built with [Vocs](https://vocs.dev), a modern documentation framework. The site contains comprehensive documentation for Reth, the Ethereum execution client, including installation guides, CLI references, SDK documentation, and tutorials.
+
+## Repository Structure
+
+- **`docs/pages/`**: All documentation content in MDX format
+  - `cli/`: Command-line interface documentation and references
+  - `exex/`: Execution Extensions (ExEx) guides and examples
+  - `installation/`: Installation and setup guides
+  - `introduction/`: Introduction, benchmarks, and why-reth content
+  - `jsonrpc/`: JSON-RPC API documentation
+  - `run/`: Node running guides and configuration
+  - `sdk/`: SDK documentation and examples
+- **`docs/snippets/`**: Code examples and snippets used in documentation
+- **`sidebar.ts`**: Navigation configuration
+- **`vocs.config.ts`**: Vocs configuration file
+
+## Essential Commands
+
+```bash
+# Install dependencies
+bun install
+
+# Start development server
+bun run dev
+
+# Build for production
+bun run build
+
+# Preview production build
+bun run preview
+```
+
+## Development Workflow
+
+### Content Organization
+
+1. **MDX Files**: All content is written in MDX (Markdown + React components)
+2. **Navigation**: Update `sidebar.ts` when adding new pages
+3. **Code Examples**: Place reusable code snippets in `docs/snippets/`
+4. **Assets**: Place images and static assets in `docs/public/`
+
+### Adding New Documentation
+
+1. Create new `.mdx` files in appropriate subdirectories under `docs/pages/`
+2. Update `sidebar.ts` to include new pages in navigation
+3. Use consistent heading structure and markdown formatting
+4. Reference code examples from `docs/snippets/` when possible
+
+### Code Examples and Snippets
+
+- **Live Examples**: Use the snippets system to include actual runnable code
+- **Rust Code**: Include cargo project examples in `docs/snippets/sources/`
+- **CLI Examples**: Show actual command usage with expected outputs
+
+### Configuration
+
+- **Base Path**: Site deploys to `/reth` path (configured in `vocs.config.ts`)
+- **Theme**: Custom accent colors for light/dark themes
+- **Vite**: Uses Vite as the underlying build tool
+
+### Content Guidelines
+
+1. **Be Practical**: Focus on actionable guides and real-world examples
+2. **Code First**: Show working code examples before explaining concepts
+3. **Consistent Structure**: Follow existing page structures for consistency
+4. **Cross-References**: Link between related pages and sections
+5. **Keep Current**: Ensure documentation matches latest Reth features
+
+### File Naming Conventions
+
+- Use kebab-case for file and directory names
+- Match URL structure to file structure
+- Use descriptive names that reflect content purpose
+
+### Common Tasks
+
+**Adding a new CLI command documentation:**
+1. Create `.mdx` file in `docs/pages/cli/reth/`
+2. Add to sidebar navigation
+3. Include usage examples and parameter descriptions
+
+**Adding a new guide:**
+1. Create `.mdx` file in appropriate category
+2. Update sidebar with new entry
+3. Include practical examples and next steps
+
+**Updating code examples:**
+1. Modify files in `docs/snippets/sources/`
+2. Ensure examples compile and run correctly
+3. Test that documentation references work properly
+
+## Development Notes
+
+- This is a TypeScript/React project using Vocs framework
+- Content is primarily MDX with some TypeScript configuration
+- Focus on clear, practical documentation that helps users succeed with Reth
+- Maintain consistency with existing documentation style and structure

book/vocs/README.md

@@ -0,0 +1 @@
+This is a [Vocs](https://vocs.dev) project bootstrapped with the Vocs CLI.

book/vocs/check-links.ts

@@ -0,0 +1,316 @@
+#!/usr/bin/env bun
+import { Glob } from "bun";
+import { readFileSync } from "node:fs";
+import { join, dirname, resolve, relative } from "node:path";
+
+const CONFIG = {
+	DOCS_DIR: "./docs/pages",
+	PUBLIC_DIR: "./docs/public",
+	REPORT_PATH: "links-report.json",
+	FILE_PATTERNS: "**/*.{md,mdx}",
+	MARKDOWN_EXTENSIONS: /\.(md|mdx)$/,
+} as const;
+
+interface BrokenLink {
+	file: string;
+	link: string;
+	line: number;
+	reason: string;
+}
+
+interface LinkCheckReport {
+	timestamp: string;
+	totalFiles: number;
+	totalLinks: number;
+	brokenLinks: Array<BrokenLink>;
+	summary: {
+		brokenCount: number;
+		validCount: number;
+	};
+}
+
+main();
+
+async function main() {
+	try {
+		const report = await checkLinks();
+		await saveReport(report);
+		displayResults(report);
+
+		process.exit(report.summary.brokenCount > 0 ? 1 : 0);
+	} catch (error) {
+		console.error("\n❌ Fatal error during link checking:");
+
+		if (error instanceof Error) {
+			console.error(`   ${error.message}`);
+			if (error.stack) {
+				[console.error("\nStack trace:"), console.error(error.stack)];
+			}
+		} else console.error(error);
+
+		process.exit(2);
+	}
+}
+
+async function checkLinks(): Promise<LinkCheckReport> {
+	console.log("🔍 Finding markdown files...");
+	const files = await getAllMarkdownFiles();
+	console.log(`📄 Found ${files.length} markdown files`);
+
+	console.log("🔍 Finding public assets...");
+	const publicAssets = await getAllPublicAssets();
+	console.log(`🖼️  Found ${publicAssets.length} public assets`);
+
+	console.log("🗺️  Building file path map...");
+	const pathMap = buildFilePathMap(files, publicAssets);
+	console.log(`📍 Mapped ${pathMap.size} possible paths`);
+
+	const brokenLinks: BrokenLink[] = [];
+	let totalLinks = 0;
+
+	console.log("🔗 Checking links in files...");
+
+	for (let index = 0; index < files.length; index++) {
+		const file = files[index];
+
+		try {
+			const content = readFileSync(file, "utf-8");
+			const links = extractLinksFromMarkdown(content);
+
+			for (const { link, line } of links) {
+				totalLinks++;
+				const error = validateLink(link, file, pathMap);
+
+				if (error) {
+					brokenLinks.push({
+						file: relative(process.cwd(), file),
+						link,
+						line,
+						reason: error,
+					});
+				}
+			}
+		} catch (error) {
+			console.error(`\nError reading ${file}:`, error);
+		}
+	}
+
+	console.log("\n✅ Link checking complete!");
+
+	return {
+		timestamp: new Date().toISOString(),
+		totalFiles: files.length,
+		totalLinks,
+		brokenLinks,
+		summary: {
+			brokenCount: brokenLinks.length,
+			validCount: totalLinks - brokenLinks.length,
+		},
+	};
+}
+
+async function getAllMarkdownFiles(): Promise<string[]> {
+	const glob = new Glob(CONFIG.FILE_PATTERNS);
+	const files = await Array.fromAsync(glob.scan({ cwd: CONFIG.DOCS_DIR }));
+	return files.map((file) => join(CONFIG.DOCS_DIR, file));
+}
+
+async function getAllPublicAssets(): Promise<string[]> {
+	const glob = new Glob("**/*");
+	const files = await Array.fromAsync(glob.scan({ cwd: CONFIG.PUBLIC_DIR }));
+	return files;
+}
+
+function buildFilePathMap(
+	files: Array<string>,
+	publicAssets: Array<string>,
+): Set<string> {
+	const pathMap = new Set<string>();
+
+	const addPath = (path: string) => {
+		if (path && typeof path === "string") pathMap.add(path);
+	};
+
+	for (const file of files) {
+		const relativePath = relative(CONFIG.DOCS_DIR, file);
+
+		addPath(relativePath);
+
+		const withoutExt = relativePath.replace(CONFIG.MARKDOWN_EXTENSIONS, "");
+		addPath(withoutExt);
+
+		if (withoutExt.endsWith("/index"))
+			addPath(withoutExt.replace("/index", ""));
+
+		addPath(`/${withoutExt}`);
+		if (withoutExt.endsWith("/index"))
+			addPath(`/${withoutExt.replace("/index", "")}`);
+	}
+
+	for (const asset of publicAssets) addPath(`/${asset}`);
+
+	return pathMap;
+}
+
+function extractLinksFromMarkdown(
+	content: string,
+): Array<{ link: string; line: number }> {
+	const lines = content.split("\n");
+	const links: Array<{ link: string; line: number }> = [];
+	let inCodeBlock = false;
+
+	for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+		const line = lines[lineIndex];
+		const lineNumber = lineIndex + 1;
+
+		// Toggle code block state
+		if (line.trim().startsWith("```")) {
+			inCodeBlock = !inCodeBlock;
+			continue;
+		}
+
+		if (inCodeBlock) continue;
+
+		const processedLine = line
+			.split("`")
+			.filter((_, index) => index % 2 === 0)
+			.join("");
+
+		links.push(...extractMarkdownLinks(processedLine, lineNumber));
+		links.push(...extractHtmlLinks(processedLine, lineNumber));
+	}
+
+	return links;
+}
+
+function extractMarkdownLinks(
+	line: string,
+	lineNumber: number,
+): Array<{ link: string; line: number }> {
+	const regex = /\[([^\]]*)\]\(([^)]+)\)/g;
+	return [...line.matchAll(regex)]
+		.map(([, , url]) => ({ link: url, line: lineNumber }))
+		.filter(({ link }) => isInternalLink(link));
+}
+
+function extractHtmlLinks(
+	line: string,
+	lineNumber: number,
+): Array<{ link: string; line: number }> {
+	const regex = /<a[^>]+href=["']([^"']+)["'][^>]*>/g;
+	return [...line.matchAll(regex)]
+		.map(([, url]) => ({ link: url, line: lineNumber }))
+		.filter(({ link }) => isInternalLink(link));
+}
+
+function isInternalLink(url: string): boolean {
+	return (
+		!url.startsWith("http") &&
+		!url.startsWith("mailto:") &&
+		!url.startsWith("#")
+	);
+}
+
+function validateLink(
+	link: string,
+	sourceFile: string,
+	pathMap: Set<string>,
+): string | null {
+	const [linkPath] = link.split("#");
+	if (!linkPath) return null; // Pure anchor link
+
+	if (linkPath.startsWith("/")) return validateAbsolutePath(linkPath, pathMap);
+	return validateRelativePath(linkPath, sourceFile, pathMap);
+}
+
+function validateAbsolutePath(
+	linkPath: string,
+	pathMap: Set<string>,
+): string | null {
+	const variations = [
+		linkPath,
+		linkPath.slice(1), // Remove leading slash
+		linkPath.replace(/\/$/, ""), // Remove trailing slash
+		linkPath
+			.slice(1)
+			.replace(/\/$/, ""), // Remove both
+	];
+
+	return variations.some((path) => pathMap.has(path))
+		? null
+		: `Absolute path not found: ${linkPath}`;
+}
+
+function validateRelativePath(
+	linkPath: string,
+	sourceFile: string,
+	pathMap: Set<string>,
+): string | null {
+	const sourceDir = dirname(relative(CONFIG.DOCS_DIR, sourceFile));
+	const resolvedPath = resolve(sourceDir, linkPath);
+	const normalizedPath = relative(".", resolvedPath);
+
+	const variations = [
+		linkPath,
+		normalizedPath,
+		`/${normalizedPath}`,
+		normalizedPath.replace(CONFIG.MARKDOWN_EXTENSIONS, ""),
+		`/${normalizedPath.replace(CONFIG.MARKDOWN_EXTENSIONS, "")}`,
+	];
+
+	return variations.some((path) => pathMap.has(path))
+		? null
+		: `Relative path not found: ${linkPath} (resolved to: ${normalizedPath})`;
+}
+
+async function saveReport(report: LinkCheckReport) {
+	try {
+		await Bun.write(CONFIG.REPORT_PATH, JSON.stringify(report, null, 2));
+		console.log(`\n📝 Report saved to: ${CONFIG.REPORT_PATH}`);
+	} catch (error) {
+		console.error(
+			`\n⚠️  Warning: Failed to save report to ${CONFIG.REPORT_PATH}`,
+		);
+		console.error(error);
+	}
+}
+
+function displayResults(report: LinkCheckReport) {
+	LinkCheckReporter.printSummary(report);
+
+	if (report.brokenLinks.length > 0)
+		LinkCheckReporter.printBrokenLinks(report.brokenLinks);
+	else console.log("\n✅ All links are valid!");
+}
+
+const LinkCheckReporter = {
+	printSummary: (report: LinkCheckReport) => {
+		console.log("\n📊 Link Check Summary:");
+		console.log(`   📄 Files checked: ${report.totalFiles}`);
+		console.log(`   🔗 Total links: ${report.totalLinks}`);
+		console.log(`   ✅ Valid links: ${report.summary.validCount}`);
+		console.log(`   ❌ Broken links: ${report.summary.brokenCount}`);
+	},
+	printBrokenLinks: (brokenLinks: Array<BrokenLink>) => {
+		if (brokenLinks.length === 0) return;
+
+		console.log("\n❌ Broken Links Found:\n");
+
+		const byFile = brokenLinks.reduce(
+			(acc, broken) => {
+				if (!acc[broken.file]) acc[broken.file] = [];
+				acc[broken.file].push(broken);
+				return acc;
+			},
+			{} as Record<string, BrokenLink[]>,
+		);
+
+		for (const [file, links] of Object.entries(byFile)) {
+			console.log(`📄 ${file}:`);
+			for (const broken of links) {
+				console.log(`   Line ${broken.line}: ${broken.link}`);
+				console.log(`   └─ ${broken.reason}\n`);
+			}
+		}
+	},
+};

book/vocs/docs/components/SdkShowcase.tsx

@@ -0,0 +1,88 @@
+import React from 'react'
+
+interface SdkProject {
+  name: string
+  description: string
+  loc: string
+  githubUrl: string
+  logoUrl?: string
+  company: string
+}
+
+const projects: SdkProject[] = [
+  {
+    name: 'Base Node',
+    description: "Coinbase's L2 scaling solution node implementation",
+    loc: '~3K',
+    githubUrl: 'https://github.com/base/node-reth',
+    company: 'Coinbase'
+  },
+  {
+    name: 'Bera Reth',
+    description: "Berachain's high-performance EVM node with custom features",
+    loc: '~1K',
+    githubUrl: 'https://github.com/berachain/bera-reth',
+    company: 'Berachain'
+  },
+  {
+    name: 'Reth Gnosis',
+    description: "Gnosis Chain's xDai-compatible execution client",
+    loc: '~5K',
+    githubUrl: 'https://github.com/gnosischain/reth_gnosis',
+    company: 'Gnosis'
+  },
+  {
+    name: 'Reth BSC',
+    description: "BNB Smart Chain execution client implementation",
+    loc: '~6K',
+    githubUrl: 'https://github.com/loocapro/reth-bsc',
+    company: 'Binance Smart Chain'
+  }
+]
+
+export function SdkShowcase() {
+  return (
+    <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
+      {projects.map((project, index) => (
+        <div
+          key={index}
+          className="relative bg-white/5 dark:bg-white/5 border border-black/10 dark:border-white/10 rounded-xl p-6 hover:bg-black/5 dark:hover:bg-white/10 transition-colors group"
+        >
+          {/* LoC Badge */}
+          <div className="absolute top-4 right-4 bg-black/10 dark:bg-white/10 text-black dark:text-white px-3 py-1 rounded-full text-sm font-medium">
+            {project.loc} LoC
+          </div>
+          
+          {/* Content */}
+          <div className="space-y-3">
+            <div>
+              <h3 className="text-xl font-semibold text-black dark:text-white mb-1">
+                {project.name}
+              </h3>
+              <p className="text-sm text-gray-600 dark:text-gray-400">
+                {project.company}
+              </p>
+            </div>
+            
+            <p className="text-gray-700 dark:text-gray-300 text-sm leading-relaxed">
+              {project.description}
+            </p>
+            
+            {/* GitHub Link */}
+            <a
+              href={project.githubUrl}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="inline-flex items-center gap-2 text-sm text-black dark:text-white hover:text-gray-700 dark:hover:text-gray-300 font-medium transition-colors"
+            >
+              <svg className="w-4 h-4" fill="currentColor" viewBox="0 0 24 24">
+                <path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/>
+              </svg>
+              View on GitHub
+            </a>
+          </div>
+        </div>
+      ))}
+    </div>
+  )
+}

book/vocs/docs/components/TrustedBy.tsx

@@ -0,0 +1,49 @@
+import React from 'react'
+
+interface TrustedCompany {
+  name: string
+  logoUrl: string
+}
+
+const companies: TrustedCompany[] = [
+  {
+    name: 'Flashbots',
+    logoUrl: '/flashbots.png'
+  },
+  {
+    name: 'Coinbase',
+    logoUrl: '/coinbase.png'
+  },
+  {
+    name: 'Alchemy',
+    logoUrl: '/alchemy.png'
+  },
+  {
+    name: 'Succinct Labs',
+    logoUrl: '/succinct.png'
+  }
+]
+
+export function TrustedBy() {
+  return (
+    <div className="grid grid-cols-2 md:grid-cols-4 gap-6">
+      {companies.map((company, index) => (
+        <div
+          key={index}
+          className="relative bg-white/5 dark:bg-white/5 border border-black/10 dark:border-white/10 rounded-xl p-8 hover:bg-black/5 dark:hover:bg-white/10 transition-colors flex flex-col items-center justify-center h-40 group"
+        >
+          {/* Company Logo */}
+          <div className={`flex items-center justify-center ${
+            company.name === 'Coinbase' || company.name === 'Alchemy' ? 'w-32 h-32' : 'w-24 h-24'
+          }`}>
+            <img
+              src={company.logoUrl}
+              alt={`${company.name} logo`}
+              className="max-w-full max-h-full object-contain"
+            />
+          </div>
+        </div>
+      ))}
+    </div>
+  )
+}

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

@@ -0,0 +1,47 @@
+- [`reth`](/cli/reth)
+  - [`reth node`](/cli/reth/node)
+  - [`reth init`](/cli/reth/init)
+  - [`reth init-state`](/cli/reth/init-state)
+  - [`reth import`](/cli/reth/import)
+  - [`reth import-era`](/cli/reth/import-era)
+  - [`reth dump-genesis`](/cli/reth/dump-genesis)
+  - [`reth db`](/cli/reth/db)
+    - [`reth db stats`](/cli/reth/db/stats)
+    - [`reth db list`](/cli/reth/db/list)
+    - [`reth db checksum`](/cli/reth/db/checksum)
+    - [`reth db diff`](/cli/reth/db/diff)
+    - [`reth db get`](/cli/reth/db/get)
+      - [`reth db get mdbx`](/cli/reth/db/get/mdbx)
+      - [`reth db get static-file`](/cli/reth/db/get/static-file)
+    - [`reth db drop`](/cli/reth/db/drop)
+    - [`reth db clear`](/cli/reth/db/clear)
+      - [`reth db clear mdbx`](/cli/reth/db/clear/mdbx)
+      - [`reth db clear static-file`](/cli/reth/db/clear/static-file)
+    - [`reth db version`](/cli/reth/db/version)
+    - [`reth db path`](/cli/reth/db/path)
+  - [`reth download`](/cli/reth/download)
+  - [`reth stage`](/cli/reth/stage)
+    - [`reth stage run`](/cli/reth/stage/run)
+    - [`reth stage drop`](/cli/reth/stage/drop)
+    - [`reth stage dump`](/cli/reth/stage/dump)
+      - [`reth stage dump execution`](/cli/reth/stage/dump/execution)
+      - [`reth stage dump storage-hashing`](/cli/reth/stage/dump/storage-hashing)
+      - [`reth stage dump account-hashing`](/cli/reth/stage/dump/account-hashing)
+      - [`reth stage dump merkle`](/cli/reth/stage/dump/merkle)
+    - [`reth stage unwind`](/cli/reth/stage/unwind)
+      - [`reth stage unwind to-block`](/cli/reth/stage/unwind/to-block)
+      - [`reth stage unwind num-blocks`](/cli/reth/stage/unwind/num-blocks)
+  - [`reth p2p`](/cli/reth/p2p)
+    - [`reth p2p header`](/cli/reth/p2p/header)
+    - [`reth p2p body`](/cli/reth/p2p/body)
+    - [`reth p2p rlpx`](/cli/reth/p2p/rlpx)
+      - [`reth p2p rlpx ping`](/cli/reth/p2p/rlpx/ping)
+  - [`reth config`](/cli/reth/config)
+  - [`reth debug`](/cli/reth/debug)
+    - [`reth debug execution`](/cli/reth/debug/execution)
+    - [`reth debug merkle`](/cli/reth/debug/merkle)
+    - [`reth debug in-memory-merkle`](/cli/reth/debug/in-memory-merkle)
+    - [`reth debug build-block`](/cli/reth/debug/build-block)
+  - [`reth recover`](/cli/reth/recover)
+    - [`reth recover storage-tries`](/cli/reth/recover/storage-tries)
+  - [`reth prune`](/cli/reth/prune)

book/vocs/docs/pages/cli/cli.mdx

@@ -1,7 +1,9 @@
+import Summary from './SUMMARY.mdx';
+
 # CLI Reference
 
 The Reth node is operated via the CLI by running the `reth node` command. To stop it, press `ctrl-c`. You may need to wait a bit as Reth tears down existing p2p connections or other cleanup tasks.
 
 However, Reth has more commands:
 
-{{#include ./SUMMARY.md}}
+<Summary />

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

@@ -247,6 +247,9 @@ RPC:
 
           [default: 8545]
 
+      --http.disable-compression
+          Disable compression for HTTP responses
+
       --http.api <HTTP_API>
           Rpc Modules to be configured for the HTTP server
 
@@ -718,6 +721,15 @@ Pruning:
       --prune.storagehistory.before <BLOCK_NUMBER>
           Prune storage history before the specified block number. The specified block number is not pruned
 
+      --prune.bodies.pre-merge
+          Prune bodies before the merge block
+
+      --prune.bodies.distance <BLOCKS>
+          Prune bodies before the `head-N` block number. In other words, keep last N + 1 blocks
+
+      --prune.bodies.before <BLOCK_NUMBER>
+          Prune storage history before the specified block number. The specified block number is not pruned
+
 Engine:
       --engine.persistence-threshold <PERSISTENCE_THRESHOLD>
           Configure persistence threshold for engine experimental
@@ -732,9 +744,6 @@ Engine:
       --engine.legacy-state-root
           Enable legacy state root
 
-      --engine.caching-and-prewarming
-          CAUTION: This CLI flag has no effect anymore, use --engine.disable-caching-and-prewarming if you want to disable caching and prewarming
-
       --engine.disable-caching-and-prewarming
           Disable cross-block caching and parallel prewarming
 
@@ -762,8 +771,31 @@ Engine:
 
           [default: 1]
 
-      --engine.precompile-cache
-          Enable precompile cache
+      --engine.disable-precompile-cache
+          Disable precompile cache
+
+      --engine.state-root-fallback
+          Enable state root fallback, useful for testing
+
+      --engine.always-process-payload-attributes-on-canonical-head
+          Always process payload attributes and begin a payload build process even if `forkchoiceState.headBlockHash` is already the canonical head or an ancestor. See `TreeConfig::always_process_payload_attributes_on_canonical_head` for more details.
+
+          Note: This is a no-op on OP Stack.
+
+ERA:
+      --era.enable
+          Enable import from ERA1 files
+
+      --era.path <ERA_PATH>
+          The path to a directory for import.
+
+          The ERA1 files are read from the local directory parsing headers and bodies.
+
+      --era.url <ERA_URL>
+          The URL to a remote host where the ERA1 files are hosted.
+
+          The ERA1 files are read from the remote host using HTTP GET requests parsing headers
+          and bodies.
 
 Ress:
       --ress.enable