pezkuwichain/pezkuwi-validator-v1.0.0
1
0
Fork 0
mirror of https://github.com/pezkuwichain/pezkuwi-validator-v1.0.0.git synced 2026-04-21 23:37:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Update README for v3.0.0 distributed multi-network architecture

Browse Source 
- Updated for distributed deployment model (8 separate machines)
- Added multi-network documentation (beta_testnet, staging, mainnet)
- Comprehensive setup instructions for validator operators
- Bootnode connection guide for sequential validator deployment
- Enhanced troubleshooting section
- Added security best practices
- Updated system requirements and port allocation
- Removed references to shared resources/single machine
- Added detailed validator management commands
- Updated to v3.0.0 package version
This commit is contained in:
Kurdistan Tech Ministry
2025-11-06 08:28:50 +03:00
parent f08f0017d1
commit dc17d8f986
1 changed files with 399 additions and 215 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+399 -215
View File
@@ -1,196 +1,214 @@
# Pezkuwi Beta Testnet - Validator Package v2.0.0
# Pezkuwi Validator Setup - Multi-Network Deployment v3.0.0
Simplified validator setup package for Pezkuwi blockchain beta testnet with 8 validators running on a single machine.
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** - Automated installation and configuration
- **Automatic dependency checking** - Detects and guides installation of required tools
- **Shared SDK build** - Single Pezkuwi-SDK build shared across all validators
- **Single DKSweb frontend** - One frontend instance with auto-update from GitHub
- **Real validator keys** - Pre-configured with actual beta testnet validator keys
- **Systemd service management** - Easy start/stop/restart with systemd
- **Helper scripts** - Convenient management scripts for all validators
- **Nginx deployment** - Production-ready frontend deployment
- ✅ **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 (v16+ recommended)
- **Build tools** - build-essential, cmake, clang, libssl-dev, pkg-config
- **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 System
### Recommended Hardware
**Per Validator:**
- **OS**: Ubuntu 20.04 LTS or newer
- **CPU**: 4+ cores
- **RAM**: 8GB+
- **Storage**: 50GB+ SSD
- **Network**: Stable internet connection
- **RAM**: 8GB minimum, 16GB recommended
- **Storage**: 100GB+ SSD
- **Network**: Stable internet connection with public IP
- **Ports**: Firewall configured for P2P communication
## Directory Structure
## Repository Structure
```
beta_testnet/
├── README.md # This file
├── setup.sh # Main setup script
├── config/ # Global configuration
├── scripts/ # Helper scripts
│ ├── start.sh # Start individual validator
│ ├── stop.sh # Stop individual validator
│ ├── status.sh # Check validator status
│ └── logs.sh # View validator logs
├── validators/ # Validator-specific data
│ ├── validator1/
│ │ ├── config/
│ │ │ └── keys.sh # Validator 1 keys (RPC: 9944, Bootnode)
│ │ ├── data/ # Blockchain data
│ │ ├── keys/ # Keystore
│ │ └── logs/ # Log files
│ ├── validator2/ # RPC: 9945, P2P: 30334
│ ├── validator3/ # RPC: 9946, P2P: 30335
│ ├── validator4/ # RPC: 9947, P2P: 30336
│ ├── validator5/ # RPC: 9948, P2P: 30337
│ ├── validator6/ # RPC: 9949, P2P: 30338
│ ├── validator7/ # RPC: 9950, P2P: 30339
│ └── validator8/ # RPC: 9951, P2P: 30340
├── shared/ # Shared resources
│ ├── pezkuwi-sdk/ # Shared SDK build
│ └── dksweb/ # Shared frontend
└── systemd/ # Systemd service templates
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:
```bash
# 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
```bash
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:**
```bash
# 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
| Validator | RPC Port | P2P Port | WS Port | 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 |
Each validator uses sequential ports:
## Quick Start
| 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 |
### 1. Initial Setup
**Pattern:** Each subsequent validator increments all ports by 1.
Run the main setup script with a validator number (1-8):
## Validator Management
### Systemd Service Commands
The setup script creates a systemd service for each validator:
```bash
cd /home/mamostehp/pezkuwi-validator-v2.0.0/beta_testnet
sudo ./setup.sh 1
```
# Start your validator
sudo systemctl start pezkuwi-validator-beta_testnet-8
This will:
- Check all dependencies
- Clone/update Pezkuwi-SDK (if needed)
- Build SDK in release mode (shared build)
- Clone/update DKSweb frontend (if needed)
- Build and deploy frontend with Nginx
- Insert validator keys
- Create systemd service
- Start the validator
# Stop your validator
sudo systemctl stop pezkuwi-validator-beta_testnet-8
### 2. Setup Additional Validators
# Restart your validator
sudo systemctl restart pezkuwi-validator-beta_testnet-8
```bash
sudo ./setup.sh 2
sudo ./setup.sh 3
# ... up to 8
```
# Check validator status
sudo systemctl status pezkuwi-validator-beta_testnet-8
### 3. Verify All Validators Are Running
```bash
./scripts/status.sh
```
## Helper Scripts Usage
### Start Validator
Start a single validator:
```bash
./scripts/start.sh 1
```
Start all validators:
```bash
for i in {1..8}; do ./scripts/start.sh $i; done
```
### Stop Validator
Stop a single validator:
```bash
./scripts/stop.sh 1
```
Stop all validators:
```bash
for i in {1..8}; do ./scripts/stop.sh $i; done
```
### Check Status
Check single validator:
```bash
./scripts/status.sh 1
```
Check all validators:
```bash
./scripts/status.sh
```
### View Logs
View logs for a validator:
```bash
./scripts/logs.sh 1
```
Follow logs in real-time:
```bash
./scripts/logs.sh 1 follow
```
## Systemd Service Management
Validators are managed as systemd services:
```bash
# Start validator
sudo systemctl start pezkuwi-validator-1
# Stop validator
sudo systemctl stop pezkuwi-validator-1
# Restart validator
sudo systemctl restart pezkuwi-validator-1
# Check status
sudo systemctl status pezkuwi-validator-1
# View logs
sudo journalctl -u pezkuwi-validator-1 -f
# View live logs
sudo journalctl -u pezkuwi-validator-beta_testnet-8 -f
# Enable auto-start on boot
sudo systemctl enable pezkuwi-validator-1
sudo systemctl enable pezkuwi-validator-beta_testnet-8
# Disable auto-start
sudo systemctl disable pezkuwi-validator-1
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:
```bash
# 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 validator has 6 types of keys pre-configured in `validators/validatorN/config/keys.sh`:
Each beta testnet validator has 6 types of pre-configured keys:
- **BABE** - Block authorship (sr25519)
- **GRANDPA** - Finality (ed25519)
@@ -199,117 +217,218 @@ Each validator has 6 types of keys pre-configured in `validators/validatorN/conf
- **AUDI** - Authority discovery (sr25519)
- **BEEF** - BEEFY consensus (ecdsa)
**SECURITY WARNING**: These keys are for beta testnet only. Never use testnet keys in production!
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:
```bash
sudo systemctl start pezkuwi-validator-beta_testnet-1
```
2. Check logs for your peer ID:
```bash
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, DKSweb frontend is available at:
- **Local**: http://localhost (via Nginx)
After setup, the DKSweb frontend is available at:
- **Local**: http://localhost
- **Network**: http://YOUR_SERVER_IP
The frontend connects to validator 1 (bootnode) by default at `ws://127.0.0.1:9944`.
The frontend connects to your local validator node and provides:
- Wallet management
- Token transfers
- Staking operations
- Network statistics
## Troubleshooting
### Validator Won't Start
### Setup Script Fails
Check logs:
**Check dependency installation:**
```bash
./scripts/logs.sh 1
# or
sudo journalctl -u pezkuwi-validator-1 -n 100
# The script should auto-install, but you can manually check:
git --version
rustc --version
cargo --version
node --version
npm --version
nginx -v
```
Common issues:
**Permission issues:**
```bash
# Make sure you're running with sudo:
sudo ./setup.sh beta_testnet 8
```
### Validator Won't Start
**Check service status:**
```bash
sudo systemctl status pezkuwi-validator-beta_testnet-8
```
**Check logs:**
```bash
sudo journalctl -u pezkuwi-validator-beta_testnet-8 -n 100
```
**Common issues:**
- Port already in use
- Keys not inserted properly
- Insufficient permissions
- Blockchain data corruption
- Insufficient disk space
- Network connectivity issues
- Invalid bootnode address
### Port Already in Use
Check what's using the port:
```bash
sudo lsof -i :9944
```
# Check what's using the port:
sudo lsof -i :9951
Kill the process:
```bash
# Kill the process if needed:
sudo kill -9 <PID>
# Restart your validator:
sudo systemctl restart pezkuwi-validator-beta_testnet-8
```
### Clear Blockchain Data
To reset a validator's blockchain data:
If you need to reset and sync from scratch:
```bash
sudo systemctl stop pezkuwi-validator-1
rm -rf /home/mamostehp/pezkuwi-validator-v2.0.0/beta_testnet/validators/validator1/data/*
sudo systemctl start pezkuwi-validator-1
# 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 you need to rebuild the SDK:
If SDK update is released:
```bash
cd /home/mamostehp/pezkuwi-validator-v2.0.0/beta_testnet/shared/pezkuwi-sdk
# 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:
```bash
# Check Nginx status
sudo systemctl status nginx
```
Check Nginx logs:
```bash
# Check Nginx error logs
sudo tail -f /var/log/nginx/error.log
```
Restart Nginx:
```bash
# Restart Nginx
sudo systemctl restart nginx
```
### Re-insert Keys
If keys need to be re-inserted:
```bash
cd /home/mamostehp/pezkuwi-validator-v2.0.0/beta_testnet
source validators/validator1/config/keys.sh
# Insert each key type
```bash
# 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:9944
http://127.0.0.1:9951
# Repeat for other key types: gran, para, asgn, audi, beef
```
## Network Information
- **Network**: Pezkuwi Beta Testnet
### Beta Testnet
- **Chain Spec**: pezkuwichain-beta-testnet
- **Genesis**: Same across all validators
- **Bootnode**: Validator 1 (127.0.0.1:30333)
- **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
```bash
cd /home/mamostehp/pezkuwi-validator-v2.0.0/beta_testnet/shared/pezkuwi-sdk
cd ~/pezkuwi-sdk
git pull origin main
cargo build --release
# Restart all validators
for i in {1..8}; do sudo systemctl restart pezkuwi-validator-$i; done
sudo systemctl restart pezkuwi-validator-beta_testnet-8
```
### Update Frontend
```bash
cd /home/mamostehp/pezkuwi-validator-v2.0.0/beta_testnet/shared/dksweb
cd ~/DKSweb
git pull origin main
npm install
npm run build
@@ -319,30 +438,92 @@ sudo systemctl restart nginx
### Backup Validator Keys
```bash
# Backup all validator keys
tar -czf validator-keys-backup.tar.gz validators/validator*/config/keys.sh
# 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 safe location
cp validator-keys-backup.tar.gz /backup/location/
# Copy to secure location (offline storage recommended)
# NEVER commit keys to git or store unencrypted online
```
### Monitor Validator
```bash
# 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. **Never expose RPC ports to public internet** - Use firewall rules
2. **Backup validator keys securely** - Store encrypted backups offline
3. **Use different keys for production** - Never reuse testnet keys
4. **Keep system updated** - Regular security updates
5. **Monitor validator logs** - Watch for suspicious activity
6. **Restrict SSH access** - Use key-based authentication only
7. **Run validators as non-root** - Use dedicated user accounts
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
For issues or questions:
- Check logs first: `./scripts/logs.sh <validator_num>`
- Review this README
- Check validator status: `./scripts/status.sh`
- Consult Pezkuwi documentation
### Getting Help
1. **Check logs first:**
```bash
sudo journalctl -u pezkuwi-validator-beta_testnet-8 -n 200
```
2. **Review this README** - Most common issues are documented here
3. **Check validator status:**
```bash
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
@@ -350,6 +531,9 @@ This validator package is part of the Pezkuwi blockchain project.
---
**Last Updated**: 2025-11-05
**Package Version**: 2.0.0
**Network**: Beta Testnet (8 Validators)
**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