# Band's Crypto V2 Oracle Script

## Summary

Band's Crypto V2 oracle script provides the aggregated prices of the requested crypto symbols. The oracle script contains a list of data sources to be queried for each symbol. Once the oracle script is called, it sends out a request to BandChain’s validators to retrieve the result from the required data sources. The retrieved prices for each symbol are then aggregated by finding the median, and the resulting price is returned.

## Reference

| BandChain | Oracle Script ID | Example Transaction |
| --------- | ------------------------------------------------------------- | --------------------------------------------------------------- |
| Mainnet | [O46](https://www.cosmoscan.io/oracle-script/46) | [R18201149](https://www.cosmoscan.io/request/18201149) |
| Testnet | [O401](https://laozi-testnet6.cosmoscan.io/oracle-script/401) | [R1214056](https://laozi-testnet6.cosmoscan.io/request/1214056) |

## Input and Output
### Input

The `Input` struct is defined as:

struct Input {
    symbols: Vec<String>,      
    minimum_source_count: u8, 
}

Where:
- `symbols` is the vector containing all the symbols of which the price of the symbol is to be given.
- `minimum_source_count` is the minimum required sources needed for the oracle script to return a value.

**Note:** The recommended minimum source count is at least 3, to ensure the oracle script can effectively calculate the median price.

### Output

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

#### ResponseCode

The `ResponseCode` enum contains the following:

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

| ResponseCode | Status | Possible Reasons |
| ------------ | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0 | Success | - |
| 1 | SymbolNotSupported | Symbol is not supported. Incorrect/mispelled input symbol |
| 2 | NotEnoughSources | Response does not meet the minimum source count requirement (see [Security Parameters](https://hackmd.io/ph1IbDXySqWyaEL0Dm9h0Q#Security-Parameters) below) |
| 3 | ConversionError | Conversion from `f64` to `u64` failed. `f64` value may be too large to be represented as a `u64` |
| 127 | Unknown | Unknown error |

#### Response

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`

#### Output

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

struct Output {
    responses: Vec<Response>
}

## Example

### 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},
    {"symbol":"NES","response_code":2,"rate":0},
]

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 |
| NES | Not enough sources | 0 |

## OBI Schema
Compact OBI representation:

{symbols:[string],minimum_source_count:u8}/{responses:[{symbol:string,response_code:u8,rate:u64}]}

Prettified OBI representation:

{
    symbols: [string],
    minimum_source_count: u8
} / {
    responses: [{
        symbol: string,
        response_code: u8,
        rate: u64
    }]
}

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

### Minimum Source Count
A user defined variable, minimum source 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 source count, `ResponseCode::NotEnoughSources` will be returned.

### Breakdown Point
The oracle script uses the breakdown point, which is calculated from the given `min_count` (minimum validator responses) 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.