Add auctions to NIP-15. (#859)

* Add auctions to NIP-15.

* Update 15.md

Co-authored-by: Vlad Stan <stan.v.vlad@gmail.com>

* Address comments from @motorina0.

* Remove reference to removed type=10.

---------

Co-authored-by: Vlad Stan <stan.v.vlad@gmail.com>

1 files changed, 77 insertions, 1 deletions

diff --git a/15.md b/15.md
index 1c3154a..e2ba639 100644
--- a/15.md
+++ b/15.md
@@ -149,7 +149,6 @@ The `merchant` and the `customer` can exchange JSON messages that represent diff
 | 1            | Merchant | Payment Request     |
 | 2            | Merchant | Order Status Update |
 
-
 ### Step 1: `customer` order (event)
 The below json goes in content of [NIP04](https://github.com/nostr-protocol/nips/blob/master/04.md).
 
@@ -229,7 +228,9 @@ The below json goes in `content` of [NIP04](https://github.com/nostr-protocol/ni
   "shipped": <bool: has been shipped>,
 }
 ```
+
 ## Customize Marketplace
+
 Create a customized user experience using the `naddr` from [NIP-19](https://github.com/nostr-protocol/nips/blob/master/19.md#shareable-identifiers-with-extra-metadata). The use of `naddr` enables easy sharing of marketplace events while incorporating a rich set of metadata. This metadata can include relays, merchant profiles, and more. Subsequently, it allows merchants to be grouped into a market, empowering the market creator to configure the marketplace's user interface and user experience, and share that marketplace. This customization can encompass elements such as market name, description, logo, banner, themes, and even color schemes, offering a tailored and unique marketplace experience.
 
 ### Event `30019`: Create or update marketplace UI/UX
@@ -253,6 +254,81 @@ Create a customized user experience using the `naddr` from [NIP-19](https://gith
 
 This event leverages naddr to enable comprehensive customization and sharing of marketplace configurations, fostering a unique and engaging marketplace environment.
 
+## Auctions
+
+### Event `30020`: Create or update a product sold as an auction
+
+**Event Content**:
+```json
+{
+    "id": <String, UUID generated by the merchant. Sequential IDs (`0`, `1`, `2`...) are discouraged>,
+    "stall_id": <String, UUID of the stall to which this product belong to>,
+    "name": <String, product name>,
+    "description": <String (optional), product description>,
+    "images": <[String], array of image URLs, optional>,
+    "starting_bid": <int>,
+    "start_date": <int (optional) UNIX timestamp, date the auction started / will start>,
+    "duration": <int, number of seconds the auction will run for, excluding eventual time extensions that might happen>,
+    "specs": [
+        [<String, spec key>, <String, spec value>]
+    ],
+    "shipping": [
+        {
+            "id": <String, UUID of the shipping zone. Must match one of the zones defined for the stall>,
+            "cost": <float, extra cost for shipping. The currency is defined at the stall level>,
+        }
+    ]
+}
+```
+
+> [!NOTE]
+> Items sold as an auction are very similar in structure to fixed-price items, with some important differences worth noting.
+
+* The `start_date` can be set to a date in the future if the auction is scheduled to start on that date, or can be omitted if the start date is unknown/hidden. If the start date is not specified, the auction will have to be edited later to set an actual date.
+
+* The auction runs for an initial number of seconds after the `start_date`, specified by `duration`.
+
+### Event `1021`: Bid
+
+```json
+{
+    "content": <int, amount of sats>,
+    "tags": [["e", <event ID of the auction to bid on>]],
+}
+```
+
+Bids are simply events of kind `1021` with a `content` field specifying the amount, in the currency of the auction. Bids must reference an auction.
+
+> [!NOTE]
+> Auctions can be edited as many times as desired (they are "parameterized replaceable events") by the author - even after the start_date, but they cannot be edited after they have received the first bid! This is enforced by the fact that bids reference the event ID of the auction (rather than the product UUID), which changes with every new version of the auctioned product. So a bid is always attached to one "version". Editing the auction after a bid would result in the new product losing the bid!
+
+### Event `1022`: Bid confirmation
+
+**Event Content**:
+
+```json
+{
+    "status": <String, "accepted" | "rejected" | "pending" | "winner">,
+    "message": <String (optional)>,
+    "duration_extended": <int (optional), number of seconds>,
+}
+```
+
+**Event Tags**:
+```json
+  "tags": [["e" <event ID of the bid being confirmed>], ["e", <event ID of the auction>]],
+```
+
+Bids should be confirmed by the merchant before being considered as valid by other clients. So clients should subscribe to *bid confirmation* events (kind `1022`) for every auction that they follow, in addition to the actual bids and should check that the pubkey of the bid confirmation matches the pubkey of the merchant (in addition to checking the signature).
+
+The `content` field is a JSON which includes *at least* a `status`. `winner` is how the *winning bid* is replied to after the auction ends and the winning bid is picked by the merchant.
+
+The reasons for which a bid can be marked as `rejected` or `pending` are up to the merchant's implementation and configuration - they could be anything from basic validation errors (amount too low) to the bidder being blacklisted or to the bidder lacking sufficient *trust*, which could lead to the bid being marked as `pending` until sufficient verification is performed. The difference between the two is that `pending` bids *might* get approved after additional steps are taken by the bidder, whereas `rejected` bids can not be later approved.
+
+An additional `message` field can appear in the `content` JSON to give further context as of why a bid is `rejected` or `pending`.
+
+Another thing that can happen is - if bids happen very close to the end date of the auction - for the merchant to decide to extend the auction duration for a few more minutes. This is done by passing a `duration_extended` field as part of a bid confirmation, which would contain a number of seconds by which the initial duration is extended. So the actual end date of an auction is always `start_date + duration + (SUM(c.duration_extended) FOR c in all confirmations`.
+
 ## Customer support events
 
 Customer support is handled over whatever communication method was specified. If communicating via nostr, NIP-04 is used https://github.com/nostr-protocol/nips/blob/master/04.md.