Tellor Docs
Search…
Integration
Token Holders
Security
Tellor Playground
This page is designed to give you a quick overview of using Tellor to get data into your smart contracts.
TL:DR
Tellor Playground aims to help anyone building on Tellor to quickly test and implement ideas. See the reference page for deployed addresses on various test networks.
Why use Tellor Playground
The TellorX repository is a large project that holds all the on-chain logic of the system, but a lot of the code there is aimed at dealing with stakers, reporters, and disputes, among other stuff, which most projects that want to request and read tellor values don't really need to worry about.
The Playground is a simplified (and not a real oracle) Tellor, containing only the small bits that third party developers integrating need to worry about: getting data, adding tips, reading events and so forth.
Why not use the real Tellor
There are a few reasons not to use even the testnet version of the real system, the first one being that it is identical to the mainnet version, where there are only 50 datapoints available for reading. You can easily get the value of USD or BTC, but if your project needs to read a value from an exotic token, it might not be available.
To include a value in the Rinkeby version, it would first need to be added to the reporter software client. Or a developer could report the value themselves, but they would have to acquire 100 Rinkeby test TRB, stake it, and then they would only be able to submit a value once every 12 hours. If you're testing an idea or building a hackathon project, it might be overkill to go through all of that and it's far easier to make use of Tellor Playground.
How to use
Reading values
If your smart contract needs to read Tellor values, you might want to use the helper usingtellor, which already provides a few helpful functions to fetch data.
The first step is to install usingtellor, then inherit the UsingTellor contract, passing the TellorPlayground address as a constructor argument. Here's an example:
1
npm install usingtellor
Copied!
1
import "usingtellor/contracts/UsingTellor.sol";
2
3
contract BtcPriceContract is UsingTellor {
4
//This contract now has access to all functions in UsingTellor
5
6
bytes public btcPrice;
7
bytes32 public btcQueryId = 0x0000000000000000000000000000000000000000000000000000000000000002;
8
9
constructor(address payable _tellorAddress) UsingTellor(_tellorAddress) public {}
10
11
function setBtcPrice() external {
12
// TIP: For best practices, use getDataBefore with a time buffer to allow time for a value to be disputed
13
(bool _ifRetrieve, bytes memory _value, uint256 _timestampRetrieved) = getDataBefore(btcQueryId, block.timestamp - 2 hours);
14
if(_ifRetrieve) {
15
btcPrice = _value;
16
}
17
}
18
}
Copied!
Setting values in the Playground
To be able to properly read a value from playground, you'll need to first set the value yourself, since it does not rely on reporters.
To do that, you can choose some arbitrary
queryData, which is a bytes value, and then take the keccak256 hash of the queryData to get the queryId. Then call submitValue with any value you wish, which will add a data point to the Playground. Your contract can now easily read Tellor values.Available Functions
Here are all the functions available in Tellor Playground:
1
/**
2
* @dev A mock function to submit a value to be read without miners needed
3
* @param _queryId The tellorId to associate the value to
4
* @param _value the value for the queryId
5
* @param _nonce the current value count for the query id
6
* @param _queryData the data used by reporters to fulfill the data query
7
*/
8
function submitValue(bytes32 _queryId, bytes calldata _value, uint256 _nonce, bytes memory _queryData) external;
9
10
/**
11
* @dev A mock function to create a dispute
12
* @param _queryId The tellorId to be disputed
13
* @param _timestamp the timestamp of the value to be disputed
14
*/
15
function beginDispute(bytes32 _queryId, uint256 _timestamp) external;
16
17
/**
18
* @dev Retrieve bytes value from oracle based on queryId/timestamp
19
* @param _queryId being retrieved
20
* @param _timestamp to retrieve data/value from
21
* @return bytes value for queryId/timestamp submitted
22
*/
23
function retrieveData(bytes32 _queryId, uint256 _timestamp) public view returns (bytes memory);
24
25
/**
26
* @dev Counts the number of values that have been submitted for a given ID
27
* @param _queryId the ID to look up
28
* @return uint256 count of the number of values received for the queryId
29
*/
30
function getNewValueCountbyQueryId(bytes32 _queryId) public view returns (uint256);
31
32
/**
33
* @dev Gets the timestamp for the value based on their index
34
* @param _queryId is the queryId to look up
35
* @param _index is the value index to look up
36
* @return uint256 timestamp
37
*/
38
function getTimestampbyQueryIdandIndex(bytes32 _queryId, uint256 _index) public view returns (uint256);
39
40
/**
41
* @dev Adds a tip to a given query ID.
42
* @param _queryId is the queryId to look up
43
* @param _amount is the amount of tips
44
* @param _queryData is the extra bytes data needed to fulfill the request
45
*/
46
function tipQuery(bytes32 _queryId, uint256 _amount, bytes memory _queryData) external;
Copied!
Tellor Playground is also an ERC20 token, and if you want to add tips to your request, you might need to get some test tokens. For that there's an available function:
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;
Copied!
Last modified 1mo ago
Copy link