Bluetooth Mesh Network (BLEService)

Relevant source files

• bitchat/Services/BLE/BLEAnnounceHandler.swift
• bitchat/Services/BLE/BLERecentPeripheralCache.swift
• bitchat/Services/BLE/BLEService.swift
• bitchat/Services/Prekeys/PrekeyBundleStore.swift
• bitchat/Services/TransportConfig.swift
• bitchatTests/BLEServiceCoreTests.swift
• bitchatTests/BLEServiceTests.swift
• bitchatTests/EndToEnd/PrivateChatE2ETests.swift
• bitchatTests/EndToEnd/PublicChatE2ETests.swift
• bitchatTests/Integration/IntegrationTests.swift
• bitchatTests/Mocks/MockBLEService.swift
• bitchatTests/Services/BLEAnnounceHandlerTests.swift
• bitchatTests/Services/BLERecentPeripheralCacheTests.swift
• bitchatTests/TestUtilities/TestHelpers.swift

Purpose and Scope

This document describes the BLEService component, which implements the Bluetooth Low Energy mesh transport layer for BitChat. BLEService provides local, offline peer-to-peer communication through a self-organizing mesh network that operates without internet connectivity or central infrastructure.

This page covers:

• BLE scanning/advertising and dual-role connection management.
• Mesh topology tracking and source-based routing.
• Message deduplication and the gossip protocol.
• Fragmentation and MTU optimization via BLEFragmentAssemblyBuffer.
• Rate-limiting and security mitigations for subscription attacks (BCH-01-004).
• Integration with Noise Protocol encryption for private messaging.
• Courier store-and-forward and prekey bundle distribution.

Sources: bitchat/Services/BLE/BLEService.swift10-14 bitchat/Services/BLE/BLEService.swift152-162

---

Architecture and Core Components

BLEService operates as both a BLE Central (scanner/connector) and BLE Peripheral (advertiser), enabling bidirectional mesh connectivity. The service manages discovery, connection lifecycle, and packet routing in a unified component.

BLEService Class Structure

The following diagram maps the high-level system responsibilities to the specific code entities within BLEService.swift.

Title: BLEService Architecture and Code Entities

Key Design Principles:

• Dual-role operation: Acts as both central and peripheral simultaneously bitchat/Services/BLE/BLEService.swift37-38
• Thread-safe state: Uses BLELinkStateStore with strict queue ownership enforcement to prevent race conditions bitchat/Services/BLE/BLEService.swift38-39
• Gossip Protocol: Implements flood-fill broadcasting with Bloom filter-based deduplication via MessageDeduplicator bitchat/Services/BLE/BLEService.swift60-61
• Adaptive TTL: Employs RelayController (referenced via logic flow) to dynamically adjust packet TTL based on network density (node degree) bitchat/Services/TransportConfig.swift10-18

Sources: bitchat/Services/BLE/BLEService.swift13-110 bitchat/Services/TransportConfig.swift5-18

---

BLE Service Identifiers and Constants

BLEService uses distinct UUIDs for test and production networks to prevent cross-contamination:

Constant	Test UUID	Production UUID	Purpose
serviceUUID	F47B5E2D-4A9E-4C5A-9B3F-8E1D2C3A4B5A	F47B5E2D-4A9E-4C5A-9B3F-8E1D2C3A4B5C	Service advertisement bitchat/Services/BLE/BLEService.swift18-21
characteristicUUID	A1B2C3D4-E5F6-4A5B-8C9D-0E1F2A3B4C5D	Same	Message transfer bitchat/Services/BLE/BLEService.swift22
centralRestorationID	chat.bitchat.ble.central	Same	iOS state restoration bitchat/Services/BLE/BLEService.swift23
peripheralRestorationID	chat.bitchat.ble.peripheral	Same	iOS state restoration bitchat/Services/BLE/BLEService.swift24

Configuration Parameters:

• Default fragment size: TransportConfig.bleDefaultFragmentSize (469 bytes) bitchat/Services/TransportConfig.swift7
• Max MTU: 512 bytes bitchat/Services/BLE/BLEService.swift28
• Message TTL: TransportConfig.messageTTLDefault (7) bitchat/Services/TransportConfig.swift8

Sources: bitchat/Services/BLE/BLEService.swift18-34 bitchat/Services/TransportConfig.swift7-10

---

Connection Management and Link Selection

To maintain a reliable mesh, BitChat uses a sophisticated link store and fanout selector to manage concurrent BLE links.

Link State Tracking

The BLELinkStateStore (referenced as linkStateStore) centralizes all BLE link state, including peripheral connections (we-as-central) and central subscriptions (they-as-central) bitchat/Services/BLE/BLEService.swift38

• Noise Authentication: The service tracks noiseAuthenticatedLinkOwners to ensure a session is bound to a specific physical ingress link bitchat/Services/BLE/BLEService.swift44
• Link Rebinding: Implements rotation-rebind cooldowns to handle identity rotation during active connections bitchat/Services/BLE/BLEService.swift46-49

Peer Discovery and Reconnection

The BLERecentPeripheralCache remembers recently seen bitchat peripherals to arm background connections bitchat/Services/BLE/BLERecentPeripheralCache.swift3-7

• Reconnection Targets: Selects the freshest eligible peripherals for background connection, capped at limit bitchat/Services/BLE/BLERecentPeripheralCache.swift39-43

Title: Discovery and Connection Flow

Sources: bitchat/Services/BLE/BLEService.swift38-52 bitchat/Services/BLE/BLERecentPeripheralCache.swift3-53

---

Mesh Gossip and Relay Control

BitChat uses a "flood-fill" gossip protocol with intelligent suppression to prevent network saturation.

Relay Decision Logic

The service uses RelayController logic to handle packet forwarding bitchat/Services/TransportConfig.swift14-18

• Topology Awareness: In dense graphs (degree ≥ bleHighDegreeThreshold), TTL is clamped harder to contain floods bitchat/Services/BLE/BLEService.swift33 bitchat/Services/TransportConfig.swift17
• Adaptive TTL: Defaults to 7, but drops to 5 in dense graphs to prevent fragment floods bitchat/Services/TransportConfig.swift16-17

Deduplication

The MessageDeduplicator ensures that a packet is only processed or relayed once. Even if received from multiple neighbors, the hash-based check suppresses subsequent copies bitchat/Services/BLE/BLEService.swift60-61 Verified in tests to ensure duplicate packets are ignored bitchatTests/BLEServiceCoreTests.swift17-49

Sources: bitchat/Services/BLE/BLEService.swift33-61 bitchat/Services/TransportConfig.swift5-18 bitchatTests/BLEServiceCoreTests.swift17-49

---

Store-and-Forward (Courier) System

BLEService integrates with the CourierStore to carry messages for offline peers.

Prekey Bundle Distribution

To enable forward-secret offline messaging, peers gossip PrekeyBundles.

• PrekeyBundleStore: Caches signature-verified bundles from other peers bitchat/Services/Prekeys/PrekeyBundleStore.swift13-23
• One-Time Use: The store tracks usedIDs to ensure a prekey is never reused across different messages bitchat/Services/Prekeys/PrekeyBundleStore.swift35-36
• Assignment Persistence: Message IDs are mapped to specific prekey IDs so that re-deposits of the same message use the same prekey bitchat/Services/Prekeys/PrekeyBundleStore.swift37-38

Courier Deposit Policy

BLEService enforces a trust-based policy for accepting store-and-forward deposits.

• Mutual Favorites: Peers identified as mutual favorites get higher quota tiers bitchat/Services/BLE/BLEService.swift71-72
• Verified Peers: Standard verified peers are accepted, while unverified identities are rejected bitchat/Services/BLE/BLEService.swift73-74

Sources: bitchat/Services/Prekeys/PrekeyBundleStore.swift13-142 bitchat/Services/BLE/BLEService.swift63-80

---

Maintenance and Resource Management

Recent Peripheral Cache

To support background reconnection, BLERecentPeripheralCache tracks recently seen peripherals.

• Eviction: Uses an LRU policy with a capacity cap (bleRecentPeripheralCacheCap) bitchat/Services/BLE/BLERecentPeripheralCache.swift27-34
• Expiry: Entries older than bleRecentPeripheralMaxAgeSeconds (900s) are pruned bitchat/Services/BLE/BLERecentPeripheralCache.swift44-45

Fragment Assembly

Large messages are reassembled using BLEFragmentAssemblyBuffer.

• In-Flight Caps: Concurrent assembly is capped by bleMaxInFlightAssemblies (128) to protect memory bitchat/Services/BLE/BLEService.swift32
• Stall Protection: Reassembly states are reset if no fragments arrive within bleAssemblerStallResetMs (250ms) bitchat/Services/TransportConfig.swift69

Sources: bitchat/Services/BLE/BLERecentPeripheralCache.swift7-53 bitchat/Services/TransportConfig.swift9-72 bitchat/Services/BLE/BLEService.swift32-34