From d9d84242a70138816b35a5a2cc32e1c3e9746e19 Mon Sep 17 00:00:00 2001 From: chonghe <44791194+chong-he@users.noreply.github.com> Date: Thu, 7 Dec 2023 07:39:22 +0800 Subject: [PATCH] CLI in Lighthouse Book (#4571) * Add cli.sh file * update bash script * update Makefile * update * modified test-suite * fix path * Fix cli.sh permissions * update cmd * cli_manual * Revise to update * Update directory in Github * Correct cli.txt directory * test old cli_manual * change exit 1 * Update cli and makefile * Move cli.sh * remove files * fix permission * Indentation and revision * Fixed permission * Create new cli folder * remove dummy * put a dummy file * Revise cli.sh * comment * function * remove vm.md * test make cli * test * testing * testing * update * update * test * test * add vm * change back non-debug mode * add exist and update for future debug * revise * remove troubleshooting part * update * add summary.md * test * test * Update Makefile Co-authored-by: Mac L * Update Makefile Co-authored-by: Mac L * Remove help-cli.md and rearrange * Remove help-cli.md * Update scripts/cli.sh Co-authored-by: Mac L * Update scripts/cli.sh Co-authored-by: Mac L * remove maxperf * move then to same line as if * Fix indent and echo file not found * To be explicit in replacing the old file * Add logging when there are changes * Add local variables * spacing * remove cargo fmt * update .md files * Edit exit message to avoid confusion * Remove am and add vm subcommands * Add cargo-fmt * Revise test-suite.yml * Update SUMMARY.md * Add set -e * Add vm * Fix * Add vm * set -e * Remove return 1 and add : * Small revision * Fix typo * Update scripts/cli.sh Co-authored-by: Mac L * Indent * Update scripts/cli.sh Co-authored-by: Mac L * Remove .exe in Windows * Fix period with \. * test * check diff * linux commit * Add cli.sh file * update bash script * update Makefile * update * modified test-suite * fix path * Fix cli.sh permissions * update cmd * cli_manual * Revise to update * Update directory in Github * Correct cli.txt directory * test old cli_manual * change exit 1 * Update cli and makefile * Move cli.sh * remove files * fix permission * Indentation and revision * Fixed permission * Create new cli folder * remove dummy * put a dummy file * Revise cli.sh * comment * function * remove vm.md * test make cli * test * testing * testing * update * update * test * test * add vm * change back non-debug mode * add exist and update for future debug * revise * remove troubleshooting part * update * add summary.md * test * test * Update Makefile Co-authored-by: Mac L * Update Makefile Co-authored-by: Mac L * Remove help-cli.md and rearrange * Remove help-cli.md * Update scripts/cli.sh Co-authored-by: Mac L * Update scripts/cli.sh Co-authored-by: Mac L * remove maxperf * move then to same line as if * Fix indent and echo file not found * To be explicit in replacing the old file * Add logging when there are changes * Add local variables * spacing * remove cargo fmt * Edit exit message to avoid confusion * update .md files * Remove am and add vm subcommands * Add cargo-fmt * Revise test-suite.yml * Update SUMMARY.md * Add set -e * Add vm * Fix * Add vm * set -e * Remove return 1 and add : * Small revision * Fix typo * Update scripts/cli.sh Co-authored-by: Mac L * Indent * Update scripts/cli.sh Co-authored-by: Mac L * Remove .exe in Windows * Fix period with \. * test * check diff * Revert "Merge branch 'book-cli' of https://github.com/chong-he/lighthouse into book-cli" This reverts commit 314005d3f8bc0c13ecfa663ac712b1a2bae17540, reversing changes made to a007f613786221211051394fad76ee1f5d0fe0f5. * update * update * Remove echo diff * Dockerize * Remove `-ti` * take ownership inside container * fix mistake * proper escaping, restore ownership afterwards * try without taking ownership of repo * update * add diff for troubleshooting * binary * update using linux * binary * make file * remove diff * add diff * update progressive balance help text * Remove diff --------- Co-authored-by: Mac L Co-authored-by: antondlr --- .github/workflows/test-suite.yml | 12 + Makefile | 8 +- book/src/SUMMARY.md | 7 + book/src/help_bn.md | 514 +++++++++++++++++++++++++++++++ book/src/help_general.md | 107 +++++++ book/src/help_vc.md | 202 ++++++++++++ book/src/help_vm.md | 97 ++++++ book/src/help_vm_create.md | 129 ++++++++ book/src/help_vm_import.md | 101 ++++++ book/src/help_vm_move.md | 112 +++++++ scripts/cli.sh | 98 ++++++ 11 files changed, 1386 insertions(+), 1 deletion(-) create mode 100644 book/src/help_bn.md create mode 100644 book/src/help_general.md create mode 100644 book/src/help_vc.md create mode 100644 book/src/help_vm.md create mode 100644 book/src/help_vm_create.md create mode 100644 book/src/help_vm_import.md create mode 100644 book/src/help_vm_move.md create mode 100755 scripts/cli.sh diff --git a/.github/workflows/test-suite.yml b/.github/workflows/test-suite.yml index 69fb0969c2..0a1499340d 100644 --- a/.github/workflows/test-suite.yml +++ b/.github/workflows/test-suite.yml @@ -411,3 +411,15 @@ jobs: run: rustup override set beta - name: Run make run: make + cli-check: + name: cli-check + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Get latest version of stable Rust + uses: moonrepo/setup-rust@v1 + with: + channel: stable + cache-target: release + - name: Run Makefile to trigger the bash script + run: make cli diff --git a/Makefile b/Makefile index 19988fc2c6..c1190ac98c 100644 --- a/Makefile +++ b/Makefile @@ -175,7 +175,7 @@ test-network-%: env FORK_NAME=$* cargo nextest run --release \ --features "fork_from_env,$(TEST_FEATURES)" \ -p network - + # Run the tests in the `slasher` crate for all supported database backends. test-slasher: cargo nextest run --release -p slasher --features "lmdb,$(TEST_FEATURES)" @@ -200,6 +200,12 @@ test-exec-engine: # test vectors. test: test-release +# Updates the CLI help text pages in the Lighthouse book. +cli: + docker run --rm --user=root \ + -v ${PWD}:/home/runner/actions-runner/lighthouse sigmaprime/github-runner \ + bash -c 'cd lighthouse && make && ./scripts/cli.sh' + # Runs the entire test suite, downloading test vectors if required. test-full: cargo-fmt test-release test-debug test-ef test-exec-engine diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 3f58d8aa45..e323659109 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -53,6 +53,13 @@ * [MEV](./builders.md) * [Merge Migration](./merge-migration.md) * [Late Block Re-orgs](./late-block-re-orgs.md) +* [Built-In Documentation](./help_general.md) + * [Beacon Node](./help_bn.md) + * [Validator Client](./help_vc.md) + * [Validator Manager](./help_vm.md) + * [Create](./help_vm_create.md) + * [Import](./help_vm_import.md) + * [Move](./help_vm_move.md) * [Contributing](./contributing.md) * [Development Environment](./setup.md) * [FAQs](./faq.md) diff --git a/book/src/help_bn.md b/book/src/help_bn.md new file mode 100644 index 0000000000..2a08f90174 --- /dev/null +++ b/book/src/help_bn.md @@ -0,0 +1,514 @@ +# Beacon Node + +``` +Sigma Prime +The primary component which connects to the Ethereum 2.0 P2P network and downloads, verifies and stores blocks. Provides +a HTTP API for querying the beacon chain and publishing messages to the network. + +USAGE: + lighthouse beacon_node [FLAGS] [OPTIONS] + +FLAGS: + --always-prefer-builder-payload If set, the beacon node always uses the payload from the builder instead + of the local payload. + --always-prepare-payload Send payload attributes with every fork choice update. This is intended + for use by block builders, relays and developers. You should set a fee + recipient on this BN and also consider adjusting the --prepare-payload- + lookahead flag. + --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. + --compact-db If present, apply compaction to the database on start-up. Use with + caution. It is generally not recommended unless auto-compaction is + disabled. + --disable-backfill-rate-limiting Disable the backfill sync rate-limiting. This allow users to just sync + the entire chain as fast as possible, however it can result in resource + contention which degrades staking performance. Stakers should generally + choose to avoid this flag since backfill sync is not required for + staking. + --disable-deposit-contract-sync Explictly disables syncing of deposit logs from the execution node. This + overrides any previous option that depends on it. Useful if you intend to + run a non-validating beacon node. + -x, --disable-enr-auto-update Discovery automatically updates the nodes local ENR with an external IP + address and port as seen by other peers on the network. This disables + this feature, fixing the ENR's IP/PORT to those specified on boot. + --disable-lock-timeouts Disable the timeouts applied to some internal locks by default. This can + lead to less spurious failures on slow hardware but is considered + experimental as it may obscure performance issues. + --disable-log-timestamp If present, do not include timestamps in logging output. + --disable-malloc-tuning If present, do not configure the system allocator. Providing this flag + will generally increase memory usage, it should only be provided when + debugging specific memory allocation issues. + --disable-optimistic-finalized-sync Force Lighthouse to verify every execution block hash with the execution + client during finalized sync. By default block hashes will be checked in + Lighthouse and only passed to the EL if initial verification fails. + --disable-packet-filter Disables the discovery packet filter. Useful for testing in smaller + networks + --disable-proposer-reorgs Do not attempt to reorg late blocks from other validators when proposing. + --disable-quic Disables the quic transport. The node will rely solely on the TCP + transport for libp2p connections. + --disable-upnp Disables UPnP support. Setting this will prevent Lighthouse from + attempting to automatically establish external port mappings. + --dummy-eth1 If present, uses an eth1 backend that generates static dummy + data.Identical to the method used at the 2019 Canada interop. + --enable-private-discovery Lighthouse by default does not discover private IP addresses. Set this + flag to enable connection attempts to local addresses. + -e, --enr-match Sets the local ENR IP address and port to match those set for lighthouse. + Specifically, the IP address will be the value of --listen-address and + the UDP port will be --discovery-port. + --eth1 If present the node will connect to an eth1 node. This is required for + block production, you must use this flag if you wish to serve a + validator. + --eth1-purge-cache Purges the eth1 block and deposit caches + --genesis-backfill Attempts to download blocks all the way back to genesis when checkpoint + syncing. + --gui Enable the graphical user interface and all its requirements. This + enables --http and --validator-monitor-auto and enables SSE logging. + -h, --help Prints help information + --http Enable the RESTful HTTP API server. Disabled by default. + --http-allow-sync-stalled Forces the HTTP to indicate that the node is synced when sync is actually + stalled. This is useful for very small testnets. TESTING ONLY. DO NOT USE + ON MAINNET. + --http-enable-tls Serves the RESTful HTTP API server over TLS. This feature is currently + experimental. + --import-all-attestations Import and aggregate all attestations, regardless of validator + subscriptions. This will only import attestations from already-subscribed + subnets, use with --subscribe-all-subnets to ensure all attestations are + received for import. + --light-client-server Act as a full node supporting light clients on the p2p network + [experimental] + --log-color Force outputting colors when emitting logs to the terminal. + --logfile-compress If present, compress old log files. This can help reduce the space needed + to store old logs. + --logfile-no-restricted-perms If present, log files will be generated as world-readable meaning they + can be read by any user on the machine. Note that logs can often contain + sensitive information about your validator and so this flag should be + used with caution. For Windows users, the log file permissions will be + inherited from the parent folder. + --metrics Enable the Prometheus metrics HTTP server. Disabled by default. + --private Prevents sending various client identification information. + --proposer-only Sets this beacon node at be a block proposer only node. This will run the + beacon node in a minimal configuration that is sufficient for block + publishing only. This flag should be used for a beacon node being + referenced by validator client using the --proposer-node flag. This + configuration is for enabling more secure setups. + --purge-db If present, the chain database will be deleted. Use with caution. + --reconstruct-historic-states After a checkpoint sync, reconstruct historic states in the database. + This requires syncing all the way back to genesis. + --reset-payload-statuses When present, Lighthouse will forget the payload statuses of any already- + imported blocks. This can assist in the recovery from a consensus + failure caused by the execution layer. + --shutdown-after-sync Shutdown beacon node as soon as sync is completed. Backfill sync will not + be performed before shutdown. + --slasher Run a slasher alongside the beacon node. It is currently only recommended + for expert users because of the immaturity of the slasher UX and the + extra resources required. + --staking Standard option for a staking beacon node. This will enable the HTTP + server on localhost:5052 and import deposit logs from the execution node. + This is equivalent to `--http` on merge-ready networks, or `--http + --eth1` pre-merge + --subscribe-all-subnets Subscribe to all subnets regardless of validator count. This will also + advertise the beacon node as being long-lived subscribed to all subnets. + --validator-monitor-auto Enables the automatic detection and monitoring of validators connected to + the HTTP API and using the subnet subscription endpoint. This generally + has the effect of providing additional logging and metrics for locally + controlled validators. + -V, --version Prints version information + -z, --zero-ports Sets all listening TCP/UDP ports to 0, allowing the OS to choose some + arbitrary free ports. + +OPTIONS: + --auto-compact-db + Enable or disable automatic compaction of the database on finalization. [default: true] + + --beacon-processor-aggregate-batch-size + Specifies the number of gossip aggregate attestations in a signature verification batch. Higher values may + reduce CPU usage in a healthy network while lower values may increase CPU usage in an unhealthy or hostile + network. [default: 64] + --beacon-processor-attestation-batch-size + Specifies the number of gossip attestations in a signature verification batch. Higher values may reduce CPU + usage in a healthy network whilst lower values may increase CPU usage in an unhealthy or hostile network. + [default: 64] + --beacon-processor-max-workers + Specifies the maximum concurrent tasks for the task scheduler. Increasing this value may increase resource + consumption. Reducing the value may result in decreased resource usage and diminished performance. The + default value is the number of logical CPU cores on the host. + --beacon-processor-reprocess-queue-len + Specifies the length of the queue for messages requiring delayed processing. Higher values may prevent + messages from being dropped while lower values may help protect the node from becoming overwhelmed. + [default: 12288] + --beacon-processor-work-queue-len + Specifies the length of the inbound event queue. Higher values may prevent messages from being dropped while + lower values may help protect the node from becoming overwhelmed. [default: 16384] + --blob-prune-margin-epochs + The margin for blob pruning in epochs. The oldest blobs are pruned up until data_availability_boundary - + blob_prune_margin_epochs. [default: 0] + --blobs-dir + Data directory for the blobs database. + + --block-cache-size + Specifies how many blocks the database should cache in memory [default: 5] + + --boot-nodes + One or more comma-delimited base64-encoded ENR's to bootstrap the p2p network. Multiaddr is also supported. + + --builder + The URL of a service compatible with the MEV-boost API. + + --builder-fallback-epochs-since-finalization + If this node is proposing a block and the chain has not finalized within this number of epochs, it 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. [default: 3] + --builder-fallback-skips + If this node is proposing a block and has seen this number of skip slots on the canonical chain in a row, it + will NOT query any connected builders, and will use the local execution engine for payload construction. + [default: 3] + --builder-fallback-skips-per-epoch + If this node is proposing a block and has seen this number of skip slots on the canonical chain in the past + `SLOTS_PER_EPOCH`, it will NOT query any connected builders, and will use the local execution engine for + payload construction. [default: 8] + --builder-profit-threshold + The minimum reward in wei provided to the proposer by a block builder for an external payload to be + considered for inclusion in a proposal. If this threshold is not met, the local EE's payload will be used. + This is currently *NOT* in comparison to the value of the local EE's payload. It simply checks whether the + total proposer reward from an external payload is equal to or greater than this value. In the future, a + comparison to a local payload is likely to be added. Example: Use 250000000000000000 to set the threshold to + 0.25 ETH. [default: 0] + --builder-user-agent + The HTTP user agent to send alongside requests to the builder URL. The default is Lighthouse's version + string. + --checkpoint-block + Set a checkpoint block to start syncing from. Must be aligned and match --checkpoint-state. Using + --checkpoint-sync-url instead is recommended. + --checkpoint-state + Set a checkpoint state to start syncing from. Must be aligned and match --checkpoint-block. Using + --checkpoint-sync-url instead is recommended. + --checkpoint-sync-url + Set the remote beacon node HTTP endpoint to use for checkpoint sync. + + --checkpoint-sync-url-timeout + Set the timeout for checkpoint sync calls to remote beacon node HTTP endpoint. [default: 180] + + -d, --datadir + Used to specify a custom root data directory for lighthouse keys and databases. Defaults to + $HOME/.lighthouse/{network} where network is the value of the `network` flag Note: Users should specify + separate custom datadirs for different networks. + --debug-level + Specifies the verbosity level used when emitting logs to the terminal. [default: info] [possible values: + info, debug, trace, warn, error, crit] + --discovery-port + The UDP port that discovery will listen on. Defaults to `port` + + --discovery-port6 + The UDP port that discovery will listen on over IPv6 if listening over both IPv4 and IPv6. Defaults to + `port6` + --enr-address
... + The IP address/ DNS address to broadcast to other peers on how to reach this node. If a DNS address is + provided, the enr-address is set to the IP address it resolves to and does not auto-update based on PONG + responses in discovery. Set this only if you are sure other nodes can connect to your local node on this + address. This will update the `ip4` or `ip6` ENR fields accordingly. To update both, set this flag twice + with the different values. + --enr-quic-port + The quic UDP4 port that will be set on the local ENR. Set this only if you are sure other nodes can connect + to your local node on this port over IPv4. + --enr-quic6-port + The quic UDP6 port that will be set on the local ENR. Set this only if you are sure other nodes can connect + to your local node on this port over IPv6. + --enr-tcp-port + The TCP4 port of the local ENR. Set this only if you are sure other nodes can connect to your local node on + this port over IPv4. The --port flag is used if this is not set. + --enr-tcp6-port + The TCP6 port of the local ENR. Set this only if you are sure other nodes can connect to your local node on + this port over IPv6. The --port6 flag is used if this is not set. + --enr-udp-port + The UDP4 port of the local ENR. Set this only if you are sure other nodes can connect to your local node on + this port over IPv4. + --enr-udp6-port + The UDP6 port of the local ENR. Set this only if you are sure other nodes can connect to your local node on + this port over IPv6. + --epochs-per-blob-prune + The epoch interval with which to prune blobs from Lighthouse's database when they are older than the data + availability boundary relative to the current epoch. [default: 1] + --epochs-per-migration + The number of epochs to wait between running the migration of data from the hot DB to the cold DB. Less + frequent runs can be useful for minimizing disk writes [default: 1] + --eth1-blocks-per-log-query + Specifies the number of blocks that a deposit log query should span. This will reduce the size of responses + from the Eth1 endpoint. [default: 1000] + --eth1-cache-follow-distance + Specifies the distance between the Eth1 chain head and the last block which should be imported into the + cache. Setting this value lower can help compensate for irregular Proof-of-Work block times, but setting it + too low can make the node vulnerable to re-orgs. + --execution-endpoint + Server endpoint for an execution layer JWT-authenticated HTTP JSON-RPC connection. Uses the same endpoint to + populate the deposit cache. + --execution-jwt + File path which contains the hex-encoded JWT secret for the execution endpoint provided in the --execution- + endpoint flag. + --execution-jwt-id + Used by the beacon node to communicate a unique identifier to execution nodes during JWT authentication. It + corresponds to the 'id' field in the JWT claims object.Set to empty by default + --execution-jwt-secret-key + Hex-encoded JWT secret for the execution endpoint provided in the --execution-endpoint flag. + + --execution-jwt-version + Used by the beacon node to communicate a client version to execution nodes during JWT authentication. It + corresponds to the 'clv' field in the JWT claims object.Set to empty by default + --execution-timeout-multiplier + Unsigned integer to multiply the default execution timeouts by. [default: 1] + + --fork-choice-before-proposal-timeout + Set the maximum number of milliseconds to wait for fork choice before proposing a block. You can prevent + waiting at all by setting the timeout to 0, however you risk proposing atop the wrong parent block. + [default: 250] + --freezer-dir + Data directory for the freezer database. + + --genesis-state-url + A URL of a beacon-API compatible server from which to download the genesis state. Checkpoint sync server + URLs can generally be used with this flag. If not supplied, a default URL or the --checkpoint-sync-url may + be used. If the genesis state is already included in this binary then this value will be ignored. + --genesis-state-url-timeout + The timeout in seconds for the request to --genesis-state-url. [default: 180] + + --graffiti + Specify your custom graffiti to be included in blocks. Defaults to the current version and commit, truncated + to fit in 32 bytes. + --historic-state-cache-size + Specifies how many states from the freezer database should cache in memory [default: 1] + + --http-address
+ Set the listen address for the RESTful HTTP API server. + + --http-allow-origin + Set the value of the Access-Control-Allow-Origin response HTTP header. Use * to allow any origin (not + recommended in production). If no value is supplied, the CORS allowed origin is set to the listen address of + this server (e.g., http://localhost:5052). + --http-duplicate-block-status + Status code to send when a block that is already known is POSTed to the HTTP API. + + --http-enable-beacon-processor + The beacon processor is a scheduler which provides quality-of-service and DoS protection. When set to + "true", HTTP API requests will be queued and scheduled alongside other tasks. When set to "false", HTTP API + responses will be executed immediately. + --http-port + Set the listen TCP port for the RESTful HTTP API server. + + --http-spec-fork + Serve the spec for a specific hard fork on /eth/v1/config/spec. It should not be necessary to set this flag. + + --http-sse-capacity-multiplier + Multiplier to apply to the length of HTTP server-sent-event (SSE) channels. Increasing this value can + prevent messages from being dropped. + --http-tls-cert + The path of the certificate to be used when serving the HTTP API server over TLS. + + --http-tls-key + The path of the private key to be used when serving the HTTP API server over TLS. Must not be password- + protected. + --ignore-builder-override-suggestion-threshold + When the EE advises Lighthouse to ignore the builder payload, this flag specifies a percentage threshold for + the difference between the reward from the builder payload and the local EE's payload. This threshold must + be met for Lighthouse to consider ignoring the EE's suggestion. If the reward from the builder's payload + doesn't exceed the local payload by at least this percentage, the local payload will be used. The conditions + under which the EE may make this suggestion depend on the EE's implementation, with the primary intent being + to safeguard against potential censorship attacks from builders. Setting this flag to 0 will cause + Lighthouse to always ignore the EE's suggestion. Default: 10.0 (equivalent to 10%). [default: 10.0] + --invalid-gossip-verified-blocks-path + If a block succeeds gossip validation whilst failing full validation, store the block SSZ as a file at this + path. This feature is only recommended for developers. This directory is not pruned, users should be careful + to avoid filling up their disks. + --libp2p-addresses + One or more comma-delimited multiaddrs to manually connect to a libp2p peer without an ENR. + + --listen-address
... + The address lighthouse will listen for UDP and TCP connections. To listen over IpV4 and IpV6 set this flag + twice with the different values. + Examples: + - --listen-address '0.0.0.0' will listen over IPv4. + - --listen-address '::' will listen over IPv6. + - --listen-address '0.0.0.0' --listen-address '::' will listen over both IPv4 and IPv6. The order of the + given addresses is not relevant. However, multiple IPv4, or multiple IPv6 addresses will not be accepted. + [default: 0.0.0.0] + --log-format + Specifies the log format used when emitting logs to the terminal. [possible values: JSON] + + --logfile + File path where the log file will be stored. Once it grows to the value specified in `--logfile-max-size` a + new log file is generated where future logs are stored. Once the number of log files exceeds the value + specified in `--logfile-max-number` the oldest log file will be overwritten. + --logfile-debug-level + The verbosity level used when emitting logs to the log file. [default: debug] [possible values: info, + debug, trace, warn, error, crit] + --logfile-format + Specifies the log format used when emitting logs to the logfile. [possible values: DEFAULT, JSON] + + --logfile-max-number + The maximum number of log files that will be stored. If set to 0, background file logging is disabled. + [default: 5] + --logfile-max-size + The maximum size (in MB) each log file can grow to before rotating. If set to 0, background file logging is + disabled. [default: 200] + --max-skip-slots + Refuse to skip more than this many slots when processing an attestation. This prevents nodes on minority + forks from wasting our time and disk space, but could also cause unnecessary consensus failures, so is + disabled by default. + --metrics-address
+ Set the listen address for the Prometheus metrics HTTP server. + + --metrics-allow-origin + Set the value of the Access-Control-Allow-Origin response HTTP header. Use * to allow any origin (not + recommended in production). If no value is supplied, the CORS allowed origin is set to the listen address of + this server (e.g., http://localhost:5054). + --metrics-port + Set the listen TCP port for the Prometheus metrics HTTP server. + + --monitoring-endpoint
+ Enables the monitoring service for sending system metrics to a remote endpoint. This can be used to monitor + your setup on certain services (e.g. beaconcha.in). This flag sets the endpoint where the beacon node + metrics will be sent. Note: This will send information to a remote sever which may identify and associate + your validators, IP address and other personal information. Always use a HTTPS connection and never provide + an untrusted URL. + --monitoring-endpoint-period + Defines how many seconds to wait between each message sent to the monitoring-endpoint. Default: 60s + + --network + Name of the Eth2 chain Lighthouse will sync and follow. [possible values: mainnet, prater, goerli, gnosis, + chiado, sepolia, holesky] + --network-dir + Data directory for network keys. Defaults to network/ inside the beacon node dir. + + --port + The TCP/UDP ports to listen on. There are two UDP ports. The discovery UDP port will be set to this value + and the Quic UDP port will be set to this value + 1. The discovery port can be modified by the --discovery- + port flag and the quic port can be modified by the --quic-port flag. If listening over both IPv4 + and IPv6 the --port flag will apply to the IPv4 address and --port6 to the IPv6 address. [default: 9000] + --port6 + The TCP/UDP ports to listen on over IPv6 when listening over both IPv4 and IPv6. Defaults to 9090 when + required. The Quic UDP port will be set to this value + 1. [default: 9090] + --prepare-payload-lookahead + The time before the start of a proposal slot at which payload attributes should be sent. Low values are + useful for execution nodes which don't improve their payload after the first call, and high values are + useful for ensuring the EL is given ample notice. Default: 1/3 of a slot. + --progressive-balances + Control the progressive balances cache mode. The default `fast` mode uses the cache to speed up fork choice. + A more conservative `checked` mode compares the cache's results against results without the cache. If there + is a mismatch, it falls back to the cache-free result. Using the default `fast` mode is recommended unless + advised otherwise by the Lighthouse team. [possible values: disabled, checked, strict, fast] + --proposer-reorg-cutoff + Maximum delay after the start of the slot at which to propose a reorging block. Lower values can prevent + failed reorgs by ensuring the block has ample time to propagate and be processed by the network. The default + is 1/12th of a slot (1 second on mainnet) + --proposer-reorg-disallowed-offsets + Comma-separated list of integer offsets which can be used to avoid proposing reorging blocks at certain + slots. An offset of N means that reorging proposals will not be attempted at any slot such that `slot % + SLOTS_PER_EPOCH == N`. By default only re-orgs at offset 0 will be avoided. Any offsets supplied with this + flag will impose additional restrictions. + --proposer-reorg-epochs-since-finalization + Maximum number of epochs since finalization at which proposer reorgs are allowed. Default: 2 + + --proposer-reorg-threshold + Percentage of vote weight below which to attempt a proposer reorg. Default: 20% + + --prune-blobs + Prune blobs from Lighthouse's database when they are older than the data data availability boundary relative + to the current epoch. [default: true] + --prune-payloads + Prune execution payloads from Lighthouse's database. This saves space but imposes load on the execution + client, as payloads need to be reconstructed and sent to syncing peers. [default: true] + --quic-port + The UDP port that quic will listen on. Defaults to `port` + 1 + + --quic-port6 + The UDP port that quic will listen on over IPv6 if listening over both IPv4 and IPv6. Defaults to `port6` + + 1 + --safe-slots-to-import-optimistically + Used to coordinate manual overrides of the SAFE_SLOTS_TO_IMPORT_OPTIMISTICALLY parameter. This flag should + only be used if the user has a clear understanding that the broad Ethereum community has elected to override + this parameter in the event of an attack at the PoS transition block. Incorrect use of this flag can cause + your node to possibly accept an invalid chain or sync more slowly. Be extremely careful with this flag. + --shuffling-cache-size + Some HTTP API requests can be optimised by caching the shufflings at each epoch. This flag allows the user + to set the shuffling cache size in epochs. Shufflings are dependent on validator count and setting this + value to a large number can consume a large amount of memory. + --slasher-att-cache-size + Set the maximum number of attestation roots for the slasher to cache + + --slasher-backend + Set the database backend to be used by the slasher. [possible values: lmdb, disabled] + + --slasher-broadcast + Broadcast slashings found by the slasher to the rest of the network [Enabled by default]. [default: true] + + --slasher-chunk-size + Number of epochs per validator per chunk stored on disk. + + --slasher-dir + Set the slasher's database directory. + + --slasher-history-length + Configure how many epochs of history the slasher keeps. Immutable after initialization. + + --slasher-max-db-size + Maximum size of the MDBX database used by the slasher. + + --slasher-slot-offset + Set the delay from the start of the slot at which the slasher should ingest attestations. Only effective if + the slasher-update-period is a multiple of the slot duration. + --slasher-update-period + Configure how often the slasher runs batch processing. + + --slasher-validator-chunk-size + Number of validators per chunk stored on disk. + + --slots-per-restore-point + Specifies how often a freezer DB restore point should be stored. Cannot be changed after initialization. + [default: 8192 (mainnet) or 64 (minimal)] + --suggested-fee-recipient + Emergency fallback fee recipient for use in case the validator client does not have one configured. You + should set this flag on the validator client instead of (or in addition to) setting it here. + --target-peers + The target number of peers. + + --terminal-block-hash-epoch-override + Used to coordinate manual overrides to the TERMINAL_BLOCK_HASH_ACTIVATION_EPOCH parameter. This flag should + only be used if the user has a clear understanding that the broad Ethereum community has elected to override + the terminal PoW block. Incorrect use of this flag will cause your node to experience a consensus failure. + Be extremely careful with this flag. + --terminal-block-hash-override + Used to coordinate manual overrides to the TERMINAL_BLOCK_HASH parameter. This flag should only be used if + the user has a clear understanding that the broad Ethereum community has elected to override the terminal + PoW block. Incorrect use of this flag will cause your node to experience a consensus failure. Be extremely + careful with this flag. + --terminal-total-difficulty-override + Used to coordinate manual overrides to the TERMINAL_TOTAL_DIFFICULTY parameter. Accepts a 256-bit decimal + integer (not a hex value). This flag should only be used if the user has a clear understanding that the + broad Ethereum community has elected to override the terminal difficulty. Incorrect use of this flag will + cause your node to experience a consensus failure. Be extremely careful with this flag. + -t, --testnet-dir + Path to directory containing eth2_testnet specs. Defaults to a hard-coded Lighthouse testnet. Only effective + if there is no existing database. + --trusted-peers + One or more comma-delimited trusted peer ids which always have the highest score according to the peer + scoring system. + --trusted-setup-file-override + Path to a json file containing the trusted setup params. NOTE: This will override the trusted setup that is + generated from the mainnet kzg ceremony. Use with caution + --validator-monitor-file + As per --validator-monitor-pubkeys, but the comma-separated list is contained within a file at the given + path. + --validator-monitor-individual-tracking-threshold + Once the validator monitor reaches this number of local validators it will stop collecting per-validator + Prometheus metrics and issuing per-validator logs. Instead, it will provide aggregate metrics and logs. This + avoids infeasibly high cardinality in the Prometheus database and high log volume when using many + validators. Defaults to 64. + --validator-monitor-pubkeys + A comma-separated list of 0x-prefixed validator public keys. These validators will receive special + monitoring and additional logging. + --wss-checkpoint + Specify a weak subjectivity checkpoint in `block_root:epoch` format to verify the node's sync against. The + block root should be 0x-prefixed. Note that this flag is for verification only, to perform a checkpoint sync + from a recent state use --checkpoint-sync-url. +``` \ No newline at end of file diff --git a/book/src/help_general.md b/book/src/help_general.md new file mode 100644 index 0000000000..7169884cdc --- /dev/null +++ b/book/src/help_general.md @@ -0,0 +1,107 @@ +# Lighthouse General Commands + +``` +Sigma Prime +Ethereum 2.0 client by Sigma Prime. Provides a full-featured beacon node, a validator client and utilities for managing +validator accounts. + +USAGE: + lighthouse [FLAGS] [OPTIONS] [SUBCOMMAND] + +FLAGS: + --disable-log-timestamp If present, do not include timestamps in logging output. + --disable-malloc-tuning If present, do not configure the system allocator. Providing this flag will + generally increase memory usage, it should only be provided when debugging + specific memory allocation issues. + -l Enables environment logging giving access to sub-protocol logs such as discv5 + and libp2p + -h, --help Prints help information + --log-color Force outputting colors when emitting logs to the terminal. + --logfile-compress If present, compress old log files. This can help reduce the space needed to + store old logs. + --logfile-no-restricted-perms If present, log files will be generated as world-readable meaning they can be + read by any user on the machine. Note that logs can often contain sensitive + information about your validator and so this flag should be used with caution. + For Windows users, the log file permissions will be inherited from the parent + folder. + -V, --version Prints version information + +OPTIONS: + -d, --datadir + Used to specify a custom root data directory for lighthouse keys and databases. Defaults to + $HOME/.lighthouse/{network} where network is the value of the `network` flag Note: Users should specify + separate custom datadirs for different networks. + --debug-level + Specifies the verbosity level used when emitting logs to the terminal. [default: info] [possible values: + info, debug, trace, warn, error, crit] + --genesis-state-url + A URL of a beacon-API compatible server from which to download the genesis state. Checkpoint sync server + URLs can generally be used with this flag. If not supplied, a default URL or the --checkpoint-sync-url may + be used. If the genesis state is already included in this binary then this value will be ignored. + --genesis-state-url-timeout + The timeout in seconds for the request to --genesis-state-url. [default: 180] + + --log-format + Specifies the log format used when emitting logs to the terminal. [possible values: JSON] + + --logfile + File path where the log file will be stored. Once it grows to the value specified in `--logfile-max-size` a + new log file is generated where future logs are stored. Once the number of log files exceeds the value + specified in `--logfile-max-number` the oldest log file will be overwritten. + --logfile-debug-level + The verbosity level used when emitting logs to the log file. [default: debug] [possible values: info, + debug, trace, warn, error, crit] + --logfile-format + Specifies the log format used when emitting logs to the logfile. [possible values: DEFAULT, JSON] + + --logfile-max-number + The maximum number of log files that will be stored. If set to 0, background file logging is disabled. + [default: 5] + --logfile-max-size + The maximum size (in MB) each log file can grow to before rotating. If set to 0, background file logging is + disabled. [default: 200] + --network + Name of the Eth2 chain Lighthouse will sync and follow. [possible values: mainnet, prater, goerli, gnosis, + chiado, sepolia, holesky] + --safe-slots-to-import-optimistically + Used to coordinate manual overrides of the SAFE_SLOTS_TO_IMPORT_OPTIMISTICALLY parameter. This flag should + only be used if the user has a clear understanding that the broad Ethereum community has elected to override + this parameter in the event of an attack at the PoS transition block. Incorrect use of this flag can cause + your node to possibly accept an invalid chain or sync more slowly. Be extremely careful with this flag. + --terminal-block-hash-epoch-override + Used to coordinate manual overrides to the TERMINAL_BLOCK_HASH_ACTIVATION_EPOCH parameter. This flag should + only be used if the user has a clear understanding that the broad Ethereum community has elected to override + the terminal PoW block. Incorrect use of this flag will cause your node to experience a consensus failure. + Be extremely careful with this flag. + --terminal-block-hash-override + Used to coordinate manual overrides to the TERMINAL_BLOCK_HASH parameter. This flag should only be used if + the user has a clear understanding that the broad Ethereum community has elected to override the terminal + PoW block. Incorrect use of this flag will cause your node to experience a consensus failure. Be extremely + careful with this flag. + --terminal-total-difficulty-override + Used to coordinate manual overrides to the TERMINAL_TOTAL_DIFFICULTY parameter. Accepts a 256-bit decimal + integer (not a hex value). This flag should only be used if the user has a clear understanding that the + broad Ethereum community has elected to override the terminal difficulty. Incorrect use of this flag will + cause your node to experience a consensus failure. Be extremely careful with this flag. + -t, --testnet-dir + Path to directory containing eth2_testnet specs. Defaults to a hard-coded Lighthouse testnet. Only effective + if there is no existing database. + +SUBCOMMANDS: + account_manager Utilities for generating and managing Ethereum 2.0 accounts. [aliases: a, am, account, + account_manager] + beacon_node The primary component which connects to the Ethereum 2.0 P2P network and downloads, + verifies and stores blocks. Provides a HTTP API for querying the beacon chain and + publishing messages to the network. [aliases: b, bn, beacon] + boot_node Start a special Lighthouse process that only serves as a discv5 boot-node. This process + will *not* import blocks or perform most typical beacon node functions. Instead, it will + simply run the discv5 service and assist nodes on the network to discover each other. This + is the recommended way to provide a network boot-node since it has a reduced attack surface + compared to a full beacon node. + database_manager Manage a beacon node database [aliases: db] + help Prints this message or the help of the given subcommand(s) + validator_client When connected to a beacon node, performs the duties of a staked validator (e.g., proposing + blocks and attestations). [aliases: v, vc, validator] + validator_manager Utilities for managing a Lighthouse validator client via the HTTP API. [aliases: vm, + validator-manager, validator_manager] +``` \ No newline at end of file diff --git a/book/src/help_vc.md b/book/src/help_vc.md new file mode 100644 index 0000000000..4471b0e104 --- /dev/null +++ b/book/src/help_vc.md @@ -0,0 +1,202 @@ +# Validator Client + +``` +When connected to a beacon node, performs the duties of a staked validator (e.g., proposing blocks and attestations). + +USAGE: + lighthouse validator_client [FLAGS] [OPTIONS] + +FLAGS: + --builder-proposals + If this flag is set, Lighthouse will query the Beacon Node for only block headers during proposals and will + sign over headers. Useful for outsourcing execution payload construction during proposals. + --disable-auto-discover + If present, do not attempt to discover new validators in the validators-dir. Validators will need to be + manually added to the validator_definitions.yml file. + --disable-log-timestamp If present, do not include timestamps in logging output. + --disable-malloc-tuning + If present, do not configure the system allocator. Providing this flag will generally increase memory usage, + it should only be provided when debugging specific memory allocation issues. + --disable-run-on-all + DEPRECATED. Use --broadcast. By default, Lighthouse publishes attestation, sync committee subscriptions and + proposer preparation messages to all beacon nodes provided in the `--beacon-nodes flag`. This option changes + that behaviour such that these api calls only go out to the first available and synced beacon node + --enable-doppelganger-protection + If this flag is set, Lighthouse will delay startup for three epochs and monitor for messages on the network + by any of the validators managed by this client. This will result in three (possibly four) epochs worth of + missed attestations. If an attestation is detected during this period, it means it is very likely that you + are running a second validator client with the same keys. This validator client will immediately shutdown if + this is detected in order to avoid potentially committing a slashable offense. Use this flag in order to + ENABLE this functionality, without this flag Lighthouse will begin attesting immediately. + --enable-high-validator-count-metrics + Enable per validator metrics for > 64 validators. Note: This flag is automatically enabled for <= 64 + validators. Enabling this metric for higher validator counts will lead to higher volume of prometheus + metrics being collected. + -h, --help Prints help information + --http Enable the RESTful HTTP API server. Disabled by default. + --http-allow-keystore-export + If present, allow access to the DELETE /lighthouse/keystores HTTP API method, which allows exporting + keystores and passwords to HTTP API consumers who have access to the API token. This method is useful for + exporting validators, however it should be used with caution since it exposes private key data to authorized + users. + --http-store-passwords-in-secrets-dir + If present, any validators created via the HTTP will have keystore passwords stored in the secrets-dir + rather than the validator definitions file. + --init-slashing-protection + If present, do not require the slashing protection database to exist before running. You SHOULD NOT use this + flag unless you're certain that a new slashing protection database is required. Usually, your database will + have been initialized when you imported your validator keys. If you misplace your database and then run with + this flag you risk being slashed. + --log-color Force outputting colors when emitting logs to the terminal. + --logfile-compress + If present, compress old log files. This can help reduce the space needed to store old logs. + + --logfile-no-restricted-perms + If present, log files will be generated as world-readable meaning they can be read by any user on the + machine. Note that logs can often contain sensitive information about your validator and so this flag should + be used with caution. For Windows users, the log file permissions will be inherited from the parent folder. + --metrics Enable the Prometheus metrics HTTP server. Disabled by default. + --unencrypted-http-transport + This is a safety flag to ensure that the user is aware that the http transport is unencrypted and using a + custom HTTP address is unsafe. + --use-long-timeouts + If present, the validator client will use longer timeouts for requests made to the beacon node. This flag is + generally not recommended, longer timeouts can cause missed duties when fallbacks are used. + -V, --version Prints version information + +OPTIONS: + --beacon-nodes + Comma-separated addresses to one or more beacon node HTTP APIs. Default is http://localhost:5052. + + --beacon-nodes-tls-certs + Comma-separated paths to custom TLS certificates to use when connecting to a beacon node (and/or proposer + node). These certificates must be in PEM format and are used in addition to the OS trust store. Commas must + only be used as a delimiter, and must not be part of the certificate path. + --broadcast + Comma-separated list of beacon API topics to broadcast to all beacon nodes. Possible values are: none, + attestations, blocks, subscriptions, sync-committee. Default (when flag is omitted) is to broadcast + subscriptions only. + --builder-registration-timestamp-override + This flag takes a unix timestamp value that will be used to override the timestamp used in the builder api + registration + -d, --datadir + Used to specify a custom root data directory for lighthouse keys and databases. Defaults to + $HOME/.lighthouse/{network} where network is the value of the `network` flag Note: Users should specify + separate custom datadirs for different networks. + --debug-level + Specifies the verbosity level used when emitting logs to the terminal. [default: info] [possible values: + info, debug, trace, warn, error, crit] + --gas-limit + The gas limit to be used in all builder proposals for all validators managed by this validator client. Note + this will not necessarily be used if the gas limit set here moves too far from the previous block's gas + limit. [default: 30,000,000] + --genesis-state-url + A URL of a beacon-API compatible server from which to download the genesis state. Checkpoint sync server + URLs can generally be used with this flag. If not supplied, a default URL or the --checkpoint-sync-url may + be used. If the genesis state is already included in this binary then this value will be ignored. + --genesis-state-url-timeout + The timeout in seconds for the request to --genesis-state-url. [default: 180] + + --graffiti + Specify your custom graffiti to be included in blocks. + + --graffiti-file + Specify a graffiti file to load validator graffitis from. + + --http-address
+ Set the address for the HTTP address. The HTTP server is not encrypted and therefore it is unsafe to publish + on a public network. When this flag is used, it additionally requires the explicit use of the + `--unencrypted-http-transport` flag to ensure the user is aware of the risks involved. For access via the + Internet, users should apply transport-layer security like a HTTPS reverse-proxy or SSH tunnelling. + --http-allow-origin + Set the value of the Access-Control-Allow-Origin response HTTP header. Use * to allow any origin (not + recommended in production). If no value is supplied, the CORS allowed origin is set to the listen address of + this server (e.g., http://localhost:5062). + --http-port + Set the listen TCP port for the RESTful HTTP API server. + + --latency-measurement-service + Set to 'true' to enable a service that periodically attempts to measure latency to BNs. Set to 'false' to + disable. [default: true] + --log-format + Specifies the log format used when emitting logs to the terminal. [possible values: JSON] + + --logfile + File path where the log file will be stored. Once it grows to the value specified in `--logfile-max-size` a + new log file is generated where future logs are stored. Once the number of log files exceeds the value + specified in `--logfile-max-number` the oldest log file will be overwritten. + --logfile-debug-level + The verbosity level used when emitting logs to the log file. [default: debug] [possible values: info, + debug, trace, warn, error, crit] + --logfile-format + Specifies the log format used when emitting logs to the logfile. [possible values: DEFAULT, JSON] + + --logfile-max-number + The maximum number of log files that will be stored. If set to 0, background file logging is disabled. + [default: 5] + --logfile-max-size + The maximum size (in MB) each log file can grow to before rotating. If set to 0, background file logging is + disabled. [default: 200] + --metrics-address
+ Set the listen address for the Prometheus metrics HTTP server. + + --metrics-allow-origin + Set the value of the Access-Control-Allow-Origin response HTTP header. Use * to allow any origin (not + recommended in production). If no value is supplied, the CORS allowed origin is set to the listen address of + this server (e.g., http://localhost:5064). + --metrics-port + Set the listen TCP port for the Prometheus metrics HTTP server. + + --monitoring-endpoint
+ Enables the monitoring service for sending system metrics to a remote endpoint. This can be used to monitor + your setup on certain services (e.g. beaconcha.in). This flag sets the endpoint where the beacon node + metrics will be sent. Note: This will send information to a remote sever which may identify and associate + your validators, IP address and other personal information. Always use a HTTPS connection and never provide + an untrusted URL. + --monitoring-endpoint-period + Defines how many seconds to wait between each message sent to the monitoring-endpoint. Default: 60s + + --network + Name of the Eth2 chain Lighthouse will sync and follow. [possible values: mainnet, prater, goerli, gnosis, + chiado, sepolia, holesky] + --proposer-nodes + Comma-separated addresses to one or more beacon node HTTP APIs. These specify nodes that are used to send + beacon block proposals. A failure will revert back to the standard beacon nodes specified in --beacon-nodes. + --safe-slots-to-import-optimistically + Used to coordinate manual overrides of the SAFE_SLOTS_TO_IMPORT_OPTIMISTICALLY parameter. This flag should + only be used if the user has a clear understanding that the broad Ethereum community has elected to override + this parameter in the event of an attack at the PoS transition block. Incorrect use of this flag can cause + your node to possibly accept an invalid chain or sync more slowly. Be extremely careful with this flag. + --secrets-dir + The directory which contains the password to unlock the validator voting keypairs. Each password should be + contained in a file where the name is the 0x-prefixed hex representation of the validators voting public + key. Defaults to ~/.lighthouse/{network}/secrets. + --suggested-fee-recipient + Once the merge has happened, this address will receive transaction fees from blocks proposed by this + validator client. If a fee recipient is configured in the validator definitions it takes priority over this + value. + --terminal-block-hash-epoch-override + Used to coordinate manual overrides to the TERMINAL_BLOCK_HASH_ACTIVATION_EPOCH parameter. This flag should + only be used if the user has a clear understanding that the broad Ethereum community has elected to override + the terminal PoW block. Incorrect use of this flag will cause your node to experience a consensus failure. + Be extremely careful with this flag. + --terminal-block-hash-override + Used to coordinate manual overrides to the TERMINAL_BLOCK_HASH parameter. This flag should only be used if + the user has a clear understanding that the broad Ethereum community has elected to override the terminal + PoW block. Incorrect use of this flag will cause your node to experience a consensus failure. Be extremely + careful with this flag. + --terminal-total-difficulty-override + Used to coordinate manual overrides to the TERMINAL_TOTAL_DIFFICULTY parameter. Accepts a 256-bit decimal + integer (not a hex value). This flag should only be used if the user has a clear understanding that the + broad Ethereum community has elected to override the terminal difficulty. Incorrect use of this flag will + cause your node to experience a consensus failure. Be extremely careful with this flag. + -t, --testnet-dir + Path to directory containing eth2_testnet specs. Defaults to a hard-coded Lighthouse testnet. Only effective + if there is no existing database. + --validator-registration-batch-size + Defines the number of validators per validator/register_validator request sent to the BN. This value can be + reduced to avoid timeouts from builders. [default: 500] + --validators-dir + The directory which contains the validator keystores, deposit data for each validator along with the common + slashing protection database and the validator_definitions.yml +``` \ No newline at end of file diff --git a/book/src/help_vm.md b/book/src/help_vm.md new file mode 100644 index 0000000000..fa08aa4f65 --- /dev/null +++ b/book/src/help_vm.md @@ -0,0 +1,97 @@ +# Validator Manager + +``` +Utilities for managing a Lighthouse validator client via the HTTP API. + +USAGE: + lighthouse validator_manager [FLAGS] [OPTIONS] [SUBCOMMAND] + +FLAGS: + --disable-log-timestamp If present, do not include timestamps in logging output. + --disable-malloc-tuning If present, do not configure the system allocator. Providing this flag will + generally increase memory usage, it should only be provided when debugging + specific memory allocation issues. + -h, --help Prints help information + --log-color Force outputting colors when emitting logs to the terminal. + --logfile-compress If present, compress old log files. This can help reduce the space needed to + store old logs. + --logfile-no-restricted-perms If present, log files will be generated as world-readable meaning they can be + read by any user on the machine. Note that logs can often contain sensitive + information about your validator and so this flag should be used with caution. + For Windows users, the log file permissions will be inherited from the parent + folder. + -V, --version Prints version information + +OPTIONS: + -d, --datadir + Used to specify a custom root data directory for lighthouse keys and databases. Defaults to + $HOME/.lighthouse/{network} where network is the value of the `network` flag Note: Users should specify + separate custom datadirs for different networks. + --debug-level + Specifies the verbosity level used when emitting logs to the terminal. [default: info] [possible values: + info, debug, trace, warn, error, crit] + --genesis-state-url + A URL of a beacon-API compatible server from which to download the genesis state. Checkpoint sync server + URLs can generally be used with this flag. If not supplied, a default URL or the --checkpoint-sync-url may + be used. If the genesis state is already included in this binary then this value will be ignored. + --genesis-state-url-timeout + The timeout in seconds for the request to --genesis-state-url. [default: 180] + + --log-format + Specifies the log format used when emitting logs to the terminal. [possible values: JSON] + + --logfile + File path where the log file will be stored. Once it grows to the value specified in `--logfile-max-size` a + new log file is generated where future logs are stored. Once the number of log files exceeds the value + specified in `--logfile-max-number` the oldest log file will be overwritten. + --logfile-debug-level + The verbosity level used when emitting logs to the log file. [default: debug] [possible values: info, + debug, trace, warn, error, crit] + --logfile-format + Specifies the log format used when emitting logs to the logfile. [possible values: DEFAULT, JSON] + + --logfile-max-number + The maximum number of log files that will be stored. If set to 0, background file logging is disabled. + [default: 5] + --logfile-max-size + The maximum size (in MB) each log file can grow to before rotating. If set to 0, background file logging is + disabled. [default: 200] + --network + Name of the Eth2 chain Lighthouse will sync and follow. [possible values: mainnet, prater, goerli, gnosis, + chiado, sepolia, holesky] + --safe-slots-to-import-optimistically + Used to coordinate manual overrides of the SAFE_SLOTS_TO_IMPORT_OPTIMISTICALLY parameter. This flag should + only be used if the user has a clear understanding that the broad Ethereum community has elected to override + this parameter in the event of an attack at the PoS transition block. Incorrect use of this flag can cause + your node to possibly accept an invalid chain or sync more slowly. Be extremely careful with this flag. + --terminal-block-hash-epoch-override + Used to coordinate manual overrides to the TERMINAL_BLOCK_HASH_ACTIVATION_EPOCH parameter. This flag should + only be used if the user has a clear understanding that the broad Ethereum community has elected to override + the terminal PoW block. Incorrect use of this flag will cause your node to experience a consensus failure. + Be extremely careful with this flag. + --terminal-block-hash-override + Used to coordinate manual overrides to the TERMINAL_BLOCK_HASH parameter. This flag should only be used if + the user has a clear understanding that the broad Ethereum community has elected to override the terminal + PoW block. Incorrect use of this flag will cause your node to experience a consensus failure. Be extremely + careful with this flag. + --terminal-total-difficulty-override + Used to coordinate manual overrides to the TERMINAL_TOTAL_DIFFICULTY parameter. Accepts a 256-bit decimal + integer (not a hex value). This flag should only be used if the user has a clear understanding that the + broad Ethereum community has elected to override the terminal difficulty. Incorrect use of this flag will + cause your node to experience a consensus failure. Be extremely careful with this flag. + -t, --testnet-dir + Path to directory containing eth2_testnet specs. Defaults to a hard-coded Lighthouse testnet. Only effective + if there is no existing database. + +SUBCOMMANDS: + create Creates new validators from BIP-39 mnemonic. A JSON file will be created which contains all the + validator keystores and other validator data. This file can then be imported to a validator client + using the "import-validators" command. Another, optional JSON file is created which contains a list of + validator deposits in the same format as the "ethereum/staking-deposit-cli" tool. + help Prints this message or the help of the given subcommand(s) + import Uploads validators to a validator client using the HTTP API. The validators are defined in a JSON file + which can be generated using the "create-validators" command. + move Uploads validators to a validator client using the HTTP API. The validators are defined in a JSON file + which can be generated using the "create-validators" command. This command only supports validators + signing via a keystore on the local file system (i.e., not Web3Signer validators). +``` \ No newline at end of file diff --git a/book/src/help_vm_create.md b/book/src/help_vm_create.md new file mode 100644 index 0000000000..505ea8638f --- /dev/null +++ b/book/src/help_vm_create.md @@ -0,0 +1,129 @@ +# Validator Manager Create + +``` +Creates new validators from BIP-39 mnemonic. A JSON file will be created which contains all the validator keystores and +other validator data. This file can then be imported to a validator client using the "import-validators" command. +Another, optional JSON file is created which contains a list of validator deposits in the same format as the +"ethereum/staking-deposit-cli" tool. + +USAGE: + lighthouse validator_manager create [FLAGS] [OPTIONS] --output-path + +FLAGS: + --disable-deposits When provided don't generate the deposits JSON file that is commonly used + for submitting validator deposits via a web UI. Using this flag will save + several seconds per validator if the user has an alternate strategy for + submitting deposits. + --disable-log-timestamp If present, do not include timestamps in logging output. + --disable-malloc-tuning If present, do not configure the system allocator. Providing this flag + will generally increase memory usage, it should only be provided when + debugging specific memory allocation issues. + --force-bls-withdrawal-credentials If present, allows BLS withdrawal credentials rather than an execution + address. This is not recommended. + -h, --help Prints help information + --log-color Force outputting colors when emitting logs to the terminal. + --logfile-compress If present, compress old log files. This can help reduce the space needed + to store old logs. + --logfile-no-restricted-perms If present, log files will be generated as world-readable meaning they can + be read by any user on the machine. Note that logs can often contain + sensitive information about your validator and so this flag should be used + with caution. For Windows users, the log file permissions will be + inherited from the parent folder. + --specify-voting-keystore-password If present, the user will be prompted to enter the voting keystore + password that will be used to encrypt the voting keystores. If this flag + is not provided, a random password will be used. It is not necessary to + keep backups of voting keystore passwords if the mnemonic is safely backed + up. + --stdin-inputs If present, read all user inputs from stdin instead of tty. + -V, --version Prints version information + +OPTIONS: + --beacon-node + A HTTP(S) address of a beacon node using the beacon-API. If this value is provided, an error will be raised + if any validator key here is already known as a validator by that beacon node. This helps prevent the same + validator being created twice and therefore slashable conditions. + --builder-proposals + When provided, all created validators will attempt to create blocks via builder rather than the local EL. + [possible values: true, false] + --count + The number of validators to create, regardless of how many already exist + + -d, --datadir + Used to specify a custom root data directory for lighthouse keys and databases. Defaults to + $HOME/.lighthouse/{network} where network is the value of the `network` flag Note: Users should specify + separate custom datadirs for different networks. + --debug-level + Specifies the verbosity level used when emitting logs to the terminal. [default: info] [possible values: + info, debug, trace, warn, error, crit] + --deposit-gwei + The GWEI value of the deposit amount. Defaults to the minimum amount required for an active validator + (MAX_EFFECTIVE_BALANCE) + --eth1-withdrawal-address + If this field is set, the given eth1 address will be used to create the withdrawal credentials. Otherwise, + it will generate withdrawal credentials with the mnemonic-derived withdrawal public key in EIP-2334 format. + --first-index + The first of consecutive key indexes you wish to create. [default: 0] + + --gas-limit + All created validators will use this gas limit. It is recommended to leave this as the default value by not + specifying this flag. + --genesis-state-url + A URL of a beacon-API compatible server from which to download the genesis state. Checkpoint sync server + URLs can generally be used with this flag. If not supplied, a default URL or the --checkpoint-sync-url may + be used. If the genesis state is already included in this binary then this value will be ignored. + --genesis-state-url-timeout + The timeout in seconds for the request to --genesis-state-url. [default: 180] + + --log-format + Specifies the log format used when emitting logs to the terminal. [possible values: JSON] + + --logfile + File path where the log file will be stored. Once it grows to the value specified in `--logfile-max-size` a + new log file is generated where future logs are stored. Once the number of log files exceeds the value + specified in `--logfile-max-number` the oldest log file will be overwritten. + --logfile-debug-level + The verbosity level used when emitting logs to the log file. [default: debug] [possible values: info, + debug, trace, warn, error, crit] + --logfile-format + Specifies the log format used when emitting logs to the logfile. [possible values: DEFAULT, JSON] + + --logfile-max-number + The maximum number of log files that will be stored. If set to 0, background file logging is disabled. + [default: 5] + --logfile-max-size + The maximum size (in MB) each log file can grow to before rotating. If set to 0, background file logging is + disabled. [default: 200] + --mnemonic-path If present, the mnemonic will be read in from this file. + --network + Name of the Eth2 chain Lighthouse will sync and follow. [possible values: mainnet, prater, goerli, gnosis, + chiado, sepolia, holesky] + --output-path + The path to a directory where the validator and (optionally) deposits files will be created. The directory + will be created if it does not exist. + --safe-slots-to-import-optimistically + Used to coordinate manual overrides of the SAFE_SLOTS_TO_IMPORT_OPTIMISTICALLY parameter. This flag should + only be used if the user has a clear understanding that the broad Ethereum community has elected to override + this parameter in the event of an attack at the PoS transition block. Incorrect use of this flag can cause + your node to possibly accept an invalid chain or sync more slowly. Be extremely careful with this flag. + --suggested-fee-recipient + All created validators will use this value for the suggested fee recipient. Omit this flag to use the + default value from the VC. + --terminal-block-hash-epoch-override + Used to coordinate manual overrides to the TERMINAL_BLOCK_HASH_ACTIVATION_EPOCH parameter. This flag should + only be used if the user has a clear understanding that the broad Ethereum community has elected to override + the terminal PoW block. Incorrect use of this flag will cause your node to experience a consensus failure. + Be extremely careful with this flag. + --terminal-block-hash-override + Used to coordinate manual overrides to the TERMINAL_BLOCK_HASH parameter. This flag should only be used if + the user has a clear understanding that the broad Ethereum community has elected to override the terminal + PoW block. Incorrect use of this flag will cause your node to experience a consensus failure. Be extremely + careful with this flag. + --terminal-total-difficulty-override + Used to coordinate manual overrides to the TERMINAL_TOTAL_DIFFICULTY parameter. Accepts a 256-bit decimal + integer (not a hex value). This flag should only be used if the user has a clear understanding that the + broad Ethereum community has elected to override the terminal difficulty. Incorrect use of this flag will + cause your node to experience a consensus failure. Be extremely careful with this flag. + -t, --testnet-dir + Path to directory containing eth2_testnet specs. Defaults to a hard-coded Lighthouse testnet. Only effective + if there is no existing database. +``` \ No newline at end of file diff --git a/book/src/help_vm_import.md b/book/src/help_vm_import.md new file mode 100644 index 0000000000..3960a55f1a --- /dev/null +++ b/book/src/help_vm_import.md @@ -0,0 +1,101 @@ +# Validator Manager Import + +``` +Uploads validators to a validator client using the HTTP API. The validators are defined in a JSON file which can be +generated using the "create-validators" command. + +USAGE: + lighthouse validator_manager import [FLAGS] [OPTIONS] --validators-file + +FLAGS: + --disable-log-timestamp If present, do not include timestamps in logging output. + --disable-malloc-tuning If present, do not configure the system allocator. Providing this flag will + generally increase memory usage, it should only be provided when debugging + specific memory allocation issues. + -h, --help Prints help information + --ignore-duplicates If present, ignore any validators which already exist on the VC. Without this + flag, the process will terminate without making any changes. This flag should + be used with caution, whilst it does not directly cause slashable conditions, + it might be an indicator that something is amiss. Users should also be careful + to avoid submitting duplicate deposits for validators that already exist on the + VC. + --log-color Force outputting colors when emitting logs to the terminal. + --logfile-compress If present, compress old log files. This can help reduce the space needed to + store old logs. + --logfile-no-restricted-perms If present, log files will be generated as world-readable meaning they can be + read by any user on the machine. Note that logs can often contain sensitive + information about your validator and so this flag should be used with caution. + For Windows users, the log file permissions will be inherited from the parent + folder. + -V, --version Prints version information + +OPTIONS: + -d, --datadir + Used to specify a custom root data directory for lighthouse keys and databases. Defaults to + $HOME/.lighthouse/{network} where network is the value of the `network` flag Note: Users should specify + separate custom datadirs for different networks. + --debug-level + Specifies the verbosity level used when emitting logs to the terminal. [default: info] [possible values: + info, debug, trace, warn, error, crit] + --genesis-state-url + A URL of a beacon-API compatible server from which to download the genesis state. Checkpoint sync server + URLs can generally be used with this flag. If not supplied, a default URL or the --checkpoint-sync-url may + be used. If the genesis state is already included in this binary then this value will be ignored. + --genesis-state-url-timeout + The timeout in seconds for the request to --genesis-state-url. [default: 180] + + --log-format + Specifies the log format used when emitting logs to the terminal. [possible values: JSON] + + --logfile + File path where the log file will be stored. Once it grows to the value specified in `--logfile-max-size` a + new log file is generated where future logs are stored. Once the number of log files exceeds the value + specified in `--logfile-max-number` the oldest log file will be overwritten. + --logfile-debug-level + The verbosity level used when emitting logs to the log file. [default: debug] [possible values: info, + debug, trace, warn, error, crit] + --logfile-format + Specifies the log format used when emitting logs to the logfile. [possible values: DEFAULT, JSON] + + --logfile-max-number + The maximum number of log files that will be stored. If set to 0, background file logging is disabled. + [default: 5] + --logfile-max-size + The maximum size (in MB) each log file can grow to before rotating. If set to 0, background file logging is + disabled. [default: 200] + --network + Name of the Eth2 chain Lighthouse will sync and follow. [possible values: mainnet, prater, goerli, gnosis, + chiado, sepolia, holesky] + --safe-slots-to-import-optimistically + Used to coordinate manual overrides of the SAFE_SLOTS_TO_IMPORT_OPTIMISTICALLY parameter. This flag should + only be used if the user has a clear understanding that the broad Ethereum community has elected to override + this parameter in the event of an attack at the PoS transition block. Incorrect use of this flag can cause + your node to possibly accept an invalid chain or sync more slowly. Be extremely careful with this flag. + --terminal-block-hash-epoch-override + Used to coordinate manual overrides to the TERMINAL_BLOCK_HASH_ACTIVATION_EPOCH parameter. This flag should + only be used if the user has a clear understanding that the broad Ethereum community has elected to override + the terminal PoW block. Incorrect use of this flag will cause your node to experience a consensus failure. + Be extremely careful with this flag. + --terminal-block-hash-override + Used to coordinate manual overrides to the TERMINAL_BLOCK_HASH parameter. This flag should only be used if + the user has a clear understanding that the broad Ethereum community has elected to override the terminal + PoW block. Incorrect use of this flag will cause your node to experience a consensus failure. Be extremely + careful with this flag. + --terminal-total-difficulty-override + Used to coordinate manual overrides to the TERMINAL_TOTAL_DIFFICULTY parameter. Accepts a 256-bit decimal + integer (not a hex value). This flag should only be used if the user has a clear understanding that the + broad Ethereum community has elected to override the terminal difficulty. Incorrect use of this flag will + cause your node to experience a consensus failure. Be extremely careful with this flag. + -t, --testnet-dir + Path to directory containing eth2_testnet specs. Defaults to a hard-coded Lighthouse testnet. Only effective + if there is no existing database. + --validators-file + The path to a JSON file containing a list of validators to be imported to the validator client. This file is + usually named "validators.json". + --vc-token + The file containing a token required by the validator client. + + --vc-url + A HTTP(S) address of a validator client using the keymanager-API. If this value is not supplied then a 'dry + run' will be conducted where no changes are made to the validator client. [default: http://localhost:5062] +``` \ No newline at end of file diff --git a/book/src/help_vm_move.md b/book/src/help_vm_move.md new file mode 100644 index 0000000000..dea440dca9 --- /dev/null +++ b/book/src/help_vm_move.md @@ -0,0 +1,112 @@ +# Validator Manager Move + +``` +Uploads validators to a validator client using the HTTP API. The validators are defined in a JSON file which can be +generated using the "create-validators" command. This command only supports validators signing via a keystore on the +local file system (i.e., not Web3Signer validators). + +USAGE: + lighthouse validator_manager move [FLAGS] [OPTIONS] --dest-vc-token --dest-vc-url --src-vc-token --src-vc-url + +FLAGS: + --disable-log-timestamp If present, do not include timestamps in logging output. + --disable-malloc-tuning If present, do not configure the system allocator. Providing this flag will + generally increase memory usage, it should only be provided when debugging + specific memory allocation issues. + -h, --help Prints help information + --log-color Force outputting colors when emitting logs to the terminal. + --logfile-compress If present, compress old log files. This can help reduce the space needed to + store old logs. + --logfile-no-restricted-perms If present, log files will be generated as world-readable meaning they can be + read by any user on the machine. Note that logs can often contain sensitive + information about your validator and so this flag should be used with caution. + For Windows users, the log file permissions will be inherited from the parent + folder. + --stdin-inputs If present, read all user inputs from stdin instead of tty. + -V, --version Prints version information + +OPTIONS: + --builder-proposals + When provided, all created validators will attempt to create blocks via builder rather than the local EL. + [possible values: true, false] + --count The number of validators to move. + -d, --datadir + Used to specify a custom root data directory for lighthouse keys and databases. Defaults to + $HOME/.lighthouse/{network} where network is the value of the `network` flag Note: Users should specify + separate custom datadirs for different networks. + --debug-level + Specifies the verbosity level used when emitting logs to the terminal. [default: info] [possible values: + info, debug, trace, warn, error, crit] + --dest-vc-token + The file containing a token required by the destination validator client. + + --dest-vc-url + A HTTP(S) address of a validator client using the keymanager-API. This validator client is the "destination" + and will have new validators added as they are removed from the "source" validator client. + --gas-limit + All created validators will use this gas limit. It is recommended to leave this as the default value by not + specifying this flag. + --genesis-state-url + A URL of a beacon-API compatible server from which to download the genesis state. Checkpoint sync server + URLs can generally be used with this flag. If not supplied, a default URL or the --checkpoint-sync-url may + be used. If the genesis state is already included in this binary then this value will be ignored. + --genesis-state-url-timeout + The timeout in seconds for the request to --genesis-state-url. [default: 180] + + --log-format + Specifies the log format used when emitting logs to the terminal. [possible values: JSON] + + --logfile + File path where the log file will be stored. Once it grows to the value specified in `--logfile-max-size` a + new log file is generated where future logs are stored. Once the number of log files exceeds the value + specified in `--logfile-max-number` the oldest log file will be overwritten. + --logfile-debug-level + The verbosity level used when emitting logs to the log file. [default: debug] [possible values: info, + debug, trace, warn, error, crit] + --logfile-format + Specifies the log format used when emitting logs to the logfile. [possible values: DEFAULT, JSON] + + --logfile-max-number + The maximum number of log files that will be stored. If set to 0, background file logging is disabled. + [default: 5] + --logfile-max-size + The maximum size (in MB) each log file can grow to before rotating. If set to 0, background file logging is + disabled. [default: 200] + --network + Name of the Eth2 chain Lighthouse will sync and follow. [possible values: mainnet, prater, goerli, gnosis, + chiado, sepolia, holesky] + --safe-slots-to-import-optimistically + Used to coordinate manual overrides of the SAFE_SLOTS_TO_IMPORT_OPTIMISTICALLY parameter. This flag should + only be used if the user has a clear understanding that the broad Ethereum community has elected to override + this parameter in the event of an attack at the PoS transition block. Incorrect use of this flag can cause + your node to possibly accept an invalid chain or sync more slowly. Be extremely careful with this flag. + --src-vc-token + The file containing a token required by the source validator client. + + --src-vc-url + A HTTP(S) address of a validator client using the keymanager-API. This validator client is the "source" and + contains the validators that are to be moved. + --suggested-fee-recipient + All created validators will use this value for the suggested fee recipient. Omit this flag to use the + default value from the VC. + --terminal-block-hash-epoch-override + Used to coordinate manual overrides to the TERMINAL_BLOCK_HASH_ACTIVATION_EPOCH parameter. This flag should + only be used if the user has a clear understanding that the broad Ethereum community has elected to override + the terminal PoW block. Incorrect use of this flag will cause your node to experience a consensus failure. + Be extremely careful with this flag. + --terminal-block-hash-override + Used to coordinate manual overrides to the TERMINAL_BLOCK_HASH parameter. This flag should only be used if + the user has a clear understanding that the broad Ethereum community has elected to override the terminal + PoW block. Incorrect use of this flag will cause your node to experience a consensus failure. Be extremely + careful with this flag. + --terminal-total-difficulty-override + Used to coordinate manual overrides to the TERMINAL_TOTAL_DIFFICULTY parameter. Accepts a 256-bit decimal + integer (not a hex value). This flag should only be used if the user has a clear understanding that the + broad Ethereum community has elected to override the terminal difficulty. Incorrect use of this flag will + cause your node to experience a consensus failure. Be extremely careful with this flag. + -t, --testnet-dir + Path to directory containing eth2_testnet specs. Defaults to a hard-coded Lighthouse testnet. Only effective + if there is no existing database. + --validators + The validators to be moved. Either a list of 0x-prefixed validator pubkeys or the keyword "all". +``` \ No newline at end of file diff --git a/scripts/cli.sh b/scripts/cli.sh new file mode 100755 index 0000000000..d9def7624f --- /dev/null +++ b/scripts/cli.sh @@ -0,0 +1,98 @@ +#! /usr/bin/env bash + +# IMPORTANT +# This script should NOT be run directly. +# Run `make cli` from the root of the repository instead. + +set -e + +# A function to generate formatted .md files +write_to_file() { + local cmd="$1" + local file="$2" + local program="$3" + + # Remove first line of cmd to get rid of commit specific numbers. + cmd=${cmd#*$'\n'} + + # We need to add the header and the backticks to create the code block. + printf "# %s\n\n\`\`\`\n%s\n\`\`\`" "$program" "$cmd" > "$file" +} + +CMD=./target/release/lighthouse + +# Store all help strings in variables. +general_cli=$($CMD --help) +bn_cli=$($CMD bn --help) +vc_cli=$($CMD vc --help) +vm_cli=$($CMD vm --help) +vm_cli_create=$($CMD vm create --help) +vm_cli_import=$($CMD vm import --help) +vm_cli_move=$($CMD vm move --help) + +general=./help_general.md +bn=./help_bn.md +vc=./help_vc.md +am=./help_am.md +vm=./help_vm.md +vm_create=./help_vm_create.md +vm_import=./help_vm_import.md +vm_move=./help_vm_move.md + +# create .md files +write_to_file "$general_cli" "$general" "Lighthouse General Commands" +write_to_file "$bn_cli" "$bn" "Beacon Node" +write_to_file "$vc_cli" "$vc" "Validator Client" +write_to_file "$vm_cli" "$vm" "Validator Manager" +write_to_file "$vm_cli_create" "$vm_create" "Validator Manager Create" +write_to_file "$vm_cli_import" "$vm_import" "Validator Manager Import" +write_to_file "$vm_cli_move" "$vm_move" "Validator Manager Move" + +#input 1 = $1 = files; input 2 = $2 = new files +files=(./book/src/help_general.md ./book/src/help_bn.md ./book/src/help_vc.md ./book/src/help_vm.md ./book/src/help_vm_create.md ./book/src/help_vm_import.md ./book/src/help_vm_move.md) +new_files=($general $bn $vc $vm $vm_create $vm_import $vm_move) + +# function to check +check() { + local file="$1" + local new_file="$2" + + if [[ -f $file ]]; then # check for existence of file + diff=$(diff $file $new_file || :) + else + cp $new_file $file + changes=true + echo "$file is not found, it has just been created" + fi + + if [[ -z $diff ]]; then # check for difference + : # do nothing + else + cp $new_file $file + changes=true + echo "$file has been updated" + fi +} + +# define changes as false +changes=false +# call check function to check for each help file +check ${files[0]} ${new_files[0]} +check ${files[1]} ${new_files[1]} +check ${files[2]} ${new_files[2]} +check ${files[3]} ${new_files[3]} +check ${files[4]} ${new_files[4]} +check ${files[5]} ${new_files[5]} +check ${files[6]} ${new_files[6]} + +# remove help files +rm -f help_general.md help_bn.md help_vc.md help_am.md help_vm.md help_vm_create.md help_vm_import.md help_vm_move.md + +# only exit at the very end +if [[ $changes == true ]]; then + echo "Exiting with error to indicate changes occurred..." + exit 1 +else + echo "CLI help texts are up to date." + exit 0 +fi