diff --git a/book/src/new_sell_order.md b/book/src/new_sell_order.md index 0fe58a4..542571f 100644 --- a/book/src/new_sell_order.md +++ b/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, diff --git a/book/src/new_sell_range_order.md b/book/src/new_sell_range_order.md new file mode 100644 index 0000000..31dac8e --- /dev/null +++ b/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" + } +] +``` diff --git a/book/src/take_buy_range_order.md b/book/src/take_buy_range_order.md new file mode 100644 index 0000000..b0e4b4b --- /dev/null +++ b/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. diff --git a/book/src/take_sell_range_order.md b/book/src/take_sell_range_order.md new file mode 100644 index 0000000..68da0f1 --- /dev/null +++ b/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, "mostro_p2p@ln.tips", 15] + } + } +} +```