# Wire format

> The Weald envelope, the event kinds and the error registry, with the CDDL grammar and the reconciliation algorithm published in full.

Source: https://getweald.com/docs/protocol/wire
Last modified: 2026-08-04

---

## The envelope

Last updated 2026-08-04

The relay stores one unit, a deterministic CBOR envelope. Its header carries a protocol version, an encryption mode, an opaque group id, an MLS epoch, a BLAKE3 content address and the ciphertext. Nothing else about a message is legible to the relay.

## What a relay validates

A relay checks the version, the encryption floor, that the group exists, the content address, the size, and that the authenticated device session sits inside the group's access set. That is the complete list.

The encrypted author field is deliberately not used for that check. Authorization is a property of the connection and the access set, not a claim inside a payload the relay cannot verify.

## Ordering and duplicates

Sequence numbers are per group, monotonic, and assigned by the relay inside the transaction that inserts the envelope. A duplicate content address is resolved before the counter is touched, so a retry after a dropped connection returns the original sequence and takes no lock.

Nothing above the transport reads a sequence number for correctness, so a gap left by a rolled-back transaction is legal and clients tolerate one. Reconciliation works over the space that exists rather than over a dense range.

## Documents

- Wire protocol. The envelope, the event kinds, the sync algorithm and the transport.
- CDDL grammar. The machine-checkable grammar for every frame and every envelope.
- Error registry. Every code a relay may return, with the condition that produces it.
- Reconciliation. Range-based set reconciliation, and the bound on what it exchanges.
- Channels. Channel state, ordering and the documents a workspace carries.
- Retention. Checkpoints, snapshots and the rules for deleting below a barrier.

## Version negotiation

A client offers its maximum protocol version in its connect frame and the relay selects the lower of the two ceilings, signing the selection into the challenge the client answers. A downgrade therefore breaks the signature rather than the connection.

Version 4 is current and version 1 is still served. Version 2 adds two frames and one event kind and changes nothing about the envelope, so a version 1 client keeps working and is never sent a frame it does not know. A version error aborts the connection rather than continuing, because a client that silently accepts a floor below its own has no floor.

## Errors

Every error carries a class, a stable code, and where relevant the current state hash so a client can rebase rather than guess. The five classes are retry, reject, denied, quota and version, and the full registry is published with the condition that produces each code.

A send never returns retry for contention, only for infrastructure. There is no server-side head chain to contend over, which is why a busy group does not look like a broken one.