Skip to main content
Version: development

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] 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 --chain-id option for the eth1 subcommand in an environment variable export WEB3SIGNER_ETH1_CHAIN_ID=2017, but the subcommand must be specified in the command line.

View help​

To view the command line help for the subcommands:

Options​

eth1​

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 KMS. Useful for local testing against LocalStack.

aws-kms-access-key-id​

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

AWS Access Key ID to authenticate AWS KMS. Required when --aws-kms-auth-mode is SPECIFIED.

aws-kms-auth-mode​

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

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

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

aws-kms-client-cache-size​

--aws-kms-client-cache-size=<LONG>

AWS KMS client cache size. Set to the total number of credentials used to access the service plus the number of regions the service is accessed from. The default is 1.

aws-kms-enabled​

--aws-kms-enabled=<BOOLEAN>

Set to true to enable bulk loading from the AWS KMS. The default is false.

aws-kms-region​

--aws-kms-region=<STRING>

AWS region where AWS KMS is available.

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

aws-kms-secret-access-key​

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

AWS secret access key to authenticate AWS KMS. Required when --aws-kms-auth-mode is SPECIFIED.

aws-kms-tag-names-filter​

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

Optional comma-separated list of tag names filter to apply while fetching key IDs from AWS KMS. Applied as AND operation with other filters.

aws-kms-tag-values-filter​

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

Optional comma-separated list of tag values filter to apply while fetching key IDs from AWS KMS. 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-response-timeout​

--azure-response-timeout=<AZURE_RESPONSE_TIMEOUT>

The response timeout used by the HTTP client (in seconds). The default is 60. You can also set the timeout using the timeout field in the Azure metadata file.

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.

chain-id​

--chain-id=<LONG>

ID of the chain to receive the signed transactions. The Besu documentation lists chain IDs for public networks.

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-response-timeout​

--azure-response-timeout=<AZURE_RESPONSE_TIMEOUT>

The response timeout used by the HTTP client (in seconds). The default is 60. You can also set the timeout using the timeout field in the Azure metadata file.

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.

gcp-project-id​

--gcp-project-id=<STRING>

Globally unique identifier for the Google Cloud Platform (GCP) project where the secrets to be used by Web3Signer are stored.

gcp-secrets-enabled​

--gcp-secrets-enabled=<BOOLEAN>

Set to true to enable bulk loading from the GCP Secrets Manager service. The default is false.

gcp-secrets-filter​

--gcp-secrets-filter=<STRING>

Filter to use when loading secrets into Web3Signer. List operation filtering is applied.

Only secrets matching the filter are loaded. If not specified, all secrets from the project identified by --gcp-project-id are loaded.

key-manager-api-enabled​

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

Enables the key manager API. The default is false.

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 layerProductionEthereum main network.
minimalConsensus layerTestUsed for local testing and development networks.
sepoliaConsensus layerTestMulti-client permissioned testnet.
holeskyConsensus layerTestMulti-client testnet.
luksoConsensus layerProductionLukso main network.
gnosisConsensus layerProductionGnosis main network.
chiadoConsensus layerTestMulti-client Gnosis 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.

watermark-repair​

Updates the slashing protection low or high watermark for all validators. You can only increase the low watermark, not decrease it. If you set the high watermark, you should set this to a future epoch and slot. Setting a high watermark prevents the validator from signing at or beyond this point.

caution

We only recommend this subcommand for advanced users.

epoch​

--epoch=<LONG>

Low watermark to set the attestation source and target to. (Sets the high watermark epoch when --set-high-watermark is true.)

slot​

--slot=<LONG>

Low watermark to set the block slot to. (Sets the high watermark slot when --set-high-watermark is true.)

remove-high-watermark​

--remove-high-watermark=<BOOLEAN>

Removes the high watermark. When set to true, all other watermark-repair options are ignored. The default is false.

set-high-watermark​

--set-high-watermark=<BOOLEAN>

Sets the high watermark to the specified epoch and slot. (Sets the low watermark when --set-high-watermark is false.) The default is false.