Registering an Upkeep on Chainlink Keepers
This article will guide you through the process of registering your contract as an Upkeep on Chainlink Keepers, a revamp of the Keep3r Network, using Defender Admin, as well as leveraging Relayers, Autotasks, and Sentinels for monitoring and operations.
What is Chainlink Keepers?
Chainlink Keepers aims to provide smart contracts options to outsource regular maintenance tasks (harvesting, liquidating, rebase, etc.) in a trust minimized (decentralized) manner. The network aims to provide a protocol for incentivization & governance for the keeper ecosystem.
There are 3 main actors in this network:
-
Upkeep: These are smart contracts that need external entities to service their maintenance tasks.
-
Keepers: External actors that execute the published upkeep.
-
Registry: Provide discovery mechanisms for the above actors and provide hooks for governance to keep the network healthy.
Prerequisites
You will need LINK tokens in order to pay for executions on your Upkeep contract. For Kovan, you can acquire them in this faucet. For Mainnet, you can purchase them on Uniswap. You will also need ETH to pay for any transactions you need to send.
Implementing the Upkeep interface
The first step for registering your contract as an Upkeep is to have it implement the required Upkeep interface, which consists of the following two methods:
-
checkUpKeep: This function will be called every block (about ~15 sec) & the boolean return value decides if the contract needs to be serviced at this time or not. If the upkeep is required, you can also return bytes that will be passed toperformUpkeepfunction. -
performUpkeep: This function is the actual upkeep that the contract wants servicing. This function is called only if checkUpKeep has returned true.
pragma solidity 0.7.6;
interface KeeperCompatibleInterface {
/**
* @notice method that is simulated by the keepers to see if any work actually
* needs to be performed. This method does does not actually need to be
* executable, and since it is only ever simulated it can consume lots of gas.
* @dev To ensure that it is never called, you may want to add the
* cannotExecute modifier from KeeperBase to your implementation of this
* method.
* @param checkData specified in the upkeep registration so it is always the
* same for a registered upkeep. This can easily be broken down into specific
* arguments using `abi.decode`, so multiple upkeeps can be registered on the
* same contract and easily differentiated by the contract.
* @return upkeepNeeded boolean to indicate whether the keeper should call
* performUpkeep or not.
* @return performData bytes that the keeper should call performUpkeep with, if
* upkeep is needed. If you would like to encode data to decode later, try
* `abi.encode`.
*/
function checkUpkeep(
bytes calldata checkData
)
external
returns (
bool upkeepNeeded,
bytes memory performData
);
/**
* @notice method that is actually executed by the keepers, via the registry.
* The data returned by the checkUpkeep simulation will be passed into
* this method to actually be executed.
* @dev The input to this method should not be trusted, and the caller of the
* method should not even be restricted to any single registry. Anyone should
* be able call it, and the input should be validated, there is no guarantee
* that the data passed in is the performData returned from checkUpkeep. This
* could happen due to malicious keepers, racing keepers, or simply a state
* change while the performUpkeep transaction is waiting for confirmation.
* Always validate the data passed in.
* @param performData is the 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 not be trusted, and should be
* validated against the contract's current state.
*/
function performUpkeep(
bytes calldata performData
) external;
}After you have implemented these methods, you can compile and deploy your contract using your favorite toolchain.
Verifying your contract code on Etherscan
To be accepted in the Chainlink Keepers network, your Upkeep contract source code needs to be verified on Etherscan. You can use your favorite toolchain to do this.
Registering on the network
Once deployed, you can register your contract as an Upkeep on the Keeper Network. To do this using Defender, start by adding your contract in Admin. Defender will automatically check if your contract properly implements the Upkeep interface.
From your contract’s page, you can now start the Upkeep registration in Chainlink Keeper by clicking on Register in the Chainlink Keeper section.
To begin the registration process, Defender will ask you to fill some details into a registration Google Form. This form will be reviewed by the Chainlink Keepers onboarding team as part of the approval process for the open beta. The information you fill in will help improve Chainlink Keepers to provide you with optimal solutions for your use case.
Click on Open registration Google Form, fill in the details and come back to Defender after doing so.
Once you return from filling the registration Google Form, Defender will ask you to enter an admin address (who will be able to withdraw funds), email (for notification purposes from Chainlink), and gas limit for keeper calls (between 2300 and 2500000).
At the time of writing, the registration process requires you to provide an initial fund of at least 5 LINK for your contract, so make sure the account you use to request the registration has at least that amount of LINK in it. You may choose to make this initial fund bigger to save on future top up gas fees.
Once the registration is submitted, you’ll have a waiting period no longer than a few days, after which your Upkeep will be registered as a valid Upkeep and assigned a numeric identifier in the Registry. Defender will reflect this on Chainlink Keepers of your contract’s page. See below how your contract page looks after the registration was submitted, but its approval is pending.
When your registration is approved, Defender will show you your Upkeep balance, as well as the latest executions by the network’s keepers. Keep in mind that, in order for your contract to be serviced by the network, you will also need to fund it with LINK tokens. You can also do this from Defender, by clicking on Deposit LINK.
Monitoring your Upkeep
You can leverage Defender Sentinels and Autotasks to monitor your Upkeep in the network. For example, you can monitor for failed executions, low funds, or unexecuted tasks.
Failed executions
You can set up a Sentinels to alert you whenever your contract has one or several failed executions over a period of time, so you can investigate the cause for these failures and adjust your Upkeep code if needed.
To do this, begin by creating a new Sentinel to monitor the Chainlink Keeper Registry (0x109A81F1E0A35D4c1D0cae8aCc6597cd54b47Bc6 on Kovan).
And listen for UpkeepPerformed events, where the job id matches your own, and the execution was not successful.
Next you can choose how you want to be notified. Sentinels support Email, Slack, Telegram, and Discord notifications.
Finally, you can choose to be alerted on every single execution failure, or only when there are several failures over a window of time, such as five failures over half an hour. You can also filter notifications so you don’t get alerted too often, such as no more than once per hour.
After you’ve set up this Sentinel, you’ll be alerted on execution failures on your Upkeep.
Low funds
You can combine Sentinels with Autotasks and Relayers to top-up your upkeep when your LINK balance is running low.
As an alternative to auto-funding, you can also just have the Autotask send you a notification, so you addFunds manually.
|
To do this, first create a Relayer that we will use for topping up your Upkeep. Each Relayer you create in Defender has a unique address, and is only usable by your team. Make sure you create your Relayer in the Kovan or Mainnet network, depending where you are running your Upkeep.
Once created, transfer some LINK and ETH to the Relayer’s address, so it can top-up your Upkeep Job, and can pay for the gas of the transactions it sends. On Kovan, you can get test LINK from this faucet.
Next step is to create an Autotask that can query your Upkeep’s balance, and add LINK funds to it if it’s below a threshold. Set up this Autotask to run on a webhook, connected to the Relayer you created earlier, and with the code from the low-funds snippet in the defender-autotask-examples repository.
Whenever this Autotask runs, if it detects that balance is lower than however many tokens you configure, it will use your Relayer to send more LINK to fund your Upkeep.
Last step is to trigger this Autotask. You can have it run on a recurring basis, by setting it to schedule instead of webhook mode, or trigger it after a job is executed. If you go with the latter, you will need to create a Sentinel to monitor the Chainlink Keeper Registry (0x42dD7716721ba279dA2f1F06F97025d739BD79a8 on Kovan) as in the previous scenario, and filter by all UpkeepPerformed events on your job.
And set it up so it calls your Autotask right after a job is worked. You can also limit how often the Autotask will be called, such as no more than once every ten minutes.
Questions
If you have any questions or comments, don’t hesitate to ask on the forum!