> ## 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.34.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. In React Native from 0.33.0, request the Android runtime grants before start() with requestMeshPermissionsForConfig(config), and keep the development warnings (devPeerAddressWarnings, devLifecycleWarnings on ProtocolConfig) on while building: they flag a recipient that is not an off1 address and calls made in the wrong order. From 0.34.0, forScenario(scenario, { appId, profile, overrides }) builds a working React Native config from a named preset, and npx --no-install mesh-sdk-doctor checks a React Native host for known setup mistakes such as Expo Go without expo-dev-client.
> Call the company and product Offline Protocol, never Offline alone. Current packages: @offline-protocol/mesh-sdk 0.34.0 (React Native), offline-protocol-sdk 0.34.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.34.0 on crates.io, the OfflineProtocolSDK Swift package 0.34.0 (preview, iOS 13+ only), the Android library com.offlineprotocol:offline-protocol-sdk 0.34.0 on Maven Central (preview, minSdk 24), the Java binding com.offlineprotocol:offline-protocol-java 0.34.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.34.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.34.0, a project reference over the C API, not on NuGet), the browser binding (experimental; the offline-protocol-web crate 0.34.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.34.0; MeshSdk carries the React Native module's native surface), the service container image ghcr.io/offline-protocol/offline-protocol-service 0.34.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.3 (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.34.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__ or __FAST_LINK__ 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.3 is on npm (@offline-protocol/cli, command offline). Its local MCP server, named offline-protocol, runs with npx -y @offline-protocol/cli@0.3.3 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.34.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. From 0.34.0 an app can call requestFastLink(peerId) to bring up a Wi-Fi network with a peer it meets only over BLE (React Native and Flutter; Android 10+ hosts or joins, iOS joins only after a system prompt and needs the Hotspot Configuration entitlement); it never comes up on its own, and a file transfer uses it only when sent after fast_link_changed reports up. See /mesh-sdk/fast-link. 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.

# Fast link: Wi-Fi between phones that meet over Bluetooth

> Bring up a Wi-Fi link between two phones that meet only over Bluetooth LE with requestFastLink in Mesh SDK v0.34.0, for large transfers.

From v0.34.0 two phones that share a confirmed session but meet only over Bluetooth LE can bring up a Wi-Fi network between them for a large transfer. One device hosts a Wi-Fi Direct group with fresh random credentials, the credentials travel to the peer sealed in their 1:1 MLS session, and the peer joins. The stream opened over that network is an ordinary peer stream in the Wi-Fi slot, so traffic moves onto it through the SDK's normal transport selection. The design and its reasons are in [ADR 0038](https://github.com/Offline-Protocol/offline-protocol-sdk/blob/v0.34.0/docs/adr/0038-a-fast-link-is-offered-inside-the-session.md).

On the SDK's lab pair of an Android phone and an iPhone with no shared network, a 1 MiB file took 197.7 s over Bluetooth LE and about 2.5 s over a fast link, after one join prompt on the iPhone. A message too large for Bluetooth fits the peer-stream slot's 1 MiB ceiling.

## When it comes up

A fast link comes up only when your app asks for it. The engine never brings one up on discovery: on iOS every join shows a system prompt and takes the phone off its own Wi-Fi, so whether a transfer is worth that is the app's decision.

`requestFastLink(peerId)` is accepted when all of these hold:

* the peer has a confirmed 1:1 session with this device and a live Bluetooth LE link to it;
* the peer runs v0.34.0 or later, so its key package advertises fast-link support;
* no peer stream already reaches the peer, for example over a shared home network;
* this device can host or join, and holds no link with another peer. A device holds one link at a time.

Otherwise the call rejects. Bluetooth LE stays up throughout and carries traffic before, during and after the switch.

## Platform support

| Platform | Role |
| - | - |
| Android 10 and later | Hosts or joins. Hosting is a Wi-Fi Direct group; an Android joiner stays on its own Wi-Fi. |
| iOS | Joins only, after a system prompt. The iPhone leaves its own Wi-Fi while the link lasts. |
| Android below 10, desktop, browser | Neither. A request from or to such a device is refused. |

So a link needs an Android 10+ device on at least one side: an Android phone with an iPhone, or two Android phones. Two iPhones cannot link. It is available in the [React Native](https://www.offlineprotocol.com/docs/mesh-sdk/installation-rn.md) package and the [Flutter plugin](https://www.offlineprotocol.com/docs/mesh-sdk/flutter.md) (`MeshSdk.requestFastLink({'peerId': peer})` and `MeshSdk.closeFastLink({'peerId': peer})`), with the Wi-Fi slot (`transports.wifiDirect`) enabled. Over the FFI the engine methods are `request_fast_link` and `close_fast_link`; a custom platform declares what it can do with `wifi_direct_set_fast_link_roles`, and one that declares nothing is never asked to host or join.

## What your app does

1. Enable the Wi-Fi slot: `transports: { wifiDirect: { enabled: true } }`.
2. Set up the permissions below.
3. Register a `fast_link_changed` listener, then call `requestFastLink(peerId)` for a peer you are about to send something large to.
4. Start the transfer after `fast_link_changed` reports state `up` for that peer. A file transfer keeps the carrier it started on, so one started over Bluetooth before the link came up stays on Bluetooth.
5. Call `closeFastLink(peerId)` when you are done, or let the link end on its own.

```typescript theme={null}
import { OfflineProtocol, type ProtocolEvent } from '@offline-protocol/mesh-sdk';

// Ask for a fast link, then send the file once the link is up.
export function sendOverFastLink(
  protocol: OfflineProtocol,
  peerId: string,
  filePath: string,
  fileName: string
): Promise<string> {
  return new Promise((resolve, reject) => {
    const listener = (event: ProtocolEvent) => {
      if (event.type !== 'fast_link_changed' || event.peer_id !== peerId) return;
      if (event.state === 'up') {
        protocol.off('fast_link_changed', listener);
        protocol.sendFileFromPath({ recipient: peerId, filePath, fileName }).then(resolve, reject);
      } else if (event.state === 'closed') {
        protocol.off('fast_link_changed', listener);
        reject(new Error(`Fast link closed: ${event.reason ?? 'unknown'}`));
      }
    };
    protocol.on('fast_link_changed', listener);
    protocol.requestFastLink(peerId).catch((error: unknown) => {
      protocol.off('fast_link_changed', listener);
      reject(error);
    });
  });
}
```

`requestFastLink` resolves with a link id as soon as the first step is taken; the outcome arrives as `fast_link_changed` events. Match them by peer, not by that id: when the host answers with a network it already had, the link takes the host's id. A rejected or closed link leaves Bluetooth LE as it was, so the app can still send over it.

## Events

[`fast_link_changed`](https://www.offlineprotocol.com/docs/mesh-sdk/events#fast_link_changed) carries `peer_id`, `link_id`, `role` (`host` or `join`), `state` and, on `closed`, `reason`. It never carries a network name or a passphrase.

| State | Meaning |
| - | - |
| `requested` | This device can only join and asked the peer to host. |
| `hosting` | This device is bringing up the network. |
| `offered` | The network is up and its credentials were sent to the peer. |
| `joining` | This device received an offer and is joining. |
| `up` | A stream over the network proved the peer. Large traffic can use it now. |
| `closed` | The link ended; `reason` says why. |

Reasons include `declined` (the joiner's user said no, or the app is set to `requestedOnly`), `idle`, `lost`, `expired`, `background`, `busy`, `cannot_host`, `cannot_join` and `superseded` (another connection, such as a shared home network, reached the peer first and carries its traffic). Treat an unknown reason as a failure. Traffic moving onto the link is reported by `transport_switched`.

## When a link ends

The engine ends a link when its offer expires unused (120 s), when the stream over it is lost, after 60 s with nothing large carried (a body of 16 KiB or more) and no transfer to the peer under way, on `closeFastLink` from either side, and when the app pauses or stops the engine. On iOS the link ends when the app leaves the foreground. A file transfer that was on the link when it ended fails at once with `media_send_failed`; send it again and it goes over what remains.

## Permissions and entitlements

| Platform | What the app needs |
| - | - |
| iOS | The **Hotspot Configuration** capability (`com.apple.developer.networking.HotspotConfiguration`) in the app's entitlements, and the local-network `Info.plist` keys for [peer streams](https://www.offlineprotocol.com/docs/mesh-sdk/installation-rn.md#ios-keys). Without the entitlement every join ends `failed`. No location permission or Access Wi-Fi Information entitlement is needed. |
| Android | Android 10 or later, and the Wi-Fi Direct grants: `NEARBY_WIFI_DEVICES` on Android 13 and later, fine location on Android 12 and lower ([runtime permissions](https://www.offlineprotocol.com/docs/mesh-sdk/installation-rn.md#runtime-permissions)). No prompt is shown. |

iOS shows "“App” Wants to Join Wi‑Fi Network “DIRECT-…”?" on every join.

## Choose how far your app takes part

`wifiDirect.fastLink` decides whether a peer's app can start a link with yours:

| Value | Behaviour |
| - | - |
| `'any'` (default) | Hosts for a peer's request (Android) and joins an offer your app did not ask for, which shows the iOS join prompt without your app asking. |
| `'requestedOnly'` | Takes part only in links your app requests. A peer's request or unasked offer is answered `declined`. Two apps both set to this never link. |
| `'off'` | Never hosts or joins. |

```typescript theme={null}
import { OfflineProtocol } from '@offline-protocol/mesh-sdk';

export const protocol = new OfflineProtocol({
  appId: 'field-handoff',
  profile: 'default',
  transports: {
    ble: { enabled: true },
    wifiDirect: { enabled: true, fastLink: 'requestedOnly' },
  },
});
```

On Android a fast link and Wi-Fi Direct group formation (`wifiDirect.autoAccept`) share the one group a device can own: while either holds it, the other is refused.

## Security

The network name is `DIRECT-` plus random characters, with nothing derived from the app, the user or the device, and the passphrase is 128 random bits made fresh for every link. The offer travels once over the live Bluetooth link inside the confirmed MLS session, never through the outbox or a relay. The host admits only the peer it invited, and the joiner's stream must prove the host's address. The network's name and existence are visible to anyone in radio range while it is up; see residual risk R34 in the [threat model](https://github.com/Offline-Protocol/offline-protocol-sdk/blob/v0.34.0/docs/security/threat-model.md).

## Reference

* [Fast link state machine](https://github.com/Offline-Protocol/offline-protocol-sdk/blob/v0.34.0/docs/state-machines/fast-link.md): every state, timer and frame.
* [Mobile permissions, fast link](https://github.com/Offline-Protocol/offline-protocol-sdk/blob/v0.34.0/docs/mobile-permissions.md#fast-link).
* [`requestFastLink` and `closeFastLink`](https://www.offlineprotocol.com/docs/mesh-sdk/api/networking) in the generated reference.


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