From 8a6cbb17483258cda42f8feca786aba7bfba945d Mon Sep 17 00:00:00 2001 From: HermanKoii Date: Thu, 27 Mar 2025 23:09:59 +0000 Subject: [PATCH] Update README.md with comprehensive documentation for K2 Validator setup --- README.md | 407 ++++++++++++++---------------------------------------- 1 file changed, 107 insertions(+), 300 deletions(-) diff --git a/README.md b/README.md index 8926e91..1d0a487 100644 --- a/README.md +++ b/README.md @@ -1,334 +1,141 @@ -# How to Set Up and Run a K2 Validator - -## Table of Contents - -- [Run a K2 Validator](#run-a-k2-validator) - - [Validator Requirements](#validator-requirements) - - [Minimum Koii requirements](#minimum-koii-requirements) - - [Hardware requirements](#hardware-requirements) - - [Pre-requisites setup](#pre-requisites-setup) - - [1. Ensure system is up-to-date](#1-ensure-system-is-up-to-date) - - [2. User setup](#2-user-setup) - - [3. Koii cli setup](#3-koii-cli-setup) - - [4. Key pairs creation](#4-key-pairs-creation) - - [5. Network configuration](#5-network-configuration) - - [6. Systuning setup](#6-systuning-setup) - - [Validator setup](#validator-setup) - - [1. Systemd service setup](#1-systemd-service-setup) - - [2. Create a vote account](#2-create-a-vote-account) - - [3. Enable and Start the Koii validator](#3-enable-and-start-the-koii-validator) - - [4. Configure the Commission Rate for Your Validator](#4-configure-the-commission-rate-for-your-validator) - - [5. Update Your Validator Information](#5-update-your-validator-information) - - [Staking KOII in the validator](#staking-koii-in-the-validator) - - [1. Create a stake account](#1-create-a-stake-account) - - [2. Delegate the stake to your validator](#2-delegate-the-stake-to-your-validator) - - [3. Check your delegated stake's status](#3-check-your-delegated-stakes-status) - - -## Validator Requirements - -### Minimum Koii requirements - -There is no minimum amount of KOII required to stake and participate in the voting process. - -To participate in the voting process you must configure your system, start a validator, and configure your voting and stake accounts. This guide will show you how to do this. - -### Hardware requirements - -Here are the minimum hardware requirements for running a K2 Validator in terms of memory, computing, storage, and your operating system: - -- Memory - - 256GB, or more for consensus validator nodes - - 512GB, or more for RPC nodes -- Compute - - 12 cores / 24 threads, or more @ minimum of 2.8GHz for consensus validator nodes - - 16 cores / 32 threads, or more for RPC nodes -- Storage - - - - For consensus validators: - - - PCIe Gen3 x4 NVME SSD, or better - - Accounts: 500GB, or larger. High TBW (Total Bytes Written) - - Ledger: 2TB or larger. High TBW suggested - - For RPC nodes: - - - A larger ledger disk if longer transaction history is required, accounts and ledger should not be stored on the same disk - - GPUs are not strictly necessary - - Network: 1 Gbps uplink and downlink speed, must be unshaped and unmetered - - Operating System - -Currently, we are testing our binaries for Ubuntu 22.04. We do provide binaries for other operating systems however the operation of these binaries is not guaranteed. - -Once a properly sized Ubuntu 22.04 system is available we can begin to configure the system for operation of a validator node. - ---- - -## Pre-requisites setup - -> **All following steps need to be run on the validator server, unless mentioned otherwise.** -> - -### 1. Ensure system is up-to-date - -Ensure your Ubuntu system is up-to-date and has all the base packages required - +# K2 Validator Setup Guide for Koii Network + +## Project Overview + +This repository provides a comprehensive guide and installation scripts for setting up a validator node on the Koii Network's K2 blockchain. The project is designed to help blockchain enthusiasts, developers, and network participants establish and maintain a Koii validator with detailed, step-by-step instructions. + +🔗 **Network**: Koii Mainnet +🌐 **Blockchain**: K2 (Koii's Layer 1 Blockchain) + +### Key Objectives +- Provide a complete walkthrough for K2 validator setup +- Offer installation scripts for different versions +- Guide users through technical requirements and configuration steps + +## Features / Capabilities + +- Detailed validator setup instructions +- Scripts for different K2 release versions +- Comprehensive network and system configuration guidance +- Step-by-step validator initialization process +- Instructions for: + - System preparation + - Keypair generation + - Vote account creation + - Stake delegation + - Validator configuration + +## Technologies Used + +- **Operating System**: Ubuntu 22.04 (recommended) +- **Languages/Tools**: + - Shell Scripting + - Koii CLI +- **Blockchain**: Koii K2 Network +- **Key Components**: + - Systemd + - UFW (Uncomplicated Firewall) + +## System Requirements + +### Minimum Hardware Specifications +- **Memory**: + - 256GB for consensus validator nodes + - 512GB for RPC nodes +- **Compute**: + - 12 cores / 24 threads @ 2.8GHz (consensus validator) + - 16 cores / 32 threads (RPC nodes) +- **Storage**: + - PCIe Gen3 x4 NVME SSD + - Accounts: 500GB high TBW + - Ledger: 2TB high TBW + +### Network Requirements +- 1 Gbps symmetrical uplink/downlink +- Unshaped and unmetered connection + +## Getting Started + +### Prerequisites +1. Ubuntu 22.04 server +2. Basic Linux administration skills +3. KOII tokens for staking + +### Quick Installation ```bash +# Update system sudo apt update && sudo apt upgrade -sudo apt install libssl-dev libudev-dev pkg-config zlib1g-dev llvm clang -``` - -### 2. User setup -```bash -sudo adduser koii -sudo usermod -aG sudo koii -sudo su koii -cd ~ -``` - - - -### 3. Koii cli setup - -* Required both on your secure computer for keypair generation and on the validator - -```bash +# Install Koii CLI sh -c "$(curl -sSfL https://raw.githubusercontent.com/koii-network/k2-release/master/k2-install-init_v1.16.6.sh)" -# You may need to update PATH variable for the cli to be available -echo 'export PATH="/home/koii/.local/share/koii/install/active_release/bin:$PATH"' >> ~/.bashrc -source ~/.bashrc -# Set the koii config to point to the testnet -koii config set --url https://mainnet.koii.network +# Configure Koii CLI +koii config set --url https://mainnet.koii.network ``` -### 4. Key pairs creation - -> Run commands for **only this step** on a **secure computer** **separate from the validator server** -You need to **install Koii cli on this secure computer** as well, to be able to use the commands below -> - -We will be creating the following 4 key pairs: +## Usage Examples +### Generate Validator Keypairs ```bash +# On a secure computer koii-keygen new --outfile ~/validator-keypair.json koii-keygen new --outfile ~/vote-account-keypair.json -koii-keygen new --outfile ~/stake-account-keypair.json -koii-keygen new --outfile ~/authorized-withdrawer-keypair.json -# To print your Public key(i.e. Wallet address) for any keypairs -# koii-keygen pubkey ``` -- **validator-keypair.json :** Identity of the validator on the network - - Copy this to the remote validator server at `/home/koii/validator-keypair.json` -- **vote-account-keypair.json** : Voting account on the network - - Copy this to the remote validator server at `/home/koii/vote-account-keypair.json` -- **stake-account-keypair.json** : Keypair for your staking wallet - - Keep this secure since this will hold the wallet that you delegate stake from -- **authorized-withdrawer-keypair.json** : Authorized withdrawer keypair, allowd to withdraw funds from your validator vote account **** - - - - - -### 5. Network configuration - -If you have firewall software installed you will need to allow traffic on the following ports: - -```bash -sudo ufw allow 10000:10500/udp -sudo ufw allow 10000:10500/tcp -sudo ufw allow 10899/tcp -sudo ufw allow 10900/tcp -``` - -### 6. Systuning setup - -- Create a file at `/etc/systemd/system/systuner.service` : - - ```bash - [Unit] - Description=Koii System Tuner - After=network.target - [Service] - Type=simple - Restart=on-failure - RestartSec=1 - ExecStart=/home/koii/.local/share/koii/install/active_release/bin/koii-sys-tuner --user koii - [Install] - WantedBy=multi-user.target - - ``` - -- Start and Enable the service to automatically start - - ```bash - sudo systemctl start systuner - sudo systemctl enable systuner - ``` - - ---- - -## Validator setup - -### 1. Systemd service setup - -**Copy the following file to `/home/koii/validator.sh` and make it executable** - -```bash -#!/bin/sh -exec /home/koii/.local/share/koii/install/active_release/bin/koii-validator \ - --identity /home/koii/validator-keypair.json \ - --vote-account /home/koii/vote-account-keypair.json \ - --ledger /home/koii/ledger/ledgerdb \ - --accounts /home/koii/accounts/accountdb \ - --log /home/koii/koii-rpc.log \ - --rpc-bind-address 0.0.0.0 \ - --rpc-port 10899 \ - --gossip-port 10001 \ - --dynamic-port-range 10002-10500 \ - --enable-rpc-transaction-history \ - --known-validator BPRAynHogErzYmEtAaeJFugRozXuU6EEqNa4rEKtF4mS \ - --known-validator GqmBXoaetkMXzrMhCijJDsL5J4KDvDFzZuMEpoXYUowc \ - --known-validator Hajii3WYcyRWDzENPJwaY2WGtNpYQ7vrCqpgaUi8fsUo \ - --known-validator Fme35immspxuG6fboueneNDque5xLu62Ca2BHRuLgTSV \ - --entrypoint entrypoint-1.mainnet.koii.network:10001 \ - --entrypoint entrypoint-2.mainnet.koii.network:10001 \ - --entrypoint entrypoint.mainnet.haji.ro:10001 \ - --entrypoint entrypoint-koii-mainnet.stakecraft.com:10001 \ - --rpc-faucet-address rpc-faucet.testnet.koii.network:9900 \ - --init-complete-file /home/koii/init-completed \ - --no-wait-for-vote-to-start-leader \ - --enable-extended-tx-metadata-storage \ - --maximum-full-snapshots-to-retain 20 \ - --maximum-incremental-snapshots-to-retain 20 \ - --limit-ledger-size 200000000 \ - --only-known-rpc \ - --wal-recovery-mode skip_any_corrupted_record \ - --expected-genesis-hash 7rVVciNgm2m5JquMbKNxEYPryvzVtDktWhHLM4xFpfjq - -``` - -**Create a systemd unit file at `/etc/systemd/system/koii-validator.service`** - -```bash -[Unit] -Description=Koii Validator -After=network.target -Wants=systuner.service -StartLimitIntervalSec=0 -[Service] -User=koii -Group=koii -LimitNOFILE=1000000 -LogRateLimitIntervalSec=0 -Environment="PATH=/home/koii/.local/share/koii/install/active_release/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games" -ExecStart=/home/koii/validator.sh -Restart=on-failure -RestartSec=10 -[Install] -WantedBy=multi-user.target -``` - -### 2. Create a vote account - - - - - -Run the following command to create a vote-account on the network: - +### Create Vote Account ```bash +# After funding your validator identity koii create-vote-account ~/vote-account-keypair.json ~/validator-keypair.json ~/authorized-withdrawer-keypair.json ``` -### 3. Enable and Start the Koii validator - +### Stake KOII Tokens ```bash -sudo systemctl enable koii-validator.service -sudo systemctl start koii-validator.service -sudo systemctl status koii-validator.service +# Delegate stake to your validator +koii delegate-stake ~/stake-account-keypair.json ~/vote-account-keypair.json ``` -### 4. Configure the Commission Rate for Your Validator +## Versioning -The commission rate determines the percentage of staking rewards allocated to the validator as a fee for their services, with the remainder distributed to the stakers. The commission rate must be a valid percentage between 0 and 100. +This repository includes multiple installation scripts for different K2 releases: +- v1.14.19 +- v1.14.20 +- v1.14.21 +- v1.15.0 +- v1.16.0 to v1.16.6 -To update the commission rate for your validator's vote account, use the following command: +Always use the latest version recommended by the Koii Network. -```bash -koii vote-update-commission --authorized-voter -``` -### 5. Update Your Validator Information +## Security Considerations -To update or publish your validator's information on the Koii network, use the following command: +⚠️ **Important Security Notes**: +- Keep validator and withdrawer keypairs secure +- Never share private keys +- Use a separate secure computer for key generation +- Implement proper firewall and network security -```bash -koii validator-info publish "" -w "" -``` ---- +## Troubleshooting -## Staking KOII in the validator +- Check systemd service status: `sudo systemctl status koii-validator` +- Verify Koii CLI configuration: `koii config get` +- Review logs at `/home/koii/koii-rpc.log` -> Commands in this section are to be run on the computer which has the stake account key pair (**NOT ON VALIDATOR**) +## Contributing -### 1. Create a stake account +Contributions are welcome! Please: +- Report issues on the GitHub repository +- Submit pull requests with improvements +- Follow Koii Network's contribution guidelines -Run the following command, AFTER replacing . +## License -```bash -koii create-stake-account ~/stake-account-keypair.json --stake-authority ~/validator-keypair.json --withdraw-authority ~/authorized-withdrawer-keypair.json -``` - -### 2. Delegate the stake to your validator +This project is open-source. Please refer to the LICENSE file for detailed information. -```bash -koii delegate-stake ~/stake-account-keypair.json ~/vote-account-keypair.json --stake-authority ~/validator-keypair.json --force -``` +## Support -### 3. Check your delegated stake’s status +For additional support: +- Koii Network Documentation: [https://docs.koii.network](https://docs.koii.network) +- Community Discord: [Koii Network Discord](https://discord.gg/koii) -Your validator will not show up in the koii validators list for 12 to 24 hours, you can check your stake to make sure it is properly delegated by running the following command - -```bash -koii stake-account ~/stake-account-keypair.json -``` - -Expected output: - -```bash -Balance: -Rent Exempt Reserve: -Delegated Stake: -Activating Stake: -Delegated Vote Account Address: -Stake Authority: -Withdraw Authority: -``` +--- -If you see a value in “Activating Stake” then you should be successfully voting within 24 hours +*Disclaimer: Running a validator involves technical complexity and financial risks. Always do thorough research and understand the responsibilities.* \ No newline at end of file