p2ns/docs/THE_THEORY.md

# THE THEORY: A Whitepaper on Peer-to-Peer Name Resolution

**P2NS: Reclaiming the Internet's Naming Layer**

---

## Abstract

P2NS (Peer-to-Peer Name System) represents a fundamental reimagining of how domain names are resolved, owned, and served on the internet. By replacing centralized DNS infrastructure with a distributed consensus mechanism built on cryptographic identities and peer-to-peer networking, P2NS eliminates single points of failure, removes gatekeepers from domain ownership, and enables truly decentralized web hosting. This whitepaper presents the theoretical foundations, architectural decisions, and philosophical principles underlying P2NS—a system where domains are claimed through cryptographic proof, resolved through peer consensus, and served through NAT-traversing encrypted tunnels, all without requiring any central authority.

---

## 1. The Problem: Centralization in the Naming Layer

The Domain Name System (DNS) is often called the "phone book of the internet." What is less often acknowledged is that this phone book is controlled by a hierarchical structure of authorities—ICANN at the apex, registrars beneath, and ultimately governments with the power to seize domains or compel censorship.

### 1.1 Single Points of Failure and Control

Traditional DNS suffers from several critical weaknesses:

- **Centralized registries**: Top-level domains are controlled by designated authorities who can revoke, transfer, or censor domain names
- **Registrar dependence**: Domain "ownership" is actually a lease agreement subject to terms of service, payment requirements, and legal jurisdiction
- **Root server vulnerability**: The 13 root server clusters, while distributed, represent chokepoints that can be targeted or manipulated
- **Censorship capability**: Governments routinely order DNS-level blocking, making entire websites invisible to users within their jurisdiction

### 1.2 The NAT Problem

Beyond naming, the modern internet suffers from a connectivity crisis. Network Address Translation (NAT), originally a workaround for IPv4 address exhaustion, has become a barrier to peer-to-peer communication. Most internet users sit behind NAT devices that prevent incoming connections, forcing all communication through centralized servers that can see, log, and control traffic.

### 1.3 The Hosting Problem

Even with a domain name, serving content requires:
- Renting server infrastructure from cloud providers
- Trusting those providers not to terminate service
- Paying ongoing fees to maintain availability
- Accepting that your content lives on someone else's computer

P2NS addresses all of these problems through a unified architecture that replaces centralized naming, hosting, and connectivity with cryptographic proofs and peer consensus.

---

## 2. Theoretical Foundations

P2NS is built on several foundational technologies and concepts that, when combined, enable fully decentralized naming and hosting.

### 2.1 Cryptographic Identity

At the core of P2NS is the principle that **identity is a keypair**. Every participant in the network possesses an Ed25519 keypair:

- The **public key** serves as a persistent, globally unique identifier
- The **private key** proves ownership and authorizes actions
- No registration, no permission, no authority required to create an identity

This cryptographic identity is deterministic and portable. A peer's identity remains constant across sessions, enabling reputation, trust, and accountability without centralized identity providers.

### 2.2 Distributed Hash Tables

P2NS uses Hyperswarm's distributed hash table (DHT) for peer discovery. The DHT enables:

- **Topic-based discovery**: Peers interested in the same topic (derived from a shared seed) can find each other
- **NAT traversal**: The DHT facilitates hole-punching to establish direct connections through NAT devices
- **No central coordination**: Peer discovery happens through the DHT's gossip protocol without any central server

### 2.3 Append-Only Data Structures

The system leverages Hypercore, an append-only log structure that provides:

- **Immutable history**: Once written, data cannot be modified without detection
- **Cryptographic verification**: Each entry is signed and linked to previous entries
- **Efficient replication**: Only new entries need to be synchronized between peers

### 2.4 Consensus Without Coordination

Traditional consensus mechanisms (Paxos, Raft, PBFT) require coordinated rounds of communication. P2NS implements **eventual consensus** through a claim-vote-resolve model that converges without explicit coordination:

- Peers independently observe claims and cast votes
- The network state converges as peers replicate data
- Resolution happens locally based on observed votes, not through coordinated agreement

---

## 3. The P2NS Architecture

P2NS operates as a three-layer system, each layer building on the one below.

### 3.1 Network Layer: Hyperswarm and Holesail

The network layer handles peer discovery and connectivity:

```
┌─────────────────────────────────────────────────────────────┐
│                     APPLICATION LAYER                        │
│            (Plugins, Websites, Databases, Files)            │
├─────────────────────────────────────────────────────────────┤
│                     RESOLUTION LAYER                         │
│         (Claims, Votes, Consensus, Domain → Hash)           │
├─────────────────────────────────────────────────────────────┤
│                      NETWORK LAYER                           │
│        (Hyperswarm DHT, Holesail Tunnels, Encryption)       │
└─────────────────────────────────────────────────────────────┘
```

**Hyperswarm** provides the DHT for peer discovery. All P2NS nodes join a common topic (derived from a configurable seed), enabling them to find each other regardless of network topology.

**Holesail** builds encrypted tunnels on top of Hyperswarm connections. When a domain resolves to a hash, Holesail creates a tunnel to the peer serving that hash, punching through NATs as needed.

### 3.2 Resolution Layer: Autopass and Consensus

The resolution layer maintains the distributed mapping of domain names to content hashes:

**Autopass** is a distributed key-value store built on Hypercore. It stores:
- **Claims**: `claim:domain:claimant` → `{hash, timestamp, ssl, clients}`
- **Votes**: `vote:domain:claimant:voter` → `hash`

The resolution process:
1. A peer queries for domain "example.p2p"
2. The system retrieves all claims for that domain
3. Votes are tallied for each claimant
4. The claimant meeting quorum with the most votes wins
5. The winning claim's hash is returned for tunnel establishment

### 3.3 Application Layer: Plugins and Services

The application layer enables rich functionality through plugins:

- **Internal domains**: Plugins register domains (e.g., "peer.directory") that resolve to localhost
- **HyperDB**: Distributed databases with automatic P2P replication
- **Hyperdrive**: Distributed file systems for content hosting
- **Plugin RPC (protomux-rpc)**: Named JSON methods for real-time peer communication between plugins

---

## 4. The Consensus Mechanism

P2NS implements a novel consensus mechanism optimized for domain name resolution. Unlike blockchain consensus (which orders all transactions globally), P2NS only needs to agree on the current owner of each domain.

### 4.1 The Claim-Vote-Resolve Model

**Claims** are assertions of domain ownership:
```
claim:mydomain:abc123def... → {
  hash: "holesail-connection-hash",
  timestamp: 1702800000000,
  ssl: true,
  clients: ["peer1", "peer2"]
}
```

The claimant (identified by public key) asserts they control the domain and provides a hash for connecting to their service.

**Votes** are endorsements of claims:
```
vote:mydomain:abc123def...:voter456... → "holesail-connection-hash"
```

Peers vote for the claim they believe is legitimate. By default, peers:
1. Vote for their own claims (self-vote)
2. Vote for single claimants (no competition)
3. Use tie-breaker rules when multiple claims exist

**Resolution** runs against the consensus Autobase sidecar apply view (not a per-query KV scan). The pure resolver applies the same rules locally:

```
minVotes = max(MIN_VOTES, ceil(activePeers × QUORUM_THRESHOLD))

if (totalVotes >= minVotes) {
  winner = claimant with most votes
  // If tie, apply tie-breaker
}
```

Claim and vote KV writes in Autopass dual-append typed events to the sidecar; the apply handler maintains per-domain state in linearized order. See [RFC 0001](rfcs/0001-autobase-consensus.md).

### 4.2 Quorum Mathematics

The quorum threshold (default 50%) ensures that resolution requires meaningful network participation:

- With 10 active peers and 50% threshold: 5 votes needed
- With 100 active peers: 50 votes needed
- Minimum votes (default 2) prevents single-peer takeover in small networks

This creates a balance: small networks can function with few participants, while large networks require broader consensus.

### 4.3 Tie-Breaking Strategies

When multiple claimants receive equal votes, P2NS applies deterministic tie-breakers:

1. **Timestamp** (default): Oldest claim wins (first-come-first-served)
2. **Claimant age**: Prefer claimants with longer network history
3. **Lexicographic**: Deterministic ordering by public key

These strategies ensure that resolution is deterministic—all peers observing the same data will reach the same conclusion.

### 4.4 Byzantine Fault Tolerance Properties

P2NS tolerates certain Byzantine behaviors:

- **Conflicting claims**: Resolved through voting, not prevented
- **Vote manipulation**: Mitigated by requiring quorum from diverse peers
- **Network partitions**: Each partition resolves independently; convergence occurs on reconnection

The system does not prevent Sybil attacks (one entity creating many identities), but the cost of maintaining many active peers limits practical attacks.

---

## 5. NAT Traversal and Connectivity

P2NS solves the NAT problem through Hyperswarm's hole-punching and Holesail's tunnel abstraction.

### 5.1 Hole Punching Theory

NAT devices track outgoing connections and allow responses. Hole punching exploits this:

1. Both peers connect to the DHT (outgoing connections, allowed by NAT)
2. The DHT coordinates timing for simultaneous connection attempts
3. Both peers send packets to each other's public IP:port
4. NAT devices see these as responses to "outgoing" connections
5. A direct connection is established

This works for most NAT types (full cone, restricted cone, port-restricted cone) but may fail for symmetric NATs, where relay fallback is used.

### 5.2 Encrypted Tunnel Establishment

Once hole-punched, Holesail establishes an encrypted tunnel:

1. Domain resolves to a 64-character hex hash (the Holesail key)
2. Client creates a Holesail connection to that key
3. Holesail handles encryption, multiplexing, and reconnection
4. Traffic flows through the tunnel as if it were a local connection

### 5.3 Virtual Interface Abstraction

To make P2P domains accessible to standard browsers, P2NS creates virtual network interfaces:

1. When a domain is first accessed, a virtual IP is assigned (e.g., 192.168.3.42)
2. The IP is bound to a loopback interface alias
3. A TLS proxy listens on that IP, presenting a valid certificate
4. DNS queries for the domain return the virtual IP
5. Browser connects to the virtual IP; proxy tunnels to the P2P peer

This abstraction allows any application expecting HTTP/HTTPS to transparently access P2P content.

---

## 6. The Plugin Ecosystem

P2NS is not just a naming system—it's a platform for decentralized applications.

### 6.1 Plugin Architecture

Plugins are self-contained applications that:
- Register internal domains (resolved to 127.0.0.1)
- Serve web interfaces through the internal HTTP server
- Access the P2NS SDK for network, DNS, and storage operations

The plugin lifecycle:
1. Plugin directory scanned at startup
2. `config.json` defines domain, routes, and capabilities
3. `index.js` (if present) runs server-side logic
4. `www/` directory serves static content

### 6.2 HyperDB: Distributed Databases

Plugins can create HyperDB databases that automatically replicate across peers:

- **Schema definition**: Collections, indexes, and resolution functions
- **Deterministic keys**: Database identity derived from plugin domain + version
- **Automatic replication**: Data syncs when peers connect on the global topic
- **Conflict resolution**: Configurable strategies for concurrent writes

This enables applications like distributed social networks, collaborative documents, or decentralized marketplaces.

### 6.3 Hyperdrive: Distributed Files

For file storage, plugins use Hyperdrive:

- **Content-addressed**: Files identified by hash, enabling deduplication
- **Sparse replication**: Only requested files are downloaded
- **Version history**: Full history of changes preserved
- **Streaming support**: Large files can be streamed without full download

### 6.4 Plugin RPC: Custom Protocols

For real-time communication, plugins register protomux-rpc protocols via `sdk.channels`:

- **Protocol multiplexing**: Multiple RPC muxes share a single Hyperswarm connection
- **Named methods**: JSON request/response and fire-and-forget events (e.g. `chat.message`, `profile.updated`)
- **Bidirectional**: `request`, `event`, and `broadcast` between peers
- **Auto-reconnection**: RPC sessions are recreated when peers reconnect (see admin **Plugin RPC** stats)

This enables chat, collaboration, live profile sync, and other low-latency peer protocols without HTTP. See [plugins/PLUGIN_CHANNELS.md](plugins/PLUGIN_CHANNELS.md).

---

## 7. Security Model

P2NS provides security through cryptography rather than trust.

### 7.1 Cryptographic Guarantees

- **Identity**: Public keys are unforgeable; only the private key holder can sign
- **Integrity**: Hypercore's append-only structure detects tampering
- **Confidentiality**: Holesail tunnels use Noise protocol encryption
- **Authentication**: Peers verify each other's public keys during connection

### 7.2 Certificate Authority Integration

For browser compatibility, P2NS includes a local certificate authority:

1. A root CA is generated on first run
2. The root certificate can be installed in the system trust store
3. Per-domain certificates are generated on demand
4. Browsers see valid HTTPS for P2P domains

This is a pragmatic compromise: true end-to-end verification would require browser modifications, but CA-signed certificates provide immediate compatibility.

### 7.3 Peer Blocking and Trust

P2NS supports peer blocking:

- Blocked peers cannot connect or participate in consensus
- Block lists are local (not replicated)
- Future versions may support shared reputation systems

---

## 8. Network Topology

P2NS networks can operate in various configurations.

### 8.1 Master and Non-Master Nodes

- **Master nodes**: Maintain persistent connections, higher availability, serve as reliable peers for bootstrapping
- **Non-master nodes**: Connect on-demand, may have intermittent availability

Master nodes are not privileged in consensus—they simply provide stability.

### 8.2 Peer Discovery and Gossip

Peers discover each other through:
1. DHT lookup on the global topic
2. Connection to discovered peers
3. Replication of Autopass data (claims, votes)
4. Gossip of peer information

The network is self-organizing: new peers automatically integrate and begin participating in consensus.

### 8.3 Replication Strategies

Data replication follows Hypercore's model:
- **Live replication**: Changes propagate as they occur
- **Sparse replication**: Only requested data is fetched
- **Prioritized sync**: Recent data prioritized over historical

---

## 9. Philosophical Implications

P2NS embodies several philosophical principles:

### 9.1 Ownership Without Permission

In P2NS, domain ownership is established by cryptographic claim, not granted by authority. Anyone can claim any unclaimed domain. Disputes are resolved by peer consensus, not legal process.

### 9.2 Availability Through Redundancy

Content availability depends on peers willing to serve it. Popular content naturally becomes more available as more peers cache it. Unpopular content requires dedicated hosting by interested parties.

### 9.3 Censorship Resistance

No single entity can remove a domain or block access. Censorship would require:
- Controlling a majority of active peers (for consensus manipulation)
- Blocking all network paths to serving peers (for connectivity denial)

Both are difficult at scale.

### 9.4 The Cost of Decentralization

P2NS trades some conveniences for decentralization:
- No customer support for lost keys
- No legal recourse for domain disputes
- No guaranteed uptime without peer redundancy
- Higher latency than centralized DNS

These tradeoffs are acceptable for users who value sovereignty over convenience.

---

## 10. Future Directions

P2NS is a foundation for continued development.

### 10.1 Scaling Considerations

Current challenges at scale:
- Consensus voting requires observing many claims
- Storage grows with domain count

Potential solutions:
- Sharded consensus by domain namespace
- Pruning of abandoned claims

### 10.2 Governance Models

Future versions may explore:
- Stake-weighted voting (reputation or resource commitment)
- Domain namespaces with different governance rules
- Federated networks with cross-resolution

### 10.3 Interoperability

P2NS could integrate with:
- Traditional DNS (as fallback or bridge)
- Other P2P naming systems (IPNS, ENS)
- Tor/I2P for additional anonymity

---

## What we found

P2NS demonstrates that the internet's naming layer need not be centralized. By combining cryptographic identity, distributed consensus, NAT-traversing tunnels, and a rich plugin ecosystem, P2NS provides a complete alternative to traditional DNS and web hosting.

The system is not merely theoretical—it is implemented, functional, and available for use. Every component described in this whitepaper corresponds to working code that has been tested in real network conditions.

The internet was designed as a decentralized network of peers. Decades of commercial development have layered centralization on top of that foundation. P2NS peels back those layers, returning to the original vision: a network where participants are equals, where identity is self-sovereign, and where no single entity controls the map.

**The theory is simple: if you can prove you are you, and your peers agree you own a name, then you own that name. No permission required.**