You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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>
Copy file name to clipboardExpand all lines: src/bond_slashed.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -23,13 +23,13 @@ The `bond-slashed` action is a notification Mostro sends to a bonded party when
23
23
"order": {
24
24
"id": "<Order Id>",
25
25
"kind": "sell",
26
-
"status": "canceled",
26
+
"status": null,
27
27
"amount": 785,
28
28
"fiat_code": "VES",
29
29
"fiat_amount": 100,
30
30
"payment_method": "face to face",
31
31
"premium": 1,
32
-
"created_at": 1698937797
32
+
"created_at": null
33
33
}
34
34
}
35
35
}
@@ -38,7 +38,7 @@ The `bond-slashed` action is a notification Mostro sends to a bonded party when
38
38
]
39
39
```
40
40
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).
Copy file name to clipboardExpand all lines: src/order_event.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -65,7 +65,7 @@ Events are [addressable events](https://github.com/nostr-protocol/nips/blob/mast
65
65
-`f` < Currency >: The fiat asset being traded, using the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) standard.
66
66
-`s` < Status >: `pending`, `canceled`, `in-progress`, `success`, `expired`.
67
67
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.
69
69
-`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.
70
70
-`fa` < Fiat amount >: The fiat amount being traded, for range orders two values are expected, the minimum and maximum amount.
71
71
-`pm` < Payment method >: The payment method used for the trade, if the order has multiple payment methods, they should be separated by a comma.
Copy file name to clipboardExpand all lines: src/pay_bond_invoice.md
+10-8Lines changed: 10 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -30,7 +30,7 @@ The message's content has the same shape as `pay-invoice`; only the action discr
30
30
{
31
31
"id": "<Order Id>",
32
32
"kind": "sell",
33
-
"status": "waiting-taker-bond",
33
+
"status": "pending",
34
34
"amount": 7851,
35
35
"fiat_code": "VES",
36
36
"fiat_amount": 100,
@@ -47,7 +47,7 @@ The message's content has the same shape as `pay-invoice`; only the action discr
47
47
]
48
48
```
49
49
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.
51
51
52
52
### Expected client behaviour
53
53
@@ -64,11 +64,11 @@ Once the bond HTLC is `Accepted`, Mostro proceeds with the normal trade flow:
64
64
65
65
> **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.
66
66
67
-
### Daemon status `waiting-taker-bond` (DM payloads only)
67
+
### Daemon status `waiting-taker-bond` (internal only)
68
68
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.
70
70
71
-
Internal transitions (visible only in DM payload echoes):
71
+
Internal transitions (not visible to clients):
72
72
73
73
- From `pending` → `waiting-taker-bond`, after a successful `take-buy` / `take-sell` when bonds are enabled.
74
74
- 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
90
90
91
91
-**Direction:** Mostro → user (the maker).
92
92
-**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).
94
94
95
95
### Mostro message to the maker
96
96
@@ -136,9 +136,11 @@ Once the maker's bond HTLC is `Accepted`:
136
136
1. Mostro publishes the order to Nostr with status `pending` for the first time.
137
137
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)).
138
138
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.
140
142
141
-
Internal transitions (visible only in DM payload echoes):
143
+
Internal transitions (not visible to clients):
142
144
143
145
- On `new-order` receipt → `waiting-maker-bond`, before any NIP-33 event is emitted.
144
146
-`waiting-maker-bond` → `pending` (and order published), once the bond HTLC is `Accepted`.
Copy file name to clipboardExpand all lines: src/take_buy.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -33,7 +33,7 @@ The event to send to Mostro would look like this:
33
33
34
34
## Optional: anti-abuse bond step
35
35
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.
37
37
38
38
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.
Copy file name to clipboardExpand all lines: src/take_sell.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,7 +19,7 @@ If the order amount is `0` the buyer doesn't know the exact amount to create the
19
19
20
20
## Optional: anti-abuse bond step
21
21
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.
0 commit comments