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/matchandPOST /api/player/match/ticketanswer{"match_id", "status", "transport", "region", "descriptor": {…}, "credential": {…}}; thedescriptorobject 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'slaunchrules 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>"}
payloadis the exact JSON the Allocator signed;signatureis detached Ed25519 over those bytes with the placement-claim key namedkid. A verifier checks the signature over the decoded payload bytes and reads the roster from them;rosteris a readable copy and is never trusted whenpayloadis present. (Earlier SDKs re-canonicalisedroster; 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_spellslists the held items whose id starts with the Matchmaker'sMATCHMAKER_ROSTER_ITEM_PREFIX(Elemaniacs:spell.);roomandhost_player_idcome from the Allocator, never from the caller.loadoutis 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
OTH1andOTHPMUST be sent from the socket the host will use for the leg; the proof is also the return-routability check.- Retransmit
OTH1every 500 ms (max 10) untilOTCHorOTNO; a duplicateOTH1from the same address within 10 s gets the sameOTCHagain. RetransmitOTHPevery 500 ms (max 10) untilOTHKorOTNO; a duplicateOTHPafter attach gets the sameOTHKagain. max_slotsis the number of client slots (players − 1, at most 7). Slots are numbered1..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. ENDwith reason 0 ends the room asended; reason 1 or 2 ends it ashost_lost. The host SHOULD retransmitENDevery 200 ms until acked (max 5). AfterENDthe 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}
}
transportonPOST /internal/allocationsis new; absent keeps today's behaviour (any free server, never a room).host_candidatesis required forp2p_host(1..8 entries, each a distinct player; on the party route each must be one ofplayer_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 withALLOCATOR_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
typevalues MAY be added; a receiver MUST drop a frame type it does not know (counted on the proxy, ignored by the SDK). NewLEAVE/ENDreason 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_keyin 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;JOINis 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'seconomy.trustp2p_hostpolicy (docs/guide/peer-hosted-rewards.md). The matchmaker now records each match's origin and host with Economy.