Relay & rendezvous server for the Undertow P2P network. Run a beacon, help peers find each other, earn reputation — and one day, credits.
A Beacon is a publicly accessible server (VPS) that helps Undertow peers connect to each other. It serves two primary functions:
- Rendezvous — peers register their current IP/port so others can discover them
- Relay — when direct P2P connection fails (NAT, firewall), the Beacon forwards encrypted traffic between peers
Think of it as a lighthouse: ships (peers) report their position, and the lighthouse helps them find each other in the fog. When two ships can't see each other directly, the lighthouse relays their signals.
| Benefit | Description |
|---|---|
| Help the network | More beacons = more resilient, decentralized network |
| Earn reputation | Online time and bandwidth contribute to your standing |
| Future: earn credits | Reputation will convert to on-chain credits tradable for perks or real value |
| Priority access | Beacon operators get priority in the network |
⚠️ Economy is not live yet. Currently beacons run on good will and early-adopter spirit. The credit system is planned for the near future.
┌─────────────────────────────────────────────────────────────┐
│ UNDERTOW NETWORK │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Peer A │◄───────►│ Beacon │◄───────►│ Peer B │ │
│ │ (home) │ relay │ (VPS) │ relay │ (home) │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │
│ └───────────────────┼───────────────────┘ │
│ │ │
│ ┌──────┴──────┐ │
│ │ Harbor │ │
│ │ (bootstrap) │ │
│ └─────────────┘ │
│ │
│ Harbor = trusted bootstrap node (hardcoded in clients) │
│ Beacon = community-run relay/rendezvous node │
└─────────────────────────────────────────────────────────────┘
| Beacon | Harbor | |
|---|---|---|
| Who runs | Anyone with a VPS | Core team / verified operators only |
| Purpose | Relay + rendezvous | Bootstrap + metadata + compliance |
| Trust | Community node | Trusted entry point |
| Visibility | Sees encrypted packets only | May see metadata (future) |
| How to get | cargo run |
By invitation / verification |
Harbor is a separate, hardened version of Beacon. It is planned as a closed repository for verified operators. See Harbor (planned).
- Rust 1.70+ (
rustc --version) - VPS with public IP (any cloud provider: cloud.reg.ru, DigitalOcean, Hetzner, etc.)
- Ubuntu 22.04 or similar (tested on Ubuntu 22.04)
# Clone the repository
git clone https://github.com/daniil-verba/undertow-beacon.git
cd undertow-beacon
# Run the beacon
cargo run
# Then enter the port when prompted (default test port: 7777)That's it. The beacon is now listening and ready to accept peers.
🔒 The beacon expects encrypted packets only. Plaintext traffic is dropped.
- Peer connects to Beacon and registers its
PeerId+ current endpoint - Another peer asks the Beacon for a specific
PeerId - Beacon returns the registered endpoint
- Peers attempt direct connection (hole punching)
- If direct connection fails, peers negotiate a relay slot through the Beacon
- Beacon forwards encrypted packets between the two peers
- Traffic is opaque to the Beacon — it cannot read the contents
- Beacons will exchange peer lists and form a DHT overlay
- If a Beacon doesn't know a peer, it queries neighboring beacons
- Harbor nodes serve as authoritative bootstrap sources
Currently minimal — the beacon is designed to work out of the box:
| Setting | How to set | Default |
|---|---|---|
| Port | Prompt on startup | User-defined (tested on 7777) |
| Logs | stdout | Plain text, levels: INFO, WARN, ERROR |
Future settings (planned):
- Maximum relay bandwidth per peer
- Rate limiting thresholds
- Harbor authentication keys
- DHT bootstrap peers
To prevent abuse, future versions will enforce:
| Limit | Behavior |
|---|---|
| Outgoing traffic cap | Per-PeerId monthly quota |
| Quota exceeded | Temporary ban from relay/rendezvous until reset |
| Free tier | Generous allowance for normal users |
| Paid tier | Credits unlock higher limits |
Only outgoing traffic counts against your quota. Receiving data is always free.
| Metric | Reward |
|---|---|
| Uptime (hours online) | +credits |
| Relay bandwidth provided | +credits |
| Low latency / high throughput | Bonus multiplier |
Credits will be:
- Exchangeable for additional relay quota
- Tradable on a P2P marketplace
- Potentially backed by blockchain / smart contracts
The beacon supports multiple transports and will expand over time:
| Transport | Status |
|---|---|
| TCP | ✅ Working |
| UDP | ✅ Working |
| WebSocket | 📋 Planned |
| QUIC | 📋 Planned |
- All packets must be encrypted by the Undertow protocol layer
- Beacon operates on opaque encrypted payloads — it never sees message content
- Peer authentication via
PeerId(SHA-256 of X25519 public key) - Future: Harbor nodes may handle metadata for compliance purposes
Currently: plain text to stdout.
Future: structured logs (JSON), configurable levels, file output.
| Repository | Purpose | Status |
|---|---|---|
| undertow-protocol | Core library (PeerId, crypto, network) | 🚧 Prototype |
| undertow-client | TUI messenger | 🚧 Prototype |
| undertow-beacon | Relay / rendezvous server | 🚧 Prototype |
| undertow-harbor (planned) | Trusted bootstrap & compliance node | 📋 Planned |
- Basic TCP/UDP relay
- Rendezvous (peer registration & lookup)
- Hole punching coordination
- DHT peer discovery across beacons
- Rate limiting & traffic quotas
- Reputation & credit system
- Harbor integration
- WebSocket transport
- TUI for beacon management
- Structured logging
Harbor is the next evolution of Beacon:
- Bootstrap authority — hardcoded in official clients as the first point of contact
- Metadata handling — may process routing metadata for compliance and network health
- Verified operators — access granted after checks and approval
- Closed source initially — will open over time as the network matures
If you run a reliable Beacon for an extended period, you may be invited to operate a Harbor node.
- Rust — latest stable
- OS — Linux (Ubuntu 22.04 tested), macOS, Windows
- Network — Public IP required; UDP + TCP open on chosen port
MIT — free to use, modify, and distribute. Commercial use allowed.
- 📧 daniilverba123@gmail.com
- 💬 VK
- 🐛 Issues — GitHub Issues
Run a beacon. Light the way. Keep the current flowing.