# Oracle Script

## Introduction

### Changes Made

There are three major changes that this oracle script implements:
- Allowing a partial response
- Descriptive output
- Additional security parameters

### Partial Response
Previously, the oracle script would not return a result if any of the given inputs did not respond accordingly, i.e If an unsupported symbol was provided in the input, the oracle script would end its execution. The new oracle script will return a result if an error is occured and describe the given error as well.

### Descriptive Output
Previously, the oracle script would list out the asset prices in the same order given as the input array. The new oracle script explicitly notates which symbol the results are shown for now so knowledge of the input is not needed to interpret the output data.

### Security Parameters
The new oracle script now implements two new security feature:
- A minimum response count, which is set by the user.
- Rejecting a source if the breakdown point from the validator's responses is exceeded.

#### Minimum Response Count
A user defined variable, minimum response count now allows users to specify how many sources they require to respond in order return a valid result. In the case that a symbol does not meet this minimum response count, `ResponseCode::NotEnoughSources` will be returned.

#### Breakdown Point
The new oracle script now uses the breakdown point, which is calculated from the given `ask_count` in the request.

In the case that a validator returns an invalid result or does not return a result, the oracle script will immediately discredit and ignore the validator's response. If the total validator responses is insufficient, the source is ultimately ignored.

## Input

The `Input` struct is defined as:

struct Input {
    symbols: Vec<String>,      // Where the symbols requested are given
    minimum_source_count: u8,  // The minimum required source to show a valid response
}

Where symbol is defined as the a vector containing all the symbols of which the price of the symbol is to be given and minimum source count is defined as the minimum required sources needed for the oracle script to return a value.

## Output

The `Output` struct for the oracle script contains two components, the `Response` struct and the `ResponseCode` enum.

The `ResponseCode` enum contains the following:

enum ResponseCode {
    Success,
    SymbolNotSupported,
    NotEnoughSources,
    ConversionError,
    Unknown = 127,
}

and the `Response` struct is defined as:

struct Response {
    symbol: String,   
    response_code: u8,
    rate: u64,
}

Where
- `symbol` is the symbol's asset ticker
- `response_code` is the code defining the symbol's response
- `rate` is the symbol's rate multiplied by 1E9. In the case of a non-zero response code, the rate is given as `0`

The `Output` struct itself contains a vector of the `Response` struct
and is defined as:

struct Output {
    responses: Vec<Response>
}

## Example input:

Where the expected symbols are BTC, DNE, ETH and USDT and the minimum source count is set to 3, the expected input should look as follows:

{
    "symbols": ["BTC","DNE","ETH","USDT"],
    "minimum_source_count": 3
}

## Example output:

Given the same input as before, an example output can be seen below:

[
    {"symbol":"BTC","response_code":0,"rate":20734240000000},
    {"symbol":"DNE","response_code":1,"rate":0,    
    {"symbol":"ETH","response_code":0,"rate":1518970504937},
    {"symbol":"USDT","response_code":0,"rate":1000000000},
]

Where the results can be interpreted as:

| Symbol | Response Code Interpretation | Price |
| ------ | ---------------------------- | --------------- |
| BTC | Success | 20,734.24 |
| DNE | Symbol is not supported | 0 |
| ETH | Success | 1,518.970504937 |
| USDT | Success | 1.00 |

## Testnet Details

The Oracle script is deployed at [O396](https://laozi-testnet6.cosmoscan.io/oracle-script/396) and an example transaction can be found [here](https://laozi-testnet6.cosmoscan.io/request/433272).