docs: add validator migration guide and networks list table #1854
Conversation
WalkthroughThe pull request enhances the validator node documentation by introducing a comprehensive guide for migrating a validator to a new machine. The new section provides a detailed, step-by-step process that covers setting up a new consensus node, stopping the old validator, securely transferring the validator key, and restarting the validator. Additionally, a new FAQ entry is added to help users troubleshoot a specific block version mismatch error, improving the overall documentation's utility and user guidance. Changes
Poem
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
how-to-guides/validator-node.md (2)
275-283: Clarify the service name placeholderThe
<SERVICE_NAME>placeholder needs more context. Consider adding a note explaining that this should be replaced with the actual SystemD service name (e.g.,celestia-appd.service) that was set up during the initial validator configuration.
293-297: Consider additional backup recommendationsWhile backing up
priv_validator_key.jsonis crucial, consider recommending backup of additional important files:
config/node_key.jsonfor node identitydata/priv_validator_state.jsonfor validator stateconfig/client.tomlfor custom configurations
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
how-to-guides/validator-node.md(2 hunks)
🔇 Additional comments (2)
how-to-guides/validator-node.md (2)
184-189: Well-structured networks table!The table provides clear and accurate information about available networks, with proper documentation links and correct chain IDs.
251-253: Excellent warning about double signing risks!The note effectively emphasizes the critical nature of the migration process and potential consequences of mistakes.
| If everything checks out, you can now restart the new node with the updated validator key: | ||
|
|
||
| ```bash | ||
| sudo systemctl restart <SERVICE_NAME> | ||
| ``` |
There was a problem hiding this comment.
🛠️ 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.
how-to-guides/validator-node.md
Outdated
| | Name | Type | Chain ID | CLI Usage | | ||
| |-------------------------------------------------------------------|---------------|-------------|-------------------------| | ||
| | [Celestia](https://docs.celestia.org/how-to-guides/mainnet) | Mainnet Beta | `celestia` | `--chain-id celestia` | | ||
| | [Mocha](https://docs.celestia.org/how-to-guides/mocha-testnet) | Testnet | `mocha-4` | `--chain-id mocha-4` | |
There was a problem hiding this comment.
let's use the constants here from https://github.com/celestiaorg/docs/blob/main/.vitepress/constants/constants.js to define the chain IDs!
There was a problem hiding this comment.
example:
There was a problem hiding this comment.
also use relative links for the internal links
how-to-guides/validator-node.md
Outdated
|
|
||
| ### Step 1: Set up a new full consensus node | ||
|
|
||
| First, set up a new [full consensus node](https://docs.celestia.org/how-to-guides/consensus-node) 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: |
There was a problem hiding this comment.
let's use relative link for the link to consensus-node.md
how-to-guides/validator-node.md
Outdated
|
|
||
| ### 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](https://docs.celestia.org/how-to-guides/systemd), use the following command: |
how-to-guides/validator-node.md
Outdated
| | Name | Type | Chain ID | CLI Usage | | ||
| |-------------------------------------------------------------------|---------------|-------------|-------------------------| | ||
| | [Celestia](https://docs.celestia.org/how-to-guides/mainnet) | Mainnet Beta | `celestia` | `--chain-id celestia` | | ||
| | [Mocha](https://docs.celestia.org/how-to-guides/mocha-testnet) | Testnet | `mocha-4` | `--chain-id mocha-4` | |
There was a problem hiding this comment.
also use relative links for the internal links
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
how-to-guides/validator-node.md (1)
307-311: 🛠️ Refactor suggestionAdd verification steps after migration
As suggested in the previous review, include commands to verify the validator's status after migration:
sudo systemctl restart <SERVICE_NAME> + +# Verify the validator is operating correctly: + +# Check validator status and voting power +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) + +# Check if the validator is in the active set +celestia-appd query tendermint-validator-set | grep $(celestia-appd tendermint show-validator)
🧹 Nitpick comments (1)
how-to-guides/validator-node.md (1)
313-314: Add monitoring recommendationsConsider adding guidance on monitoring the validator during and after migration:
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. + +It's recommended to: +1. Monitor your validator's signing performance using a block explorer +2. Set up alerts for missed blocks using tools like Grafana or Tenderduty +3. Keep track of your uptime percentage during the migration window
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
how-to-guides/validator-node.md(2 hunks)
🔇 Additional comments (3)
how-to-guides/validator-node.md (3)
273-274: 🛠️ Refactor suggestionUse relative link for SystemD reference
Update the link to use a relative path:
-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: +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:Likely invalid or redundant comment.
257-258: 🛠️ Refactor suggestionUse relative link for consensus node reference
Update the link to use a relative path:
-First, set up a new [full consensus node](./consensus-node.md) on the new server +First, set up a new [full consensus node](../consensus-node.md) on the new serverLikely invalid or redundant comment.
184-188: 🛠️ Refactor suggestionUse relative links in the network table
As requested, please update the links to use relative paths:
-| [Celestia](./mainnet.md) | Mainnet Beta | {{ constants.mainnetChainId }} | -| [Mocha](./mocha-testnet.md) | Testnet | {{ constants.mochaChainId }} | -| [Arabica](./arabica-devnet.md) | Devnet | {{ constants.arabicaChainId }} | +| [Celestia](../mainnet.md) | Mainnet Beta | {{ constants.mainnetChainId }} | +| [Mocha](../mocha-testnet.md) | Testnet | {{ constants.mochaChainId }} | +| [Arabica](../arabica-devnet.md) | Devnet | {{ constants.arabicaChainId }} |Likely invalid or redundant comment.
| 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> |
There was a problem hiding this comment.
🛠️ 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.
| sudo systemctl stop <SERVICE_NAME> | |
| sudo systemctl stop celestia-appd.service # Replace with your actual service name if different |
|
hey @jcstein, thanks for the feedback, everything's updated! |
Overview
This PR adds two sections to the docs, specifically to the
validator-node.mdfile:Summary by CodeRabbit