Peer Discovery Mechanisms

Relevant source files

The following files were used as context for generating this wiki page: - [core/src/discovery/peer.ts](https://github.com/Treystu/SC/blob/HEAD/core/src/discovery/peer.ts) - [android/app/src/main/java/com/sovereign/communications/ble/BLEDeviceDiscovery.kt](https://github.com/Treystu/SC/blob/HEAD/android/app/src/main/java/com/sovereign/communications/ble/BLEDeviceDiscovery.kt) - [web/src/utils/peerBootstrap.ts](https://github.com/Treystu/SC/blob/HEAD/web/src/utils/peerBootstrap.ts) - [README.md](https://github.com/Treystu/SC/blob/HEAD/README.md) - [tests/peer-discovery.test.ts](https://github.com/Treystu/SC/blob/HEAD/tests/peer-discovery.test.ts) - [BOOTSTRAP_VERIFICATION.md](https://github.com/Treystu/SC/blob/HEAD/BOOTSTRAP_VERIFICATION.md) - [V1_COMPLETION_FINAL_REPORT.md](https://github.com/Treystu/SC/blob/HEAD/V1_COMPLETION_FINAL_REPORT.md)

The Sovereign Communications (SC) platform operates without central servers, making robust peer discovery a cornerstone of its architecture. To establish connections, clients must have a way to find each other. The system employs a multi-faceted approach to discovery, combining local network scanning, proximity-based methods, and manual exchange of connection information. This ensures that peers can connect in a variety of scenarios, whether they are on the same Wi-Fi network, in close physical proximity, or communicating over the internet.

The core data structure for discovery is PeerInfo, which encapsulates a peer's identity, public key, and a list of connection endpoints. Each endpoint specifies a transport type (webrtc, bluetooth, local, manual) and the necessary addressing information. This flexible structure allows a single peer identity to be reachable through multiple communication channels.

Sources: README.md, core/src/discovery/peer.ts:6-18

Overview of Discovery Methods

The system utilizes several distinct methods for peer discovery, providing redundancy and adaptability to different environments.

This diagram shows the categorization of the various peer discovery mechanisms available in the system.
Sources: README.md, tests/peer-discovery.test.ts

Key Data Structures

The discovery process revolves around the PeerInfo and PeerEndpoint interfaces.

// core/src/discovery/peer.ts:6-18
export interface PeerInfo {
  publicKey: Uint8Array;
  peerId: string;
  endpoints: PeerEndpoint[];
  displayName?: string;
  timestamp: number;
}

export interface PeerEndpoint {
  type: 'webrtc' | 'bluetooth' | 'local' | 'manual';
  address?: string; // IP:port for manual/local
  signaling?: string; // Signaling peer ID for WebRTC
  rssi?: number; // Signal strength for BLE
}

Sources: core/src/discovery/peer.ts:6-18

The following table summarizes the available discovery methods:

Method	Type	Use Case
QR Code Exchange	Manual/Explicit	Sharing identity and connection info visually between two devices.
Manual IP:Port Entry	Manual/Explicit	Directly connecting to a peer with a known network address.
Web-to-Mobile Bootstrap	Manual/Explicit	Transferring a list of known peers from a web session to a newly installed mobile app.
Local Network (mDNS)	Network-Based	Automatically discovering peers on the same local Wi-Fi or Ethernet network.
Peer Announcement	Network-Based	Broadcasting one's existence to the mesh network for discovery by other peers.
Mesh Introduction	Network-Based	An existing peer in the mesh introduces two other peers to each other.
Bluetooth Low Energy (BLE)	Proximity-Based	Discovering nearby peers without an internet or Wi-Fi connection, based on signal strength.
Audio Pairing	Proximity-Based	Exchanging peer information using DTMF tones, for devices in close proximity.

Sources: README.md, core/src/discovery/peer.ts, tests/peer-discovery.test.ts

Manual and Explicit Discovery

These methods require direct user action to exchange connection information.

QR Code Exchange

This mechanism allows for the out-of-band exchange of peer information by encoding it into a scannable QR code.

The QRCodeDiscovery class provides static methods to generate and parse this data. The data is structured as a JSON object, which is then Base64-encoded and prefixed with sc://.

This flowchart illustrates the process of encoding PeerInfo into a QR code and decoding it back.
Sources: core/src/discovery/peer.ts:23-95, tests/peer-discovery.test.ts:98-121

The JSON payload structure is as follows:

Field	Type	Description
v	number	The version of the QR data format (currently 1).
pk	string	The peer's public key, hex-encoded.
id	string	The peer's unique ID.
name	string	The peer's optional display name.
endpoints	array	An array of PeerEndpoint objects.
ts	number	A timestamp of when the data was generated.

Sources: core/src/discovery/peer.ts:28-43

Manual IP:Port Entry

The ManualDiscovery class handles the parsing of a peer's address entered manually by a user. It supports the format peer_id@ip:port or simply ip:port. The class validates the port number to be within the valid range (1-65535).

Sources: core/src/discovery/peer.ts:97-138, tests/peer-discovery.test.ts:200-227

Web-to-Mobile Bootstrap

This mechanism facilitates a seamless transition from using the web app to a native mobile app. When a user on the web app decides to install the mobile APK, the web app saves a list of currently discovered and connected peers to localStorage. This data is then encoded and passed to the mobile app via a deep link.

The mobile app, upon launch, parses this bootstrap data from the deep link, retrieves the list of peers, and immediately attempts to connect to them, populating the user's mesh network without requiring manual discovery.

This sequence diagram shows the flow of bootstrapping a mobile app with peer data from a web session.
Sources: web/src/utils/peerBootstrap.ts, BOOTSTRAP_VERIFICATION.md

Proximity-Based Discovery

These methods are designed for discovering peers that are physically close, without needing a shared internet connection.

Bluetooth Low Energy (BLE)

BLE discovery is a key feature on mobile platforms, particularly Android. The BLEDeviceDiscovery.kt class manages the entire process.

The manager uses BluetoothLeScanner to find nearby devices. It applies a ScanFilter (though the service UUID is noted as a V1.1 optimization) and uses ScanSettings with SCAN_MODE_BALANCED for a compromise between discovery speed and battery life.

Discovered devices are ranked based on their RSSI (Received Signal Strength Indication) value, with stronger signals indicating closer proximity. A ConcurrentHashMap is used to store discovered devices, and callbacks are invoked to notify the application of new or updated peers.

This flowchart outlines the BLE device discovery process on Android.
Sources: android/app/src/main/java/com/sovereign/communications/ble/BLEDeviceDiscovery.kt, V1_COMPLETION_FINAL_REPORT.md

Key configuration and logic from BLEDeviceDiscovery.kt:

• MIN_RSSI: A constant set to -80, used to filter out devices that are too far away.
• startScanning(): Initiates the scan, checking for BLUETOOTH_SCAN and BLUETOOTH_CONNECT permissions.
• stopScanning(): Stops the ongoing scan and cleans up resources.
• ScanCallback: An inner class that handles onScanResult, onBatchScanResults, and onScanFailed events.

Sources: android/app/src/main/java/com/sovereign/communications/ble/BLEDeviceDiscovery.kt:33-118

Audio Pairing

Audio pairing uses DTMF (Dual-Tone Multi-Frequency) tones to encode and transmit peer information. This is suitable for devices in close proximity where one can play the tones and the other can listen. The tests indicate functionality for encoding data into tones and decoding them, even in the presence of noise.

Sources: README.md, tests/peer-discovery.test.ts:123-157

Mesh-Based Discovery

Once a peer is connected to the mesh, it can leverage the network itself to discover other peers.

Peer Announcement & Introduction

• Peer Announcement: A peer can broadcast its PeerInfo to the entire mesh. Other peers receiving this announcement can add the new peer to their routing tables. A deduplication mechanism based on a hash cache prevents processing the same announcement multiple times.
• Peer Introduction: An existing peer (A) can introduce two other peers (B and C) by sending a special message. For example, A can tell B about C's existence and connection endpoints.

The PeerIntroduction class provides methods to create and parse these introduction messages, which contain the introducer's ID and the full PeerInfo of the peer being introduced.

Sources: core/src/discovery/peer.ts:140-213, README.md

Peer Reachability Verification

After discovering a peer, it's crucial to verify if it's actually reachable. The PeerReachability class manages this by sending ping-like messages. It tracks test attempts and the timestamp of the last successful response to determine a peer's status as reachable, unreachable, or unknown. This helps maintain a healthy and accurate routing table by pruning unresponsive peers.

Sources: core/src/discovery/peer.ts:215-263, tests/peer-discovery.test.ts:276-310

Conclusion

The Sovereign Communications platform employs a diverse and resilient set of peer discovery mechanisms. This hybrid approach, combining manual, proximity, and network-based methods, is essential for a decentralized system that aims to function across various environments and network conditions. The ability to bootstrap new devices from existing web sessions, discover peers via BLE without internet, and leverage the mesh itself for discovery creates a robust foundation for building and maintaining a distributed communication network.