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
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
Last updated