Running a Keep3r Network keeper

This guide will walk you through the process of running a Keeper in the Keep3r Network by leveraging Defender Relay and Autotasks.

The Keep3r Network project is in beta. Use at your own risk.

What is a Keeper?

In the context of the Keep3r Network, Keepers are participants who execute available jobs in exchange for a reward. A contract may register a job to be executed, and once it’s available, a registered Keeper can send a transaction to execute it.

A Keeper is the term used to refer to an external person and/or team that executes a job. This can be as simplistic as calling a transaction, or as complex as requiring extensive off-chain logic. The scope of Keep3r network is not to manage these jobs themselves, but to allow contracts to register as jobs for keepers, and keepers to register themselves as available to perform jobs. It is up to the individual keeper to set up their devops and infrastructure and create their own rules based on what transactions they deem profitable.

Prerequisites

To get started, you’ll need the following:

  1. A Defender mainnet account. Head over to Defender to sign up for a new account, and then apply for mainnet access indicating that you are interested in running a Keeper. We’ll contact you shortly to activate your account for mainnet access. Note that mainnet accounts are free for now, but will be paid starting end of year.

  2. ETH to pay for transactions gas. Keeper transactions require gas for execution, so make sure to have some ETH available to fund your Relay.

  3. KP3R tokens to bond (optional). When you register your Keeper, you may choose to bond a certain amount of KP3R tokens. This affects the rewards you get when working Jobs. Note that you can still run a Keeper without bonding any tokens.

Creating a Relayer

The first step will be to create a Defender Relayer to act as your Keeper. This Relayer will be the Ethereum account you will be executing jobs from.

You do not need to register as a Keeper manually in keep3r.network, doing so will register your wallet as a Keeper, not your Relayer.

To create a Relayer, simple head over to the Relay section in Defender, and create a new relayer on the Mainnet network. Once created, take note of the Relayer address; you will not need the generated API key and secret for this guide.

Creating a new Relayer in mainnet
If the option to create the relayer in mainnet is locked, it means your Defender account does not have mainnet access yet. Make sure to apply for mainnet access first and wait for our response.

Fund your Relayer

Next step is to send ETH to your Relayer, so it has funds to execute the jobs. Copy the Ethereum address of your new Relayer, and use your favorite wallet to send ETH to it. You can send whatever amount you want, but you want at least around 0.2 ETH to be able to send a handful of transactions before running out.

After the transaction is confirmed, you should see the the funds you have transferred in the Relayer’s balance.

Checking the balance of your Relayer
Defender will send you an email when your Relay’s funds drop below 0.1 ETH to remind you to refill it.

If you want to bond any KP3R tokens to your Relayer, you will need to transfer the tokens to the Relayer address as well. Make sure to send the tokens to the Relayer address and not to the KP3R token contract!

Bond your Relayer

To get your Relayer registered as a Keeper, the first step is to bond it. Click on the gear icon in your Relayer settings page, and choose to Bond to Keep3r Network.

If you want to bond KP3R tokens, now is the time to choose how many you want to bond. Note that you can work with zero bonded KP3R tokens, and you can bond more tokens later if you want to do so.

Bonding your Relayer

After the transaction to bond your Relayer is sent, your Relayer will now enter a 3-day waiting period before it can be activated as a Relayer. You can access your Relayer page at any time to check how much time is remaining.

Waiting period for activating the Relayer as a Keeper
You can at any time choose to Bond to Keep3r Network again. This will allow you to bond additional KP3R tokens, but will reset the waiting period back to 3 days.

Activate your Relayer

After the 3-day waiting period is over, you will have the option to Activate as keep3r. Doing so will send a transaction to activate your Relayer as a Keeper in the network.

Relayer is now a Keeper

Create an Autotask

Now that you have your Relayer active as a Keeper, let’s set up the Defender Autotask that will instruct your Relayer to send them. An Autotask is a snippet of code that runs at regular intervals, in this case, we’ll use it to automate the process of bonding, activating, searching for jobs, and executing them.

Create a new Autotask in the Autotasks section of Defender, choosing to run every one minute, and connecting it to the Relayer you had created previously.

As for the code, paste this code snippet from the defender-autotask-examples repository, which will attempt to work the YearnV1EarnKeep3r, HegicPoolKeep3r, and UniswapV2SlidingOracle contracts. Once you hit save, Defender will start executing the Autotask every minute.

If you are familiar with javascript, you can edit your Autotask code at any time to add new jobs as they are published. To do this, add the ABI of the contract you want to work to the ABIs object in the snippet, and add an entry to Jobs with the contract name and address, as well as the names of the workable and work functions.

Executing Jobs

The autotask you have set up will automatically start looking for available jobs in the YearnV1EarnKeep3r, HegicPoolKeep3r, and UniswapV2SlidingOracle contracts. You can check out your Autotask logs to see what your Keeper has done on each run, and monitor your rewards on the Relayer page.

Keep in mind that sending the transaction does not automatically mean you will get rewarded for it: other Keepers may also be monitoring the job for work, and if their transaction gets mined before yours, you will not get the reward!

Collecting your Rewards

After working some jobs, you can send your earned KP3R tokens from your Relayer back to your wallet. To do so, go to your Relayer page and choose to Withdraw funds. Enter your wallet address, choose KPR as currency, and input the amount of tokens you want to withdraw. Make sure you enter your wallet address correctly, or you may irretrievably lose your tokens!

Withdrawing your tokens from the Relayer
You can also use the Withdraw funds option to send ETH from your Relayer back to your wallet at any time.

Leaving the Keeper network

In the event that you no longer wish to participate as a Keeper, you can just stop your Autotask to stop executing Jobs, and withdraw your KP3R and ETH from your Relayer. If you hadn’t bonded any tokens during the registration phase, this is enough.

If you did bond tokens during registration, and you want to retrieve, you will need to unregister as a Keeper. To do this, start by choosing to Send a transaction in your Relayer page, enter the Keeper contract address 0x1cEB5cB57C4D4E2b2433641b95Dd330A33185A44, and choose the unbond function. The bonding parameter corresponds to the address of the token you had bonded (again 0x1cEB5cB57C4D4E2b2433641b95Dd330A33185A44 for KP3R), and amount is the number of tokens you want to unbond (including the extra decimals as zeros, so 100 KP3R should be entered as 100000000000000000000).

Unbonding your Relayer from the Keep3r Network

After this transaction is sent, you will have to wait a 14-day unbonding period. Once passed, you will need to send another transaction from your Relayer, this time calling the withdraw function instead, with the same bonding parameter as before. This will effectively remove your Relayer as a Keeper, and send your bonded tokens back to your Relayer address, from where you can Withdraw them to your wallet.

Troubleshooting

These are some common issues you may see along the way. If you have any questions, don’t hesitate to ask on the forum!

Autotask fails with error "failed to meet quorum"

This error is related to the ethers.js provider being throttled by Alchemy, Infura, or Etherscan due to making too many queries to the network. You can read more about this in the ethers.js documentation. To fix this now, you can apply for an API token as described on the ethers.js docs, and modify the Autotask snippet to use it instead of creating a new ethers.getDefaultProvider(). Meanwhile, we are working on adding a custom Defender provider, so you don’t need to go through this on your end!