| i was frustrated by the documentation, so i had claude break this down. it might be wtong but i wouldve had to invest significant time to understand your networking model without it. ----- ## Holesail Connection & Encryption Architecture ### Core Technology Stack Holesail is built on top of *Holepunch’s Hyperswarm* ecosystem, specifically: 1. *HyperDHT* - Kademlia-based distributed hash table for peer discovery
1. *Hyperswarm* - High-level P2P networking abstraction
1. *@hyperswarm/secret-stream* - Noise Protocol + libsodium encryption layer
1. *UDX* - Custom UDP transport protocol ----- ### Connection Technique: UDP Holepunching *How it works:* 1. *Peer Discovery via DHT*: When you run `holesail --live <port>`, the server generates an *Ed25519 keypair* and announces its public key to the HyperDHT. The connection string (`hs://...`) is essentially this public key encoded.
1. *NAT Traversal*: The DHT nodes themselves act as holepunch facilitators. Unlike traditional STUN/TURN servers, any peer in the DHT can help coordinate the holepunch between two NAT’d peers. This is what makes it “truly P2P” - no centralized relay infrastructure.
1. *Holepunch Mechanics*: - Both peers send UDP packets to each other’s external IP:port (discovered via DHT)
- The simultaneous outbound packets “punch” holes in both NATs
- The DHT nodes relay timing/coordination metadata
- Once holepunched, a direct UDP connection is established 1. *Transport*: Uses *UDX* (custom UDP protocol) for the data plane after holepunching. TCP fallback is available when UDP fails. ----- ### Encryption Management *Two-layer encryption using Noise Protocol + libsodium secretstream:* |Layer |Protocol |Purpose |
|---------|--------------------------|------------------------------------|
|Handshake|*Noise XX pattern* |Key exchange, mutual authentication |
|Data |*libsodium secretstream*|Symmetric encryption of all payloads| *Cryptographic Primitives:* - *Key generation*: Ed25519 keypairs (identity/authentication)
- *Key exchange*: Noise Protocol XX pattern (ephemeral DH)
- *Symmetric encryption*: XChaCha20-Poly1305 (via libsodium secretstream)
- *Handshake hash*: Unique per-session identifier (`socket.handshakeHash`) for crypto binding *Secure vs Insecure Mode:* - `hs://s000...` = *Secure* (prefix `s`) - Full Noise handshake with authentication
- `hs://0000...` = *Insecure* - Presumably skips authentication (anonymous connections) *The flow:* ```
1. Peer A generates keypair → announces publicKey to DHT
2. Peer B looks up publicKey → initiates holepunch
3. After UDP connection established:
a. Noise XX handshake begins (ephemeral keys exchanged)
b. Both sides derive shared secret
c. secretstream initialized with derived keys
4. All subsequent data encrypted with XChaCha20-Poly1305
``` ----- ### Key Properties - *Identity-based routing*: Peers connect by public key, not IP address - works even if you move networks
- *E2E encrypted by default*: No way for DHT nodes or relays to read your traffic
- *No central servers*: Bootstrap nodes exist but only for DHT entry; traffic never routes through them
- *Firewall support*: Optional `firewall()` callback to accept/reject connections by remotePublicKey ----- ### References - Holesail: <https://github.com/holesail/holesail>
- HyperDHT: <https://github.com/holepunchto/hyperdht>
- Hyperswarm Secret Stream: <https://github.com/holepunchto/hyperswarm-secret-stream>
- Holepunch docs: <https://docs.holepunch.to/building-blocks/hyperswarm>
- Hypertele (predecessor): <https://github.com/bitfinexcom/hypertele> |
If you have a particular question about it, I am happy to help.