Import validator keys#

This guide describes how to set up a node to run as a validator node that participates in the Concordium network on different platforms. A node receives blocks and transactions from other nodes and propagates information about blocks and transactions to the nodes in the Concordium network. In addition, a validator node also participates in the lottery and produces its own blocks. The validator node will start producing blocks two epochs after the transaction has been approved.

Note

Validator credentials registered on mainnet will not work with a testnet node and vice versa.

Platform-specific configuration#

Select your platform below to configure your node with validator keys.

Windows

Prerequisites

  • Run Windows 10 or later or Windows Server 2019 or later

  • Have the administrator password to your computer

  • Run a node on Windows

  • Have generated validator keys, see Add a validator for details. For an overview of the process, see Validation.

Configure a validator node on Windows

  1. Create validator keys in Concordium Wallet for Web, CryptoX Concordium Wallet, Desktop Wallet or Concordium Client and associate them with an account either on mainnet or testnet. Follow this article for help.

    Note

    The validator credentials file must be accessible by the SYSTEM user and can’t be encrypted.

    Warning

    Do not edit the name or contents of the validator-credentials.json file.

  2. Once you’ve added validation to an account and exported the validator keys, you have to change the configuration file for the Concordium Node Service. Open Configure Concordium Node Service from the Start menu, and select Yes when you see the message Do you want to allow this app to make changes to your device?. The configuration file opens.

  3. Add the following in the [node.mainnet] section if the credentials are for mainnet, or the [node.testnet] section if they are for testnet. Make sure that you add the credentials to the network the account was created on.

    baker_credentials = 'C:\path\to\validator-credentials.json'

    where you replace C:\path\to\validator-credentials.json with the full path to the validator credentials file.

  4. Save the file.

  5. Stop and restart the node runner service using the Stop Concordium Service Node and the Start Concordium Service Node shortcuts. Don’t use End task in the Task Manager as it might cause errors.

View the node log

You can find the node logs here:

  • Mainnet: C:\ProgramData\Concordium\Node Runner\mainnet\logs

  • Testnet: C:\ProgramData\Concordium\Node Runner\testnet\logs

Troubleshooting

If a node fails to start, for example because of a configuration issue, or stops unexpectedly, there will be an Error-level event in the Event Viewer that explains why. The following are common error scenarios and possible solutions.

  • The node doesn’t restart after you’ve set the credentials in the configuration file. This error can occur when the specified location of the credentials file is incorrect. In the Event Viewer an error such as the following might appear. When this happens, change the path in the configuration file.

  • The node doesn’t start validation, and in the log file you see the message Validator keys are incorrect repeatedly. It takes 1-2 hours after validator keys have been added to an account for the keys to be eligible to produce blocks. If this problem persists beyond two hours, then likely the keys are incorrect. Double check that you are not using keys from testnet on mainnet, or vice-versa.

For more information on the logs, see Run a node on Windows.

Ubuntu

Prerequisites

Configure the node with validator keys

  1. Move the JSON file with the validator keys you generated to the server that’s running the node. Store it, for example, in /home/user/concordium/validator-credentials.json.

  2. In the terminal, enter one of the following depending on your network:

    For Mainnet:

    $sudo systemctl edit concordium-mainnet-node.service

    For Testnet:

    $sudo systemctl edit concordium-testnet-node.service

  3. Add the following snippet to the opened file (the file is empty the first time you open it):

    For Mainnet:

    [Service]

Environment=CONCORDIUM_NODE_BAKER_CREDENTIALS_FILE=%S/concordium-9dd9ca4d19e9393877d2c44b70f89acbfc0883c2243e5eeaecc0d1cd0503f478/validator-credentials.json
BindReadOnlyPaths=/home/user/concordium/validator-credentials.json:%S/concordium-9dd9ca4d19e9393877d2c44b70f89acbfc0883c2243e5eeaecc0d1cd0503f478/validator-credentials.json

    For Testnet:

    [Service]

Environment=CONCORDIUM_NODE_VALIDATOR_CREDENTIALS_FILE=%S/concordium-b6078154d6717e909ce0da4a45a25151b592824f31624b755900a74429e3073d/validator-credentials.json
BindReadOnlyPaths=/home/user/concordium/validator-credentials.json:%S/concordium-b6078154d6717e909ce0da4a45a25151b592824f31624b755900a74429e3073d/validator-credentials.json

    Where you replace the path /home/user/concordium/validator-credentials.json with the actual location of the file.

    Note

    The paths above contain the default paths to the validator’s state directory, where the long hash is the genesis hash for each network.

  4. Save the edited file.

  5. Restart the node for the changes to take effect. Enter:

    For Mainnet:

    $sudo systemctl restart concordium-mainnet-node.service

    For Testnet:

    $sudo systemctl restart concordium-testnet-node.service

  6. To verify the node is running, enter:

    For Mainnet:

    $sudo systemctl status concordium-mainnet-node.service

    For Testnet:

    $sudo systemctl status concordium-testnet-node.service
macOS

Prerequisites

Configure a node as a validator

Once you have generated validator keys, you need to move the generated validator keys file to a location accessible by the node, and finally specify this location in the service file for the Concordium Node.

  1. Move the validator-credentials.json file to the node’s config folder:

    For Mainnet:

    $sudo cp "/path/to/mainnet/validator-credentials.json" "/Library/Application Support/Concordium Node/Mainnet/Config/validator-credentials.json"

    For Testnet:

    $sudo cp "/path/to/testnet/validator-credentials.json" "/Library/Application Support/Concordium Node/Testnet/Config/validator-credentials.json"

    (replacing the source path with the actual file path to your validator credentials).

  2. Edit the service file as an administrator:

    For Mainnet: "/Library/Concordium Node/LaunchDaemons/software.concordium.mainnet.node.plist"

    For Testnet: "/Library/Concordium Node/LaunchDaemons/software.concordium.testnet.node.plist"

  3. In the EnvironmentVariables section of the file add the following:

    For Mainnet:

    <!-- Path to the validator credentials file. -->
<key>CONCORDIUM_NODE_BAKER_CREDENTIALS_FILE</key>
<string>/Library/Application Support/Concordium Node/Mainnet/Config/validator-credentials.json</string>

    For Testnet:

    <!-- Path to the validator credentials file. -->
<key>CONCORDIUM_NODE_BAKER_CREDENTIALS_FILE</key>
<string>/Library/Application Support/Concordium Node/Testnet/Config/validator-credentials.json</string>

  4. Restart your node:

    For Mainnet: Run Concordium Node Stop Mainnet (if running) and then Concordium Node Start Mainnet.

    For Testnet: Run Concordium Node Stop Testnet (if running) and then Concordium Node Start Testnet.

Docker

Prerequisites

Configure a node as a validator

Once you have generated validator keys, you need to move the generated validator keys file to a location accessible by the node, and finally specify this location in the service file for the Concordium Node.

To register the keys in the network you need to be running a node and send a validator add transaction to the network:

$concordium-client validator add <keys-file>.json --sender validatorAccount --stake <amount-to-stake> --validator-credentials-out <concordium-data-dir>/validator-credentials.json

where you replace

  • <amount-to-stake> with the CCD amount for the validator’s initial stake

  • <concordium-data-dir> with the directory specified as the volume mount for the node database. In the sample configuration file this is /var/lib/concordium-testnet for the testnet node, and /var/lib/concordium-mainnet for the mainnet node.

Warning

Do not stake all of your funds or you will not have enough funds to cover transaction fees.

Provide a --no-restake flag to avoid automatically adding the rewards to the staked amount on the validator account. Read more about this behavior in the section Restake earnings.

To start the node with these validator keys and produce blocks, do the following:

  1. Stop the currently running node. To do this, press Ctrl + C on the terminal where the node is running or run

    $docker stop testnet-node

    or

    $docker stop mainnet-node

    depending on the environment.

  2. Update the configuration file for the node by adding

    - CONCORDIUM_NODE_BAKER_CREDENTIALS_FILE=/mnt/data/validator-credentials.json

    into the environment section of the node service section of the file.

When you’ve placed the file in the appropriate directory, start the node again in the same way as the first time, e.g., docker compose -f testnet-node.yaml up. The node will automatically start producing blocks when the validator is included in the validators for the current epoch.

Verify that a node is a validator node#

Two epochs must have elapsed before you can see the validator ID of the node on the dashboard.

You can use concordium-client to see the status of the node. For more information, see Concordium Client.

$concordium-client raw GetNodeInfo

...

Consensus type: "Active"

...

In the wallets, a badge is added to the account associated with the validator node. The badge appears as soon as the transaction has been submitted. That is, before the two epochs have elapsed.

Was this article helpful?