Sign in

Keepers and Chainlink Automation

Suggest an edit

A contract cannot start itself

Nothing inside a contract ever runs on its own. Every state change traces back to some externally owned account, or another contract, sending a transaction that calls in. This is fine when a user supplies both the intent and the gas: a swap happens because a trader submitted it. The problem shows up the moment a contract's correct behavior depends on something happening without a user present to make it happen. A lending protocol needs undercollateralized positions liquidated the instant their health factor (collateral value times a safety threshold, divided by the debt) drops below 1, and no borrower is going to liquidate themselves. A yield vault needs to harvest and recompound rewards on a regular cadence to stay competitive. In both cases the contract knows what should happen and can check whether the condition is met, but someone, the executor, has to send the transaction.

Before you look for that someone, check whether the work has to happen on its own at all. A vesting contract needs no monthly release transaction, because it can compute how much has vested at the moment the beneficiary claims. An executor is needed only for work that cannot wait until someone who wants the result calls the contract.

Your own bot and a paid open call both fall short

The first instinct of most developers coming from web2 is to run a bot, also called a keeper. Spin up a server, poll the chain every block, and when the condition is met, sign and send the transaction from a hot wallet.

The bot is a single point of failure. The work stops when your server goes down or the hot wallet runs out of ETH for gas, and if the machine is compromised, the attacker has a funded key. You have reintroduced the centralized, trusted operator that the contract was supposed to do without.

The second instinct is to make the work permissionless and let economics handle it. Anyone can call liquidate(), and the caller takes a cut of the seized collateral. This works when the task carries a built-in profit. Liquidations get done because liquidators race for the bonus, around 5% to 10% for ETH on Aave (more in the lending lesson). The same logic drives arbitrage and the closing of expired options.

It falls apart for any task that has no natural payout. Nobody will pay gas to call your vault's harvest() out of goodwill. You can add a reward yourself, for example a share of the harvest for whoever calls it. Then you have to price it: a reward that does not cover the caller's gas attracts nobody, and everything above that is overpaid on every call. Someone also has to write and run a bot for your contract before any reward is claimed.

A keeper network sells this as a service. Its nodes are already running, and they send your transaction for the gas plus a premium. You pay for every call in both designs. With the network you do not have to price a reward or wait for bots. In exchange you depend on the network and on keeping your balance with it funded. Chainlink Automation is such a network.

Automation checks off-chain and executes on-chain

Automation, called Chainlink Keepers until its 2022 rename, is a network of independent nodes that monitor upkeeps (jobs registered with the network) and execute them on-chain when they are due. No single node decides whether your function runs, and the network is paid in LINK to cover gas plus a premium.

The custom-logic integration rests on a two-function interface your contract implements.

solidity
interface AutomationCompatibleInterface {
    function checkUpkeep(bytes calldata checkData)
        external
        returns (bool upkeepNeeded, bytes memory performData);

    function performUpkeep(bytes calldata performData) external;
}

checkUpkeep answers one question: is there work to do right now. The Automation nodes call it off-chain, as a simulation, on every block. Because the call never lands in a block, it costs no gas and changes no state. You can read as much as you need inside it. It returns a boolean and an optional performData blob that gets handed to the execution step.

performUpkeep does the actual work. When checkUpkeep returns true, a node packages a real transaction that calls performUpkeep on-chain, pays the gas, and the work happens. This is the only part that touches the chain and the only part you pay for.

Chainlink Automation cycle: off-chain checkUpkeep to on-chain performUpkeepThe Automation node network calls checkUpkeep() on your contract off-chain, for free, on every block. When it returns true, the Registry and Forwarder send a real transaction that calls performUpkeep(), paid from the LINK balance. The Automation cycle: check off-chain every block, execute on-chain when needed OFF-CHAIN (simulated, no gas, runs constantly) Automation node network decentralized keepers checkUpkeep() your contract, view only "is there work to do?" simulate every block mostly false when checkUpkeep returns true, a real transaction crosses to chain upkeepNeeded == true ON-CHAIN (a real transaction, costs gas, paid in LINK) Registry + Forwarder sends the tx, pays gas performUpkeep() your contract, does the work re-checks, then acts calls with performData LINK balance funds the upkeep The off-chain check is free and constant. Only performUpkeep touches the chain and costs gas.

Automation has two other trigger types: a time-based trigger runs a target function on a schedule given as a cron expression, with no checkUpkeep at all, and a log trigger fires when a specific event log is emitted on-chain and uses checkLog instead of checkUpkeep. The rest of this lesson stays with custom logic.

A stop-loss order as an upkeep

Here is a contract that sells a held asset when its price drops below a floor. It reads a Chainlink price feed, the same latestRoundData and staleness check from the oracle lesson, and it uses Automation to fire the sale automatically. The listing shows the state and the two Automation functions. The constructor, the error declarations, the owner-guarded setter for forwarder, and the sale itself are left out.

solidity
contract StopLoss is AutomationCompatibleInterface {
    AggregatorV3Interface public immutable priceFeed;
    int256 public immutable floorPrice;   // e.g. 1800 * 1e8 for an 8-decimal feed
    address public forwarder;             // assigned after the upkeep is registered
    bool public triggered;

    // Simulated off-chain by the nodes on every block. Never mined.
    function checkUpkeep(bytes calldata)
        external
        view
        override
        returns (bool upkeepNeeded, bytes memory)
    {
        if (triggered) return (false, "");
        (, int256 price,, uint256 updatedAt,) = priceFeed.latestRoundData();
        bool fresh = block.timestamp - updatedAt < 1 hours + 10 minutes;
        upkeepNeeded = fresh && price > 0 && price < floorPrice;
    }

    // Mined on-chain by the forwarder when checkUpkeep returned true.
    function performUpkeep(bytes calldata) external override {
        if (msg.sender != forwarder) revert NotForwarder();

        (, int256 price,, uint256 updatedAt,) = priceFeed.latestRoundData();
        if (block.timestamp - updatedAt >= 1 hours + 10 minutes) revert PriceStale();
        if (triggered || price <= 0 || price >= floorPrice) revert ConditionNotMet();

        triggered = true;
        _executeSell();   // swap the held asset against a DEX router, omitted here
    }
}

checkUpkeep is marked view. It reads the feed, checks freshness, and reports whether the price has fallen below the floor. The Automation contracts also offer a cannotExecute modifier you can add to guarantee the function reverts if anyone tries to call it in a real transaction, since it is meant for simulation only.

The check is a few blocks old when the transaction lands

performUpkeep re-reads the price and checks the condition from scratch, reverting if the price is stale or has climbed back above the floor. It has to, because checkUpkeep runs off-chain at block N. By the time a node builds the transaction, broadcasts it, and it lands in a block, two or three blocks have passed, and the price may have moved in between. If performUpkeep trusted the stale decision, it would sell at a price the user never agreed to, after the stop-loss condition had already cleared. So in every Automation integration, treat checkUpkeep as a cheap filter that tells the network when to bother sending a transaction, and treat performUpkeep as the authority that re-establishes every precondition before doing anything irreversible.

checkUpkeep vs performUpkeep timeline: price moves $1,790 to $1,815A timeline shows checkUpkeep running off-chain at block N, where the price is $1,790 and below $1,800, so it returns true. By the time performUpkeep runs on-chain at block N+2, the price has moved to $1,815, back above $1,800: trusting the stale true value sells at the wrong price (a bug), while re-reading the price reverts safely because the condition is now false. The gap: state can change between the check and the execution time block N block N+2 the node builds and mines the tx: a few blocks pass checkUpkeep (off-chain) price = $1,790 below $1,800 → true performUpkeep (on-chain) price = $1,815 back above $1,800 if it trusts the stale "true" sells at $1,815, not $1,790 the trigger condition is gone wrong execution, a real bug if it re-reads the price sees $1,815, condition false reverts or returns early no bad trade, safe performUpkeep must re-validate the condition. The off-chain "true" is a hint, never a guarantee.

The result must not depend on the caller

performUpkeep is a public function. By default, any address can call it, including ones that have nothing to do with the Automation network. The re-check is the first defense against them. A stranger who calls the function early gets a revert and wastes their own gas, and a stranger who calls it when the condition holds does the work you wanted done. If the result is the same whoever calls, the function can stay open, and the Automation network is one executor among several.

The result does depend on the caller when the caller chooses something the function trusts. The usual case is performData: checkUpkeep computes off-chain which items to process, and whoever calls performUpkeep directly passes a blob of their own. The function should re-check every item it is handed.

Where a caller can still gain by choosing the moment or the data, Automation gives you a second lock, the forwarder. When you register an upkeep, the registry generates a unique forwarder address for it, and that address is the only one the network uses to call your performUpkeep. Once you know it, restrict the function to msg.sender == forwarder, as the stop-loss does. Do not hardcode the forwarder in the constructor. You do not know its address until after registration, which happens after deployment. Set it afterward through an owner-guarded setter.

The lock makes the function depend on one executor. The stop-loss re-checks everything and ignores performData, so it would do the right thing for any caller. With the lock, if the network stops running the upkeep, nobody else can execute the sale, and the owner has to point forwarder at an address they control and call performUpkeep by hand. When you add the forwarder check, decide in advance who executes if the network does not.

An upkeep can stop without the contract noticing

An upkeep is paid in LINK. You deposit a LINK balance when you register it, and the network deducts from that balance each time it runs performUpkeep, covering the gas plus a premium that pays the node. When the LINK balance is depleted, the upkeep stops being executed. Nothing reverts and nothing warns the contract, so the sale or liquidation it was supposed to trigger quietly fails to happen. Monitoring the balance and topping it up is operational work you own.

The other limit to plan for is gas. Each upkeep has a configured gas limit for performUpkeep. If your execution exceeds it, the transaction reverts and the work does not get done. This makes unbounded loops especially dangerous here, because the loop might fit under the limit in a test with three items and blow past it in production with three thousand. Cap the work per execution, or use performData to tell performUpkeep which items to process, computed during the free off-chain check. checkUpkeep runs off-chain and costs nothing to simulate, within the node's generous limits, so it is the right place for heavy reads and iteration. performUpkeep costs real gas and runs under a hard limit, so keep it lean.

Automation is also best-effort: it fires soon after the condition is met, usually within a block or two. Anything that needs sub-block precision or guaranteed execution in a specific block should not depend on it.

For every job in your protocol that has to run without a user asking, answer four questions. Can the result be computed later, when someone asks for it? If not, who is paid to send the transaction? Is the result the same whoever sends it? And who sends it if the network you pay stops?