docs

Documentation

Two kinds of document live here, and they answer different questions.

Guides answer "how do I use this". Start with the Quick Start and the integration guide for your platform.

Reference answers "what is the contract" and "why is it like this". Read it before changing behaviour, not before using the SDK.

Getting Started

Guide	Description
Quick Start	Get started in 5 minutes (React Native, iOS, Android)
Upgrading	Breaking changes and required app-side work
React Native Integration	Full SDK integration guide with complete API reference
iOS Integration	Native iOS (Swift) setup and usage
Android Integration	Native Android (Kotlin) setup and usage
The local API	Run the SDK as a service several local applications share: the service, the policy file, and the two client examples

Core Concepts

Guide	Description
Architecture	Design philosophy, crate organization, and system overview
API Reference	Core types, configuration structs, main API, and events
Configuration	All configuration parameters with use-case examples

Features

Guide	Description
DORS Deep Dive	How the transport selection engine works (scoring, switching, escalation)
DORS Configuration	Tuning DORS for different use cases with parameter reference
Message Delivery	Delivery lifecycle, retry/ACK system, flush triggers, and client-side persistence
Mesh Networking	Peer discovery, connection management, message delivery, and routing
Replicated Documents	Offline-first shared state: spaces, collections, how edits merge, attachments, storage
MLS Encryption	End-to-end encryption with auto-encryption and manual MLS APIs
Service Discovery	Decentralized service registration, discovery, and request/response
Telemetry	Enable the SDK's own telemetry with a portal key: what leaves the device, when, and the controls
Privacy	The app-store disclosures telemetry carries, and the one opt-in that changes them
Transport Architecture	Transport abstraction layer and how to add new transports
Reticulum Transport	Reticulum mesh transport setup, architecture, and platform integration
Nostr Transport	Nostr relay transport, censorship-resistant routing over WebSockets

Protocol specification

The wire and behaviour contract, independent of this implementation. A second implementation written against these documents should interoperate.

Document	Scope
Specification index	Layering, conformance language, the two overriding invariants
Identity and addressing	Address derivation, canonical form, session and group identifiers
Message model and wire format	The abstract message, the JSON floor, binary v1, the extension TLV registry
Control messages	Reserved prefix registry, control-plane signing, the two exemption classes
Document replication	Sync frames, anti-entropy, attachment references, blobs over the media path
Encryption envelopes	MLS envelope forms, media chunk envelope, sealed rich payload
Group protocol	Group frames, membership commits, leaf identity binding, relay broadcast
Capability negotiation	What peers advertise, what it gates, what absence means
Leaf node provisioning	What a constrained device owes at pairing, the never-committing profile
Bluetooth LE framing	The GATT contract, the fragment header, and what a receiver owes on reassembly
Peer-stream framing	The preamble that proves a stream's peer, the length-prefixed message frame, and the LAN discovery hint
DNS-SD mapping	A service descriptor as a DNS-SD instance: the subtype, the instance name, the TXT record and its bounds, and what an unsigned LAN import may never become
Username discovery and invites	The self-certifying invite payload, the username directory, and the signing-domain registry
The gateway contract	What a gateway is, the five verbs, the daemon wire protocol, and the backbone
The local API	One server, several local applications: JSON-RPC over a WebSocket, the method and event tables, routing, replay, errors
Custody	Holding a neighbour's replication frame for hours: the deposit, the receipt that settles nothing, the hold, redelivery, quotas, erase
Conformance	The two profiles, what every implementation owes, and the vectors that decide it

Security

Document	Scope
Threat model and trust boundaries	Assets, adversary classes, controls, and the residual risks stated plainly
Security Policy	Vulnerability reporting and safe harbor

State machines

Document	Governs
Overview	The invariant that spans all six
Delivery and acknowledgements	What happens to an inbound frame, and when a receiver acknowledges
Outbox and retries	An outbound message from send to terminal state
Session lifecycle	1:1 MLS establishment, confirmation, desync, and heal
Group message lifecycle	A group message through fan-out, buffering, and drain
Transport lifecycle	Transport availability, scoring, switching, escalation
Document replication	A document from edit to durable record, a space from offer to convergence, an attachment fetch

Decisions

Document	Scope
ADR index	Twenty-six decisions that are expensive to reverse or easy to undo by accident

If something in the codebase looks redundant or over-engineered, check here before simplifying it.

Bridge contracts

What each language binding owes the core, and what the core owes it. Every rule in here fails silently when violated.

Document	Scope
Shared contract	The thirteen rules every binding shares
Swift	iOS native and the React Native iOS bridge
Kotlin	Android native and the React Native Android bridge
Python	Desktop and tooling
TypeScript	The React Native JavaScript surface
Local API	A server fronting one engine for several local clients over a socket

Release history

Resource	Description
CHANGELOG	Unreleased changes and the current release
Changelog archive	Older releases, one file per minor series

Examples

Resource	Description
React Native Example App	Complete messaging app demonstrating all SDK features
Example App Setup	First-time setup for the example app
Example App Integration Guide	Step-by-step project integration walkthrough
Mesh Wiki	Mesh services: a device answering queries over BLE with no internet
Storage adapters	SQLite ProtocolStateStorage implementations for Swift, Kotlin and Python
cargo run -p offline-protocol --example replicated_notes	Replicated documents: open a store, edit, persist, reopen
cargo run -p offline-protocol-data --example offline_merge	What two people editing the same document offline actually get back

Contributing

Resource	Description
Contributing Guide	Development setup, code quality standards, and PR process

Licensing

Resource	Description
Licensing FAQ	The dual license in practice: app stores, the AGPL's reach, commercial licensing
Export Control Notice	Encryption export status of the SDK and what app teams must handle themselves