nostr/nips
1
0
Fork 0
mirror of https://github.com/nostr-protocol/nips.git synced 2025-01-13 00:52:10 -05:00
Code Issues Actions Packages Projects Releases Wiki Activity
598682be74
nips/15.md
gzuuus 598682be74 clean up, rewrite, clarify specification
2024-05-09 17:36:51 +02:00

372 lines
18 KiB
Markdown
Raw Blame History

NIP-15
======
Nostr Marketplace
-----------------
`draft` `optional`
Based on https://github.com/lnbits/Diagon-Alley.
Implemented in [NostrMarket](https://github.com/lnbits/nostrmarket) and [Plebeian Market](https://github.com/PlebeianTech/plebeian-market).
## Terms
- `merchant` - Seller of products with NOSTR key-pair
- `customer` - Buyer of products with NOSTR key-pair
- `stall` - List of products controlled by `merchant` (a `merchant` can have multiple stalls)
- `product` - Item for sale by the `merchant`
- `auction` - Item for sale, as auction, by the `merchant`
- `bid` - Bids from users participating in a auction.
- `marketplace` - clientside software for searching `stalls` and purchasing `products`
- `checkout events` - A series of private messages exchanged between `merchant` and `customer`, representing the checkout process.
> [!NOTE]
> Nostr Marketplaces operates using Bitcoin as its currency, but `merchants` have the flexibility to set prices in their preferred currency for their `stalls`. This means they can convert from their chosen currency to set a fixed price. Alternatively, merchants can opt to use Bitcoin as their currency, ensuring a fixed price in BTC.
## Nostr Marketplace Clients
### Merchant admin
The `merchant` admin software is where the `merchant` creates, updates, and deletes `stalls` and `products`, as well as manages sales, payments, and communication with `customers`. While the `merchant` admin software can be purely client-side, implementations will likely have a server client listening for NOSTR events for convenience and uptime. The `merchant` admin software can be integrated into the marketplace client.
### Marketplace
`Marketplace` software should be entirely client-side, either as a standalone app or as a purely frontend webpage. A `customer` subscribes to different merchant NOSTR public keys, and those `merchants'` `stalls` and `products` become listed and searchable. The marketplace client is similar to any other e-commerce site, with a basket and checkout. `Marketplaces` may also wish to include a `customer` support area for direct message communication with `merchants`.
## `Merchant` publishing/updating products (event)
A merchant can publish these events:
| Kind | | Description |
| --------- | ------------------ | --------------------------------------------------------------------------------------------------------------- |
| `30017` | `set_stall` | Create or update a stall. |
| `30018` | `set_product` | Create or update a product. |
| `30020` | `set_auction` | Create or update a product selled as auction. |
Alongside other kinds of events that can be involved.
| Kind | | Description |
| --------- | ------------------ | --------------------------------------------------------------------------------------------------------------- |
| `4` | `direct_message` | Used for `checkout events` and communication between `merchant` - `customer`. |
| `5` | `delete` | Delete a product or a stall. |
### Event `30017`: Create or update a stall.
**Event Content**
```json
{
"name": <string, stall name>,
"description": <string (optional), stall description>,
"currency": <string, currency used>,
"shipping": [
{
"id": <string, id of the shipping zone, generated by the merchant>,
"name": <string (optional), zone name>,
"cost": <float, base cost for shipping. The currency is defined at the stall level>,
"regions": [<string, regions included in this zone>]
}
]
}
```
Observations:
- `currency` defines the currency in which the merchant wishes to operate. If it's `BTC`, no conversion is required; if it's different from `BTC`, the platform should perform the necessary conversion to `BTC` at the time of purchase, ensuring accurate price conversion for each buyer.
- Ideally `currency` and `regions` values for shipping costs will utilize ISO 3166 codes to ensure accurate and consistent calculations.
Fields that are not self-explanatory:
- `shipping`:
- an array with possible shipping zones for this stall.
- the customer MUST choose exactly one of those shipping zones.
- shipping to different zones can have different costs. For some goods (digital for example) the cost can be zero.
- the `id` is an internal value used by the merchant. This value must be sent back as the customer selection.
- each shipping zone contains the base cost for orders made to that shipping zone, but a specific shipping cost per
product can also be specified if the shipping cost for that product is higher than what's specified by the base cost.
**Event Tags**
```json
{
"tags": [["d", <string, id of the stall>]],
...
}
```
- the `d` tag is required and represents the stall id.
### Event `30018`: Create or update a product
**Event Content**
```json
{
"stall_id": <string, id of the stall to which this product belong to>,
"name": <string, product name>,
"type": <string, "simple" | "variable" | "variation">,
"description": <string (optional), product description>,
"images": <[string], array of image URLs, optional>,
"price": <float, cost of product>,
"quantity": <int or null, available items>,
"specs": [
[<string, spec key>, <string, spec value>]
],
"shipping": [
{
"id": <string, id 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>
}
]
}
```
Observations:
- The product inherits its currency from the stall it belongs to.
Fields that are not self-explanatory:
- `quantity`: can be null in the case of items with unlimited availability, like digital items, or services
- `specs`:
- an optional array of key pair values. It allows for the Customer UI to present product specifications in a structure mode. It also allows comparison between products
- eg: `[["operating_system", "Android 12.0"], ["screen_size", "6.4 inches"], ["connector_type", "USB Type C"]]`
- `shipping`:
- an _optional_ array of extra costs to be used per shipping zone, only for products that require special shipping costs to be added to the base shipping cost defined in the stall
- the `id` should match the id of the shipping zone, as defined in the `shipping` field of the stall
- to calculate the total cost of shipping for an order, the user will choose a shipping option during checkout, and then the client must consider this costs:
- the `base cost from the stall` for the chosen shipping option
- the result of multiplying the product units by the `shipping costs specified in the product`, if any.
- `type`:This determination categorizes a product as either a `simple` product, a `variable` product, or a `variation` of a variable product. For example, a shirt sold in a single color is a `simple` product, while a shirt offered in multiple colors is a `variable` product with `variations`. To establish a link between a variable product and its variations, the variation product event should include an `a` tag that references the event coordinate of the corresponding variable product.
**Event Tags**
```json
"tags": [
["d", <string, id of product>],
["a", <event coordinate (decoded naddr) of the variable product (optional, only for variations)>, <recommended relay URL, optional>, <string, "variation">],
["t", <string (optional), product category],
["t", <string (optional), product category],
...
],
...
```
- The `d` tag is required.
- The `t` tag is as searchable tag, it represents different categories that the product can be part of (`food`, `fruits`). Multiple `t` tags can be present.
- The `a` tag is employed in products that are variations of a variable product, serving as a linking mechanism. It follows the conventions outlined in [nip01](https://github.com/nostr-protocol/nips/blob/master/01.md#tags)
## Checkout events
All checkout events are sent as JSON strings using ([NIP-04](https://github.com/nostr-protocol/nips/blob/master/04.md)).
The `merchant` and the `customer` can exchange JSON messages that represent different actions. Each `JSON` message `MUST` have a `type` field indicating the what the JSON represents. Possible types:
| Message Type | Sent By | Description |
|--------------|----------|---------------------|
| 0 | Customer | New Order |
| 1 | Merchant | Payment Request |
| 2 | Merchant | Order Status Update |
### Step 1: `customer` order (event)
The below JSON goes in content of [NIP-04](https://github.com/nostr-protocol/nips/blob/master/04.md).
```json
{
"id": <string, id generated by the customer>,
"type": 0,
"name": <string (optional), ???>,
"address": <string (optional), for physical goods an address should be provided>,
"message": <string (optional), message for merchant>,
"contact": {
"nostr": <32-bytes hex of a pubkey>,
"phone": <string (optional), if the customer wants to be contacted by phone>,
"email": <string (optional), if the customer wants to be contacted by email>
},
"items": [
{
"product_id": <string, id of the product>,
"quantity": <int, how many products the customer is ordering>
}
],
"shipping_id": <string, id of the shipping zone>
}
```
### Step 2: `merchant` request payment (event)
Sent back from the merchant for payment. Any payment option is valid that the merchant can check.
The below JSON goes in `content` of [NIP-04](https://github.com/nostr-protocol/nips/blob/master/04.md).
`payment_options`/`type` include:
- `url` URL to a payment page, stripe, paypal, btcpayserver, etc
- `btc` onchain bitcoin address
- `ln` bitcoin lightning invoice
- `lnurl` bitcoin lnurl-pay
```json
{
"id": <string, id of the order>,
"type": 1,
"message": <string, message to customer, optional>,
"payment_options": [
{
"type": <string, option type>,
"link": <string, url, btc address, ln invoice, etc>
},
{
"type": <string, option type>,
"link": <string, url, btc address, ln invoice, etc>
},
{
"type": <string, option type>,
"link": <string, url, btc address, ln invoice, etc>
}
]
}
```
### Step 3: `merchant` verify payment/shipped (event)
Once payment has been received and processed.
The below JSON goes in `content` of [NIP-04](https://github.com/nostr-protocol/nips/blob/master/04.md).
```json
{
"id": <string, id of the order>,
"type": 2,
"status":<string, "pending" | "processing" | "completed" | "cancelled" | "refunded" | "failed">;,
"message": <string, message to customer>,
"paid": <bool: has received payment>,
"shipped": <bool: has been shipped>,
}
```
Possible order statuses meaning:
- `Pending` - The order has been created there is something that maintains it on hold, i.e: payment has not been received yet, or the stock of the product has been reduced but the merchant needs to approve the payment.
- `Processing` - The payment has been received and the order is awaiting fulfillment (i.e. shipping products)
- `Completed` - The payment is successful and the order has been fulfilled.
- `Cancelled` - The order has been manually cancelled by the admin or the customer.
- `Refunded` - The order has been refunded by the admin.
- `Failed` - The order has failed due to technical issues or the payment being declined.
## 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
**Event Content**
```json
{
"name": <string (optional), market name>,
"about": <string (optional), market description>,
"ui": {
"picture": <string (optional), market logo image URL>,
"banner": <string (optional), market logo banner URL>,
"theme": <string (optional), market theme>,
"darkMode": <bool, true/false>
},
"merchants": [array of pubkeys (optional)],
...
}
```
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
{
"stall_id": <String, UUID of the stall to which this product belong to>,
"name": <String, product name>,
"description": <String (optional), product description>,
"type": <string, "simple" | "variable" | "variation">,
"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`.
```json
"tags": [
["d", <string, id of product auction>],
["a", <event coordinate (decoded naddr) of the variable product (optional, only for variations)>, <recommended relay URL, optional>, <string,"variation">],
["t", <string (optional), product category],
["t", <string (optional), product category],
...
],
...
```
- The `d` tag is required.
### Event `1021`: Bid
```json
{
"content": <stringified auction event>,
"tags": [
["a", <event coordinate of the auction to bid on>],
["amount": <int, in the currency of the auction>]
]
}
```
Bids are simply events of kind `1021` with a `content` field containing the strigified version of the auction event, and tags consisting of a tag:`a` pointing to the auction event coordinates and a tag:`amount` containing the bid amount expressed as an integer in the auction currency. Bids must refer to an auction.
### Event `1022`: Bid confirmation
**Event Content**:
```json
{
"status": <String, "accepted" | "rejected" | "pending" | "winner">,
"message": <String (optional)>,
}
```
**Event Tags**:
```json
{
"tags": [
["e" <event ID of the bid being confirmed>],
["a", <event coordinate of the auction>]
],
}
```
To ensure the validity of bids, merchants must confirm them before they can be considered valid by other clients. Therefore, clients should subscribe to 'bid confirmation' events (kind `1022`) for every auction they follow, in addition to the actual bids. When checking the bid confirmation, clients must verify 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 object that includes, at a minimum, a `status` field. The `winner` field is used to respond to the winning bid after the auction ends and the merchant has selected the winner.
The reasons for marking a bid as `rejected` or `pending` are determined by the merchant's implementation and configuration. These reasons can range from basic validation errors (e.g., amount too low) to the bidder being blacklisted or lacking sufficient trust, which may lead to the bid being marked as `pending` until additional verification is performed. The key difference between `rejected` and `pending` bids is that `pending` bids may be approved after the bidder takes additional steps, whereas `rejected` bids cannot be later approved. Note that pending bids can be re-evaluated after an update to the auction event, at which point the merchant may publish an update to the starting bid field and mark bids with lower values as pending.
An optional `message` field can appear in the `content` JSON to provide further context for why a bid is `rejected` or `pending`.
If bids are placed very close to the auction's end date, the merchant can extend the auction duration by updating the `duration` field in the auction event.
## 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.
## Additional
Standard data models can be found <a href="https://raw.githubusercontent.com/lnbits/nostrmarket/main/models.py">here</a>
Reference in New Issue View Git Blame Copy Permalink