Contact Discovery

QR Code Payload Structure:

zentalk://contact?
  addr=zk1qxy7f8h9j2k3m4n5p6q7r8s9t0u1v2w3x4y5z6
  &name=Alice
  &fp=37291847561928304857
  &v=1

https://zentalk.app/add/zk1qxy7f8h9j2k3m4n5p6q7r8s9t0u1v2w3x4y5z6

Username Registration Flow:

1. User selects username: "alice_z"
2. Client creates registration message:
   {
     username: "alice_z",
     wallet_address: "zk1...",
     timestamp: 1704067200,
     signature: sign(identity_key, username || address || timestamp)
   }
3. Submit to DHT with key = hash("zentalk:username:" || "alice_z")
4. DHT stores mapping, verifiable by anyone

Simplified PSI Protocol:

Client:
  1. contacts = ["alice@email.com", "bob@email.com", ...]
  2. hashed_contacts = [H(c || client_salt) for c in contacts]
  3. blind hashed_contacts with random values
  4. send blinded_hashes to server

Server:
  1. users = [all registered user identifiers]
  2. hashed_users = [H(u || server_salt) for u in users]
  3. perform PSI computation on blinded_hashes
  4. return blinded results

Client:
  1. unblind results
  2. compare with own hashed_contacts
  3. matches = contacts that are Zentalk users

QR Code Parsing:

INPUT: Camera captures QR code image
OUTPUT: Contact information structure

1. Decode QR code to string
2. Parse URI: zentalk://contact?addr=...&name=...&fp=...
3. Validate wallet address format
4. Validate fingerprint format (if present)
5. Display to user for confirmation

Address Validation:

FUNCTION validate_zentalk_address(address):
    IF NOT address.startswith("zk1"):
        RETURN error("Invalid prefix")

    IF length(address) != 42:
        RETURN error("Invalid length")

    IF NOT bech32_checksum_valid(address):
        RETURN error("Checksum failed")

    IF NOT all_valid_bech32_chars(address):
        RETURN error("Invalid characters")

    RETURN success

Verification Prompt Flow:

WHEN user sends first message to unverified contact:
    SHOW dialog:
        "You haven't verified [Contact Name]'s identity.

        For sensitive conversations, compare safety numbers
        in person or via a trusted channel.

        [Verify Now]  [Send Anyway]  [Cancel]"

Contact Request Wire Format:

+--------+----------------+-------------+-------------+
| type   | sender_address | sender_name | message     |
| 1 byte | 32 bytes       | var (≤64)   | var (≤256)  |
+--------+----------------+-------------+-------------+
| timestamp | pow_nonce | signature                    |
| 8 bytes   | 8 bytes   | 64 bytes                     |
+------------------+------------------------------------+

Proof-of-Work Verification:

FUNCTION verify_contact_request_pow(request):
    challenge = hash(
        request.sender_address ||
        request.recipient_address ||
        request.timestamp ||
        request.pow_nonce
    )

    // Check for 20 leading zero bits
    IF leading_zeros(challenge) ≥ 20:
        RETURN valid
    ELSE:
        RETURN invalid

Request Lifecycle:

1. Sender creates request with timestamp T
2. Request encrypted and sent via mesh network
3. Recipient's device stores in pending queue
4. After 7 days: request auto-deleted if not acted upon
5. No notification to sender (prevents existence confirmation)

Safety Number Derivation:

FUNCTION generate_safety_number(my_identity_key, their_identity_key):
    // Sort keys for consistency (both parties see same number)
    IF my_identity_key < their_identity_key:
        combined = my_identity_key || their_identity_key
    ELSE:
        combined = their_identity_key || my_identity_key

    // Derive safety number
    hash = SHA-256(combined || "ZentalkSafetyNumber")

    // Format as readable number
    safety_number = format_as_numeric_blocks(hash)

    RETURN safety_number  // e.g., "37291 84756 19283 04857 29184 73829"

QR Verification Process:

ALICE'S DEVICE:
    qr_content = {
        identity_key: alice_identity_public_key,
        safety_number: compute_safety_number(alice, bob),
        timestamp: current_time(),
        signature: sign(alice_identity_private_key, above_fields)
    }
    DISPLAY qr_code(qr_content)

BOB'S DEVICE:
    scanned = scan_qr_code()
    VERIFY signature with scanned.identity_key
    VERIFY safety_number matches locally computed value
    VERIFY timestamp is recent (within 5 minutes)
    IF all valid:
        MARK alice as verified
        DISPLAY "Verification successful"

Key Change Warning Dialog:

"Security Alert: [Contact Name]'s identity key has changed.

This could mean:
- They reinstalled Zentalk
- They switched to a new device
- They restored from backup
- Someone is intercepting your messages

Your previous verification is no longer valid.

[View New Safety Number]  [Block Contact]  [Continue Unverified]"

Contact Storage Encryption:

FUNCTION store_contact(contact, metadata_storage_key):
    // Derive per-contact key
    contact_key = HKDF(
        ikm = metadata_storage_key,
        salt = contact.contact_id,
        info = "zentalk-contact-encrypt"
    )

    // Encrypt sensitive fields
    encrypted_data = AES_GCM_Encrypt(
        key = contact_key,
        plaintext = serialize(
            wallet_address,
            display_name,
            nickname,
            notes,
            identity_key,
            verified_at
        ),
        aad = contact.contact_id
    )

    // Store with plaintext indexes
    IndexedDB.put("contacts", {
        contact_id: contact.contact_id,
        added_at: contact.added_at,
        last_message_at: contact.last_message_at,
        address_hash: hash(contact.wallet_address),
        encrypted_data: encrypted_data
    })

Contact Sync Protocol:

DEVICE A (source):
    1. Add new contact locally
    2. Encrypt contact with user's storage key
    3. Create sync record:
       {
         type: "contact_add",
         encrypted_contact: ...,
         timestamp: ...,
         device_id: device_a_id
       }
    4. Sign with device key
    5. Upload to mesh storage at user's sync location

DEVICE B (destination):
    1. Poll sync location for new records
    2. Verify signature from known device
    3. Decrypt contact with storage key
    4. Add to local database
    5. Acknowledge sync (prevent re-download)

Block Implementation:

FUNCTION block_contact(wallet_address):
    // Add to local block list
    blocked_list = get_blocked_list()
    blocked_list.add({
        address: wallet_address,
        blocked_at: current_time(),
        reason: user_provided_reason  // Optional, local only
    })
    save_blocked_list(blocked_list)

    // Clear any pending messages/requests
    delete_pending_from(wallet_address)

    // No network communication - purely local

FUNCTION on_message_received(message):
    IF sender_address IN blocked_list:
        DISCARD message silently
        RETURN

    // Process message normally
    ...

Report Submission Flow:

1. User selects "Report" on message/contact
2. Choose report category
3. Optionally add description
4. Optionally include message evidence
5. Choose anonymous or identified report
6. Encrypt report with community moderator keys
7. Submit via 3-hop relay (hide reporter IP)
8. Moderators review (decentralized moderation)

Organization Storage:

// Groups stored separately from contacts
groups_table = {
    group_id: uuid,
    name: encrypted_string,
    description: encrypted_string,
    created_at: timestamp,
    parent_group_id: nullable uuid
}

// Membership is a separate table
group_membership = {
    group_id: uuid,
    contact_id: uuid,
    added_at: timestamp
}

// Labels stored similarly
labels_table = {
    label_id: uuid,
    name: encrypted_string,
    color: string  // Not sensitive
}

contact_labels = {
    contact_id: uuid,
    label_id: uuid,
    applied_at: timestamp
}

Complete Contact Addition Flow:

1. DISCOVERY
   - Scan QR code, OR
   - Enter wallet address manually, OR
   - Search username (if registered)

2. VALIDATION
   - Verify address format
   - Check not already in contacts
   - Check not in block list

3. KEY RETRIEVAL
   - Query DHT for contact's key bundle
   - Retrieve identity key, signed pre-key, one-time pre-keys
   - Verify key bundle signatures

4. CONTACT REQUEST
   - Generate proof-of-work
   - Create contact request message
   - Encrypt with X3DH
   - Send via 3-hop relay

5. RECIPIENT PROCESSING
   - Receive contact request
   - Verify PoW
   - Display to user for action

6. ACCEPTANCE
   - User accepts request
   - Contact added to encrypted local storage
   - Notify sender of acceptance

7. VERIFICATION (optional)
   - Compare safety numbers
   - QR code verification
   - Mark as verified

8. SYNC
   - Encrypt contact data
   - Upload to mesh storage
   - Sync to other devices