HashiCorp Vault

The Operator supports loading signing keys from a remote HashiCorp Vault ↗ instance, avoiding storage of keystores on the filesystem. This approach is best suited for node operators who already have most of StakeWise Operator functionality implemented in their systems, and only need integration for validators registration or pooling support.

Prerequisites

Complete the following steps before proceeding:

1. Installation → completed
2. Prepare Operator → — keys generated and deposit data uploaded
3. Validator keys stored in your HashiCorp Vault ↗ instance

Key Storage Format

The user must provide the HashiCorp Vault instance URL, authentication token, and secret path in the K/V engine.

Internal structure of the secret must resemble the following JSON format:

{
"pubkey1": "privkey1",
"pubkey2": "privkey2",
...
}

Public and private signing keys must be stored in hex form, with or without 0x prefix.

After loading keys from HashiCorp Vault, the operator behaves in the same way as if it had loaded them from keystores, No additional operations are needed to support the integration.

Start Operator Service

Passing the following options to the start command will enable loading validator signing keys from remote HashiCorp Vault ↗.

Important

Make sure the keystores directory is empty before running this command, otherwise the operator will prefer local keystores.

./operator start \
  --network=mainnet \
  --vault=0x834F27bC8670491b75af512d943f01D5383F87Cf \
  --consensus-endpoints=https://consensus-node \
  --execution-endpoints=https://execution-node \
  --hashi-vault-url=https://hashi-vault:8200 \
  --hashi-vault-token=hvs.abcde \
  --hashi-vault-key-path=keystores1 \
  --hashi-vault-key-path=keystores2

start flags

Flag	Description
--hashi-vault-url	Base URL of the vault service, e.g. http://vault:8200
--hashi-vault-token	Authentication token for accessing HashiCorp Vault
--hashi-vault-key-path	Key path(s) in the K/V secret engine where validator signing keys are stored. Can be repeated for multiple paths
--hashi-vault-key-prefix	Key prefix(es) in the K/V secret engine. Can be repeated for multiple prefixes
--hashi-vault-parallelism	Number of parallel requests to K/V secrets engine

For additional configuration, see the full list of optional flags.