How to gather data from the real-world (i.e.: APIs) and boost your smart contracts built with Convector Suite.
Hello all. Walter from WorldSibu here. Our open source community grows every day and as it matures along with the framework we can move to more complex topics.
This topic was recently discussed in the Discord chat so I decided to create an example of how to work with oracles in Convector Suite (not to be confused with “Oracle” the company 🧐).
This blog post is to help you understand what oracles are, how to integrate them, and get a real example up and running. I know how hard it is to find real examples of how to do blockchain in the enterprise — we try a lot to create repos like this one to guide developers in our Github.
I will be using Convector Smart Contracts, Hurley, NestJS, mockable.io, and of course, Hyperledger Fabric 1.4. Since oracles can be confusing at first I will try to explain and iterate in the data flow through multiple conceptual and technical diagrams.
No time to read? Go download the repo here!
Oracles are the means by which a smart contract can access data from off the chain. A smart contract can’t rely on external data for computing — meaning that it needs deterministic data to compute and apply transactions to the ledger.
Consider the following scenario of what could happen if the smart contract could access an external resource like an API:
This may happen because external resources are not deterministic. They may change from time to time. Failures, changes, attacks, all can affect the computing of a smart contract.
Some people refer to this property by making this thought process: if I were to take all the historic data of the blockchain and re-compute it, the results should be the same.
However, if Central Bank was in the blockchain:
This looks nice, but data needs to be put before its needed. What about on-demand off-chain data? That's where an oracle is helpful.
An oracle allows for requesting external resources, save them, and compute based on that data. An oracle is more than just code — it’s a kind of trusted entity that everybody relies upon to “reflect” real-life data into the chain keeping the track of the requested resource and making the computing deterministic.
The transaction computes and requests the external resource through an event. The oracle computes the requests, gets the data, and “restarts” the transaction by calling the function __callback() inside of the original smart contract.
In a nutshell, it's like saying… “we start this transaction but need this value to finalize it. Hey Mr. oracle look and find the external resource for us and then store it in the blockchain and let us know to complete the transaction”.
We will look further into the flow later in the post.
Some common data that may be required from the outside includes:
A typical flow includes 2 main steps:
Step 1: Initiate the transaction and request the external resource.
Step 2: Get the response from the outside world and continue the transaction.
You would need these main components:
Initiate the transaction and request the external resource from the smart contract.
The oracle daemon gets the response from the outside world and continues the transaction.
Download the source code here:
git clone https://github.com/worldsibu/convector-oracle
cd convector-oracle
There are a few key concepts:
The logic of the code is:
create()
to create a car but the .insuranceLevel
property will be set by the oracle by querying an external web service.__callback()
..insuranceLevel
will be set with the data returned by the API. Also, the value dateOracleResponse
will be set to log when the oracle returned data.Our model's structure is pretty simple:
And our controller looks like this:
A few things to notice:
create
we trigger an event this.tx.stub.setEvent
. insuranceLevel
.Let’s explore the actual flow a bit more in detail:
To run the project first make sure to meet Hyperledger Fabric pre-requisites.
Then, you will need a mockable.io API running — https://www.mockable.io
In mockable.io you just need to follow the tutorial and configure it like this:
Notice the Verb in POST and the Path with bankapi.
Then just make sure to get it up:
Click on “stopped” — yeah the UX is weird, you click “stopped” to get it up.
Copy the url from the field
Path
including the /bankapi
piece. This will emulate our external API that the oracle daemon will call.Add a new file in
./packages/conv-oracle/src/.env
with the following content:EXTERNAL_URL=<full-url>
This will tell the oracle daemon server where to fetch the data.
The first transaction will take a few seconds to instantiate the smart contract in the second organization.
npm install
# Start a blockchain network locally
npm run env:restart
# Install the smart contract
npm run cc:start
# Start the oracle daemon [ignore npx if you don't use npx]
npx lerna run start --scope conv-oracle --stream
# Make a call to see everything in action
# YOU WILL NEED ANOTHER CONSOLE TAB
hurl invoke carinsurance carinsurance_create "1" "volk" "1199"
Congratulations! You ran your first oracle with Hyperledger Fabric thanks to Convector! 🎊
Let’s explore the data — go in your browser to http://localhost:5084/_utils/#database/ch1_carinsurance/1
You will see something like:
Fields dateOracleResponse and insuranceLevel were set by the Oracle from the API.
Try some things to prove that it’s not cheating, turn off the oracle daemon (just type control+c) in the tab running the server.
Send another transaction:
hurl invoke carinsurance carinsurance_create "2" "volk" "1199"
And explore the results: http://localhost:5084/_utils/#database/ch1_carinsurance/2
Oracles are a great tool to have at your disposal — we make use of Convector’s ability to use Hyperledger Fabric’s events and with this bootstrapped nestjs oracle daemon you can start doing some neat things!
I hope this was useful and also to see you around in theDiscord communityHundreds of devs helping each other and learning together!
Just like blockchain infrastructure, oracle’s infrastructure is not trivial — in fact, that’s why we created Forma to solve the infrastructure pains without cutting out the decentralized benefits of a blockchain network. So here are my recommendations to what to focus on when creating oracles:
Just to mention a few. Oracles are critical components of blockchain networks and as such they should be treated carefully.
What do you think? Real-life data is necessary for real-life blockchains. At WorldSibu we love exposing our experience and building along with the community.