Whether you are a developer, tech enthusiast or enterprise, iExec offers one of the most complete and simple-to-use decentralized oracle solutions. This guide will show you how to start feeding Web 2.0 API data into your Ethereum smart contract in no time. For a general overview of what a decentralized oracle is and why it is needed, have a look at our previous article:

If earning some RLC while learning about decentralized oracles is something that interests you, check out our developer training reward program!

In the following guide, we are going to see how to fetch the price of any crypto pair (ex: ETH/USD) from an API on the internet and put it back into a smart contract on the Ethereum Blockchain. Such a mechanism is called a price feed oracle and is one of the many use cases enabled by iExec’s decentralized cloud.

All the terminal commands part of this tutorial were run on a macOS machine. If using Linux, you can use almost all the same commands. However, Windows users may need to adapt OS-specific commands and install apps such as Git Bash — but we can not provide full tech support. If you encounter any issues while following the tutorial, our developers we’ll be happy to help or receive feedback on Slack, Gitter, or Telegram.

0. Pre-Requirements

Install OS specific compiling libs

on MacOS

Ensure that you installed the Xcode Command Line Tool.

on Linux

sudo apt-get update

sudo apt-get install python

sudo apt-get install build-essential

on Windows 10

Unless you are a Windows power user or Windows addict, and installing Visual Studio to be able to compile c++ doesn’t sound terrifying for you, then you may consider using Windows Subsystem for Linux (to get a linux shell integrated in Windows) or you could just install Virtualbox and launch a Linux VM.

Install Docker

On MacOS

Go on Docker website, sign up and install Docker Desktop. Once successfully installed, log in Docker Desktop. Ensure that Docker Desktop is up by running in your terminal:

docker --version

On Linux

Go on this Docker documentation page explaining how to install Docker on Ubuntu (all Linux flavors are supported). Ensure Docker is installed by running:

docker --version

Create a repository on DockerHub

Head over dockerhub, create a repository and name it price-feed.

Install NodeJS

The cleanest way to install node on Linux & MacOS is by using theNVM installer. Run the below command to install NodeJS on your system:



command -v nvm #should output 'nvm' if installation worked

nvm install node 10.12 # this will install latest stable node version

nvm use node #make nvm installed node the system's default node curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.34.0/install.sh | bash #works for MacOS & Linuxcommand -v nvm #should output 'nvm' if installation workednvm install node 10.12 # this will install latest stable node versionnvm use node #make nvm installed node the system's default node

Ensure that NodeJS is up by running in your terminal.

node --version

On Windows, download the NodeJS Windows installer from their official website.

Instal the iExec SDK

The iExec SDK is a node module. To install it, just run:

npm -g install iexec

Ensure that iExec SDK is correctly installed by running:

iexec --version

That’s it for the prerequisites, that’s a one shot install. Next part is about setting up your DOracle project (like create and fill your Ethereum wallet).

1. Initialize the project

Now let’s initialize our new price-feed oracle project:

mkdir price-feed #new folder

cd price-feed #enter the folder

iexec init #init iexec project. If you already have an iExec wallet, run iexec init --skip-wallet to keep using your current wallet

The last command will create an Ethereum wallet.

Important: choose a password and save it (you will need it after).

Great! Now you have an Ethereum wallet.

It is saved encrypted as a .json file in your machine user folder. Ex: on Linux : ~/.ethereum/keystore, on Mac: ~/Library/Ethereum/keystore, on Windows: ~/AppData/Roaming/Ethereum/keystore).

Now let’s get some ETH to interact with the Ethereum Blockchain, and some RLC to interact with the iExec’s platform.

Reminder: All commands in this tutorial that interact with the Blockchain will use the Kovan testnet blockchain. It works identically to Ethereum Mainnet, but doesn’t require real money to get started. Perfect for testing!

Let’s ask iExec for some free Kovan RLC:

iexec wallet getRLC --chain kovan

At this stage, you should see your Wallet displayed in your terminal with a credit of 200 nRLC.

Now to get some free Kovan ETH, you will need to post your Ethereum wallet address in this Gitter group chat. To know your wallet address, run:

iexec wallet show --chain kovan

Then go over the Kovan Faucet Gitter, sign in to Gitter and copy-paste your wallet address in the discussion.

Paste your wallet address on the chatbox to receive 3.0 Kovan ETH

Before going further, we need to ensure that our wallet received the ETH and the RLC we asked for. Run this command to check your wallet balance:

iexec wallet show --chain kovan

Your balance should show you 3.0 ETH and 200 nRLC. If not, wait for a minute.

Now let’s top up 200 RLC on our iExec account (so we can spend them in the platform) and move on to the next section:

iexec account deposit 200 --chain kovan

2. Deploy your off-chain application

In order to run the price-feed application on the iExec’s decentralized cloud, we need to go through the following steps:

Dockerize the “price-feed” application, Push it on the DockerHub public registry Deploy it on the iExec’s Platform

Ensure that your terminal is in the price-feed folder, and let’s create a new folder named app, containing the off-chain logic:

mkdir app

cd app # enter the folder

Then download the price-feed JS script that implements the price fetching logic (we encourage you to have a look at the JS code):

Now, let’s dockerize our JS application. The first step is to open your IDE (Developer environment), create a file named Dockerfile in the app folder, and paste below content in it:

Notice the entrypoint.sh file, it’s only used to “spread” the CLI arguments from a single string to multiple args, so it’s correctly interpreted by node. With a future iExec worker upgrade, we’ll be able to skip this unnecessary step ;)

Now we are ready to build the Docker image and publish it to dockerhub. In your terminal, run these commands:

docker build . # write down your image ID (it appears after the text "successfully built 19acce70289d" <-- that is the image ID)

You’ve built a docker image. Now we want to tag this image with our dockerhub username:

docker tag <IMAGE_ID> <YOUR_DOCKERHUB_NAME>/price-feed:1.0.0 # ex: docker tag 19acce70289d iexechub/price-feed

Finally, we can push our local image to the dockerhub public repository:

docker push <YOUR_DOCKERHUB_NAME>/price-feed #write down your image digest (it appears after sha256:959eb75b13efb41a8f37495784150574d66175adebd0c6c18216b482c574d109 <-- this is your image digest)

Now we are just a few steps from having our application being “iExec’s ready”:

cd .. #move to upper folder

iexec app init # tell the SDK that you want to create an app

Then, open the newly created “iexec.json” file, and edit these three fields:

name: We name it “PriceFeed”.

We name it “PriceFeed”. multiaddr: replace by dockerhub repository name. “registry.hub.docker.com/<YOUR_DOCKERHUB_NAME>/price-feed:1.0.0”.

replace by dockerhub repository name. “registry.hub.docker.com/<YOUR_DOCKERHUB_NAME>/price-feed:1.0.0”. checksum: given by the command docker push. (warning: add 0x before the sha256:)

Now let’s deploy your price-feed application on iExec, in the terminal:

iexec app deploy --chain kovan # that is a blockchain transaction

Congrats! Your Price-Feed App is now deployed on the iExec platform.

Finally, let’s publish sell orders for your application, so iExec platform users are able to use your application at the price you write on the orders:

iexec order init --app

iexec order sign --app

iexec order publish --app # publish your apporder on the marketplace and get an orderHash

iexec order show --app [orderHash]

3. Deploy your on-chain DOracle Smart Contract

Let’s clone the repo on your terminal, enter the smart-contract folder, and install JS dependencies:



cd smart-contract

npm install git clone https://github.com/iExecBlockchainComputing/price-feed-doracle.git smart-contractcd smart-contractnpm install

In order to deploy the smart contract on the Blockchain, you need to tell Truffle your wallet private key. Here is how you can show your wallet’s private key:

cd .. # move to upper folder

iexec wallet show --show-private-key # copy your private key for next step

Now you are ready to deploy. Thanks to truffle, that’s as simple as this:

cd smart-contract # move back to the smart-contract folder

MNEMONIC=<YOUR_PRIVATE_KEY> ./node_modules/.bin/truffle migrate --network kovan # Deploy your smart contract to the Blockchain

2 smart-contracts deployed

Great, your DOracle smart contract is now deployed on Kovan testnet blockchain. How about feeding it with the ETH/USD price?

4. Update your DOracle (as a requester)

Now let’s buy a “price-feed” run on iExec by running these commands on your terminal:

cd .. # move back to parent folder price-feed

Let’s show the unique ID (order hash) of the orders we want to buy. One is the workerpool order, and the other one is our price feed app order:

iexec orderbook workerpool --category 0 --chain kovan # copy the workerpool order hash returned from this command

iexec orderbook app <app_eth_address> --chain kovan # copy the app order hash returned by this command

Now we want to fill the orders (workerpool + app), that’s as simple as running:

iexec order fill --app <APP_ORDER_HASH> --workerpool <WORKERPOOL_ORDER_HASH> --params "RLC BTC 9 2019-07-09T13:27:24.909Z" --chain kovan # start the DOracle computation!

That’s it! we sent to the iExec platform the computation request. To ensure we all talk the same language, you now have a deal, and in that deal, there is one task (that’s a way to enable the coming “bag of task” feature). Let’s track the progress of the computation by using these commands:

iexec deal show <DEAL_ID> --chain kovan

iexec task show <TASK_ID> --watch --chain kovan

You can also head over the iExec Explorer (https://explorer.iex.ec/kovan/task/<TASK_ID>) to track the task. After a few minutes, the status should turn to a green “completed”.

So what happened so far? We ask a workerpool to run our price-feed application, the workers fetched the ETH/USD price, the result is validated by the PoCo, and as soon as there is consensus, it is stored back into iExec’s smart contracts. Last step consists of calling the function named “_iexecDoracleGetVerifiedResult” on your DOracle smart contract, so it will check the result stored on the iExec’s smart contract, run some filtering logic (ex: is the new price associated with a UTC date more recent than the previous one I pulled), and if all your custom conditions are fulfilled, then it will update itself with the new ETH/USD price! Makes sense?

We will soon update the article with a truffle script to show this last step. If you can’t wait, just try by yourself! Also, we encourage you to try out our price-feed frontend to see what the end-user experience could look like: https://price-feed-doracle.iex.ec

That’s it! We hope you realized how easy it is to build a decentralized oracle on iExec.

If you liked it, then you definitely want to learn more about our dev training reward program that makes building DOracle on iExec fun & financially rewarding: