pezkuwi-validator-v1.0.0/README.md

Pezkuwi Validator Setup - Multi-Network Deployment v3.0.0

Complete validator setup package for Pezkuwi blockchain with support for multiple networks and distributed deployment across separate machines.

Overview

This repository provides an automated setup system for deploying Pezkuwi blockchain validators across distributed infrastructure. Designed for multi-network deployment (beta testnet, staging, mainnet) with each validator running on its own dedicated machine.

Architecture

Distributed Deployment Model:

• Each validator runs on a separate physical/virtual machine
• Each validator builds its own SDK and frontend locally
• Validators connect sequentially: V2→V1, V3→V2, V4→V3, etc.
• Bootnode information shared manually between operators
• No shared resources between validators

Network Support:

• Beta Testnet: 8 validators (fully configured with keys)
• Staging: 20 validators (validator1 ready, others to be added)
• Mainnet: 100 validators (validator1 ready, others to be added)

Features

• ✅ One-command setup - Single command for complete validator deployment
• ✅ Automatic dependency installation - Detects and installs all required tools
• ✅ Multi-network support - Beta testnet, staging, and mainnet configurations
• ✅ Distributed architecture - Each validator on separate machine
• ✅ User-safe builds - All builds run as actual user (not root)
• ✅ Pre-configured keys - Real validator keys for beta testnet
• ✅ Systemd integration - Production-ready service management
• ✅ Nginx deployment - Frontend served via Nginx
• ✅ First-time user friendly - Designed for terminal beginners

System Requirements

Required Dependencies

The setup script automatically installs:

• Git - Version control
• Rust & Cargo - Substrate/Polkadot SDK compilation
• Node.js & npm - Frontend build (v20.x)
• Build tools - build-essential, clang, libssl-dev, pkg-config
• Nginx - Frontend web server
• Systemd - Service management (included in Ubuntu)

Recommended Hardware

Per Validator:

• OS: Ubuntu 20.04 LTS or newer
• CPU: 4+ cores
• RAM: 8GB minimum, 16GB recommended
• Storage: 100GB+ SSD
• Network: Stable internet connection with public IP
• Ports: Firewall configured for P2P communication

Repository Structure

pezkuwi-validator/
├── README.md                              # This file
├── .gitignore                             # Git ignore rules
├── setup.sh                               # Multi-network setup script (v3.0.0)
│
├── beta_testnet/                          # Beta Testnet (8 validators)
│   ├── validators/
│   │   ├── validator1/config/keys.sh     # Bootnode (RPC: 9944, P2P: 30333)
│   │   ├── validator2/config/keys.sh     # RPC: 9945, P2P: 30334
│   │   ├── validator3/config/keys.sh     # RPC: 9946, P2P: 30335
│   │   ├── validator4/config/keys.sh     # RPC: 9947, P2P: 30336
│   │   ├── validator5/config/keys.sh     # RPC: 9948, P2P: 30337
│   │   ├── validator6/config/keys.sh     # RPC: 9949, P2P: 30338
│   │   ├── validator7/config/keys.sh     # RPC: 9950, P2P: 30339
│   │   └── validator8/config/keys.sh     # RPC: 9951, P2P: 30340
│   └── chain-specs/                      # Network chain specifications
│
├── staging/                               # Staging Network (20 validators)
│   ├── validators/
│   │   └── validator1/config/            # More validators to be added
│   └── chain-specs/
│
└── mainnet/                               # Production Network (100 validators)
    ├── validators/
    │   └── validator1/config/            # More validators to be added
    └── chain-specs/

Quick Start

For Validator Operators

You will receive a single command via WhatsApp that looks like this:

# Example: Setting up validator 8 on beta testnet
git clone https://github.com/pezkuwichain/pezkuwi-validator-v1.0.0.git
cd pezkuwi-validator-v1.0.0
sudo ./setup.sh beta_testnet 8

That's it! The script will:

1. ✅ Check and install all missing dependencies
2. ✅ Clone and build Pezkuwi SDK (~15-30 minutes)
3. ✅ Clone and build DKSweb frontend
4. ✅ Prompt for bootnode information (if validator > 1)
5. ✅ Configure validator-specific settings
6. ✅ Create systemd service
7. ✅ Setup Nginx for frontend
8. ✅ Provide clear next-step instructions

Setup Script Usage

sudo ./setup.sh <network> <validator_number>

Parameters:

• <network>: Network to deploy on

  • beta_testnet - Beta testnet (8 validators)
  • staging - Staging network (20 validators)
  • mainnet - Production network (100 validators)

• <validator_number>: Your validator number (1-8 for beta, 1-20 for staging, 1-100 for mainnet)

Examples:

# Beta testnet validator 1 (bootnode)
sudo ./setup.sh beta_testnet 1

# Beta testnet validator 8
sudo ./setup.sh beta_testnet 8

# Staging network validator 5
sudo ./setup.sh staging 5

# Mainnet validator 42
sudo ./setup.sh mainnet 42

Port Allocation

Each validator uses sequential ports:

Validator	RPC Port	P2P Port	WebSocket	Prometheus
1 (Boot)	9944	30333	9944	9615
2	9945	30334	9945	9616
3	9946	30335	9946	9617
4	9947	30336	9947	9618
5	9948	30337	9948	9619
6	9949	30338	9949	9620
7	9950	30339	9950	9621
8	9951	30340	9951	9622

Pattern: Each subsequent validator increments all ports by 1.

Validator Management

Systemd Service Commands

The setup script creates a systemd service for each validator:

# Start your validator
sudo systemctl start pezkuwi-validator-beta_testnet-8

# Stop your validator
sudo systemctl stop pezkuwi-validator-beta_testnet-8

# Restart your validator
sudo systemctl restart pezkuwi-validator-beta_testnet-8

# Check validator status
sudo systemctl status pezkuwi-validator-beta_testnet-8

# View live logs
sudo journalctl -u pezkuwi-validator-beta_testnet-8 -f

# Enable auto-start on boot
sudo systemctl enable pezkuwi-validator-beta_testnet-8

# Disable auto-start
sudo systemctl disable pezkuwi-validator-beta_testnet-8

Service Name Pattern: pezkuwi-validator-<network>-<validator_number>

Examples:

• pezkuwi-validator-beta_testnet-1
• pezkuwi-validator-staging-5
• pezkuwi-validator-mainnet-42

Log Files

Logs are stored in your validator directory:

# After setup completes, logs are at:
# /home/mamostehp/pezkuwi-validator/beta_testnet/validators/validator8/logs/

# View validator log
tail -f ~/pezkuwi-validator/beta_testnet/validators/validator8/logs/validator.log

# View error log
tail -f ~/pezkuwi-validator/beta_testnet/validators/validator8/logs/validator-error.log

Validator Keys

Each beta testnet validator has 6 types of pre-configured keys:

• BABE - Block authorship (sr25519)
• GRANDPA - Finality (ed25519)
• PARA - Parachain validation (sr25519)
• ASGN - Assignment (sr25519)
• AUDI - Authority discovery (sr25519)
• BEEF - BEEFY consensus (ecdsa)

Keys are stored in:

beta_testnet/validators/validator<N>/config/keys.sh

⚠️ SECURITY WARNING:

• Beta testnet keys are for testing only
• Never use testnet keys in staging or production
• Keep production keys secure and backed up offline
• Never commit private keys to version control

Bootnode Connection

For Validator 1 (Bootnode)

After starting your validator, you'll need to share your bootnode information:

1. Start your validator:

   sudo systemctl start pezkuwi-validator-beta_testnet-1
   

2. Check logs for your peer ID:

   tail -f ~/pezkuwi-validator/beta_testnet/validators/validator1/logs/validator.log | grep "Local node identity"
   

3. You'll see something like:

   Local node identity is: 12D3KooWAbCdEf...
   

4. Share your bootnode multiaddr with validator 2:

   /ip4/YOUR_PUBLIC_IP/tcp/30333/p2p/12D3KooWAbCdEf...
   

For Validators 2-8

During setup, you'll be prompted:

Please obtain the bootnode multiaddr from validator N-1
Enter bootnode multiaddr (or press Enter to skip):

Paste the multiaddr you received from the previous validator.

Frontend Access

After setup, the DKSweb frontend is available at:

• Local: http://localhost
• Network: http://YOUR_SERVER_IP

The frontend connects to your local validator node and provides:

• Wallet management
• Token transfers
• Staking operations
• Network statistics

Troubleshooting

Setup Script Fails

Check dependency installation:

# The script should auto-install, but you can manually check:
git --version
rustc --version
cargo --version
node --version
npm --version
nginx -v

Permission issues:

# Make sure you're running with sudo:
sudo ./setup.sh beta_testnet 8

Validator Won't Start

Check service status:

sudo systemctl status pezkuwi-validator-beta_testnet-8

Check logs:

sudo journalctl -u pezkuwi-validator-beta_testnet-8 -n 100

Common issues:

• Port already in use
• Keys not inserted properly
• Insufficient disk space
• Network connectivity issues
• Invalid bootnode address

Port Already in Use

# Check what's using the port:
sudo lsof -i :9951

# Kill the process if needed:
sudo kill -9 <PID>

# Restart your validator:
sudo systemctl restart pezkuwi-validator-beta_testnet-8

Clear Blockchain Data

If you need to reset and sync from scratch:

# Stop validator
sudo systemctl stop pezkuwi-validator-beta_testnet-8

# Clear blockchain data
rm -rf ~/pezkuwi-validator/beta_testnet/validators/validator8/data/*

# Start validator
sudo systemctl start pezkuwi-validator-beta_testnet-8

Rebuild SDK

If SDK update is released:

# Navigate to SDK directory
cd ~/pezkuwi-sdk

# Pull latest changes
git pull origin main

# Clean and rebuild
cargo clean
cargo build --release

# Restart your validator
sudo systemctl restart pezkuwi-validator-beta_testnet-8

Frontend Not Loading

# Check Nginx status
sudo systemctl status nginx

# Check Nginx error logs
sudo tail -f /var/log/nginx/error.log

# Restart Nginx
sudo systemctl restart nginx

Re-insert Keys

If keys need to be re-inserted:

# Source your keys
cd ~/pezkuwi-validator
source beta_testnet/validators/validator8/config/keys.sh

# Insert BABE key (example)
curl -H "Content-Type: application/json" \
  -d "{\"id\":1,\"jsonrpc\":\"2.0\",\"method\":\"author_insertKey\",\"params\":[\"babe\",\"$BABE_SEED\",\"$BABE_PUBLIC_KEY\"]}" \
  http://127.0.0.1:9951

# Repeat for other key types: gran, para, asgn, audi, beef

Network Information

Beta Testnet

• Chain Spec: pezkuwichain-beta-testnet
• Validators: 8
• Purpose: Testing and development
• Bootnode: Validator 1

Staging

• Chain Spec: pezkuwichain-staging
• Validators: 20 (planned)
• Purpose: Pre-production testing
• Status: Under development

Mainnet

• Chain Spec: pezkuwichain-mainnet
• Validators: 100 (planned)
• Purpose: Production network
• Status: Under development

Maintenance

Update SDK

cd ~/pezkuwi-sdk
git pull origin main
cargo build --release
sudo systemctl restart pezkuwi-validator-beta_testnet-8

Update Frontend

cd ~/DKSweb
git pull origin main
npm install
npm run build
sudo systemctl restart nginx

Backup Validator Keys

# Backup your keys (do this regularly!)
cp ~/pezkuwi-validator/beta_testnet/validators/validator8/config/keys.sh \
   ~/validator8-keys-backup-$(date +%Y%m%d).sh

# Copy to secure location (offline storage recommended)
# NEVER commit keys to git or store unencrypted online

Monitor Validator

# Live logs
sudo journalctl -u pezkuwi-validator-beta_testnet-8 -f

# Check if producing blocks
tail -f ~/pezkuwi-validator/beta_testnet/validators/validator8/logs/validator.log | grep "Prepared block"

# Check peer count
tail -f ~/pezkuwi-validator/beta_testnet/validators/validator8/logs/validator.log | grep "peers"

Security Best Practices

1. 🔒 Firewall Configuration

   • Only expose P2P port (30333+) to internet
   • Block RPC/WebSocket ports from external access
   • Use SSH key-based authentication only

2. 🔑 Key Management

   • Backup keys to offline storage
   • Never share private keys or seeds
   • Use different keys for each network
   • Rotate keys periodically

3. 🛡️ System Security

   • Keep system updated: sudo apt update && sudo apt upgrade
   • Run validator as non-root user
   • Enable automatic security updates
   • Monitor logs for suspicious activity

4. 📊 Monitoring

   • Set up monitoring alerts
   • Check validator uptime regularly
   • Monitor disk space usage
   • Watch for sync issues

5. 💾 Backups

   • Backup validator keys regularly
   • Document your validator setup
   • Keep recovery procedures updated

Support

Getting Help

1. Check logs first:

   sudo journalctl -u pezkuwi-validator-beta_testnet-8 -n 200
   

2. Review this README - Most common issues are documented here

3. Check validator status:

   sudo systemctl status pezkuwi-validator-beta_testnet-8
   

4. Contact the team - Reach out via official Pezkuwi channels

Common Questions

Q: How long does initial sync take? A: Initial blockchain sync can take several hours depending on network size and your connection speed.

Q: Can I run multiple validators on one machine? A: Not recommended for this deployment model. Each validator should have dedicated hardware.

Q: What if I lose my keys? A: Always backup keys securely. Lost keys mean lost validator access.

Q: Can I change my validator number? A: No, validator numbers are assigned and fixed per network.

Contributing

This is a production deployment repository. Changes should be coordinated with the Pezkuwi team.

License

This validator package is part of the Pezkuwi blockchain project.

---

Package Version: v3.0.0 Last Updated: 2025-11-06 Architecture: Distributed Multi-Network Deployment Supported Networks: Beta Testnet (8), Staging (20), Mainnet (100)

Repository: https://github.com/pezkuwichain/pezkuwi-validator-v1.0.0