Skip to main content

Keepers and scheduled callbacks

Keepers submit ordinary transactions for on-chain requests whose time has arrived. The current coordinator supports paid, zero-value, one-shot callbacks. An application can schedule its next callback to build a recurring workflow.

Request a callback​

A contract calls requestCall(data, gasLimit, executeAfter, expiresAt) on the coordinator, paying the request fee. The callback targets that requesting contract, preventing an unrelated user from borrowing another application's privileges. The consumer must authenticate the coordinator and match the callback to its stored request ID and data.

For an existing target that cannot request callbacks, deploy an owner-controlled KeeperAccount. Grant it the target's precise required permission, then schedule the target and calldata through that account. The target sees KeeperAccount as its immediate caller.

Public coordinator addresses, ABI and consumer SDK release details are TBD. For an owner-scheduled action, restrict scheduling to the owner, store the exact action/request association and accept only the authenticated callback. Pay the current coordinator quote for the selected gas limit; callback authentication and the application action both consume that budget. Each schedule is a separate paid request.

Bounds and failures​

The coordinator bounds every request:

  • Only contracts can request callbacks, and a callback always targets the contract that requested it.
  • Calldata is 4–16,384 bytes. Callback gas must be between 25,000 and 6,000,000.
  • The request stores a hash of its calldata, so a worker cannot change what runs. A worker can act only between the execution time and the expiry.
  • Payment above the quote becomes a withdrawable credit, not a fee.
  • A KeeperAccount owner can cancel a scheduled action before it runs.

Workers, fees and the treasury are set by the coordinator's owner; the current keeper service is operated, not permissionless.

Calls can be scheduled within the coordinator's 30-day horizon. Fix callback gas, execution time and expiry when requesting. Worker retries recover delivery/transaction failures; they do not repeat already consumed application callbacks. A reverted consumer records CallbackFailed and consumes the request, while insufficient callback gas reverts without consumption. Expired unfulfilled requests can be cancelled for consumer credits.

The target must recheck its current conditions and authority at execution. Scheduling a payment does not guarantee future available funds, eligible assets or uncongested inclusion. Add application-level retry requests only where idempotence and budget rules permit them.

Planned trigger types​

State predicates, events and finalized oracle triggers with editable/cancellable jobs are planned features. The current API schedules one-shot callbacks. No generic public predicate-registration endpoint is documented here. Event observation by a worker never grants authority over another account.