v2.0.0 hard fork

The v2.0.0 hard fork introduces security-relevant improvements to the Nimiq protocol. Its activation is coordinated through validator stake signaling rather than a predetermined block height.

Validators independently decide whether to install the patch and signal readiness. The upgrade cannot be activated by the Nimiq team or any individual network participant. It becomes eligible for activation only after validators representing at least 80% of the active stake have signaled readiness.

Installing the patch and signaling readiness are separate actions. The patch is backwards compatible: a patched client that has not sent a signaling transaction keeps operating under the current consensus rules and does not count toward the 80% threshold.

Phase 1, validators: apply the security patch, restart your client, and manually send a signaling transaction. This happens before the hard fork.

Phase 2, node operators: after activation, update to the public release to stay on the upgraded chain.

Validators act in Phase 1 only. Node operators operate only in Phase 2.

Phase 1: Validators

Validators receive the security patch through the CERT channel. The patch contains the hard fork code.

Before you start

You will need:

• The security patch from the CERT channel: the gist or the Docker image.
• Your validator cold key: the private key of the Schnorr keypair your validator address is derived from, generated with nimiq-address when you set up your validator. The signaling transaction is signed with it.

Step 1: Apply the patch and restart

From source

1. Stop the running nimiq-client.
2. Apply the patch you received from the CERT channel.
3. Rebuild and restart: cargo build --release --bin nimiq-client, then run cargo run --release --bin nimiq-client.

The run command loads the config file from its default location. If you keep your client.toml at a non-default path, point the client to it by appending -- -c /path/to/client.toml to the run command, as described under option B in Configuration.

Docker

1. Stop the running container.
2. Pull the prebuilt image from the CERT channel.
3. Start a new container from the new image, reusing your existing data volume, ports, and config.

Once restarted, your validator runs the patched client and is ready to signal.

Step 2: Send the signaling transaction

1. Confirm you are running the patched client from Step 1; you can check the client version with the get_client_version RPC command.
2. Signal support after you update your client. The transaction must be signed with your validator cold key.

To make this easier, we provide the nimiq-mktx tool to build and sign this specific transaction. The tool runs offline and does not broadcast the transaction; it prints the signed transaction as a hex string, which you send to the network in the next step. You can also build the signaling transaction with any other tooling you prefer.

cargo run --release --bin nimiq-mktx validator signal-upgrade <version> <fee-secret-key> <validator-cold-secret-key> --validity-start <validity-start-block-number>

The command prints the signed transaction as a hex string. This transaction is not on the network yet. Broadcast it with the sendRawTransaction RPC method, passing the hex string as the raw_tx parameter. Using the RPC client:

cargo run --release --bin nimiq-rpc send-raw-transaction <hex-string>

The call returns the transaction hash. Look it up in a blockchain explorer to confirm the transaction was included and confirmed.

What happens after you signal

The fork requires 80% of the stake represented by validators to signal readiness. Once readiness reaches 80%, the fork can activate at any subsequent election macro block. Whether a given election macro block triggers a fork depends on its proposer: the proposer must be willing to fork.

If 80% is not reached, the chain continues to produce blocks under the current consensus rules. Unlike the PoS migration, which was activated at a fixed block, this fork has no fixed activation block. Readiness is re-evaluated at each election macro block until the threshold is met. If the threshold is never reached, you do not need to take any further action: the patched client keeps running as it does today.

You can track readiness on the dashboard throughout this phase.

Phase 2: Node operators

Phase 2 starts only after the chain has been upgraded, immediately following the fork. A public release is published at that point and announced in the Coders Dojo Telegram channel. Node operators who want to follow the upgraded chain must apply it. Validators are not required to, since they already applied the patch.

Because the release ships after the fork, your node stays on the pre-fork client through activation and follows the upgraded chain once you apply the release.

Update your client

After the fork activates, stop your running client or container, then update to v2.0.0 from source or Docker.

git fetch --tags
git checkout v2.0.0
cargo build --release --bin nimiq-client
cargo run --release --bin nimiq-client

docker pull ghcr.io/nimiq/core-rs-albatross:v2.0.0
# Stop the old container and start a new one from the new image,
# reusing your existing data volume, ports, and config.

When running from source, the run command loads the config file from its default location. If you keep your client.toml at a non-default path, point the client to it by appending -- -c /path/to/client.toml to the run command, as described under option B in Configuration.

Once updated, your node follows the upgraded chain. Node operators are finished after this step.

Support

• Validators: CERT Validators Telegram channel.
• Node operators: Coders Dojo Telegram channel.