Contract methods

Documentation of all interactable contract methods.

Constructor

Creates a new instance of the contract.

#[init]
pub fn new(
initial_whitelist: Option<Vec<ValidAccountId>>,
config: oracle_config::OracleConfig
) -> Self

Key

Type

Description

initial_whitelist

Option<Vec<ValidAccountId>>

The initial whitelisted contract ids who can interact with the oracle. More can be added later with the add_to_whitelist function through the DAO.

config

OracleConfig

The initial oracle config. Contains details about fees, window duration, etc. See OracleConfig. Can be changed by the DAO through the set_config function.

OracleConfig (Object)

Key

Type

Description

gov

AccountId/String

Can execute config function on the contract. This should be assigned to a DAO.

final_arbitrator

AccountId/String

The final account id can resolve a data request when the request hits a certain amount of stake. This is to prevent a data request from being stuck in limbo.

stake_token

AccountId/String

The token is used for staking.

bond_token

AccountId/String

The token is used for paying the bond.

validity_bond

U128

The number of tokens must be submitted to create a data request

max_outcomes

u8

The maximum amount of outcomes a data request can have when used.

default_challenge_window_duration

U64

The default duration of a challenge window in nanoseconds

min_initial_challenge_window_duration

U64

The minimum duration of a challenge window

final_arbitrator_invoke_amount

U128

Amount of tokens that when bonded in a single ResolutionWindow should trigger the final arbitrator

resolution_fee_percentage

u16

Percentage of requesters tvl behind the request that's to be paid out to stakers, denominated in 1e4 so 1 = 0.01% - 10000 = 100%

Setting the global config (gov only)

Sets the global config for new data requests. Old data requests are not affected and will use the old config.

#[payable]
pub fn set_config(&mut self, new_config: OracleConfig) -> ()

Key

Type

Description

new_config

OracleConfig

The oracle config will be used for newer data requests. For documentation about each property see OracleConfig above.

Getting the active config (read-only)

Returns the current active OracleConfig

pub fn get_config(&self) -> OracleConfig

Add account to whitelist (gov only)

Adds a contract to the whitelist. Allowing the contract to interact with the oracle contract.

#[payable]
fn add_to_whitelist(&mut self, new_requestor: ValidAccountId) -> ()

Key

Type

Description

new_requestor

ValidAccountId

A NEAR account id that you want to add to the whitelist

Remove account from the whitelist (gov only)

Removes an account from the whitelist. This will disable the account's access to interacting with the oracle.

#[payable]
fn remove_from_whitelist(&mut self, requestor: ValidAccountId) -> bool

Key

Type

Description

requestor

ValidAccountId

A NEAR account id that you want to remove from the whitelist

Checking if an account is in the whitelist (read-only)

Checks if the given account is in the whitelist. Returns true when the account is in the whitelist, false otherwise.

fn whitelist_contains(&self, requestor: AccountId) -> bool

Getting the storage requirements (read-only)

Returns the bounds for storage. The minimum storage is required to make transactions.

fn storage_balance_bounds(&self) -> fn storage_balance_bounds(&self) -> StorageBalanceBounds

Returns StorageBalanceBounds

StorageBalanceBounds

Key

Type

Description

min

U128

The minimum amount of storage the contract needs for interacting

max

Option<U128>

The maximum amount of storage allowed for the contract

Getting the amount of storage an account has (read-only)

Gets the storage balance of a specific account id. Returns null if the account has no storage.

fn storage_balance_of(&self, account_id: ValidAccountId) -> Option<StorageBalance>

Returns StorageBalance

StorageBalance

Key

Type

Description

total

U128

The total amount of NEAR deposited in the contract

available

U128

The amount of NEAR that is available to be used for storage

Depositing NEAR for storage

Deposits NEAR to be used for storage inside the contract.

#[payable]
fn storage_deposit(&mut self, account_id: Option<ValidAccountId>) -> StorageBalance

Key

Type

Description

account_id

Option<ValidAccountId>

The account id you want to fund the storage. It will use the predecessor account id when null/None

Withdrawing NEAR from storage

Withdraws NEAR that are unused. (Only possible when the account has already deposited storage).

#[payable]
fn storage_withdraw(&mut self, amount: U128) -> StorageBalance

Returns StorageBalance (See above for documentation)

Creating a new data request

Creating a new data request requires the call to be done through ft_transfer_call with the bond_token. It requires a message to be attached to the call containing an NewDataRequest object. Please fetch the current oracle config with get_config to see the number of tokens you need to send with the request. Below you can see an example using JavaScript:

ft_transfer_call("ORACLE_CONTRACT_ACCOUNT", "1000000000000000000", JSON.stringify({
"NewDataRequest": {
// 12 hours in nano seconds
"challenge_period": "43200000000000",
// Tue Jun 01 2021 13:10:31 GMT+0200 in nano seconds
"settlement_time": "1622545831163000000",
"target_contract": "MY_CONTRACT_ID",
"outcomes": ["BTC", "ETH", "NEAR"],
"sources": [{
"end_point": "http://myurl/api/data"
"source_path": "path.to.value"
}],
"description": "Some description",
"tags": ["TAG_FOR_IDENTIFICATION"],
}
}))

Key

Type

Description

challenge_period

U64

The amount of time a challenge is in nanoseconds

settlement_time

U64

The timestamp in nanoseconds when the request should be settled

target_contract

AccountId/String

The contract that implements the set_outcome function.

outcomes

Option<Vec<String>>

Optional outcomes, validators can only pick an answer from this array.

sources

Vec<Source>

Array API sources/paths. (More on the topic below) Can be an empty array for non API data

description

Option<String>

Description to resolve this data request. Mandatory if you have no sources attached

tags

Option<Vec<String>>

Tags that can be used to identify the data request.

Staking on a data request

Staking on a data request requires the call to be done through ft_transfer_call with the stake_token (from the config). It requires a message to be attached to the call containing an StakeDataRequest object. Staking can only be done when the settlement_time has been reached. Below you can see an example using JavaScript for a valid outcome:

ft_transfer_call("ORACLE_CONTRACT_ACCOUNT", "1000000000000000000", JSON.stringify({
"StakeDataRequest": {
"id": "1",
"outcome": {
"Answer": "MY_ANSWER_HERE"
},
}
}))

And for an invalid outcome:

ft_transfer_call("ORACLE_CONTRACT_ACCOUNT", "1000000000000000000", JSON.stringify({
"StakeDataRequest": {
"id": "1",
"outcome": "Invalid",
}
}))

Key

Type

Description

id

U64

The data request-id you want to stake on

outcome

Outcome

The outcome that belongs to this request. Can be either "Invalid" or { "Answer": "ANSWER_HERE" }

Unstaking on a data request

Unstaking can be done as long as the resolution window hasn't bonded yet.

pub fn dr_unstake(&mut self, request_id: U64, resolution_round: u16, outcome: Outcome, amount: U128) -> Promise

Key

Type

Description

request_id

U64

The request-id where you want to unstake

resolution_round

u16

Which round you want to unstake on (should be the latest round)

outcome

Outcome

The outcome that you want to unstake on. Can be either "Invalid" or { "Answer": "ANSWER_HERE" }

amount

U128

The number of tokens you want to unstake

Finalizing a data request

Once the window has been closed and the bonded_outcome has been met you can finalize a request. This will call the target_contract with the finalized outcome.

#[payable]
pub fn dr_finalize(&mut self, request_id: U64) -> PromiseOrValue<bool>

Key

Type

Description

request_id

U64

The request-id you want to finalize.

Finalizing a data request as the final arbitrator

Only the final arbitrator can finalize data requests that have met the final_arbitrator_invoke_amount requirement.

#[payable]
pub fn dr_final_arbitrator_finalize(&mut self, request_id: U64, outcome: Outcome) -> PromiseOrValue<bool>

Key

Type

Description

request_id

U64

The request-id you want to finalize

outcome

Outcome

The outcome that you want to set as the outcome. Can be either "Invalid" or { "Answer": "ANSWER_HERE" }

Claim earnings for a data request

Once the data request is finalized you can claim earnings for correctly staking on an outcome.

#[payable]
pub fn dr_claim(&mut self, account_id: String, request_id: U64) -> Promise

Key

Type

Description

account_id

AccountId/String

The account id you want to claim for

request_id

U64

The request-id you want to claim