prvng_extensions/taskservs/infrastructure/polkadot/bootnode/README.md

# Polkadot Bootnode Task Service

## Overview

The Polkadot Bootnode task service provides a complete installation and configuration of a [Polkadot](https://polkadot.network/) bootnode server. Bootnodes are essential infrastructure components that help new nodes discover and connect to the Polkadot network. They provide initial peer discovery services and stable connection points for the peer-to-peer network.

## Features

### Core Capabilities
- **Network Discovery** - Helps nodes find peers and join Polkadot networks
- **Multi-Protocol Support** - P2P, WebSocket, and Secure WebSocket connections
- **Chain Support** - Polkadot, Kusama, Westend, and custom chains
- **High Availability** - Stable, long-running peer discovery service
- **Connection Management** - Optimized for handling many incoming connections

### Network Configuration
- **P2P Port (30310)** - Direct peer-to-peer connections
- **WebSocket Port (30311)** - WebSocket RPC endpoint
- **Secure WebSocket Port (30312)** - WSS with SSL/TLS encryption
- **Custom Port Configuration** - Configurable port assignments
- **Firewall Integration** - Automatic firewall rule configuration

### Security Features
- **SSL/TLS Support** - Full HTTPS/WSS encryption support
- **Certificate Management** - Let's Encrypt and custom certificates
- **Node Key Management** - Automatic ED25519 key generation
- **Access Control** - Connection limiting and rate limiting
- **Systemd Hardening** - Security-hardened service configuration

### Management Features
- **Systemd Integration** - Full service management and auto-start
- **Health Monitoring** - Built-in health check endpoints
- **Log Management** - Structured logging with configurable levels
- **Metric Reporting** - Prometheus metrics and telemetry support

## Configuration

### Basic Configuration
```kcl
bootnode: PolkadotBootnode = {
    name: "polkadot-bootnode"
    version: "1.5.0"
    run_user: {
        name: "polkadot"
        home: "/home/polkadot"
    }
    chain: "polkadot"
    ports: {
        p2p_port: 30310
        ws_port: 30311
        wss_port: 30312
    }
    max_peers: 200
}
```

### Production Configuration with SSL
```kcl
bootnode: PolkadotBootnode = {
    name: "polkadot-bootnode-prod"
    version: "1.5.0"
    run_user: {
        name: "polkadot"
        group: "polkadot"
        home: "/opt/polkadot"
    }
    chain: "polkadot"
    base_path: "/var/lib/polkadot"
    ports: {
        p2p_port: 30310
        ws_port: 30311
        wss_port: 30312
    }
    wss: {
        enabled: true
        domain: "bootnode.company.com"
        rate_limit: 100
    }
    ssl: {
        enabled: true
        cert_file: "/etc/ssl/certs/polkadot-bootnode.crt"
        key_file: "/etc/ssl/private/polkadot-bootnode.key"
        ca_file: "/etc/ssl/certs/ca.crt"
    }
    max_peers: 500
    telemetry_enabled: true
    telemetry_url: "wss://telemetry.polkadot.io/submit/ 0"
    log_level: "info"
}
```

### High-Availability Configuration
```kcl
bootnode: PolkadotBootnode = {
    name: "polkadot-bootnode-ha"
    # ... base configuration
    external_addresses: [
        "/ip4/203.0.113.1/tcp/30310",
        "/ip6/2001:db8::1/tcp/30310"
    ]
    reserved_nodes: [
        "/ip4/198.51.100.1/tcp/30310/p2p/12D3KooW...",
        "/ip4/198.51.100.2/tcp/30310/p2p/12D3KooW..."
    ]
    node_key_file: "/etc/polkadot/node.key"
    discovery_enabled: true
    max_peers: 1000
    prometheus_external: true
    prometheus_port: 9615
}
```

## Usage

### Deploy Bootnode
```bash
./core/nulib/provisioning taskserv create polkadot-bootnode --infra <infrastructure-name>
```

### List Available Task Services
```bash
./core/nulib/provisioning taskserv list
```

### SSH to Bootnode Server
```bash
./core/nulib/provisioning server ssh <bootnode-server>
```

### Service Management
```bash
# Check bootnode status
systemctl status polkadot-bootnode

# Start/stop bootnode
systemctl start polkadot-bootnode
systemctl stop polkadot-bootnode
systemctl restart polkadot-bootnode

# View bootnode logs
journalctl -u polkadot-bootnode -f

# Check node identity
sudo -u polkadot polkadot key inspect-node-key --file /var/lib/polkadot/node.key
```

### Get Bootnode Connection String
```bash
# Get node's peer ID
sudo -u polkadot polkadot key inspect-node-key --file /var/lib/polkadot/node.key

# Example bootnode string format:
# /ip4/YOUR_SERVER_IP/tcp/30310/p2p/12D3KooWYourPeerIDHere
```

### Health Monitoring
```bash
# Check node health
curl http://localhost:9933/health

# Check prometheus metrics
curl http://localhost:9615/metrics

# WebSocket connection test
wscat -c ws://localhost:30311
```

## Architecture

### Network Architecture
```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Polkadot     │────│  Bootnode Server │────│   Network       │
│   Nodes        │    │                  │    │   Discovery     │
│                │    │ • P2P (30310)    │    │                 │
│ • Full Nodes    │────│ • WS (30311)     │────│ • Peer List     │
│ • Validators    │    │ • WSS (30312)    │    │ • Chain Info    │
│ • Light Clients │    │ • SSL/TLS        │    │ • Sync Status   │
└─────────────────┘    └──────────────────┘    └─────────────────┘
```

### Port Configuration
- **P2P Port (30310)** - Main peer-to-peer networking
- **WebSocket Port (30311)** - RPC and subscription services
- **WSS Port (30312)** - Secure WebSocket with SSL/TLS
- **Prometheus Port (9615)** - Metrics and monitoring
- **Health Port (9933)** - Health check endpoint

### File Structure
```
/var/lib/polkadot/          # Main data directory
├── chains/                 # Chain-specific data
│   └── polkadot/          # Polkadot chain data
├── node.key               # Node identity key
└── network/               # Network state

/etc/polkadot/             # Configuration directory
├── polkadot.conf          # Main configuration
└── ssl/                   # SSL certificates

/home/polkadot/            # Service user home
├── .local/                # Local binaries
└── logs/                  # Application logs
```

## Supported Operating Systems

- Ubuntu 20.04+ / Debian 11+
- CentOS 8+ / RHEL 8+ / Fedora 35+

## System Requirements

### Minimum Requirements
- **RAM**: 4GB (8GB recommended)
- **Storage**: 50GB SSD (100GB+ for archive nodes)
- **CPU**: 2 cores (4 cores recommended)
- **Network**: Stable internet with good bandwidth
- **Ports**: 30310, 30311, 30312 open for inbound connections

### Production Requirements
- **RAM**: 16GB+ (for high-traffic bootnodes)
- **Storage**: 200GB+ NVMe SSD
- **CPU**: 4+ cores with high clock speed
- **Network**: Dedicated server with high bandwidth
- **Monitoring**: External monitoring and alerting

### Network Requirements
- **Inbound Connections** - Must accept connections on P2P port
- **Public IP** - Static public IP address recommended
- **Firewall** - Properly configured firewall rules
- **DNS** - Domain name for SSL/WSS (optional but recommended)

## Troubleshooting

### Service Issues
```bash
# Check bootnode status
systemctl status polkadot-bootnode

# View recent logs
journalctl -u polkadot-bootnode -n 100

# Check configuration
sudo -u polkadot polkadot --help

# Verify node key
sudo -u polkadot polkadot key inspect-node-key --file /var/lib/polkadot/node.key
```

### Network Connectivity
```bash
# Check if ports are listening
netstat -tlnp | grep -E ':(30310|30311|30312)'

# Test P2P connectivity
telnet your-server-ip 30310

# Test WebSocket connection
wscat -c ws://your-server-ip:30311

# Test SSL WebSocket (if configured)
wscat -c wss://bootnode.yourdomain.com:30312
```

### SSL/TLS Issues
```bash
# Check certificate validity
openssl x509 -in /etc/ssl/certs/polkadot-bootnode.crt -text -noout

# Test SSL configuration
openssl s_client -connect bootnode.yourdomain.com:30312

# Check Nginx configuration (if using proxy)
nginx -t
systemctl status nginx
```

### Performance Issues
```bash
# Check system resources
htop
df -h /var/lib/polkadot
iostat -x 1

# Monitor network connections
netstat -an | grep :30310 | wc -l

# Check Polkadot metrics
curl -s http://localhost:9615/metrics | grep polkadot_
```

### Peer Discovery Issues
```bash
# Check connected peers
curl -H "Content-Type: application/json" \
  -d '{"id":1, "jsonrpc":"2.0", "method": "system_peers", "params":[]}' \
  http://localhost:9933/

# Verify node is discoverable
# Use network scanning tools to verify external connectivity

# Check bootnodes configuration
sudo -u polkadot polkadot --chain polkadot --bootnodes
```

## Security Considerations

### Network Security
- **Firewall Configuration** - Properly configure iptables/ufw
- **DDoS Protection** - Implement rate limiting and connection limits
- **Port Security** - Only expose necessary ports
- **Network Monitoring** - Monitor for unusual traffic patterns

### Node Security
- **User Isolation** - Run bootnode as dedicated user
- **File Permissions** - Secure node.key and configuration files
- **System Updates** - Keep system and Polkadot binary updated
- **Access Control** - Limit SSH and admin access

### SSL/TLS Security
- **Certificate Management** - Use proper CA-signed certificates
- **Key Security** - Secure private key storage
- **Cipher Configuration** - Use strong TLS cipher suites
- **Certificate Renewal** - Implement automatic renewal

## Performance Optimization

### System Optimization
- **Storage Performance** - Use NVMe SSDs for chain data
- **Memory Configuration** - Allocate sufficient RAM for caching
- **CPU Optimization** - Use high-performance CPU with good single-thread performance
- **Network Tuning** - Optimize TCP settings for high connection counts

### Polkadot Configuration
- **Peer Limits** - Set appropriate max_peers for your hardware
- **Cache Settings** - Configure database and state caches
- **Pruning** - Use state pruning to manage disk usage
- **Telemetry** - Enable telemetry for network health monitoring

### Connection Management
- **Rate Limiting** - Implement connection rate limiting
- **Load Balancing** - Use multiple bootnodes behind load balancer
- **Geographic Distribution** - Deploy bootnodes in multiple regions
- **Monitoring** - Implement comprehensive monitoring and alerting

## Integration Examples

### Polkadot Node Configuration
```toml
# In other nodes' configuration
[network]
bootnodes = [
    "/ip4/203.0.113.1/tcp/30310/p2p/12D3KooWYourBootnodePeerID",
    "/dns/bootnode.company.com/tcp/30310/p2p/12D3KooWYourBootnodePeerID"
]
```

### Kubernetes Deployment
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: polkadot-bootnode
spec:
  replicas: 3
  selector:
    matchLabels:
      app: polkadot-bootnode
  template:
    metadata:
      labels:
        app: polkadot-bootnode
    spec:
      containers:
      - name: polkadot
        image: parity/polkadot:latest
        ports:
        - containerPort: 30310
        - containerPort: 30311
        - containerPort: 30312
        env:
        - name: RUST_LOG
          value: "info"
```

### Monitoring Integration
```yaml
# Prometheus configuration
- job_name: 'polkadot-bootnode'
  static_configs:
  - targets: ['bootnode.company.com:9615']
  metrics_path: '/metrics'
  scrape_interval: 30s
```

### Load Balancer Configuration
```nginx
upstream polkadot_bootnodes {
    server bootnode1.company.com:30310;
    server bootnode2.company.com:30310;
    server bootnode3.company.com:30310;
}

server {
    listen 30310;
    proxy_pass polkadot_bootnodes;
    proxy_timeout 30s;
}
```

## Backup and Recovery

### Backup Procedure
```bash
# Stop bootnode service
systemctl stop polkadot-bootnode

# Backup node key (critical!)
cp /var/lib/polkadot/node.key /backup/node-key-$(date +%Y%m%d).key

# Backup configuration
tar -czf /backup/polkadot-config-$(date +%Y%m%d).tar.gz \
    /etc/polkadot/ \
    /var/lib/polkadot/node.key

# Restart service
systemctl start polkadot-bootnode
```

### Recovery Procedure
1. **Stop bootnode service**
2. **Restore node key** to maintain same peer ID
3. **Restore configuration** files
4. **Verify file permissions** and ownership
5. **Start bootnode service**
6. **Verify network connectivity**

### Disaster Recovery
- **Geographic Redundancy** - Deploy bootnodes in multiple regions
- **Automated Failover** - Use DNS-based failover mechanisms
- **Backup Bootnodes** - Maintain standby bootnode instances
- **Monitoring** - Implement external monitoring for quick detection

## Resources

- **Official Documentation**: [wiki.polkadot.network](https://wiki.polkadot.network)
- **GitHub Repository**: [paritytech/polkadot](https://github.com/paritytech/polkadot)
- **Telemetry**: [telemetry.polkadot.io](https://telemetry.polkadot.io)
- **Community**: [polkadot.network/community](https://polkadot.network/community)