ChainlinkClient API Reference

Index

Methods

Events

Modifiers

Constants

Structs

Methods

Below you'll find each helper explained in greater detail alongside respective implementation examples to help you leverage these methods once you start building your own Chainlinked contract.

After the function signature and a short description, two code examples are provided, one focusing on the exact usage of the method and one where the helper is presented in the context of a full contract.

setChainlinkOracle

function _setChainlinkOracle(
  address _oracle
)

Sets a private storage variable provided for convenience if your contract only needs to talk to one oracle and you do not want to specify it on every request. Once an oracle is set with setChainlinkOracle that is the address used with sendChainlinkRequest.

Retrieve the oracle address using chainlinkOracleAddress. These getters and setters are provided to enforce that changes to the oracle are explicitly made in the code.

constructor(address _oracle)
{
  _setChainlinkOracle(_oracle);
}

setChainlinkToken

_setChainlinkToken(
  address _link
)

Sets the stored address for the LINK token which is used to send requests to Oracles. There are different token addresses on different network. See LINK Token Contracts for the address of the LINK token on the network you're deploying to.

constructor(address _link)
  public
{
  _setChainlinkToken(_link);
}

buildChainlinkRequest

Use buildOperatorRequest function if the oracle is an Operator contract.

function _buildChainlinkRequest(
    bytes32 _jobId,
    address _callbackAddress,
    bytes4 _callbackFunctionSignature
) returns (Chainlink.Request memory request)

Instantiates a Request from the Chainlink contract. A Request is a struct which contains the necessary parameters to be sent to the oracle contract. The buildChainlinkRequest function takes an ID, which can be a Job ID, a callback address to receive the resulting data, and a callback function signature to call on the callback address.

function requestPrice()
  public
{
  bytes32 jobId = "493610cff14346f786f88ed791ab7704";
  bytes4 selector = this.myCallback.selector;
  // build a request that calls the myCallback function defined
  //   below by specifying the address of this contract and the function
  //   selector of the myCallback
  Chainlink.Request memory request = _buildChainlinkRequest(
    jobId,
    address(this),
    selector);
}

buildOperatorRequest

This function is similar to buildChainlinkRequestfunction. One major difference is that buildOperatorRequest does not allow setting up the address of the callback. The callback address is set to the address of the calling contract.

It is recommended to use buildOperatorRequest but make sure the oracle you are contacting is an Operator contract.

function buildOperatorRequest(
    bytes32 _jobId,
    bytes4 _callbackFunctionSignature
) returns (Chainlink.Request memory request)

Instantiates a Request from the Chainlink contract. A Request is a struct that contains the necessary parameters to be sent to the oracle contract. The buildOperatorRequest function takes an ID, which can be a Job ID, and a callback function signature to call on the calling contract address.

function requestPrice()
  public
{
  bytes32 jobId = "493610cff14346f786f88ed791ab7704";
  bytes4 selector = this.myCallback.selector;
  // build a request that calls the myCallback function defined
  //   below by specifying the function selector of myCallback
  Chainlink.Request memory request = buildOperatorRequest(
    jobId,
    selector);
}

sendChainlinkRequest

Use sendOperatorRequest function if the oracle is an Operator contract.

function _sendChainlinkRequest(
    Chainlink.Request memory _req,
    uint256 _payment
) returns (bytes32 requestId)

Sends the request payload to the stored oracle address. It takes a Chainlink.Request and the amount of LINK to send amount as parameters. The request is serialized and calls oracleRequest on the address stored in chainlinkOracleAddress via the LINK token's transferAndCall method.

sendChainlinkRequest returns the ID of the request. If your application needs to, your contract can store that ID, but you don't need to. The ChainlinkClient helpers will store the ID under the hood, along with the oracle address, and use them when you call recordChainlinkFulfillment in your callback function to make sure only that the address you want can call your Chainlink callback function.

sendChainlinkRequest emits a ChainlinkRequested event containing the request ID, if you would like to use it in your Web3 application.

function requestPrice()
  public
{
  Chainlink.Request memory request = _buildChainlinkRequest(jobId, address(this), this.callback.selector);
  uint256 paymentAmount = 1 * LINK_DIVISIBILITY / 10; // Equivalent to 0.1 LINK

  // send the request that you just built
  _sendChainlinkRequest(request, paymentAmount);
}

sendChainlinkRequestTo

Use sendOperatorRequestTo function if the oracle is an Operator contract.

function _sendChainlinkRequestTo(
  address _oracle,
  Chainlink.Request memory _req,
  uint256 _payment
) returns (bytes32 requestId)

Similar to sendChainlinkRequest, sendChainlinkRequestTo sends a Request but allows the target oracle to be specified. It requires an address, a Request, and an amount, and returns the requestId. This allows a requesting contract to create and track requests sent to multiple oracle contract addresses.

sendChainlinkRequestTo emits a ChainlinkRequested event containing the request ID, if you would like to use it in your Web3 application.

function requestPriceFrom(address _oracle)
  public
{
  Chainlink.Request memory request = _buildChainlinkRequest(jobId, address(this), this.callback.callbackSelector);
  uint256 paymentAmount = 1 * LINK_DIVISIBILITY; // = 1 LINK

  // send the request that you just built to a specified oracle
  _sendChainlinkRequestTo(_oracle, request, paymentAmount);
}

sendOperatorRequest

This function is similar to sendChainlinkRequestfunction. It is recommended to use sendOperatorRequest but make sure the oracle you are contacting is an Operator contract.

function sendOperatorRequest(
    Chainlink.Request memory _req,
    uint256 _payment
) returns (bytes32 requestId)

The sendOperatorRequest function sends the request payload to the stored oracle address. It takes a Chainlink.Request and the amount of LINK to send amount as parameters. The request is serialized and calls operatorRequest on the address stored in chainlinkOracleAddress using the LINK token's transferAndCall method.

sendOperatorRequest returns the ID of the request. Optionally, your contract can store the ID if your application needs it. The ChainlinkClient helpers store the ID and the oracle address and use them when you call recordChainlinkFulfillment in your callback function. This ensures that only the specified address can call your Chainlink callback function.

sendOperatorRequest emits a ChainlinkRequested event containing the request ID that you can use in your Web3 application.

function requestPrice()
  public
{
  Chainlink.Request memory request = buildOperatorRequest(jobId, this.callback.selector);
  uint256 paymentAmount = 1 * LINK_DIVISIBILITY / 10; // Equivalent to 0.1 LINK

  // send the request that you just built
  sendOperatorRequest(request, paymentAmount);
}

sendOperatorRequestTo

This function is similar to sendChainlinkRequestTofunction. It is recommended to use sendOperatorRequestTo, but make sure the oracle you are contacting is an Operator contract.

function _sendChainlinkRequestTo(
  address _oracle,
  Chainlink.Request memory _req,
  uint256 _payment
) returns (bytes32 requestId)

Similar to sendOperatorRequest, sendOperatorRequestTo sends a Request but allows the target oracle to be specified. It requires an address, a Request, and an amount, and returns the requestId. This allows a requesting contract to create and track requests sent to multiple oracle contract addresses.

sendOperatorRequestTo emits a ChainlinkRequested event containing a request ID that you can use in your Web3 application.

function requestPriceFrom(address _oracle)
  public
{
  Chainlink.Request memory request = buildOperatorRequest(jobId, this.callback.callbackSelector);
  uint256 paymentAmount = 1 * LINK_DIVISIBILITY; // = 1 LINK

  // send the request that you just built to a specified oracle
  sendOperatorRequestTo(_oracle, request, paymentAmount);
}

validateChainlinkCallback

function validateChainlinkCallback(
    bytes32 _requestId
)

Used on fulfillment callbacks to ensure that the caller and requestId are valid. They protect ChainlinkClient callbacks from being called by malicious callers. validateChainlinkCallback allows for a request to be called

This is the method equivalent of the modifier recordChainlinkFulfillment. Either validateChainlinkCallback or recordChainlinkFulfillment should be used on all fulfillment functions to ensure that the caller and requestId are valid. Use the modifier or the method, not both.

validateChainlinkCallback emits a ChainlinkFulfilled event.

function myCallback(bytes32 _requestId, uint256 _price)
  public
{
  validateChainlinkCallback(_requestId);
  currentPrice = _price;
}

addChainlinkExternalRequest

function addChainlinkExternalRequest(
  address _oracle,
  bytes32 _requestId
)

addChainlinkExternalRequest allows a Chainlink contract to track unfulfilled requests that it hasn't created itself. For example, contract A creates a request and sets the callback for contract B. Contract B needs to know about the request created by contract A so that it can validate the callback when it is executed.

function expectResponseFor(bytes32 _requestId)
  public
{
  addChainlinkExternalRequest(chainlinkOracleAddress(), _requestId);
}

cancelChainlinkRequest

function _cancelChainlinkRequest(bytes32 _requestId,
    uint256 _payment,
    bytes4 _callbackFunc,
    uint256 _expiration
)

In case an oracle node does not respond, it may be necessary to retrieve the LINK used to pay for the unfulfilled request. The cancelChainlinkRequest will send the cancel request to the address used for the request, which transfers the amount of LINK back to the requesting contract, and delete it from the tracked requests.

The default expiration for a request is five minutes, after which it can be cancelled. The cancellation must be sent by the address which was specified as the callback location of the contract.

For the sake of efficient gas usage, only a hash of the request's parameters are stored onchain. In order to validate the terms of the request and that it can be calculated, the request parameters must be provided. Additionally, cancellation must be called by the address which the callback would otherwise have been called on.

cancelChainlinkRequest emits a ChainlinkCancelled event.

function cancelRequest(
    bytes32 _requestId,
    uint256 _payment,
    bytes4 _callbackFunc,
    uint256 _expiration
) public {
  _cancelChainlinkRequest(_requestId, _payment, _callbackFunc, _expiration);
}

useChainlinkWithENS

function useChainlinkWithENS(
  address _ens,
  bytes32 _node
)

Allows a Chainlink contract to store the addresses of the LINK token and oracle contract addresses without supplying the addresses themselves. We use ENS where available to resolve these addresses. It requires the address of the ENS contract and the node (which is a hash) for the domain.

If your Oracle provider supports using ENS for rolling upgrades to their oracle contract, once you've pointed your Chainlinked contract to the ENS records then you can update the records using updateChainlinkOracleWithENS.

address constant ROPSTEN_ENS = 0x112234455C3a32FD11230C42E7Bccd4A84e02010;
bytes32 constant ROPSTEN_CHAINLINK_ENS = 0xead9c0180f6d685e43522fcfe277c2f0465fe930fb32b5b415826eacf9803727;

constructor(){
  useChainlinkWithENS(ROPSTEN_ENS, ROPSTEN_CHAINLINK_ENS);
}

updateChainlinkOracleWithENS

function updateChainlinkOracleWithENS()

Updates the stored oracle contract address with the latest address resolved through the ENS contract. This requires the oracle provider to support listing their address on ENS.

This method only works after useChainlinkWithENS has been called on the contract.

function updateOracleAddressToLatest() public {
  updateChainlinkOracleWithENS();
}

chainlinkTokenAddress

function _chainlinkTokenAddress() returns (address)

The chainlinkTokenAddress function is a helper used to return the stored address of the Chainlink token. This variable is protected and so only made available through getters and setters.

function withdrawLink() public {
  LinkTokenInterface link = LinkTokenInterface(_chainlinkTokenAddress());

  require(link.transfer(msg.sender, link.balanceOf(address(this))), "Unable to transfer");
}

chainlinkOracleAddress

The chainlinkOracleAddress function is a helper used to return the stored address of the oracle contract.

function getOracle() public view returns (address) {
  return chainlinkOracleAddress();
}

Events

ChainlinkRequested

event ChainlinkRequested(
  bytes32 indexed id
)

Emitted when sendChainlinkRequest and sendChainlinkRequestTo are called. Includes the request ID as an event topic.

ChainlinkFulfilled

event ChainlinkFulfilled(
  bytes32 indexed id
)

Emitted when validateChainlinkCallback or recordChainlinkFulfillment are called. Includes the request ID as an event topic.

ChainlinkCancelled

event ChainlinkCancelled(
  bytes32 indexed id
)

Emitted when cancelChainlinkRequest is called. Includes the request ID as an event topic.

Constants

LINK_DIVISIBILITY

LINK_DIVISIBILITY is a uint256 constant to represent one whole unit of the LINK token (1000000000000000000). It can be used with another value to specify payment in an easy-to-read format, instead of hardcoding magic numbers.

uint256 constant private ORACLE_PAYMENT = 100 * LINK_DIVISIBILITY; // = 100 LINK

Modifiers

recordChainlinkFulfillment

recordChainlinkFulfillment is used on fulfillment callbacks to ensure that the caller and requestId are valid. This is the method equivalent of the method validateChainlinkCallback.

Either validateChainlinkCallback or recordChainlinkFulfillment should be used on all Chainlink callback functions to ensure that the sender and requestId are valid. They protect ChainlinkClient callbacks from being called by malicious callers. Do not call both of them, or your callback may revert before you can record the reported response.

function myCallback(bytes32 _requestId, uint256 _price)
  public
  recordChainlinkFulfillment(_requestId) // always validate callbacks
{
  currentPrice = _price;
}

Chainlink.Request

library Chainlink {
  struct Request {
    bytes32 id;
    address callbackAddress;
    bytes4 callbackFunctionId;
    uint256 nonce;
    Buffer.buffer buf;
  }
}

The Chainlink Request struct encapsulates all of the fields needed for a Chainlink request and its corresponding response callback.

The Chainlink protocol aims to be flexible and not restrict application developers. The Solidity Chainlink Request model is a great example of that. It is exceptionally flexible, given the limitations of Solidity. The request can contain an arbitrary amount of keys and values to be passed offchain to the oracles for each request. It does so by converting the parameters into CBOR, and then storing them in a buffer. This allows for any number of parameters all of different types to be encoded onchain.

The request's ID is generated by hashing the sender's address and the request's nonce. This scheme ensures that only the requester can generate their request ID, and no other contract can trigger a response from an oracle with that ID. New requests whose IDs match an unfulfilled request ID will not be accepted by the oracle.

Attributes

Methods

add

function add(
  Request memory self,
  string _key,
  string _value
)

Add a string value to the run request parameters. Commonly used for get with jobs using httpGet tasks.

function requestEthereumPrice()
  public
{
  Chainlink.Request memory req = _buildChainlinkRequest(jobId, this, this.fulfill.selector);

  req._add("get", "https://min-api.cryptocompare.com/data/price?fsym=ETH&tsyms=USD,EUR,JPY");

  _sendChainlinkRequest(req, 1 * LINK_DIVISIBILITY); // =1 LINK
}

addBytes

function addBytes(
  Request memory self,
  string _key,
  bytes _value
)

Add a CBOR bytes type value to the run request parameters.

function requestEmojiPopularity(bytes _unicode)
  public
{
  Chainlink.Request memory req = _buildChainlinkRequest(jobId, this, this.fulfill.selector);

  req.addBytes("emojiUnicode", _unicode);

  _sendChainlinkRequest(req, LINK_DIVISIBILITY * 1);
}

Note that this can also be used as a workaround to pass other data types like arrays or addresses. For instance, to add an address, one would first encode it using abi.encode then pass the result to addBytes:

Chainlink.Request memory req = _buildChainlinkRequest(jobId, this, this.fulfill.selector);

req.addBytes("address", abi.encode(msg.sender)); // msg.sender used in this example. Replace it with your address

addInt

function addInt(
  Request memory self,
  string _key,
  int256 _value
)

Add a CBOR signed integer type value to the run request parameters. Commonly used with the times parameter of any job using a multiply task.

function requestPrice()
  public
{
  Chainlink.Request memory req = _buildChainlinkRequest(jobId, this, this.fulfill.selector);

  req._addInt("times", 100);

  _sendChainlinkRequest(req, LINK_DIVISIBILITY * 1);
}

addUint

function addUint(
  Request memory self,
  string _key,
  uint256 _value
)

Add a CBOR unsigned integer type value to the run request parameters. Commonly used with the times parameter of any job using a multiply task.

function requestPrice()
  public
{
  Chainlink.Request memory req = _buildChainlinkRequest(jobId, this, this.fulfill.selector);

  req.addUint("times", 100);

  _sendChainlinkRequest(req, LINK_DIVISIBILITY * 1);
}

addStringArray

function addStringArray(
  Request memory self,
  string _key,
  string[] memory _values
)

Add a CBOR array of strings to the run request parameters. Commonly used with the path parameter for any job including a jsonParse task.

function requestPrice(string _currency)
  public
{
  Chainlink.Request memory req = _buildChainlinkRequest(JOB_ID, this, this.myCallback.selector);
  string[] memory path = new string[](2);
  path[0] = _currency;
  path[1] = "recent";

  // specify templated fields in a job specification
  req.addStringArray("path", path);

  _sendChainlinkRequest(req, PAYMENT);
}

setBuffer

function setBuffer(
  Request memory self,
  bytes _data
)

Set the CBOR payload directly on the request object, avoiding the cost of encoding the parameters in CBOR. This can be helpful when reading the bytes from storage or having them passed in from offchain where they were pre-encoded.

function requestPrice(bytes _cbor)
  public
{
  Chainlink.Request memory req = _buildChainlinkRequest(JOB_ID, this, this.myCallback.selector);

  req.setBuffer(_cbor);

  _sendChainlinkRequest(req, PAYMENT);
}