Add range order docs (#287)

book/src/new_sell_order.md

@@ -14,6 +14,8 @@ To create a new sell order the user should send a Nostr event kind 4 (an encrypt
         "status": "pending",
         "amount": 0,
         "fiat_code": "VES",
+        "min_amount": null,
+        "max_amount": null,
         "fiat_amount": 100,
         "payment_method": "face to face",
         "premium": 1,

book/src/new_sell_range_order.md

@@ -0,0 +1,90 @@
+# Creating a new sell range order
+
+To create a new range order the user should send a Nostr event kind 4 (an encrypted message) to Mostro with the following content:
+
+```json
+{
+  "order": {
+    "version": 1,
+    "pubkey": "00000ba40c5795451705bb9c165b3af93c846894d3062a9cd7fcba090eb3bf78", // Seller's real pubkey
+    "action": "new-order",
+    "content": {
+      "order": {
+        "kind": "sell",
+        "status": "pending",
+        "amount": 0,
+        "fiat_code": "VES",
+        "min_amount": 10,
+        "max_amount": 20,
+        "fiat_amount": 0,
+        "payment_method": "face to face",
+        "premium": 1,
+        "created_at": 0
+      }
+    }
+  }
+}
+```
+
+We two new fields, `min_amount` and `max_amount`, to define the range of the order. The `fiat_amount` field is set to 0 to indicate that the order is for a range of amounts.
+
+When a taker takes the order, the amount will be set on the message.
+
+## Confirmation message
+
+Mostro will send back a nip04 event as a confirmation message to the user like the following:
+
+```json
+{
+  "order": {
+    "version": 1,
+    "id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842",
+    "pubkey": "00000ba40c5795451705bb9c165b3af93c846894d3062a9cd7fcba090eb3bf78",
+    "content": {
+      "order": {
+        "id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842",
+        "kind": "sell",
+        "status": "pending",
+        "amount": 0,
+        "fiat_code": "VES",
+        "min_amount": 10,
+        "max_amount": 20,
+        "fiat_amount": 0,
+        "payment_method": "face to face",
+        "premium": 1,
+        "created_at": 1698870173
+      }
+    }
+  }
+}
+```
+
+Mostro publishes this order as an event kind `38383` with status `pending`:
+
+```json
+[
+  "EVENT",
+  "RAND",
+  {
+    "id": "84fad0d29cb3529d789faeff2033e88fe157a48e071c6a5d1619928289420e31",
+    "pubkey": "dbe0b1be7aafd3cfba92d7463edbd4e33b2969f61bd554d37ac56f032e13355a",
+    "created_at": 1702548701,
+    "kind": 38383,
+    "tags": [
+      ["d", "ede61c96-4c13-4519-bf3a-dcf7f1e9d842"],
+      ["k", "sell"],
+      ["f", "VES"],
+      ["s", "pending"],
+      ["amt", "0"],
+      ["fa", "10-20"],
+      ["pm", "face to face"],
+      ["premium", "1"],
+      ["y", "mostrop2p"],
+      ["z", "order"],
+      ["expiration", "1716453501"]
+    ],
+    "content": "",
+    "sig": "7e8fe1eb644f33ff51d8805c02a0e1a6d034e6234eac50ef7a7e0dac68a0414f7910366204fa8217086f90eddaa37ded71e61f736d1838e37c0b73f6a16c4af2"
+  }
+]
+```

book/src/take_buy_range_order.md

@@ -0,0 +1,21 @@
+# Taking a buy range order
+
+If the order fiat amount is a range like `10-20` the seller must indicate a fiat amount to take the order, seller will send a message in a Nostr event kind 4 to Mostro with the following content:
+
+```json
+{
+  "order": {
+    "version": 1,
+    "id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842",
+    "pubkey": "0000147e939bef2b81c27af4c1b702c90c3843f7212a34934bff1e049b7f1427",
+    "action": "take-buy",
+    "content": {
+      "amount": 15
+    }
+  }
+}
+```
+
+## Mostro response
+
+Response is the same as we explained in the [Taking a buy order](./take_buy.md) section.

book/src/take_sell_range_order.md

@@ -0,0 +1,97 @@
+# Taking a sell range order
+
+If the order fiat amount is a range like `10-20` the buyer must indicate a fiat amount to take the order, buyer will send a message in a Nostr event kind 4 to Mostro with the following content:
+
+```json
+{
+  "order": {
+    "version": 1,
+    "id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842",
+    "pubkey": "0000147e939bef2b81c27af4c1b702c90c3843f7212a34934bff1e049b7f1427",
+    "action": "take-sell",
+    "content": {
+      "amount": 15
+    }
+  }
+}
+```
+
+## Mostro response
+
+In order to continue the buyer needs to send a lightning network invoice to Mostro, in this case the amount of the order is `0`, so Mostro will need to calculate the amount of sats for this order, then Mostro will send back a message asking for a LN invoice indicating the correct amount of sats that the invoice should have, here the unencrypted content of the message:
+
+```json
+{
+  "order": {
+    "version": 1,
+    "id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842",
+    "pubkey": null,
+    "action": "add-invoice",
+    "content": {
+      "order": {
+        "id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842",
+        "amount": 7851,
+        "fiat_code": "VES",
+        "min_amount": 10,
+        "max_amount": 20,
+        "fiat_amount": 15,
+        "payment_method": "face to face",
+        "premium": 1,
+        "master_buyer_pubkey": null,
+        "master_seller_pubkey": null,
+        "buyer_invoice": null,
+        "created_at": null,
+        "expires_at": null
+      }
+    }
+  }
+}
+```
+
+Mostro updates the nip 33 event with `d` tag `ede61c96-4c13-4519-bf3a-dcf7f1e9d842` to change the status to `waiting-buyer-invoice`:
+
+```json
+[
+  "EVENT",
+  "RAND",
+  {
+    "id": "eb0582360ebd3836c90711f774fbecb27e600f4a5fedf4fc2d16fc852f8380b1",
+    "pubkey": "dbe0b1be7aafd3cfba92d7463edbd4e33b2969f61bd554d37ac56f032e13355a",
+    "created_at": 1702549437,
+    "kind": 38383,
+    "tags": [
+      ["d", "ede61c96-4c13-4519-bf3a-dcf7f1e9d842"],
+      ["k", "sell"],
+      ["f", "VES"],
+      ["s", "waiting-buyer-invoice"],
+      ["amt", "7851"],
+      ["fa", "15"],
+      ["pm", "face to face"],
+      ["premium", "1"],
+      ["y", "mostrop2p"],
+      ["z", "order"],
+      ["expiration", "1716453501"]
+    ],
+    "content": "",
+    "sig": "a835f8620db3ebdd9fa142ae99c599a61da86321c60f7c9fed0cc57169950f4121757ff64a5e998baccf6b68272aa51819c3e688d8ad586c0177b3cd1ab09c0f"
+  }
+]
+```
+
+## Using a lightning address
+
+The buyer can use a [lightning address](https://github.com/andrerfneves/lightning-address) to receive funds and avoid to create and send lightning invoices on each trade, with a range order we set the fiat amount as the third element of the `payment_request` array, to acomplish this the buyer will send a message in a Nostr event kind 4 to Mostro with the following content:
+
+```json
+{
+  "order": {
+    "version": 1,
+    "id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842",
+    "pubkey": "0000147e939bef2b81c27af4c1b702c90c3843f7212a34934bff1e049b7f1427",
+    "action": "take-sell",
+    "content": {
+      "payment_request": [null, "[email protected]", 15]
+    }
+  }
+}
+```