# Network Topology

KayakNet uses a decentralized peer-to-peer topology with no central servers.

## Network Structure

```
                    ┌──────────┐
                    │Bootstrap │
                    │  Node    │
                    └────┬─────┘
                         │
         ┌───────────────┼───────────────┐
         │               │               │
    ┌────▼────┐     ┌────▼────┐     ┌────▼────┐
    │  Node A │◄───►│  Node B │◄───►│  Node C │
    └────┬────┘     └────┬────┘     └────┬────┘
         │               │               │
         │    ┌──────────┘               │
         │    │                          │
    ┌────▼────▼──┐              ┌────────▼───┐
    │   Node D   │◄────────────►│   Node E   │
    └────────────┘              └────────────┘
```

## Node Types

### Bootstrap Nodes

* Well-known entry points
* Help new nodes join
* Provide initial peer lists
* Always available

### Regular Nodes

* Run by users
* Equal participants
* Route traffic for others
* Come and go freely

### Relay Nodes (Optional)

* High-bandwidth volunteers
* Prioritized for routing
* No special privileges

## Peer Discovery

### Initial Connection

1. New node contacts bootstrap
2. Solves Proof-of-Work challenge
3. Receives initial peer list
4. Connects to peers

### DHT-Based Discovery

Once connected:

1. Node joins Kademlia DHT
2. Announces its presence
3. Discovers peers via DHT queries
4. Maintains routing table

### Peer Selection

Criteria for selecting peers:

* **Diversity** - Different subnets/geographies
* **Reliability** - Low latency, high uptime
* **Capacity** - Bandwidth availability
* **Reputation** - Peer score

## Connection Management

### Maintaining Connections

```
┌─────────────┐
│   Target:   │
│  10-50 peers│
└──────┬──────┘
       │
       ▼
┌─────────────────────────────────┐
│ If peers < min:                 │
│   - Query DHT for more          │
│   - Try cached addresses        │
│ If peers > max:                 │
│   - Disconnect lowest scored    │
└─────────────────────────────────┘
```

### Connection Limits

| Parameter       | Default | Description            |
| --------------- | ------- | ---------------------- |
| Min Peers       | 5       | Minimum connections    |
| Max Peers       | 50      | Maximum connections    |
| Bootstrap Peers | 3       | Reserved for bootstrap |

### Peer Scoring

Peers are scored based on:

* **Latency** - Lower is better
* **Uptime** - Longer is better
* **Behavior** - No spam, valid messages
* **Throughput** - Bandwidth provided

## Network Resilience

### Node Failures

When a peer disconnects:

1. Mark as offline
2. Try reconnection (3 attempts)
3. Remove from active list
4. Keep in cache for later
5. Find replacement peer

### Partition Healing

If network splits:

1. Both partitions continue independently
2. Bootstrap nodes bridge partitions
3. DHT eventually merges
4. Data reconciles

### Attack Resistance

| Attack    | Mitigation        |
| --------- | ----------------- |
| Sybil     | PoW, peer scoring |
| Eclipse   | Diverse selection |
| DDoS      | Rate limiting     |
| Partition | Bootstrap bridges |

## Data Propagation

### Message Routing

Messages propagate via:

1. **Direct** - To connected peers
2. **Gossip** - Random peer selection
3. **DHT** - Store and forward
4. **PubSub** - Topic subscription

### Latency

Typical message latency:

* Direct peer: 50-100ms
* 2-hop: 100-200ms
* 3-hop (onion): 150-300ms
* DHT lookup: 200-500ms

## Geographic Distribution

Nodes are globally distributed:

* No geographic restrictions
* Automatic peer diversity
* Regional clustering avoided

```
Americas        Europe          Asia-Pacific
   ●              ●●               ●
  ●●●            ●●●●             ●●●
   ●●             ●●               ●●
```

## Bootstrap Infrastructure

### Current Bootstrap Nodes

| Address             | Location | Status |
| ------------------- | -------- | ------ |
| 203.161.33.237:4242 | Primary  | Active |

### Running Your Own Bootstrap

```bash
./kayakd \
  --listen 0.0.0.0:4242 \
  --public-api \
  --name my-bootstrap \
  --data-dir /var/lib/kayaknet
```

Contact us to be added to default list.

## Monitoring

### Network Health

Check your node's connectivity:

```bash
curl http://127.0.0.1:8080/api/network/peers
```

Key metrics:

* Peer count (should be 5-50)
* Latency (should be <500ms)
* Message throughput

### Debug Logging

```bash
./kayakd --log-level debug
```