Relay protocol

What travels between a node and its relay, and between two federating relays: the envelope layouts, the error codes, the per-leg overheads, and the fields relays, the signed map, the snapshot and the journal carry for the relay directory and federation. The relay never sees payload plaintext — a forwarded Atlas datagram is encrypted between the two peers whatever it carries.

Frames

Three outer message types exist. A client opens a session with Noise IK against the relay's pinned static key (RelaySessionInit 0x0D, RelaySessionResp 0x0E); afterwards both directions exchange RelayFrame 0x0F: a u64 nonce and the AEAD ciphertext of one envelope. Relays answer STUN on the same UDP port, by default 3478.

The outer header carries the node's wire number. A relay server carries two wires on its own sessions, the current one and the one before it — today 3 and 2 — and answers each client on the version that client's init spoke, so the hosted relays can run ahead of every customer fleet. A datagram on wire 1 is dropped unanswered, counted protocol_refused in the heartbeat, and its sender named once in the log. The relay contract is 2: contract 1 is the pre-federation set (Forward, Deliver, Keepalive, Error), and 2 adds ForwardVia, Close, DeliverVia, the federation hello, RelayForward and RelayError. nexus-atlas-relay --version prints both: nexus-atlas-relay 1.0.0+4d54d40 · wire 3, 2 · relay 2.

Envelope layouts

The plaintext inside a RelayFrame; keys are 32-byte Curve25519 static public keys.

Forward      0x01 | dest[32] | ptype[1] | payload…                  client → relay
Deliver      0x02 | src[32]  | ptype[1] | payload…                  relay  → client
Keepalive    0x03                                                   both
ForwardVia   0x04 | dest[32] | via[32] | ptype[1] | payload…        client → relay
RelayForward 0x10 | src_client[32] | dst_client[32] | hop[1] | ptype[1] | payload…
                                                                    relay  → relay
RelayError   0x11 | code[1] | dst_client[32] | from_relay[32] | src_client[32]
                                                                    relay  → relay
Error        0x7F | code[1] | dest[32]                              relay  → client

The via hint

A Forward may carry a via hint: the static key of the relay the destination is homed on. Without a hint it is a plain Forward (kind 0x01); with one it is kind 0x04. A relay without federation support (relay contract 1) does not know that kind and drops the frame silently, so a hinted frame is never misread as a plain Forward.

1. The node's relay R1 receives ForwardVia{dest, via}. If R1 holds dest itself, it delivers locally. Otherwise, with federation on and via listed in its signed relay map, it wraps the frame as RelayForward with hop = 0 and sends it over its Noise IK session to the via relay R2, opening that session if needed.
2. R2 delivers it to the destination as an ordinary Deliver{src} — the destination sees nothing new — or answers RelayError on the same session.
3. R1 turns a RelayError into the usual Error{code, dest} for the sender. RelayError names src_client so R1 can address the error without keeping per-frame state.

Exactly one relay-to-relay hop: a RelayForward is delivered or refused, never sent on, and one arriving with hop != 0 is dropped. A RelayForward from a relay key the signed map does not list is dropped as well.

Error codes

On the relay-to-relay leg, a far relay that does not federate answers RelayError{FEDERATION_OFF}, which the first relay reports to its client as VIA_UNKNOWN, so FEDERATION_OFF at a client always means its own relay. atlasd answers codes 3 and 4 by sending plain Forwards on that relay for 60 s before retrying the hint.

Overheads

The relay-to-relay leg is the largest of the three, so a node with federation on caps its fragment payload so that leg stays one 1500-byte IPv4 datagram:

Atlas datagram = payload + 56;  + 99 relay → relay leg;  + 28 UDP/IPv4
1500 − 183 = 1317-byte fragment payload

Inter-relay sessions

• Noise IK between the two relays' static keys, which come from the same Ed25519-signed relay map clients use, verified with the same pinned key.
• Opened on the first via naming a relay, keepalived every 20 s, declared dead after 45 s of silence (and handshaken again if still in use), closed after 5 minutes unused.
• At most max_pairs outbound and max_pairs inbound at once; the least recently used idle session makes room.
• The sender's per-session forward quota is charged as for any Forward; on top, each relay pair has a per-direction pair_mbps bucket on the sending relay and on the receiving one.

Heartbeat and map additions

A relay registered with the control plane reports itself in a heartbeat; federation adds three things to it and one to the signed map.

Snapshot additions

In GET /api/stats (see the REST API):

One relay link carrying a federated path, abbreviated:

"relay": {
  "server": "203.0.113.10:3478",
  "region": "eu-central",
  "state": "established",
  "rtt_ms": 18.4,
  "elected": true,
  "rank": 1,
  "bootstrap": false,
  "via": {
    "server": "198.51.100.20:3478",
    "pubkey_short": "c41e..07ba",
    "region": "na-east",
    "city": null
  },
  "frames_via": 18234,
  "federation_errors": 0
}

Journal codes

Read them with GET /api/journal?code=… (see the journal endpoint).