Update specs adding json event examples (#164)

MostroP2P · Dec 15, 2023 · 0c585b8 · 0c585b8
1 parent 9e3d924
commit 0c585b8
Show file tree

Hide file tree

Showing 10 changed files with 418 additions and 8 deletions.
diff --git a/book/src/cancel.md b/book/src/cancel.md
@@ -1,6 +1,6 @@
 # Cancel Order
 
-A user can cancel an Order created by himself and with status `Pending` sending action `Cancel`, the message will look like this:
+A user can cancel an Order created by himself and with status `Pending` sending action `Cancel`, the message content will look like this:
 
 ```json
 {
@@ -30,6 +30,35 @@ Mostro will send a message with action `Cancel` confirming the order was cancele
 }
 ```
 
+Mostro updates the nip 33 event with `d` tag `ede61c96-4c13-4519-bf3a-dcf7f1e9d842` to change the status to `Canceled`:
+
+```json
+[
+  "EVENT",
+  "RAND",
+  {
+    "id": "eb0582360ebd3836c90711f774fbecb27e600f4a5fedf4fc2d16fc852f8380b1",
+    "pubkey": "dbe0b1be7aafd3cfba92d7463edbd4e33b2969f61bd554d37ac56f032e13355a",
+    "created_at": 1702549437,
+    "kind": 38383,
+    "tags": [
+      ["d", "ede61c96-4c13-4519-bf3a-dcf7f1e9d842"],
+      ["k", "Sell"],
+      ["f", "VES"],
+      ["s", "Canceled"],
+      ["amt", "7851"],
+      ["fa", "100"],
+      ["pm", "face to face"],
+      ["premium", "1"],
+      ["l", "MostroP2P"],
+      ["data_label", "order"]
+    ],
+    "content": "",
+    "sig": "a835f8620db3ebdd9fa142ae99c599a61da86321c60f7c9fed0cc57169950f4121757ff64a5e998baccf6b68272aa51819c3e688d8ad586c0177b3cd1ab09c0f"
+  }
+]
+```
+
 ## Cancel cooperatively
 
 A user can cancel an `Active` order, but will need the counterparty to agree, let's look at an example where the seller initiates a cooperative cancellation:
@@ -74,6 +103,35 @@ And this message to the buyer:
 }
 ```
 
+Mostro updates the nip 33 event with `d` tag `ede61c96-4c13-4519-bf3a-dcf7f1e9d842` to change the status to `CooperativelyCanceled`:
+
+```json
+[
+  "EVENT",
+  "RAND",
+  {
+    "id": "eb0582360ebd3836c90711f774fbecb27e600f4a5fedf4fc2d16fc852f8380b1",
+    "pubkey": "dbe0b1be7aafd3cfba92d7463edbd4e33b2969f61bd554d37ac56f032e13355a",
+    "created_at": 1702549437,
+    "kind": 38383,
+    "tags": [
+      ["d", "ede61c96-4c13-4519-bf3a-dcf7f1e9d842"],
+      ["k", "Sell"],
+      ["f", "VES"],
+      ["s", "CooperativelyCanceled"],
+      ["amt", "7851"],
+      ["fa", "100"],
+      ["pm", "face to face"],
+      ["premium", "1"],
+      ["l", "MostroP2P"],
+      ["data_label", "order"]
+    ],
+    "content": "",
+    "sig": "a835f8620db3ebdd9fa142ae99c599a61da86321c60f7c9fed0cc57169950f4121757ff64a5e998baccf6b68272aa51819c3e688d8ad586c0177b3cd1ab09c0f"
+  }
+]
+```
+
 The buyer can accept the cooperative cancellation sending this message:
 
 ```json

diff --git a/book/src/dispute.md b/book/src/dispute.md
@@ -43,3 +43,5 @@ And here is the message to the buyer:
   }
 }
 ```
+
+Mostro will not update the nip 33 event with `d` tag `ede61c96-4c13-4519-bf3a-dcf7f1e9d842` to change the status to `Dispute`, this is because the order is still active, the dispute is just a way to let the admins and the other party know that there is a problem with the order.
diff --git a/book/src/fiatsent.md b/book/src/fiatsent.md
@@ -51,3 +51,32 @@ And here an example of the message from Mostro to the seller:
   }
 }
 ```
+
+Mostro updates the nip 33 event with `d` tag `ede61c96-4c13-4519-bf3a-dcf7f1e9d842` to change the status to `FiatSent`:
+
+```json
+[
+  "EVENT",
+  "RAND",
+  {
+    "id": "eb0582360ebd3836c90711f774fbecb27e600f4a5fedf4fc2d16fc852f8380b1",
+    "pubkey": "dbe0b1be7aafd3cfba92d7463edbd4e33b2969f61bd554d37ac56f032e13355a",
+    "created_at": 1702549437,
+    "kind": 38383,
+    "tags": [
+      ["d", "ede61c96-4c13-4519-bf3a-dcf7f1e9d842"],
+      ["k", "Sell"],
+      ["f", "VES"],
+      ["s", "FiatSent"],
+      ["amt", "7851"],
+      ["fa", "100"],
+      ["pm", "face to face"],
+      ["premium", "1"],
+      ["l", "MostroP2P"],
+      ["data_label", "order"]
+    ],
+    "content": "",
+    "sig": "a835f8620db3ebdd9fa142ae99c599a61da86321c60f7c9fed0cc57169950f4121757ff64a5e998baccf6b68272aa51819c3e688d8ad586c0177b3cd1ab09c0f"
+  }
+]
+```
diff --git a/book/src/new_order.md b/book/src/new_order.md
@@ -1,6 +1,6 @@
 # Creating a new order
 
-To create a new sell order the user should send a Nostr event kind 4 to Mostro with the following content:
+To create a new sell order the user should send a Nostr event kind 4 (an encrypted message) to Mostro with the following content:
 
 ```json
 {
@@ -32,9 +32,25 @@ Let's explain some of the fields:
 - pubkey: Real user's npub, 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
 
+The event to send to Mostro would look like this:
+
+```json
+{
+  "id": "cade205b849a872d74ba4d2a978135dbc05b4e5f483bb4403c42627dfd24f67d",
+  "kind": 4,
+  "pubkey": "1f5bb148a25bca31506594722e746b10acf2641a12725b12072dcbc46ade544d",
+  "content": "base64-encoded-aes-256-cbc-encrypted-JSON-serialized-string",
+  "tags": [
+    ["p", "dbe0b1be7aafd3cfba92d7463edbd4e33b2969f61bd554d37ac56f032e13355a"] // Mostro's pubkey
+  ],
+  "created_at": 1234567890,
+  "sig": "a21eb195fe418613aa9a3a8a78039b090e50dc3f9fb06b0f3fe41c63221adc073a9317a1f28d9db843a43c28d860ba173b70132ca85b0e706f6487d43a57ee82"
+}
+```
+
 ## Confirmation message
 
-Mostro will send back a confirmation message to the user like the following:
+Mostro will send back a nip04 event as a confirmation message to the user like the following:
 
 ```json
 {
@@ -59,3 +75,32 @@ Mostro will send back a confirmation message to the user like the following:
   }
 }
 ```
+
+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", "100"],
+      ["pm", "face to face"],
+      ["premium", "1"],
+      ["l", "MostroP2P"],
+      ["data_label", "order"]
+    ],
+    "content": "",
+    "sig": "7e8fe1eb644f33ff51d8805c02a0e1a6d034e6234eac50ef7a7e0dac68a0414f7910366204fa8217086f90eddaa37ded71e61f736d1838e37c0b73f6a16c4af2"
+  }
+]
+```
diff --git a/book/src/overview.md b/book/src/overview.md
@@ -2,7 +2,7 @@
 
 ## Overview
 
-All messages broadcasted by Mostro daemon 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)
+All messages broadcasted by Mostro daemon are [Parameterized Replaceable Events](https://github.com/nostr-protocol/nips/blob/master/01.md#kinds) and use `38383` 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
 

diff --git a/book/src/release.md b/book/src/release.md
@@ -59,3 +59,61 @@ Right after seller release sats Mostro will try to pay the buyer's lightning inv
   }
 }
 ```
+
+Mostro updates the nip 33 event with `d` tag `ede61c96-4c13-4519-bf3a-dcf7f1e9d842` to change the status to `SettledHoldInvoice`:
+
+```json
+[
+  "EVENT",
+  "RAND",
+  {
+    "id": "eb0582360ebd3836c90711f774fbecb27e600f4a5fedf4fc2d16fc852f8380b1",
+    "pubkey": "dbe0b1be7aafd3cfba92d7463edbd4e33b2969f61bd554d37ac56f032e13355a",
+    "created_at": 1702549437,
+    "kind": 38383,
+    "tags": [
+      ["d", "ede61c96-4c13-4519-bf3a-dcf7f1e9d842"],
+      ["k", "Sell"],
+      ["f", "VES"],
+      ["s", "SettledHoldInvoice"],
+      ["amt", "7851"],
+      ["fa", "100"],
+      ["pm", "face to face"],
+      ["premium", "1"],
+      ["l", "MostroP2P"],
+      ["data_label", "order"]
+    ],
+    "content": "",
+    "sig": "a835f8620db3ebdd9fa142ae99c599a61da86321c60f7c9fed0cc57169950f4121757ff64a5e998baccf6b68272aa51819c3e688d8ad586c0177b3cd1ab09c0f"
+  }
+]
+```
+
+Seconds later Mostro will try to pay the buyer's invoice, if the payment is successful Mostro updates the nip 33 event with `d` tag `ede61c96-4c13-4519-bf3a-dcf7f1e9d842` to change the status to `Success`:
+
+```json
+[
+  "EVENT",
+  "RAND",
+  {
+    "id": "eb0582360ebd3836c90711f774fbecb27e600f4a5fedf4fc2d16fc852f8380b1",
+    "pubkey": "dbe0b1be7aafd3cfba92d7463edbd4e33b2969f61bd554d37ac56f032e13355a",
+    "created_at": 1702549437,
+    "kind": 38383,
+    "tags": [
+      ["d", "ede61c96-4c13-4519-bf3a-dcf7f1e9d842"],
+      ["k", "Sell"],
+      ["f", "VES"],
+      ["s", "Success"],
+      ["amt", "7851"],
+      ["fa", "100"],
+      ["pm", "face to face"],
+      ["premium", "1"],
+      ["l", "MostroP2P"],
+      ["data_label", "order"]
+    ],
+    "content": "",
+    "sig": "a835f8620db3ebdd9fa142ae99c599a61da86321c60f7c9fed0cc57169950f4121757ff64a5e998baccf6b68272aa51819c3e688d8ad586c0177b3cd1ab09c0f"
+  }
+]
+```
diff --git a/book/src/seller_pay_hold_invoice.md b/book/src/seller_pay_hold_invoice.md
@@ -1,6 +1,6 @@
 # Seller pays 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:
+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 content of the message will look like this:
 
 ```json
 {
@@ -79,6 +79,35 @@ Mostro also send a message to the buyer, this way they can both write to each ot
 }
 ```
 
+Mostro updates the nip 33 event with `d` tag `ede61c96-4c13-4519-bf3a-dcf7f1e9d842` to change the status to `Active`:
+
+```json
+[
+  "EVENT",
+  "RAND",
+  {
+    "id": "eb0582360ebd3836c90711f774fbecb27e600f4a5fedf4fc2d16fc852f8380b1",
+    "pubkey": "dbe0b1be7aafd3cfba92d7463edbd4e33b2969f61bd554d37ac56f032e13355a",
+    "created_at": 1702549437,
+    "kind": 38383,
+    "tags": [
+      ["d", "ede61c96-4c13-4519-bf3a-dcf7f1e9d842"],
+      ["k", "Sell"],
+      ["f", "VES"],
+      ["s", "Active"],
+      ["amt", "7851"],
+      ["fa", "100"],
+      ["pm", "face to face"],
+      ["premium", "1"],
+      ["l", "MostroP2P"],
+      ["data_label", "order"]
+    ],
+    "content": "",
+    "sig": "a835f8620db3ebdd9fa142ae99c599a61da86321c60f7c9fed0cc57169950f4121757ff64a5e998baccf6b68272aa51819c3e688d8ad586c0177b3cd1ab09c0f"
+  }
+]
+```
+
 ## 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 each party real pubkeys.
-Original file line number
+Diff line change
@@ Expand Up / @@ -43,3 +43,5 @@ And here is the message to the buyer: @@
       }
     }
     ```
+    Mostro will not update the nip 33 event with `d` tag `ede61c96-4c13-4519-bf3a-dcf7f1e9d842` to change the status to `Dispute`, this is because the order is still active, the dispute is just a way to let the admins and the other party know that there is a problem with the order.