Introduction

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 convenient 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 parameters.
Test: Use the TellorPlayground contract
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 Oracle contract address(see references page for the address)
Available Tellor Functions
Children contracts have access to the following functions:
1
​
2
    /**
3
     * @dev A mock function to create a dispute
4
     * @param _queryId The tellorId to be disputed
5
     * @param _timestamp the timestamp of the value to be disputed
6
     */
7
    function beginDispute(bytes32 _queryId, uint256 _timestamp) external;
8
​
9
    /**
10
     * @dev Counts the number of values that have been submitted for a given ID
11
     * @param _queryId the ID to look up
12
     * @return uint256 count of the number of values received for the queryId
13
     */
14
    function getNewValueCountbyQueryId(bytes32 _queryId) public view returns (uint256);
15
​
16
    /**
17
     * @dev Gets the timestamp for the value based on their index
18
     * @param _queryId is the queryId to look up
19
     * @param _index is the value index to look up
20
     * @return uint256 timestamp
21
     */
22
    function getTimestampbyQueryIdandIndex(bytes32 _queryId, uint256 _index) public view returns (uint256);
23
​
24
    /**
25
     * @dev Retrieve bytes value from oracle based on queryId/timestamp
26
     * @param _queryId being retrieved
27
     * @param _timestamp to retrieve data/value from
28
     * @return bytes value for queryId/timestamp submitted
29
     */
30
    function retrieveData(bytes32 _queryId, uint256 _timestamp) public view returns (bytes memory);
31
​
32
    /**
33
     * @dev A mock function to submit a value to be read without miners needed
34
     * @param _queryId The tellorId to associate the value to
35
     * @param _value the value for the queryId
36
     * @param _nonce the current value count for the query id
37
     * @param _queryData the data used by reporters to fulfill the data query
38
     */
39
    function submitValue(bytes32 _queryId, bytes calldata _value, uint256 _nonce, bytes memory _queryData) external;
40
​
41
    /**
42
     * @dev Adds a tip to a given query ID.
43
     * @param _queryId is the queryId to look up
44
     * @param _amount is the amount of tips
45
     * @param _queryData is the extra bytes data needed to fulfill the request
46
     */
47
    function tipQuery(bytes32 _queryId, uint256 _amount, bytes memory _queryData) external;
Copied!
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 have access to all functions on UsingTellor
4
​
5
  uint256 btcPrice;
6
  uint256 btcQueryId = 2;
7
​
8
  constructor(address payable _tellorAddress) UsingTellor(_tellorAddress) public {}
9
​
10
  function setBtcPrice() public {
11
    bool _didGet;
12
    uint _timestamp;
13
    bytes _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
npx hardhat test
Copied!
Sample Project
We provide a repo with this setup installed and ready for use: SampleUsingTellor.
Whitepaper - Previous
Use Cases
Next - Integration
Data feed IDs
Last modified 19d ago
Copy link
Contents
Integrating Tellor Oracle Data in Ethereum Smart Contracts
Installation
Using in the contract in solidity:
Testing your contracts
Sample Project