Skip to main content

Setup Guide

Setup a builder with the ethgas-builder-scripts repo.

Prerequisites​

Before setting up your builder, ensure you have:

1. Docker

For containerized deployment

2. Network Access

Ability to connect to ETHGas APIs

3. BLS Key Pair

Your BLS public and secret keys

4. Entity Information

Your company/entity name for registration

5. EOA Signing Key

Your registered or to-be-registered account on ETHGas Exchange

info

The JWT access token is valid for 1 hour; after each hour an access token refresh is required. A private REST request needs to include the JWT in the request header: Authorization: 'Bearer accessToken'. A private session is valid for 7 days; after 7 days a re-login is required. For WebSocket, include the access token in the session header: Bearer accessToken.

Quick Start​

Clone the Repository​

git clone https://github.com/ethgas-developer/ethgas-builder-scripts
cd ethgas-builder-scripts

Configure Environment Variables​

cp .env.example.mainnet .env

The .env.example.mainnet file contains production settings:

EXCHANGE_API_BASE="https://mainnet.app.ethgas.com/api"
CHAIN=Mainnet
BLS_PUBKEY=0x...
BLS_SECRET_KEY=0x...
EOA_SIGNING_KEY=0x...
ENTITY_NAME="TestBuilder"
ENABLE_REGISTRATION=true

Build and Deploy​

./scripts/build.sh

docker-compose -f docker-compose.yml up

Key Management​

BLS Key Pair​

Your BLS key pair is essential for builder identification and block signing:

  • BLS_PUBKEY: Your BLS public key (required for registration)
  • BLS_SECRET_KEY: Your BLS secret key (keep secure, never commit to version control)

EOA Signing Key​

Your EOA signing key is used for authentication and fee collection:

  • Must be a registered account or a to-be-registered account on ETHGas Exchange
  • Used for signing registration transactions
  • Required for fee distribution

Registration Process​

Automatic Registration​

When ENABLE_REGISTRATION=true:

  • ✅ Validate keys — Verify BLS and EOA keys are valid
  • ✅ Check registration — Verify if already registered
  • ✅ Submit registration — Register with ETHGas Exchange
  • ✅ Confirm status — Verify registration was successful

Manual Registration​

curl -H "Authorization: Bearer {{access_token}}" -X POST "$ETHGAS_API_URL/v1/builder/register?publicKeys=0x12345...,0x234134...&signatures=2asdfjghadg,xghlktdhj"

Request Parameters

ParameterRequiredTypeDescription
publicKeysYesstringComma separated list of builder BLS public keys in hex
signaturesYesstringComma separated list of BLS signatures in hex

Response Example

{
    "success": true,
    "data": {
        "results": [
            {
                "publicKey": "0xa25addc4fc16f72ca667177d7a5533d4287b3574f0127ffc227095e90b0b1fd0dd48c421e04e613d2298fe4dac83a2a5",
                "result": {
                    "result": 0,
                    "description": "Success"
                }
            }
        ]
    }
}
note

Please refer to Lookup Tables as needed for result codes.

Integration with Modified rbuilder​

Installation​

# Clone the modified rbuilder
git clone https://github.com/ethgas-developer/preconf-builder
cd preconf-builder

# Build the project
cargo build --release

# Configure the builder
cp config.example.toml config.toml
# Edit config.toml with your settings

Configuration​

log_json = false
log_level = "info,rbuilder=debug"
#log_file_path = "<project path>/preconf-builder/logs/rbuilder.log"
redacted_telemetry_server_port = 6061
redacted_telemetry_server_ip = "0.0.0.0"
full_telemetry_server_port = 6060
full_telemetry_server_ip = "0.0.0.0"

chain = ""
reth_datadir = ""

exchange_secret_key = "env:EXCHANGE_SECRET_KEY"
coinbase_secret_key = "env:COINBASE_SECRET_KEY"
relay_secret_key = "env:RELAY_SECRET_KEY"
optimistic_relay_secret_key = "env:OPTIMISTIC_RELAY_SECRET_KEY"


# cl_node_url can be a single value, array of values, or passed by an environment variables with values separated with a comma
# cl_node_url = "http://localhost:3500"
cl_node_url = ["env:CL_NODE_URL"]
jsonrpc_server_port = 8645
jsonrpc_server_ip = "0.0.0.0"
el_node_ipc_path = "/tmp/reth.ipc"
extra_data = "ETHGas www.ethgas.com"

#blocklist_file_path = "./blocklist.json"

ignore_cancellable_orders = false

# watchdog_timeout_sec = 600
# simulation_threads = 1

# genesis_fork_version = "0x00112233"

sbundle_mergeabe_signers = []
live_builders = ["preconf-ordering"]

enabled_relays = ["custom"]


# EthGas API domain
preconf_api_url = "https://"
# EthGas WebSocket domain
preconf_ws_url = "wss://"
fallback_fee_recipient = ""

[[relays]]
name = "custom"
url = ""
priority = 0
use_ssz_for_submit = false
use_gzip_for_submit = false

[[builders]]
name = "preconf-ordering"
algo = "ordering-builder"
discard_txs = false
coinbase_payment = true
sorting = "preconf"
failed_order_retries = 1
drop_failed_orders = true
build_duration_deadline_ms = 1500

#[[builders]]
#name = "mgp-ordering"
#algo = "ordering-builder"
#discard_txs = true
#sorting = "mev-gas-price"
#failed_order_retries = 1
#drop_failed_orders = true
#
#[[builders]]
#name = "mp-ordering"
#algo = "ordering-builder"
#discard_txs = true
#sorting = "max-profit"
#failed_order_retries = 1
#drop_failed_orders = true
#coinbase_payment = false

Compliance Requirements​

Block Validation​

All built blocks must pass validation checks:

  • Preconf inclusion: All preconf transactions with canRevert equal to false must be included
  • Bundle positioning: Top and bottom bundles must be in correct positions
  • Empty Space Requirement: The minimum gas unit of a block needs to be left as empty
  • Gas limit: Block must not exceed gas limit
  • Commitment compliance: Block must satisfy all trader commitments

Next Steps​