Merge branch 'main' into feat/persistent-shared-domains

Author: mh0lt

.claude/skills/launch-bal-devnet-2/SKILL.md

@@ -173,6 +173,104 @@ bash $WORKDIR/clean.sh
 
 This runs `stop.sh`, removes erigon chain data (chaindata, snapshots, txpool, nodes, temp) and lighthouse data, then re-initializes genesis. After clean, start again with Steps 4-5.
 
+## A/B Testing: BAL vs Non-BAL Parallel Execution
+
+Compare parallel execution throughput with and without BAL scheduling optimization.
+
+### Overview
+
+- **Instance A (BAL)**: Default `bal-devnet-2` instance at `$WORKDIR` — uses BAL to pre-populate version maps and schedule transactions optimistically
+- **Instance B (No-BAL)**: Second instance at `$WORKDIR-nobal` — sets `IGNORE_BAL=true` to force dependency-tracking scheduling path
+
+Both instances sync the same chain, enabling direct throughput comparison.
+
+### Instance B Port Assignments (offset +400)
+
+| Service | Port | Protocol |
+|---------|------|----------|
+| Erigon HTTP RPC | 8945 | TCP |
+| Erigon Engine API (authrpc) | 8951 | TCP |
+| Erigon WebSocket | 8946 | TCP |
+| Erigon P2P | 30703 | TCP+UDP |
+| Erigon gRPC | 9490 | TCP |
+| Erigon Torrent | 42469 | TCP+UDP |
+| Erigon pprof | 6460 | TCP |
+| Erigon metrics | 6461 | TCP |
+| Lighthouse P2P | 9100 | TCP+UDP |
+| Lighthouse QUIC | 9101 | UDP |
+| Lighthouse HTTP API | 5352 | TCP |
+| Lighthouse metrics | 5464 | TCP |
+
+### Setup Instance B
+
+1. Create working directory and copy config:
+   ```bash
+   NOBAL_DIR=${WORKDIR}-nobal
+   mkdir -p $NOBAL_DIR/erigon-data $NOBAL_DIR/lighthouse-data
+   cp -r $WORKDIR/testnet-config $NOBAL_DIR/
+   cp $WORKDIR/genesis.json $NOBAL_DIR/
+   ```
+
+2. Build a binary with `IGNORE_BAL` support (requires bal-devnet-2 branch with commit `45625d09`+):
+   ```bash
+   # Build from bal-devnet-2 branch (or use existing binary if already up to date)
+   make erigon
+   ```
+
+3. Initialize genesis:
+   ```bash
+   ./build/bin/erigon init --datadir=$NOBAL_DIR/erigon-data $NOBAL_DIR/genesis.json
+   ```
+
+4. Create start scripts — same as Instance A but with:
+   - `export IGNORE_BAL=true` in `start-erigon.sh`
+   - Port offsets from the table above
+   - Docker container name: `bal-devnet-2-nobal-lighthouse`
+   - `--execution-endpoint=http://127.0.0.1:8951` in Lighthouse
+   - `--disable-enr-auto-update` in Lighthouse (second instance on same host)
+
+5. Start Instance B (erigon first, then Lighthouse):
+   ```bash
+   cd $NOBAL_DIR && nohup bash start-erigon.sh > erigon-console.log 2>&1 &
+   # Wait for jwt.hex
+   cd $NOBAL_DIR && nohup bash start-lighthouse.sh > lighthouse-console.log 2>&1 &
+   ```
+
+### Metrics to Compare
+
+Once both instances reach chain tip, compare at-head execution metrics:
+
+| Metric | Source | What it measures |
+|--------|--------|------------------|
+| `gas/s` | Execution log lines | Raw execution throughput |
+| `repeat%` | Execution log lines | Speculative re-execution rate (lower = better dependency prediction) |
+| `abort` | Execution log lines | Number of aborted transactions per batch |
+| `invalid` | Execution log lines | Transactions invalidated by conflict detection |
+| `blk/s` | Execution log lines | Block processing rate |
+
+**Expected**: BAL instance should have lower `repeat%` and `abort` counts because BAL pre-populates the version map, reducing false conflicts. The `gas/s` difference shows the net throughput impact.
+
+### Monitoring Script
+
+```bash
+# Side-by-side log comparison
+echo "=== BAL (Instance A) ===" && \
+grep -E "parallel (executed|done)" $WORKDIR/erigon-data/logs/erigon.log | tail -3 && \
+echo "" && \
+echo "=== No-BAL (Instance B) ===" && \
+grep -E "parallel (executed|done)" ${WORKDIR}-nobal/erigon-data/logs/erigon.log | tail -3
+```
+
+### Cleanup
+
+```bash
+# Stop Instance B
+docker stop bal-devnet-2-nobal-lighthouse 2>/dev/null
+pkill -f "datadir.*bal-devnet-2-nobal/erigon-data"
+# Optionally remove data
+rm -rf ${WORKDIR}-nobal
+```
+
 ## Troubleshooting
 
 | Problem | Solution |

.github/workflows/scripts/run_rpc_tests_ethereum.sh

@@ -41,4 +41,4 @@ DISABLED_TEST_LIST=(
 DISABLED_TESTS=$(IFS=,; echo "${DISABLED_TEST_LIST[*]}")
 
 # Call the main test runner script with the required and optional parameters
-"$(dirname "$0")/run_rpc_tests.sh" mainnet v1.122.0 "$DISABLED_TESTS" "$WORKSPACE" "$RESULT_DIR"
+"$(dirname "$0")/run_rpc_tests.sh" mainnet v1.123.0 "$DISABLED_TESTS" "$WORKSPACE" "$RESULT_DIR"

.github/workflows/scripts/run_rpc_tests_ethereum_latest.sh

@@ -34,4 +34,4 @@ DISABLED_TEST_LIST=(
 DISABLED_TESTS=$(IFS=,; echo "${DISABLED_TEST_LIST[*]}")
 
 # Call the main test runner script with the required and optional parameters
-"$(dirname "$0")/run_rpc_tests.sh" mainnet v1.122.0 "$DISABLED_TESTS" "$WORKSPACE" "$RESULT_DIR" "latest" "$REFERENCE_HOST" "do-not-compare-error-message" "$DUMP_RESPONSE"
+"$(dirname "$0")/run_rpc_tests.sh" mainnet v1.123.0 "$DISABLED_TESTS" "$WORKSPACE" "$RESULT_DIR" "latest" "$REFERENCE_HOST" "do-not-compare-error-message" "$DUMP_RESPONSE"

.github/workflows/scripts/run_rpc_tests_gnosis.sh

@@ -22,5 +22,5 @@ DISABLED_TEST_LIST=(
 DISABLED_TESTS=$(IFS=,; echo "${DISABLED_TEST_LIST[*]}")
 
 # Call the main test runner script with the required and optional parameters
-"$(dirname "$0")/run_rpc_tests.sh" gnosis v1.122.0 "$DISABLED_TESTS" "$WORKSPACE" "$RESULT_DIR"
+"$(dirname "$0")/run_rpc_tests.sh" gnosis v1.123.0 "$DISABLED_TESTS" "$WORKSPACE" "$RESULT_DIR"
 

.github/workflows/scripts/run_rpc_tests_remote_ethereum.sh

@@ -28,4 +28,4 @@ DISABLED_TEST_LIST=(
 DISABLED_TESTS=$(IFS=,; echo "${DISABLED_TEST_LIST[*]}")
 
 # Call the main test runner script with the required and optional parameters
-"$(dirname "$0")/run_rpc_tests.sh" mainnet v1.122.0 "$DISABLED_TESTS" "$WORKSPACE" "$RESULT_DIR"
+"$(dirname "$0")/run_rpc_tests.sh" mainnet v1.123.0 "$DISABLED_TESTS" "$WORKSPACE" "$RESULT_DIR"

.github/workflows/test-all-erigon.yml

@@ -46,6 +46,9 @@ jobs:
           # marginal timeouts while keeping Linux/macOS at the tighter 20m.
           - os: windows-2025
             test_timeout: 30m
+            skip_execution_tests: 'true'
+          - os: macos-15
+            skip_execution_tests: 'true'
     runs-on: ${{ matrix.os }}
 
     steps:
@@ -71,6 +74,7 @@ jobs:
         env:
           SKIP_FLAKY_TESTS: 'true'
           TEST_TIMEOUT: ${{ matrix.test_timeout || '20m' }}
+          ERIGON_SKIP_EXECUTION_TESTS: ${{ matrix.skip_execution_tests || '' }}
         run: |
           if ! make test-all GO_FLAGS="--timeout $TEST_TIMEOUT"; then
             # Retry after clearing the Go build cache. Low disk space can cause

.github/workflows/test-hive-eest.yml

@@ -19,14 +19,31 @@ jobs:
   test-hive-eest:
     runs-on:
       group: hive
+    name: test-hive-eest (${{ matrix.shard }})
     strategy:
       fail-fast: false
       matrix:
         include:
+          # consume-engine: split by fork for parallelism (61k+ tests total).
+          # Engine API tests only exist from Paris (The Merge) onwards.
+          # Pattern format: "<suite-regex>/<test-regex>" — the leading ".*/""
+          # matches the suite name (eest/consume-engine) while the remainder
+          # filters individual pytest test IDs by fork parameter.
           - sim: consume-engine
-            sim-limit: ""
+            sim-limit: ".*/.*fork_(Paris|Shanghai)"
+            shard: paris+shanghai
+          - sim: consume-engine
+            sim-limit: ".*/.*fork_Cancun"
+            shard: cancun
+          - sim: consume-engine
+            sim-limit: ".*/.*fork_Prague"
+            shard: prague
+          - sim: consume-engine
+            sim-limit: ".*/.*fork_Osaka"
+            shard: osaka
           - sim: consume-rlp
             sim-limit: ".*eip2930_access_list.*" # all tests take too long
+            shard: rlp
     steps:
       - name: Clean docker system
         run: |
@@ -120,28 +137,28 @@ jobs:
             failed=$(echo "$status_line" | sed -n 's/.*failed=\([0-9]*\).*/\1/p')
 
             echo -e "\n"
-            message="-----------   Results for ${1}    -----------\nTests: $tests, Failed: $failed\n\n============================================================"
+            message="-----------   Results for ${1} (${{ matrix.shard }})    -----------\nTests: $tests, Failed: $failed\n\n============================================================"
             echo -e "$message"
             echo -e "$message" >> result.log
 
             if (( tests < 4 )); then
-              echo "Too few tests run for suite ${1} - ${tests} tests"
+              echo "Too few tests run for ${{ matrix.shard }} - ${tests} tests"
               echo "failed" > failed.log
               exit 1
             fi
             if (( failed > 0 )); then
-              echo "Too many failures for suite ${1} - ${failed} failed out of ${tests}"
+              echo "Too many failures for ${{ matrix.shard }} - ${failed} failed out of ${tests}"
               echo "failed" > failed.log
               exit 1
             fi
           }
-          run_suite ${{ matrix.sim }} ${{ matrix.sim-limit }}
+          run_suite "${{ matrix.sim }}" "${{ matrix.sim-limit }}"
         continue-on-error: true
       - name: Upload output log
         if: always()
         uses: actions/upload-artifact@v6
         with:
-          name: hive-workspace-log-${{ matrix.sim }}
+          name: hive-workspace-log-${{ matrix.shard }}
           path: hive/workspace/logs
           if-no-files-found: ignore
       - name: Test Results

.github/workflows/test-hive.yml

@@ -60,7 +60,7 @@ jobs:
             max-allowed-failures: 0
           - sim: rpc
             sim-limit: compat
-            max-allowed-failures: 57 # 56 missing eth_simulateV1 MaxGasUsed in Hive tests + 1 https://github.com/erigontech/erigon/issues/19758
+            max-allowed-failures: 56 # 56 missing eth_simulateV1 MaxGasUsed in Hive tests 
     steps:
       - name: Checkout Erigon go.mod
         uses: actions/checkout@v6

.github/workflows/test-integration-caplin.yml

@@ -37,16 +37,14 @@ jobs:
       - uses: ./.github/actions/setup-erigon
         id: erigon
 
-      - name: Download consensus spec tests
-        id: download-spec-tests
-        continue-on-error: true
-        run: cd cl/spectest && make download-spec
-
-      - name: Run consensus spec tests
-        if: steps.download-spec-tests.outcome == 'success'
+      - name: test-integration-caplin
         run: |
-          cd cl/spectest && make tests
-          make mainnet 2>&1 | ../../tools/filter-test-output | tee run.log
+          cd cl/spectest
+          if make tests; then
+            make mainnet 2>&1 | ../../tools/filter-test-output | tee run.log
+          else
+            echo "::warning::consensus spec test setup failed; skipping mainnet tests"
+          fi
 
       - uses: ./.github/actions/cleanup-erigon
         if: always()

agents.md

@@ -56,6 +56,10 @@ Cherry-pick PRs: when opening a PR that cherry-picks a commit to a `release/X.Y`
 
 **Important**: Always run `make lint` after making code changes and before committing. Fix any linter errors before proceeding. PRs must pass `make lint` before being opened or updated.
 
+## Pull Requests & Workflows
+
+When manually dispatching a workflow that is not part of the PR's automatic check list, add a comment on the PR explaining which workflow was dispatched, why it was chosen, and include a direct link to the workflow run.
+
 ## Pre-push
 
 Before running `git push`, always run `make lint` first and fix all issues. Run lint multiple times if needed — it is non-deterministic.