PoS Migration Guide for Validators ​

This guide is for users interested in using Nimiq’s Migration Tools to register their validator and transition from Nimiq PoW to PoS. For post-migration validator registration, refer to the becoming a validator documentation. For a complete understanding of the migration technicalities, refer to this document.

Validator Registration Tool ​

The Validator Registration tool facilitates the pre-registration process for validators, so they are included in the PoS genesis block. Validators pre-register within the PoW chain. The Validator Registration tool operates in two distinct modes:

• Keys and corresponding address generation
• Validator registration via transactions

Prerequisites ​

1. Make sure you have Node.js >= v18.20.4 installed.
2. Clone the Nimiq Validator Registration Tool repository.
3. Install its dependencies by executing yarn inside the repository.

Step 1: Generate validator keys ​

Execute the tool without parameters to generate a validator address, signing key, and voting key:

node validator-registration.js

The tool generates fresh keys and stores them into the validator-keys.json file in your current directory. The following screenshot demonstrates an example output of the script:

Using your own keys ​

You can of course also generate your validator, signing and/or voting keys yourself through other methods. Just replace the address and keys in the validator-keys.json file with the ones you have and continue with the next step.

Step 2: Fund your validator address ​

To start the validator registration process, fund the validator address you just generated to cover the nominal transaction fees of 1 Luna each (you need at least 6 Lunas = 0.00006 NIM) associated with the validator registration process. Additionally, you will need to pay the readiness transaction, so you need to fund your address with 10 Lunas for the registration and activation transactions. You can use any wallet to send Lunas to this address.

Step 3: Run the validator registration tool ​

To register your validator and the corresponding keys on the PoW Mainnet, you must specify the arguments as follows:

node validator-registration.js --validator validator-keys.json --network main

The tool will connect to the Nimiq PoW Mainnet chain. Upon consensus, the tool creates and signs the validator registration transactions and sends them to the network, effectively registering your validator. Note that these transactions are a bundle of 6, and each one has a nominal fee of 1 Luna. Please ensure you have funded your validator address — as instructed in the previous step — as the transaction fees are paid from this address.

For detailed guidance through the scripts and their options, run node validator-registration.js --help. This will print out the usage instructions.

Step 4: Deposit payment and commit ​

The final step involves committing to the registration and paying the validator's deposit of 100 000 NIM. This transaction can be sent from any address. Irrespective of the address you send the deposit from, you must include your validator address in the transaction’s “public message” field so your deposit can later be matched to your validator. Please include your validator address in human-readable format (NQ...).

To send the transaction manually via the Nimiq Wallet, you need the following data:

Validator Activation Tool ​

The Activation Tool facilitates the transition from the PoW chain to the PoS chain. We recommend running the activation tool before its window begins to ensure sufficient time for migrating the history, as this process can be time-consuming.

Prerequisites ​

• Access to a PoW chain client with RPC access enabled.
  • Follow instructions in the core-js repository to start your client and have your client synchronized against the main network.
  • Follow the instructions in this sample guide to enable RPC in your POW client.
• Clone and compile the PoS blockchain repository and follow the instructions.

Step 1: Add your Validator Data into the Configuration File ​

Once you have your client setup, you can either:

• Go to the file $HOME/.nimiq/client.toml, which includes a dedicated validator section at the end, and paste your validator data into this section.
• Refer to this guide.

Ensure that you set your sync_mode as full or history in the consensus part of the configuration file. Only full or history nodes are eligible to be validators.

Step 2: Run the Activation Tool ​

The Activation tool establishes a connection with the PoW chain via RPC, extracting data from your configuration file and crosschecking it with the information in the JSON file within the PoW chain.

To execute the tool successfully, you need to ensure that you are fully synced and in consensus within the PoW chain. This requires starting the PoW client with an RPC server enabled on your imported validator address (this might take a while). As in this example, you can do it in your configuration file by adding your address and key pair.

Alternatively, you can start the RPC server by cloning the Nimiq CoreJS repository then following the quickstart instructions and finally running the following command:

node clients/nodejs/index.js --dumb --network=main --rpc=8648 --wallet-seed=private_keypublic_key

Note that private_keypublic_key is the concatenation of your private key and public key in that order.

Before executing the activation tool, make sure you run cargo build --release within the PoS repository to compile the code.

Once you have consensus on the PoW chain, proceed to execute the migration tool by running the following command in the PoS chain client directory, including the path to the configuration file containing your validator data and specifying the RPC server to be used:

cargo run --release --bin nimiq-pow-migration --url "url-according-your-configuration" --config client.toml

Where url-according-your-configuration is the PoW client RPC url. For example: http://172.0.0.1:8648.

When the tool is launched, it will monitor the network for at least 80% readiness. Once this threshold is reached, the transition block marks the beginning of the PoS chain, and any transactions sent after the transition block are not considered part of the PoS chain. Learn more about this here.