Mesh Networking and Routing
Relevant source files
The following files were used as context for generating this wiki page:The Sovereign Communications (SC) project utilizes a decentralized mesh networking model to facilitate secure, end-to-end encrypted communication without central servers. The core of this system is responsible for managing peer connections, routing messages between nodes, and ensuring efficient and reliable message delivery across the network.
Key functionalities of the mesh networking layer include an in-memory routing table, a peer registry for tracking connected peers, message deduplication to prevent processing loops, and Time-to-Live (TTL) management to expire old messages. The system employs a flood routing algorithm, where messages are forwarded to all connected peers except the original sender.
Sources: IMPLEMENTATION_SUMMARY.md, README.md
Core Components
The mesh networking system is composed of several key classes that work together to manage peers and route messages.
| Component | Description | Source File |
|---|---|---|
RoutingTable | Manages the state of directly connected peers and determines the next hop for a message. | core/src/mesh/routing.ts |
PeerDirectory | A higher-level registry for all known peers, whether connected or not, and their capabilities. | core/src/mesh/directory.ts |
MessageRelay | Processes incoming messages, handles deduplication, TTL, and forwards them to other peers. | core/src/mesh/relay.ts |
SeenAdapter | A simple cache used by MessageRelay to track seen message hashes for deduplication. | core/src/mesh/seen-adapter.ts |
Peer and Routing Management
At the heart of the mesh network are the Peer data structure and the RoutingTable and PeerDirectory classes that manage them.
Peer Data Structure
A Peer represents another node in the network. It contains identification, connection state, and metadata used for routing decisions and maintaining network health.
This diagram shows the relationship between the Peer, PeerMetadata, and PeerCapabilities interfaces.
Sources: core/src/mesh/routing.ts:10-44
The table below details the properties of the Peer object.
| Property | Type | Description |
|---|---|---|
id | string | A unique identifier for the peer. |
publicKey | Uint8Array | The peer's 32-byte Ed25519 public key. |
state | PeerState | The current connection state (DISCONNECTED, CONNECTING, CONNECTED). |
transportType | string | The communication transport used (e.g., 'webrtc', 'ble'). |
metadata | PeerMetadata | Contains metrics and capability information about the peer. |
Sources: core/src/mesh/routing.ts:25-31
RoutingTable
The RoutingTable class is a low-level manager for directly connected peers. It holds an in-memory map of peers and provides methods to add, retrieve, and find the next hop for a message. It is also responsible for managing peer reputation.
Key methods include:
addPeer(peer: Peer): Adds a peer to the routing table.getPeer(peerId: string): Retrieves a peer by its ID.getNextHop(destinationId: string): Determines the next peer to forward a message to.updatePeerReputation(peerId: string, successful: boolean): Adjusts a peer's reputation score based on interaction success. A successful interaction increases the score, while a failure decreases it.
Sources: core/src/mesh/routing.ts:50-153, tests/integration/mesh-routing.integration.test.ts:57-78
PeerDirectory
The PeerDirectory acts as a global registry for all known peers, not just those that are currently connected. It allows for querying peers based on their capabilities, which is essential for more advanced routing decisions.
Key methods include:
addOrUpdatePeer(peer: Peer): Adds a new peer or updates an existing one.getPeer(peerId: string): Retrieves a peer by its ID.removePeer(peerId: string): Removes a peer from the directory.findPeersByCapability(feature: string): Returns a list of peers that support a specific feature (e.g., 'relay', 'file-transfer').
Sources: core/src/mesh/directory.ts:9-48
Message Relay and Forwarding
The MessageRelay class is the central component for processing and forwarding messages throughout the mesh network. It uses a "flood routing" algorithm.
Message Processing Flow
When a message is received, MessageRelay.processMessage executes a series of checks before forwarding it.
This flowchart illustrates the logic within the MessageRelay to validate and forward an incoming message.
Sources: core/src/mesh/relay.ts:37-75, README.md
Message Deduplication
To prevent infinite loops in the mesh network, the MessageRelay uses a SeenAdapter to track messages it has already processed. The adapter maintains an in-memory Set of message hashes. If a message's hash is already in the set, it is discarded.
// From: core/src/mesh/seen-adapter.ts
export class SeenAdapter {
private seen: Set<string>;
// ...
has(hash: string): boolean {
return this.seen.has(hash);
}
add(hash: string): void {
this.seen.add(hash);
// ...
}
}
Sources: core/src/mesh/seen-adapter.ts:4-28, core/src/mesh/relay.ts:41-45, tests/integration/mesh-routing.integration.test.ts:81-101
Time-to-Live (TTL)
Every message header contains a ttl field. Each time a message is relayed (a "hop"), its TTL is decremented. If the TTL reaches 0, the message is considered expired and is dropped, preventing it from circulating indefinitely.
Sources: core/src/mesh/relay.ts:47-51, tests/integration/mesh-routing.integration.test.ts:103-122
Relay Statistics
The MessageRelay class tracks metrics about its operations, which can be used for network monitoring and diagnostics.
| Metric | Description |
|---|---|
messagesReceived | Total number of messages received for processing. |
messagesForwarded | Total number of messages successfully forwarded to other peers. |
messagesDuplicate | Number of messages discarded because they were duplicates. |
messagesExpired | Number of messages discarded due to TTL expiration. |
messagesInvalid | Number of messages discarded due to an invalid signature or format. |
Sources: core/src/mesh/relay.ts:24-28, 93-100
Conclusion
The mesh networking and routing system in SC provides a robust foundation for decentralized communication. Through the combined work of the RoutingTable, PeerDirectory, and MessageRelay components, the system can manage peer connections, make routing decisions, and efficiently forward messages. Critical features like message deduplication via SeenAdapter and TTL management ensure network stability by preventing message loops and discarding stale packets. This architecture enables a resilient, serverless network where nodes collaborate to deliver messages.