document LC data serving options (#3922)

Adds a documentation page for configuring LC data serving.

beacon_chain/conf.nim

@@ -210,7 +210,7 @@ type
 
     # https://github.com/ethereum/execution-apis/blob/v1.0.0-alpha.9/src/engine/authentication.md#key-distribution
     jwtSecret* {.
-      desc: "A file containing the hex-encoded 256 bit secret key to be used for verifying/generating jwt tokens"
+      desc: "A file containing the hex-encoded 256 bit secret key to be used for verifying/generating JWT tokens"
       name: "jwt-secret" .}: Option[string]
 
     case cmd* {.
@@ -467,6 +467,7 @@ type
         desc: "Which classes of light client data to import. " &
               "Must be one of: none, only-new, full (slow startup), on-demand (may miss validator duties)"
         defaultValue: LightClientDataImportMode.OnlyNew
+        defaultValueDesc: $LightClientDataImportMode.OnlyNew
         name: "light-client-data-import-mode" .}: LightClientDataImportMode
 
       lightClientDataMaxPeriods* {.

beacon_chain/conf_light_client.nim

@@ -133,7 +133,7 @@ type LightClientConf* = object
     name: "web3-url" .}: seq[string]
 
   jwtSecret* {.
-    desc: "A file containing the hex-encoded 256 bit secret key to be used for verifying/generating jwt tokens"
+    desc: "A file containing the hex-encoded 256 bit secret key to be used for verifying/generating JWT tokens"
     name: "jwt-secret" .}: Option[string]
 
   safeSlotsToImportOptimistically* {.

beacon_chain/consensus_object_pools/block_pools_types_light_client.nim

@@ -23,13 +23,13 @@ type
   LightClientDataImportMode* {.pure.} = enum
     ## Controls which classes of light client data are imported.
     None = "none"
-      ## Import no light client data.
+      ## Do not import new light client data.
     OnlyNew = "only-new"
-      ## Import only new light client data.
+      ## Incrementally import new light client data.
     Full = "full"
-      ## Import light client data for entire weak subjectivity period.
+      ## Import historic light client data (slow startup).
     OnDemand = "on-demand"
-      ## Don't precompute historic data. Slow, may miss validator duties.
+      ## Like `full`, but import on demand instead of on start.
 
   OnLightClientFinalityUpdateCallback* =
     proc(data: altair.LightClientFinalityUpdate) {.gcsafe, raises: [Defect].}

docs/the_nimbus_book/mkdocs.yml

@@ -103,6 +103,7 @@ nav:
     - 'keymanager-api.md'
     - 'data-dir.md'
     - 'migration-options.md'
+    - 'light-client-data.md'
     - 'troubleshooting.md'
     - 'developers.md'
     - 'contribute.md'

docs/the_nimbus_book/src/el-light-client.md

@@ -1,9 +1,9 @@
 # Light client based EL sync
 
-Execution layer (EL) implementations provide the [web3 API](https://ethereum.github.io/execution-apis/api-documentation/) to expose information stored on the Ethereum blockchain. With [the merge 🐼](./merge.md), EL's can no longer run standalone and require an external component to determine the latest state to sync to.
+Execution layer (EL) clients provide the [web3 API](https://ethereum.github.io/execution-apis/api-documentation/) to expose information stored on the Ethereum blockchain. With [the merge 🐼](./merge.md), EL clients can no longer run standalone and require an external component to determine the latest state to sync to.
 
 !!! warning
-    It is recommended to pair the EL with a consensus layer (CL) full node. To use Nimbus, follow the [installation instructions](./install.md).
+    It is recommended to pair the EL client with a consensus layer (CL) full node. To use Nimbus, follow the [installation instructions](./install.md).
 
 In environments where running a full node is not feasible, a light client may be used instead. Light clients delegate full validation to other network participants and operate under a honest supermajority (> 2/3) assumption among elected participants. Due to this delegation, light clients are typically behind by ~4/3 slots (~15 seconds on Ethereum mainnet). On the other hand, light clients do not require storing a big database and need much less bandwith and compute power to stay in sync with the Ethereum network.
 
@@ -31,9 +31,9 @@ make -j4 nimbus_light_client
 
 This may take a few minutes. When the process finishes, the `nimbus_light_client` executable can be found in the `build` subdirectory.
 
-## Pairing with the EL
+## Pairing with the EL client
 
-To ensure that only the light client can control the EL, a file with random content (JWT secret) must be created. The format is 64 hexadecimal (0-9, a-f) characters. To create one, the following command may be used:
+To ensure that only the light client can control the EL client, a file with random content (JWT secret) must be created. The format is 64 hexadecimal (0-9, a-f) characters. To create one, the following command may be used:
 
 ```sh
 openssl rand -hex 32 | tr -d "\n" > "$HOME/jwtsecret"
@@ -42,11 +42,11 @@ openssl rand -hex 32 | tr -d "\n" > "$HOME/jwtsecret"
 !!! tip
     To adjust where the file is created, adjust the `$HOME/jwtsecret` portion in the command above. Also adjust other commands in this guide accordingly.
 
-The JWT secret must be passed to both the EL and the light client to complete the pairing.
+The JWT secret must be passed to both the EL client and the light client to complete the pairing.
 
-## Running the EL
+## Running the EL client
 
-In addition to the [regular instructions](./eth1.md) to run an EL, the JWT secret must be configured. The following sections explain how to do this for certain EL implementations.
+In addition to the [regular instructions](./eth1.md) to run an EL client, the JWT secret must be configured. The following sections explain how to do this for certain EL clients.
 
 ### Geth
 
@@ -74,7 +74,7 @@ In addition to the [regular instructions](./eth1.md) to run an EL, the JWT secre
 
 ### Others
 
-Please consult your EL's documentation for instructions on how to configure the JWT secret and running the EL.
+Please consult your EL client's documentation for instructions on how to configure the JWT secret and running the EL client.
 
 ## Running the light client
 
@@ -96,7 +96,7 @@ A block root may be obtained from another trusted beacon node, or from a trusted
     On the [beaconcha.in](https://beaconcha.in) website ([Goerli](https://prater.beaconcha.in)), navigate to the `Epochs` section and select a recent `Finalized` epoch. Then, scroll down to the bottom of the page. If the bottom-most slot has a `Proposed` status, copy its `Root Hash`. Otherwise, for example if the bottom-most slot was `Missed`, go back and pick a different epoch.
 
 !!! warning
-    Selecting a block root from an untrusted source or using an outdated block root may lead to the light client syncing to an unexpected state. If that happens, stop the light client and restart it with a new trusted block root. Depending on the EL, its database must be deleted and sync restarted from scratch.
+    Selecting a block root from an untrusted source or using an outdated block root may lead to the light client syncing to an unexpected state. If that happens, stop the light client and restart it with a new trusted block root. Depending on the EL client, its database must be deleted and sync restarted from scratch.
 
 2. Starting the light client
 
@@ -123,7 +123,7 @@ To start the light client, run the following commands (inserting your own truste
 
 ## Observing the sync process
 
-After a while, the light client will pick up beacon block headers from the Ethereum network and start informing the EL about the latest data. You should see logs similar to the following:
+After a while, the light client will pick up beacon block headers from the Ethereum network and start informing the EL client about the latest data. You should see logs similar to the following:
 
 ### Nimbus
 
@@ -145,7 +145,7 @@ NOT 2022-07-24 22:09:05.069+02:00 New LC optimistic block                    opt
 ```
 
 !!! note
-    The [light client protocol](https://github.com/ethereum/consensus-specs/blob/dev/specs/altair/light-client/sync-protocol.md) depends on consensus layer (CL) implementations to serve additional data. As this is a new protocol, not all implementations are supporting it yet. Therefore, it may take several minutes to discover supporting peers, during which no log messages may be produced.
+    The [light client protocol](https://github.com/ethereum/consensus-specs/blob/dev/specs/altair/light-client/sync-protocol.md) depends on consensus layer (CL) full nodes to serve additional data. As this is a new protocol, not all implementations are supporting it yet. Therefore, it may take several minutes to discover supporting peers, during which no log messages may be produced.
 
 ### Geth
 
@@ -154,7 +154,7 @@ WARN [07-24|22:19:16.777] Ignoring payload with missing parent     number=12,658
 INFO [07-24|22:19:16.778] Forkchoice requested sync to new head    number=12,658,012 hash=306fad..bdfd44
 INFO [07-24|22:19:17.232] Syncing beacon headers                   downloaded=7168 left=12,650,843 eta=13m21.441s
 INFO [07-24|22:19:21.626] Syncing beacon headers                   downloaded=75201 left=0          eta=0s
-INFO [07-24|22:19:21.627] Block synchronisation started 
+INFO [07-24|22:19:21.627] Block synchronisation started
 ```
 
 ### Nethermind

docs/the_nimbus_book/src/keymanager-api.md

@@ -23,7 +23,8 @@ All requests must be authorized through the `Authorization: Bearer` scheme with
 ### Enabling connections from outside machines
 By default, only connections from the same machine are entertained. If you wish to change this you can configure the port and listening address with the `--keymanager-port` and `--keymanager-address` options respectively.
 
-> ⚠️ The Keymanager API port should only be exposed through a secure channel (e.g. HTTPS, an SSH tunnel, a VPN, etc.)
+!!! warning
+    The Keymanager API port should only be exposed through a secure channel (e.g. HTTPS, an SSH tunnel, a VPN, etc.)
 
 ## Specification
 

docs/the_nimbus_book/src/light-client-data.md

@@ -0,0 +1,19 @@
+# Light client data (advanced)
+
+Nimbus is configured by default to serve data that allows light clients to stay in sync with the Ethereum network. Light client data is imported incrementally and does not affect validator performance. Information about the light client sync protocol can be found in the [Ethereum consensus specs](https://github.com/ethereum/consensus-specs/blob/dev/specs/altair/light-client/sync-protocol.md).
+
+!!! note
+    Nimbus also implements a [standalone light client](./el-light-client.md) that may be used to sync an execution layer (EL) client.
+
+## Configuration
+
+The following [configuration options](./options.md) adjust the import and serving of light client data:
+
+| Option                                         | Description |
+|------------------------------------------------|-------------|
+| <nobr>`--light-client-data-serve`</nobr>       | <ul><li>`false`: Disable light client data serving</li><li>`true` (default): Provide imported light client data to others</li></ul> |
+| <nobr>`--light-client-data-import-mode`</nobr> | <ul><li>`none`: Do not import new light client data</li><li>`only-new` (default): Incrementally import new light client data</li><li>`full`: Import historic light client data (slow startup)</li><li>`on-demand`: Like `full`, but import on demand instead of on start</li></ul> |
+| <nobr>`--light-client-data-max-periods`</nobr> | <ul><li>Controls the maximum number of sync committee periods to retain light client data</li><li>When unspecified (default), light client data is retained based on [`MIN_EPOCHS_FOR_BLOCK_REQUESTS`](https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/p2p-interface.md#configuration) (129 sync committee periods, ~5 months on Ethereum mainnet)</li></ul> |
+
+!!! warning
+    Setting `--light-client-data-import-mode` to `full` or `on-demand` imports historic light client data which is computationally expensive. While importing historic light client data, validator duties may be missed.

docs/the_nimbus_book/src/options.md

@@ -34,20 +34,23 @@ The following options are available:
      --validators-dir          A directory containing validator keystores.
      --secrets-dir             A directory containing validator keystore passwords.
      --wallets-dir             A directory containing wallet files.
-     --web3-url                One or more Web3 provider URLs used for obtaining deposit contract data.
+     --web3-url                One or more execution layer Web3 provider URLs.
      --non-interactive         Do not display interative prompts. Quit on missing configuration.
      --netkey-file             Source of network (secp256k1) private key file (random|<path>) [=random].
      --insecure-netkey-password  Use pre-generated INSECURE password for network private key file [=false].
      --agent-string            Node agent string which is used as identifier in network [=nimbus].
      --subscribe-all-subnets   Subscribe to all subnet topics when gossiping [=false].
      --num-threads             Number of worker threads ("0" = use as many threads as there are CPU cores
                                available) [=0].
+     --jwt-secret              A file containing the hex-encoded 256 bit secret key to be used for
+                               verifying/generating JWT tokens.
  -b, --bootstrap-node          Specifies one or more bootstrap nodes to use when connecting to the network.
      --bootstrap-file          Specifies a line-delimited file of bootstrap Ethereum network addresses.
      --listen-address          Listening address for the Ethereum LibP2P and Discovery v5 traffic [=0.0.0.0].
      --tcp-port                Listening TCP port for Ethereum LibP2P traffic [=9000].
      --udp-port                Listening UDP port for node discovery [=9000].
-     --max-peers               The maximum number of peers to connect to [=160].
+     --max-peers               The target number of peers to connect to [=160].
+     --hard-max-peers          The maximum number of peers to connect to. Defaults to maxPeers * 1.5.
      --nat                     Specify method to use for determining public address. Must be one of: any, none,
                                upnp, pmp, extip:<IP> [=any].
      --enr-auto-update         Discovery can automatically update its ENR with the IP address and UDP port as
@@ -85,6 +88,10 @@ The following options are available:
                                CORS-enabled clients such as browsers).
      --keymanager-token-file   A file specifying the authorization token required for accessing the keymanager
                                API.
+     --light-client-data-serve  Serve data for enabling light clients to stay in sync with the network [=true].
+     --light-client-data-import-mode  Which classes of light client data to import. Must be one of: none, only-new,
+                               full (slow startup), on-demand (may miss validator duties) [=only-new].
+     --light-client-data-max-periods  Maximum number of sync committee periods to retain light client data.
      --in-process-validators   Disable the push model (the beacon node tells a signing process with the private
                                keys of the validators what to sign and when) and load the validators in the
                                beacon node itself [=true].
@@ -103,6 +110,7 @@ The following options are available:
                                enabled (BETA).
      --validator-monitor-totals  Publish metrics to single 'totals' label for better collection performance when
                                monitoring many validators (BETA) [=false].
+     --suggested-fee-recipient  Suggested fee recipient.
 
 ...
 ```

scripts/test_merge_node.nim

@@ -26,7 +26,7 @@ from ../beacon_chain/networking/network_metadata import Eth1Network
 from ../beacon_chain/spec/datatypes/base import ZERO_HASH
 from ../beacon_chain/spec/presets import Eth1Address, defaultRuntimeConfig
 
-# TODO factor this out and have a version with the result of the jwt secret
+# TODO factor this out and have a version with the result of the JWT secret
 # slurp for testing purposes
 proc readJwtSecret(jwtSecretFile: string): Result[seq[byte], cstring] =
   # https://github.com/ethereum/execution-apis/blob/v1.0.0-alpha.9/src/engine/authentication.md#key-distribution

scripts/test_merge_vectors.nim

@@ -26,7 +26,7 @@ else:
   {.push raises: [].}
 
 # TODO hm, actually factor this out into a callable function
-# and have a version with the result of the jwt secret slurp for testing purposes
+# and have a version with the result of the JWT secret slurp for testing purposes
 proc readJwtSecret(jwtSecretFile: string): Result[seq[byte], cstring] =
   # https://github.com/ethereum/execution-apis/blob/v1.0.0-alpha.9/src/engine/authentication.md#key-distribution
   # If such a parameter is given, but the file cannot be read, or does not