KiiChain

KiiChain node guide documentation

Kiichain Validator Node Setup Guide with Cosmovisor

This guide walks you through the process of setting up a Kiichain validator node on Testnet Oro using cosmovisor for seamless chain upgrades.

---

Requirements

• Golang: v1.21.x or v1.22.x (Golang v1.23.x or higher will cause compilation errors)

• Build Tools: build-essential package (for Linux)

---

1. Install Kiichain CLI

Clone the repository and build the binary:

git clone https://github.com/KiiChain/kiichain.git
cd kiichain
make install

Verify the installation:

kiichaind version

---

2. Join the Testnet

You have two options to bootstrap your node:

a. Standard Full Node

curl -O https://raw.githubusercontent.com/KiiChain/testnets/refs/heads/main/testnet_oro/join_oro.sh
chmod +x join_oro.sh
./join_oro.sh

b. Node with Cosmovisor (Recommended)

curl -O https://raw.githubusercontent.com/KiiChain/testnets/refs/heads/main/testnet_oro/join_oro_cv.sh
chmod +x join_oro_cv.sh
./join_oro_cv.sh

---

3. Initial Node Configuration

a. Backup and Clean Existing Configurations

# Backup old configuration (if any)
cp -r $HOME/.kiichain3 $HOME/.kiichain3-bk
# Remove old configuration
rm -r $HOME/.kiichain3

b. Set Environment Variables

PERSISTENT_PEERS="[e-mail]:26656,[e-mail]:26656"
CHAIN_ID=kiichain3
NODE_HOME=$HOME/.kiichain3
NODE_MONIKER=testnet_oro
GENESIS_URL=https://raw.githubusercontent.com/KiiChain/testnets/refs/heads/main/testnet_oro/genesis.json

c. Initialize the Node

kiichaind init $NODE_MONIKER --chain-id $CHAIN_ID --home $NODE_HOME

d. Set Persistent Peers

sed -i -e "/persistent-peers =/ s^= .*^= \"$PERSISTENT_PEERS\"^" $NODE_HOME/config/config.toml

e. Enable Database Features and Increase Concurrency

sed -i.bak -e "s|^occ-enabled *=.*|occ-enabled = true|" $NODE_HOME/config/app.toml
sed -i.bak -e "s|^sc-enable *=.*|sc-enable = true|" $NODE_HOME/config/app.toml
sed -i.bak -e "s|^ss-enable *=.*|ss-enable = true|" $NODE_HOME/config/app.toml
sed -i.bak -e 's/^# concurrency-workers = 20$/concurrency-workers = 500/' $NODE_HOME/config/app.toml

f. Download and Set the Genesis File

wget $GENESIS_URL -O genesis.json
mv genesis.json $NODE_HOME/config/genesis.json

(Optional) Verify the genesis file's SHA256 checksum:

sha256sum $NODE_HOME/config/genesis.json

Expected SHA256: e22442f19149db7658bcf777d086b52b38d834ea17010c313cd8aece137b647a

---

4. Configure as Validator Node

Change the node mode from full node to validator:

sed -i 's/mode = "full"/mode = "validator"/g' $NODE_HOME/config/config.toml

---

5. (Optional) Setup State Sync

State sync speeds up synchronization by downloading recent state data.

a. Determine Sync Block Height

TRUST_HEIGHT_DELTA=500
LATEST_HEIGHT=$(curl -s https://rpc.uno.sentry.testnet.v3.kiivalidator.com/block | jq -r ".block.header.height")
if [[ "$LATEST_HEIGHT" -gt "$TRUST_HEIGHT_DELTA" ]]; then
  SYNC_BLOCK_HEIGHT=$(($LATEST_HEIGHT - $TRUST_HEIGHT_DELTA))
else
  SYNC_BLOCK_HEIGHT=$LATEST_HEIGHT
fi

b. Get the Sync Block Hash

SYNC_BLOCK_HASH=$(curl -s "https://rpc.uno.sentry.testnet.v3.kiivalidator.com/block?height=$SYNC_BLOCK_HEIGHT" | jq -r ".block_id.hash")

c. Update the config.toml for State Sync

sed -i.bak -e "s|^enable *=.*|enable = true|" $NODE_HOME/config/config.toml
sed -i.bak -e "s|^rpc-servers *=.*|rpc-servers = \"https://rpc.uno.sentry.testnet.v3.kiivalidator.com,https://rpc.dos.sentry.testnet.v3.kiivalidator.com\"|" $NODE_HOME/config/config.toml
sed -i.bak -e "s|^db-sync-enable *=.*|db-sync-enable = false|" $NODE_HOME/config/config.toml
sed -i.bak -e "s|^trust-height *=.*|trust-height = $SYNC_BLOCK_HEIGHT|" $NODE_HOME/config/config.toml
sed -i.bak -e "s|^trust-hash *=.*|trust-hash = \"$SYNC_BLOCK_HASH\"|" $NODE_HOME/config/config.toml

---

6. Start the Node

Run your Kiichain node:

kiichaind start --home $NODE_HOME

---

7. Create and Register Your Validator

a. Create a New Key

Generate a key for transactions:

kiichaind keys add $VALIDATOR_KEY_NAME

Keep the mnemonic safe—it is required for account recovery.

b. Get Your Validator Public Key

kiichaind tendermint show-validator

c. Create the Validator

Replace <your-moniker> and $VALIDATOR_KEY_NAME with your values:

CHAIN_ID=kiichain3
MONIKER=<your-moniker>
AMOUNT=1000000000ukii   # 1000 kii for self-delegation
COMMISSION_MAX_CHANGE_RATE=0.1
COMMISSION_MAX_RATE=0.1
COMMISSION_RATE=0.1
MIN_SELF_DELEGATION_AMOUNT=1000000000

kiichaind tx staking create-validator \
  --amount=$AMOUNT \
  --pubkey=$(kiichaind tendermint show-validator) \
  --moniker=$MONIKER \
  --chain-id=$CHAIN_ID \
  --commission-rate=$COMMISSION_RATE \
  --commission-max-rate=$COMMISSION_MAX_RATE \
  --commission-max-change-rate=$COMMISSION_MAX_CHANGE_RATE \
  --min-self-delegation=$MIN_SELF_DELEGATION_AMOUNT \
  --gas="auto" \
  --gas-adjustment 1.3 \
  --gas-prices="0.01ukii" \
  --from=$VALIDATOR_KEY_NAME

This transaction must be sent from the machine running your node.

---

8. (Optional) Configure as an Archival Node

If you wish to save all historical states, update the pruning setting in $NODE_HOME/config/config.toml:

pruning = "nothing"

Other pruning options include default, everything, and custom.

---

9. Cosmovisor Upgrade Management

Cosmovisor is used to manage automatic chain upgrades. The cosmovisor bootstrap script (join_oro_cv.sh) already sets up your node for automated upgrades.

Adding a New Upgrade

1. Compile the new binary (ensure it is built on the correct upgrade tag, e.g., v1.0.1 or v2.0.0).

2. Verify the binary version:

   kiichaind version

3. Add the upgrade:

   cosmovisor add-upgrade <upgrade-name> <path-to-binary>

   • <upgrade-name>: The on-chain upgrade name.

   • <path-to-binary>: Full path to the new binary (e.g., /home/ubuntu/kiichain/build/kiichaind).

---

Final Notes

• System Requirements: Recommended specs are 16 vCPU, 64 GB RAM, and 1 TB NVME SSD for optimal performance.

• Monitoring: Regularly monitor your node and review logs to troubleshoot issues.

• Documentation: For additional details, consult the official Kiichain and Cosmos validator documentation.

---

Happy validating!