feat(xmtp_proto): XIP-83 d14n QueryApi.Subscribe protos (vector-cursor topics, OriginatorEnvelope delivery)

[tylerhawkes]

What

Regenerate xmtp_proto from xmtp/proto main (f04e01a9, proto #338) to pull in the decentralized (d14n) XIP-83 binding: QueryApi.Subscribe (bidirectional mutable subscription) plus SubscribeRequest / SubscribeResponse / Ping / Pong, using per-originator vector cursors and OriginatorEnvelope delivery.

Why

This is the client-side counterpart to the d14n backend (xmtpd #2020, QueryApi.Subscribe). It's the proto-regen step that makes the d14n Subscribe types available in libxmtp so the client lane can be built on top.

It mirrors the v3 client stack — #3769 (protos) → #3770 (shared bidi_stream transport, already merged) → #3771 → #3772. The d14n binding reuses that same bidi_stream primitive; only the proto types differ (xmtpv4.message_api vector-cursor / OriginatorEnvelope vs mls.api.v1 single-cursor / GroupMessage+WelcomeMessage).

Scope

Purely additive generated code — no hand-written changes:

• crates/xmtp_proto/proto_version: ac2aa57f → f04e01a9
• crates/xmtp_proto/src/gen/xmtp.xmtpv4.message_api.{rs,serde.rs}: the new Subscribe types
• crates/xmtp_proto/src/gen/proto_descriptor.bin: runtime FILE_DESCRIPTOR_SET carries the new types

Unrelated generator-version drift in other gen packages (message_api.v1, message_contents, mls.database, mls.message_contents*) was restored to main, per the established regen pattern (same as #3769). Nothing consumes the new types yet — the d14n transport impl and actor follow in later PRs.

Verification

• Regenerated via ./dev/gen_protos.sh (default main) from the public proto repo.
• cargo check -p xmtp_proto --features grpc_server_impls and cargo check -p xmtp_api_d14n clean (existing xmtpv4 consumers still compile).

🤖 Generated with Claude Code

Note

Add XIP-83 bidirectional streaming Subscribe proto types to QueryApi

• Adds SubscribeRequest and SubscribeResponse proto message types supporting a vector-cursor topic subscription model with mutate, ping/pong, and catchup semantics.
• Extends query_api_server with a bidirectional streaming Subscribe method using the new request/response types.
• Adds new tonic server modules: notification_api_server (server-streaming SubscribeAllEnvelopes) and publish_api_server (unary PublishPayerEnvelopes).
• Generates serde implementations for all new types in xmtp.xmtpv4.message_api.serde.rs, including base64 encoding for bytes fields and camelCase/snake_case support.
• Updates the proto descriptor binary and version hash; all changed files are generated.

^{Macroscope summarized 10cb8a2.}

[claude]

Claude finished @tylerhawkes's task —— View job

---

Code Review Complete ✓

Review Date: 2026-06-24 23:18 UTC

Summary

This PR regenerates proto definitions for XIP-83 d14n QueryApi.Subscribe — a purely additive, generated-code change. The review confirms the changes align with the stated scope and follow established patterns.

Findings

✅ Code Quality: Excellent

• All changes are machine-generated by prost-build (header: // This file is @generated by prost-build)
• Follows existing code patterns in the xmtp_proto crate
• Properly structured with nested modules matching proto package hierarchy
• Consistent naming conventions throughout

✅ Scope Verification: Accurate

• Proto version bump: ac2aa57f → f04e01a9 (crates/xmtp_proto/proto_version:1)
• New Subscribe types added to xmtp.xmtpv4.message_api.{rs,serde.rs}
• Key additions: SubscribeRequest, SubscribeResponse, Ping, Pong, with vector-cursor support via OriginatorEnvelope
• Binary descriptor updated accordingly
• No hand-written code changes detected

✅ Architecture: Sound

• QueryApi.Subscribe method signature (crates/xmtp_proto/src/gen/xmtp.xmtpv4.message_api.rs:2249-2252):
  • Bidirectional streaming: Streaming<SubscribeRequest> → SubscribeStream
  • Well-documented: "XIP-83 bidirectional mutable subscription" with clear HTTP/2 requirement note
  • Supports dynamic mutation (add/remove topics), ping/pong liveness
• Vector cursor model via OriginatorEnvelope throughout response types
• Proper versioning: SubscribeRequest.Version and SubscribeResponse.Version enums enable future evolution

✅ Security & Performance: No concerns

• Generated code follows prost security best practices
• No unsafe code blocks
• Streaming semantics appropriate for long-lived subscriptions
• Per-originator vector cursors enable efficient resumption

✅ Test Coverage: N/A for generated code

• This is proto-only; functional tests belong in the transport/client implementation PRs that follow (referenced feat(xmtp_api_d14n): XmtpMlsBidiStreams trait + v3 Subscribe transport #3771, feat(xmtp_api_d14n): BidiConnection actor — own both wire halves, internal liveness #3772)
• Author verified compilation: cargo check -p xmtp_proto --features grpc_server_impls and cargo check -p xmtp_api_d14n

Recommendation

LGTM — Approve and merge. This is a clean proto regeneration that unblocks the d14n client subscription stack. No issues found.

---

[macroscopeapp]

Approvability

Verdict: Approved

Auto-generated protobuf code adding new XIP-83 Subscribe API types and gRPC scaffolding. All files are owned by the author, changes are purely additive type definitions with no hand-written logic or behavioral modifications to existing code.

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.43%. Comparing base (5a8a134) to head (10cb8a2).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3781   +/-   ##
=======================================
  Coverage   84.43%   84.43%           
=======================================
  Files         408      408           
  Lines       59904    59904           
=======================================
+ Hits        50578    50580    +2     
+ Misses       9326     9324    -2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.