Protocol

How devices discover each other, establish trust, and exchange messages.

1. Enrollment

Recovery

16-word mnemonic phrase (BIP-39 style) encodes the salt. With the same PRF output + PIN + salt, identical keys are derived. The mnemonic does NOT contain the PRF output -- the passkey authenticator is still required.

2. Pairing (Emoji Link)

3. Message Delivery

Relay path (always available)

Group message path

Generate random AES-256 session key. Encrypt plaintext once with AES-GCM. For each group member: seal the (groupId + sessionKey + ciphertext) individually. Publish N sealed events (one per member). Each member decrypts their event, extracts session key, decrypts message.

4. Voice / Video Calls

1:1 Call Signaling

Group Call (Mesh)

• Each pair of participants has an independent RTCPeerConnection
• Audio from all peers mixed via AudioContext to a single output
• Signaling: kind 25100 sealed events, one per peer pair
• Max ~6 participants (mesh bandwidth limit)

5. Identity Merging

One person may use multiple devices, each with different keys. Users can manually merge contacts that represent the same person.

Aspect	Behavior
Storage	merged_contacts IndexedDB store: { mergedId, displayName, deviceKeys }
Contact list	One entry per merged identity
Chat view	Messages from all device keys, merge-sorted by time
Sending	Encrypts and delivers to all device keys independently
Unread counts	Aggregated across all device keys

6. Relay List

Default relays (hardcoded, used on first connection):

wss://relay.damus.io
wss://nos.lol
wss://relay.snort.social
wss://nostr.wine
wss://relay.nostr.band
... (21+ relays for redundancy)

The relay manager connects to all relays in parallel, publishes to all, and subscribes on all. Messages are deduplicated by event ID.

7. Offline Behavior

• Service Worker caches all static assets (HTML, JS, WASM)
• App works fully offline for local operations (read messages, browse contacts)
• Messages queued while offline are NOT automatically retried (no outbox)
• Relay reconnection uses exponential backoff (1s, 2s, 4s, ... up to 30s)
• PWA installable on all platforms (manifest.json)

8. Nostr Event Lifecycle

Event created:
  -> JSON serialized
  -> ID = SHA-256(serialized [0, pubkey, created_at, kind, tags, content])
  -> Signature = BIP-340 Schnorr sign(private_key, ID)
  -> Published: ["EVENT", signed_event_json]

Event received:
  -> Verify ID matches SHA-256 of serialized fields
  -> Verify BIP-340 signature
  -> Route by kind to appropriate handler
  -> For kind 1059: attempt decryption with known contacts

BINARY WIRE PROTOCOL

All internal messages can be encoded as bitpacked binary for BLE transport (20-244 byte MTU). Header byte: [VV][TTTTTT] — 2-bit version, 6-bit type. Backward compatible: first byte 0x7B ({) = legacy JSON.

Size comparison

Message	JSON	Binary	Savings
Text "hello"	80 B	19 B	76%
Reaction	80 B	10 B	88%
Chess move	55 B	3 B	95%
Location	100 B	15 B	85%
Ping	40 B	2 B	95%
Sketch (10 pts)	150 B	30 B	80%

Dictionary compression

Optional per-message. Marker 0x01 + 1 byte = word index (128 common English words). Marker 0x02 + 1 byte = emoji index (256 emoji). Raw UTF-8 passes through unchanged. Dictionary frozen per protocol version.

Reply-to-message

Type 0x02: includes 8-byte reference to original message + up to 64 bytes quoted preview. Rendered as a quoted bar above the reply bubble. Tap to scroll to original.

REPLY-TO-MESSAGE

Long-press any message to open the action picker. Alongside reaction emoji, a reply button (↩) enters reply mode. The quoted message preview appears above the input field. Send attaches replyToId and replyToPreview to the message. Rendered as a bordered quote bar above the bubble text.

Protocol version 2. Subject to evolution. All changes will be documented.