Buildoor: Ethereum PBS Testing Tool

Work in Progress - This project is under active development. APIs, configuration flags, and behavior may change without notice.

Devnet & Testnet Use Only - Buildoor is a testing tool designed exclusively for Ethereum devnets and testnets. It is not intended to be profitable or used on mainnet. Its sole purpose is to exercise and validate the block builder flow during protocol development and testing.

Buildoor is an Ethereum block builder that supports two modes of operation: ePBS (enshrined Proposer-Builder Separation) for the upcoming Gloas fork, and the traditional Builder API for pre-ePBS forks (Fulu and earlier). It connects to consensus layer (CL) and execution layer (EL) clients to build blocks, submit bids, and manage builder lifecycle operations.

Builder Modes

ePBS (Enshrined Proposer-Builder Separation)

The ePBS mode is designed for the Gloas fork, where proposer-builder separation is enshrined directly into the Ethereum protocol. In this mode, Buildoor:

• Builds execution payloads via the Engine API
• Submits bids to the beacon node on a configurable time schedule relative to slot boundaries
• Reveals payloads at a configured time after the block is proposed
• Tracks bid competition and payload inclusion on-chain
• Requires the builder to be registered on the beacon chain with a deposit (managed via --lifecycle)

ePBS is automatically available when the connected beacon node has the Gloas fork epoch configured. Use --epbs-enabled to activate bidding/revealing at startup.

Builder API

The Builder API mode implements the traditional MEV-Boost Builder API for pre-ePBS forks. In this mode, Buildoor:

• Runs a Builder API HTTP server that validators/relays can connect to
• Accepts validator registrations with fee recipient preferences
• Responds to getHeader requests with signed bid headers
• Publishes full blocks when a proposer submits a blinded block via submitBlindedBlock
• Supports a configurable block value subsidy to make bids more attractive for testing

Enable with --builder-api-enabled --builder-api-port <port>.

Building

# Build the binary (includes frontend)
make build

# Build Docker image
make docker

# Run tests
make test

Requires Go 1.25+ and Node.js 20+ (for the frontend).

Usage

Required Flags

Every run requires these four flags:

Basic Example

buildoor run \
  --builder-privkey <BLS_PRIVATE_KEY> \
  --cl-client http://localhost:5052 \
  --el-engine-api http://localhost:8551 \
  --el-jwt-secret /path/to/jwt.hex

ePBS Example

buildoor run \
  --builder-privkey <BLS_PRIVATE_KEY> \
  --cl-client http://localhost:5052 \
  --el-engine-api http://localhost:8551 \
  --el-jwt-secret /path/to/jwt.hex \
  --epbs-enabled \
  --lifecycle \
  --el-rpc http://localhost:8545 \
  --wallet-privkey <ECDSA_PRIVATE_KEY>

Builder API Example

buildoor run \
  --builder-privkey <BLS_PRIVATE_KEY> \
  --cl-client http://localhost:5052 \
  --el-engine-api http://localhost:8551 \
  --el-jwt-secret /path/to/jwt.hex \
  --builder-api-enabled \
  --builder-api-port 18550

Configuration Reference

Configuration can be provided via CLI flags, a YAML config file (--config path/to/config.yaml), or an environment variables.

Core Flags

Builder API Flags

ePBS Flags

Schedule Flags

Lifecycle Flags

Other Flags

WebUI

Buildoor includes a web dashboard for monitoring builder activity in real time. Enable it with --api-port <port> and open http://localhost:<port> in your browser.

The dashboard provides:

• Real-time slot timeline and bid tracking via Server-Sent Events (SSE)
• Builder statistics and configuration management
• Bids Won tracking (Builder API mode)
• Validator registration overview

Local Development

# Start a local devnet
make devnet

# Run buildoor against the devnet
make devnet-run-docker

# Clean up the devnet
make devnet-clean

The devnet launches canonical buildoor instances via the ethereum-package (buildoor_params.instances in .hack/devnet/custom-kurtosis.devnet.config.yaml). make devnet-run / make devnet-run-docker stop the first canonical instance and run your local build in its place — same builder key, wallet and service name — so it receives the CL's builder API calls. Use BUILDOOR_INDEX=<n> (or BUILDOOR_SERVICE=<name>) to replace a different instance.

For frontend development:

cd pkg/webui
npm install
npm run dev    # watch mode

Docker

# Build
docker build -t buildoor .

# Run
docker run --rm buildoor run --help

License

See LICENSE for details.