Oracles: bringing data to the blockchain

In the context of blockchains, an oracle is an agent that finds and verifies real-world occurrences and submits this information to the blockchain to be used by smart contracts. The data could be the price of a currency, the weather at a given location, the result of a sport event or an election.

There are different types of oracles that can be implemented and used depending on your needs:

  • Software oracles handle information available online on the internet. An example could be the temperature, prices of commodities and goods, flight or train delays, etc. The data originates from online sources, like APIs, websites… The software oracle extracts the needed information and pushes it into the smart contract. We wrote about the Oraclize service that does this for you.
  • Hardware Oracles, some smart contracts need information directly from the physical world, for example, a product is scanned using a barcode reader and the information is sent to the smart contract. Another use case is RFID sensors in the supply chain industry that could help the blockchain tracks the supply.

The oracle could just provide the result of an action happening in the real world or could be here to resolve a dispute as an expert in a contract where parties are don’t agree on something.

The oracles can either bring data inside the blockchain or inform an actor outside of the blockchain about an event:

  • Inbound Oracles These provide the smart contract with data from the external world. Example use case will be an automatic buy order if the USD hits a certain price.
  • Outbound Oracles These provide smart contracts with the ability to send data to the outside world. An example would be a smart lock in the physical world which receives a payment on its blockchain address and will unlock automatically.


To implement a simple Oracle pattern we could write a simple smart contract for a flight delay insurance. In this smart contract, they will be three actors: The insurer, the client and an thrusted oracle that will tell if the flight was late or not and transfer all the bounty to the insurer or the client depending on the result.

Our smart contract will work in 3 steps:

  • The insurer create the contract and lock 10 time the price of the cost of the insurance in the smart contract.
  • The client pay the price of the insurance and the money of the client and the insurer are locked.
  • The oracle tells if the flight was delayed or not. If the flight was late the client receive his deposit and the money from the insurer, if the flight was on time the insurer get refunded his guarantee and get the fee paid by the client.

There is lot of room for improvement in our basic contract, for example we could also imagine that the oracle get a fee for rewarding his service.

Here is the basic implementation of our contract:



Getting data from the internet with Oraclize

Smart contracts can interact with data living in the blockchain but it is impossible to get informations from the web. Using Oraclize, we’ll see how your smart contracts can get data from outside the blockchain and execute any API call. Some use cases can be:

  • As seen in our article about the lottery, it’s hard to generating completely random data on the blockchain can be a problem, you could use Oraclize to get a random number from outside the blockchain.
  • In crowd sales, it could be interesting to know the current $ price of Ethereum or other tokens.
  • In a betting case, it could be interesting to get the result of a sport event from an external website.

First of all, you need to understand that reading data from the internet and manipulating money depending on the result requires to thrust an external source. Always keep in mind that you should have a way to pause and retrieve the funds in the smart contract in case of problems or change to the API you are reading from.

To try and test how Oraclize works, we’ll use the Remix interface they provide here. This interface let’s you discover some samples and test your own code for free on a simulated blockchain. The service is not free and require you to send funds to make queries, the costs inside described on their documentation.

The service works in 3 steps:

  1. You send a query to the Oraclize smart contract.
  2. Oraclize receive your query and make the corresponding request.
  3. Once they receive the data, they call a callback function of your smart contract where you’ll be able to access the requested data.


For this example we will write a simple smart contract that will fetch the current price of Ethereum in US dollars from the public API.

First of all, you need inherit form the usingOraclize  contract. If you don’t know about inheritance you should read our article. To import it’s source you can read and copy the content of the file on Github. Or import it directly from the repository putting the import at the beginning of your code file:

Once you imported the Oraclize API smart contract, you need to inherit from the usingOraclize .

This contract won’t do much, we now need to add the code to retrieve the price. using Oraclize is done in two step. The first is to inform the Oraclize about what we want by calling the oraclize_query  function. Once called with the parameters describing our query, the Oraclize smart contract will transfer the result to us by calling a function named __callback  we need to implement in our code.

We’ll first write our update function that will tell Oraclize about what we want. In our case:

You can note our update function has the payable  modifier as we should accept Ethereum to be sent as the oraclize_query  function require to send funds to the contract. Also note that first query made by a contract is free, so you can include call the update  function from your smart contract constructor without sending funds.

The query is specifying to retrieve a JSON content and directly retrieve one property of the object: the USD price.

The oraclize_query  accept two string parameters, the first string define the type of request and today we’ll use an URL  but you can also query the result of a WolframAlpha  formula or a IPFS  multi hash. It is also possible to add a third parameter in order to make the query delayed.

We now have to write our callback to receive the price:

The callback must be named __callback , the first parameter is the id of the request that can be saved when you make the request so you could handle different requests in the same callback. The second parameter is the result of your request. We use the parseInt  function that is inherited from the API file.

Here is our final smart contract:

From the Remix interface you first need to press the Compile  button to compile the contract to bytecode:

Then hit Create  button to publish your smart contract to the blockchain:


Once the contract is published, you will see the Log event appear:

If you click on the getPrice  button, you’ll see the price value appear in cents:


SafeMath to protect from overflows

Considering security is a big part of writing good Ethereum smart contracts. A common problem when dealing with numeric operations is the risk of overflow. In this article we will introduce to the SafeMath library available in the open zeppelin smart contracts collection.

What is an overflow?

An overflow/underflow happens when an arithmetic operation reach the maximum or minimum size of the type. For example if you store your number in the uint256  type, it means your number will be stored in a 256 bits unsigned number ranging from 0 to 2^256. In computer programming, an integer overflow occurs when an arithmetic operation attempts to create a numeric value that is outside of the range that can be represented with a given number of bits – either larger than the maximum or lower than the minimum representable value.

The most common result of an overflow is that the least significant representable bits of the result are stored; the result is said to wrap around the maximum (i.e. modulo power of two).

An overflow condition gives incorrect results and, particularly if the possibility has not been anticipated, can compromise a program’s reliability and security.


Let’s protect!

This could happen whenever you are doing arithmetic operations such as + , - ,  * . When using the SafeMath library, the results of this operations will be checked and an error will be thrown stopping the execution of your smart contract.

Here is the code:

To use a Solidity library, just type inside of your contrat and you can then call the public functions defined by your library:

For example this little smart contracts that does nothing but just storing safely the result of an addition:

Don’t hesitate to use the SafeMath library to protect from inputs that could make your contract do unexpected things after overflow or underflow leading arithmetic operations.




Testing your Solidity smart contracts

A good practice in the software industry is writing tests for code. The tests needs to cover the features of your code and assert that everything is working as predicted. As we are writing smart contracts that can deal with money, writing tests is a really important task for us. The Embark Framework offers a pretty rich environment for testing our smart contracts.

We will write our tests in Javascript using the Mocha. To install it just type npm install -g mocha  in your terminal.

Let’s start writing test for our MDBService  contract that we deployed in our previous tutorial. We want to test the functionalities of our contract:

  • It’s empty when initialized
  • When a user registers, it creates a contract
  • We can retrieve a contract made by a user
  • A user can’t register more than one time

We will create a new file in the test directory  test/MDBService_spec.js .  We will import the libraries and tools we need to test our code:

Following the Mocha syntax we will describe our tests and deploy all of the contracts in our project:

Our first test will check if when the MDBService , it is really empty:

Then we will check if an account is really created after we call the register function:

Then we test if the contract has a correct address and our method to access the contracts works:

And finally we’ll unsure one user can’t create multiple accounts:

Even if smart contracts code are by nature pretty short, writing tests is really important to help you identify errors while building an application. It is also important as in smart contracts development, we often re use existing contracts code and it is important to know that your bricks are sane and safe.

To run your tests using Embark Framework, in a terminal type:

With our current test we should see this:

Here is our complete test file:


Deploying our first contracts with Embark Framework

Since we installed Embark Framework and made a quick tour of it, we’ll now use it to create our first DApp: Decentralized Application. Our DApp will have two parts:

  • Smart contract – It will live on the blockchain  and handle the logic of our application. Coded with Solidity.
  • User interface – Will let normal users interact with the contract and is built with standard web technologies: HTML, CSS, Javascript.

Our DApp will be a decentralized micro blogging platform  (read Twitter clone). The functionalities will be:

  • A user can register
  • A user can post a message
  • List all the accounts
  • List all the messages of a user

Our application will be called MDB which stands for Micro Decentralized Blog. For this we will write two smart contracts, the first one is the actual application that will store all the accounts and let the user register: MDBService. The second part will be the user account containing all the tweets of the user: MDBAccount. When a user register using the application contract, it will actually create an account and store it’s address similar to what we did in our article about factories.

In this tutorial we will only write the smart contract part, we’ll cover the user interface and other topics such as writing tests in next tutorials.

First, we will use Embark Framework to create our code base. In your favorite terminal type:

Embark created the folders for our application, you can load the folder in your favorite IDE and we’ll create our first Smart contract: the user account. We will call it MDBAccount.sol and place it in the folder app/contracts .


We will use the struct  keyword to define a new type, a Post. A Post will store the message that was posted and the timestamp the user posted the message.

If you already followed the basic tutorials, the code is pretty straightforward:

We will try and deploy this first contract. In a terminal we will start our testing blockchain:

embark simulator

and then in an other terminal window:

embark run

We can see our contract was deployed.

So let’s try to see if our contract works, we’ll access the contract from the console using:  MDBAccount.getNumberPosts().toNumber()  and  MDBAccount.getOwnerAddress .

As you can see, we have a serious problem, the owner address is set as 0x00 which is definitely not ours. So due to the modifier we won’t be able to interact with our contract. We need to tell Embark to supply our address as the first argument of the constructor.

For this, we’ll go in the config/contracts.json  file and past the address of our contract. To know it, just type: web3.eth.accounts[0]  in the Embark console. Mine is: 0x4d89d68b3325e620339fbd3c5ad7c4a8c22cd7dd . So let’s add it on the contracts configuration file:

If you save the file, you’ll see that the Embark console will deploy the contract again automatically, we can now play with our contract:


You can try yourself using the following calls:

  • MDBAccount.getNumberPosts().toNumber()
  •"Hello World")
  • MDBAccount.getPost(0)[0]  //Getting the message of the post
  • MDBAccount.getPost(0)[1].toNumber()  //Getting the timestamp

It was nice to play around with our simple contract, we will now make the MDBService  in a new app/contracts/MDBService.sol  file which will be in charge of managing the accounts.  As our MDBService contract will use the MDBAccount contract we need to import it. The import keyword just copy the content of a file.

The whole code for registering our new accounts and retrieving them:

As the accounts contract will be created by our MDBService contract, we need to specify to Embark that we don’t want it to be deployed in the file config/contracts.json .

Now your contract should appear as not deployed in the list:

We can quickly test our contract by calling register and get the address of our account with the console.

This is everything for the smart contract part of our brand new DApp. We voluntary didn’t test much interacting with the service and sending data to our post through it because in the next tutorial we will cover good practice for testing your smart contracts with Embark Framework.


Getting started with Embark Framework

In the previous articles we saw all the basics of Ethereum smart contracts development with Solidity. We used Ethereum Wallet and it was great! We were able to have a simple and easy to setup small dev environment. As you figured out it was nice for getting started but what if we want to go deeper? We want to write bigger applications, be able to use multiple source files. Write tests, debug, use a versioning system, deploy multiple contracts at once ect…

To go deeper we’ll use the Embark Framework. Embark Framework is easy to get started with and has a lot of features:

Blockchain (Ethereum)

  • Automatically deploy contracts and make them available in your JS code. Embark watches for changes, and if you update a contract, Embark will automatically redeploy the contracts (if needed) and the dapp.
  • Contracts are available in JS with Promises.
  • Do Test Driven Development with Contracts using Javascript.
  • Keep track of deployed contracts; deploy only when truly needed.
  • Manage different chains (e.g testnet, private net, livenet)
  • Easily manage complex systems of interdependent contracts.

Decentralized Storage (IPFS)

  • Easily Store & Retrieve Data on the DApp through EmbarkJS. Including uploading and retrieving files.
  • Deploy the full application to IPFS or Swarm.

Decentralized Communication (Whisper, Orbit)

  • Easily send/receive messages through channels in P2P through Whisper or Orbit.

Web Technologies

  • Integrate with any web technology including React, Foundation, etc..
  • Use any build pipeline or tool you wish, including grunt, gulp and webpack.


Installing Embark framework

You can get started on any platform, here are the tools you need:

Once you got this installed, we’ll use NPM to install the embark framework.

Embark framework Hello World

The Embark framework contains a basic demo we can deploy to understand how it works.  To deploy it type in your terminal the following command, it will create a new folder called embark_demo  containing the source code of the demo.

To lunch the demo we’ll need to lunch the simulator. The simulator has two advantages, it will create a blockchain on your computer so your computer will be able to mine when needed to deploy contracts and do other transactions and you don’t have to download all the Ethereum blockchain which will save you space!

Let it run on a terminal window and in a new terminal window you’ll start the Embark demo application with:

On your terminal, the embark dashboard will take life, it should look like this:

Here are the elements:

  1. The list of your deployed contracts and there addresses, in the Embark demonstration sample, there is only one contract: Simple Storage  that have a simple mission: storing one value and make this value readable from outside.
  2. The services that are currently running. We’ll explain the server running on port 8000 in a minute.
  3. The logs of what happened
  4. A console that let’s you interact with your contracts.

So let’s first check the code of the contract that lives in the app/contracts  folder of the demo:

In the app folder, you will also notice the css , images  and js  folders. They contains the sources for building web applications that will interact with the blockchain. Let’s now check what the Embark demo web app does. You’ll need to visit  http://localhost:8000/ with your favorite browser.

Note that if you have some apps already using the port 8000, you can change the port used by Embark in the folder config/webserver.json .

So you can see we have a simple interface to interact with our contract, we can set the value stored in the contract, get it and see  the calls that were made to interact with it.

The contract calls that were made can also be used in the console we saw in the Embark dashboard.

This was our walk around the Embark framework, in the next lessons we’ll create our own application using the Embark framework.

In the next tutorial we will start developing our first application with Embark Framework and deploy our first contracts.


Security and smart contracts

As you may know, the Ethereum and more widely blockchain community suffered from a lot of hacks. These major hacks involved million of dollars stolen by exploiting security vulnerability in smart contracts developed by companies. Even the most talented programmers can easily make a mistake with code and when something involves money: a lot of people are here to exploit any vulnerabilities.

Here are two smart contract hacking that happened:


Always remember that it happens and you should always think about security when writing smart contracts or any code that involves manipulating money, or sensitive data.

Here are few advices:

  • Always check the input data.
  • Keep your contracts as simple and small as possible.
  • Keep control and always have a simple and secure way to stop your contract and recover it’s holdings.
  • Use as much as possible modules to keep codebase tiny and built around simple modules as we covered with our inheritance tutorial.
  • Be extremely careful about external contract calls, which may execute malicious code and change control flow.
  • Understand that your public functions are public, and may be called maliciously. Your private data is also viewable by anyone.

They are many possible flows in a smart contract such as integers overflow and underflow. Always keep up to date and learn about how your code could be exploited.

Please go and read the smart contracts best practices guide on Github. Also, always stay updated by reading news and following suggested peoples on Twitter.


Inheritance in Solidity

We already explored a lot of subjects and while writing our contracts we found out that we were often using the same patterns: for example the fact that a contract has a owner which is set in the constructor and then make a modifier to only let the owner use some functions. What if we make a base contract that implement those functionality and reuse it in our future contracts? You guess it, we’ll use inheritance.

In Solidity, inheritance is pretty similar to classic oriented object programming languages. You’ll first write your base contract and tell that your new contract will inherit from the base one.

You also have to know that Solidity supports multiple inheritance by copying code including polymorphism. All function calls are virtual, which means that the most derived function is called, except when the contract name is explicitly given. When a contract inherits from multiple contracts, only a single contract is created on the blockchain, and the code from all the base contracts is copied into the created contract.

Let’s write our base contract: it will let us add easily ownership to our contracts. We’ll name it Ownable . The people at at OpenZeppelin wrote a lot of reusable code you can use in your smart contracts. The snippets are available through their tool or their Github repository.

Here is the code:

Another pattern we often write is the ability to destroy our contract and transfer the funds that were stored in the contract to the owner or to another address. What is important is that we don’t want to anyone to be able to destroy our contract, so our Destructible should inherit from Ownable . The inheritance is done with the is  keyword after the name of your smart contract.

You have to note that is Solidity, by default functions or are accessible from derived class. As in other programing language you can specify what should be accessible from the outside or from the derived contract. Functions can be specified as being external , public , internal  or private , where the default is public .

  • external : External functions are part of the contract interface, which means they can be called from other contracts and via transactions. An external  function f cannot be called internally (i.e. f() does not work, but this.f() works). External functions are sometimes more efficient when they receive large arrays of data.
  • public : Public functions are part of the contract interface and can be either called internally or via messages. For public state variables, an automatic getter function (see below) is generated.
  • internal : Those functions and state variables can only be accessed internally (i.e. from within the current contract or contracts deriving from it), without using this.
  • private : Private functions and state variables are only visible for the contract they are defined in and not in derived contracts.

Here is our second contract.

Now using those two base contracts, we’ll write a simple BankAccount contract where people can send money and the owner can withdraw it.

Note that we need to inherit from both contracts. The order of inheritance is important.  A simple rule to know the order is to specify the base classes in the order from “most base-like” to “most derived”.

 Here is the whole code we’ll deploy:

We can now deploy our bank account contract.

After being deployed we can see that we see our bank account functions but also the inherited one.

Manage several contracts with factories

We wrote a small contract for counting as a Hello World. What if we could create a contract that lets users create their own counters?

Let’s create our contract CounterFactory  that will manage all the other Counters . It will contain a mapping that will associate an owner to the address of his counter contract.

When a user want to use our counter system to have his own cool counter he will need request the creation of his counter.

Note that we pass to the constructor the address of it’s owner so we’ll transfer the ownership of the caller. In the constructor of the new contract, the msg.sender  will refer to the address of our contract factory. This is a really important point to understand as using a contract to interact with other contracts is a common practice. You should therefore take care of who is the sender in complex cases.

Now the increment function, we’ll first check if the user already registered a contract and call the increment function from the contract.  As the mapping store the address of the contract, we need to cast the address to the Counter contract type. Storing the address of the contract and not a direct reference to a contract permit us to check if the contract was initialized or not by checking it with a null address: 0 or 0x0..

Finally to read the value of the counter we’ll take the address of the user as parameter to fetch the value of the counter.

In this example, we keep it simple but you could imagine few scenarios, for example require to send Ether to the createCounter()  function so the initial creator of the contract could get some earning for his hard work. We could also had the ability to the original creator to delete a counter, or to associate a contract to a string or a number.

The Counter contract was slightly edited to fit the new address passed as parameter.

Here is the complete code:


Note that if called to many times, our counter could possibly victim of an overflow. You should use the SafeMath library as much as possible to protect from this possible case.

To deploy our contract, you will need to provide both the code of the CounterFactory  and the Counter . When deploying you’ll need to select CounterFactory .

After executing the createCounter()  function from one of your accounts and calling the increment()  function in the reading part of the contract interface you’ll need to put the address of your account to read the value of your counter. You can now have one counter per account.

In the next tutorial we’ll see how we can use inheritance to keep clean code and reuse existing and tested bricks.

Better readability with modifiers

Modifiers are functions you can apply to other functions. They are really useful to make sure some prerequisite are met before calling a function. Let’s take a simple example. In the contracts we already wrote we often have to check if the caller of a function if the owner of the contract:

Imagine if our contract have multiple functions that can only be called by the owner, wouldn’t be nice to refactor this if (owner == msg.sender)  part? This is where modifiers will help us. Let’s right our first modifier:

Our modifier looks like a function. The require()  function evaluate a condition and will throw an exception if the condition is not met which will stop the execution of our smart contract. The _  keyword tells the compiler to replace _  by the body of the function.

As same as a function, a modifier can accept parameters. Let’s say we could have multiple users and want to check the ownership.

As you can see our modifier is more generic and let us do more.

You could also write the most generic modifier that only runs if any condition is true:

Multiple modifiers are applied to a function by specifying them in a whitespace-separated list and are evaluated in the order presented.

In the next tutorial, we’ll learn how we can use one contract to create and interact with other contracts.