Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add validator migration guide and networks list table #1854

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 72 additions & 0 deletions how-to-guides/validator-node.md
Original file line number Diff line number Diff line change
Expand Up @@ -181,6 +181,12 @@ Now, connect to the network of your choice.

You have the following option of connecting to list of networks shown below:

| Name | Type | Chain ID | CLI Usage |
|--------------------------------|---------------|--------------------------------|--------------------------------------------|
| [Celestia](./mainnet.md) | Mainnet Beta | {{ constants.mainnetChainId }} | `--chain-id {{ constants.mainnetChainId }}`|
| [Mocha](./mocha-testnet.md) | Testnet | {{ constants.mochaChainId }} | `--chain-id {{ constants.mochaChainId }}` |
| [Arabica](./arabica-devnet.md) | Devnet | {{ constants.arabicaChainId }} | `--chain-id {{ constants.arabicaChainId }}`|

Continuing the validator tutorial, here are the steps to connect your
validator to Mocha:

Expand Down Expand Up @@ -240,6 +246,72 @@ Follow the instructions under
[transaction indexer configuration options](/how-to-guides/consensus-node#optional-transaction-indexer-configuration-options)
to configure your `config.toml` file to select which transactions to index.

## Migrating a validator to another machine

:::tip NOTE
Moving a validator to a new machine is a sensitive process that needs to be done carefully. If the transfer isn’t handled properly, it could result in double signing, which will permanently slash your validator, wipe out delegated tokens, and remove you from the active validator set. To avoid this, make sure to follow the steps closely and stop the old node completely before starting the migration.
:::

### Step 1: Set up a new full consensus node

First, set up a new [full consensus node](./consensus-node.md) on the new server and make sure the node is fully synced with the chain. To check whether your node is synced, you can check the `catching_up` status using:

```bash
celestia-appd status | jq '{ "catching_up": .SyncInfo.catching_up }'
```

If the node is synced, the output will look like this:

```json
{
"catching_up": false
}
```

### Step 2: Stop the old validator

After your new full consensus node is synced, proceed to stop the current validator on the old machine. If you’re running it with [SystemD](./systemd.md), use the following command:

```bash
sudo systemctl stop <SERVICE_NAME>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Add explanation for the SERVICE_NAME placeholder

The <SERVICE_NAME> placeholder needs clarification for users:

-sudo systemctl stop <SERVICE_NAME>
+sudo systemctl stop celestia-appd.service  # Replace with your actual service name if different
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
sudo systemctl stop <SERVICE_NAME>
sudo systemctl stop celestia-appd.service # Replace with your actual service name if different

```

Additionally, it’s recommended to disable the service to prevent it from restarting automatically after a system reboot. You can do this with:

```bash
sudo systemctl disable <SERVICE_NAME>
```

For extra safety, you may also delete the service file from the server:

```bash
sudo rm -rf /etc/systemd/system/<SERVICE_NAME>.service
```

### Step 3: Backup and transfer `priv_validator_key.json`

Once the old validator is stopped and the new node is synced, you’ll need to back up the `priv_validator_key.json` file from the old server (if it has not been backed up earlier). This file is located at:

```plaintext
~/.celestia-app/config/priv_validator_key.json
```

Copy this file to the same location on the new server. To verify that the file has been transferred correctly, compare its contents on both servers using:

```bash
cat ~/.celestia-app/config/priv_validator_key.json
```

### Step 4: Start the new validator

If everything checks out, you can now restart the new node with the updated validator key:

```bash
sudo systemctl restart <SERVICE_NAME>
```
Comment on lines +307 to +311
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Add verification steps after migration

Consider adding commands to verify the validator is operating correctly after migration:

  • Check validator status and voting power
  • Verify block signing
  • Monitor for any missed blocks

Example verification commands to add:

+# Check validator status
+celestia-appd query staking validator $(celestia-appd keys show $VALIDATOR_WALLET --bech val -a)
+
+# Monitor block signing
+celestia-appd query slashing signing-info $(celestia-appd tendermint show-validator)

Committable suggestion skipped: line range outside the PR's diff.


After this, your validator will resume signing blocks on the new server, and the migration is complete. Validators operate within a 10,000 signed block window, and missing more than 2,500 blocks in this window will result in downtime jail. The faster you complete the transfer, the fewer blocks your validator will miss.

## Additional resources

For additional resources, refer to
Expand Down
Loading