1. Home
  2. Docs
  3. SmartContracts
  4. SmartContracts Tutorials
  5. ChainlinkClient Library

ChainlinkClient Library

Helpers Index

The ChainlinkClient Library can be imported into contracts directly. Once imported, contracts are considered to be “Chainlinked,” meaning developers can now leverage the different helper methods offered to simplify the process of making a Chainlink request on-chain for external data.

Security of Helpers

Given the nuanced security of smart contracts, the ChainlinkClient attempts to avoid assumptions about your contract logic. In addition providing flexible APIs, this means that inheriting from ChainlinkClient does not include any functionality by default.
All storage, methods, and constants provided by the ChainlinkClient contract are of either private or internal visibility. This means that contract developers need to explicitly create public methods to expose Chainlink functionality.
Still, unexpected behavior can still be introduced. Please take caution when developing your smart contracts, and reach out to us at support@smartcontract.com or on Gitter with any Solidity related questions.

pragma solidity 0.4.24;

import "./Chainlink.sol";
import "./ENSResolver.sol";
import "./interfaces/ENSInterface.sol";
import "./interfaces/LinkTokenInterface.sol";
import "./interfaces/ChainlinkRequestInterface.sol";
import "./interfaces/PointerInterface.sol";
import "openzeppelin-solidity/contracts/math/SafeMath.sol";

 * @title The ChainlinkClient contract
 * @notice Contract writers can inherit this contract in order to create requests for the
 * Chainlink network
contract ChainlinkClient {
  using Chainlink for Chainlink.Request;
  using SafeMath for uint256;

  uint256 constant internal LINK = 10**18;
  uint256 constant private AMOUNT_OVERRIDE = 0;
  address constant private SENDER_OVERRIDE = 0x0;
  uint256 constant private ARGS_VERSION = 1;
  bytes32 constant private ENS_TOKEN_SUBNAME = keccak256("link");
  bytes32 constant private ENS_ORACLE_SUBNAME = keccak256("oracle");
  address constant private LINK_TOKEN_POINTER = 0xC89bD4E1632D3A43CB03AAAd5262cbe4038Bc571;

  ENSInterface private ens;
  bytes32 private ensNode;
  LinkTokenInterface private link;
  ChainlinkRequestInterface private oracle;
  uint256 private requests = 1;
  mapping(bytes32 => address) private pendingRequests;

  event ChainlinkRequested(bytes32 indexed id);
  event ChainlinkFulfilled(bytes32 indexed id);
  event ChainlinkCancelled(bytes32 indexed id);

   * @notice Creates a request that can hold additional parameters
   * @param _specId The Job Specification ID that the request will be created for
   * @param _callbackAddress The callback address that the response will be sent to
   * @param _callbackFunctionSignature The callback function signature to use for the callback address
   * @return A Chainlink Request struct in memory
  function buildChainlinkRequest(
    bytes32 _specId,
    address _callbackAddress,
    bytes4 _callbackFunctionSignature
  ) internal pure returns (Chainlink.Request memory) {
    Chainlink.Request memory req;
    return req.initialize(_specId, _callbackAddress, _callbackFunctionSignature);

   * @notice Creates a Chainlink request to the stored oracle address
   * @dev Calls `chainlinkRequestTo` with the stored oracle address
   * @param _req The initialized Chainlink Request
   * @param _payment The amount of LINK to send for the request
   * @return The request ID
  function sendChainlinkRequest(Chainlink.Request memory _req, uint256 _payment)
    returns (bytes32)
    return sendChainlinkRequestTo(oracle, _req, _payment);

   * @notice Creates a Chainlink request to the specified oracle address
   * @dev Generates and stores a request ID, increments the local nonce, and uses `transferAndCall` to
   * send LINK which creates a request on the target oracle contract.
   * Emits ChainlinkRequested event.
   * @param _oracle The address of the oracle for the request
   * @param _req The initialized Chainlink Request
   * @param _payment The amount of LINK to send for the request
   * @return The request ID
  function sendChainlinkRequestTo(address _oracle, Chainlink.Request memory _req, uint256 _payment)
    returns (bytes32 requestId)
    requestId = keccak256(abi.encodePacked(this, requests));
    _req.nonce = requests;
    pendingRequests[requestId] = _oracle;
    emit ChainlinkRequested(requestId);
    require(link.transferAndCall(_oracle, _payment, encodeRequest(_req)), "unable to transferAndCall to oracle");
    requests += 1;

    return requestId;

   * @notice Allows a request to be cancelled if it has not been fulfilled
   * @dev Requires keeping track of the expiration value emitted from the oracle contract.
   * Deletes the request from the `pendingRequests` mapping.
   * Emits ChainlinkCancelled event.
   * @param _requestId The request ID
   * @param _payment The amount of LINK sent for the request
   * @param _callbackFunc The callback function specified for the request
   * @param _expiration The time of the expiration for the request
  function cancelChainlinkRequest(
    bytes32 _requestId,
    uint256 _payment,
    bytes4 _callbackFunc,
    uint256 _expiration
    ChainlinkRequestInterface requested = ChainlinkRequestInterface(pendingRequests[_requestId]);
    delete pendingRequests[_requestId];
    emit ChainlinkCancelled(_requestId);
    requested.cancelOracleRequest(_requestId, _payment, _callbackFunc, _expiration);

   * @notice Sets the stored oracle address
   * @param _oracle The address of the oracle contract
  function setChainlinkOracle(address _oracle) internal {
    oracle = ChainlinkRequestInterface(_oracle);

   * @notice Sets the LINK token address
   * @param _link The address of the LINK token contract
  function setChainlinkToken(address _link) internal {
    link = LinkTokenInterface(_link);

   * @notice Sets the Chainlink token address for the public
   * network as given by the Pointer contract
  function setPublicChainlinkToken() internal {

   * @notice Retrieves the stored address of the LINK token
   * @return The address of the LINK token
  function chainlinkTokenAddress()
    returns (address)
    return address(link);

   * @notice Retrieves the stored address of the oracle contract
   * @return The address of the oracle contract
  function chainlinkOracleAddress()
    returns (address)
    return address(oracle);

   * @notice Allows for a request which was created on another contract to be fulfilled
   * on this contract
   * @param _oracle The address of the oracle contract that will fulfill the request
   * @param _requestId The request ID used for the response
  function addChainlinkExternalRequest(address _oracle, bytes32 _requestId)
    pendingRequests[_requestId] = _oracle;

   * @notice Sets the stored oracle and LINK token contracts with the addresses resolved by ENS
   * @dev Accounts for subnodes having different resolvers
   * @param _ens The address of the ENS contract
   * @param _node The ENS node hash
  function useChainlinkWithENS(address _ens, bytes32 _node)
    ens = ENSInterface(_ens);
    ensNode = _node;
    bytes32 linkSubnode = keccak256(abi.encodePacked(ensNode, ENS_TOKEN_SUBNAME));
    ENSResolver resolver = ENSResolver(ens.resolver(linkSubnode));

   * @notice Sets the stored oracle contract with the address resolved by ENS
   * @dev This may be called on its own as long as `useChainlinkWithENS` has been called previously
  function updateChainlinkOracleWithENS()
    bytes32 oracleSubnode = keccak256(abi.encodePacked(ensNode, ENS_ORACLE_SUBNAME));
    ENSResolver resolver = ENSResolver(ens.resolver(oracleSubnode));

   * @notice Encodes the request to be sent to the oracle contract
   * @dev The Chainlink node expects values to be in order for the request to be picked up. Order of types
   * will be validated in the oracle contract.
   * @param _req The initialized Chainlink Request
   * @return The bytes payload for the `transferAndCall` method
  function encodeRequest(Chainlink.Request memory _req)
    returns (bytes memory)
    return abi.encodeWithSelector(
      SENDER_OVERRIDE, // Sender value - overridden by onTokenTransfer by the requesting contract's address
      AMOUNT_OVERRIDE, // Amount value - overridden by onTokenTransfer by the actual amount of LINK sent

   * @notice Ensures that the fulfillment is valid for this contract
   * @dev Use if the contract developer prefers methods instead of modifiers for validation
   * @param _requestId The request ID for fulfillment
  function validateChainlinkCallback(bytes32 _requestId)
    // solium-disable-next-line no-empty-blocks

   * @dev Reverts if the sender is not the oracle of the request.
   * Emits ChainlinkFulfilled event.
   * @param _requestId The request ID for fulfillment
  modifier recordChainlinkFulfillment(bytes32 _requestId) {
    require(msg.sender == pendingRequests[_requestId], "Source must be the oracle of the request");
    delete pendingRequests[_requestId];
    emit ChainlinkFulfilled(_requestId);

   * @dev Reverts if the request is already pending
   * @param _requestId The request ID for fulfillment
  modifier notPendingRequest(bytes32 _requestId) {
    require(pendingRequests[_requestId] == address(0), "Request is already pending");



Sets the stored address for the oracle contract


Sets the stored address for the LINK token


Sets the LINK token address for the detected public network


Instantiates a Request object with the required parameters


Sends the request payload to the stored address stored as chainlinkOracleAddress


Sends a request to the oracle address specified


Secures the fulfillment callback to make sure it is only called by permissioned senders


Allows a Chainlinked contract to track unfulfilled requests that it hasn’t created itself


Cancels Chainlink requests attempting to contact an unresponsive node


Looks up the addresses of the LINK token and Oracle contract through ENS


Updates the stored oracle address with the latest address resolved through ENS


Returns the stored address of the LINK token


Returns the stored address of the oracle contract



Emitted from a Chainlinked contract when a request is sent to an oracle


Emitted from a Chainlinked contract when a request is fulfilled by an oracle


Emitted from a Chainlinked contract when a request is cancelled



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



Helper uint256 to represent the divisibility of a LINK token. Equivalent to 10^18



All of the parameters that can be passed over in a Chainlink request

Was this article helpful to you? Yes No

How can we help?

Leave a Reply

Your email address will not be published. Required fields are marked *