This project implements the Flashbots block builder, based on go-ethereum (geth).
See also: https://docs.flashbots.net/flashbots-mev-boost/block-builders
Run on your favorite network, including Mainnet, Goerli, Sepolia and local devnet. Instructions for running a pos local devnet can be found here.
You will need to run a modified beacon node that sends a custom rpc call to trigger block building. You can use the modified prysm fork for this.
Test with mev-boost and mev-boost test cli.
Building geth requires both a Go (version 1.19 or later) and a C compiler. You can install
them using your favourite package manager. Once the dependencies are installed, run
- Builder polls relay for the proposer registrations for the next epoch when block building is triggered
- If both local relay and remote relay are enabled, local relay will overwrite remote relay data. This is only meant for the testnets!
- Does not accept external blocks
- Does not have payload cache, only the latest block is available
Configure geth for your network, it will become the block builder.
Builder-related options:
$ geth --help
BUILDER
--builder (default: false)
Enable the builder
--builder.algotype value (default: "mev-geth")
Block building algorithm to use [=mev-geth] (mev-geth, greedy, greedy-buckets)
--builder.beacon_endpoints value (default: "http://127.0.0.1:5052")
Comma separated list of beacon endpoints to connect to for beacon chain data
[$BUILDER_BEACON_ENDPOINTS]
--builder.bellatrix_fork_version value (default: "0x02000000")
Bellatrix fork version. [$BUILDER_BELLATRIX_FORK_VERSION]
--builder.blacklist value
Path to file containing blacklisted addresses, json-encoded list of strings.
Builder will ignore transactions that touch mentioned addresses.
--builder.block_resubmit_interval value (default: "500ms")
Determines the interval at which builder will resubmit block submissions
[$FLASHBOTS_BUILDER_RATE_LIMIT_RESUBMIT_INTERVAL]
--builder.cancellations (default: false)
Enable cancellations for the builder
--builder.discard_revertible_tx_on_error (default: false)
When enabled, if a transaction submitted as part of a bundle in a send bundle
request has error on commit, and its hash is specified as one that can revert in
the request body, the builder will discard the hash of the failed transaction
from the submitted bundle.For additional details on the structure of the request
body, see
https://docs.flashbots.net/flashbots-mev-share/searchers/understanding-bundles#bundle-definition
[$FLASHBOTS_BUILDER_DISCARD_REVERTIBLE_TX_ON_ERROR]
--builder.dry-run (default: false)
Builder only validates blocks without submission to the relay
--builder.genesis_fork_version value (default: "0x00000000")
Gensis fork version. [$BUILDER_GENESIS_FORK_VERSION]
--builder.genesis_validators_root value (default: "0x0000000000000000000000000000000000000000000000000000000000000000")
Genesis validators root of the network. [$BUILDER_GENESIS_VALIDATORS_ROOT]
--builder.ignore_late_payload_attributes (default: false)
Builder will ignore all but the first payload attributes. Use if your CL sends
non-canonical head updates.
--builder.listen_addr value (default: ":28545")
Listening address for builder endpoint [$BUILDER_LISTEN_ADDR]
--builder.local_relay (default: false)
Enable the local relay
--builder.no_bundle_fetcher (default: false)
Disable the bundle fetcher
--builder.price_cutoff_percent value (default: 50)
flashbots - The minimum effective gas price threshold used for bucketing
transactions by price. For example if the top transaction in a list has an
effective gas price of 1000 wei and price_cutoff_percent is 10 (i.e. 10%), then
the minimum effective gas price included in the same bucket as the top
transaction is (1000 * 10%) = 100 wei.
NOTE: This flag is only used when
builder.algotype=greedy-buckets [$FLASHBOTS_BUILDER_PRICE_CUTOFF_PERCENT]
--builder.rate_limit_duration value (default: "500ms")
Determines rate limit of events processed by builder. For example, a value of
"500ms" denotes that the builder processes events every 500ms. A duration string
is a possibly signed sequence of decimal numbers, each with optional fraction
and a unit suffix, such as "300ms", "-1.5h" or "2h45m"
[$FLASHBOTS_BUILDER_RATE_LIMIT_DURATION]
--builder.rate_limit_max_burst value (default: 10)
Determines the maximum number of burst events the builder can accommodate at any
given point in time. [$FLASHBOTS_BUILDER_RATE_LIMIT_MAX_BURST]
--builder.relay_secret_key value (default: "0x2fc12ae741f29701f8e30f5de6350766c020cb80768a0ff01e6838ffd2431e11")
Builder local relay API key used for signing headers [$BUILDER_RELAY_SECRET_KEY]
--builder.remote_relay_endpoint value
Relay endpoint to connect to for validator registration data, if not provided
will expose validator registration locally [$BUILDER_REMOTE_RELAY_ENDPOINT]
--builder.secondary_remote_relay_endpoints value
Comma separated relay endpoints to connect to for validator registration data
missing from the primary remote relay, and to push blocks for registrations
missing from or matching the primary [$BUILDER_SECONDARY_REMOTE_RELAY_ENDPOINTS]
--builder.seconds_in_slot value (default: 12)
Set the number of seconds in a slot in the local relay
--builder.secret_key value (default: "0x2fc12ae741f29701f8e30f5de6350766c020cb80768a0ff01e6838ffd2431e11")
Builder key used for signing blocks [$BUILDER_SECRET_KEY]
--builder.slots_in_epoch value (default: 32)
Set the number of slots in an epoch in the local relay
--builder.submission_offset value (default: 3s)
Determines the offset from the end of slot time that the builder will submit
blocks. For example, if a slot is 12 seconds long, and the offset is 2 seconds,
the builder will submit blocks at 10 seconds into the slot.
[$FLASHBOTS_BUILDER_SUBMISSION_OFFSET]
--builder.validation_blacklist value
Path to file containing blacklisted addresses, json-encoded list of strings
--builder.validation_use_balance_diff (default: false)
Block validation API will use fee recipient balance difference for profit
calculation.
--builder.validator_checks (default: false)
Enable the validator checks
MINER
--miner.algotype value (default: "mev-geth")
[NOTE: Deprecated, please use builder.algotype instead] Block building algorithm
to use [=mev-geth] (mev-geth, greedy, greedy-buckets)
--miner.blocklist value
[NOTE: Deprecated, please use builder.blacklist] flashbots - Path to JSON file with
list of blocked addresses. Miner will ignore txs that touch mentioned addresses.
--miner.extradata value
Block extra data set by the miner (default = client version)
--miner.price_cutoff_percent value (default: 50)
flashbots - The minimum effective gas price threshold used for bucketing
transactions by price. For example if the top transaction in a list has an
effective gas price of 1000 wei and price_cutoff_percent is 10 (i.e. 10%), then
the minimum effective gas price included in the same bucket as the top
transaction is (1000 * 10%) = 100 wei.
NOTE: This flag is only used when
miner.algotype=greedy-buckets
METRICS
--metrics.builder value (default: false)
Enable builder metrics collection and reporting
Environment variables:
BUILDER_TX_SIGNING_KEY - private key of the builder used to sign payment transaction, must be the same as the coinbase address
FLASHBOTS_BUILDER_RATE_LIMIT_DURATION - determines rate limit of events processed by builder; a duration string is a
possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m".
FLASHBOTS_BUILDER_RATE_LIMIT_MAX_BURST - determines the maximum number of events the builder can accommodate at any point in time
FLASHBOTS_BUILDER_RATE_LIMIT_RESUBMIT_INTERVAL - determines the interval at which builder will resubmit block submissions
To enable metrics on the builder you will need to enable metrics with the flags --metrics --metrics.addr 127.0.0.1 --metrics.builder which will run
a metrics server serving at 127.0.0.1:6060/debug/metrics. This will record performance metrics such as block profit and block building times.
The full list of metrics can be found in miner/metrics.go.
See the metrics docs for geth for more documentation.
If you want to reject transactions interacting with certain addresses, save the addresses in json file with an array of strings. Deciding whether to use such a list, as well as maintaining it, is your own responsibility.
- for block building and validation, use
--builder.blacklist
--
There are two parts of the builder.
./builderresponsible for communicating with the relay./minerresponsible for producing blocks
Main logic of the builder is in the builder.go file.
Builder is driven by the consensus client SSE events that sends payload attribute events, triggering the OnPayloadAttribute call.
After requesting additional validator data from the relay builder starts building job with runBuildingJob.
Building job continuously makes a request to the miner with the correct parameters and submits produced block.
- Builder retries build block requests every second on average.
- If the job is running but a new one is submitted for a different slot we cancel previous job.
- All jobs have 12s deadline.
- If new request is submitted for the same slot as before but with different parameters, we run these jobs in parallel. It is possible to receive multiple requests from CL for the same slot but for different parent blocks if there is a possibility of a missed block.
- All submissions to the relay are rate limited at 2 req/s
- Only blocks that have more profit than the previous best submissions for the particular job are submitted.
Additional features of the builder:
- Builder can submit data about build blocks to the database. It stores block data, included bundles, and all considered bundles.
Implemented in
flashbotsextra.IDatabaseService. - It's possible to run local relay in the same process
- It can validate blocks instead of submitting them to the relay. (see
--builder.dry-run)
Miner is responsible for block creation. Request from the builder is routed to the worker.go where
generateWork does the job of creating a block.
- Coinbase of the block is set to the address of the block proposer, fee recipient of the validator receives its eth in the last tx in the block.
- We reserve gas for the proposer payment using
proposerTxPrepareand commit proposer payment after txs are added withproposerTxCommit. We do it in a way so all fees received by the block builder are sent to the fee recipient. - Transaction insertion is done in
fillTransactionsAlgoWorker\fillTransactions. Depending on the algorithm selected. Algo worker (greedy) inserts bundles whenever they belong in the block by effective gas price but default method inserts bundles on top of the block. (see--miner.algotype) - Worker is also responsible for simulating bundles. Bundles are simulated in parallel and results are cached for the particular parent block.
algo_greedy.goimplements logic of the block building. Bundles and transactions are sorted in the order of effective gas price then we try to insert everything into to block until gas limit is reached. Failing bundles are reverted during the insertion but txs are not.- Builder can filter transactions touching a particular set of addresses.
If a bundle or transaction touches one of the addresses it is skipped. (see
--builder.blacklistflag)
There are two ways bundles are moved to builders
- via API -
sendBundle - via Database -
flashbotsextra.IDatabaseService
- Fetcher service is part of
flashbotsextra.IDatabaseServicewhich is responsible for fetching the bundles from db and pushing into mev bundles queue which will be processed by builder. - Fetcher is a background process which fetches high priority and low priority bundles from db.
- Fetch
759E
er fetches
500high priority bundles on every head change, and100low priority bundles in the interval of every2 seconds.
If you find a security vulnerability in this project or any other initiative related to proposer/builder separation in Ethereum, please let us know sending an email to security@flashbots.net.
The code in this project is free software under the LGPL License.