# ADR-0003: Choose Holepunch P2P stack

- **Status:** Accepted
- **Date:** 2026-07-30

## Context

Connectivity must be pure peer-to-peer with E2E encryption, topic discovery, multi-writer metadata, and multiplexed app protocols — without app-operated servers.

## Decision

Adopt the Holepunch stack:

| Layer | Packages |
|-------|----------|
| Discovery / links | `hyperswarm`, `hyperdht` |
| Streams | `@hyperswarm/secret-stream` (via swarm) |
| Multiplex / RPC | `protomux`, `protomux-rpc` |
| Codecs | `compact-encoding`, `hyperschema` |
| Storage | `corestore`, `hypercore`, `hyperbee`, `hyperdrive` |
| Multi-writer | `autobase` (mesh registry) |
| Capabilities | `hyperswarm-capability` |
| App shell | `pear-runtime`, `pear-electron` |

Versions pinned from local mirror investigation (see `developer_docs/MODULES.md`).

## Consequences

### Positive

- Battle-tested mesh primitives
- Matches peardock/hello-pear patterns already used by the team
- Encryption and holepunching “for free”

### Negative / tradeoffs

- Learning curve for Autobase writer admission
- DHT bootstrap nodes are third-party infrastructure (acceptable; not app masters)

### Follow-ups

- [ ] Wire worker swarm in Phase 2+
- [ ] Schema freeze for invites/channels