|
| 1 | +--- |
| 2 | +title: Validator Key Management |
| 3 | +description: Learn how to generate and manage validator keys, including session keys for consensus participation and node keys for maintaining a stable network identity. |
| 4 | +--- |
| 5 | + |
| 6 | +# Key Management |
| 7 | + |
| 8 | +## Introduction |
| 9 | + |
| 10 | +After setting up your node environment as shown in the [Setup](/infrastructure/running-a-validator/onboarding-and-offboarding/set-up-validator){target=\_blank} section, you'll need to configure multiple keys for your validator to operate properly. This includes setting up session keys, which are essential for participating in the consensus process, and configuring a node key that maintains a stable network identity. This guide walks you through the key management process, showing you how to generate, store, and register these keys. |
| 11 | + |
| 12 | +## Set Session Keys |
| 13 | + |
| 14 | +Setting up your validator's session keys is essential to associate your node with your stash account on the Polkadot network. Validators use session keys to participate in the consensus process. Your validator can only perform its role in the network by properly setting session keys which consist of several key pairs for different parts of the protocol (e.g., GRANDPA, BABE). These keys must be registered on-chain and associated with your validator node to ensure it can participate in validating blocks. |
| 15 | + |
| 16 | +### Generate Session Keys |
| 17 | + |
| 18 | +There are multiple ways to create the session keys. It can be done by interacting with the [Polkadot.js Apps UI](https://polkadot.js.org/apps/#/explorer){target=\_blank}, using the curl command or by using [Subkey](https://paritytech.github.io/polkadot-sdk/master/subkey/index.html){target=\_blank}. |
| 19 | + |
| 20 | +=== "Polkadot.js Apps UI" |
| 21 | + |
| 22 | + 1. In Polkadot.js Apps, connect to your local node, navigate to the **Developer** dropdown, and select the **RPC Calls** option |
| 23 | + |
| 24 | + 2. Construct an `author_rotateKeys` RPC call and execute it |
| 25 | + |
| 26 | + 1. Select the **author** endpoint |
| 27 | + 2. Choose the **rotateKeys()** call |
| 28 | + 3. Click the **Submit RPC Call** button |
| 29 | + 4. Copy the hex-encoded public key from the response |
| 30 | + |
| 31 | +  |
| 32 | + |
| 33 | +=== "Curl" |
| 34 | + |
| 35 | + Generate session keys by running the following command on your validator node: |
| 36 | + |
| 37 | + ``` bash |
| 38 | + curl -H "Content-Type: application/json" \ |
| 39 | + -d '{"id":1, "jsonrpc":"2.0", "method": "author_rotateKeys", "params":[]}' \ |
| 40 | + http://localhost:9944 |
| 41 | + ``` |
| 42 | + |
| 43 | + This command will return a JSON object. The `result` key is the hex-encoded public part of the newly created session key. Save this for later use. |
| 44 | + |
| 45 | + ```json |
| 46 | + {"jsonrpc":"2.0","result":"0xda3861a45e0197f3ca145c2c209f9126e5053fas503e459af4255cf8011d51010","id":1} |
| 47 | + ``` |
| 48 | + |
| 49 | +=== "Subkey" |
| 50 | + |
| 51 | + To create a keypair for your node's session keys, use the `subkey generate` command. This generates a set of cryptographic keys that must be stored in your node's keystore directory. |
| 52 | + |
| 53 | + When you run the command, it produces output similar to this example: |
| 54 | + |
| 55 | + --8<-- 'code/infrastructure/running-a-validator/onboarding-and-offboarding/key-management/subkey-generate.html' |
| 56 | + |
| 57 | + To properly store these keys, create a file in your keystore directory with a specific naming convention. The filename must consist of the hex string `61757261` (which represents "aura" in hex) followed by the public key without its `0x` prefix. |
| 58 | + |
| 59 | + Using the example above, you would create a file named: |
| 60 | + |
| 61 | + ``` |
| 62 | + ./keystores/6175726128cc2fdb6e28835e2bbac9a16feb65c23d448c9314ef12fe083b61bab8fc2755 |
| 63 | + ``` |
| 64 | + |
| 65 | + And store only the secret phrase in the file: |
| 66 | + |
| 67 | + ``` |
| 68 | + "twist buffalo mixture excess device drastic vague mammal fitness punch match hammer" |
| 69 | + ``` |
| 70 | + |
| 71 | +### Submit Transaction to Set Keys |
| 72 | + |
| 73 | +Now that you have generated your session keys, you must submit them to the chain. Follow these steps: |
| 74 | + |
| 75 | +1. Go to the **Network > Staking > Accounts** section on Polkadot.js Apps |
| 76 | +2. Select **Set Session Key** on the bonding account you generated earlier |
| 77 | +3. Paste the hex-encoded session key string you generated (from either the UI or CLI) into the input field and submit the transaction |
| 78 | + |
| 79 | + |
| 80 | + |
| 81 | +Once the transaction is signed and submitted, your session keys will be registered on-chain. |
| 82 | + |
| 83 | +### Verify Session Key Setup |
| 84 | + |
| 85 | +To verify that your session keys are properly set, you can use one of two RPC calls: |
| 86 | + |
| 87 | +- **`hasKey`** - checks if the node has a specific key by public key and key type |
| 88 | +- **`hasSessionKeys`** - verifies if your node has the full session key string associated with the validator |
| 89 | + |
| 90 | +For example, you can [check session keys on the Polkadot.js Apps](https://polkadot.js.org/apps/#/rpc){target=\_blank} interface or by running an RPC query against your node. Once this is done, your validator node is ready for its role. |
| 91 | + |
| 92 | +## Set the Node Key |
| 93 | + |
| 94 | +Validators on Polkadot need a static network key (also known as the node key) to maintain a stable node identity. This key ensures that your validator can maintain a consistent peer ID, even across restarts, which is crucial for maintaining reliable network connections. |
| 95 | + |
| 96 | +Starting with Polkadot version 1.11, validators without a stable network key may encounter the following error on startup: |
| 97 | + |
| 98 | +--8<-- 'code/infrastructure/running-a-validator/onboarding-and-offboarding/set-up-a-validator/node-key-error-01.html' |
| 99 | + |
| 100 | +### Generate the Node Key |
| 101 | + |
| 102 | +Use one of the following methods to generate your node key: |
| 103 | + |
| 104 | +=== "Save to file" |
| 105 | + |
| 106 | + The recommended solution is to generate a node key and save it to a file using the following command: |
| 107 | + |
| 108 | + ``` bash |
| 109 | + polkadot key generate-node-key --file INSERT_PATH_TO_NODE_KEY |
| 110 | + ``` |
| 111 | + |
| 112 | +=== "Use default path" |
| 113 | + |
| 114 | + You can also generate the node key with the following command, which will automatically save the key to the base path of your node: |
| 115 | + |
| 116 | + ``` bash |
| 117 | + polkadot key generate-node-key --default-base-path |
| 118 | + ``` |
| 119 | + |
| 120 | +Save the file path for reference. You will need it in the next step to configure your node with a static identity. |
| 121 | + |
| 122 | +### Set Node Key |
| 123 | + |
| 124 | +After generating the node key, configure your node to use it by specifying the path to the key file when launching your node. Add the following flag to your validator node's startup command: |
| 125 | + |
| 126 | +``` bash |
| 127 | +polkadot --node-key-file INSERT_PATH_TO_NODE_KEY |
| 128 | +``` |
| 129 | + |
| 130 | +Following these steps ensures that your node retains its identity, making it discoverable by peers without the risk of conflicting identities across sessions. For further technical background, see Polkadot SDK [Pull Request #3852](https://github.com/paritytech/polkadot-sdk/pull/3852){target=\_blank} for the rationale behind requiring static keys. |
0 commit comments