How to rotate Vega keys

Vega key rotation is a safety feature that allows validator nodes to manage their Vega keys. Every validator node in the network needs three keys: Ethereum, CometBFT and Vega. This section described to how to dynamically rotate a node's Vega key.

Key rotation is a cryptographic best practise that allows a current in-use key to be replaced by a new, different key. It is an activity that should be performed regularly to guard against an in-use key being unknowingly compromised.

The process assumes that the Validator node's current wallet is an isolated wallet, and that the wallet containing the master key is held separately on a different machine. This is the recommended handling of Vega wallets for security reasons.

The below steps are carried out on the machine containing the full wallet:

1. Confirm that the Vega wallet is the correct wallet
2. Generate a new key with the Vega wallet
3. Isolate the new key
4. Generate a Vega key rotation transaction

The below steps are then carried out from the Validator nodes's machine:

1. Send the Vega key rotation transaction to the network
2. Import and load the isolated wallet
3. Confirm the key rotation
4. Transfer self-delegations to the new Vega key

Prerequisites:

1. Installed Vega Wallet CLI binary ↗ (under assets for each software version)
2. Running validator node with admin server enabled
3. The node wallet passphrases
4. Access to wallet with current Vega and master key (usually the original wallet that generated those keys)
5. Removable media for transporting an isolated wallet

Terminology:

• VEGA_PUB_KEY - the public key being rotated from
• NEW_VEGA_PUB_KEY - the public key being rotated to
• WALLET_NAME - the name of the wallet which originally generated VEGA_PUB_KEY
• WALLET_HOME - represents the path to the wallet above (WALLET_NAME).
• ISOLATED_WALLET_PATH - path to the isolated wallet containing NEW_VEGA_PUB_KEY
• ENCODED_TRANSACTION - an encoded and pre-signed key rotation transaction

Prepare a key rotation transaction and an isolated wallet

The following steps should be executed on the machine containing the Vega wallet. This machine which should be seen as containing more sensitive data that the machine running the validator node.

Confirm Vega wallet is using correct wallet

It is important that the Vega wallet used to generate NEW_VEGA_PUB_KEY is the same as the one which generated VEGA_PUB_KEY otherwise the key rotation transaction will be rejected by the network.

To confirm that WALLET_NAME is the correct wallet the run below command

vegawallet --home "WALLET_HOME" info --wallet "WALLET_NAME"

You'll receive the following information as a response

Type:
HD wallet
Version:
2
ID:
44de1774ceb9bfb5e9b3c94e1453224ca08704f91c22ad112e07facc4ef532d8

Here 44de1774ceb9bfb5e9b3c94e1453224ca08704f91c22ad112e07facc4ef532d8 it the master public key of the wallet and is used as the ID for any running node.

Proceed with this process only if the ID of this wallet matches the ID of your node.

Generate a new Vega key with the Vega wallet

All generated keys are indexed by the order they were generated by the wallet. It is a requirement that you rotate to a Vega key with a higher index than the current Vega key. The best way to ensure this is to always generate a new Vega key.

The below command can be used to generate a new key

vegawallet --home "WALLET_HOME" key generate --wallet "WALLET_NAME"

You'll receive the following information as a response

✓ Key pair has been generated in wallet WALLET_NAME
✓ Generating a key pair succeeded

Public key:
627246392917415c7159d7d640fcc6098ec1d0ca5c4a9f99da8d2c8625ad6445
Metadata:
name | Key 5

where 627246392917415c7159d7d640fcc6098ec1d0ca5c4a9f99da8d2c8625ad6445 is NEW_VEGA_PUB_KEY.

Isolate the new key

With NEW_VEGA_PUB_KEY generated, the key can be isolated into a new wallet using the below command

vegawallet --home "WALLET_PATH" key isolate --wallet "WALLET_NAME" --pubkey "GENERATED_PUB_KEY"

You'll receive the following information as a response

✓ Key pair has been isolated in wallet test.debf91ba.isolated at: WALLET_HOME/wallets/test.debf91ba.isolated
✓ Key isolation succeeded

where WALLET_HOME/wallets/test.debf91b is the filepath to the new isolated wallet. Make a note of its location as you will need to transport this file onto another machine later.

Generate a Vega key rotation transaction

After generating a new key and isolating it in a wallet, create a key rotation transaction that can be sent to the network.

vegawallet --home WALLET_HOME key rotate 
           --wallet WALLET_NAME
           --current-pubkey VEGA_PUB_KEY
           --new-pubkey NEW_VEGA_PUB_KEY 
           --tx-height TX_HEIGHT 
           --target-height TARGET_HEIGHT
           --chain-id=CHAINID

where TX_HEIGHT is the approximate height at which the transaction will be sent to the network, and TARGET_HEIGHT is the block height at which the key-rotation will take place. The latter should be chosen such that it is far enough into the future that the rest of the process can be completed.

The response from this command is ENCODED_TRANSACTION, a base64 encoded transaction that will later be sent to the network,

✓ Key rotation succeeded

Transaction (base64-encoded):
CpoBCLvli5S+lOaH9gEQZKp9iQEIChCWARpAYmJmNTA3OWI4MDBhOTNjN2U5Nzc1NDdmNDVhN2QwMzUzYWEyZTUyYjBjNzQ1ZmYwOT
BmYzc5NWQ5MDEyYTYwNCJAZDRjYzEyMjI1ZDUyZDExMDVkZmI2ZDcyZjJhODQyYmUwNGM3OTUzYTY2OGYxYTllNTQyODVhM2Q2MzU5
ODJlNhKTAQqAATlmYTk4OGE0MDdmZGU0Yjk4Y2E0ZTg0NjRlYTExZWViYjhkOTIzNGM3YzRhNWNlOTJlYzM2ODEwOGEzYzcyYzZmNj
IzNmIxMWZmNDQ0NDMzMzk5MTNmZjA0Y2I0MTU3NTRjYTY2Yzg5YzUyYjQ3YzE1ZjYxYjk0ODMzZjUxMjBiEgx2ZWdhL2VkMjU1MTkY
AYB9A9I+QDQ0ZGUxNzc0Y2ViOWJmYjVlOWIzYzk0ZTE0NTMyMjRjYTA4NzA0ZjkxYzIyYWQxMTJlMDdmYWNjNGVmNTMyZDg=

Master public key used:
44de1774ceb9bfb5e9b3c94e1453224ca08704f91c22ad112e07facc4ef532d8

The transaction will be signed by the wallet's master key which is necessary for the network to accept the rotation request. The base64-encoded transaction string should be noted down or saved to a file.

note

It is advised to choose TARGET_HEIGHT to be away from an epoch boundary to allow enough time to transfer self-delegations between the rotated Vega keys

Transfering the Artefacts

The isolated wallet file and the encoded transaction will need to be transported to the machine that is running the validator node. This is so that the isolated wallet file can be imported and the key rotation transaction can be sent to the network.

How this is done is dependent on the hardware and networking available to you.

Submitting the Key Rotation Transaction and Updating the Node Wallet

The following steps should be executed on the machine running the Validator node. The artefacts generated in the previous steps should be in an accessible location.

Send the Vega key rotation transaction to the network

The pre-signed ENCODED_TRANSACTION can be sent to the network via the running validator node using the following command:

vega wallet tx send ----node-address NODE_ADDRESS BASE64_TRANSACTION

where NODE_ADDRESS is the address of the gRPC endpoint for the running validator node. This will stage the key rotation to take place at the previously chosen block height.

This command will tell the network to stage the key rotation to occur at the TARGET_HEIGHT chosen earlier.

Import and Load the Isolated Wallet

The isolated wallet containing NEW_VEGA_PUB_KEY can be imported into the running validator node using the following command

vega nodewallet import --wallet-path ISOLATED_WALLET_PATH -c vega --force

import successful:
walletFilePath:
VEGA_HOME/node/wallets/vega/vega.1666281615881884000
registryFilePath:
VEGA_HOME/node/wallets.encrypted

This will position the wallet such that it is ready to be used by the validator node upon reloading of the node's wallet.

Once the network reaches TARGET_BLOCK it will rotate the keys associating NEW_VEGA_PUB_KEY with the node. It is at this time that the following command needs to be run to rotate the key on the node itself:

vega nodewallet reload -c vega

You'll receive the following information as a response

reload successful:
{
  "oldWallet": {
    "name": "vega.1666231001522813494",
    "publicKey": "c3848cfce23861f44a3abe3dd96f5427edcab29f481928bcb120b1044469b9ab"
  },
  "newWallet": {
    "name": "vega.1666231083909167745",
    "publicKey": "4bd6c22c72b7c5503d14ed513a2f9a705d9875449cc9144a372328825170b3f8"
  }
}

danger

Whereas it is not necessary to reload the nodewallet exactly at TARGET_BLOCK doing so significantly early or significantly late may affect the node's performance scores and therefore the reward payout to that node.

Confirm a successful key rotation

To confirm that the key rotation occurred and to see that NEW_VEGA_PUB_KEY is now acknowledged by the network as the node's new Vega key, there are two end-points on a data node that can be used:

# this will show the details of all Vega key rotations that have happened for all nodes
$DATA_NODE_REST_ADDR/api/v2/vega/keys/rotations`

# this will show the Vega key of each node and should now show NEW_VEGA_PUB_KEY
$DATA_NODE_REST_ADDR/api/v2/nodes`

Transfer self-stake and self-delegations to the new Vega key

As a result of the key rotation any Vega staked to, and delegated by, CURRENT_PUB_KEY will no longer be seen as self-delegated since this key is no longer seen as associated with the node. This staked Vega should be undelegated and transfered to NEW_PUB_KEY where it can be re-delegated and seen as self-delegated by the network.

danger

If delegations are not transfered to the new Vega key by the end of the epoch that node will risk demotion.