PoS Migration Guide for Node Operators ​

Our migration guides are designed for users who want to actively participate in the transition process. This specific guide is for those who want to run the migration process without becoming validators (if you want to become one of the first validators from the start of the PoS chain, please refer to this guide). It is suitable for:

  • Node Operators
  • Exchanges
  • Regular Users

This guide provides instructions to run the Activation Tool, the final step of the migration to the Nimiq PoS. There is no requirement to run the migration as a node operator. You can simply start your PoS client once the migration process ends and build your own node.

It's important to note that, as a node operator, your role is primarily as an observer during the activation process. The migration will only proceed if at least 80% of the allocated stake is ready to migrate. Since you have not pre-registered as a validator, running the activation tool does not contribute to meet the threshold requirement for the transition. Nonetheless, by running the migration tool, you will replicate the state migration and genesis block creation process.

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. Follow the appropriate guide based on whether you already have a PoW client running.

Users without an Existing PoW Client

Step 1: Set Up your PoS Configuration File

This step involves configuring your PoS client settings to prepare for the transition. You'll set parameters such as the network, sync mode, and RPC server.

Once you have your client compiled in the PoS chain, you can:

  • Open the configuration file which is by default located in $HOME/.nimiq/client.toml. (see example)
  • Set the network to main-albatross
  • Choose your sync_mode setting as full or history
  • Optionally, enable the PoS RPC server by uncommenting the section in the [rpc-server] configuration section if you need it

Step 2: Check Client Sync Status

In the PoW chain, ensure you are fully synced and in consensus. Start the PoW client with an RPC server (this might take a while). Run the following command:

bash
node clients/nodejs/index.js --dumb --network=main --rpc=8648

Step 3: Run the Activation Tool

The Activation Tool establishes a connection with the PoW client via RPC, extracting data from your PoW client with the PoS client configuration.

Ensure your PoW client is fully synced before running the Activation Tool on the PoS chain side. Before executing the Activation Tool, compile the PoS chain client by running cargo build --release.

Once you are in consensus in the PoW chain, proceed to execute the Activation Tool by running the following command in the PoS client repository directory, including the path to the configuration file containing your validator data and specifying the PoW RPC server to be used. Note that this assumes the PoS client and PoW client (with RPC server enabled) are running on the same machine:

bash
cargo run --release --bin nimiq-pow-migration --url "http://127.0.0.1:8648" --config client.toml
Users with an Existing PoW Client
  • Make sure you have your PoW RPC server enabled to allow your PoS client to connect to it
  • Clone the PoS blockchain repository and follow the instructions to compile the code

Step 1: Set Up your PoS Configuration File

This step involves configuring your PoS client settings to prepare for the transition. You'll set parameters such as the network, sync mode, and RPC server.

Once you have your client compiled, you can:

  • Open the configuration file which is by default located at $HOME/.nimiq/client.toml (see example)
  • Set the network to main-albatross
  • Choose your sync_mode setting as full or history
  • Optionally, enable the PoS RPC server by uncommenting the section in the [rpc-server] configuration section if you need it

Step 2: Run the Activation Tool

The Activation Tool establishes a connection with the PoW chain via RPC, extracting data from your PoW client with the PoS client configuration.

Ensure your PoW client is fully synced before running the Activation Tool on the PoS chain side. Before executing the Activation Tool, compile the PoS chain code by running cargo build --release.

Once you are in consensus in the PoW chain, proceed to execute the Activation Tool by running the following command in the PoS client repository directory, including the path to the configuration file containing your validator data and specifying the RPC server to be used. Note that this assumes the PoS client and the PoW client (with the RPC server enabled at port 8648) are running on the same machine:

bash
cargo run --release --bin nimiq-pow-migration --url "http://127.0.0.1:8648" --config client.toml

The Activation Tool connects with the PoW client via RPC to extract necessary data for the migration process. The tool:

  • Captures the state of the PoW chain at the candidate block for the transition to the PoS chain
  • Starts migrating the state from the PoW chain to the PoS state format
  • Generates the "genesis" block using a candidate transition block for the PoS chain
  • Monitors the readiness of validators, waiting for at least 80% of them to signal readiness

Once the readiness threshold is met, the PoS client starts, marking the beginning of the PoS chain. Mind that as a non-validator, your role during this process is primarily observant, as your participation does not contribute to reach the 80% readiness threshold.