gnosis/lighthouse
1
0
Fork 0
mirror of https://github.com/sigp/lighthouse.git synced 2026-04-17 04:48:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

Builder Specs v0.2.0 (#3134)

Browse Source 
## Issue Addressed

https://github.com/sigp/lighthouse/issues/3091

Extends https://github.com/sigp/lighthouse/pull/3062, adding pre-bellatrix block support on blinded endpoints and allowing the normal proposal flow (local payload construction) on blinded endpoints. This resulted in better fallback logic because the VC will not have to switch endpoints on failure in the BN <> Builder API, the BN can just fallback immediately and without repeating block processing that it shouldn't need to. We can also keep VC fallback from the VC<>BN API's blinded endpoint to full endpoint.

## Proposed Changes

- Pre-bellatrix blocks on blinded endpoints
- Add a new `PayloadCache` to the execution layer
- Better fallback-from-builder logic

## Todos

- [x] Remove VC transition logic
- [x] Add logic to only enable builder flow after Merge transition finalization
- [x] Tests
- [x] Fix metrics
- [x] Rustdocs


Co-authored-by: Mac L <mjladson@pm.me>
Co-authored-by: realbigsean <sean@sigmaprime.io>
This commit is contained in:
realbigsean
2022-07-30 00:22:37 +00:00
parent 25f0e261cb
commit 6c2d8b2262
61 changed files with 3522 additions and 687 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
book/src/SUMMARY.md
View File

@@ -18,21 +18,21 @@
* [Create a validator](./validator-create.md)
* [Key recovery](./key-recovery.md)
* [Validator Management](./validator-management.md)
* [Importing from the Staking Launchpad](./validator-import-launchpad.md)
* [Importing from the Staking Launchpad](./validator-import-launchpad.md)
* [Slashing Protection](./slashing-protection.md)
* [Voluntary Exits](./voluntary-exit.md)
* [Validator Monitoring](./validator-monitoring.md)
* [Doppelganger Protection](./validator-doppelganger.md)
* [Suggested Fee Recipient](./suggested-fee-recipient.md)
* [APIs](./api.md)
* [Beacon Node API](./api-bn.md)
* [/lighthouse](./api-lighthouse.md)
* [Validator Inclusion APIs](./validator-inclusion.md)
* [Validator Client API](./api-vc.md)
* [Endpoints](./api-vc-endpoints.md)
* [Authorization Header](./api-vc-auth-header.md)
* [Signature Header](./api-vc-sig-header.md)
* [Prometheus Metrics](./advanced_metrics.md)
* [Beacon Node API](./api-bn.md)
* [/lighthouse](./api-lighthouse.md)
* [Validator Inclusion APIs](./validator-inclusion.md)
* [Validator Client API](./api-vc.md)
* [Endpoints](./api-vc-endpoints.md)
* [Authorization Header](./api-vc-auth-header.md)
* [Signature Header](./api-vc-sig-header.md)
* [Prometheus Metrics](./advanced_metrics.md)
* [Advanced Usage](./advanced.md)
* [Checkpoint Sync](./checkpoint-sync.md)
* [Custom Data Directories](./advanced-datadir.md)
@@ -45,6 +45,7 @@
* [Redundancy](./redundancy.md)
* [Pre-Releases](./advanced-pre-releases.md)
* [Release Candidates](./advanced-release-candidates.md)
* [MEV and Lighthouse](./builders.md)
* [Contributing](./contributing.md)
* [Development Environment](./setup.md)
* [Development Environment](./setup.md)
* [FAQs](./faq.md)

144
book/src/builders.md Normal file
View File

@@ -0,0 +1,144 @@
# MEV and Lighthouse
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. For
economic reasons, these parties will refuse to reveal the list of transactions to the validator
before the validator has committed to (i.e. signed) the block. A primer on MEV can be found
[here]([MEV](https://ethereum.org/en/developers/docs/mev/)).
Using the builder API is not known to introduce additional slashing risks, however a live-ness risk
(i.e. the ability for the chain to produce valid blocks) is introduced because your node will be
signing blocks without executing the transactions within the block. Therefore it won't know whether
the transactions are valid and it may sign a block that the network will reject. This would lead to
a missed proposal and 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.
```
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 with stubbed-out transactions. 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
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]
## Validator Client Configuration
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. 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`
#### HTTP Specification
| Property | Specification |
|-------------------|--------------------------------------------|
| Path | `/lighthouse/validators/:voting_pubkey` |
| Method | PATCH |
| Required Headers | [`Authorization`](./api-vc-auth-header.md) |
| Typical Responses | 200, 400 |
#### Example Path
```
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 on the canonical chain 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 on the canonical chain 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

18
book/src/suggested-fee-recipient.md
View File

@@ -30,6 +30,15 @@ Assuming trustworthy nodes, the priority for the four methods is:
1. `--suggested-fee-recipient` provided to the VC.
1. `--suggested-fee-recipient` provided to the BN.
## Strict Fee Recipient
If the flag `--strict-fee-recipient` is set in the validator client, Lighthouse will refuse to sign any block whose
`fee_recipient` does not match the `suggested_fee_recipient` sent by this validator. This applies to both the normal
block proposal flow and block proposals through the builder API. Proposals through the builder API are more likely
to have a discrepancy in `fee_recipient` so you should be aware of how your connected relay sends proposer payments before
using this flag. If this flag is used, a fee recipient mismatch in the builder API flow will result in a fallback to the
local execution engine for payload construction, where a strict fee recipient check will still be applied.
### 1. Setting the fee recipient in the `validator_definitions.yml`
Users can set the fee recipient in `validator_definitions.yml` with the `suggested_fee_recipient`
@@ -62,15 +71,6 @@ validators where a `suggested_fee_recipient` is not loaded from another method.
The `--suggested-fee-recipient` can be provided to the BN to act as a default value when the
validator client does not transmit a `suggested_fee_recipient` to the BN.
## Strict Fee Recipient
If the flag `--strict-fee-recipient` is set in the validator client, Lighthouse will refuse to sign any block whose
`fee_recipient` does not match the `suggested_fee_recipient` sent by this validator. This applies to both the normal
block proposal flow, as well as block proposals through the builder API. Proposals through the builder API are more likely
to have a discrepancy in `fee_recipient` so you should be aware of how your connected relay sends proposer payments before
using this flag. If this flag is used, a fee recipient mismatch in the builder API flow will result in a fallback to the
local execution engine for payload construction, where a strict fee recipient check will still be applied.
## Setting the fee recipient dynamically using the keymanager API
When the [validator client API](api-vc.md) is enabled, the