docs: add transport v2 (NIP-44 direct) migration spec#620
Conversation
…ages - Document protocol v1 (NIP-59 gift wrap) → v2 (NIP-44 direct, kind 14) migration strategy - Define auto-detection via protocol_version tag from kind-38385 info event, defaulting to v1 when absent - Specify dual-transport support: v1 uses 2-tuple [message, tradeSig] in kind-1059 gift wrap; v2 uses 3-tuple [message, tradeSig, identityProof] in kind-14 signed by trade key - Map version field to transport (v1→version:1, v2→version:2) and document
|
Warning Review limit reached
More reviews will be available in 36 minutes and 21 seconds. Learn how PR review limits work. Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file). ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits. 🚦 How do rate limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
WalkthroughA new architecture document ChangesTransport v2 Migration Documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 37554a7d31
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/architecture/TRANSPORT_V2_MIGRATION.md`:
- Around line 81-85: Three fenced code blocks in the Markdown file are missing
language specifiers, which violates the MD040 markdownlint rule. Add the
language identifier `text` immediately after the opening triple backticks for
all three code blocks: the protocol version tag examples block containing the
content about NIP-59 gift wrap and NIP-44 direct messaging, the domain-tagged
payload format block containing the mostro-transport-v2-identity format string,
and the send/receive flow comparison block showing the v1 and v2 diagram. Change
each triple backtick opening from ``` to ```text.
- Line 20: There is a blank line at line 20 inside the blockquote that breaks
the blockquote structure between the Scope and Status sections (MD028
violation). Remove the blank line entirely to maintain blockquote continuity, or
if the blank line is intentional for formatting, add the blockquote marker (>)
to the blank line to continue the blockquote structure uninterrupted.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: d86fe8e5-09a8-4ff1-a2b2-12a550dd1e6a
📒 Files selected for processing (1)
docs/architecture/TRANSPORT_V2_MIGRATION.md
- Add closing angle bracket to blockquote continuation - Add language specifiers to fenced code blocks per coding guidelines
![ermeme[bot]](https://avatars.githubusercontent.com/in/3690068?s=60&v=4){kind=small}
There was a problem hiding this comment.
Section-by-section take: the migration shape looks right, but I would tighten 3 things before implementation:
-
Transport abstraction: the doc correctly says
versionshould follow the resolved transport, not a global constant. I would avoid threading raw ints through the code and introduce a small transport enum/resolver so send/receive stay aligned and the version field cannot drift. -
Receive path: this is the fragile part. For v2, the subscription filter must be exact (
kind: 14,authors: [mostroPubkey],p: [tradeKeys]), otherwise Mostro v2 events will get mixed with other kind-14 traffic and the bug will be silent. -
Fallback/telemetry: defaulting to v1 when
protocol_versionis absent is the right compatibility choice, but I would log that downgrade explicitly so a misconfigured node does not leave the app in a degraded mode without anyone noticing.
Overall: good plan, conservative, and the migration boundary is well chosen. The main risk is implementation plumbing, not protocol design.
There was a problem hiding this comment.
If I were implementing this migration, I would do it in this order:
- Introduce a tiny transport enum/resolver first (
v1/v2) and makeprotocol_versionparsing feed it. That keeps the decision in one place and preventsversionfrom becoming a global footgun. - Ship the receive path before the send path. The dangerous failure mode here is silent: if subscription filters are wrong, v2 replies disappear without obvious crashes.
- Keep the v1 code path byte-for-byte unchanged. Treat v2 as an additive path, not a refactor of the current gift-wrap flow.
- Add round-trip tests for both transports, plus a fallback test for missing
protocol_version→ v1.
Best approach overall: small adapter layer, dual receive first, dual send second. That gives you the safest rollout and the easiest rollback path.
…icit downgrade logging
1 participant
Adds the client-side implementation spec for supporting both Mostro wire transports during the v1 → v2 migration: protocol v1 (NIP-59 gift wrap, kind 1059) and protocol v2 (NIP-44 direct, signed kind 14), selected per node via the
protocol_versiontag on the kind-38385 instance-status event.Documentation only — no
lib/changes. Defines the wire-format differences, the per-node auto-detection design, code touch points, and a phased implementation plan (dual receive, dual send, auto-detection, tests) for subsequent branches.Summary by CodeRabbit