Use Web3Signer
Web3Signer is an open-source remote signing service developed by Consensys. Prysm users can use this tool as an alternative to storing keys locally. Web3Signer uses REST APIs to sign transactions and messages.
Web3Signer follows the Remote Signing API specification.
Prysm supports the use of Web3Signer the following flags:
--validators-external-signer-url
: base URL for the Web3Signer.
example:
--validators-external-signer-url=http://localhost:9000
the flag is also aliased to --remote-signer-url
example:
--remote-signer-url=http://localhost:9000
It is recommended to use https
for the Web3Signer url. Prysm currently supports one to one on Web3Signer and does not support multiple key management systems with the same validator client. Prysm does not support partial local and partial remote key management. Web3signer does not support authentication between the validator client and the signer.
--validators-external-signer-public-keys
: Comma separated list of public validator keys in hex format or an external url endpoint for the validator to retrieve public keys in JSON format.
HEX example:
--validators-external-signer-public-keys=0xa99a...e44c,0xb89b...4a0b
URL example:
--validators-external-signer-public-keys=https://web3signer.com/api/v1/eth2/publicKeys
The flag is also aliased to --remote-signer-keys
example:
--remote-signer-keys=0xa99a...e44c,0xb89b...4a0b
URLs will only pull once and does not poll. Additional keys can be added or removed via the Remote Keymanager API.
Most Prysm keymanager types require a corresponding Prysm wallet for storing keys, the web3signer type doesn't use any locally stored Prysm wallet.
The --wallet-dir
flag will still be needed if using the Remote Keymanager API for auth-token
purposes.
Remote Keymanager API
Keymanager APIs is a recommended set of REST APIs that validator clients have agreed upon for managing keys.
The Remote Keymanager APIs allows Prysm users to list, update, and delete the public keys set on the validator for Web3Signer.
To use the Remote keymanager API, one would need to run the validator with the --web
and --validators-external-signer-url
flags with --validators-external-signer-public-keys
being optional.
if --validators-external-signer-public-keys
is not defined the validator client would simply run in a loop waiting for keys to be set.
example:
validator --web --validators-external-signer-url=http://localhost:9000
The --web
flag will enable validator client APIs as well as the web ui ( not supported for web3signer ). A JWT token ( found on the second line of the auth-token file) will be generated in the prysm default wallet directory otherwise defined by --wallet-dir
flag. the token will also be printed in the console:
[2022-04-15 14:07:39] INFO rpc: http://127.0.0.1:7500/initialize?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.ck3J6tcvHcI74IiFjyJqcBH-MmNAq-fMr0ncyZkGvFM
The token needs to be copied and set in the header of the API request:
Authorization: `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.ck3J6tcvHcI74IiFjyJqcBH-MmNAq-fMr0ncyZkGvFM`
For more information on Remote Keymanager API visit the Keymanager APIs Github Repo.
Prysm Web Interface can only support local keys and will not support the Web3Signer keys.eth2-keymanager-frontend is a front-end alternative to the Prysm UI for the Keymanager APIs.
The remote keymanager API only currently supports Web3Signer types, please use the regular keymanager API for locally stored keys.
Both Keymanager APIs are only supported when the beacon chain syncs.
Public Key Persistence
The public keys set on the validator for a remote signer are NOT
persisted by DEFAULT
.
This means that if the validator client restarts, only the public keys set via flag options will be used on the validator and keys set via the Remote Keymanager API will be lost.
Keys can be persisted by setting the --validators-external-signer-key-file
set to a file path.
example:
--validators-external-signer-key-file=/path/to/keyfile.txt
the flag is also aliased to --remote-signer-keys-file
example:
--remote-signer-keys-file=/path/to/keyfile.txt
Keys updated via the Remote Keymanager API will be persisted to the file as a hex string, one key per line.
If the file is removed or the file is empty, the validator will revert to the public keys set via the --validators-external-signer-public-keys
flag.
On restart, the validator will read the file and set the public keys from the file.