NEW

CCIP is now available on testnet for all developers. Get started today.

Operator

Oracles must deploy an on-chain 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 Oracle contracts. 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
NameTypeDescription
senderaddressThe sender of the request
paymentuint256The amount of payment given (specified in wei)
specIdbytes32The Job Specification ID
callbackAddressaddressThe consumer of the request
callbackFunctionIdbytes4The callback function ID for the response
nonceuint256The nonce sent by the requester
dataVersionuint256The specified data version
databytesThe 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 on-chain commitment for the request. Emits OracleRequest event for the Chainlink node to detect.

Parameters
NameTypeDescription
senderaddressThe sender of the request
paymentuint256The amount of payment given (specified in wei)
specIdbytes32The Job Specification ID
callbackFunctionIdbytes4The callback function ID for the response
nonceuint256The nonce sent by the requester
dataVersionuint256The specified data version
databytesThe 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
NameTypeDescription
requestIdbytes32The fulfillment request ID that must match the requester's
paymentuint256The payment amount that will be released for the oracle (specified in wei)
callbackAddressaddressThe callback address to call for fulfillment
callbackFunctionIdbytes4The callback function ID to use for fulfillment
expirationuint256The expiration that the node should respond by before the requester can cancel
databytes32The data to return to the consuming contract
Return values
NameTypeDescription
boolStatus 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
NameTypeDescription
requestIdbytes32The fulfillment request ID that must match the requester's
paymentuint256The payment amount that will be released for the oracle (specified in wei)
callbackAddressaddressThe callback address to call for fulfillment
callbackFunctionIdbytes4The callback function ID to use for fulfillment
expirationuint256The expiration that the node should respond by before the requester can cancel
databytesThe data to return to the consuming contract
Return values
NameTypeDescription
boolStatus 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
NameTypeDescription
ownableaddress[]list of addresses to transfer
newOwneraddressaddress 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
NameTypeDescription
ownableaddress[]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
NameTypeDescription
targetsaddress[]The addresses to set permissions on
sendersaddress[]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
NameTypeDescription
targetsaddress[]The addresses to set permissions on
sendersaddress[]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
NameTypeDescription
recipientaddressThe address to send the LINK token to
amountuint256The 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
NameTypeDescription
uint256The 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
NameTypeDescription
toaddressaddress
databytesto forward

ownerTransferAndCall

function ownerTransferAndCall(address to, uint256 value, bytes data) external returns (bool success)

Interact with other LinkTokenReceiver contracts by calling transferAndCall.

Parameters
NameTypeDescription
toaddressThe address to transfer to.
valueuint256The amount to be transferred.
databytesThe extra data to be passed to the receiving contract.
Return values
NameTypeDescription
successboolbool

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
NameTypeDescription
receiversaddress payable[]list of addresses
amountsuint256[]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
NameTypeDescription
requestIdbytes32The request ID
paymentuint256The amount of payment given (specified in wei)
callbackFuncbytes4The requester's specified callback function selector
expirationuint256The 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
NameTypeDescription
nonceuint256The nonce used to generate the request ID
paymentuint256The amount of payment given (specified in wei)
callbackFuncbytes4The requester's specified callback function selector
expirationuint256The 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)

Stay updated on the latest Chainlink news