Vauchi DocsMessage Delivery Flow
Interaction Type: 🌐 REMOTE (Via Relay)
End-to-end message delivery from card update to acknowledgment.
Participants
- Alice - User sending card update
- Alice's Device - Source device
- Relay - WebSocket relay server
- Bob's Device - Recipient device
- Bob - Contact receiving update
Message Sizes & Frequency
| Message Type | Payload | Padded Size | Frequency |
|---|---|---|---|
| Card delta | 50-200 B | 256 B | 1-5/month |
| Full card | 500 B-2 KB | 1-4 KB | Initial only |
| Ack | 32-64 B | 256 B | Per message |
| Device sync | 100-500 B | 256 B-1 KB | Real-time |
Complete Delivery Flow
┌───────┐ ┌───────────────────┐ ┌───────────┐ ┌─────────────────┐ ┌─────┐
│ Alice │ │ Alice's Device 📱 │ │ Relay 🖥️ │ │ Bob's Device 📱 │ │ Bob │
└───┬───┘ └─────────┬─────────┘ └─────┬─────┘ └────────┬────────┘ └──┬──┘
│ │ │ │ │
│ Edit phone: "555-1111" → "555-2222" │ │ │ │
│────────────────────────────────────────▶ │ │ │
│ │ │ │ │
│ ├───┐ │ │ │
│ │ │ Update local card │ │ │
│ ◀───┘ │ │ │
│ │ │ │ │
│ ├───┐ │ │ │
│ │ │ Create CardDelta │ │ │
│ ◀───┘ │ │ │
│ │ │ │ │
│ │ ┌──────────────────────────────────────┐ │ │ │
│ │ │ Delta: ~100 bytes │ │ │ │
│ │ │ {"field":"phone","value":"555-2222"} │ │ │ │
│ │ └──────────────────────────────────────┘ │ │ │
│ │ │ │ │
│ ├───┐ │ │ │
│ │ │ Check visibility: Bob can see phone? ✓ │ │ │
│ ◀───┘ │ │ │
│ │ │ │ │
│ ├───┐ │ │ │
│ │ │ Ratchet send chain forward │ │ │
│ ◀───┘ │ │ │
│ │ │ │ │
│ │ ┌─────────────────────┐ │ │ │
│ │ │ Chain gen 42 → 43 │ │ │ │
│ │ │ Message key derived │ │ │ │
│ │ └─────────────────────┘ │ │ │
│ │ │ │ │
│ ├───┐ │ │ │
│ │ │ Encrypt delta (XChaCha20-Poly1305) │ │ │
│ ◀───┘ │ │ │
│ │ │ │ │
│ ├───┐ │ │ │
│ │ │ Pad to 256 bytes (bucket) │ │ │
│ ◀───┘ │ │ │
│ │ │ │ │
│ ├───┐ │ │ │
│ │ │ Generate CEK, sign payload │ │ │
│ ◀───┘ │ │ │
│ │ │ │ │
│ │ ┌───────────────────┐ │ │ │
│ │ │ Final: ~256 bytes │ │ │ │
│ │ │ (v0x02 format) │ │ │ │
│ │ └───────────────────┘ │ │ │
│ │ │ │ │
│ │ EncryptedUpdate(recipient=Bob, blob=...) │ │ │
│ │─────────────────────────────────────────────▶ │ │
│ │ │ │ │
│ │ ┌───────────────────────────────┐ │ │ │
│ │ │ WebSocket frame: │ │ │ │
│ │ │ 4-byte length + JSON envelope │ │ │ │
│ │ └───────────────────────────────┘ │ │ │
│ │ │ │ │
│ │ ├───┐ │ │
│ │ │ │ Validate recipient_id format │ │
│ │ ◀───┘ │ │
│ │ │ │ │
│ │ ├───┐ │ │
│ │ │ │ Check quota (blobs < 1000, storage < 50MB)│ │
│ │ ◀───┘ │ │
│ │ │ │ │
│ │ ├───┐ │ │
│ │ │ │ Store blob indexed by recipient_id │ │
│ │ ◀───┘ │ │
│ │ │ │ │
│ │ Acknowledgment(status=Stored) │ │ │
│ ◀╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌│ │ │
│ │ │ │ │
│ │ │ ┌──────────────────────────────┐ │ │
│ │ │ │ Blob stored with 120-day TTL │ │ │
│ │ │ └──────────────────────────────┘ │ │
│ │ │ │ │
│ ┌alt [Bob is Online (Connected to Relay)]─────────────────────────────────────────────────────────────────────────────────────────────┐
│ │ │ │ │ │ │
│ │ │ │ Forward EncryptedUpdate │ │ │
│ │ │ │╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌▶ │ │
│ │ │ │ │ │ │
│ │ │ │ ├───┐ │ │
│ │ │ │ │ │ Receive encrypted blob │ │
│ │ │ │ ◀───┘ │ │
│ │ │ │ │ │ │
│ │ │ │ ├───┐ │ │
│ │ │ │ │ │ Resolve anonymous sender ID │
│ │ │ │ ◀───┘ │ │
│ │ │ │ │ │ │
│ │ │ │ │ ┌────────────────────┐ │ │
│ │ │ │ │ │ Try each contact's │ │ │
│ │ │ │ │ │ shared key against │ │ │
│ │ │ │ │ │ anonymous_id │ │ │
│ │ │ │ │ └────────────────────┘ │ │
│ │ │ │ │ │ │
│ │ │ │ ├───┐ │ │
│ │ │ │ │ │ Found: Alice │ │
│ │ │ │ ◀───┘ │ │
│ │ │ │ │ │ │
│ │ │ │ ├───┐ │ │
│ │ │ │ │ │ Derive message key (chain gen │3)
│ │ │ │ ◀───┘ │ │
│ │ │ │ │ │ │
│ │ │ │ ├───┐ │ │
│ │ │ │ │ │ Decrypt payload │ │
│ │ │ │ ◀───┘ │ │
│ │ │ │ │ │ │
│ │ │ │ ├───┐ │ │
│ │ │ │ │ │ Remove padding │ │
│ │ │ │ ◀───┘ │ │
│ │ │ │ │ │ │
│ │ │ │ ├───┐ │ │
│ │ │ │ │ │ Verify Ed25519 signature │ │
│ │ │ │ ◀───┘ │ │
│ │ │ │ │ │ │
│ │ │ │ ├───┐ │ │
│ │ │ │ │ │ Update Alice's card locally │
│ │ │ │ ◀───┘ │ │
│ │ │ │ │ │ │
│ │ │ │ │ Alice updated contact info │ │
│ │ │ │ │───────────────────────────────▶ │
│ │ │ │ │ │ │
│ │ │ │ Acknowledgment(status=ReceivedByRecipient) │ │ │
│ │ │ ◀───────────────────────────────────────────────│ │ │
│ │ │ │ │ │ │
│ │ │ Forward Acknowledgment │ │ │ │
│ │ ◀╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌│ │ │ │
│ │ │ │ │ │ │
│ │ │ ┌─────────────────────────┐ │ │ │ │
│ │ │ │ Sender notified if │ │ │ │ │
│ │ │ │ suppress_presence=false │ │ │ │ │
│ │ │ └─────────────────────────┘ │ │ │ │
│ │ │ │ │ │ │
│ │ ├───┐ │ │ │ │
│ │ │ │ Mark update as delivered │ │ │ │
│ │ ◀───┘ │ │ │ │
│ │ │ │ │ │ │
│ │ │ │ ┌───────────────────────┐ │ │ │
│ │ │ │ │ Blob queued for later │ │ │ │
│ │ │ │ └───────────────────────┘ │ │ │
│ │ │ │ │ │ │
│ │ │ ┌opt [Bob comes online later]───────────────────────────┐ │ │
│ │ │ │ │ │ │ │ │
│ ├[Bob is Offline]╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ │ │ │ │ │ │ │ │
│ │ │ │ │ Connect (Handshake) │ │ │ │
│ │ │ │ ◀───────────────────────────────────────────────│ │ │ │
│ │ │ │ │ │ │ │ │
│ │ │ │ │ Deliver queued blobs │ │ │ │
│ │ │ │ │╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌▶ │ │ │
│ │ │ │ │ │ │ │ │
│ │ │ │ │ ├───│ │ │
│ │ │ │ │ │ │ Process all pending updates │
│ │ │ │ │ ◀───│ │ │
│ │ │ │ │ │ │ │ │
│ │ │ │ │ ├───│ │ │
│ │ │ │ │ │ │ Updates applied in order │ │
│ │ │ │ │ ◀───│ │ │
│ │ │ │ │ │ │ │ │
│ │ │ ┌────────────────────────────────┐ │ │ │ │
│ │ │ │ Bob now sees Alice's new phone │ │ │ │ │
│ │ │ └────────────────────────────────┘ │ │ │ │
│ │ │ │ │ │ │ │ │
│ │ │ └───────────────────────────────────────────────────────┘ │ │
│ │ │ │ │ │ │
│ └─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
│ │ │ │ │
┌───┴───┐ ┌─────────┴─────────┐ ┌─────┴─────┐ ┌────────┴────────┐ ┌──┴──┐
│ Alice │ │ Alice's Device 📱 │ │ Relay 🖥️ │ │ Bob's Device 📱 │ │ Bob │
└───────┘ └───────────────────┘ └───────────┘ └─────────────────┘ └─────┘
Double Ratchet Message Flow
┌─────────────────┐ ┌───────────────┐
│ Alice's Ratchet │ │ Bob's Ratchet │
└────────┬────────┘ └───────┬───────┘
│ │
┌rect [rgb(240, 248, 255)]───────────────────────────┐
│ │ │ │
│ ├───┐ │ │
│ │ │ Ratchet send chain: gen 0 → 1 │ │
│ ◀───┘ │ │
│ │ │ │
│ ├───┐ │ │
│ │ │ Derive message key (gen 0) │ │
│ ◀───┘ │ │
│ │ │ │
│ ├───┐ │ │
│ │ │ Encrypt with message key │ │
│ ◀───┘ │ │
│ │ │ │
│ ├───┐ │ │
│ │ │ Delete message key │ │
│ ◀───┘ │ │
│ │ │ │
│ │ [DH_pub, gen=0, idx=0] + ciphertext │ │
│ │────────────────────────────────────────────▶ │
│ │ │ │
│ │ ┌─────────────────────┐
│ │ │ RECEIVE (Message 1) │
│ │ └─────────────────────┘
│ │ │ │
└────────────────────────────────────────────────────┘
│ │
│ ┌rect [r┐
│ │ │ │
│ │ ├───│
│ │ │ │ Verify DH generation matches
│ │ ◀───│
│ │ │ │
│ │ ├───│
│ │ │ │ Ratchet receive chain: gen 0 → 1
│ │ ◀───│
│ │ │ │
│ │ ├───│
│ │ │ │ Derive message key (gen 0)
│ │ ◀───│
│ │ │ │
│ │ ├───│
│ │ │ │ Decrypt
│ │ ◀───│
│ │ │ │
│ │ ├───│
│ │ │ │ Delete message key
│ │ ◀───│
│ │ │ │
│ ┌──────────────────────────────────┐
│ │ SEND REPLY (triggers DH ratchet) │
│ └──────────────────────────────────┘
│ │ │ │
│ └───────┘
│ │
┌rect [rgb(255, 248, 240)]───────────────────────────┐
│ │ │ │
│ │ ├───│
│ │ │ │ Generate new ephemeral DH keypair
│ │ ◀───│
│ │ │ │
│ │ ├───│
│ │ │ │ DH ratchet: compute new root key
│ │ ◀───│
│ │ │ │
│ │ ├───│
│ │ │ │ Create new send chain
│ │ ◀───│
│ │ │ │
│ │ ├───│
│ │ │ │ Encrypt with new chain's key
│ │ ◀───│
│ │ │ │
│ │ [NEW_DH_pub, gen=1, idx=0] + ciphertext │ │
│ ◀────────────────────────────────────────────│ │
│ │ │ │
┌───────────────────────────────┐ │ │
│ RECEIVE (triggers DH ratchet) │ │ │
└───────────────────────────────┘ │ │
│ │ │ │
└────────────────────────────────────────────────────┘
│ │
┌rect [r┐ │
│ │ │ │
│ ├───│ │
│ │ │ Detect new DH public key │
│ ◀───│ │
│ │ │ │
│ ├───│ │
│ │ │ DH ratchet: compute matching root key │
│ ◀───│ │
│ │ │ │
│ ├───│ │
│ │ │ Create new receive chain │
│ ◀───│ │
│ │ │ │
│ ├───│ │
│ │ │ Decrypt with new chain's key │
│ ◀───│ │
│ │ │ │
└───────┘ │
│ │
┌────────┴────────┐ ┌───────┴───────┐
│ Alice's Ratchet │ │ Bob's Ratchet │
└─────────────────┘ └───────────────┘
Out-of-Order Message Handling
┌────────────────┐ ┌───────┐ ┌──────────────┐
│ Alice's Device │ │ Relay │ │ Bob's Device │
└────────┬───────┘ └───┬───┘ └───────┬──────┘
│ │ │
│ Message 1 (gen=0, idx=0) │ │
│─────────────────────────────▶ │
│ │ │
│ Message 2 (gen=0, idx=1) │ │
│─────────────────────────────▶ │
│ │ │
│ Message 3 (gen=0, idx=2) │ │
│─────────────────────────────▶ │
│ │ │
│ ┌────────────────┐ │
│ │ Network delays │ │
│ └────────────────┘ │
│ │ │
│ │ Message 3 arrives first │
│ │╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌▶
│ │ │
│ │ ├───┐
│ │ │ │ Expected idx=0, got idx=2
│ │ ◀───┘
│ │ │
│ │ ├───┐
│ │ │ │ Skip chain to idx=2
│ │ ◀───┘
│ │ │
│ │ ├───┐
│ │ │ │ Store skipped keys: [idx=0, idx=1]
│ │ ◀───┘
│ │ │
│ │ ├───┐
│ │ │ │ Decrypt message 3
│ │ ◀───┘
│ │ │
│ │ Message 1 arrives │
│ │╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌▶
│ │ │
│ │ ├───┐
│ │ │ │ Lookup skipped key for idx=0
│ │ ◀───┘
│ │ │
│ │ ├───┐
│ │ │ │ Found! Decrypt message 1
│ │ ◀───┘
│ │ │
│ │ ├───┐
│ │ │ │ Delete skipped key
│ │ ◀───┘
│ │ │
│ │ Message 2 arrives │
│ │╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌▶
│ │ │
│ │ ├───┐
│ │ │ │ Lookup skipped key for idx=1
│ │ ◀───┘
│ │ │
│ │ ├───┐
│ │ │ │ Found! Decrypt message 2
│ │ ◀───┘
│ │ │
│ │ ├───┐
│ │ │ │ Delete skipped key
│ │ ◀───┘
│ │ │
│ │ ┌─────────────────────────┐
│ │ │ All messages processed, │
│ │ │ skipped keys cleaned up │
│ │ └─────────────────────────┘
│ │ │
┌────────┴───────┐ ┌───┴───┐ ┌───────┴──────┐
│ Alice's Device │ │ Relay │ │ Bob's Device │
└────────────────┘ └───────┘ └──────────────┘
Relay Acknowledgment States
●───● ╭──────╮ ╭────────╮ ╭───────────────╮ ╭─────────────────────╮ ╔═══╗
│ │ │ │ │ │ │ │ │ │ ║ ║
│ │─Message─created►│ Sent ├Relay─confirms─storage─►│ Stored │ ├────Recipient─connected────►│ Delivered ├Recipient─acks─►│ ReceivedByRecipient ├────►║ ║
│ │ │ │ │ │ │ │ │ │ ║ ║
●───● ╰──────╯ ╰────┬───╯ ╰───────┬───────╯ ╰─────────────────────╯ ╚═══╝
│ │
│ Decrypt error
│ │
│ │
│ ▼
│ ╭───────────────╮ ╔═════════════════════╗
│ │ │ ║ ║
└────────────Quota─exceeded─────────────►│ Failed ├───────────────►║ ║
│ │ ║ ║
╰───────────────╯ ╚═════════════════════╝
Wire Protocol
Envelope Format
┌─────────────────────────────────────────────────────────────┐
│ MESSAGE ENVELOPE │
├─────────────────────────────────────────────────────────────┤
│ 4 bytes: Length (big-endian) │
│ JSON payload: │
│ { │
│ "version": 1, │
│ "message_id": "uuid", │
│ "timestamp": unix_secs, │
│ "payload": { ... } │
│ } │
└─────────────────────────────────────────────────────────────┘
EncryptedUpdate Payload
{
"type": "EncryptedUpdate",
"sender_id": "anonymous_id (hourly rotation)",
"recipient_id": "mailbox token (daily rotation)",
"ratchet_header": {
"dh_public": "[32 bytes] sender DH public key",
"dh_generation": 5,
"message_index": 10,
"previous_chain_length": 3
},
"ciphertext": "base64(encrypted_delta)"
}
Acknowledgment Payload
{
"type": "Acknowledgment",
"message_id": "original message uuid",
"status": "Stored|Delivered|Received|Failed",
"error": null
}
Timing Estimates
| Phase | Duration | Notes |
|---|---|---|
| Encryption + padding | 1-5 ms | XChaCha20 is fast |
| Network latency | 50-200 ms | Relay location |
| Relay storage | 1-10 ms | SQLite insert |
| Forward to recipient | 50-200 ms | If online |
| Decryption + verify | 1-5 ms | |
| Total (online) | 100-400 ms | End-to-end |
| Total (offline) | < 120 days | Until connect |
Related Features
- Contact Exchange
- How keys are established
- Sync Updates
- Multi-device sync
- Crypto Hierarchy
- Key derivation