chore: explain provider oracle

Author: bangjelkoski

docs/develop/guides/oracle/_category_.json

@@ -0,0 +1,8 @@
+{
+    "label": "Oracle",
+    "position": 5,
+    "link": {
+      "type": "doc",
+      "id":"index"
+    }
+  }

docs/develop/guides/oracle/index.md

@@ -0,0 +1,17 @@
+# Oracle
+
+Prerequisite: [Injective Oracle Module](../../../develop/modules/injective/oracle/).
+
+## Oracle Provider
+
+The goal of this section is to provide users a guide on how to launch and maintain a oracle provider on Injective. These oracles can be used for various purposes, like Perpetual Markets, Expiry Futures Markets, [Binary Options markets](../../../develop/modules/injective/exchange/02_binary_options_markets.md), etc. 
+
+First, what is an oracle provider? It's an oracle **TYPE** which allows external parties to relay price feed to the Injective chain. These external parties are called providers. Each external party is identified by a provider and all of the price feeds provided on the chain are stored under that particular provider. This allows custom price feed to be created on Injective which can power creative and advanced markets being launched on Injective. 
+
+The first thing developers need to do is register their provider under the Oracle Provider type. You can do that by submitting a `GrantProviderPrivilegeProposal` governance proposal. Once the proposal passes, your provider will be registered and you'll be able to relay price feeds. You can do it in a CLI environment using `injectived` (`grant-provider-privilege-proposal [providerName] [relayers] --title [title] --description [desc] [flags]`) or using any of our SDKs to create the message and broadcast it to the chain. 
+
+Note: the `relayers` of the `GrantProviderPrivilegeProposal` are addresses which will be whitelisted to submit the price feeds to Injective.
+
+Once the proposal passes, the `relayers` can use the `MsgRelayProviderPrices` to submit prices for a base/quote pair within their provider namespace of the Oracle Provider Type oracle on Injective. You can do it in a CLI environment using `injectived` (`relay-provider-prices [providerName] [symbol:prices] [flags]`) or using any of our SDKs to create the message and broadcast it to the chain. 
+
+Finally, you can use these price feeds to create your Derivative Markets. 

docs/develop/modules/injective/exchange/02_binary_options_markets.md

@@ -19,7 +19,7 @@ Alice buys 1 contract at $0.20 (margined with $0.20) against Bob who sells 1 con
 
 - Alice wins $0.80 if the market settles at $1 and Bob wins $0.2 if the market settles at $0.
 
-### Oracle
+## Oracle
 
 Binary options markets are tightly coupled to the Provider Oracle type, which allows a governance-registered provider to relay price feed data for arbitrary new price feeds under the provider's subtype without the need for extra governance for adding successively new price feeds. Each binary options market is comprised of the following oracle parameters:
 * Oracle symbol (e.g. UFC-KHABIB-TKO-09082022)
@@ -35,7 +35,23 @@ Oracle can also post the final price of **-1**, which is the flag price than tri
 
 Further documentation on the oracle provider type can be found in the Oracle module documentation.  
 
+### Registering an oracle provider
+
+To register your oracle provider, you need to submit a `GrantProviderPrivilegeProposal` governance proposal. This proposal will register your provider and will allow your address to relay price feeds. 
+
+```go
+type GrantProviderPrivilegeProposal struct {
+	Title       string   
+	Description string   
+	Provider    string    // the name of the provider, should be specific to you
+	Relayers    []string  // addresses which will be able to relay prices 
+}
+```
+
+Once the proposal passes, your provider will be registered and you'll be able to relay your price feeds (example below). 
+
 ## Market Lifecycle
+
 ### Market Creation
 A binary options market can be created through an instant launch (through a `MsgInstantBinaryOptionsMarketLaunch`) or through governance (through a `BinaryOptionsMarketLaunchProposal`). 
 
@@ -50,3 +66,50 @@ Pertinently, binary options markets also have a characteristic `ExpirationTimest
 * **Expired** = trading is closed, open orders are cancelled, no change to positions. 
 * **Demolished** = positions are settled / refunded (depending on the settlement), market is demolished
 
+The nature of the status transitions for binary options markets are as follows:
+
+| Status Change | Workflow |
+| --- | --- |
+| Active → Expired | Expiration is part of the standard workflow for a market. Trading is halted immediately for the market and all open orders are cancelled. The market can now be settled immediately (forcefully) by the admin or oracle or be settled naturally using the latest oracle price when we reach SettlementTimestamp.
+| Expired → Demolished (Settlement) | All positions are settled at either the price set by forceful settlement or natural settlement. The market can never be traded on or reactivated again. For natural settlement, upon the SettlementTimestamp time, the last oracle price is recorded and used for settlement. For ‘force-settle’, Admin should post the MarketUpdate msg with SettlementPrice in it being set in a price band of [0, 1]. 
+| Active/Expired → Demolished (Refund) | All positions get refunded. The market can never be traded on or reactivated again. Admin should post the MarketUpdate msg with SettlementPrice in it being set to -1. |
+
+
+### Market Settlement
+
+The settlement price options are explained above in the [oracle](#oracle) section. 
+
+Settling a market can be achieved using one of these two options: 
+1. Using the registered provider oracle for the particular market. Once the provider oracle is granted privileges to relay prices (explained above), the address with the privileges can relay prices for a particular price feed using the `MsgRelayProviderPrices` message. 
+```go
+// MsgRelayProviderPrices defines a SDK message for setting a price through the provider oracle.
+type MsgRelayProviderPrices struct {
+	Sender   string                        
+	Provider string                        
+	Symbols  []string                      
+	Prices   []cosmossdk_io_math.LegacyDec 
+}
+```
+
+2. Using the `MsgAdminUpdateBinaryOptionsMarket` which allows the market's admin (creator) to submit a settlement price directly to the market. 
+```go
+type MsgAdminUpdateBinaryOptionsMarket struct {
+  // new price at which market will be settled
+  SettlementPrice *Dec 
+  // expiration timestamp
+  ExpirationTimestamp int64
+  // expiration timestamp
+  SettlementTimestamp int64
+  // Status of the market
+  Status MarketStatus
+}
+
+// Where Status can be one of these options
+enum MarketStatus {
+  Unspecified = 0;
+  Active = 1;
+  Paused = 2;
+  Demolished = 3;
+  Expired = 4;
+} 
+```

docs/develop/modules/injective/oracle/03_messages.md

@@ -164,3 +164,27 @@ This message is expected to fail if:
 - the Relayer (`sender`) is not an authorized oracle publisher or if `assetId` is not unique amongst the provided asset pairs 
 - ECDSA signature verification fails for the `SignedPriceOfAssetPair`  
 - the difference between timestamps exceeds the `MaxStorkTimestampIntervalNano` (500 milliseconds).
+
+## MsgRelayProviderPrices
+
+Relayers of a particular Provider can send the price feed using `MsgRelayProviderPrices` message.
+
+```protobuf
+// MsgRelayProviderPrice defines a SDK message for setting a price through the provider oracle.
+message MsgRelayProviderPrices {
+  option (amino.name) = "oracle/MsgRelayProviderPrices";
+  option (gogoproto.equal) = false;
+  option (gogoproto.goproto_getters) = false;
+  option (cosmos.msg.v1.signer) = "sender";
+
+  string sender = 1;
+  string provider = 2;
+  repeated string symbols = 3;
+  repeated string prices = 4 [
+    (gogoproto.customtype) = "cosmossdk.io/math.LegacyDec",
+    (gogoproto.nullable) = false
+  ];
+}
+```
+
+This message is expected to fail if the Relayer (`Sender`) is not an authorized pricefeed relayer for the given Base Quote pair or if the price is greater than 10000000.