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).

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

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

NameTypePublicDescription
alpacaAlpaca
Alpaca Token ERC20 Contract Address
devaddraddress
Address of Alpaca's developer fund
alpacaPerBlockuint256
Number of Alpaca token that will be minted per block
bonusMultiplieruint256
Multiplier as a bonus for early adopter of Alpaca platform
bonusEndBlockuint256
Last block that bonus multiplier will be in effect
bonusLockUpBpsuint256
Percentage of bonus reward that will be locked in Basis Point unit
poolInfoarray
array of available Pools represented in PoolInfo struct
userInfomapping
2D hash table [poolID][user's address] ⇒ UserInfo struct
totalAllocPointuint256
Total number of allocation point for each pool added
startBlockuint256
Block number that Alpaca can be minted onward

Functions

Functions

NameTypeDescriptionDocumented
setDevPublic
setAlpacaPerBlockExternalOwner
setBonusExternalOwner
addPoolExternalOwner
setPoolExternalOwner
isDuplicatedPoolPublicView
poolLengthExternalView
manualMintExternalOwner
getMultiplierPublicView
pendingAlpacaExternalView
massUpdatePoolsPublic
updatePoolPublic
depositExternal
withdrawExternal
withdrawAllExternal
_withdrawInternal
harvestExternal
_harvestInternal
emergencyWithdrawExternal
safeAlpacaTransferInternal

setDev

Use case

function Params

NameTypeDescription
_devaddruint256New dev account address

Logic

  1. Only the one who has access to current dev account can change

setAlpacaPerBlock

Use case

function Params

NameTypeDescription
_alpacaPerBlockuint256Number of Alpaca to be mint by the number of block passed

Logic

  1. Only Owner of this contract can set the parameter

Set Bonus

Use case

function Params

NameTypeDescription
_bonusMultiplieruint256Multiplier value that will be used in bonus calculation
_bonusEndBlockuint256The last block number that Bonus period will be effective
_bonusLockUpBpsuint256Percentage in Basis Point to be locked

Logic

  1. Verify ownership
  1. Set the value accordingly

setPool

Use case

function Params

NameTypeDescription
_piduint256The target Pool ID that will be updated
_allocPointuint256Allocation point used for calculating Alpaca reward

Logic

  1. Update all the pools in the contracts to mint pending Alpaca
  1. Update total allocation point by subtracting the old pool's allocation point value and add new one from params
  1. Change current pool's allocation point to the new value

addPool

addPool Params

NameTypeDescription
_allocPointuint256Portion of allocation that this pool will distribute alpaca per block
_stakeTokenaddressAddress of the token that will be accepted to this pool
_withUpdateboolAddress of the token that will be accepted to this pool

Logic

  1. Owner call addPool function
  1. 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 Params

NameTypeDescription
_stakeTokenaddressAddress of ERC20 token that need to be check

Logic

  1. Loop through all of the existing pools
  1. return true if there is a pool that has the same address as of the input token address
  1. return false otherwise

poolLength

Use case

function Params

NameTypeDescription
Untitled

Logic

  1. return total number of element in poolInfo attribute

manualMint

Use case

function Params

NameTypeDescription
_toaddressRecipient address
_amountuint256Amount of Alpaca to be minted

Logic

  1. Voila! Free Alpaca

getMultiplier

Use case

function Params

NameTypeDescription
_lastRewardBlockuint256the latest block number that Alpaca rewards were minted
_currentBlockuint256block number of interest

Logic

  1. Basically, this is to see how many blocks have past since the last reward allocation
  1. If it's in middle of Bonus period, take that into account as well

pendingAlpaca

Use case

function Params

NameTypeDescription
_piduint256The target Pool ID that user want to check
_useraddressAddress of user that associate with Alpaca rewards

Logic

  1. Calculate using the formula
    1. pending reward = (user.amount * pool.accAlpacaPerShare) - user.rewardDebt
  1. Take account of Bonus period in to calculation as well

massUpdatePools

Use case

Logic

  1. Loop through all the pools available
    1. call updatePool() function

updatePool

Use Cases

function Params

NameTypeDescription
_piduint256The target Pool ID that the token will be updated

Logic

deposit

Use Cases

function Params

NameTypeDescription
_foraddressaddress 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.
_piduint256The target Pool ID that the token will be deposited to.
_amountuint256Amount of token that will be deposit in this function call

Logics

  1. Since this action will affect reward distribution to every user in the pool, the contract will call updatePool(_pid) function
  1. If user's already have share in the pool
    1. Harvest the outstanding rewards
    1. Transfer ERC20 token that associated to the poolID from user's to FairLaunch account
    1. 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
  1. Emit event Deposit

withdraw

Use case

function Params

NameTypeDescription
_foraddressdestination address
_piduint256Target Pool ID that will be withdrawn from
_amountuint256Amount of token to be withdrawn

Logic

  1. Call internal functoin _withdraw

withdrawAll

Use case

Copy of function Params

NameTypeDescription
_foraddressdestination address
_piduint256Target Pool ID that will be withdrawn from
_amountuint256Amount of token to be withdrawn

Logic

  1. Call internal functoin _withdraw with all the amount that user had in that pool

_withdraw

Use case

Params

function Params

NameTypeDescription
_foraddressAddress that will receive staked token back
_piduint256The target Pool ID that user will withdraw staked token from
_amountuint256Amount of token to be withdraw

Logics

  1. Update Pool
  1. Claim Alpaca rewards
  1. Reset the rewardDebt attribute (starting alpaca reward position)
  1. Transfer staked token back
  1. Emit Withdraw event

harvest

Use Cases

function Params

NameTypeDescription
_foraddressAddress that will receive Alpaca
_piduint256The target Pool ID that user will take Alpaca from

Logic

  1. update the pool and mint Alpaca to the pool of interest
  1. call _harvest function
  1. 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

Copy of function Params

NameTypeDescription
_foraddressAddress that will receive Alpaca
_piduint256The target Pool ID that user will take Alpaca from

Logic

  1. Calculate the amount of alpaca user will get
  1. Transfer ALPACA to the user's account

emergencyWithdraw

Use Case

function Params

NameTypeDescription
_piduint256The target Pool ID that user will withdraw staked token neglecting the Alpaca reward

Logics

  1. Only the funder of this user's portion of the pool can call this
  1. Transfer back the stake token to the caller
  1. Wipe user's data associated to this pool position

safeAlpacaTransfer

Use case

function Params

NameTypeDescription
_toaddressTarget address to send Alpaca to
_amountuint256Amount of Alpaca to be sent

Logic

  1. if the amount requested > remaining Alpaca in FairLaunch account, try to transfer all of what's left in the account
  1. else, try to transfer what has been requested