Automation Interfaces

Your Automation-compatible contracts may use the following interfaces. You can find them in the Chainlink repository. To understand how to implement these contracts, visit the Compatible Contracts page.

• If you want a log event to trigger your upkeep, use the ILogAutomation interface.
• If you want to use onchain state (excluding logs) in a custom calculation to trigger your upkeep, use AutomationCompatibleInterface interface.
• If you want to call a function just based on time, consider using a time-based upkeep.
• If you want to use Automation with Data Streams, use StreamsLookupCompatibleInterface interface.

ILogAutomation

To use log triggers, you will need to implement the ILogAutomation.sol interface in your smart contract. Click on the functions below to understand the parameters:

checkLog function

checkLog is a view function that will be simulated offchain once a log that matches your LogTriggerConfig has been emitted. You should parse the log data and the check if something needs to happen onchain. For example, it can trigger the retrieval of Data Streams reports. See the Data Streams Getting Started guide to see an example.

Parameters

Example

// SPDX-License-Identifier: SEE LICENSE IN LICENSE
pragma solidity ^0.8.7;

struct Log {
    uint256 index;
    uint256 timestamp;
    bytes32 txHash;
    uint256 blockNumber;
    bytes32 blockHash;
    address source;
    bytes32[] topics;
    bytes data;
}

function checkLog(
    Log calldata log,
    bytes memory checkData
) external returns (bool upkeepNeeded, bytes memory performData);

performUpkeep function for log triggers

This function contains the code that will be executed onchain to finalize the trade.

Parameters

AutomationCompatibleInterface

Custom logic upkeeps need to use the AutomationCompatibleInterface.sol interface. Click on one of the functions below to understand its parameters and limits.

checkUpkeep function

This view function contains the logic that runs offchain during every block as an eth_call to determine if performUpkeep should be executed onchain. To reduce onchain gas usage, attempt to do your gas intensive calculations offchain in checkUpkeep and pass the result to performUpkeep onchain. It is a best practice to import the AutomationCompatible.sol contract and use the cannotExecute modifier to ensure that the method can be used only for simulation purposes.

function checkUpkeep(
  bytes calldata checkData
) external view override returns (bool upkeepNeeded, bytes memory performData);

Below are the parameters and return values of the checkUpkeep function. Click each value to learn more about its design patterns and best practices:

Parameters:

• checkData: Fixed and specified at upkeep registration and used in every checkUpkeep. Can be empty (0x).

Return Values:

• upkeepNeeded: Boolean that when True will trigger the onchain performUpkeep call.
• performData: Bytes that will be used as input parameter when calling performUpkeep. If you would like to encode data to decode later, try abi.encode.

checkData

You can pass information into your checkUpkeep function from your upkeep registration to execute different code paths. For example, to check the balance on a specific address, set the checkData to abi encode the address. To learn how to create flexible upkeeps with checkData, please see our flexible upkeeps page.

function checkUpkeep(
    bytes calldata checkData
) public view returns (bool, bytes memory) {
    address wallet = abi.decode(checkData, (address));
    return (wallet.balance < 1 ether, bytes(""));
}

Tips on using checkData:

• Managing unbounded upkeeps: Limit the problem set of your onchain execution by creating a range bound for your upkeep to check and perform. This allows you to keep within predefined gas limits, which creates a predictable upper bound gas cost on your transactions. Break apart your problem into multiple upkeep registrations to limit the scope of work.

  Example: You could create an upkeep for each subset of addresses that you want to service. The ranges could be 0 to 49, 50 to 99, and 100 to 149.

• Managing code paths: Pass in data to your checkUpkeep to make your contract logic go down different code paths. This can be used in creative ways based on your use case needs.

  Example: You could support multiple types of upkeep within a single contract and pass a function selector through the checkData function.

performData

The response from checkUpkeep is passed to the performUpkeep function as performData. This allows you to perform complex and gas intensive calculations as a simulation offchain and only pass the needed data onchain.

You can create a highly flexible offchain computation infrastructure that can perform precise actions onchain by using checkData and performData. Both of these computations are entirely programmable.

performUpkeep function for custom logic triggers

When checkUpkeep returns upkeepNeeded == true, the Automation node broadcasts a transaction to the blockchain to execute your performUpkeep function onchain with performData as an input.

Ensure that your performUpkeep is idempotent. Your performUpkeep function should change state such that checkUpkeep will not return true for the same subset of work once said work is complete. Otherwise the Upkeep will remain eligible and result in multiple performances by the Chainlink Automation Network on the exactly same subset of work. As a best practice, always check conditions for your upkeep at the start of your performUpkeep function.

function performUpkeep(bytes calldata performData) external override;

Parameters:

• performData: Data which was passed back from the checkData simulation. If it is encoded, it can easily be decoded into other types by calling abi.decode. This data should always be validated against the contract's current state.

performData

You can perform complex and broad offchain computation, then execute onchain state changes on a subset that meets your conditions. This can be done by passing the appropriate inputs within performData based on the results from your checkUpkeep. This pattern can greatly reduce your onchain gas usage by narrowing the scope of work intelligently in your own Solidity code.

• Identify a list of addresses that require work: You might have a number of addresses that you are validating for conditions before your contract takes an action. Doing this onchain can be expensive. Filter the list of addresses by validating the necessary conditions within your checkUpkeep function. Then, pass the addresses that meet the condition through the performData function. For example, if you have a "top up" contract that ensures several hundred account balances never decrease below a threshold, pass the list of accounts that meet the conditions so that the performUpkeep function validates and tops up only a small subset of the accounts.
• Identify the subset of states that must be updated: If your contract maintains complicated objects such as arrays and structs, or stores a lot of data, you should read through your storage objects within your checkUpkeep and run your proprietary logic to determine if they require updates or maintenance. After that is complete, you can pass the known list of objects that require updates through the performData function.

StreamsLookupCompatibleInterface

See the Data Streams Getting Started guide to see an example of how to use this interface.

To use Data Streams with Automation, your contract must be Automation-compatible and include a StreamsLookupCompatibleInterface interface. This interface fetches and processes Data Streams reports.

StreamsLookup revert

Automation network will use this revert to trigger fetching of the specified reports.

Parameters

Outputs

The fetched signed reports will be provided to the user in checkCallback. This is an offchain compute that the user can use to structure data as needed before performing the onchain confirmation and validation transactions.

checkCallback function

This is a view function that will be simulated offchain to receive the signed reports and conduct any final parsing before sending data onchain via performUpkeep. Inputs will match outputs of the oracleLookup revert.

Parameters

Outputs

checkErrorHandler function

This function is simulated offchain to respond to error codes before sending data onchain in the performUpkeep function.

Parameters

Outputs