BitChat Protocol Features: Complete Guide to Offline-First Messaging with Bluetooth Mesh and Nostr

BitChat implements a dual-transport, privacy-first messaging protocol that routes messages over Bluetooth LE mesh when offline and automatically falls back to Nostr relays for internet connectivity.

The BitChat messaging protocol, developed in the permissionlesstech/bitchat repository, combines peer-to-peer Bluetooth mesh networking with decentralized Nostr infrastructure. This architecture enables censorship-resistant communication that functions without internet access while seamlessly integrating with global relay networks when available.

Dual Transport Architecture: Bluetooth Mesh Plus Nostr Fallback

The defining characteristic of BitChat protocol features is its intelligent routing layer that unifies two fundamentally different transport mechanisms.

Bluetooth LE Mesh for Offline Messaging

Each BitChat device operates as a node in a decentralized Bluetooth Low Energy mesh network. The implementation in BLEService.swift handles:

• Automatic peer discovery via BLE advertisements
• Multi-hop message relay across up to seven intermediate devices
• Store-and-forward queuing when recipients are temporarily unreachable

This mesh topology ensures messages propagate through crowded areas—concerts, protests, disaster zones—without any internet infrastructure.

Nostr Protocol for Global Reach

When the mesh cannot reach a destination, the MessageRouter automatically promotes messages to the Nostr relay network. The NostrProtocol.swift implementation manages:

• WebSocket connections to geographically distributed relays
• BitChat-specific private envelope encryption (XChaCha20-Poly1305)
• Event signing and verification per NIP-01

The routing decision logic is abstracted behind the Transport protocol in Transport.swift, allowing the application layer to send messages without knowing which underlying transport will carry them.

Location-Based Channels and Geographic Scoping

BitChat protocol features geohash-coordinated public chat rooms that automatically group users by physical proximity.

The GeoRelayDirectory.swift file maps the device's current location to:

• A geohash-derived channel name (e.g., "u4pruydqqvj")
• A curated list of Nostr relays known to carry traffic for that region
• Geographic broadcast announcements that help nearby peers discover the same channel

This design eliminates the need for centralized room creation—users in the same area naturally share communication channels through spatial coincidence rather than explicit coordination.

Cryptographic Security and Identity Model

BitChat protocol features employ a dual-key identity system documented in WHITEPAPER.md:

Key Type	Purpose	Algorithm
Static identity key	Long-term device identification	Curve25519 (Noise XX)
Signing key	Nostr event authentication	Ed25519

Each device derives a stable 8-byte peer ID from its long-term keys, enabling persistent addressing without revealing the full public key. Private messages use the Noise Protocol for mesh transport and XChaCha20-Poly1305 for Nostr envelopes.

Courier System: Physical Message Carrying

Among the most distinctive BitChat protocol features is the store-and-forward courier mechanism specified in section 6.2 of WHITEPAPER.md:

When a recipient is out of Bluetooth range, the sender seals messages in courier envelopes and distributes copies to up to three connected peers. These devices physically carry the encrypted payload until they encounter the intended recipient, then deliver it automatically. This "data mule" pattern extends effective communication range beyond direct radio contact without internet dependency.

Public History Synchronization

Mesh peers reconcile recent public chat history using compact Golomb-coded set (GCS) filters. As described in WHITEPAPER.md section 6.3:

• Broadcast messages are cached with 6-hour time windows
• Peers exchange GCS filters every ~15 seconds
• Missing messages are requested and backfilled via BLE

This gossip protocol ensures new mesh participants rapidly converge on the current conversation state without flooding the network with redundant history.

Performance and Operational Features

LZ4 Compression and Adaptive Battery

The protocol applies LZ4 compression to all messages before transmission, reducing payload size for bandwidth-constrained BLE links. Adaptive battery modes throttle advertisement frequency and scan windows based on remaining charge, extending operational time on low-power devices.

IRC-Style Command Interface

Users interact through familiar slash commands:

• /msg <peer> <text> — private message
• /who — list visible peers
• /slap <target> — action message

These parse through the standard message pipeline without protocol-level distinction from regular chat.

Emergency Panic Wipe

The PanicResettingTransport implementation provides triple-tap immediate data destruction:

chatViewModel.panicReset()  // Erases all keys, outbox, and cached history

This operation completes in milliseconds, leaving no recoverable cryptographic material on the device.

Code-Level Protocol Usage

The Swift interface demonstrates how application code leverages these BitChat protocol features:

// Automatic transport selection — BLE preferred, Nostr fallback
chatViewModel.sendMessage("Mesh hello!", mentions: [])

// Encrypted direct message with transport-agnostic addressing
chatViewModel.sendPrivateMessage(
    "Confidential",
    to: peerID,
    recipientNickname: "bob",
    messageID: UUID().uuidString
)

// Geohash-scoped broadcast to location channel
chatViewModel.sendBroadcastAnnounce()

All calls route through the Transport abstraction, with concrete implementations in BLEService.swift extensions and NostrProtocol.swift.

Summary

BitChat protocol features deliver:

• Dual transport — Bluetooth LE mesh with automatic Nostr fallback
• Geographic channels — Geohash-based public rooms without central coordination
• Physical message carrying — Courier envelopes for offline store-and-forward
• Strong cryptography — Noise Protocol and XChaCha20-Poly1305 encryption
• Mesh-optimized sync — GCS filter reconciliation for public history
• Operational security — Emergency wipe and adaptive power management

These capabilities are implemented across Transport.swift, BLEService.swift, NostrProtocol.swift, and specified in detail in WHITEPAPER.md.

Frequently Asked Questions

How does BitChat work without internet access?

BitChat uses Bluetooth Low Energy mesh networking where each device relays messages for others. The protocol supports up to seven hops between source and destination, and the courier system allows messages to be physically carried by intermediate devices until reaching the recipient.

What encryption does BitChat use for private messages?

Private messages use the Noise XX handshake protocol over Bluetooth mesh, and XChaCha20-Poly1305 authenticated encryption when transmitted via Nostr relays. The dual-key identity system in WHITEPAPER.md section 3 separates long-term identity from signing operations.

Can BitChat messages be censored by relay operators?

Nostr relays can reject events, but the Bluetooth mesh operates entirely peer-to-peer without infrastructure dependencies. The protocol automatically falls back to mesh-only operation when relays are unavailable or filtering traffic, maintaining connectivity between physically proximate users.

What platforms does BitChat support?

The codebase is a universal Swift application supporting iOS, macOS, and watchOS natively, as declared in README.md. The protocol implementation is platform-agnostic and could be ported to Android or embedded systems.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}