xmtp_proto: XIP-83 d14n binding — QueryApi.Subscribe (bidi mutable subscription)

[tylerhawkes]

Adds the decentralized-backend binding of XIP-83 — companion to the v3 MlsApi.Subscribe binding (#337, merged). A new bidirectional Subscribe(stream SubscribeRequest) returns (stream SubscribeResponse) RPC on QueryApi, additive alongside the existing server-streaming SubscribeTopics.

The control protocol is identical to the v3 binding — Mutate (add/remove topics in place, history_only, mutate_id), Started, CatchupComplete, TopicsLive, Ping/Pong — adapted to the decentralized data model:

• Per-originator vector cursor: each Subscription resumes from a xmtp.xmtpv4.envelopes.Cursor (the same type SubscribeTopics uses), not v3's scalar id_cursor.
• Envelope delivery: responses carry OriginatorEnvelopes; the client demultiplexes by topic.
• Kind-prefixed binary topics (XIP-49 §3.3.2) — already the decentralized backend's native representation.

Bidirectional streaming requires HTTP/2; browser/connect-web clients stay on SubscribeTopics.

Spec: xmtp/XIPs#139 (the "Decentralized (d14n) binding" section).

🤖 Generated with Claude Code

Note

Add bidirectional QueryApi.Subscribe RPC with mutable topic subscriptions and ping/pong liveness

• Adds SubscribeRequest and SubscribeResponse messages to message_api.proto defining the client→node and node→client framing for the new bidi subscription protocol (XIP-83 d14n binding).
• SubscribeRequest.V1.Mutate supports atomic topic adds/removes, a history_only catch-up flag, and a mutate_id for correlating CatchupComplete responses.
• SubscribeResponse.V1 carries batched Envelopes, stream init metadata (Started), topic live-boundary markers (TopicsLive), per-mutation completion signals (CatchupComplete), and Ping/Pong liveness frames.
• Registers the new Subscribe bidi-streaming RPC on the QueryApi service in query_api.proto, alongside the existing server-streaming SubscribeTopics.

^{Macroscope summarized 6ccd578.}

[macroscopeapp]

Approvability

Verdict: Approved

Purely additive protobuf schema changes defining a new bidirectional subscription API. No existing definitions modified, and the author is the designated code owner for both files.

^{You can customize Macroscope's approvability policy. Learn more.}