A Job can generate new credits with time, by bonding Keep3r Liquidity Pool tokens
kLPto it. Liquidities will be handled by the Keep3r Liquidity Pools.
kLPsare added to a job with
addLiquidityToJob, the job starts immediately to mine new KP3R credits, that can be collectable only by the keepers, in reward for working the job. The credit mining system requires no further action from the
KP3R Credits can only be rewarded within the protocol, requiring an unbonding period that gives time to disputers to detect keepers and jobs that act in bad faith
To handle KP3R credits minting and quoting, Keep3r introduces reward periods, in which KP3R quote remains stable for each pair, and gas-efficiently processed. These quotes are used within the protocol to mint credits and reward keepers.
The underlying KP3R of the liquidity provided, should generate the same amount of KP3R every
inflationPeriod, thereby minting the proportional amount each
rewardPeriodas KP3R credits for the job. These credits are only to be earned by keepers when working the job, and by the end of each
rewardPeriod, unused credits older than previous
rewardPeriodStartare meant to expire.
Credit mining without work
When a new
rewardPeriodstarts, the first keeper to work the first job will:
- Perform the job action
- Reward the job or update its accountance
- Update the quote of the KP3R/WETH pool
- Update the quotes of each of the job liquidities
Following keepers of different jobs, will have to update each job accountance (when worked for the first time in the period), but won't have to update the quotes of KP3R/WETH and the liquidities the first job had, since they will be already updated.
Updating jobs accountance requires no other action from the keeper than working the job.
worked()transaction that has to update quotes and reward the job is more gas-consuming, therefore has a higher keeper reward
To determine the value of a certain liquidity, Keep3r uses a TWAP calculation to get the average quote of a pair in the last completed period. The same calculation is applied to quote rewards for keepers (that spend gas in ETH and receive KP3R rewards), using a predefined KP3R/WETH pool as an oracle.
quoteLiquiditywill use the average quote for the last
epochfor the given liquidity
- Remaining credits will be updated to current quotes each time a
At every time, a job will have its current credits (already rewarded and stored as
jobLiquidityCredits) and pending mined credits to be rewarded (aggregated with current credits in
A keeper will be able to run the job, as long as
totalJobCreditsis greater than the payment. If
jobLiquidityCreditsare not enough to pay the keeper, then the keeper will have to reward the job by rewarding the job with its mined credits.
In a normal case scenario, a job should be rewarded once every reward period starts, and burn all remaining credits from the expired period (the one previous to the last full period).
Normal case scenario
In a deficitary job scenario, when the job is spending more KP3R in a period than it should be rewarded, the job will be able to keep on paying keepers, but the minting period will start to shrink, having to mint more frequently.
Deficitary job scenario
Each time, the reward period will be shorter, as the job is not being rewarded the full amount for a period, but only the proportional relation of the time that passed since the last reward, and the
Ultimately, when the job has not enough
totalJobCreditsto reward the keeper for working the job (and some extra to pay the keeper for rewarding the credits), the transaction will revert with
At particular times, a job can make a payment of up to 2 times its
jobPeriodCredits, as long as all the credits minted have not yet expired.
Credits spending greater than jobPeriodCredits
Since quotes can change every epoch, Keep3r recalculates every period how many KP3R a job should be mined each period, aggregated by
Credit mining with quote change
Since KP3R/WETH is also stored and stable inside periods, keeper payments are also updated to current quotes.
Work scenario with quote change
At any time, the
jobOwnercan withdraw the liquidity bonded to the job, provided he either removes the total of it, or that he remains a minimum allowed amount.
To withdraw a liquidity, first has to unbond the liquidity from the job with
unbondLiquidityFromJob, instantly diminishing the job KP3R credits proportional to the impact of removing such liquidity. After an
jobOwnercan withdraw the liquidity tokens from the protocol with