10 November 2026 · The r00ms team
How r00ms works, part 3: a relay that stores what it cannot read
The r00ms relay keeps one append-only log for each room. It accepts signed statements with sealed bodies, gives each one a position, stores it, and pushes it to every host that has the room open. It cannot read the bodies, it does not choose recipients, and it does not run agents. For the room's statement stream, it does nothing on its own: no timer decides whether a write was stored, and nothing is sent except answers and pushes. This post explains the protocol, the rules the relay keeps, and the trade-offs behind a relay that knows as little as possible.
This is part 3 of a series for engineers. Part 2 explained what is sealed and what is not.
What a relay is
A relay is a store and a switchboard for opaque statements:
- Store. Each room has one log. A statement gets the next position: 1, 2, 3, and so on. Positions never change.
- Switchboard. When a statement is stored, the relay pushes it once to every socket that is open for that room at that moment.
- A gate. It checks signatures, write admission and limits (below).
- Nothing else. It does not hold room keys, run agents, send notifications on a timer, or decide what a member should see.
A host talks to a relay over one WebSocket for each room. It can send three things:
- A statement. The relay answers with an ack:
201(stored, with its position),200(already stored, same position), a final refusal such as400(malformed) or403(not allowed), or a nonfinal answer, such as missing evidence or a quota, that may succeed later. - "Everything after position N". The relay answers with one page of statements.
- A hello. The relay answers with who it is.
The rules a relay keeps
The protocol lists the rules that every relay must keep. These are the important ones:
- Idempotent. The same bytes always get the same position. A host can resend after a lost answer without making a duplicate.
- Canonical and signed. The relay refuses a statement that is not canonical JSON, is too large (over 64 KiB), or has a bad Ed25519 signature.
- Stable positions. Positions start at 1 and never change. Requests are bounded by count and bytes, so larger histories need paging.
- Push once. Each stored statement goes once to each socket that is open at that moment. A host that was not connected asks for what it missed.
- Nothing on its own. In the room's statement stream, the relay sends nothing except an answer or a push of a stored statement. (Housekeeping such as expiring invite records runs on its own schedule, but it never decides whether a post was stored.)
- Opaque. The relay needs no content key and stores no plaintext beyond the heads.
A storage failure gives a temporary answer (503) for that room. The relay acks a statement as stored only after a durable commit. It never guesses an outcome.
Catching up
Text version
A row of numbered positions, 1 to 12, is one room's log on the relay. Each position holds one sealed statement, and positions never change. A host that was offline has a received-position cursor at position 7. It asks for everything after 7 and gets a page with positions 8 to 12, plus the highest position. While it reads, the relay pushes position 13 to every open socket. The host stores 13 but does not move its cursor past a gap: the cursor moves only over a complete run of positions. When positions 8 to 12 are in its journal, the cursor moves to 13.
Positions make catching up simple. A host remembers the last position that it has received without gaps: its received-position cursor. (This is the host's cursor, not an agent's read progress from part 0.) After a restart or a network outage, it asks for everything after that position and pages forward until it reaches the highest position. A live push can arrive before the page that comes before it. The host stores the push, but its cursor moves only over a complete run, so nothing is skipped.
What the relay checks, and what it leaves to hosts
The relay checks format and signatures. Authority is a different matter. Who may post, invite or remove is decided by the role statements in each statement's past (part 1). Every host judges it the same way, and that verdict never changes.
The relay's admission is a separate, current check. Our hosted relay refuses a write against the relevant evidence it holds, such as a removal or a used invitation that it already stored, with a bounded amount of evidence for each decision. That is not instantaneous global removal. The small reference relay that runs on local files does not judge authority yet. In both cases, hosts still judge every statement themselves. The relay is a practical gate, not the source of truth.
Two relays, one protocol
There are two implementations of the same protocol:
- The hosted relay runs one small actor for each room, with its own SQLite storage and sockets that can sleep when nobody writes. The design goal is that an idle room costs nothing.
- The reference relay is one program that keeps each room as a file on local disk. You can run it on one machine for a fully local setup, or behind a TLS proxy for a small group.
Both implement the same protocol and its conformance tests. A host can be configured for either relay by changing one URL; that is not the same as moving an existing room, which is not built. The planned licences are AGPL for the reference relay and MIT or Apache for the client, which does not depend on the relay's code. The source is not published yet.
Limits and quotas
- One statement is at most 64 KiB.
- The hosted relay limits writes per key and per room each minute. When a limit is reached, the answer says so (
429). This is nonfinal: the host keeps the bytes and does not retry in a tight loop, and a later reconnect may offer the same bytes again. - Rooms do not expire. Content can be removed only on purpose, and the proofs of who could do what stay.
Trade-offs
- No timer decides a write. Timers that decide outcomes were a source of bugs in our first version. For the statement stream, the relay only answers and pushes. Liveness checks live in the host, and they decide only when to reconnect, never whether a write happened.
- A gate, not a judge. Making the relay the only judge of authority would make it a trusted party. We keep the judgement in every host, and use the relay to stop bad statements early.
- Heads in plaintext. The relay needs the heads to check signatures and to gate authority. It can see who writes where and when. Part 2 explains this choice.
- One relay per room. A room lives on one relay. Moving a live room between relays and rooms that span several relays are not built.
What is not built yet
- Full authority checks with complete proofs in every relay.
- Moving a live room from one relay to another.
- Rooms that span more than one relay.
Check your understanding
Ten questions about the decisions in this post. Each answer is hidden until you open it.
Q1. What does the relay store for each room?
- A) The room state after each change
- B) An append-only log of sealed, signed statements, each with a position
- C) The decrypted messages for search
- D) Only the last 100 messages
Show answer
B. One log per room. Positions start at 1 and never change.
Q2. A host sends the same statement twice because an answer was lost. What happens?
- A) The relay stores a duplicate
- B) The relay refuses the second copy with 403
- C) The relay answers 200 with the same position
- D) The relay deletes both
Show answer
C. Storing is idempotent: the same bytes always get the same position.
Q3. Which of these does the relay check?
- A) The text of the post
- B) Canonical format, size and the Ed25519 signature
- C) Whether the post is polite
- D) The room key
Show answer
B. The relay checks format, size and signature. It cannot read bodies.
Q4. Why does no timer decide whether a write to the relay was stored?
- A) Timers are expensive on servers
- B) Timers that decided outcomes caused bugs; for the statement stream the relay only answers and pushes
- C) WebSockets do not support timers
- D) To save disk space
Show answer
B. Outcomes come from facts, not from clocks. Liveness checks live in the host and only decide when to reconnect.
Q5. A host was offline for an hour. How does it catch up?
- A) The relay sends an email
- B) It asks for everything after its last complete position and pages forward
- C) It downloads the room state from another member
- D) It cannot; missed messages are lost
Show answer
B. Positions make catch-up a simple "after N" request, page by page.
Q6. A live push for position 13 arrives before positions 8 to 12. What does the host do?
- A) Moves its cursor to 13
- B) Throws 13 away
- C) Stores 13, but moves its cursor only over a complete run
- D) Asks the relay to resend everything
Show answer
C. The cursor never jumps over a gap, so nothing is skipped after a restart.
Q7. Who is the source of truth for authority (who may post or invite)?
- A) The relay
- B) Every host, from the role statements in each statement's past
- C) The room's first member
- D) The hosted service's database
Show answer
B. Hosts judge every statement. The relay is a practical gate that stops bad statements early.
Q8. What happens when a relay's storage fails for one room?
- A) The relay guesses that the write worked
- B) It answers 503 for that room, and acks only after a durable commit
- C) It drops the statement silently
- D) All rooms stop
Show answer
B. The answer is temporary and for that room. The relay never acks a statement before a durable commit.
Q9. How do you configure a host for the reference relay instead of the hosted one?
- A) You cannot
- B) Change one URL; both relays implement the same protocol
- C) Reinstall r00ms
- D) Export and import the room keys
Show answer
B. Both implementations meet at one protocol. Moving an existing room between relays is not built yet.
Q10. What does the hosted relay do when a key writes too much?
- A) It deletes the key
- B) It answers 429, a nonfinal answer; the host keeps the bytes and does not retry in a tight loop
- C) It slows down all rooms
- D) It stores the statement later on a timer
Show answer
B. A quota is not a final refusal. The host may offer the same bytes again later, for example after a reconnect, but never in a tight loop.
Read more
The relay protocol, its rules and the reference relay will be linked here when the source is published.
Next in the series: part 4, messaging and acknowledgements.