feat(mev): add custom mev_type with component-based relay/sidecar/builder resolution

.github/tests/mev-custom-helix-cb.yaml

@@ -0,0 +1,112 @@
+participants:
+  - el_type: geth
+    el_image: ethpandaops/geth:master
+    cl_type: lighthouse
+    cl_image: ethpandaops/lighthouse:unstable
+    vc_image: ethpandaops/lighthouse:unstable
+    supernode: true
+    count: 2
+
+additional_services:
+  - dora
+  - spamoor
+
+# Custom MEV config: Helix relay + Commit-Boost sidecar + Flashbots builder
+# Tests inline helix_relay_config override. commit-boost uses default template.
+mev_type: custom
+mev_params:
+  mev_relay: helix
+  mev_sidecar: commit-boost
+  mev_builder: flashbots
+  helix_relay_image: ghcr.io/gattaca-com/helix-relay:main
+  mev_boost_image: ghcr.io/commit-boost/pbs:latest
+  mev_builder_image: ethpandaops/reth-rbuilder:develop
+  mev_builder_cl_image: ethpandaops/lighthouse:unstable
+  mev_builder_subsidy: 1
+  helix_relay_config: |
+    instance_id: "custom-helix-cb-test"
+
+    network_config: !Custom
+      dir_path: "{{ .GENESIS_CONFIG_MOUNT_PATH_ON_CONTAINER }}/config.json"
+      genesis_validator_root: "{{ .GENESIS_VALIDATORS_ROOT }}"
+      genesis_time: {{ .GENESIS_TIME }}
+
+    postgres:
+      hostname: "{{ .POSTGRES_HOST_NAME }}"
+      port: {{ .POSTGRES_PORT }}
+      db_name: "{{ .POSTGRES_DB }}"
+      user: "{{ .POSTGRES_USER }}"
+      password: "{{ .POSTGRES_PASS }}"
+      region: 0
+      region_name: "LOCAL"
+
+    beacon_clients:
+      - url: "{{ .BEACON_URI }}"
+
+    gossip_payload_on_header: false
+
+    simulators:
+      - url: "{{ .BLOCKSIM_URI }}"
+        namespace: flashbots
+        is_merging_simulator: false
+        max_concurrent_tasks: 32
+
+    router_config:
+      enabled_routes:
+        - route: GetValidators
+        - route: SubmitBlock
+        - route: GetTopBid
+        - route: GetHeader
+          rate_limit:
+            replenish_ms: 50
+            burst_size: 20
+        - route: GetPayload
+        - route: RegisterValidators
+        - route: Status
+        - route: ProposerPayloadDelivered
+        - route: BuilderBidsReceived
+        - route: ValidatorRegistration
+      shutdown_delay_ms: 12000
+
+    timing_game_config:
+      max_header_delay_ms: 400
+      latest_header_delay_ms_in_slot: 1500
+      default_client_latency_ms: 50
+
+    target_get_payload_propagation_duration_ms: 500
+
+    is_submission_instance: true
+    is_registration_instance: true
+
+    admin_token: "test_admin_token"
+
+    logging:
+      type: Console
+
+    cores:
+      auctioneer: 0
+      sub_workers: [0]
+      reg_workers: [0]
+      tokio: [0]
+      tcp_bid_submissions_tile: 2
+
+    is_local_dev: false
+
+
+spamoor_params:
+  spammers:
+    - name: "Blob Spammer"
+      scenario: "blobs"
+      config:
+        throughput: 10
+    - name: "ERC txs"
+      scenario: "erctx"
+      config:
+        throughput: 50
+        max_pending: 400
+
+network_params:
+  min_validator_withdrawability_delay: 1
+  shard_committee_period: 1
+  churn_limit_quotient: 16
+  prefunded_accounts: '{"0xb9e79d19f651a941757b35830232e7efc77e1c79": {"balance": "100000ETH"}}'

README.md

@@ -1470,6 +1470,7 @@ mempool_bridge_params:
 #            Note: Helix uses TimescaleDB (PostgreSQL with time-series extension) for data storage
 # "buildoor" - a self-contained builder+relay service & mev-boost are spun up, powered by [buildoor](https://github.com/ethpandaops/buildoor)
 #              Supports both legacy builder API and ePBS bidding. No separate relay infrastructure or builder participant needed.
+# "custom" - mix and match relay, sidecar, and builder components via mev_params.mev_relay, mev_params.mev_sidecar, mev_params.mev_builder
 # We have seen instances of multibuilder instances failing to start mev-relay-api with non zero epochs
 mev_type: null
 
@@ -1538,6 +1539,20 @@ mev_params:
   #     [logs.stdout]
   #     level = "debug"
   commit_boost_config: ""
+  # Inline Helix relay config template. When set, replaces the default auto-generated config.
+  # Template variables {{ .GENESIS_TIME }}, {{ .BEACON_URI }}, {{ .GENESIS_VALIDATORS_ROOT }},
+  # {{ .POSTGRES_HOST_NAME }}, {{ .POSTGRES_PORT }}, {{ .POSTGRES_DB }}, {{ .POSTGRES_USER }},
+  # {{ .POSTGRES_PASS }}, {{ .BLOCKSIM_URI }}, {{ .GENESIS_CONFIG_MOUNT_PATH_ON_CONTAINER }}
+  # are rendered at enclave creation.
+  helix_relay_config: ""
+  # Component overrides for custom mev_type (required when mev_type is "custom", optional otherwise)
+  # mev_relay: which relay to launch. Valid: "flashbots", "helix", "mev-rs", "mock", "none"
+  # mev_sidecar: which per-validator PBS service. Valid: "mev-boost", "commit-boost", "mev-rs", "none"
+  # mev_builder: which block builder. Valid: "flashbots", "mev-rs", "buildoor", "mock", "none"
+  # When used with a preset mev_type (e.g. "flashbots"), these override individual components.
+  mev_relay: ""
+  mev_sidecar: ""
+  mev_builder: ""
 
 # Parameters for the buildoor builder+relay service (used when mev_type is "buildoor")
 buildoor_params:
@@ -1985,6 +2000,42 @@ network_params:
 
 </details>
 
+<details>
+    <summary>Custom MEV: Helix relay + Commit-Boost sidecar + Flashbots builder</summary>
+
+```yaml
+participants:
+  - el_type: geth
+    el_image: ethpandaops/geth:master
+    cl_type: lighthouse
+    cl_image: ethpandaops/lighthouse:unstable
+    vc_image: ethpandaops/lighthouse:unstable
+    supernode: true
+    count: 2
+
+mev_type: custom
+mev_params:
+  mev_relay: helix
+  mev_sidecar: commit-boost
+  mev_builder: flashbots
+  helix_relay_image: ghcr.io/gattaca-com/helix-relay:main
+  mev_boost_image: ghcr.io/commit-boost/pbs:latest
+  mev_builder_image: ethpandaops/reth-rbuilder:develop
+  mev_builder_cl_image: ethpandaops/lighthouse:unstable
+  mev_builder_subsidy: 1
+
+additional_services:
+  - dora
+  - spamoor
+
+network_params:
+  min_validator_withdrawability_delay: 1
+  shard_committee_period: 1
+  prefunded_accounts: '{"0xb9e79d19f651a941757b35830232e7efc77e1c79": {"balance": "100000ETH"}}'
+```
+
+</details>
+
 <details>
     <summary>A 2-node geth/lighthouse network with optional services (Grafana, Prometheus, tx_fuzz, EngineAPI snooper)</summary>
 
@@ -2156,9 +2207,19 @@ The package also supports other MEV implementations:
 - `"mev_type": "mev-rs"` - Alternative relay implementation powered by [mev-rs](https://github.com/ralexstokes/mev-rs/)
 - `"mev_type": "commit-boost"` - Infrastructure powered by [commit-boost](https://github.com/Commit-Boost/commit-boost-client)
 - `"mev_type": "buildoor"` - A self-contained builder+relay service powered by [buildoor](https://github.com/ethpandaops/buildoor). Supports both legacy builder API and ePBS bidding without requiring separate relay infrastructure or a dedicated builder participant.
+- `"mev_type": "custom"` - Mix and match any relay, sidecar, and builder via `mev_params.mev_relay`, `mev_params.mev_sidecar`, `mev_params.mev_builder`. For example, Helix relay + Commit-Boost sidecar + Flashbots builder.
 
 Each implementation provides different features and performance characteristics suitable for various testing and development scenarios.
 
+You can also override individual components on any preset. For example, to use commit-boost as the sidecar with an otherwise-standard flashbots setup:
+
+```yaml
+mev_type: flashbots
+mev_params:
+  mev_sidecar: commit-boost
+  mev_boost_image: ghcr.io/commit-boost/pbs:latest
+```
+
 <details>
     <summary>Caveats when using "mev_type": "flashbots"</summary>