FairLaunch Contract
** Note: Currently we use FairLaunch
https://github.com/alpaca-finance/bsc-alpaca-contract/blob/main/contracts/6/token/FairLaunch.sol
To explain this in Laymen term, the FairLaunch is a contract that responsible for distributing alpaca token.
Table of content
Background
To incentivize user to use Alpaca platform, we offer Alpaca token from various actions. This included but not limited to lending, borrowing (through LFY), provide liquidity to Alpaca token (PancakeSwap's LP).
- FairLaunch is the owner of Alpaca Token
- FairLaunch can have more than one pool
- Users can deposit any token that is available in various Pool i.g. ibBNB, debtBNB, PancakeSwap WBNB-Alpaca LP.
- Users can claim their alpaca reward at any point in time
- 10 percent of Alpaca on top of what minted for depositors will go to Dev Fee fund account
Diagram Flow
graph TD
A[fa:fa-user User] -->|Interact| B[fa:fa-mobile Alpaca Frontend]
B --> C[fa:fa-file-code FairLaunch]
C -->|Deposit ibToken| D["fa:fa-code deposit(address _for, uint256 _pid, uint256 _amount)"]
C -->|withdraw ibToken| E["fa:fa-code withdrawAll(address _for, uint256 _pid)"]
C -->|Claim Reward| F["fa:fa-code harvest(uint256 _pid)"]
Abstract
- accAlpacaPerShare keep increasing
- When user deposit, rewardDebt remember the position when user enter
- To calculate how much reward can user get, it use the current accAlpacaPerShare position - rewardDebt which is the starting position.
- Once user harvet the reward by any mean, it will reset the debtReward position to the current position. Hence, restarting the reward accumulation process
Structs
PoolInfo
struct PoolInfo {
address stakeToken; // Address of Staking token contract.
uint256 allocPoint; // How many allocation points assigned to this pool. ALPACAs to distribute per block.
uint256 lastRewardBlock; // Last block number that ALPACAs distribution occurs.
uint256 accAlpacaPerShare; // Accumulated ALPACAs per share, times 1e12. See below.
uint256 accAlpacaPerShareTilBonusEnd; // Accumated ALPACAs per share until Bonus End.
}
UserInfo
struct UserInfo {
uint256 amount; // How many Staking tokens the user has provided.
uint256 rewardDebt; // Reward debt. See explanation below.
uint256 bonusDebt; // Last block that user exec something to the pool.
address fundedBy; // Funded by who?
}
Attributes
FairLaunch Attribute
Name | Type | Public | Description |
---|---|---|---|
alpaca | Alpaca | Alpaca Token ERC20 Contract Address | |
devaddr | address | Address of Alpaca's developer fund | |
alpacaPerBlock | uint256 | Number of Alpaca token that will be minted per block | |
bonusMultiplier | uint256 | Multiplier as a bonus for early adopter of Alpaca platform | |
bonusEndBlock | uint256 | Last block that bonus multiplier will be in effect | |
bonusLockUpBps | uint256 | Percentage of bonus reward that will be locked in Basis Point unit | |
poolInfo | array | array of available Pools represented in PoolInfo struct | |
userInfo | mapping | 2D hash table [poolID][user's address] ⇒ UserInfo struct | |
totalAllocPoint | uint256 | Total number of allocation point for each pool added | |
startBlock | uint256 | Block number that Alpaca can be minted onward |
Functions
Functions
Name | Type | Description | Documented |
---|---|---|---|
setDev | Public | ||
setAlpacaPerBlock | ExternalOwner | ||
setBonus | ExternalOwner | ||
addPool | ExternalOwner | ||
setPool | ExternalOwner | ||
isDuplicatedPool | PublicView | ||
poolLength | ExternalView | ||
manualMint | ExternalOwner | ||
getMultiplier | PublicView | ||
pendingAlpaca | ExternalView | ||
massUpdatePools | Public | ||
updatePool | Public | ||
deposit | External | ||
withdraw | External | ||
withdrawAll | External | ||
_withdraw | Internal | ||
harvest | External | ||
_harvest | Internal | ||
emergencyWithdraw | External | ||
safeAlpacaTransfer | Internal |
setDev
Use case
- Change the address of Dev Fee account
function Params
Name | Type | Description |
---|---|---|
_devaddr | uint256 | New dev account address |
Logic
- Only the one who has access to current dev account can change
setAlpacaPerBlock
Use case
- Update the emission rate of Alpaca minted in each block
function Params
Name | Type | Description |
---|---|---|
_alpacaPerBlock | uint256 | Number of Alpaca to be mint by the number of block passed |
Logic
- Only Owner of this contract can set the parameter
Set Bonus
Use case
- Owner set the bonus emission rate and period
function Params
Name | Type | Description |
---|---|---|
_bonusMultiplier | uint256 | Multiplier value that will be used in bonus calculation |
_bonusEndBlock | uint256 | The last block number that Bonus period will be effective |
_bonusLockUpBps | uint256 | Percentage in Basis Point to be locked |
Logic
- Verify ownership
- Set the value accordingly
setPool
Use case
- Owner want to set a pool's allocation point which will reflect how Alpaca will be distributed
function Params
Name | Type | Description |
---|---|---|
_pid | uint256 | The target Pool ID that will be updated |
_allocPoint | uint256 | Allocation point used for calculating Alpaca reward |
Logic
- Update all the pools in the contracts to mint pending Alpaca
- Update total allocation point by subtracting the old pool's allocation point value and add new one from params
- Change current pool's allocation point to the new value
addPool
addPool Params
Name | Type | Description |
---|---|---|
_allocPoint | uint256 | Portion of allocation that this pool will distribute alpaca per block |
_stakeToken | address | Address of the token that will be accepted to this pool |
_withUpdate | bool | Address of the token that will be accepted to this pool |
Logic
- Owner call addPool function
- This will create a PoolInfo object and push to the poolInfo array storage in the smart contract thus keep track of all available pools
isDuplicatedPool
Use case
- function to check if there's already a pool with specify token address exist
function Params
Name | Type | Description |
---|---|---|
_stakeToken | address | Address of ERC20 token that need to be check |
Logic
- Loop through all of the existing pools
- return true if there is a pool that has the same address as of the input token address
- return false otherwise
poolLength
Use case
- Check how many pools are there in the contract
function Params
Name | Type | Description |
---|---|---|
Untitled |
Logic
- return total number of element in poolInfo attribute
manualMint
Use case
- Owner want to just mint Alpaca token
function Params
Name | Type | Description |
---|---|---|
_to | address | Recipient address |
_amount | uint256 | Amount of Alpaca to be minted |
Logic
- Voila! Free Alpaca
getMultiplier
Use case
- grab the current multiplier value that will be used in reward calculation
function Params
Name | Type | Description |
---|---|---|
_lastRewardBlock | uint256 | the latest block number that Alpaca rewards were minted |
_currentBlock | uint256 | block number of interest |
Logic
- Basically, this is to see how many blocks have past since the last reward allocation
- If it's in middle of Bonus period, take that into account as well
pendingAlpaca
Use case
- User want to see how many Alpaca that has not been claimed
function Params
Name | Type | Description |
---|---|---|
_pid | uint256 | The target Pool ID that user want to check |
_user | address | Address of user that associate with Alpaca rewards |
Logic
- Calculate using the formula
- pending reward = (user.amount * pool.accAlpacaPerShare) - user.rewardDebt
- Take account of Bonus period in to calculation as well
massUpdatePools
Use case
- Mint Alpaca for all the pools
- Can be called by anyone that willing to spend the gas fee
Logic
- Loop through all the pools available
- call updatePool() function
updatePool
Use Cases
- When users want to deposit token into the pool
- When users want to withdraw from the pool
- When users want to claim alpaca reward
- When owner add a new pool to the set of pools
- When owner update some of the pool
function Params
Name | Type | Description |
---|---|---|
_pid | uint256 | The target Pool ID that the token will be updated |
Logic
- If the pool is up-to-date, skip
- if the pool has no token deposited, update lastBlockReward value and skip
- Calculate Alpaca reward to get for that pool and mint accordingly
- 10% of total reward will be minted to dev address.
- The reward will be minted for FairLaunch contract address.
- Update accumulated Alpaca Per Share of the pool, waiting for user to claim the reward
- Handle Bonus Alpaca from first phase of fair launch // Ended already
deposit
Use Cases
- User want to deposit ibToken to get alpaca rewards
- User open farm position and borrow token. As a sequence, frontend will deposit debtToken to get alpaca rewards
function Params
Name | Type | Description |
---|---|---|
_for | address | address of user who deposit the token. Instead of using msg.sender, we explicitly state this since there can be a case where other smart contract deposit this on behalf of users. |
_pid | uint256 | The target Pool ID that the token will be deposited to. |
_amount | uint256 | Amount of token that will be deposit in this function call |
Logics
- Since this action will affect reward distribution to every user in the pool, the contract will call updatePool(_pid) function
- If user's already have share in the pool
- Harvest the outstanding rewards
- Transfer ERC20 token that associated to the poolID from user's to FairLaunch account
- Update userInfo
- add _amount to the existing deposited amount
- update reward ratio that user is accustomed for
- update bonus reward ratio that user is accustomed for
- Emit event Deposit
withdraw
Use case
- User want to withdraw some amount of staked token from the pool
function Params
Name | Type | Description |
---|---|---|
_for | address | destination address |
_pid | uint256 | Target Pool ID that will be withdrawn from |
_amount | uint256 | Amount of token to be withdrawn |
Logic
- Call internal functoin _withdraw
withdrawAll
Use case
- User want to withdraw all the staked token from the pool
Copy of function Params
Name | Type | Description |
---|---|---|
_for | address | destination address |
_pid | uint256 | Target Pool ID that will be withdrawn from |
_amount | uint256 | Amount of token to be withdrawn |
Logic
- Call internal functoin _withdraw with all the amount that user had in that pool
_withdraw
Use case
- get called from external / public function that want to execute withdrawal
Params
function Params
Name | Type | Description |
---|---|---|
_for | address | Address that will receive staked token back |
_pid | uint256 | The target Pool ID that user will withdraw staked token from |
_amount | uint256 | Amount of token to be withdraw |
Logics
- Update Pool
- Claim Alpaca rewards
- Reset the rewardDebt attribute (starting alpaca reward position)
- Transfer staked token back
- Emit Withdraw event
harvest
Use Cases
- When users want to claim Alpaca rewards from staking token
function Params
Name | Type | Description |
---|---|---|
_for | address | Address that will receive Alpaca |
_pid | uint256 | The target Pool ID that user will take Alpaca from |
Logic
- update the pool and mint Alpaca to the pool of interest
- call _harvest function
- Reset the reward position by setting user's rewardDebt and bonusDebt to current position of Alpaca Per Share
_harvest
** NOTE: If user only want to claim alpaca, it will be called from harvest public function which will call to this _harvest internal function.
Use Cases
- When users want to claim Alpaca rewards from staking token
- Before user deposit token to the pool
- Before user withdraw token from the pool
- Before user close farming position, subsequently withdraw debt token from the pool.
Copy of function Params
Name | Type | Description |
---|---|---|
_for | address | Address that will receive Alpaca |
_pid | uint256 | The target Pool ID that user will take Alpaca from |
Logic
- Calculate the amount of alpaca user will get
- Transfer ALPACA to the user's account
emergencyWithdraw
Use Case
- User panic and pull token out of deposited pool
function Params
Name | Type | Description |
---|---|---|
_pid | uint256 | The target Pool ID that user will withdraw staked token neglecting the Alpaca reward |
Logics
- Only the funder of this user's portion of the pool can call this
- Transfer back the stake token to the caller
- Wipe user's data associated to this pool position
safeAlpacaTransfer
Use case
- wrapper function for tranferring Alpaca from FairLaunch's Address to target address
function Params
Name | Type | Description |
---|---|---|
_to | address | Target address to send Alpaca to |
_amount | uint256 | Amount of Alpaca to be sent |
Logic
- if the amount requested > remaining Alpaca in FairLaunch account, try to transfer all of what's left in the account
- else, try to transfer what has been requested