Skip to main content

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

Your deviceXMTP nodesTheir deviceEncrypt with the conversation's current MLS epochCiphertextStored so offline devices can collect itFetchCiphertextDecrypt, keep the history in the browser
The normal path. XMTP nodes store ciphertext; only the two devices can read it.
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 browser

Keys and epochs

Wallet signatureInstallation keysmade in this browserMLS groupone per conversationEpoch nEpoch n plus 1Forward secrecy andpost-compromise securityauthorisesmember or key update
Messaging Layer Security (RFC 9420). Each browser gets its own keys once the wallet authorises it, and the group key changes with every epoch.
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]:::ok

The fallback path

Your deviceXMTPNot deliveredOur serverPostgreSQL, Redis 7 daysTheir deviceLabelled on both sidesfirstrecipient has no installation yetthe app may hand it toreadable by the server
The fallback path. It exists so a first message reaches someone who has not opened Ledger Chat yet. Messages on it are readable by our server, and both people see a label.
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

Fallback message bodySealed envelopehlv1.algorithm.payload?StoredRecorded that a readable bodyarrived, without the bodyRejectedyesno, default modeno, with the flag on
A guard on the fallback path reports readable bodies today and rejects them once clients seal every fallback message.
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]:::danger

Signals inside the conversation

Typing, read, reaction,edit, pin, voteXMTPTypingTheir deviceshows typing for 7 sordinary MLS messagesat most one every 5 s
Receipts, reactions and typing are messages like any other, encrypted the same way. Typing is sent at most every five seconds.
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

Clear chatCut-off time, on this deviceand on your other devicesDelete chatDeletion timeNo message from before itis shown againOut of the list untila newer message arrivesThe other person's copydoes not touch
Clear and delete are recorded, so nothing comes back on the next sync (lib/chat/cleared-chats.ts). Neither removes the other person's copy.
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]:::muted

Communities

MemberOur serverchecks the role on every requestPostgreSQLcommunities, channels, roles, postsInvite linkAdminNot end-to-end encrypted yetHMAC-SHA256 tagrevokesreadable by the server today
Communities are server rows today. Invite links cannot be forged and can be revoked; posts are not end-to-end encrypted yet.
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]:::danger

Files

Sending a file

Your deviceOur serverFile storageTheir deviceEncrypt, AES-256-GCM with a key fromHKDF-SHA256CiphertextCiphertextLink and the digest it computedChecks the digest matcheshl.attachment message with link and key, insideMLSDownload ciphertextDecrypt with the key from the message
Files up to 20 MB (lib/chat/send-attachment.ts). The key travels only inside the end-to-end encrypted message.
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 message

Large files

File over 20 MB16 MiB piecesup to 2048One key per fileHKDF-SHA256AES-256-GCMeach pieceUpload each piecewith retriesFile storageciphertexthl.largefile messagepieces and key, inside MLS
Large files, up to 32 GiB (lib/chat/large-file.ts). Each piece is encrypted on the device before anything is uploaded.
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

Prefix, 8 random bytesNonce: prefix andindex as 4 bytesPiece indexAssociated datahl.largefile/v1, index, totalTotal piecesAES-256-GCMA piece moved, dropped orswapped fails to open
Why pieces cannot be rearranged: every piece is bound to its position and to the total number of pieces.
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]:::ok

Receiving a large file

loop[Each piece]Their deviceOur serverReads the hl.largefile messageDownload pieceCiphertextDecrypt with its nonce and associated dataWrites the file to disk when the browser allows, elseto memory
Receiving a large file. A piece that fails to open stops the download with an error instead of a damaged 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 memory

When storage is off

UploadFile storageswitched on?Stored as ciphertextSent inside theXMTP message itselfYou read: file storageis not switched onyesno, small fileno, large file
When storage is not configured the app says so plainly. Small files can still travel inside the encrypted message.
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]:::danger

Calls

How a call connects

CallerPeerJS signallingCallee1Offer2Offer3Answer4Answer5ICE candidates6ICE candidates7DTLS handshake8Media, SRTP
Setting up a call. The signalling service carries descriptions and candidates; the media key is negotiated by the two browsers.
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, SRTP

Direct or relayed

Your deviceDirect path?Device to deviceDTLS-SRTPTURN relayshort-lived credentialsStill DTLS-SRTPthe relay cannot decodeRelay-only settingThe other person doesnot learn your IP addressyesno
Direct when possible, relayed when not. Either way the media is encrypted between the two browsers.
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

Shared secretrelay and coturnHMAC-SHA1Username: expiry andrandom charactersPassword, base64coturn checks the expiryand recomputes the passwordNothing ties it to youno wallet, no user id
TURN credentials from Ledger Relay (relay/src/turn.mjs), in the form coturn accepts with use-auth-secret. They expire and carry no identifier.
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]:::ok

Call states

IdleRinging themRinging youConnectingIn callMoving to a new connectionthe old one keeps playingEndedyou callthey callansweredyou answermedia flowsnetwork changesnew one readyhang up
The states of a call (lib/calls/machine.ts). A call that is declined, missed or not answered ends. When the network changes the call stays on: a new connection is made first and the old one closes after. Every screen and sound follows one state, so a call cannot ring and talk at once.
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