status-im
/
nimbus-eth2
mirror of https://github.com/status-im/nimbus-eth2.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

document LC data serving options (#3922) 

Adds a documentation page for configuring LC data serving.
This commit is contained in:
Etan Kissling 2022-08-02 14:23:03 +02:00 committed by GitHub
parent 2240594ed8
commit 9c6a4316aa
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 53 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
beacon_chain/conf.nim
View File

@ -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* {.

2
beacon_chain/conf_light_client.nim
View File

@ -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* {.

8
beacon_chain/consensus_object_pools/block_pools_types_light_client.nim
View File

@ -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].}

1
docs/the_nimbus_book/mkdocs.yml
View File

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

24
docs/the_nimbus_book/src/el-light-client.md
View File

@ -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

3
docs/the_nimbus_book/src/keymanager-api.md
View File

@ -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

19
docs/the_nimbus_book/src/light-client-data.md Normal file
View File

@ -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.

12
docs/the_nimbus_book/src/options.md
View File

@ -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|<path>) [=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:<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.
...
```

2
scripts/test_merge_node.nim
View File

@ -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

2
scripts/test_merge_vectors.nim
View File

@ -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