This project is currently in pre-alpha stage and is being actively developed as a proof of concept. The codebase is under heavy construction and may undergo significant changes.
BuilderNet Playground is a toolset for customizing and deploying a local dev instance of BuilderNet, this includes:
- QEMU virtual machine configuration
- Disk encryption
- Ethereum client integration (Reth and Lighthouse)
- Debugging tools
- Integration with builder-playground
- This is experimental software
- Not ready for production use
- Features and architecture may change without notice
- Documentation is minimal and in progress
This guide will walk you through setting up BuilderNet Playground, a local development environment for Ethereum MEV builders.
- Linux environment with Docker, QEMU, and Git installed
- Basic familiarity with command-line tools
- Go installed for building components
git clone --recursive https://github.com/flashbots/buildernet-playground.git
cd buildernet-playground
# Navigate to builder-playground directory
cd builder-playground
# Build the playground executable
go build -o builder-playground
# Start the environment and generate testnet files
./builder-playground cook buildernet --output output
# Wait for all services to start
# This creates the testnet files needed for the VM
# Clone the builder-hub repository (if not already done)
git clone https://github.com/flashbots/builder-hub.git
cd builder-hub
# Setup the development database with local configurations
make dev-db-setup
# Return to main directory
cd ..
# This single command will extract the initramfs, inject custom scripts,
# create the QEMU disk image, and run the VM
# Prior running this command, please make sure you downloaded
# the buildernet image artificats:
# "bzImage"
# "cvm-initramfs-tdx.cpio.gz"
make run-gz
The VM will pause during boot for debugging. You should see output indicating SSH access is available at ssh -p 10022 root@localhost
.
In a new terminal, run:
# Transfer the required files from builder-playground to the VM
make post-provision
This command:
- Copies genesis.json and testnet configuration
- Configures proper permissions
- Continues the VM boot process
After post-provisioning, the VM will continue booting and start the Ethereum clients. Connect to the VM to check the status:
ssh -p 10022 root@localhost
# Inside the VM, check service logs
tail -f /var/log/lighthouse.log
tail -f /var/log/reth.log
The following diagram shows the relationship between components:
- Start builder-playground services on the host
- Setup the builder-hub database
- Run the VM with
make run-gz
- Execute post-provisioning with
make post-provision
- Connect to the VM and verify Ethereum clients are running
- Submit builder payload via the builder-hub API on port 8888
The environment is now ready for testing MEV block building and related functionality!