The most important part of the PowerAgent operation. This section describes all steps performed by a Keeper and the Agent contract to execute the Job at a given time (or upon satisfying given conditions).
Whenever execution conditions are met, a Keeper is chosen to execute the task. Alternatively, a Keeper can be pre-selected for the next execution when a number of events happen (e.g. the job parameters or credits values change).
Keeper selection
For more information on Keeper selection, see <page>.
ā ā ā
Specification
The chosen Keeper calls the function execute_44g58pv of the Agent contract, passing required calldata dependent on the type of the Job and the config for the execution.
The function is heavily optimized for gas savings; inline assembly is used alongside with binary operations.
This config is constructed by the Keeper for each execution separately. Setting the flags allows the keeper to override reversion when the block base gas fee exceeds the limit set by the job owner; the second boolean flag determines whether to accrue the reward for the execution on the PowerAgent contract or transfer it to the keeper worker address immediately.
calldata
Calldata passed by the keeper for the target function execution. Read this section for information on execution calldata.
Algorithm
execute_44g58pv
function execute_44g58pv() external
{
//Hook called at the very start of the execution.
_beforeExecution();
//=========Assertions=========
_assertKeeperHasSufficientStake();
_assertJobIsActive();
_assertMinCvpDeposit();
_assertIntervalHasPassed();
_assertBaseFee();
_assertEoaMsgSender();
//=======Calldata load========
_assertCalldataNotMissing();
_assertSelectorCheck();
//=========Execution==========
//Try to execute
//if execution failed, store Job response in the memory for the purpose of constructing traceback.
//==========Payout==========
//If execution succeeded, pay compensation + reward
//Else, pay compensation (in RanDAO; in Flashbots realisation the payment is always in full)
//==========Events============
//If execution succeeded,
emit Execute(
jobKey,
jobAddress,
actualKeeperId,
gasUsed,
block.basefee,
tx.gasprice,
compensation,
bytes32(binJob)
);
//Hook called after successful execution
_afterExecutionSucceeded(
jobKey,
actualKeeperId,
binJob
);
//Else
//Hook called after execution reverted
_afterExecutionReverted(
jobKey,
//Type of calldata provided for execution
calldataSource,
actualKeeperId,
//Response from the Job contract stored if the execution reverted
executionResponse
);
}
Hooks
The hook functions are used to process execution calls by slashers (INSERT LINK TO SLASHING).
Their implementation varies depending on the realisation of the PowerAgent.
_beforeExecute
This hook is called at the very beginning of the execute function. It executes only if the caller is a slasher.
The purpose of this hook is to ensure that by the time the slasher called this function, the slashing has been initiated and the task has been failed by the assigned keeper. If so, after the hook the execution continues, and the slasher becomes the executor of the task. Otherwise, a corresponding error is thrown, and the slasher is reverted.
Flashbots
Not implemented.
RanDAO
function _beforeExecute(
//jobKey of the job to check
bytes32 jobKey_,
//id of the keeper which was responsible for execution earlier
uint256 actualKeeperId_,
//binary of the job
uint256 binJob_
) internal virtual override
{
if (intervalSeconds > 0 && nextKeeperId != actualKeeperId_) {
The hook checks whether the Job is an interval task or a selector task.
Interval task
The assigned keeper can only be slashed if they failed to execute the task during the grace period defined by the rdConfig.period1 parameter, starting from the timestamp at which execution becomes available.
Resolver task
The keeper can be slashed only if the slashing has been initiated (slashing can be initiated by the currently assigned slasher if the job can be executed, i.e., when the designated slasher is capable of executing the job, he may initiate slashing, obtaining the ability to execute the job and slash the designated keeper's stake when the grace period specified by the rdConfig.period1 parameter elapses). Do bear in mind that the only slasher permitted to perform this is the one who initiated slashing.
_afterExecutionSucceeded
Called at the end if the execution was successful.
Flashbots
Not implemented
RanDAO
Handles post-execution slashing when necessary (i.e. when the execution function invoker is a slasher):
function _afterExecutionSucceeded(
//Key of the executed job
bytes32 jobKey_,
//ID of the keeper/slasher who successfully executed the task
uint256 actualKeeperId_,
// Job binary representation
uint256 binJob_) internal override
The assigned keeper is released, the slashing action parameters set (given the job is of resolver type) are zeroed out, and, if the invoker of the function is not the assigned keeper (i.e. is a slasher), the sum of the static and dynamic slashing fees are subtracted from the CVP stake of the keeper and added to that of the slasher.
_afterExecutionReverted
Called at the end if the transaction was reverted by the Job contract.
Flashbots
function _afterExecutionReverted(
//reverted job key
bytes32 jobKey_,
//job type (SELECTOR, PRE_DEFINED, RESOLVER)
CalldataSourceType calldataSource_,
//ID of the keeper whose execution reverted
uint256 keeperId_,
//offset pointing to the memory location of the message with which the function reverted
bytes memory executionResponse_
) internal virtual
Handles the returned traceback: if no specifying message is returned, this function reverts with the error revert JobCallRevertedWithoutDetails(), and otherwise it wraps the traceback and compiles a custom message consisting of a pointer to the function revert response and the response itself.
RanDAO
function _afterExecutionReverted(
//key of the reverted job
bytes32 jobKey_,
//type of the reverted job
CalldataSourceType calldataSource_,
//ID of the keeper who attempted to execute the job
uint256 keeperId_,
//offset pointing to the memory location of the message with which the function reverted
bytes memory executionResponse_
)
Unlike in Flashbots, in RanDAO version this hook does not wrap any tracebacks; instead, it reverts with a custom message if a resolver-type function reverted without slashing being initiated, which can happen if the problem is in the job itself (since slashing initiation requires an executability check, and we can assume that a rational slasher initiates slashing immediately after he is able to ascertain possibility of execution) and otherwise emits an event with the execution response pointer passed to the function and releases the keeper assigned.
Select a Keeper
Flashbots
At the current state of PPagentV2, the keeper to execute the task is selected by the Flashbots: the one offering the highest gas price is chosen, others are reverted with no cost.
RanDAO
Choosing a keeper by random seems like a smart idea.
In the RanDAO version, the choice is made by the following algorithm:
//get the randao realisation for the current block, stored in the block.difficulty
uint256 pseudoRandom = _getPseudoRandom();
//get the cardinality of the keeper set so that the index may be taken modulo it
uint256 totalActiveKeepers = activeKeepers.length();
//get the minimal CVP stake demanded of the keeper by the job
uint256 _jobMinKeeperCvp = jobMinKeeperCvp[jobKey_];
//obtain the index by taking the pseudorandom input, adding the job key so that variance in chosen keeper indices is observed within any single block, and mapping the result into the keeper index set by taking the modulo operation
//the resultant variable index is the index of the keeper selected for execution
uint256 index;
unchecked {
index = ((pseudoRandom + uint256(jobKey_)) % totalActiveKeepers);
}
//iterate over all the keepers, starting with the randomly selected one, until a keeper admissible for the job at hand is found or all gas has been expended
while (true) {
//effectively modulo operation
if (index >= totalActiveKeepers) {
index = 0;
}
//obtain the ID of the next keeper by the index selected
uint256 _nextExecutionKeeperId = activeKeepers.at(index);
//required stake is set to be the global minimal demanded CVP unless the job has a specification of its own
uint256 requiredStake = _jobMinKeeperCvp > 0 ? _jobMinKeeperCvp : minKeeperCvp;
//load the keeper object at the selected ID
Keeper memory keeper = keepers[_nextExecutionKeeperId];
//if the keeper is admissible, i.e. active and has sufficient stake, then assign him as the next keeper of the job and terminate the passage
if (keeper.isActive && keeper.cvpStake >= requiredStake) {
jobNextKeeperId[jobKey_] = _nextExecutionKeeperId;
keeperLocksByJob[_nextExecutionKeeperId].add(jobKey_);
emit KeeperJobLock(_nextExecutionKeeperId, jobKey_);
return;
}
index += 1;
}
}
Keeper assignment only takes place at either a corresponding external call by a job owner, after a successful job execution, after a job is registered; if a job changes its activity status or credit amount deposited, the keeper is assigned conditionally if the job has at least the minimal admissible amount of credits (specified by the RanDAO realisation config parameter rdConfig.jobMinCreditsFinney).
