Skip to content
You are reading Web3Signer development version documentation and some displayed features may not be available in the stable release. You can switch to stable version using the version box at screen bottom.

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]

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.

Example

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

View help

To view the command line help for the subcommands:

Options

eth1

eth2

aws-connection-cache-size

--aws-connection-cache-size=<LONG>
--aws-connection-cache-size=5
WEB3SIGNER_ETH2_AWS_CONNECTION_CACHE_SIZE=5
eth2.aws-connection-cache-size: 5

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

aws-secrets-enabled

--aws-secrets-enabled=<BOOLEAN>
--aws-secrets-enabled=true
WEB3SIGNER_ETH2_AWS_SECRETS_ENABLED=true
eth2.aws-secrets-enabled: true

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

aws-secrets-auth-mode

--aws-secrets-auth-mode=<STRING>
--aws-secrets-auth-mode=ENVIRONMENT
WEB3SIGNER_ETH2_AWS_SECRETS_AUTH_MODE=ENVIRONMENT
eth2.aws-secrets-auth-mode: "ENVIRONMENT"

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-secrets-access-key-id=AKIAIOSFODNN7EXAMPLE
WEB3SIGNER_ETH2_AWS_SECRETS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
eth2.aws-secrets-access-key-id: "AKIAIOSFODNN7EXAMPLE"

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-secrets-secret-access-key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
WEB3SIGNER_ETH2_AWS_SECRETS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
eth2.aws-secrets-secret-access-key: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"

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-secrets-region=us-east-2
WEB3SIGNER_ETH2_AWS_SECRETS_REGION=us-east-2
eth2.aws-secrets-region: "us-east-2"

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>,...]
--aws-secrets-prefixes-filter=prefix1,prefix2
WEB3SIGNER_ETH2_AWS_SECRETS_PREFIXES_FILTER=prefix1,prefix2
eth2.aws-secrets-prefixes-filter: ["prefix1","prefix2"]

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>,...]
--aws-secrets-tag-names-filter=tagName1,tagName2
WEB3SIGNER_ETH2_AWS_SECRETS_TAG_NAMES_FILTER=tagName1,tagName2
eth2.aws-secrets-tag-names-filter: ["tagName1","tagName2"]

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>,...]
--aws-secrets-tag-values-filter=tagValue1,tagValue2
WEB3SIGNER_ETH2_AWS_SECRETS_TAG_VALUES_FILTER=tagValue1,tagValue2
eth2.aws-secrets-tag-values-filter: ["tagValue1","tagValue2"]

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>
--azure-vault-enabled=true
WEB3SIGNER_ETH2_AZURE_VAULT_ENABLED=true
eth2.azure-vault-enabled: true

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

azure-client-id

--azure-client-id=<STRING>
--azure-client-id=87efaa5b-4029-4b54-98bb2e2e8a11
WEB3SIGNER_ETH2_AZURE_CLIENT_ID=87efaa5b-4029-4b54-98bb2e2e8a11
eth2.azure-client-id: "87efaa5b-4029-4b54-98bb2e2e8a11"

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>
--azure-client-secret=0DgK4V_YA99RPk7.f_1op0-em_a46wSe.Z
WEB3SIGNER_ETH2_AZURE_CLIENT_SECRET=0DgK4V_YA99RPk7.f_1op0-em_a46wSe.Z
eth2.azure-client-secret: "0DgK4V_YA99RPk7.f_1op0-em_a46wSe.Z"

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

azure-tenant-id

--azure-tenant-id=<STRING>
--azure-tenant-id=34255fb0-379b-4a1a-bd47-d211ab86df81
WEB3SIGNER_ETH2_AZURE_TENANT_ID=34255fb0-379b-4a1a-bd47-d211ab86df81
eth2.azure-tenant-id: "34255fb0-379b-4a1a-bd47-d211ab86df81"

The tenant ID of the Azure Portal instance being used.

azure-vault-auth-mode

--azure-vault-auth-mode=<STRING>
--azure-vault-auth-mode=USER_ASSIGNED_MANAGED_IDENTITY
WEB3SIGNER_ETH2_AZURE_VAULT_AUTH_MODE=USER_ASSIGNED_MANAGED_IDENTITY
eth2.azure-vault-auth-mode: "USER_ASSIGNED_MANAGED_IDENTITY"

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>
--azure-vault-name=AzureKeyVault
WEB3SIGNER_ETH2_AZURE_VAULT_NAME=AzureKeyVault
eth2.azure-vault-name: "AzureKeyVault"

Name of the vault to access. Sub-domain of vault.azure.net.

key-manager-api-enabled

--key-manager-api-enabled=<BOOLEAN>
--key-manager-api-enabled=true
WEB3SIGNER_ETH2_KEY_MANAGER_API_ENABLED=true
eth2.key-manager-api-enabled: true

Enables the key manager API. The default is false.

Caution

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

keystores-password-file

--keystores-password-file=<FILE>
--keystores-password-file=/Users/me/passwds/keystore_passwords.txt
WEB3SIGNER_ETH2_KEYSTORES_PASSWORD_FILE=/Users/me/passwds/keystore_passwords.txt
eth2.keystores-password-file: "/Users/me/passwds/keystore_passwords.txt"

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>
--keystores-passwords-path=/Users/me/passwds
WEB3SIGNER_ETH2_KEYSTORES_PASSWORDS_PATH=/Users/me/passwds
eth2.keystores-passwords-path: "/Users/me/passwds"

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>
--keystores-path=/Users/me/keystores
WEB3SIGNER_ETH2_KEYSTORES_PATH=/Users/me/keystores
eth2.keystores-path: "/Users/me/keystores"

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>
--network=mainnet
WEB3SIGNER_ETH2_NETWORK=mainnet
network: "mainnet"

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:

Network Chain Type Description
mainnet Consensus layer Production Main network.
minimal Consensus layer Test Used for local testing and development networks.
prater Consensus layer Test Multi-client testnet.
kiln Consensus layer Test Multi-client testnet.
ropsten Consensus layer Test Multi-client testnet.
gnosis Consensus layer Test Multi-client testnet.

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

--slashing-protection-db-health-check-interval-milliseconds=<INTERVAL>
--slashing-protection-db-health-check-interval-milliseconds=20000
WEB3SIGNER_ETH2_SLASHING_PROTECTION_DB_HEALTH_CHECK_INTERVAL_MILLISECONDS=20000
eth2.slashing-protection-db-health-check-interval-milliseconds: 20000

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>
--slashing-protection-db-health-check-timeout-milliseconds=2000
WEB3SIGNER_ETH2_SLASHING_PROTECTION_DB_HEALTH_CHECK_TIMEOUT_MILLISECONDS=2000
eth2.slashing-protection-db-health-check-timeout-milliseconds: 2000

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>
--slashing-protection-db-password=changeme
WEB3SIGNER_ETH2_SLASHING_PROTECTION_DB_PASSWORD=changeme
eth2.slashing-protection-db-password: "changeme"

The password to connect to the slashing protection database.

slashing-protection-db-pool-configuration-file

--slashing-protection-db-pool-configuration-file=<FILE>
--slashing-protection-db-pool-configuration-file=/Users/me/config/HikariConfig.properties
WEB3SIGNER_ETH2_SLASHING_PROTECTION_DB_POOL_CONFIGURATION_FILE=/Users/me/config/HikariConfig.properties
eth2.slashing-protection-db-pool-configuration-file: "/Users/me/config/HikariConfig.properties"

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 be override them with this option.

slashing-protection-db-url

--slashing-protection-db-url=<JDBC_URL>
--slashing-protection-db-url=jdbc:postgresql://localhost/web3signer
WEB3SIGNER_ETH2_SLASHING_PROTECTION_DB_URL=jdbc:postgresql://localhost/web3signer
eth2.slashing-protection-db-url: "jdbc:postgresql://localhost/web3signer"

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>
--slashing-protection-db-username=postgres
WEB3SIGNER_ETH2_SLASHING_PROTECTION_DB_USERNAME=postgres
eth2.slashing-protection-db-username: "postgres"

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

slashing-protection-enabled

--slashing-protection-enabled=<BOOLEAN>
--slashing-protection-enabled=false
WEB3SIGNER_ETH2_SLASHING_PROTECTION_ENABLED=false
eth2.slashing-protection-enabled: false

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>
--slashing-protection-pruning-at-boot-enabled=false
WEB3SIGNER_ETH2_SLASHING_PROTECTION_PRUNING_AT_BOOT_ENABLED=false
eth2.slashing-protection-pruning-at-boot-enabled: false

When set to false, slashing protection database pruning is disabled at boot and only takes place at the scheduled pruning intervals.

The default is true.

slashing-protection-pruning-enabled

--slashing-protection-pruning-enabled=<BOOLEAN>
--slashing-protection-pruning-enabled=true
WEB3SIGNER_ETH2_SLASHING_PROTECTION_PRUNING_ENABLED=true
eth2.slashing-protection-pruning-enabled: true

Enables slashing protection database pruning. The default is false.

slashing-protection-pruning-epochs-to-keep

--slashing-protection-pruning-epochs-to-keep=<LONG>
--slashing-protection-pruning-epochs-to-keep=12000
WEB3SIGNER_ETH2_SLASHING_PROTECTION_PRUNING_EPOCHS_TO_KEEP=12000
eth2.slashing-protection-pruning-epochs-to-keep: 12000

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

The default is 10000.

slashing-protection-pruning-interval

--slashing-protection-pruning-interval=<LONG>
--slashing-protection-pruning-interval=48
WEB3SIGNER_ETH2_SLASHING_PROTECTION_PRUNING_INTERVAL=48
eth2.slashing-protection-pruning-interval: 48

Hours between slashing protection database pruning operations.

The default is 24.

slashing-protection-pruning-slots-per-epoch

--slashing-protection-pruning-slots-per-epoch=<LONG>
--slashing-protection-pruning-slots-per-epoch=20
WEB3SIGNER_ETH2_SLASHING_PROTECTION_PRUNING_SLOTS_PER_EPOCH=20
eth2.slashing-protection-pruning-slots-per-epoch: 20

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>
--to=/Users/me/my_node/interchange.json
WEB3SIGNER_ETH2_EXPORT_TO=/Users/me/my_node/interchange.json
eth2.export.to: /Users/me/my_node/interchange.json

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

eth2 import

Import a slashing protection database from a file.

from

--from=<FILE>
--from=/Users/me/my_node/interchange.json
WEB3SIGNER_ETH2_IMPORT_FROM=/Users/me/my_node/interchange.json
eth2.import.from: /Users/me/my_node/interchange.json

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

filecoin

network

--network=<NETWORK>
--network=TESTNET
WEB3SIGNER_FILECOIN_NETWORK=TESTNET
filecoin.network: "TESTNET"

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

Questions or feedback? You can discuss issues and obtain free support on Web3Signer Discord channel.
For paid professional support by Consensys, contact us at [email protected].