Skip to content

Commit 60f4956

Browse files
grunchclaude
andcommitted
docs: correct waiting-*-bond status echo to match implementation
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 parent 2ec4c38 commit 60f4956

5 files changed

Lines changed: 16 additions & 14 deletions

File tree

src/bond_slashed.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,13 +23,13 @@ The `bond-slashed` action is a notification Mostro sends to a bonded party when
2323
"order": {
2424
"id": "<Order Id>",
2525
"kind": "sell",
26-
"status": "canceled",
26+
"status": null,
2727
"amount": 785,
2828
"fiat_code": "VES",
2929
"fiat_amount": 100,
3030
"payment_method": "face to face",
3131
"premium": 1,
32-
"created_at": 1698937797
32+
"created_at": null
3333
}
3434
}
3535
}
@@ -38,7 +38,7 @@ The `bond-slashed` action is a notification Mostro sends to a bonded party when
3838
]
3939
```
4040

41-
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.
41+
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. The `status` field is `null` on this message — the `SmallOrder` carries only the bond context (id, kind, amounts), not an order status; clients should rely on the `bond-slashed` action itself, and on the separate order-status messages that follow (`canceled` for the order, plus a republished NIP-33 event when the order returns to the book).
4242

4343
## What happens next
4444

src/order_event.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ Events are [addressable events](https://github.com/nostr-protocol/nips/blob/mast
6565
- `f` < Currency >: The fiat asset being traded, using the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) standard.
6666
- `s` < Status >: `pending`, `canceled`, `in-progress`, `success`, `expired`.
6767

68-
An order with `s = pending` may already be matched to a taker who is in the middle of paying their anti-abuse bond. It remains takeable in this window — another user may attempt the take, and whichever bond locks first wins (the prior taker is notified with `Action::Canceled`, see [Cancel](./cancel.md)). The internal daemon state that tracks this (`waiting-taker-bond`, visible only in DM payload echoes) is not part of NIP-69's four-bucket wire model. Clients **must not** gray out or hide a `pending` order from the local order-book view just because their user has initiated a take.
68+
An order with `s = pending` may already be matched to a taker who is in the middle of paying their anti-abuse bond. It remains takeable in this window — another user may attempt the take, and whichever bond locks first wins (the prior taker is notified with `Action::Canceled`, see [Cancel](./cancel.md)). The internal daemon state that tracks this (`waiting-taker-bond`, kept in the daemon's database only and never emitted on the wire) is not part of NIP-69's four-bucket wire model. Clients **must not** gray out or hide a `pending` order from the local order-book view just because their user has initiated a take.
6969
- `amt` < Amount >: The amount of Bitcoin to be traded, the amount is defined in satoshis, if `0` means that the amount of satoshis will be obtained from a public API after the taker accepts the order.
7070
- `fa` < Fiat amount >: The fiat amount being traded, for range orders two values are expected, the minimum and maximum amount.
7171
- `pm` < Payment method >: The payment method used for the trade, if the order has multiple payment methods, they should be separated by a comma.

src/pay_bond_invoice.md

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ The message's content has the same shape as `pay-invoice`; only the action discr
3030
{
3131
"id": "<Order Id>",
3232
"kind": "sell",
33-
"status": "waiting-taker-bond",
33+
"status": "pending",
3434
"amount": 7851,
3535
"fiat_code": "VES",
3636
"fiat_amount": 100,
@@ -47,7 +47,7 @@ The message's content has the same shape as `pay-invoice`; only the action discr
4747
]
4848
```
4949

50-
> Note: the `status` value `"waiting-taker-bond"` here is the daemon-internal state echoed in the DM payload. The corresponding NIP-33 addressable order event's `s` tag is still `pending`.
50+
> Note: the `SmallOrder` echo carries `"status": "pending"` — the NIP-69 wire bucket the order is advertised in while the bond is outstanding. The daemon-internal state `waiting-taker-bond` (which Mostro uses to route subsequent messages) is tracked only in the daemon's database and is **never** emitted in the DM payload. Clients should dispatch on the `pay-bond-invoice` action, not on a status field.
5151
5252
### Expected client behaviour
5353

@@ -64,11 +64,11 @@ Once the bond HTLC is `Accepted`, Mostro proceeds with the normal trade flow:
6464

6565
> **Important — buy order taken (seller-as-taker):** this is the only flow on which a single user pays **two hold invoices in sequence on the same order** — first the bond (`pay-bond-invoice`), then the trade escrow (`pay-invoice`). They arrive as distinct actions and must be presented to the user as separate steps. Do not auto-pay either, do not coalesce them, and make the distinction obvious in the UI; this is the most error-prone path for client developers.
6666
67-
### Daemon status `waiting-taker-bond` (DM payloads only)
67+
### Daemon status `waiting-taker-bond` (internal only)
6868

69-
In addition to the NIP-69 wire status (`pending` while the bond is outstanding), Mostro tags the order's internal state as `waiting-taker-bond` so it can route subsequent messages correctly. Clients see this value in the `SmallOrder` echo embedded in `pay-bond-invoice` payloads and may use it to drive UI ("Waiting for bond payment"). It does **not** appear on the addressable NIP-33 order event — that one continues to advertise the order as `pending`.
69+
Mostro tags the order's internal state as `waiting-taker-bond` so it can route subsequent messages correctly while one or more taker bonds are outstanding. This status lives **only in the daemon's database** — it is neither published on the NIP-33 order event (whose `s` tag stays `pending`) nor echoed in any DM payload (the `pay-bond-invoice` `SmallOrder` carries `pending`, as shown above). It is documented here only to describe the daemon's lifecycle; clients never observe the literal `waiting-taker-bond` value on the wire.
7070

71-
Internal transitions (visible only in DM payload echoes):
71+
Internal transitions (not visible to clients):
7272

7373
- From `pending``waiting-taker-bond`, after a successful `take-buy` / `take-sell` when bonds are enabled.
7474
- From `waiting-taker-bond``waiting-payment` (buy order taken) or → `waiting-buyer-invoice` (sell order taken), once the bond HTLC is `Accepted`.
@@ -90,7 +90,7 @@ When `apply_to` is `"make"` or `"both"`, the **maker** must lock a bond before t
9090

9191
- **Direction:** Mostro → user (the maker).
9292
- **Trigger:** Sent in response to a `new-order` message when the operator has bonds enabled for makers, **before** the order is published.
93-
- **Order visibility:** The order is **not published** to Nostr while the maker bond is outstanding. External observers see nothing — no `pending` order event, no order in the book. This differs from the taker bond, where the order remains visible and re-takeable throughout. The daemon tracks this internally as `waiting-maker-bond`, a status visible only in DM payload echoes.
93+
- **Order visibility:** The order is **not published** to Nostr while the maker bond is outstanding. External observers see nothing — no `pending` order event, no order in the book. This differs from the taker bond, where the order remains visible and re-takeable throughout. The daemon tracks this internally as `waiting-maker-bond`, a status kept in its database only — it is never emitted on the wire (the `SmallOrder` echo carries `pending`, as shown below).
9494

9595
### Mostro message to the maker
9696

@@ -136,9 +136,11 @@ Once the maker's bond HTLC is `Accepted`:
136136
1. Mostro publishes the order to Nostr with status `pending` for the first time.
137137
2. Mostro sends the maker the `new-order` confirmation message (same as in the no-bond flow — see [Creating a new sell order](./new_sell_order.md) and [Creating a new buy order](./new_buy_order.md)).
138138

139-
### Daemon status `waiting-maker-bond` (DM payloads only)
139+
### Daemon status `waiting-maker-bond` (internal only)
140+
141+
Like `waiting-taker-bond`, this status lives **only in the daemon's database** — it is never published on a NIP-33 event (none exists yet) nor echoed in any DM payload (the `pay-bond-invoice` `SmallOrder` carries `pending`). It is documented here only to describe the daemon's lifecycle.
140142

141-
Internal transitions (visible only in DM payload echoes):
143+
Internal transitions (not visible to clients):
142144

143145
- On `new-order` receipt → `waiting-maker-bond`, before any NIP-33 event is emitted.
144146
- `waiting-maker-bond``pending` (and order published), once the bond HTLC is `Accepted`.

src/take_buy.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ The event to send to Mostro would look like this:
3333

3434
## Optional: anti-abuse bond step
3535

36-
When the receiving Mostro node has bonds enabled, the seller (taker) first receives a [`pay-bond-invoice`](./pay_bond_invoice.md) message; the published NIP-33 order event remains `pending` (re-takeability is preserved — see [order event](./order_event.md)) and the DM payload echoes the internal status `waiting-taker-bond`. Only after the bond HTLC is `Accepted` does Mostro send the `pay-invoice` message described below.
36+
When the receiving Mostro node has bonds enabled, the seller (taker) first receives a [`pay-bond-invoice`](./pay_bond_invoice.md) message; the published NIP-33 order event remains `pending` (re-takeability is preserved — see [order event](./order_event.md)) and the bond message's embedded `SmallOrder` carries `status: pending` (the daemon tracks the internal `waiting-taker-bond` state in its database only — it is never emitted on the wire). Only after the bond HTLC is `Accepted` does Mostro send the `pay-invoice` message described below.
3737

3838
This is the **only flow on which a single user pays two hold invoices in sequence on the same order**: the bond first, then the trade hold invoice. They arrive as distinct actions (`pay-bond-invoice` then `pay-invoice`) and clients **must** present them as separate steps. Clients that do not recognise `pay-bond-invoice` should expect the take to time out and surface a clear error to the user — do not silently retry the take.
3939

src/take_sell.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ If the order amount is `0` the buyer doesn't know the exact amount to create the
1919

2020
## Optional: anti-abuse bond step
2121

22-
When the receiving Mostro node has bonds enabled, the buyer (taker) first receives a [`pay-bond-invoice`](./pay_bond_invoice.md) message; the published NIP-33 order event remains `pending` (re-takeability is preserved — see [order event](./order_event.md)) and the DM payload echoes the internal status `waiting-taker-bond`. Only after the bond HTLC is `Accepted` does Mostro send the `add-invoice` message described below. Clients that do not recognise `pay-bond-invoice` should expect the take to time out and surface a clear error to the user — do not silently retry the take.
22+
When the receiving Mostro node has bonds enabled, the buyer (taker) first receives a [`pay-bond-invoice`](./pay_bond_invoice.md) message; the published NIP-33 order event remains `pending` (re-takeability is preserved — see [order event](./order_event.md)) and the bond message's embedded `SmallOrder` carries `status: pending` (the daemon tracks the internal `waiting-taker-bond` state in its database only — it is never emitted on the wire). Only after the bond HTLC is `Accepted` does Mostro send the `add-invoice` message described below. Clients that do not recognise `pay-bond-invoice` should expect the take to time out and surface a clear error to the user — do not silently retry the take.
2323

2424
## Mostro response
2525

0 commit comments

Comments
 (0)