docs

sigp · Jul 29, 2022 · 84e7f53 · 84e7f53
1 parent eda5a5c
commit 84e7f53
Show file tree

Hide file tree

Showing 2 changed files with 120 additions and 25 deletions.
diff --git a/book/src/builders.md b/book/src/builders.md
@@ -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
diff --git a/book/src/suggested-fee-recipient.md b/book/src/suggested-fee-recipient.md
@@ -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