bitchat Development Roadmap: BLE Mesh Architecture Overhaul in 3 Phases

The bitchat roadmap centers on transforming its BLE transport from a monolithic "god-object" into a clean, layered mesh stack through link-layer extraction, a Sans-I/O engine core with simulator, and modular feature extraction.

The permissionlesstech/bitchat project is undertaking a foundational architectural restructuring of its Bluetooth Low Energy (BLE) networking layer. According to the official BLE-ARCHITECTURE-V3 design document, the bitchat development roadmap proceeds through three deliberate phases designed to eliminate race conditions, enable deterministic testing, and prepare the codebase for diverse peer-to-peer features.

Phase 1: Link-Layer Extraction

The first milestone of the bitchat roadmap moves CoreBluetooth delegates, scheduling, duty-cycle handling, and buffers behind new LinkEvent and LinkCommand ports.

This extraction eliminates the problematic "check-bind-then-act" race condition by making bindings engine-owned rather than delegate-owned. The implementation follows a specific sequence:

1. Radio-half extraction — Scanning, advertising, and duty-cycle logic migrate to BLERadioController (referenced as [#1539] in planning documents)
2. Binding and link-auth migration — Move to BLELinkAuthState and BLELinkBindings within the engine
3. Delegate reduction — CoreBluetooth delegates shrink to simple event emitters

Both steps (a) and (b) are already landed in the codebase as of the V3 document (lines 131-166).

Key Architecture Constraint

The link-layer extraction enforces strict concurrency contracts defined in lines 54-78 of the architecture document:

• Engine-confined — All engine state manipulation occurs on a dedicated serial queue
• bleQueue-confined — BLE operations remain isolated to their dispatch queue
• Lock-backed stores — Shared state uses explicit locking primitives

These constraints prevent deadlocks by construction rather than by debugging.

Phase 2: Sans-I/O Engine Core and Simulator

The second phase of the bitchat development roadmap converts the engine into a pure function with the signature handle(event) → [Effect].

This Sans-I/O architecture removes all side effects from the core logic, making the engine entirely deterministic. The team drives this core with a SimulatedLinkLayer that can:

• Execute property-based tests without real radios
• Run multi-node simulations without wall-clock waits
• Reproduce timing-dependent bugs consistently

The simulator is already functional in bitchatTests/Simulation/. Current deterministic tests complete in approximately 40 milliseconds and have already uncovered a real bug in the announce throttle logic (lines 194-202).

Engine Core Implementation Pattern

// Engine core handling an event – now a pure function
func handle(_ event: BLELinkEvent) -> [Effect] {
    switch event {
    case .bytesReceived(let id, let payload):
        // Decode, look up binding, produce effects (e.g., forward packet)
        return [.forward(packet: payload, to: id)]
    // … other cases
    }
}

Phase 3: Feature-Module Extraction

The final planned phase extracts each high-level capability into its own module, leaving only a thin transport core in the engine.

Modules planned for extraction include:

• Courier — Message relay and store-and-forward
• Board — Public topic-based messaging
• Pre-keys — Offline encryption key exchange
• Voice — Real-time audio streaming
• File transfer — Chunked data transmission
• Groups — Multi-party conversations
• Diagnostics — Network health and debugging
• Verification — Identity attestation flows
• Public archive — Historical message retention

Each module will own its state and register for its specific message types. The architecture document notes that a formal effect system is deferred until all modules are in place.

Link-Layer Event Emission

Once extraction completes, modules interact with the link layer through clean event interfaces:

// Emitting a link-layer event (e.g., new bytes received)
let event = BLELinkEvent.bytesReceived(linkID: 42, payload: data)
BLELinkLayer.shared.emitLinkEvent(event)   // Handed to the engine

Simulator Usage for Testing

The deterministic simulator enables rapid iteration on complex scenarios:

// Using the simulator for deterministic multi-node tests
let sim = SimulatedMesh()
sim.addNode(id: "alice")
sim.addNode(id: "bob")
sim.runScenario(.announceAndBind)   // No real Bluetooth required

Key Source Files in the bitchat Roadmap

File	Role in Roadmap
docs/BLE-ARCHITECTURE-V3.md	Canonical roadmap document with line-level references
BLEService+LinkLayerCentralRole.swift	CoreBluetooth delegate extensions (post-extraction central role)
BLEService+LinkLayerPeripheralRole.swift	Peripheral-role link-layer implementation
BLELinkLayer.swift	New BLELinkLayer class exposing emitLinkEvent
SimulatedMesh.swift	Test-only simulator driving the engine core
bitchat/Nostr/	Core Nostr protocol implementation used by transport
Package.swift	Swift package definition and module structure

Summary

• bitchat's roadmap follows three phases: link-layer extraction, Sans-I/O engine with simulator, and feature modularization
• Link-layer extraction is substantially complete, with BLERadioController and BLELinkAuthState already landed
• Sans-I/O engine core enables 40ms deterministic tests that have already found real bugs
• Modular feature extraction will separate courier, board, voice, file transfer, and other capabilities into independent modules
• Strict concurrency contracts (engine-confined, bleQueue-confined, lock-backed stores) prevent deadlocks by design

Frequently Asked Questions

What is the current status of the bitchat BLE architecture overhaul?

The link-layer extraction (Phase 1) is largely complete. The BLERadioController, BLELinkAuthState, and BLELinkBindings components are already implemented. The Sans-I/O simulator (Phase 2) is functional and actively catching bugs. Feature-module extraction (Phase 3) remains future work.

Where can I read the official bitchat development roadmap?

The canonical document is docs/BLE-ARCHITECTURE-V3.md in the permissionlesstech/bitchat repository. It contains detailed line references, phase breakdowns, and concurrency contract specifications (direct link).

How does the bitchat simulator improve testing?

The SimulatedMesh class drives the engine core without real Bluetooth hardware or wall-clock delays. Tests run in approximately 40 milliseconds, enable property-based testing across many scenarios, and provide deterministic reproduction of timing-dependent bugs.

What modules are planned for extraction from the bitchat engine?

The roadmap targets nine feature modules: courier, board, pre-keys, voice, file transfer, groups, diagnostics, verification, and public archive. Each will own its state and message-type registration, communicating through the thin transport core via the LinkEvent/LinkCommand ports.

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