Private groups in Bitchat let a small set of mesh peers share a dedicated encrypted chat room without revealing messages to the broader network. Groups are a Bluetooth mesh feature — all members must have been seen on mesh at some point — and they work entirely offline.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/permissionlesstech/bitchat/llms.txt
Use this file to discover all available pages before exploring further.
How Groups Work
A group is a named conversation secured with a 32-byte ChaCha20-Poly1305 symmetric key that only current members hold. The key lives in the system Keychain, never on disk in plaintext. Each message is encrypted with the current group key, signed by the sender’s Ed25519 key, and broadcast over the mesh as agroupMessage packet (type 0x25). Relaying nodes see only the 16-byte group ID, the key epoch, and the encrypted payload — they cannot read content or identify senders.
Groups have a hard cap of 16 members including the creator.
Creating a Group
Create the group
Type Bitchat generates a random 16-byte group ID and a random 32-byte symmetric key, starts you as the sole member at epoch 1, and stores both in the Keychain.
/group create <name> in the composer and send.Invite members
With the group chat open, invite peers by name:Bitchat sends a signed
groupInvite packet to each invitee over their Noise session. The invite contains the group name, member roster, the current epoch key, and your creator signature. The invitee’s device verifies your signature before accepting.Managing Membership
Only the group creator can invite and remove members./group invite @nickname
/group invite @nickname
Sends a creator-signed group state packet to the named peer over their Noise session. The packet contains the full roster, the current epoch key, and a signature covering the group ID, epoch, key hash, roster hash, and group name.The invitee stores the key in their Keychain and the roster metadata in Application Support.
/group remove @nickname
/group remove @nickname
Removes a member from the group. Because the removed member previously held the group key, Bitchat rotates the key on removal: the epoch counter increments, a new 32-byte key is generated, and the updated group state is sent to every remaining member over their individual Noise sessions.After rotation, the removed peer cannot decrypt new messages even if they replay the mesh traffic.
/group leave
/group leave
Leave the current group. Your local copy of the key and roster is deleted. If you are the creator, the group continues for remaining members but nobody can issue further invites or removals until a successor is implemented (creator-only group management is a v1 constraint).
/group list
/group list
Lists all groups you are currently a member of, with their names and member counts.
Encryption Details
Group messages use a layered crypto scheme designed so intermediate mesh nodes learn nothing about group membership or content.- Message encryption
- Group state (invites & key updates)
- Key storage
Each message is sealed with the current epoch key (ChaCha20-Poly1305). The additional authenticated data (AAD) binds the group ID and epoch to the ciphertext, so a ciphertext from one epoch cannot be replayed as valid under a different epoch key.The plaintext inner payload also carries an Ed25519 sender signature covering the group ID, epoch, message ID, timestamp, and content. Recipients verify this signature against the sender’s signing key pinned in the group roster.Only the group ID, epoch, and 12-byte nonce are visible to the mesh — everything else is ciphertext.
Key Epoch
Theepoch counter is a UInt32 that starts at 1 and increments by 1 each time a member is removed and the key is rotated. Messages are bound to the epoch under which they were sealed — the epoch is both covered by the AEAD additional data and embedded in the signed inner payload — so a current member cannot replay a decrypted message under a later epoch key (the signature would fail verification at the new epoch).
Persistence and Panic Wipe
Group state persists across app restarts:- Keys survive in the Keychain; metadata survives on disk.
- At startup, only groups with a matching Keychain key are loaded — stale metadata without a key is silently discarded.
- A panic wipe (triple-tap the logo) deletes every group key from the Keychain and removes the groups JSON file. All group conversations become unreadable immediately.