docs: document anti-abuse bond implementation (Phases 1–7)

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>

Author: grunch

src/SUMMARY.md

@@ -18,6 +18,7 @@
 - [Take range buy order](./take_buy_range_order.md)
 - [Pay bond invoice](./pay_bond_invoice.md)
 - [Bond payout invoice](./add_bond_invoice.md)
+- [Bond slashed notification](./bond_slashed.md)
 - [Seller pays hold invoice](./seller_pay_hold_invoice.md)
 - [Fiat sent](./fiatsent.md)
 - [Release](./release.md)

src/add_bond_invoice.md

@@ -99,11 +99,78 @@ The recipient of the request message is the non-slashed counterparty of the trad
 - **Treat re-deliveries as idempotent reminders.** The same outstanding request is being repeated; do not re-prompt the user for a fresh invoice on every retry. `slashed_at` is re-emitted unchanged, so the deadline the client shows must not shift across retries.
 - **Sign the reply with the non-slashed side's trade key.** See [Keys management](./key_management.md).
 
+## Payout confirmations (Phase 3.5)
+
+After the counterparty submits their payout invoice, Mostro acknowledges receipt and later confirms payment with two dedicated actions.
+
+### `bond-invoice-accepted`
+
+Sent by Mostro to the counterparty immediately after successfully receiving and validating their payout bolt11. This confirms Mostro has the invoice on file and is attempting the Lightning payment.
+
+```json
+[
+  {
+    "order": {
+      "version": 1,
+      "id": "<Order Id>",
+      "action": "bond-invoice-accepted",
+      "payload": {
+        "order": {
+          "id": "<Order Id>",
+          "kind": "sell",
+          "amount": 500,
+          "fiat_code": "VES",
+          "fiat_amount": 100,
+          "payment_method": "face to face",
+          "premium": 1
+        }
+      }
+    }
+  },
+  null
+]
+```
+
+Clients should surface this as a reassurance: *"Your bond payout invoice has been received and the payment is being processed."*
+
+### `bond-payout-completed`
+
+Sent by Mostro to the counterparty when the Lightning payment to their invoice has been confirmed as settled. The `amount` in the payload reflects the amount paid.
+
+```json
+[
+  {
+    "order": {
+      "version": 1,
+      "id": "<Order Id>",
+      "action": "bond-payout-completed",
+      "payload": {
+        "order": {
+          "id": "<Order Id>",
+          "kind": "sell",
+          "amount": 500,
+          "fiat_code": "VES",
+          "fiat_amount": 100,
+          "payment_method": "face to face",
+          "premium": 1
+        }
+      }
+    }
+  },
+  null
+]
+```
+
+Clients should surface this as a terminal success: *"Your bond payout of `amount` Sats has been completed!"*
+
+Both actions carry `Payload::Order` (the `SmallOrder` context) and are serde-additive: a client that does not recognise them ignores the message and falls back to the `add-bond-invoice` reply it already handles — no funds at risk.
+
 ## Failure modes
 
 - The counterparty never replies before the deadline → no Lightning payment arrives and the share is forfeited; the slashed funds remain with the node.
 - A reply arrives after the deadline, or from a sender other than the resolved recipient, or after another reply already won the race → Mostro responds with a `cant-do` action carrying reason `not-allowed-by-status`.
 - The bolt11 principal does not match the requested counterparty share, or the invoice is otherwise undecodable / expired → Mostro responds with `cant-do` reason `invalid-invoice`.
 - On a node where the operator retains 100% of slashed bonds, **no `add-bond-invoice` message is emitted at all**. Clients should not surface a phantom payout request.
+- If `send_payment` retries are exhausted (see `payout_max_retries` in the info event) the counterparty is re-prompted with a fresh `add-bond-invoice` request, provided the claim window has not yet elapsed. If the window has passed, the share is forfeited and no further messages are sent.
 
 On success, the counterparty receives their share as a Lightning payment from the node's wallet. The routing fee is paid separately from that wallet and is not deducted from the principal.

src/bond_slashed.md

@@ -0,0 +1,61 @@
+# Bond slashed notification
+
+The `bond-slashed` action is a notification Mostro sends to a bonded party when their anti-abuse bond has been **settled due to a waiting-state timeout**. It is a forfeiture notice: the bond HTLC has already been claimed into Mostro's wallet by the time this message is sent.
+
+> **Scope.** This action is only emitted on the **timeout slash** path (scheduler-driven, gated by `slash_on_waiting_timeout = true` in the Mostro info event). It is **not** sent on the dispute-slash path — when a solver slashes a bond via [`admin-settle`](./admin_settle_order.md) or [`admin-cancel`](./admin_cancel_order.md), the slashed party receives the `admin-settled` / `admin-canceled` confirmation instead.
+
+## Direction and trigger
+
+- **Direction:** Mostro → the party whose bond was slashed.
+- **Trigger:** The waiting-state timeout elapsed while the responsible party had not performed their expected trade action (e.g. the seller never paid the hold invoice while in `waiting-payment`, or the buyer never submitted an invoice in `waiting-buyer-invoice`), and the operator has configured `slash_on_waiting_timeout = true`.
+- The `amount` in the payload is the **slashed bond amount in satoshis** — not the trade amount.
+
+## Wire format
+
+```json
+[
+  {
+    "order": {
+      "version": 1,
+      "id": "<Order Id>",
+      "action": "bond-slashed",
+      "payload": {
+        "order": {
+          "id": "<Order Id>",
+          "kind": "sell",
+          "status": "canceled",
+          "amount": 785,
+          "fiat_code": "VES",
+          "fiat_amount": 100,
+          "payment_method": "face to face",
+          "premium": 1,
+          "created_at": 1698937797
+        }
+      }
+    }
+  },
+  null
+]
+```
+
+The `amount` field in the embedded `SmallOrder` is the **slashed bond amount** (not the original trade amount). For a range-order maker bond, this is the proportional slice amount for the taken sub-order.
+
+## What happens next
+
+After `bond-slashed` is sent to the responsible party, Mostro also:
+
+1. **Cancels or republishes the order** depending on which party was responsible:
+   - **Maker responsible** (e.g. maker-as-seller never paid the hold invoice): the order is **cancelled** (since the maker cannot be trusted to fulfil it). The maker receives the `bond-slashed` notice followed by a `canceled` confirmation.
+   - **Taker responsible** (e.g. taker-as-buyer never submitted their invoice): the order is **republished** to the book as `pending` so the maker can be matched again. The taker receives `bond-slashed` followed by `canceled`. The maker's bond (if any) remains `Locked`.
+
+2. **Asks the winning counterparty for a payout invoice** by sending them an [`add-bond-invoice`](./add_bond_invoice.md) message for their share of the slashed bond (governed by `bond_slash_node_share_pct` — the node retains its share, the rest goes to the counterparty).
+
+## Expected client behaviour
+
+- Surface `bond-slashed` to the user as an explicit forfeiture notice, not as a generic cancellation. Suggested wording: *"Your bond of `amount` Sats has been forfeited due to a waiting-state timeout."*
+- This action is distinct from `canceled` — clients should not suppress it or merge it into the cancel flow.
+- A `canceled` message will typically follow for the order itself; clients should handle both.
+
+## Note on cancels vs. slashes
+
+A cancel sent by either party **before** the timeout elapses never triggers `bond-slashed`. Bonds are always released (never slashed) on user-initiated cancels. Only the automated scheduler-driven timeout slash path emits this action, and only when `slash_on_waiting_timeout = true` is set by the operator.

src/cancel.md

@@ -68,7 +68,26 @@ Mostro updates the addressable event with `d` tag `<Order Id>` to change the sta
 
 ## Bond race during take
 
-A client that sent `take-buy` / `take-sell` and is waiting for [`pay-bond-invoice`](./pay_bond_invoice.md) may receive `Action::Canceled` instead — meaning another user paid their bond first on the same order (whichever bond locks first wins; see [pay bond invoice](./pay_bond_invoice.md)). Surface this clearly to the user, e.g. *"Order was taken by another user before you locked the bond."* Do not silently retry the take — the order may not be available anymore, and the supersede mechanism on the daemon side has already discarded the prior bond request.
+Multiple takers may simultaneously attempt to take the same order: each creates their own bond hold invoice (a `Requested` bond row) and whichever HTLC is accepted first by LND wins. When a bond locks, all other concurrent `Requested` bonds on the same order are released and their takers each receive `Action::Canceled`.
+
+A client that sent `take-buy` / `take-sell` and is waiting for [`pay-bond-invoice`](./pay_bond_invoice.md) may therefore receive `canceled` instead — meaning another taker's bond locked first. Surface this clearly to the user, e.g. *"Order was taken by another user before you locked the bond."* Do not silently retry the take — the order may no longer be available.
+
+## Cancel during `waiting-taker-bond`
+
+An order remains in the daemon-internal `waiting-taker-bond` state (NIP-33 `s` tag still `pending`) while one or more taker bonds are outstanding. Cancels during this window are routed differently from cancels on `pending` orders.
+
+### Taker self-cancel
+
+A taker who has a `Requested` (unpaid) bond on an order may cancel it by sending `cancel`. Mostro releases **only that taker's bond** (LND invoice cancelled, funds returned). Other concurrent takers' bonds are unaffected and continue racing.
+
+- If the cancelling taker was the only prospective taker, the order drops back to `pending` and is visible on the order book again.
+- If other takers' bonds are still `Requested`, the order remains in `waiting-taker-bond` with those bonds still racing.
+
+The maker is not notified; the NIP-33 order event stays `pending` throughout.
+
+### Maker cancel
+
+The maker can cancel the order at any point before trade flow starts (i.e. while in `pending` or `waiting-taker-bond`). Sending `cancel` releases **all** concurrent taker bonds on the order, notifies each prospective taker with `canceled`, transitions the order to `canceled`, and publishes the updated NIP-33 event.
 
 ## Cancel cooperatively
 

src/message_suggestions_for_actions.md

@@ -19,6 +19,15 @@ Below are suggestions for messages that clients can show to users when receiving
 - **add-bond-invoice:**  
   Please send me a Lightning invoice for `amount` Sats — this is your share of a slashed bond on order `id`. You have until `deadline` to submit it, or your share will be forfeited and the entire bond will be retained by the node.
 
+- **bond-invoice-accepted:**  
+  Your bond payout invoice has been received. The payment is being processed — you'll be notified once it completes.
+
+- **bond-payout-completed:**  
+  Your bond payout of `amount` Sats has been sent successfully. The funds should arrive in your Lightning wallet shortly.
+
+- **bond-slashed:**  
+  Your anti-abuse bond of `amount` Sats has been forfeited. This happened because the waiting-state timeout elapsed before you completed your required action on order `id`. The bond has been settled into the node's wallet.
+
 - **add-invoice:**  
   Please send me an invoice for `amount` satoshis equivalent to `fiat_code` `fiat_amount`. This is where I will send the funds upon trade completion. If you don’t provide the invoice within `expiration_seconds`, the trade will be canceled.
 

src/new_buy_order.md

@@ -38,6 +38,16 @@ The nostr event will look like this:
 }
 ```
 
+## Optional: anti-abuse maker bond
+
+When the Mostro node has bonds enabled and `apply_to` is `"make"` or `"both"`, the maker must lock a bond **before** the order is published. Instead of a `new-order` confirmation, Mostro first responds with a [`pay-bond-invoice`](./pay_bond_invoice.md#maker-bond) message asking the maker to pay a small hold invoice (typically ~1% of the trade amount). The order is **not visible on Nostr** until the bond HTLC is accepted.
+
+Only after the maker pays the bond does Mostro:
+1. Publish the order to Nostr with status `pending`.
+2. Send the `new-order` confirmation (shown below).
+
+If the maker never pays the bond invoice it expires and no order is created. See [Pay bond invoice — Maker bond](./pay_bond_invoice.md#maker-bond) for details.
+
 ## Confirmation message
 
 Mostro will send back a nip59 event as a confirmation message, the message in the rumor looks like the following:

src/new_sell_order.md

@@ -47,6 +47,16 @@ The event to send to Mostro would look like this:
 }
 ```
 
+## Optional: anti-abuse maker bond
+
+When the Mostro node has bonds enabled and `apply_to` is `"make"` or `"both"`, the maker must lock a bond **before** the order is published. Instead of a `new-order` confirmation, Mostro first responds with a [`pay-bond-invoice`](./pay_bond_invoice.md#maker-bond) message asking the maker to pay a small hold invoice (typically ~1% of the trade amount). The order is **not visible on Nostr** until the bond HTLC is accepted.
+
+Only after the maker pays the bond does Mostro:
+1. Publish the order to Nostr with status `pending`.
+2. Send the `new-order` confirmation (shown below).
+
+If the maker never pays the bond invoice it expires and no order is created. See [Pay bond invoice — Maker bond](./pay_bond_invoice.md#maker-bond) for details.
+
 ## Confirmation message
 
 Mostro will send back a nip59 event as a confirmation message to the user like the following (unencrypted rumor's content example):

src/new_sell_range_order.md

@@ -30,6 +30,14 @@ Here we have two new fields, `min_amount` and `max_amount`, to define the range
 
 When a taker takes the order, the amount will be set on the message.
 
+## Optional: anti-abuse maker bond
+
+When the Mostro node has bonds enabled and `apply_to` is `"make"` or `"both"`, the maker of a range order must lock a bond **before** the order is published — same as non-range orders, with one key difference: **the bond is sized against `max_amount`**, not the minimum.
+
+Mostro responds to the `new-order` with a [`pay-bond-invoice`](./pay_bond_invoice.md#maker-bond) instead of the confirmation below. The order is not published to Nostr until the bond HTLC is accepted.
+
+When a taker takes a slice of the range order, the bond obligation is reduced proportionally (the slice's fiat amount relative to `max_amount`). The bond hold invoice remains `Locked` for the lifetime of the range order and is settled once in full when the range closes; partial slashes are tracked as child bond rows rather than early partial settlements. See [Pay bond invoice — Maker bond](./pay_bond_invoice.md#maker-bond) for details.
+
 ## Confirmation message
 
 Mostro will send back a nip59 event as a confirmation message to the user like the following: