Wire format

Conventions

• Integers in the packet header, the sealed message and voice frames are big-endian.
• A mesh packet is self-framing: the same bytes travel over Bluetooth notifications, Bluetooth writes and TCP, chunked to each link's size and reassembled by the receiver.

Mesh packet

A 41-byte header followed by the payload.

Decoding fails on fewer than 41 bytes, a wrong magic, a version other than 1, an unknown kind, a length over 8,192, or a payload shorter than its declared length. The length is checked before any payload is copied.

Kinds

Contact card

The hello payload, and the form in which contacts are stored, is a JSON object:

{
  "signingKey": "<32-byte Ed25519 public key, base64>",
  "agreementKey": "<32-byte X25519 public key, base64>",
  "displayName": "Ama"
}

A card is valid when both keys are 32 bytes.

Fingerprint and number

fingerprint = SHA-256(signingKey || agreementKey)[0..8]
number      = Crockford base 32 of fingerprint[0..5], grouped 4-4

The alphabet is 0123456789ABCDEFGHJKMNPQRSTVWXYZ. When parsing, input is uppercased, O becomes 0, I and L become 1, and hyphens and spaces are ignored. ABCD-1234, ABCD-0000 and WXYZ-1234 are reserved and never issued.

Sealed message

The payload of a direct or receipt packet.

payload = encapsulatedKey (32) || HPKE ciphertext (inner || 16-byte tag)

Inner plaintext

The padded plaintext is a 4-byte length followed by the plaintext and zeros up to the next bucket of 256, 512, 1,024, 2,048, 4,096 or 8,192 bytes. The signature covers the unpadded plaintext.

A sealed message therefore adds 176 bytes to its padded plaintext: 32 for the encapsulated key, 128 for the sender's keys and signature, and 16 for the tag. Because the whole payload must fit 8,192 bytes, the largest bucket that can be delivered is 4,096.

Content types

The first byte of the plaintext says what the message carries.

Call signalling bodies are UTF-8 text separated by single spaces. A nonce is eight characters. A direct audio service name has the form call- followed by eight characters.

Voice frame

The payload of a voice packet over the mesh, and the whole datagram over the direct UDP path.

On the mesh a 20 ms frame is 41 bytes of packet header, 4 of sequence number, about 60 of Opus at 24 kbit/s and 16 of tag: 121 bytes, or 48.4 kbit/s at 50 frames a second.

Identity file

Stored sealed at rest (see Security and privacy). The serialised form:

Bluetooth identifiers

The advertisement carries only the service UUID. A sender writes to the peer's inbox without response when it reached the peer as a central, and notifies through its own outbox when the peer subscribed to it. Chunks are sized to fit both limits.

Bonjour service types