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|
```
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
Hey thanks for the feedback, I am rewriting the whole documentation at the moment to make it easier to understand and cover v2 of Holesail that we recently released.
If you have a particular question about it, I am happy to help.
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>
Hey thanks for the feedback, I am rewriting the whole documentation at the moment to make it easier to understand and cover v2 of Holesail that we recently released.
If you have a particular question about it, I am happy to help.