Keeper Initiator

The Keeper initiator allows Chainlink nodes to be used as a decentralized monitoring and executing network. Nodes running this external initiator can point to any public smart contract function, determine if a condition is met, and execute a job run which can call another contract function to modify state. This initiator supports two types of polling functions, functions which return a Boolean value, and functions which return an array.

Query Function Return Types

Boolean

If the solidity function returns a Boolean value, the Keeper initiator will only initiate a job run if the returned value is true.

A return value of false is a no-op.

Example

// Node polls this function
function canExecute() public view returns (bool) {
  return someFlag;
}

// If canExecute() returns true, node triggers a job
// run which can call this function
function execute() external {
  require(canExecute(), "Cannot execute");
  someFlag = false;
}

Array of addresses

If the Solidity function returns an array of addresses, the Keeper initiator will initiate a job run for each address.

The address is provided in the job run as the defined response key (default: "value").

If the array is empty, no job runs will be initiated.

Example

// Node polls this function for a list of addresses
function getDelinquentAddresses() public view returns (address[] memory) {
  uint256 count;
  for (uint i = 0; i < users.length; i++) {
    if (isDelinquent(users[i])) {
      count++;
    }
  }
  if (count == 0) {
    return new address[](0);
  }
  address[] memory delinquentAddresses = new address[](count);
  for (uint i = 0; i < users.length; i++) {
    if (isDelinquent(users[i])) {
      delinquentAddresses[i] = users[i];
    }
  }
  return delinquentAddresses;
}

// If getDelinquentAddresses() returns any addresses, node triggers a job
// run which can call this function for each address returned
function execute(address _user) external {
  require(isDelinquent(_user), "Not delinquent");
  _execute(_user);
}

Configuration

The Keeper endpoints can be configured with the following formats:

• HTTP(s) RPC: {"name":"name-here","type":"keeper","url":"http://localhost:8545","refreshInterval":600}
• WS(S): {"name":"name-here","type":"keeper","url":"ws://localhost:8546"}

refreshInterval is number of seconds to wait between polling the RPC endpoint.

WS connections will poll on every new block after the cooldown period is completed.

The block cooldown can be configured with the EI environment variable EI_KEEPER_BLOCK_COOLDOWN (number of blocks to cool down).

Example Job Spec

{
    "initiators": [
        {
            "type": "external",
            "params": {
                "name": "ei-name-here",
                "body": {
                    "endpoint": "endpoint-configured-in-ei-here",
                    "address": "0x1cB7441062D8fEFe57Efc0d62002D3f67a3B9C37",
                    "upkeepId": "123"
                }
            }
        }
    ],
    "tasks": [
        {
            "type": "EthTx"
        }
    ]
}