How Chainlink Works Under the Covers

This article provides an insider’s view of how the different components of a Chainlink network fit together to provide blockchain developers with a robust and extensible mechanism to interact with the outside world. The Chainlink network provides reliable tamper-proof inputs and outputs for complex smart contracts, connecting these to real-world data, events, and payments.

Chainlink has been popular in the blockchain community with its architecture as a decentralized Oracle technology. Unlike other Oracle designs that rely on a centralized party to be trusted as a gateway, Chainlink is built on a network of independent node operators to offer unique integrations. The node operators are rewarded with the LINK tokens for performing verifiably honest and high-quality work. They can also be punished for being dishonest or turning up a result of poor quality.

Originally described in the whitepaper published in September 2017, the overall design has stayed by and large the same. The current codebase is still under active development, with many of the features described in the design still coming.

Kaleido release 1.0.22 was just published, which includes an upgraded Chainlink runtime from the opensource project‘s 0.7.0 release. Chainlink was among the earliest entries in the Kaleido marketplace, available to anyone building their own blockchain.

A high-level architecture overview can be found here.

How Chainlink Is Different From Other Oracle Technologies

Chainlink comprises multiple decentralized oracle networks, each containing several blockchain oracles for data retrieval and validation. This enables smart contracts connected to Chainlink to aggregate data from numerous oracle nodes rather than depend on a single source.

A summary of the comparison is outlined below:

Components of The Chainlink Design

A Chainlink network is made up of a collection of Chainlink nodes with registered Job specifications, who can carry out Jobs execution coordinated by the on-chain Oracle contract(s), which use LINK Tokens as an incentive for the Chainlink node operators to serve clients via the Chainlink client smart contracts.

Oracle Smart Contract

The Oracle contract is at the center of the Chainlink design. This is a core aspect of how Chainlink is used in Kaleido blockchain networks.

• Controls which Chainlink nodes are allowed to fulfill job requests
• Gateway for client contracts to access the Chainlink network
• Relays job execution results from the Chainlink network back to the client contract
• Locks Chainlink node operator deposits as punishment for poor performance

The contract communicates with the Chainlink network nodes by publishing EVM events specifically designed to broadcast client requests for external data or job execution: OracleRequest. The request object contains the job ID, client payment amount, client’s desired job execution parameters, and callback addresses for the client contract to accept job execution results.

More than one Oracle contracts may be active in a blockchain network. A Chainlink node operator may choose which Oracle contracts to register with in order to be permitted to handle job requests. A Chainlink client contract may choose which Oracle to send the job request to.

Client Smart Contract

The main consumer of the Chainlink Oracle function is naturally a smart contract. This is what the application developers building enterprise blockchain solutions need to develop. As described above, a client smart contract is not allowed to interact with the outside world. This must be done by going through a mechanism where the need for the external data is broadcast via transaction events, then an external party that listens for such events get notified for the request, and grabs the requested data and finally sends it into the chain by calling the smart contract via a transaction.

The Chainlink design is built on this Request-Event-Response mechanism, with a slightly more elaborate interaction flow. The client application developers do not have to write the smart contract from scratch. A base contract, ChainlinkClient.sol, is provided to make the contract developer’s life much easier.

The application developer only needs to implement three pieces of the client smart contract:

• Decide which LinkToken contract and Oracle contract to use. This can be configured in the constructor:  constructor(address _link, address _oracle) public Ownable() {
     setChainlinkToken(_link);
     setChainlinkOracle(_oracle);
   }
• Implement the function that constructs the Job request, with desired parameters and the callback function, and sends it to the Oracle contract:  function requestEthereumPrice(string _jobId)
     public
     onlyOwner
   {
     Chainlink.Request memory req = buildChainlinkRequest(stringToBytes32(_jobId), address(this), this.fulfillEthereumPrice.selector);
     req.add("get", "https://min-api.cryptocompare.com/data/price?fsym=ETH&tsyms=USD");
     req.add("path", "USD");
     req.addInt("times", 100);
     sendChainlinkRequest(req, ORACLE_PAYMENT);
   }
• Implement the callback function for the response data to be sent to:  function fulfillEthereumPrice(bytes32 _requestId, uint256 _price)
     public
     recordChainlinkFulfillment(_requestId)
   {
     emit RequestEthereumPriceFulfilled(_requestId, _price);
     currentPrice = _price;
   }

Chainlink Node

Chainlink nodes are the workers that carry out the requested jobs execution. There can be any number of Chainlink nodes attached to the blockchain network. Chainlink nodes operate independently of each other, as there are no peer-2-peer networking among them. Rather they communicate with the blockchain node that they are attached to, listening for job request events and submitting results back via transactions.

The organizations using the Chainlink client smart contract can deploy some shared instances of Chainlink nodes so that when Job specifications are deployed the resulting Job IDs can be shared with the participating organizations. The Job ID is the only required piece of information to utilize Chainlink’s oracle service. At the current release level, Job IDs are uniquely generated each time it’s deployed. Therefore every data request has a pre-determined Chainlink node that can fulfill it. In other words, Chainlink has yet fully implemented the decentralized nature of the original design.

LinkToken Smart Contract

In a decentralized world, it’s critical to have a robust mechanism to both incentivize honest behaviors and ensure there is enough deterrence against bad actors. Chainlink uses an economic model to achieve this with the LINK token. The LinkToken contract is an ERC20 token implementation so it offers the standard operations like transfer, approve and transferFrom. It also implements the ERC677 interface to provide a transferAndCall function to allow payment and invocation to be done with a single transaction.

The LINK token is used in two places:

• Keeping node operators honest: if a Chainlink node wants to offer its service, it can be required to deposit a certain amount of LINK tokens as collateral in the Oracle contract and then register itself with the Oracle contract. The Oracle contract will make a judgement on the node operator performance and refuse to refund the locked funds to misbehaving nodes
• Payment from client to node operators: when a node operator publishes a job specification, it can set a price for clients to utilize its service. Client contracts will then have to present payment in LINK tokens along with the job request

Kaleido Chainlink service offers a funding pool of 1 billion LINK tokens for each environment, for use only within Kaleido blockchain networks (these LINK tokens don’t have a monetary value). All consortium members are able to draw LINK tokens from the faucet using the service console UI or Kaleido Platform API. However, all Chainlink nodes are configured to allow zero payment for executing job requests. As a result, all built-in tasks are “free of charge” without requiring LINK payments. A Chainlink service administrator can still define new types of external adapters

Jobs

At the end of the day, Oracle is about doing some work, like executing some logic or obtaining external data, that is not possible inside the constrained on-chain environments like the EVM. Chainlink defines Jobs as the model that describes the work to execute. The following is an example of a job specification:

{
 "initiators": [{
   "type": "RunLog",
   "params": { }
 }],
 "tasks": [{
   "type": "HTTPGet",
   "confirmations": 0,
   "params": { "get": "https://bitstamp.net/api/ticker/" }
 }, {
   "type": "JSONParse",
   "params": { "path": [ "last" ] }
 }, {
   "type": "Multiply",
   "params": { "times": 100 }
 }, {
   "type": "EthUint256"
 }, {
   "type": "EthTx"
 }]
}

Each job spec has two sections:

• initiators: this describes how the job is triggered. A job can be launched by an event published by the target blockchain or launched on a pre-defined schedule once or in a repeated pattern, or by HTTP requests against the Chainlink node directly
• tasks: specifies the series of steps to take in order to accomplish the job. The spec can use both built-in tasks like HTTPGet, JSONParse, etc., and custom-built tasks using the Chainlink adaptor extensions.

A job needs to be registered on a Chainlink node using the job spec. After registration, a unique job ID is provided by the node. This is the identifier to use for the client to request for the execution to occur.

Putting It All Together

A typical workflow goes like this:

• Step 1: the client smart contract is called by a transaction to execute a function, whose implementation requires external data.  It prepares a request using a Job ID that has been acquired a priori, plus the parameter values it wants to use for the Job execution. It then calls the Oracle contract with the request
• Step 2: The Oracle contract publishes an event with the job ID and the parameter values, along with the promised payment (in LINK tokens) by the client contract
• Step 3: All Chainlink nodes attached to the blockchain network are notified of the Job request via the event
• Step 4: The Chainlink node that had the Job ID deployed on it realizes it’s the responsible party for the request. It combines the Job Specification corresponding to the Job ID, with the parameters contained in the event, to form the execution context for the job
• Step 5: After having acquired the desired data, the Chainlink node submits a transaction to the Oracle contract, signaling the fulfillment of the Job request. The transaction payload contains the job execution results
• Step 6: The Oracle contract uses the request ID to look up the corresponding requestor, and calls back the requestor contract with the Oracle result data

At this point, the client smart contract has successfully gotten hold of the data from the outside world and proceeds to process the original transaction request by the client application.

What Does Chainlink Do?

Using Chainlink is fun and is critical to enable your blockchain application to talk to the outside world, but it could also be a bit daunting given the amount of custom code needed to get things working end to end. To help developers adopt this essential technology for blockchain-based applications, the Kaleido team has published two samples:

• Truffle project for developing Chainlink client smart contracts
• Sample application written in JavaScript that demonstrates how to interact with Chainlink client smart contracts

Watch the demo video below to see an end-to-end walkthrough of using Chainlink on Kaleido.

Looking forward to hearing how you are using Chainlink!

If there is interest in learning more or seeing a live demo of the Kaleido platform, feel free to contact us. You can also try Kaleido free!