prvng_extensions/taskservs/infrastructure/polkadot/bootnode

Polkadot Bootnode Task Service

Overview

The Polkadot Bootnode task service provides a complete installation and configuration of a Polkadot 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

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

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

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

./core/nulib/provisioning taskserv create polkadot-bootnode --infra <infrastructure-name>

List Available Task Services

./core/nulib/provisioning taskserv list

SSH to Bootnode Server

./core/nulib/provisioning server ssh <bootnode-server>

Service Management

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

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

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

Load Balancer Configuration

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

# 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
• GitHub Repository: paritytech/polkadot
• Telemetry: telemetry.polkadot.io
• Community: polkadot.network/community