Home Welcome to the Documentation of Oraclize! Background Oraclize is the leading oracle service for smart contracts and blockchain applications, serving thousands of requests is bitcoin mining itself compromising the security of SHA256 day on Ethereum, Bitcoin and Rootstock. In the blockchain space, an oracle is a party which provides data.
But to rely on a new trusted intermediary, the oracle in this case, it would be betraying the security and reduced-trust model of blockchain applications: which is what makes them interesting and useful in first place. One solution is to accept data inputs from more than one untrusted or partially trusted party and then execute the data-dependent action only after a number of them have provided the same answer or an answer within some constrains. This type of system can be considered a decentralized oracle system. It is inherently inefficient: all the parties participating will require a fee and, for every request, it will take time before reaching a sufficient number of answers.
Octagon vs bitcoin calculator
The solution developed by Oraclize is instead to demonstrate that the data fetched from the original data-source is genuine and untampered. This is accomplished by accompanying the returned data together with a document called authenticity proof. The authenticity proofs can build upon different technologies such as auditable virtual machines and Trusted Execution Environments. A more detailed overview of Oraclize authenticity proofs is provided in the Authenticity Proofs section of this documentation. Data providers don’t have to modify their services in order to be compatible with blockchain protocols. Smart contracts can directly access data from Web sites or APIs. Oraclize engine can be easily integrated with both private and public instances of different blockchain protocols.
While building the service, the Oraclize team has realized that the concept of authenticity proofs has much broader applicability that initially envisioned. General Concepts Oraclize is integrated with a number of blockchain protocols and its service is useful and accessible also for non-blockchain applications. In the following section, general concepts which apply to all integrations will be explained. Oraclize Engine The Oraclize Engine powers the service for both blockchain-based and non-blockchain-based application. Internally replicates an “If This Then That” logical model.
This means that it will execute a given set of instructions if some other given conditions are met. For example, it could repeatedly verify a condition and only return data or perform an action when the condition has been met. Data Source Types A data source is a trusted provider of data. It can be a website or web API such as Reuters, Weather.
The first parameter is the main argument and it is usually mandatory. For example, in the case of the URL Data Source Type, the first argument is the expected URL where the resource resides. If only the first argument is present, then the URL Data Source assumes that an HTTP GET was requested. The second parameters, which it is optional, should contain the data payload of the HTTP POST request. The intermediate result of a query may need to be parsed: for example, to extract a precise field in JSON API response. Therefore, the query can also specify parsing helpers to be applied.
Parsing Helpers Oraclize offers XML, JSON, XHTML and a binary parser helpers. HTML Parser: helper is useful for HTML scraping. The first parameter is the expected to be the offset, while the second one is the length of the returned slice. 4, which can be easily tested via this external website. If Oraclize is unable to generate an authenticity proof for technical reasons, it will return in most cases the result without the requested proof.
Data Sources Listed here are the data-sources you can choose from when using our oracle service. Please note that datasource selection is not case-sensitive. URL The URL data source type enables access to any API or web page on the Internet. It supports both HTTP GET and HTTP POST request. If only one parameters is specified in the query, the service will default to perform an HTTP GET request. If a second parameter is specified, then the service will perform an HTTP POST request, posting the second parameter as data.
Note that if the second parameter is valid JSON, then it will be posted as such. As Oraclize is a remote service, it requires the `URL` datasource to also be remotely accessible. Developers should test the validity of the query via Oraclize’s Test Page to make sure your syntax makes sense to Wolfram’s engine. For this reason, Oraclize recommends to use this data source type only for testing. This datasource expects as sole parameter the IPFS multihash in the query. If Oraclize fails to fetch the IPFS content within 20 seconds, the request will fail.
Persistance of the file is not garanteed. The computation datasource enables the auditable execution of an application or a script by leveraging a sandboxed Amazon Web Service virtual machine. The application has to print, on standard output, the result of the computation as the last line before it quits. The result can be up to 2500 characters long.
The execution context has to be described by a Dockerfile, where building and running it should start the main application straight away. Currently Oraclize only provides one type of auditable instance: a t2. The developer can send to Oraclize the application binary or the script, its dependency and the Dockerfile by creating an archive and uploading it to IPFS. The query expects as first argument the IPFS multihash of that archive, while the following arguments will be passed to the execution environment as environmental variables, making them accessible by the application. Oraclize might use the email specified in the MAINTAINER field of the Dockerfile, as contact information in case any issue arises. The Dockerfile must be in the root of the archive.
The authenticity proof, attached with the result, can be easily verified not just off-chain but even by any Solidity contract receiving them. The example presented here, showing how to integrate the verification process, discards any random result whose authenticity proofs don’t pass the verification process. The random datasource is leveraging the Ledger proof to prove that the origin of the generated randomness is really a secure Ledger device. 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 apply here as well.
The nested datasource is a meta datasource, it does not provide access to additional services. It was designed to provide some simple aggregation logic, enabling a single query to leverage sub-queries based on any available datasource and produce a single string as a result. Please mind the square brackets 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.
Alternative Public Chains Oraclize is constantly studying new public blockchain protocols and considering further blockchain integrations. Since the Oraclize Engine is completely blockchain agnostic and can interact via HTTP API, developers are encouraged to work on open-source independent Oraclize integration on the model of the Ethereum-Bridge. Private Ethereum-based Chains Private, Ethereum-based chains can currently integrate with Oraclize by using the Ethereum-Bridge. Forks of Ethereum such as Monax included. Alternative Private Chains The Oraclize team is currently investigating to create software for a native integration for alternative private distributed ledger protocols such as Corda, Chain and Hyperledger.
Additional information are available on contacts. Non-blockchain Applications The oraclize-lib enables the use of the Oraclize engine capabilities also in a non-blockchain context, by providing an abstraction layer which resolves to Oraclize HTTP API. The oraclize-lib is currently in a experimental-stage. Ethereum The following section is dedicated to the Ethereum and Oraclize integration. To better profit from this section of the documentation, previous knowledge of Solidity and Ethereum is required.
The interaction between Oraclize and an Ethereum smart contract is asynchronous. Firstly, in the most common case, a transaction executing a function of a smart contract is broadcasted by an user. The function contains a special instruction which manifest to Oraclize, who is constantly monitoring the Ethereum blockchain for such instruction, a request for data. Secondly, according to the parameters of such request, Oraclize will fetch or compute a result, build, sign and broadcast the transaction carrying the result. In the default configuration, such transaction will execute the __callback function which should be placed in the smart contract by its developer: for this reason, this transaction is referred in the documentation as the Oraclize callback transaction.
As said in previous sections, one of the fundamental characteristics of Oraclize is the capability of returning data to a smart contract together with one or more proofs of authenticity of the data. The generation of an authenticity proof is optional and it is a contract-wide setting which must be configured by the smart contract developer before the request for data is initiated. Oraclize always recommends the use of authenticity proofs for production deployments. Oraclize query was sent, standing by for the answer.
Version 1.3.12, 2004-05-02¶
The most simple way to introduce the Ethereum – Oraclize integration, it is by showing a working example, such as the smart contract on the right. The code in the example is working out of the box if Remix is used to compile and deploy it on any of the Ethereum networks: main-net and the Ropsten, Kovan and Rinkeby testnets. If, instead, another tool is used, it will be necessary to replace the import statement with a local import of the oraclizeAPI. To ease development, Oraclize doesn’t charge a contract for its first request of data done using the default gas parameters.
Successive requests will require the contract to pay the Oraclize fee and the ether necessary to pay for the callback transaction. Both are automatically taken from the contract balance. If the contract doesn’t have enough funds in his balance, the request will fail and Oraclize won’t return any data. Only the first query is free. Ensure that the contract has a sufficient ETH balance to pay the following queries. The contract gets automatically charged on the `oraclize_query` call but fails if the balance is insufficient. The URL datasource also supports a supplement argument, useful for creating HTTP POST requests.
If that argument is a valid JSON string, it will be automatically sent as JSON. A request for data is called query. The argument for the given data-source. The number and type of supported arguments depends from the data-source in use.
Beside, few more code example will be shown and commented. The datasource, as well as the authenticity proof chosen, determine the fee which the contract has to pay to Oraclize. The execution of a query can be scheduled in a future date. The function oraclize_query accepts as a parameter the delay in seconds from the current time or the timestamp in the future as first argument.
Smart contract using Oraclize can be effectively autonomous by implementing a new call to Oraclize into their __callback method. This can be useful for implementing periodic updates of some on-chain reference data, as with price feeds, or to periodically check for some off-chain conditions. GBP exchange rate every 60 seconds, until the contract has enough funds to pay for the Oraclize fee. In general it is recommended to send queries purposefully. This ensures that each query response is processed only once and helps avoid misuse of the smart contract logic. Moreover, it protects the smart contract during blockchain reorganizations, as explained in the dedicated paragraph of this section.
The transaction originating from Oraclize to the __callback function pays a fee to the miner which include the transaction in a block, just like any other transaction. If no settings are specified, Oraclize will use the default values of 200,000 gas and 20 GWei. This last value is on the higher-end of the pricing spectrum right now, but it helps having faster confirmation times during network-wide congestions. Smart contract developers should estimate correctly and minimize the cost of their __callback method, as any unspent gas will be returned to Oraclize and no refund is available.
However, there is no need to put `wei` keyword in the parameter. Authenticity proofs are at the core of Oraclize’s oracle model. The authenticity proof can be either deliver directly to the smart contract or it can be saved, upload and stored on IPFS. TLSNotary Proof bytes as the proof argument in the callback transaction. Oraclize will return only the base58-decoded IPFS multihash as the proof argument.
To obtain the IPFS multihash, the bytes must be encoded to base58. Verifiability Supported proofs can be verified. You have to consider that your account will be debited for most of your Oraclize calls. If your contract is not covered with enough ETH, the query will fail.
Depending on your contract logic you may want to check the price for your next query before it gets send. This effectively marks the query id as processed. It might occur that a callback function of a sent query gets called more than once. Therefore it might be helpful to initiate a mapping that manages the query ids and their states.
Michael G. Jensen
When the callback function of a query gets called, the require statement checks if the current query id needs to be processed. After one successful iteration the id gets deleted to prevent further callbacks for that particular id. The encrypted queries feature may be of interested to developers who want to deploy their blockchain applications of public networks. Oraclize therefore offers the possibility of encrypting the parameters contained in a query to Oraclize’s public key: 044992e9473b7d90ca54d2886c7addd14a61109af202f1c95e218b0c99eb060c7134c4ae46345d0383ac996185762f04997d6fd6c393c86e4325c469741e64eca9 Only Oraclize will then be able to decrypt the request using its paired private key.
To encrypt the query, Oraclize provides a CLI tool, which can be found here. This will encrypt the query with the default Oraclize public key. The encrypted string can then be used as an argument for an Oraclize query. In this example, the entire first argument of an oraclize_query has been encrypted. Our encryption system also permits users to encrypt any of the supported datasource options. Oraclize with a given encrypted query becomes its rightful “owner”. Any other contract using that exact same string will receive an empty result.
Mapping the Price of Beer Around the World
As a consequence, remember to always generate a new encrypted string when re-deploying contracts using encrypted queries. 256k1 as curve and ANSI X9. 63 with SHA256 as Key Derivation Function. This algorithm is used to derive a shared secret from the Oraclize public key and ad-hoc, randomly generated developer private key.
The IV can be set to the zero byte-array because each shared secret is thrown-away and use only once. Every time the encryption function is called a new developer private key is re-generated. Arguments can be passed to the package by adding parameters to the query array. They will be accessible from within the Docker instances as environmental parameters. RUN pip3 install requests CMD python .
Encrypted arguments can be passed using the nested and the decrypt meta data sources, as shown in the example at the right. For advance usage of Random Data Source, it is recommended to read the following section. Multi-Party Interactions In the case of multi-party interactions, such as voting schemes or lotteries, the commitment data can should include all participants addresses, to ensure that the transaction cannot be replayed by a miner on a fork or a reorged chain where a participant didn’t put a stake. A production-ready version will follow in the future. Rootstock Rootstock is the first production sidechain of the Bitcoin network.
BTX Trader Explained
It aims to extends Bitcoin capabilities without compromising its decentralization and censorship resistance properties. On the Rootstock networks, participants are able to interact with smart contracts using a token called Smart Bitcoin. The peg between Bitcoin and Smart Bitcoins is maintained by a federation of distinguished players and backed by merged mining. The RSK Mainnet and public Testnet are now live and they both have full integration with Oraclize services.
Smart contracts on Rootstock are executed by an upgraded, but backward compatible version, of the Ethereum Virtual Machine. Those are written using the programming language Solidity and are fully compatible with Ethereum smart contracts. The Oraclize Rootstock integration is in fact completely compatible with the Ethereum one, since Ethereum smart contract can be compiled and executed on Rootstock natively. For more technical details on how to use the Oraclize service from within Solidity smart contracts, please refer to the Ethereum section of this documentation. Corda Here we will cover the Oraclize’s Corda integration. Before reading this section, you must be familiar with the Corda platform key concepts like flows, subflows, contracts, transactions, commands, oracles etc.