Maximum Hop Count for Messages in the BitChat BLE Mesh Network

BitChat’s BLE mesh network enforces a hard limit of 7 hops for message relay, discarding any packet that would require more intermediate devices to reach its destination.

The BitChat open-source project implements a Bluetooth Low Energy (BLE) mesh that lets messages hop across nearby devices when direct links are unavailable. Understanding the maximum hop count for messages in the BitChat BLE mesh network is essential for developers building reliable relay logic and estimating delivery bounds in sparse networks. This limit is explicitly documented in the repository and validated by the routing test suite.

Where the 7-Hop Limit Is Documented

According to the BitChat source code, the README.md file lists the Multi-hop Relay feature with a clear ceiling: messages route through nearby devices up to a maximum of 7 hops. This documentation appears in the feature overview section of the repository, establishing the relay boundary that all routing algorithms must respect.

How BitChat Enforces the Maximum Hop Count

The project does not rely solely on documentation; the routing layer and its tests actively reject paths that would violate the threshold.

Routing Logic in BLEService

As implemented in permissionlesstech/bitchat, the mesh routing logic residing under /bitchat/Services/ applies the hop-count check when constructing viable paths. The tracker computes candidate routes with a maxHops parameter, and any path requiring more than seven intermediate traversals is filtered out before a packet is ever transmitted.

Unit Tests for the Hop Ceiling

The test suite in bitchatTests/Services/MeshTopologyTrackerTests.swift contains assertions that validate this behavior. Lines 131–139 verify that routes are rejected when they would exceed the allowed hop count, ensuring the 7-hop ceiling is respected across code changes.

Swift Code Example: Enforcing the Hop Limit Before Routing

Below is a practical Swift snippet illustrating how BitChat applies the hop ceiling when computing a message route:

// Attempt to compute a route with a hop limit
let maxAllowedHops = 7               // BitChat's hard-coded limit
let route = try tracker.computeRoute(
    from: sourceNode,
    to: destinationNode,
    maxHops: maxAllowedHops
)

// The route will be `nil` if it would require more than 7 hops
guard let viableRoute = route else {
    print("Message cannot be delivered – exceeds 7-hop limit")
    return
}

// Forward the packet along the computed path
meshEngine.sendPacket(packet, via: viableRoute)

In this pattern, tracker.computeRoute(from:to:maxHops:) returns nil when no valid path exists within the limit. The caller then abandons delivery rather than letting the packet expire unpredictably in the mesh.

Summary

• BitChat’s BLE mesh network supports multi-hop relay with a strict maximum of 7 hops per message.
• The README.md documents this limit in the feature list, while the routing implementation under /bitchat/Services/ enforces it at runtime.
• Unit tests in MeshTopologyTrackerTests.swift (lines 131–139) guard against regressions by rejecting routes that exceed the threshold.
• Application code should check for a nil route after calling computeRoute and handle the undeliverable packet gracefully.

Frequently Asked Questions

What is the maximum hop count for messages in the BitChat BLE mesh network?

BitChat supports a maximum of 7 hops. Any message that cannot reach its destination within seven intermediate relays is discarded rather than forwarded further.

How does BitChat enforce the 7-hop relay limit?

The enforcement happens in two places. The routing logic under /bitchat/Services/ caps path length via the maxHops parameter when calling computeRoute, preventing invalid paths from being selected. Additionally, the unit tests in MeshTopologyTrackerTests.swift verify that longer routes are rejected, which protects against regressions.

What happens if a message route exceeds 7 hops in BitChat?

When tracker.computeRoute(from:to:maxHops:) cannot find a path within the limit, it returns nil. The sender should treat this as a delivery failure and avoid transmitting the packet into the mesh. This prevents stale packets from circulating beyond the intended network boundary.

Where is the hop count limit documented in the BitChat source code?

The limit is documented in the repository’s README.md inside the Multi-hop Relay feature description. It is also codified in the routing tests at bitchatTests/Services/MeshTopologyTrackerTests.swift, which validate the threshold during continuous integration.

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