Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

IBD Bandwidth Protection

Overview

The node implements comprehensive protection against Initial Block Download (IBD) bandwidth exhaustion attacks. This prevents malicious peers from forcing a node to upload the entire blockchain multiple times, which could cause ISP data cap overages and economic denial-of-service.

Protection Mechanisms

Per-Peer Bandwidth Limits

Tracks bandwidth usage per peer with configurable daily and hourly limits:

  • Daily Limit: Maximum bytes a peer can request per day
  • Hourly Limit: Maximum bytes a peer can request per hour
  • Automatic Throttling: Blocks requests when limits are exceeded
  • Legitimate Node Protection: First request always allowed, reasonable limits for legitimate sync

Code: ibd_protection.rs

Per-IP Bandwidth Limits

Tracks bandwidth usage per IP address to prevent single-IP attacks:

  • IP-Based Tracking: Monitors all peers from the same IP
  • Aggregate Limits: Combined daily/hourly limits for all peers from an IP
  • Attack Detection: Identifies coordinated attacks from single IP

Code: ibd_protection.rs

Per-Subnet Bandwidth Limits

Tracks bandwidth usage per subnet to prevent distributed attacks:

  • IPv4 Subnets: Tracks /24 subnets (256 addresses)
  • IPv6 Subnets: Tracks /64 subnets
  • Subnet Aggregation: Combines bandwidth from all IPs in subnet
  • Distributed Attack Mitigation: Prevents coordinated attacks from subnet

Code: ibd_protection.rs

Concurrent IBD Serving Limits

Limits how many peers can simultaneously request IBD:

  • Concurrent Limit: Maximum number of peers serving IBD at once
  • Queue Management: Queues additional requests when limit reached
  • Fair Serving: Rotates serving to queued peers

Code: ibd_protection.rs

Peer Reputation Scoring

Tracks peer behavior to identify malicious patterns:

  • Reputation System: Scores peers based on behavior
  • Suspicious Pattern Detection: Identifies rapid reconnection with new peer IDs
  • Cooldown Periods: Enforces cooldown after suspicious activity
  • Legitimate Node Protection: First-time sync always allowed

Code: ibd_protection.rs

Configuration

Default Limits

[network.ibd_protection]
max_bandwidth_per_peer_per_day_gb = 50.0
max_bandwidth_per_peer_per_hour_gb = 10.0
max_bandwidth_per_ip_per_day_gb = 100.0
max_bandwidth_per_ip_per_hour_gb = 20.0
max_bandwidth_per_subnet_per_day_gb = 500.0
max_bandwidth_per_subnet_per_hour_gb = 100.0
max_concurrent_ibd_serving = 3
ibd_request_cooldown_seconds = 3600
suspicious_reconnection_threshold = 3
reputation_ban_threshold = -100
enable_emergency_throttle = false
emergency_throttle_percent = 50

Configuration Options

  • max_bandwidth_per_peer_per_day_gb: Daily limit per peer (default: 50 GB)
  • max_bandwidth_per_peer_per_hour_gb: Hourly limit per peer (default: 10 GB)
  • max_bandwidth_per_ip_per_day_gb: Daily limit per IP (default: 100 GB)
  • max_bandwidth_per_ip_per_hour_gb: Hourly limit per IP (default: 20 GB)
  • max_bandwidth_per_subnet_per_day_gb: Daily limit per subnet (default: 500 GB)
  • max_bandwidth_per_subnet_per_hour_gb: Hourly limit per subnet (default: 100 GB)
  • max_concurrent_ibd_serving: Maximum concurrent IBD serving (default: 3)
  • ibd_request_cooldown_seconds: Cooldown period after suspicious activity (default: 3600 seconds)
  • suspicious_reconnection_threshold: Number of reconnections in 1 hour to be considered suspicious (default: 3)
  • reputation_ban_threshold: Reputation score below which peer is banned (default: -100)
  • enable_emergency_throttle: Enable emergency bandwidth throttling (default: false)
  • emergency_throttle_percent: Percentage of bandwidth to throttle when emergency throttle is enabled (default: 50)

Code: ibd_protection.rs

Attack Mitigation

Single IP Attack

Attack: Attacker runs multiple fake nodes from same IP Protection: Per-IP bandwidth limits aggregate all peers from IP Result: Blocked after IP limit reached

Subnet Attack

Attack: Attacker distributes fake nodes across subnet Protection: Per-subnet bandwidth limits aggregate all IPs in subnet Result: Blocked after subnet limit reached

Rapid Reconnection Attack

Attack: Attacker disconnects and reconnects with new peer ID Protection: Reputation scoring detects pattern, enforces cooldown Result: Blocked during cooldown period

Distributed Attack

Attack: Coordinated attack from multiple IPs/subnets Protection: Concurrent serving limits prevent serving too many peers simultaneously Result: Additional requests queued, serving rotated fairly

Legitimate New Node

Scenario: Legitimate new node requests full sync Protection: First request always allowed, reasonable limits accommodate legitimate sync Result: Allowed to sync within limits

Integration

The IBD protection is automatically integrated into the network manager:

  • Automatic Tracking: Tracks bandwidth when serving Headers/Block messages
  • Request Protection: Protects GetHeaders and GetData requests
  • Cleanup: Automatically cleans up tracking on peer disconnect

Code: mod.rs

LAN Peer Prioritization

LAN peers are automatically discovered and prioritized for IBD, but still respect bandwidth protection limits:

  • Priority Assignment: LAN peers get priority within bandwidth limits
  • Score Multiplier: LAN peers receive up to 3x score multiplier (progressive trust system)
  • Bandwidth Limits: LAN peers still respect per-peer, per-IP, and per-subnet limits
  • Reputation Scoring: LAN peer behavior affects reputation scoring

Code: parallel_ibd.rs

For details on LAN peering discovery, security, and configuration, see LAN Peering System.

See Also