diff --git a/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md b/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md index 741966d13..03ee87cdd 100644 --- a/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md +++ b/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md @@ -22,9 +22,10 @@ streamline development and reduce friction for any new potential contributor. - [Pre-Requisites](#pre-requisites) - [Account Setup](#account-setup) - - [Create and fund the `Gateway` and `Application` accounts](#create-and-fund-the-gateway-and-application-accounts) + - [Create the Gateway and Application accounts](#create-the-gateway-and-application-accounts) - [Prepare your environment](#prepare-your-environment) - [Fund the Gateway and Application accounts](#fund-the-gateway-and-application-accounts) +- [Gateway and Application Configurations](#gateway-and-application-configurations) - [Stake the `Gateway`](#stake-the-gateway) - [Stake the delegating `Application`](#stake-the-delegating-application) - [Delegate the `Application` to the `Gateway`](#delegate-the-application-to-the-gateway) @@ -54,7 +55,7 @@ This is not recommended but provided for convenience for NON PRODUCTION USE ONLY ## Account Setup -### Create and fund the `Gateway` and `Application` accounts +### Create the Gateway and Application accounts Create a new key pair for the delegating `Application`: @@ -116,6 +117,8 @@ You can find all the explorers, faucets and tools at the [tools page](../../expl ::: +## Gateway and Application Configurations + ### Stake the `Gateway` Create a Gateway stake configuration file: diff --git a/docusaurus/docs/operate/quickstart/supplier_cheatsheet.md b/docusaurus/docs/operate/quickstart/supplier_cheatsheet.md index 0b5f7115b..77a0f69e9 100644 --- a/docusaurus/docs/operate/quickstart/supplier_cheatsheet.md +++ b/docusaurus/docs/operate/quickstart/supplier_cheatsheet.md @@ -23,10 +23,10 @@ streamline development and reduce friction for any new potential contributor. - [Pre-Requisites](#pre-requisites) - [Context](#context) - [Account Setup](#account-setup) - - [Create and fund the `Supplier` account](#create-and-fund-the-supplier-account) + - [Create the `Supplier` account](#create-the-supplier-account) - [Prepare your environment](#prepare-your-environment) -- [Supplier Configuration](#supplier-configuration) - [Fund the Supplier account](#fund-the-supplier-account) +- [Supplier Configuration](#supplier-configuration) - [Stake the Supplier](#stake-the-supplier) - [RelayMiner Configuration](#relayminer-configuration) - [Configure the RelayMiner](#configure-the-relayminer) @@ -66,7 +66,7 @@ By the end of it, you should be able to serve Relays off-chain, and claim on-cha ## Account Setup -### Create and fund the `Supplier` account +### Create the `Supplier` account Create a new key pair for the `Supplier` @@ -96,8 +96,6 @@ your `~/.profile` (or `~/.bashrc`) file for a cleaner organization. ::: -## Supplier Configuration - ### Fund the Supplier account Run the following command to get the `Supplier`: @@ -121,6 +119,8 @@ You can find all the explorers, faucets and tools at the [tools page](../../expl ::: +## Supplier Configuration + ### Stake the Supplier :::info diff --git a/docusaurus/docs/operate/quickstart/validator_cheatsheet.md b/docusaurus/docs/operate/quickstart/validator_cheatsheet.md index f12ffe560..28a10052d 100644 --- a/docusaurus/docs/operate/quickstart/validator_cheatsheet.md +++ b/docusaurus/docs/operate/quickstart/validator_cheatsheet.md @@ -3,28 +3,196 @@ title: Validator Cheat Sheet sidebar_position: 4 --- -## Validator Cheat Sheet +This cheat sheet provides quick copy-pasta instructions for staking and running a Validator node on Pocket Network. - +:::info -This cheat sheet provides quick copy-pasta like instructions for installing and -running a Validator using an automated script. +If you're interested in understanding everything validator related, or having full control of every +step, check out the [Validator Walkthrough](../run_a_node/validator_walkthrough.md). + +::: + +- [Prerequisites](#prerequisites) +- [Account Setup](#account-setup) + - [Create the Validator Account](#create-the-validator-account) + - [Prepare your environment](#prepare-your-environment) + - [Fund the Validator account](#fund-the-validator-account) +- [Configure the Validator](#configure-the-validator) + - [Get the Validator's PubKey](#get-the-validators-pubkey) + - [Create the Validator JSON File](#create-the-validator-json-file) + - [Create the Validator](#create-the-validator) + - [Verify the Validator Status](#verify-the-validator-status) +- [Validator FAQ](#validator-faq) + - [How do I delegate additional tokens to my validator?](#how-do-i-delegate-additional-tokens-to-my-validator) + - [How do I unbond (undelegate) tokens from my validator?](#how-do-i-unbond-undelegate-tokens-from-my-validator) +- [Troubleshooting and Critical Notes](#troubleshooting-and-critical-notes) + +## Prerequisites + +1. **CLI**: Make sure to [install the `poktrolld` CLI](../user_guide/install.md). +2. **Full Node**: Make sure you have followed the [Full Node Cheat Sheet](./full_node_cheatsheet.md) to install and run a Full Node first. + +## Account Setup :::tip -If you're interested in understanding everything, or having full control of every -step, check out the [Validator Walkthrough](../run_a_node/validator_walkthrough.md). +if you're running a full node using the [Full Node Cheat Sheet](./full_node_cheatsheet.md), you can can switch to +the user you created in the full node setup to get access to the `poktrolld` CLI. Like this: + +```bash +su - poktroll # or a different user if you used a different name +``` ::: -- [Introduction](#introduction) - - [Pre-Requisites](#pre-requisites) +### Create the Validator Account + +Create a new key pair for the validator: + +```bash +poktrolld keys add validator +``` + +This will generate a new address and mnemonic. **Save the mnemonic securely**. + +### Prepare your environment + +For convenience, we're setting several environment variables to streamline +the process of interacting with the Shannon network: + +We recommend you put these in your `~/.bashrc` file: + +```bash +export NODE="https://shannon-testnet-grove-rpc.beta.poktroll.com" +export NODE_FLAGS="--node=https://shannon-testnet-grove-rpc.beta.poktroll.com" +export TX_PARAM_FLAGS="--gas=auto --gas-prices=1upokt --gas-adjustment=1.5 --chain-id=pocket-beta --yes" +export VALIDATOR_ADDR=$(poktrolld keys show validator -a) +``` + +:::tip + +As an alternative to appending directly to `~/.bashrc`, you can put the above +in a special `~/.poktrollrc` and add `source ~/.poktrollrc` to +your `~/.profile` (or `~/.bashrc`) file for a cleaner organization. + +::: + +### Fund the Validator account + +Run the following command to get the `Validator`: + +```bash +echo "Validator address: $VALIDATOR_ADDR" +``` + +Then use the [Shannon Beta TestNet faucet](https://faucet.beta.testnet.pokt.network/) to fund the validator account. + +Afterwards, you can query the balance using the following command: + +```bash +poktrolld query bank balances $VALIDATOR_ADDR $NODE_FLAGS +``` + +:::tip + +You can find all the explorers, faucets and tools at the [tools page](../../explore/tools.md). + +::: + +## Configure the Validator + +### Get the Validator's PubKey + +To get the validator's public key, run: + +```bash +poktrolld comet show-validator +``` + +This will output something like: + +```json +{ + "@type": "/cosmos.crypto.ed25519.PubKey", + "key": "YdlQyhjtrq9pk7afmz6oQ275L4FElzjzEJvB1fj3e1w=" +} +``` + +**Copy the entire output; you will need it in the next step.** + +### Create the Validator JSON File + +Create a JSON file named `validator.json` with the following content: + +```json +{ + "pubkey": { + "@type": "/cosmos.crypto.ed25519.PubKey", + "key": "YdlQyhjtrq9pk7afmz6oQ275L4FElzjzEJvB1fj3e1w=" + }, + "amount": "1000000upokt", + "moniker": "YourValidatorName", + "identity": "", + "website": "", + "security": "", + "details": "", + "commission-rate": "0.100000000000000000", + "commission-max-rate": "0.200000000000000000", + "commission-max-change-rate": "0.010000000000000000", + "min-self-delegation": "1" +} +``` + +Make the following changes: + +- Replace the `"pubkey"` value with the output from `poktrolld comet show-validator`. +- Update the `"amount"` field with the amount you wish to stake (e.g., `"1000000upokt"`). +- Set the `"moniker"` to your validator's name. +- You can optionally fill in `"identity"`, `"website"`, `"security"`, and `"details"`. + +### Create the Validator + +Run the following command to create the validator: + +```bash +poktrolld tx staking create-validator ./validator.json --from=validator $TX_PARAM_FLAGS $NODE_FLAGS +``` + +This command uses the `validator.json` file to submit the `create-validator` transaction. + +For example: + +```bash +poktrolld tx staking create-validator ./validator.json --from=validator $TX_PARAM_FLAGS $NODE_FLAGS +``` + +### Verify the Validator Status + +You can verify the status of your validator by running: + +```bash +poktrolld query staking validator $VALIDATOR_ADDR +``` + +This will display information about your validator, including its status and delegation. + +## Validator FAQ + +### How do I delegate additional tokens to my validator? + +```bash +poktrolld tx staking delegate $VALIDATOR_ADDR 1000000upokt --from your_account --chain-id=pocket-beta --gas=auto --gas-adjustment=1.5 --gas-prices=1upokt +``` -## Introduction +### How do I unbond (undelegate) tokens from my validator? -This guide will help you install a Validator on Pocket Network, -**using helpers that abstract out some of the underlying complexity.** +```bash +poktrolld tx staking unbond $VALIDATOR_ADDR 500000upokt --from your_account --chain-id=pocket-beta --gas=auto --gas-adjustment=1.5 --gas-prices=1upokt +``` -### Pre-Requisites +## Troubleshooting and Critical Notes -1. **Run a Full Node**: Make sure you have followed the [Full Node Cheat Sheet](../quickstart/full_node_cheatsheet.md) to install and run a Full Node first +- Ensure your node is fully synced before attempting to create the validator. +- Keep your mnemonic and private keys secure. +- Adjust the `"amount"` in `validator.json` and delegation amounts according to your available balance. +- The `commission-rate`, `commission-max-rate`, and `commission-max-change-rate` are expressed as decimal numbers (e.g., `0.1` for 10%). diff --git a/docusaurus/docs/operate/run_a_node/validator_walkthrough.md b/docusaurus/docs/operate/run_a_node/validator_walkthrough.md index 6c8842f52..ea93da23b 100644 --- a/docusaurus/docs/operate/run_a_node/validator_walkthrough.md +++ b/docusaurus/docs/operate/run_a_node/validator_walkthrough.md @@ -3,27 +3,232 @@ title: Validator Walkthrough sidebar_position: 4 --- -## Validator Walkthrough - - - -This walkthrough provides a detailed step-by-step instructions to run a validator node for Pocket Network. +This walkthrough provides detailed step-by-step instructions to stake and run a Validator node on Pocket Network. :::tip -If you're comfortable using an automated scripts, or simply want to _copy-pasta_ a -few commands to get started, check out the [Validator Cheat Sheet](../quickstart/validator_cheatsheet.md). +If you're interested in a simple guide with _copy-pasta_ of a few commands to get started, check out the [Validator Cheat Sheet](../quickstart/validator_cheatsheet.md) instead. ::: - [Introduction](#introduction) -- [Pre-Requisites](#pre-requisites) +- [Prerequisites](#prerequisites) +- [1. Run a Full Node](#1-run-a-full-node) +- [2. Account Setup](#2-account-setup) + - [2.1. Create the Validator Account](#21-create-the-validator-account) + - [2.2. Prepare your environment](#22-prepare-your-environment) + - [2.3. Fund the Validator Account](#23-fund-the-validator-account) +- [3. Get the Validator's Public Key](#3-get-the-validators-public-key) +- [4. Create the Validator JSON File](#4-create-the-validator-json-file) +- [5. Create the Validator](#5-create-the-validator) +- [6. Verify the Validator Status](#6-verify-the-validator-status) +- [7. Additional Commands](#7-additional-commands) +- [Notes](#notes) ## Introduction -This guide will help you install a Validator on Pocket Network, from scratch, manually, -**giving you control over each step of the process**. +This guide will help you stake and run a Validator node on Pocket Network, from scratch, manually, **giving you control over each step of the process**. + +As a Validator, you'll be participating in the consensus of the network, validating transactions, and securing the blockchain. + +## Prerequisites + +**Run a Full Node**: Ensure you have followed the [Full Node Walkthrough](./full_node_walkthrough.md) to install and run a Full Node. Your node must be fully synced with the network before proceeding. + +## 1. Run a Full Node + +Before becoming a Validator, you need to run a Full Node. If you haven't set up a Full Node yet, please follow the [Full Node Walkthrough](./full_node_walkthrough.md) to install and configure your node. + +:::tip + +if you're already running a full node using the [Full Node Walkthrough](./full_node_walkthrough.md), you can can switch to +the user you created in the full node setup to get access to the `poktrolld` CLI. Like this: + +```bash +su - poktroll # or a different user if you used a different name +``` + +::: + +Ensure your node is running and fully synchronized with the network. You can check the synchronization status by running: + +```bash +poktrolld status +``` + +## 2. Account Setup + +To become a Validator, you need a Validator account with sufficient funds to stake. + +### 2.1. Create the Validator Account + +Create a new key pair for your Validator account: + +```bash +poktrolld keys add validator +``` + +### 2.2. Prepare your environment + +For convenience, we're setting several environment variables to streamline +the process of interacting with the network: + +```bash +export NODE="https://shannon-testnet-grove-rpc.beta.poktroll.com" +export NODE_FLAGS="--node=https://shannon-testnet-grove-rpc.beta.poktroll.com" +export TX_PARAM_FLAGS="--gas=auto --gas-prices=1upokt --gas-adjustment=1.5 --chain-id=pocket-beta --yes" +export VALIDATOR_ADDR=$(poktrolld keys show validator -a) +``` + +:::tip +As an alternative to appending directly to `~/.bashrc`, you can put the above +in a special `~/.poktrollrc` and add `source ~/.poktrollrc` to +your `~/.profile` (or `~/.bashrc`) file for a cleaner organization. +::: + +### 2.3. Fund the Validator Account + +Run the following command to get the `Validator`: + +```bash +echo "Validator address: $VALIDATOR_ADDR" +``` + +Then use the [Shannon Beta TestNet faucet](https://faucet.beta.testnet.pokt.network/) to fund the validator account. + +Check the balance of your Validator account: + +```bash +poktrolld query bank balances $VALIDATOR_ADDR $NODE_FLAGS +``` + +:::tip +You can find all the explorers, faucets and tools at the [tools page](../../explore/tools.md). +::: + +## 3. Get the Validator's Public Key + +Your node has a unique public key associated with it, which is required for creating the Validator. + +To retrieve your node's public key, run: + +```bash +poktrolld comet show-validator +``` -## Pre-Requisites +This command outputs your node's public key in JSON format: + +```json +{"@type":"/cosmos.crypto.ed25519.PubKey","key":"YourPublicKeyHere"} +``` + +- Copy the entire output (including `"@type"` and `"key"`), as you'll need it for the next step. + +## 4. Create the Validator JSON File + +Create a JSON file named `validator.json` in your home directory (or any convenient location), which contains the information required to create your Validator. + +```bash +nano ~/validator.json +``` + +Paste the following content into `validator.json`, replacing placeholders with your information: + +```json +{ + "pubkey": {"@type":"/cosmos.crypto.ed25519.PubKey","key":"YourPublicKeyHere"}, + "amount": "1000000upokt", + "moniker": "YourValidatorName", + "identity": "", + "website": "", + "security": "", + "details": "", + "commission-rate": "0.10", + "commission-max-rate": "0.20", + "commission-max-change-rate": "0.01", + "min-self-delegation": "1" +} +``` + +- **Replace** `"YourPublicKeyHere"` with the `"key"` value from `poktrolld comet show-validator`. +- **Update** `"amount"` with the amount you wish to stake (e.g., `"1000000upokt"`). Ensure this amount is less than or equal to your account balance. +- **Set** `"moniker"` to your desired Validator name. This is how your Validator will appear to others. +- **Optional**: Fill in `"identity"`, `"website"`, `"security"`, and `"details"` if you wish to provide additional information about your Validator. + +Save and close the file. + +## 5. Create the Validator + +Now, you are ready to create your Validator on the network. + +Run the following command: + +```bash +poktrolld tx staking create-validator ~/validator.json --from=validator $TX_PARAM_FLAGS $NODE_FLAGS +``` + +- **Parameters**: + - `~/validator.json`: The path to your validator JSON file. + - `--from=validator`: Specifies the local key to sign the transaction. + - `--chain-id=`: Replace `` with the chain ID of the network you are joining (e.g., `pocket-beta` for testnet). + - `--gas=auto`: Automatically estimate gas required for the transaction. + - `--gas-adjustment=1.5`: Adjust the estimated gas by a factor (can help prevent out-of-gas errors). + - `--gas-prices=1upokt`: Set the gas price; adjust as needed based on network conditions. + +**Example**: + +```bash +poktrolld tx staking create-validator ~/validator.json --from=validator --chain-id=pocket-beta --gas=auto --gas-adjustment=1.5 --gas-prices=1upokt +``` + +After running the command, you should see a transaction confirmation with an output hash. + +## 6. Verify the Validator Status + +To verify that your Validator has been successfully created, run: + +```bash +poktrolld query staking validator $VALIDATOR_ADDR +``` + +This command displays information about your Validator, including status, tokens staked, commission rates, and more. + +Ensure that the `status` field indicates that your Validator is active. + +## 7. Additional Commands + +Here are some useful commands for managing your Validator: + +- **Delegate additional tokens to your Validator**: + + If you wish to increase your self-delegation or others want to delegate to your Validator, use: + + ```bash + poktrolld tx staking delegate $VALIDATOR_ADDR --from $TX_PARAM_FLAGS $NODE_FLAGS + ``` + + Replace `` with the amount to delegate (e.g., `1000000upokt`) and `` with the name of the key in your keyring. + +- **Unbond (undelegate) tokens from your Validator**: + + To unbond a portion of your staked tokens: + + ```bash + poktrolld tx staking unbond $VALIDATOR_ADDR --from $TX_PARAM_FLAGS $NODE_FLAGS + ``` + + Note that unbonding tokens initiates an unbonding period during which the tokens are locked. The unbonding period duration depends on the network configuration. + +## Notes + +- **Node Synchronization**: Your Full Node must be fully synchronized with the network before creating the Validator. Use `poktrolld status` to check synchronization status. + +- **Security**: Keep your mnemonic phrases and private keys secure. Do not share them or store them in insecure locations. + +- **Monitoring**: Regularly monitor your Validator's status to ensure it remains active and does not get jailed due to downtime or misbehavior. + +- **Upgrades**: Keep your node software up-to-date. Follow upgrade notifications in Pocket Network's [Discord](https://discord.com/invite/pocket-network) and ensure your node is running the [latest recommended version](../../protocol/upgrades/upgrade_list.md). + +--- -1. **Run a Full Node**: Make sure you have followed the [Full Node Walkthrough](../run_a_node/full_node_walkthrough.md) to install and run a Full Node first +Congratulations! You have successfully set up and run a Validator on Pocket Network. Remember to stay engaged with the community and keep your node running smoothly to contribute to the network's security and decentralization.