> ## Documentation Index
> Fetch the complete documentation index at: https://www.offlineprotocol.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
> Offline-first mesh networking SDK for React Native. Peer-to-peer messaging over BLE, Wi-Fi Direct, Internet, Reticulum, and Nostr with intelligent transport switching.
# 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
BLE, Wi-Fi Direct, Internet, Reticulum, and Nostr, switched automatically based on network
conditions and message requirements.
MLS (RFC 9420) encryption for 1:1 and group conversations with forward secrecy, automatic
key exchange, and Ed25519 signing. Fail-closed by default.
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.
Encrypted MLS groups with member invitations, admin/member roles with last-admin safety
invariants, and automatic fan-out or O(1) relay broadcast.
Dynamic Offline Relay Switch scores every transport on signal, proximity, bandwidth,
congestion, energy, and reliability, with hysteresis and cooldown to prevent flapping.
Acknowledgments, exponential backoff retries, store-and-forward outbox, and message
deduplication.
Turn every device into a service provider. Register capabilities, discover services across
the mesh, and invoke them with request/response. No server required.
Real-time presence (online/away/offline) from both relay and peer sources, typing
indicators, and read receipts.
Chunked transfers with progress tracking, resumable descriptors across process restarts,
and sealed metadata for cloud-stored attachments.
A unified sink with push and pull channels covering protocol events, MLS lifecycle, metrics
frames, routing decisions, and device capability.
Mesh and relay decisions consider battery level, with automatic demotion when a device
drops below its relay threshold.
## Requirements
| Requirement | Minimum |
| ------------------- | -------------------- |
| React Native | 0.70.0 |
| React | 16.8.0 |
| iOS | 13.0 |
| Android | API 24 (Android 7.0) |
| JDK (Android build) | 17 |
| Node.js | 18+ |
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:
```typescript theme={null}
const protocol = new OfflineProtocol({ appId: 'my-app', profile: 'default' });
protocol.on('identity_ready', ({ address }) => {
console.log(address); // "off1q..."
});
```
`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](/docs/mesh-sdk/identity) 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](/docs/mesh-sdk/methods#service-discovery--rpc-meshservices) for the API.
## Architecture
The SDK is a set of modular Rust crates with platform bindings:
| Component | Responsibility |
| ------------------------------ | ------------------------------------------------------ |
| `offline-protocol-core` | Core types and data structures |
| `offline-protocol-transport` | Multi-transport abstraction across all five transports |
| `offline-protocol-router` | DORS routing and relay management |
| `offline-protocol-reliability` | ACKs, retries, deduplication |
| `offline-protocol-mls` | End-to-end encryption using MLS (RFC 9420) |
| `offline-protocol-services` | Service discovery and request/response |
| `offline-protocol` | Main protocol engine with automatic encryption |
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.
Get started with installation