Skip to content

flashbots/buildernet-playground

Repository files navigation

BuilderNet Playground

⚠️ Pre-Alpha Proof of Concept ⚠️

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.

Overview

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

Status

  • This is experimental software
  • Not ready for production use
  • Features and architecture may change without notice
  • Documentation is minimal and in progress

BuilderNet Playground Setup Guide

This guide will walk you through setting up BuilderNet Playground, a local development environment for Ethereum MEV builders.

Prerequisites

  • Linux environment with Docker, QEMU, and Git installed
  • Basic familiarity with command-line tools
  • Go installed for building components

Setup Process

1. Clone the Repository

git clone --recursive https://github.com/flashbots/buildernet-playground.git
cd buildernet-playground

2. Start Builder Playground Environment

# 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

3. Setup Builder Hub

# 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 ..

4. Run the VM

# 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.

5. Perform Post-Provisioning

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

6. Verify the Setup

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

System Architecture

The following diagram shows the relationship between components:

BuilderNet Architecture

Full Development Cycle

  1. Start builder-playground services on the host
  2. Setup the builder-hub database
  3. Run the VM with make run-gz
  4. Execute post-provisioning with make post-provision
  5. Connect to the VM and verify Ethereum clients are running
  6. Submit builder payload via the builder-hub API on port 8888

The environment is now ready for testing MEV block building and related functionality!

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published