Note: We’re using the Ropsten testnet in this example.
Let’s assume that we want to create a smart contract that acts upon the USD price of Ethereum, as reported from the popular price analysis site CoinGecko. We know that there is no native way our smart contract can call an external HTTP API, but an oracle node can.
Using the request-and-response cycle, our smart contract can request data from an oracle node, which is configured to perform HTTP GET requests, and implement a callback function for the oracle to fulfil with a response.
Figure 1: Request & receive data flow
We can’t simply use any oracle, because each is configured to perform specific tasks depending on the adapters they support. To find a high-quality oracle to suit our needs, we must search for one using a listing service like Chainlink Market.
Chainlink market
Listing services enable us to find oracles that can serve our requests. Popular APIs often have oracle implementations of requests to certain endpoints pre-configured, which makes our development much easier. We can find out if our desired CoinGecko endpoint is already implemented by an oracle by heading to the Chainlink Market homepage and typing “CoinGecko” in the search bar.
Figure 2: Chainlink Market search for “CoinGecko”
As we can see in figure 2, we have some results!
The Nodes section lists the oracle nodes that have returned results for the search string. This likely means that they support jobs which retrieve data from the CoinGecko API. Of the three nodes available, Omniscience-Ropsten is verified (circled), indicating its trustworthiness. It also has the highest number of job runs.
Scrolling down we can see ETH-USD CoinGecko under the Jobs heading. This looks perfect, as it seems to describe exactly what we want to retrieve, and uses the verified node. Clicking on the link will provide us with more information about the job.
Figure 3: Node details page
Figure 3 shows the node details page, which gives us more information about the Oracle node. On the left-hand side (inside the red rectangle) is the on-chain address of the oracle. If we are to use this oracle, we need to make a note of this address.
On the right-hand side of the screen are three tabs: Adapters, Feeds, and Jobs. Click on Jobs and scroll until you find ETH-USD CoinGecko. Click on that link to display the job information page.
Figure 4: Job information page
Figure 4 shows us the job information page, where we can see details about what it does when it’s requested. Highlighted are the job ID and the cost of running this job (make a note of these, too).
On the right-hand side of the page is the Task List. This is the list of operations the job performs when it is invoked. Each task uses a supported adapter, one after the other, creating a chain of tasks. Let’s walk through each task in the list to figure out how the job gets the data we want:
1. HTTP GET Request
Task 1
The first task is the call to the CoinGecko API using HTTP GET. We can confirm from the URL in the params that it makes the correct CoinGecko request. This returns a JSON response body.
2. JSON Parse
Task 2
Since task 1 returns JSON, the next task needs to parse it to access the target data. Task 2 uses the JSON Parse adapter to traverse the returned JSON object using the path provided. The target data in the path from task 2, for example, would be located in the following JSON structure:
{
"market_data":
{
"current_price":
{
"usd": "PRICE_HERE"
}
}
}
3. Multiply
Task 3
We’ve retrieved the price from the JSON, but it’s not quite ready yet. Since Solidity can’t handle decimals, task 3 multiplies the price by 100,000,000 to ensure it can be represented as an integer.
4. ETH Int256
Task 4
Task 4 then converts the result into encoded int256.
5. ETH Transaction
Task 5
Finally, task 5 creates an Ethereum transaction to send the result back to the original contract.
