oracle proposal

Oracle.md

@@ -0,0 +1,136 @@
+# Oracle specifications
+
+## Introduction
+
+For the purpose of these specifications, an event is a digital representation of a real world fact.
+An [oracle](./Introduction#Oracle) is an entity that commits to publishing a signature over a (number of) event outcome(s) ahead of time by releasing an [R-value](./Introduction#R-value) as well as necessary information for two parties to build a set of [CETs](./Introduction#Contract-Execution-Transaction-(CET)).
+This necessary information is committed in a so-called _event descriptor_ that will be further detailed in this document.
+Descriptors are classified and discovered through a namespace presently represented as Unique Resource Identifier (URI) paths.
+
+## Event descriptor
+
+An event descriptor provides information to clients about an event for which an oracle plans on releasing a signature over its outcome.
+The provided information should be sufficient for a client to create a set of CETs that will cover all possible outcomes of the event.
+
+Regardless of the outcome type, an event descriptor should include:
+
+- The R value that will be used to sign the event outcome (possibly several).
+- The public key of the oracle.
+- The earliest date at which the event outcome will be released in Unix epoch format.
+
+Here we assume that an event outcome can be represented either as a set of strings or numbers.
+Three kinds of event outcomes are defined (note that a single even can be composed of several types).
+
+### Simple enumeration
+
+For events that have a narrow range of possible outcomes, the outcomes can simply be enumerated.
+For the sake of simplicity, outcomes should be represented as strings.
+
+#### Example: Weather tomorrow
+
+Tomorrow's weather can be represented as the set of strings `[sunny, cloudy, rainy]`.
+
+### Range
+
+When an event has numerical outcomes that cannot be easily enumerated, they can be represented as a series with:
+
+- start: the first possible outcome number
+- end: the last possible outcome number
+- step: the increment
+
+#### Example: tomorrow's temperature
+
+```
+start: -100
+end: 100
+step: 1
+```
+
+### Large range
+
+When a range of a numerical outcomes is large or unbounded, the oracle can represent the outcome using exponent/mantissa (using true normalized form).
+
+The event descriptor should include:
+
+- base: the base in which the outcome is represented
+
+The oracle will then release two R value `R_exponent` and `R_mantissa` as well as two signatures `s_exponent` and `s_mantissa`.
+
+#### Example: BTC/USD rate
+
+```
+base: 10
+exponent: 5
+mantissa: 0.9
+```
+
+### Serialization and signature
+
+Event descriptors should be serialized using [TLV format](https://github.com/lightningnetwork/lightning-rfc/blob/master/01-messaging.md#type-length-value-format) (to be defined).
+The oracle should provide a signature over the serialized descriptor together with the [even identifier](#Unique-Resource-Identifier) to the client as an attestation that he committed to release a signature over the event outcome.
+The signature should be produced in the same way that signatures over event outcomes are produced, namely following [BIP 340](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki).
+
+## Unique Resource Identifiers
+
+To identify, organize or filter events, it is useful that they are assigned unique resource identifier.
+
+### Categorization
+
+Each segment of the URI path, with the exception of the last one, should represent a (sub)-categorization of the event that is being identified.
+Upon being requested a URI corresponding to a category, the resource provider should return a list of resources included in the category that should correspond to either a sub-category or of an event together with their respective URI (HATEOAS).
+The interpretation of the category semantics is not specified and left to the interpretation of the client (or user).
+
+When the list of events within a sub-category is too large to be enumerated, the oracle can instead provide a way for the client to build the last segment of an event URI.
+
+In the case where the events occur periodically, the oracle can return a date range represented as follow:
+
+```
+- startDate: the date of the first event to have occurred within the category (could be past or future) in ISO 8601 format
+- frequency: a period of time representing the frequency at which event in the category occur (ISO 8601 format)
+- range: how far in the future can the oracle provide a descriptor for an event relative to the request time (period in ISO 8601 format).
+```
+
+For cases where the set of events are represented using a number, a range (start, end, step) suffices.
+
+With the information provided, the client can then create the last segment of a URI for an event they are interested in and append it to the URI of the subsection from which they obtained the information in the first place.
+
+#### Example: Oracle web server
+
+A client is given the hostname of an oracle web server `https://crystalball.dlc`.
+The client accesses the root resource `/` and is returned a list of event categories served by the oracle with their respective URIs:
+
+- Sport: `/sport`
+- Finance: `/finance`
+- Politics: `/politics`
+
+The client can then request these URIs to access events or sub-categories.
+
+If the oracle is supporting BTC/USD, a request over `/finance/cryptocurrencies/BTC_USD/biweekly` could for example return:
+
+```
+- startDate: "2020-08-07T22:00:00Z"
+- frequency: "P2W"
+- range: "P4W"
+```
+
+This means that the oracle will sign the BTC/USD rate every two weeks (on Fridays) and that a client can query up to 4 weeks in advance.
+
+### Events
+
+The last segment of a URI must identify a single event.
+Upon requesting an event URI, a client must be served with:
+
+- The event descriptor for the event together with a signature over it and its URI
+- The event result and signature(s) over it if available
+
+_NOTE: we could maybe further split the URI into `/signature` and `/descriptor` but that's a detail for now_
+
+An event URI must include a segment guaranteeing its uniqueness across all events served by the oracle, such as a monotonously increasing number or a timestamp.
+
+### Examples:
+
+- Tennis: `/sport/tennis/wimbledon/2019/federer-djokovitch/vs`
+- NBA score: `/sport/nba/s2019/w24/HOU_PHI/vs`
+- NBA score diff: `/sport/nba/s2019/w24/HOU_PHI/diff`
+
+_Note: The URI scheme doesn't have to be bound to http web server and would still be useful in a P2P context such as if using distributed hash tables to request/propagate data for example._