Add OBIP describing CRYPTOCURRENCY protocol changes

obip-0009.md

@@ -0,0 +1,103 @@
+<pre>
+OBIP: 9
+Title: 3rd Party Search Providers
+Author: Mike Wolf <mike@ob1.io> and Mike Greenberg <mikeg@ob1.io>
+Discussions-To: Github Issues or #obips on Slack
+Status: Accepted
+Type: Standards Track
+Created: 10/03/2018
+Copyright: MIT
+</pre>
+
+# Abstract
+Improvement to listings to allow support for Cryptocurrency trading on OpenBazaar.
+
+# Motivation
+Given that cryptocurrencies have an external price which the market uses to value any given denomination, the protocol requires a way to identify these listings.
+
+This OBIP outlines a new listing type to identify which listings depended on these external prices, the additional metadata required to represent these prices accurately within the client, and 3rd party search APIs changes to express this new metadata.
+
+# CoinTypes
+
+Are manually updated based on coins available in the API provided by [CoinMarketCap](https://api.coinmarketcap.com/v2/listings/).
+
+# Protocol Changes
+
+- `Listings` protobufs have changes applied to their `Metadata` section:
+        - `contractType` includes a new enumeration `CRYPTOCURRENCY`
+        - `format` is expected to be `MARKET_PRICE` to make use of exchange rate lookup but is not a hard requirement by the protocol.
+        - `CRYPTOCURRENCY` listings are expected to include `priceModifier`, `coinType`, and `coinDivisibility` in their responses and would be omitted for other types
+        - `priceModifer` is a signed float representing the percentage-based multiplier to raise/lower the sale price in relation to the market price. The value range is `1000.0 <= modifier <= -99.99`.
+          - Example: `-5` would affect the sale price as `MARKETPRICE *  -0.05 = SALEPRICE`
+          - Example: `100` would apply `MARKETPRICE * 1.00 = SALEPRICE`
+          - Example: `-99.99` would apply `MARKETPRICE * -0.9999 = SALEPRICE`
+        - `coinType` is the representation of the coin's denomination as defined by CoinMarketCap
+        - `coinDivisibility` describes the magnitutde of the quantity represented in the listing. Currently fixed at 10,000,000 for every coin but should reflect the value provided in the listing when/if this magnitutde must change.
+
+
+# 3rd Party Search API
+
+## CRYPTOCURRENCY Listing Search Response
+
+If the listing represents a `CRYPTOCURRENCY` then the returned data requires additional fields.
+
+```
+{
+  "name": "OB1",
+  "logo": "https://ob1.io/logo.png",
+  "options": { ... },
+  "sortBy": { ... },
+  "links": { ... },
+  "results": {
+    "results": [
+      {
+       "type": "listing",
+       "relationships": { ... },
+        "data": {
+          "hash": "",
+          "slug": "air-direct-amplifier",
+          "title": "Air Direct Amplifier",
+          "tags": [
+            "culpa",
+            "nihil",
+            "sit",
+            "nesciunt",
+            "ad",
+            "accusamus",
+            "sit"
+          ],
+          "categories": [
+            "Digital Goods"
+          ],
+          "contractType": "CRYPTOCURRENCY",
+          "description": "unde illo tempore omnis corporis repellat non. et eum excepturi ipsam alias quae.\tquia voluptates sed et provident qui. inventore eligendi vel autem modi asperiores autem sed.",
+          "thumbnail": {
+            "tiny": "QmTHCaDpznJStWvPUSiKNDd53VVZmPtnrHx5diGP5gskCx",
+            "small": "QmfVecQaoy1pZD3wsHHC82kYg24yhVaqBsAzm5aJCabXPQ",
+            "medium": "QmS1z4qW1SiDNtLD1Bfno8WEbFUV8qwb5CQxgR6BREyVTJ",
+            "original": "QmRSJfL6rEuZ6fBaCfd1ZYXHTnPKj4ZZuEuMsNmbbFjLfH",
+            "large": "QmWoNr88v9dnsJAZBkuZJAXjPGn1MBLobp3S6F8NnuZ1m3"
+          },
+          "language": "",
+          "price": {
+            "currencyCode": "btc",
+            "amount": 34,
+            "modifier" 3,
+          },
+          "coinType": "ltc",
+          "coinDivisibility": 100000000,
+          "nsfw": true
+        }
+      }, ... (repeat for additional listings)
+    ]
+  }
+}
+```
+
+# Listing Search Response Explanation
+
+- Top level items (`name`, `logo`, `links`, `options`, `sortBy`...) remain unchanged
+- `results` (remain unchanged) contain the search results for the given query
+  - `results` (remain unchanged) is an array of "listing" results of the following format
+   - The `data` object (remains unchanged) represents the listing data itself
+      - Affected keys within `data` include `contractType`, `price.modifer`, `coinType`, and `coinDivisibility` which should be the same as provided by the listing