JobRegistry

This page covers technical information on the JobRegistry contract.

Events

JobCreated

event JobCreated(uint256 indexed index, address indexed owner, address indexed application, bool initialExecution)

Emitted when a job is created via createJob.

JobDeleted

event JobDeleted(uint256 indexed index, address indexed owner, address indexed application, bool applicationRevertedOnDelete)

Emitted when a job is deleted via deleteJob.

JobDeactivated

event JobDeactivated(uint256 indexed index, address indexed owner, address indexed application);

Emitted when a job is deactivated via deactivateJob.

JobExecuted

event JobExecuted(uint256 indexed index, address indexed owner, address indexed application, bool success, uint48 executionNumber, uint256 executionFee, address executionFeeToken, bool inZeroFeeWindow);

Emitted when a job is executed via execute.

FeeModuleUpdate

event FeeModuleUpdate(uint256 indexed index, address indexed owner, address indexed sponsor, bytes1 feeModule);

Emitted when the fee module data is updated or a migration to a new fee module for a job via updateFeeModule.

SponsorshipRevoked

event SponsorshipRevoked(uint256 indexed index, address indexed owner, address indexed newSponsor, address oldSponsor);

Emitted when the sponsor of a job revokes the sponsorship via revokeSponsorship.

State-changing functions

createJob

function createJob(JobSpecification calldata _specification, address _sponsor, bytes calldata _sponsorSignature, bytes calldata _ownerSignature, uint256 _index) external returns (uint256 index);

Creates a new job according to the _specification. This call will make external onCreateJob calls to the specified execution module, fee module and application. Both _sponsorSignature and _ownerSignature are EIP-712 signatures of the _specification. The function supports ERC-1271 and ERC-6492 verification of signatures.

Arguments

Name	Type	Description
_specification	JobSpecification calldata	Specification of the job containing, execution module, fee module, application and initialization data to these, as well as general job settings.
_sponsor	address	Address of the sponsor. The zero address means no sponsor set.
_sponsorSignature	bytes calldata	An EIP-712 signature of the _specification, signed by _sponsor.
_ownerSignature	bytes calldata	An EIP-712 signature of _specification, signed by _specification.owner.
_index	uint256	Index in the jobs array where the job is intended to be created.

Notes

• If _index is greater or equal to the current length of the jobs array, then the job will be created at the last index expanding the jobs array. Otherwise it will try to reuse the existing slot at _index succeeding if the current job at that index is expired or has been deleted. Otherwise, it falls back to expanding the array.

• If the caller is the owner of the _specification then the _ownerSignature is not considered.

• If the _sponsor is the zero address, then the _sponsorSignature is not considered.

• The sponsor will be set as the payer of execution fees and should thus have approved fee tokens to the JobRegistry contract.

• The job may execute immediately as decided by the execution module and _specification.executionModuleInput. In this case the application will be executed and the execution counter is incremented. If the application call reverts, then the createJob call also reverts.

• Having both _specification.sponsorFallbackToOwner and _specification.sponsorCanUpdateFeeModule true at the same time should be prevented as the sponsor can update the fee module setting an exceedingly large fee and then withdraw their sponsorship, falling back to the owner.

Emits JobCreated and possibly JobExecuted.

execute

function execute(uint256 _index, address _feeRecipient) external returns (uint256 executionFee, address executionFeeToken, uint8 executionModule, uint8 feeModule, bool inZeroFeeWindow)

Executes a job, making external onExecuteJob calls to the execution module, fee module and application associated with the job. It also handles transferring of execution fees.

Arguments

Name	Type	Description
_index	uint256	The index of the job to be executed in the jobs array.
_feeRecipient	address	Address that execution fees are transferred to.

Return data

Name	Type	Description
executionFee	uint256	Number of executionFeeToken that are transferred to _recipient.
executionFeeToken	address	Address of the ERC-20 token the execution fee is transferred in.
executionModule	uint8	Identifier of the executed job's execution module.
feeModule	uint8	Identifier of the executed job's fee module.
inZeroFeeWindow	bool	A flag telling if the job is in zero fee window.

Notes

• Can only be called by coordinator.

• If the sponsorFallbackToOwner field of the job is true, it will try to transfer the fee from the owner if transferring from the sponsor fails. If the owner transfer succeeds, the owner is set as sponsor.

• May deactivate the job if application reverted and the ignoreAppRevert property of the job is false or if maxExecutions of the job is reached.

• Only increments the job's executionCounter upon successful execution of application (even when ignoreAppRevert is true).

Emits JobExecuted.

deleteJob

function deleteJob(uint256 _index) external;

Deletes the job from the jobs array and externally calls onDeleteJob on the associated execution module, fee module and application.

Arguments

Name	Type	Description
_index	uint256	Index in the jobs array of the job to be deleted.

Notes

• Can only be called by the owner of the job.

• Will not revert of application's onDeleteJob call reverts.

Emits JobDeleted.

deactivateJob

function deactivateJob(uint256 _index) external;

Deactivates a job, preventing it from being executed, but keeps the job in storage.

Arguments

Name	Type	Description
_index	uint256	Index in the jobs array of the job to be deactivated.

Notes

• Can only be called by the owner of the job.

• Sets activate field of the job to false.

• Does not perform any external calls to modules or application.

Emits JobDeactivated.

revokeSponsorship

function revokeSponsorship(uint256 _index) external;

Revokes sponsorship of a job, alternating the sponsor field of the job.

Arguments

Name	Type	Description
_index	uint256	Index in the jobs array of the job to revoke sponsorship for.

Notes

• Can only be called by the owner or the sponsor of the job.

• If called by the owner, the owner is set as the new sponsor.

• If called by the sponsor, the owner is set as sponsor if the sponsorFallbackToOwner of the job is set to true, otherwise it sets the zero address as sponsor. Note that in this case, if the job owner does not find a new sponsor or chose to sponsor themselves before the next execution window is over, then the job will expire.

Emits SponsorshipRevoked.

updateFeeModule

function updateFeeModule(FeeModuleInput calldata _feeModuleInput, address _sponsor, bytes calldata _sponsorSignature) external;

Updates current fee module data or migrates to a different fee module. This function supports EIP-1271 and EIP-6492.

Arguments

_feeModuleInput	FeeModuleInput calldata	Contains information about the new fee module as well as input data to the module.
_sponsor	address	Address of the new sponsor of the job.
_sponsorSignature	bytes calldata	EIP-712 signature of the _feeModuleInput.

Notes

• Can only be called by the owner of the job, unless the sponsorCanUpdateFeeModule field of the job is true, then the sponsor can also call this function.

• Cannot be called while the job is in execution window.

• If the fee module code is the same as the current one, the fee module data is updated calling onUpdateData on the existing fee module.

• If the fee module code differs from the current one, a migration to the new fee module happens. Here, onDeleteJob is called on the old fee module and onCreateJob is called on the new fee module.

Emits FeeModuleUpdate.

Read-only functions

getJobsArrayLength

function getJobsArrayLength() external view returns (uint256 length)

Returns the length of the jobs array.

Return data

Name	Type	Description
length	uint256	Length of the jobs array.