Chainlink Developers

Welcome to the Chainlink documentation site. You'll find comprehensive guides and documentation to help you start working with Chainlink as quickly as possible, as well as support if you get stuck. Click here for an introductory walkthrough on how to create a Chainlink request on the Ropsten test network!

Chainlinked Functions

addExternalRequest

addExternalRequest allows a Chainlinked 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 knows that it's receiving a valid response.

Implementation example:

function addRequestFrom(address _oracle, bytes32 _requestId)
  public
{
  addExternalRequest(_oracle, _requestId);
}

cancelChainlinkRequest

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.

Implementation example:

function cancelRequest(bytes32 _requestId) public {
  cancelChainlinkRequest(_requestId);
}

chainlinkRequest

chainlinkRequest sends the request payload to the stored oracle address. It requires a Run and an amount as parameters and returns the requestId.

Implementation example:

chainlinkRequest(run, ORACLE_PAYMENT);

chainlinkRequestFrom

Similar to chainlinkRequest, chainlinkRequestFrom sends a request payload, but to the oracle address specified. It requires an address, a Run, and an amount, and returns the requestId. This allows a requesting contract to create and track requests sent to multiple oracle contract addresses.

Implementation example:

chainlinkRequestFrom(_oracle, run, ORACLE_PAYMENT);

chainlinkToken

The chainlinkToken function is a helper used to return the stored address of the Chainlink token.

Implementation examples:

function getChainlinkToken() public view returns (address) {
  return chainlinkToken();
}
function withdrawLink() public {
  LinkTokenInterface link = LinkTokenInterface(chainlinkToken());
  require(link.transfer(msg.sender, link.balanceOf(address(this))), "Unable to transfer");
}

checkChainlinkFulfillment

checkChainlinkFulfillment is a modifier that should be used on all fulfillment functions to ensure that the caller and requestId are valid.

Implementation example:

function fulfill(bytes32 _requestId, uint256 _price)
  public
  checkChainlinkFulfillment(_requestId)
{
  currentPrice = _price;
}

completeChainlinkFulfillment

If your programming style does not favor using modifiers, we give the completeChainlinkFulfillment as an alternative to the checkChainlinkFulfillment modifier. It will also ensure that the caller and requestId are valid.

Implementation example:

function fulfill(bytes32 _requestId, uint256 _price)
  public
{
  completeChainlinkFulfillment(_requestId);
  currentPrice = _price;
}

encodeRequest

encodeRequest is utilized by the chainlinkRequest and chainlinkRequestFrom methods to format the payload for the oracle contract. No additional implementation is needed by requesting or consuming contracts.

isUnfulfilledRequest

isUnfulfilledRequest is a modifier used in the addExternalRequest function. It will ensure that the external request does not already exist so that it cannot be overwritten. No additional implementation is needed by requesting or consuming contracts.

LINK

LINK 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.

Implementation example:

uint256 constant private ORACLE_PAYMENT = 1 * LINK;

newChainlinkWithENS

newChainlinkWithENS 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.

Implementation example:

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

constructor() public {
  newChainlinkWithENS(ROPSTEN_ENS, ROPSTEN_CHAINLINK_ENS);
}

newRun

newRun instantiates a Run from the ChainlinkLib contract. A Run is a struct with contains the necessary parameters to be sent to the oracle contract. The newRun function takes an ID, which can be a Job Spec ID or a Service Agreement ID, a callback address to receive the resulting data, and a callback function signature.

Implementation example:

ChainlinkLib.Run memory run = newRun(_jobId, this, this.fulfill.selector);

oracleAddress

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

Implementation example:

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

setLinkToken

setLinkToken sets the stored address for the LINK token.

Implementation example:

constructor(address _link, address _oracle) public {
  setLinkToken(_link);
  setOracle(_oracle);
}

setOracle

setOracle sets the stored address for the oracle contract.

Implementation example:

constructor(address _link, address _oracle) public {
  setLinkToken(_link);
  setOracle(_oracle);
}

updateOracleWithENS

updateOracleWithENS updates the stored oracle contract address with the latest address resolved through the ENS contract.

Implementation example:

function updateOracle() public {
  updateOracleWithENS();
}