Skip to main content

​
Offline Protocol Mesh SDK

The Mesh SDK is an offline-first mesh networking SDK for React Native that enables peer-to-peer messaging across five transports with intelligent switching between them.

​
Why It Matters

In a world where connectivity is often unreliable, the Mesh SDK provides:
  • Offline-First: works without internet connectivity using BLE mesh networking
  • Intelligent Transport Switching: automatically selects the best of five transports using DORS
  • Mesh Networking: messages hop through multiple devices to reach their destination
  • Self-Certifying Identity: devices are addressed by a hash of their own identity key, so impersonation is not possible
  • Reliability: acknowledgments, retries, and deduplication ensure message delivery

​
Key Capabilities

Five Transports

BLE, Wi-Fi Direct, Internet, Reticulum, and Nostr, switched automatically based on network conditions and message requirements.

End-to-End Encryption

MLS (RFC 9420) encryption for 1:1 and group conversations with forward secrecy, automatic key exchange, and Ed25519 signing. Fail-closed by default.

Self-Certifying Addresses

Every device derives an off1… address from an identity key it mints for itself. Peers verify an address by re-deriving it from the key its owner presents.

Group Messaging

Encrypted MLS groups with member invitations, admin/member roles with last-admin safety invariants, and automatic fan-out or O(1) relay broadcast.

DORS Technology

Dynamic Offline Relay Switch scores every transport on signal, proximity, bandwidth, congestion, energy, and reliability, with hysteresis and cooldown to prevent flapping.

Reliability Layer

Acknowledgments, exponential backoff retries, store-and-forward outbox, and message deduplication.

Service Discovery & RPC

Turn every device into a service provider. Register capabilities, discover services across the mesh, and invoke them with request/response. No server required.

Presence & Typing

Real-time presence (online/away/offline) from both relay and peer sources, typing indicators, and read receipts.

Media & File Transfer

Chunked transfers with progress tracking, resumable descriptors across process restarts, and sealed metadata for cloud-stored attachments.

Telemetry

A unified sink with push and pull channels covering protocol events, MLS lifecycle, metrics frames, routing decisions, and device capability.

Battery-Aware

Mesh and relay decisions consider battery level, with automatic demotion when a device drops below its relay threshold.

​
Requirements

The SDK is a native module, so it does not run in Expo Go.

​
Identity

Your app does not choose its identity on the mesh. The SDK mints an Ed25519 identity key and derives a self-certifying address from it:
profile selects which stored identity this instance runs as and never leaves the device.
ProtocolConfig.userId was removed in v0.21.0. If you are upgrading, read Identity & Addressing before bumping. There is deliberately no in-place migration of existing sessions.

​
What You Can Build

  • Offline chat applications with end-to-end encrypted 1:1 and group messaging
  • Proximity-based social apps with connection requests, profiles, and presence
  • Collaborative tools for teams working with poor connectivity
  • Emergency communication systems that work when infrastructure fails
  • Off-grid networks spanning kilometres over LoRa via Reticulum
  • Decentralized service networks where devices expose and consume capabilities without a central server
  • Peer-to-peer marketplaces where nearby devices advertise services and transact directly

​
Service Discovery: The Offline Internet

Service Discovery turns the mesh into a decentralized service network where any device can be both consumer and provider, effectively an internet that works without the internet. On the traditional internet, a client discovers a service via DNS, connects to a server, and makes a request. Service Discovery follows the same pattern, but everything happens over the mesh. Devices advertise what they can do, others discover them through multi-hop routing, and invoke those capabilities directly. How it works:
  1. A device registers a service with an ID, version, and capability metadata
  2. Other devices broadcast discovery queries that propagate across the mesh via multi-hop routing
  3. Providers respond with their capabilities and hop count
  4. Consumers send requests directly to providers and receive responses
Because discovery propagates through the mesh, services do not need to be directly connected. A device five hops away can still be discovered and invoked. Examples: local AI inference, ad-hoc sensor networks, emergency resource coordination, event and venue services, collaborative computing, and decentralized content delivery. See Service Discovery for the API.

​
Architecture

The SDK is a set of modular Rust crates with platform bindings: Devices organize into clusters of nearby connected peers, with bridge connections joining clusters so messages can traverse the whole mesh.
The Rust crates are I/O-free protocol engines: they queue, route, encrypt, and select transports, but never open a socket or touch a radio. A platform bridge does the actual I/O. The React Native binding ships those bridges for iOS and Android, so nothing extra is required.

​
Licensing

The SDK is dual-licensed under AGPL-3.0-only or a commercial license. App-store distribution has consequences under the AGPL, and the software contains encryption subject to export control. Both are worth reviewing before shipping.

Next Steps

Get started with installation