snxraven/p2ns
2
1
Fork 1
Code Issues Pull Requests Packages Projects Releases Wiki Activity

reorg

Browse Source
This commit is contained in:
Raven Scott
2025-12-17 20:05:50 -05:00
commit 742e27d3f7
276 changed files with 89838 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/NETWORK_TOPOLOGY.md
+427
View File
@@ -0,0 +1,427 @@
# 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
### 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