Diagrams
The system in diagrams
How Ledger Chat is put together, how you sign in and how a computer is linked to your phone, drawn one step at a time.
Each drawing below is written in Mermaid and drawn on our server. Open Mermaid source under a drawing to copy it. The drawings show what runs today; anything in design is drawn with a dashed border and named as such.
The whole system
Ledger Chat at a glance
Mermaid source
Mermaid
flowchart LR
You[Your device<br/>app, keys, prover]:::accent
XMTP[XMTP network<br/>relays MLS ciphertext]
Peer[The other person's device]
Srv[Our servers<br/>accounts, contacts, communities]:::dashed
Az[Aztec network<br/>proofs and notes]
Eth[Ethereum<br/>settlement]
You -->|messages, MLS| XMTP --> Peer
You -->|calls, DTLS-SRTP| Peer
You -.->|session| Srv
You -->|proof| Az -->|settles on| EthWhat runs where
Mermaid source
Mermaid
flowchart LR
subgraph dev [Your browser]
App[Ledger Chat web app]
X[XMTP client<br/>keys of this installation]
P[Private eXecution Environment<br/>notes and proofs]
H[(IndexedDB<br/>decrypted history)]
end
subgraph ours [Our servers]
API[Next.js routes]
PG[(PostgreSQL)]
R[(Redis)]
ST[(File storage<br/>ciphertext)]
end
subgraph net [Networks]
XN[XMTP nodes]
AZ[Aztec node]
EV[EVM chains]
end
App --> X --> XN
App --> P --> AZ
App --> H
App --> API --> PG
API --> R
API --> ST
App -->|public payments| EVWhere your data is kept
Mermaid source
Mermaid
flowchart LR
Msg[A message you write] --> H[(Your device<br/>decrypted history)]
Msg -->|MLS ciphertext| XC[(XMTP nodes<br/>ciphertext)]
Msg -.->|fallback path only, readable| F[(Our server<br/>PostgreSQL, Redis 7 days)]:::dashed
File[A file you send] -->|encrypted first| S[(File storage<br/>ciphertext)]
Pay[A private payment] --> N[(Your device<br/>notes, encrypted store)]
Pay -->|proof| AZ[(Aztec<br/>notes and nullifiers)]
Acct[Your account] --> A[(Our server<br/>profile, contacts, communities)]In front of every route
The identity perimeter
Mermaid source
Mermaid
flowchart LR
Req[Request] --> Strip[Remove identity headers<br/>sent by the client]
Strip --> V{Valid session<br/>token?}
V -->|yes| Att[Attach the address<br/>from the token]:::ok
V -->|no| Pub{Public route?}
Att --> Route[The route reads identity<br/>only from that value]
Pub -->|yes| Page[Public page]
Pub -->|no| Stop[401 or sign in]:::dangerContent security policy
Mermaid source
Mermaid
flowchart LR
MW[Middleware] -->|new nonce per request| CSP[Content-Security-Policy<br/>script-src self and the nonce]
MW --> HTML[Server-rendered page<br/>its scripts carry the nonce]
CSP --> B[Browser]
HTML --> B
B --> Run[Runs scripts with the nonce]:::ok
B --> Block[Refuses injected scripts]:::dangerHow it scales
Mermaid source
Mermaid
flowchart LR
U[Browsers] --> W1[Web server<br/>stateless]
U --> W2[Web server<br/>stateless]
W1 --> Pool[Connection pooler]
W2 --> Pool
Pool --> PG[(PostgreSQL)]
Mig[Migrations] -.->|direct connection| PG
W1 --> R[(Redis<br/>online status, with expiry)]
W2 --> RFrom a change to the site
Mermaid source
Mermaid
flowchart TB
PR[Pull request] --> CI[CI<br/>types, lint, forbidden patterns, tests]
CI --> Rev[Review and merge<br/>by a maintainer]
Rev --> Dep[Deployment]
Agent[Changes made by an agent] -.->|claude/ branches only| PROne register for every public claim
Mermaid source
Mermaid
flowchart LR
Reg[Claims register<br/>lib/landing/claims.ts]:::accent --> Land[Landing page]
Reg --> Brief[Printable brief]
Test[Unit test] -->|fails the build on| Rogue[A status written by hand<br/>or a banned word]:::dangerSigning in
Sign in with a wallet
Mermaid source
Mermaid
sequenceDiagram
autonumber
participant D as Your device
participant W as Your wallet
participant S as Our server
D->>S: Ask for a nonce
S-->>D: Nonce, and a sealed cookie valid ten minutes
D->>W: Sign this message: website, address, nonce, time, chain
W-->>D: Signature
D->>S: Message and signature
Note over S: Checks website, nonce and age, marks the nonce used, recovers the signer
S-->>D: Session cookie, HttpOnly, seven daysContract wallets
Mermaid source
Mermaid
flowchart LR
Sig[Signature on the message] --> T{Kind of wallet}
T -->|externally owned| Rec[Recover the signer<br/>it must match the address]:::ok
T -->|smart contract wallet| C[ERC-1271 or ERC-6492<br/>checked on its own chain]:::ok
Any[Any EVM chain] -.-> TSign in with email
Mermaid source
Mermaid
sequenceDiagram
participant U as You
participant S as Our server
participant M as Your inbox
U->>S: Email address
S->>M: One-time code
U->>S: The code
S-->>U: Session for an account with a random identifier
Note over S: Routes that need a wallet refuse this account explicitlySeeing what you sign
Mermaid source
Mermaid
flowchart TB
Msg[Exact text the wallet will sign] --> Parse[Read its fields]
Parse --> F[Website, address, chain,<br/>nonce, issued, expires]
F --> C{Website matches<br/>this page?}
C -->|yes| Sign[Sign in the wallet]:::ok
C -->|no| Warn[Warning: do not sign]:::danger
Msg -.->|one tap| Full[Show the exact text]The PIN
Mermaid source
Mermaid
flowchart LR
PIN[Six digit PIN] -->|Argon2id, salt, server pepper| H[(Hash on our server)]
H --> Lim[Eight attempts<br/>per five minutes]
PIN -.->|not used to derive| Keys[Message keys]:::muted
Flag[Off since 11 November 2026<br/>build flag]:::dashed -.-> PINLinking a computer
Linking a computer to your phone
Mermaid source
Mermaid
sequenceDiagram
autonumber
participant C as Computer
participant S as Our server
participant P as Your phone
C->>C: New P-256 key pair
C-->>P: QR code with the public key, valid four minutes
P->>P: Names the computer that asks and waits for you
P->>S: Claim code, device id and channel key, encrypted to the computer
Note over S: Keeps only ciphertext and the SHA-256 of the claim
C->>S: Proves it decrypted the claim
S-->>C: Session in HttpOnly cookiesSignatures for a linked computer
Mermaid source
Mermaid
sequenceDiagram
participant C as Computer
participant S as Our server
participant P as Your phone
C->>S: Request sealed with AES-256-GCM under the channel key
Note over C,S: Request id and kind bound as associated data
S->>P: Ciphertext
P->>P: Says what the signature is for
alt You approve
P->>S: Signature, sealed
S->>C: Ciphertext
else You decline
P->>S: Declined
endWhat a linked computer can do
Mermaid source
Mermaid
flowchart LR
Ph[Your phone]:::accent -->|lists and unlinks| Comp[Linked computers<br/>at most five]
Comp --> Exp[Each link lasts<br/>seven days]
Ph -->|unlink| Rev[Session token revoked at once]:::danger
Comp -.->|cannot| L[Link more devices]:::muted
Comp -.->|cannot| A[Answer signature requests]:::mutedLedger Relay, in design
Ledger Relay
Mermaid source
Mermaid
flowchart LR
A[Your device]:::accent <-->|signalling<br/>TURN credentials<br/>encrypted files| Rl[Ledger Relay<br/>stateless, self-hostable]:::dashed
Rl <-->|signalling| B[Other device]
Rl -->|empty push| PS[Push service]
PS -.->|wake up| BCiphertext only
Mermaid source
Mermaid
flowchart LR
Up[Upload to the relay] --> Sz{Within size and quota?}
Sz -->|no| R413[Refused: too large]:::danger
Sz -->|yes| Sig{Starts like a known file<br/>PNG, JPEG, PDF, ZIP, MP4, text}
Sig -->|yes| R415[Refused: not encrypted]:::danger
Sig -->|no| Keep[(Kept until it expires)]:::okWaking a device
Mermaid source
Mermaid
sequenceDiagram
participant B as Their device
participant Rl as Ledger Relay
participant P as Push service
participant A as Your device
A->>Rl: Register a push subscription
Rl-->>A: Opaque token
A->>B: The token, inside an MLS message
B->>Rl: Wake this token
Rl->>P: Empty push, no payload
P->>A: Wake up
A->>A: Fetches new messages over XMTP itself