bitchat-android/docs/PEERID_GATT_SERVER_CLIENT_SPEC.md

Bitchat Mesh: Direct Client Identity Signaling & Connection Deduplication Spec

1. Overview

This specification details the mechanism for Bitchat nodes to signal their persistent Peer Identity over Bluetooth Low Energy (BLE) to prevent duplicate connections.

In a privacy-preserving mesh network, devices frequently rotate their MAC addresses. This creates a problem where two nodes might establish multiple redundant connections to each other (thinking they are new devices), wasting limited connection slots and battery power.

This spec defines a dual-strategy approach:

1. Passive Signaling: Inclusion of Peer ID in BLE Scan Responses (Server-side).
2. Active Signaling: A dedicated GATT "Identity Characteristic" for clients to write their ID immediately upon connection.

Target Audience: Android & iOS Engineering Teams.

---

2. Protocol Constants

2.1 UUIDs

All Bitchat BLE operations use the following 128-bit UUIDs.

Name	UUID	Usage
Service UUID	F47B5E2D-4A9E-4C5A-9B3F-8E1D2C3A4B5C	The main Bitchat Mesh Service.
Data Characteristic	A1B2C3D4-E5F6-4A5B-8C9D-0E1F2A3B4C5D	Main channel for BitchatPacket transfer (Notify/Write).
Identity Characteristic	A1B2C3D4-E5F6-4A5B-8C9D-0E1F2A3B4C5E	(NEW) For clients to signal identity (Write/WriteNr).

2.2 Data Formats

• Peer ID Truncation: For BLE signaling, the full 64-char hex Peer ID is truncated to the first 8 bytes (16 hex characters).
• Byte Order: Big-Endian (Network Byte Order).

---

3. Passive Signaling (Advertisements)

Already implemented on Android and iOS.

When acting as a Peripheral (Server), the node MUST include its truncated Peer ID in the Scan Response packet.

• Data Type: Service Data (0x16)
• UUID: F47B5E2D-4A9E-4C5A-9B3F-8E1D2C3A4B5C (16-bit or 128-bit representation depending on space)
• Payload: First 8 bytes of Peer ID.

Behavior:

• Scanners (Clients) can map the ephemeral MAC address to this Peer ID before connecting.
• If the Scanner is already connected to this Peer ID (via a different MAC), it MUST NOT initiate a new connection.

---

4. Active Signaling (Identity Characteristic)

New implementation requirement.

When acting as a Central (Client), the node cannot advertise its ID to the Server if the Server is not scanning. Therefore, the Client MUST write its identity to the Server immediately after connection establishment.

4.1 Client Implementation Spec

1. Connect to the Peripheral.
2. Discover Services.
3. Check for the existence of Identity Characteristic (...C5E).
4. Action: If present, write the local truncated Peer ID (8 bytes) to this characteristic.
   • Write Type: WRITE_TYPE_NO_RESPONSE (preferred for speed) or WRITE_TYPE_DEFAULT.
5. Timing: This MUST be the first action after service discovery, before enabling notifications on the Data Characteristic.

Android Reference (Client)

// In onServicesDiscovered()
val identityChar = service.getCharacteristic(IDENTITY_CHARACTERISTIC_UUID)
if (identityChar != null) {
    // 1. Prepare 8-byte ID
    val idBytes = myPeerID.chunked(2).map { it.toInt(16).toByte() }
        .toByteArray().take(8).toByteArray()
    
    // 2. Write to characteristic
    identityChar.value = idBytes
    identityChar.writeType = BluetoothGattCharacteristic.WRITE_TYPE_NO_RESPONSE
    gatt.writeCharacteristic(identityChar)
}

4.2 Server Implementation Spec

1. Add Characteristic: The GATT Server MUST include the Identity Characteristic in its service definition.
   • Properties: Write | Write No Response
   • Permissions: Write
2. Handle Write Request: When a write request is received on this UUID:
   • Extract the 8-byte Peer ID.
   • Bind the identity to the current connection handle (MAC address).
   • Execute Deduplication Policy (see Section 5).

Android Reference (Server)

// In onCharacteristicWriteRequest()
if (characteristic.uuid == IDENTITY_CHARACTERISTIC_UUID) {
    val peerID = value.joinToString("") { "%02x".format(it) }
    
    // 1. Update internal mapping (MAC -> PeerID)
    connectionTracker.setDevicePeerID(device.address, peerID)
    
    // 2. Deduplication Check
    val duplicate = connectionTracker.getConnectedDevices().values.firstOrNull { 
        it.peerID == peerID && it.device.address != device.address 
    }
    
    if (duplicate != null) {
        // Peer is already connected via a different MAC
        Log.w(TAG, "Deduplication: Rejecting new connection from $peerID")
        
        // Respond success to complete the transaction gracefully
        if (responseNeeded) {
             gattServer.sendResponse(device, requestId, GATT_SUCCESS, 0, null)
        }
        
        // Terminate the NEW connection
        gattServer.cancelConnection(device)
        return
    }
}

---

5. Deduplication Policy

The goal is to allow only one logical connection between any two peers, regardless of direction (Client/Server) or MAC address rotation.

5.1 Rules

1. Peer ID Primacy: The persistent Peer ID is the source of truth, not the MAC address.
2. First-Come-First-Served: The existing stable connection is preferred. A new incoming connection attempting to claim the same Peer ID will be rejected.
3. Cross-Role Deduplication:
   • If Node A is connected to Node B (A=Client, B=Server).
   • And Node B tries to connect to Node A (B=Client, A=Server).
   • If both sides identify correctly, one link is redundant.
   • Current Policy: Bitchat currently treats dual-direction links as acceptable but suboptimal. However, strict deduplication via Active Signaling will treat the second link as a duplicate if the application layer maps them to the same ID.
   • Strict Mode (Recommended): If PeerID_X is connected as a client, do NOT accept PeerID_X as a server.

5.2 Conflict Resolution Flow

1. New Connection (Incoming): Device AA:BB:CC connects.
2. Identity Signal: Device writes ID 12345678.
3. Lookup: Server checks list of other active connections.
   • Is 12345678 connected via DD:EE:FF?
4. Decision:
   • Yes: Disconnect AA:BB:CC immediately. (Keep the old, stable link).
   • No: Accept AA:BB:CC and update the map.

---

6. iOS Implementation Notes

Swift Implementation Guidance

The iOS CoreBluetooth implementation should mirror the logic above.

CBPeripheralManagerDelegate: In didReceiveWrite requests:

func peripheralManager(_ peripheral: CBPeripheralManager, didReceiveWrite requests: [CBATTRequest]) {
    for request in requests {
        if request.characteristic.uuid == CBUUID(string: "A1B2C3D4-E5F6-4A5B-8C9D-0E1F2A3B4C5E") {
            let peerData = request.value
            // 1. Parse PeerID
            // 2. Check Connection Manager for existing PeerID
            // 3. If duplicate, cancel connection:
            //    peripheralManager.respond(to: request, withResult: .success)
            //    // Wait briefly or disconnect immediately?
            //    // CBCentralManager usually handles disconnects, but as a Peripheral, 
            //    // you simply stop processing. To force disconnect, you might need 
            //    // to let the Central handle the rejection or implement app-layer timeout.
            //    // NOTE: iOS Peripheral cannot force-disconnect a Central easily.
            //    // Alternative: Send an app-layer "Disconnect" packet or error response.
        }
    }
}

Note on iOS Peripheral Disconnects: Unlike Android, iOS CBPeripheralManager does not have a direct cancelConnection for a specific central.

• Strategy: If a duplicate is detected, the iOS Peripheral should respond with a custom GATT Error (if possible) or simply ignore further data requests, causing the Central (if Bitchat) to timeout.
• Preferred Strategy: The Android/iOS Client (Central) is the one that typically manages the connection lifecycle. If the Server detects a duplicate, it could write a specific "Go Away" code to the characteristic or simply refuse to process further packets.
• Protocol Refinement: If the Server responds with GATT_SUCCESS, the Client assumes it's accepted. If the Server responds with an error (e.g., CBATTError.insufficientResources or a custom code), the Client should disconnect itself.

Refined Server Logic (Cross-Platform): If the Server detects a duplicate:

1. Respond to the Write Request with GATT_SUCCESS (to satisfy the protocol).
2. Internally flag this CBCentral as "Rejected".
3. Ignore any subsequent data writes from this Central.
4. (Optional) If the Central subscribes to the Data Characteristic, send a single "Disconnect Command" packet and then stop notifying.

Android Compliance

The Android implementation provided in the Reference section uses gattServer.cancelConnection(device), which effectively terminates the link. iOS devices acting as Clients will see this as a disconnection and should handle it gracefully (auto-retry logic should respect the fact that it might be a purposeful disconnect, but standard backoff applies).