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.

Example Job Spec

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