Tellor Docs
Search…
Integration
Token Holders
Security
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
We provide a helper contract that provides convenient functions for interacting with the Tellor system.
Installation
1
npm install usingtellor
Copied!
Using in a contract in solidity:
Just import the UsingTellor contract into your solidity file passing the desired Tellor address (see references page) as a parameter.
1
pragma solidity >=0.8.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 contract address (see references page for the address). For testing, use a TellorPlayground address. In production, use either the TellorMaster address on Ethereum mainnet or the TellorFlex address on Polygon.
Available Tellor Functions
Children contracts have access to the following functions:
1
/**
2
* @dev Retrieve value from oracle based on queryId/timestamp
3
* @param _queryId being requested
4
* @param _timestamp to retrieve data/value from
5
* @return bytes value for query/timestamp submitted
6
*/
7
function retrieveData(bytes32 _queryId, uint256 _timestamp)
8
public
9
view
10
returns (bytes memory);
11
12
/**
13
* @dev Determines whether a value with a given queryId and timestamp has been disputed
14
* @param _queryId is the value id to look up
15
* @param _timestamp is the timestamp of the value to look up
16
* @return bool true if queryId/timestamp is under dispute
17
*/
18
function isInDispute(bytes32 _queryId, uint256 _timestamp)
19
public
20
view
21
returns (bool);
22
23
/**
24
* @dev Counts the number of values that have been submitted for the queryId
25
* @param _queryId the id to look up
26
* @return uint256 count of the number of values received for the queryId
27
*/
28
function getNewValueCountbyQueryId(bytes32 _queryId)
29
public
30
view
31
returns (uint256);
32
33
/**
34
* @dev Gets the timestamp for the value based on its index
35
* @param _queryId is the id to look up
36
* @param _index is the value index to look up
37
* @return uint256 timestamp
38
*/
39
function getTimestampbyQueryIdandIndex(bytes32 _queryId, uint256 _index)
40
public
41
view
42
returns (uint256);
43
44
/**
45
* @dev Allows the user to get the latest value for the queryId specified
46
* @param _queryId is the id to look up the value for
47
* @return ifRetrieve bool true if non-zero value successfully retrieved
48
* @return value the value retrieved
49
* @return _timestampRetrieved the retrieved value's timestamp
50
*/
51
function getCurrentValue(bytes32 _queryId)
52
public
53
view
54
returns (
55
bool _ifRetrieve,
56
bytes memory _value,
57
uint256 _timestampRetrieved
58
);
59
60
/**
61
* @dev Retrieves the latest value for the queryId before the specified timestamp
62
* @param _queryId is the queryId to look up the value for
63
* @param _timestamp before which to search for latest value
64
* @return _ifRetrieve bool true if able to retrieve a non-zero value
65
* @return _value the value retrieved
66
* @return _timestampRetrieved the value's timestamp
67
*/
68
function getDataBefore(bytes32 _queryId, uint256 _timestamp)
69
public
70
view
71
returns (
72
bool _ifRetrieve,
73
bytes memory _value,
74
uint256 _timestampRetrieved
75
);
Copied!
Line 68: When retrieving your data from Tellor, it's recommended you use the
getDataBefore function with a time buffer to allow time for a bad value to be disputed.Query IDs
The query ID is used to look up values in the Tellor Oracle. You will need to figure out what the query ID is for the data you want. The BTC/USD price is query ID 2.
Example usage
1
contract BtcPriceContract is UsingTellor {
2
3
// This contract now has access to all functions in UsingTellor
4
5
bytes btcPrice;
6
bytes32 btcQueryId = 0x0000000000000000000000000000000000000000000000000000000000000002;
7
8
constructor(address payable _tellorAddress) UsingTellor(_tellorAddress) public {}
9
10
function setBtcPrice() public {
11
bool _didGet;
12
uint _timestamp;
13
14
(_didGet, btcPrice, _timestamp) = getCurrentValue(btcQueryId);
15
}
16
}
Copied!
Line 6: The
btcQueryId is set to2 (in bytes32), the BTC/USD query IDTesting 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
function faucet(address user) external;
6
7
/**
8
* @dev A mock function for submitting a value without reporter staking needed
9
* @param _queryId the ID to associate the value to
10
* @param _value the requested oracle value
11
* @param _nonce the current value count for the query id
12
* @param _queryData the data used by reporters to fulfill the data query
13
*/
14
function submitValue(
15
bytes32 _queryId,
16
bytes calldata _value,
17
uint256 _nonce,
18
bytes memory _queryData
19
) external;
Copied!
Running tests
1
npx hardhat test
Copied!
Sample Project
Last modified 1mo ago