Jobs and registry

A job is an on-chain specification of the details of the execution. The JobRegistry contract stores them as Job structs inside a public array jobs:

struct Job {
    address owner;
    bool active;
    bool ignoreAppRevert;
    bool sponsorFallbackToOwner;
    bool sponsorCanUpdateFeeModule;
    bytes1 executionModule;
    bytes1 feeModule;
    uint24 executionWindow;
    uint24 zeroFeeWindow;
    address sponsor;
    uint48 executionCounter;
    uint48 maxExecutions;
    IApplication application;
    uint96 creationTime;
}

Job[] public jobs;

Let's break down the content of the Job struct:

• address owner is the creator of the job and has the ability to deactivate the job.

• bool active is a flag telling whether the job can still be executed. An active job is still stored on-chain until expiry or maxExecutions is reached, whereafter it can be deleted.

• bool ignoreAppRevert is a flag telling whether the job should continue if the application reverts during execution. If this is true, the job will not expire upon reversion of the application onExecute call.

• bool sponsorFallbackToOwner is a flag telling whether the protocol should try to transfer execution fees from the owner in the case the transfer from the sponsor reverts. In this case, if the transfer from the owner succeeds, then the owner will be set as the sponsor going forward. If this is enabled, the owner should have token permissions to the JobRegistry contract.

• bool sponsorCanUpdateFeeModule is a flag telling whether the sponsor of the job is allowed to update the fee module. Updating can either be changing the parameters of the existing fee module or migrate to another fee module with new parameters. If this is set to false, only the owner can update the fee module.

• bytes1 executionModule is the identifier of the execution module tied to the job. This controls timing of the execution and expiry of the job.

• bytes1 feeModule is the identifier of the execution module tied to the job. This is responsible for calculating the execution fee and token for the job.

• uint24 executionWindow is the number of seconds in which the job can be executed after it is due. If the job is not executed within this window, the job will expire according to the execution module.

• uint24 zeroFeeWindow is the number of seconds in which the job pays zero execution fee. This means that there will be no incentive to execute this job for this duration. It is an option for applications running their own execution logic and using EES as a fallback mechanism in case of execution misses or censorship. It will always be smaller than executionWindow.

• address sponsor is the payer of the execution fees. As we will see later, any third-party can generate a signature approving the job specification and agreeing to pay the execution fees. If no sponsor is given upon creation, the sponsor field will default to the owner.

• uint48 executionCounter is the current number of successful executions for this job. Successful means that the application did not revert upon execution.

• uint48 maxExecutions is the maximum number of executions possible on this job before it will expire when executionCounter reaches this number.

• IApplication application is the application contract implementing the IApplication interface. This contains logic on what is executed.

• uint96 creationTime stores the unix timestamp in seconds (block.timestamp) of when the job was created.

Careful: Having both sponsorFallbackToOwner and sponsorCanUpdateFeeModule true at the same time is dangerous for the owner as the sponsor can update the fee module setting an exceedingly large fee and then withdraw their sponsorship, falling back to the owner.

Note: A job that is expired cannot be executed. Deleting a job simply means deleting the struct and calling onDeleteJob on its execution module, fee module and application.

When a job is canceled, its index in the jobs array is freed up and can be taken by another newly created job. This effectively makes the slots in the jobs array reusable and helps maintaing the size of the array and this minimizing the memory footprint on the chain. Because it is cheaper gas wise to cancel an expired job than extending the array, there is incentivement to do so.

Careful: If you are storing indices off-chain, be sure to check that the jobs are still the ones you expect and that they have not been canceled and replaced. Listening for events can help updating these automatically.