Skip to content

Document chainlinkClient operator functions #956

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dwightjl merged 5 commits into from
Aug 25, 2022
Merged

Document chainlinkClient operator functions #956

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3b1ebf8
Document chainlinkClient operator functions
aelmanaa Aug 24, 2022
8563dd3
fix hyperinks
aelmanaa Aug 24, 2022
40c5d12
Apply suggestions from code review
aelmanaa Aug 24, 2022
54bea0c
Merge branch 'main' into aelmanaa/any-api-review-api-reference
aelmanaa Aug 24, 2022
c9175a3
Merge branch 'main' into aelmanaa/any-api-review-api-reference
aelmanaa Aug 24, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 114 additions & 15 deletions docs/any-api/api-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,26 +5,32 @@ date: Last Modified
title: 'ChainlinkClient API Reference'
permalink: 'docs/any-api/api-reference/'
---
API reference for [`ChainlinkClient`](https://github.com/smartcontractkit/chainlink/blob/master/contracts/src/v0.8/ChainlinkClient.sol).

> 📘 API reference for `ChainlinkClient` [contract](https://github.com/smartcontractkit/chainlink/blob/master/contracts/src/v0.8/ChainlinkClient.sol).
>
> `ChainlinkClient` contracts can communicate with legacy `Oracle` [contracts](https://github.com/smartcontractkit/chainlink/blob/develop/contracts/src/v0.4/Oracle.sol) or `Operator` [contracts](https://github.com/smartcontractkit/chainlink/blob/develop/contracts/src/v0.7/Operator.sol).

## Index

### Methods

| Name | Description |
| :------------------------------------------------------------ | :---------------------------------------------------------------------------------------- |
| [setChainlinkOracle](#setchainlinkoracle) | Sets the stored address for the oracle contract |
| [setChainlinkToken](#setchainlinktoken) | Sets the stored address for the LINK token |
| [buildChainlinkRequest](#buildchainlinkrequest) | Instantiates a Request object with the required parameters |
| [sendChainlinkRequest](#sendchainlinkrequest) | Sends the request payload to the stored address stored as chainlinkOracleAddress |
| [sendChainlinkRequestTo](#sendchainlinkrequestto) | Sends a request to the oracle address specified |
| [validateChainlinkCallback](#validatechainlinkcallback) | Secures the fulfillment callback to make sure it is only called by permissioned senders |
| [addChainlinkExternalRequest](#addchainlinkexternalrequest) | Allows a Chainlinked contract to track unfulfilled requests that it hasn't created itself |
| [cancelChainlinkRequest](#cancelchainlinkrequest) | Cancels Chainlink requests attempting to contact an unresponsive node |
| [useChainlinkWithENS](#usechainlinkwithens) | Looks up the addresses of the LINK token and Oracle contract through ENS |
| [updateChainlinkOracleWithENS](#updatechainlinkoraclewithens) | Updates the stored oracle address with the latest address resolved through ENS |
| [chainlinkTokenAddress](#chainlinktokenaddress) | Returns the stored address of the LINK token |
| [chainlinkOracleAddress](#chainlinkoracleaddress) | Returns the stored address of the oracle contract |
| Name | Description |
| :------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [setChainlinkOracle](#setchainlinkoracle) | Sets the stored address for the oracle contract |
| [setChainlinkToken](#setchainlinktoken) | Sets the stored address for the LINK token |
| [buildChainlinkRequest](#buildchainlinkrequest) | Instantiates a Request object with the required parameters |
| [buildOperatorRequest](#buildoperatorrequest) | Instantiates a Request object with the required parameters. **Note** the oracle must be an `Operator` [contract](https://github.com/smartcontractkit/chainlink/blob/develop/contracts/src/v0.7/Operator.sol) |
| [sendChainlinkRequest](#sendchainlinkrequest) | Sends the request payload to the stored address stored as chainlinkOracleAddress |
| [sendChainlinkRequestTo](#sendchainlinkrequestto) | Sends a request to the oracle address specified |
| [sendOperatorRequest](#sendoperatorrequest) | Sends the request payload to the stored address stored as chainlinkOracleAddress. **Note** the oracle must be an `Operator` [contract](https://github.com/smartcontractkit/chainlink/blob/develop/contracts/src/v0.7/Operator.sol) |
| [sendOperatorRequestTo](#sendoperatorrequestto) | Sends a request to the oracle address specified. **Note** the oracle must be an `Operator` [contract](https://github.com/smartcontractkit/chainlink/blob/develop/contracts/src/v0.7/Operator.sol) |
| [validateChainlinkCallback](#validatechainlinkcallback) | Secures the fulfillment callback to make sure it is only called by permissioned senders |
| [addChainlinkExternalRequest](#addchainlinkexternalrequest) | Allows a Chainlinked contract to track unfulfilled requests that it hasn't created itself |
| [cancelChainlinkRequest](#cancelchainlinkrequest) | Cancels Chainlink requests attempting to contact an unresponsive node |
| [useChainlinkWithENS](#usechainlinkwithens) | Looks up the addresses of the LINK token and Oracle contract through ENS |
| [updateChainlinkOracleWithENS](#updatechainlinkoraclewithens) | Updates the stored oracle address with the latest address resolved through ENS |
| [chainlinkTokenAddress](#chainlinktokenaddress) | Returns the stored address of the LINK token |
| [chainlinkOracleAddress](#chainlinkoracleaddress) | Returns the stored address of the oracle contract |

### Events

Expand Down Expand Up @@ -97,6 +103,8 @@ constructor(address _link)

### buildChainlinkRequest

> 📘 Use `buildOperatorRequest` [function](#buildoperatorrequest) if the oracle is an `Operator` [contract](https://github.com/smartcontractkit/chainlink/blob/develop/contracts/src/v0.7/Operator.sol).

```solidity example
function buildChainlinkRequest(
bytes32 _jobId,
Expand All @@ -123,8 +131,38 @@ function requestPrice()
}
```

### buildOperatorRequest

> 📘 This function is similar to `buildChainlinkRequest`[function](#buildchainlinkrequest). 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](https://github.com/smartcontractkit/chainlink/blob/develop/contracts/src/v0.7/Operator.sol).

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

Instantiates a _Request_ from the Chainlink contract. A [Request](#chainlinkrequest) 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](/docs/jobs/), and a callback function signature to call on the calling contract address.

```solidity example
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](#sendoperatorrequest) if the oracle is an `Operator` [contract](https://github.com/smartcontractkit/chainlink/blob/develop/contracts/src/v0.7/Operator.sol).

```solidity
function sendChainlinkRequest(
Chainlink.Request memory _req,
Expand Down Expand Up @@ -152,6 +190,8 @@ function requestPrice()

### sendChainlinkRequestTo

> 📘 Use `sendOperatorRequestTo` [function](#sendoperatorrequestto) if the oracle is an `Operator` [contract](https://github.com/smartcontractkit/chainlink/blob/develop/contracts/src/v0.7/Operator.sol).

```solidity
function sendChainlinkRequestTo(
address _oracle,
Expand All @@ -176,6 +216,65 @@ function requestPriceFrom(address _oracle)
}
```

### sendOperatorRequest

> 📘 This function is similar to `sendChainlinkRequest`[function](#sendchainlinkrequest).
> It is recommended to use `sendOperatorRequest` but make sure the oracle you are contacting is an `Operator` [contract](https://github.com/smartcontractkit/chainlink/blob/develop/contracts/src/v0.7/Operator.sol).

```solidity
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](#chainlinkrequest) 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](#chainlinkrequested) event containing the request ID that you can use in your Web3 application.

```solidity example
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 `sendChainlinkRequestTo`[function](#sendchainlinkrequestto).
> It is recommended to use `sendOperatorRequestTo`, but make sure the oracle you are contacting is an `Operator` [contract](https://github.com/smartcontractkit/chainlink/blob/develop/contracts/src/v0.7/Operator.sol).

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

Similar to [sendOperatorRequest](#sendoperatorrequest), `sendOperatorRequestTo` sends a [Request](#chainlinkrequest) 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](#chainlinkrequested) event containing a request ID that you can use in your Web3 application.

```solidity example
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

```solidity
Expand Down