@1inch/farming
v3.2.0
Published
Set of contracts for farming incentives
Downloads
885
Keywords
Readme
Farming contracts
Overview
About
1inch farming contract offers protocols to give rewards to users holding specific tokens. The repository offers two ways to get incentivisation rewards to holders:
- Token smart contract could be derived from
ERC20Plugins
and allow farming in multiple farms without necessarity staking token to any pool. User should add farm as a plugin (seeERC20Plugins
concept) and keep tokens on its address to be eligible for rewards. - A user can stake/deposit specific tokens to
FarmingPool
smart contract. It is less convenient way and is only used for backward compatibility for those smart contracts that have been deployed and there are no way to change it.
Math
Farming reward is distributed uniformly across the whole farming period and depends on number of participants. Actually, the reward is a piecewise linear function which is set by formula
$$ R_p= \sum{ R \ * \frac {t}{T} *\ \frac {V}{V_{total}} } $$
where $R_p$ - total farming reward for a farming participant
R - total reward locked for farming
t - time period duration (between farm’s joins and/or exits)
T - total farming duration
V - participant’s farmable tokens share
$V_{total}$ - total number of farmable tokens joined the farm
Example
Given $72 000 reward is locked for 5 weeks in a farm and there are three farmers
Farmer 1
joins at week 1 with 100 farmable tokens on his balance but exits at week 2 and rejoins at week 3. At week 4 he increases his balance up to 200 farmable tokensFarmer 2
joins at week 2 with 300 farmable tokens and exits after week 3Farmer 3
joins at week 2 with 300 farmable tokens but decreases his farmable token balance after week 3 down to 100 and exits at week 4
| 72000$ reward | Week 1 | Week 2 | Week 3 | Week 4 | | --- | --- | --- | --- | --- | | Farmer 1 | 100 | | 100 | 200 | | Farmer 2 | | 300 | 300 | | | Farmer 3 | | 300 | 100 | |
The resulting reward distribution would be the following
| | Week 1 | Week 2 | Week 3 | Week 4 | | --- | --- | --- | --- | --- | | Farmer 1 | 18000 | | 3600 | 18000 | | Farmer 2 | | 9000 | 10800 | | | Farmer 3 | | 9000 | 3600 | |
More examples are here @1inch/farming/TESTS.md#deposit
ERC20Plugins
and FarmingPlugin
usage
Concept
To start new farming owner should deploy (or use already deployed) farming for a pair of tokens and initialize it.
- Deploy farm and set farmable and reward token
- Start farming
- Set distributor
- From distributor account send reward amount and set farming period
When farming is started users holding farmable tokens may addPlugin
the farm to accumulate rewards. After joining a farm, a user starts to get farm rewards for the whole amount of farmable tokens he owns. When a user’s balance changes the reward share is changed automatically.
If a user wants to stop participating in farming he should removePlugin
the farm with. Rewards for previous farming periods may be claimed any time with claim
function of the farm regardless if a user is still farming or has already exited the farm.
A user may join several farms which provide rewards for the same token.
To prevent new farmings from starting an owner may set a distributor address to zero.
Installation
$ npm install @1inch/farming
or
$ yarn add @1inch/farming
Usage
Once installed, you can use the contracts in the library by importing them. Just use ERC20Plugins
instead of ERC20
to derive from
pragma solidity ^0.8.0;
import "@1inch/farming/contracts/ERC20Plugins.sol";
contract AMMPoolToken is ERC20Plugins {
constructor(uint256 farmsLimit) ERC20("AMMPoolToken", "AMM") ERC20Plugins(farmsLimit) {
}
}
Optimizations
Storage access:
1 storage slot for farming params, updated only on farming restarting:
uint40 public finished; uint32 public duration; uint184 public reward;
1 storage slot for farming state, updated only on changing number of farming tokens:
uint40 public checkpoint; uint216 public farmedPerTokenStored;
1 storage slot per each farmer, updated on deposits/withdrawals (kudos to @snjax):
mapping(address => int256) public corrections;
Compact address array is used for storing farms per user/wallet. Array length is stored in high bits of the first array item:
FarmingPool
usage
The FarmingPool
usage is almost the same but a farmer has to deposit farmable tokens to farm account and withdraw it after the farming is completed.