The iExec Oracle Factory allows you to create oracles from scratch. If you’ve already deployed your first oracle — this article will show you how to integrate your newly created oracle into a Dapp (and maybe even earn RLC token rewards for doing so).

⚠️UPDATE ⚠️ - A revised tutorial has been published. It includes the Oracle Factory new functionalities. Here’s a link to it: Update your Cross-Chain Oracles & Integrate them in your iExec, Ethereum, or Polygon Dapps

The iExec Oracle Factory is a developer interface allowing anyone to create custom oracles from scratch, in minutes, without blockchain knowledge and directly from a web browser. If you missed the product announcement, introducing this iExec new product, read this article.

The iExec Oracle Factory provides a quick and simple way of getting data into a smart contract. With a few clicks and URL copy/paste, users can configure the source data of an oracle from any API available on the web (the key API is also required if the API is not public). One of the advantages of the iExec Oracle Factory is that any oracle can be created from any API. For Dapp developers needing oracles that need to make use of specific data, the ability to create custom oracles is a game changer!

In this article, we are going to describe how to integrate an oracle created with the iExec Oracle Factory into your Dapp. In other words, once you have created your oracle with the Oracle Factory, how to bring data from the Oracle Factory into solidity smart contract code.

🛠Learn how to create your oracle using the iExec Oracle Factory.

⏯ Watch the video tutorial

At a basic level, oracles work by receiving an update request, then pushing the value returned by the API to be stored in the generic oracle smart contract. This allows for any smart contract in the same network to retrieve that value and execute logic on it.

Once your oracle is created, the iExec Oracle Factory stores your oracle data on-chain in a smart contract called the genericOracle. You can inspect its source code here.

Prerequisite: Whitelisting your address for the iExec Sidechain

The iExec Oracle Factory is currently running on iExec’s sidechain. In order for you to integrate an Oracle Factory oracle, we’ll need the ETH address that you’ll be using to interact with the blockchain to ‘whitelist’ your address for this chain. To get your address whitelisted, please join the iExec Tech-support channel on Discord, and leave a message with a public ETH address, and we’ll whitelist it, and you’ll be all set!

The code:

As shown in the contract, the mapping ’values’ is where the data is stored:

mapping(bytes32 => TimedRawValue) public values;

In order to retrieve the stored data, you have to do a function call, depending on the type of sought value:

function getRaw(bytes32)public view virtual returns (bytes memory, uint256);
function getString(bytes32)public view virtual returns (string memory, uint256);
function getInt(bytes32) public view virtual returns (int256, uint256);
function getBool(bytes32) public view virtual returns (bool, uint256);

Once the call is done, you need to create a smart contract that holds the value of an oracle at a given time. For some context, you can check the Solidity documentation here.

The oracleId is the key to retrieving the data from the mapping values (the mapping is a representation of key-value data).

The oracleAddress is the address of the deployed generic oracle, we use it to call functions from the generic oracle.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.9;

abstract contract Oracle {
   function getRaw(bytes32)public view virtual returns (bytes memory, uint256);
   function getString(bytes32)public view virtual returns (string memory, uint256);
   function getInt(bytes32) public view virtual returns (int256, uint256);
   function getBool(bytes32) public view virtual returns (bool, uint256);
}

contract SimpleOracleStorage {
   int256  storedValue;
   uint256 storedDate;
   event valueChanged(int256 newValue, uint256 newDate);
   address oracleAddress = 0x36dA71ccAd7A67053f0a4d9D5f55b725C9A25A3E;

   function getOracleData(bytes32 _oracleId) public {
       Oracle oracleContract = Oracle(oracleAddress);
       (int256 value, uint256 date) = oracleContract.getInt(_oracleId);
       storedValue = value;
       storedDate = date;
       emit valueChanged(value, date);
   }

   function get() public view returns (int256, uint256) {
       return (storedValue, storedDate);
   }
}

The oracleAddress corresponds to the address pointing to the previously mentioned genericOracle contract.

The getter function getInt(oracleId) is in charge of retrieving the oracle’s value and its last updated date; these two values are then stored in the storedValue variable.

The contract Oracle that is declared at the top is not the actual genericOracle, but a variable that acts as an interface to call the real genericOracle deployed at the address: 0x36dA71ccAd7A67053f0a4d9D5f55b725C9A25A3E

The same address for Polygon (Mainnet & Testnet Mumbai), Ethereum (Mainnet & Testnet Goerli) and iExec Sidechain.

Et voilà, your oracle created with the iExec Oracle Factory is now integrated into your Dapp!

In order to follow best practices, the oracle contract (the interface) should be placed in a separate file and then imported into the contract, that way it can be reutilized in other contracts.

NB: To include your oracle created with the iExec Oracle Factory into your Dapp, the deployment address needs to be whitelisted by iExec. If you want to deploy a smart contract on the iExec sidechain Viviani, don’t hesitate to make a request to the team on our Discord tech support channel to have your deployment address whitelisted.

An example of oracle integration into the Dapp with ‘Flight Pronostics’

To illustrate how the oracle works with the Dapp, we have created ‘Flight Pronostics’, a PoC application (to be seen as demo, as xRLC is needed to engage with it as a user). Using this Dapp, users can speculate on whether a flight is going to take off as planned or whether it will be canceled and/or diverted.

Try out the application here: https://iexecblockchaincomputing.github.io/flight-pronostics-ui

Here is how this Dapp works:

       
• In the Dapp, the speculations are made by the users regarding flight departure.
       
• The ‘event’ happens, and the flight status is known in the real world.
       
• Before the flight status is sent to the generic oracle smart contract, we need to update the flight status oracle via the iExec oracle factory user interface:

       
• The flight pronostics dapp fetches the oracle data in the getOracleData() function, which simply calls the getString function of the deployed generic oracle smart contract:

function getOracleData(bytes32 _oracleId) public returns (string memory) {
    Oracle oracleContract = Oracle(oracleAddress);
    (string memory value, uint256 date) = oracleContract.getString(_oracleId);
    storedValue = value;
    storedDate = date;
    return value;
}

       
• When you click on the claim prize button, the stakes are distributed among the winning participants.

Example Smart Contracts

The smart contracts for the ‘Flight Pronostics’ Dapp can be consulted here.

Developer Onboarding — Whitelisting your address for the Viviani Sidechain

The iExec Oracle Factory is currently running on iExec’s ‘Viviani’ sidechain. In order for you to integrate an Oracle Factory oracle, we’ll need the ETH address that you’ll be using to interact with the blockchain to onboard and ‘whitelist’ your address for this chain. To get your address whitelisted, please join the iExec Tech-support channel on Discord.Leave a message with a public ETH address, and we’ll whitelist it, and you’ll be all set!

💰 Developer Rewards Build with the iExec Oracle Factory and Earn RLC Token rewards!

As part of the iExec Developer Rewards Program, iExec is offering RLC token rewards and support to anyone building with iExec. Got an idea for an application that uses an Oracle from the iExec Oracle Factory? The iExec team may be able to fund your idea. All you need to do is follow this documentation and deliver a usable frontend UI! To apply for funding, please detail your application idea here

Thanks for reading!

Twitter • Youtube • iExec Roadmap • Github • Telegram • Slack