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>

.gitattributes

@@ -1,4 +1,4 @@
 book/cli/**/*.md linguist-vendored
 book/cli/cli.md -linguist-vendored
 
-crates/storage/libmdbx-rs/mdbx-sys/** linguist-vendored
+crates/storage/libmdbx-rs/mdbx-sys/libmdbx/** linguist-vendored

.github/CODEOWNERS

@@ -1,18 +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/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
@@ -23,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
@@ -43,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_rv32imac.sh

@@ -4,9 +4,11 @@ set +e  # Disable immediate exit on error
 # Array of crates to check
 crates_to_check=(
     reth-codecs-derive
+    reth-primitives
     reth-primitives-traits
     reth-network-peers
     reth-trie-common
+    reth-trie-sparse
     reth-chainspec
     reth-consensus
     reth-consensus-common
@@ -14,15 +16,19 @@ crates_to_check=(
     reth-static-file-types
     reth-storage-errors
     reth-execution-errors
+    reth-errors
     reth-execution-types
     reth-db-models
     reth-evm
+    reth-revm
     reth-storage-api
 
     ## ethereum
     reth-evm-ethereum
     reth-ethereum-forks
     reth-ethereum-primitives
+    reth-ethereum-consensus
+    reth-stateless
 
     ## optimism
     reth-optimism-chainspec

.github/assets/check_wasm.sh

@@ -44,7 +44,6 @@ exclude_crates=(
   reth-optimism-payload-builder
   reth-optimism-rpc
   reth-optimism-storage
-  reth-optimism-chain-registry
   reth-rpc
   reth-rpc-api
   reth-rpc-api-testing-util
@@ -59,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
@@ -70,8 +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/build_simulators.sh

@@ -11,7 +11,7 @@ go build .
 
 # Run each hive command in the background for each simulator and wait
 echo "Building images"
-./hive -client reth --sim "ethereum/eest" --sim.buildarg fixtures=https://github.com/ethereum/execution-spec-tests/releases/download/pectra-devnet-6%40v1.0.0/fixtures_pectra-devnet-6.tar.gz -sim.timelimit 1s || true &
+./hive -client reth --sim "ethereum/eest" --sim.buildarg fixtures=https://github.com/ethereum/execution-spec-tests/releases/download/v4.4.0/fixtures_develop.tar.gz --sim.buildarg branch=v4.4.0 -sim.timelimit 1s || true &
 ./hive -client reth --sim "ethereum/engine" -sim.timelimit 1s || true &
 ./hive -client reth --sim "devp2p" -sim.timelimit 1s || true &
 ./hive -client reth --sim "ethereum/rpc-compat" -sim.timelimit 1s || true &
@@ -20,18 +20,21 @@ echo "Building images"
 ./hive -client reth --sim "ethereum/sync" -sim.timelimit 1s || true &
 wait
 
-# Run docker save in parallel and wait
+# Run docker save in parallel, wait and exit on error
 echo "Saving images"
-docker save hive/hiveproxy:latest -o ../hive_assets/hiveproxy.tar &
-docker save hive/simulators/devp2p:latest -o ../hive_assets/devp2p.tar &
-docker save hive/simulators/ethereum/engine:latest -o ../hive_assets/engine.tar &
-docker save hive/simulators/ethereum/rpc-compat:latest -o ../hive_assets/rpc_compat.tar &
-docker save hive/simulators/ethereum/eest/consume-engine:latest -o ../hive_assets/eest_engine.tar &
-docker save hive/simulators/ethereum/eest/consume-rlp:latest -o ../hive_assets/eest_rlp.tar &
-docker save hive/simulators/smoke/genesis:latest -o ../hive_assets/smoke_genesis.tar &
-docker save hive/simulators/smoke/network:latest -o ../hive_assets/smoke_network.tar &
-docker save hive/simulators/ethereum/sync:latest -o ../hive_assets/ethereum_sync.tar &
-wait
+saving_pids=( )
+docker save hive/hiveproxy:latest -o ../hive_assets/hiveproxy.tar & saving_pids+=( $! )
+docker save hive/simulators/devp2p:latest -o ../hive_assets/devp2p.tar & saving_pids+=( $! )
+docker save hive/simulators/ethereum/engine:latest -o ../hive_assets/engine.tar & saving_pids+=( $! )
+docker save hive/simulators/ethereum/rpc-compat:latest -o ../hive_assets/rpc_compat.tar & saving_pids+=( $! )
+docker save hive/simulators/ethereum/eest/consume-engine:latest -o ../hive_assets/eest_engine.tar & saving_pids+=( $! )
+docker save hive/simulators/ethereum/eest/consume-rlp:latest -o ../hive_assets/eest_rlp.tar & saving_pids+=( $! )
+docker save hive/simulators/smoke/genesis:latest -o ../hive_assets/smoke_genesis.tar & saving_pids+=( $! )
+docker save hive/simulators/smoke/network:latest -o ../hive_assets/smoke_network.tar & saving_pids+=( $! )
+docker save hive/simulators/ethereum/sync:latest -o ../hive_assets/ethereum_sync.tar & saving_pids+=( $! )
+for pid in "${saving_pids[@]}"; do
+    wait "$pid" || exit
+done
 
 # Make sure we don't rebuild images on the CI jobs
 git apply ../.github/assets/hive/no_sim_build.diff

.github/assets/hive/expected_failures.yaml

@@ -1,4 +1,4 @@
-# https://github.com/paradigmxyz/reth/issues/13879
+# tracked by https://github.com/paradigmxyz/reth/issues/13879
 rpc-compat:
   - debug_getRawBlock/get-invalid-number (reth)
   - debug_getRawHeader/get-invalid-number (reth)
@@ -16,7 +16,11 @@ rpc-compat:
   - eth_getTransactionReceipt/get-legacy-input (reth)
   - eth_getTransactionReceipt/get-legacy-receipt (reth)
 
-# https://github.com/paradigmxyz/reth/issues/8732
+  # 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)
   - Withdrawals Fork on Block 1 (Paris) (reth)
@@ -29,29 +33,78 @@ engine-withdrawals:
   - Empty Withdrawals (Paris) (reth)
   - Corrupted Block Hash Payload (INVALID) (Paris) (reth)
   - Withdrawals Fork on Block 1 - 8 Block Re-Org NewPayload (Paris) (reth)
-  - Withdrawals Fork on Block 1 - 8 Block Re-Org, Sync (Paris) (reth)
-  - Withdrawals Fork on Block 8 - 10 Block Re-Org NewPayload (Paris) (reth)
-  - Withdrawals Fork on Block 8 - 10 Block Re-Org Sync (Paris) (reth)
   - Withdrawals Fork on Canonical Block 8 / Side Block 7 - 10 Block Re-Org (Paris) (reth)
-  - Withdrawals Fork on Canonical Block 8 / Side Block 7 - 10 Block Re-Org Sync (Paris) (reth)
-  - Withdrawals Fork on Canonical Block 8 / Side Block 9 - 10 Block Re-Org (Paris) (reth)
-  - Withdrawals Fork on Canonical Block 8 / Side Block 9 - 10 Block Re-Org Sync (Paris) (reth)
 
 engine-api: []
 
-# https://github.com/paradigmxyz/reth/issues/8305
-# https://github.com/paradigmxyz/reth/issues/6217
-# https://github.com/paradigmxyz/reth/issues/8306
-# https://github.com/paradigmxyz/reth/issues/7144
+# no fix due to https://github.com/paradigmxyz/reth/issues/8732
 engine-cancun:
-  - Blob Transaction Ordering, Multiple Clients (Cancun) (reth)
   - 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: []
 
-# no fix: it’s too expensive to check whether the storage is empty on each creation
+# https://github.com/ethereum/hive/issues/1277
+engine-auth:
+  - "JWT Authentication: No time drift, correct secret (Paris) (reth)"
+  - "JWT Authentication: Negative time drift, within limit, correct secret (Paris) (reth)"
+  - "JWT Authentication: Positive time drift, within limit, correct secret (Paris) (reth)"
+
+# 7702 test - no fix: it’s too expensive to check whether the storage is empty on each creation
+# 6110 related tests - may start passing when fixtures improve
+# 7002 related tests - post-fork test, should fix for spec compliance but not
+# realistic on mainnet
+# 7251 related tests - modified contract, not necessarily practical on mainnet,
+# worth re-visiting when more of these related tests are passing
 eest/consume-engine:
   - tests/prague/eip7702_set_code_tx/test_set_code_txs.py::test_set_code_to_non_empty_storage[fork_Prague-blockchain_test_engine-zero_nonce]-reth
+  - tests/prague/eip7251_consolidations/test_modified_consolidation_contract.py::test_system_contract_errors[fork_Prague-blockchain_test_engine-system_contract_reaches_gas_limit-system_contract_0x0000bbddc7ce488642fb579f8b00f3a590007251]-reth
+  - tests/prague/eip7251_consolidations/test_contract_deployment.py::test_system_contract_deployment[fork_CancunToPragueAtTime15k-blockchain_test_engine-deploy_after_fork-nonzero_balance]-reth
+  - tests/prague/eip7251_consolidations/test_contract_deployment.py::test_system_contract_deployment[fork_CancunToPragueAtTime15k-blockchain_test_engine-deploy_after_fork-zero_balance]-reth
+  - tests/prague/eip6110_deposits/test_modified_contract.py::test_invalid_layout[fork_Prague-blockchain_test_engine-log_argument_amount_offset-value_zero]-reth
+  - tests/prague/eip6110_deposits/test_modified_contract.py::test_invalid_layout[fork_Prague-blockchain_test_engine-log_argument_amount_size-value_zero]-reth
+  - tests/prague/eip6110_deposits/test_modified_contract.py::test_invalid_layout[fork_Prague-blockchain_test_engine-log_argument_index_offset-value_zero]-reth
+  - tests/prague/eip6110_deposits/test_modified_contract.py::test_invalid_layout[fork_Prague-blockchain_test_engine-log_argument_index_size-value_zero]-reth
+  - tests/prague/eip6110_deposits/test_modified_contract.py::test_invalid_layout[fork_Prague-blockchain_test_engine-log_argument_pubkey_offset-value_zero]-reth
+  - tests/prague/eip7002_el_triggerable_withdrawals/test_modified_withdrawal_contract.py::test_system_contract_errors[fork_Prague-blockchain_test_engine-system_contract_reaches_gas_limit-system_contract_0x00000961ef480eb55e80d19ad83579a64c007002]-reth
+  - tests/prague/eip6110_deposits/test_modified_contract.py::test_invalid_layout[fork_Prague-blockchain_test_engine-log_argument_pubkey_size-value_zero]-reth
+  - tests/prague/eip6110_deposits/test_modified_contract.py::test_invalid_layout[fork_Prague-blockchain_test_engine-log_argument_signature_offset-value_zero]-reth
+  - tests/prague/eip6110_deposits/test_modified_contract.py::test_invalid_layout[fork_Prague-blockchain_test_engine-log_argument_signature_size-value_zero]-reth
+  - tests/prague/eip6110_deposits/test_modified_contract.py::test_invalid_layout[fork_Prague-blockchain_test_engine-log_argument_withdrawal_credentials_offset-value_zero]-reth
+  - tests/prague/eip6110_deposits/test_modified_contract.py::test_invalid_layout[fork_Prague-blockchain_test_engine-log_argument_withdrawal_credentials_size-value_zero]-reth
+  - tests/prague/eip7002_el_triggerable_withdrawals/test_contract_deployment.py::test_system_contract_deployment[fork_CancunToPragueAtTime15k-blockchain_test_engine-deploy_after_fork-nonzero_balance]-reth
+  - tests/prague/eip7002_el_triggerable_withdrawals/test_contract_deployment.py::test_system_contract_deployment[fork_CancunToPragueAtTime15k-blockchain_test_engine-deploy_after_fork-zero_balance]-reth
+  - tests/prague/eip6110_deposits/test_modified_contract.py::test_invalid_log_length[fork_Prague-blockchain_test_engine-slice_bytes_False]-reth
+  - tests/prague/eip6110_deposits/test_modified_contract.py::test_invalid_log_length[fork_Prague-blockchain_test_engine-slice_bytes_True]-reth
+  # the next test expects a concrete new format in the error message, there is no spec for this message, so it is ok to ignore
+  - tests/cancun/eip4844_blobs/test_blob_txs.py::test_blob_type_tx_pre_fork[fork_ShanghaiToCancunAtTime15k-blockchain_test_engine_from_state_test-one_blob_tx]-reth
+# 7702 test - no fix: it’s too expensive to check whether the storage is empty on each creation
+# rest of tests - see above
 eest/consume-rlp:
   - tests/prague/eip7702_set_code_tx/test_set_code_txs.py::test_set_code_to_non_empty_storage[fork_Prague-blockchain_test-zero_nonce]-reth
+  - tests/prague/eip7251_consolidations/test_modified_consolidation_contract.py::test_system_contract_errors[fork_Prague-blockchain_test_engine-system_contract_reaches_gas_limit-system_contract_0x0000bbddc7ce488642fb579f8b00f3a590007251]-reth
+  - tests/prague/eip7251_consolidations/test_contract_deployment.py::test_system_contract_deployment[fork_CancunToPragueAtTime15k-blockchain_test_engine-deploy_after_fork-nonzero_balance]-reth
+  - tests/prague/eip7251_consolidations/test_contract_deployment.py::test_system_contract_deployment[fork_CancunToPragueAtTime15k-blockchain_test_engine-deploy_after_fork-zero_balance]-reth
+  - tests/prague/eip6110_deposits/test_modified_contract.py::test_invalid_layout[fork_Prague-blockchain_test_engine-log_argument_amount_offset-value_zero]-reth
+  - tests/prague/eip6110_deposits/test_modified_contract.py::test_invalid_layout[fork_Prague-blockchain_test_engine-log_argument_amount_size-value_zero]-reth
+  - tests/prague/eip6110_deposits/test_modified_contract.py::test_invalid_layout[fork_Prague-blockchain_test_engine-log_argument_index_offset-value_zero]-reth
+  - tests/prague/eip6110_deposits/test_modified_contract.py::test_invalid_layout[fork_Prague-blockchain_test_engine-log_argument_index_size-value_zero]-reth
+  - tests/prague/eip6110_deposits/test_modified_contract.py::test_invalid_layout[fork_Prague-blockchain_test_engine-log_argument_pubkey_offset-value_zero]-reth
+  - tests/prague/eip7002_el_triggerable_withdrawals/test_modified_withdrawal_contract.py::test_system_contract_errors[fork_Prague-blockchain_test_engine-system_contract_reaches_gas_limit-system_contract_0x00000961ef480eb55e80d19ad83579a64c007002]-reth
+  - tests/prague/eip6110_deposits/test_modified_contract.py::test_invalid_layout[fork_Prague-blockchain_test_engine-log_argument_pubkey_size-value_zero]-reth
+  - tests/prague/eip6110_deposits/test_modified_contract.py::test_invalid_layout[fork_Prague-blockchain_test_engine-log_argument_signature_offset-value_zero]-reth
+  - tests/prague/eip6110_deposits/test_modified_contract.py::test_invalid_layout[fork_Prague-blockchain_test_engine-log_argument_signature_size-value_zero]-reth
+  - tests/prague/eip6110_deposits/test_modified_contract.py::test_invalid_layout[fork_Prague-blockchain_test_engine-log_argument_withdrawal_credentials_offset-value_zero]-reth
+  - tests/prague/eip6110_deposits/test_modified_contract.py::test_invalid_layout[fork_Prague-blockchain_test_engine-log_argument_withdrawal_credentials_size-value_zero]-reth
+  - tests/prague/eip7002_el_triggerable_withdrawals/test_contract_deployment.py::test_system_contract_deployment[fork_CancunToPragueAtTime15k-blockchain_test_engine-deploy_after_fork-nonzero_balance]-reth
+  - tests/prague/eip7002_el_triggerable_withdrawals/test_contract_deployment.py::test_system_contract_deployment[fork_CancunToPragueAtTime15k-blockchain_test_engine-deploy_after_fork-zero_balance]-reth
+  - tests/prague/eip6110_deposits/test_modified_contract.py::test_invalid_log_length[fork_Prague-blockchain_test_engine-slice_bytes_False]-reth
+  - tests/prague/eip6110_deposits/test_modified_contract.py::test_invalid_log_length[fork_Prague-blockchain_test_engine-slice_bytes_True]-reth
+  - tests/prague/eip7251_consolidations/test_modified_consolidation_contract.py::test_system_contract_errors[fork_Prague-blockchain_test-system_contract_reaches_gas_limit-system_contract_0x0000bbddc7ce488642fb579f8b00f3a590007251]-reth
+  - tests/prague/eip7251_consolidations/test_contract_deployment.py::test_system_contract_deployment[fork_CancunToPragueAtTime15k-blockchain_test-deploy_after_fork-nonzero_balance]-reth
+  - tests/prague/eip7251_consolidations/test_contract_deployment.py::test_system_contract_deployment[fork_CancunToPragueAtTime15k-blockchain_test-deploy_after_fork-zero_balance]-reth
+  - tests/prague/eip7002_el_triggerable_withdrawals/test_modified_withdrawal_contract.py::test_system_contract_errors[fork_Prague-blockchain_test-system_contract_reaches_gas_limit-system_contract_0x00000961ef480eb55e80d19ad83579a64c007002]-reth
+  - tests/prague/eip7002_el_triggerable_withdrawals/test_contract_deployment.py::test_system_contract_deployment[fork_CancunToPragueAtTime15k-blockchain_test-deploy_after_fork-nonzero_balance]-reth
+  - tests/prague/eip7002_el_triggerable_withdrawals/test_contract_deployment.py::test_system_contract_deployment[fork_CancunToPragueAtTime15k-blockchain_test-deploy_after_fork-zero_balance]-reth

.github/assets/kurtosis_op_network_params.yaml

@@ -4,11 +4,26 @@ ethereum_package:
       el_extra_params:
         - "--rpc.eth-proof-window=100"
       cl_type: teku
+  network_params:
+    preset: minimal
+    genesis_delay: 5
+    additional_preloaded_contracts: '
+      {
+        "0x4e59b44847b379578588920cA78FbF26c0B4956C": {
+          "balance": "0ETH",
+          "code": "0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe03601600081602082378035828234f58015156039578182fd5b8082525050506014600cf3",
+          "storage": {},
+          "nonce": "1"
+        }
+      }'
 optimism_package:
   chains:
     - participants:
       - el_type: op-geth
         cl_type: op-node
       - el_type: op-reth
-        el_image: "ghcr.io/paradigmxyz/op-reth:kurtosis-ci"
         cl_type: op-node
+        el_image: "ghcr.io/paradigmxyz/op-reth:kurtosis-ci"
+      network_params:
+        holocene_time_offset: 0
+        isthmus_time_offset: 0

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

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

.github/workflows/docker-git.yml

@@ -24,6 +24,14 @@ jobs:
     permissions:
       packages: write
       contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        build:
+          - name: 'Build and push the git-sha-tagged reth image'
+            command: 'make PROFILE=maxperf GIT_SHA=$GIT_SHA docker-build-push-git-sha'
+          - name: 'Build and push the git-sha-tagged op-reth image'
+            command: 'make IMAGE_NAME=$OP_IMAGE_NAME DOCKER_IMAGE_NAME=$OP_DOCKER_IMAGE_NAME GIT_SHA=$GIT_SHA PROFILE=maxperf op-docker-build-push-git-sha'
     steps:
       - uses: actions/checkout@v4
       - uses: rui314/setup-mold@v1
@@ -42,7 +50,5 @@ jobs:
         run: |
           docker run --privileged --rm tonistiigi/binfmt --install arm64,amd64
           docker buildx create --use --name cross-builder
-      - name: Build and push the git-sha-tagged reth image
-        run: make PROFILE=maxperf GIT_SHA=$GIT_SHA docker-build-push-git-sha
-      - name: Build and push the git-sha-tagged op-reth image
-        run: make IMAGE_NAME=$OP_IMAGE_NAME DOCKER_IMAGE_NAME=$OP_DOCKER_IMAGE_NAME GIT_SHA=$GIT_SHA PROFILE=maxperf op-docker-build-push-git-sha
+      - name: Build and push ${{ matrix.build.name }}
+        run: ${{ matrix.build.command }}

.github/workflows/docker-nightly.yml

@@ -3,6 +3,7 @@
 name: docker-nightly
 
 on:
+  workflow_dispatch:
   schedule:
     - cron: "0 1 * * *"
 env:
@@ -21,8 +22,25 @@ jobs:
     permissions:
       packages: write
       contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        build:
+          - name: 'Build and push the nightly reth image'
+            command: 'make PROFILE=maxperf docker-build-push-nightly'
+          - name: 'Build and push the nightly profiling reth image'
+            command: 'make PROFILE=profiling docker-build-push-nightly-profiling'
+          - name: 'Build and push the nightly op-reth image'
+            command: 'make IMAGE_NAME=$OP_IMAGE_NAME DOCKER_IMAGE_NAME=$OP_DOCKER_IMAGE_NAME PROFILE=maxperf op-docker-build-push-nightly'
+          - name: 'Build and push the nightly profiling op-reth image'
+            command: 'make IMAGE_NAME=$OP_IMAGE_NAME DOCKER_IMAGE_NAME=$OP_DOCKER_IMAGE_NAME PROFILE=profiling op-docker-build-push-nightly-profiling'
     steps:
       - uses: actions/checkout@v4
+      - name: Remove bloatware
+        uses: laverdet/remove-bloatware@v1.0.0
+        with:
+          docker: true
+          lang: rust
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
@@ -39,7 +57,5 @@ jobs:
         run: |
           docker run --privileged --rm tonistiigi/binfmt --install arm64,amd64
           docker buildx create --use --name cross-builder
-      - name: Build and push the nightly reth image
-        run: make PROFILE=maxperf docker-build-push-nightly
-      - name: Build and push the nightly op-reth image
-        run: make IMAGE_NAME=$OP_IMAGE_NAME DOCKER_IMAGE_NAME=$OP_DOCKER_IMAGE_NAME PROFILE=maxperf op-docker-build-push-nightly
+      - name: Build and push ${{ matrix.build.name }}
+        run: ${{ matrix.build.command }}

.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,12 +16,21 @@ 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
       contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        build:
+          - name: "Build and push reth image"
+            command: "make IMAGE_NAME=$IMAGE_NAME DOCKER_IMAGE_NAME=$DOCKER_IMAGE_NAME PROFILE=maxperf docker-build-push"
+          - name: "Build and push op-reth image"
+            command: "make IMAGE_NAME=$OP_IMAGE_NAME DOCKER_IMAGE_NAME=$OP_DOCKER_IMAGE_NAME PROFILE=maxperf op-docker-build-push"
     steps:
       - uses: actions/checkout@v4
       - uses: rui314/setup-mold@v1
@@ -41,11 +49,41 @@ jobs:
         run: |
           docker run --privileged --rm tonistiigi/binfmt --install arm64,amd64
           docker buildx create --use --name cross-builder
-      - name: Build and push reth image, tag as "latest"
-        run: make PROFILE=maxperf docker-build-push-latest
-      - name: Build and push reth image
-        run: make PROFILE=maxperf docker-build-push
-      - name: Build and push op-reth image, tag as "latest"
-        run: make IMAGE_NAME=$OP_IMAGE_NAME DOCKER_IMAGE_NAME=$OP_DOCKER_IMAGE_NAME PROFILE=maxperf op-docker-build-push-latest
-      - name: Build and push op-reth image
-        run: make IMAGE_NAME=$OP_IMAGE_NAME DOCKER_IMAGE_NAME=$OP_DOCKER_IMAGE_NAME PROFILE=maxperf op-docker-build-push
+      - 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
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-on-failure: true
+      - name: Install cross main
+        id: cross_main
+        run: |
+          cargo install cross --git https://github.com/cross-rs/cross
+      - name: Log in to Docker
+        run: |
+          echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io --username ${DOCKER_USERNAME} --password-stdin
+      - name: Set up Docker builder
+        run: |
+          docker run --privileged --rm tonistiigi/binfmt --install arm64,amd64
+          docker buildx create --use --name cross-builder
+      - name: Build and push ${{ matrix.build.name }}
+        run: ${{ matrix.build.command }}

.github/workflows/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
@@ -62,17 +62,19 @@ jobs:
           - sim: ethereum/sync
           - sim: devp2p
             limit: discv4
-          - sim: devp2p
-            limit: eth
-            include:
-              # failures tracked in https://github.com/paradigmxyz/reth/issues/14825
-              - Status
-              - GetBlockHeaders
-              - ZeroRequestID
-              - GetBlockBodies
-              - MaliciousHandshake
-              - Transaction
-              - NewPooledTxs
+          # started failing after https://github.com/ethereum/go-ethereum/pull/31843, no
+          # action on our side, remove from here when we get unxpected passes on these tests
+          # - sim: devp2p
+          #  limit: eth
+          #  include:
+          #    - MaliciousHandshake
+          #    # failures tracked in https://github.com/paradigmxyz/reth/issues/14825
+          #    - Status
+          #    - GetBlockHeaders
+          #    - ZeroRequestID
+          #    - GetBlockBodies
+          #    - Transaction
+          #    - NewPooledTxs
           - sim: devp2p
             limit: discv5
             include:
@@ -113,35 +115,35 @@ jobs:
 
           # consume-engine
           - sim: ethereum/eest/consume-engine
-            limit: .*tests/prague
+            limit: .*tests/prague.*
           - sim: ethereum/eest/consume-engine
-            limit: .*tests/cancun
+            limit: .*tests/cancun.*
           - sim: ethereum/eest/consume-engine
-            limit: .*tests/shanghai
+            limit: .*tests/shanghai.*
           - sim: ethereum/eest/consume-engine
-            limit: .*tests/berlin
+            limit: .*tests/berlin.*
           - sim: ethereum/eest/consume-engine
-            limit: .*tests/istanbul
+            limit: .*tests/istanbul.*
           - sim: ethereum/eest/consume-engine
-            limit: .*tests/homestead
+            limit: .*tests/homestead.*
           - sim: ethereum/eest/consume-engine
-            limit: .*tests/frontier
+            limit: .*tests/frontier.*
 
           # consume-rlp
           - sim: ethereum/eest/consume-rlp
-            limit: .*tests/prague
+            limit: .*tests/prague.*
           - sim: ethereum/eest/consume-rlp
-            limit: .*tests/cancun
+            limit: .*tests/cancun.*
           - sim: ethereum/eest/consume-rlp
-            limit: .*tests/shanghai
+            limit: .*tests/shanghai.*
           - sim: ethereum/eest/consume-rlp
-            limit: .*tests/berlin
+            limit: .*tests/berlin.*
           - sim: ethereum/eest/consume-rlp
-            limit: .*tests/istanbul
+            limit: .*tests/istanbul.*
           - sim: ethereum/eest/consume-rlp
-            limit: .*tests/homestead
+            limit: .*tests/homestead.*
           - sim: ethereum/eest/consume-rlp
-            limit: .*tests/frontier
+            limit: .*tests/frontier.*
     needs:
       - prepare-reth
       - prepare-hive

.github/workflows/integration.yml

@@ -7,6 +7,9 @@ on:
   merge_group:
   push:
     branches: [main]
+  schedule:
+    # Run once a day at 3:00 UTC
+    - cron: "0 3 * * *"
 
 env:
   CARGO_TERM_COLOR: always
@@ -19,6 +22,7 @@ concurrency:
 jobs:
   test:
     name: test / ${{ matrix.network }}
+    if: github.event_name != 'schedule'
     runs-on:
       group: Reth
     env:
@@ -53,7 +57,7 @@ jobs:
   integration-success:
     name: integration success
     runs-on: ubuntu-latest
-    if: always()
+    if: always() && github.event_name != 'schedule'
     needs: [test]
     timeout-minutes: 30
     steps:
@@ -61,3 +65,18 @@ jobs:
         uses: re-actors/alls-green@release/v1
         with:
           jobs: ${{ toJSON(needs) }}
+
+  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

.github/workflows/kurtosis-op.yml

@@ -5,8 +5,11 @@ name: kurtosis-op
 on:
   workflow_dispatch:
   schedule:
-    # run every 12 hours
-    - cron: "0 */12 * * *"
+    - cron: "0 */6 * * *"
+
+  push:
+    tags:
+      - '*'
 
 env:
   CARGO_TERM_COLOR: always
@@ -59,10 +62,12 @@ 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-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-2-op-reth-op-node-op-kurtosis".public_ports.rpc.number')
+          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')
           echo "GETH_RPC=http://127.0.0.1:$GETH_PORT" >> $GITHUB_ENV
           echo "RETH_RPC=http://127.0.0.1:$RETH_PORT" >> $GITHUB_ENV
 
@@ -76,8 +81,8 @@ jobs:
             if [ $BLOCK_GETH -ge 100 ] && [ $BLOCK_RETH -ge 100 ] ; then exit 0; fi
             echo "Waiting for clients to advance..., Reth: $BLOCK_RETH Geth: $BLOCK_GETH"
           done
-          kurtosis service logs -a op-devnet op-el-2-op-reth-op-node-op-kurtosis
-          kurtosis service logs -a op-devnet op-cl-2-op-node-op-reth-op-kurtosis
+          kurtosis service logs -a op-devnet op-el-2151908-2-op-reth-op-node-op-kurtosis
+          kurtosis service logs -a op-devnet op-cl-2151908-2-op-node-op-reth-op-kurtosis
           exit 1
 
 

.github/workflows/kurtosis.yml

@@ -5,8 +5,11 @@ name: kurtosis
 on:
   workflow_dispatch:
   schedule:
-    # run every 12 hours
-    - cron: "0 */12 * * *"
+    - cron: "0 */6 * * *"
+
+  push:
+    tags:
+      - '*'
 
 env:
   CARGO_TERM_COLOR: always

.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
@@ -121,7 +118,7 @@ jobs:
       - uses: rui314/setup-mold@v1
       - uses: dtolnay/rust-toolchain@master
         with:
-          toolchain: "1.85" # MSRV
+          toolchain: "1.86" # MSRV
       - uses: Swatinem/rust-cache@v2
         with:
           cache-on-failure: true
@@ -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

@@ -0,0 +1,86 @@
+name: Pull Request
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - edited
+      - synchronize
+
+permissions:
+  pull-requests: read
+  contents: read
+
+jobs:
+  conventional-title:
+    name: Validate PR title is Conventional Commit
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - name: Check title
+        id: lint_pr_title
+        uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            chore
+            test
+            bench
+            perf
+            refactor
+            docs
+            ci
+            revert
+            deps
+        continue-on-error: true
+      - name: Add PR Comment for Invalid Title
+        if: steps.lint_pr_title.outcome == 'failure'
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: pr-title-lint-error
+          message: |
+            Your PR title doesn't follow the Conventional Commit guidelines.
+
+            **Example of valid titles:**
+            - `feat: add new user login`
+            - `fix: correct button size`
+            - `docs: update README`
+
+            **Usage:**
+            - `feat`: Introduces a new feature
+            - `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
+        with:
+          header: pr-title-lint-error
+          delete: true
+
+      - name: Fail workflow if title invalid
+        if: steps.lint_pr_title.outcome == 'failure'
+        run: exit 1

.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-reproducible.yml

@@ -0,0 +1,56 @@
+# This workflow is for building and pushing reproducible Docker images for releases.
+
+name: release-reproducible
+
+on:
+  push:
+    tags:
+      - v*
+
+env:
+  DOCKER_REPRODUCIBLE_IMAGE_NAME: ghcr.io/${{ github.repository_owner }}/reth-reproducible
+
+jobs:
+  extract-version:
+    name: extract version
+    runs-on: ubuntu-latest
+    steps:
+      - name: Extract version
+        run: echo "VERSION=$(echo ${GITHUB_REF#refs/tags/})" >> $GITHUB_OUTPUT
+        id: extract_version
+    outputs:
+      VERSION: ${{ steps.extract_version.outputs.VERSION }}
+
+  build-reproducible:
+    name: build and push reproducible image
+    runs-on: ubuntu-latest
+    needs: extract-version
+    permissions:
+      packages: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push reproducible image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile.reproducible
+          push: true
+          tags: |
+            ${{ env.DOCKER_REPRODUCIBLE_IMAGE_NAME }}:${{ needs.extract-version.outputs.VERSION }}
+            ${{ env.DOCKER_REPRODUCIBLE_IMAGE_NAME }}:latest
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          provenance: false
+        env:
+          DOCKER_BUILD_RECORD_UPLOAD: false

.github/workflows/release.yml

@@ -7,48 +7,92 @@ on:
   push:
     tags:
       - v*
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Enable dry run mode (builds artifacts but skips uploads and release creation)"
+        type: boolean
+        default: false
 
 env:
   REPO_NAME: ${{ github.repository_owner }}/reth
-  OP_IMAGE_NAME: ${{ github.repository_owner }}/op-reth
   IMAGE_NAME: ${{ github.repository_owner }}/reth
+  OP_IMAGE_NAME: ${{ github.repository_owner }}/op-reth
+  REPRODUCIBLE_IMAGE_NAME: ${{ github.repository_owner }}/reth-reproducible
   CARGO_TERM_COLOR: always
-  DOCKER_IMAGE_NAME: ghcr.io/${{ github.repository_owner }}/reth
-  DOCKER_REPRODUCIBLE_IMAGE_NAME: ghcr.io/${{ github.repository_owner }}/reth-reproducible
+  DOCKER_IMAGE_NAME_URL: ghcr.io/${{ github.repository_owner }}/reth
+  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
     steps:
       - name: Extract version
-        run: echo "VERSION=$(echo ${GITHUB_REF#refs/tags/})" >> $GITHUB_OUTPUT
+        run: echo "VERSION=${GITHUB_REF_NAME}" >> $GITHUB_OUTPUT
         id: extract_version
     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
@@ -96,55 +140,24 @@ jobs:
         shell: bash
 
       - name: Upload artifact
+        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 != 'true' }}
         uses: actions/upload-artifact@v4
         with:
           name: ${{ matrix.build.binary }}-${{ needs.extract-version.outputs.VERSION }}-${{ matrix.configs.target }}.tar.gz.asc
           path: ${{ matrix.build.binary }}-${{ needs.extract-version.outputs.VERSION }}-${{ matrix.configs.target }}.tar.gz.asc
 
-  build-reproducible:
-    name: build and push reproducible image
-    runs-on: ubuntu-latest
-    needs: extract-version
-    permissions:
-      packages: write
-      contents: read
-    steps:
-      - uses: actions/checkout@v4
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Log in to GitHub Container Registry
-        uses: docker/login-action@v3
-        with:
-          registry: ghcr.io
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Build and push reproducible image
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          file: ./Dockerfile.reproducible
-          push: true
-          tags: |
-            ${{ env.DOCKER_REPRODUCIBLE_IMAGE_NAME }}:${{ needs.extract-version.outputs.VERSION }}
-            ${{ env.DOCKER_REPRODUCIBLE_IMAGE_NAME }}:latest
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
-          provenance: false
-        env:
-          DOCKER_BUILD_RECORD_UPLOAD: false
-
   draft-release:
     name: draft release
-    needs: [build, build-reproducible, extract-version]
     runs-on: ubuntu-latest
+    needs: [build, extract-version]
+    if: ${{ github.event.inputs.dry_run != 'true' }}
     env:
       VERSION: ${{ needs.extract-version.outputs.VERSION }}
     permissions:
@@ -171,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)
 
@@ -217,17 +235,27 @@ jobs:
 
           The binaries are signed with the PGP key: `50FB 7CC5 5B2E 8AFA 59FE 03B7 AA5E D56A 7FBF 253E`
 
+          ### Reth
+
           | System | Architecture | Binary | PGP Signature |
           |:---:|:---:|:---:|:---|
-          | <img src="https://simpleicons.org/icons/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://simpleicons.org/icons/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://simpleicons.org/icons/windows.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://simpleicons.org/icons/apple.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://simpleicons.org/icons/apple.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) |
-          | | | | |
-          | **System** | **Option** | - | **Resource** |
-          | <img src="https://simpleicons.org/icons/docker.svg" style="width: 32px;"/> | Docker | | [${{ env.IMAGE_NAME }}](https://github.com/paradigmxyz/reth/pkgs/container/reth) |
-          | <img src="https://simpleicons.org/icons/docker.svg" style="width: 32px;"/> | Docker (Reproducible) | | [${{ env.IMAGE_NAME }}-reproducible](https://github.com/paradigmxyz/reth/pkgs/container/reth-reproducible) |
+          | <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" 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=()
@@ -235,4 +263,26 @@ 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
+    runs-on: ubuntu-latest
+    needs: [build, extract-version]
+    if: ${{ github.event.inputs.dry_run == 'true' }}
+    env:
+      VERSION: ${{ needs.extract-version.outputs.VERSION }}
+    steps:
+      - name: Summarize dry run
+        run: |
+          echo "## 🧪 Release Dry Run Summary"
+          echo ""
+          echo "✅ Successfully completed dry run for commit ${{ github.sha }}"
+          echo ""
+          echo "### What would happen in a real release:"
+          echo "- Binary artifacts would be uploaded to GitHub"
+          echo "- Docker images would be pushed to registry"
+          echo "- A draft release would be created"
+          echo ""
+          echo "### Next Steps"
+          echo "To perform a real release, push a git tag."

.github/workflows/reproducible-build.yml

@@ -0,0 +1,38 @@
+name: reproducible-build
+
+on:
+  workflow_dispatch: {}
+  schedule:
+    - cron: "0 1 */2 * *"
+
+jobs:
+  build:
+    name: build reproducible binaries
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: rui314/setup-mold@v1
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          target: x86_64-unknown-linux-gnu
+      - name: Install cross main
+        run: |
+          cargo install cross --git https://github.com/cross-rs/cross
+      - name: Install cargo-cache
+        run: |
+          cargo install cargo-cache
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-on-failure: true
+      - name: Build Reth
+        run: |
+          make build-reproducible
+          mv target/x86_64-unknown-linux-gnu/release/reth reth-build-1
+      - name: Clean cache
+        run: make clean && cargo cache -a
+      - name: Build Reth again
+        run: |
+          make build-reproducible
+          mv target/x86_64-unknown-linux-gnu/release/reth reth-build-2
+      - name: Compare binaries
+        run: cmp reth-build-1 reth-build-2

.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
@@ -58,7 +60,7 @@ jobs:
             | grep ${{ matrix.chain.tip }}
       - name: Run stage unwind for 100 blocks
         run: |
-          ${{ matrix.chain.bin }} stage --chain ${{ matrix.chain.chain }} unwind num-blocks 100
+          ${{ matrix.chain.bin }} stage unwind num-blocks 100 --chain ${{ matrix.chain.chain }}
       - name: Run stage unwind to block hash
         run: |
-          ${{ matrix.chain.bin }} stage --chain ${{ matrix.chain.chain }} unwind to-block ${{ matrix.chain.unwind-target }}
+          ${{ matrix.chain.bin }} stage unwind to-block ${{ matrix.chain.unwind-target }} --chain ${{ matrix.chain.chain }} 

.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
@@ -81,7 +77,7 @@ jobs:
         uses: actions/checkout@v4
         with:
           repository: ethereum/tests
-          ref: 59781f1c6cce3d6c161751ab3512d79fa75d5597
+          ref: 81862e4848585a438d64f911a19b3825f0f4cd95
           path: testing/ef-tests/ethereum-tests
           submodules: recursive
           fetch-depth: 1

.github/workflows/update-superchain.yml

@@ -0,0 +1,36 @@
+name: Update Superchain Config
+
+on:
+  schedule:
+    - cron: '0 3 * * 0'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  update-superchain:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install required tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y jq zstd qpdf yq
+
+      - name: Run fetch_superchain_config.sh
+        run: |
+          chmod +x crates/optimism/chainspec/res/fetch_superchain_config.sh
+          cd crates/optimism/chainspec/res
+          ./fetch_superchain_config.sh
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v7
+        with:
+          commit-message: "chore: update superchain config"
+          title: "chore: update superchain config"
+          body: "This PR updates the superchain configs via scheduled workflow."
+          branch: "ci/update-superchain-config"
+          delete-branch: true

.github/workflows/windows.yml

@@ -11,7 +11,7 @@ on:
 
 jobs:
   check-reth:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     timeout-minutes: 60
 
     steps:
@@ -30,7 +30,7 @@ jobs:
         run: cargo check --target x86_64-pc-windows-gnu
 
   check-op-reth:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     timeout-minutes: 60
 
     steps:

.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,7 +1,7 @@
 [workspace.package]
-version = "1.3.0"
+version = "1.4.8"
 edition = "2021"
-rust-version = "1.85"
+rust-version = "1.86"
 license = "MIT OR Apache-2.0"
 homepage = "https://paradigmxyz.github.io/reth"
 repository = "https://github.com/paradigmxyz/reth"
@@ -11,6 +11,7 @@ exclude = [".github/"]
 members = [
     "bin/reth-bench/",
     "bin/reth/",
+    "crates/alloy-provider/",
     "crates/chain-state/",
     "crates/chainspec/",
     "crates/cli/cli/",
@@ -28,8 +29,11 @@ members = [
     "crates/engine/service",
     "crates/engine/tree/",
     "crates/engine/util/",
+    "crates/era",
+    "crates/era-downloader",
+    "crates/era-utils",
     "crates/errors/",
-    "crates/ethereum-forks/",
+    "crates/ethereum/hardforks/",
     "crates/ethereum/cli/",
     "crates/ethereum/consensus/",
     "crates/ethereum/engine-primitives/",
@@ -39,7 +43,7 @@ members = [
     "crates/ethereum/primitives/",
     "crates/ethereum/reth/",
     "crates/etl/",
-    "crates/evm/",
+    "crates/evm/evm",
     "crates/evm/execution-errors",
     "crates/evm/execution-types",
     "crates/exex/exex/",
@@ -73,7 +77,6 @@ members = [
     "crates/optimism/evm/",
     "crates/optimism/hardforks/",
     "crates/optimism/node/",
-    "crates/optimism/chain-registry/",
     "crates/optimism/payload/",
     "crates/optimism/primitives/",
     "crates/optimism/reth/",
@@ -102,11 +105,12 @@ 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/",
     "crates/stages/types/",
+    "crates/stateless",
     "crates/static-file/static-file",
     "crates/static-file/types/",
     "crates/storage/codecs/",
@@ -130,18 +134,25 @@ 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/",
     "examples/bsc-p2p",
     "examples/custom-dev-node/",
+    "examples/custom-node/",
     "examples/custom-engine-types/",
     "examples/custom-evm/",
     "examples/custom-inspector/",
     "examples/custom-node-components/",
     "examples/custom-payload-builder/",
     "examples/custom-rlpx-subprotocol",
+    "examples/custom-node",
     "examples/db-access",
+    "examples/engine-api-access",
+    "examples/exex-hello-world",
+    "examples/exex-subscription",
+    "examples/exex-test",
     "examples/manual-p2p/",
     "examples/network-txpool/",
     "examples/network/",
@@ -150,11 +161,12 @@ members = [
     "examples/node-event-hooks/",
     "examples/polygon-p2p/",
     "examples/rpc-db/",
-    "examples/stateful-precompile/",
+    "examples/precompile-cache/",
     "examples/txpool-tracing/",
     "examples/custom-beacon-withdrawals",
     "testing/ef-tests/",
     "testing/testing-utils",
+    "crates/tracing-otlp",
 ]
 default-members = ["bin/reth"]
 exclude = ["book/sources", "book/cli"]
@@ -208,7 +220,7 @@ manual_clamp = "warn"
 manual_is_variant_and = "warn"
 manual_string_new = "warn"
 match_same_arms = "warn"
-missing-const-for-fn = "allow" # TODO: https://github.com/rust-lang/rust-clippy/issues/14020
+missing-const-for-fn = "warn"
 mutex_integer = "warn"
 naive_bytecount = "warn"
 needless_bitwise_bool = "warn"
@@ -309,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" }
@@ -319,7 +332,7 @@ reth-cli-runner = { path = "crates/cli/runner" }
 reth-cli-util = { path = "crates/cli/util" }
 reth-codecs = { path = "crates/storage/codecs" }
 reth-codecs-derive = { path = "crates/storage/codecs/derive" }
-reth-config = { path = "crates/config" }
+reth-config = { path = "crates/config", default-features = false }
 reth-consensus = { path = "crates/consensus/consensus", default-features = false }
 reth-consensus-common = { path = "crates/consensus/common", default-features = false }
 reth-consensus-debug-client = { path = "crates/consensus/debug-client" }
@@ -338,19 +351,22 @@ reth-engine-primitives = { path = "crates/engine/primitives", default-features =
 reth-engine-tree = { path = "crates/engine/tree" }
 reth-engine-service = { path = "crates/engine/service" }
 reth-engine-util = { path = "crates/engine/util" }
+reth-era = { path = "crates/era" }
+reth-era-downloader = { path = "crates/era-downloader" }
+reth-era-utils = { path = "crates/era-utils" }
 reth-errors = { path = "crates/errors" }
 reth-eth-wire = { path = "crates/net/eth-wire" }
 reth-eth-wire-types = { path = "crates/net/eth-wire-types" }
 reth-ethereum-cli = { path = "crates/ethereum/cli" }
-reth-ethereum-consensus = { path = "crates/ethereum/consensus" }
+reth-ethereum-consensus = { path = "crates/ethereum/consensus", default-features = false }
 reth-ethereum-engine-primitives = { path = "crates/ethereum/engine-primitives", default-features = false }
-reth-ethereum-forks = { path = "crates/ethereum-forks", default-features = false }
+reth-ethereum-forks = { path = "crates/ethereum/hardforks", default-features = false }
 reth-ethereum-payload-builder = { path = "crates/ethereum/payload" }
 reth-ethereum-primitives = { path = "crates/ethereum/primitives", default-features = false }
 reth-ethereum = { path = "crates/ethereum/reth" }
 reth-etl = { path = "crates/etl" }
-reth-evm = { path = "crates/evm", default-features = false }
-reth-evm-ethereum = { path = "crates/ethereum/evm" }
+reth-evm = { path = "crates/evm/evm", default-features = false }
+reth-evm-ethereum = { path = "crates/ethereum/evm", default-features = false }
 reth-optimism-evm = { path = "crates/optimism/evm", default-features = false }
 reth-execution-errors = { path = "crates/evm/execution-errors", default-features = false }
 reth-execution-types = { path = "crates/evm/execution-types", default-features = false }
@@ -381,7 +397,6 @@ reth-optimism-node = { path = "crates/optimism/node" }
 reth-node-types = { path = "crates/node/types" }
 reth-op = { path = "crates/optimism/reth", default-features = false }
 reth-optimism-chainspec = { path = "crates/optimism/chainspec", default-features = false }
-reth-optimism-chain-resitry = { path = "crates/optimism/chain-registry" }
 reth-optimism-cli = { path = "crates/optimism/cli" }
 reth-optimism-consensus = { path = "crates/optimism/consensus", default-features = false }
 reth-optimism-forks = { path = "crates/optimism/hardforks", default-features = false }
@@ -410,10 +425,11 @@ 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 }
+reth-stateless = { path = "crates/stateless" }
 reth-static-file = { path = "crates/static-file/static-file" }
 reth-static-file-types = { path = "crates/static-file/types", default-features = false }
 reth-storage-api = { path = "crates/storage/storage-api", default-features = false }
@@ -427,75 +443,76 @@ reth-trie = { path = "crates/trie/trie" }
 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" }
+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 = "20.0.0-alpha.5", default-features = false }
-revm-bytecode = { version = "1.0.0-alpha.3", default-features = false }
-revm-database = { version = "1.0.0-alpha.3", default-features = false }
-revm-state = { version = "1.0.0-alpha.3", default-features = false }
-revm-primitives = { version = "16.0.0-alpha.3", default-features = false }
-revm-interpreter = { version = "16.0.0-alpha.5", default-features = false }
-revm-inspector = { version = "1.0.0-alpha.5", default-features = false }
-revm-context = { version = "1.0.0-alpha.4", default-features = false }
-revm-context-interface = { version = "1.0.0-alpha.4", default-features = false }
-revm-database-interface = { version = "1.0.0-alpha.3", default-features = false }
-op-revm = { version = "1.0.0-alpha.4", default-features = false }
-revm-inspectors = "0.17.0-alpha.1"
+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.1.64", default-features = false }
-alloy-dyn-abi = "0.8.20"
-alloy-eip2124 = { version = "0.1.0", default-features = false }
-alloy-evm = { version = "0.1.0-alpha.1", default-features = false }
-alloy-primitives = { version = "0.8.20", default-features = false, features = ["map-foldhash"] }
+alloy-chains = { version = "0.2.0", default-features = false }
+alloy-dyn-abi = "1.2.0"
+alloy-eip2124 = { version = "0.2.0", default-features = false }
+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-types = { version = "0.8.20", default-features = false }
-alloy-trie = { version = "0.7.9", 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.1"
+alloy-hardforks = "0.2.7"
 
-alloy-consensus = { version = "0.12.5", default-features = false }
-alloy-contract = { version = "0.12.5", default-features = false }
-alloy-eips = { version = "0.12.5", default-features = false }
-alloy-genesis = { version = "0.12.5", default-features = false }
-alloy-json-rpc = { version = "0.12.5", default-features = false }
-alloy-network = { version = "0.12.5", default-features = false }
-alloy-network-primitives = { version = "0.12.5", default-features = false }
-alloy-node-bindings = { version = "0.12.5", default-features = false }
-alloy-provider = { version = "0.12.5", features = ["reqwest"], default-features = false }
-alloy-pubsub = { version = "0.12.5", default-features = false }
-alloy-rpc-client = { version = "0.12.5", default-features = false }
-alloy-rpc-types = { version = "0.12.5", features = ["eth"], default-features = false }
-alloy-rpc-types-admin = { version = "0.12.5", default-features = false }
-alloy-rpc-types-anvil = { version = "0.12.5", default-features = false }
-alloy-rpc-types-beacon = { version = "0.12.5", default-features = false }
-alloy-rpc-types-debug = { version = "0.12.5", default-features = false }
-alloy-rpc-types-engine = { version = "0.12.5", default-features = false }
-alloy-rpc-types-eth = { version = "0.12.5", default-features = false }
-alloy-rpc-types-mev = { version = "0.12.5", default-features = false }
-alloy-rpc-types-trace = { version = "0.12.5", default-features = false }
-alloy-rpc-types-txpool = { version = "0.12.5", default-features = false }
-alloy-serde = { version = "0.12.5", default-features = false }
-alloy-signer = { version = "0.12.5", default-features = false }
-alloy-signer-local = { version = "0.12.5", default-features = false }
-alloy-transport = { version = "0.12.5" }
-alloy-transport-http = { version = "0.12.5", features = ["reqwest-rustls-tls"], default-features = false }
-alloy-transport-ipc = { version = "0.12.5", default-features = false }
-alloy-transport-ws = { version = "0.12.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.1.0-alpha.1", default-features = false }
-alloy-op-hardforks = "0.1"
-op-alloy-rpc-types = { version = "0.11.1", default-features = false }
-op-alloy-rpc-types-engine = { version = "0.11.1", default-features = false }
-op-alloy-network = { version = "0.11.1", default-features = false }
-op-alloy-consensus = { version = "0.11.1", default-features = false }
-op-alloy-flz = { version = "0.11.1", default-features = false }
-op-alloy-rpc-jsonrpsee = { version = "0.11.1", 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"
@@ -519,13 +536,14 @@ humantime = "2.1"
 humantime-serde = "1.1"
 itertools = { version = "0.14", default-features = false }
 linked_hash_set = "0.1"
+lz4 = "1.28.1"
 modular-bitfield = "0.11.2"
 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"
-rand = "0.8.5"
+rand = "0.9"
 rayon = "1.7"
 rustc-hash = { version = "2.0", default-features = false }
 schnellru = "0.2"
@@ -539,12 +557,15 @@ strum = { version = "0.27", default-features = false }
 strum_macros = "0.27"
 syn = "2.0"
 thiserror = { version = "2.0.0", default-features = false }
+tar = "0.4.44"
 tracing = { version = "0.1.0", default-features = false }
 tracing-appender = "0.2"
 url = { version = "2.3", default-features = false }
 zstd = "0.13"
 byteorder = "1"
 mini-moka = "0.10"
+tar-no-std = { version = "0.3.2", default-features = false }
+miniz_oxide = { version = "0.8.4", default-features = false }
 
 # metrics
 metrics = "0.24.0"
@@ -558,7 +579,7 @@ proc-macro2 = "1.0"
 quote = "1.0"
 
 # tokio
-tokio = { version = "1.39", default-features = false }
+tokio = { version = "1.44.2", default-features = false }
 tokio-stream = "0.1.11"
 tokio-util = { version = "0.7.4", features = ["codec"] }
 
@@ -573,7 +594,7 @@ hyper-util = "0.1.5"
 pin-project = "1.0.12"
 reqwest = { version = "0.12", default-features = false }
 tracing-futures = "0.2"
-tower = "0.4"
+tower = "0.5"
 tower-http = "0.6"
 
 # p2p
@@ -581,11 +602,11 @@ discv5 = "0.9"
 if-addrs = "0.13"
 
 # rpc
-jsonrpsee = "0.24"
-jsonrpsee-core = "0.24"
-jsonrpsee-server = "0.24"
-jsonrpsee-http-client = "0.24"
-jsonrpsee-types = "0.24"
+jsonrpsee = "0.25.1"
+jsonrpsee-core = "0.25.1"
+jsonrpsee-server = "0.25.1"
+jsonrpsee-http-client = "0.25.1"
+jsonrpsee-types = "0.25.1"
 
 # http
 http = "1.0"
@@ -598,9 +619,11 @@ proptest-arbitrary-interop = "0.1.0"
 enr = { version = "0.13", default-features = false }
 k256 = { version = "0.13", default-features = false, features = ["ecdsa"] }
 secp256k1 = { version = "0.30", default-features = false, features = ["global-context", "recovery"] }
+# rand 8 for secp256k1
+rand_08 = { package = "rand", version = "0.8" }
 
 # for eip-4844
-c-kzg = "1.0.0"
+c-kzg = "2.1.1"
 
 # config
 toml = "0.8"
@@ -609,14 +632,17 @@ toml = "0.8"
 arbitrary = "1.3"
 assert_matches = "1.5.0"
 criterion = { package = "codspeed-criterion-compat", version = "2.7" }
-pprof = "0.14"
-proptest = "1.4"
+proptest = "1.7"
 proptest-derive = "0.5"
-serial_test = { default-features = false, version = "3" }
 similar-asserts = { version = "1.5.0", features = ["serde"] }
-tempfile = "3.8"
+tempfile = "3.20"
 test-fuzz = "7"
 rstest = "0.24.0"
+test-case = "3"
+
+# ssz encoding
+ethereum_ssz = "0.9.0"
+ethereum_ssz_derive = "0.9.0"
 
 # allocators
 tikv-jemalloc-ctl = "0.6"
@@ -631,7 +657,6 @@ snmalloc-rs = { version = "0.3.7", features = ["build_cc"] }
 crunchy = "=0.2.2"
 aes = "0.8.1"
 ahash = "0.8"
-alloy-sol-macro = "0.8.9"
 anyhow = "1.0"
 bindgen = { version = "0.70", default-features = false }
 block-padding = "0.3.2"
@@ -648,14 +673,14 @@ data-encoding = "2"
 delegate = "0.13"
 digest = "0.10.5"
 hash-db = "=0.15.2"
-hickory-resolver = "0.25.0-alpha.5"
+hickory-resolver = "0.25.0"
 hmac = "0.12.1"
 human_bytes = "0.4.1"
 indexmap = "2"
 interprocess = "2.2.0"
 lz4_flex = { version = "0.11", default-features = false }
 memmap2 = "0.9.4"
-mev-share-sse = { version = "0.4.0", default-features = false }
+mev-share-sse = { version = "0.5.0", default-features = false }
 num-traits = "0.2.15"
 page_size = "0.6.0"
 parity-scale-codec = "3.2.1"
@@ -667,7 +692,7 @@ rmp-serde = "1.3"
 roaring = "0.10.2"
 rolling-file = "0.2.0"
 sha3 = "0.10.5"
-snap = "1.0.5"
+snap = "1.1.1"
 socket2 = { version = "0.5", default-features = false }
 sysinfo = { version = "0.33", default-features = false }
 tracing-journald = "0.3"
@@ -680,39 +705,56 @@ visibility = "0.1.1"
 walkdir = "2.3.3"
 vergen-git2 = "1.0.5"
 
-# [patch.crates-io]
-# alloy-consensus = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-contract = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-eips = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-genesis = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-json-rpc = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-network = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-network-primitives = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-node-bindings = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-provider = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-pubsub = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-rpc-client = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-rpc-types = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-rpc-types-admin = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-rpc-types-anvil = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-rpc-types-beacon = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-rpc-types-debug = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-rpc-types-engine = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-rpc-types-eth = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-rpc-types-mev = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-rpc-types-trace = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-rpc-types-txpool = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-serde = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-signer = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-signer-local = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-transport = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-transport-http = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-transport-ipc = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-# alloy-transport-ws = { git = "https://github.com/alloy-rs/alloy", rev = "cfb13aa" }
-#
-# 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" }
+[patch.crates-io]
+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" }
+#
+# jsonrpsee = { git = "https://github.com/paradigmxyz/jsonrpsee", branch = "matt/make-rpc-service-pub" }
+# jsonrpsee-core = { git = "https://github.com/paradigmxyz/jsonrpsee", branch = "matt/make-rpc-service-pub" }
+# jsonrpsee-server = { git = "https://github.com/paradigmxyz/jsonrpsee", branch = "matt/make-rpc-service-pub" }
+# jsonrpsee-http-client = { git = "https://github.com/paradigmxyz/jsonrpsee", branch = "matt/make-rpc-service-pub" }
+# jsonrpsee-types = { git = "https://github.com/paradigmxyz/jsonrpsee", branch = "matt/make-rpc-service-pub" }

Cross.toml

@@ -1,12 +1,38 @@
 [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.
-    "apt-get update && apt-get install --assume-yes --no-install-recommends llvm-dev libclang-10-dev clang-10",
+    "apt-get update && apt-get install --assume-yes --no-install-recommends llvm-dev libclang-dev clang",
+]
+
+[target.x86_64-pc-windows-gnu]
+# Why do we need a custom Dockerfile on Windows:
+# 1. `reth-libmdbx` stopped working with MinGW 9.3 that cross image comes with.
+# 2. To be able to update the version of MinGW, we need to also update the Ubuntu that the image is based on.
+#
+# Also see https://github.com/cross-rs/cross/issues/1667
+# 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",
-]
+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.reproducible

@@ -1,8 +1,8 @@
-# Use the Rust 1.85 image based on Debian Bullseye
-FROM rust:1.85-bullseye AS builder
+# Use the Rust 1.86 image based on Debian Bookworm
+FROM rust:1.86-bookworm AS builder
 
 # Install specific version of libclang-dev
-RUN apt-get update && apt-get install -y libclang-dev=1:11.0-51+nmu5
+RUN apt-get update && apt-get install -y libclang-dev=1:14.0-55.7~deb12u1
 
 # Copy the project to the container
 COPY ./ /app

Dockerfile.x86_64-pc-windows-gnu

@@ -0,0 +1,73 @@
+FROM ubuntu:24.04 AS cross-base
+ENV DEBIAN_FRONTEND=noninteractive
+
+# 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
+RUN git checkout 9e2298e17170655342d3248a9c8ac37ef92ba38f
+
+RUN cp common.sh lib.sh / && /common.sh
+RUN cp cmake.sh / && /cmake.sh
+RUN cp xargo.sh / && /xargo.sh
+
+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 && 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
+# files. For some reason it does not work inside a docker container (it works
+# fine in the host). So we replace the usual paths of run-detectors to run wine
+# directly. This only affects the guest, we are not messing up with the host.
+#
+# See /usr/share/doc/binfmt-support/detectors
+RUN mkdir -p /usr/lib/binfmt-support/ && \
+    rm -f /usr/lib/binfmt-support/run-detectors /usr/bin/run-detectors && \
+    ln -s /usr/bin/wine /usr/lib/binfmt-support/run-detectors && \
+    ln -s /usr/bin/wine /usr/bin/run-detectors
+
+RUN cp windows-entry.sh /
+ENTRYPOINT ["/windows-entry.sh"]
+
+RUN cp toolchain.cmake /opt/toolchain.cmake
+
+# for why we always link with pthread support, see:
+# https://github.com/cross-rs/cross/pull/1123#issuecomment-1312287148
+ENV CROSS_TOOLCHAIN_PREFIX=x86_64-w64-mingw32-
+ENV CROSS_TOOLCHAIN_SUFFIX=-posix
+ENV CROSS_SYSROOT=/usr/x86_64-w64-mingw32
+ENV CROSS_TARGET_RUNNER="env -u CARGO_TARGET_X86_64_PC_WINDOWS_GNU_RUNNER wine"
+ENV CARGO_TARGET_X86_64_PC_WINDOWS_GNU_LINKER="$CROSS_TOOLCHAIN_PREFIX"gcc"$CROSS_TOOLCHAIN_SUFFIX" \
+    CARGO_TARGET_X86_64_PC_WINDOWS_GNU_RUNNER="$CROSS_TARGET_RUNNER" \
+    AR_x86_64_pc_windows_gnu="$CROSS_TOOLCHAIN_PREFIX"ar \
+    CC_x86_64_pc_windows_gnu="$CROSS_TOOLCHAIN_PREFIX"gcc"$CROSS_TOOLCHAIN_SUFFIX" \
+    CXX_x86_64_pc_windows_gnu="$CROSS_TOOLCHAIN_PREFIX"g++"$CROSS_TOOLCHAIN_SUFFIX" \
+    CMAKE_TOOLCHAIN_FILE_x86_64_pc_windows_gnu=/opt/toolchain.cmake \
+    BINDGEN_EXTRA_CLANG_ARGS_x86_64_pc_windows_gnu="--sysroot=$CROSS_SYSROOT -idirafter/usr/include" \
+    CROSS_CMAKE_SYSTEM_NAME=Windows \
+    CROSS_CMAKE_SYSTEM_PROCESSOR=AMD64 \
+    CROSS_CMAKE_CRT=gnu \
+    CROSS_CMAKE_OBJECT_FLAGS="-ffunction-sections -fdata-sections -m64"

HARDFORK-CHECKLIST.md

@@ -1,21 +1,41 @@
 # Non-exhaustive checklist for integrating new changes for an upcoming hard fork/devnet
 
-## Introducing new EIP types or changes to primitive types 
+## Introducing new EIP types or changes to primitive types
 
 - Make required changes to primitive data structures on [alloy](https://github.com/alloy-rs/alloy)
 - All new EIP data structures/constants/helpers etc. go into the `alloy-eips` crate at first.
 - New transaction types go into `alloy-consensus`
-- If there are changes to existing data structures, such as `Header` or `Block`, apply them to the types in `alloy-consensus` (e.g. new `request_hashes` field in Prague)
+- If there are changes to existing data structures, such as `Header` or `Block`, apply them to the types in
+  `alloy-consensus` (e.g. new `request_hashes` field in Prague)
 
 ## Engine API
 
-- If there are changes to the engine API (e.g. a new `engine_newPayloadVx` and `engine_getPayloadVx` pair) add the new types to the `alloy-rpc-types-engine` crate.
-- If there are new parameters to the `engine_newPayloadVx` endpoint, add them to the `ExecutionPayloadSidecar` container type. This types contains all additional parameters that are required to convert an `ExecutionPayload` to an EL block.
+- If there are changes to the engine API (e.g. a new `engine_newPayloadVx` and `engine_getPayloadVx` pair) add the new
+  types to the `alloy-rpc-types-engine` crate.
+- If there are new parameters to the `engine_newPayloadVx` endpoint, add them to the `ExecutionPayloadSidecar` container
+  type. This types contains all additional parameters that are required to convert an `ExecutionPayload` to an EL block.
 
 ## Reth changes
 
 ### Updates to the engine API
 
 - Add new endpoints to the `EngineApi` trait and implement endpoints.
-- Update the `ExecutionPayload` + `ExecutionPayloadSidecar` to `Block` conversion if there are any additional parameters.
+- Update the `ExecutionPayload` + `ExecutionPayloadSidecar` to `Block` conversion if there are any additional
+  parameters.
 - Update version specific validation checks in the `EngineValidator` trait.
+
+## Op-Reth changes
+
+### Updates to the engine API
+
+Opstack tries to be as close to the L1 engine API as much as possible. Isthmus (Prague equivalent) introduced the first
+deviation from the L1 engine API with an additional field in the `ExecutionPayload`. For this reason the op engine API
+has it's own server traits `OpEngineApi`.
+Adding a new versioned endpoint requires the same changes as for L1 just for the dedicated OP types.
+
+### Hardforks
+
+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`.

Makefile

@@ -26,7 +26,7 @@ PROFILE ?= release
 CARGO_INSTALL_EXTRA_FLAGS ?=
 
 # The release tag of https://github.com/ethereum/tests to use for EF tests
-EF_TESTS_TAG := v12.2
+EF_TESTS_TAG := v17.0
 EF_TESTS_URL := https://github.com/ethereum/tests/archive/refs/tags/$(EF_TESTS_TAG).tar.gz
 EF_TESTS_DIR := ./testing/ef-tests/ethereum-tests
 
@@ -65,7 +65,7 @@ RUST_BUILD_FLAGS =
 # Enable static linking to ensure reproducibility across builds
 RUST_BUILD_FLAGS += --C target-feature=+crt-static
 # Set the linker to use static libgcc to ensure reproducibility across builds
-RUST_BUILD_FLAGS += -Clink-arg=-static-libgcc
+RUST_BUILD_FLAGS += -C link-arg=-static-libgcc
 # Remove build ID from the binary to ensure reproducibility across builds
 RUST_BUILD_FLAGS += -C link-arg=-Wl,--build-id=none
 # Remove metadata hash from symbol names to ensure reproducible builds
@@ -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:
@@ -292,6 +304,23 @@ op-docker-build-push-latest: ## Build and push a cross-arch Docker image tagged
 op-docker-build-push-nightly: ## Build and push cross-arch Docker image tagged with the latest git tag with a `-nightly` suffix, and `latest-nightly`.
 	$(call op_docker_build_push,nightly,nightly)
 
+# Note: This requires a buildx builder with emulation support. For example:
+#
+# `docker run --privileged --rm tonistiigi/binfmt --install amd64,arm64`
+# `docker buildx create --use --name cross-builder`
+.PHONY: docker-build-push-nightly-profiling
+docker-build-push-nightly-profiling: ## Build and push cross-arch Docker image with profiling profile tagged with nightly-profiling.
+	$(call docker_build_push,nightly-profiling,nightly-profiling)
+
+	# Note: This requires a buildx builder with emulation support. For example:
+#
+# `docker run --privileged --rm tonistiigi/binfmt --install amd64,arm64`
+# `docker buildx create --use --name cross-builder`
+.PHONY: op-docker-build-push-nightly-profiling
+op-docker-build-push-nightly-profiling: ## Build and push cross-arch Docker image tagged with the latest git tag with a `-nightly` suffix, and `latest-nightly`.
+	$(call op_docker_build_push,nightly-profiling,nightly-profiling)
+
+
 # Create a cross-arch Docker image with the given tags and push it
 define op_docker_build_push
 	$(MAKE) op-build-x86_64-unknown-linux-gnu
@@ -345,6 +374,10 @@ update-book-cli: build-debug ## Update book cli documentation.
 profiling: ## Builds `reth` with optimisations, but also symbols.
 	RUSTFLAGS="-C target-cpu=native" cargo build --profile profiling --features jemalloc,asm-keccak
 
+.PHONY: profiling-op
+profiling-op: ## Builds `op-reth` with optimisations, but also symbols.
+	RUSTFLAGS="-C target-cpu=native" cargo build --profile profiling --features jemalloc,asm-keccak --bin op-reth --manifest-path crates/optimism/bin/Cargo.toml
+
 .PHONY: maxperf
 maxperf: ## Builds `reth` with the most aggressive optimisations.
 	RUSTFLAGS="-C target-cpu=native" cargo build --profile maxperf --features jemalloc,asm-keccak
@@ -371,6 +404,17 @@ clippy:
 	--all-features \
 	-- -D warnings
 
+clippy-op-dev:
+	cargo +nightly clippy \
+	--bin op-reth \
+	--workspace \
+	--lib \
+	--examples \
+	--tests \
+	--benches \
+	--locked \
+	--all-features
+
 lint-codespell: ensure-codespell
 	codespell --skip "*.json" --skip "./testing/ef-tests/ethereum-tests"
 

README.md

@@ -1,7 +1,8 @@
 # reth
 
+[![bench status](https://github.com/paradigmxyz/reth/actions/workflows/bench.yml/badge.svg)](https://github.com/paradigmxyz/reth/actions/workflows/bench.yml)
 [![CI status](https://github.com/paradigmxyz/reth/workflows/unit/badge.svg)][gh-ci]
-[![cargo-deny status](https://github.com/paradigmxyz/reth/workflows/deny/badge.svg)][gh-deny]
+[![cargo-lint status](https://github.com/paradigmxyz/reth/actions/workflows/lint.yml/badge.svg)][gh-lint]
 [![Telegram Chat][tg-badge]][tg-url]
 
 **Modular, contributor-friendly and blazing-fast implementation of the Ethereum protocol**
@@ -14,7 +15,7 @@
 | [Crate Docs](https://reth.rs/docs)
 
 [gh-ci]: https://github.com/paradigmxyz/reth/actions/workflows/unit.yml
-[gh-deny]: https://github.com/paradigmxyz/reth/actions/workflows/lint.yml
+[gh-lint]: https://github.com/paradigmxyz/reth/actions/workflows/lint.yml
 [tg-badge]: https://img.shields.io/endpoint?color=neon&logo=telegram&label=chat&url=https%3A%2F%2Ftg.sumanjay.workers.dev%2Fparadigm%5Freth
 
 ## What is Reth?
@@ -87,7 +88,7 @@ When updating this, also update:
 - .github/workflows/lint.yml
 -->
 
-The Minimum Supported Rust Version (MSRV) of this project is [1.85.0](https://blog.rust-lang.org/2025/02/20/Rust-1.85.0.html).
+The Minimum Supported Rust Version (MSRV) of this project is [1.86.0](https://blog.rust-lang.org/2025/04/03/Rust-1.86.0/).
 
 See the book for detailed instructions on how to [build from source](https://paradigmxyz.github.io/reth/installation/source.html).
 
@@ -103,21 +104,14 @@ cd reth
 Next, run the tests:
 
 ```sh
-# Without Geth
-cargo test --workspace
+cargo nextest run --workspace
 
-# With Geth
-cargo test --workspace --features geth-tests
-
-# With Ethereum Foundation tests
-#
-# Note: Requires cloning https://github.com/ethereum/tests
-#
-#   cd testing/ef-tests && git clone https://github.com/ethereum/tests ethereum-tests
-cargo test -p ef-tests --features ef-tests
+# Run the Ethereum Foundation tests
+make ef-tests
 ```
 
-We recommend using [`cargo nextest`](https://nexte.st/) to speed up testing. With nextest installed, simply substitute `cargo test` with `cargo nextest run`.
+We highly recommend using [`cargo nextest`](https://nexte.st/) to speed up testing.
+Using `cargo test` to run tests may work fine, but this is not tested and does not support more advanced features like retries for spurious failures.
 
 > **Note**
 >

bin/reth-bench/Cargo.toml

@@ -58,6 +58,7 @@ tokio = { workspace = true, features = ["sync", "macros", "time", "rt-multi-thre
 clap = { workspace = true, features = ["derive", "env"] }
 eyre.workspace = true
 thiserror.workspace = true
+humantime.workspace = true
 
 # for writing data
 csv.workspace = true

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/bench/new_payload_fcu.rs

@@ -15,6 +15,7 @@ use alloy_provider::Provider;
 use alloy_rpc_types_engine::{ExecutionPayload, ForkchoiceState};
 use clap::Parser;
 use csv::Writer;
+use humantime::parse_duration;
 use reth_cli_runner::CliContext;
 use reth_node_core::args::BenchmarkArgs;
 use std::time::{Duration, Instant};
@@ -27,6 +28,10 @@ pub struct Command {
     #[arg(long, value_name = "RPC_URL", verbatim_doc_comment)]
     rpc_url: String,
 
+    /// How long to wait after a forkchoice update before sending the next payload.
+    #[arg(long, value_name = "WAIT_TIME", value_parser = parse_duration, verbatim_doc_comment)]
+    wait_time: Option<Duration>,
+
     #[command(flatten)]
     benchmark: BenchmarkArgs,
 }
@@ -57,7 +62,7 @@ impl Command {
                     block.body.blob_versioned_hashes_iter().copied().collect::<Vec<_>>();
 
                 // Convert to execution payload
-                let payload = ExecutionPayload::from_block_slow(&block).0;
+                let (payload, sidecar) = ExecutionPayload::from_block_slow(&block);
                 let header = block.header;
                 let head_block_hash = payload.block_hash();
                 let safe_block_hash =
@@ -78,6 +83,7 @@ impl Command {
                         header,
                         blob_versioned_hashes,
                         payload,
+                        sidecar,
                         head_block_hash,
                         safe_block_hash,
                         finalized_block_hash,
@@ -92,7 +98,7 @@ impl Command {
         let total_benchmark_duration = Instant::now();
         let mut total_wait_time = Duration::ZERO;
 
-        while let Some((header, versioned_hashes, payload, head, safe, finalized)) = {
+        while let Some((header, versioned_hashes, payload, sidecar, head, safe, finalized)) = {
             let wait_start = Instant::now();
             let result = receiver.recv().await;
             total_wait_time += wait_start.elapsed();
@@ -115,6 +121,7 @@ impl Command {
             let message_version = call_new_payload(
                 &auth_provider,
                 payload,
+                sidecar,
                 header.parent_beacon_block_root,
                 versioned_hashes,
             )
@@ -138,6 +145,11 @@ impl Command {
             // convert gas used to gigagas, then compute gigagas per second
             info!(%combined_result);
 
+            // wait if we need to
+            if let Some(wait_time) = self.wait_time {
+                tokio::time::sleep(wait_time).await;
+            }
+
             // record the current result
             let gas_row = TotalGasRow { block_number, gas_used, time: current_duration };
             results.push((gas_row, combined_result));

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

@@ -33,8 +33,6 @@ pub struct Command {
 impl Command {
     /// Execute `benchmark new-payload-only` command
     pub async fn execute(self, _ctx: CliContext) -> eyre::Result<()> {
-        // TODO: this could be just a function I guess, but destructuring makes the code slightly
-        // more readable than a 4 element tuple.
         let BenchContext { benchmark_mode, block_provider, auth_provider, mut next_block } =
             BenchContext::new(&self.benchmark, self.rpc_url).await?;
 
@@ -54,10 +52,10 @@ impl Command {
 
                 let blob_versioned_hashes =
                     block.body.blob_versioned_hashes_iter().copied().collect::<Vec<_>>();
-                let payload = ExecutionPayload::from_block_slow(&block).0;
+                let (payload, sidecar) = ExecutionPayload::from_block_slow(&block);
 
                 next_block += 1;
-                sender.send((block.header, blob_versioned_hashes, payload)).await.unwrap();
+                sender.send((block.header, blob_versioned_hashes, payload, sidecar)).await.unwrap();
             }
         });
 
@@ -66,7 +64,7 @@ impl Command {
         let total_benchmark_duration = Instant::now();
         let mut total_wait_time = Duration::ZERO;
 
-        while let Some((header, versioned_hashes, payload)) = {
+        while let Some((header, versioned_hashes, payload, sidecar)) = {
             let wait_start = Instant::now();
             let result = receiver.recv().await;
             total_wait_time += wait_start.elapsed();
@@ -87,6 +85,7 @@ impl Command {
             call_new_payload(
                 &auth_provider,
                 payload,
+                sidecar,
                 header.parent_beacon_block_root,
                 versioned_hashes,
             )

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

@@ -123,7 +123,6 @@ impl Serialize for CombinedResult {
 #[derive(Debug)]
 pub(crate) struct TotalGasRow {
     /// The block number of the block being processed.
-    #[allow(dead_code)]
     pub(crate) block_number: u64,
     /// The total gas used in the block.
     pub(crate) gas_used: u64,

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

@@ -104,19 +104,31 @@ impl Command {
         // Convert to execution payload
         let execution_payload = ExecutionPayload::from_block_slow(&block).0;
 
+        let use_v4 = block.header.requests_hash.is_some();
+
         // Create JSON request data
-        let json_request = serde_json::to_string(&(
-            execution_payload,
-            blob_versioned_hashes,
-            parent_beacon_block_root,
-        ))?;
+        let json_request = if use_v4 {
+            serde_json::to_string(&(
+                execution_payload,
+                blob_versioned_hashes,
+                parent_beacon_block_root,
+                block.header.requests_hash.unwrap_or_default(),
+            ))?
+        } else {
+            serde_json::to_string(&(
+                execution_payload,
+                blob_versioned_hashes,
+                parent_beacon_block_root,
+            ))?
+        };
 
         // Print output or execute command
         match self.mode {
             Mode::Execute => {
                 // Create cast command
                 let mut command = std::process::Command::new("cast");
-                command.arg("rpc").arg("engine_newPayloadV3").arg("--raw");
+                let method = if use_v4 { "engine_newPayloadV4" } else { "engine_newPayloadV3" };
+                command.arg("rpc").arg(method).arg("--raw");
                 if let Some(rpc_url) = self.rpc_url {
                     command.arg("--rpc-url").arg(rpc_url);
                 }
@@ -144,10 +156,10 @@ impl Command {
                 );
 
                 if let Some(rpc_url) = self.rpc_url {
-                    cmd += &format!(" --rpc-url {}", rpc_url);
+                    cmd += &format!(" --rpc-url {rpc_url}");
                 }
                 if let Some(secret) = &jwt_secret {
-                    cmd += &format!(" --jwt-secret {}", secret);
+                    cmd += &format!(" --jwt-secret {secret}");
                 }
 
                 println!("{cmd}");

bin/reth-bench/src/valid_payload.rs

@@ -2,11 +2,12 @@
 //! response. This is useful for benchmarking, as it allows us to wait for a payload to be valid
 //! before sending additional calls.
 
+use alloy_eips::eip7685::RequestsOrHash;
 use alloy_primitives::B256;
-use alloy_provider::{ext::EngineApi, Network};
+use alloy_provider::{ext::EngineApi, Network, Provider};
 use alloy_rpc_types_engine::{
-    ExecutionPayload, ExecutionPayloadInputV2, ExecutionPayloadV1, ExecutionPayloadV3,
-    ForkchoiceState, ForkchoiceUpdated, PayloadAttributes, PayloadStatus,
+    ExecutionPayload, ExecutionPayloadInputV2, ExecutionPayloadSidecar, ExecutionPayloadV1,
+    ExecutionPayloadV3, ForkchoiceState, ForkchoiceUpdated, PayloadAttributes, PayloadStatus,
 };
 use alloy_transport::TransportResult;
 use reth_node_api::EngineApiMessageVersion;
@@ -15,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,
@@ -38,24 +39,34 @@ pub trait EngineApiValidWaitExt<N>: Send + Sync {
         parent_beacon_block_root: B256,
     ) -> TransportResult<PayloadStatus>;
 
-    /// Calls `engine_forkChoiceUpdatedV1` with the given [ForkchoiceState] and optional
-    /// [PayloadAttributes], and waits until the response is VALID.
+    /// 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,
+        payload: ExecutionPayloadV3,
+        versioned_hashes: Vec<B256>,
+        parent_beacon_block_root: B256,
+        requests_hash: B256,
+    ) -> TransportResult<PayloadStatus>;
+
+    /// 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,
@@ -67,7 +78,7 @@ pub trait EngineApiValidWaitExt<N>: Send + Sync {
 impl<N, P> EngineApiValidWaitExt<N> for P
 where
     N: Network,
-    P: EngineApi<N>,
+    P: Provider<N> + EngineApi<N>,
 {
     async fn new_payload_v1_wait(
         &self,
@@ -131,6 +142,60 @@ where
         Ok(status)
     }
 
+    async fn new_payload_v4_wait(
+        &self,
+        payload: ExecutionPayloadV3,
+        versioned_hashes: Vec<B256>,
+        parent_beacon_block_root: B256,
+        requests_hash: B256,
+    ) -> TransportResult<PayloadStatus> {
+        // We cannot use `self.new_payload_v4` because it does not support sending
+        // `RequestsOrHash::Hash`
+
+        let mut status: PayloadStatus = self
+            .client()
+            .request(
+                "engine_newPayloadV4",
+                (
+                    payload.clone(),
+                    versioned_hashes.clone(),
+                    parent_beacon_block_root,
+                    RequestsOrHash::Hash(requests_hash),
+                ),
+            )
+            .await?;
+        while !status.is_valid() {
+            if status.is_invalid() {
+                error!(
+                    ?status,
+                    ?payload,
+                    ?versioned_hashes,
+                    ?parent_beacon_block_root,
+                    "Invalid newPayloadV4",
+                );
+                panic!("Invalid newPayloadV4: {status:?}");
+            }
+            if status.is_syncing() {
+                return Err(alloy_json_rpc::RpcError::UnsupportedFeature(
+                    "invalid range: no canonical state found for parent of requested block",
+                ))
+            }
+            status = self
+                .client()
+                .request(
+                    "engine_newPayloadV4",
+                    (
+                        payload.clone(),
+                        versioned_hashes.clone(),
+                        parent_beacon_block_root,
+                        RequestsOrHash::Hash(requests_hash),
+                    ),
+                )
+                .await?;
+        }
+        Ok(status)
+    }
+
     async fn fork_choice_updated_v1_wait(
         &self,
         fork_choice_state: ForkchoiceState,
@@ -225,19 +290,32 @@ where
 pub(crate) async fn call_new_payload<N, P: EngineApiValidWaitExt<N>>(
     provider: P,
     payload: ExecutionPayload,
+    sidecar: ExecutionPayloadSidecar,
     parent_beacon_block_root: Option<B256>,
     versioned_hashes: Vec<B256>,
 ) -> 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");
-            provider
-                .new_payload_v3_wait(payload, versioned_hashes, parent_beacon_block_root)
-                .await?;
+                .expect("parent_beacon_block_root is required for V3 payloads and higher");
 
-            Ok(EngineApiMessageVersion::V3)
+            if let Some(requests_hash) = sidecar.requests_hash() {
+                provider
+                    .new_payload_v4_wait(
+                        payload,
+                        versioned_hashes,
+                        parent_beacon_block_root,
+                        requests_hash,
+                    )
+                    .await?;
+                Ok(EngineApiMessageVersion::V4)
+            } else {
+                provider
+                    .new_payload_v3_wait(payload, versioned_hashes, parent_beacon_block_root)
+                    .await?;
+                Ok(EngineApiMessageVersion::V3)
+            }
         }
         ExecutionPayload::V2(payload) => {
             let input = ExecutionPayloadInputV2 {
@@ -267,8 +345,7 @@ pub(crate) async fn call_forkchoice_updated<N, P: EngineApiValidWaitExt<N>>(
     payload_attributes: Option<PayloadAttributes>,
 ) -> TransportResult<ForkchoiceUpdated> {
     match message_version {
-        EngineApiMessageVersion::V4 => todo!("V4 payloads not supported yet"),
-        EngineApiMessageVersion::V3 => {
+        EngineApiMessageVersion::V3 | EngineApiMessageVersion::V4 | EngineApiMessageVersion::V5 => {
             provider.fork_choice_updated_v3_wait(forkchoice_state, payload_attributes).await
         }
         EngineApiMessageVersion::V2 => {

bin/reth/Cargo.toml

@@ -14,119 +14,118 @@ workspace = true
 
 [dependencies]
 # reth
-reth-cli.workspace = true
 reth-ethereum-cli.workspace = true
 reth-chainspec.workspace = true
-reth-config.workspace = true
 reth-primitives.workspace = true
-reth-primitives-traits.workspace = true
-reth-fs-util.workspace = true
 reth-db = { workspace = true, features = ["mdbx"] }
-reth-db-api.workspace = true
-reth-exex.workspace = true
 reth-provider.workspace = true
 reth-evm.workspace = true
 reth-revm.workspace = true
-reth-stages.workspace = true
-reth-execution-types.workspace = true
-reth-errors.workspace = true
 reth-transaction-pool.workspace = true
 reth-cli-runner.workspace = true
-reth-cli-commands.workspace = true
 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
 reth-network = { workspace = true, features = ["serde"] }
-reth-network-p2p.workspace = true
 reth-network-api.workspace = true
-reth-downloaders.workspace = true
-reth-tracing.workspace = true
 reth-tasks.workspace = true
 reth-payload-builder.workspace = true
 reth-payload-primitives.workspace = true
-reth-basic-payload-builder.workspace = true
-reth-static-file.workspace = true
-reth-trie = { workspace = true, features = ["metrics"] }
-reth-trie-db = { workspace = true, features = ["metrics"] }
 reth-node-api.workspace = true
 reth-node-core.workspace = true
 reth-ethereum-payload-builder.workspace = true
 reth-ethereum-primitives.workspace = true
 reth-node-ethereum = { workspace = true, features = ["js-tracer"] }
 reth-node-builder.workspace = true
-reth-node-events.workspace = true
 reth-node-metrics.workspace = true
 reth-consensus.workspace = true
-reth-prune.workspace = true
 reth-tokio-util.workspace = true
 reth-ress-protocol.workspace = true
 reth-ress-provider.workspace = true
 
 # alloy
-alloy-eips = { workspace = true, features = ["kzg"] }
-alloy-rlp.workspace = true
 alloy-rpc-types = { workspace = true, features = ["engine"] }
-alloy-consensus.workspace = true
-alloy-primitives.workspace = true
 
 # tracing
 tracing.workspace = true
 
-# io
-serde_json.workspace = true
-
 # async
 tokio = { workspace = true, features = ["sync", "macros", "time", "rt-multi-thread"] }
-futures.workspace = true
 
 # misc
 aquamarine.workspace = true
-eyre.workspace = true
 clap = { workspace = true, features = ["derive", "env"] }
-backon.workspace = true
-similar-asserts.workspace = true
+eyre.workspace = true
 
 [dev-dependencies]
+backon.workspace = true
+similar-asserts.workspace = true
 tempfile.workspace = true
 
 [features]
 default = ["jemalloc", "reth-revm/portable"]
 
-dev = ["reth-cli-commands/arbitrary"]
+dev = ["reth-ethereum-cli/dev"]
 
 asm-keccak = [
     "reth-node-core/asm-keccak",
     "reth-primitives/asm-keccak",
-    "alloy-primitives/asm-keccak",
+    "reth-ethereum-cli/asm-keccak",
 ]
 
 jemalloc = [
     "reth-cli-util/jemalloc",
     "reth-node-core/jemalloc",
     "reth-node-metrics/jemalloc",
+    "reth-ethereum-cli/jemalloc",
 ]
 jemalloc-prof = [
     "reth-cli-util/jemalloc",
     "reth-cli-util/jemalloc-prof",
+    "reth-ethereum-cli/jemalloc-prof",
+]
+tracy-allocator = [
+    "reth-cli-util/tracy-allocator",
+    "reth-ethereum-cli/tracy-allocator",
 ]
-tracy-allocator = ["reth-cli-util/tracy-allocator"]
 
 # Because jemalloc is default and preferred over snmalloc when both features are
 # enabled, `--no-default-features` should be used when enabling snmalloc or
 # snmalloc-native.
-snmalloc = ["reth-cli-util/snmalloc"]
-snmalloc-native = ["reth-cli-util/snmalloc-native"]
+snmalloc = [
+    "reth-cli-util/snmalloc",
+    "reth-ethereum-cli/snmalloc",
+]
+snmalloc-native = [
+    "reth-cli-util/snmalloc-native",
+    "reth-ethereum-cli/snmalloc-native",
+]
 
-min-error-logs = ["tracing/release_max_level_error"]
-min-warn-logs = ["tracing/release_max_level_warn"]
-min-info-logs = ["tracing/release_max_level_info"]
-min-debug-logs = ["tracing/release_max_level_debug"]
-min-trace-logs = ["tracing/release_max_level_trace"]
+min-error-logs = [
+    "tracing/release_max_level_error",
+    "reth-ethereum-cli/min-error-logs",
+]
+min-warn-logs = [
+    "tracing/release_max_level_warn",
+    "reth-ethereum-cli/min-warn-logs",
+]
+min-info-logs = [
+    "tracing/release_max_level_info",
+    "reth-ethereum-cli/min-info-logs",
+]
+min-debug-logs = [
+    "tracing/release_max_level_debug",
+    "reth-ethereum-cli/min-debug-logs",
+]
+min-trace-logs = [
+    "tracing/release_max_level_trace",
+    "reth-ethereum-cli/min-trace-logs",
+]
 
 [[bin]]
 name = "reth"

bin/reth/src/cli/mod.rs

@@ -1,352 +1,15 @@
 //! CLI definition and entrypoint to executable
 
-use crate::{
-    args::LogArgs,
-    commands::debug_cmd,
-    version::{LONG_VERSION, SHORT_VERSION},
-};
-use clap::{value_parser, Parser, Subcommand};
-use reth_chainspec::ChainSpec;
-use reth_cli::chainspec::ChainSpecParser;
-use reth_cli_commands::{
-    config_cmd, db, dump_genesis, import, init_cmd, init_state,
-    node::{self, NoArgs},
-    p2p, prune, recover, stage,
-};
-use reth_cli_runner::CliRunner;
-use reth_db::DatabaseEnv;
-use reth_ethereum_cli::chainspec::EthereumChainSpecParser;
-use reth_network::EthNetworkPrimitives;
-use reth_node_builder::{NodeBuilder, WithLaunchContext};
-use reth_node_ethereum::{consensus::EthBeaconConsensus, EthExecutorProvider, EthereumNode};
-use reth_node_metrics::recorder::install_prometheus_recorder;
-use reth_tracing::FileWorkerGuard;
-use std::{ffi::OsString, fmt, future::Future, sync::Arc};
-use tracing::info;
-
-/// Re-export of the `reth_node_core` types specifically in the `cli` module.
+/// Re-export of the [`reth_node_core`] types specifically in the `cli` module.
 ///
 /// This is re-exported because the types in `reth_node_core::cli` originally existed in
-/// `reth::cli` but were moved to the `reth_node_core` crate. This re-export avoids a breaking
-/// change.
+/// `reth::cli` but were moved to the [`reth_node_core`] crate. This re-export avoids a
+/// breaking change.
 pub use crate::core::cli::*;
 
-/// The main reth cli interface.
+/// Re-export of the [`reth_ethereum_cli`] types specifically in the `interface` module.
 ///
-/// This is the entrypoint to the executable.
-#[derive(Debug, Parser)]
-#[command(author, version = SHORT_VERSION, long_version = LONG_VERSION, about = "Reth", long_about = None)]
-pub struct Cli<C: ChainSpecParser = EthereumChainSpecParser, Ext: clap::Args + fmt::Debug = NoArgs>
-{
-    /// The command to run
-    #[command(subcommand)]
-    pub command: Commands<C, Ext>,
-
-    /// The chain this node is running.
-    ///
-    /// Possible values are either a built-in chain or the path to a chain specification file.
-    #[arg(
-        long,
-        value_name = "CHAIN_OR_PATH",
-        long_help = C::help_message(),
-        default_value = C::SUPPORTED_CHAINS[0],
-        value_parser = C::parser(),
-        global = true,
-    )]
-    pub chain: Arc<C::ChainSpec>,
-
-    /// 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
-    #[arg(long, value_name = "INSTANCE", global = true, default_value_t = 1, value_parser = value_parser!(u16).range(..=200))]
-    pub instance: u16,
-
-    /// The logging configuration for the CLI.
-    #[command(flatten)]
-    pub logs: LogArgs,
-}
-
-impl Cli {
-    /// Parsers only the default CLI arguments
-    pub fn parse_args() -> Self {
-        Self::parse()
-    }
-
-    /// Parsers only the default CLI arguments from the given iterator
-    pub fn try_parse_args_from<I, T>(itr: I) -> Result<Self, clap::error::Error>
-    where
-        I: IntoIterator<Item = T>,
-        T: Into<OsString> + Clone,
-    {
-        Self::try_parse_from(itr)
-    }
-}
-
-impl<C: ChainSpecParser<ChainSpec = ChainSpec>, Ext: clap::Args + fmt::Debug> Cli<C, Ext> {
-    /// Execute the configured cli command.
-    ///
-    /// This accepts a closure that is used to launch the node via the
-    /// [`NodeCommand`](node::NodeCommand).
-    ///
-    /// This command will be run on the [default tokio runtime](reth_cli_runner::tokio_runtime).
-    ///
-    ///
-    /// # Example
-    ///
-    /// ```no_run
-    /// use reth::cli::Cli;
-    /// use reth_node_ethereum::EthereumNode;
-    ///
-    /// Cli::parse_args()
-    ///     .run(async move |builder, _| {
-    ///         let handle = builder.launch_node(EthereumNode::default()).await?;
-    ///
-    ///         handle.wait_for_node_exit().await
-    ///     })
-    ///     .unwrap();
-    /// ```
-    ///
-    /// # Example
-    ///
-    /// Parse additional CLI arguments for the node command and use it to configure the node.
-    ///
-    /// ```no_run
-    /// use clap::Parser;
-    /// use reth::cli::Cli;
-    /// use reth_ethereum_cli::chainspec::EthereumChainSpecParser;
-    ///
-    /// #[derive(Debug, Parser)]
-    /// pub struct MyArgs {
-    ///     pub enable: bool,
-    /// }
-    ///
-    /// Cli::<EthereumChainSpecParser, MyArgs>::parse()
-    ///     .run(async move |builder, my_args: MyArgs|
-    ///         // launch the node
-    ///         Ok(()))
-    ///     .unwrap();
-    /// ````
-    pub fn run<L, Fut>(self, launcher: L) -> eyre::Result<()>
-    where
-        L: FnOnce(WithLaunchContext<NodeBuilder<Arc<DatabaseEnv>, C::ChainSpec>>, Ext) -> Fut,
-        Fut: Future<Output = eyre::Result<()>>,
-    {
-        self.with_runner(CliRunner::try_default_runtime()?, launcher)
-    }
-
-    /// Execute the configured cli command with the provided [`CliRunner`].
-    ///
-    ///
-    /// # Example
-    ///
-    /// ```no_run
-    /// use reth::cli::Cli;
-    /// use reth_cli_runner::CliRunner;
-    /// use reth_node_ethereum::EthereumNode;
-    ///
-    /// let runtime = tokio::runtime::Builder::new_multi_thread()
-    ///     .worker_threads(4)
-    ///     .max_blocking_threads(256)
-    ///     .enable_all()
-    ///     .build()
-    ///     .unwrap();
-    /// let runner = CliRunner::from_runtime(runtime);
-    ///
-    /// Cli::parse_args()
-    ///     .with_runner(runner, |builder, _| async move {
-    ///         let handle = builder.launch_node(EthereumNode::default()).await?;
-    ///         handle.wait_for_node_exit().await
-    ///     })
-    ///     .unwrap();
-    /// ```
-    pub fn with_runner<L, Fut>(mut self, runner: CliRunner, launcher: L) -> eyre::Result<()>
-    where
-        L: FnOnce(WithLaunchContext<NodeBuilder<Arc<DatabaseEnv>, C::ChainSpec>>, Ext) -> Fut,
-        Fut: Future<Output = eyre::Result<()>>,
-    {
-        // add network name to logs dir
-        self.logs.log_file_directory =
-            self.logs.log_file_directory.join(self.chain.chain.to_string());
-
-        let _guard = self.init_tracing()?;
-        info!(target: "reth::cli", "Initialized tracing, debug log directory: {}", self.logs.log_file_directory);
-
-        // Install the prometheus recorder to be sure to record all metrics
-        let _ = install_prometheus_recorder();
-
-        let components = |spec: Arc<C::ChainSpec>| {
-            (EthExecutorProvider::ethereum(spec.clone()), EthBeaconConsensus::new(spec))
-        };
-        match self.command {
-            Commands::Node(command) => {
-                runner.run_command_until_exit(|ctx| command.execute(ctx, launcher))
-            }
-            Commands::Init(command) => {
-                runner.run_blocking_until_ctrl_c(command.execute::<EthereumNode>())
-            }
-            Commands::InitState(command) => {
-                runner.run_blocking_until_ctrl_c(command.execute::<EthereumNode>())
-            }
-            Commands::Import(command) => {
-                runner.run_blocking_until_ctrl_c(command.execute::<EthereumNode, _, _>(components))
-            }
-            Commands::DumpGenesis(command) => runner.run_blocking_until_ctrl_c(command.execute()),
-            Commands::Db(command) => {
-                runner.run_blocking_until_ctrl_c(command.execute::<EthereumNode>())
-            }
-            Commands::Stage(command) => runner.run_command_until_exit(|ctx| {
-                command.execute::<EthereumNode, _, _, EthNetworkPrimitives>(ctx, components)
-            }),
-            Commands::P2P(command) => {
-                runner.run_until_ctrl_c(command.execute::<EthNetworkPrimitives>())
-            }
-            #[cfg(feature = "dev")]
-            Commands::TestVectors(command) => runner.run_until_ctrl_c(command.execute()),
-            Commands::Config(command) => runner.run_until_ctrl_c(command.execute()),
-            Commands::Debug(command) => {
-                runner.run_command_until_exit(|ctx| command.execute::<EthereumNode>(ctx))
-            }
-            Commands::Recover(command) => {
-                runner.run_command_until_exit(|ctx| command.execute::<EthereumNode>(ctx))
-            }
-            Commands::Prune(command) => runner.run_until_ctrl_c(command.execute::<EthereumNode>()),
-        }
-    }
-
-    /// Initializes tracing with the configured options.
-    ///
-    /// If file logging is enabled, this function returns a guard that must be kept alive to ensure
-    /// that all logs are flushed to disk.
-    pub fn init_tracing(&self) -> eyre::Result<Option<FileWorkerGuard>> {
-        let guard = self.logs.init_tracing()?;
-        Ok(guard)
-    }
-}
-
-/// Commands to be executed
-#[derive(Debug, Subcommand)]
-#[allow(clippy::large_enum_variant)]
-pub enum Commands<C: ChainSpecParser, Ext: clap::Args + fmt::Debug> {
-    /// Start the node
-    #[command(name = "node")]
-    Node(Box<node::NodeCommand<C, Ext>>),
-    /// Initialize the database from a genesis file.
-    #[command(name = "init")]
-    Init(init_cmd::InitCommand<C>),
-    /// Initialize the database from a state dump file.
-    #[command(name = "init-state")]
-    InitState(init_state::InitStateCommand<C>),
-    /// This syncs RLP encoded blocks from a file.
-    #[command(name = "import")]
-    Import(import::ImportCommand<C>),
-    /// Dumps genesis block JSON configuration to stdout.
-    DumpGenesis(dump_genesis::DumpGenesisCommand<C>),
-    /// Database debugging utilities
-    #[command(name = "db")]
-    Db(db::Command<C>),
-    /// Manipulate individual stages.
-    #[command(name = "stage")]
-    Stage(stage::Command<C>),
-    /// P2P Debugging utilities
-    #[command(name = "p2p")]
-    P2P(p2p::Command<C>),
-    /// Generate Test Vectors
-    #[cfg(feature = "dev")]
-    #[command(name = "test-vectors")]
-    TestVectors(reth_cli_commands::test_vectors::Command),
-    /// Write config to stdout
-    #[command(name = "config")]
-    Config(config_cmd::Command),
-    /// Various debug routines
-    #[command(name = "debug")]
-    Debug(Box<debug_cmd::Command<C>>),
-    /// Scripts for node recovery
-    #[command(name = "recover")]
-    Recover(recover::Command<C>),
-    /// Prune according to the configuration without any limits
-    #[command(name = "prune")]
-    Prune(prune::PruneCommand<C>),
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::args::ColorMode;
-    use clap::CommandFactory;
-    use reth_ethereum_cli::chainspec::SUPPORTED_CHAINS;
-
-    #[test]
-    fn parse_color_mode() {
-        let reth = Cli::try_parse_args_from(["reth", "node", "--color", "always"]).unwrap();
-        assert_eq!(reth.logs.color, ColorMode::Always);
-    }
-
-    /// Tests that the help message is parsed correctly. This ensures that clap args are configured
-    /// correctly and no conflicts are introduced via attributes that would result in a panic at
-    /// runtime
-    #[test]
-    fn test_parse_help_all_subcommands() {
-        let reth = Cli::<EthereumChainSpecParser, NoArgs>::command();
-        for sub_command in reth.get_subcommands() {
-            let err = Cli::try_parse_args_from(["reth", sub_command.get_name(), "--help"])
-                .err()
-                .unwrap_or_else(|| {
-                    panic!("Failed to parse help message {}", sub_command.get_name())
-                });
-
-            // --help is treated as error, but
-            // > Not a true "error" as it means --help or similar was used. The help message will be sent to stdout.
-            assert_eq!(err.kind(), clap::error::ErrorKind::DisplayHelp);
-        }
-    }
-
-    /// Tests that the log directory is parsed correctly. It's always tied to the specific chain's
-    /// name
-    #[test]
-    fn parse_logs_path() {
-        let mut reth = Cli::try_parse_args_from(["reth", "node"]).unwrap();
-        reth.logs.log_file_directory =
-            reth.logs.log_file_directory.join(reth.chain.chain.to_string());
-        let log_dir = reth.logs.log_file_directory;
-        let end = format!("reth/logs/{}", SUPPORTED_CHAINS[0]);
-        assert!(log_dir.as_ref().ends_with(end), "{log_dir:?}");
-
-        let mut iter = SUPPORTED_CHAINS.iter();
-        iter.next();
-        for chain in iter {
-            let mut reth = Cli::try_parse_args_from(["reth", "node", "--chain", chain]).unwrap();
-            reth.logs.log_file_directory =
-                reth.logs.log_file_directory.join(reth.chain.chain.to_string());
-            let log_dir = reth.logs.log_file_directory;
-            let end = format!("reth/logs/{chain}");
-            assert!(log_dir.as_ref().ends_with(end), "{log_dir:?}");
-        }
-    }
-
-    #[test]
-    fn parse_env_filter_directives() {
-        let temp_dir = tempfile::tempdir().unwrap();
-
-        unsafe { std::env::set_var("RUST_LOG", "info,evm=debug") };
-        let reth = Cli::try_parse_args_from([
-            "reth",
-            "init",
-            "--datadir",
-            temp_dir.path().to_str().unwrap(),
-            "--log.file.filter",
-            "debug,net=trace",
-        ])
-        .unwrap();
-        assert!(reth.run(async move |_, _| Ok(())).is_ok());
-    }
-}
+/// This is re-exported because the types in [`reth_ethereum_cli::interface`] originally
+/// existed in `reth::cli` but were moved to the [`reth_ethereum_cli`] crate. This re-export
+/// avoids a breaking change.
+pub use reth_ethereum_cli::interface::*;

bin/reth/src/commands/mod.rs

@@ -1,3 +0,0 @@
-//! This contains all of the `reth` commands
-
-pub mod debug_cmd;

bin/reth/src/lib.rs

@@ -28,7 +28,6 @@
 #![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
 
 pub mod cli;
-pub mod commands;
 
 /// Re-exported utils.
 pub mod utils {
@@ -176,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::*;
     }
 }
 
@@ -191,3 +190,7 @@ pub use reth_cli_runner::{tokio_runtime, CliContext, CliRunner};
 
 // for rendering diagrams
 use aquamarine as _;
+
+// used in main
+use clap as _;
+use reth_cli_util as _;

bin/reth/src/main.rs

@@ -29,7 +29,7 @@ fn main() {
                 install_ress_subprotocol(
                     ress_args,
                     node.provider,
-                    node.block_executor,
+                    node.evm_config,
                     node.network,
                     node.task_executor,
                     node.add_ons_handle.engine_events.new_listener(),

bin/reth/src/ress.rs

@@ -1,9 +1,9 @@
-use reth_evm::execute::BlockExecutorProvider;
+use reth_ethereum_primitives::EthPrimitives;
+use reth_evm::ConfigureEvm;
 use reth_network::{protocol::IntoRlpxSubProtocol, NetworkProtocols};
 use reth_network_api::FullNetwork;
 use reth_node_api::BeaconConsensusEngineEvent;
 use reth_node_core::args::RessArgs;
-use reth_primitives::EthPrimitives;
 use reth_provider::providers::{BlockchainProvider, ProviderNodeTypes};
 use reth_ress_protocol::{NodeType, ProtocolState, RessProtocolHandler};
 use reth_ress_provider::{maintain_pending_state, PendingState, RethRessProtocolProvider};
@@ -16,14 +16,14 @@ use tracing::*;
 pub fn install_ress_subprotocol<P, E, N>(
     args: RessArgs,
     provider: BlockchainProvider<P>,
-    block_executor: E,
+    evm_config: E,
     network: N,
     task_executor: TaskExecutor,
     engine_events: EventStream<BeaconConsensusEngineEvent<EthPrimitives>>,
 ) -> eyre::Result<()>
 where
     P: ProviderNodeTypes<Primitives = EthPrimitives>,
-    E: BlockExecutorProvider<Primitives = EthPrimitives> + Clone,
+    E: ConfigureEvm<Primitives = EthPrimitives> + Clone + 'static,
     N: FullNetwork + NetworkProtocols,
 {
     info!(target: "reth::cli", "Installing ress subprotocol");
@@ -39,11 +39,12 @@ where
     let (tx, mut rx) = mpsc::unbounded_channel();
     let provider = RethRessProtocolProvider::new(
         provider,
-        block_executor,
+        evm_config,
         Box::new(task_executor.clone()),
-        pending_state,
+        args.max_witness_window,
         args.witness_max_parallel,
         args.witness_cache_size,
+        pending_state,
     )?;
     network.add_rlpx_sub_protocol(
         RessProtocolHandler {

book/SUMMARY.md

@@ -1,82 +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 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 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,45 +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 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 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/config.md

@@ -1,117 +0,0 @@
-# reth config
-
-Write config to stdout
-
-```bash
-$ reth config --help
-```
-```txt
-Usage: reth config [OPTIONS]
-
-Options:
-      --config <FILE>
-          The path to the configuration file to use.
-
-      --default
-          Show the default config
-
-      --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/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: 60]
-
-      --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: 100]
-
-      --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/recover.md

@@ -1,115 +0,0 @@
-# reth recover
-
-Scripts for node recovery
-
-```bash
-$ reth recover --help
-```
-```txt
-Usage: reth recover [OPTIONS] <COMMAND>
-
-Commands:
-  storage-tries  Recover the node by deleting dangling storage tries
-  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/reth/stage.md

@@ -1,118 +0,0 @@
-# reth stage
-
-Manipulate individual stages
-
-```bash
-$ reth stage --help
-```
-```txt
-Usage: reth stage [OPTIONS] <COMMAND>
-
-Commands:
-  run     Run a single stage
-  drop    Drop a stage's tables from the database
-  dump    Dumps a stage from a range into a new database
-  unwind  Unwinds a certain block range, deleting it from the database
-  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/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.mdx

@@ -13,8 +13,10 @@ Commands:
   init          Initialize the database from a genesis file
   init-state    Initialize the database from a state dump file
   import        This syncs RLP encoded blocks from a file
+  import-era    This syncs ERA encoded blocks from a directory
   dump-genesis  Dumps genesis block JSON configuration to stdout
   db            Database debugging utilities
+  download      Download public node snapshots
   stage         Manipulate individual stages
   p2p           P2P Debugging utilities
   config        Write config to stdout
@@ -24,26 +26,6 @@ Commands:
   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')
 

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

@@ -0,0 +1,97 @@
+# reth config
+
+Write config to stdout
+
+```bash
+$ reth config --help
+```
+```txt
+Usage: reth config [OPTIONS]
+
+Options:
+      --config <FILE>
+          The path to the configuration file to use.
+
+      --default
+          Show the default config
+
+  -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/vocs/docs/pages/cli/reth/db.mdx

@@ -21,17 +21,6 @@ Commands:
   help      Print this message or the help of the given subcommand(s)
 
 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')
 
@@ -58,7 +47,7 @@ Datadir:
           Possible values are either a built-in chain or the path to a chain specification file.
 
           Built-in chains:
-              mainnet, sepolia, holesky, dev
+              mainnet, sepolia, holesky, hoodi, dev
 
           [default: mainnet]
 

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

@@ -22,20 +22,19 @@ Options:
       --limit <LIMIT>
           The maximum number of records that are queried and used to compute the checksum
 
-      --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:
+      --chain <CHAIN_OR_PATH>
+          The chain this node is running.
+          Possible values are either a built-in chain or the path to a chain specification file.
+
+          Built-in chains:
+              mainnet, sepolia, holesky, hoodi, dev
+
+          [default: mainnet]
+
 Logging:
       --log.stdout.format <FORMAT>
           The format to use for logs written to stdout

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

@@ -14,20 +14,19 @@ Commands:
   help         Print this message or the help of the given subcommand(s)
 
 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:
+      --chain <CHAIN_OR_PATH>
+          The chain this node is running.
+          Possible values are either a built-in chain or the path to a chain specification file.
+
+          Built-in chains:
+              mainnet, sepolia, holesky, hoodi, dev
+
+          [default: mainnet]
+
 Logging:
       --log.stdout.format <FORMAT>
           The format to use for logs written to stdout

book/vocs/docs/pages/cli/reth/db/clear/mdbx.mdx

@@ -13,20 +13,19 @@ Arguments:
 
 
 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:
+      --chain <CHAIN_OR_PATH>
+          The chain this node is running.
+          Possible values are either a built-in chain or the path to a chain specification file.
+
+          Built-in chains:
+              mainnet, sepolia, holesky, hoodi, dev
+
+          [default: mainnet]
+
 Logging:
       --log.stdout.format <FORMAT>
           The format to use for logs written to stdout

book/vocs/docs/pages/cli/reth/db/clear/static-file.mdx

@@ -17,20 +17,19 @@ Arguments:
           - block-meta:   Static File segment responsible for the `BlockBodyIndices`, `BlockOmmers`, `BlockWithdrawals` tables
 
 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:
+      --chain <CHAIN_OR_PATH>
+          The chain this node is running.
+          Possible values are either a built-in chain or the path to a chain specification file.
+
+          Built-in chains:
+              mainnet, sepolia, holesky, hoodi, dev
+
+          [default: mainnet]
+
 Logging:
       --log.stdout.format <FORMAT>
           The format to use for logs written to stdout

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

@@ -12,17 +12,6 @@ Options:
       --secondary-datadir <SECONDARY_DATADIR>
           The path to the data dir for all reth files and subdirectories.
 
-      --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')
 
@@ -60,6 +49,16 @@ Database:
       --output <OUTPUT>
           The output directory for the diff report.
 
+Datadir:
+      --chain <CHAIN_OR_PATH>
+          The chain this node is running.
+          Possible values are either a built-in chain or the path to a chain specification file.
+
+          Built-in chains:
+              mainnet, sepolia, holesky, hoodi, dev
+
+          [default: mainnet]
+
 Logging:
       --log.stdout.format <FORMAT>
           The format to use for logs written to stdout

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

@@ -12,20 +12,19 @@ Options:
   -f, --force
           Bypasses the interactive confirmation and drops the database directly
 
-      --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:
+      --chain <CHAIN_OR_PATH>
+          The chain this node is running.
+          Possible values are either a built-in chain or the path to a chain specification file.
+
+          Built-in chains:
+              mainnet, sepolia, holesky, hoodi, dev
+
+          [default: mainnet]
+
 Logging:
       --log.stdout.format <FORMAT>
           The format to use for logs written to stdout

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

@@ -14,20 +14,19 @@ Commands:
   help         Print this message or the help of the given subcommand(s)
 
 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:
+      --chain <CHAIN_OR_PATH>
+          The chain this node is running.
+          Possible values are either a built-in chain or the path to a chain specification file.
+
+          Built-in chains:
+              mainnet, sepolia, holesky, hoodi, dev
+
+          [default: mainnet]
+
 Logging:
       --log.stdout.format <FORMAT>
           The format to use for logs written to stdout

book/vocs/docs/pages/cli/reth/db/get/mdbx.mdx

@@ -22,20 +22,19 @@ Options:
       --raw
           Output bytes instead of human-readable decoded value
 
-      --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:
+      --chain <CHAIN_OR_PATH>
+          The chain this node is running.
+          Possible values are either a built-in chain or the path to a chain specification file.
+
+          Built-in chains:
+              mainnet, sepolia, holesky, hoodi, dev
+
+          [default: mainnet]
+
 Logging:
       --log.stdout.format <FORMAT>
           The format to use for logs written to stdout

book/vocs/docs/pages/cli/reth/db/get/static-file.mdx

@@ -23,20 +23,19 @@ Options:
       --raw
           Output bytes instead of human-readable decoded value
 
-      --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:
+      --chain <CHAIN_OR_PATH>
+          The chain this node is running.
+          Possible values are either a built-in chain or the path to a chain specification file.
+
+          Built-in chains:
+              mainnet, sepolia, holesky, hoodi, dev
+
+          [default: mainnet]
+
 Logging:
       --log.stdout.format <FORMAT>
           The format to use for logs written to stdout

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

@@ -55,20 +55,19 @@ Options:
       --raw
           Output bytes instead of human-readable decoded value
 
-      --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:
+      --chain <CHAIN_OR_PATH>
+          The chain this node is running.
+          Possible values are either a built-in chain or the path to a chain specification file.
+
+          Built-in chains:
+              mainnet, sepolia, holesky, hoodi, dev
+
+          [default: mainnet]
+
 Logging:
       --log.stdout.format <FORMAT>
           The format to use for logs written to stdout

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

@@ -9,20 +9,19 @@ $ reth db path --help
 Usage: reth db path [OPTIONS]
 
 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:
+      --chain <CHAIN_OR_PATH>
+          The chain this node is running.
+          Possible values are either a built-in chain or the path to a chain specification file.
+
+          Built-in chains:
+              mainnet, sepolia, holesky, hoodi, dev
+
+          [default: mainnet]
+
 Logging:
       --log.stdout.format <FORMAT>
           The format to use for logs written to stdout

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

@@ -22,20 +22,19 @@ Options:
 
           For individual table checksums, use the `reth db checksum` command.
 
-      --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:
+      --chain <CHAIN_OR_PATH>
+          The chain this node is running.
+          Possible values are either a built-in chain or the path to a chain specification file.
+
+          Built-in chains:
+              mainnet, sepolia, holesky, hoodi, dev
+
+          [default: mainnet]
+
 Logging:
       --log.stdout.format <FORMAT>
           The format to use for logs written to stdout

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

@@ -9,20 +9,19 @@ $ reth db version --help
 Usage: reth db version [OPTIONS]
 
 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:
+      --chain <CHAIN_OR_PATH>
+          The chain this node is running.
+          Possible values are either a built-in chain or the path to a chain specification file.
+
+          Built-in chains:
+              mainnet, sepolia, holesky, hoodi, dev
+
+          [default: mainnet]
+
 Logging:
       --log.stdout.format <FORMAT>
           The format to use for logs written to stdout

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

@@ -16,26 +16,6 @@ Commands:
   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')
 

book/vocs/docs/pages/cli/reth/debug/build-block.mdx

@@ -9,17 +9,6 @@ $ reth debug build-block --help
 Usage: reth debug build-block [OPTIONS] --prev-randao <PREV_RANDAO> --timestamp <TIMESTAMP> --suggested-fee-recipient <SUGGESTED_FEE_RECIPIENT>
 
 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')
 
@@ -46,7 +35,7 @@ Datadir:
           Possible values are either a built-in chain or the path to a chain specification file.
 
           Built-in chains:
-              mainnet, sepolia, holesky, dev
+              mainnet, sepolia, holesky, hoodi, dev
 
           [default: mainnet]
 
@@ -78,9 +67,6 @@ Database:
       --db.read-transaction-timeout <READ_TRANSACTION_TIMEOUT>
           Read transaction timeout in seconds, 0 means no timeout
 
-      --trusted-setup-file <PATH>
-          Overrides the KZG trusted setup by reading from the supplied file
-
       --parent-beacon-block-root <PARENT_BEACON_BLOCK_ROOT>
 
 

book/vocs/docs/pages/cli/reth/debug/execution.mdx

@@ -9,17 +9,6 @@ $ reth debug execution --help
 Usage: reth debug execution [OPTIONS] --to <TO>
 
 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')
 
@@ -46,7 +35,7 @@ Datadir:
           Possible values are either a built-in chain or the path to a chain specification file.
 
           Built-in chains:
-              mainnet, sepolia, holesky, dev
+              mainnet, sepolia, holesky, hoodi, dev
 
           [default: mainnet]
 
@@ -123,7 +112,7 @@ Networking:
       --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: 60]
+          [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
@@ -133,7 +122,7 @@ Networking:
       --discovery.v5.bootstrap.lookup-countdown <DISCOVERY_V5_BOOTSTRAP_LOOKUP_COUNTDOWN>
           The number of times to carry out boost lookup queries at bootstrap
 
-          [default: 100]
+          [default: 200]
 
       --trusted-peers <TRUSTED_PEERS>
           Comma separated enode URLs of trusted peers for P2P connections.
@@ -245,6 +234,13 @@ Networking:
 
           If flag is set, but no value is passed, the default interface for docker `eth0` is tried.
 
+      --tx-propagation-policy <TX_PROPAGATION_POLICY>
+          Transaction Propagation Policy
+
+          The policy determines which peers transactions are gossiped to.
+
+          [default: All]
+
       --to <TO>
           The maximum block height