# P2NS Network Topology

This document illustrates what a large-scale P2NS network looks like with many peers, domains, and services.

## Network Overview

A mature P2NS network consists of interconnected peers, each potentially claiming domains, voting on claims, and subscribing to services from other peers.

```mermaid
graph TB
    subgraph Internet[Internet / Hyperswarm DHT]
        DHT[Distributed Hash Table]
    end
    
    subgraph Region1[Region: North America]
        P1[Peer: alice]
        P2[Peer: bob]
        P3[Peer: charlie]
    end
    
    subgraph Region2[Region: Europe]
        P4[Peer: diana]
        P5[Peer: erik]
        P6[Peer: fiona]
    end
    
    subgraph Region3[Region: Asia]
        P7[Peer: george]
        P8[Peer: hana]
    end
    
    P1 <--> DHT
    P2 <--> DHT
    P3 <--> DHT
    P4 <--> DHT
    P5 <--> DHT
    P6 <--> DHT
    P7 <--> DHT
    P8 <--> DHT
    
    P1 <-.-> P2
    P2 <-.-> P3
    P4 <-.-> P5
    P5 <-.-> P6
    P7 <-.-> P8
    P1 <-.-> P4
    P3 <-.-> P7
```

## Example Large Network

### Network Statistics

| Metric | Value |
|--------|-------|
| Total Peers | 50 |
| Active Peers | 42 |
| Total Domains Claimed | 150 |
| Unique Domains | 120 |
| Contested Domains | 30 |
| Total Services | 200+ |
| Average Votes per Domain | 8 |

### Domain Distribution

```mermaid
pie title Domain Ownership Distribution
    "Single Owner" : 90
    "2 Claimants" : 20
    "3+ Claimants" : 10
```

## Peer Roles

In a large network, peers naturally take on different roles:

### Domain Owners
Peers that claim and host domains:

```
Peer: alice (pk: a1b2c3...)
├── Claims:
│   ├── my-blog.p2p (hs://abc123...)
│   ├── photo-gallery.p2p (hs://def456...)
│   └── api.my-blog.p2p (hs://ghi789...)
├── Services Published:
│   ├── my-blog.p2p:web (port 443)
│   ├── my-blog.p2p:api (port 8080)
│   └── photo-gallery.p2p:web (port 443)
└── Votes Cast: 45 domains
```

### Service Consumers
Peers that primarily subscribe to others' services:

```
Peer: bob (pk: d4e5f6...)
├── Claims: (none)
├── Subscriptions:
│   ├── alice/my-blog.p2p:web -> localhost:8001
│   ├── diana/shop.p2p:web -> localhost:8002
│   └── erik/chat.p2p:* (subscribe-all)
└── Votes Cast: 30 domains
```

### Infrastructure Nodes
High-availability peers that help maintain network health:

```
Peer: infra-node-1 (pk: x7y8z9...)
├── Claims:
│   └── status.network.p2p
├── Uptime: 99.9%
├── Connected Peers: 48/50
├── Votes Cast: 120 domains (all known)
└── Role: Helps reach quorum for contested domains
```

## Domain Lifecycle

### New Domain Claim

```mermaid
sequenceDiagram
    participant Alice as alice
    participant Network as P2NS Network
    participant Bob as bob
    participant Charlie as charlie
    
    Alice->>Network: Claim "shop.p2p" (hs://abc...)
    Network->>Bob: Replicate claim
    Network->>Charlie: Replicate claim
    
    Note over Network: Auto-vote triggered
    
    Bob->>Network: Vote for alice/shop.p2p
    Charlie->>Network: Vote for alice/shop.p2p
    
    Note over Network: Quorum reached (3 votes)
    
    Network->>Alice: Consensus: resolved
    Network->>Bob: Consensus: resolved
    Network->>Charlie: Consensus: resolved
```

### Contested Domain

```mermaid
sequenceDiagram
    participant Alice as alice
    participant Network as P2NS Network
    participant Bob as bob
    participant Diana as diana
    
    Note over Network: "popular.p2p" claimed by alice
    
    Diana->>Network: Claim "popular.p2p" (hs://xyz...)
    
    Note over Network: Now 2 claimants
    
    Network->>Bob: Which claim to support?
    Bob->>Network: Vote for alice (older claim)
    
    Note over Network: Vote count: alice=25, diana=5
    Note over Network: Quorum: 15 (30 peers * 0.5)
    
    Network->>Diana: Consensus: alice wins
    Diana->>Diana: Remove claim or keep trying
```

## Service Mesh

Large networks often develop service meshes where domains expose multiple services:

```
┌─────────────────────────────────────────────────────────────┐
│                     shop.example.p2p                         │
├─────────────────────────────────────────────────────────────┤
│  Services:                                                   │
│  ├── web      (hs://aaa...) port 443  - Main website        │
│  ├── api      (hs://bbb...) port 8080 - REST API            │
│  ├── graphql  (hs://ccc...) port 4000 - GraphQL endpoint    │
│  ├── ws       (hs://ddd...) port 3000 - WebSocket server    │
│  └── metrics  (hs://eee...) port 9090 - Prometheus metrics  │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                     chat.example.p2p                         │
├─────────────────────────────────────────────────────────────┤
│  Services:                                                   │
│  ├── web      (hs://fff...) port 443  - Web client          │
│  ├── api      (hs://ggg...) port 8080 - REST API            │
│  └── rtc      (hs://hhh...) port 5000 - WebRTC signaling    │
└─────────────────────────────────────────────────────────────┘
```

### Subscriber View

A peer subscribing to multiple services:

```
Local Port Mappings (bob's machine):
┌──────────────────────────────────────────────────────────┐
│ Local Port │ Remote Service              │ Status        │
├──────────────────────────────────────────────────────────┤
│ 8001       │ shop.example.p2p:web        │ Connected     │
│ 8002       │ shop.example.p2p:api        │ Connected     │
│ 8003       │ chat.example.p2p:web        │ Connected     │
│ 8004       │ chat.example.p2p:api        │ Connecting... │
│ 8005       │ blog.alice.p2p:web          │ Connected     │
│ 8006       │ status.network.p2p:metrics  │ Connected     │
└──────────────────────────────────────────────────────────┘
```

## Consensus at Scale

Each peer maintains a local consensus Autobase sidecar replicated over Hyperswarm connections (`replicateConsensus`). The apply view converges as claim/vote events arrive in linearized order; reads do not scan the full Autopass ledger.

### Quorum Dynamics

With 50 peers and default settings:

```
CONSENSUS_QUORUM_THRESHOLD = 0.5
CONSENSUS_MIN_VOTES = 2

Quorum requirement = max(2, ceil(50 * 0.5)) = 25 votes
```

### Vote Distribution Example

```
Domain: popular-service.p2p

Claimants:
├── alice (pk: a1b2...) - 28 votes ✓ WINNER
├── bob (pk: d4e5...)   - 15 votes
└── charlie (pk: g7h8...) - 7 votes

Total votes: 50
Quorum: 25 ✓ Met
Status: resolved -> alice
```

### Network Partition Scenario

```mermaid
graph TB
    subgraph Partition1[Partition A - 30 peers]
        PA1[alice]
        PA2[bob]
        PA3[...]
        PA4[30 peers total]
    end
    
    subgraph Partition2[Partition B - 20 peers]
        PB1[charlie]
        PB2[diana]
        PB3[...]
        PB4[20 peers total]
    end
    
    PA1 -.X.- PB1
    
    Note1[Partition A: Quorum = 15, can resolve]
    Note2[Partition B: Quorum = 10, can resolve]
```

During partition:
- Each partition calculates quorum based on visible peers
- Resolutions may differ between partitions
- On reconnection, claims/votes merge and re-resolve

## Plugin Distribution

Large networks often have popular plugins replicated across peers:

```
Plugin: global.profile
├── Installed on: 45/50 peers (90%)
├── HyperDB replication: Active
└── Profiles synced: 2,500+

Plugin: peer.directory  
├── Installed on: 50/50 peers (100%)
├── Domains indexed: 150
└── Search queries/day: 500+

Plugin: domain.consensus
├── Installed on: 35/50 peers (70%)
├── Visualizations: Real-time
└── Vote tracking: All domains
```

## Scaling Considerations

### Subnet Allocation

Large deployments need multiple subnets:

```env
SUBNETS=[
  {"base":"192.168.1.0","cidr":24,"startIndex":2,"name":"Primary"},
  {"base":"192.168.2.0","cidr":24,"startIndex":2,"name":"Secondary"},
  {"base":"192.168.3.0","cidr":24,"startIndex":2,"name":"Tertiary"},
  {"base":"10.0.0.0","cidr":16,"startIndex":2,"name":"Extended"}
]
```

Capacity:
- 3 x /24 subnets = 759 domains
- 1 x /16 subnet = 65,534 domains
- Total: 66,293 possible domains per peer

### Performance Tuning

For large networks:

```env
# Increase DNS pool for more concurrent queries
DNS_POOL_SIZE=10

# Adjust consensus for larger peer counts
CONSENSUS_QUORUM_THRESHOLD=0.3
CONSENSUS_MIN_VOTES=5

# Increase cache TTLs to reduce load
# (configured in code, not env vars)
```

### Resource Usage

Estimated resources for a peer in a 50-peer network:

| Resource | Typical Usage |
|----------|---------------|
| Memory | 200-500 MB |
| CPU | 1-5% idle, 20% during sync |
| Disk | 100 MB - 1 GB (depending on plugins) |
| Bandwidth | 10-50 KB/s average |
| Open connections | 50-100 |

## Network Health Monitoring

### Key Metrics to Watch

```
Dashboard: P2NS Network Health
┌────────────────────────────────────────────────────────┐
│ Connected Peers: 48/50          Uptime: 99.2%         │
├────────────────────────────────────────────────────────┤
│ Consensus Health:                                      │
│ ├── Resolved domains: 115/120 (95.8%)                 │
│ ├── Quorum failures: 3                                │
│ ├── Active ties: 2                                    │
│ └── Validation failures: 0                            │
├────────────────────────────────────────────────────────┤
│ Holesail Connections:                                  │
│ ├── Servers running: 5                                │
│ ├── Clients connected: 12                             │
│ └── Failed connections: 1                             │
├────────────────────────────────────────────────────────┤
│ DNS Queries (last hour):                               │
│ ├── Total: 1,250                                      │
│ ├── P2P resolved: 800 (64%)                           │
│ ├── Public fallback: 400 (32%)                        │
│ └── Local DNS: 50 (4%)                                │
└────────────────────────────────────────────────────────┘
```

### Alerting Thresholds

| Condition | Warning | Critical |
|-----------|---------|----------|
| Connected peers | < 80% | < 50% |
| Quorum failures | > 5% | > 20% |
| Holesail failures | > 10% | > 30% |
| DNS resolution time | > 500ms | > 2000ms |

## Growth Patterns

### Organic Growth

```
Month 1:  5 peers,  10 domains,   20 services
Month 3: 15 peers,  40 domains,   80 services
Month 6: 30 peers, 100 domains,  200 services
Year 1:  50 peers, 200 domains,  500 services
Year 2: 100 peers, 500 domains, 1500 services
```

### Trust Networks

As networks grow, trust patterns emerge:

```mermaid
graph LR
    subgraph TrustedCore[Trusted Core - High Vote Weight]
        T1[infra-1]
        T2[infra-2]
        T3[alice]
        T4[bob]
    end
    
    subgraph ActiveUsers[Active Users]
        A1[charlie]
        A2[diana]
        A3[erik]
    end
    
    subgraph NewPeers[New Peers]
        N1[new-1]
        N2[new-2]
    end
    
    T1 --> A1
    T2 --> A2
    T3 --> A3
    A1 --> N1
    A2 --> N2
```

## Related Documentation

- [CONSENSUS.md](CONSENSUS.md) - Consensus mechanism details
- [GLOSSARY.md](GLOSSARY.md) - Terms and concepts
- [ARCHITECTURE.md](ARCHITECTURE.md) - System internals
- [README.md](../README.md) - Getting started