Architecture Overview

Draft

This section is under construction.

Design Goals

SimpleX is designed around three core principles:

1. No User Identifiers — Users have no permanent identifiers, not even random ones
2. Unidirectional Queues — Each queue has exactly one sender and one recipient
3. Server Trust Minimization — Servers cannot read messages or correlate users

Protocol Stack

┌─────────────────────────────────────────┐
│         Chat Application Layer          │  simplex-chat
│    (ChatMessage, JSON, Compression)     │
├─────────────────────────────────────────┤
│          Agent Protocol Layer           │  simplexmq Agent
│    (Handshake, Connection Management)   │
├─────────────────────────────────────────┤
│   Encryption Layer 1: Double Ratchet    │  X3DH + AES-256-GCM
├─────────────────────────────────────────┤
│   Encryption Layer 2: Per-Queue E2E     │  NaCl crypto_box
├─────────────────────────────────────────┤
│   Encryption Layer 3: Server-Recipient  │  NaCl crypto_box
├─────────────────────────────────────────┤
│         SMP Command Layer               │  NEW, SUB, SEND, MSG, ACK
├─────────────────────────────────────────┤
│         SMP Transport Layer             │  16KB blocks, padding
├─────────────────────────────────────────┤
│         TLS 1.3 Transport               │  ChaCha20-Poly1305
└─────────────────────────────────────────┘

Connection Lifecycle

A SimpleX connection goes through four phases:

1. Invitation Phase — Initiator creates a Contact Queue and shares the invitation link out-of-band
2. Confirmation Phase — Joiner sends profile to Contact Queue; Initiator sends confirmation to Reply Queue
3. Secured Phase — Both parties exchange HELLO messages to confirm the connection
4. Active Phase — Normal message exchange using Double Ratchet encryption