-
Notifications
You must be signed in to change notification settings - Fork 740
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
eda5a5c
commit 84e7f53
Showing
2 changed files
with
120 additions
and
25 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,45 +1,140 @@ | ||
# MEV and Lighthouse | ||
|
||
A primer on MEV can be found [here]([MEV](https://ethereum.org/en/developers/docs/mev/)). | ||
Lighthouse is able to interact with servers that implement the [builder API](https://github.com/ethereum/builder-specs), | ||
allowing it to produce blocks without having knowledge of the transactions included in the block. This enables | ||
Lighthouse to outsource the job of transaction gathering/ordering within a block to parties specialized in this | ||
particular task. A primer on MEV can be found [here]([MEV](https://ethereum.org/en/developers/docs/mev/)). | ||
|
||
Lighthouse is able to interact with servers that implement the [builder API](https://github.com/ethereum/builder-specs). | ||
If the builder you are connected to | ||
There is no slashing risk when connecting to the builder API because Lighthouse will keep you from ever signing over *two* | ||
blocks, but a live-ness risk is introduced because you will be signing blocks where you haven't actually executed the transactions | ||
within the block. So you won't know whether the transactions are valid and you might sign a block that the network will | ||
reject. This leads to a missed proposal which earns a penalty on top of the opportunity cost of lost block rewards. | ||
|
||
## How to connect to a builder | ||
|
||
The beacon node and validator client each require a new flag for lighthouse to be fully compatible with builder API servers. | ||
It's important that the builder API server you are connected to is serving informatoin about | ||
|
||
``` | ||
lighthouse bn --builder https://mainnet-builder.test | ||
``` | ||
The `--builder` flag will cause the beacon node to query the provided URL during block production for a block | ||
payload whose transactions have been stubbed out. If this request fails, Lighthouse will fall back to the local | ||
execution engine and produce a block using transactions gathered and verified locally. | ||
|
||
The beacon node will *only* query for this type of block (a "blinded" block) when a validator specifically requests it. | ||
Otherwise, it will continue to serve full blocks as normal. In order to configure the validator client to query for | ||
blinded blocks, you should use the following flag: | ||
|
||
``` | ||
lighthouse vc --builder-proposals | ||
``` | ||
With the `--builder-proposals` flag, the validator client will ask for blinded blocks for all validators it manages. | ||
In order to configure whether a validator queries for blinded blocks check out [this section.](#validator-client-configuration) | ||
|
||
## Multiple builders | ||
|
||
Run MEV-boost to multiplex builder connections. | ||
Lighthouse currently only supports a connection to a single builder. If you'd like to connect to multiple builders or | ||
relays, run one of the following services and configure lighthouse to use it with the `--builder` flag. | ||
|
||
* [`mev-boost`][mev-boost] | ||
* [`mev-rs`][mev-rs] | ||
|
||
## Fallback to local | ||
## Validator Client Configuration | ||
|
||
- `--builder-fallback-skips` | ||
- `--builder-fallback-skips-per-epoch` | ||
- `--builder-fallback-epochs-since-finalization` | ||
- `--builder-fallback-disable-checks` | ||
In the validator client, you can configure gas limit, fee recipient, and whether to use the builder API on a | ||
per-validator basis or set a configuration for all validators managed by the validator client. CLI flags for each of these | ||
will serve as default values for all validators managed by the validator client. In order to manage the values | ||
per-validator you can either make updates to the `validator_definitions.yml` file or you can use the HTTP requests | ||
described below. | ||
|
||
Both the gas limit and fee recipient will be passed along as suggestions to connected builders but if there is a discrepancy | ||
in either, it will *not* keep you from proposing a block with the builder. This is because the bounds on gas limit are calculated based | ||
on prior execution blocks, so it should be managed by an execution engine, even if it is external. Depending on the | ||
connected relay, payment to the proposer might be in the form of a transaction within the block to the fee recipient, | ||
so a discrepancy in fee recipient might not indicate that there is something afoot. If you know the relay you are connected to *should* | ||
only create blocks with a `fee_recipient` field matching the one suggested, you can use | ||
the [strict fee recipient](suggested-fee-recipient.md#strict-fee-recipient) flag. | ||
|
||
### Enable/Disable builder proposals and set Gas Limit | ||
Use the [lighthouse API](api-vc-endpoints.md) to configure these fields per-validator. | ||
|
||
#### `PATCH /lighthouse/validators/:voting_pubkey` | ||
|
||
[mev-rs]: https://github.com/ralexstokes/mev-rs | ||
[mev-boost]: https://github.com/flashbots/mev-boost | ||
|
||
## Per-validator configuration | ||
#### HTTP Specification | ||
|
||
Refer to [fee recipient documentation](suggested-fee-recipient) | ||
| Property | Specification | | ||
|-------------------|--------------------------------------------| | ||
| Path | `/lighthouse/validators/:voting_pubkey` | | ||
| Method | PATCH | | ||
| Required Headers | [`Authorization`](./api-vc-auth-header.md) | | ||
| Typical Responses | 200, 400 | | ||
|
||
//TODO(sean): add docs about the strict fee recipient flag | ||
#### Example Path | ||
|
||
## Gas Limit | ||
``` | ||
localhost:5062/lighthouse/validators/0xb0148e6348264131bf47bcd1829590e870c836dc893050fd0dadc7a28949f9d0a72f2805d027521b45441101f0cc1cde | ||
``` | ||
|
||
#### Example Request Body | ||
Each field is optional. | ||
```json | ||
{ | ||
"builder_proposals": true, | ||
"gas_limit": 3000000001 | ||
} | ||
``` | ||
|
||
#### Example Response Body | ||
|
||
```json | ||
null | ||
``` | ||
### Fee Recipient | ||
|
||
Refer to [suggested fee recipient](suggested-fee-recipient.md) documentation. | ||
|
||
### Validator definitions example | ||
``` | ||
--- | ||
- enabled: true | ||
voting_public_key: "0x87a580d31d7bc69069b55f5a01995a610dd391a26dc9e36e81057a17211983a79266800ab8531f21f1083d7d84085007" | ||
type: local_keystore | ||
voting_keystore_path: /home/paul/.lighthouse/validators/0x87a580d31d7bc69069b55f5a01995a610dd391a26dc9e36e81057a17211983a79266800ab8531f21f1083d7d84085007/voting-keystore.json | ||
voting_keystore_password_path: /home/paul/.lighthouse/secrets/0x87a580d31d7bc69069b55f5a01995a610dd391a26dc9e36e81057a17211983a79266800ab8531f21f1083d7d84085007 | ||
suggested_fee_recipient: "0x6cc8dcbca744a6e4ffedb98e1d0df903b10abd21" | ||
gas_limit: 3000000001 | ||
builder_proposals: true | ||
- enabled: false | ||
voting_public_key: "0xa5566f9ec3c6e1fdf362634ebec9ef7aceb0e460e5079714808388e5d48f4ae1e12897fed1bea951c17fa389d511e477" | ||
type: local_keystore voting_keystore_path: /home/paul/.lighthouse/validators/0xa5566f9ec3c6e1fdf362634ebec9ef7aceb0e460e5079714808388e5d48f4ae1e12897fed1bea951c17fa389d511e477/voting-keystore.json | ||
voting_keystore_password: myStrongpa55word123&$ | ||
suggested_fee_recipient: "0xa2e334e71511686bcfe38bb3ee1ad8f6babcc03d" | ||
gas_limit: 333333333 | ||
builder_proposals: true | ||
``` | ||
|
||
## Circuit breaker conditions | ||
|
||
By outsourcing payload construction and signing blocks without verifying transactions, we are creating a new risk to | ||
live-ness. If most of the network is using a small set of relays and one is bugged, a string of missed proposals could | ||
happen quickly. This is not only generally bad for the network, but if you have a proposal coming up, you might not | ||
realize that your next proposal is likely to be missed until it's too late. So we've implemented some "chain health" | ||
checks to try and avoid scenarios like this. | ||
|
||
By default, Lighthouse is strict with these conditions, but we encourage users to learn about and adjust them. | ||
|
||
- `--builder-fallback-skips` - If we've seen this number of skip slots in a row prior to proposing, we will NOT query | ||
any connected builders, and will use the local execution engine for payload construction. | ||
- `--builder-fallback-skips-per-epoch` - If we've seen this number of skip slots in the past `SLOTS_PER_EPOCH`, we will NOT | ||
query any connected builders, and will use the local execution engine for payload construction. | ||
- `--builder-fallback-epochs-since-finalization` - If we're proposing and the chain has not finalized within | ||
this number of epochs, we will NOT query any connected builders, and will use the local execution engine for payload | ||
construction. Setting this value to anything less than 2 will cause the node to NEVER query connected builders. Setting | ||
it to 2 will cause this condition to be hit if there are skips slots at the start of an epoch, right before this node | ||
is set to propose. | ||
- `--builder-fallback-disable-checks` - This flag disables all checks related to chain health. This means the builder | ||
API will always be used for payload construction, regardless of recent chain conditions. | ||
|
||
[mev-rs]: https://github.com/ralexstokes/mev-rs | ||
[mev-boost]: https://github.com/flashbots/mev-boost |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters