Operator
Oracles must deploy an onchain contract to handle requests made through the LINK token (Read Basic Request Model to learn more).
When the Basic Request model was introduced, node operators had to deploy the legacy Oracle contract. However, these come with some limitations, and soon, we introduced operator contracts.
In addition to replacing oracle contracts, operator contracts come with additional features that add more security and flexibility for node operators.
Features
Multi-word response
In the EVM architecture, a word is made up of 32 bytes. One limitation of the Oracle.sol contract is that it limits responses to requests to 32 bytes.
Operator.sol doesn't have the same limitation as it supports a response made of multiple EVM words.
Factory deployment
To deploy an Oracle contract, each node operator has to manually compile and deploy Oracle.sol. The vast number of Solidity versions and steps involved in verifying the contract made it difficult for a client to verify that the deployed contract had not been tampered with. To fix this, node operators can use a factory to deploy an instance of the operator contract. Moreover, the factory exposes a getter for clients to check if it deployed a specific operator contract address.
Distributing funds to multiple addresses
A common pain point of node operators is keeping their addresses funded. Operator's distributeFunds method allows node operators to fund multiple addresses in a single transaction.
Flexibility and security
By using multiple externally-owned accounts (EOAs) on Chainlink nodes and forwarder contracts, node operators can set up different transaction-sending strategies.
As discussed in the forwarder contracts page:
- Chainlink nodes' EOAs are hot wallets that fulfill requests.
- These EOAs can be associated with one or multiple forwarder contracts. The forwarder's owner must whitelist them to call the forward function. One operator contract owns one or multiple forwarder contracts.
- Node operators manage their forwarder contracts through operator contracts. They use a secure wallet such as hardware or a multisig wallet as the operator's owner account.
API reference
The operator contract inherits AuthorizedReceiver and ConfirmedOwnerWithProposal. Read AuthorizedReceiver and ConfirmedOwnerWithProposal API references.
Methods
oracleRequest
function oracleRequest(address sender, uint256 payment, bytes32 specId, address callbackAddress, bytes4 callbackFunctionId, uint256 nonce, uint256 dataVersion, bytes data) external
Creates the Chainlink request. This is backwards compatible API with Oracle.sol contracts, but the behavior changes because callbackAddress is assumed to be the same as the request sender.
Parameters
| Name | Type | Description |
|---|---|---|
| sender | address | The sender of the request |
| payment | uint256 | The amount of payment given (specified in wei) |
| specId | bytes32 | The Job Specification ID |
| callbackAddress | address | The consumer of the request |
| callbackFunctionId | bytes4 | The callback function ID for the response |
| nonce | uint256 | The nonce sent by the requester |
| dataVersion | uint256 | The specified data version |
| data | bytes | The extra request parameters |
operatorRequest
function operatorRequest(address sender, uint256 payment, bytes32 specId, bytes4 callbackFunctionId, uint256 nonce, uint256 dataVersion, bytes data) external
Creates the Chainlink request. Stores the hash of the params as the onchain commitment for the request. Emits OracleRequest event for the Chainlink node to detect.
Parameters
| Name | Type | Description |
|---|---|---|
| sender | address | The sender of the request |
| payment | uint256 | The amount of payment given (specified in wei) |
| specId | bytes32 | The Job Specification ID |
| callbackFunctionId | bytes4 | The callback function ID for the response |
| nonce | uint256 | The nonce sent by the requester |
| dataVersion | uint256 | The specified data version |
| data | bytes | The extra request parameters |
fulfillOracleRequest
function fulfillOracleRequest(bytes32 requestId, uint256 payment, address callbackAddress, bytes4 callbackFunctionId, uint256 expiration, bytes32 data) external returns (bool)
Called by the Chainlink node to fulfill requests. Given params must hash back to the commitment stored from oracleRequest. Will call the callback address' callback function without bubbling up error checking in a require so that the node can get paid. Emits OracleResponse event.
Parameters
| Name | Type | Description |
|---|---|---|
| requestId | bytes32 | The fulfillment request ID that must match the requester's |
| payment | uint256 | The payment amount that will be released for the oracle (specified in wei) |
| callbackAddress | address | The callback address to call for fulfillment |
| callbackFunctionId | bytes4 | The callback function ID to use for fulfillment |
| expiration | uint256 | The expiration that the node should respond by before the requester can cancel |
| data | bytes32 | The data to return to the consuming contract |
Return values
| Name | Type | Description |
|---|---|---|
| bool | Status if the external call was successful |
fulfillOracleRequest2
function fulfillOracleRequest2(bytes32 requestId, uint256 payment, address callbackAddress, bytes4 callbackFunctionId, uint256 expiration, bytes data) external returns (bool)
Called by the Chainlink node to fulfill requests with multi-word support. Given params must hash back to the commitment stored from oracleRequest. Will call the callback address' callback function without bubbling up error checking in a require so that the node can get paid. Emits OracleResponse event.
Parameters
| Name | Type | Description |
|---|---|---|
| requestId | bytes32 | The fulfillment request ID that must match the requester's |
| payment | uint256 | The payment amount that will be released for the oracle (specified in wei) |
| callbackAddress | address | The callback address to call for fulfillment |
| callbackFunctionId | bytes4 | The callback function ID to use for fulfillment |
| expiration | uint256 | The expiration that the node should respond by before the requester can cancel |
| data | bytes | The data to return to the consuming contract |
Return values
| Name | Type | Description |
|---|---|---|
| bool | Status if the external call was successful |
transferOwnableContracts
function transferOwnableContracts(address[] ownable, address newOwner) external
Transfer the ownership of ownable contracts. This is primarily intended for authorized forwarders but could possibly be extended to work with future contracts.
Parameters
| Name | Type | Description |
|---|---|---|
| ownable | address[] | list of addresses to transfer |
| newOwner | address | address to transfer ownership to |
acceptOwnableContracts
function acceptOwnableContracts(address[] ownable) public
Accept the ownership of an ownable contract. This is primarily intended for authorized forwarders but could possibly be extended to work with future contracts. Emits OwnableContractAccepted event.
Must be the pending owner on the contract
Parameters
| Name | Type | Description |
|---|---|---|
| ownable | address[] | list of addresses of Ownable contracts to accept |
setAuthorizedSendersOn
function setAuthorizedSendersOn(address[] targets, address[] senders) public
Sets the fulfillment permission for senders on targets. Emits TargetsUpdatedAuthorizedSenders event.
Parameters
| Name | Type | Description |
|---|---|---|
| targets | address[] | The addresses to set permissions on |
| senders | address[] | The addresses that are allowed to send updates |
acceptAuthorizedReceivers
function acceptAuthorizedReceivers(address[] targets, address[] senders) external
Accepts ownership of ownable contracts and then immediately sets the authorized sender list on each of the newly owned contracts. This is primarily intended for authorized forwarders but could possibly be extended to work with future contracts.
Parameters
| Name | Type | Description |
|---|---|---|
| targets | address[] | The addresses to set permissions on |
| senders | address[] | The addresses that are allowed to send updates |
withdraw
function withdraw(address recipient, uint256 amount) external
Allows the node operator to withdraw earned LINK to a given address recipient.
The owner of the contract can be another wallet and does not have to be a Chainlink node
Parameters
| Name | Type | Description |
|---|---|---|
| recipient | address | The address to send the LINK token to |
| amount | uint256 | The amount to send (specified in wei) |
withdrawable
function withdrawable() external view returns (uint256)
Displays the amount of LINK that is available for the node operator to withdraw.
We use 1 in place of 0 in storage
Return values
| Name | Type | Description |
|---|---|---|
| uint256 | The amount of withdrawable LINK on the contract |
ownerForward
function ownerForward(address to, bytes data) external
Forward a call to another contract.
Only callable by the owner
Parameters
| Name | Type | Description |
|---|---|---|
| to | address | address |
| data | bytes | to forward |
ownerTransferAndCall
function ownerTransferAndCall(address to, uint256 value, bytes data) external returns (bool success)
Interact with other LinkTokenReceiver contracts by calling transferAndCall.
Parameters
| Name | Type | Description |
|---|---|---|
| to | address | The address to transfer to. |
| value | uint256 | The amount to be transferred. |
| data | bytes | The extra data to be passed to the receiving contract. |
Return values
| Name | Type | Description |
|---|---|---|
| success | bool | bool |
distributeFunds
function distributeFunds(address payable[] receivers, uint256[] amounts) external payable
Distribute funds to multiple addresses using ETH sent to this payable function.
Array length must be equal, ETH sent must equal the sum of amounts. A malicious receiver could cause the distribution to revert, in which case it is expected that the address is removed from the list.
Parameters
| Name | Type | Description |
|---|---|---|
| receivers | address payable[] | list of addresses |
| amounts | uint256[] | list of amounts |
cancelOracleRequest
function cancelOracleRequest(bytes32 requestId, uint256 payment, bytes4 callbackFunc, uint256 expiration) external
Allows recipient to cancel requests sent to this oracle contract. Will transfer the LINK sent for the request back to the recipient address. Given params must hash to a commitment stored on the contract in order for the request to be valid. Emits CancelOracleRequest event.
Parameters
| Name | Type | Description |
|---|---|---|
| requestId | bytes32 | The request ID |
| payment | uint256 | The amount of payment given (specified in wei) |
| callbackFunc | bytes4 | The requester's specified callback function selector |
| expiration | uint256 | The time of the expiration for the request |
cancelOracleRequestByRequester
function cancelOracleRequestByRequester(uint256 nonce, uint256 payment, bytes4 callbackFunc, uint256 expiration) external
Allows requester to cancel requests sent to this oracle contract. Will transfer the LINK sent for the request back to the recipient address. Given params must hash to a commitment stored on the contract in order for the request to be valid. Emits CancelOracleRequest event.
Parameters
| Name | Type | Description |
|---|---|---|
| nonce | uint256 | The nonce used to generate the request ID |
| payment | uint256 | The amount of payment given (specified in wei) |
| callbackFunc | bytes4 | The requester's specified callback function selector |
| expiration | uint256 | The time of the expiration for the request |
getChainlinkToken
function getChainlinkToken() public view returns (address)
Returns the address of the LINK token
This is the public implementation for chainlinkTokenAddress, which is an internal method of the ChainlinkClient contract.
Events
OracleRequest
event OracleRequest(bytes32 specId, address requester, bytes32 requestId, uint256 payment, address callbackAddr, bytes4 callbackFunctionId, uint256 cancelExpiration, uint256 dataVersion, bytes data)
CancelOracleRequest
event CancelOracleRequest(bytes32 requestId)
OracleResponse
event OracleResponse(bytes32 requestId)
OwnableContractAccepted
event OwnableContractAccepted(address acceptedContract)
TargetsUpdatedAuthorizedSenders
event TargetsUpdatedAuthorizedSenders(address[] targets, address[] senders, address changedBy)