Skip to main content

Subcommands

Use the Web3Signer subcommands to specify the platform being used:

  • web3signer [options] eth2 [Eth2 options]
  • web3signer [options] eth2 export [Eth2 export options]
  • web3signer [options] eth2 import [Eth2 import options]
  • web3signer [options] eth1
  • web3signer [options] filecoin [Filecoin options]
  • web3signer [options] watermark-repair [watermark repair options]
note

This documentation has been updated in line with the name changes recommended by the Ethereum Foundation. The eth1 subcommands relate to the execution layer, previously called “Ethereum 1.0.” The eth2 subcommands relate to the consensus layer, previously called “Ethereum 2.0.”

Specify subcommand options​

The subcommand must be specified on the command line, but the subcommand options can be specified:

  • On the command line.
  • As environment variables. For each subcommand option, the equivalent environment variable is:
    • Uppercase.
    • _ replaces -.
    • Has a WEB3SIGNER_ + <SIGNING_OPTION>_ prefix.
  • In a YAML configuration file.

For example, you can set the --network option for the filecoin subcommand in an environment variable export WEB3SIGNER_FILECOIN_NETWORK=TESTNET, but the subcommand must be specified in the command line.

web3signer --key-store-path=/Users/me/keyFiles/ filecoin

View help​

To view the command line help for the subcommands:

Options​

eth1​

azure-vault-enabled​

--azure-vault-enabled=<BOOLEAN>

Enables bulk loading keys from Azure Key Vault. The default is false.

azure-client-id​

--azure-client-id=<STRING>

ID used to authenticate with Azure Key Vault.

Required when --azure-vault-auth-mode is CLIENT_SECRET or USER_ASSIGNED_MANAGED_IDENTITY.

azure-client-secret​

--azure-client-secret=<STRING>

The secret used to access the vault along with the ID specified in azure-client-id.

azure-tags​

--azure-tags=<TAG_NAME=TAG_VALUE>

Tags to filter on with Azure Key Vault.

azure-tenant-id​

--azure-tenant-id=<STRING>

The tenant ID of the Azure Portal instance being used.

azure-vault-auth-mode​

--azure-vault-auth-mode=<STRING>

Authentication mode for Azure Vault. Options are CLIENT_SECRET, SYSTEM_ASSIGNED_MANAGED_IDENTITY, and USER_ASSIGNED_MANAGED_IDENTITY. The default is CLIENT_SECRET.

Set --azure-client-id if using CLIENT_SECRET or USER_ASSIGNED_MANAGED_IDENTITY.

azure-vault-name​

--azure-vault-name=<STRING>

Name of the vault to access. Subdomain of vault.azure.net.

downstream-http-host​

--downstream-http-host=<downstreamHttpHost>

Host to which received requests are forwarded. The default is localhost.

downstream-http-path​

--downstream-http-path=<downstreamHttpPath>

Path to which received requests are forwarded. The default is /.

This might be required if connecting to a cloud-based Ethereum client such as Infura.

downstream-http-port​

--downstream-http-port=<downstreamHttpPort>

Port to which received requests are forwarded.

downstream-http-proxy-host​

--downstream-http-proxy-host=<HOST>

Hostname for proxy. There's no proxy if set to null. The default is null.

downstream-http-proxy-port​

--downstream-http-proxy-port=<PORT>

Port for proxy. The default is 80.

downstream-http-proxy-username​

--downstream-http-proxy-username=<username>

Username for proxy. There's no authentication if set to null. The default is null.

downstream-http-proxy-password​

--downstream-http-proxy-password=<password>

Password for proxy. There's no authentication if set to null. The default is null.

downstream-http-request-timeout​

--downstream-http-request-timeout=<downstreamHttpRequestTimeout>

Timeout period (in milliseconds) for downstream requests. The default is 5000.

downstream-http-tls-enabled​

--downstream-http-tls-enabled=<BOOLEAN>

Enables or disables TLS for server connections. The default is false.

downstream-http-tls-known-servers-file​

--downstream-http-tls-known-servers-file=<FILE>

File containing the hostnames, ports, and SHA256 certificate fingerprints of trusted servers.

downstream-http-tls-ca-auth-enabled​

--downstream-http-tls-ca-auth-enabled=<BOOLEAN>

Enables or disables connections to servers with trusted CAs. The default is true.

keystores-password-file​

--keystores-password-file=<FILE>

File that contains the password used by all keystores. Cannot be set if --keystores-passwords-path is also specified.

note

Alternatively, use --keystores-passwords-path to specify a directory containing a separate password file for each keystore.

keystores-passwords-path​

--keystores-passwords-path=<PATH>

Directory containing password files for corresponding keystores. Each password file name must match the corresponding keystore filename, but with a .txt extension.

Cannot be set if --keystores-password-file is also specified.

note

Alternatively, use --keystores-password-file to specify a single password file that contains the password used by all keystores.

keystores-path​

--keystores-path=<PATH>

Directory that stores the keystore files. Keystore files must use a .json file extension.

Use --keystores-password-file or --keystores-passwords-path to specify keystore passwords.

Important

Restart Web3Signer if you want to pick up new keystores added to the directory since Web3Signer started.

eth2​

aws-connection-cache-size​

--aws-connection-cache-size=<LONG>

When loading multiple keys from AWS Secrets Manager, set to the maximum number of connections to cache. The default is 1.

aws-endpoint-override​

--aws-endpoint-override=<ENDPOINT_URL>

Endpoint override for AWS Secrets Manager. This is useful for local testing against LocalStack.

aws-secrets-enabled​

--aws-secrets-enabled=<BOOLEAN>

Enables or disables bulk loading keys from AWS Secrets Manager. The default is false.

aws-secrets-auth-mode​

--aws-secrets-auth-mode=<STRING>

Authentication mode for AWS Secrets Manager. Options are SPECIFIED and ENVIRONMENT. The default is SPECIFIED.

Set --aws-secrets-access-key-id, --aws-secrets-secret-access-key, and --aws-secrets-region if using SPECIFIED.

aws-secrets-access-key-id​

--aws-secrets-access-key-id=<STRING>

AWS access key ID to authenticate AWS Secrets Manager.

Required when --aws-secrets-auth-mode is SPECIFIED.

aws-secrets-secret-access-key​

--aws-secrets-secret-access-key=<STRING>

AWS secret access key to authenticate AWS Secrets Manager.

Required when --aws-secrets-auth-mode is SPECIFIED.

aws-secrets-region​

--aws-secrets-region=<STRING>

AWS region where AWS Secrets Manager is available.

Required when --aws-secrets-auth-mode is SPECIFIED.

aws-secrets-prefixes-filter​

--aws-secrets-prefixes-filter=<STRING>[,<STRING>,...]

Optional comma-separated list of secret name prefixes filter to apply while fetching secrets from AWS Secrets Manager. Applied as AND operation with other filters.

aws-secrets-tag-names-filter​

--aws-secrets-tag-names-filter=<STRING>[,<STRING>,...]

Optional comma-separated list of tag names filter to apply while fetching secrets from AWS Secrets Manager. Applied as AND operation with other filters.

aws-secrets-tag-values-filter​

--aws-secrets-tag-values-filter=<STRING>[,<STRING>,...]

Optional comma-separated list of tag values filter to apply while fetching secrets from AWS Secrets Manager. Applied as AND operation with other filters.

azure-vault-enabled​

--azure-vault-enabled=<BOOLEAN>

Enables bulk loading keys from Azure Key Vault. The default is false.

azure-client-id​

--azure-client-id=<STRING>

ID used to authenticate with Azure Key Vault.

Required when --azure-vault-auth-mode is CLIENT_SECRET or USER_ASSIGNED_MANAGED_IDENTITY.

azure-client-secret​

--azure-client-secret=<STRING>

The secret used to access the vault along with the ID specified in azure-client-id.

azure-tags​

--azure-tags=<TAG_NAME=TAG_VALUE>

Tags to filter on using Azure Key Vault.

azure-tenant-id​

--azure-tenant-id=<STRING>

The tenant ID of the Azure Portal instance being used.

azure-vault-auth-mode​

--azure-vault-auth-mode=<STRING>

Authentication mode for Azure Vault. Options are CLIENT_SECRET, SYSTEM_ASSIGNED_MANAGED_IDENTITY, and USER_ASSIGNED_MANAGED_IDENTITY. The default is CLIENT_SECRET.

Set --azure-client-id if using CLIENT_SECRET or USER_ASSIGNED_MANAGED_IDENTITY.

azure-vault-name​

--azure-vault-name=<STRING>

Name of the vault to access. Subdomain of vault.azure.net.

key-manager-api-enabled​

--key-manager-api-enabled=<BOOLEAN>

Enables the key manager API. The default is false.

Warning

The key manager API is an early access feature and is still in development.

keystores-password-file​

--keystores-password-file=<FILE>

File that contains the password used by all keystores. Cannot be set if --keystores-passwords-path is also specified.

note

Alternatively, use --keystores-passwords-path to specify a directory containing a separate password file for each keystore.

keystores-passwords-path​

--keystores-passwords-path=<PATH>

Directory containing password files for corresponding keystores. Each password file name must match the corresponding keystore filename, but with a .txt extension.

Cannot be set if --keystores-password-file is also specified.

note

Alternatively, use --keystores-password-file to specify a single password file that contains the password used by all keystores.

keystores-path​

--keystores-path=<PATH>

Directory that stores the keystore files. Keystore files must use a .json file extension.

Use --keystores-password-file or --keystores-passwords-path to specify keystore passwords.

Important

Restart Web3Signer if you want to pick up new keystores added to the directory since Web3Signer started.

network​

--network=<NETWORK>

Predefined network configuration. Accepts a predefined network name, or file path or URL to a YAML configuration file. See the consensus specification for examples.

The default is mainnet.

Important

If Teku connects to a network other than mainnet, then this option must be specified, and it must match the --network value of the connected Teku client.

Possible values are:

NetworkChainTypeDescription
mainnetConsensus layerProductionMain network.
minimalConsensus layerTestUsed for local testing and development networks.
goerliConsensus layerTestMulti-client testnet.
kilnConsensus layerTestMulti-client testnet.
ropstenConsensus layerTestMulti-client testnet.
gnosisConsensus layerTestMulti-client testnet.

slashing-protection-db-health-check-interval-milliseconds​

--slashing-protection-db-health-check-interval-milliseconds=<INTERVAL>

Milliseconds between the slashing protection database health checks. The default is 30000.

The service responds with a 200 message if healthy, and 503 if unhealthy.

slashing-protection-db-health-check-timeout-milliseconds​

--slashing-protection-db-health-check-timeout-milliseconds=<INTERVAL>

Milliseconds after which to fail the database health check. For example, if the health check connects to the slashing protection database, but does not report back in a timely manner.

The default is 3000.

slashing-protection-db-password​

--slashing-protection-db-password=<PASSWORD>

The password to connect to the slashing protection database.

slashing-protection-db-pool-configuration-file​

--slashing-protection-db-pool-configuration-file=<FILE>

HikariCP connection pool configuration file.

Web3Signer uses HikariCP to manage database connections, and uses the default configuration values. The defaults perform well in most deployments, but you can override them using this option.

slashing-protection-db-url​

--slashing-protection-db-url=<JDBC_URL>

The Java Database Connectivity (JDBC) URL of the slashing protection database.

note

If using a non-default port number for your PostgreSQL database, then include the port number in the database URL.

slashing-protection-db-username​

--slashing-protection-db-username=<USERNAME>

The username to use when connecting to the slashing protection database.

slashing-protection-enabled​

--slashing-protection-enabled=<BOOLEAN>

Enables Web3Signer slashing protection. If true, then all signing operations are validated against historical data before signing.

The default is true.

slashing-protection-pruning-at-boot-enabled​

--slashing-protection-pruning-at-boot-enabled=<BOOLEAN>

When set to true, slashing protection database pruning is enabled at startup and at the defined pruning intervals.

The default is false.

slashing-protection-pruning-db-pool-configuration-file​

--slashing-protection-pruning-db-pool-configuration-file=<FILE>

HikariCP connection pool configuration file used by the pruning process.

Web3Signer uses HikariCP to manage database connections, and uses the default configuration values. The defaults perform well in most deployments, but you can override them using this option.

slashing-protection-pruning-enabled​

--slashing-protection-pruning-enabled=<BOOLEAN>

Enables slashing protection database pruning. The default is false.

slashing-protection-pruning-epochs-to-keep​

--slashing-protection-pruning-epochs-to-keep=<LONG>

Number of epochs to keep when pruning the slashing protection database.

The default is 250.

slashing-protection-pruning-interval​

--slashing-protection-pruning-interval=<LONG>

Hours between slashing protection database pruning operations.

The default is 24.

slashing-protection-pruning-slots-per-epoch​

--slashing-protection-pruning-slots-per-epoch=<LONG>

Number of slots per epoch. This number multiplied by the number of epochs to keep determines what blocks to keep when pruning the slashing protection database.

The default is 32 as defined on Mainnet.

eth2 export​

Exports the slashing protection database to a file.

to​

--to=<FILE>

The file to export the slashing protection database to. The exported file uses the validator client interchange format.

eth2 import​

Imports a slashing protection database from a file.

from​

--from=<FILE>

The file to import the slashing protection database from. The file must be formatted in the validator client interchange format.

filecoin​

network​

--network=<NETWORK>

Predefined network configuration. Accepts a predefined network name. The default is TESTNET.

watermark-repair​

Updates the slashing protection low watermark for validators. You can only increase the low watermark, not decrease it.

epoch​

--epoch=<LONG>

Low watermark to set the attestation source and target to.

slot​

--slot=<LONG>

Low watermark to set the block slot to.

validator-ids​

--validator-ids=<KEY>[,<KEY>,...]

List of validator public keys as hexadecimal to apply low watermark update to. If none are specified, the low watermark is updated for all validators.