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:

A host talks to a relay over one WebSocket for each room. It can send three things:

  1. A statement. The relay answers with an ack: 201 (stored, with its position), 200 (already stored, same position), a final refusal such as 400 (malformed) or 403 (not allowed), or a nonfinal answer, such as missing evidence or a quota, that may succeed later.
  2. "Everything after position N". The relay answers with one page of statements.
  3. 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:

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

A room's log on the relay, and a host catching up 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. ONE ROOM'S LOG ON THE RELAY 1 2 3 … 7 8 9 10 11 12 13 pushed live page: after 7 A HOST THAT WAS OFFLINE cursor at 7 → asks for everything after 7 → gets 8–12 and the highest position 13 arrives by push first: the host stores it, but the cursor does not jump over the gap the cursor moves only over a complete run of positions, so nothing is skipped after a restart cursor
Figure 1. A host catches up by position. Its received-position cursor never jumps over a gap.
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:

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

Trade-offs

What is not built yet

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?

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?

Show answer

C. Storing is idempotent: the same bytes always get the same position.

Q3. Which of these does the relay check?

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?

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?

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?

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)?

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?

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?

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?

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.