Core Library Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Sovereign Communications project is a monorepo containing multiple platform applications (Web, Android, iOS) that all share a common core library, @sc/core. This library is the single source of truth for the project's cryptography, communication protocol, and mesh networking logic. Its purpose is to ensure consistent behavior, security, and interoperability across all platforms.
The core library is written in TypeScript and provides the foundational primitives for building decentralized, end-to-end encrypted applications. By centralizing this critical logic, any updates or security patches to @sc/core are automatically propagated to all client applications, ensuring a unified and secure ecosystem.
Sources: CONTRIBUTING.md, README.md
Monorepo Structure
The project's monorepo architecture places the @sc/core library at the center, with platform-specific applications depending on it. This structure facilitates shared logic and consistent updates.
The diagram below illustrates the relationship between the core library and the platform applications.
Sources: CONTRIBUTING.md
Key Components
The @sc/core library is organized into several distinct modules, each responsible for a specific aspect of the communication platform.
| Component | Description | Location |
|---|---|---|
| Cryptography | Handles identity, signing, key exchange, and encryption. | core/src/crypto/ |
| Protocol | Defines the binary message format for communication. | core/src/protocol/ |
| Mesh Networking | Manages peer connections, routing, and message relay. | core/src/mesh/ |
| Transport | Provides abstractions for underlying transport layers like WebRTC and BLE. | core/src/transport/ |
| Peer Discovery | Implements mechanisms for finding and connecting to other peers. | core/src/discovery/ |
Sources: CONTRIBUTING.md, IMPLEMENTATION_SUMMARY.md
Cryptography
The cryptographic module provides production-ready security primitives using audited, industry-standard libraries (@noble/curves, @noble/ciphers). It is the foundation of the platform's end-to-end encryption and identity management.
The cryptographic stack includes:
- Ed25519: Used for digital signatures to authenticate messages and establish identity.
- X25519: Used for Elliptic Curve Diffie-Hellman (ECDH) key exchange to establish shared secrets.
- XChaCha20-Poly1305: An Authenticated Encryption with Associated Data (AEAD) cipher used for encrypting message content with extended nonces.
- Double Ratchet: Implemented for perfect forward secrecy through automatic session key rotation.
- SHA-256: Used for generating key fingerprints and message hashes for deduplication.
Sources: IMPLEMENTATION_SUMMARY.md, README.md, COMPLETION_STATUS.md
The following diagram shows the relationship between the cryptographic components.
Sources: README.md, IMPLEMENTATION_SUMMARY.md
Binary Message Protocol
All communication within the mesh network uses a standardized binary message format. Each message consists of a fixed-size header and a variable-length, encrypted payload.
Message Header
The header is 109 bytes and contains metadata for routing, authentication, and message handling.
| Field | Size (bytes) | Description |
|---|---|---|
| Version | 1 | Protocol version number. |
| Type | 1 | The type of message (e.g., TEXT, FILE_CHUNK, CONTROL). |
| TTL | 1 | Time-To-Live, decremented at each hop to prevent infinite loops. |
| Reserved | 1 | Reserved for future use. |
| Timestamp | 8 | Unix timestamp in milliseconds when the message was created. |
| Sender ID | 32 | The sender's 32-byte Ed25519 public key. |
| Signature | 65 | A 65-byte compact Ed25519 signature of the message. |
Sources: IMPLEMENTATION_SUMMARY.md, README.md
Message Types
The protocol defines several message types to handle different kinds of communication, including TEXT, FILE_METADATA, FILE_CHUNK, VOICE, CONTROL, PEER_DISCOVERY, and KEY_EXCHANGE.
Sources: IMPLEMENTATION_SUMMARY.md
Mesh Networking
The mesh networking module is responsible for managing peer connections and routing messages through the network. It uses a flood routing algorithm.
Key sub-components include:
- Routing Table: An in-memory table that stores routes and information about known peers.
- Peer Registry: Tracks currently connected peers and their metadata, such as transport type and connection quality.
- Message Deduplication: A hash-based cache that stores hashes of seen messages to prevent processing duplicates.
- TTL Management: Enforces the Time-To-Live on messages, dropping them when TTL reaches zero.
- Message Priority Queue: Schedules messages for sending based on priority:
Control > Voice > Text > File. - Peer Health Monitoring: Uses adaptive heartbeats to monitor the health of connected peers and removes stale ones.
Sources: IMPLEMENTATION_SUMMARY.md, COMPLETION_STATUS.md
Message Routing Flow
The following diagram illustrates how an incoming message is processed by the mesh networking layer.
Sources: README.md, COMPLETION_STATUS.md
Peer Discovery
The core library supports multiple mechanisms for peers to discover and connect with each other, enabling flexibility in various network environments.
| Mechanism | Description |
|---|---|
| mDNS/Bonjour | Discovers peers on the same local network. |
| QR Code | Exchanges identity information (public key) by scanning a QR code. |
| Audio Pairing | Uses DTMF tones for proximity pairing. |
| Bluetooth Low Energy (BLE) | Uses RSSI-based discovery for mobile devices. |
| Manual Entry | Allows direct connection via IP address and port. |
| Mesh Introduction | An existing peer in the mesh introduces two other peers to each other. |
Sources: README.md, V1_COMPLETE_TASK_LIST.md
Conclusion
The @sc/core library is the architectural cornerstone of the Sovereign Communications project. It provides a robust, secure, and platform-agnostic foundation for all client applications. By encapsulating the complex logic of cryptography, networking protocols, and mesh routing, it enables rapid development of interoperable clients while maintaining a high standard of security and a single, verifiable source of truth for the entire system.
Sources: CONTRIBUTING.md, IMPLEMENTATION_SUMMARY.md