Add pay hold invoice page (#139)

Small fixes
MostroP2P · Nov 2, 2023 · 7fadff7 · 7fadff7
1 parent 559db1b
commit 7fadff7
Show file tree

Hide file tree

Showing 4 changed files with 107 additions and 12 deletions.
diff --git a/docs/new_order.md b/docs/new_order.md
@@ -6,7 +6,7 @@ All Mostro messages are [Parameterized Replaceable Events](https://github.com/no
 
 ## Communication between users and Mostro
 
-All messages from/to Mostro should be a Nostr event kind 4, the content of the event should be a JSON-serialized string (with no white space or line breaks) of the following structure:
+All messages from/to Mostro should be a Nostr event [kind 4](https://github.com/nostr-protocol/nips/blob/master/04.md), the `content` field of the event should be a base64-encoded, aes-256-cbc encrypted JSON-serialized string (with no white space or line breaks) of the following structure:
 
 - `version`
 - `order_id` (optional)
@@ -21,7 +21,7 @@ To create a new sell order the user should send a Nostr event kind 4 to Mostro w
 ```json
 {
   "version": "0",
-  "pubkey": "npub1qqq...",
+  "pubkey": "npub1qqqxssz4k6swex94zdg5s4pqx3uqlhwsc2vdzvhjvzk33pcypkhqe9aeq2",
   "action": "Order",
   "content": {
     "Order": {
@@ -32,7 +32,6 @@ To create a new sell order the user should send a Nostr event kind 4 to Mostro w
       "fiat_amount": 100,
       "payment_method": "face to face",
       "premium": 1,
-      "master_seller_pubkey": "npub1qqq...",
       "created_at": 0
     }
   }
@@ -44,7 +43,7 @@ Let's explain some of the fields:
 - kind: `Sell` or `Buy`
 - status: Is always `Pending` when creating a new order
 - amount: 0 for when we want to sell with at market price, otherwise the amount in satoshis
-- master_seller_pubkey: Real user's pubkey, we use this when the message was sent from an ephemeral key
+- pubkey: Real user's pubkey, we use this when the message was sent from an ephemeral key
 - created_at: No need to send the correct unix timestamp, Mostro will replace it with the current time
 
 ## Confirmation message

diff --git a/docs/seller_pay_hold_invoice.md b/docs/seller_pay_hold_invoice.md
@@ -0,0 +1,94 @@
+# Seller pays hold invoice
+
+## Overview
+
+All Mostro messages are [Parameterized Replaceable Events](https://github.com/nostr-protocol/nips/blob/master/01.md#kinds) and use `30078` as event `kind`, a list of standard event kinds can be found [here](https://github.com/nostr-protocol/nips#event-kinds)
+
+## Communication between users and Mostro
+
+All messages from/to Mostro should be a Nostr event [kind 4](https://github.com/nostr-protocol/nips/blob/master/04.md), the `content` field of the event should be a base64-encoded, aes-256-cbc encrypted JSON-serialized string (with no white space or line breaks) of the following structure:
+
+- `version`
+- `order_id` (optional)
+- `pubkey` (optional)
+- `action` (https://docs.rs/mostro-core/latest/mostro_core/enum.Action.html)
+- `content` (optional https://docs.rs/mostro-core/latest/mostro_core/enum.Content.html)
+
+## Paying a hold invoice
+
+When the seller is the maker and the order was taken by a buyer, Mostro will send to the seller a message asking to pay the hold invoice, the message will look like this:
+
+```json
+{
+  "version": "0",
+  "order_id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842",
+  "pubkey": null,
+  "action": "PayInvoice",
+  "content": {
+    "PaymentRequest": [
+      {
+        "id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842",
+        "kind": "Sell",
+        "status": "WaitingBuyerInvoice",
+        "amount": 7851,
+        "fiat_code": "VES",
+        "fiat_amount": 100,
+        "payment_method": "face to face",
+        "premium": 1,
+        "created_at": 1698937797
+      },
+      "lnbcrt78510n1pj59wmepp50677g8tffdqa2p8882y0x6newny5vtz0hjuyngdwv226nanv4uzsdqqcqzzsxqyz5vqsp5skn973360gp4yhlpmefwvul5hs58lkkl3u3ujvt57elmp4zugp4q9qyyssqw4nzlr72w28k4waycf27qvgzc9sp79sqlw83j56txltz4va44j7jda23ydcujj9y5k6k0rn5ms84w8wmcmcyk5g3mhpqepf7envhdccp72nz6e"
+    ]
+  }
+}
+```
+
+After the hold invoice is paid Mostro will send a new message to seller with the following content:
+
+```json
+{
+  "version": "0",
+  "order_id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842",
+  "pubkey": null,
+  "action": "BuyerTookOrder",
+  "content": {
+    "SmallOrder": {
+      "id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842",
+      "amount": 7851,
+      "fiat_code": "VES",
+      "fiat_amount": 100,
+      "payment_method": "face to face",
+      "premium": 1,
+      "buyer_pubkey": "npub1qqqt938cer4dvlslg04zwwf66ts8r3txp6mv79cx2498pyuqx8uq0c7qkj",
+      "seller_pubkey": "npub1qqqxssz4k6swex94zdg5s4pqx3uqlhwsc2vdzvhjvzk33pcypkhqe9aeq2"
+    }
+  }
+}
+```
+
+Mostro also send a message to the buyer, this way they can both to to each other in private, this message would look like this:
+
+```json
+{
+  "version": "0",
+  "order_id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842",
+  "pubkey": null,
+  "action": "HoldInvoicePaymentAccepted",
+  "content": {
+    "SmallOrder": {
+      "id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842",
+      "amount": 7851,
+      "fiat_code": "VES",
+      "fiat_amount": 100,
+      "payment_method": "face to face",
+      "premium": 1,
+      "buyer_pubkey": "npub1qqqt938cer4dvlslg04zwwf66ts8r3txp6mv79cx2498pyuqx8uq0c7qkj",
+      "seller_pubkey": "npub1qqqxssz4k6swex94zdg5s4pqx3uqlhwsc2vdzvhjvzk33pcypkhqe9aeq2"
+    }
+  }
+}
+```
+
+## Ephemeral keys
+
+Mostro clients should use ephemeral keys to communicate with Mostro, indicating the pubkey where they want to be contacted in the `pubkey` field of the message, this way orders and users can't be easily linked, `buyer_pubkey` and `seller_pubkey` fields are the real pubkeys of the users.
diff --git a/docs/take_sell.md b/docs/take_sell.md
@@ -6,7 +6,7 @@ All Mostro messages are [Parameterized Replaceable Events](https://github.com/no
 
 ## Communication between users and Mostro
 
-All messages from/to Mostro should be a Nostr event kind 4, the content of the event should be a JSON-serialized string (with no white space or line breaks) of the following structure:
+All messages from/to Mostro should be a Nostr event [kind 4](https://github.com/nostr-protocol/nips/blob/master/04.md), the `content` field of the event should be a base64-encoded, aes-256-cbc encrypted JSON-serialized string (with no white space or line breaks) of the following structure:
 
 - `version`
 - `order_id` (optional)
@@ -16,31 +16,31 @@ All messages from/to Mostro should be a Nostr event kind 4, the content of the e
 
 ## Taking a sell order
 
-To take a new sell order the user should send a Nostr event kind 4 to Mostro with the following content:
+If the order amount is `0` the buyer don't know the exact amount to create the invoice, buyer will send a message in a Nostr event kind 4 to Mostro with the following content:
 
 ```json
 {
   "version": "0",
-  "pubkey": "npub1qqq...",
-  "order_id": "68e373ef-898b-4312-9f49-dfc50404e3b2",
+  "pubkey": "npub1qqqt938cer4dvlslg04zwwf66ts8r3txp6mv79cx2498pyuqx8uq0c7qkj",
+  "order_id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842",
   "action": "TakeSell",
   "content": null
 }
 ```
 
 ## Mostro response
 
-In order to continue the buyer needs to send a lightning network invoice to Mostro, if the amount of the order is `0`, Mostro will need to calculate the amount of sats of 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:
+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:
 
 ```json
 {
   "version": "0",
-  "order_id": "68e373ef-898b-4312-9f49-dfc50404e3b2",
+  "order_id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842",
   "pubkey": null,
   "action": "AddInvoice",
   "content": {
     "SmallOrder": {
-      "id": "68e373ef-898b-4312-9f49-dfc50404e3b2",
+      "id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842",
       "amount": 7851,
       "fiat_code": "VES",
       "fiat_amount": 100,
@@ -55,6 +55,8 @@ In order to continue the buyer needs to send a lightning network invoice to Most
 
 ## Buyer sends LN invoice
 
+Here is how the buyer send the LN invoice to Mostro, in case the order has a fixed sats amount, the buyer can we skip the previous step:
+
 ```json
 {
   "version": "0",

diff --git a/docs/user_rating.md b/docs/user_rating.md
@@ -6,7 +6,7 @@ All Mostro messages are [Parameterized Replaceable Events](https://github.com/no
 
 ## Communication between users and Mostro
 
-All messages from/to Mostro should be a Nostr event kind 4, the content of the event should be a JSON-serialized string (with no white space or line breaks) of the following structure:
+All messages from/to Mostro should be a Nostr event [kind 4](https://github.com/nostr-protocol/nips/blob/master/04.md), the `content` field of the event should be a base64-encoded, aes-256-cbc encrypted JSON-serialized string (with no white space or line breaks) of the following structure:
 
 - `version`
 - `order_id` (optional)