Diagrams
Messages, files and calls in diagrams
How a message, a file and a call travel from your device to the other person's, drawn step by step.
Messages
A direct message
Mermaid source
Mermaid
sequenceDiagram
participant A as Your device
participant X as XMTP nodes
participant B as Their device
A->>A: Encrypt with the conversation's current MLS epoch
A->>X: Ciphertext
Note over X: Stored so offline devices can collect it
B->>X: Fetch
X-->>B: Ciphertext
B->>B: Decrypt, keep the history in the browserKeys and epochs
Mermaid source
Mermaid
flowchart TB
W[Wallet signature] -->|authorises| I[Installation keys<br/>made in this browser]:::accent
I --> G[MLS group<br/>one per conversation]
G --> E1[Epoch n]
E1 -->|member or key update| E2[Epoch n plus 1]
E2 --> FS[Forward secrecy and<br/>post-compromise security]:::okThe fallback path
Mermaid source
Mermaid
flowchart TB
A[Your device] -->|first| X[XMTP]
X -->|recipient has no installation yet| Nd[Not delivered]:::danger
Nd -->|the app may hand it to| F[Our server<br/>PostgreSQL, Redis 7 days]:::dashed
F -->|readable by the server| B[Their device]
B --> L[Labelled on both sides]The fallback guard
Mermaid source
Mermaid
flowchart LR
Body[Fallback message body] --> G{Sealed envelope<br/>hlv1.algorithm.payload?}
G -->|yes| Store[Stored]:::ok
G -->|no, default mode| Rep[Recorded that a readable body<br/>arrived, without the body]
G -->|no, with the flag on| Rej[Rejected]:::dangerSignals inside the conversation
Mermaid source
Mermaid
flowchart LR
Sig[Typing, read, reaction,<br/>edit, pin, vote] -->|ordinary MLS messages| X[XMTP]
Typ[Typing] -->|at most one every 5 s| Sig
X --> B[Their device<br/>shows typing for 7 s]Clear chat and delete chat
Mermaid source
Mermaid
flowchart TB
Clear[Clear chat] --> Cut[Cut-off time, on this device<br/>and on your other devices]
Delete[Delete chat] --> Cut
Delete --> Del[Deletion time]
Cut --> Hide[No message from before it<br/>is shown again]:::ok
Del --> Away[Out of the list until<br/>a newer message arrives]:::ok
Cut -.->|does not touch| Theirs[The other person's copy]:::mutedCommunities
Mermaid source
Mermaid
flowchart TB
M[Member] --> S[Our server<br/>checks the role on every request]
S --> PG[(PostgreSQL<br/>communities, channels, roles, posts)]
Inv[Invite link] -->|HMAC-SHA256 tag| S
Adm[Admin] -->|revokes| Inv
PG -.->|readable by the server today| E[Not end-to-end encrypted yet]:::dangerFiles
Sending a file
Mermaid source
Mermaid
sequenceDiagram
participant A as Your device
participant S as Our server
participant R as File storage
participant B as Their device
A->>A: Encrypt, AES-256-GCM with a key from HKDF-SHA256
A->>S: Ciphertext
S->>R: Ciphertext
S-->>A: Link and the digest it computed
A->>A: Checks the digest matches
A->>B: hl.attachment message with link and key, inside MLS
B->>S: Download ciphertext
B->>B: Decrypt with the key from the messageLarge files
Mermaid source
Mermaid
flowchart LR
F[File over 20 MB] --> Split[16 MiB pieces<br/>up to 2048]
Key[One key per file<br/>HKDF-SHA256] --> Enc[AES-256-GCM<br/>each piece]:::accent
Split --> Enc
Enc --> Up[Upload each piece<br/>with retries]
Up --> St[(File storage<br/>ciphertext)]
Up --> Msg[hl.largefile message<br/>pieces and key, inside MLS]One piece
Mermaid source
Mermaid
flowchart LR
Pre[Prefix, 8 random bytes] --> N[Nonce: prefix and<br/>index as 4 bytes]
I[Piece index] --> N
I --> AAD[Associated data<br/>hl.largefile/v1, index, total]
T[Total pieces] --> AAD
N --> G[AES-256-GCM]
AAD --> G
G --> Out[A piece moved, dropped or<br/>swapped fails to open]:::okReceiving a large file
Mermaid source
Mermaid
sequenceDiagram
participant B as Their device
participant S as Our server
B->>B: Reads the hl.largefile message
loop Each piece
B->>S: Download piece
S-->>B: Ciphertext
B->>B: Decrypt with its nonce and associated data
end
B->>B: Writes the file to disk when the browser allows, else to memoryWhen storage is off
Mermaid source
Mermaid
flowchart LR
Up[Upload] --> R{File storage<br/>switched on?}
R -->|yes| Ok[Stored as ciphertext]:::ok
R -->|no, small file| In[Sent inside the<br/>XMTP message itself]
R -->|no, large file| Msg[You read: file storage<br/>is not switched on]:::dangerCalls
How a call connects
Mermaid source
Mermaid
sequenceDiagram
autonumber
participant A as Caller
participant P as PeerJS signalling
participant B as Callee
A->>P: Offer
P->>B: Offer
B->>P: Answer
P->>A: Answer
A->>P: ICE candidates
P->>B: ICE candidates
A->>B: DTLS handshake
A->>B: Media, SRTPDirect or relayed
Mermaid source
Mermaid
flowchart LR
A[Your device] --> Q{Direct path?}
Q -->|yes| D[Device to device<br/>DTLS-SRTP]:::ok
Q -->|no| T[TURN relay<br/>short-lived credentials]:::muted
T --> E[Still DTLS-SRTP<br/>the relay cannot decode]:::ok
Set[Relay-only setting] -.-> T
Set -.-> IP[The other person does<br/>not learn your IP address]TURN credentials
Mermaid source
Mermaid
flowchart LR
Sec[Shared secret<br/>relay and coturn] --> H[HMAC-SHA1]
U[Username: expiry and<br/>random characters] --> H
H --> Pw[Password, base64]
U --> C[coturn checks the expiry<br/>and recomputes the password]
Pw --> C
U -.->|no wallet, no user id| Priv[Nothing ties it to you]:::okCall states
Mermaid source
Mermaid
flowchart TB
Idle[Idle] -->|you call| Out[Ringing them]
Idle -->|they call| In[Ringing you]
Out -->|answered| Con[Connecting]
In -->|you answer| Con
Con -->|media flows| Act[In call]:::ok
Act -->|network changes| Re[Moving to a new connection<br/>the old one keeps playing]
Re -->|new one ready| Act
Out -.-> End[Ended]
In -.-> End
Act -->|hang up| End