lnbits-legend/lnbits/extensions/market/README.md

## Nostr Diagon Alley protocol (for resilient marketplaces)

#### Original protocol https://github.com/lnbits/Diagon-Alley

> The concepts around resilience in Diagon Alley helped influence the creation of the NOSTR protocol, now we get to build Diagon Alley on NOSTR!

In Diagon Alley, `merchant` and `customer` communicate via NOSTR relays, so loss of money, product information, and reputation become far less likely if attacked.

A `merchant` and `customer` both have a NOSTR key-pair that are used to sign notes and subscribe to events. 

#### For further information about NOSTR, see https://github.com/nostr-protocol/nostr


## Terms

* `merchant` - seller of products with NOSTR key-pair
* `customer` - buyer of products with NOSTR key-pair
* `product` - item for sale by the `merchhant`
* `stall` - list of products controlled by `merchant`
* `marketplace` - clientside software for searching `stalls` an buying `products`

## Diagon Alley Clients

### Merchant admin

Where the `merchant` creates, updates and deletes `stalls` and `products`, as well as where they manage sales, payments and communication with `customers`. 

The `merchant` admin software can be purely clientside, but for `convenience` and uptime, implementations will likely have a server listening for NOSTR events.

### Marketplace

`Marketplace` software should be entirely clientside, either as a stand-alone 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 like any other ecommerce site, with basket and checkout. `Marketplaces` may also wish to include a `customer` support area for direct message communication with `merchants`.

## `Merchant` publishing/updating products (event)

NIP-01 https://github.com/nostr-protocol/nips/blob/master/01.md uses the basic NOSTR event type.

The `merchant` event that publishes and updates product lists

ALL fields are optional apart from the `timestamp`. Data from newer events should replace data from older events.  

`action` types (used to indicate changes):
* `update` element has chnaged
* `delete` element should be deleted
* `suspend` element is suspended
* `unsuspend` element is unsuspended


```
{
    "name": <String, name of merchant>,
    "description": <String, description of merchant>,
    "timestamp": <String, unix timestamp>,
    "action": <String, optional action>,
    "stalls": [
        {
            "id": <UUID dervied from merchant public-key>,
            "name": <String, stall name>,
            "description": <String, stall description>,
            "categories": <String, CSV of voluntary categories>,
            "currency": <Str, currency used>,
            "action": <String, optional action>,
            "products": [
                {
                    "id": <String, UUID derived from stall ID>,
                    "name": <String, name of product>,
                    "description": <String, product description>,
                    "categories": <String, CSV of voluntary categories>,
                    "amount": <Int, number of units>,
                    "price": <Int, cost per unit>,
                    "action": <String, optional action>,
                },
                {
                    "id": <String, UUID derived from stall ID>,
                    "name": <String, name of product>,
                    "description": <String, product description>,
                    "categories": <String, CSV of voluntary categories>,
                    "amount": <Int, number of units>,
                    "price": <Int, cost per unit>,
                    "action": <String, optional action>,
                },
            ]
        },
        {
            "id": <UUID dervied from merchant public_key>,
            "name": <String, stall name>,
            "description": <String, stall description>,
            "categories": <String, CSV of voluntary categories>,
            "currency": <Str, currency used>,
            "action": <String, optional action>,
            "products": [
                {
                    "id": <String, UUID derived from stall ID>,
                    "name": <String, name of product>,
                    "categories": <String, CSV of voluntary categories>,
                    "amount": <Int, number of units>,
                    "price": <Int, cost per unit>,
                    "action": <String, optional action>,
                }
            ]
        }
    ]
}

```

## Checkout events

NIP-04 https://github.com/nostr-protocol/nips/blob/master/04.md, all checkout events are encrypted

### Step 1: `customer` order (event)

ALL fields are optional apart from `timestamp`.

```
{
    "id": <String, UUID derived from sum of product ids + timestamp>,
    "name": <String, name of customer>,
    "description": <String, description of customer>,
    "address": <String, postal address>,
    "message": <String, special request>,
    "timestamp": <String, unix timestamp>,
    "contact": [
        "nostr": <String, NOSTR pubkey>,
        "phone": <String, phone number>,
        "email": <String, email address>
    ],
    "items": [
        {
            "id": <String, product ID>,
            "quantity": <String, stall name>,
            "message": <String, special request>
        },
        {
            "id": <String, product ID>,
            "quantity": <String, stall name>,
            "message": <String, special request>
        },
        {
            "id": <String, product ID>,
            "quantity": <String, stall name>,
            "message": <String, special request>
        }
    
}

```

Merchant should verify the sum of product ids + timestamp.

### Step 2: `merchant` request payment (event)

Sent back from the merchant for payment. Any payment option is valid that the merchant can check.

`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  

```
{
    "id": <String, UUID derived from sum of product ids + timestamp>,
    "message": <String, message to customer>,
    "timestamp": <String, unix timestamp>,
    "payment_options": [
        {
            "type": <String, option type>,
            "link": <String, url, btc adress, ln invoice, etc>
        },
        {
            "type": <String, option type>,
            "link": <String, url, btc adress, ln invoice, etc>
        },
                {
            "type": <String, option type>,
            "link": <String, url, btc adress, ln invoice, etc>
        }
}

```

### Step 3: `merchant` verify payment/shipped (event)

Once payment has been received and processed.
```
{
    "id": <String, UUID derived from sum of product ids + timestamp>,
    "message": <String, message to customer>,
    "paid": <Bool, true/false has received payment>,
    "shipped": <Bool, true/false has been shipped>,
}

```

## Customer support events

Customer support is handle over whatever communication method was specified. If communicationg via nostr, NIP-04 is used https://github.com/nostr-protocol/nips/blob/master/04.md.