Note: This WHITEPAPER is a copy from jackjackbits/bitchat by @jackjackbits.
bitchat is a decentralized, peer-to-peer messaging application that operates over Bluetooth Low Energy (BLE) mesh networks. It provides ephemeral, encrypted communication without relying on internet infrastructure, making it resilient to network outages and censorship. This whitepaper details the technical architecture, protocols, and privacy mechanisms that enable secure, decentralized communication.
- Introduction
- Architecture Overview
- Bluetooth Mesh Network
- Message Relay Protocol
- Store and Forward Mechanism
- Encryption and Security
- Channel-Based Communication
- Binary Protocol Specification
- Privacy Features
- Message Fragmentation
- Conclusion
bitchat addresses the need for resilient, private communication that doesn't depend on centralized infrastructure. By leveraging Bluetooth Low Energy mesh networking, bitchat enables direct peer-to-peer messaging within physical proximity, with automatic message relay extending the effective range beyond direct Bluetooth connections.
- Decentralized: No servers, no infrastructure dependencies
- Ephemeral: Messages exist only in device memory by default
- Encrypted: End-to-end encryption for private messages
- Resilient: Automatic mesh networking and message relay
- Private: No phone numbers, emails, or permanent identifiers
graph TB
subgraph "Application Layer"
UI[Chat UI]
CMD[Commands]
ROOM[Channel Management]
end
subgraph "Service Layer"
ENC[Encryption Service]
RETRY[Message Retry Service]
RETAIN[Message Retention Service]
COMP[Compression Service]
BATT[Battery Optimizer]
end
subgraph "Mesh Network Layer"
ROUTE[Message Router]
RELAY[Relay Engine]
STORE[Store & Forward Cache]
end
subgraph "Transport Layer"
PROTO[Binary Protocol]
FRAG[Fragment Handler]
BLE[BLE Central/Peripheral]
end
UI & CMD & ROOM --> ENC & RETRY & RETAIN & COMP & BATT
ENC & RETRY & RETAIN & COMP & BATT --> ROUTE & RELAY & STORE
ROUTE & RELAY & STORE --> PROTO & FRAG & BLE
style UI fill:#e1f5fe
style CMD fill:#e1f5fe
style ROOM fill:#e1f5fe
style ENC fill:#f3e5f5
style RETRY fill:#f3e5f5
style RETAIN fill:#f3e5f5
style COMP fill:#f3e5f5
style BATT fill:#f3e5f5
style ROUTE fill:#e8f5e9
style RELAY fill:#e8f5e9
style STORE fill:#e8f5e9
style PROTO fill:#fff3e0
style FRAG fill:#fff3e0
style BLE fill:#fff3e0
bitchat implements a custom mesh networking protocol over BLE, where each device acts as both a central (client) and peripheral (server), enabling multi-hop message delivery.
graph TD
subgraph "Physical Space (e.g., Conference, Protest, Disaster Area)"
subgraph "Zone A"
A1["Alice\n📱"]
A2["Bob\n📱"]
A3["Carol\n📱"]
end
subgraph "Zone B"
B1["Dave\n📱"]
B2["Eve\n📱"]
B3["Frank\n📱"]
end
subgraph "Zone C"
C1["Grace\n📱"]
C2["Henry\n📱"]
C3["Iris\n📱"]
end
end
A1 -.->|BLE| A2
A2 -.->|BLE| A3
A1 -.->|BLE| A3
B1 -.->|BLE| B2
B2 -.->|BLE| B3
B1 -.->|BLE| B3
C1 -.->|BLE| C2
C2 -.->|BLE| C3
C1 -.->|BLE| C3
A3 ==>|Bridge| B1
B3 ==>|Bridge| C1
style A1 fill:#e3f2fd
style A2 fill:#e3f2fd
style A3 fill:#e3f2fd
style B1 fill:#f3e5f5
style B2 fill:#f3e5f5
style B3 fill:#f3e5f5
style C1 fill:#e8f5e9
style C2 fill:#e8f5e9
style C3 fill:#e8f5e9
In this topology:
- Local clusters form based on physical proximity (≈30m range)
- Bridge nodes connect clusters when in overlapping range
- Messages hop across the network reaching distant peers
- No infrastructure required - completely peer-to-peer
sequenceDiagram
participant A as Device A
participant B as Device B
participant C as Device C
Note over A,C: Discovery Phase
A->>B: Advertise (Peripheral)
B->>C: Advertise (Peripheral)
B->>A: Scan & Connect (Central)
C->>B: Scan & Connect (Central)
Note over A,C: Communication Phase
A->>B: Message
B->>A: Response
B->>C: Message
C->>B: Response
Note over A: Acts as both<br/>Central & Peripheral
Note over B: Acts as both<br/>Central & Peripheral
Note over C: Acts as both<br/>Central & Peripheral
Each device:
- Advertises as a BLE peripheral with the bitchat service UUID
- Scans for other devices advertising the same service
- Connects to discovered peers as a central
- Maintains simultaneous connections as both central and peripheral
The mesh network automatically handles:
- Connection limits: Manages BLE connection constraints
- Duty cycling: Balances battery life with connectivity
- Peer tracking: Maintains active peer lists with RSSI values
- Automatic reconnection: Handles connection drops gracefully
The relay protocol enables messages to reach peers beyond direct Bluetooth range through multi-hop forwarding.
graph LR
A[Device A<br/>Origin<br/>TTL=3] -->|TTL=3| B[Device B<br/>Relay 1<br/>TTL=2]
B -->|TTL=2| C[Device C<br/>Relay 2<br/>TTL=1]
C -->|TTL=1| D[Device D<br/>Final<br/>TTL=0]
B -->|TTL=2| E[Device E<br/>TTL=1]
C -->|TTL=1| F[Device F<br/>TTL=1]
style A fill:#4caf50,color:#fff
style D fill:#2196f3,color:#fff
style B fill:#ffc107
style C fill:#ffc107
style E fill:#ff9800
style F fill:#ff9800
Each message includes a Time-To-Live (TTL) field:
- Initial TTL: Set to 7 for maximum reach
- Decrement: Each relay decrements TTL by 1
- Drop: Messages with TTL=0 are not forwarded
- Loop prevention: Message IDs prevent circular routing
function shouldRelay(packet):
if packet.ttl <= 0:
return false
if packet.messageID in processedMessages:
return false
if packet.recipientID == myID:
return false # We're the destination
if packet.recipientID == broadcast:
return true # Always relay broadcasts
return true # Relay private messages for meshThe store-and-forward system ensures message delivery to temporarily offline peers.
graph TB
subgraph "Message Cache Architecture"
subgraph "Regular Messages"
R1[Message 1]
R2[Message 2]
R3[Message 3]
R4[...]
R1 -.->|12hr TTL| R2
R2 -.->|100 msg limit| R3
R3 -.-> R4
end
subgraph "Favorite Peer Messages"
F1[Favorite 1]
F2[Favorite 2]
F3[Favorite 3]
F4[...]
F1 -.->|No TTL| F2
F2 -.->|1000 msg limit| F3
F3 -.-> F4
end
end
style R1 fill:#e3f2fd
style R2 fill:#e3f2fd
style R3 fill:#e3f2fd
style F1 fill:#fce4ec
style F2 fill:#fce4ec
style F3 fill:#fce4ec
sequenceDiagram
participant A as Sender A
participant B as Relay B
participant C as Recipient C
Note over C: Offline
A->>B: Send Message
B->>B: Store in Cache
B--xC: Delivery Failed<br/>(Recipient Offline)
Note over C: Comes Online
C->>B: Announce Presence
B->>C: Deliver Cached Messages
Note over C: Messages Received
Key features:
- Automatic caching: Messages cached when recipient unreachable
- Tiered retention: Regular (12hr) vs favorite peer (indefinite)
- Delivery on reconnect: Cached messages sent when peer returns
- Duplicate prevention: Message IDs prevent redundant delivery
bitchat implements multiple layers of encryption for secure communication.
sequenceDiagram
participant Alice
participant Bob
Alice->>Bob: Announce (includes public key)
Note over Bob: Stores Alice's public key
Bob->>Alice: Key Exchange Request<br/>(Bob's public key)
Note over Alice: Derives shared secret<br/>using X25519
Alice->>Bob: Key Exchange Response<br/>(Encrypted with shared secret)
Note over Bob: Derives shared secret<br/>verifies response
Alice->>Bob: Encrypted Message<br/>(AES-256-GCM)
Bob->>Alice: Encrypted Response<br/>(AES-256-GCM)
Note over Alice,Bob: Forward Secrecy Achieved
- Private Messages: X25519 key exchange + AES-256-GCM
- Channel Messages: Password-derived keys using Argon2id
- Digital Signatures: Ed25519 for message authenticity
graph LR
P[Password] --> A[Argon2id]
A --> K[256-bit Key]
K --> AES[AES-256-GCM]
S[Salt - SHA256 of channelName] --> A
I[Iterations - 10] --> A
M[Memory - 64MB] --> A
T[Parallelism - 4] --> A
style P fill:#ffccbc
style A fill:#b3e5fc
style K fill:#c8e6c9
style AES fill:#d1c4e9
Channels provide topic-based group messaging with optional password protection.
stateDiagram-v2
[*] --> Discovery
Discovery --> Joined: /j #channel
Joined --> PasswordPrompt: Channel is protected
Joined --> Unlocked: Channel is public
PasswordPrompt --> Unlocked: Correct password
PasswordPrompt --> PasswordPrompt: Wrong password
Unlocked --> [*]: Leave channel
state Discovery {
[*] --> Scanning
Scanning --> Found: Channel activity detected
}
state Unlocked {
[*] --> Active
Active --> Sending: Send message
Sending --> Active: Message sent
Active --> Receiving: Receive message
Receiving --> Active: Message displayed
}
- Hashtag naming: Channels identified by #channelname
- Password protection: Optional encryption with shared passwords
- Owner privileges: Transfer ownership, change passwords
- Message retention: Owner-controlled mandatory retention
- Decentralized discovery: Channels discovered through usage
bitchat uses an efficient binary protocol to minimize bandwidth usage.
classDiagram
class BitchatPacket {
+uint8 version
+uint8 type
+bytes[8] senderID
+bytes[8] recipientID
+uint64 timestamp
+uint8 ttl
+bytes[] payload
+bytes[64] signature
}
class PacketHeader {
<<1 byte>> version
<<1 byte>> type
<<8 bytes>> senderID
<<8 bytes>> recipientID
}
class PacketBody {
<<8 bytes>> timestamp
<<1 byte>> ttl
<<variable>> payload
}
class PacketSignature {
<<64 bytes>> Ed25519 signature
<<optional>> May be omitted
}
BitchatPacket --> PacketHeader
BitchatPacket --> PacketBody
BitchatPacket --> PacketSignature
| Type | Value | Description |
|---|---|---|
| ANNOUNCE | 0x01 | Peer announcement with public key |
| KEY_EXCHANGE | 0x02 | Key exchange messages |
| LEAVE | 0x03 | Graceful disconnect |
| MESSAGE | 0x04 | Chat messages (private/broadcast) |
| FRAGMENT_START | 0x05 | Start of fragmented message |
| FRAGMENT_CONTINUE | 0x06 | Continuation fragment |
| FRAGMENT_END | 0x07 | Final fragment |
| ROOM_ANNOUNCE | 0x08 | Channel status announcement |
| ROOM_RETENTION | 0x09 | Channel retention policy |
bitchat implements intelligent message compression to reduce bandwidth usage:
graph LR
M[Message] --> C{Size > 100 bytes?}
C -->|Yes| E[Entropy Check]
C -->|No| T[Transmit Raw]
E --> H{High Entropy?}
H -->|No| L[LZ4 Compress]
H -->|Yes| T
L --> S[30-70% Smaller]
S --> T
style M fill:#e3f2fd
style L fill:#c8e6c9
style S fill:#a5d6a7
The compression system:
- LZ4 Algorithm: Fast compression/decompression optimized for real-time use
- Entropy detection: Skips compression for already-compressed data
- Threshold-based: Only compresses messages larger than 100 bytes
- Transparent: Compression/decompression handled automatically
The system dynamically adjusts behavior based on battery state:
graph TD
B[Battery Monitor] --> C{Charging?}
C -->|Yes| P[Performance Mode]
C -->|No| L{Level?}
L -->|>60%| P
L -->|30-60%| BA[Balanced Mode]
L -->|10-30%| PS[Power Saver]
L -->|<10%| ULP[Ultra Low Power]
P --> F1[3s scan, 2s pause<br/>20 connections<br/>Continuous advertising]
BA --> F2[2s scan, 3s pause<br/>10 connections<br/>5s advertising intervals]
PS --> F3[1s scan, 8s pause<br/>5 connections<br/>15s advertising intervals]
ULP --> F4[0.5s scan, 20s pause<br/>2 connections<br/>30s advertising intervals]
style P fill:#4caf50,color:#fff
style BA fill:#8bc34a
style PS fill:#ffc107
style ULP fill:#f44336,color:#fff
Power modes affect:
- Scan duty cycle: How often and how long we scan for peers
- Connection limits: Maximum simultaneous peer connections
- Advertising intervals: How often we broadcast our presence
- Message aggregation: Batching window for outgoing messages
For efficient duplicate message detection:
- Bit-packed storage: Uses UInt64 arrays for memory efficiency
- SHA256 hashing: High-quality hash distribution
- Dynamic sizing: Adapts to network size (small: 500 items, large: 5000 items)
- Low false positive rate: 0.01 (1%) for accurate duplicate detection
bitchat implements several privacy-enhancing mechanisms.
gantt
title Cover Traffic Timeline
dateFormat X
axisFormat %s
section Real Messages
A to B :done, real1, 0, 1
C to D :done, real2, 4, 1
E to F :done, real3, 8, 1
section Cover Traffic
A to C (dummy) :crit, cover1, 2, 1
B to E (dummy) :crit, cover2, 6, 1
D to A (dummy) :crit, cover3, 10, 1
Cover traffic characteristics:
- Random intervals: 30-120 seconds between dummy messages
- Realistic content: Mimics actual user messages
- Marked internally: Identified and discarded after decryption
- Battery aware: Disabled when battery < 20%
graph LR
subgraph "Without Randomization"
U1[User Types] -->|0ms| T1[Transmit]
U2[User Types] -->|0ms| T2[Transmit]
U3[User Types] -->|0ms| T3[Transmit]
end
subgraph "With Randomization"
V1[User Types] -->|127ms| R1[Transmit]
V2[User Types] -->|394ms| R2[Transmit]
V3[User Types] -->|51ms| R3[Transmit]
end
style U1 fill:#ffcdd2
style U2 fill:#ffcdd2
style U3 fill:#ffcdd2
style V1 fill:#c8e6c9
style V2 fill:#c8e6c9
style V3 fill:#c8e6c9
This prevents timing analysis attacks by adding random delays (50-500ms) to all operations, making it impossible to correlate user actions with network traffic.
- No registration: No account creation or phone numbers
- Random peer IDs: Generated fresh each session
- Public key fingerprints: Only persistent identifier for favorites
- Nickname-based: Human-readable names without permanent binding
Large messages are automatically fragmented for reliable transmission over BLE.
graph TD
O[Original Message<br/>10KB] --> F[Fragment Handler]
F --> F1[Fragment 1<br/>START<br/>500 bytes]
F --> F2[Fragment 2<br/>CONTINUE<br/>500 bytes]
F --> F3[Fragment 3<br/>CONTINUE<br/>500 bytes]
F --> FN[Fragment N<br/>END<br/>≤500 bytes]
F1 -->|20ms delay| T1[Transmit]
F2 -->|20ms delay| T2[Transmit]
F3 -->|20ms delay| T3[Transmit]
FN -->|20ms delay| TN[Transmit]
T1 --> R[Reassembly Buffer]
T2 --> R
T3 --> R
TN --> R
R --> M[Complete Message<br/>10KB]
style O fill:#bbdefb
style M fill:#c8e6c9
style F fill:#fff3e0
style R fill:#f8bbd0
- Fragment ID: 8-byte identifier linking fragments
- Sequence tracking: START, CONTINUE, END types
- Reliability: Each fragment independently relayed
- Optimization: 20ms inter-fragment delay for BLE 5.0
To illustrate how all components work together, here's the complete flow of a message through the bitchat system:
sequenceDiagram
participant U as User Interface
participant E as Encryption Service
participant F as Fragment Handler
participant B as BLE Transport
participant M as Mesh Router
participant S as Store & Forward
participant R as Remote Peer
U->>E: User sends message
Note over E: Generate random delay<br/>(50-500ms)
alt Private Message
E->>E: Encrypt with X25519<br/>shared secret
else Channel Message
E->>E: Encrypt with Argon2id<br/>derived key
else Broadcast
E->>E: Sign with Ed25519
end
E->>F: Encrypted payload
alt Message > 500 bytes
F->>F: Fragment into chunks
loop Each fragment
F->>B: Send fragment
Note over B: 20ms inter-fragment delay
end
else Message ≤ 500 bytes
F->>B: Send complete message
end
B->>M: Transmit packet (TTL=7)
M->>M: Check recipient
alt Recipient online
M->>R: Direct delivery
else Recipient offline
M->>S: Cache message
Note over S: Retain 12hrs (regular)<br/>or indefinite (favorite)
end
alt TTL > 0
M->>M: Decrement TTL
M->>B: Relay to other peers
end
Note over R: When peer comes online
S->>R: Deliver cached messages
A planned enhancement will add WiFi Direct as an alternative transport layer:
- 100x bandwidth: 250+ Mbps vs BLE's 1-3 Mbps
- Extended range: 100-200m vs BLE's 10-30m
- Automatic handoff: Seamlessly switch between BLE and WiFi Direct
- Hybrid mesh: Some nodes BLE-only, others WiFi-capable
- Battery-aware: Only activate for large transfers or when charging
Future transport options being considered:
- Ultrasonic Communication: 1-10 kbps through air, works when radio is jammed
- LoRa (Long Range): 2-15km range for disaster scenarios
- Transport bonding: Use multiple simultaneously for redundancy
The planned architecture will abstract transport selection:
protocol TransportProtocol {
var transportType: TransportType { get }
var isAvailable: Bool { get }
func send(_ packet: BitchatPacket, to peer: PeerID?)
}
class TransportManager {
func sendOptimal(_ packet: BitchatPacket, to peer: PeerID?) {
// Choose based on: message size, battery, available transports
}
}While bitchat is designed to operate without internet infrastructure, there are scenarios where selective network bridging could enhance its capabilities without compromising its core principles. The Nostr protocol presents a particularly interesting integration opportunity.
graph TB
subgraph "Local Mesh Network"
L1[Peer A] -.->|BLE| L2[Peer B]
L2 -.->|BLE| L3[Peer C]
L3 -.->|BLE| GW[Gateway Peer]
end
subgraph "Internet Bridge"
GW ==>|Optional| NR[Nostr Relay]
end
subgraph "Remote Mesh Network"
NR ==>|Optional| GW2[Gateway Peer]
GW2 -.->|BLE| R1[Peer D]
GW2 -.->|BLE| R2[Peer E]
R1 -.->|BLE| R3[Peer F]
end
style GW fill:#ffeb3b
style GW2 fill:#ffeb3b
style NR fill:#9c27b0,color:#fff
1. Geographic Bridge: Connect isolated mesh networks across distances while maintaining local peer-to-peer operation.
2. Asynchronous Delivery: Nostr's event-based model aligns well with bitchat's store-and-forward mechanism, enabling message delivery across time zones and sporadic connectivity.
3. Selective Sharing: Users could opt-in to share specific channels or conversations beyond the local mesh, maintaining privacy by default.
4. Decentralized Architecture: Nostr's relay model preserves bitchat's decentralization principles - no single point of failure or control.
sequenceDiagram
participant M as Mesh Network
participant G as Gateway Service
participant N as Nostr Client
participant R as Nostr Relay
M->>G: Message for remote delivery
G->>G: Check opt-in status
alt Channel allows bridging
G->>N: Convert to Nostr event
Note over N: Add bitchat metadata<br/>Maintain encryption
N->>R: Publish event
R->>R: Store and relay
else Local only
G->>M: Keep within mesh
end
R->>N: New bitchat event
N->>G: Convert to bitchat message
G->>M: Inject into local mesh
Key considerations for maintaining bitchat's privacy model:
- Opt-in Only: Network bridging disabled by default, requiring explicit user consent
- Channel-Level Control: Bridge permissions managed per channel, not globally
- Maintained Encryption: Messages remain end-to-end encrypted when bridged
- Ephemeral Options: Support for Nostr's ephemeral events (NIP-16) for temporary bridging
- Identity Isolation: Generate separate Nostr keypairs unlinked to local peer identities
- Disaster Coordination: Bridge local emergency mesh networks to coordinate broader relief efforts
- Event Overflow: Extend large gatherings beyond Bluetooth range while maintaining local clusters
- Checkpoint Sync: Periodically sync specific channels when internet is briefly available
- Cross-Community Bridges: Connect related but geographically separated communities
This extension would be implemented as an optional module, ensuring the core bitchat system remains fully functional without any network dependencies. Users in pure offline environments would see no change, while those with selective connectivity could benefit from enhanced reach when desired.
bitchat demonstrates that secure, private messaging is possible without centralized infrastructure. By combining Bluetooth mesh networking, end-to-end encryption, and privacy-preserving protocols, bitchat provides resilient communication that works anywhere people gather, regardless of internet availability.
The system's design prioritizes:
- User privacy: No persistent identifiers or metadata collection
- Resilience: Automatic mesh networking and store-and-forward
- Security: Strong encryption with forward secrecy
- Efficiency: Binary protocols and intelligent caching
- Simplicity: No account creation or complex setup
As a public domain project, bitchat serves as both a practical tool and a reference implementation for decentralized, privacy-preserving communication systems.
This document is released into the public domain under The Unlicense.