Solidity Integration

Connecting to the Oracle

To use Tellor data, you can use the UsingTellor helper contract. After connecting it to the oracle, you can read a value using your queryId. This guide uses the BTC/USD SpotPrice as an example query.

Example: Sample project using Tellor

Video: Integration Tutorial

Installation

To install usingtellor, run one the following commands:

Hardhat:

npm install usingtellor

Foundry:

forge install tellor-io/usingtellor

Importing

To import the UsingTellor contract into your Solidity file, pass the desired Tellor address (see the references page for the address) as a parameter:

pragma solidity >=0.8.0;

import "usingtellor/contracts/UsingTellor.sol";

contract MyContract is UsingTellor {

  constructor(address payable _tellorAddress) UsingTellor(_tellorAddress) {

  }

  // ...

}

Note: In the constructor on line 7, you need to specify the Tellor contract address. For testing, you can use a Tellor Playground address. In production, use the Oracle address on your chosen network.

Reading data

You can either use our QueryId builder to create a queryId and hardcode it, or use solidity to generate it. Once you have created a queryId, you can add the Tellor data feed to your contract code.

The best practice for reading Tellor data is to use the_getDataBefore function with a buffer time that allows time for bad values to be disputed:

_getDataBefore(_queryId,block.timestamp - 20 minutes);

It's also best practice to require/check that the data is not too old. For example:

require(block.timestamp -`` _timestampRetrieved < 24 hours);

In the example below, we add a function getBtcSpotPrice that reads the BTC/USD price feed from the Oracle:

// SPDX-License-Identifier: MIT
pragma solidity 0.8.3;

import "usingtellor/contracts/UsingTellor.sol";

contract ExampleContract is UsingTellor {

    ...

    function getBtcSpotPrice() external view returns(uint256) {
    
      bytes memory _queryData = abi.encode("SpotPrice", abi.encode("btc", "usd"));
      bytes32 _queryId = keccak256(_queryData);
      
      (bytes memory _value, uint256 _timestampRetrieved) =
          _getDataBefore(_queryId, block.timestamp - 20 minutes);
      if (_timestampRetrieved == 0) return 0;
      require(block.timestamp - _timestampRetrieved < 24 hours);
      return abi.decode(_value, (uint256));
    }

Next up! Please be sure to review the User Checklists which guide you through the necessary preparations & processes for using the Tellor oracle