Oracle Client Interfaces in Solidity

Using Oraclize to update the ETH/USD exchange rate from an external source is a Solidity example demonstrating how Oraclize can be used to continuously poll for the ETH/USD price from an API and store the result in a usable manner.

Example 1. Using Oraclize to update the ETH/USD exchange rate from an external source

  1. /*
  2.    ETH/USD price ticker leveraging CryptoCompare API
  4.    This contract keeps in storage an updated ETH/USD price,
  5.    which is updated every 10 minutes.
  6.  */
  8. pragma solidity ^0.4.1;
  9. import "github.com/oraclize/ethereum-api/oraclizeAPI.sol";
  11. /*
  12.    "oraclize_" prepended methods indicate inheritance from "usingOraclize"
  13.  */
  14. contract EthUsdPriceTicker is usingOraclize {
  16.     uint public ethUsd;
  18.     event newOraclizeQuery(string description);
  19.     event newCallbackResult(string result);
  21.     function EthUsdPriceTicker() payable {
  22.         // signals TLSN proof generation and storage on IPFS
  23.         oraclize_setProof(proofType_TLSNotary | proofStorage_IPFS);
  25.         // requests query
  26.         queryTicker();
  27.     }
  29.     function __callback(bytes32 _queryId, string _result, bytes _proof) public {
  30.         if (msg.sender != oraclize_cbAddress()) throw;
  31.         newCallbackResult(_result);
  33.         /*
  34.          * Parse the result string into an unsigned integer for on-chain use.
  35.          * Uses inherited "parseInt" helper from "usingOraclize", allowing for
  36.          * a string result such as "123.45" to be converted to uint 12345.
  37.          */
  38.         ethUsd = parseInt(_result, 2);
  40.         // called from callback since we're polling the price
  41.         queryTicker();
  42.     }
  44.     function queryTicker() external payable {
  45.         if (oraclize_getPrice("URL") > this.balance) {
  46.             newOraclizeQuery("Oraclize query was NOT sent, please add some ETH
  47.                 to cover for the query fee");
  48.         } else {
  49.             newOraclizeQuery("Oraclize query was sent, standing by for the
  50.                 answer...");
  52.             // query params are (delay in seconds, datasource type,
  53.             // datasource argument)
  54.             // specifies JSONPath, to fetch specific portion of JSON API result
  55.             oraclize_query(60 * 10, "URL",
  56.                 "json(https://min-api.cryptocompare.com/data/price?\
  57.                 fsym=ETH&tsyms=USD,EUR,GBP).USD");
  58.         }
  59.     }
  60. }

To integrate with Oraclize, the contract EthUsdPriceTicker must be a child of usingOraclize; the usingOraclize contract is defined in the oraclizeAPI file. The data request is made using the oraclize_query function, which is inherited from the usingOraclize contract. This is an overloaded function that expects at least two arguments:

  • The supported data source to use, such as URL, WolframAlpha, IPFS, or computation

  • The argument for the given data source, which may include the use of JSON or XML parsing helpers

The price query is performed in the queryTicker function. In order to perform the query, Oraclize requires the payment of a small fee in ether, covering the gas cost for processing the result and transmitting it to the __callback function and an accompanying surcharge for the service. This amount is dependent on the data source and, where specified, the type of authenticity proof that is required. Once the data has been retrieved, the __callback function is called by an Oraclize-controlled account permissioned to do the callback; it passes in the response value and a unique queryId argument, which, for example, can be used to handle and track multiple pending callbacks from Oraclize.

Financial data provider Thomson Reuters also provides an oracle service for Ethereum, called BlockOne IQ, allowing market and reference data to be requested by smart contracts running on private or permissioned networks. Contract calling the BlockOne IQ service for market data shows the interface for the oracle, and a client contract that will make the request.

Example 2. Contract calling the BlockOne IQ service for market data

  1. pragma solidity ^0.4.11;
  3. contract Oracle {
  4.     uint256 public divisor;
  5.     function initRequest(
  6.        uint256 queryType, function(uint256) external onSuccess,
  7.        function(uint256
  8.     ) external onFailure) public returns (uint256 id);
  9.     function addArgumentToRequestUint(uint256 id, bytes32 name, uint256 arg) public;
  10.     function addArgumentToRequestString(uint256 id, bytes32 name, bytes32 arg)
  11.         public;
  12.     function executeRequest(uint256 id) public;
  13.     function getResponseUint(uint256 id, bytes32 name) public constant
  14.         returns(uint256);
  15.     function getResponseString(uint256 id, bytes32 name) public constant
  16.         returns(bytes32);
  17.     function getResponseError(uint256 id) public constant returns(bytes32);
  18.     function deleteResponse(uint256 id) public constant;
  19. }
  21. contract OracleB1IQClient {
  23.     Oracle private oracle;
  24.     event LogError(bytes32 description);
  26.     function OracleB1IQClient(address addr) external payable {
  27.         oracle = Oracle(addr);
  28.         getIntraday("IBM", now);
  29.     }
  31.     function getIntraday(bytes32 ric, uint256 timestamp) public {
  32.         uint256 id = oracle.initRequest(0, this.handleSuccess, this.handleFailure);
  33.         oracle.addArgumentToRequestString(id, "symbol", ric);
  34.         oracle.addArgumentToRequestUint(id, "timestamp", timestamp);
  35.         oracle.executeRequest(id);
  36.     }
  38.     function handleSuccess(uint256 id) public {
  39.         assert(msg.sender == address(oracle));
  40.         bytes32 ric = oracle.getResponseString(id, "symbol");
  41.         uint256 open = oracle.getResponseUint(id, "open");
  42.         uint256 high = oracle.getResponseUint(id, "high");
  43.         uint256 low = oracle.getResponseUint(id, "low");
  44.         uint256 close = oracle.getResponseUint(id, "close");
  45.         uint256 bid = oracle.getResponseUint(id, "bid");
  46.         uint256 ask = oracle.getResponseUint(id, "ask");
  47.         uint256 timestamp = oracle.getResponseUint(id, "timestamp");
  48.         oracle.deleteResponse(id);
  49.         // Do something with the price data
  50.     }
  52.     function handleFailure(uint256 id) public {
  53.         assert(msg.sender == address(oracle));
  54.         bytes32 error = oracle.getResponseError(id);
  55.         oracle.deleteResponse(id);
  56.         emit LogError(error);
  57.     }
  59. }

The data request is initiated using the initRequest function, which allows the query type (in this example, a request for an intraday price) to be specified, in addition to two callback functions. This returns a uint256 identifier that can then be used to provide additional arguments. The addArgumentToRequestString function is used to specify the Reuters Instrument Code (RIC), here for IBM stock, and addArgumentToRequestUint allows the timestamp to be specified. Now, passing in an alias for block.timestamp will retrieve the current price for IBM. The request is then executed by the executeRequest function. Once the request has been processed, the oracle contract will call the onSuccess callback function with the query identifier, allowing the resulting data to be retrieved; in the event of retrieval failure, the onFailure callback will return an error code instead. The available fields that can be retrieved on success include open, high, low, close (OHLC), and bid/ask prices.