SimpleX Protocol Stack: Implementation Specification
An Implementer's Guide to the SimpleX Messaging Protocol Suite
Version 0.1 (Draft) — February 2026
Contributors: cannatoshi, SimpleGo Project
License: CC BY-SA 4.0
What is this document?
This specification provides a complete, implementation-oriented reference for the SimpleX messaging protocol stack. It is designed to enable developers to build interoperable SimpleX clients without reading the Haskell source code.
SimpleX is a decentralized, metadata-private messaging protocol created by Evgeny Poberezkin and the SimpleX Chat team. Unlike other messaging protocols, SimpleX uses no user identifiers — not even random ones. Instead, it relies on unidirectional message queues on untrusted relay servers.
Why this spec exists
As of early 2026, SimpleX does not have a complete formal specification. The protocol creator confirmed:
"I am currently updating the protocol specification to match the current protocol"
— Evgeny Poberezkin, January 28, 2026
The existing documentation covers parts of the protocol but leaves critical implementation details undocumented:
- Wire format byte layouts (length prefixes, encoding conventions)
- Encryption layer parameters (IV sizes, HKDF salts, AAD construction)
- Double Ratchet profile (deviations from the Signal specification)
- Encoding conventions (Maybe-type, ByteString length encoding, SPKI)
- Versioning across all five independent version layers
- Compressed message format (Zstd integration)
Origin
This specification was reverse-engineered during the development of SimpleGo — the first native third-party implementation of the SimpleX protocol, running on ESP32-S3 microcontrollers. Over 20 development sessions, we:
- Found and documented 19 protocol-level bugs with before/after analysis
- Verified every encryption layer byte-by-byte against the Haskell reference
- Produced verified hex dumps for every processing step
- Identified all deviations from standard cryptographic libraries
- Created 14,000+ lines of analysis documentation
How to read this specification
The specification is organized in layers, from the outermost (transport) to the innermost (application messages):
| Chapter | Content | Status |
|---|---|---|
| 00 — Terminology | Conventions, glossary, RFC 2119 keywords | 🔲 Draft |
| 01 — Architecture | System design, layer model, connection lifecycle | 🔲 Draft |
| 02 — Transport | TLS 1.3, block format, version negotiation | 🔲 Draft |
| 03 — SMP Commands | Queue operations, command encoding, authentication | 🔲 Draft |
| 04 — Encryption Layer 3 | Server-to-recipient (NaCl crypto_box) | 🔲 Draft |
| 05 — Encryption Layer 2 | Per-queue E2E (NaCl crypto_box) | 🔲 Draft |
| 06 — Encryption Layer 1 | Double Ratchet (X3DH, AES-256-GCM) | 🔲 Draft |
| 07 — Agent Protocol | Handshake, connection state machine | 🔲 Draft |
| 08 — Wire Format | Encoding rules, byte layouts | 🔲 Draft |
| 09 — Message Types | Chat messages, ConnInfo, compression | 🔲 Draft |
| 10 — Versioning | Five independent version layers | 🔲 Draft |
| 11 — Security | Threat model, private routing | 🔲 Draft |
Appendices
| Appendix | Content |
|---|---|
| A — Test Vectors | Verified hex dumps from ESP32 hardware tests |
| B — Implementation Notes | Pitfalls, deviations, our 19 bugs |
| C — Haskell Reference | Mapping: spec section → Haskell source file:line |
| D — Changelog | Specification revision history |
Audience
- Implementers building SimpleX clients in other languages
- Security researchers auditing the protocol
- The SimpleX team as a basis for the official specification
- Academics formally analyzing the protocol
Conventions
This document uses RFC 2119 keywords: MUST, MUST NOT, SHOULD, SHOULD NOT, MAY. See Terminology for full definitions and notation conventions.
This is a living document. Corrections, additions, and test vectors are welcome via GitHub Issues or pull requests.