Validate the Circuit Relay v2 relay-server contract #61

Destination

Produce a validated, implementation-ready four-PR specification for a minip2p Circuit Relay v2 relay server: relay-side wire roles, a sans-I/O service, std Endpoint integration, and the example/docs/CI needed to ship it. Use rust-libp2p relay 0.22 as the behavioral baseline and make every deliberate minip2p deviation explicit.

Notes

• Planning only: this map resolves decisions and validates the specification; it does not implement or merge the relay server.
• Canonical specification: Circuit Relay v2 Relay Server for minip2p.
• Upstream baseline: rust-libp2p relay 0.22 at 170c3c81ddd80e7c58b0500563e00a09139e8545.
• Protocol baseline: Circuit Relay v2 at 6b6203ee6f62938ce67efdb33498173f475851c0.
• Every grilling ticket uses both the grilling and domain-modeling skills. Create domain glossary or ADR files only if that session resolves something that belongs in them.
• Resolve at most one non-research ticket per session. Refer to maps and tickets by linked title, never by bare number.

Decisions so far

• Audit the relay-server compatibility envelope — The seed needs explicit compatibility layers; its HOP/address, admission, byte/duration, lifecycle, and worker-cap claims require correction.
• Choose the reservation cardinality model — The relay promises one active reservation per peer, with exact-connection renewal, fresh reservation after supersession, rate-first admission, and replacement-based capacity accounting.
• Define relay reachability and HOP advertisement — HOP is a static explicit capability; reservation addresses use validated explicit, confirmed-external, then concrete-listener precedence with runtime replacement and future-Identify updates.
• Lock circuit byte-limit semantics — Each direction gets an independent 128 KiB soft limit; accepted payload including handshake leftovers is counted, with directional totals and exactly-once terminal reporting.
• Define reservation termination observability — Committed reservations renew in place and end once with an explicit reason; monotonic time governs expiry while optional Unix time is wire/event metadata.
• Freeze the public relay-server contract — The std-only feature exposes validated defaults, explicit builder/runtime controls, typed lifecycle events and errors, directional protocol roles, and no stream-level Endpoint plumbing.
• Approve the implementation-ready relay-server specification — The revised canonical plan assigns every resolved wire, Swarm, service, Endpoint, interoperability, and documentation obligation across four implementation PRs with no remaining product decision.

Not yet specified

None.

Out of scope

• Implementing, reviewing, or merging the relay-server code.
• Retiring tests/support/relay.rs internals or other fixture migration beyond the four-PR specification.
• Portable/smoltcp Endpoint integration for the relay server.
• Reservation vouchers, relay discovery, and autorelay.
• ACLs, metrics, proxy-aware IP limiting, and deployment operations.
• Swarm-level inbound-negotiation caps; any omission remains an explicit documented deviation.