Contract methods

Documentation of all interactable contract methods.
Constructor
Creates a new instance of the contract.
1
#[init]
2
pub fn new(
3
    initial_whitelist: Option<Vec<ValidAccountId>>,
4
    config: oracle_config::OracleConfig
5
) -> Self
Copied!
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.
1
#[payable]
2
pub fn set_config(&mut self, new_config: OracleConfig) -> ()
Copied!
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
1
pub fn get_config(&self) -> OracleConfig
Copied!
Add account to whitelist (gov only)
Adds a contract to the whitelist. Allowing the contract to interact with the oracle contract.
1
#[payable]
2
fn add_to_whitelist(&mut self, new_requestor: ValidAccountId) -> ()
Copied!
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.
1
#[payable]
2
fn remove_from_whitelist(&mut self, requestor: ValidAccountId) -> bool
Copied!
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.
1
fn whitelist_contains(&self, requestor: AccountId) -> bool
Copied!
Getting the storage requirements (read-only)
Returns the bounds for storage. The minimum storage is required to make transactions.
1
fn storage_balance_bounds(&self) -> fn storage_balance_bounds(&self) -> StorageBalanceBounds
Copied!
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.
1
fn storage_balance_of(&self, account_id: ValidAccountId) -> Option<StorageBalance>
Copied!
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.
1
#[payable]
2
fn storage_deposit(&mut self, account_id: Option<ValidAccountId>) -> StorageBalance
Copied!
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).
1
#[payable]
2
fn storage_withdraw(&mut self, amount: U128) -> StorageBalance
Copied!
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:
1
ft_transfer_call("ORACLE_CONTRACT_ACCOUNT", "1000000000000000000", JSON.stringify({
2
    "NewDataRequest": {
3
        // 12 hours in nano seconds
4
        "challenge_period": "43200000000000",
5
        // Tue Jun 01 2021 13:10:31 GMT+0200 in nano seconds
6
        "settlement_time": "1622545831163000000",
7
        "target_contract": "MY_CONTRACT_ID",
8
        "outcomes": ["BTC", "ETH", "NEAR"],
9
        "sources": [{
10
            "end_point": "http://myurl/api/data"
11
            "source_path": "path.to.value"
12
        }],
13
        "description": "Some description",
14
        "tags": ["TAG_FOR_IDENTIFICATION"],
15
    }
16
}))
Copied!
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:
1
ft_transfer_call("ORACLE_CONTRACT_ACCOUNT", "1000000000000000000", JSON.stringify({
2
    "StakeDataRequest": {
3
        "id": "1",
4
        "outcome": {
5
            "Answer": "MY_ANSWER_HERE"
6
        },
7
    }
8
}))
Copied!
And for an invalid outcome:
1
ft_transfer_call("ORACLE_CONTRACT_ACCOUNT", "1000000000000000000", JSON.stringify({
2
    "StakeDataRequest": {
3
        "id": "1",
4
        "outcome": "Invalid",
5
    }
6
}))
Copied!
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.
1
pub fn dr_unstake(&mut self, request_id: U64, resolution_round: u16, outcome: Outcome, amount: U128) -> Promise
Copied!
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.
1
#[payable]
2
pub fn dr_finalize(&mut self, request_id: U64) -> PromiseOrValue<bool>
Copied!
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.
1
#[payable]
2
pub fn dr_final_arbitrator_finalize(&mut self, request_id: U64, outcome: Outcome) -> PromiseOrValue<bool>
Copied!
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.
1
#[payable]
2
pub fn dr_claim(&mut self, account_id: String, request_id: U64) -> Promise
Copied!
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