Skip to content

validator CLI Command


Run one or multiple validator clients


Available Sub-Commands

The following sub-commands are available with the validator command:


Examples

Base validator command

Run one validator client with all the keystores available in the directory .goerli/keystores

./lodestar validator --network goerli


validator Options

--dataDir

description: Lodestar root data directory

type: string


--network

description: Name of the Ethereum Consensus chain network to join

type: string

choices: "mainnet", "gnosis", "goerli", "ropsten", "sepolia", "holesky", "chiado", "ephemery", "dev"

default: "mainnet"


--paramsFile

description: Network configuration file

type: string


--terminal-total-difficulty-override

description: Terminal PoW block TTD override

type: string


--terminal-block-hash-override

description: Terminal PoW block hash override

type: string


--terminal-block-hash-epoch-override

description: Terminal PoW block hash override activation epoch

type: string


--logLevel

description: Logging verbosity level for emitting logs to terminal

type: string

choices: "error", "warn", "info", "verbose", "debug", "trace"

default: "info"


--logFile

description: Path to output all logs to a persistent log file, use 'none' to disable

type: string


--logFileLevel

description: Logging verbosity level for emitting logs to file

type: string

choices: "error", "warn", "info", "verbose", "debug", "trace"

default: "debug"


--logFileDailyRotate

description: Daily rotate log files, set to an integer to limit the file count, set to 0 (zero) to disable rotation

type: number

default: 5


--keymanager

description: Enable key manager API server

type: boolean


--keymanager.authEnabled

description: Enable token bearer authentication for key manager API server

type: boolean

default: true


--keymanager.port

description: Set port for key manager API

type: number

default: 5062


--keymanager.address

description: Set host for key manager API

type: string

default: "127.0.0.1"


--keymanager.cors

description: Configures the Access-Control-Allow-Origin CORS header for key manager API

type: string

default: "*"


--beaconNodes

description: Addresses to connect to BeaconNode

type: string[]

default: [ "http://127.0.0.1:9596" ]


--force

description: Open validators even if there's a lockfile. Use with caution

type: boolean


--graffiti

description: Specify your custom graffiti to be included in blocks (plain UTF8 text, 32 characters max)

type: string


--proposerSettingsFile

description: 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

type: string


--suggestedFeeRecipient

description: 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.

type: string

default: "0x0000000000000000000000000000000000000000"


--strictFeeRecipientCheck

description: Enable strict checking of the validator's feeRecipient with the one returned by engine

type: boolean


--defaultGasLimit

description: Suggested gas limit to the engine/builder for building execution payloads. Only used post merge.

type: number

default: 30000000


--builder

description: An alias for --builder.selection maxprofit for the builder flow, ignored if --builder.selection is explicitly provided

type: boolean


--builder.selection

description: Builder block selection strategy maxprofit, builderalways, builderonly, executionalways, or executiononly

type: string

default: "executiononly"


--builder.boostFactor

description: Percentage multiplier the block producing beacon node must apply to boost (>100) or dampen (<100) builder block value for selection against execution block. The multiplier is ignored if --builder.selection is set to anything other than maxprofit

type: string

default: "100"


--useProduceBlockV3

description: Enable/disable usage of produceBlockV3 for block production, is auto enabled on deneb+ blocks

type: boolean


--broadcastValidation

description: Validations to be run by beacon node for the signed block prior to publishing

type: string

default: "gossip"


--blindedLocal

description: Request fetching local block in blinded format for produceBlockV3

type: boolean

default: false


--importKeystores

description: Path(s) to a directory or single file path to validator keystores, i.e. Launchpad validators

type: string[]

default: [ "./keystores/*.json" ]


--importKeystoresPassword

description: Path to a file with password to decrypt all keystores from importKeystores option

type: string

default: "./password.txt"


--doppelgangerProtection

description: Enables Doppelganger protection

type: boolean


--externalSigner.url

description: URL to connect to an external signing server

type: string


--externalSigner.pubkeys

description: List of validator public keys used by an external signer. May also provide a single string of comma-separated public keys

type: string[]


--externalSigner.fetch

description: Fetch the list of public keys to validate from an external signer. Cannot be used in combination with --externalSigner.pubkeys

type: boolean


--distributed

description: Enables specific features required to run as part of a distributed validator cluster

type: boolean


--metrics

description: Enable the Prometheus metrics HTTP server

type: boolean

default: false


--metrics.port

description: Listen TCP port for the Prometheus metrics HTTP server

type: number

default: 5064


--metrics.address

description: Listen address for the Prometheus metrics HTTP server

type: string

default: "127.0.0.1"


--monitoring.endpoint

description: Enables monitoring service for sending clients stats to the specified endpoint of a remote service (e.g. beaconcha.in)

type: string


--monitoring.interval

description: Interval in milliseconds between sending client stats to the remote service

type: number

default: 60000



validator slashing-protection import

Import an interchange file.

validator slashing-protection import Options

Supports all parent command options plus the following:


--beaconNodes

description: Addresses to connect to BeaconNode

type: string[]

default: [ "http://127.0.0.1:9596" ]


--force

description: If genesisValidatorsRoot can't be fetched from the Beacon node, use a zero hash

type: boolean


--file

description: The slashing protection interchange file to import (.json).

required: true

type: string



validator slashing-protection export

Export an interchange file.

validator slashing-protection export Options

Supports all parent command options plus the following:


--beaconNodes

description: Addresses to connect to BeaconNode

type: string[]

default: [ "http://127.0.0.1:9596" ]


--force

description: If genesisValidatorsRoot can't be fetched from the Beacon node, use a zero hash

type: boolean


--file

description: The slashing protection interchange file to export to (.json).

required: true

type: string


--pubkeys

description: Export slashing protection data only for a given subset of public keys

type: string[]



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.

validator import Examples

Import validator keystores generated with the Ethereum Foundation Staking Launchpad

./lodestar validator import --network goerli --importKeystores $HOME/staking-deposit-cli/validator_keys

validator import Options

Supports all parent command options plus the following:


--importKeystores

description: Path(s) to a directory or single file path to validator keystores, i.e. Launchpad validators

type: string[]

default: [ "./keystores/*.json" ]


--importKeystoresPassword

description: Path to a file with password to decrypt all keystores from importKeystores option

type: string

default: "./password.txt"



validator list

Lists the public keys of all validators

validator list Examples

List all validator public keys previously imported

./lodestar 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.

validator voluntary-exit Examples

Perform a voluntary exit for the validator who has a public key 0xF00

./lodestar validator voluntary-exit --network goerli --pubkeys 0xF00

Perform a voluntary exit for the validator who has a public key 0xF00 and its secret key is on a remote signer

./lodestar validator voluntary-exit --network goerli --externalSigner.url http://signer:9000 --externalSigner.fetch --pubkeys 0xF00

validator voluntary-exit Options

Supports all parent command options plus the following:


--exitEpoch

description: The epoch upon which to submit the voluntary exit. If no value is provided, then we default to the current epoch.

type: number


--pubkeys

description: Public keys to exit

type: string[]


--yes

description: Skip confirmation prompt

type: boolean



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.

validator bls-to-execution-change Examples

Perform BLS To Execution Change for the validator who has a public key 0xF00

./lodestar validator bls-to-execution-change --publicKey 0xF00 --fromBlsPrivkey ... --toExecutionAddress ...

validator bls-to-execution-change Options

Supports all parent command options plus the following:


--publicKey

description: Validator public key for which to set withdrawal address hence enabling withdrawals

required: true

type: string


--fromBlsPrivkey

description: Bls withdrawals private key to sign the message

required: true

type: string


--toExecutionAddress

description: Address to which the validator's balances will be set to be withdrawn.

required: true

type: string