docs: update message examples to protocol version 2 - #51
Conversation
All per-action JSON examples still showed "version": 1 even though protocol v2 (NIP-44 direct transport) is the current version and v1 is deprecated. Update every standalone message example to "version": 2. Deliberately kept at version 1: - overview.md v1-vs-v2 content-array comparison (illustrates v1) - key_management.md gift-wrap (kind 1059) walkthrough examples, which document the deprecated v1 envelope Also fix the stale note in last_trade_index.md that claimed the current protocol version is 1.
|
Warning Review limit reached
Next review available in: 30 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?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 reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. 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, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (4)
WalkthroughDocumentation examples across order, payment, administration, dispute, settlement, rating, and restore flows now use protocol version 2. Messaging examples also reflect NIP-44 direct messages and revised envelope arrays. ChangesProtocol v2 documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ 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: 24b1515df2
ℹ️ 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".
| { | ||
| "order": { | ||
| "version": 1, | ||
| "version": 2, |
There was a problem hiding this comment.
When a client follows this example, the page explicitly instructs it to send a Gift Wrap event and later shows kind 1059, but src/overview.md:25-54 and src/transport_migration.md:33-52 define version: 2 exclusively for kind-14 direct messages with a three-element content tuple. The confirmation on this page also remains a two-element v1 tuple, and the same mismatch recurs across the changed action pages, so these examples now describe messages that conform to neither protocol. Either keep version: 1 on the retained Gift Wrap examples or update the transport prose, event, and tuple shape together.
Useful? React with 👍 / 👎.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 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 `@src/last_trade_index.md`:
- Line 13: Update the transport and envelope descriptions surrounding
restore.version 2 so every example consistently identifies NIP-44 direct
transport rather than deprecated Gift Wrap: revise the request, response, and
standalone examples in src/last_trade_index.md at lines 13, 29-30, and 51-52,
and the request, response, and use-case response descriptions in
src/restore_session.md at lines 13, 30, and 88. Preserve the existing version 2
examples and terminology consistently across all six sites.
In `@src/new_buy_order.md`:
- Line 8: Protocol v2 examples retain v1 transport or incomplete envelopes
instead of using the required NIP-44 structure. Migrate src/new_buy_order.md
lines 8 and 59, src/new_buy_order_ln_address.md lines 9 and 53,
src/new_sell_order.md lines 8 and 68, src/cancel.md lines 9, 27, 100, 116, 132,
148, and 164, and src/dispute.md lines 9, 27, 45, 91, 107, and 138 to direct
kind-14 v2 envelopes with the third identity-proof element; update
src/admin_settle_order.md lines 9, 27, and 64 with the complete v2 envelope
structure; add the missing identity-proof element at src/bond_slashed.md line
19; and replace the Gift Wrap transport at src/dispute_chat.md line 13 with v2
direct transport. Preserve version 1 where migration is not intended.
In `@src/new_sell_range_order.md`:
- Line 8: Align every version-2 example with the NIP-44 direct transport rather
than Gift Wrap/NIP-59. Update the creation, confirmation, request/response, and
flow transport descriptions and envelopes in src/new_sell_range_order.md lines
8-8 and 49-49; src/orders.md lines 13-13 and 41-41; src/take_buy.md lines 9-9,
48-48, 111-111, 129-129, 144-144, and 173-173; src/take_buy_range_order.md line
9-9; src/take_sell.md lines 9-9, 32-32, 93-93, and 119-119; src/fiatsent.md
lines 8-8, 23-23, 40-40, and 57-57; and src/user_rating.md lines 9-9, 25-25, and
45-45, preserving the existing message examples while making all transport
terminology and envelopes consistent with version 2.
🪄 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 Plus
Run ID: 42befc59-e280-4f7f-b033-90813c6b0742
📒 Files selected for processing (27)
src/add_bond_invoice.mdsrc/admin_add_solver.mdsrc/admin_cancel_order.mdsrc/admin_settle_order.mdsrc/bond_slashed.mdsrc/cancel.mdsrc/dispute.mdsrc/dispute_chat.mdsrc/fiatsent.mdsrc/last_trade_index.mdsrc/new_buy_order.mdsrc/new_buy_order_ln_address.mdsrc/new_sell_order.mdsrc/new_sell_range_order.mdsrc/orders.mdsrc/overview.mdsrc/pay_bond_invoice.mdsrc/payment_failed.mdsrc/release.mdsrc/restore_session.mdsrc/seller_pay_hold_invoice.mdsrc/take_buy.mdsrc/take_buy_range_order.mdsrc/take_sell.mdsrc/take_sell_ln_address.mdsrc/take_sell_range_order.mdsrc/user_rating.md
| { | ||
| "restore": { | ||
| "version": 1, | ||
| "version": 2, |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Keep the documented transport consistent with restore.version.
Both files now use version 2, which the supplied protocol contract defines as NIP-44 direct transport, but their surrounding request prose still describes Gift Wrap. Update the transport/envelope wording so readers do not implement version 2 with the deprecated v1 transport.
src/last_trade_index.md#L13-L13: align the request example’s surrounding transport description with version 2.src/last_trade_index.md#L29-L30: align the response example with the same v2 transport terminology.src/last_trade_index.md#L51-L52: align the standalone example with the v2 transport.src/restore_session.md#L13-L13: update the restore-session request transport description.src/restore_session.md#L30-L30: update the restore-session response transport description.src/restore_session.md#L88-L88: update the use-case response transport description.
📍 Affects 2 files
src/last_trade_index.md#L13-L13(this comment)src/last_trade_index.md#L29-L30src/last_trade_index.md#L51-L52src/restore_session.md#L13-L13src/restore_session.md#L30-L30src/restore_session.md#L88-L88
🤖 Prompt for 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.
In `@src/last_trade_index.md` at line 13, Update the transport and envelope
descriptions surrounding restore.version 2 so every example consistently
identifies NIP-44 direct transport rather than deprecated Gift Wrap: revise the
request, response, and standalone examples in src/last_trade_index.md at lines
13, 29-30, and 51-52, and the request, response, and use-case response
descriptions in src/restore_session.md at lines 13, 30, and 88. Preserve the
existing version 2 examples and terminology consistently across all six sites.
Address review feedback on PR #51: examples were relabeled version 2 but kept the v1 Gift Wrap transport. Now every changed page uses the real v2 wire format: - content tuples gain the third identity-proof element (identity proof for signed user requests, null for Mostro replies and full privacy) - kind 1059 event examples become signed kind 14 events authored by the trade key, with NIP-44 ciphertext content and NIP-40 expiration tag - prose no longer references Gift Wrap / NIP-59 / rumors on v2 pages - Mostro-reply examples that wrongly showed a trade-key signature now carry null, per overview.md content-array rules dispute_chat.md keeps its kind 1059 sections: they document the separate shared-key chat scheme from chat.md, not the Mostro message transport.
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/new_buy_order.md (1)
3-25: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick winComplete the v2 request content tuples.
Both initial order requests declare NIP-44 ciphertext for a content array but show only the payload object. Append the index-N signature and index-0 identity-proof elements, as demonstrated by the lightning-address request example.
src/new_buy_order.md#L3-L25: wrap the order object in the three-element v2 tuple.src/new_sell_order.md#L3-L27: apply the same tuple structure to the sell-order request.🤖 Prompt for 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. In `@src/new_buy_order.md` around lines 3 - 25, Complete the v2 request content tuple in src/new_buy_order.md lines 3-25 by wrapping the existing order object with the index-N signature and index-0 identity-proof elements, matching the lightning-address example; apply the same three-element tuple structure to the sell-order request in src/new_sell_order.md lines 3-27.
🤖 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 `@src/cancel.md`:
- Line 20: Update the “Mostro response” heading in the documentation to the
possessive form “Mostro’s response,” preserving the existing heading level and
surrounding content.
In `@src/take_sell_range_order.md`:
- Line 25: Update the buyer-invoice explanation in the order example to remove
the claim that the order amount is zero, and state that Mostro calculates the
satoshi amount from the selected fiat amount before requesting the Lightning
invoice.
- Line 92: Update the sentence in the range-order documentation near the
payment_request description: replace “avoid to create and send lightning
invoices” with “avoid creating and sending lightning invoices,” and correct “to
acomplish this” to “to accomplish this.”
---
Outside diff comments:
In `@src/new_buy_order.md`:
- Around line 3-25: Complete the v2 request content tuple in
src/new_buy_order.md lines 3-25 by wrapping the existing order object with the
index-N signature and index-0 identity-proof elements, matching the
lightning-address example; apply the same three-element tuple structure to the
sell-order request in src/new_sell_order.md lines 3-27.
🪄 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 Plus
Run ID: 32ce7a58-5281-4b6d-a7b8-1835154fc5e3
📒 Files selected for processing (26)
src/add_bond_invoice.mdsrc/admin_add_solver.mdsrc/admin_cancel_order.mdsrc/admin_settle_order.mdsrc/bond_slashed.mdsrc/cancel.mdsrc/dispute.mdsrc/dispute_chat.mdsrc/fiatsent.mdsrc/last_trade_index.mdsrc/new_buy_order.mdsrc/new_buy_order_ln_address.mdsrc/new_sell_order.mdsrc/new_sell_range_order.mdsrc/orders.mdsrc/pay_bond_invoice.mdsrc/payment_failed.mdsrc/release.mdsrc/restore_session.mdsrc/seller_pay_hold_invoice.mdsrc/take_buy.mdsrc/take_buy_range_order.mdsrc/take_sell.mdsrc/take_sell_ln_address.mdsrc/take_sell_range_order.mdsrc/user_rating.md
🚧 Files skipped from review as they are similar to previous changes (12)
- src/last_trade_index.md
- src/admin_add_solver.md
- src/admin_settle_order.md
- src/new_sell_range_order.md
- src/dispute_chat.md
- src/restore_session.md
- src/bond_slashed.md
- src/release.md
- src/pay_bond_invoice.md
- src/dispute.md
- src/payment_failed.md
- src/seller_pay_hold_invoice.md
- new_buy_order.md, new_sell_order.md: wrap the request example in the full 3-element v2 content tuple, matching the lightning-address page - take_sell_range_order.md: the sats amount comes from the buyer's selected fiat amount, not from a zero order amount; grammar fixes - cancel.md: 'Mostro response' -> 'Mostro's response'
1 participant
Summary
"version": 1even though protocol v2 (NIP-44 direct transport) is current and v1 is deprecated (transport_migration.md). This updates all standalone message examples across 27 pages to"version": 2.last_trade_index.md("Protocol version. Current is1.") to state that the current version is2, with1only on the deprecated gift-wrap transport.Deliberately kept at
"version": 1overview.md— the v1-vs-v2 content-array comparison block (it illustrates v1 on purpose).key_management.md— the gift-wrap (kind1059) walkthrough examples documenting the deprecated v1 envelope.Known follow-up (not in this PR)
Several per-action pages still describe the reply envelope as a "nip59 event" with 2-element content arrays. Updating that prose/shape to the v2 kind-14 3-element format is a larger rewrite that probably deserves its own pass.
Test plan
mdbook buildpassesgrep -rn '"version": 1' src/returns only the 4 deliberate v1 illustrationsSummary by CodeRabbit
version: 2(replacingversion: 1) for ordering, payments, cancellations, disputes, ratings, and admin workflows.14) instead of gift-wrap wording/content.restore-sessionexamples to use the currentversion: 2format and explicitly flagversion: 1as deprecated.nullplaceholders).