Skip to content

Peer-hosted matches (p2p_host): wire contract

Contract version: p2p-wire/1 · Status: frozen for phase P1 (design 31). Any change after the first commit of this file is listed in the changelog at the bottom, never edited silently.

Audience: the Godot SDK (addons/otomo) implementing host and client modes, and the otomo services (Allocator, Gameplay Proxy, Matchmaker) implementing the other side. Everything here is normative; "MUST", "SHOULD" and "MAY" have their RFC 2119 meaning.

Unchanged and not repeated here: the OTJ1 client handshake and its OTOK/OTNO 1..4 answers (design 14 §8), the placement-claim signature, iss/aud/kid/JWKS rules (design 14 §5), ENet on the client. A non-host client of a relayed match does exactly what a client of a dedicated match does, plus the OTNO 5 retry in §4.3.


1. Roles and the one rule that matters

  • Host: one player's client. It runs the authoritative simulation (a listen server). It reaches the Gameplay Proxy over one UDP socket (the "host leg") and multiplexes every other player on it with the framing of §5.
  • Client: every other player. It reaches the proxy over its own UDP socket (a "client leg") with raw ENet datagrams, exactly like a dedicated match.
  • Proxy: the Gameplay Proxy in relay mode. It never parses, rewrites or logs game payloads, never tells a host a client's address or a client the host's, and never queues or retransmits: over-budget traffic is dropped.

The proxy's public UDP address is the same endpoint a dedicated match uses. Relay and dedicated traffic share the port.

2. Discovering your role: the descriptor

A p2p_host placement is described with the same descriptor shape as otomo-udp, plus two fields:

{
  "transport": "p2p_host",
  "region": "default",
  "endpoint": {"address": "play.example.com", "port": 27000},
  "room": "room-0f3c9a1b2d4e5f60718293a4b5c6d7e8",
  "host_player_id": "8a7d6c5b-4e3f-4a2b-9c1d-0e1f2a3b4c5d",
  "proxied": true
}
Field Type Meaning
transport string "p2p_host". A client with no p2p support MUST refuse the join (design 22).
endpoint.address, endpoint.port string, int the proxy. Both roles send to it.
room string the room id, room- + 32 lowercase hex. It is also the claim's srv.
host_player_id string (UUID, lowercase) the player chosen to host. Role = host iff this equals your own player id, else client.
proxied bool always true.

Where the descriptor reaches the SDK:

  • Matchmade match: GET /api/player/match and POST /api/player/match/ticket answer {"match_id", "status", "transport", "region", "descriptor": {…}, "credential": {…}}; the descriptor object is the one above, verbatim from the Allocator.
  • Party launch (Session): not wired in P1 (see docs/p2p-implementation-notes.md); a party launch is always a dedicated or photon placement until Session's launch rules block lands.

3. Getting a claim

3.1 Client claim

Unchanged: POST /api/player/match/ticket with no body or {} → credential.value is a placement claim (role absent or "client").

3.2 Host claim (new)

The host generates an Ed25519 key pair before asking for its claim, keeps the private key in memory for the life of the match (it is needed again to resume, §6), and sends the public key:

POST /api/player/match/ticket
Authorization: Bearer <player access token>
Content-Type: application/json

{"host_key": "<base64url, unpadded, of the 32-byte raw Ed25519 public key>"}

Answer: the same 200 body as §3.1; credential.value is a host claim. Errors (COM-5 envelope {"error":{"code","message","request_id"}}):

Status code Meaning
400 invalid_request host_key is not 43 base64url chars decoding to 32 bytes
403 not_host you sent host_key but you are not this room's host
409 host_key_required you are the host of a p2p_host match and sent no host_key; the host never gets a client claim
409 not_p2p host_key sent for a match that is not p2p_host
404 / 409 no_match / match_ended unchanged

The Session party route POST /api/player/party/launch/ticket does not take host_key in P1: no party launch is p2p_host yet (see the changelog).

3.3 Claim payload (JWT, EdDSA)

Existing fields: iss, sub (player id), aud, exp (60 s), iat, jti (single use), alloc, srv. New fields:

Claim Present on Value
role host claims; MAY be absent on client claims "host" or "client"; absent means "client"
cnf host claims only {"jkt": "<RFC 7638 JWK thumbprint of the host public key>"}, i.e. base64url-unpadded SHA-256 of {"crv":"Ed25519","kty":"OKP","x":"<base64url pubkey>"}
region every claim from a P1+ Allocator the Allocator's region. The proxy refuses a claim whose region differs from its own (when it has one configured)

The SDK treats the claim as opaque and never needs to parse it.

3.4 Signed roster and the placement keys

A host holds no Session or Economy key, so otomo tells it, signed, who may play and what each player owns. Every player of the match (host and peers) reads the same document:

GET /api/player/match/{match_id}/roster        (player token; the caller's own live p2p_host match)
200 {"roster": {...}, "payload": "<base64url>", "kid": "<kid>", "signature": "<base64url>"}
  • payload is the exact JSON the Allocator signed; signature is detached Ed25519 over those bytes with the placement-claim key named kid. A verifier checks the signature over the decoded payload bytes and reads the roster from them; roster is a readable copy and is never trusted when payload is present. (Earlier SDKs re-canonicalised roster; that form is not produced any more because Go and .NET encode some characters differently.)
  • The roster: {"match_id", "room", "host_player_id", "expires_at" (unix seconds, 2 h), "members": [{"player_id", "display_name", "loadout": [], "owned_spells": [item ids]}]}. Members are the match's formed roster; names come from Session; owned_spells lists the held items whose id starts with the Matchmaker's MATCHMAKER_ROSTER_ITEM_PREFIX (Elemaniacs: spell.); room and host_player_id come from the Allocator, never from the caller. loadout is empty in P1.
  • Errors: 404 no_match (not the caller's live match), 409 match_ended, 409 not_p2p, 409 host_not_in_roster / no_host, 502 roster_unavailable (retry).
  • Keys: the gateway publishes the Allocator's JWKS at GET {gateway}/p2p/v1/placement-keys (public, the same document as the Allocator's /.well-known/jwks.json; the gateway serves no /.well-known/ path). Hosts verify peer tickets with it, everyone verifies the roster with it. Fetch it before verifying anything: an empty cache answers "unknown kid".

4. Handshakes (all big-endian, magic = 4 ASCII bytes)

Datagram Direction Layout Size
OTJ1 client → proxy "OTJ1" · u16 len · claim 6 + len
OTOK proxy → client "OTOK" 4
OTNO proxy → either "OTNO" · u8 reason 5
OTH1 host → proxy "OTH1" · u16 len · claim · pubkey[32] 38 + len
OTCH proxy → host "OTCH" · nonce[16] 20
OTHP host → proxy "OTHP" · nonce[16] · sig[64] 84
OTHK proxy → host "OTHK" · leg_token u64 · max_slots u8 13
OTP1 anyone → proxy "OTP1" · nonce[8] · zero padding to exactly 64 bytes 64
OTP2 proxy → prober "OTP2" · nonce[8] 12

No reply is larger than the datagram that caused it.

4.1 Refusal reasons (OTNO byte)

Byte Name Sent for SDK action
1 invalid bad claim/signature/iss/aud, wrong role for the datagram, sub ≠ room host (OTH1), jkt ≠ thumbprint(pubkey), region mismatch, bad proof (OTHP), proxy session limit give up; fetch a new claim only if you changed something
2 expired claim past exp + 5 s fetch a new claim, retry
3 reused jti already accepted from another address fetch a new claim, retry
4 unknown server srv not in the proxy's directory (room ended or never existed) stop; the match is over or not placed
5 host not ready (new) client OTJ1 for a room whose host leg is not attached (waiting or in grace) retry the same OTJ1 every 500 ms for up to 20 s (the claim is not consumed by this refusal)
6 room full or closed (new) client: every slot taken or room closed; host: another key already hosts it, room closed, or the proxy's room cap is reached stop

4.2 Host handshake

host                                   proxy
 | OTH1 claim(role=host) pubkey  ───▶  | verify claim, role, sub == room host, jkt == thumbprint(pubkey),
 |                                     | region, room known (directory refresh once if not), jti unseen
 | ◀───────────────────  OTCH nonce    | nonce: 16 random bytes, remembered ≤10 s for (addr, room)
 | OTHP nonce sig  ──────────────────▶ | sig = Ed25519(priv, "OTHP" ‖ nonce ‖ ASCII(room))  (16+4+37 bytes signed)
 | ◀──────────  OTHK leg_token slots   | jti consumed; host leg = (this addr, leg_token); room attached
  • OTH1 and OTHP MUST be sent from the socket the host will use for the leg; the proof is also the return-routability check.
  • Retransmit OTH1 every 500 ms (max 10) until OTCH or OTNO; a duplicate OTH1 from the same address within 10 s gets the same OTCH again. Retransmit OTHP every 500 ms (max 10) until OTHK or OTNO; a duplicate OTHP after attach gets the same OTHK again.
  • max_slots is the number of client slots (players − 1, at most 7). Slots are numbered 1..max_slots.
  • The proxy keeps at most 256 pending host handshakes, each only after a validly signed host claim.

4.3 Client handshake

Unchanged OTJ1. For a room: OTOK opens the client leg and the proxy sends the host JOIN(slot, player_id); OTNO 5 means "host not attached yet, retry" (§4.1). A client claim whose sub is the room's host is refused OTNO 1. A second OTJ1 from a new address for a player who already holds a slot (a reconnect from a new port) replaces the old leg: the host gets LEAVE(slot, 3 replaced) then JOIN(slot, player_id) for the same slot. A duplicate OTJ1 from the leg's own address gets OTOK again and is not forwarded.

4.4 Connectivity probe (OTP1)

Before any match the SDK MAY send 20 OTP1 datagrams, 50 ms apart, each with a fresh 8-byte nonce, and time the OTP2 echoes: rtt_ms = median RTT, loss_pct = lost / 20 × 100. The proxy answers only datagrams of exactly 64 bytes, at most 20 per second per source IP and 2,000 per second in total; excess is dropped silently. OTP1 is answered only when the proxy runs with relay enabled.

5. Host-leg framing

Client legs carry raw game datagrams in both directions, untouched.

proxy → host :  type u8 | slot u8 | payload                     (2-byte header)
host  → proxy:  type u8 | slot u8 | leg_token u64 | payload     (10-byte header)
type Name Direction slot Payload
0 DATA both 1..max_slots one game datagram for/from that slot's client
1 JOIN proxy → host the slot player id, 16 raw bytes (UUID in RFC 4122 byte order)
2 LEAVE proxy → host the slot u8 reason: 1 idle timeout, 2 kicked, 3 replaced, 4 room closing
3 KEEPALIVE both 0 empty. Host sends every 2 s; the proxy answers each with a KEEPALIVE
4 KICK host → proxy the slot optional u8 reason (logged). Frees the slot; proxy answers LEAVE(slot, 2)
5 END host → proxy, and proxy → host as the ack 0 u8 reason: 0 ok (match finished), 1 quit, 2 error. The proxy acks with END (type 5, slot 0, no payload)

Rules:

  • A host datagram is accepted only from the leg's address and with the leg's leg_token; anything else is dropped silently and counted. A frame shorter than its header is dropped.
  • DATA to a slot with no leg is dropped (reason="no_slot"). JOIN is the host's only source of player identity; nothing a client says in game packets is identity.
  • Maximum datagram: client → proxy 1,400 bytes; host → proxy 1,410 bytes including the 10-byte header. Larger datagrams are dropped (reason="oversize"). ENet's default MTU (1,392) fits.
  • END with reason 0 ends the room as ended; reason 1 or 2 ends it as host_lost. The host SHOULD retransmit END every 200 ms until acked (max 5). After END the room is closed: client legs are dropped and further datagrams are ignored.
  • Every slot's JOIN is sent once when the client attaches and again, for every live slot, after a host resume (§6). The host MUST treat a JOIN for an occupied slot with the same player id as idempotent.

6. Timers, budgets, failure and resume

Item Value (default; proxy env var)
host keepalive every 2 s (SDK)
host leg idle → grace 10 s without any valid host datagram (PROXY_RELAY_HOST_IDLE)
grace (resume window) 30 s (PROXY_RELAY_GRACE) → room ends host_lost
client leg idle 30 s (PROXY_IDLE_TIMEOUT) → LEAVE(slot, 1)
host attach deadline the reservation TTL (60 s, Allocator); nobody hosts → allocation expired
client leg in 120 pps, 48 KiB/s, burst 2× (PROXY_RELAY_CLIENT_PPS, PROXY_RELAY_CLIENT_BPS)
host leg in 120 pps × slots, 64 KiB/s × slots, burst 2× (PROXY_RELAY_HOST_PPS_PER_SLOT, PROXY_RELAY_HOST_BPS_PER_SLOT)
room total (both directions) 1,000 pps, 512 KiB/s (PROXY_RELAY_ROOM_PPS, PROXY_RELAY_ROOM_BPS)
rooms per proxy 25 (PROXY_MAX_ROOMS)

Over-budget datagrams are dropped, never queued. ENet's reliability is the only retransmission.

Relay lost (host side). If the host has received nothing from the proxy (no KEEPALIVE answer, no DATA) for 6 s it SHOULD assume its leg is gone and resume.

Resume. Inside the grace window — or at any time while attached, e.g. after a NAT rebinding — the host fetches a fresh host claim with the same host_key (§3.2) and runs §4.2 again from its (possibly new) socket. A different key is OTNO 6. On success the leg moves to the new address with a new leg_token, the room is attached again and the proxy re-sends JOIN for every live slot. Client legs are kept throughout grace; clients see silence, not a disconnect, and new clients get OTNO 5.

Grace expiry / host quit. The room ends host_lost; parties are returned with reason host_lost and the match outcome is abandoned (design 31 §4). Nothing pays out on a host's word (design 32).

7. Allocator API additions (service-to-service; the SDK never calls these)

All internal routes take Authorization: Bearer <service key> and answer the COM-5 error envelope. p2p_host is served only when the Allocator runs with ALLOCATOR_P2P_ENABLED=true; otherwise every request naming it is 400 unknown_transport, as for any unserved transport.

7.1 POST /internal/matches (Matchmaker key) and POST /internal/allocations (Session key)

New optional request fields:

{
  "transport": "p2p_host",
  "fallback_transport": "otomo-udp",
  "leader_id": "…uuid…",
  "host_candidates": [
    {"player_id": "…uuid…", "opt_in": true, "can_host": true, "rtt_ms": 38, "loss_pct": 0.5,
     "tested_at": "2026-11-07T10:00:00Z"}
  ],
  "host_policy": {"max_host_rtt_ms": 120, "require_opt_in": true}
}
  • transport on POST /internal/allocations is new; absent keeps today's behaviour (any free server, never a room).
  • host_candidates is required for p2p_host (1..8 entries, each a distinct player; on the party route each must be one of player_ids). Every profile field is optional. A candidate that carries no profile field at all is eligible (ranked after every profiled one) only when the Allocator runs with ALLOCATOR_P2P_ALLOW_UNPROFILED=true; a candidate with any profile field must pass every rule.
  • For p2p_host, player_count (match route) must be 2..8.

New answer fields: host_player_id (top level, and inside descriptor), descriptor.room. On the party route tickets has a client claim for every player except the host, who must fetch a host claim with host_key.

New refusals: 409 no_host (no eligible candidate and no fallback; a retry with the same members cannot succeed), 503 no_capacity (relay full, or no relay heartbeat within ALLOCATOR_HEARTBEAT_TIMEOUT; fallback is tried first when given), 400 invalid_request (bad candidates/policy).

7.2 Tickets routes

POST /internal/matches/{match_id}/tickets and POST /internal/allocations/{allocation_id}/tickets accept {"player_id", "host_key"?} with the semantics and errors of §3.2 (not_host 403, host_key_required 409, not_p2p 409, invalid_request 400).

POST /internal/matches/{match_id}/roster (Matchmaker key, mounted with ALLOCATOR_P2P_ENABLED) takes {"members": [...]} (§3.4 member shape), adds the room, host and expiry, signs and answers the §3.4 envelope. 400 invalid_request, 404 not_found, 409 allocation_ended, not_p2p, no_host, host_not_in_roster. Economy's POST /internal/economy/players/owned ({"player_ids", "prefix"}, Matchmaker key) is where owned_spells comes from.

7.3 Proxy-role routes (Gameplay Proxy key)

GET /internal/servers — unchanged shape; p2p_host rows are listed (old proxies skip them by transport) with one extra object:

{"server_id": "room-…", "internal_addr": "relay", "state": "reserved", "transport": "p2p_host",
 "room": {"allocation_id": "…", "host_player_id": "…", "max_slots": 3}}

POST /internal/rooms/heartbeat, every 5 s:

{"relay_id": "default", "max_rooms": 25, "rooms_free": 21,
 "rooms": [{"room_id": "room-…", "host_attached": true, "players_connected": 4}]}

→ 200 {"ended": ["room-…"]}: listed rooms the Allocator no longer holds (the proxy closes them). players_connected counts the host. The first non-zero count moves the allocation reserved → active. Rooms still waiting for their host stay alive while any relay heartbeats; an active room the proxy stops listing is reaped server_dead after ALLOCATOR_HEARTBEAT_TIMEOUT.

POST /internal/rooms/{room_id}/ended {"reason": "ended" | "host_lost"} → 204, idempotent; 404 not_found unknown room; 409 not_p2p for a non-room server. It ends the allocation and queues the usual outbox callback (reason is passed through: Session and the Matchmaker see host_lost).

POST /internal/rooms/events (groundwork for design 32 presence):

{"events": [
  {"room_id": "room-…", "type": "host_ready" | "joined" | "left" | "host_lost" | "host_resumed",
   "player_id": "…uuid…", "at": "RFC 3339",
   "first_at": "RFC 3339", "bytes_up": 0, "bytes_down": 0}
]}

→ 202. Up to 256 events per call; recorded append-only; first_at/bytes_* only on left.

7.4 End reasons

allocation.end_reason gains host_lost. Outbox callbacks to Session and the Matchmaker carry it unchanged.

8. Versioning

  • The datagram magics carry the version (OTH1, OTP1). A breaking change to §4–§5 gets new magics (OTH2, …); the proxy keeps answering the old ones for at least one SDK release.
  • New frame type values MAY be added; a receiver MUST drop a frame type it does not know (counted on the proxy, ignored by the SDK). New LEAVE/END reason values MAY be added; treat unknown as "error".
  • New JSON fields MAY be added to any answer; clients MUST ignore unknown fields. New request fields are always optional.

Changelog

  • p2p-wire/1 (initial, aea946e).
  • 2026-11-07, still p2p-wire/1, no SDK-visible change to §2–§6:
  • §3.2: the Session party route does not accept host_key in P1 (the first version said it was accepted and forwarded; it is not implemented, and no party launch is peer-hosted yet).
  • §7.1: the switch for id-only candidates is ALLOCATOR_P2P_ALLOW_UNPROFILED=true (first version: ALLOCATOR_P2P_REQUIRE_PROBE=false), and it applies only to a candidate with no profile field.
  • §6, clarification: while a room is in grace, a valid host datagram (right address, right leg_token) re-attaches it without a new handshake; JOIN is re-sent for every live slot as on any resume.
  • 2026-11-07, still p2p-wire/1, additive: §3.4 the signed roster route and the public placement keys at /p2p/v1/placement-keys; §7.2 the Allocator's roster-signing route.
  • 2026-11-07, additive: §4.4 match reports are served. POST /api/player/economy/match-reports (player token) stores a player's own facts and the host's outcome and answers {match_id, status: accepted|late|rejected, accepted: n, replayed: n, rejected: [keys], detail}. Nothing pays on the call: the match is settled after it ends by the developer's economy.trust p2p_host policy (docs/guide/peer-hosted-rewards.md). The matchmaker now records each match's origin and host with Economy.