Skip to main content
Version: development

validator-client, vc

Run a validator client that connects to a remote beacon node.

beacon-node-api-endpoint, beacon-node-api-endpoints​

teku vc --beacon-node-api-endpoint=<ENDPOINT>[,<ENDPOINT>...]...

Endpoint of the beacon node's REST API. You can configure multiple beacon nodes by providing a comma-separated list of beacon node API endpoints.

If multiple beacon node endpoints are configured, the first one is used as primary and others as failovers.

note

This option cannot be used with the sentry beacon nodes early access feature.

The default is http://127.0.0.1:5051.

beacon-node-ssz-blocks-enabled​

teku vc --beacon-node-ssz-blocks-enabled=<BOOLEAN>

Enable or disable the use of SSZ encoding for API requests to the beacon node to create blocks. The default is true.

config-file​

teku vc --config-file=<FILE>

Path to the YAML configuration file. The default is none.

data-base-path, data-path​

teku vc --data-base-path=<PATH>

Path to the Teku base directory for storage. The default directory is OS-dependent:

  • macOS: ~/Library/teku
  • Unix/Linux: $XDG_DATA_HOME/teku if $XDG_DATA_HOME is set; otherwise ~/.local/share/teku
  • Windows: %localappdata%\teku.

The default Docker image location is /root/.local/share/teku.

data-validator-path​

teku vc --data-validator-path=<PATH>

Path to the validator client data. The default is <data-base-path>/validator where <data-base-path> is specified using --data-base-path.

log-color-enabled​

teku vc --log-color-enabled[=<BOOLEAN>]

Specify whether status and event log messages include a console color display code. The default is true.

log-destination​

teku vc --log-destination=<LOG_DESTINATION>

Specify where to output log information. Valid options are:

  • BOTH
  • CONSOLE
  • DEFAULT_BOTH
  • FILE

The default is DEFAULT_BOTH. When using BOTH or DEFAULT_BOTH, system updates such as blockchain events are displayed on the console, and errors and other information are logged to a file. Specify the log file with the --log-file command-line option.

For production systems we recommend using the CONSOLE or FILE options to ensure all log information is available in one place.

note

Use DEFAULT_BOTH when using a custom Log4J2 configuration file. Any other option applies the custom logging changes on top of its default settings.

log-file​

teku vc --log-file=<FILENAME>

Relative or absolute location, and filename of the log file.

The default directory is OS-dependent:

  • macOS: ~/Library/teku/logs
  • Unix/Linux: $XDG_DATA_HOME/teku/logs if $XDG_DATA_HOME is set; otherwise ~/.local/share/teku/logs
  • Windows: %localappdata%\teku\logs

The default Docker image location is /root/.local/share/teku/logs.

log-file-name-pattern​

teku vc --log-file-name-pattern=<REGEX>

Filename pattern to apply when creating log files. The default pattern is teku_%d{yyyy-MM-dd}.log

log-include-events-enabled​

teku vc --log-include-events-enabled[=<BOOLEAN>]

Specify whether to log frequent update events. For example every slot event with validators and attestations. The default is true.

log-include-validator-duties-enabled​

teku vc --log-include-validator-duties-enabled[=<BOOLEAN>]

Specify whether to log details of validator event duties. The default is true.

note

Logs could become noisy when running many validators.

metrics-enabled​

teku vc --metrics-enabled[=<BOOLEAN>]

Set to true to enable the metrics exporter. The default is false.

metrics-host-allowlist​

teku vc --metrics-host-allowlist=<hostname>[,<hostname>...]... or "*"

A comma-separated list of hostnames to allow access to the [Teku metrics]. By default, Teku accepts access from localhost and 127.0.0.1.

tip

To allow all hostnames, use "*". We don't recommend allowing all hostnames for production environments.

metrics-categories​

teku vc --metrics-categories=<CATEGORY>[,<CATEGORY>...]...

Categories for which to track metrics. Options are JVM, PROCESS, BEACON, DISCOVERY, EVENTBUS, EXECUTOR, LIBP2P, NETWORK, STORAGE, STORAGE_HOT_DB, STORAGE_FINALIZED_DB, REMOTE_VALIDATOR, VALIDATOR, VALIDATOR_PERFORMANCE. All categories are enabled by default.

metrics-interface​

teku vc --metrics-interface=<HOST>

Host on which Prometheus accesses Teku metrics. The default is 127.0.0.1.

metrics-port​

teku vc --metrics-port=<PORT>

Specifies the port (TCP) on which Prometheus accesses Teku metrics. The default is 8008.

network​

teku vc --network=<NETWORK>

Predefined network configuration. The default is mainnet.

Use auto to fetch the network configuration from the beacon node endpoint directly.

validator-keys​

teku vc --validator-keys=<KEY_DIR>:<PASS_DIR> | <KEY_FILE>:<PASS_FILE>[,<KEY_DIR>:<PASS_DIR> | <KEY_FILE>:<PASS_FILE>...]...

Directory or file to load the encrypted keystore file(s) and associated password file(s) from. Keystore files must use the .json file extension, and password files must use the .txt file extension.

When specifying directories, Teku expects to find identically named keystore and password files. For example validator_217179e.json and validator_217179e.txt.

When specifying file names, Teku expects that the files exist.

note

The path separator is operating system dependent, and should be ; in Windows rather than :.

validators-early-attestations-enabled​

teku vc --validators-early-attestations-enabled[=<BOOLEAN>]

Specify whether to use Teku's built-in early attestation production, which creates an attestation once a block is received. The default is true.

Set this option to false if running a validator client connected to a load balanced beacon node (including most hosted beacon nodes such as [Infura]), and validator effectiveness is poor.

note

Delaying attestation production increases the chances of generating a correct attestation when using a load balanced beacon node, but it increases the risk of inclusion delays.

validators-external-signer-keystore​

teku vc --validators-external-signer-keystore=<FILE>

The keystore that Teku presents to the external signer for TLS authentication. Teku can use PKCS12 or JKS keystore types.

Use the PKCS12 keystore type if connecting to Web3Signer.

validators-external-signer-keystore-password-file​

teku vc --validators-external-signer-keystore-password-file=<FILE>

Password file used to decrypt the keystore.

validators-external-signer-public-keys​

teku vc --validators-external-signer-public-keys=<KEY>[,<KEY>...]

List or URL of validator public keys used by an external signer (for example, Web3Signer).

Use the URL to load the public keys from a remote service. For example:

--validators-external-signer-public-keys=http://localhost:9900/api/v1/eth2/publicKeys

Use the value external-signer to load all public keys managed by the external signer. Teku automatically queries the external signer's public keys endpoint.

--validators-external-signer-public-keys=external-signer

validators-external-signer-slashing-protection-enabled​

teku vc --validators-external-signer-slashing-protection-enabled[=<BOOLEAN>]

Specify whether to use Teku's built-in slashing protection when using an external signer such as Web3Signer. The default is true.

Set this option to false if using the slashing protection implemented by an external signer.

danger

Ensure the external signer has slashing protection enabled before disabling Teku slashing protection, otherwise a validator may get slashed.

Built-in slashing protection can only be disabled for validators using external signers. Validators using Teku to sign blocks and attestations always uses its built-in slashing protection.

validators-external-signer-timeout​

teku vc --validators-external-signer-timeout=<INTEGER>

Timeout in milliseconds for requests to the external signer. The default is 5000.

validators-external-signer-truststore​

teku vc --validators-external-signer-truststore=<FILE>

PKCS12 or JKS keystore used to trust external signer's self-signed certificate or CA certificate which signs the external signer's certificate.

validators-external-signer-truststore-password-file​

teku vc --validators-external-signer-truststore-password-file=<FILE>

Password file used to decrypt the keystore.

validators-external-signer-url​

teku vc --validators-external-signer-url=<URL>

URL on which the external signer (for example, Web3Signer) is running.

validators-graffiti​

teku vc --validators-graffiti=<STRING>

Graffiti to add when creating a block. Gets converted to bytes and padded to Bytes32.

The same graffiti is used for all validators started with this beacon node.

validators-graffiti-file​

teku vc --validators-graffiti-file=<FILE>

File containing the validator graffiti to add when creating a block. The file content is converted to bytes and padded to Bytes32. The same graffiti is used for all validators started with this beacon node.

You can overwrite the file while Teku is running to update the graffiti.

This option takes precedence over --validators-graffiti.

validators-keystore-locking-enabled​

teku vc --validators-keystore-locking-enabled=<BOOLEAN>

Locks the keystore files listed in --validator-keys. The default is true.

Attempts to lock all keystores in a directory if a directory is specified in --validator-keys.

validators-performance-tracking-mode​

teku vc --validators-performance-tracking-mode=<STRING>

Set the validator performance tracking strategy. Valid options are LOGGING, METRICS, ALL, and NONE. The default is ALL.

When LOGGING is enabled, attestation and block performance is reported as log messages. When METRICS is enabled, attestation and block performance is reported using metrics in the VALIDATOR_PERFORMANCE metrics category.