diff --git a/docs/new_order.md b/docs/new_order.md index cdcefad..9c33ee0 100644 --- 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 new file mode 100644 index 0000000..81d6b0b --- /dev/null +++ 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 index 09ac8a6..72d9c55 100644 --- 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,13 +16,13 @@ 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 } @@ -30,17 +30,17 @@ To take a new sell order the user should send a Nostr event kind 4 to Mostro wit ## 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 index a417fef..dca262a 100644 --- 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)