Tellor Docs
Search…
Introduction
This page is designed to give you a quick overview of using Tellor to get data into your smart contracts.

Integrating Tellor Oracle Data in Ethereum Smart Contracts

For this, we provide a helper contract that will provide convenience functions to interact with the Tellor System.

Installation

1
npm install usingtellor
Copied!

Using in the contract in solidity:

Just import the usingTellor contract to your solidity file passing the desired Tellor address(see references page) as a parameter.
Test: Use the TellorPlayground contract
1
pragma solidity >=0.4.21 <0.7.0;
2
3
import "usingtellor/contracts/UsingTellor.sol";
4
5
contract MyContract is UsingTellor {
6
7
constructor(address payable _tellorAddress) UsingTellor(_tellorAddress) public {
8
9
}
10
11
// ...
12
13
}
Copied!

Important Details

Line 5: Your contract inherits the functions needed to interact with Tellor
Line 7: Your constructor needs to specify the Tellor Oracle contract address(see references page for the address)

Available Tellor Functions

Children contracts have access to the following functions:
1
/**
2
* @dev Retreive value from oracle based on requestId/timestamp
3
* @param _requestId being requested
4
* @param _timestamp to retreive data/value from
5
* @return uint value for requestId/timestamp submitted
6
*/
7
function retrieveData(uint256 _requestId, uint256 _timestamp) public view returns(uint256);
8
9
/**
10
* @dev Gets if the mined value for the specified requestId/_timestamp is currently under dispute
11
* @param _requestId to looku p
12
* @param _timestamp is the timestamp to look up miners for
13
* @return bool true if requestId/timestamp is under dispute
14
*/
15
function isInDispute(uint256 _requestId, uint256 _timestamp) public view returns(bool);
16
17
/**
18
* @dev Counts the number of values that have been submitted for the request
19
* @param _requestId the requestId to look up
20
* @return uint count of the number of values received for the requestId
21
*/
22
function getNewValueCountbyRequestId(uint256 _requestId) public view returns(uint);
23
24
/**
25
* @dev Gets the timestamp for the value based on their index
26
* @param _requestId is the requestId to look up
27
* @param _index is the value index to look up
28
* @return uint timestamp
29
*/
30
function getTimestampbyRequestIDandIndex(uint256 _requestId, uint256 _index) public view returns(uint256);
31
32
/**
33
* @dev Allows the user to get the latest value for the requestId specified
34
* @param _requestId is the requestId to look up the value for
35
* @return bool true if it is able to retreive a value, the value, and the value's timestamp
36
*/
37
function getCurrentValue(uint256 _requestId) public view returns (bool ifRetrieve, uint256 value, uint256 _timestampRetrieved);
38
39
/**
40
* @dev Allows the user to get the first value for the requestId before the specified timestamp
41
* @param _requestId is the requestId to look up the value for
42
* @param _timestamp before which to search for first verified value
43
* @return bool true if it is able to retreive a value, the value, and the value's timestamp
44
*/
45
function getDataBefore(uint256 _requestId, uint256 _timestamp)
46
public
47
view
48
returns (bool _ifRetrieve, uint256 _value, uint256 _timestampRetrieved);
Copied!

Request IDs

The request ID is used to look up prices in the Tellor Oracle. You will need to figure out what the request ID is for the price data you want. The BTC/USD price is request ID 2.

Example usage

1
contract BtcPriceContract is UsingTellor {
2
3
//This Contract now have access to all functions on UsingTellor
4
5
uint256 btcPrice;
6
uint256 btcRequestId = 2;
7
8
constructor(address payable _tellorAddress) UsingTellor(_tellorAddress) public {}
9
10
function setBtcPrice() public {
11
bool _didGet;
12
uint _timestamp;
13
uint _value;
14
15
(_didGet, btcPrice, _timestamp) = getCurrentValue(btcRequestId);
16
}
17
}
Copied!
Line 4: ThebtcRequetId is set local to2, the BTC/USD request ID
Line 12: The call to getCurrentValue returns the value into btcPrice

Testing your contracts

For ease of use, the UsingTellor repo comes with Tellor Playground system for easier integration. This mock version contains a few helper functions:
1
/**
2
* @dev Public function to mint tokens for the passed address
3
* @param user The address which will own the tokens
4
*
5
*/
6
function faucet(address user) external;
7
8
9
/**
10
* @dev A mock function to submit a value to be read without miners needed
11
* @param _requestId The tellorId to associate the value to
12
* @param _value the value for the requestId
13
*/
14
function submitValue(uint256 _requestId,uint256 _value) external;
Copied!

Running tests

1
npm run test
Copied!

Migration

Just run truffle migrate with the desired Network
1
truffle migrate --network rinkeby
Copied!

Sample Project

We provide a repo with this setup installed and ready for use: SampleUsingTellor. Watch the video walkthrough here.
Last modified 4mo ago