Sync Configuration Parameters for BitChat's Gossip System: Complete Guide

TLDR; All tunable knobs for BitChat's gossip synchronization are centralized in TransportConfig.swift within the bitchat/Services package, with defaults ranging from a 2-second startup delay to 6-hour archive retention, consumed by GossipSyncManager to balance network efficiency against message propagation speed.

BitChat uses a gossip protocol to mesh public messages, pre-key bundles, and topology updates across decentralized devices. Understanding these sync configuration parameters allows developers to optimize bandwidth consumption and ensure reliable message delivery across intermittent network partitions according to the permissionlesstech/bitchat source code.

Core Timing Parameters in TransportConfig.swift

The primary timing controls defined in bitchat/Services/TransportConfig.swift regulate when and how frequently synchronization occurs.

gossipSyncInitialDelay

Located at line 226, the gossipSyncInitialDelay parameter specifies how long the application waits after launch before reading the persisted gossip archive. This prevents a burst of sync traffic immediately after startup. The default value is 2 seconds.

gossipSyncRoundInterval

As implemented at line 403, gossipSyncRoundInterval sets the cadence for regular gossip-sync rounds that publish the device's own bundles. This modest cadence defaults to 5 seconds, keeping the network fresh without flooding peers.

Bandwidth and Peer Limits

These parameters prevent network congestion by limiting the scope of each synchronization round.

gossipSyncMaxPeersPerRound

Defined at line 410, gossipSyncMaxPeersPerRound establishes an upper bound of 12 peers per sync round. This limits the bandwidth consumed during each synchronization cycle.

gossipSyncBundleCadence

Also referenced around lines 410-415, the gossipSyncBundleCadence parameter enforces a minimum interval of 30 seconds between re-gossiping changed pre-key bundles. The GossipSyncManager only pushes a bundle again when the generatedAt timestamp is newer than the stored archive copy.

Persistence Configuration

Long-term storage settings ensure gossip state survives application restarts and temporary mesh partitions.

gossipArchivePath and gossipArchiveRetention

The GossipMessageArchive class persists data to the path defined by gossipArchivePath, defaulting to ApplicationSupport/gossip-archive.json. The gossipArchiveRetention parameter, documented in the privacy assessment, retains messages for 21,600 seconds (6 hours), allowing sync to survive mesh partitions after device restarts.

Rate Limiting and Safety Controls

These safeguards protect against denial-of-service and provide operational kill switches.

gossipSyncRateLimit

Implemented in bitchat/Sync/SyncResponseRateLimiter.swift, this rate limiter caps inbound public-message batch requests at 1 request per second, protecting against replay-storm attacks.

gossipSyncEnabled

A master boolean switch defined in TransportConfig.swift, gossipSyncEnabled defaults to true but can disable all gossip networking for test harnesses or controlled deployments.

GossipSyncManager Implementation Flow

The GossipSyncManager class orchestrates the synchronization process using these parameters from the configuration:

1. On startup, it respects gossipSyncInitialDelay before loading the persisted archive from GossipMessageArchive.

2. Every gossipSyncRoundInterval, it constructs a sync packet targeting up to gossipSyncMaxPeersPerRound peers.

3. The packet includes the device's pre-key bundle only if the last broadcast exceeds gossipSyncBundleCadence.

4. Incoming packets pass through SyncResponseRateLimiter to enforce the rate limit.

5. Newly seen public messages persist back to the archive, subject to gossipArchiveRetention.

Runtime Configuration Examples

// Customizing gossip sync settings via TransportConfig.Builder
let config = TransportConfig.Builder()
    .setGossipSyncInitialDelay(seconds: 3)          // Longer startup delay
    .setGossipSyncRoundInterval(seconds: 4)          // Faster sync rounds
    .setGossipSyncMaxPeersPerRound(8)                // Reduced peer count
    .setGossipSyncBundleCadence(seconds: 20)         // More frequent bundle updates
    .setGossipArchiveRetention(seconds: 12 * 60 * 60) // 12-hour retention
    .build()

// Inspecting active parameters at runtime
if let manager = bleService.gossipSyncManager {
    print("Current round interval:", manager.roundInterval)       // → 5 s
    print("Max peers per round:", manager.maxPeersPerRound)     // → 12
    print("Archive path:", manager.archive.fileURL.path)         // → …/gossip-archive.json
}

// Disabling gossip sync for unit testing
let testConfig = TransportConfig.Builder()
    .setGossipSyncEnabled(false)   // Turn off all gossip networking
    .build()

Summary

• TransportConfig.swift centralizes all gossip sync parameters including delays, intervals, and peer limits
• Default values balance responsiveness (5-second rounds) with efficiency (12 peers max, 30-second bundle cadence)
• 6-hour archive retention enables recovery from mesh partitions after device restarts
• Rate limiting at 1 request/second prevents replay attacks
• Boolean gossipSyncEnabled provides a kill switch for testing environments

Frequently Asked Questions

Where are BitChat's gossip sync parameters defined?

All parameters reside in bitchat/Services/TransportConfig.swift, with additional rate-limiting logic in bitchat/Sync/SyncResponseRateLimiter.swift and persistence handling in bitchat/Sync/GossipMessageArchive.swift.

What is the default gossip sync interval in BitChat?

The gossipSyncRoundInterval defaults to 5 seconds as defined at line 403 of TransportConfig.swift, ensuring regular updates without network flooding.

How long does BitChat retain gossip messages for synchronization?

Messages persist for 6 hours (21,600 seconds) according to the gossipArchiveRetention parameter, allowing devices to rejoin mesh partitions and synchronize missed messages.

Can I disable gossip sync entirely for testing?

Yes. Set gossipSyncEnabled to false using TransportConfig.Builder().setGossipSyncEnabled(false) to completely disable gossip networking in test harnesses or controlled deployments.

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