# JobRegistry ## Events ### JobCreated ```solidity event JobCreated(uint256 indexed index, address indexed owner, address indexed application, bool initialExecution) ``` Emitted when a job is created via [createJob](#createjob). ### JobDeleted 
event JobDeleted(uint256 indexed index, address indexed owner, address indexed application, bool applicationRevertedOnDelete)
Emitted when a job is deleted via [deleteJob](#deletejob). ### JobDeactivated ```solidity event JobDeactivated(uint256 indexed index, address indexed owner, address indexed application); ``` Emitted when a job is deactivated via [deactivateJob](#deactivatejob). ### JobExecuted ```solidity 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](#execute). ### FeeModuleUpdate ```solidity 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](#updatefeemodule). ### SponsorshipRevoked ```solidity 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](#revokesponsorship). ## State-changing functions ### createJob ```solidity 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](#jobcreated) and possibly [JobExecuted](#jobexecuted). ### execute ```solidity 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`](https://docs.ees.xyz/technical-reference/api/core/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](#jobexecuted). ### deleteJob ```solidity 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](#jobdeleted). ### deactivateJob ```solidity 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](#jobdeactivated). ### revokeSponsorship ```solidity 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](#sponsorshiprevoked). ### updateFeeModule ```solidity 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](#feemoduleupdate). ## Read-only functions ### getJobsArrayLength ```solidity 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. |