Command Line Reference¶
This reference describes the syntax of the Lodestar CLI commands and their options.
Global Options¶
Option | Type | Description | Default |
---|---|---|---|
--dataDir |
string | Lodestar root data 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 goerli testnet
beacon --network goerli
Options
Option | Type | Description | Default |
---|---|---|---|
--checkpointSyncUrl |
string | Server url hosting Beacon Node APIs to fetch weak subjectivity state. Fetch latest finalized by default, else set --wssCheckpoint | |
--checkpointState |
string | Set a checkpoint state to start syncing from | |
--wssCheckpoint |
string | Start beacon node off a state at the provided weak subjectivity checkpoint, to be supplied in |
|
--forceCheckpointSync |
boolean | Force syncing from checkpoint state even if db state is within weak subjectivity period. This helps to avoid long sync times after node has been offline for a while. | |
--private |
boolean | Do not send implementation details over p2p identify protocol and in builder requests | |
--logLevel |
string | Logging verbosity level for emitting logs to terminal | info |
--logFile |
string | Path to output all logs to a persistent log file, use 'none' to disable | |
--logFileLevel |
string | Logging verbosity level for emitting logs to file | debug |
--logFileDailyRotate |
number | Daily rotate log files, set to an integer to limit the file count, set to 0 (zero) to disable rotation | 5 |
--rest |
boolean | Enable/disable HTTP API | true |
--rest.namespace |
array | Pick namespaces to expose for HTTP API. Set to '*' to enable all namespaces | ["beacon","config","events","node","validator","lightclient"] |
--rest.cors |
string | Configures the Access-Control-Allow-Origin CORS header for HTTP API | * |
--rest.address |
string | Set host for HTTP API | 127.0.0.1 |
--rest.port |
number | Set port for HTTP API | 9596 |
--suggestedFeeRecipient |
string | Specify fee recipient default for collecting the EL block fees and rewards (a hex string representing 20 bytes address: ^0x[a-fA-F0-9]{40}$) in case validator fails to update for a validator index before calling produceBlock . |
0x0000000000000000000000000000000000000000 |
--emitPayloadAttributes |
boolean | Flag to SSE emit execution payloadAttributes before every slot |
false |
--eth1 |
boolean | Whether to follow the eth1 chain | true |
--eth1.providerUrls |
array | Urls to Eth1 node with enabled rpc. If not explicitly provided and execution endpoint provided via execution.urls, it will use execution.urls. Otherwise will try connecting on the specified default(s) | http://localhost:8545 |
--execution.urls |
array | Urls to execution client engine API | http://localhost:8551 |
--execution.timeout |
number | Timeout in milliseconds for execution engine API HTTP client | 12000 |
--execution.retryAttempts |
number | Number of retry attempts when calling execution engine API | 3 |
--execution.retryDelay |
number | Delay time in milliseconds between retries when retrying calls to the execution engine API | 2000 |
--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. | |
--builder |
boolean | Enable builder interface | |
--builder.urls |
array | Urls hosting the builder API | http://localhost:8661 |
--builder.timeout |
number | Timeout in milliseconds for builder API HTTP client | 12000 |
--builder.faultInspectionWindow |
number | Window to inspect missed slots for enabling/disabling builder circuit breaker | |
--builder.allowedFaults |
number | Number of missed slots allowed in the faultInspectionWindow for builder circuit |
|
--metrics |
boolean | Enable the Prometheus metrics HTTP server | |
--metrics.port |
number | Listen TCP port for the Prometheus metrics HTTP server | 8008 |
--metrics.address |
string | Listen address for the Prometheus metrics HTTP server | 127.0.0.1 |
--monitoring.endpoint |
string | Enables monitoring service for sending clients stats to the specified endpoint of a remote service (e.g. beaconcha.in) | |
--monitoring.interval |
number | Interval in milliseconds between sending client stats to the remote service | 60000 |
--discv5 |
boolean | Enable discv5 | true |
--listenAddress |
string | The IPv4 address to listen for p2p UDP and TCP connections | 0.0.0.0 |
--port |
number | The TCP/UDP port to listen on. The UDP port can be modified by the --discoveryPort flag. | 9000 |
--discoveryPort |
number | The UDP port that discovery will listen on. Defaults to port |
port |
--listenAddress6 |
string | The IPv6 address to listen for p2p UDP and TCP connections | |
--port6 |
number | The TCP/UDP port to listen on. The UDP port can be modified by the --discoveryPort6 flag. | 9090 |
--discoveryPort6 |
number | The UDP port that discovery will listen on. Defaults to port6 |
port6 |
--bootnodes |
array | Bootnodes for discv5 discovery | [] |
--targetPeers |
number | The target connected peers. Above this number peers will be disconnected | 50 |
--deterministicLongLivedAttnets |
boolean | Use deterministic subnet selection for long-lived subnet subscriptions | true |
--subscribeAllSubnets |
boolean | Subscribe to all subnets regardless of validator count | false |
--disablePeerScoring |
boolean | Disable peer scoring, used for testing on devnets | false |
--mdns |
boolean | Enable mdns local peer discovery | false |
--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 | |
--nat |
boolean | Allow configuration of non-local addresses |
validator
¶
Run one or multiple validator clients
Examples
Run one validator client with all the keystores available in the directory .goerli/keystores
validator --network goerli
Options
The options below apply to all sub-commands.
Option | Type | Description | Default |
---|---|---|---|
--logLevel |
string | Logging verbosity level for emitting logs to terminal | info |
--logFile |
string | Path to output all logs to a persistent log file, use 'none' to disable | |
--logFileLevel |
string | Logging verbosity level for emitting logs to file | debug |
--logFileDailyRotate |
number | Daily rotate log files, set to an integer to limit the file count, set to 0 (zero) to disable rotation | 5 |
--keymanager |
boolean | Enable key manager API server | |
--keymanager.authEnabled |
boolean | Enable token bearer authentication for key manager API server | true |
--keymanager.port |
number | Set port for key manager API | 5062 |
--keymanager.address |
string | Set host for key manager API | 127.0.0.1 |
--keymanager.cors |
string | Configures the Access-Control-Allow-Origin CORS header for key manager API | * |
--beaconNodes |
array | Addresses 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) | |
--proposerSettingsFile |
string | A yaml file to specify detailed default and per validator public key customized proposer configs. PS: This feature and its format is in alpha and subject to change | |
--suggestedFeeRecipient |
string | Specify fee recipient default for collecting the EL block fees and rewards (a hex string representing 20 bytes address: ^0x[a-fA-F0-9]{40}$). It would be possible (WIP) to override this per validator key using config or key manager API. Only used post merge. | 0x0000000000000000000000000000000000000000 |
--strictFeeRecipientCheck |
boolean | Enable strict checking of the validator's feeRecipient with the one returned by engine |
|
--defaultGasLimit |
number | Suggested gas limit to the engine/builder for building execution payloads. Only used post merge. | 30000000 |
--builder |
boolean | Enable execution payload production via a builder for better rewards | |
--builder.selection |
string | Default builder block selection strategy: maxprofit , builderalways , or builderonly |
maxprofit |
--importKeystores |
array | Path(s) to a directory or single file path to validator keystores, i.e. Launchpad validators | ./keystores/*.json |
--importKeystoresPassword |
string | Path to a file with password to decrypt all keystores from importKeystores option |
./password.txt |
--doppelgangerProtection |
boolean | Enables Doppelganger protection | |
--externalSigner.url |
string | URL to connect to an external signing server | |
--externalSigner.pubkeys |
array | List of validator public keys used by an external signer. May also provide a single string a comma separated public keys | |
--externalSigner.fetch |
boolean | Fetch then list of public keys to validate from an external signer | |
--distributed |
boolean | Enables specific features required to run as part of a distributed validator cluster | |
--metrics |
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 |
--monitoring.endpoint |
string | Enables monitoring service for sending clients stats to the specified endpoint of a remote service (e.g. beaconcha.in) | |
--monitoring.interval |
number | Interval in milliseconds between sending client stats to the remote service | 60000 |
validator slashing-protection
¶
Import or export slashing protection data to or from another client.
Options
The options below apply to all sub-commands.
Option | Type | Description | Default |
---|---|---|---|
--beaconNodes |
array | Addresses 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 |
validator slashing-protection import
¶
Import an interchange file.
Examples
Import an interchange file to the slashing protection DB
validator slashing-protection import --network goerli --file interchange.json
Options
Option | Type | Description | Default |
---|---|---|---|
--file |
string | The slashing protection interchange file to import (.json). |
validator slashing-protection export
¶
Export an interchange file.
Examples
Export an interchange JSON file for all validators in the slashing protection DB
validator slashing-protection export --network goerli --file interchange.json
Options
Option | Type | Description | Default |
---|---|---|---|
--file |
string | The slashing protection interchange file to export to (.json). | |
--pubkeys |
array | Export slashing protection data only for a given subset of public keys |
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
validator import --network goerli --importKeystores $HOME/staking-deposit-cli/validator_keys
Options
Option | Type | Description | Default |
---|---|---|---|
--importKeystores |
array | Path(s) to a directory or single file path to validator keystores, i.e. Launchpad validators | ./keystores/*.json |
--importKeystoresPassword |
string | Path to a file with password to decrypt all keystores from importKeystores option |
./password.txt |
validator list
¶
Lists the public keys of all validators
Examples
List all validator public keys previously imported
validator list
validator voluntary-exit
¶
Performs a voluntary exit for a given set of validators as identified via pubkeys
. If no pubkeys
are provided, it will exit all validators that have been imported.
Examples
Perform a voluntary exit for the validator who has a public key 0xF00
validator voluntary-exit --network goerli --pubkeys 0xF00
Options
Option | Type | Description | Default |
---|---|---|---|
--exitEpoch |
number | The epoch upon which to submit the voluntary exit. If no value is provided, then we default to the current epoch. | |
--pubkeys |
array | Public keys to exit, must be available as local signers | |
--yes |
boolean | Skip confirmation prompt |
validator bls-to-execution-change
¶
Performs BLS To Execution Change 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 BLS To Execution Change.
Examples
Perform BLS To Execution Change for the validator who has a public key 0xF00
validator bls-to-execution-change --publicKey 0xF00 --fromBlsPrivkey ... --toExecutionAddress ...
Options
Option | Type | Description | Default |
---|---|---|---|
--publicKey |
string | Validator public key for which to set withdrawal address hence enabling withdrawals | |
--fromBlsPrivkey |
string | Bls withdrawals private key to sign the message | |
--toExecutionAddress |
string | Address to which the validator's balances will be set to be withdrawn. |
lightclient
¶
Run lightclient
Examples
Run lightclient with goerli network
lightclient --network goerli
Options
Option | Type | Description | Default |
---|---|---|---|
--logLevel |
string | Logging verbosity level for emitting logs to terminal | info |
--logFile |
string | Path to output all logs to a persistent log file, use 'none' to disable | |
--logFileLevel |
string | Logging verbosity level for emitting logs to file | debug |
--logFileDailyRotate |
number | Daily rotate log files, set to an integer to limit the file count, set to 0 (zero) to disable rotation | 5 |
--beaconApiUrl |
string | Url to a beacon node that support lightclient API | |
--checkpointRoot |
string | Checkpoint root hex string to sync the lightclient from, start with 0x |
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 |
---|---|---|---|
--keymanager |
boolean | Enable key manager API server | |
--keymanager.authEnabled |
boolean | Enable token bearer authentication for key manager API server | true |
--keymanager.port |
number | Set port for key manager API | 5062 |
--keymanager.address |
string | Set host for key manager API | 127.0.0.1 |
--keymanager.cors |
string | Configures the Access-Control-Allow-Origin CORS header for key manager API | * |
--beaconNodes |
array | Addresses 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) | |
--proposerSettingsFile |
string | A yaml file to specify detailed default and per validator public key customized proposer configs. PS: This feature and its format is in alpha and subject to change | |
--strictFeeRecipientCheck |
boolean | Enable strict checking of the validator's feeRecipient with the one returned by engine |
|
--defaultGasLimit |
number | Suggested gas limit to the engine/builder for building execution payloads. Only used post merge. | 30000000 |
--builder.selection |
string | Default builder block selection strategy: maxprofit , builderalways , or builderonly |
maxprofit |
--importKeystores |
array | Path(s) to a directory or single file path to validator keystores, i.e. Launchpad validators | ./keystores/*.json |
--importKeystoresPassword |
string | Path to a file with password to decrypt all keystores from importKeystores option |
./password.txt |
--doppelgangerProtection |
boolean | Enables Doppelganger protection | |
--externalSigner.url |
string | URL to connect to an external signing server | |
--externalSigner.pubkeys |
array | List of validator public keys used by an external signer. May also provide a single string a comma separated public keys | |
--externalSigner.fetch |
boolean | Fetch then list of public keys to validate from an external signer | |
--distributed |
boolean | Enables specific features required to run as part of a distributed validator cluster | |
--network |
string | Name of the Ethereum Consensus chain network to join | mainnet |
--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. | 8 |
--startValidators |
string | Start interop validators in inclusive range with notation '0..7' | |
--genesisTime |
number | genesis_time to initialize interop genesis state | now |
--reset |
boolean | To delete chain and validator directories | |
--dumpTestnetFiles |
string | Dump testnet files and exit |
bootnode
¶
Run a discv5 bootnode. This will NOT perform any beacon node functions, rather, it will run a discv5 service that allows nodes on the network to discover one another.
Options
Option | Type | Description | Default |
---|---|---|---|
--listenAddress |
string | The IPv4 address to listen for discv5 connections | 0.0.0.0 |
--port |
number | The UDP port to listen on | 9000 |
--listenAddress6 |
string | The IPv6 address to listen for discv5 connections | |
--port6 |
number | The UDP port to listen on | 9090 |
--bootnodes |
array | Additional bootnodes for discv5 discovery | [] |
--bootnodesFile |
string | Additional bootnodes for discv5 discovery file path | |
--persistNetworkIdentity |
boolean | Whether to reuse the same peer-id across restarts | true |
--enr.ip |
string | Override ENR IP entry | |
--enr.udp |
number | Override ENR UDP entry | |
--enr.ip6 |
string | Override ENR IPv6 entry | |
--enr.udp6 |
number | Override ENR (IPv6-specific) UDP entry | |
--nat |
boolean | Allow ENR configuration of non-local addresses | |
--logLevel |
string | Logging verbosity level for emitting logs to terminal | info |
--logFile |
string | Path to output all logs to a persistent log file, use 'none' to disable | |
--logFileLevel |
string | Logging verbosity level for emitting logs to file | debug |
--logFileDailyRotate |
number | Daily rotate log files, set to an integer to limit the file count, set to 0 (zero) to disable rotation | 5 |
--metrics |
boolean | Enable the Prometheus metrics HTTP server | |
--metrics.port |
number | Listen TCP port for the Prometheus metrics HTTP server | 8008 |
--metrics.address |
string | Listen address for the Prometheus metrics HTTP server | 127.0.0.1 |