mirror of
https://github.com/lnbits/lnbits-legend.git
synced 2025-02-25 23:21:21 +01:00
198 lines
No EOL
7.1 KiB
Markdown
198 lines
No EOL
7.1 KiB
Markdown
## 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. |