# WZP Protocol Specification (one-page reference)

> Distilled from `docs/ARCHITECTURE.md` and the `wzp-proto` crate. Authoritative wire details live in `crates/wzp-proto/src/packet.rs`.
>
> **Status:** v2 is the deployed protocol (audio + video, 16 B header, MediaType, u32 seq). v1 clients are rejected with `Hangup::ProtocolVersionMismatch`.

## Layer summary

| Layer | WZP | FaceTime equivalent |
|---|---|---|
| Transport | **QUIC datagrams** (Quinn), PLPMTUD 1200 → 1452 | RTP/SRTP over UDP, ICE |
| Signaling | `SignalMessage` (bincode) over a QUIC stream, SNI = hashed room name | APNs-tunneled binary plist |
| Identity | Ed25519 + X25519 from BIP39 seed; fingerprint = SHA-256(pubkey)[..16] | IDS RSA + ECDSA per device |
| Key agreement | X25519 DH + HKDF, Ed25519 signatures, rekey every 65,536 packets | Per-call DH signed by IDS keys |
| Bulk crypto | ChaCha20-Poly1305, 64-packet sliding anti-replay | SRTP (AES-CTR + HMAC) |
| Loss recovery | **RaptorQ FEC + Opus DRED + classical PLC** | NACK / PLI + reference-picture selection |
| Adaptive | 3-tier hysteresis (Good / Degraded / Catastrophic) + continuous DRED tuner | Per-frame bitrate ladder |
| Topology | SFU rooms + inter-relay federation + P2P via ICE | Mesh ≤ ~3, SFU above, Apple relays |
| Header | 16 B `MediaHeader` v2 / 5 B `MiniHeader` (49 of 50), 4 B `QualityReport` trailer | RTP 12 B + extensions |

## Distinctive choices

- **QUIC datagrams instead of raw UDP + SRTP.** Brings TLS 1.3, PLPMTUD, path migration, and ACK-based RTT/loss estimation for free.
- **Continuous DRED tuning.** Maps live `(loss%, RTT, jitter)` to a continuous Opus DRED lookback window. Most stacks treat DRED as discrete tiers.
- **MiniHeader (5 B for 49/50 packets).** Saves ~11 B/packet ≈ 550 B/s/stream at 50 pps vs. the full 16 B header.
- **E2E-preserving SFU.** The relay forwards encrypted datagrams; it never decrypts media. Room membership uses SNI = `hash(room_name)`.
- **Codec coordination via `QualityReport` trailer.** Receivers attach 4-byte loss/RTT/jitter/cap to media packets; the SFU broadcasts `QualityDirective` so all senders in a room converge on the same tier.

## Wire format (current — v2)

### `MediaHeader` v2 (16 bytes, byte-aligned)

```
Byte 0:      version        (u8)   0x02
Byte 1:      flags          (u8)   [T:1][Q:1][KeyFrame:1][FrameEnd:1][reserved:4]
Byte 2:      media_type     (u8)   0=audio, 1=video, 2=data, 3=control
Byte 3:      codec_id       (u8)   0-255 (see codec table)
Byte 4:      stream_id      (u8)   simulcast layer; 0=base
Byte 5:      fec_ratio      (u8)   0..200 → 0.0..2.0
Bytes 6-9:   sequence       (u32 BE)
Bytes 10-13: timestamp_ms   (u32 BE)
Bytes 14-15: fec_block_id   (u16 BE)
```

| Field | Bits | Meaning |
|---|---|---|
| version | 8 | Must be `0x02`; v1 clients receive `Hangup::ProtocolVersionMismatch` |
| T (bit 7 of flags) | 1 | 1 = FEC repair packet |
| Q (bit 6 of flags) | 1 | QualityReport trailer present |
| KeyFrame (bit 5 of flags) | 1 | Packet belongs to a video I-frame |
| FrameEnd (bit 4 of flags) | 1 | Last packet of an access unit |
| reserved (bits 3-0 of flags) | 4 | Must be zero |
| media_type | 8 | 0=audio, 1=video, 2=data, 3=control |
| codec_id | 8 | See codec table (widened from v1's 4-bit field) |
| stream_id | 8 | Simulcast layer; 0=base layer |
| fec_ratio | 8 | 0..200 → 0.0..2.0 |
| sequence | 32 | Monotonically increasing packet seq (not reset by rekey) |
| timestamp_ms | 32 | ms since session start. Monotonic across the full session; **not reset by rekey** |
| fec_block_id | 16 | FEC source block ID |

### Codec table

| ID | Codec | Bitrate | Sample | Frame |
|---|---|---|---|---|
| 0 | Opus 24k | 24 kbps | 48 kHz | 20 ms |
| 1 | Opus 16k | 16 kbps | 48 kHz | 20 ms |
| 2 | Opus 6k | 6 kbps | 48 kHz | 40 ms |
| 3 | Codec2 3200 | 3.2 kbps | 8 kHz | 20 ms |
| 4 | Codec2 1200 | 1.2 kbps | 8 kHz | 40 ms |
| 5 | ComfortNoise | 0 | 48 kHz | 20 ms |
| 6 | Opus 32k | 32 kbps | 48 kHz | 20 ms |
| 7 | Opus 48k | 48 kbps | 48 kHz | 20 ms |
| 8 | Opus 64k | 64 kbps | 48 kHz | 20 ms |
| 9 | H.264 Baseline | — | — | — |
| 10 | H.264 Main | — | — | — |
| 11 | H.265 Main | — | — | — |
| 12 | AV1 Main | — | — | — |

### `MiniHeader` v2 (5 bytes, compressed — 49 of every 50 packets)

```
[FRAME_TYPE_MINI = 0x01]
Byte 0:    seq_delta           (u8)
Bytes 1-2: timestamp_delta_ms  (u16 BE)
Bytes 3-4: payload_len         (u16 BE)
```

Full header sent every 50th packet to resync.

### `TrunkFrame` (batched, relay-internal)

```
[count: u16]
  [session_id: 2][len: u16][payload: len]   × count
```

Up to 10 entries or PMTUD-discovered MTU; flushed every 5 ms.

### `QualityReport` (4 bytes, optional inline trailer)

```
Byte 0: loss_pct          (0-255 → 0-100%)
Byte 1: rtt_4ms           (0-255 → 0-1020 ms)
Byte 2: jitter_ms         (0-255 ms)
Byte 3: bitrate_cap_kbps  (0-255 kbps)
```

### Version negotiation

- `version=0x02` in `MediaHeader` is a hard switch — there is no fallback negotiation.
- Both endpoints must speak v2. A v1 peer receives `Hangup::ProtocolVersionMismatch` immediately.
- Relays inspect only `version` and `media_type`; they never downgrade or translate between versions.

## Session lifecycle

```
Idle → Connecting → Handshaking → Active ⇄ Rekeying → Closed
```

- `CallOffer { identity_pub, ephemeral_pub, signature, profiles }`
- `CallAnswer { identity_pub, ephemeral_pub, signature, chosen_profile }`
- `session_key = HKDF(X25519_DH(eph_a, eph_b), "warzone-session-key")`
- Rekey every 65,536 packets via fresh ephemeral DH.

## SFU forwarding rules

1. Fan-out to all room participants except the sender.
2. Failed sends are skipped; forwarding is best-effort.
3. The relay never decrypts media.
4. With trunking on, packets to the same receiver are batched (flush 5 ms).
5. `QualityDirective` is broadcast when the room-wide tier degrades.

## Adaptive quality (audio, today)

| Tier | Codec | FEC | Frame |
|---|---|---|---|
| Good | Opus 24 k | 20 % | 20 ms |
| Degraded | Opus 6 k | 50 % | 40 ms |
| Catastrophic | Codec2 1200 | 100 % | 40 ms |

Hysteresis: 3 reports to downgrade (2 on cellular), 10 to upgrade.

## NAT traversal (Phase 8)

- Candidate types: Host, Port-mapped (NAT-PMP / PCP / UPnP), Server-reflexive (STUN), Relay.
- Hard-NAT port prediction with `classify_port_allocation()` → `predict_ports()` → `HardNatProbe` signal.
- Mid-call re-gather: `CandidateUpdate { generation }`.