NAV
Oraclize log

Overview

Oraclize aims to be the privileged data gateway between blockchain protocols and the world wide web.

Oraclize main goal as a company is to provide a way for smart contracts to break free of their constrains and provide them the ability to access all the data they need from the web, without compromising their trustless nature.

In particular, the aim is not to force smart contract developers in having to trust Oraclize with the data they need. Without any backing of authenticity, Oraclize could easily tamper with the data.

In order to complete this complex task, Oraclize returns the data requested along with a proof of the authenticity: i.e that the data comes from the data provider which has been explicity demanded by the smart contract.

More can be read about the authenticity proofs provided by Oraclize, within the dedicated Authencity Proofs section of this documentation.

Getting Started

The following documentation enables developers to start integrating Oraclize into their project.

The service is currently live on Bitcoin, Ethereum’s mainnet and testnet and Rootstock’s testnet.

Ethereum Integration

The following is meant to be a short but complete introduction to explain how the interfacing of an Ethereum contract with Oraclize actually works. To better profit from the documentation, previous knowledge of Solidity, the most used smart contract language on Ethereum, is required.

All the reference code used is written in Solidity, but since the interface would be the same for any other language.

Sending a query to Oraclize means sending a contract call, also called internal transaction, to the on-chain Oraclize contract.

With that, Oraclize will:

Note that the transaction sent back by Oraclize can trigger any status change in the calling contract, and can include the sending of another query to Oraclize. What can be done in the __callback method is only bounded by the block gas limit.

Getting Everything on Track

First, place usingOraclize contract into your code. You do not need to import the OraclizeI and OraclizeAddrResolverI contract interfaces as this is taken care of.

The purpose of the usingOraclize contract is to make calls to OraclizeI and OraclizeAddrResolverI as painless as possible for you. However, if you know what you are doing, you are free to call our OraclizeI and OraclizeAddrResolverI interfaces directly. The upside is that you would spend a lower amount of gas for contract deployment. The downside is that if anything goes wrong a throw is raised.

In order to simplify the use of our API, we highly recommend that you simply extend the usingOraclize contract and use its inherited methods, about which we discuss below. Indeed, these methods already handle payments and API calls correctly.

All the code you need is found here http://dev.oraclize.it/api.sol. After making your contract extend usingOraclize, it would look like:

import "github.com/oraclize/ethereum-api/oraclizeAPI.sol";

contract YourContractName is usingOraclize {

    function YourContractName() {
        ..
    } 

}

Simple Query

Note: All the code written here assumes that you have already included all the necessary code as described in the paragraphs above, and that your contract already extends our usingOraclize contract (if you are using Solidity).

When sending a query to Oraclize you have to specify at least two arguments:

More information about these can be found in the Overview document.

An example code might look like this:

oraclize_query("WolframAlpha", "random number between 0 and 100");

This code example will ask Oraclize to send you back immediately a transaction with the primary result (as a string) of the given formula (“random number between 0 and 100”) fetched from the data-source “WolframAlpha”.

Similarly, you can use any other data-source, here we list some examples:

oraclize_query("URL", "https://api.kraken.com/0/public/Ticker?pair=ETHXBT")
oraclize_query("URL",
  "json(https://www.therocktrading.com/api/ticker/BTCEUR).result.0.last")
oraclize_query("IPFS", "QmdEJwJG1T9rzHvBD8i69HHuJaRgXRKEQCP7Bh1BVttZbU")
/* 
  the only data-source accepting 2 string arguments is
  'URL' when we want it to send an HTTP POST request
  with the 2nd argument being the query-string we want
  to send to the given server.

  note that when the 2nd argument is a valid JSON string
  it will be automatically sent as JSON
*/
oraclize_query("URL", "json(https://shapeshift.io/sendamount).success.deposit",
  '{"pair":"eth_btc","amount":"1","withdrawal":"1AAcCo21EUc1jbocjssSQDzLna9Vem2UN5"}')

Schedule a Query in the Future

If you want Oraclize to execute your query at a scheduled future time, just specify the delay (in seconds) from the current time or the timestamp in the future as first argument.

Please note that in order for the future timestamp to be accepted by Oraclize it must be within 60 days from the current time.

// get the result from the given URL 60 seconds from now
oraclize_query(60, "URL",
  "json(https://api.kraken.com/0/public/Ticker?pair=ETHXBT).result.XETHXXBT.c.0")
// get the result from the given datasource at the specified timestamp in the future
oraclize_query(scheduled_arrivaltime+3*3600,
  "WolframAlpha", strConcat("flight ", flight_number, " landed"));

The query ID

Every time you call oraclize_query(...), it returns you a unique ID that represents your query. Whether you store this ID for future reference is up to you.

// get the result from the given URL 60 seconds from now
bytes32 myid = oraclize_query(60, "URL",
  "json(https://api.kraken.com/0/public/Ticker?pair=ETHXBT).result.XETHXXBT.c.0");

Callback Functions

Once your result is ready, Oraclize will send a transaction back to your contract address, and invoke 1 of these 3 methods:

Here are some handling examples:

function __callback(bytes32 myid, string result) {
    if (msg.sender != oraclize_cbAddress()) {
      // just to be sure the calling address is the Oraclize authorized one
      throw;
    }
    ETHXBT = result; // doing something with the result..
    // new query for Oraclize!
    bytes32 myid = oraclize_query(60, "URL",
      "json(https://api.kraken.com/0/public/Ticker?pair=ETHXBT).result.XETHXXBT.c.0");
}

In the snippet above we call oraclize_query again within the __callback function. In effect, this makes the contract receive automatically __callback every minute forever. Or at least, until you run out of funds!

Note that myid can be used to implement different behaviours into the __callback function, in particular when there is more than one pending call from Oraclize.

Custom Gas

The transaction originating from Oraclize to your __callback function costs gas, just like any other transaction. However, as you learned earlier, you need to cover Oraclize for this gas cost, and the oraclize_query function helpfully handles that. It defaults at 200,000 gas.

This return gas cost is actually in your control since you write the code in the __callback method, and as such, can estimate it. So, when placing a query with Oraclize, you can also specify how much the gasLimit should be on the __callback transaction. Note however that, since Oraclize sends the transaction, any unspent gas is returned to Oraclize, not you.

If the default, and minimum, value of 200,000 gas, is not enough, you can increase it by specifying a different gasLimit in this way:

// Oraclize will use a 500k gasLimit for the callback transaction, instead of 200k
oraclize_query("WolframAlpha", "random number between 0 and 100", 500000);
// you can set both custom timestamp/delay and custom gasLimit
oraclize_query(60, "WolframAlpha", "random number between 0 and 100", 500000);

Note also that if you offer too low a gasLimit, and your __callback method is long, you may never see a callback.

TLSNotary Proof

In order to get, or not, the TLSNotary proof back from Oraclize you need to specify the proofType and proofStorage. You do this by calling:

You may execute this method just once, for instance in the constructor, or at any other time, if, for instance, you need the proof for certain queries only.

proofStorage_IPFS means that Oraclize will:

The proof string is exactly the IPFS multihash that identifies your TLSNotary proof, so you can fetch it for example at http://ipfs.io/ipfs/proof

Note: There might not always be a TLSNotary proof for your query, depending on the data source you have chosen

Here is an example:

import "github.com/oraclize/ethereum-api/oraclizeAPI.sol";

contract YourContractName is usingOraclize {

    function YourContractName() {
        oraclize_setProof(proofType_TLSNotary | proofStorage_IPFS);
        oraclize_query("URL",
          "xml(https://www.fueleconomy.gov/ws/rest/fuelprices).fuelPrices.diesel");
    }

    function __callback(bytes32 myid, string result, bytes proof) {
        if (msg.sender != oraclize_cbAddress()) throw;
        ..
    }
}

More Examples

You can have a look at more complete and complex examples by heading to our dedicated github repository: https://github.com/oraclize/ethereum-examples

Random Utilities

Since the callback transaction always provides results as strings, the Solidity API helpers also include some convenience functions, which might prove useful to you. Especially since Solidity does not provide any official “standard Library” yet.

You can check them out here.

Best Practices

import "github.com/oraclize/ethereum-api/oraclizeAPI.sol";

contract YourContractName is usingOraclize {

    mapping(bytes32=>bool) myidList;

    function YourContractName(){
         oraclize_query("URL","json(http://exampleUrl.url).result");
    }

    function __callback(bytes32 myid, string result) {
        if(msg.sender != oraclize_cbAddress()) throw;
        if(myidList[myid]==true) {
          // check if this myid was already processed before
          throw;
        }
        myidList[myid] = true; // mark this myid (default bool value is false)
        ...
    }

}

What follows are some practical tips we recommend you to use when writing Oraclize-based smart contracts:

Datasources

We list here the data-sources you can choose from when using our oracle service.
Please note that datasource selection is not case-sensitive.

Datasource Distributions Proof type
Ethereum Mainnet
Ethereum Morden HTTP API
None TLSNotary
URL
WolframAlpha N/A
Blockchain
IPFS 1 N/A
decrypt N/A
nested 1 3
computation 1

1 Still experimental

2 Still experimental, will be available on mainnet once it’s stable

3 Depending on the datasources you choose in sub-queries, proofs may be provided for each of them, but not for the aggregation itself

URL

The most generic data-source we provide is the URL one, which can be used to access any public API or page on the Internet. As a first step you need to provide the actual URL whose HTTP GET / POST output you want Oraclize to fetch; and optionally the query-string parameters. Oraclize will forward you the response, while optionally attaching the TLSNotary proof.

WolframAlpha

The WolframAlpha data-source lets you specify as argument a query to submit to the WolframAlpha knowledge engine. Oraclize will send you back the primary response as a string if any.

Blockchain

The Blockchain data-source provides you with easy access to blockchain-related data. You can see this data-source as a shortcut to common block explorer APIs, but with a built-in easy-to-use syntax. Possible query arguments are:

IPFS

The IPFS data-source can be used to retrieve the content of a file on the IPFS protocol.

This datasource expects you to specify the IPFS multihash in the query i.e. QmT78zSuBmuS4z925WZfrqQ1qHaJ56DQaTfyMUF7F8ff5o will return "hello world\n" (note that in this case we have a terminating new line because the original IPFS file had it).

Please note that if we fail to fetch the IPFS content within 20 seconds, such request will fail.

decrypt

Even though the decrypt datasource can be used as any other, it was specifically designed to be used within the nested datasource to enable partial query encryption.

The result is the decrypted query string. Please note that all the logic, limitations and tools provided by the Encryption feature do apply here with no modification.

nested

The nested datasource is a meta datasource, it does not provide access to additional services. It was designed to provide a simple aggregation logic, enabling a single query to leverage sub-queries based on any available datasource and producing as result a single string.

The query format is built in a way you can specify a sub-datasource and a sub-query as follows: [datasource_name] query_content.

Please mind the square brakets delimiting the datasource name and the whitespace prefixing the actual sub-query. The sub-query content can optionally be delimited by either single or double quotes.

You can optionally specify more than one sub-query, by using as delimitators the ${ special opener and the } special closer.

Example: [WolframAlpha] temperature in ${[IPFS] QmP2ZkdsJG7LTw7jBbizTTgY1ZBeen64PqMgCAWz2koJBL}

computation

The computation datasource enables the auditable execution of a given application into a secure blockchain-unrelated (off-chain) context.

Such application has to print the query result on the last line (on standard output) before its quits. The execution context has to be described by a Dockerfile, where building and running it should start your main application straight away. The Dockerfile initialization + your application execution should terminate as soon as possible: the maximum execution timeout is ~5 minutes on an AWS t2.micro instance.

As the query is the IPFS multihash of a zip archive containing such files (Dockerfile + any external file dependencies, the Dockerfile has to be places in the archive root), you should take care of preparing such archive and pushing it to IPFS beforehand.

Example:

  1. Dockerfile content:

  1. zip -rarchive.zip.

  2. ipfs add archive.zip

    • Output: added QmRxtL9K2de7v7QBYCCrwcjZHjYmuKggZ8xaqZ6UUWvd1s archive.zip
  3. our query argument is QmRxtL9K2de7v7QBYCCrwcjZHjYmuKggZ8xaqZ6UUWvd1s and the query result will be 72

Pricing

The use of Oraclize APIs requires the payment of a small fee, you can check out the pricing for each integration below:

Ethereum

The fee for Ethereum comes on top of the reimbursement for the full gasLimit we are setting in the transaction when we call back your contract.

Free calls

In order to make the testing of our service a little bit easier (and cheaper) to you, the first Oraclize query call coming from any Ethereum address is completely free of charge. This means we are even covering the callback transaction gas costs for you (up to the default gasLimit of 200k gas).

This might be helpful, for example, to send the first call to Oraclize directly from your contract constructor function without having to create your contract with an attached amount of Wei. This means, again, that you can have one free triggering transaction for any date in the future (up to 60 days).

Call fees

Payment is part and parcel of the oraclize_query function call, and our pricing model is simple. It’s composed of two parts:

Datasource Base price Proof type
None TLSNotary
URL 0.01$ +0.0$ +0.04$
Blockchain 0.01$ +0.0$ +0.04$
WolframAlpha 0.03$ +0.0$ N/A
IPFS 0.01$ +0.0$ N/A

Authenticity Proofs

As digital technologies have reduced the barrier to entries for information creation and distribution, it has become extremely important to be able to authenticate a piece of information as originating from a known, trusted source.

In the context of web technologies, authentication is provided by the HTTPS protocol, an extension of the HTTP protocol which create an encrypted and authenticated channel between the client and the web-server containing the data.

When dealing with data which could be used to determine different financial transactions, authentication becomes of fundamental importance. Unfortunately, the most used and available blockchain protocols have no direct way of interacting with HTTPS and therefore digesting authenticated data. It would seem then that there is a need for a trusted service which can provide this data or complete actions based on it; but that would in part defeat the point of having a decentralized protocol for exchanging value without trusted parties.

This is the reason why Oraclize has been designing systems for authenticating data and made it part of its core business. These systems are called authenticity proofs, which enable auditability of the oracle’s service record in delivering untampered data. The authenticity proofs leverage different attestation technologies: some are software-based and some rely on trusted hardware technologies.

TLSNotary Proof

The TLSNotary Proof leverages a feature of the TLS 1.0 and 1.1 protocols which enables the splitting of the TLS master key between three parties: the server, an auditee and an auditor. In this scheme, Oraclize is the auditee while a locked-down AWS instance of a specially-designed, open-source Amazon Machine Image acts as the auditor. The TLSNotary protocol is an open-source technology, developed and used by the PageSigner project.

Android Proof

The Android Proof is a result of some of Oraclize’s internal R&D work. It leverages software remote attestation technology developed by Google, called SafetyNet, to validate that a given Android application is running on a safe, non-rooted physical device, connected to Oraclize’s infrastructure. It also remotely validates the application code hash, enabling authentication of the application running on the device. The application code is open-source, thereby enabling auditability and verification of the code hash. The Android Proof goes further, by using the newly introduced Android Hardware Attestion to prove that the physical device is updated to the latest available Android version, further ensuring integrity by having any potential exploits within the system patched. Furthermore, it verifies that the device’s Root-of-Binding-Trust is valid. Both these technologies together effectively turn the physical Android device into a provably-secure environment in which an untampered HTTPS connection to a remote datasource can be initiated. For Oraclize or an external attacker with unauthorized gained access to the infrastructure to compromise the device and generate a false but valid proof, a zero-day exploit unbeknownst to Google must be discovered by said party, which either breaks the Android sandboxing model or is a kernel-level exploit, of the latest version of Android OS and its available security patches. You can access more information about the Android Proof by reading the white paper on it and experiment with it on the Ethereum and Bitcoin testnets. The enabling of the Android Proof on mainnet is pending based on an update by Google, effectively enabling Android Nougat Hardware Attestation.

Storage and Delivery

The authenticity proofs may be relatively large files, of up to a few kilobytes. Delivering such proofs directly within the result of the data payload in an Ethereum transaction can get quite expensive, in terms of EVM execution costs, and may even be impossible for larger data.

Moreover, Oraclize strives to be blockchain agnostic, enabling the proof to be used even on Bitcoin and other blockchains. Therefore the proof is uploaded and saved to IPFS, a decentralized and distributed storage system. In providing a pointer to the content, IPFS uses a custom hashing algorithm called multihash. The resulting address is Base64 encoded and it’s a unique ID specific to the file which can be used to access it globally, and changes along with any edits to the file contained.

IPFS, by itself, doesn’t provide any long-term guarantees of persistency, however as part of Oraclize’s infrastructures it runs the IPFS persistence consortium. Anyone can join Oraclize’s consortium and help in keeping an independent copy of all the proofs by pointing a IPFS persistence consortium node to the following aggregation peer: QmSsSSfJAJwj3jsNfzbSrxtLAjhpYPjbUEsCQT8mWVgBiL

Additional Features

Parsing Helpers

In order to make things simpler to handle on the smart-contract side, you can provide the URL inside one of the following parsing helpers:

Encrypted Queries

There are some use cases where you are interested in not disclosing your clear text query to the blockchain: for example, if your query includes some API secret credentials.

One option is to encrypt the entire query using Oraclize public key 044992e9473b7d90ca54d2886c7addd14a61109af202f1c95e218b0c99eb060c7134c4ae46345d0383ac996185762f04997d6fd6c393c86e4325c469741e64eca9

This means your request will be stored in the blockchain in an encrypted form and that only Oraclize will be able to decrypt it by using its paired private key.

To encrypt the query, you can use our encrypted_queries_tools.py python script (you can find it here).

The CLI command to encrypt an arbitrary string of text is then:

python encrypted_queries_tools.py -e -p 044992e9473b7d90ca54d2886c7addd14a61109af202f1c95e218b0c99eb060c7134c4ae46345d0383ac996185762f04997d6fd6c393c86e4325c469741e64eca9 "YOUR QUERY"

It will encrypt the query with the default Oraclize public key. You can then use the encrypted string to query Oraclize in an on-chain Ethereum smart contract.

// here we specify the encrypted formula directly
oraclize_query("URL","AzK149Vj4z65WphbBPiuWQ2PStTINeVp5sS9PSwqZi8NsjQy6jJLH765qQu3U/
  bZPNeEB/bYZJYBivwmmREXTGjmKJk/62ikcO6mIMQfB5jBVVUOqzzZ/A8ecWR2nOLv0CKkkkFzBYp2sW1H
  31GI+SQzWV9q64WdqZsAa4gXqHb6jmLkVFjOGI0JvrA/Zh6T5lyeLPSmaslI");

In this case, we have encrypted the following string json(https://poloniex.com/public?command=returnTicker).BTC_ETH.last, which uses the JSON helper to parse the API response, but in the query you can specify any datasource and helper that you want. The example uses a public API, but you can use any private API that only require a secret user key authentication method.

The encryption method is also available for POST requests: you can encrypt both the URL and the POST data field as in the following example:

// This is the query that we want to encrypt
oraclize_query("URL","json(https://api.postcodes.io/postcodes).status",
  '{"postcodes" : ["OX49 5NU", "M32 0JG", "NE30 1DP"]}')

Encrypt the datasource (URL in this case):
python encrypted_queries_tools.py -e -p 044992e94... "URL"

Result in:
BEIGVzv6fJcFiYQNZF8ArHnvNMAsAWBz8Zwl0YCsy4K/RJTN8ERHfBWtSfYHt+uegdD1wtXTkP30sTW+3xR3w/un1i3caSO0Rfa+wmIMmNHt4aOS

Encrypt the argument(in this case we are using JSON parse helper to retrieve the “status” ):
python encrypted_queries_tools.py -e -p 044992e94... "json(https://api.postcodes.io/postcodes).status"

Result in:
BNKdFtmfmazLLR/bfey4mP8v/R5zCIUK7obcUrF2d6CWUMvKKUorQqYZNu1YfRZsGlp/F96CAQhSGomJC7oJa3PktwoW5J1Oti/y2v4+b5+vN8yLIj1trS7p1l341Jf66AjaxnoFPplwLqE=

Encrypt the JSON (third argument, the data to POST):
python encrypted_queries_tools.py -e -p 044992e94... '{"postcodes" : ["OX49 5NU", "M32 0JG", "NE30 1DP"]}'

Result in:
BF5u1td9ugoacDabyfVzoTxPBxGNtmXuGV7AFcO1GLmXkXIKlBcAcelvaTKIbmaA6lXwZCJCSeWDHJOirHiEl1LtR8lCt+1ISttWuvpJ6sPx3Y/QxTajYzxZfQb6nCGkv+8cczX0PrqKKwOn/Elf9kpQQCXeMglunT09H2B4HfRs7uuI

// Finally we add all the encrypted text 
// to the oraclize_query (in the right order)
oraclize_query("BEIGVzv6fJcFiYQNZF8ArHnvNMAsAWBz8Zwl0YCsy4K/RJTN8ERHfBWtSfYHt+
  uegdD1wtXTkP30sTW+3xR3w/un1i3caSO0Rfa+wmIMmNHt4aOS","BNKdFtmfmazLLR/bfey4mP8
  v/R5zCIUK7obcUrF2d6CWUMvKKUorQqYZNu1YfRZsGlp/F96CAQhSGomJC7oJa3PktwoW5J1Oti/
  y2v4+b5+vN8yLIj1trS7p1l341Jf66AjaxnoFPplwLqE=", "BF5u1td9ugoacDabyfVzoTxPBxG
  NtmXuGV7AFcO1GLmXkXIKlBcAcelvaTKIbmaA6lXwZCJCSeWDHJOirHiEl1LtR8lCt+1ISttWuvp
  J6sPx3Y/QxTajYzxZfQb6nCGkv+8cczX0PrqKKwOn/Elf9kpQQCXeMglunT09H2B4HfRs7uuI");

Another use case may be a request from a datasource, as WolframAlpha, Bitcoin blockchain or IPFS. Our encryption system also permits users to encrypt any of the supported datasource option.

Chosen Encryption Scheme

To protect your encrypted queries, we have chosen an Elliptic Curve Integrated Encryption Scheme composed of the following algorithms: