feat: add buildoor as separate mev stack (#1309)

## Summary
- Add `buildoor` as a new MEV type - a self-contained builder+relay
service that integrates with standard flashbots mev-boost
- Unlike flashbots/helix/mev-rs, buildoor doesn't require separate relay
infrastructure or a dedicated builder participant
- Configurable via `buildoor_params` with support for legacy builder API
(`--builder-api-enabled`) and ePBS (`--epbs-enabled`)

## Settings

`mev_type: buildoor`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `buildoor_params.image` | string | `ethpandaops/buildoor:main` |
Docker image for the buildoor service |
| `buildoor_params.builder_api` | bool | `true` | Enable the traditional
Builder API (`--builder-api-enabled`) |
| `buildoor_params.epbs_builder` | bool | `true` | Enable ePBS bidding
and revealing (`--epbs-enabled`) |
| `buildoor_params.extra_args` | list | `[]` | Additional CLI flags
passed to the buildoor service |

## Example
Run `kurtosis run . --args-file .github/tests/mev-buildoor.yaml` and see
buildoor url in services

## Buildoor Screenshot
<img width="1861" height="1005" alt="image"
src="https://github.com/user-attachments/assets/9a3b2c1b-11bd-4711-9ff9-2b6481213223"
/>

---------

Co-authored-by: Barnabas Busa <barnabas.busa@ethereum.org>

Author: pk910

.github/tests/mev-buildoor.yaml

@@ -0,0 +1,11 @@
+participants:
+  - el_type: geth
+    cl_type: lighthouse
+    count: 2
+mev_type: buildoor
+buildoor_params:
+  builder_api: true
+  epbs_builder: true
+additional_services:
+  - dora
+  - spamoor

README.md

@@ -1272,14 +1272,16 @@ mempool_bridge_params:
   # Default: "30s"
   retry_interval: "30s"
 
-# Supports six values
+# Supports seven values
 # Default: "null" - no mev boost, mev builder, mev flood or relays are spun up
 # "mock" - mock-builder & mev-boost are spun up
 # "flashbots" - mev-boost, relays, flooder and builder are all spun up, powered by [flashbots](https://github.com/flashbots)
 # "mev-rs" - mev-boost, relays and builder are all spun up, powered by [mev-rs](https://github.com/ralexstokes/mev-rs/)
 # "commit-boost" - mev-boost, relays and builder are all spun up, powered by [commit-boost](https://github.com/Commit-Boost/commit-boost-client)
 # "helix" - helix relay, flashbots builder and mev-boost are spun up, powered by [helix](https://github.com/gattaca-com/helix)
 #            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.
 # We have seen instances of multibuilder instances failing to start mev-relay-api with non zero epochs
 mev_type: null
 
@@ -1331,6 +1333,17 @@ mev_params:
   # The image to use for helix relay (used when run_multiple_relays is true or mev_type is helix)
   helix_relay_image: ghcr.io/gattaca-com/helix-relay:main
 
+# Parameters for the buildoor builder+relay service (used when mev_type is "buildoor")
+buildoor_params:
+  # The image to use for buildoor
+  image: ethpandaops/buildoor:main
+  # Enable the legacy builder API (traditional block building via relay)
+  builder_api: true
+  # Enable ePBS bidding and revealing
+  epbs_builder: true
+  # Extra parameters to pass to the buildoor service
+  extra_args: []
+
 # Enables Xatu Sentry for all participants
 # Defaults to false
 xatu_sentry_enabled: false
@@ -1662,6 +1675,25 @@ network_params:
 
 </details>
 
+<details>
+    <summary>A 2-node Ethereum network with buildoor (self-contained builder+relay)</summary>
+
+```yaml
+participants:
+  - el_type: geth
+    cl_type: lighthouse
+    count: 2
+mev_type: buildoor
+buildoor_params:
+  builder_api: true
+  epbs_builder: true
+additional_services:
+  - dora
+  - spamoor
+```
+
+</details>
+
 <details>
     <summary>A 3-node Ethereum network with Helix relay for MEV-boost infrastructure</summary>
 
@@ -1865,6 +1897,7 @@ The package also supports other MEV implementations:
 - `"mev_type": "helix"` - Uses the high-performance [Helix relay](https://github.com/gattaca-com/helix) with TimescaleDB backend for data storage
 - `"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.
 
 Each implementation provides different features and performance characteristics suitable for various testing and development scenarios.
 

main.star

@@ -52,6 +52,7 @@ flashbots_mev_relay = import_module(
 )
 helix_relay = import_module("./src/mev/helix/helix_relay_launcher.star")
 mock_mev = import_module("./src/mev/flashbots/mock_mev/mock_mev_launcher.star")
+buildoor = import_module("./src/mev/buildoor/buildoor_launcher.star")
 mev_custom_flood = import_module(
     "./src/mev/flashbots/mev_custom_flood/mev_custom_flood_launcher.star"
 )
@@ -367,6 +368,35 @@ def run(plan, args={}):
         )
         mev_endpoints.append(endpoint)
         mev_endpoint_names.append(constants.MOCK_MEV_TYPE)
+    elif (
+        args_with_right_defaults.mev_type
+        and args_with_right_defaults.mev_type == constants.BUILDOOR_MEV_TYPE
+    ):
+        beacon_uri = "http://{0}:{1}".format(
+            all_cl_contexts[0].ip_address,
+            all_cl_contexts[0].http_port,
+        )
+        el_rpc_uri = "http://{0}:{1}".format(
+            all_el_contexts[0].ip_addr,
+            all_el_contexts[0].rpc_port_num,
+        )
+        engine_rpc_uri = "http://{0}:{1}".format(
+            all_el_contexts[0].ip_addr,
+            all_el_contexts[0].engine_rpc_port_num,
+        )
+        endpoint = buildoor.launch_buildoor(
+            plan,
+            beacon_uri,
+            el_rpc_uri,
+            engine_rpc_uri,
+            jwt_file,
+            prefunded_accounts[0].private_key,
+            args_with_right_defaults.buildoor_params,
+            global_node_selectors,
+            global_tolerations,
+        )
+        mev_endpoints.append(endpoint)
+        mev_endpoint_names.append(constants.BUILDOOR_MEV_TYPE)
     elif args_with_right_defaults.mev_type and (
         args_with_right_defaults.mev_type == constants.FLASHBOTS_MEV_TYPE
         or args_with_right_defaults.mev_type == constants.MEV_RS_MEV_TYPE
@@ -496,6 +526,7 @@ def run(plan, args={}):
                     args_with_right_defaults.mev_type == constants.FLASHBOTS_MEV_TYPE
                     or args_with_right_defaults.mev_type == constants.MOCK_MEV_TYPE
                     or args_with_right_defaults.mev_type == constants.HELIX_MEV_TYPE
+                    or args_with_right_defaults.mev_type == constants.BUILDOOR_MEV_TYPE
                 ):
                     mev_boost_launcher = flashbots_mev_boost.new_mev_boost_launcher(
                         MEV_BOOST_SHOULD_CHECK_RELAY,

network_params.yaml

@@ -190,7 +190,7 @@ ethereum_metrics_exporter_enabled: false
 parallel_keystore_generation: false
 disable_peer_scoring: false
 persistent: false
-# Supports: null, mock, flashbots, mev-rs, commit-boost, helix
+# Supports: null, mock, flashbots, mev-rs, commit-boost, helix, buildoor
 mev_type: null
 mev_params:
   mev_relay_image: ethpandaops/mev-boost-relay:main
@@ -213,6 +213,11 @@ mev_params:
   helix_relay_image: ghcr.io/gattaca-com/helix-relay:main
   custom_flood_params:
     interval_between_transactions: 1
+buildoor_params:
+  image: ethpandaops/buildoor:main
+  builder_api: true
+  epbs_builder: true
+  extra_args: []
 bootnodoor_params:
   image: ethpandaops/bootnodoor:latest
   min_cpu: 100

src/mev/buildoor/buildoor_launcher.star

@@ -0,0 +1,83 @@
+constants = import_module("../../package_io/constants.star")
+shared_utils = import_module("../../shared_utils/shared_utils.star")
+
+BUILDOOR_SERVICE_NAME = "buildoor"
+BUILDOOR_API_PORT = 8080
+BUILDOOR_BUILDER_API_PORT = 9000
+
+MIN_CPU = 100
+MAX_CPU = 1000
+MIN_MEMORY = 128
+MAX_MEMORY = 1024
+
+
+def launch_buildoor(
+    plan,
+    beacon_uri,
+    el_rpc_uri,
+    engine_rpc_uri,
+    jwt_file,
+    prefunded_key,
+    buildoor_params,
+    global_node_selectors,
+    global_tolerations,
+):
+    tolerations = shared_utils.get_tolerations(global_tolerations=global_tolerations)
+
+    # Strip 0x prefix if present since keys are expected as hex-only
+    wallet_key = prefunded_key
+    if wallet_key.startswith("0x"):
+        wallet_key = wallet_key[2:]
+
+    # Use the existing BLS keypair from constants for builder identity
+    builder_bls_key = constants.DEFAULT_MEV_SECRET_KEY[2:]
+
+    cmd = [
+        "run",
+        "--cl-client={0}".format(beacon_uri),
+        "--el-rpc={0}".format(el_rpc_uri),
+        "--el-engine-api={0}".format(engine_rpc_uri),
+        "--el-jwt-secret=" + constants.JWT_MOUNT_PATH_ON_CONTAINER,
+        "--builder-privkey={0}".format(builder_bls_key),
+        "--wallet-privkey={0}".format(wallet_key),
+        "--api-port={0}".format(BUILDOOR_API_PORT),
+        "--builder-api-port={0}".format(BUILDOOR_BUILDER_API_PORT),
+    ]
+
+    if buildoor_params.builder_api:
+        cmd.append("--builder-api-enabled")
+
+    if buildoor_params.epbs_builder:
+        cmd.append("--epbs-enabled")
+
+    cmd += buildoor_params.extra_args
+
+    buildoor_service = plan.add_service(
+        name=BUILDOOR_SERVICE_NAME,
+        config=ServiceConfig(
+            image=buildoor_params.image,
+            ports={
+                "api": PortSpec(
+                    number=BUILDOOR_API_PORT,
+                    transport_protocol="TCP",
+                    application_protocol="http",
+                ),
+                "builder-api": PortSpec(
+                    number=BUILDOOR_BUILDER_API_PORT, transport_protocol="TCP"
+                ),
+            },
+            cmd=cmd,
+            files={
+                constants.JWT_MOUNTPOINT_ON_CLIENTS: jwt_file,
+            },
+            min_cpu=MIN_CPU,
+            max_cpu=MAX_CPU,
+            min_memory=MIN_MEMORY,
+            max_memory=MAX_MEMORY,
+            node_selectors=global_node_selectors,
+            tolerations=tolerations,
+        ),
+    )
+    return "http://{0}@{1}:{2}".format(
+        constants.DEFAULT_MEV_PUBKEY, BUILDOOR_SERVICE_NAME, BUILDOOR_BUILDER_API_PORT
+    )

src/package_io/constants.star

@@ -97,6 +97,7 @@ FLASHBOTS_MEV_TYPE = "flashbots"
 MEV_RS_MEV_TYPE = "mev-rs"
 COMMIT_BOOST_MEV_TYPE = "commit-boost"
 HELIX_MEV_TYPE = "helix"
+BUILDOOR_MEV_TYPE = "buildoor"
 DEFAULT_DORA_IMAGE = "ethpandaops/dora:latest"
 DEFAULT_CHECKPOINTZ_IMAGE = "ethpandaops/checkpointz:latest"
 DEFAULT_SPAMOOR_IMAGE = "ethpandaops/spamoor:latest"
@@ -114,6 +115,7 @@ DEFAULT_MEV_RS_IMAGE = "ethpandaops/mev-rs:main"
 DEFAULT_MEV_RS_IMAGE_MINIMAL = "ethpandaops/mev-rs:main-minimal"
 DEFAULT_COMMIT_BOOST_MEV_BOOST_IMAGE = "ghcr.io/commit-boost/pbs:latest"
 DEFAULT_MOCK_MEV_IMAGE = "ethpandaops/rustic-builder:main"
+DEFAULT_BUILDOOR_IMAGE = "ethpandaops/buildoor:main"
 DEFAULT_HELIX_RELAY_IMAGE = "ghcr.io/gattaca-com/helix-relay:main"
 DEFAULT_EWS_IMAGE = "ghcr.io/eth-act/zkboost/execution-witness-sentry:latest"
 DEFAULT_MEV_PUBKEY = "0xa55c1285d84ba83a5ad26420cd5ad3091e49c55a813eee651cd467db38a8c8e63192f47955e9376f6b42f6d190571cb5"

src/package_io/input_parser.star

@@ -90,6 +90,7 @@ ATTR_TO_BE_SKIPPED_AT_ROOT = (
     "bootnodoor_params",
     "mempool_bridge_params",
     "ews_params",
+    "buildoor_params",
     "ethereum_genesis_generator_params",
 )
 
@@ -129,6 +130,7 @@ def input_parser(plan, input_args):
     result["spamoor_params"] = get_default_spamoor_params()
     result["mempool_bridge_params"] = get_default_mempool_bridge_params()
     result["ews_params"] = get_default_ews_params()
+    result["buildoor_params"] = get_default_buildoor_params()
 
     if constants.NETWORK_NAME.shadowfork in result["network_params"]["network"]:
         shadow_base = result["network_params"]["network"].split("-shadowfork")[0]
@@ -222,6 +224,10 @@ def input_parser(plan, input_args):
             for sub_attr in input_args["ews_params"]:
                 sub_value = input_args["ews_params"][sub_attr]
                 result["ews_params"][sub_attr] = sub_value
+        elif attr == "buildoor_params":
+            for sub_attr in input_args["buildoor_params"]:
+                sub_value = input_args["buildoor_params"][sub_attr]
+                result["buildoor_params"][sub_attr] = sub_value
 
     if result.get("disable_peer_scoring"):
         result = enrich_disable_peer_scoring(result)
@@ -232,6 +238,7 @@ def input_parser(plan, input_args):
         constants.MEV_RS_MEV_TYPE,
         constants.COMMIT_BOOST_MEV_TYPE,
         constants.HELIX_MEV_TYPE,
+        constants.BUILDOOR_MEV_TYPE,
     ):
         result = enrich_mev_extra_params(
             result,
@@ -243,7 +250,7 @@ def input_parser(plan, input_args):
         pass
     else:
         fail(
-            "Unsupported MEV type: {0}, please use 'mock', 'flashbots', 'mev-rs', 'commit-boost' or 'helix' type".format(
+            "Unsupported MEV type: {0}, please use 'mock', 'flashbots', 'mev-rs', 'commit-boost', 'helix' or 'buildoor' type".format(
                 result.get("mev_type")
             )
         )
@@ -932,6 +939,12 @@ def input_parser(plan, input_args):
             num_proofs=result["ews_params"]["num_proofs"],
             env=result["ews_params"]["env"],
         ),
+        buildoor_params=struct(
+            image=result["buildoor_params"]["image"],
+            extra_args=result["buildoor_params"]["extra_args"],
+            builder_api=result["buildoor_params"]["builder_api"],
+            epbs_builder=result["buildoor_params"]["epbs_builder"],
+        ),
     )
 
 
@@ -1900,6 +1913,15 @@ def get_default_ews_params():
     }
 
 
+def get_default_buildoor_params():
+    return {
+        "image": constants.DEFAULT_BUILDOOR_IMAGE,
+        "extra_args": [],
+        "builder_api": True,
+        "epbs_builder": True,
+    }
+
+
 def get_port_publisher_params(parameter_type, input_args=None):
     port_publisher_parameters = {
         "nat_exit_ip": "KURTOSIS_IP_ADDR_PLACEHOLDER",

src/package_io/sanity_check.star

@@ -427,6 +427,12 @@ SUBCATEGORY_PARAMS = {
         "num_proofs",
         "env",
     ],
+    "buildoor_params": [
+        "image",
+        "extra_args",
+        "builder_api",
+        "epbs_builder",
+    ],
 }
 
 ADDITIONAL_SERVICES_PARAMS = [