Protocol
The Humanity Ledger platform paper
A technical description of the platform: its design goals, each subsystem, the threat model and the open problems.
Revised 11 November 2026: linked devices (2.1), private payments on Aztec Alpha with their fees (7), and Ledger Studio on open models (8). The 21 October revision had replaced earlier versions that described components the product does not use, such as Waku routing and a Double Ratchet over X3DH.
Abstract
Humanity Ledger is a communication platform in which an Ethereum address is the account. Ledger Chat, its first application, offers direct messages encrypted with MLS through the XMTP network, communities, WebRTC calls and payments signed by the user's own wallet. This paper describes each subsystem, states what each party can observe, and lists the properties the system does not yet provide.
1. Design goals
- No phone number, no password. Possession of a wallet is sufficient to create and use an account.
- Content belongs to the endpoints. Our servers should not be able to read direct messages.
- No custody. The platform never holds user funds or keys that can move them.
- Stated limits. Where a goal is not met, the product says so in the interface and in this paper.
2. Identity and sessions
Authentication follows EIP-4361. The client requests a nonce from the server, which returns it together with a cookie sealed by the server and valid for ten minutes, so only a nonce the server issued can be used. The client constructs a Sign in with Ethereum message containing the domain, the address, the nonce, the issue time and the chain, and the wallet signs it. The server checks the domain against its configured address (with or without www.), checks the nonce and its age, marks the nonce as used so it cannot be used twice, and recovers the signer, which must match the address in the message. Smart contract wallets are checked on their own chain (ERC-1271 and ERC-6492). Any EVM chain is accepted, since a wallet signature does not depend on the chain.
Sessions are JSON Web Tokens signed with HMAC-SHA256 and held in a cookie unavailable to scripts, valid for seven days. A perimeter function in front of every route removes identity headers supplied by the client and attaches the address taken from the verified token. Routes read identity only from that value.
Accounts can also be created with an email address and a one time code. Such accounts are identified internally by a random identifier rather than an address, and are marked so that routes requiring a wallet can refuse them explicitly.
2.1 Linked devices
A computer is used the way WhatsApp Web or Signal Desktop is: it becomes a linked device of the phone that holds the account, and it never receives the wallet. The computer generates an ephemeral P-256 key pair and shows its public key in a QR code that expires after four minutes. The signed in phone scans it, shows a description of the computer taken from its own request (for example Chrome on macOS) and links nothing until the person confirms. It then encrypts to the computer's key, through ECDH and HKDF-SHA256, a random claim code, a device identifier and a fresh 256-bit channel key. The server keeps only that ciphertext and the SHA-256 of the claim; it mints the computer's session and releases it, in HttpOnly cookies, only to the browser that opened the code and proves it decrypted the claim.
When the computer needs a wallet signature, to register its own XMTP installation or to open the private wallet, it sends the request through our server sealed with AES-256-GCM under the channel key, with the request identifier and its kind bound as associated data, so an answer cannot be replayed onto another request. The phone states what the signature is for and signs only on approval. A computer cannot link further devices or answer requests. The phone lists linked computers and unlinks any of them at once by revoking its session token; at most five are linked, and a link lasts seven days.
- Computer → Our serverMakes a one-time key pair and shows a QR code with its public key.The code expires in 4 minutes
- Your phoneYou scan it in Settings → Linked devices. The phone shows which computer asks and links nothing until you confirm.
- Your phone → Our serverSends, encrypted to the computer's key, a claim code and a fresh 256-bit channel key.The server keeps only ciphertext and the claim's hash
- Computer → Our serverDecrypts the claim and trades it for its session, set in HttpOnly cookies.
- Computer → Your phoneNeeds a wallet signature: asks the phone over the channel, AES-256-GCM.The phone shows what it is for; you approve or decline
3. Direct messages
Direct messages use the XMTP network, which implements the Messaging Layer Security protocol (RFC 9420). Each browser installation generates its own key material after the user authorises it with a wallet signature. Conversations are MLS groups; the epoch key schedule gives forward secrecy and post compromise security at the granularity of group updates.
XMTP nodes store ciphertext so that offline recipients can collect it. At the time of writing they are operated by a single company and retain payloads without a time limit. Decrypted history is stored in the browser.
Normal path
- Encrypts the message
- Stores it until collected
- Decrypts it with its own keys
Fallback path, only if the normal path fails
- Sends the text as written
- Can read it
- Labels it in the chat
- Shows the label
3.1 The fallback relay
When delivery through XMTP fails, typically because the recipient has no XMTP installation yet, the client may submit the message to our server. The server stores it in PostgreSQL and in a Redis sorted set with a seven day expiry until the recipient collects it. Messages on this path are readable by the server. The client labels them on both sides of the conversation.
A guard on the server rejects or reports any message body that is not a sealed envelope of the form hlv1.<algorithm>.<payload>. In its default mode it records that a readable body arrived without recording the body. Rejection is enabled with a configuration flag once clients seal fallback messages.
4. Communities
Communities, channels, members and roles are rows in PostgreSQL, and permissions are enforced by the server on every request. Invite links carry an HMAC-SHA256 tag so they cannot be forged, and can be revoked. Community posts and channel messages are currently stored in readable form on the server.
5. Calls
Calls use WebRTC. Session descriptions and candidates are exchanged through the public PeerJS signalling service. Connectivity uses Google STUN servers and, when a direct path is unavailable, a TURN relay with short lived credentials from the server, when one is configured. The public OpenRelay service is no longer used. Media is encrypted with DTLS-SRTP negotiated between the browsers, so neither signalling nor relays can decode it. A setting forces relay only connections, which prevents the remote party from learning the user's IP address.
6. Payments
Payments are ordinary EVM transactions constructed by the client with wagmi and viem and signed by the user's wallet through EIP-1193 or WalletConnect. Native transfers use value transfers; ERC-20 transfers call transfer(address,uint256). The server never receives a signing key. After confirmation the client sends a receipt into the conversation. Payment requests can be encoded as EIP-681 URIs for display as QR codes.
7. Private payments
The private wallet runs on Aztec Alpha, the Aztec network that settles on Ethereum mainnet, with Aztec's standard token contract and the operator's token HLC. The client derives the secret of a Schnorr account contract from an EIP-712 signature by the user's wallet using HKDF-SHA256, so the same wallet always recovers the same account and the server never holds a spending key. A Private eXecution Environment runs in the browser with encrypted storage, decrypts the user's notes and generates proofs on the device. Before any step that moves value the client rereads the node's identity (L1 chain, rollup version and address, Fee Juice portal and token) and refuses a node that differs from the pins compiled into the build.
A payment from a direct message goes only to the Aztec address the peer announced in that conversation with a Schnorr signature by its account key, which the client reverifies every time value moves. Amounts are capped per token by the operator, and the sender acknowledges that the contracts are unaudited and that the fee payer is public. The transfer calls transfer_private_to_private: the amount and the recipient stay private. The receiver's wallet registers every chat contact with a pinned address as a known sender, so the new note is discovered on its next sync without any manual step.
- Receiver → SenderAnnounces its Aztec address in the DM, signed with its account key.G7: the sender verifies the proof before pinning it
- SenderChecks network pins, the cap for the token and your two acknowledgements.
- Sender → Aztec AlphaProves the private transfer on the device and sends it. The fee is paid in Fee Juice.Amount and recipient private; fee payer public
- Receiver → Aztec AlphaIts wallet already knows chat contacts as senders, so it finds the new note on the next sync.
7.1 Fees
Alpha has no sponsored fee contract, and Ledger Chat sponsors no fee. Every transaction, including the one that creates the account, pays with the account's own Fee Juice: AZTEC bridged one way from Ethereum through the enshrined FeeJuicePortal. A new account waits until a deposit arrives and deploys itself by claiming it in the same transaction. Claim secrets are derived from the wallet signature, so a deposit is recoverable from Ethereum on any device. Paying a fee from one's own balance makes the account the visible fee payer of its transactions.
Because most people hold no AZTEC, a contact can pay the fees for them. The new user shares a link that carries their Aztec address and the hash of a claim secret reserved for this purpose; the contact deposits AZTEC for that address from their own Ethereum wallet. Only the recipient can claim it, and the deposit is public on Ethereum: the contact's address, the recipient's Aztec address and the amount.
8. Ledger Studio
Ledger Studio, the AI workspace, runs on open weight models (GPT-OSS 120B and 20B, Qwen) served by Groq at no cost to users. Conversations are stored on the user's device and sent with each turn; the server keeps none of them. It checks the session, the plan and an allowance counted in tokens, then fits each call to the provider's limit of 8,000 tokens per minute by leaving out the oldest messages first and telling the user. A model that is busy falls back to another. Studio is not end to end encrypted: what is sent to it is processed by the provider.
- Your browser → Our serverSends the chat, its files and settings. The history lives on your device only.
- Our serverChecks your session, plan and allowance, then fits the call to 8,000 tokens per minute.Oldest messages left out first, and you are told
- Our server → GroqCalls an open model (GPT-OSS 120B, 20B or Qwen); a busy model falls back to another.
- Our server → Your browserStreams text, tool calls and artifacts back; usage is counted in tokens, never billed.
9. Device protection
Since 11 November 2026 the PIN screen is off (build flag NEXT_PUBLIC_ENCLAVE_PIN_LOCK); sign in with the wallet is the only requirement. When it is on, access to Ledger Chat on a device is gated by a six digit PIN. The server stores Argon2id of the PIN with a per account salt and a server held pepper, limits concurrent hashing work, and allows eight attempts per five minute window. The PIN gates the interface; it is not used to derive message keys.
10. Threat model
| Adversary | Can | Cannot |
|---|---|---|
| Someone with full control of our servers | Read fallback messages, community posts, attachments, contacts and account data. See who is online. Deny service. | Read direct messages delivered through XMTP. Sign as a user. Move user funds. |
| An XMTP node operator | See encrypted messages, their size and timing, and the conversations they belong to. | Read them. |
| An observer on the user's network | See which services the user connects to and when. | Read any content protected by TLS. |
| Someone with the user's unlocked device | Open Ledger Chat if they know the PIN. Read data stored by the browser with developer tools, even without it. | Sign in on another device without the wallet. |
| Someone who tricks the user into scanning their QR code | Ask to be linked. The phone names the computer and asks for confirmation; once linked, read and send messages until unlinked. | Obtain the wallet, or any signature the user does not approve on the phone. |
| Malware on the user's device | Everything the user can see. | Nothing prevents this. No software only design can. |
11. Scaling
Web servers are stateless. PostgreSQL is reached through a connection pooler, with a direct connection reserved for migrations. Online status is written to Redis with an expiry rather than to the database. Remaining single instance state, such as device linking codes held in memory, and polling in parts of the interface are the current limits on horizontal scaling.
12. Open problems
- Removing the readable fallback path, by sealing fallback messages on the client or by ensuring both parties have XMTP installations.
- Encrypting community content end to end, for example as MLS groups.
- Encrypting attachments before upload.
- An independent audit of the contracts and a penetration test of the application.
- Self hosted call signalling, so that call setup does not depend on a public service.
- A private fee payer on Aztec, so that a user's transactions cannot be linked to each other through the public fee payer.
- Post quantum key exchange for linked devices and messages, for example hybrid ML-KEM, once MLS and the browser support it.
