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

> Master BitChat's gossip system sync configuration. Discover essential parameters in TransportConfig.swift to optimize network efficiency and message propagation speed. Get the complete guide now.

- Repository: [permissionlesstech/bitchat](https://github.com/permissionlesstech/bitchat)
- Tags: how-to-guide
- Published: 2026-08-23

---

**TLDR;** All tunable knobs for BitChat's gossip synchronization are centralized in [`TransportConfig.swift`](https://github.com/permissionlesstech/bitchat/blob/main/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`](https://github.com/permissionlesstech/bitchat/blob/main/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`](https://github.com/permissionlesstech/bitchat/blob/main/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`](https://github.com/permissionlesstech/bitchat/blob/main/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`](https://github.com/permissionlesstech/bitchat/blob/main/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

```swift
// 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()

```

```swift
// 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
}

```

```swift
// 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`](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Services/TransportConfig.swift), with additional rate-limiting logic in [`bitchat/Sync/SyncResponseRateLimiter.swift`](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Sync/SyncResponseRateLimiter.swift) and persistence handling in [`bitchat/Sync/GossipMessageArchive.swift`](https://github.com/permissionlesstech/bitchat/blob/main/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`](https://github.com/permissionlesstech/bitchat/blob/main/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.