docs: document anti-abuse bond implementation (Phases 1–7)#46
Conversation
Cover all protocol changes introduced by the anti-abuse bond PRs
(#712–#777) that were not yet reflected in the protocol docs:
### New page
- `bond_slashed.md`: documents the `bond-slashed` action (Phase 4/7).
Sent to the bonded party when a waiting-state timeout elapses and
`slash_on_waiting_timeout = true`. Distinguishes timeout-slash from
dispute-slash path; explains order cancel vs. republish depending on
which party was responsible; notes that cancel-before-timeout never
triggers this.
### Extended pages
- `pay_bond_invoice.md`: restructured to cover both taker bond (Phase 1.5,
existing) and maker bond (Phase 5/6, new). Maker bond: trigger is
`new-order` response; order not published until bond HTLC accepts;
`waiting-maker-bond` DM status; range orders sized against `max_amount`.
- `add_bond_invoice.md`: adds Phase 3.5 payout confirmations —
`bond-invoice-accepted` (Mostro acknowledges receipt of payout bolt11)
and `bond-payout-completed` (payment settled). Notes re-prompt on
`send_payment` exhaustion and claim window.
- `cancel.md`: fixes incorrect "supersede mechanism" wording (replaced by
concurrent bonds / first-to-lock-wins model since Phase 1.5). Adds two
new sections — taker self-cancel during `waiting-taker-bond` (releases
only sender's bond; order stays in `waiting-taker-bond` if others
remain) and maker cancel during `waiting-taker-bond` (releases all
concurrent bonds).
### Order creation pages
- `new_sell_order.md`, `new_buy_order.md`: "Optional: anti-abuse maker bond"
section explaining that `pay-bond-invoice` precedes `new-order`
confirmation when `apply_to ∈ {make, both}`.
- `new_sell_range_order.md`: same section, noting bond sized against
`max_amount` and proportional per-slice accounting.
### Message suggestions
- `message_suggestions_for_actions.md`: adds `bond-invoice-accepted`,
`bond-payout-completed`, and `bond-slashed` suggested texts.
### Navigation
- `SUMMARY.md`: adds `bond_slashed.md` link after `add_bond_invoice.md`.
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
|
Warning Review limit reached
More reviews will be available in 33 minutes and 29 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 We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. 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 (5)
WalkthroughDocumentation-only update expanding the anti-abuse bond feature across eight markdown files. Adds a new ChangesAnti-abuse bond documentation
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related issues
Possibly related PRs
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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
src/pay_bond_invoice.md (1)
19-19: 💤 Low valueMinor clarity: consider replacing "rumor's content" with "message's content".
While "rumor's content" is grammatically correct (the encrypted rumor/message payload), clients and most other documentation refer to it simply as "message." Changing this to "The message's content has the same shape..." would improve consistency and clarity.
🤖 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/pay_bond_invoice.md` at line 19, In the text on line 19 of src/pay_bond_invoice.md, replace "rumor's content" with "message's content" to maintain consistency with how clients and documentation refer to the payload. Change the sentence from "The rumor's content has the same shape as `pay-invoice`; only the action discriminator differs:" to "The message's content has the same shape as `pay-invoice`; only the action discriminator differs:".Source: Learnings
🤖 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/bond_slashed.md`:
- Around line 48-57: The markdown file mixes British and American spelling
variants for the word "cancelled" vs "canceled". On line 48, the phrase "the
order is **cancelled**" uses the British spelling, while lines 49 and 57 use the
American spelling "canceled", which is consistent with the rest of the protocol
documentation including pay_bond_invoice.md. Replace the single instance of
"cancelled" on line 48 with "canceled" to maintain consistent American spelling
throughout the document.
---
Nitpick comments:
In `@src/pay_bond_invoice.md`:
- Line 19: In the text on line 19 of src/pay_bond_invoice.md, replace "rumor's
content" with "message's content" to maintain consistency with how clients and
documentation refer to the payload. Change the sentence from "The rumor's
content has the same shape as `pay-invoice`; only the action discriminator
differs:" to "The message's content has the same shape as `pay-invoice`; only
the action discriminator differs:".
🪄 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: 415c18b9-2247-43d1-b660-cc1635cc7e85
📒 Files selected for processing (9)
src/SUMMARY.mdsrc/add_bond_invoice.mdsrc/bond_slashed.mdsrc/cancel.mdsrc/message_suggestions_for_actions.mdsrc/new_buy_order.mdsrc/new_sell_order.mdsrc/new_sell_range_order.mdsrc/pay_bond_invoice.md
![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: 5320436b14
ℹ️ 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".
- bond_slashed.md: 'cancelled' → 'canceled' (American spelling throughout) - bond_slashed.md: slash_on_waiting_timeout → bond_slash_on_waiting_timeout (correct wire tag name per other_events.md kind-38385 spec) - pay_bond_invoice.md: 'rumor's content' → 'message's content' - pay_bond_invoice.md: maker-bond SmallOrder status 'waiting-maker-bond' → 'pending' (matches flow.rs:380 which uses Some(Status::Pending) as the wire-facing NIP-69 bucket; waiting-maker-bond is daemon-internal only and never emitted in DM payloads) Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Code review against the daemon (src/app/bond/flow.rs) found the DM payload echo was documented incorrectly: - request_taker_bond (flow.rs:203) and request_maker_bond (flow.rs:380) both build the pay-bond-invoice SmallOrder with `Some(Status::Pending)`. The internal `waiting-taker-bond` / `waiting-maker-bond` states are kept in the daemon DB only and are NEVER emitted on the wire. Docs previously claimed clients "see" / "echo" these internal statuses in DM payloads. Fixes: - pay_bond_invoice.md: taker JSON example status waiting-taker-bond → pending; rewrote both "Daemon status" notes (taker + maker) to state the status is internal-only, never echoed. (Maker example was already pending from the prior review.) - take_buy.md / take_sell.md: corrected the "DM payload echoes waiting-taker-bond" phrasing to "SmallOrder carries status: pending". - order_event.md: corrected "visible only in DM payload echoes" → "kept in the daemon's database only and never emitted on the wire". - bond_slashed.md: notify_bond_slashed (slash.rs:696) builds the SmallOrder with status=None and created_at=None; corrected the wire example from status "canceled" / created_at <ts> to null, with an explanatory note. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 participant
Summary
Covers all protocol changes from the anti-abuse bond PRs (#712–#777) that were not yet reflected in the protocol documentation. The PRs brought bond-related machinery in seven distinct phases; the previous protocol docs only covered Phases 1.5, 2, 3, 4 (partially) and 8. This PR fills the gaps.
What was already documented (untouched)
pay_bond_invoice.md— taker bond (Phase 1.5)add_bond_invoice.md— bond payout request/reply (Phase 3)admin_settle_order.md/admin_cancel_order.md—BondResolutionpayload (Phase 2)other_events.md— bond policy tags in kind-38385 (Phase 8)order_event.md—bondtag +waiting-taker-bondNIP-69 notetake_sell.md/take_buy.md— anti-abuse bond step (taker)cancel.md— bond race during take (partially, had a bug)Changes
New page
bond_slashed.md—bond-slashedaction (Phase 4/7). Timeout-slash notification sent to the responsible party when their bond is settled by the scheduler. Explains the cancel-vs-republish outcome depending on who timed out, and links toadd-bond-invoicefor the winner's payout flow. Clarifies that this action is only emitted on the timeout path, not on the dispute-slash path.Extended pages
pay_bond_invoice.md— restructured into Taker bond and Maker bond sections. The Maker bond section (Phase 5/6) explains: trigger isnew-orderresponse (nottake-*); the order is NOT published to Nostr until the bond HTLC accepts;waiting-maker-bondstatus in DM payloads; range orders sized againstmax_amountwith proportional-per-slice accounting; failure modes (bond expires → order silently discarded, no NIP-33 ever emitted).add_bond_invoice.md— adds the Phase 3.5 payout confirmations:bond-invoice-accepted(receipt acknowledgement) andbond-payout-completed(terminal success). Also documents the re-prompt path onsend_paymentexhaustion.cancel.md— fixes incorrect "supersede mechanism" wording (supersede was removed in Phase 1.5 in favour of concurrent bonds / first-to-lock-wins). Adds two new sections: taker self-cancel duringwaiting-taker-bondand maker cancel duringwaiting-taker-bond.Order creation pages
new_sell_order.md,new_buy_order.md— "Optional: anti-abuse maker bond" section (Phase 5). The maker receivespay-bond-invoicebefore anynew-orderconfirmation whenapply_to ∈ {make, both}.new_sell_range_order.md— same section plus the range-specific note: bond sized againstmax_amount, proportional per-slice obligation (Phase 6).Message suggestions
message_suggestions_for_actions.md— addsbond-invoice-accepted,bond-payout-completed, andbond-slashedsuggested user-facing texts.Navigation
SUMMARY.md— addsbond_slashed.mdlink afteradd_bond_invoice.md.How to review
Cross-check each section against the implementation in the
mostrodaemon repo:src/app/bond/flow.rs::request_maker_bond(PR #767)src/app/bond/slash.rs::record_maker_slice_slash(PR #770)bond-slashednotify:src/scheduler.rs+src/app/bond/slash.rs(PRs #744, #775)src/app/bond/payout.rs(PR #743)src/app/bond/flow.rs,src/app/cancel.rs(PR #733, #736)🤖 Generated with Claude Code
Summary by CodeRabbit
bond-invoice-accepted,bond-payout-completed,bond-slashed).