Building PeerLink — a decentralized P2P messenger in C++ with NAT traversal and relay fallback
Hi everyone,
I've been working on a project called PeerLink, an experimental decentralized peer-to-peer messenger written in C++. The goal of the project is to explore resilient distributed messaging architectures that can operate without relying on a central message server.
This project started as an attempt to understand how real-world peer-to-peer messaging systems handle unreliable networks, NAT restrictions, and intermittent connectivity.
This article briefly describes the architecture, design goals, and current implementation status.
Motivation
Traditional messaging systems usually depend on centralized infrastructure that stores messages and coordinates communication.
While this model works well at scale, it also introduces:
- central points of failure
- dependency on infrastructure availability
- storage of communication metadata in centralized locations
PeerLink explores an alternative architecture where:
- peers communicate directly whenever possible
- relay nodes are used only when necessary
- message delivery reliability is preserved
- history is stored locally on user devices
High-Level Architecture
PeerLink is built around a distributed node-based model.
Each running instance of the messenger acts as a network node, capable of:
- accepting incoming connections
- initiating outgoing connections
- relaying messages
- storing local chat history
Communication between nodes follows a fallback strategy.
Connection flow:
- Direct TCP connection attempt
- Reverse connection attempt
- UDP hole punching attempt
- Relay-based delivery
This layered approach improves reliability in real-world network environments.
Core Features
The current implementation includes:
Peer-to-Peer Messaging
Nodes can connect directly and exchange messages without a central server.
Features:
- direct messaging between peers
- session-based communication
- persistent peer identity
Persistent Chat History
Message history is stored locally on each node.
Features:
- automatic history restoration after restart
- synchronization after reconnect
- per-peer message storage
This allows conversations to continue even after temporary disconnections.
NAT Traversal
One of the biggest challenges in peer-to-peer systems is NAT traversal.
PeerLink currently supports:
- reverse connection fallback
- UDP hole punching
- multi-strategy connection attempts
If direct communication fails, the system switches to alternative methods.
Relay-Based Delivery
When direct communication is not possible, messages are delivered through relay nodes.
Relay logic supports:
- forwarding messages between unreachable peers
- store-and-forward delivery
- retry logic with backoff
This enables communication even in restricted network environments.
Offline Message Delivery
If the recipient is temporarily offline:
- messages are queued
- delivery is retried
- acknowledgment confirms delivery
This improves reliability across unstable connections.
Bootstrap Nodes
Bootstrap nodes help new peers discover existing network participants.
They provide:
- initial peer discovery
- fallback connection paths
- network entry points
These nodes do not store message history permanently.
Networking Stack
PeerLink uses:
- C++
- WinSock / WinAPI
- custom binary protocol
- TCP + UDP communication
- retry and acknowledgment logic
The build system:
- xmake
Currently, the project is tested primarily on Windows.
Message Delivery Model
Messages follow a reliability-aware flow:
- Message is created locally
- Attempt direct delivery
- If delivery fails → fallback strategy
- If recipient offline → store-and-forward
- Retry until acknowledgment
Acknowledgment logic ensures messages are not silently lost.
Local Storage Model
Each node maintains:
- identity data
- peer list
- message history
- relay queue
History persists across restarts and reconnects.
This allows sessions to resume without losing prior messages.
Current Project Status
Early Alpha
The core networking infrastructure is implemented, but the project is still evolving.
Current focus areas:
- stability improvements
- connection reliability
- edge-case testing
- performance optimization
This version is not intended for production use.
How to Build
Requirements:
- C++ compiler
- xmake
- Windows environment
Build steps:
bash
xmake
