Oracle

An Oracle contract that collects price reports from several feeds and ensures they are within a price range and time limit.

Structs

Oracle

 struct Oracle<phantom Witness: drop> has key, store {
    id: UID,
    // Set of module Witnesses that are allowed to report prices.
    feeds: VecSet<TypeName>,
    // Reported prices must have a timestamp earlier than `current_timestamp - time_limit`. 
    // It is in milliseconds. 
    time_limit: u64,
    // Reported prices must be within the following range: `leader_price + deviation % >= reported_price >= leader_price - deviation %`.
    deviation: u256
  }  

• feeds - Set of module Witnesses that are allowed to report prices.

• time_limit - Reported prices must have a timestamp earlier than `current_timestamp - time_limit`. It is in milliseconds.

• deviation - Reported prices must be within the following range: `leader_price + deviation % >= reported_price >= leader_price - deviation %`.

Report

struct Report has store, copy, drop {
    price: u256,
    timestamp: u64
 }

• price - Price has 18 decimals.

• timestamp - Timestamp in milliseconds.

Price

struct Price {
    // `sui::object::ID` of the`Oracle` this request was sent from.
    oracle: ID,
    // The first reported price. 
    // Price has 18 decimals.  
    price: u256,
    // It is always 18.  
    decimals: u8, 
    // The price was reported at this time.  
    timestamp: u64    
 }

• oracle - the `sui::object::ID` of the Oracle this request was sent from.

• price - The first reported price after all checks.

• decimals - It is always 18.

• timestamp - The time at which this price was reported.

Interface

new

Creates an Oracle with a set of feeds.

public fun new<Witness: drop>(
  cap: &mut OwnerCap<Witness>,
  wit: Witness, 
  feeds: vector<TypeName>, 
  time_limit: u64, 
  deviation: u256, 
  ctx: &mut TxContext
): Oracle<Witness>

• @param cap: An owner cap from suitears::owner. This OwnerCap will be the owner of the new Oracle.

• @param wit: A Witness from the module that will manage this Oracle.

• @param feeds: Feed Witnesses. Only modules in the Oracle.feeds can report a price in the Request hot potato.

• @param time_limit: A time in milliseconds that determines how old a price timestamp can be.

• @param deviation: A percentage that determines an acceptable price range for all reported prices.

• @return Oracle<Witness>.

Aborts

• feeds vector has repeated values.

• time_limit must be higher than 0 milliseconds.

• deviation must be higher than 0.

share

Shares the Oracle object.

public fun share<Witness: drop>(self: Oracle<Witness>)

• @param self: The Oracle.

request

Creates a Request hot potato.

public fun request<Witness: drop>(self: &Oracle<Witness>): Request

• @param self: The Request will require all feeds from Oracle to be reported.

• @return Request.

Aborts

• self.feed is empty.

report

Adds a price Report to the Request.

public fun report<Witness: drop>(request: &mut Request, _: Witness, timestamp: u64, price: u128, decimals: u8)

• @param request: Request hot potato.

• @param _ : A Witness to verify the reporters.

• @param timestamp: The timestamp of the price feed.

• @param price: The price

• @param decimals: The decimal houses of the price value.

• @return Request.

Aborts

• a feed reports more than once.

destroy_request

Destroy the Request potato and verify the price values and timestamps.

public fun destroy_request<Witness: drop>(self: &Oracle<Witness>, request: Request, c: &Clock): Price

• @param self: The Oracle that the Request was sent from.

• @param request: The Request.

• @param c: The shared sui::clock::Clock object.

• @return Price.

Aborts

• TheRequest.oracle does not match the self.id.

• The number of reports does not match the number of feeds in the Oracle.feeds.

• The report witnesses do not match the required feed witnesses.

• The reported price is outside the time_limit.

• The price falls outside the outside deviation range.

destroy_price

Destroys an Oracle object.

public fun destroy_oracle<Witness: drop>(self: Oracle<Witness>)

• @param self: The Oracle that the Request was sent from.

• @param cap: The suitears::owner::OwnerCap that owns the self.

Aborts

• the cap is not the owner of self.

feeds

Returns a vector of the Oracle.feeds.

public fun feeds<Witness: drop>(self: &Oracle<Witness>): vector<TypeName>

• @param self: An Oracle object.

• @return vector

feeds

Returns a vector of the Oracle.feeds.

public fun feeds<Witness: drop>(self: &Oracle<Witness>): vector<TypeName>

• @param self: An Oracle object.

• @return vector

time_limit

Returns a time limit set in the Oracle.

public fun feeds<Witness: drop>(self: &Oracle<Witness>): vector<TypeName>

• @param self: An Oracle object.

• @return vector

deviation

Returns the price deviation set in the Oracle.

public fun deviation<Witness: drop>(self: &Oracle<Witness>): u256

• @param self: An Oracle object.

• @return u256

uid

Allows extensions to read dynamic fields.

public fun uid<Witness: drop>(self: &Oracle<Witness>): &UID

• @param self: An Oracle object.

• @return sui::object::UID

oracle

Returns the sui::object::ID of a Price's oracle.

public fun oracle(price: &Price): ID

• @param price: A Price potato.

• @return sui::object::ID

price

Returns the price value of a Price hot potato.

public fun price(price: &Price): u256

• @param price: A Price potato.

• @return u256

decimals

Returns the decimal houses of the price value.

public fun decimals(price: &Price): u8

• @param price: A Price potato.

• @return u8

timestamp

Returns the timestamp of the a Price.

public fun timestamp(price: &Price): u64

• @param price: A Price potato.

• @return u64

uid_mut

Allows extensions to add/remove dynamic fields.

public fun uid_mut<Witness: drop>(self: &mut Oracle<Witness>, cap: &OwnerCap<Witness>): &mut UID

• @param self: An Oracle object.

• @param cap: The suitears::owner::OwnerCap that owns the self.

• @return sui::object::UID

Aborts

• The cap is not the owner of self.

add

Adds a feed Witness to an Oracle.

public fun add<Witness: drop>(self: &mut Oracle<Witness>, cap: &OwnerCap<Witness>, feed: TypeName)

• @param self: An Oracle object.

• @param cap: The suitears::owner::OwnerCap that owns the self.

• @param feed: A Witness feed.

Aborts

• The cap is not the owner of self.

• A duplicated feed is added.

remove

Removes a feed Witness to an Oracle.

public fun remove<Witness: drop>(self: &mut Oracle<Witness>, cap: &OwnerCap<Witness>, feed: TypeName)

• @param self: An Oracle object.

• @param cap: The suitears::owner::OwnerCap that owns the self.

• @param feed: A Witness feed.

Aborts

• The cap is not the owner of self.

• The Oracle has 1 feed left.

update_time_limit

Updates the time_limit of an Oracle.

public fun update_time_limit<Witness: drop>(self: &mut Oracle<Witness>, cap: &OwnerCap<Witness>, time_limit: u64)

• @param self: An Oracle object.

• @param cap: The suitears::owner::OwnerCap that owns the self.

• @param time_limit: The new time_limit.

Aborts

• The cap is not the owner of self.

• The time_limit cannot be zero.

update_deviation

Updates the deviation of an Oracle.

public fun update_deviation<Witness: drop>(self: &mut Oracle<Witness>, cap: &OwnerCap<Witness>, deviation: u256)

• @param self: An Oracle object.

• @param cap: The suitears::owner::OwnerCap that owns the self.

• @param deviation: The new deviation.

Aborts

• The cap is not the owner of self.

• The time_limit cannot be zero.

new_price_for_testing

Creates a Price for testing purposes only. Only available in tests.

#[test_only]
public fun new_price_for_testing(
 oracle: ID,
 price: u256,
 decimals: u8,
 timestamp: u64
): Price

• @param oracle: sui::object::ID of theOracle this request was sent from.

• @param price: The reported price.

• @param decimals: The decimals precision of price.

• @param timestamp: The timestamp in milliseconds in which the price was recorded.