mirror of
https://github.com/permissionlesstech/bitchat-android.git
synced 2026-07-24 23:45:19 +00:00
157 lines
5.7 KiB
Markdown
157 lines
5.7 KiB
Markdown
|
|
# bitchat
|
|
|
|
A secure, decentralized, peer-to-peer messaging app that works over Bluetooth mesh networks. No internet required, no servers, no phone numbers - just pure encrypted communication.
|
|
|
|
## License
|
|
|
|
This project is released into the public domain. See the [LICENSE](LICENSE) file for details.
|
|
|
|
## Features
|
|
|
|
- **Decentralized Mesh Network**: Automatic peer discovery and multi-hop message relay over Bluetooth LE
|
|
- **End-to-End Encryption**: X25519 key exchange + AES-256-GCM for private messages
|
|
- **Channel-Based Chats**: Topic-based group messaging with optional password protection
|
|
- **Store & Forward**: Messages cached for offline peers and delivered when they reconnect
|
|
- **Privacy First**: No accounts, no phone numbers, no persistent identifiers
|
|
- **IRC-Style Commands**: Familiar `/join`, `/msg`, `/who` style interface
|
|
- **Message Retention**: Optional channel-wide message saving controlled by channel owners
|
|
- **Universal App**: Native support for iOS and macOS
|
|
- **Cover Traffic**: Timing obfuscation and dummy messages for enhanced privacy
|
|
- **Emergency Wipe**: Triple-tap to instantly clear all data
|
|
- **Performance Optimizations**: LZ4 message compression, adaptive battery modes, and optimized networking
|
|
|
|
## Setup
|
|
|
|
### Option 1: Using XcodeGen (Recommended)
|
|
|
|
1. Install XcodeGen if you haven't already:
|
|
```bash
|
|
brew install xcodegen
|
|
```
|
|
|
|
2. Generate the Xcode project:
|
|
```bash
|
|
cd bitchat
|
|
xcodegen generate
|
|
```
|
|
|
|
3. Open the generated project:
|
|
```bash
|
|
open bitchat.xcodeproj
|
|
```
|
|
|
|
### Option 2: Using Swift Package Manager
|
|
|
|
1. Open the project in Xcode:
|
|
```bash
|
|
cd bitchat
|
|
open Package.swift
|
|
```
|
|
|
|
2. Select your target device and run
|
|
|
|
### Option 3: Manual Xcode Project
|
|
|
|
1. Open Xcode and create a new iOS/macOS App
|
|
2. Copy all Swift files from the `bitchat` directory into your project
|
|
3. Update Info.plist with Bluetooth permissions
|
|
4. Set deployment target to iOS 16.0 / macOS 13.0
|
|
|
|
## Usage
|
|
|
|
### Basic Commands
|
|
|
|
- `/j #channel` - Join or create a channel
|
|
- `/m @name message` - Send a private message
|
|
- `/w` - List online users
|
|
- `/channels` - Show all discovered channels
|
|
- `/block @name` - Block a peer from messaging you
|
|
- `/block` - List all blocked peers
|
|
- `/unblock @name` - Unblock a peer
|
|
- `/clear` - Clear chat messages
|
|
- `/pass [password]` - Set/change channel password (owner only)
|
|
- `/transfer @name` - Transfer channel ownership
|
|
- `/save` - Toggle message retention for channel (owner only)
|
|
|
|
### Getting Started
|
|
|
|
1. Launch bitchat on your device
|
|
2. Set your nickname (or use the auto-generated one)
|
|
3. You'll automatically connect to nearby peers
|
|
4. Join a channel with `/j #general` or start chatting in public
|
|
5. Messages relay through the mesh network to reach distant peers
|
|
|
|
### Channel Features
|
|
|
|
- **Password Protection**: Channel owners can set passwords with `/pass`
|
|
- **Message Retention**: Owners can enable mandatory message saving with `/save`
|
|
- **@ Mentions**: Use `@nickname` to mention users (with autocomplete)
|
|
- **Ownership Transfer**: Pass control to trusted users with `/transfer`
|
|
|
|
## Security & Privacy
|
|
|
|
### Encryption
|
|
- **Private Messages**: X25519 key exchange + AES-256-GCM encryption
|
|
- **Channel Messages**: Argon2id password derivation + AES-256-GCM
|
|
- **Digital Signatures**: Ed25519 for message authenticity
|
|
- **Forward Secrecy**: New key pairs generated each session
|
|
|
|
### Privacy Features
|
|
- **No Registration**: No accounts, emails, or phone numbers required
|
|
- **Ephemeral by Default**: Messages exist only in device memory
|
|
- **Cover Traffic**: Random delays and dummy messages prevent traffic analysis
|
|
- **Emergency Wipe**: Triple-tap logo to instantly clear all data
|
|
- **Local-First**: Works completely offline, no servers involved
|
|
|
|
## Performance & Efficiency
|
|
|
|
### Message Compression
|
|
- **LZ4 Compression**: Automatic compression for messages >100 bytes
|
|
- **30-70% bandwidth savings** on typical text messages
|
|
- **Smart compression**: Skips already-compressed data
|
|
|
|
### Battery Optimization
|
|
- **Adaptive Power Modes**: Automatically adjusts based on battery level
|
|
- Performance mode: Full features when charging or >60% battery
|
|
- Balanced mode: Default operation (30-60% battery)
|
|
- Power saver: Reduced scanning when <30% battery
|
|
- Ultra-low power: Emergency mode when <10% battery
|
|
- **Background efficiency**: Automatic power saving when app backgrounded
|
|
- **Configurable scanning**: Duty cycle adapts to battery state
|
|
|
|
### Network Efficiency
|
|
- **Optimized Bloom filters**: Faster duplicate detection with less memory
|
|
- **Message aggregation**: Batches small messages to reduce transmissions
|
|
- **Adaptive connection limits**: Adjusts peer connections based on power mode
|
|
|
|
## Technical Architecture
|
|
|
|
### Binary Protocol
|
|
bitchat uses an efficient binary protocol optimized for Bluetooth LE:
|
|
- Compact packet format with 1-byte type field
|
|
- TTL-based message routing (max 7 hops)
|
|
- Automatic fragmentation for large messages
|
|
- Message deduplication via unique IDs
|
|
|
|
### Mesh Networking
|
|
- Each device acts as both client and peripheral
|
|
- Automatic peer discovery and connection management
|
|
- Store-and-forward for offline message delivery
|
|
- Adaptive duty cycling for battery optimization
|
|
|
|
For detailed protocol documentation, see the [Technical Whitepaper](WHITEPAPER.md).
|
|
|
|
## Building for Production
|
|
|
|
1. Set your development team in project settings
|
|
2. Configure code signing
|
|
3. Archive and distribute through App Store or TestFlight
|
|
|
|
## Android Compatibility
|
|
|
|
The protocol is designed to be platform-agnostic. An Android client can be built using:
|
|
- Bluetooth LE APIs
|
|
- Same packet structure and encryption
|
|
- Compatible service/characteristic UUIDs
|