Web3Signer setup guide

What is Web3Signer?

Web3Signer is an open-source signing service developed under the Apache 2.0 license and written in Java. Web3Signer is capable of signing on multiple platforms using private keys stored in an external vault, or encrypted on a disk.

It is an innovative tool designed to enhance security and simplify the process of signing transactions in web3 applications. With Web3Signer, developers can seamlessly integrate external wallets or vaults into their decentralized applications, ensuring robust protection for private keys and providing users with a seamless and secure transaction signing experience.

This tool streamlines the signing process and offers enhanced security measures, making it a valuable asset for developers and users in the Web3 ecosystem. Learn more

To set up Web3Signer, follow these steps:

Step 1: Setting up the binary

Web3Signer offers two setup options: Docker mode or running it natively with a binary.

• For Docker mode, refer to the following documentation: https://docs.web3signer.consensys.net/HowTo/Get-Started/Use-Docker
• To set it up in native mode, follow the instructions provided in this documentation: https://docs.web3signer.consensys.net/HowTo/Get-Started/Start-Web3Signer

Step 2: Enable signing mode

• The signing mode of your Web3signer should be consensus layer client mode. To enable this signing mode simply add "eth2" after the web3signer command. For example: web3signer <commands> eth2 <sub commands>
• To explore the available commands that can be used with web3signer in eth2 mode, you can run web3signer eth2 --help. This will provide you with a list of possible commands and their usage.

Step 3: Setup slashing protection

When integrating Web3Signer with your validator client, it is highly recommended to set up slashing protection. Slashing protection ensures that validators do not sign duplicate attestations or blocks, preventing potential double signing issues.

To enable slashing protection with Web3Signer, the node operator needs to maintain a PostgreSQL database that can be shared among multiple instances of Web3Signer. This enables efficient slashing protection across the network.

• For a detailed understanding of slashing protection, please refer to the following documentation: https://docs.web3signer.consensys.net/Concepts/Slashing-Protection
• Find the relevant commands for setting up slashing protection in the following documentation: https://docs.web3signer.consensys.net/Reference/CLI/CLI-Subcommands#slashing-protection-db-url

Step 4: Setting up the Keys

• To determine the storage location for your keys in Web3Signer, you need to create a configuration file that specifies the desired storage location. This configuration file can then be passed to Web3Signer using the following flag: https://docs.web3signer.consensys.net/Reference/CLI/CLI-Syntax#key-store-path
• For detailed instructions on how to curate the configuration file and to learn about the supported platforms for Web3Signer, please refer to this documentation: https://docs.web3signer.consensys.net/Reference/Key-Configuration-Files

Step 5: Host Whitelisting

To restrict access to the web3signer instance you have set up, you can create a whitelist of permitted hosts. This ensures that only specified hosts can make use of the web3signer's REST API.

To set up the host whitelist, you can utilize the allowlist command. This command enables you to specify the hosts that are allowed to access the REST API. For more detailed information on using this command, please refer to the following documentation: https://docs.web3signer.consensys.net/Reference/CLI/CLI-Syntax#http-host-allowlist

Step 6: Connecting To Validator Clients

After setting up your web3signer, it is highly advisable to establish a connection between web3signer and your running validator client. This connection is crucial to prevent duplicate keys. Typically, you would have one key imported with the validator client and a duplicate copy stored on platforms like AWS KMS or Hashicorp Vault. This is an inconvenient situation which can potentially cause double slashing.

To seamlessly connect web3signer with your validator clients, please refer to the provided documentation for detailed instructions and guidelines. Following these instructions will ensure a smooth and secure integration between web3signer and your validator clients.

• For lighthouse - https://lighthouse-book.sigmaprime.io/validator-web3signer.html
• For Nimbus - https://nimbus.guide/keymanager-api.html
• For Prysm - https://docs.prylabs.network/docs/wallet/web3signer
• For Teku - https://docs.teku.consensys.net/how-to/use-external-signer/use-web3signer

Need further help?

For a comprehensive tutorial on setting up web3signer and establishing a connection with your validator client, we recommend following this resource: https://docs.web3signer.consensys.net/Tutorials/Launchpad-Keystores