diff --git a/beacon_chain/conf.nim b/beacon_chain/conf.nim index d63a92e47c..80cbc456e8 100644 --- a/beacon_chain/conf.nim +++ b/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* {. diff --git a/beacon_chain/conf_light_client.nim b/beacon_chain/conf_light_client.nim index fc74bff08b..5d195336c5 100644 --- a/beacon_chain/conf_light_client.nim +++ b/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* {. diff --git a/beacon_chain/consensus_object_pools/block_pools_types_light_client.nim b/beacon_chain/consensus_object_pools/block_pools_types_light_client.nim index 71c0c8d371..0b783c4320 100644 --- a/beacon_chain/consensus_object_pools/block_pools_types_light_client.nim +++ b/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].} diff --git a/docs/the_nimbus_book/mkdocs.yml b/docs/the_nimbus_book/mkdocs.yml index 89e810acc0..8b7a3d0125 100644 --- a/docs/the_nimbus_book/mkdocs.yml +++ b/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' diff --git a/docs/the_nimbus_book/src/el-light-client.md b/docs/the_nimbus_book/src/el-light-client.md index c89680cd9a..2ac23b8c04 100644 --- a/docs/the_nimbus_book/src/el-light-client.md +++ b/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 diff --git a/docs/the_nimbus_book/src/keymanager-api.md b/docs/the_nimbus_book/src/keymanager-api.md index 0db15ad354..52c4be985f 100644 --- a/docs/the_nimbus_book/src/keymanager-api.md +++ b/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 diff --git a/docs/the_nimbus_book/src/light-client-data.md b/docs/the_nimbus_book/src/light-client-data.md new file mode 100644 index 0000000000..f5ce7adc7b --- /dev/null +++ b/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 | +|------------------------------------------------|-------------| +| `--light-client-data-serve` | | +| `--light-client-data-import-mode` | | +| `--light-client-data-max-periods` | | + +!!! 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. diff --git a/docs/the_nimbus_book/src/options.md b/docs/the_nimbus_book/src/options.md index a21123603b..e437ae0602 100644 --- a/docs/the_nimbus_book/src/options.md +++ b/docs/the_nimbus_book/src/options.md @@ -34,7 +34,7 @@ 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|) [=random]. --insecure-netkey-password Use pre-generated INSECURE password for network private key file [=false]. @@ -42,12 +42,15 @@ The following options are available: --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: [=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. ... ``` diff --git a/scripts/test_merge_node.nim b/scripts/test_merge_node.nim index aa26936170..16f1992297 100644 --- a/scripts/test_merge_node.nim +++ b/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 diff --git a/scripts/test_merge_vectors.nim b/scripts/test_merge_vectors.nim index f81768aaef..70ee2dd139 100644 --- a/scripts/test_merge_vectors.nim +++ b/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