From 6013356988f73e95145f521148e9f8917bace4ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Francisco=20Calder=C3=B3n?= Date: Mon, 6 Jan 2025 19:08:21 -0300 Subject: [PATCH] Add trade-pubkey action case Include trade-index in some messages Small fixes --- .gitignore | 1 + src/SUMMARY.md | 3 +- src/new_buy_order.md | 1 + src/new_buy_order_ln_address.md | 1 + src/new_sell_order.md | 1 + src/new_sell_range_order.md | 1 + src/order-event.md | 83 +-------------------------------- src/order_event.md | 82 ++++++++++++++++++++++++++++++++ src/overview.md | 6 +-- src/release.md | 6 ++- src/release_range_order.md | 49 +++++++++++++++++++ src/take_buy.md | 1 + src/take_buy_range_order.md | 1 + src/take_sell.md | 1 + src/take_sell_ln_address.md | 1 + src/take_sell_range_order.md | 1 + 16 files changed, 151 insertions(+), 88 deletions(-) create mode 100644 .gitignore create mode 100644 src/order_event.md create mode 100644 src/release_range_order.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..4e42a1b --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +book/ \ No newline at end of file diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 0eaeaee..9c90bc5 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -16,6 +16,7 @@ - [Seller pays hold invoice](./seller_pay_hold_invoice.md) - [Fiat sent](./fiatsent.md) - [Release](./release.md) +- [Release a range order](./release_range_order.md) - [Rate user](./user_rating.md) - [Cancel](./cancel.md) - [Dispute](./dispute.md) @@ -25,5 +26,5 @@ - [Admin Add Solver](./admin_add_solver.md) - [Actions](./actions.md) - [Message suggestions for actions](./message_suggestions_for_actions.md) -- [P2P Order event. NIP-69](./order-event.md) +- [P2P Order event. NIP-69](./order_event.md) - [Other events published by Mostro](./other_events.md) diff --git a/src/new_buy_order.md b/src/new_buy_order.md index 217c0bd..0aa62c3 100644 --- a/src/new_buy_order.md +++ b/src/new_buy_order.md @@ -7,6 +7,7 @@ To create a new buy order the user should send a Gift wrap Nostr event to Mostro "order": { "version": 1, "action": "new-order", + "trade_index": 1, "payload": { "order": { "kind": "buy", diff --git a/src/new_buy_order_ln_address.md b/src/new_buy_order_ln_address.md index 8520889..8c6026c 100644 --- a/src/new_buy_order_ln_address.md +++ b/src/new_buy_order_ln_address.md @@ -7,6 +7,7 @@ Creating buy order with a [lightning address](https://github.com/andrerfneves/li "order": { "version": 1, "action": "new-order", + "trade_index": 1, "payload": { "order": { "kind": "buy", diff --git a/src/new_sell_order.md b/src/new_sell_order.md index d42bb51..e3e9a5d 100644 --- a/src/new_sell_order.md +++ b/src/new_sell_order.md @@ -7,6 +7,7 @@ To create a new sell order the user should send a Gift wrap Nostr event to Mostr "order": { "version": 1, "action": "new-order", + "trade_index": 1, "payload": { "order": { "kind": "sell", diff --git a/src/new_sell_range_order.md b/src/new_sell_range_order.md index 221e698..f25e985 100644 --- a/src/new_sell_range_order.md +++ b/src/new_sell_range_order.md @@ -7,6 +7,7 @@ To create a new range order the user should send a Gift wrap Nostr event to Most "order": { "version": 1, "action": "new-order", + "trade_index": 1, "payload": { "order": { "kind": "sell", diff --git a/src/order-event.md b/src/order-event.md index a2e7172..2c0943c 100644 --- a/src/order-event.md +++ b/src/order-event.md @@ -1,82 +1 @@ -# Peer-to-peer Order events. NIP-69 - -## Abstract - -Peer-to-peer (P2P) platforms have seen an upturn in recent years, while having more and more options is positive, in the specific case of p2p, having several options contributes to the liquidity split, meaning sometimes there's not enough assets available for trading. If we combine all these individual solutions into one big pool of orders, it will make them much more competitive compared to centralized systems, where a single authority controls the liquidity. - -This NIP defines a simple standard for peer-to-peer order events, which enables the creation of a big liquidity pool for all p2p platforms participating. - -## The event - -Events are [addressable events](https://github.com/nostr-protocol/nips/blob/master/01.md#kinds) and use `38383` as event kind, a p2p event look like this: - -```json -{ - "id": "", - "pubkey": "", - "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", "bank transfer"], - ["premium", "1"], - [ - "rating", - "{\"total_reviews\":1,\"total_rating\":3.0,\"last_rating\":3,\"max_rate\":5,\"min_rate\":1}" - ], - ["source", "https://t.me/p2plightning/xxxxxxx"], - ["network", "mainnet"], - ["layer", "lightning"], - ["name", "Nakamoto"], - ["g", ""], - ["bond", "0"], - ["expiration", "1719391096"], - ["y", "lnp2pbot"], - ["z", "order"] - ], - "content": "", - "sig": "" -} -``` - -## Tags - -- `d` < Order ID >: A unique identifier for the order. -- `k` < Order type >: `sell` or `buy`. This specifies the type of transaction in terms of bitcoin. "sell" means selling bitcoin, while "buy" indicates buying bitcoin. -- `f` < Currency >: The fiat asset being traded, using the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) standard. -- `s` < Status >: `pending`, `canceled`, `in-progress`, `success`. -- `amt` < Amount >: The amount of Bitcoin to be traded, the amount is defined in satoshis, if `0` means that the amount of satoshis will be obtained from a public API after the taker accepts the order. -- `fa` < Fiat amount >: The fiat amount being traded, for range orders two values are expected, the minimum and maximum amount. -- `pm` < Payment method >: The payment method used for the trade, if the order has multiple payment methods, they should be separated by a comma. -- `premium` < Premium >: The percentage of the premium the maker is willing to pay. -- `source` [Source]: The source of the order, it can be a URL that redirects to the order. -- `rating` [Rating]: The rating of the maker, this document does not define how the rating is calculated, it's up to the platform to define it. -- `network` < Network >: The network used for the trade, it can be `mainnet`, `testnet`, `signet`, etc. -- `layer` < Layer >: The layer used for the trade, it can be `onchain`, `lightning`, `liquid`, etc. -- `name` [Name]: The name of the maker. -- `g` [Geohash]: The geohash of the operation, it can be useful in a face to face trade. -- `bond` [Bond]: The bond amount, the bond is a security deposit that both parties must pay. -- `expiration` < Expiration\>: The expiration date of the order ([NIP-40](https://github.com/nostr-protocol/nips/blob/master/40.md)). -- `y` < Platform >: The platform that created the order. -- `z` < Document >: `order`. - -Mandatory tags are enclosed with ``, optional tags are enclosed with `[tag]`. - -## Implementations - -Currently implemented on the following platforms: - -- [Mostro](https://github.com/MostroP2P/mostro) -- [@lnp2pBot](https://github.com/lnp2pBot/bot) -- [Robosats](https://github.com/RoboSats/robosats/pull/1362) - -## This document is inspired on - -- [Mostro protocol specification](https://mostro.network/protocol/) -- [Messages specification for peer 2 peer NIP proposal](https://github.com/nostr-protocol/nips/blob/8250274a22f4882f621510df0054fd6167c10c9e/31001.md) -- [n3xB](https://github.com/nobu-maeda/n3xb) +# P2P Order event. NIP-69 diff --git a/src/order_event.md b/src/order_event.md new file mode 100644 index 0000000..a2e7172 --- /dev/null +++ b/src/order_event.md @@ -0,0 +1,82 @@ +# Peer-to-peer Order events. NIP-69 + +## Abstract + +Peer-to-peer (P2P) platforms have seen an upturn in recent years, while having more and more options is positive, in the specific case of p2p, having several options contributes to the liquidity split, meaning sometimes there's not enough assets available for trading. If we combine all these individual solutions into one big pool of orders, it will make them much more competitive compared to centralized systems, where a single authority controls the liquidity. + +This NIP defines a simple standard for peer-to-peer order events, which enables the creation of a big liquidity pool for all p2p platforms participating. + +## The event + +Events are [addressable events](https://github.com/nostr-protocol/nips/blob/master/01.md#kinds) and use `38383` as event kind, a p2p event look like this: + +```json +{ + "id": "", + "pubkey": "", + "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", "bank transfer"], + ["premium", "1"], + [ + "rating", + "{\"total_reviews\":1,\"total_rating\":3.0,\"last_rating\":3,\"max_rate\":5,\"min_rate\":1}" + ], + ["source", "https://t.me/p2plightning/xxxxxxx"], + ["network", "mainnet"], + ["layer", "lightning"], + ["name", "Nakamoto"], + ["g", ""], + ["bond", "0"], + ["expiration", "1719391096"], + ["y", "lnp2pbot"], + ["z", "order"] + ], + "content": "", + "sig": "" +} +``` + +## Tags + +- `d` < Order ID >: A unique identifier for the order. +- `k` < Order type >: `sell` or `buy`. This specifies the type of transaction in terms of bitcoin. "sell" means selling bitcoin, while "buy" indicates buying bitcoin. +- `f` < Currency >: The fiat asset being traded, using the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) standard. +- `s` < Status >: `pending`, `canceled`, `in-progress`, `success`. +- `amt` < Amount >: The amount of Bitcoin to be traded, the amount is defined in satoshis, if `0` means that the amount of satoshis will be obtained from a public API after the taker accepts the order. +- `fa` < Fiat amount >: The fiat amount being traded, for range orders two values are expected, the minimum and maximum amount. +- `pm` < Payment method >: The payment method used for the trade, if the order has multiple payment methods, they should be separated by a comma. +- `premium` < Premium >: The percentage of the premium the maker is willing to pay. +- `source` [Source]: The source of the order, it can be a URL that redirects to the order. +- `rating` [Rating]: The rating of the maker, this document does not define how the rating is calculated, it's up to the platform to define it. +- `network` < Network >: The network used for the trade, it can be `mainnet`, `testnet`, `signet`, etc. +- `layer` < Layer >: The layer used for the trade, it can be `onchain`, `lightning`, `liquid`, etc. +- `name` [Name]: The name of the maker. +- `g` [Geohash]: The geohash of the operation, it can be useful in a face to face trade. +- `bond` [Bond]: The bond amount, the bond is a security deposit that both parties must pay. +- `expiration` < Expiration\>: The expiration date of the order ([NIP-40](https://github.com/nostr-protocol/nips/blob/master/40.md)). +- `y` < Platform >: The platform that created the order. +- `z` < Document >: `order`. + +Mandatory tags are enclosed with ``, optional tags are enclosed with `[tag]`. + +## Implementations + +Currently implemented on the following platforms: + +- [Mostro](https://github.com/MostroP2P/mostro) +- [@lnp2pBot](https://github.com/lnp2pBot/bot) +- [Robosats](https://github.com/RoboSats/robosats/pull/1362) + +## This document is inspired on + +- [Mostro protocol specification](https://mostro.network/protocol/) +- [Messages specification for peer 2 peer NIP proposal](https://github.com/nostr-protocol/nips/blob/8250274a22f4882f621510df0054fd6167c10c9e/31001.md) +- [n3xB](https://github.com/nobu-maeda/n3xb) diff --git a/src/overview.md b/src/overview.md index 3a4bb75..86b08bb 100644 --- a/src/overview.md +++ b/src/overview.md @@ -14,16 +14,16 @@ All messages from/to Mostro should be [Gift wrap Nostr events](https://github.co - [action](https://docs.rs/mostro-core/latest/mostro_core/message/enum.Action.html): Action to be performed by Mostro daemon - [payload](https://docs.rs/mostro-core/latest/mostro_core/message/enum.Content.html) (optional): Payload of the message, this field is optional and depends on the action -These fields are relative to the wrapper, here an example of a `fiat-sent` Order message, in this case `id` is the Order Id: +These fields are relative to the wrapper, here an example of a `take-buy` order message: ```json { "order": { "version": 1, "id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842", - "request_id": "12345", + "request_id": "123456", "trade_index": 1, - "action": "fiat-sent", + "action": "take-buy", "payload": null } } diff --git a/src/release.md b/src/release.md index a0c44a1..0dc91f9 100644 --- a/src/release.md +++ b/src/release.md @@ -1,12 +1,13 @@ -# release +# Release -After confirming the buyer sent the fiat money, the seller should send a message to Mostro indicating that sats should be delivered to the buyer, the rumor's content of the message will look like this: +After confirming the buyer sent the fiat money, the seller should send a message to Mostro indicating that sats should be delivered to the buyer, the message inside rumor's content will look like this: ```json { "order": { "version": 1, "id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842", + "request_id": "123456", "action": "release", "payload": null } @@ -22,6 +23,7 @@ Here an example of the Mostro response to the seller: "order": { "version": 1, "id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842", + "request_id": "123456", "action": "hold-invoice-payment-settled", "payload": null } diff --git a/src/release_range_order.md b/src/release_range_order.md new file mode 100644 index 0000000..b38c234 --- /dev/null +++ b/src/release_range_order.md @@ -0,0 +1,49 @@ +# Release a range order + +In most of the cases after release a range order a child order needs to be created, the client is rotating keys favoring privacy so Mostro can't know which would be the next `trade pubkey` of the maker, also the client needs to know the new id and amounts of the child order, for this case Mostro send a message with the new order, the message is the same we saw on [new range sell](./new_sell_range_order.md), it looks like this: + +```json +{ + "order": { + "version": 1, + "id": "4fd93fc9-e909-4fc9-acef-9976122b5dfa", + "action": "new-order", + "request_id": "123456", + "payload": { + "order": { + "id": "4fd93fc9-e909-4fc9-acef-9976122b5dfa", + "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 + } + } + } +} +``` + +The client will be waiting for a message with the same request_id that was sent on the release message, then the client will know this new order is related to the previous one. + +## TradePubkey action + +Now that the client have updated the child order, it's time to let know to Mostro for the next `trade_pubkey`and `trade_index` of that child order, the message looks like this: + +```json +{ + "order": { + "version": 1, + "id": "4fd93fc9-e909-4fc9-acef-9976122b5dfa", + "trade_index": 2, + "action": "trade-pubkey", + "payload": null + } +} +``` + +As we explained in [keys management section](./key_management.md), the client will wrap the `trade_pubkey` in the `pubkey` field inside the rumor. diff --git a/src/take_buy.md b/src/take_buy.md index d6a7a86..e49816d 100644 --- a/src/take_buy.md +++ b/src/take_buy.md @@ -8,6 +8,7 @@ To take an order the seller will send to Mostro a message with the following rum "version": 1, "id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842", "action": "take-buy", + "trade_index": 1, "payload": null } } diff --git a/src/take_buy_range_order.md b/src/take_buy_range_order.md index b389f7f..b224898 100644 --- a/src/take_buy_range_order.md +++ b/src/take_buy_range_order.md @@ -8,6 +8,7 @@ If the order fiat amount is a range like `10-20` the seller must indicate a fiat "version": 1, "id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842", "action": "take-buy", + "trade_index": 1, "payload": { "amount": 15 } diff --git a/src/take_sell.md b/src/take_sell.md index 047dbba..5e2873a 100644 --- a/src/take_sell.md +++ b/src/take_sell.md @@ -8,6 +8,7 @@ If the order amount is `0` the buyer don't know the exact amount to create the i "version": 1, "id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842", "action": "take-sell", + "trade_index": 1, "payload": null } } diff --git a/src/take_sell_ln_address.md b/src/take_sell_ln_address.md index 8defdaf..6e25951 100644 --- a/src/take_sell_ln_address.md +++ b/src/take_sell_ln_address.md @@ -8,6 +8,7 @@ The buyer can use a [lightning address](https://github.com/andrerfneves/lightnin "version": 1, "id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842", "action": "take-sell", + "trade_index": 1, "payload": { "payment_request": [null, "mostro_p2p@ln.tips"] } diff --git a/src/take_sell_range_order.md b/src/take_sell_range_order.md index c88e951..d2a5412 100644 --- a/src/take_sell_range_order.md +++ b/src/take_sell_range_order.md @@ -8,6 +8,7 @@ If the order fiat amount is a range like `10-20` the buyer must indicate a fiat "version": 1, "id": "ede61c96-4c13-4519-bf3a-dcf7f1e9d842", "action": "take-sell", + "trade_index": 1, "payload": { "amount": 15 }