Command Line Reference¶
This reference describes the syntax of the Lodestar CLI commands and their options.
Global Options¶
| Option | Type | Description | Default |
|---|---|---|---|
--rootDir |
string | Lodestar root directory | |
--network |
string | Name of the Ethereum Consensus chain network to join | mainnet |
--paramsFile |
string | Network configuration file | |
--terminal-total-difficulty-override |
string | Terminal PoW block TTD override | |
--terminal-block-hash-override |
string | Terminal PoW block hash override | |
--terminal-block-hash-epoch-override |
string | Terminal PoW block hash override activation epoch |
beacon¶
Run a beacon chain node
Examples
Run a beacon chain node and connect to the prater testnet
beacon --network prater
Options
| Option | Type | Description | Default |
|---|---|---|---|
--port |
number | The TCP/UDP port to listen on. The UDP port can be modified by the --discovery-port flag. | 9000 |
--discoveryPort |
number | The UDP port that discovery will listen on. Defaults to port |
port |
--forceGenesis |
boolean | Force beacon to create genesis without file | |
--genesisStateFile |
string | Path or URL to download a genesis state file in ssz-encoded format | |
--logLevel |
string | Logging verbosity level | info |
--logLevelFile |
string | Logging verbosity level for file transport | info |
--logRotate |
boolean | Daily rotate log files | |
--logMaxFiles |
number | Number of log files to maintain while rotating logs(if provided with logRotate) | |
--configFile |
string | Beacon node configuration file path | |
--logFile |
string | Path to output all logs to a persistent log file | |
--api.rest.api |
array | Pick namespaces to expose for HTTP API. Set to '*' to enable all namespaces | ["beacon","config","events","node","validator"] |
--api.rest.cors |
string | Configures the Access-Control-Allow-Origin CORS header for HTTP API | * |
--api.rest.enabled |
boolean | Enable/disable HTTP API | true |
--api.rest.host |
string | Set host for HTTP API | 127.0.0.1 |
--api.rest.port |
number | Set port for HTTP API | 9596 |
--chain.proposerBoostEnabled |
boolean | Enable proposer boost to reward a timely block | false |
--eth1.enabled |
boolean | Whether to follow the eth1 chain | true |
--eth1.providerUrl |
string | [DEPRECATED] Url to Eth1 node with enabled rpc | [DEPRECATED] |
--eth1.providerUrls |
array | Urls to Eth1 node with enabled rpc | http://localhost:8545 |
--eth1.depositContractDeployBlock |
number | Block number at which the deposit contract contract was deployed | 0 |
--execution.urls |
array | Urls to execution client engine API | |
--execution.timeout |
number | Timeout in miliseconds for execution engine API HTTP client | |
--jwt-secret |
string | File path to a shared hex-encoded jwt secret which will be used to generate and bundle HS256 encoded jwt tokens for authentication with the EL client's rpc server hosting engine apis. Secret to be exactly same as the one used by the corresponding EL client. | |
--metrics.enabled |
boolean | Enable the Prometheus metrics HTTP server | false |
--metrics.port |
number | Listen TCP port for the Prometheus metrics HTTP server | 8008 |
--metrics.address |
string | Listen address for the Prometheus metrics HTTP server | undefined |
--network.discv5.enabled |
boolean | Enable discv5 | true |
--network.discv5.bindAddr |
string | Local multiaddress to listen on for discv5 | /ip4/0.0.0.0/udp/9000 |
--network.discv5.bootEnrs |
array | Bootnodes for discv5 discovery | [] |
--network.maxPeers |
number | The maximum number of connections allowed | 55 |
--network.targetPeers |
number | The target connected peers. Above this number peers will be disconnected | 50 |
--network.bootMultiaddrs |
array | Libp2p peers to connect to on boot | [] |
--network.localMultiaddrs |
array | Local listening addresses for req/resp and gossip | /ip4/0.0.0.0/tcp/9000 |
--network.subscribeAllSubnets |
boolean | Subscribe to all subnets regardless of validator count | false |
--network.connectToDiscv5Bootnodes |
boolean | Attempt direct connection to discv5 bootnodes from network.discv5.bootEnrs option | false |
--network.discv5FirstQueryDelayMs |
number | Delay the 1st heart beat of Peer Manager after starting Discv5 | 1000 |
--terminal-total-difficulty-override |
string | Terminal PoW block TTD override | |
--terminal-block-hash-override |
string | Terminal PoW block hash override | |
--terminal-block-hash-epoch-override |
string | Terminal PoW block hash override activation epoch | |
--enr.ip |
string | Override ENR IP entry | |
--enr.tcp |
number | Override ENR TCP entry | |
--enr.udp |
number | Override ENR UDP entry | |
--enr.ip6 |
string | Override ENR IPv6 entry | |
--enr.tcp6 |
number | Override ENR (IPv6-specific) TCP entry | |
--enr.udp6 |
number | Override ENR (IPv6-specific) UDP entry | |
--weakSubjectivityStateFile |
string | Path or URL to download a weak subjectivity state file in ssz-encoded format | |
--weakSubjectivitySyncLatest |
boolean | Sync and start from a weak subjectivity state at --weakSubjectivityCheckpoint (if provided, else fetches the latest finalized) via the --weakSubjectivityServerUrl | |
--weakSubjectivityServerUrl |
string | Pass in a server url hosting Beacon Node APIs from which to fetch weak subjectivity state, required in conjunction with --weakSubjectivitySyncLatest or --weakSubjectivityCheckpoint. | |
--weakSubjectivityCheckpoint |
string | To fetch and start beacon node off a state at the provided weakSubjectivity checkpoint, to be supplied in |
validator¶
Run one or multiple validator clients
Examples
Run one validator client with all the keystores available in the directory .prater/keystores
validator --network prater
Options
| Option | Type | Description | Default |
|---|---|---|---|
--keystoresDir |
string | Directory for storing validator keystores. | $rootDir/keystores |
--secretsDir |
string | Directory for storing validator keystore secrets. | $rootDir/secrets |
--logLevel |
string | Logging verbosity level | info |
--logLevelFile |
string | Logging verbosity level for file transport | info |
--logRotate |
boolean | Daily rotate log files | |
--logMaxFiles |
number | Number of log files to maintain while rotating logs(if provided with logRotate) | |
--keymanagerEnabled |
boolean | Enable keymanager API server | |
--keymanagerAuthEnabled |
boolean | Enable token bearer authentication for keymanager API server | true |
--keymanagerPort |
number | Set port for keymanager API | 5062 |
--keymanagerHost |
string | Set host for keymanager API | 127.0.0.1 |
--keymanagerCors |
string | Configures the Access-Control-Allow-Origin CORS header for keymanager API | * |
--logFile |
string | Path to output all logs to a persistent log file | |
--validatorsDbDir |
string | Data directory for validator databases. | $rootDir/validator-db |
--server |
string | Address to connect to BeaconNode | http://127.0.0.1:9596 |
--force |
boolean | Open validators even if there's a lockfile. Use with caution | |
--graffiti |
string | Specify your custom graffiti to be included in blocks (plain UTF8 text, 32 characters max) | |
--importKeystoresPath |
array | Path(s) to a directory or single filepath to validator keystores, i.e. Launchpad validators | ./keystores/*.json |
--importKeystoresPassword |
string | Path to a file with password to decrypt all keystores from importKeystoresPath option | ./password.txt |
--externalSignerUrl |
string | URL to connect to an external signing server | |
--externalSignerPublicKeys |
array | List of validator public keys used by an external signer. May also provide a single string a comma separated public keys | |
--externalSignerFetchPubkeys |
boolean | Fetch then list of pubkeys to validate from an external signer | |
--metrics.enabled |
boolean | Enable the Prometheus metrics HTTP server | false |
--metrics.port |
number | Listen TCP port for the Prometheus metrics HTTP server | 5064 |
--metrics.address |
string | Listen address for the Prometheus metrics HTTP server | 127.0.0.1 |
account¶
Utilities for generating and managing Ethereum Consensus accounts
account validator¶
Provides commands for managing Ethereum Consensus validators.
Options
The options below apply to all subcommands.
| Option | Type | Description | Default |
|---|---|---|---|
--keystoresDir |
string | Directory for storing validator keystores. | $rootDir/keystores |
--secretsDir |
string | Directory for storing validator keystore secrets. | $rootDir/secrets |
account validator create¶
Creates new validators from an existing EIP-2386 wallet using the EIP-2333 HD key derivation scheme. Creates a new directory per validator with a voting keystore, withdrawal keystore, and pre-computed deposit RPL data
Examples
Create a validator from HD wallet named 'primary'
account validator create --name primary --passphraseFile primary.pass
Options
| Option | Type | Description | Default |
|---|---|---|---|
--name |
string | Use the wallet identified by this name | |
--passphraseFile |
string | A path to a file containing the password which will unlock the wallet. | |
--depositGwei |
string | The GWEI value of the deposit amount. Defaults to the minimum amount required for an active validator (MAX_EFFECTIVE_BALANCE) | |
--storeWithdrawalKeystore |
boolean | If present, the withdrawal keystore will be stored alongside the voting keypair. It is generally recommended to not store the withdrawal key and instead generate them from the wallet seed when required. | |
--count |
number | The number of validators to create | 1 |
account validator deposit¶
DEPRECATED. Please use the official tools to perform your deposits - eth2.0-deposit-cli: https://github.com/ethereum/eth2.0-deposit-cli - Ethereum Foundation launchpad: https://launchpad.ethereum.org
Examples
Options
account validator import¶
Imports one or more EIP-2335 keystores into a Lodestar validator client directory, requesting passwords interactively. The directory flag provides a convenient method for importing a directory of keys generated by the eth2-deposit-cli Ethereum Foundation utility.
Examples
Import validator keystores generated with the Ethereum Foundation Staking Launchpad
account validator import --network prater --directory $HOME/eth2.0-deposit-cli/validator_keys
Options
| Option | Type | Description | Default |
|---|---|---|---|
--keystore |
string | Path to a single keystore to be imported. | |
--directory |
string | Path to a directory which contains zero or more keystores for import. This directory and all sub-directories will be searched and any file name which contains 'keystore' and has the '.json' extension will be attempted to be imported. | |
--passphraseFile |
string | Path to a file that contains password that protects the keystore. |
account validator list¶
Lists the public keys of all validators
Examples
List all validator pubkeys in the directory .testing/keystores
account validator list --keystoresDir .testing/keystores
account validator recover¶
Recovers validator private keys given a BIP-39 mnemonic phrase. If you did not specify a --firstIndex or count --count, by default this will only recover the keys associated with the validator at index 0 for an HD wallet in accordance with the EIP-2333 spec.
Examples
Recover validator
account validator recover
Options
| Option | Type | Description | Default |
|---|---|---|---|
--count |
number | The number of validators to create | 1 |
--depositGwei |
string | The GWEI value of the deposit amount. Defaults to the minimum amount required for an active validator (MAX_EFFECTIVE_BALANCE) | |
--storeWithdrawalKeystore |
boolean | If present, the withdrawal keystore will be stored alongside the voting keypair. It is generally recommended to not store the withdrawal key and instead generate them from the wallet seed when required. | |
--mnemonicInputPath |
string | If present, the mnemonic will be read in from this file. | |
--firstIndex |
number | The first of consecutive key indexes you wish to recover. |
account validator slashing-protection¶
Import or export slashing protection data to or from another client.
Options
The options below apply to all subcommands.
| Option | Type | Description | Default |
|---|---|---|---|
--server |
string | Address to connect to BeaconNode | http://127.0.0.1:9596 |
--force |
boolean | If genesisValidatorsRoot can't be fetched from the Beacon node, use a zero hash |
account validator slashing-protection import¶
Import an interchange file.
Examples
Import an interchange file to the slashing protection DB
account validator slashing-protection import --network prater --file interchange.json
Options
| Option | Type | Description | Default |
|---|---|---|---|
--file |
string | The slashing protection interchange file to import (.json). |
account validator slashing-protection export¶
Export an interchange file.
Examples
Export an interchange JSON file for all validators in the slashing protection DB
account validator slashing-protection export --network prater --file interchange.json
Options
| Option | Type | Description | Default |
|---|---|---|---|
--file |
string | The slashing protection interchange file to export to (.json). |
account validator voluntary-exit¶
Performs a voluntary exit for a given validator (as identified via publicKey. If no publicKey is provided, a prompt will ask the user which validator they would like to choose for the voluntary exit.
Examples
Perform a voluntary exit for the validator who has a public key 0xF00
account validator voluntary-exit --publicKey 0xF00
Options
| Option | Type | Description | Default |
|---|---|---|---|
--keystoresDir |
string | Directory for storing validator keystores. | $rootDir/keystores |
--secretsDir |
string | Directory for storing validator keystore secrets. | $rootDir/secrets |
--logLevel |
string | Logging verbosity level | info |
--logLevelFile |
string | Logging verbosity level for file transport | info |
--logRotate |
boolean | Daily rotate log files | |
--logMaxFiles |
number | Number of log files to maintain while rotating logs(if provided with logRotate) | |
--keymanagerEnabled |
boolean | Enable keymanager API server | |
--keymanagerAuthEnabled |
boolean | Enable token bearer authentication for keymanager API server | true |
--keymanagerPort |
number | Set port for keymanager API | 5062 |
--keymanagerHost |
string | Set host for keymanager API | 127.0.0.1 |
--keymanagerCors |
string | Configures the Access-Control-Allow-Origin CORS header for keymanager API | * |
--logFile |
string | Path to output all logs to a persistent log file | |
--validatorsDbDir |
string | Data directory for validator databases. | $rootDir/validator-db |
--server |
string | Address to connect to BeaconNode | http://127.0.0.1:9596 |
--force |
boolean | Open validators even if there's a lockfile. Use with caution | |
--graffiti |
string | Specify your custom graffiti to be included in blocks (plain UTF8 text, 32 characters max) | |
--importKeystoresPath |
array | Path(s) to a directory or single filepath to validator keystores, i.e. Launchpad validators | ./keystores/*.json |
--importKeystoresPassword |
string | Path to a file with password to decrypt all keystores from importKeystoresPath option | ./password.txt |
--externalSignerUrl |
string | URL to connect to an external signing server | |
--externalSignerPublicKeys |
array | List of validator public keys used by an external signer. May also provide a single string a comma separated public keys | |
--externalSignerFetchPubkeys |
boolean | Fetch then list of pubkeys to validate from an external signer | |
--metrics.enabled |
boolean | Enable the Prometheus metrics HTTP server | false |
--metrics.port |
number | Listen TCP port for the Prometheus metrics HTTP server | 5064 |
--metrics.address |
string | Listen address for the Prometheus metrics HTTP server | 127.0.0.1 |
--publicKey |
string | The public key of the validator to voluntarily exit | |
--exitEpoch |
number | The epoch upon which to submit the voluntary exit. If no value is provided, then we default to the currentEpoch. |
account wallet¶
Provides commands for managing Ethereum Consensus wallets.
Options
The options below apply to all subcommands.
| Option | Type | Description | Default |
|---|---|---|---|
--walletsDir |
string | Directory for storing wallets. | $rootDir/wallets |
account wallet create¶
Creates a new HD (hierarchical-deterministic) EIP-2386 wallet
Examples
Create an HD wallet named 'primary'
account wallet create --name primary --passphraseFile primary.pass
Options
| Option | Type | Description | Default |
|---|---|---|---|
--walletsDir |
string | Directory for storing wallets. | $rootDir/wallets |
--name |
string | The wallet will be created with this name. It is not allowed to create two wallets with the same name for the same --base-dir. | |
--passphraseFile |
string | A path to a file containing the password which will unlock the wallet. If the file does not exist, a random password will be generated and saved at that path. To avoid confusion, if the file does not already exist it must include a '.pass' suffix. | |
--type |
string | The type of wallet to create. Only HD (hierarchical-deterministic) wallets are supported presently. | hd |
--mnemonicOutputPath |
string | If present, the mnemonic will be saved to this file |
account wallet list¶
Lists the names of all wallets
Examples
List all wallets in .network/wallets
account wallet list --walletsDir .network/wallets
account wallet recover¶
Recovers an EIP-2386 wallet from a given a BIP-39 mnemonic phrase.
Examples
Recover wallet
account wallet recover
Options
| Option | Type | Description | Default |
|---|---|---|---|
--walletsDir |
string | Directory for storing wallets. | $rootDir/wallets |
--name |
string | The wallet will be created with this name. It is not allowed to create two wallets with the same name for the same --base-dir. | |
--passphraseFile |
string | A path to a file containing the password which will unlock the wallet. If the file does not exist, a random password will be generated and saved at that path. To avoid confusion, if the file does not already exist it must include a '.pass' suffix. | |
--type |
string | The type of wallet to create. Only HD (hierarchical-deterministic) wallets are supported presently. | hd |
--mnemonicOutputPath |
string | If present, the mnemonic will be saved to this file | |
--mnemonicInputPath |
string | If present, the mnemonic will be read in from this file. |
init¶
Initialize Lodestar directories and files necessary to run a beacon chain node. This step is not required, and should only be used to prepare special configurations
Examples
Initialize a configuration for the Prater testnet. Then, you can edit the config file undefined to customize your beacon node settings
init --network prater
Options
Cmd init has all the options from the beacon cmd.
dev¶
Quickly bootstrap a beacon node and multiple validators. Use for development and testing
Examples
Start a single beacon node with 8 interop validators
dev --genesisValidators 8 --reset
Options
Cmd dev has all the options from the beacon cmd.
| Option | Type | Description | Default |
|---|---|---|---|
--keymanagerEnabled |
boolean | Enable keymanager API server | |
--keymanagerAuthEnabled |
boolean | Enable token bearer authentication for keymanager API server | true |
--keymanagerPort |
number | Set port for keymanager API | 5062 |
--keymanagerHost |
string | Set host for keymanager API | 127.0.0.1 |
--keymanagerCors |
string | Configures the Access-Control-Allow-Origin CORS header for keymanager API | * |
--importKeystoresPath |
array | Path(s) to a directory or single filepath to validator keystores, i.e. Launchpad validators | ./keystores/*.json |
--importKeystoresPassword |
string | Path to a file with password to decrypt all keystores from importKeystoresPath option | ./password.txt |
--genesisEth1Hash |
string | If present it will create genesis with this eth1 hash. | |
--genesisValidators |
number | If present it will create genesis with interop validators and start chain. | |
--startValidators |
string | Start interop validators in inclusive range with notation '0:7' | |
--genesisTime |
number | genesis_time to initialize interop genesis state | |
--reset |
boolean | To delete chain and validator directories | |
--server |
string | Address to connect to BeaconNode. Pass 'memory' for in memory communication | http://127.0.0.1:9596 |