Skip to main content

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

Your deviceapp, keys, proverXMTP networkrelays MLS ciphertextThe other person's deviceOur serversaccounts, contacts, communitiesAztec networkproofs and notesEthereumsettlementmessages, MLScalls, DTLS-SRTPsessionproofsettles on
Your device does the encryption and the proving. Messages travel as MLS ciphertext over XMTP, calls go device to device, and private payments reach Aztec as proofs. Our servers keep accounts, contacts and communities.
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| Eth

What runs where

Your browserOur serversNetworksLedger Chat web appXMTP clientkeys of this installationPrivate eXecution Environmentnotes and proofsIndexedDBdecrypted historyNext.js routesPostgreSQLRedisFile storageciphertextXMTP nodesAztec nodeEVM chainspublic payments
What runs where. Keys, decrypted history and private notes stay in the browser. Our servers run the routes, the database, Redis and the file storage, which only receives ciphertext.
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| EV

Where your data is kept

A message you writeYour devicedecrypted historyXMTP nodesciphertextOur serverPostgreSQL, Redis 7 daysA file you sendFile storageciphertextA private paymentYour devicenotes, encrypted storeAztecnotes and nullifiersYour accountOur serverprofile, contacts, communitiesMLS ciphertextfallback path only, readableencrypted firstproof
Where each kind of data ends up. Only the fallback path, used when the other person has no XMTP installation yet, leaves a message readable by our server, and the app labels it on both sides.
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

RequestRemove identity headerssent by the clientValid sessiontoken?Attach the addressfrom the tokenPublic route?The route reads identityonly from that valuePublic page401 or sign inyesnoyesno
The identity perimeter (middleware.ts). A client cannot claim to be someone else by sending a header: it is removed, and the only identity a route sees is the one taken from the verified session token.
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]:::danger

Content security policy

MiddlewareContent-Security-Policyscript-src self and the nonceServer-rendered pageits scripts carry the nonceBrowserRuns scripts with the nonceRefuses injected scriptsnew nonce per request
A fresh nonce for every response (buildCsp in middleware.ts). A script injected into a page has no nonce, so the browser refuses to run it.
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]:::danger

How it scales

BrowsersWeb serverstatelessWeb serverstatelessConnection poolerPostgreSQLMigrationsRedisonline status, with expirydirect connection
Scaling. Web servers keep no state, PostgreSQL is reached through a pooler and online status lives in Redis with an expiry. Device linking codes held in memory are the remaining single-instance state.
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 --> R

From a change to the site

Pull requestCItypes, lint, forbidden patterns, testsReview and mergeby a maintainerDeploymentChanges made by an agentclaude/ branches only
How a change reaches the site. Every pull request runs the type check, the linter, the forbidden-pattern scan and the tests. Agents push only to claude/ branches and never merge.
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| PR

One register for every public claim

Claims registerlib/landing/claims.tsLanding pagePrintable briefUnit testA status written by handor a banned wordfails the build on
Every status on the landing (Live, Closed alpha, Not enabled yet, In design) comes from one register. A test fails the build if a page writes a status of its own.
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]:::danger

Signing in

Sign in with a wallet

Your deviceYour walletOur server1Ask for a nonce2Nonce, and a sealed cookie valid ten minutes3Sign this message: website, address, nonce, time,chain4Signature5Message and signatureChecks website, nonce and age, marks thenonce used, recovers the signer6Session cookie, HttpOnly, seven days
Sign in with Ethereum (EIP-4361). Signing is free and is not a transaction. A nonce can be used once, and only a nonce our server issued.
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 days

Contract wallets

Signature on the messageKind of walletRecover the signerit must match the addressERC-1271 or ERC-6492checked on its own chainAny EVM chainexternally ownedsmart contract wallet
Both kinds of wallet sign in. A contract wallet is asked on its own chain whether the signature is valid; a signature does not depend on the chain.
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] -.-> T

Sign in with email

YouOur serverYour inboxEmail addressOne-time codeThe codeSession for an account with a random identifierRoutes that need a wallet refuse this accountexplicitly
Signing in with email. The account has no wallet, so anything that needs one says so instead of failing later.
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 explicitly

Seeing what you sign

Exact text the wallet will signRead its fieldsWebsite, address, chain,nonce, issued, expiresWebsite matchesthis page?Sign in the walletWarning: do not signShow the exact textyesnoone tap
What you see before signing (components/auth/SignaturePreview.tsx). The summary is read from the exact text the wallet receives, and a website that differs from the page is flagged.
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

Six digit PINHash on our serverEight attemptsper five minutesMessage keysOff since 11 November 2026build flagArgon2id, salt, server peppernot used to derive
The PIN, when it is switched on, gates the interface on a device. It does not protect message keys, and it is off today.
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 -.-> PIN

Linking a computer

Linking a computer to your phone

ComputerOur serverYour phone1New P-256 key pair2QR code with the public key, valid four minutes3Names the computer that asks and waits for you4Claim code, device id and channel key, encrypted tothe computerKeeps only ciphertext and the SHA-256 of theclaim5Proves it decrypted the claim6Session in HttpOnly cookies
Linking works like WhatsApp Web or Signal Desktop. The computer never receives the wallet, and our server holds no key that opens what it relays.
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 cookies

Signatures for a linked computer

alt[You approve][You decline]ComputerOur serverYour phoneRequest sealed with AES-256-GCM under thechannel keyRequest id and kind bound as associated dataCiphertextSays what the signature is forSignature, sealedCiphertextDeclined
When a linked computer needs a wallet signature, the phone shows what it is for and signs only on approval. An answer cannot be replayed onto another request.
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
  end

What a linked computer can do

Your phoneLinked computersat most fiveEach link lastsseven daysSession token revoked at onceLink more devicesAnswer signature requestslists and unlinksunlinkcannotcannot
The limits of a linked computer. The phone holds the account; a computer can do neither of the two things that would let it act as the phone.
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]:::muted

Ledger Relay, in design

Ledger Relay

Your deviceLedger Relaystateless, self-hostableOther devicePush servicesignallingTURN credentialsencrypted filessignallingempty pushwake up
Ledger Relay (relay/ in the repository) is built and tested but not deployed. It would replace the public signalling service and give anyone a relay they can run themselves.
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| B

Ciphertext only

Upload to the relayWithin size and quota?Refused: too largeStarts like a known filePNG, JPEG, PDF, ZIP, MP4, textRefused: not encryptedKept until it expiresnoyesyesno
The relay's blob store accepts ciphertext only. A file that begins like a common plaintext format is refused, so a client that forgot to encrypt cannot leave a readable file there.
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)]:::ok

Waking a device

Their deviceLedger RelayPush serviceYour deviceRegister a push subscriptionOpaque tokenThe token, inside an MLS messageWake this tokenEmpty push, no payloadWake upFetches new messages over XMTP itself
Push without content. The relay sees an endpoint, an opaque token and the time of each wake, never who wrote or what.
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