diff --git a/README.md b/README.md index dfec5bbb9..990e02fa9 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ - BOLT + BOLT @@ -15,45 +15,47 @@ > [!IMPORTANT] -> Bolt is an implementation of _permissionless proposer commitments through -> PBS_. In its essence, it consists in a light fork of the current MEV-Boost -> stack that allows users to request **preconfirmations** from proposers, and -> then adds a way for proposers to commit to transaction inclusion in a way that -> is easily verifiable. +> Bolt is an implementation of permissionless proposer commitments that is fully compatible with PBS. +> In its essence, it consists in a fork of the MEV-Boost stack that allows users to request commitments +> like preconfirmations from proposers, and then adds a way for proposers to commit to transaction +> inclusion in a way that is verifiable on-chain. -* [How it works](#how-it-works) -* [Scope of this repository](#scope-of-this-repository) -* [Devnet and demo app](#devnet-and-demo-app) - * [Requirements and setup](#requirements-and-setup) - * [Running the devnet and demo](#running-the-devnet-and-demo) - * [Stopping the devnet and demo](#stopping-the-devnet-and-demo) -* [Telemetry & Metrics](#telemetry-&-metrics) -* [License](#license) +- [How it works](#how-it-works) +- [Repository structure](#repository-structure) +- [Kurtosis Devnet](#kurtosis-devnet) + - [Requirements and setup](#requirements-and-setup) + - [Running the devnet](#running-the-devnet-and-demo) + - [Stopping the devnet](#stopping-the-devnet-and-demo) +- [Telemetry & Metrics](#telemetry-&-metrics) +- [License](#license) ## How it works -The flow of Bolt can be summarized in the following steps: +The technical flow of Bolt can be summarized in the following steps: 1. Users submit transactions to an RPC endpoint that will forward them to the - proposer opted-in to Bolt in the consensus lookahead window. -2. The proposer can accept this request and turn it into a "constraint" on the block - that it is going to propose. This constraint acts as guarantee of inclusion of + proposer opted-in to Bolt in the beacon chain lookahead window. +2. The proposer can accept this request and turn it into a _commitment_ relative to the + block that it is going to propose. This commitment acts as guarantee of inclusion of the transaction in the block, also known as a _preconfirmation_. -3. Builders subscribe to proposer constraints in real time through a new relay - streaming endpoint to keep informed about the preconfirmations. -4. Builders build valid blocks that adhere to all constraints, and append inclusion - proofs together with the bids to the relay. -5. When it's time to propose a block, the proposer will fetch the best valid bid +3. Near the time of block proposal, the proposer will share the list of committed transactions + with the relays that are connected to block builders. This list is called a _constraint_. +4. Builders subscribe to proposer constraints in real time through a new relay + streaming endpoint to keep informed about the outstanding preconfirmations. +5. Builders build valid blocks that adhere to all _constraints_, and append inclusion + proofs together with the bids to the relay for trustless verification. +6. When it's time to propose a block, the proposer will fetch the best valid bid from the relay, and verify its inclusion proofs locally before signing the header. -6. If the constraints are respected, the proposer can propose the payload as usual +7. If the constraints are respected, the proposer can propose the payload as usual by sending the signed header back to the relay. If not, the proposer can self-build a payload and propose it directly instead. -The following diagram illustrates the flow: +
+Here is a diagram illustrating the flow explained above: ```mermaid sequenceDiagram @@ -85,20 +87,21 @@ sequenceDiagram end ``` -## Scope of this repository +
-This repository contains all the necessary components to illustrate the flow -described above. It can be thought of a reference implementation. +## Repository structure + +This monorepo contains all the necessary components of the Bolt protocol stack. In particular, the core components are: - [**Bolt Sidecar**](./bolt-sidecar/): New validator software (akin to [mev-boost][fb-mev-boost]) that handles the receipt of preconfirmation requests from users, translates them - into constraints, and forwards them to relays. Additionally, it handles the + into _constraints_, and forwards them to relays. Additionally, it handles the fallback logic to produce a block locally when relays send invalid inclusion proofs. - [**Builder**](./builder/): A fork of the [Flashbots builder][fb-builder] that subscribes to new constraints from relays, builds blocks that respect them, and - includes the necessary proofs of inclusion in the bid submitted to relays. -- [**Relay**](./mev-boost-relay/): A fork of the [Flashbots relay][fb-relay] that + includes the necessary proofs of inclusion in the bids submitted to relays. +- [**MEV-Boost Relay**](./mev-boost-relay/): A fork of the [Flashbots relay][fb-relay] that receives constraints from proposers, and forwards them to builders. It also receives bids with proofs of inclusion from builders, verifies them and forwards the best bid to proposers for block proposal. @@ -106,13 +109,25 @@ In particular, the core components are: that includes new API endpoints to proxy requests from the Bolt Sidecar to the connected relays. - [**Bolt Contracts**](./bolt-contracts/): A set of smart contracts for peripheral functionality such as proposer registration and permissionless dispute resolution for attributable faults. +- [**Bolt Boost**](./bolt-boost/): A [Commit-Boost][commit-boost] module that implements the + Constraints-API and is compatible with the Bolt Sidecar. +- [**Bolt client**](./bolt-client/): A CLI tool to send preconfirmations on enabled test networks. +- [**Bolt Kurtosis client**](./bolt-kurtosis-client/): A CLI tool to send preconfirmations on our Kurtosis devnet. +- [**Bolt delegations CLI**](./bolt-delegations-cli/): A CLI tool to generate signed delegation and revocation messages for ETH validators. +- [**Testnets**](./testnets/): A set of guides and scripts to deploy the Bolt contracts on testnets. + +Additionally, this repository contains the necessary scripts to spin up a [Kurtosis][kurtosis] +devnet with all the components running. + +> [!NOTE] +> Bolt also works with external components that aren't part of this repository, +> such as [Helix][helix] by Gattaca, which will replace the MEV-Boost relay soon. +> +> You can find the forked version of Helix [here](https://github.com/chainbound/helix). -Additionally, this repository contains the necessary scripts to spin up a [Kurtosis][kurtosis] devnet -with all the components running, and a simple [web demo](./bolt-web-demo/) to showcase the preconfirmation flow. - -## Devnet and demo app +## Kurtosis Devnet -We are using a full [Kurtosis][kurtosis] devnet stack, with custom Docker images +We are using a forked [Kurtosis][kurtosis] devnet stack, with custom Docker images for the core components outlined above. The exact version of the Ethereum-package used in our devnet can be seen [here](https://github.com/chainbound/ethereum-package). @@ -127,8 +142,9 @@ Make sure you have the following requirements on your machine: - [Just](https://github.com/casey/just) installed - [Kurtosis CLI](https://docs.kurtosis.com/install/) installed - [Foundry](https://book.getfoundry.sh/getting-started/installation) installed +- [Rust & Cargo](https://www.rust-lang.org/tools/install) installed -> [!WARNING] +> [!NOTE] > The Kurtosis CLI version tested is `0.88.16`. Some issues may arise if you are > using a different version. > @@ -140,9 +156,9 @@ Then, clone this repository and navigate to the root directory of the project: git clone git@github.com:chainbound/bolt.git && cd bolt ``` -### Running the devnet and demo +### Running the devnet -Running the devnet and demo is straightforward once you have the requirements +Running the devnet is straightforward once you have the requirements installed. Just run the following commands in your terminal: ```shell @@ -151,20 +167,14 @@ just build-images # spin up the kurtosis devnet on your machine just up - -# run the web demo servers. -just demo ``` -The web demo will be available on your browser at [`http://localhost:3000`](http://localhost:3000). - **Commit-Boost support** -The devnet by default will run using a fork of MEV-Boost which -supports the [Constraints-API](https://docs.boltprotocol.xyz/api/builder). -Bolt also supports [Commit-Boost](https://commit-boost.github.io/commit-boost-client/) -by providing a compatible MEV-Boost module called _Bolt-Boost_ -that implements the Constraints-API. To use it in the devnet +The devnet by default will run using a fork of MEV-Boost which supports +the [Constraints-API](https://docs.boltprotocol.xyz/api/builder). Bolt also +supports [Commit-Boost][commit-boost] by providing a compatible MEV-Boost module +called _Bolt-Boost_ that implements the Constraints-API. To use it in the devnet add the appropriate `bolt_boost_image` in the `kurtosis_config.yaml` file: ```yaml @@ -177,10 +187,7 @@ mev_params: # ... the rest of the `mev_params` ``` -### Stopping the devnet and demo - -The demo app will remain open until you press `Ctrl+C` in the terminal where -you ran the `just demo` command. +### Stopping the devnet To stop the devnet, run the following command: @@ -192,28 +199,23 @@ just down just clean ``` -> [!WARNING] +> [!NOTE] > Remember to shut down the devnet environment when you are done with it, as it > consumes significant resources (CPU & RAM) on your machine. +## License + +MIT. Forked repositories have their own licenses. + [twitter]: https://twitter.com/chainbound_ [discord]: https://discord.gg/pK8GgjxYQS -[docs]: https://chainbound.github.io/bolt-docs/ +[docs]: https://docs.boltprotocol.xyz/ [new-issue]: https://github.com/chainbound/bolt/issues/new [fb-mev-boost]: https://github.com/flashbots/mev-boost [fb-relay]: https://github.com/flashbots/mev-boost-relay [fb-builder]: https://github.com/flashbots/builder [kurtosis]: https://www.kurtosis.com/ - -## Telemetry & Metrics - -The Bolt sidecar offers an optional set of metrics that can be scraped by a Prometheus server, and shown in Grafana dashboards. -They show various informations such as the number of constraints received, the number of blocks proposed, etc. - -These metrics are enabled by default but can be disabled by setting running the sidecar with the `--metrics` flag set to `false`. - -## License - -MIT. Forked repositories have their own licenses. +[helix]: https://github.com/gattaca-com/helix +[commit-boost]: https://commit-boost.github.io/commit-boost-client/ diff --git a/bolt-boost/README.md b/bolt-boost/README.md index b88e1336e..13f1da4f5 100644 --- a/bolt-boost/README.md +++ b/bolt-boost/README.md @@ -1,4 +1,10 @@ # Bolt-Boost -Bolt-Boost is a [commit-boost](https://commit-boost.github.io/commit-boost-client) module that extends the default PBS module with the [constraints-API](https://chainbound.github.io/bolt-docs/api/builder). -It inherits the PBS module configuration for the modified `get_header` call. +Bolt-Boost is a [Commit-Boost][commit-boost] module that extends the default PBS module +with the [constraints-API][constraints-api]. It inherits the PBS module configuration +for the modified `get_header` call. + +[commit-boost]: https://commit-boost.github.io/commit-boost-client +[constraints-api]: https://docs.boltprotocol.xyz/api/builder + + diff --git a/bolt-client/README.md b/bolt-client/README.md index 2566a78b3..76d7e7b54 100644 --- a/bolt-client/README.md +++ b/bolt-client/README.md @@ -1,6 +1,6 @@ # Bolt CLI client -This is a simple CLI tool to interact with Bolt. +This is a CLI tool to interact with Bolt by sending preconfirmation requests. ## Requirements diff --git a/bolt-client/src/registry.rs b/bolt-client/src/registry.rs index 429389de6..79dd9fbd9 100644 --- a/bolt-client/src/registry.rs +++ b/bolt-client/src/registry.rs @@ -72,7 +72,7 @@ impl BoltRegistry { } } - /// Gets the next pre-confirmation slot and proposer RPC URL from the registry contract + /// Gets the next preconfirmation slot and proposer RPC URL from the registry contract /// /// Returns Ok(None) if no registered validators are found in the lookahead pub async fn next_preconfer_from_registry( @@ -89,7 +89,7 @@ impl BoltRegistry { next_preconfer_slot = duty.slot; proposer_rpc = token_raw.metadata.rpc; info!( - "pre-confirmation will be sent for slot {} to validator with index {} at url {}", + "preconfirmation will be sent for slot {} to validator with index {} at url {}", duty.slot, duty.validator_index, proposer_rpc, diff --git a/bolt-delegations-cli/delegations.json b/bolt-delegations-cli/delegations.json new file mode 100644 index 000000000..0637a088a --- /dev/null +++ b/bolt-delegations-cli/delegations.json @@ -0,0 +1 @@ +[] \ No newline at end of file diff --git a/bolt-delegations-cli/private_key.txt b/bolt-delegations-cli/private_key.txt new file mode 100644 index 000000000..c2bd154d9 --- /dev/null +++ b/bolt-delegations-cli/private_key.txt @@ -0,0 +1 @@ +1a28765fd3e2a37f8477b8ec79434e682c538eb3d79ecbd6690d4d1712a8ac58 \ No newline at end of file diff --git a/bolt-kurtosis-client/README.md b/bolt-kurtosis-client/README.md index 98aa01d91..743a65f9e 100644 --- a/bolt-kurtosis-client/README.md +++ b/bolt-kurtosis-client/README.md @@ -1,6 +1,6 @@ -## A pre-confirmation spammer for the Helder testnet +## A preconfirmation sender for the Kurtosis devnet -To run the spammer, make sure to set the following environment variables in a `.env` file: +To run the tool, make sure to set the following environment variables in a `.env` file: ```text EL_PROVIDER_URL=https://rpc.helder-devnets.xyz @@ -12,6 +12,10 @@ REGISTRY_ABI_PATH=./registry_abi.json This template can be found in the `env.example` file. -Then, just run the spammer with `cargo run`. It will fetch all the validators of the current epoch, -and try to send a pre-confirmation to the first one registered on the Bolt registry. -If no validators are found, the program will gracefully exit. Please try again in the next epoch! +Then, just run the tool with `cargo run`. + +It will fetch all the validators of the current epoch, and try to send a +preconfirmation to the first one registered on the Bolt registry. + +If no validators are found, the program will gracefully exit. +Please try again in the next epoch! diff --git a/bolt-sidecar/README.md b/bolt-sidecar/README.md index 206dcdb73..2b11d6095 100644 --- a/bolt-sidecar/README.md +++ b/bolt-sidecar/README.md @@ -38,4 +38,153 @@ in case a fallback block is required. ## Running -- We require Anvil to be installed in the $PATH for running tests +- We require Anvil to be installed in the $PATH for running tests + +```text +Command-line options for the Bolt sidecar + +Usage: bolt-sidecar [OPTIONS] + <--private-key |--commit-boost-address |--keystore-password > + +Options: + --port + Port to listen on for incoming JSON-RPC requests + + [env: BOLT_SIDECAR_PORT=] + [default: 8000] + + --beacon-api-url + URL for the beacon client + + [env: BOLT_SIDECAR_BEACON_API_URL=] + [default: http://localhost:5052] + + --constraints-url + URL for the Constraint sidecar client to use + + [env: BOLT_SIDECAR_CONSTRAINTS_URL=] + [default: http://localhost:3030] + + --execution-api-url + Execution client API URL + + [env: BOLT_SIDECAR_EXECUTION_API_URL=] + [default: http://localhost:8545] + + --engine-api-url + Execution client Engine API URL + + [env: BOLT_SIDECAR_ENGINE_API_URL=] + [default: http://localhost:8551] + + --constraints-proxy-port + Constraint proxy server port to use + + [env: BOLT_SIDECAR_CONSTRAINTS_PROXY_PORT=] + [default: 18551] + + --validator-indexes + Validator indexes of connected validators that the sidecar should accept commitments on behalf of. + Accepted values: + - a comma-separated list of indexes (e.g. "1,2,3,4") + - a contiguous range of indexes (e.g. "1..4") + - a mix of the above (e.g. "1,2..4,6..8") + + [env: BOLT_SIDECAR_VALIDATOR_INDEXES=] + [default: ] + + --jwt-hex + The JWT secret token to authenticate calls to the engine API. + + It can either be a hex-encoded string or a file path to a file containing the hex-encoded secret. + + [env: BOLT_SIDECAR_JWT_HEX=] + [default: 0xcc68d8051627b89005165f38a351242848e4c53be38d398069967ba62970edf0] + + --fee-recipient + The fee recipient address for fallback blocks + + [env: BOLT_SIDECAR_FEE_RECIPIENT=] + [default: 0x0000000000000000000000000000000000000000] + + --builder-private-key + Secret BLS key to sign fallback payloads with (If not provided, a random key will be used) + + [env: BOLT_SIDECAR_BUILDER_PRIVATE_KEY=] + [default: 0x240872ca0812e33503482a886e05dfe30ae9cf757bf5c040e70eac685e419c6e] + + --max-commitments-per-slot + Max number of commitments to accept per block + + [env: BOLT_SIDECAR_MAX_COMMITMENTS=] + [default: 128] + + --max-committed-gas-per-slot + Max committed gas per slot + + [env: BOLT_SIDECAR_MAX_COMMITTED_GAS=] + [default: 10000000] + + --min-priority-fee + Min priority fee to accept for a commitment + + [env: BOLT_SIDECAR_MIN_PRIORITY_FEE=] + [default: 1000000000] + + --chain + Chain on which the sidecar is running + + [env: BOLT_SIDECAR_CHAIN=] + [default: mainnet] + [possible values: mainnet, holesky, helder, kurtosis] + + --commitment-deadline + The deadline in the slot at which the sidecar will stop accepting new commitments for + the next block (parsed as milliseconds) + + [env: BOLT_SIDECAR_COMMITMENT_DEADLINE=] + [default: 8000] + + --slot-time + The slot time duration in seconds. If provided, it overrides the default for the selected [Chain] + + [env: BOLT_SIDECAR_SLOT_TIME=] + [default: 12] + + --private-key + Private key to use for signing preconfirmation requests + + [env: BOLT_SIDECAR_PRIVATE_KEY=] + + --commit-boost-address + Socket address for the commit-boost sidecar + + [env: BOLT_SIDECAR_CB_SIGNER_URL=] + + --commit-boost-jwt-hex + JWT in hexadecimal format for authenticating with the commit-boost service + + [env: BOLT_SIDECAR_CB_JWT_HEX=] + + --keystore-password + The password for the ERC-2335 keystore. Reference: https://eips.ethereum.org/EIPS/eip-2335 + + [env: BOLT_SIDECAR_KEYSTORE_PASSWORD=] + + --keystore-path + Path to the keystores folder. If not provided, the default path is used + + [env: BOLT_SIDECAR_KEYSTORE_PATH=] + + -m, --metrics-port + The port on which to expose Prometheus metrics + + [env: METRICS_PORT=] + [default: 3300] + + -d, --disable-metrics + [env: DISABLE_METRICS=] + + -h, --help + Print help (see a summary with '-h') +``` diff --git a/builder/README.flashbots.md b/builder/README.flashbots.md new file mode 100644 index 000000000..1c8148421 --- /dev/null +++ b/builder/README.flashbots.md @@ -0,0 +1,283 @@ +[geth readme](README.original.md) + +# Flashbots Block Builder + +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](https://github.com/avalonche/eth-pos-devnet). + +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](https://github.com/flashbots/prysm) for this. + +Test with [mev-boost](https://github.com/flashbots/mev-boost) and [mev-boost test cli](https://github.com/flashbots/mev-boost/tree/main/cmd/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 + +## How it works + +* 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! + +## Limitations + +* Does not accept external blocks +* Does not have payload cache, only the latest block is available + +# Usage + +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 +``` + +## Metrics + +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](https://geth.ethereum.org/docs/monitoring/metrics) for geth for more documentation. + +## Blacklisting addresses + +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` + +-- + +## Details of the implementation + +There are two parts of the builder. + +1. `./builder` responsible for communicating with the relay +2. `./miner` responsible for producing blocks + +### `builder` module + +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` module + +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 `proposerTxPrepare` and commit proposer payment after txs are added with + `proposerTxCommit`. 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.go` implements 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.blacklist` flag) + +## Bundle Movement + +There are two ways bundles are moved to builders + +1. via API -`sendBundle` +2. via Database - `flashbotsextra.IDatabaseService` + +### `fetcher` service +* Fetcher service is part of `flashbotsextra.IDatabaseService` which 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. +* Fetcher fetches `500` high priority bundles on every head change, and `100` low priority bundles in the interval of every `2 seconds`. + +## Block builder diagram + +![block builder diagram](docs/builder/builder-diagram.png "Block builder diagram") + +--- + +# Security + +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. + +--- + +# License + +The code in this project is free software under the [LGPL License](COPYING.LESSER). + diff --git a/builder/README.md b/builder/README.md index 1c8148421..a335eba08 100644 --- a/builder/README.md +++ b/builder/README.md @@ -1,283 +1,15 @@ -[geth readme](README.original.md) +[flashbots builder readme](README.flashbots.md) -# Flashbots Block Builder +# Bolt builder -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](https://github.com/avalonche/eth-pos-devnet). - -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](https://github.com/flashbots/prysm) for this. - -Test with [mev-boost](https://github.com/flashbots/mev-boost) and [mev-boost test cli](https://github.com/flashbots/mev-boost/tree/main/cmd/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 +Bolt builder is a fork of the Flsahbots Builder that implements the functionality of the Constraints API. ## How it works -* 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! - -## Limitations - -* Does not accept external blocks -* Does not have payload cache, only the latest block is available - -# Usage - -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 -``` - -## Metrics - -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](https://geth.ethereum.org/docs/monitoring/metrics) for geth for more documentation. - -## Blacklisting addresses - -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` - --- - -## Details of the implementation - -There are two parts of the builder. - -1. `./builder` responsible for communicating with the relay -2. `./miner` responsible for producing blocks - -### `builder` module - -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` module - -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 `proposerTxPrepare` and commit proposer payment after txs are added with - `proposerTxCommit`. 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.go` implements 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.blacklist` flag) - -## Bundle Movement - -There are two ways bundles are moved to builders - -1. via API -`sendBundle` -2. via Database - `flashbotsextra.IDatabaseService` - -### `fetcher` service -* Fetcher service is part of `flashbotsextra.IDatabaseService` which 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. -* Fetcher fetches `500` high priority bundles on every head change, and `100` low priority bundles in the interval of every `2 seconds`. - -## Block builder diagram - -![block builder diagram](docs/builder/builder-diagram.png "Block builder diagram") - ---- - -# Security - -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. - ---- - -# License - -The code in this project is free software under the [LGPL License](COPYING.LESSER). +The builder has the standard functionality of the Flashbots builder, but with the +added functionality of the Constraints API which can be summarized as follows: +1. The builder subscribes to the relays for streams of constraints sent by proposers. +2. After receiving constraints and validating their authenticity, the builder builds a block that + respects all constraints and includes the necessary proofs of inclusion in its bid. +3. The builder sends the signed bid as usual to the relay. diff --git a/mev-boost-relay/README.flashbots.md b/mev-boost-relay/README.flashbots.md new file mode 100644 index 000000000..edb49d4c2 --- /dev/null +++ b/mev-boost-relay/README.flashbots.md @@ -0,0 +1,401 @@ +# MEV-Boost Relay + +[![Goreport status](https://goreportcard.com/badge/github.com/flashbots/mev-boost-relay)](https://goreportcard.com/report/github.com/flashbots/mev-boost-relay) +[![Test status](https://github.com/flashbots/mev-boost-relay/workflows/Checks/badge.svg)](https://github.com/flashbots/mev-boost-relay/actions?query=workflow%3A%22Checks%22) +[![Docker hub](https://badgen.net/docker/size/flashbots/mev-boost-relay?icon=docker&label=image)](https://hub.docker.com/r/flashbots/mev-boost-relay/tags) + +MEV-Boost Relay for Ethereum proposer/builder separation (PBS). + +Currently live at: + +* [boost-relay.flashbots.net](https://boost-relay.flashbots.net) (also on [Goerli](https://boost-relay-goerli.flashbots.net), [Sepolia](https://boost-relay-sepolia.flashbots.net) and [Holesky](https://boost-relay-holesky.flashbots.net)) +* [relay.ultrasound.money](https://relay.ultrasound.money), [agnostic-relay.net](https://agnostic-relay.net), bloXroute relays ([light fork](https://github.com/bloXroute-Labs/mev-relay)) +* [mainnet.aestus.live](https://mainnet.aestus.live), [relay.edennetwork.io/info](https://relay.edennetwork.io/info), [mainnet-relay.securerpc.com](https://mainnet-relay.securerpc.com) + +Alternatives (not audited or endorsed): [blocknative/dreamboat](https://github.com/blocknative/dreamboat), [manifold/mev-freelay](https://github.com/manifoldfinance/mev-freelay) + +### See also + +* [Docker images](https://hub.docker.com/r/flashbots/mev-boost-relay) +* [mev-boost](https://github.com/flashbots/mev-boost) +* [Relay API specs](https://flashbots.github.io/relay-specs) +* [Guide for running mev-boost-relay at scale](https://flashbots.notion.site/Running-mev-boost-relay-at-scale-draft-4040ccd5186c425d9a860cbb29bbfe09) +* [Running relay and builders in custom devnets](https://gist.github.com/metachris/66df812f2920e6b0047afb9fdaf7df91#using-unnamed-devnets) +* [More docs](/docs/docs/) + +### Components + +The relay consists of three main components, which are designed to run and scale independently, and to be as simple as possible: + +1. [API](https://github.com/flashbots/mev-boost-relay/tree/main/services/api): Services that provide APIs for (a) proposers, (b) block builders, (c) data. +1. [Website](https://github.com/flashbots/mev-boost-relay/tree/main/services/website): Serving the [website requests](https://boost-relay.flashbots.net/) (information is pulled from Redis and database). +1. [Housekeeper](https://github.com/flashbots/mev-boost-relay/tree/main/services/housekeeper): Updates known validators, proposer duties, and more in the background. Only a single instance of this should run. + +### Dependencies + +1. Redis +1. PostgreSQL +1. one or more beacon nodes +1. block submission validation nodes +1. [optional] Memcached + +### Beacon nodes / CL clients + +- The relay services need access to one or more beacon node for event subscriptions (in particular the `head` and `payload_attributes` topics). +- You can specify multiple beacon nodes by providing a comma separated list of beacon node URIs. +- The beacon nodes need to support the [`payload_attributes` SSE event](https://github.com/ethereum/beacon-APIs/pull/305). +- Support the [v2 CL publish block endpoint](https://github.com/ethereum/beacon-APIs/pull/317) in the current main branch, since August 2. This is still + experimental and may or may not fully work. It requires at least one of these CL clients + - **Lighthouse+** [v4.3.0](https://github.com/sigp/lighthouse/releases) or later. Here's a [quick guide](https://gist.github.com/metachris/bcae9ae42e2fc834804241f991351c4e) for setting up Lighthouse. + - **Prysm** [v4.0.6](https://github.com/prysmaticlabs/prysm/releases) or later. +- The latest release (v0.26) still uses the old V1 broadcast endpoint using CL clients with custom validate-before-broadcast patches (see [README of the release for more details](https://github.com/flashbots/mev-boost-relay/tree/v0.26#beacon-nodes--cl-clients)) + +**Relays are strongly advised to run multiple beacon nodes!** +* The reason is that on getPayload, the block has to be validated and broadcast by a local beacon node before it is returned to the proposer. +* If the local beacon nodes don't accept it (i.e. because it's down), the block won't be returned to the proposer, which leads to the proposer missing the slot. +* The relay makes the validate+broadcast request to all beacon nodes concurrently, and returns as soon as the first request is successful. + +### Security + +A security assessment for the relay was conducted on 2022-08-22 by [lotusbumi](https://github.com/lotusbumi). Additional information can be found in the [Security](#security) section of this repository. + +If you find a security vulnerability on this project or any other initiative related to Flashbots, please let us know sending an email to security@flashbots.net. + +--- + +# Background + +MEV is a centralizing force on Ethereum. Unattended, the competition for MEV opportunities leads to consensus security instability and permissioned communication infrastructure between traders and block producers. This erodes neutrality, transparency, decentralization, and permissionlessness. + +Flashbots is a research and development organization working on mitigating the negative externalities of MEV. Flashbots started as a builder specializing in MEV extraction in proof-of-work Ethereum to democratize access to MEV and make the most profitable blocks available to all miners. >90% of miners are outsourcing some of their block construction to Flashbots today. + +The mev-boost relay is a trusted mediator between block producers and block builders. It enables all Ethereum proof-of-stake validators to offer their blockspace to not just Flashbots but other builders as well. This opens up the market to more builders and creates competition between them, leading to more revenue and choice for validators, and better censorship-resistance for Ethereum. + +In the future, [proposer/builder separation](https://ethresear.ch/t/two-slot-proposer-builder-separation/10980) will be enshrined in the Ethereum protocol itself to further harden its trust model. + +Read more in [Why run mev-boost?](https://writings.flashbots.net/writings/why-run-mevboost/) and in the [Frequently Asked Questions](https://github.com/flashbots/mev-boost/wiki/Frequently-Asked-Questions). + +--- + +# Usage + +## Running Postgres, Redis and Memcached +```bash +# Start PostgreSQL & Redis individually: +docker run -d -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=postgres postgres +docker run -d -p 6379:6379 redis + +# [optional] Start Memcached +docker run -d -p 11211:11211 memcached + +# Or with docker-compose: +docker-compose up +``` + +Note: docker-compose also runs an Adminer (a web frontend for Postgres) on http://localhost:8093/?username=postgres (db: `postgres`, username: `postgres`, password: `postgres`) + +Now start the services: + +```bash +# The housekeeper sets up the validators, and does various housekeeping +go run . housekeeper --network sepolia --db postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable + +# Run APIs for sepolia (using a dummy BLS secret key) +go run . api --network sepolia --secret-key 0x607a11b45a7219cc61a3d9c5fd08c7eebd602a6a19a977f8d3771d5711a550f2 --db postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable + +# Run Website for sepolia +go run . website --network sepolia --db postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable + +# Query status +curl localhost:9062/eth/v1/builder/status + +# Send test validator registrations +curl -X POST -H'Content-Encoding: gzip' localhost:9062/eth/v1/builder/validators --data-binary @testdata/valreg2.json.gz + +# Delete previous registrations +redis-cli DEL boost-relay/sepolia:validators-registration boost-relay/sepolia:validators-registration-timestamp +``` + + +## Environment variables + +#### General + +* `ACTIVE_VALIDATOR_HOURS` - number of hours to track active proposers in redis (default: `3`) +* `API_MAX_HEADER_BYTES` - http maximum header bytes (default: `60_000`) +* `API_TIMEOUT_READ_MS` - http read timeout in milliseconds (default: `1_500`) +* `API_TIMEOUT_READHEADER_MS` - http read header timeout in milliseconds (default: `600`) +* `API_TIMEOUT_WRITE_MS` - http write timeout in milliseconds (default: `10_000`) +* `API_TIMEOUT_IDLE_MS` - http idle timeout in milliseconds (default: `3_000`) +* `API_SHUTDOWN_WAIT_SEC` - how long to wait on shutdown before stopping server, to allow draining of requests (default: `30`) +* `API_SHUTDOWN_STOP_SENDING_BIDS` - whether API should stop sending bids during shutdown (nly useful in single-instance/testnet setups, default: `false`) +* `BLOCKSIM_MAX_CONCURRENT` - maximum number of concurrent block-sim requests (0 for no maximum, default: `4`) +* `BLOCKSIM_TIMEOUT_MS` - builder block submission validation request timeout (default: `3000`) +* `BROADCAST_MODE` - which broadcast mode to use for block publishing (default: `consensus_and_equivocation`) +* `DB_DONT_APPLY_SCHEMA` - disable applying DB schema on startup (useful for connecting data API to read-only replica) +* `DB_TABLE_PREFIX` - prefix to use for db tables (default uses `dev`) +* `GETPAYLOAD_RETRY_TIMEOUT_MS` - getPayload retry getting a payload if first try failed (default: `100`) +* `MEMCACHED_URIS` - optional comma separated list of memcached endpoints, typically used as secondary storage alongside Redis +* `MEMCACHED_EXPIRY_SECONDS` - item expiry timeout when using memcache (default: `45`) +* `MEMCACHED_CLIENT_TIMEOUT_MS` - client timeout in milliseconds (default: `250`) +* `MEMCACHED_MAX_IDLE_CONNS` - client max idle conns (default: `10`) +* `NUM_ACTIVE_VALIDATOR_PROCESSORS` - proposer API - number of goroutines to listen to the active validators channel +* `NUM_VALIDATOR_REG_PROCESSORS` - proposer API - number of goroutines to listen to the validator registration channel +* `NO_HEADER_USERAGENTS` - proposer API - comma separated list of user agents for which no bids should be returned +* `ENABLE_BUILDER_CANCELLATIONS` - whether to enable block builder cancellations +* `REDIS_URI` - main redis URI (default: `localhost:6379`) +* `REDIS_READONLY_URI` - optional, a secondary redis instance for heavy read operations + +#### Feature Flags + +* `DISABLE_PAYLOAD_DATABASE_STORAGE` - builder API - disable storing execution payloads in the database (i.e. when using memcached as data availability redundancy) +* `DISABLE_LOWPRIO_BUILDERS` - reject block submissions by low-prio builders +* `FORCE_GET_HEADER_204` - force 204 as getHeader response +* `ENABLE_IGNORABLE_VALIDATION_ERRORS` - enable ignorable validation errors +* `USE_V1_PUBLISH_BLOCK_ENDPOINT` - uses the v1 publish block endpoint on the beacon node +* `USE_SSZ_ENCODING_PUBLISH_BLOCK` - uses the SSZ encoding for the publish block endpoint + +#### Development Environment Variables + +* `RUN_DB_TESTS` - when set to "1" enables integration tests with Postgres using endpoint specified by environment variable `TEST_DB_DSN` +* `RUN_INTEGRATION_TESTS` - when set to "1" enables integration tests, currently used for testing Memcached using comma separated list of endpoints specified by `MEMCACHED_URIS` +* `TEST_DB_DSN` - specifies connection string using Data Source Name (DSN) for Postgres (default: postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable) + +#### Redis Tuning + +* `REDIS_CONNECTION_POOL_SIZE`, `REDIS_MIN_IDLE_CONNECTIONS`, `REDIS_READ_TIMEOUT_SEC`, `REDIS_POOL_TIMEOUT_SEC`, `REDIS_WRITE_TIMEOUT_SEC` (see also [the code here](https://github.com/flashbots/mev-boost-relay/blob/e39cd38010de26bf9a51d1a3e77fc235ea87b12f/datastore/redis.go#L35-L41)) + +#### Website + +* `LINK_BEACONCHAIN` - url for beaconcha.in (default: `https://beaconcha.in`) +* `LINK_DATA_API` - origin url for data api (https://domain:port) +* `LINK_ETHERSCAN` - url for etherscan (default: `https://etherscan.io`) +* `LISTEN_ADDR` - listen address for webserver (default: `localhost:9060`) +* `RELAY_URL` - full url for the relay (https://pubkey@host) +* `SHOW_CONFIG_DETAILS` - when set to "1", logs configuration details + +## Updating the website + +* Edit the HTML in `services/website/website.html` +* Edit template values in `testdata/website-htmldata.json` +* Generate a static version of the website with `go run scripts/website-staticgen/main.go` + +This builds a local copy of the template and saves it in `website-index.html` + +The website is using: +* [PureCSS](https://purecss.io/) +* [HeroIcons](https://heroicons.com/) + +--- + +# Technical Notes + +See [ARCHITECTURE.md](ARCHITECTURE.md) and [Running MEV-Boost-Relay at scale](https://flashbots.notion.site/Draft-Running-a-relay-4040ccd5186c425d9a860cbb29bbfe09) for more technical details! + +## Storing execution payloads and redundant data availability + +By default, the execution payloads for all block submission are stored in Redis and also in the Postgres database, +to provide redundant data availability for getPayload responses. But the database table is not pruned automatically, +because it takes a lot of resources to rebuild the indexes (and a better option is using `TRUNCATE`). + +Storing all the payloads in the database can lead to terabytes of data in this particular table. Now it's also possible +to use memcached as a second data availability layer. Using memcached is optional and disabled by default. + +To enable memcached, you just need to supply the memcached URIs either via environment variable (i.e. +`MEMCACHED_URIS=localhost:11211`) or through command line flag (`--memcached-uris`). + +You can disable storing the execution payloads in the database with this environment variable: +`DISABLE_PAYLOAD_DATABASE_STORAGE=1`. + +## Builder submission validation nodes + +You can use the [builder project](https://github.com/flashbots/builder) to validate block builder submissions: https://github.com/flashbots/builder + +Here's an example systemd config: + +
+/etc/systemd/system/geth.service + +```ini +[Unit] +Description=mev-boost +Wants=network-online.target +After=network-online.target + +[Service] +User=ubuntu +Group=ubuntu +Environment=HOME=/home/ubuntu +Type=simple +KillMode=mixed +KillSignal=SIGINT +TimeoutStopSec=90 +Restart=on-failure +RestartSec=10s +ExecStart=/home/ubuntu/builder/build/bin/geth \ + --syncmode=snap \ + --datadir /var/lib/goethereum \ + --metrics \ + --metrics.expensive \ + --http \ + --http.api="engine,eth,web3,net,debug,flashbots" \ + --http.corsdomain "*" \ + --http.addr "0.0.0.0" \ + --http.port 8545 \ + --http.vhosts '*' \ + --ws \ + --ws.api="engine,eth,web3,net,debug" \ + --ws.addr 0.0.0.0 \ + --ws.port 8546 \ + --ws.api engine,eth,net,web3 \ + --ws.origins '*' \ + --graphql \ + --graphql.corsdomain '*' \ + --graphql.vhosts '*' \ + --authrpc.addr="0.0.0.0" \ + --authrpc.jwtsecret=/var/lib/goethereum/jwtsecret \ + --authrpc.vhosts '*' \ + --cache=8192 + +[Install] +WantedBy=multi-user.target +``` +
+ +Sending blocks to the validation node: + +- The built-in [blocksim-ratelimiter](services/api/blocksim_ratelimiter.go) is a simple example queue implementation. +- By default, `BLOCKSIM_MAX_CONCURRENT` is set to 4, which allows 4 concurrent block simulations per API node +- For production use, use the [prio-load-balancer](https://github.com/flashbots/prio-load-balancer) project for a single priority queue, + and disable the internal concurrency limit (set `BLOCKSIM_MAX_CONCURRENT` to `0`). + +## Beacon node setup + +### Lighthouse + +- Lighthouse with validation and equivocaation check before broadcast: https://github.com/sigp/lighthouse/pull/4168 +- with `--always-prepare-payload` and `--prepare-payload-lookahead 12000` flags, and some junk feeRecipeint + +Here's a [quick guide](https://gist.github.com/metachris/bcae9ae42e2fc834804241f991351c4e) for setting up Lighthouse. + +Here's an example Lighthouse systemd config: + +
+/etc/systemd/system/lighthouse.service + +```ini +[Unit] +Description=Lighthouse +After=network.target +Wants=network.target + +[Service] +User=ubuntu +Group=ubuntu +Type=simple +Restart=always +RestartSec=5 +TimeoutStopSec=180 +ExecStart=/home/ubuntu/.cargo/bin/lighthouse bn \ + --network mainnet \ + --checkpoint-sync-url=https://mainnet-checkpoint-sync.attestant.io \ + --eth1 \ + --http \ + --http-address "0.0.0.0" \ + --http-port 3500 \ + --datadir=/mnt/data/lighthouse \ + --http-allow-sync-stalled \ + --execution-endpoints=http://localhost:8551 \ + --jwt-secrets=/var/lib/goethereum/jwtsecret \ + --disable-deposit-contract-sync \ + --always-prepare-payload \ + --prepare-payload-lookahead 12000 + +[Install] +WantedBy=default.target +``` + +
+ + +### Prysm + +- Prysm with validation and equivocaation check before broadcast: https://github.com/prysmaticlabs/prysm/pull/12335 +- use `--grpc-max-msg-size 104857600`, because by default the getAllValidators response is too big and fails + +Here's an example Prysm systemd config: + +
+/etc/systemd/system/prysm.service + +```ini +[Unit] +Description=Prysm +After=network.target +Wants=network.target + +[Service] +User=ubuntu +Group=ubuntu +Type=simple +Restart=always +RestartSec=5 +TimeoutStopSec=180 +ExecStart=/home/ubuntu/prysm/bazel-bin/cmd/beacon-chain/beacon-chain_/beacon-chain \ + --accept-terms-of-use \ + --enable-debug-rpc-endpoints \ + --checkpoint-sync-url=https://mainnet-checkpoint-sync.attestant.io \ + --genesis-beacon-api-url=https://mainnet-checkpoint-sync.attestant.io \ + --grpc-gateway-host "0.0.0.0" \ + --datadir=/mnt/data/prysm \ + --p2p-max-peers 100 \ + --execution-endpoint=http://localhost:8551 \ + --jwt-secret=/var/lib/goethereum/jwtsecret \ + --min-sync-peers=1 \ + --grpc-max-msg-size 104857600 \ + --prepare-all-payloads \ + --disable-reorg-late-blocks + +[Install] +WantedBy=default.target +``` + +
+ +## Bid Cancellations + +Block builders can opt into cancellations by submitting blocks to `/relay/v1/builder/blocks?cancellations=1`. This may incur a performance penalty (i.e. validation of submissions taking significantly longer). See also https://github.com/flashbots/mev-boost-relay/issues/348 + +--- + +# Maintainers + +- [@metachris](https://twitter.com/metachris) +- [@Ruteri](https://twitter.com/mmrosum) +- [@avalonche](https://github.com/avalonche) + +# Contributing + +[Flashbots](https://flashbots.net) is a research and development collective working on mitigating the negative externalities of decentralized economies. We contribute with the larger free software community to illuminate the dark forest. + +You are welcome here <3. + +- If you have a question, feedback or a bug report for this project, please [open a new Issue](https://github.com/flashbots/mev-boost/issues). +- If you would like to contribute with code, check the [CONTRIBUTING file](CONTRIBUTING.md) for further info about the development environment. +- We just ask you to be nice. Read our [code of conduct](CODE_OF_CONDUCT.md). + +# Security + +If you find a security vulnerability on this project or any other initiative related to Flashbots, please let us know sending an email to security@flashbots.net. + +## Audits + +- [20220822](docs/audit-20220822.md), by [lotusbumi](https://github.com/lotusbumi). + +# License + +The code in this project is free software under the [AGPL License version 3 or later](LICENSE). + +--- + +Made with ☀️ by the ⚡🤖 collective. diff --git a/mev-boost-relay/README.md b/mev-boost-relay/README.md index edb49d4c2..0680ab693 100644 --- a/mev-boost-relay/README.md +++ b/mev-boost-relay/README.md @@ -1,401 +1,16 @@ -# MEV-Boost Relay +[flashbots mev-boost-relay readme](README.flashbots.md) -[![Goreport status](https://goreportcard.com/badge/github.com/flashbots/mev-boost-relay)](https://goreportcard.com/report/github.com/flashbots/mev-boost-relay) -[![Test status](https://github.com/flashbots/mev-boost-relay/workflows/Checks/badge.svg)](https://github.com/flashbots/mev-boost-relay/actions?query=workflow%3A%22Checks%22) -[![Docker hub](https://badgen.net/docker/size/flashbots/mev-boost-relay?icon=docker&label=image)](https://hub.docker.com/r/flashbots/mev-boost-relay/tags) +# Bolt MEV-Boost Relay -MEV-Boost Relay for Ethereum proposer/builder separation (PBS). +Bolt MEV-Boost Relay is a fork of the Flashbots MEV-Boost Relay package that +implements the functionality of the Constraints API. -Currently live at: +## How it works -* [boost-relay.flashbots.net](https://boost-relay.flashbots.net) (also on [Goerli](https://boost-relay-goerli.flashbots.net), [Sepolia](https://boost-relay-sepolia.flashbots.net) and [Holesky](https://boost-relay-holesky.flashbots.net)) -* [relay.ultrasound.money](https://relay.ultrasound.money), [agnostic-relay.net](https://agnostic-relay.net), bloXroute relays ([light fork](https://github.com/bloXroute-Labs/mev-relay)) -* [mainnet.aestus.live](https://mainnet.aestus.live), [relay.edennetwork.io/info](https://relay.edennetwork.io/info), [mainnet-relay.securerpc.com](https://mainnet-relay.securerpc.com) +The MEV-Boost Relay package has the standard functionality of the Flashbots MEV-Boost Relay, +but with the added functionality of the Constraints API which can be summarized as follows: -Alternatives (not audited or endorsed): [blocknative/dreamboat](https://github.com/blocknative/dreamboat), [manifold/mev-freelay](https://github.com/manifoldfinance/mev-freelay) - -### See also - -* [Docker images](https://hub.docker.com/r/flashbots/mev-boost-relay) -* [mev-boost](https://github.com/flashbots/mev-boost) -* [Relay API specs](https://flashbots.github.io/relay-specs) -* [Guide for running mev-boost-relay at scale](https://flashbots.notion.site/Running-mev-boost-relay-at-scale-draft-4040ccd5186c425d9a860cbb29bbfe09) -* [Running relay and builders in custom devnets](https://gist.github.com/metachris/66df812f2920e6b0047afb9fdaf7df91#using-unnamed-devnets) -* [More docs](/docs/docs/) - -### Components - -The relay consists of three main components, which are designed to run and scale independently, and to be as simple as possible: - -1. [API](https://github.com/flashbots/mev-boost-relay/tree/main/services/api): Services that provide APIs for (a) proposers, (b) block builders, (c) data. -1. [Website](https://github.com/flashbots/mev-boost-relay/tree/main/services/website): Serving the [website requests](https://boost-relay.flashbots.net/) (information is pulled from Redis and database). -1. [Housekeeper](https://github.com/flashbots/mev-boost-relay/tree/main/services/housekeeper): Updates known validators, proposer duties, and more in the background. Only a single instance of this should run. - -### Dependencies - -1. Redis -1. PostgreSQL -1. one or more beacon nodes -1. block submission validation nodes -1. [optional] Memcached - -### Beacon nodes / CL clients - -- The relay services need access to one or more beacon node for event subscriptions (in particular the `head` and `payload_attributes` topics). -- You can specify multiple beacon nodes by providing a comma separated list of beacon node URIs. -- The beacon nodes need to support the [`payload_attributes` SSE event](https://github.com/ethereum/beacon-APIs/pull/305). -- Support the [v2 CL publish block endpoint](https://github.com/ethereum/beacon-APIs/pull/317) in the current main branch, since August 2. This is still - experimental and may or may not fully work. It requires at least one of these CL clients - - **Lighthouse+** [v4.3.0](https://github.com/sigp/lighthouse/releases) or later. Here's a [quick guide](https://gist.github.com/metachris/bcae9ae42e2fc834804241f991351c4e) for setting up Lighthouse. - - **Prysm** [v4.0.6](https://github.com/prysmaticlabs/prysm/releases) or later. -- The latest release (v0.26) still uses the old V1 broadcast endpoint using CL clients with custom validate-before-broadcast patches (see [README of the release for more details](https://github.com/flashbots/mev-boost-relay/tree/v0.26#beacon-nodes--cl-clients)) - -**Relays are strongly advised to run multiple beacon nodes!** -* The reason is that on getPayload, the block has to be validated and broadcast by a local beacon node before it is returned to the proposer. -* If the local beacon nodes don't accept it (i.e. because it's down), the block won't be returned to the proposer, which leads to the proposer missing the slot. -* The relay makes the validate+broadcast request to all beacon nodes concurrently, and returns as soon as the first request is successful. - -### Security - -A security assessment for the relay was conducted on 2022-08-22 by [lotusbumi](https://github.com/lotusbumi). Additional information can be found in the [Security](#security) section of this repository. - -If you find a security vulnerability on this project or any other initiative related to Flashbots, please let us know sending an email to security@flashbots.net. - ---- - -# Background - -MEV is a centralizing force on Ethereum. Unattended, the competition for MEV opportunities leads to consensus security instability and permissioned communication infrastructure between traders and block producers. This erodes neutrality, transparency, decentralization, and permissionlessness. - -Flashbots is a research and development organization working on mitigating the negative externalities of MEV. Flashbots started as a builder specializing in MEV extraction in proof-of-work Ethereum to democratize access to MEV and make the most profitable blocks available to all miners. >90% of miners are outsourcing some of their block construction to Flashbots today. - -The mev-boost relay is a trusted mediator between block producers and block builders. It enables all Ethereum proof-of-stake validators to offer their blockspace to not just Flashbots but other builders as well. This opens up the market to more builders and creates competition between them, leading to more revenue and choice for validators, and better censorship-resistance for Ethereum. - -In the future, [proposer/builder separation](https://ethresear.ch/t/two-slot-proposer-builder-separation/10980) will be enshrined in the Ethereum protocol itself to further harden its trust model. - -Read more in [Why run mev-boost?](https://writings.flashbots.net/writings/why-run-mevboost/) and in the [Frequently Asked Questions](https://github.com/flashbots/mev-boost/wiki/Frequently-Asked-Questions). - ---- - -# Usage - -## Running Postgres, Redis and Memcached -```bash -# Start PostgreSQL & Redis individually: -docker run -d -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=postgres postgres -docker run -d -p 6379:6379 redis - -# [optional] Start Memcached -docker run -d -p 11211:11211 memcached - -# Or with docker-compose: -docker-compose up -``` - -Note: docker-compose also runs an Adminer (a web frontend for Postgres) on http://localhost:8093/?username=postgres (db: `postgres`, username: `postgres`, password: `postgres`) - -Now start the services: - -```bash -# The housekeeper sets up the validators, and does various housekeeping -go run . housekeeper --network sepolia --db postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable - -# Run APIs for sepolia (using a dummy BLS secret key) -go run . api --network sepolia --secret-key 0x607a11b45a7219cc61a3d9c5fd08c7eebd602a6a19a977f8d3771d5711a550f2 --db postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable - -# Run Website for sepolia -go run . website --network sepolia --db postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable - -# Query status -curl localhost:9062/eth/v1/builder/status - -# Send test validator registrations -curl -X POST -H'Content-Encoding: gzip' localhost:9062/eth/v1/builder/validators --data-binary @testdata/valreg2.json.gz - -# Delete previous registrations -redis-cli DEL boost-relay/sepolia:validators-registration boost-relay/sepolia:validators-registration-timestamp -``` - - -## Environment variables - -#### General - -* `ACTIVE_VALIDATOR_HOURS` - number of hours to track active proposers in redis (default: `3`) -* `API_MAX_HEADER_BYTES` - http maximum header bytes (default: `60_000`) -* `API_TIMEOUT_READ_MS` - http read timeout in milliseconds (default: `1_500`) -* `API_TIMEOUT_READHEADER_MS` - http read header timeout in milliseconds (default: `600`) -* `API_TIMEOUT_WRITE_MS` - http write timeout in milliseconds (default: `10_000`) -* `API_TIMEOUT_IDLE_MS` - http idle timeout in milliseconds (default: `3_000`) -* `API_SHUTDOWN_WAIT_SEC` - how long to wait on shutdown before stopping server, to allow draining of requests (default: `30`) -* `API_SHUTDOWN_STOP_SENDING_BIDS` - whether API should stop sending bids during shutdown (nly useful in single-instance/testnet setups, default: `false`) -* `BLOCKSIM_MAX_CONCURRENT` - maximum number of concurrent block-sim requests (0 for no maximum, default: `4`) -* `BLOCKSIM_TIMEOUT_MS` - builder block submission validation request timeout (default: `3000`) -* `BROADCAST_MODE` - which broadcast mode to use for block publishing (default: `consensus_and_equivocation`) -* `DB_DONT_APPLY_SCHEMA` - disable applying DB schema on startup (useful for connecting data API to read-only replica) -* `DB_TABLE_PREFIX` - prefix to use for db tables (default uses `dev`) -* `GETPAYLOAD_RETRY_TIMEOUT_MS` - getPayload retry getting a payload if first try failed (default: `100`) -* `MEMCACHED_URIS` - optional comma separated list of memcached endpoints, typically used as secondary storage alongside Redis -* `MEMCACHED_EXPIRY_SECONDS` - item expiry timeout when using memcache (default: `45`) -* `MEMCACHED_CLIENT_TIMEOUT_MS` - client timeout in milliseconds (default: `250`) -* `MEMCACHED_MAX_IDLE_CONNS` - client max idle conns (default: `10`) -* `NUM_ACTIVE_VALIDATOR_PROCESSORS` - proposer API - number of goroutines to listen to the active validators channel -* `NUM_VALIDATOR_REG_PROCESSORS` - proposer API - number of goroutines to listen to the validator registration channel -* `NO_HEADER_USERAGENTS` - proposer API - comma separated list of user agents for which no bids should be returned -* `ENABLE_BUILDER_CANCELLATIONS` - whether to enable block builder cancellations -* `REDIS_URI` - main redis URI (default: `localhost:6379`) -* `REDIS_READONLY_URI` - optional, a secondary redis instance for heavy read operations - -#### Feature Flags - -* `DISABLE_PAYLOAD_DATABASE_STORAGE` - builder API - disable storing execution payloads in the database (i.e. when using memcached as data availability redundancy) -* `DISABLE_LOWPRIO_BUILDERS` - reject block submissions by low-prio builders -* `FORCE_GET_HEADER_204` - force 204 as getHeader response -* `ENABLE_IGNORABLE_VALIDATION_ERRORS` - enable ignorable validation errors -* `USE_V1_PUBLISH_BLOCK_ENDPOINT` - uses the v1 publish block endpoint on the beacon node -* `USE_SSZ_ENCODING_PUBLISH_BLOCK` - uses the SSZ encoding for the publish block endpoint - -#### Development Environment Variables - -* `RUN_DB_TESTS` - when set to "1" enables integration tests with Postgres using endpoint specified by environment variable `TEST_DB_DSN` -* `RUN_INTEGRATION_TESTS` - when set to "1" enables integration tests, currently used for testing Memcached using comma separated list of endpoints specified by `MEMCACHED_URIS` -* `TEST_DB_DSN` - specifies connection string using Data Source Name (DSN) for Postgres (default: postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable) - -#### Redis Tuning - -* `REDIS_CONNECTION_POOL_SIZE`, `REDIS_MIN_IDLE_CONNECTIONS`, `REDIS_READ_TIMEOUT_SEC`, `REDIS_POOL_TIMEOUT_SEC`, `REDIS_WRITE_TIMEOUT_SEC` (see also [the code here](https://github.com/flashbots/mev-boost-relay/blob/e39cd38010de26bf9a51d1a3e77fc235ea87b12f/datastore/redis.go#L35-L41)) - -#### Website - -* `LINK_BEACONCHAIN` - url for beaconcha.in (default: `https://beaconcha.in`) -* `LINK_DATA_API` - origin url for data api (https://domain:port) -* `LINK_ETHERSCAN` - url for etherscan (default: `https://etherscan.io`) -* `LISTEN_ADDR` - listen address for webserver (default: `localhost:9060`) -* `RELAY_URL` - full url for the relay (https://pubkey@host) -* `SHOW_CONFIG_DETAILS` - when set to "1", logs configuration details - -## Updating the website - -* Edit the HTML in `services/website/website.html` -* Edit template values in `testdata/website-htmldata.json` -* Generate a static version of the website with `go run scripts/website-staticgen/main.go` - -This builds a local copy of the template and saves it in `website-index.html` - -The website is using: -* [PureCSS](https://purecss.io/) -* [HeroIcons](https://heroicons.com/) - ---- - -# Technical Notes - -See [ARCHITECTURE.md](ARCHITECTURE.md) and [Running MEV-Boost-Relay at scale](https://flashbots.notion.site/Draft-Running-a-relay-4040ccd5186c425d9a860cbb29bbfe09) for more technical details! - -## Storing execution payloads and redundant data availability - -By default, the execution payloads for all block submission are stored in Redis and also in the Postgres database, -to provide redundant data availability for getPayload responses. But the database table is not pruned automatically, -because it takes a lot of resources to rebuild the indexes (and a better option is using `TRUNCATE`). - -Storing all the payloads in the database can lead to terabytes of data in this particular table. Now it's also possible -to use memcached as a second data availability layer. Using memcached is optional and disabled by default. - -To enable memcached, you just need to supply the memcached URIs either via environment variable (i.e. -`MEMCACHED_URIS=localhost:11211`) or through command line flag (`--memcached-uris`). - -You can disable storing the execution payloads in the database with this environment variable: -`DISABLE_PAYLOAD_DATABASE_STORAGE=1`. - -## Builder submission validation nodes - -You can use the [builder project](https://github.com/flashbots/builder) to validate block builder submissions: https://github.com/flashbots/builder - -Here's an example systemd config: - -
-/etc/systemd/system/geth.service - -```ini -[Unit] -Description=mev-boost -Wants=network-online.target -After=network-online.target - -[Service] -User=ubuntu -Group=ubuntu -Environment=HOME=/home/ubuntu -Type=simple -KillMode=mixed -KillSignal=SIGINT -TimeoutStopSec=90 -Restart=on-failure -RestartSec=10s -ExecStart=/home/ubuntu/builder/build/bin/geth \ - --syncmode=snap \ - --datadir /var/lib/goethereum \ - --metrics \ - --metrics.expensive \ - --http \ - --http.api="engine,eth,web3,net,debug,flashbots" \ - --http.corsdomain "*" \ - --http.addr "0.0.0.0" \ - --http.port 8545 \ - --http.vhosts '*' \ - --ws \ - --ws.api="engine,eth,web3,net,debug" \ - --ws.addr 0.0.0.0 \ - --ws.port 8546 \ - --ws.api engine,eth,net,web3 \ - --ws.origins '*' \ - --graphql \ - --graphql.corsdomain '*' \ - --graphql.vhosts '*' \ - --authrpc.addr="0.0.0.0" \ - --authrpc.jwtsecret=/var/lib/goethereum/jwtsecret \ - --authrpc.vhosts '*' \ - --cache=8192 - -[Install] -WantedBy=multi-user.target -``` -
- -Sending blocks to the validation node: - -- The built-in [blocksim-ratelimiter](services/api/blocksim_ratelimiter.go) is a simple example queue implementation. -- By default, `BLOCKSIM_MAX_CONCURRENT` is set to 4, which allows 4 concurrent block simulations per API node -- For production use, use the [prio-load-balancer](https://github.com/flashbots/prio-load-balancer) project for a single priority queue, - and disable the internal concurrency limit (set `BLOCKSIM_MAX_CONCURRENT` to `0`). - -## Beacon node setup - -### Lighthouse - -- Lighthouse with validation and equivocaation check before broadcast: https://github.com/sigp/lighthouse/pull/4168 -- with `--always-prepare-payload` and `--prepare-payload-lookahead 12000` flags, and some junk feeRecipeint - -Here's a [quick guide](https://gist.github.com/metachris/bcae9ae42e2fc834804241f991351c4e) for setting up Lighthouse. - -Here's an example Lighthouse systemd config: - -
-/etc/systemd/system/lighthouse.service - -```ini -[Unit] -Description=Lighthouse -After=network.target -Wants=network.target - -[Service] -User=ubuntu -Group=ubuntu -Type=simple -Restart=always -RestartSec=5 -TimeoutStopSec=180 -ExecStart=/home/ubuntu/.cargo/bin/lighthouse bn \ - --network mainnet \ - --checkpoint-sync-url=https://mainnet-checkpoint-sync.attestant.io \ - --eth1 \ - --http \ - --http-address "0.0.0.0" \ - --http-port 3500 \ - --datadir=/mnt/data/lighthouse \ - --http-allow-sync-stalled \ - --execution-endpoints=http://localhost:8551 \ - --jwt-secrets=/var/lib/goethereum/jwtsecret \ - --disable-deposit-contract-sync \ - --always-prepare-payload \ - --prepare-payload-lookahead 12000 - -[Install] -WantedBy=default.target -``` - -
- - -### Prysm - -- Prysm with validation and equivocaation check before broadcast: https://github.com/prysmaticlabs/prysm/pull/12335 -- use `--grpc-max-msg-size 104857600`, because by default the getAllValidators response is too big and fails - -Here's an example Prysm systemd config: - -
-/etc/systemd/system/prysm.service - -```ini -[Unit] -Description=Prysm -After=network.target -Wants=network.target - -[Service] -User=ubuntu -Group=ubuntu -Type=simple -Restart=always -RestartSec=5 -TimeoutStopSec=180 -ExecStart=/home/ubuntu/prysm/bazel-bin/cmd/beacon-chain/beacon-chain_/beacon-chain \ - --accept-terms-of-use \ - --enable-debug-rpc-endpoints \ - --checkpoint-sync-url=https://mainnet-checkpoint-sync.attestant.io \ - --genesis-beacon-api-url=https://mainnet-checkpoint-sync.attestant.io \ - --grpc-gateway-host "0.0.0.0" \ - --datadir=/mnt/data/prysm \ - --p2p-max-peers 100 \ - --execution-endpoint=http://localhost:8551 \ - --jwt-secret=/var/lib/goethereum/jwtsecret \ - --min-sync-peers=1 \ - --grpc-max-msg-size 104857600 \ - --prepare-all-payloads \ - --disable-reorg-late-blocks - -[Install] -WantedBy=default.target -``` - -
- -## Bid Cancellations - -Block builders can opt into cancellations by submitting blocks to `/relay/v1/builder/blocks?cancellations=1`. This may incur a performance penalty (i.e. validation of submissions taking significantly longer). See also https://github.com/flashbots/mev-boost-relay/issues/348 - ---- - -# Maintainers - -- [@metachris](https://twitter.com/metachris) -- [@Ruteri](https://twitter.com/mmrosum) -- [@avalonche](https://github.com/avalonche) - -# Contributing - -[Flashbots](https://flashbots.net) is a research and development collective working on mitigating the negative externalities of decentralized economies. We contribute with the larger free software community to illuminate the dark forest. - -You are welcome here <3. - -- If you have a question, feedback or a bug report for this project, please [open a new Issue](https://github.com/flashbots/mev-boost/issues). -- If you would like to contribute with code, check the [CONTRIBUTING file](CONTRIBUTING.md) for further info about the development environment. -- We just ask you to be nice. Read our [code of conduct](CODE_OF_CONDUCT.md). - -# Security - -If you find a security vulnerability on this project or any other initiative related to Flashbots, please let us know sending an email to security@flashbots.net. - -## Audits - -- [20220822](docs/audit-20220822.md), by [lotusbumi](https://github.com/lotusbumi). - -# License - -The code in this project is free software under the [AGPL License version 3 or later](LICENSE). - ---- - -Made with ☀️ by the ⚡🤖 collective. +1. Listen for incoming constraint messages from proposers +2. Propagate constraints to connected builders +3. Validate incoming signed bids and inclusion proofs from builders +4. Forward the best bid to the proposer's MEV-Boost sidecar diff --git a/mev-boost/README.flashbots.md b/mev-boost/README.flashbots.md new file mode 100644 index 000000000..411110595 --- /dev/null +++ b/mev-boost/README.flashbots.md @@ -0,0 +1,389 @@ +![mev-boost](https://user-images.githubusercontent.com/116939/224986867-3d1916c6-3219-4d61-b1ce-213fc663070c.png) + +# + +[![Goreport status](https://goreportcard.com/badge/github.com/flashbots/mev-boost)](https://goreportcard.com/report/github.com/flashbots/mev-boost) +[![Test status](https://github.com/flashbots/mev-boost/workflows/Tests/badge.svg?branch=develop)](https://github.com/flashbots/mev-boost/actions?query=workflow%3A%22Tests%22) +[![Docker hub](https://badgen.net/docker/size/flashbots/mev-boost?icon=docker&label=image)](https://hub.docker.com/r/flashbots/mev-boost/tags) + +## What is MEV-Boost? + +`mev-boost` is open source middleware run by validators to access a competitive block-building market. MEV-Boost is an initial implementation of [proposer-builder separation (PBS)](https://ethresear.ch/t/proposer-block-builder-separation-friendly-fee-market-designs/9725) for proof-of-stake (PoS) Ethereum. + +With MEV-Boost, validators can access blocks from a marketplace of builders. Builders produce blocks containing transaction orderflow and a fee for the block proposing validator. Separating the role of proposers from block builders promotes greater competition, decentralization, and censorship-resistance for Ethereum. + +## How does MEV-Boost work? + +PoS node operators must run three pieces of software: a validator client, a consensus client, and an execution client. MEV-boost is a sidecar for the beacon node - a separate piece of open source software, which queries and outsources block-building to a network of builders. Block builders prepare full blocks, optimizing for MEV extraction and fair distribution of rewards. They then submit their blocks to relays. + +Relays aggregate blocks from **multiple** builders in order to select the block with the highest fees. One instance of MEV-boost can be configured by a validator to connect to **multiple** relays. The consensus layer client of a validator proposes the most profitable block received from MEV-boost to the Ethereum network for attestation and block inclusion. + +A MEV-Boost security assessment was conducted on 2022-06-20 by [lotusbumi](https://github.com/lotusbumi). Additional information can be found in the [Security](#security) section of this repository. + + +![MEV-Boost service integration overview](https://raw.githubusercontent.com/flashbots/mev-boost/54567443e718b09f8034d677723476b679782fb7/docs/mev-boost-integration-overview.png) + +## Who can run MEV-Boost? + +MEV-Boost is a piece of software that any PoS Ethereum node operator (including solo validators) can run as part of their Beacon Client software. It is compatible with any Ethereum consensus client. Support and installation instructions for each client can be found [here](#installing). + +--- + +See also: + +* [MEV-Boost Docker images](https://hub.docker.com/r/flashbots/mev-boost) +* [Wiki](https://github.com/flashbots/mev-boost/wiki) +* Specs: + * [Builder API](https://ethereum.github.io/builder-specs) + +--- + +# Table of Contents + +- [Background](#background) +- [Installing](#installing) + - [Binaries](#binaries) + - [From source](#from-source) + - [From Docker image](#from-docker-image) + - [Systemd configuration](#systemd-configuration) +- [Usage](#usage) + - [Mainnet](#mainnet) + - [Goerli testnet](#goerli-testnet) + - [Sepolia testnet](#sepolia-testnet) + - [Holesky testnet](#holesky-testnet) + - [`test-cli`](#test-cli) + - [mev-boost cli arguments](#mev-boost-cli-arguments) +- [API](#api) +- [Maintainers](#maintainers) +- [Contributing](#contributing) +- [Security](#security) + - [Bug Bounty](#bug-bounty) + - [Audits](#audits) +- [License](#license) + +--- + +# Background + +MEV is a centralizing force on Ethereum. Unattended, the competition for MEV opportunities leads to consensus security instability and permissioned communication infrastructure between traders and block producers. This erodes neutrality, transparency, decentralization, and permissionlessness. + +Proposer/block-builder separation (PBS) was initially proposed by Ethereum researchers as a response to the risk that MEV poses to decentralization of consensus networks. They have suggested that uncontrolled MEV extraction promotes economies of scale which are centralizing in nature, and complicate decentralized pooling. + + +In the future, [proposer/builder separation](https://ethresear.ch/t/two-slot-proposer-builder-separation/10980) will be enshrined in the Ethereum protocol itself to further harden its trust model. + +Read more in [Why run MEV-Boost?](https://writings.flashbots.net/why-run-mevboost/) and in the [Frequently Asked Questions](https://github.com/flashbots/mev-boost/wiki/Frequently-Asked-Questions). + +# Installing + +The most common setup is to install MEV-Boost on the same machine as the beacon client. Multiple beacon-clients can use a single MEV-Boost instance. The default port is 18550. + +See also [Rémy Roy's guide](https://github.com/remyroy/ethstaker/blob/main/prepare-for-the-merge.md#installing-mev-boost) for comprehensive instructions on installing, configuring and running MEV-Boost. + +## Binaries + +Each release includes binaries from Linux, Windows and macOS. You can find the latest release at +https://github.com/flashbots/mev-boost/releases + + +## From source + +Requires [Go 1.18+](https://go.dev/doc/install). + +### `go install` + +Install the latest MEV-Boost release with `go install`: + +```bash +go install github.com/flashbots/mev-boost@latest +mev-boost -help +``` + +### Clone and Build + +Ensure you are downloading the most updated MEV-Boost release. Releases are available at https://github.com/flashbots/mev-boost/releases + +clone the repository and build it: + +```bash +# By default, the develop branch includes ongoing merged PRs a future release. +git clone https://github.com/flashbots/mev-boost.git +cd mev-boost + +# You can use the stable branch, which is always updated with the latest released version +git checkout stable + +# If you want to build a specific release, check out the tag. See also https://github.com/flashbots/mev-boost/releases +git checkout tags/YOUR_VERSION + +# Build most recent version of MEV-Boost +make build + +# Show help. This confirms MEV-Boost is able to start +./mev-boost -help +``` + +## From Docker image + +We maintain a MEV-Boost Docker images at https://hub.docker.com/r/flashbots/mev-boost + +- [Install Docker Engine](https://docs.docker.com/engine/install/) +- Pull & run the latest image: + +```bash +# Get the MEV-Boost image +docker pull flashbots/mev-boost:latest + +# Run it +docker run flashbots/mev-boost -help +``` + +## Systemd configuration + +You can run MEV-Boost with a systemd config like this: + +
+/etc/systemd/system/mev-boost.service + +```ini +[Unit] +Description=mev-boost +Wants=network-online.target +After=network-online.target + +[Service] +User=mev-boost +Group=mev-boost +WorkingDirectory=/home/mev-boost +Type=simple +Restart=always +RestartSec=5 +ExecStart=/home/mev-boost/bin/mev-boost \ + -relay-check \ + -relay YOUR_RELAY_CHOICE_A \ + -relay YOUR_RELAY_CHOICE_B \ + -relay YOUR_RELAY_CHOICE_C + +[Install] +WantedBy=multi-user.target +``` +
+ + +# Usage + +A single MEV-Boost instance can be used by multiple beacon nodes and validators. + +Aside from running MEV-Boost on your local network, you must configure: +* individual **beacon nodes** to connect to MEV-Boost. Beacon Node configuration varies by Consensus client. Guides for each client can be found on the [MEV-boost website](https://boost.flashbots.net/#block-356364ebd7cc424fb524428ed0134b21). +* individual **validators** to configure a preferred relay selection. Note: validators should take precautions to only connect to trusted relays. Read more about [the role of relays here](https://docs.flashbots.net/flashbots-mev-boost/relay). + +Lists of available relays are maintained by +* [Ethstaker](https://github.com/remyroy/ethstaker/blob/main/MEV-relay-list.md) [[2]](https://ethstaker.cc/mev-relay-list/) +* [Lido](https://research.lido.fi/t/lido-on-ethereum-call-for-relay-providers/2844) + +## Note on usage documentation + +The documentation in this README reflects the latest state of the `main` branch, which may have cli flags or functionality not present in the latest release. + +Please take a look at the specific release documentation about the available command line flags: https://github.com/flashbots/mev-boost/releases + +## Mainnet + +Run MEV-Boost pointed at a mainnet relay: + +``` +./mev-boost -relay-check -relay URL-OF-TRUSTED-RELAY +``` + +## Goerli testnet + +Run MEV-Boost pointed at a Goerli relay: + +``` +./mev-boost -goerli -relay-check -relay URL-OF-TRUSTED-RELAY +``` + +## Sepolia testnet + +Run MEV-Boost pointed at a Sepolia relay: + +``` +./mev-boost -sepolia -relay-check -relay URL-OF-TRUSTED-RELAY +``` + +## Holesky testnet + +Run MEV-Boost pointed at a Holesky relay: + +``` +./mev-boost -holesky -relay-check -relay URL-OF-TRUSTED-RELAY +``` + +## `test-cli` + +`test-cli` is a utility to execute all proposer requests against MEV-Boost + relay. See also the [test-cli readme](cmd/test-cli/README.md). + + +## mev-boost cli arguments + +These are the CLI arguments for the develop branch. For arguments available in a specific release, check the [release page](https://github.com/flashbots/mev-boost/releases). + +``` +$ ./mev-boost -help +Usage of mev-boost: + -addr string + listen-address for mev-boost server (default "localhost:18550") + -debug + shorthand for '-loglevel debug' + -genesis-fork-version string + use a custom genesis fork version + -goerli + use Goerli + -holesky + use Holesky + -json + log in JSON format instead of text + -log-no-version + disables adding the version to every log entry + -log-service string + add a 'service=...' tag to all log messages + -loglevel string + minimum loglevel: trace, debug, info, warn/warning, error, fatal, panic (default "info") + -mainnet + use Mainnet (default true) + -min-bid float + minimum bid to accept from a relay [eth] + -relay value + a single relay, can be specified multiple times + -relay-check + check relay status on startup and on the status API call + -relay-monitor value + a single relay monitor, can be specified multiple times + -relay-monitors string + relay monitor urls - single entry or comma-separated list (scheme://host) + -relays string + relay urls - single entry or comma-separated list (scheme://pubkey@host) + -request-timeout-getheader int + timeout for getHeader requests to the relay [ms] (default 950) + -request-timeout-getpayload int + timeout for getPayload requests to the relay [ms] (default 4000) + -request-timeout-regval int + timeout for registerValidator requests [ms] (default 3000) + -sepolia + use Sepolia + -version + only print version +``` + +### `-relays` vs `-relay` + +There are two different flags for specifying relays: `-relays` and `-relay`. +The `-relays` flag is a comma separated string of relays. On the other hand, +the `-relay` flag is used to specify a single relay, but can be used multiple +times for multiple relays. Use whichever method suits your preferences. + +These two MEV-Boost commands are equivalent: + +``` +./mev-boost -relay-check \ + -relays $YOUR_RELAY_CHOICE_A,$YOUR_RELAY_CHOICE_B,$YOUR_RELAY_CHOICE_C +``` + +``` +./mev-boost -relay-check \ + -relay $YOUR_RELAY_CHOICE_A \ + -relay $YOUR_RELAY_CHOICE_B \ + -relay $YOUR_RELAY_CHOICE_C +``` + + +### Setting a minimum bid value with `-min-bid` + +The `-min-bid` flag allows setting a minimum bid value. If no bid from the builder network delivers at least this value, MEV-Boost will not return a bid +to the beacon node, making it fall back to local block production. + +Example for setting a minimum bid value of 0.06 ETH: + +``` +./mev-boost \ + -min-bid 0.06 \ + -relay $YOUR_RELAY_CHOICE_A \ + -relay $YOUR_RELAY_CHOICE_B \ + -relay $YOUR_RELAY_CHOICE_C +``` + +--- + +# API + +`mev-boost` implements the latest [Builder Specification](https://github.com/ethereum/builder-specs). + +```mermaid +sequenceDiagram + participant consensus + participant mev_boost + participant relays + Title: Block Proposal + Note over consensus: validator starts up + consensus->>mev_boost: registerValidator + mev_boost->>relays: registerValidator + Note over consensus: wait for allocated slot + consensus->>mev_boost: getHeader + mev_boost->>relays: getHeader + relays-->>mev_boost: getHeader response + Note over mev_boost: verify response matches expected + Note over mev_boost: select best payload + mev_boost-->>consensus: getHeader response + Note over consensus: sign the header + consensus->>mev_boost: submitBlindedBlock + Note over mev_boost: identify payload source + mev_boost->>relays: submitBlindedBlock + Note over relays: validate signature + relays-->>mev_boost: submitBlindedBlock response + Note over mev_boost: verify response matches expected + mev_boost-->>consensus: submitBlindedBlock response +``` + +# Maintainers + +- [@metachris](https://github.com/metachris) +- [@jtraglia](https://github.com/jtraglia) +- [@ralexstokes](https://github.com/ralexstokes) +- [@terencechain](https://github.com/terencechain) +- [@lightclient](https://github.com/lightclient) +- [@avalonche](https://github.com/avalonche) +- [@Ruteri](https://github.com/Ruteri) + +# Contributing + +You are welcome here <3. + +- If you have a question, feedback or a bug report for this project, please [open a new Issue](https://github.com/flashbots/mev-boost/issues). +- If you would like to contribute with code, check the [CONTRIBUTING file](CONTRIBUTING.md) for further info about the development environment. +- We just ask you to be nice. Read our [code of conduct](CODE_OF_CONDUCT.md). + +# Security + +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. Refer to the [SECURITY file](SECURITY.md) +for details. + +## Bug Bounty + +We have a bug bounty program! Get up to $25k USD for a critical vulnerability. + +We would like to welcome node operators, builders, searchers, and other +participants in the ecosystem to contribute to this bounty pool to help make the +ecosystem more secure. + +## Audits + +- [20220620](docs/audit-20220620.md), by [lotusbumi](https://github.com/lotusbumi). + +# License + +The code in this project is free software under the [MIT License](LICENSE). + +Logo by [@lekevicius](https://twitter.com/lekevicius) on CC0 license. diff --git a/mev-boost/README.md b/mev-boost/README.md index 411110595..13906c688 100644 --- a/mev-boost/README.md +++ b/mev-boost/README.md @@ -1,389 +1,15 @@ -![mev-boost](https://user-images.githubusercontent.com/116939/224986867-3d1916c6-3219-4d61-b1ce-213fc663070c.png) +[flashbots mev-boost readme](README.flashbots.md) -# +# Bolt MEV-Boost -[![Goreport status](https://goreportcard.com/badge/github.com/flashbots/mev-boost)](https://goreportcard.com/report/github.com/flashbots/mev-boost) -[![Test status](https://github.com/flashbots/mev-boost/workflows/Tests/badge.svg?branch=develop)](https://github.com/flashbots/mev-boost/actions?query=workflow%3A%22Tests%22) -[![Docker hub](https://badgen.net/docker/size/flashbots/mev-boost?icon=docker&label=image)](https://hub.docker.com/r/flashbots/mev-boost/tags) +Bolt MEV-Boost is a fork of the Flashbots MEV-Boost package that +implements the functionality of the Constraints API. -## What is MEV-Boost? +## How it works -`mev-boost` is open source middleware run by validators to access a competitive block-building market. MEV-Boost is an initial implementation of [proposer-builder separation (PBS)](https://ethresear.ch/t/proposer-block-builder-separation-friendly-fee-market-designs/9725) for proof-of-stake (PoS) Ethereum. +The MEV-Boost package has the standard functionality of the Flashbots MEV-Boost, but with the added functionality of the +Constraints API which can be summarized as follows: -With MEV-Boost, validators can access blocks from a marketplace of builders. Builders produce blocks containing transaction orderflow and a fee for the block proposing validator. Separating the role of proposers from block builders promotes greater competition, decentralization, and censorship-resistance for Ethereum. - -## How does MEV-Boost work? - -PoS node operators must run three pieces of software: a validator client, a consensus client, and an execution client. MEV-boost is a sidecar for the beacon node - a separate piece of open source software, which queries and outsources block-building to a network of builders. Block builders prepare full blocks, optimizing for MEV extraction and fair distribution of rewards. They then submit their blocks to relays. - -Relays aggregate blocks from **multiple** builders in order to select the block with the highest fees. One instance of MEV-boost can be configured by a validator to connect to **multiple** relays. The consensus layer client of a validator proposes the most profitable block received from MEV-boost to the Ethereum network for attestation and block inclusion. - -A MEV-Boost security assessment was conducted on 2022-06-20 by [lotusbumi](https://github.com/lotusbumi). Additional information can be found in the [Security](#security) section of this repository. - - -![MEV-Boost service integration overview](https://raw.githubusercontent.com/flashbots/mev-boost/54567443e718b09f8034d677723476b679782fb7/docs/mev-boost-integration-overview.png) - -## Who can run MEV-Boost? - -MEV-Boost is a piece of software that any PoS Ethereum node operator (including solo validators) can run as part of their Beacon Client software. It is compatible with any Ethereum consensus client. Support and installation instructions for each client can be found [here](#installing). - ---- - -See also: - -* [MEV-Boost Docker images](https://hub.docker.com/r/flashbots/mev-boost) -* [Wiki](https://github.com/flashbots/mev-boost/wiki) -* Specs: - * [Builder API](https://ethereum.github.io/builder-specs) - ---- - -# Table of Contents - -- [Background](#background) -- [Installing](#installing) - - [Binaries](#binaries) - - [From source](#from-source) - - [From Docker image](#from-docker-image) - - [Systemd configuration](#systemd-configuration) -- [Usage](#usage) - - [Mainnet](#mainnet) - - [Goerli testnet](#goerli-testnet) - - [Sepolia testnet](#sepolia-testnet) - - [Holesky testnet](#holesky-testnet) - - [`test-cli`](#test-cli) - - [mev-boost cli arguments](#mev-boost-cli-arguments) -- [API](#api) -- [Maintainers](#maintainers) -- [Contributing](#contributing) -- [Security](#security) - - [Bug Bounty](#bug-bounty) - - [Audits](#audits) -- [License](#license) - ---- - -# Background - -MEV is a centralizing force on Ethereum. Unattended, the competition for MEV opportunities leads to consensus security instability and permissioned communication infrastructure between traders and block producers. This erodes neutrality, transparency, decentralization, and permissionlessness. - -Proposer/block-builder separation (PBS) was initially proposed by Ethereum researchers as a response to the risk that MEV poses to decentralization of consensus networks. They have suggested that uncontrolled MEV extraction promotes economies of scale which are centralizing in nature, and complicate decentralized pooling. - - -In the future, [proposer/builder separation](https://ethresear.ch/t/two-slot-proposer-builder-separation/10980) will be enshrined in the Ethereum protocol itself to further harden its trust model. - -Read more in [Why run MEV-Boost?](https://writings.flashbots.net/why-run-mevboost/) and in the [Frequently Asked Questions](https://github.com/flashbots/mev-boost/wiki/Frequently-Asked-Questions). - -# Installing - -The most common setup is to install MEV-Boost on the same machine as the beacon client. Multiple beacon-clients can use a single MEV-Boost instance. The default port is 18550. - -See also [Rémy Roy's guide](https://github.com/remyroy/ethstaker/blob/main/prepare-for-the-merge.md#installing-mev-boost) for comprehensive instructions on installing, configuring and running MEV-Boost. - -## Binaries - -Each release includes binaries from Linux, Windows and macOS. You can find the latest release at -https://github.com/flashbots/mev-boost/releases - - -## From source - -Requires [Go 1.18+](https://go.dev/doc/install). - -### `go install` - -Install the latest MEV-Boost release with `go install`: - -```bash -go install github.com/flashbots/mev-boost@latest -mev-boost -help -``` - -### Clone and Build - -Ensure you are downloading the most updated MEV-Boost release. Releases are available at https://github.com/flashbots/mev-boost/releases - -clone the repository and build it: - -```bash -# By default, the develop branch includes ongoing merged PRs a future release. -git clone https://github.com/flashbots/mev-boost.git -cd mev-boost - -# You can use the stable branch, which is always updated with the latest released version -git checkout stable - -# If you want to build a specific release, check out the tag. See also https://github.com/flashbots/mev-boost/releases -git checkout tags/YOUR_VERSION - -# Build most recent version of MEV-Boost -make build - -# Show help. This confirms MEV-Boost is able to start -./mev-boost -help -``` - -## From Docker image - -We maintain a MEV-Boost Docker images at https://hub.docker.com/r/flashbots/mev-boost - -- [Install Docker Engine](https://docs.docker.com/engine/install/) -- Pull & run the latest image: - -```bash -# Get the MEV-Boost image -docker pull flashbots/mev-boost:latest - -# Run it -docker run flashbots/mev-boost -help -``` - -## Systemd configuration - -You can run MEV-Boost with a systemd config like this: - -
-/etc/systemd/system/mev-boost.service - -```ini -[Unit] -Description=mev-boost -Wants=network-online.target -After=network-online.target - -[Service] -User=mev-boost -Group=mev-boost -WorkingDirectory=/home/mev-boost -Type=simple -Restart=always -RestartSec=5 -ExecStart=/home/mev-boost/bin/mev-boost \ - -relay-check \ - -relay YOUR_RELAY_CHOICE_A \ - -relay YOUR_RELAY_CHOICE_B \ - -relay YOUR_RELAY_CHOICE_C - -[Install] -WantedBy=multi-user.target -``` -
- - -# Usage - -A single MEV-Boost instance can be used by multiple beacon nodes and validators. - -Aside from running MEV-Boost on your local network, you must configure: -* individual **beacon nodes** to connect to MEV-Boost. Beacon Node configuration varies by Consensus client. Guides for each client can be found on the [MEV-boost website](https://boost.flashbots.net/#block-356364ebd7cc424fb524428ed0134b21). -* individual **validators** to configure a preferred relay selection. Note: validators should take precautions to only connect to trusted relays. Read more about [the role of relays here](https://docs.flashbots.net/flashbots-mev-boost/relay). - -Lists of available relays are maintained by -* [Ethstaker](https://github.com/remyroy/ethstaker/blob/main/MEV-relay-list.md) [[2]](https://ethstaker.cc/mev-relay-list/) -* [Lido](https://research.lido.fi/t/lido-on-ethereum-call-for-relay-providers/2844) - -## Note on usage documentation - -The documentation in this README reflects the latest state of the `main` branch, which may have cli flags or functionality not present in the latest release. - -Please take a look at the specific release documentation about the available command line flags: https://github.com/flashbots/mev-boost/releases - -## Mainnet - -Run MEV-Boost pointed at a mainnet relay: - -``` -./mev-boost -relay-check -relay URL-OF-TRUSTED-RELAY -``` - -## Goerli testnet - -Run MEV-Boost pointed at a Goerli relay: - -``` -./mev-boost -goerli -relay-check -relay URL-OF-TRUSTED-RELAY -``` - -## Sepolia testnet - -Run MEV-Boost pointed at a Sepolia relay: - -``` -./mev-boost -sepolia -relay-check -relay URL-OF-TRUSTED-RELAY -``` - -## Holesky testnet - -Run MEV-Boost pointed at a Holesky relay: - -``` -./mev-boost -holesky -relay-check -relay URL-OF-TRUSTED-RELAY -``` - -## `test-cli` - -`test-cli` is a utility to execute all proposer requests against MEV-Boost + relay. See also the [test-cli readme](cmd/test-cli/README.md). - - -## mev-boost cli arguments - -These are the CLI arguments for the develop branch. For arguments available in a specific release, check the [release page](https://github.com/flashbots/mev-boost/releases). - -``` -$ ./mev-boost -help -Usage of mev-boost: - -addr string - listen-address for mev-boost server (default "localhost:18550") - -debug - shorthand for '-loglevel debug' - -genesis-fork-version string - use a custom genesis fork version - -goerli - use Goerli - -holesky - use Holesky - -json - log in JSON format instead of text - -log-no-version - disables adding the version to every log entry - -log-service string - add a 'service=...' tag to all log messages - -loglevel string - minimum loglevel: trace, debug, info, warn/warning, error, fatal, panic (default "info") - -mainnet - use Mainnet (default true) - -min-bid float - minimum bid to accept from a relay [eth] - -relay value - a single relay, can be specified multiple times - -relay-check - check relay status on startup and on the status API call - -relay-monitor value - a single relay monitor, can be specified multiple times - -relay-monitors string - relay monitor urls - single entry or comma-separated list (scheme://host) - -relays string - relay urls - single entry or comma-separated list (scheme://pubkey@host) - -request-timeout-getheader int - timeout for getHeader requests to the relay [ms] (default 950) - -request-timeout-getpayload int - timeout for getPayload requests to the relay [ms] (default 4000) - -request-timeout-regval int - timeout for registerValidator requests [ms] (default 3000) - -sepolia - use Sepolia - -version - only print version -``` - -### `-relays` vs `-relay` - -There are two different flags for specifying relays: `-relays` and `-relay`. -The `-relays` flag is a comma separated string of relays. On the other hand, -the `-relay` flag is used to specify a single relay, but can be used multiple -times for multiple relays. Use whichever method suits your preferences. - -These two MEV-Boost commands are equivalent: - -``` -./mev-boost -relay-check \ - -relays $YOUR_RELAY_CHOICE_A,$YOUR_RELAY_CHOICE_B,$YOUR_RELAY_CHOICE_C -``` - -``` -./mev-boost -relay-check \ - -relay $YOUR_RELAY_CHOICE_A \ - -relay $YOUR_RELAY_CHOICE_B \ - -relay $YOUR_RELAY_CHOICE_C -``` - - -### Setting a minimum bid value with `-min-bid` - -The `-min-bid` flag allows setting a minimum bid value. If no bid from the builder network delivers at least this value, MEV-Boost will not return a bid -to the beacon node, making it fall back to local block production. - -Example for setting a minimum bid value of 0.06 ETH: - -``` -./mev-boost \ - -min-bid 0.06 \ - -relay $YOUR_RELAY_CHOICE_A \ - -relay $YOUR_RELAY_CHOICE_B \ - -relay $YOUR_RELAY_CHOICE_C -``` - ---- - -# API - -`mev-boost` implements the latest [Builder Specification](https://github.com/ethereum/builder-specs). - -```mermaid -sequenceDiagram - participant consensus - participant mev_boost - participant relays - Title: Block Proposal - Note over consensus: validator starts up - consensus->>mev_boost: registerValidator - mev_boost->>relays: registerValidator - Note over consensus: wait for allocated slot - consensus->>mev_boost: getHeader - mev_boost->>relays: getHeader - relays-->>mev_boost: getHeader response - Note over mev_boost: verify response matches expected - Note over mev_boost: select best payload - mev_boost-->>consensus: getHeader response - Note over consensus: sign the header - consensus->>mev_boost: submitBlindedBlock - Note over mev_boost: identify payload source - mev_boost->>relays: submitBlindedBlock - Note over relays: validate signature - relays-->>mev_boost: submitBlindedBlock response - Note over mev_boost: verify response matches expected - mev_boost-->>consensus: submitBlindedBlock response -``` - -# Maintainers - -- [@metachris](https://github.com/metachris) -- [@jtraglia](https://github.com/jtraglia) -- [@ralexstokes](https://github.com/ralexstokes) -- [@terencechain](https://github.com/terencechain) -- [@lightclient](https://github.com/lightclient) -- [@avalonche](https://github.com/avalonche) -- [@Ruteri](https://github.com/Ruteri) - -# Contributing - -You are welcome here <3. - -- If you have a question, feedback or a bug report for this project, please [open a new Issue](https://github.com/flashbots/mev-boost/issues). -- If you would like to contribute with code, check the [CONTRIBUTING file](CONTRIBUTING.md) for further info about the development environment. -- We just ask you to be nice. Read our [code of conduct](CODE_OF_CONDUCT.md). - -# Security - -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. Refer to the [SECURITY file](SECURITY.md) -for details. - -## Bug Bounty - -We have a bug bounty program! Get up to $25k USD for a critical vulnerability. - -We would like to welcome node operators, builders, searchers, and other -participants in the ecosystem to contribute to this bounty pool to help make the -ecosystem more secure. - -## Audits - -- [20220620](docs/audit-20220620.md), by [lotusbumi](https://github.com/lotusbumi). - -# License - -The code in this project is free software under the [MIT License](LICENSE). - -Logo by [@lekevicius](https://twitter.com/lekevicius) on CC0 license. +1. Propagate incoming constraint messages to relays +2. Validate incoming headers and inclusion proofs +3. Forward the best bid to the proposer for signing