# 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
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kayaknet.io/architecture/topology.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.