Nimiq
Validators

Becoming a Validator

This guide will walk you through the process of setting up a Nimiq validator in the Albatross network.

Setup

This guide assumes the proof-of-stake network client (the node) has been compiled, or that you are running the node through other means, such as Docker. Check this guide for more information on compiling the code yourself.

Community Docker Image

An unofficial Docker image is available at maestroi/nimiq-albatross for those who prefer containerized deployment. This is a community-maintained image and not officially supported by the Nimiq team.

This guide provides two methods for sending JSON-RPC commands to your node:

  1. arpl, an RPC client specific to Nimiq's PoS node
  2. curl, a general-purpose network request tool

Configure and run your node

Generating your validator address and keys

For running a validator you need the following items which we are generating now:

  • A validator address: Nimiq address, derived from your cold keypair (Schnorr)
  • A voting keypair: BLS keypair, also called the hot key
  • A signing keypair: Schnorr keypair, also called the warm key
  • Optionally a fee keypair: Schnorr keypair

Note that we will use these in the following steps to configure your validator. For what each key does, and why validators hold separate cold, warm, and hot keys, see Validator keys.

Keep your public and private keys accessible by writing them down or saving them on your computer. Make sure you save the private keys securely, there is no way to recover them!

We are generating these keys with utilities included in the nimiq/core-rs-albatross repository. Refer to Setup above for installation instructions.

To generate the Schnorr keypairs and the validator address, you can use:

Shell
cargo run --release --bin nimiq-address
Since we will need at least one Schnorr keypair and a Nimiq address, the command must be run 2 separate times and the output must be saved because it will be needed later in this guide.

Run the command a third time, if you want to set a specific fee keypair - otherwise it will be auto-generated when you start your node, which will still work for sending control transactions without a fee.

To generate a BLS keypair, you can use:

Shell
cargo run --release --bin nimiq-bls
The output must be saved because it will be needed later in this guide.

Configuration

Run the node once. It will generate an example configuration file in the default config folder. On Linux, that's ~/.nimiq. You need to copy ~/.nimiq/client.example.toml to ~/.nimiq/client.toml. You can leave most configuration options as they are for now to start a basic full node.

To be able to control your node and to stake and validate, you need to enable the JSON-RPC server in your client.toml. Make sure the RPC section called [rpc-server] in the configuration file is enabled by uncommenting it.

Note that you can also configure your node to use history as the sync_mode. For that, you could change the consensus section of your config file to set sync_mode like in the following example:

TOML
[consensus]
sync_mode = "history"
History sync mode uses much more storage (disk) space and can take very long to sync. As such, we recommend opting for a full node setup to get started quicker.

The next step is to set up your validator address and keys in the [validator] section of your config file:

TOML
[validator]
validator_address = "NQXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX"
signing_key_file = "signing_key.dat"
voting_key_file = "voting_key.dat"
fee_key_file = "fee_key.dat"
signing_key = "Schnorr Private Key"
fee_key = "Schnorr Private Key"
voting_key = "BLS Private Key"
automatic_reactivate = true

Replace the validator address and keys generated accordingly:

  • The validator_address corresponds to the address output of a nimiq-address command. Paste your generated validator address here.
  • Ignore the three lines specifying file names. These files are automatically generated by the node and filled with the data from in the next settings.
  • The signing_key corresponds to the private key of a nimiq-address command. Paste your Schnorr secret key here.
  • The fee_key corresponds to the private key of a nimiq-address command. If you don't want to specify your own, comment that line out.
  • The voting_key in the config file corresponds to the secret key of the nimiq-bls command. Paste your BLS secret key here.
  • Leave automatic_reactivate as is.
As previously mentioned, if you are creating a new validator from scratch, and you need to generate all those keys, then you will need to use the nimiq-address command three times and the nimiq-bls command one time.
The fee_key is used to pay the fees for automatic reactivate transactions (if enabled). Since these fees default to 0 NIM, having the node auto-generate a fee key is safe.

TLS Certificate

It is strongly recommended to set up a TLS certificate for your node, because the browser-based Nimiq Wallet can only connect to it via secure connections. In order to maintain a healthy decentralization level within the network, it is advisable for the Nimiq Wallet to connect to as many diverse nodes as possible.

There are different services where a TLS certificate can be obtained, such as Let's Encrypt.

Once the certificate is obtained, it can be specified in the Network-TLS section within the config file:

TOML
[network.tls]
private_key = "/path/to/private_key_file.pem"
certificates = "/path/to/full_certificates_file.pem"

Start your node and sync the blockchain

After you finish your configuration, run the client from inside the core-rs-albatross directory with cargo run --release --bin nimiq-client. It will connect to the seed node(s), then to other nodes in the network, and start syncing the blockchain. Next, we will query your node for its status.

When running your node through other means, such as a Docker container, refer to their respective documentation on how to start your node with your own config.

Check your status with JSON-RPC

If you enabled the JSON-RPC Server in your node’s configuration, you can query your node and send commands with arpl or curl, as installed in step 1.

Become a Validator

To become a validator, you need to register it in the staking contract by sending a create_validator transaction. For that you need to have an account with at least the validator deposit fee (100 000 NIM). This guide assumes that this amount is already present in the validator address. To check if that is the case, use this command:

Import your validator keypair

To sign and send transactions from your validator account, you need to import its keypair.

In the following commands, validator_private_key is the private key of the Schnorr keypair you generated for the validator address, that is, your cold key.

Copyright © 2026