diff --git a/book/src/help_vm_create.md b/book/src/help_vm_create.md new file mode 100644 index 0000000000..684a3c04d2 --- /dev/null +++ b/book/src/help_vm_create.md @@ -0,0 +1,132 @@ +# 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. + -s, --spec + This flag is deprecated, it will be disallowed in a future release. This value is now derived from the + --network or --testnet-dir flags. + --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_am.md b/book/src/help_vm_import.md similarity index 80% rename from book/src/help_am.md rename to book/src/help_vm_import.md index 8c1ee4d019..ca619b51a3 100644 --- a/book/src/help_am.md +++ b/book/src/help_vm_import.md @@ -1,10 +1,11 @@ -# Account Manager +# Validator Manager Import ``` -Utilities for generating and managing Ethereum 2.0 accounts. +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 account_manager [FLAGS] [OPTIONS] [SUBCOMMAND] + lighthouse validator_manager import [FLAGS] [OPTIONS] --validators-file FLAGS: --disable-log-timestamp If present, do not include timestamps in logging output. @@ -12,6 +13,12 @@ FLAGS: 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. @@ -85,9 +92,13 @@ OPTIONS: -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. -SUBCOMMANDS: - help Prints this message or the help of the given subcommand(s) - validator Provides commands for managing Eth2 validators. - wallet Manage wallets, from which validator keys can be derived. + --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.md b/book/src/help_vm_move.md similarity index 74% rename from book/src/help_vm.md rename to book/src/help_vm_move.md index be62e3549c..5b9a8e9f6d 100644 --- a/book/src/help_vm.md +++ b/book/src/help_vm_move.md @@ -1,10 +1,12 @@ -# Validator Manager +# Validator Manager Move ``` -Utilities for managing a Lighthouse validator client via the HTTP API. +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 [FLAGS] [OPTIONS] [SUBCOMMAND] + 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. @@ -20,9 +22,14 @@ FLAGS: 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 @@ -30,6 +37,15 @@ OPTIONS: --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 @@ -67,6 +83,15 @@ OPTIONS: -s, --spec This flag is deprecated, it will be disallowed in a future release. This value is now derived from the --network or --testnet-dir flags. + --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 @@ -85,16 +110,6 @@ OPTIONS: -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). + --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 index 24b6b9da2d..ed6da53430 100755 --- a/scripts/cli.sh +++ b/scripts/cli.sh @@ -32,25 +32,29 @@ fi general_cli=$($CMD --help) bn_cli=$($CMD bn --help) vc_cli=$($CMD vc --help) -am_cli=$($CMD am --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 "$am_cli" "$am" "Account Manager" -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_am.md ./book/src/help_vm.md) -new_files=($general $bn $vc $am $vm) +files=(./book/src/help_general.md ./book/src/help_bn.md ./book/src/help_vc.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_create $vm_import $vm_move) # function to check check() { @@ -82,9 +86,10 @@ 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]} # remove help files -rm -f help_general.md help_bn.md help_vc.md help_am.md help_vm.md +rm -f help_general.md help_bn.md help_vc.md help_am.md help_vm_create.md help_vm_import.md help_mv_move.md # only exit at the very end if [[ $changes == true ]]; then