bitchat/docs/GeohashPresenceSpec.md

Geohash Presence Specification

Overview

The Geohash Presence feature provides a mechanism to track online participants in geohash-based location channels. It uses a dedicated ephemeral Nostr event kind to broadcast "heartbeats," ensuring accurate and privacy-preserving online counts.

Nostr Protocol

Event Kind

A new ephemeral event kind is defined for presence heartbeats:

• Kind: 20001 (GEOHASH_PRESENCE)
• Type: Ephemeral (not stored by relays long-term)

Event Structure

The presence event mimics the structure of a geohash chat message (Kind 20000) but without content or nickname metadata, to minimize overhead and focus purely on "liveness".

{
  "kind": 20001,
  "created_at": <timestamp>,
  "tags": [
    ["g", "<geohash>"]
  ],
  "content": "",
  "pubkey": "<geohash_derived_pubkey>",
  "id": "<event_id>",
  "sig": "<signature>"
}

• content: Must be empty string.
• tags: Must include ["g", "<geohash>"]. Should NOT include ["n", "<nickname>"].
• pubkey: The ephemeral identity derived specifically for this geohash (same as used for chat messages).

Client Behavior

1. Broadcasting Presence

Clients MUST broadcast a Kind 20001 presence event globally when the app is open, regardless of which screen the user is viewing.

• Global Heartbeat:
  • Trigger: Application start / initialization, or whenever location (available geohashes) changes.
  • Frequency: Randomized loop interval between 40s and 80s (average 60s).
  • Scope: Sent to all geohash channels corresponding to the device's current physical location.
  • Privacy Restriction: Presence MUST ONLY be broadcast to low-precision geohash levels to protect user privacy. Specifically:
    • Allowed: REGION (precision 2), PROVINCE (precision 4), CITY (precision 5).
    • Denied: NEIGHBORHOOD (precision 6), BLOCK (precision 7), BUILDING (precision 8+).
  • Decorrelation: Individual broadcasts within a heartbeat loop must be separated by random delays (e.g., 2-5 seconds) to prevent temporal correlation of public keys across different geohash levels. The main loop delay is adjusted to maintain the target average cadence.

2. Subscribing to Presence

Clients must update their Nostr filters to listen for both chat and presence events on geohash channels.

• Filter:
  • kinds: [20000, 20001]
  • #g: ["<geohash>"]

3. Participant Counting

The "online participants" count shown in the UI aggregates unique public keys from both presence heartbeats and active chat messages.

• Logic:
  • Maintain a map of pubkey -> last_seen_timestamp for each geohash.
  • Update last_seen_timestamp upon receiving a valid Kind 20001 (Presence) OR Kind 20000 (Chat) event.
  • A participant is considered "online" if their last_seen_timestamp is within the last 5 minutes.

4. UI Presentation

The presentation of the participant count depends on the geohash precision level and data availability.

• Standard Display: For channels where presence is broadcast (Region, Province, City) OR any channel where at least one participant has been detected, show the exact count: [N people].
• High-Precision Uncertainty: For high-precision channels (Neighborhood, Block, Building) where:
  • Presence broadcasting is disabled (privacy restriction).
  • AND the detected participant count is 0.
  • Display: [? people]
  • Reasoning: Since clients don't announce themselves in these channels, a count of "0" is misleading (people could be lurking).

5. Implementation Details (Android Reference)

• NostrKind.GEOHASH_PRESENCE: Added constant 20001.
• NostrProtocol.createGeohashPresenceEvent: Helper to generate the event.
• GeohashViewModel:
  • startGlobalPresenceHeartbeat(): Coroutine that collectLatest on LocationChannelManager.availableChannels.
  • Implements randomized loop logic (40-80s) and per-broadcast random delays (2-5s).
  • Filters channels by precision <= 5 before broadcasting.
• GeohashMessageHandler:
  • Refactored onEvent to update participant counts for both Kind 20000 and 20001.
• LocationChannelsSheet:
  • Implements the [? people] display logic for high-precision, zero-count channels.

Benefits

• Accuracy: Counts reflect both active listeners (via heartbeats) and active speakers (via messages).
• Privacy: High-precision location presence is NOT broadcast. Temporal correlation between different levels is obfuscated via random delays.
• Consistency: "Online" status is maintained globally while the app is open.
• Transparency: The UI correctly reflects uncertainty (?) when privacy rules prevent accurate passive counting.