Job funds deposition and withdrawal

The job owner may replenish either his own credits (in native tokens) or those of any of his jobs. Owner credits are usable for payment whenever the corresponding configuration flag is set to be True.

Job credit deposition

Should a user desire to top up credits of one of his jobs, he ought to invoke the function depositJobCredits(bytes32 jobKey_) external virtual payable (which is defined as virtual and therefore can have its functionality overridden in particular realisations, all of which will be described separately). The value of the transaction call corresponds to the amount of credits deposited.

Arguments

1. bytes32 jobKey_: a job key, which is a keccak256 hash of a concatenation of the job's address and id (in that order)

Assertions

1. _assertNonZeroValue: ensures the message's value is not zero. Since this value corresponds to the amount of tokens to be deposited, this has the effect of ensuring nonzero deposition.

2. It is also checked that the job has an owner (i.e. that its key's value in the mapping mapping(bytes32 => address) internal jobOwners is not zero)

3. It is further checked that the job's credit after the tokens sans the fee are deposited does not exceed the maximum admissible value of uint88, which is the type used to store credits.

Once all assertions are satisfied, the function calculates the deposit fee (which is specified by the Agent parameter feePpm in parts per million), increments the total accrued Agent fees by the fee amount, and increments the job's credits by the deposit amount minus the fee. Finally, an overridable virtual function afterDepositJobCredits(jobKey) is called, which is implementation-specific (e.g., in PPAgentV2RANDAO this function assigns a keeper to the job if need be).

Job credit deposition update

Having incremented the credits and the fee, the function emits the event DepositJobCredits(jobKey_, msg.sender, amount, fee)

Job credits withdrawal

Should a job owner desire to withdraw some credits of one of his jobs, he ought to invoke the function withdrawJobCredits( bytes32 jobKey_, address payable to_, uint256 amount_ )

Arguments

1. bytes32 jobKey_: a job key, which is a keccak256 hash of a concatenation of the job's address and id (in that order)

2. address payable to_: the withdrawn token recipient address

3. uint256 amount_: the amount to withdraw. If this values equals type(uint256).max, then the totality of tokens is withdrawn, which is a measure of convenience.

Assertions

1. _assertOnlyJobOwner: ensures that only the owner may withdraw

2. _assertNonZeroAmount: ensures that the amount withdrawn is nonzero

3. It is also checked that the amount withdrawn does not exceed the amount available

Once all assertions are satisfied, the function decrements the job's credits by the specified amount, transfers them to the specified address, and calls the overridable virtual function afterWithdrawJobCredits(jobKey), which allows particular realisations to inject custom behaviour. E.g., the PPAgentV2RANDAO checks if the keeper assigned to the job needs to be released (e.g. if the job is left underfunded, and covering the costs with the job owner credits is not possible) and releases him if so.

Job credit withdrawal update

Having decremented the credits and sent them to the specified address, the function emits the event WithdrawJobCredits(jobKey_, msg.sender, to_, amount_)

Job owner credits deposition

If the job parameters so allow, the credits belonging to the owner and not the job itself may be used to cover the cost of execution (i.e. reward the keeper). Should a user desire to top up his credits, he ought to invoke the function depositJobOwnerCredits(address for_) external payable. The value of the transaction call corresponds to the amount of credits deposited.

Arguments

1. address for_: the job owner address to deposit for

Assertions

1. _assertNonZeroValue: ensures the message's value is not zero. Since this value corresponds to the amount of tokens to be deposited, this has the effect of ensuring nonzero deposition.

Once all assertions are satisfied, the function calculates the deposit fee (which is specified by the Agent parameter feePpm in parts per million), increments the total accrued Agent fees by the fee amount, and increments the job owner's credits (stored in the mapping mapping(address => uint256) public jobOwnerCredits with address as key) by the deposit amount minus the fee.

Job owner credit deposition update

Having incremented the credits and the fee, the function emits the event DepositJobOwnerCredits(for_, msg.sender, amount, fee)

Job owner credits withdrawal

Should a job owner desire to withdraw some or all of his credits, he ought to invoke the function withdrawJobOwnerCredits(address payable to_, uint256 amount_)

Arguments

1. address payable to_: the withdrawn token recipient address

2. uint256 amount_: the amount to withdraw. If this values equals type(uint256).max, then the totality of tokens is withdrawn, which is a measure of convenience.

Assertions

1. _assertNonZeroAmount: ensures that the amount withdrawn is nonzero

2. It is also checked that the amount withdrawn does not exceed the amount available

There are no separate checks for the sender to be the job owner because the credits available for withdrawal are taken from the mapping mapping(address => uint256) public jobOwnerCredits with the message sender's address as key.

Once all assertions are satisfied, the function decrements the job owner's credits by the specified amount and transfers them to the specified address.

Job owner credit withdrawal update

Having decremented the credits and sent them to the specified address, the function emits the event WithdrawJobOwnerCredits(msg.sender, to_, amount_)