From 559db1b7f94fa7e1b24aaa35e9d1050d901f1664 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Francisco=20Calder=C3=B3n?= Date: Wed, 1 Nov 2023 18:07:27 -0300 Subject: [PATCH] Add more docs (#138) --- docs/new_order.md | 74 ++++++++++++++++++++++++++++++++++++++++ docs/take_sell.md | 83 +++++++++++++++++++++++++++++++++++++++++++++ docs/user_rating.md | 16 ++++++++- 3 files changed, 172 insertions(+), 1 deletion(-) create mode 100644 docs/new_order.md create mode 100644 docs/take_sell.md diff --git a/docs/new_order.md b/docs/new_order.md new file mode 100644 index 0000000..cdcefad --- /dev/null +++ b/docs/new_order.md @@ -0,0 +1,74 @@ +# Creating a new order + +## 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, the content of the event should be a 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) + +## New order + +To create a new sell order the user should send a Nostr event kind 4 to Mostro with the following content: + +```json +{ + "version": "0", + "pubkey": "npub1qqq...", + "action": "Order", + "content": { + "Order": { + "kind": "Sell", + "status": "Pending", + "amount": 0, + "fiat_code": "VES", + "fiat_amount": 100, + "payment_method": "face to face", + "premium": 1, + "master_seller_pubkey": "npub1qqq...", + "created_at": 0 + } + } +} +``` + +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 +- created_at: No need to send the correct unix timestamp, Mostro will replace it with the current time + +## Confirmation message + +Mostro will send back a confirmation message to the user like the following: + +```json +{ + "version": "0", + "order_id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842", + "pubkey": null, + "action": "Order", + "content": { + "Order": { + "id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842", + "kind": "Sell", + "status": "Pending", + "amount": 0, + "fiat_code": "VES", + "fiat_amount": 100, + "payment_method": "face to face", + "premium": 1, + "created_at": 1698870173 + } + } +} +``` diff --git a/docs/take_sell.md b/docs/take_sell.md new file mode 100644 index 0000000..09ac8a6 --- /dev/null +++ b/docs/take_sell.md @@ -0,0 +1,83 @@ +# Take a sell order + +## 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, the content of the event should be a 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) + +## 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: + +```json +{ + "version": "0", + "pubkey": "npub1qqq...", + "order_id": "68e373ef-898b-4312-9f49-dfc50404e3b2", + "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: + +```json +{ + "version": "0", + "order_id": "68e373ef-898b-4312-9f49-dfc50404e3b2", + "pubkey": null, + "action": "AddInvoice", + "content": { + "SmallOrder": { + "id": "68e373ef-898b-4312-9f49-dfc50404e3b2", + "amount": 7851, + "fiat_code": "VES", + "fiat_amount": 100, + "payment_method": "face to face", + "premium": 1, + "buyer_pubkey": null, + "seller_pubkey": null + } + } +} +``` + +## Buyer sends LN invoice + +```json +{ + "version": "0", + "order_id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842", + "pubkey": null, + "action": "TakeSell", + "content": { + "PaymentRequest": [ + null, + "lnbcrt32680n1pj59wmepp50677g8tffdqa2p8882y0x6newny5vtz0hjuyngdwv226nanv4uzsdqqcqzzsxqyz5vqsp5skn973360gp4yhlpmefwvul5hs58lkkl3u3ujvt57elmp4zugp4q9qyyssqw4nzlr72w28k4waycf27qvgzc9sp79sqlw83j56txltz4va44j7jda23ydcujj9y5k6k0rn5ms84w8wmcmcyk5g3mhpqepf7envhdccp72nz6e" + ] + } +} +``` + +## Mostro response + +```json +{ + "version": "0", + "order_id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842", + "pubkey": null, + "action": "WaitingSellerToPay", + "content": null +} +``` diff --git a/docs/user_rating.md b/docs/user_rating.md index 48503c8..a417fef 100644 --- a/docs/user_rating.md +++ b/docs/user_rating.md @@ -2,7 +2,7 @@ ## 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) +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 @@ -39,3 +39,17 @@ After a Mostro client receive this message, the user can rate the other party, t } } ``` + +## Confirmation message + +If Mostro received the message correct it will send back a last confirmation message to the user with `Action: Received`: + +```json +{ + "version": "0", + "order_id": "7e44aa5d-855a-4b17-865e-8ca3834a91a3", + "pubkey": null, + "action": "Received", + "content": null +} +```