lnbits / Diagon-Alley

Diagon Alley: a decentralised market-stall protocol.

Diagon Alley: Decentralised Market-Stall Protocol

Diagon Alley is a decentralised market-stall protocol, that shifts emphasis from the frontend market to the merchants stall. If a frontend market (indexer) gets taken down, merchants just point their stalls elsewhere. Game-theoretically the winner of Diagon Alley is the most forthright, although suggestions on limiting bad behaviour are very welcome.

Indexers

An indexer is a simple frontend server and GUI that routes product, payment and shipping information between merchant and buyer. Each merchant has products in a stall. The stall chooses what products to list with the indexer. An indexer has one endpoint.

• /register/<stall_ID> POST The <stall_ID> is generated by the stall. the endpoint is for stalls to fetch rating data (0-100%), register products and check the indexer is online.

  Body (application/json)
  {"stall_url": <string>}

  Returns 200 OK (application/json)
  {"shopstatus": <boolean>, "rating": <int>}

The indexer uses the <stall_url> and <indexer_ID> for the stall endpoints.

The indexer may present information from the stalls it has registered in any way it want, either as a web shopping experience or an API or something else. It must show the stall_ID along with each product listing. When the customer clicks "buy" or equivalent it must fetch the invoice from the stall and present it to the customer.

Stalls

A stall has a keypair it uses to register itself to indexes and sign invoices. That keypair isn't related to any Lightning Network keypair, it's independent.

A stall can choose to list some/all products with an indexer. A stall is a small server that has three endpoints.

• /products/<indexer_ID> GET for fetching all products associated with an indexer ID

  Returns 200 OK (application/json)
  

  [
    {
      "product_id": <string>,
      "product_name": <string>,
      "categories": <list>,
      "description": <string>,
      "image": <string>,
      "price": <int>,
      "quantity": <int>
    },
    ...
  ]
  

• /order/<indexer_ID> POST for placing an order and sending shipping data. Returns a Lightning invoice, metadata and checking_id.

  metadata is a JSON array encoded as string containing at least two items:

  [
    [
      "text/plain",
      <string> // detailed description of the item that will be shipped and its destination>
    ],
    [
      "application/vnd.diagonalley.signature",
      <string> // DER-encoded ECDSA secp256k1 signature of the <string> tagged as "text/plain" the with the stall private key
    ]
  ]
  

  Invoices must contain the h tag (description_hash) set to sha256(metadata).

  This is such that customers can be sure they are paying an invoice originating from the stall and not from a malicious indexer. The information on metadata may be displayed in a nice way by the indexer interface, but its validity should be checked independently by the customer, perhaps at an independent website that allows him to copy-and-paste payment_request, metadata and stall_ID.

  Body (application/json)
  

  {
    "product_id": <string>,
    "address": <string>,
    "shippingzone": <integer>,
    "email": <string>,
    "quantity": <integer>
  }
  

  Returns 201 CREATED (application/json)
  {"metadata": <string>, "payment_request": <string>, "checking_id": <string>}

• /status/<checking_id> GET for checking an order status.

  Returns 200 OK (application/json)
  {"status": "SHIPPED" | "PAID" | "UNKNOWN"}