Where to Find the Full BitChat Protocol Specification: A Complete Guide

The complete BitChat protocol specification is distributed across BinaryProtocol.swift (wire-format encoding), BitchatPacket.swift (data models), and the markdown design documents in the docs/ directory of the permissionlesstech/bitchat repository.

The BitChat protocol defines a decentralized messaging format optimized for peer-to-peer and mesh networking environments. Understanding the full specification requires examining both the implementation source code and the formal design documents that describe protocol extensions and behavioral requirements.

Wire Format Implementation

The definitive byte-level specification lives in localPackages/BitFoundation/Sources/BitFoundation/BinaryProtocol.swift. This file contains the complete description of how a BitchatPacket transforms into binary data suitable for Bluetooth Low Energy (BLE) transmission and back again.

Key components defined in this file include:

• Header layout – Byte offsets for version, type, sender/recipient IDs, timestamp, and payload length
• Flag definitions – Bitmasks for compression, routing indicators, and protocol version
• Padding strategy – BLE-friendly alignment to ensure packets meet minimum size requirements
• Encoding/decoding methods – The toBinaryData() and from() implementations that handle serialization

The BinaryProtocol.swift file serves as the authoritative reference for anyone implementing the protocol in other languages or building compatible hardware.

Packet Data Model

The logical representation of protocol messages resides in localPackages/BitFoundation/Sources/BitFoundation/BitchatPacket.swift. This Swift struct defines the high-level fields that comprise every BitChat packet:

• version – Protocol version number (e.g., 2 for current routing-enabled packets)
• type – Message type identifier (e.g., 0x01 for custom messages)
• senderID and recipientID – 8-byte peer identifiers (nil for broadcast)
• timestamp – Microsecond-precision Unix timestamp
• payload – Raw message content as Data
• signature – Optional cryptographic signature for authentication
• ttl – Time-to-live counter for mesh relay limits
• route – Optional source-routing path for directed delivery
• isRSR – Boolean flag indicating peer-ID rotation status

These fields map directly to the binary layout defined in BinaryProtocol.swift, creating a clear separation between the wire format and the in-memory representation.

Protocol Extensions and Design Documents

Beyond the core implementation, the docs/ directory contains formal specifications for advanced protocol features. These markdown files explain the rationale, packet modifications, and state machine requirements for extensions.

Source-Based Routing

docs/SOURCE_ROUTING.md specifies the optional routing extension that enables explicit path traversal through the mesh. This document details:

• The HAS_ROUTE flag in the packet header
• Format of the route field (ordered list of peer IDs)
• Relay behavior when intermediate nodes process routed packets
• Fallback mechanisms when routes become stale

Peer-ID Rotation

docs/PEER-ID-ROTATION.md documents the privacy-preserving Randomized Source Routing (RSR) mechanism. Key specifications include:

• The isRSR flag and its position in the packet structure
• Rotation frequency and entropy requirements
• Impact on signature validation and identity continuity
• Interaction with the routing table maintenance

Architecture Overview

docs/ARCHITECTURE_V2.md provides the high-level design rationale, explaining how the protocol evolved from v1 to v2, the reasoning behind specific field sizes, and the trade-offs between header overhead and feature flexibility.

Working with the Protocol in Code

The following Swift example demonstrates constructing, encoding, and decoding a BitChat packet according to the specification:

import Foundation
import BitFoundation

// 1️⃣ Build a packet
let payload = "Hello, BitChat!".data(using: .utf8)!
let packet = BitchatPacket(
    type: 0x01,                         // custom message type
    senderID: Data([0xAA,0xBB,0xCC,0xDD,0xEE,0xFF,0x00,0x11]),
    recipientID: nil,                  // broadcast
    timestamp: UInt64(Date().timeIntervalSince1970 * 1_000_000),
    payload: payload,
    signature: nil,                    // unsigned for this example
    ttl: 5,
    version: 2,                        // use v2 to enable routing flags
    route: nil,                        // no explicit route
    isRSR: false
)

// 2️⃣ Encode to binary (BLE‑friendly, padded)
if let binary = packet.toBinaryData() {
    // Send `binary` over the mesh transport
    print("Encoded packet, \(binary.count) bytes")
}

// 3️⃣ Decode received data back into a packet
if let received = BitchatPacket.from(binary) {
    let text = String(data: received.payload, encoding: .utf8) ?? "<invalid>"
    print("Received payload: \(text)")
}

This implementation uses the toBinaryData() method defined in BinaryProtocol.swift and the initializer from BitchatPacket.swift to ensure full protocol compliance.

Summary

• BinaryProtocol.swift provides the authoritative wire-format specification, including byte layouts, flags, and encoding logic
• BitchatPacket.swift defines the logical data model with version, routing, and privacy fields
• docs/SOURCE_ROUTING.md details the optional source-routing extension for directed mesh traversal
• docs/PEER-ID-ROTATION.md specifies the privacy-focused identity rotation mechanism
• docs/ARCHITECTURE_V2.md explains the protocol's design evolution and field-size rationale

Together, these files constitute the complete, implementation-backed specification of the BitChat protocol.

Frequently Asked Questions

Is the BitChat protocol formally standardized?

No, the BitChat protocol is currently defined by its reference implementation in the permissionlesstech/bitchat repository. The specification exists as executable Swift code in BinaryProtocol.swift and BitchatPacket.swift, supplemented by design documents in the docs/ directory. This "code-as-specification" approach ensures the implementation and documentation remain synchronized.

Which file defines the binary packet layout?

The binary layout is definitively implemented in localPackages/BitFoundation/Sources/BitFoundation/BinaryProtocol.swift. This file specifies byte ordering, header field offsets, the compression algorithm, and BLE padding requirements. Developers porting the protocol to new platforms should treat this file as the primary specification reference.

How does source-based routing work in BitChat?

Source-based routing allows a sender to specify an explicit path through the mesh network. When the HAS_ROUTE flag is set and the route field contains a non-nil array of peer IDs, intermediate nodes forward the packet only to the next hop in the sequence rather than broadcasting. The full specification, including route compression and expiration handling, is documented in docs/SOURCE_ROUTING.md.

What is the current protocol version?

The current implementation uses version 2, which introduces support for source-routing flags and the isRSR field. Version 1 packets are deprecated but may still be parsed for backward compatibility. The version field in BitchatPacket.swift is a UInt8, allowing for future extensions up to version 255.

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