Sync Groups

A Sync Group is the set of devices that share data. Every blob sent by any member is delivered to every other member. Membership is not implicit — it is defined by a signed document called the Group Manifest, which every member holds and every member can update.

TL;DR

  • A group is its manifest. No central registry, no server-side state.
  • Any member can update it. Authority is membership; there is no admin.
  • Updates converge by version. Higher version wins. No consensus protocol required.
  • The relay sees nothing. It routes blobs by recipient public key — it has no concept of “group.”

The Group Manifest

The Group Manifest is the authoritative, versioned record of who belongs to a Sync Group. It carries a stable Group ID, a monotonically increasing version number, the member list (each member’s noise + signing public keys), and an Ed25519 signature from the member who issued this version.

Any current member can issue a new manifest version. There is no coordinator, no device with elevated authority. Authority derives from membership — if you are in the current manifest, you can issue the next one.

For the byte-level structure, see Group Manifest in the component reference.

Validity and Convergence

When a device receives a new manifest, it accepts it if:

  1. The signature is valid.
  2. The issuer is a member of the device’s current manifest — the update came from someone who was legitimately a member at the time of issuance.
  3. The version number is strictly higher than the current version.

If two members simultaneously issue conflicting updates — A removes B while C adds D — both propagate. The higher version wins. Membership converges without any consensus protocol.

Sending to the Group

When a device calls send(), trueseal-sync reads the current Group Manifest and produces one encrypted blob per member, each addressed individually to that member’s noise public key. The relay receives N independent blobs and routes each to the appropriate Inbox.

The relay has no concept of the group. It sees N blobs addressed to N public keys. It does not know they are related, or that the senders and recipients share a membership.

Receiving and Filtering

Every inbound blob is verified against the current Group Manifest. If the sender’s signing public key is not in the manifest, the blob is silently discarded — even if the Ed25519 signature itself is valid.

This is how soft removal takes effect. When a device is removed from the manifest, remaining members update their local copy and begin discarding that device’s messages. The removed device can still push blobs to the relay — the relay enforces nothing about sender identity — but every recipient discards them silently on receipt.

Joining the Group

A new device joins through the Pairing ceremony. Once the initiating device accepts the request, two things happen:

  1. The current manifest is sent to the new device, giving it an immediate complete view of the group.
  2. A new manifest version is issued that includes the new device, signed by the admitting device, and pushed to every existing member.

There is no convergence lag — every existing member receives the same authoritative document.

Offline Members

A device that is offline when a manifest update is issued will receive it when it reconnects, via the relay’s deferred delivery. Until then it operates with a stale manifest:

  • It will not send to newly added members.
  • It will not filter messages from newly removed members.

This is narrow and temporary. The moment the device reconnects, it receives the queued update and converges immediately.