> ## 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.

> ## Agent Instructions
> These docs target Mesh SDK v0.32.0. Match the installed package and binding before generating code. Start at /getting-started/agents for task-specific reading paths. Apps that call enableTelemetry on 0.26.0 to 0.29.0 should update to 0.30.0 or later: the telemetry uploader trusts only the telemetry endpoint's issuing roots from 0.30.0.
> Call the company and product Offline Protocol, never Offline alone. Current packages: @offline-protocol/mesh-sdk 0.32.0 (React Native), offline-protocol-sdk 0.32.0 on PyPI (Python 3.10 to 3.13; wheels for macOS 14+ arm64, Linux x86_64 and aarch64 with glibc 2.34+, Windows x86_64; other hosts build from source; extras lan and http add LAN discovery, the HTTP front and offline-protocol-verify), the offline-protocol crates 0.32.0 on crates.io, the OfflineProtocolSDK Swift package 0.32.0 (preview, iOS 13+ only), the Android library com.offlineprotocol:offline-protocol-sdk 0.32.0 on Maven Central (preview, minSdk 24), the Java binding com.offlineprotocol:offline-protocol-java 0.32.0 on Maven Central (JDK 22+, native library from the GitHub release's desktop archives), the C header offline_protocol.h with the native library in the GitHub release's desktop archives, the Ruby binding offline_protocol 0.32.0 on RubyGems (Ruby 3.3+, native library from the GitHub release's desktop archives), the C# binding (preview, .NET 8; source in bindings/csharp in the SDK repository at tag v0.32.0, a project reference over the C API, not on NuGet), the browser binding (experimental; the offline-protocol-web crate 0.32.0 on crates.io, with the JavaScript in bindings/web built from the SDK repository, not on npm), the offline_protocol Flutter plugin (preview, not on pub.dev; a path dependency on the SDK repository at tag v0.32.0; MeshSdk carries the React Native module's native surface), the service container image ghcr.io/offline-protocol/offline-protocol-service 0.32.0 (linux/amd64 and linux/arm64), @offline-protocol/id-react 0.3.0, @offline-protocol/id-react-native 0.4.0, @offline-protocol/pol 0.1.2 and @offline-protocol/cli 0.3.2 (account setup commands such as offline apps status, offline apps native and offline apply since 0.3.0). Canonical docs URLs start with https://www.offlineprotocol.com/docs.
> The Mesh SDK runs in a native app or gateway, and from 0.31.0 in a browser through the experimental browser binding (a full node in a Web Worker; see /mesh-sdk/web). The OfflineID SDK for React does not provide browser mesh transport. Local mesh operation does not require a portal account or API key. The Mesh SDK appId is a mesh app identifier the developer chooses, not the portal App ID (app_...) that OfflineID and Proof of Location require.
> In v0.32.0 service RPC bodies are sealed in the 1:1 MLS session once the recipient runs 0.29 or later and the session is confirmed; discovery, the first request to a provider never met, and requests to older peers are signed plaintext, so keep secrets out of service bodies unless the event says encrypted: true. Service subscriptions (subscribeService, publishServiceUpdate, from 0.32.0) are always sealed in the 1:1 MLS session with no plaintext fallback; under the default restricted policy the provider app must answer service_subscribe_received with acceptServiceSubscription or rejectServiceSubscription within 60 seconds. Content that begins with __MEMBER__ is a reserved prefix and is refused. The HTTP front (offline-protocol-service --http) always carries calls inside encrypted direct messages but does not authorize callers. Message delivery, durable local acceptance and backend commit are distinct outcomes. Use the workflow guide for the required application logic.
> Offline Protocol CLI 0.3.2 is on npm (@offline-protocol/cli, command offline). Its local MCP server, named offline-protocol, runs with npx -y @offline-protocol/cli@0.3.2 mcp serve and requires no login or key. Hosted MCP is at https://mcp.offlineprotocol.com/mcp with an app API key in Authorization: Bearer and the matching App ID in x-app-id; organization keys are rejected, and Claude Desktop and Claude.ai cannot send these headers; there, use the public read-only endpoint https://mcp.offlineprotocol.com/public/mcp as a custom connector, or local MCP to scaffold or edit projects. Follow /tools/overview for setup and do not invent commands beyond it. MCP provides integration context and planning, not mesh execution; file-writing tools are local only.
> In v0.32.0 phone Wi-Fi peer streams carry data: Android over Wi-Fi Direct (the SDK forms the group with autoAccept on Android 10+) and over the Wi-Fi network it is on (DNS-SD), iOS over Network framework (LAN or AWDL). Android and iOS meet over that slot only on a shared Wi-Fi network that allows multicast; iOS 0.28 and later does not see iOS 0.27 or earlier over it. Otherwise use BLE or a provisioned relay across platforms. The Swift and Android packages are previews; the Android library is on Maven Central from 0.29.0 only, so never give a Gradle line for an earlier version. The receiver core ACKs before application persistence; use application acceptance for durable workflows.
> OfflineID App IDs are public. A request naming an application needs a credential: an allowed browser origin, an API key in X-Api-Key from a server, or, from an iOS or Android app, an attestation from a build registered to the application (iOS bundle ID and Team ID, Android package and signing certificate SHA-256). Register native apps with offline apps native add or offline apply, pass attestation providers (createExpoAppIntegrityProviders with @expo/app-integrity) to OfflineAppProvider, sign in on a physical device, and check readiness with offline apps status. Follow /getting-started/agent-quickstart and /id-sdk/app-attestation; error responses list the fixing commands in data.next_steps.
> Proof of Location is Sepolia testnet witness evidence, not zero-knowledge proof or proof of presence. The geohash is public onchain. Read /proof-of-location/security before integration.

# Lifecycle and listeners

> Start, pause, resume and stop the React Native protocol instance; register typed event handlers.

Import `OfflineProtocol` from `@offline-protocol/mesh-sdk`. These signatures match **v0.32.0**. Read [the integration guide](https://www.offlineprotocol.com/docs/getting-started/quickstart.md) for prerequisites and complete usage.

Use one protocol instance per process. Register handlers before startup; narrow `event.type` inside each callback. `wipePersistedState` is destructive and is not a normal shutdown step. Android wake registration is documented [separately](https://www.offlineprotocol.com/docs/mesh-sdk/methods.md#android-mesh-wake).

## Methods on this page

* [`on`](#on)
* [`off`](#off)
* [`once`](#once)
* [`removeAllListeners`](#removealllisteners)
* [`start`](#start)
* [`stop`](#stop)
* [`emitTestEvent`](#emittestevent)
* [`pause`](#pause)
* [`resume`](#resume)
* [`getState`](#getstate)
* [`destroy`](#destroy)
* [`wipePersistedState`](#wipepersistedstate)

## on

Registers an event listener

**One-shot events registered for late are replayed.** An event that
reached the SDK before any listener for it existed is held and delivered
to the first listener that registers: but only for the *one-shot* tags
(`internet_session_superseded`, `mesh_stopped_by_user`), which nothing
else ever restates. Everything else is dropped, as it should be: a
periodic event replayed after the fact would report a state that has
since changed.

That window is not an edge case, it is the default. The SDK subscribes to
the native emitter inside its own constructor, so between
`new OfflineProtocol(...)` and your first `on(...)` there is a stretch in
which events arrive with nothing registered: and Android's native
redelivery of held one-shot events fires on exactly that constructor-time
subscribe, landing squarely inside it. Registering synchronously right
after construction keeps the window at zero and is still the right habit;
this hold is what makes an `await` in between survivable.

Replay is **asynchronous** (a microtask), so a handler never runs before
the `on(...)` call that registered it has returned, and every listener
registered in the same tick, including an `'all'` listener added after a
specific one, receives it. Delivery stays **at-least-once**: these events
are state, not edges, and handlers must be idempotent. See
`docs/react-native-integration.md` §6.1.

**returns:** This instance for chaining

```typescript theme={null}
on<T extends ProtocolEvent = ProtocolEvent>(eventType: EventType | "all", listener: EventListener<T>): this
```

## off

Removes an event listener

**returns:** This instance for chaining

```typescript theme={null}
off<T extends ProtocolEvent = ProtocolEvent>(eventType: EventType | "all", listener: EventListener<T>): this
```

## once

Registers a one-time event listener

**returns:** This instance for chaining

```typescript theme={null}
once<T extends ProtocolEvent = ProtocolEvent>(eventType: EventType | "all", listener: EventListener<T>): this
```

## removeAllListeners

Removes all listeners for a specific event type, or all listeners if no type specified

**returns:** This instance for chaining

```typescript theme={null}
removeAllListeners(eventType?: EventType | "all"): this
```

## start

Starts the protocol

**Automatic BLE Management:**
When called, this method automatically starts BLE operations if BLE is enabled:

* Starts scanning for nearby devices advertising the Offline Protocol service
* Starts advertising this device so others can discover it
* Begins polling for fragments to send
* Handles incoming fragments from peers

**Automatic MLS Initialization:**
If encryption is enabled (default: true), MLS is automatically initialized with
platform-specific secure storage (iOS Keychain / Android EncryptedSharedPreferences).
To disable auto-initialization, set `encryption.enabled: false` in the config.

**Permissions Required:**

* iOS: Bluetooth permissions (NSBluetoothAlwaysUsageDescription in Info.plist)
* Android: BLUETOOTH\_SCAN, BLUETOOTH\_ADVERTISE, BLUETOOTH\_CONNECT (Android 12+)
  or BLUETOOTH, BLUETOOTH\_ADMIN, ACCESS\_FINE\_LOCATION (Android 11 and below)

**throws:** Error if protocol is already started or fails to start

```typescript theme={null}
start(): Promise<void>
```

## stop

Stops the protocol

**Automatic BLE Management:**
When called, this method automatically stops all BLE operations:

* Stops scanning for devices
* Stops advertising
* Disconnects from all connected peers
* Cleans up BLE resources

**throws:** Error if protocol is not started or fails to stop

```typescript theme={null}
stop(): Promise<void>
```

## emitTestEvent

Emits a test event to verify the event system is working

This is a debugging method that emits a network\_metrics event with all zeros.
Use this to verify that events are being delivered from Rust through the
native bridge to JavaScript.

```typescript theme={null}
emitTestEvent(): Promise<void>
```

## pause

Pauses the protocol (for background mode)

**throws:** Error if protocol is not running or fails to pause

```typescript theme={null}
pause(): Promise<void>
```

## resume

Resumes the protocol from pause

**throws:** Error if protocol is not paused or fails to resume

```typescript theme={null}
resume(): Promise<void>
```

## getState

Gets the current protocol state

**returns:** Protocol state (Stopped, Running, or Paused)

**throws:** Error if retrieval fails

```typescript theme={null}
getState(): Promise<ProtocolState>
```

## destroy

Destroys the protocol instance and cleans up resources

```typescript theme={null}
destroy(): Promise<void>
```

## wipePersistedState

Erases every byte of persisted SDK state for one account: the namespaced
secure store (MLS identity, sessions, peer trust records, the Nostr signing secret,
the protocol-state record key), the account's protocol-state directory
(outbox, pending queues, block list, media descriptors), and, when this
account owns it, or nobody does, the pre-namespace store an upgraded
install inherited from.

Call this on logout and on username switch, **after** `destroy()`. The
protocol persists as it works, so wiping underneath a live instance races
those writes; the native side rejects the call if the account named here is
the one the current instance is running.

Without it, an account's undelivered messages are restored and re-driven on
the next launch for the lifetime of the outbox, and on iOS, where the
Keychain outlives the app container, its identity and delivery state
survive an uninstall and are adopted again after a reinstall.

The account is named explicitly because `destroy()` clears the config the
namespace would otherwise be derived from. Pass the same `appId` and
`profile` the protocol was created with; any other pair names a different
account and wipes nothing.

Irreversible, and it rotates the account's MLS and Nostr identities: peers
holding a session with it will see a desync on next contact and re-establish
from a fresh key package. Safe to call twice: a failed wipe should simply
be retried.

Applications that supply their own storage providers must erase their own
containers: this only knows about the built-in ones.

```typescript theme={null}
wipePersistedState(appId: string, profile: string): Promise<void>
```

## Parameter and result types

Import these types from the same SDK package. Event payloads and configuration types are linked below.

### EventListener

```typescript theme={null}
export type EventListener<T extends ProtocolEvent = ProtocolEvent> = (event: T) => void;
```

### ProtocolState

```typescript theme={null}
export enum ProtocolState {
  Stopped = "Stopped",
  Running = "Running",
  Paused = "Paused",
}
```

## Related references

* [`identity_ready`](https://www.offlineprotocol.com/docs/mesh-sdk/events#identity_ready)
* [`mesh_stopped_by_user`](https://www.offlineprotocol.com/docs/mesh-sdk/events#mesh_stopped_by_user)
* [Event payloads](https://www.offlineprotocol.com/docs/mesh-sdk/events.md)
* [Configuration types](https://www.offlineprotocol.com/docs/mesh-sdk/configuration-types.md)
* [All public types](https://www.offlineprotocol.com/docs/mesh-sdk/public-types.md)
* [Error codes](https://www.offlineprotocol.com/docs/mesh-sdk/errors.md)
* [All API tasks](https://www.offlineprotocol.com/docs/mesh-sdk/reference.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.