A native iOS client for the Reticulum Network Stack, bringing decentralized, encrypted mesh messaging to iPhone and iPad.
Reticulum Messenger is the iOS counterpart to Sideband for Android. It implements the LXMF messaging protocol over Reticulum, enabling fully encrypted peer-to-peer communication that works over any medium — WiFi, cellular, LoRa, serial, or packet radio — with zero dependence on centralized infrastructure.
Status: Active Development (v0.3.0) The core protocol architecture is in place with a comprehensive feature set. Community contributions are welcome to refine, test, and extend functionality. See Contributing below.
There is currently no native iOS client for the Reticulum ecosystem. Android users have Sideband, and desktop/CLI users have NomadNet — but iOS users are left out. This project aims to change that with a clean, well-architected Swift implementation that:
- Runs natively on iOS using SwiftUI, CryptoKit, and the Network framework
- Has zero external dependencies — pure Swift and Apple frameworks only
- Is protocol-compatible with existing Reticulum networks and LXMF nodes
- Is designed for contributors with clean architecture and comprehensive documentation
- Reticulum identity generation (Ed25519 + X25519 keypairs)
- Reticulum packet encoding/decoding (wire-compatible format)
- AES-128-CBC encryption with Fernet tokens (protocol-compatible)
- HKDF-SHA256 key derivation, HMAC-SHA256 authentication
- Identity persistence and Keychain-ready storage
- Auto-reconnection with exponential backoff
- TCP client interface with HDLC framing
- UDP interface (unicast and broadcast)
- RNode BLE interface — connect to LoRa radio hardware via Bluetooth
- KISS protocol framing/deframing
- Full radio configuration (frequency, bandwidth, SF, coding rate, TX power)
- Quick presets: Long Range, Balanced, Fast
- Real-time RSSI, SNR, battery monitoring
- Firmware version detection
- LXMF message serialization via MessagePack
- Direct delivery and propagation node fallback
- Delivery receipts and status tracking
- Image attachments (photo picker)
- File attachments (document picker)
- Voice messages (audio recorder)
- Peer discovery via network announces
- Auto-announce — periodic presence broadcasting
- Transport mode — act as a Reticulum packet relay
- Propagation node mode — store-and-forward for offline peers
- Announce stream — live view of network announce traffic
- QR code identity sharing and scanning
- Paper message support (lxm:// URI scheme)
- Live mesh map — MapKit view showing peer positions
- GPS location sharing (opt-in)
- Device telemetry collection (battery, position)
- Peer location tracking with stale-entry cleanup
- Disappearing messages — auto-delete after 30s, 5m, 1h, 24h, or 1 week per conversation
- Identity backup & restore — password-encrypted identity export (.rnid files)
- Visual identity fingerprints — color-coded grid for at-a-glance identity verification
- Modern SwiftUI interface with tab navigation
- Deterministic identicon avatars from identity hashes
- Message reactions — emoji reactions with long-press context menu
- Conversation pinning — pin important chats to the top
- Message forwarding — forward messages between conversations
- Full-screen image viewer with pinch-to-zoom and share
- Mesh network topology graph — interactive visualization of nodes and connections
- Local notifications for incoming messages
- Haptic feedback (send, receive, connect events)
- Notification categories with quick reply
- Unread badges on conversations and app icon
- Conversation search
- Swipe-to-delete and swipe-to-pin conversations
- Backward-compatible data migration (safe upgrades)
- Full link establishment with proof verification
- Group messaging
- End-to-end encrypted file transfers over links
- Contact management with nicknames and notes
- Message search within conversations
- NomadNet page rendering
- iPad split-view layout
- Interoperability test suite against Python reference
The project is organized as a Swift Package containing the protocol libraries, and a separate iOS app target that consumes them:
ReticulumMessenger/
├── Packages/ReticulumKit/ # Protocol implementation (Swift Package)
│ ├── Sources/
│ │ ├── CCommonCrypto/ # C wrapper for CommonCrypto (AES-CBC)
│ │ ├── ReticulumKit/ # Reticulum Network Stack
│ │ │ ├── Cryptography/ # X25519, Ed25519, AES-CBC, Fernet, HKDF
│ │ │ ├── Identity/ # Cryptographic identity management
│ │ │ ├── Destination/ # Addressable network endpoints
│ │ │ ├── Packet/ # Wire-format packet encoding/decoding
│ │ │ ├── Interface/ # TCP, UDP, RNode BLE, KISS protocol
│ │ │ ├── Transport/ # Path management and packet routing
│ │ │ └── Link/ # Encrypted bidirectional links & channels
│ │ └── LXMFKit/ # LXMF Messaging Protocol
│ │ ├── Message/ # LXMessage type and serialization
│ │ ├── Router/ # Message routing, peer discovery, propagation
│ │ └── Serialization/ # MessagePack encoder/decoder
│ └── Tests/
├── ReticulumMessenger/ # iOS App (SwiftUI)
│ ├── App/ # App entry point and state management
│ ├── Models/ # UI data models (Conversation, RNodeInfo, etc.)
│ ├── Services/ # Messenger, storage, telemetry, notifications
│ └── Views/ # SwiftUI views
│ ├── Conversations/ # Conversation list, new conversation, QR codes
│ ├── Messages/ # Chat view, bubbles, attachment picker
│ ├── Network/ # Status, interface config, map, announce stream
│ ├── RNode/ # RNode scanning, connection, configuration
│ ├── Settings/ # Identity, interfaces, mesh features, about
│ └── Components/ # Reusable UI components (avatar, status)
└── ReticulumMessengerTests/
- Pure Swift — No external dependencies. Only Apple frameworks (CryptoKit, Network, CommonCrypto, SwiftUI, MapKit, CoreBluetooth, CoreLocation).
- Protocol-compatible — Wire-format packets, crypto operations, and LXMF messages are compatible with the reference Python implementation.
- Library-first — The protocol stack (
ReticulumKit+LXMFKit) is a standalone Swift Package that can be used independently of the iOS app. - Actor-based concurrency — Transport, routing, and storage use Swift actors for thread safety.
- Contributor-friendly — Each component has clear boundaries, making it easy to pick up and improve a specific area.
- Xcode 15+ (Swift 5.9+)
- iOS 17.0+ deployment target
- XcodeGen for project generation
# Clone the repository
git clone https://github.com/junomaluca/ReticulumMessenger.git
cd ReticulumMessenger
# Generate the Xcode project and open it
make setup
# Or manually:
brew install xcodegen
xcodegen generate
open ReticulumMessenger.xcodeproj# Run the Swift Package tests
make test
# Or via Xcode: Product → Test (⌘U)- Build and run on a simulator or device
- Go to the Network tab
- Tap + to add an interface
- Use the Testnet quick-fill button, or enter your own Reticulum node address
- The app will connect and begin discovering peers
- Go to Settings → RNode Device
- Tap Scan to discover nearby RNode hardware
- Select your device to connect via Bluetooth
- Configure radio parameters or use a preset (Long Range / Balanced / Fast)
- The RNode will appear as an interface in your network status
This project needs you. Whether you're experienced with Reticulum or new to mesh networking, there are meaningful ways to contribute:
| Area | Description | Difficulty |
|---|---|---|
| Link Establishment | Complete the link handshake with full proof verification | Advanced |
| Group Messaging | Multi-party encrypted conversations | Advanced |
| File Transfers | End-to-end encrypted resource transfers over links | Intermediate |
| Protocol Testing | Interoperability tests against the Python reference | Intermediate |
| Contact Management | Persistent contacts with nicknames, notes, grouping | Beginner |
| UI Polish | Animations, accessibility, iPad split-view layout | Beginner |
| Documentation | Protocol documentation, code comments, user guide | Beginner |
- Fork this repository
- Create a branch for your feature (
git checkout -b feature/group-messaging) - Make your changes with clear, well-documented code
- Add tests for new functionality
- Submit a pull request with a description of what you've done
Please read CONTRIBUTING.md for detailed guidelines.
Look for issues tagged good-first-issue — these are specifically chosen to be approachable for newcomers to the project.
Type 1 (single address):
┌────────┬──────┬───────────────────┬─────────┬──────────┐
│ Header │ Hops │ Destination Hash │ Context │ Data ... │
│ 1 byte │ 1 B │ 16 bytes │ 1 byte │ variable │
└────────┴──────┴───────────────────┴─────────┴──────────┘
Type 2 (with transport):
┌────────┬──────┬──────────────┬───────────────────┬─────────┬──────────┐
│ Header │ Hops │ Transport ID │ Destination Hash │ Context │ Data ... │
│ 1 byte │ 1 B │ 16 bytes │ 16 bytes │ 1 byte │ variable │
└────────┴──────┴──────────────┴───────────────────┴─────────┴──────────┘
Header byte: [HeaderType:2][PropType:2][DestType:2][PacketType:2]
Each identity consists of:
- Ed25519 signing keypair (authentication & signatures)
- X25519 key agreement keypair (encryption & key exchange)
- Identity hash =
SHA-256(Ed25519_pub ‖ X25519_pub)[:16]
Messages are MessagePack-encoded arrays:
[source_hash, destination_hash, method, {field_map}]
Field types: content (0x01), title (0x02), timestamp (0x03), attachments (0x04), source name (0x07), etc.
- Reticulum — The cryptography-based networking stack
- LXMF — Lightweight Extensible Message Format
- Sideband — Android LXMF client
- NomadNet — Terminal-based Reticulum client
This project is licensed under the MIT License — see LICENSE for details.
- Mark Qvist for creating Reticulum, LXMF, and Sideband
- The Reticulum community for building an alternative to centralized communication
- All contributors to this project