Transport Layers (WebRTC & BLE)

Relevant source files

The following files were used as context for generating this wiki page:

• core/src/transport/webrtc-enhanced.ts
• core/src/transport/rtc-session-manager.ts
• android/app/src/main/java/com/sovereign/communications/ble/BLEConnectionManager.kt
• android/app/src/main/java/com/sovereign/communications/ble/BLEMultiHopRelay.kt
• ios/SovereignCommunications/Data/BluetoothMeshManager.swift
• README.md
• V1_READINESS.md
• COMPLETION_STATUS.md
• ios/README.md
• GAP_ANALYSIS.md

The Sovereign Communications platform utilizes a multi-transport architecture to facilitate decentralized, peer-to-peer communication. This hybrid approach ensures connectivity across various scenarios, both online and offline. The primary transport layers are WebRTC for internet-based communication and Bluetooth Low Energy (BLE) for local, serverless mesh networking on mobile devices.

This system prioritizes connection types to ensure the most efficient communication path is used. The general priority is WebRTC, followed by BLE, and then other local network discovery methods. This ensures low-latency connections when available, with robust fallbacks for offline or proximity-based communication.

Sources: README.md

Transport Layer Architecture

The following diagram illustrates the high-level architecture of the transport layers within the @sc/core library and platform-specific implementations.

WebRTC Transport Layer

WebRTC (Web Real-Time Communication) is the primary transport for real-time, low-latency communication between peers over the internet. It is implemented in the @sc/core library, making it available to all platforms (Web, Android, iOS). A key feature of this implementation is its ability to establish connections by relaying signaling data through the existing mesh network, avoiding the need for a central signaling server for subsequent connections.

Sources: README.md, V1_READINESS.md

Key Components

The WebRTC implementation is managed by two main classes:

• RTCSessionManager: Manages all WebRTC sessions. It is responsible for creating, tracking, and tearing down connections to multiple peers. It acts as the main entry point for initiating a connection.
• WebRTCEnhanced: Represents a single peer-to-peer connection. It encapsulates the RTCPeerConnection object, manages the data channels, and handles the SDP offer/answer and ICE candidate exchange lifecycle.

Sources: core/src/transport/rtc-session-manager.ts, core/src/transport/webrtc-enhanced.ts

Data Channels

The WebRTC transport uses multiple data channels, each optimized for a specific type of data. This allows for fine-grained control over reliability and ordering.

Channel Type	Reliability	Purpose
control	Reliable, Ordered	For critical control messages like heartbeats and acknowledgements.
reliable	Reliable, Ordered	For standard text messages that must arrive in order.
unreliable	Unreliable, Unordered	For real-time data like voice packets where speed is prioritized over reliability.
file	Reliable, Ordered	For file transfers, ensuring data integrity.

Sources: COMPLETION_STATUS.md

Signaling Flow

Initial peer connections require a signaling mechanism to exchange session information (SDP) and network candidates (ICE). While manual methods like QR codes are supported for bootstrapping, the primary method is to relay signaling messages through an already-established mesh connection.

The following diagram shows the signaling flow between two peers (Peer A and Peer B) arbitrated by an existing mesh network connection.

Sources: core/src/transport/webrtc-enhanced.ts, V1_READINESS.md, README.md

Bluetooth Low Energy (BLE) Transport Layer

The BLE transport layer enables direct, offline communication between mobile devices, forming a true mesh network without internet access. Implementations are platform-specific for Android and iOS.

Sources: README.md, GAP_ANALYSIS.md

Android BLE Implementation

The Android implementation is robust, supporting multi-hop relays and store-and-forward capabilities.

Key Components

• BLEConnectionManager.kt: Manages the lifecycle of BLE connections. It operates as both a GATT server (to be discovered) and a client (to discover others). It handles device scanning, connecting, and the low-level reading and writing of data to GATT characteristics.
• BLEMultiHopRelay.kt: Implements the store-and-forward logic. When a message is destined for a peer that is not directly connected, this component queues the message. When a connection to a new peer is established, it forwards the queued messages. This is critical for the "sneakernet" capability.

Sources: android/app/src/main/java/com/sovereign/communications/ble/BLEConnectionManager.kt, android/app/src/main/java/com/sovereign/communications/ble/BLEMultiHopRelay.kt, V1_READINESS_REPORT.md

Store-and-Forward Flow

The diagram below shows how the BLEMultiHopRelay handles an offline message.

Sources: android/app/src/main/java/com/sovereign/communications/ble/BLEMultiHopRelay.kt

iOS BLE Implementation

The iOS implementation leverages the CoreBluetooth framework to provide similar mesh networking capabilities.

Key Components

• BluetoothMeshManager.swift: This is the central class for BLE operations on iOS. It manages scanning for other devices, advertising the device's presence, and handling data transfer. A key feature is its support for state restoration, allowing the app to continue managing BLE connections even when it is suspended or terminated by the system.
• GATT Service: The iOS implementation advertises a custom GATT service with characteristics for exchanging peer IDs, status, and messages.

Sources: ios/SovereignCommunications/Data/BluetoothMeshManager.swift, ios/README.md

GATT Service & Characteristics

Both Android and iOS implementations use a compatible GATT service structure to ensure interoperability.

UUID (Example)	Name	Purpose	Permissions
SERVICE_UUID	Mesh Service	The primary service for Sovereign Communications.	-
CHAR_MESSAGE	Message Characteristic	For sending and receiving fragmented message data.	Read, Write, Notify
CHAR_PEER_ID	Peer ID Characteristic	To exchange the device's unique peer identifier.	Read
CHAR_STATUS	Status Characteristic	To share network status or availability.	Read, Notify

Sources: ios/SovereignCommunications/Data/BluetoothMeshManager.swift, PROGRESS.md

Conclusion

The dual-transport architecture of Sovereign Communications provides a resilient and versatile communication platform. WebRTC enables efficient, real-time communication for users connected to the internet, leveraging the mesh for decentralized signaling. Simultaneously, the sophisticated BLE transport layer on Android and iOS creates a powerful, offline-first local mesh network with store-and-forward capabilities. This combination ensures that users can communicate securely and reliably across a wide range of connectivity scenarios, fulfilling the project's core mission of decentralized communication.