# bitchat Technical Whitepaper
## Abstract
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.
## Table of Contents
1. [Introduction](#introduction)
2. [Architecture Overview](#architecture-overview)
3. [Bluetooth Mesh Network](#bluetooth-mesh-network)
4. [Message Relay Protocol](#message-relay-protocol)
5. [Store and Forward Mechanism](#store-and-forward-mechanism)
6. [Encryption and Security](#encryption-and-security)
7. [Room-Based Communication](#room-based-communication)
8. [Binary Protocol Specification](#binary-protocol-specification)
9. [Privacy Features](#privacy-features)
10. [Message Fragmentation](#message-fragmentation)
11. [Conclusion](#conclusion)
## Introduction
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.
### Key Features
- **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
## Architecture Overview
```mermaid
graph TB
subgraph "Application Layer"
UI[Chat UI]
CMD[Commands]
ROOM[Room 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
```
## Bluetooth Mesh Network
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.
### Network Topology
```mermaid
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
### Peer Discovery and Connection
```mermaid
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
Central & Peripheral
Note over B: Acts as both
Central & Peripheral
Note over C: Acts as both
Central & Peripheral
```
Each device:
1. **Advertises** as a BLE peripheral with the bitchat service UUID
2. **Scans** for other devices advertising the same service
3. **Connects** to discovered peers as a central
4. **Maintains** simultaneous connections as both central and peripheral
### Connection Management
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
## Message Relay Protocol
The relay protocol enables messages to reach peers beyond direct Bluetooth range through multi-hop forwarding.
### TTL-Based Routing
```mermaid
graph LR
A[Device A
Origin
TTL=3] -->|TTL=3| B[Device B
Relay 1
TTL=2]
B -->|TTL=2| C[Device C
Relay 2
TTL=1]
C -->|TTL=1| D[Device D
Final
TTL=0]
B -->|TTL=2| E[Device E
TTL=1]
C -->|TTL=1| F[Device F
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
### Relay Decision Logic
```python
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 mesh
```
## Store and Forward Mechanism
The store-and-forward system ensures message delivery to temporarily offline peers.
### Message Caching
```mermaid
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
```
### Delivery Flow
```mermaid
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
(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
## Encryption and Security
bitchat implements multiple layers of encryption for secure communication.
### Key Exchange Protocol
```mermaid
sequenceDiagram
participant Alice
participant Bob
Alice->>Bob: Announce (includes public key)
Note over Bob: Stores Alice's public key
Bob->>Alice: Key Exchange Request
(Bob's public key)
Note over Alice: Derives shared secret
using X25519
Alice->>Bob: Key Exchange Response
(Encrypted with shared secret)
Note over Bob: Derives shared secret
verifies response
Alice->>Bob: Encrypted Message
(AES-256-GCM)
Bob->>Alice: Encrypted Response
(AES-256-GCM)
Note over Alice,Bob: Forward Secrecy Achieved
```
### Encryption Layers
1. **Private Messages**: X25519 key exchange + AES-256-GCM
2. **Room Messages**: Password-derived keys using Argon2id
3. **Digital Signatures**: Ed25519 for message authenticity
### Key Derivation for Rooms
```mermaid
graph LR
P[Password] --> A[Argon2id]
A --> K[256-bit Key]
K --> AES[AES-256-GCM]
S[Salt - SHA256 of roomName] --> 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
```
## Room-Based Communication
Rooms provide topic-based group messaging with optional password protection.
### Room State Machine
```mermaid
stateDiagram-v2
[*] --> Discovery
Discovery --> Joined: /j #room
Joined --> PasswordPrompt: Room is protected
Joined --> Unlocked: Room is public
PasswordPrompt --> Unlocked: Correct password
PasswordPrompt --> PasswordPrompt: Wrong password
Unlocked --> [*]: Leave room
state Discovery {
[*] --> Scanning
Scanning --> Found: Room activity detected
}
state Unlocked {
[*] --> Active
Active --> Sending: Send message
Sending --> Active: Message sent
Active --> Receiving: Receive message
Receiving --> Active: Message displayed
}
```
### Room Features
- **Hashtag naming**: Rooms identified by #roomname
- **Password protection**: Optional encryption with shared passwords
- **Owner privileges**: Transfer ownership, change passwords
- **Message retention**: Owner-controlled mandatory retention
- **Decentralized discovery**: Rooms discovered through usage
## Binary Protocol Specification
bitchat uses an efficient binary protocol to minimize bandwidth usage.
### Packet Structure
```mermaid
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
<> payload
}
class PacketSignature {
<<64 bytes>> Ed25519 signature
<> May be omitted
}
BitchatPacket --> PacketHeader
BitchatPacket --> PacketBody
BitchatPacket --> PacketSignature
```
### Message Types
| 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 | Room status announcement |
| ROOM_RETENTION | 0x09 | Room retention policy |
## Performance Optimizations
### Message Compression
bitchat implements intelligent message compression to reduce bandwidth usage:
```mermaid
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
### Battery-Aware Operation
The system dynamically adjusts behavior based on battery state:
```mermaid
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
20 connections
Continuous advertising]
BA --> F2[2s scan, 3s pause
10 connections
5s advertising intervals]
PS --> F3[1s scan, 8s pause
5 connections
15s advertising intervals]
ULP --> F4[0.5s scan, 20s pause
2 connections
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
### Optimized Bloom Filters
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
## Privacy Features
bitchat implements several privacy-enhancing mechanisms.
### Cover Traffic
```mermaid
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%
### Timing Randomization
```mermaid
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.
### Ephemeral Identities
- **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
## Message Fragmentation
Large messages are automatically fragmented for reliable transmission over BLE.
### Fragmentation Flow
```mermaid
graph TD
O[Original Message
10KB] --> F[Fragment Handler]
F --> F1[Fragment 1
START
500 bytes]
F --> F2[Fragment 2
CONTINUE
500 bytes]
F --> F3[Fragment 3
CONTINUE
500 bytes]
F --> FN[Fragment N
END
ā¤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
10KB]
style O fill:#bbdefb
style M fill:#c8e6c9
style F fill:#fff3e0
style R fill:#f8bbd0
```
### Fragment Structure
- **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
## Complete Message Flow
To illustrate how all components work together, here's the complete flow of a message through the bitchat system:
```mermaid
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
(50-500ms)
alt Private Message
E->>E: Encrypt with X25519
shared secret
else Room Message
E->>E: Encrypt with Argon2id
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)
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
```
## Future Performance Enhancements
### WiFi Direct Transport
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
### Alternative Transports
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
### Transport Protocol Interface
The planned architecture will abstract transport selection:
```swift
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
}
}
```
## Future Considerations: Network Bridge Extension
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.
### Nostr as a Bridge Protocol
```mermaid
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
```
### Integration Benefits
**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 rooms 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.
### Implementation Approach
```mermaid
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 Room allows bridging
G->>N: Convert to Nostr event
Note over N: Add bitchat metadata
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
```
### Privacy Preservation
Key considerations for maintaining bitchat's privacy model:
1. **Opt-in Only**: Network bridging disabled by default, requiring explicit user consent
2. **Room-Level Control**: Bridge permissions managed per room, not globally
3. **Maintained Encryption**: Messages remain end-to-end encrypted when bridged
4. **Ephemeral Options**: Support for Nostr's ephemeral events (NIP-16) for temporary bridging
5. **Identity Isolation**: Generate separate Nostr keypairs unlinked to local peer identities
### Use Cases
- **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 rooms 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.
## Conclusion
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.*