Oracles in Ethereum - A Simple Guide

Posted on November 6, 2017

Motivation: I’ve been trying to find a tutorial on building an Oracle in Ethereum, only problem is that the articles online are either out of date (pre web3 v1.0.x) or the source code provided is structured in such a way that makes it incredibly tough to follow (having python, c# and javascript in one project with no clear description of what each language is doing and why its necessary). This guide assumes you have a basic understanding of the solidity language

Goal: By the end of this guide, I hope to have helped you build and deploy your Oracle onto your own private testnet

>>> Click here for the boilerplate project <<<

What are Oracles?

An Oracle is, simply put, a “smart contract” that is able to interact with the outside world, in the world of Ethereum that is known as off-chain. I put smart contracts in quotations because some people argue that Oracles aren’t exactly a real smart contract.

Example: Say you’re writing a smart contract that needs to retrieve weather data, however your contract can’t make arbitrary network requests on-chain. You need something that trustable (all user input aren’t) and is able to listen and respond to specific events on the blockchain. The solution: Oracles.

Building your Oracle

This guide will be building a simple Oracle that retrieves bitcoin’s total market cap from coinmarketcap and store it into the blockchain.

Setting up your environment and tools

I’ll be using the truffle framework and testrpc for this guide. You can install them by running:

I’m using truffle because is has some really nice abstractions that allows me to interact with web3 (almost) hassle free. Once you’ve installed truffle you can initialize a boilerplate by typing:

You should see the following files in your folder:

truffle boilerplate

Edit truffle.js (your truffle configuration file) to:

This points truffle to our local private chain (testrpc).

Create four new files: ./contracts/CMCOracle.sol, ./migrations/2_deploy_migrations.js, ./client.js, and ./oracle.js. Your project folder should now look like:

project structure

Building and deploying our Oracle to testrpc

Edit the file ./contracts/CMCOracle.sol so it looks like:

And the file ./migrations/2_deploy_contracts.js to:

Run testrpc in a separate terminal, and then truffle compile && truffle migrate. This compiles our contracts and deploys them onto our private testnet.

Oracle and Client logic

Edit ./oracle.js so it looks like:

And ./client.js so it looks like:

You’ll notice that there’s some code duplication between the two (particularly in getting the web3 instance), I chose not to abstract that common functionality because I intent to keep this guide as barebones as possible.

Testing our Oracle

Finally, run node oracle.js in the background, and run node client.js twice in another terminal. If you receive something similar to the following:

Then congratulations! You’ve successfully setup your own Oracle!

As you can see in our intiial request the market cap for bitcoin was 0 (default for uint in solidity). As we ran client.js we requested that the market cap be updated via the line oracleInstance.updateBTCCap({from: accounts[0]}). This triggers the event CallbackGetBTCCap which is handled by oracle.js, which fetches the bitcoin marketcap and updates the data in the smart contract.

Final thoughts

Oracles are a necessity for smart contracts to interact with the outside world, as they act as the bridge between the on-chain and off-chain world. I hope having a barebones example will help any newcomers trying to find a way in this rapidly changing field.