This document describes the data models representing peers and identities in BitChat. It covers the structure of PeerID, BitchatPeer, and the multi-layered identity system used for mesh and Nostr communication. This page details how the system bridges raw transport identifiers to user-facing social identities. For protocol-level message structures, see 8.1 Message and Packet Models For cryptographic handshakes and sessions, see 4.1 Noise Protocol Framework
The PeerID structure is the primary identifier for participants across the BitChat network. It abstracts over different ID formats used by Bluetooth mesh and Nostr transports, providing a unified interface for routing and lookup. localPackages/BitFoundation/Sources/BitFoundation/PeerID.swift12-52
BitChat uses several distinct types of peer IDs, distinguished by prefixes and lengths.
Title: "PeerID Architecture and Constructors"
Sources: localPackages/BitFoundation/Sources/BitFoundation/PeerID.swift24-44 localPackages/BitFoundation/Sources/BitFoundation/PeerID.swift63-143 localPackages/BitFoundation/Sources/BitFoundation/PeerID.swift191-202 localPackages/BitFoundation/Sources/BitFoundation/PeerID.swift208-222
| ID Type | Prefix | Bare Length | Purpose |
|---|---|---|---|
| Mesh ID | mesh: | Variable | Bluetooth mesh routing and neighbor discovery. localPackages/BitFoundation/Sources/BitFoundation/PeerID.swift28 |
| Noise ID | noise: | 64 hex | Full Noise static public key representation. localPackages/BitFoundation/Sources/BitFoundation/PeerID.swift31 |
| GeoDM ID | nostr_ | 16 hex | NIP-17 direct messaging identifier (first 16 chars of pubkey). localPackages/BitFoundation/Sources/BitFoundation/PeerID.swift34 |
| GeoChat ID | nostr: | 8 hex | Geohash public channel display ID (first 8 chars of pubkey). localPackages/BitFoundation/Sources/BitFoundation/PeerID.swift36 |
| Group ID | group_ | 32 hex | Virtual conversation ID for private groups. localPackages/BitFoundation/Sources/BitFoundation/PeerID.swift39 |
| Bridge ID | bridge: | 16 hex | Sender reached across a mesh bridge via Nostr. localPackages/BitFoundation/Sources/BitFoundation/PeerID.swift43 |
| Short ID | (none) | 16 hex | Stable 8-byte routing identifier (16 hex chars). localPackages/BitFoundation/Sources/BitFoundation/PeerID.swift21-133 |
The routingData property specifically extracts the 8-byte segment used by the binary protocol for addressing packets in the mesh. localPackages/BitFoundation/Sources/BitFoundation/PeerID.swift191-196
The BitchatPeer model is the primary data structure used by the UI and the UnifiedPeerService. It aggregates connectivity state, cryptographic keys, and social metadata. bitchat/Models/BitchatPeer.swift6-18
Title: "BitchatPeer State and Connectivity Ranking"
Sources: bitchat/Models/BitchatPeer.swift6-38 bitchat/Models/BitchatPeer.swift75-92
The connectionState property uses a priority-based evaluation to determine reachability:
.bluetoothConnected: Directly connected via BLE. bitchat/Models/BitchatPeer.swift28-29.meshReachable: Seen recently in the mesh but not directly connected. bitchat/Models/BitchatPeer.swift30-31.nostrAvailable: Offline from mesh, but reachable via Nostr because they are a mutual favorite. bitchat/Models/BitchatPeer.swift32-34.offline: No current path exists. bitchat/Models/BitchatPeer.swift35-37displayName: Returns nickname or the first 8 characters of the peerID. bitchat/Models/BitchatPeer.swift53-55statusIcon: Returns 📻 (mesh), 📡 (reachable), 🌐 (Nostr), or 🌙 (one-way favorite). bitchat/Models/BitchatPeer.swift57-72BitChat separates identity concerns into three distinct layers to preserve privacy while maintaining trust. bitchat/Identity/IdentityModels.swift16-22
Title: "Three-Layer Identity Mapping"
Sources: bitchat/Identity/IdentityModels.swift88-142 bitchat/Identity/SecureIdentityStateManager.swift154-156
Short-lived, rotatable PeerIDs that prevent long-term network tracking. bitchat/Identity/IdentityModels.swift26-30 bitchat/Identity/IdentityModels.swift90-92
The HandshakeState enum tracks Noise protocol progress:
.none: No handshake. bitchat/Identity/IdentityModels.swift95.initiated: Outgoing handshake started. bitchat/Identity/IdentityModels.swift96.inProgress: Exchange ongoing. bitchat/Identity/IdentityModels.swift97.completed(fingerprint: String): Successful handshake, revealing the stable cryptographic identity. bitchat/Identity/IdentityModels.swift98Stable anchor based on Noise Protocol static keys. The fingerprint (SHA256 of the public key) is the permanent identifier. bitchat/Identity/IdentityModels.swift32-36 bitchat/Identity/IdentityModels.swift104-110
fingerprint: SHA256 hash of publicKey. bitchat/Identity/IdentityModels.swift105publicKey: Noise static public key. bitchat/Identity/IdentityModels.swift106signingPublicKey: Ed25519 key for public message signatures. bitchat/Identity/IdentityModels.swift108Human-friendly attributes stored locally only. bitchat/Identity/IdentityModels.swift38-42 bitchat/Identity/IdentityModels.swift115-123
| Trust Level | Description |
|---|---|
unknown | New/unverified. bitchat/Identity/IdentityModels.swift135 |
casual | Basic interaction history. bitchat/Identity/IdentityModels.swift136 |
vouched | Transitively trusted via verified peers (derived at runtime). bitchat/Identity/IdentityModels.swift139 |
trusted | Explicitly trusted by user. bitchat/Identity/IdentityModels.swift140 |
verified | Cryptographic proof established. bitchat/Identity/IdentityModels.swift141 |
The IdentityCache is the persistent container for mappings. bitchat/Identity/IdentityModels.swift161
socialIdentities: fingerprint -> SocialIdentity. bitchat/Identity/IdentityModels.swift163nicknameIndex: Reverse index for nickname lookups. bitchat/Identity/IdentityModels.swift167verifiedFingerprints: Set of verified identities. bitchat/Identity/IdentityModels.swift170vouchesByVouchee: Records of transitive trust. bitchat/Identity/IdentityModels.swift184BitChat uses KeychainManager to persist identity keys and the encrypted IdentityCache. bitchat/Services/KeychainManager.swift14-30
kSecAttrAccessibleAfterFirstUnlock to allow the mesh to function while the phone is locked. bitchat/Services/KeychainManager.swift45-50Title: "Identity State Management Flow"
Sources: bitchat/Identity/SecureIdentityStateManager.swift100-143 bitchat/Services/KeychainManager.swift88-121
The isValid property ensures identifiers meet protocol requirements:
_ or - up to 63 characters. localPackages/BitFoundation/Sources/BitFoundation/PeerID.swift222-225Private groups are represented by virtual PeerIDs with the group_ prefix, derived from a 16-byte group ID. localPackages/BitFoundation/Sources/BitFoundation/PeerID.swift114-126 These are visualized in the UI via GroupChatList. bitchat/Views/GroupChatList.swift6-20
Sources: localPackages/BitFoundation/Sources/BitFoundation/PeerID.swift208-226 bitchat/Identity/IdentityModels.swift147-184 bitchat/Models/BitchatPeer.swift94-97
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.