https://github.com/alpaca-finance/bsc-alpaca-contract/blob/main/contracts/6/protocol/workers/pcs/PancakeswapV2Worker02.sol

Table of content

Background

Once user want to open position / manage position at PancakeSwap farming, a vault contract will call a contract that deployed with this worker contract

PancakeSwap is an AMM DEX that allows traders to convert one asset to another asset without order book. Users can provide liquidity to the market by providing a pair of asset with 1:1 value. For example, if current price of BNB = 500 USDT, liquidity provider need to provide 1 BNB and 500 USDT to the liquidity pool so that other can exchange directly with the pool instead of another trader.

To provide incentive to liquidity provider, AMM DEX traditionally grant a third token as a reward to compensate the opportunity cost of trading. This is where the yield farming come in to play. Alpaca finance provide a platform that allow liquidity provider to provide a liquidity with margin. Meaning they can provide a liquidity more than they currently have.

In this implementation of worker at PancakeSwap, the responsibility of PancakeSwap worker is to manage the LP token on behalf of users. This also included the borrowed capital as well.

Abstract

• PancakeSwap is a fork of UniSwap V2 and use constant x*y = k curve AMM as their engine.

• Each worker that get deployed will have a different set of base token and farm token. Read more about base token and farm token at Worker Contract

• Worker keep track of each position portion relative to total amount of LP that this worker hold on behalf of user by
  • LP share : Represent a portion of LP token with respect to the overall LP token that this worker hold
  • LP Balance : Actual amount of LP token that will be used to deposit to / withdraw from PancakeSwap MasterChef contract
  • ** Note. PancakeSwap MasterChef contract work similarly like Alpaca's FairLaunch contract. FairLaunch Contract

Attributes

Modifier

onlyEOAorWhitelisted

/// @dev Require that the caller must be an EOA account to avoid flash loans.
  modifier onlyEOA() {
    require(msg.sender == tx.origin, "PancakeswapV2Worker02::onlyEOA:: not eoa");
    _;
  }

Logic

1. the caller must be an external own account.

2. Otherwise, revert transaction.

onlyOperator

/// @dev Require that the caller must be the operator.
  modifier onlyOperator() {
    require(msg.sender == operator, "PancakeswapV2Worker02::onlyOperator:: not operator");
    _;
  }

Logic

1. the caller address must be the same as configured

2. Otherwise, revert transaction.

onlyReinvestor

//// @dev Require that the caller must be ok reinvestor.
  modifier onlyReinvestor() {
    require(okReinvestors[msg.sender], "PancakeswapV2Worker02::onlyReinvestor:: not reinvestor");
    _;

Logic

1. the caller address must be the same as configured

2. Otherwise, revert transaction.

Functions

initialize

Use case

• Deploy worker to be allow users to work on a specific base token / farm token pair

Logic

1. Set corresponding state variable

2. Check validity of configuration

shareToBalance

Use case

• Check the LP balance that belongs to the user

Logic

1. When there's no share, 1 share = 1 balance

2. Get total balance from PancakeSwap MasterChef contract

3. Calculate balance by total balance * ( share / total share in this contract )

balanceToShare

Use case

• Convert token amount to share amount respectively to this contract's total share

Logic

1. When there's no share, 1 share = 1 balance

2. Get total balance as a denominator from PancakeSwap MasterChef contract

3. calculate share by total share * (balance / total balance)

reinvest

Use case

• Allow whitelisted bot to claim CAKE reward, convert to LP token, compound back to the positions

• ** There will be fee for doing so that will go to reinvest bot. This will be our platform revenue.

Logic

1. Call _reinvest() internal function passing the caller address as a treasury account

2. call _buyback() internal function

_reinvest

Use case

• Called from reinvest function

• Triggered at the beginning of work function where positions are being adjust

Logic

1. Claim all the CAKE reward first

2. Check CAKE balance in this contract

3. If CAKE is below reinvest threshold, exit this function

4. calculate bounty for calling this reinvest function by _treasuryBountyBps * total CAKE reward

5. Cut some amount our of bounty to beneficial vault ( Vault's contract )

6. Transfer remaining bounty reward to treasury account

7. Convert all non-bounty reward to base token

8. Transfer base token to configure strategy contract that will do the converting BaseToken to LP token

9. Execute the strategy, expected the strategy will transfer the LP back

10. Deposit all LP token to PancakeSwap's MasterChef contract

work

Use case

• Called by a vault contract to do one of the following
  • Open position
  • Add collateral
  • Close position
  • Partially close the position

Logic

1. trigger _reinvest internal function if configured

2. Get the share amount of this position and convert it back to LP token

3. Execute a strategy contract that passed via data variable

4. add the LP token back to PancakeSwap's MasterChef contract. If the action is to close the position this will eventually be skipped

5. Return any remaining BaseToken back to the caller. Typically the vault contract.

getMktSellAmount

Use case

• Check the position value as a base token amount if the position to be convert all to the base token

• Called from health function

Logic

1. If aIn = 0, return 0

2. calculate using x*y = k formula

3. return the calculation with trading fee in consideration

health

Use case

• Check the position's health

• Use to check validity of liquidation of the position

• Display the health in Alpaca frontend interface

Logic

1. Calculate the LP of this position

2. Get the pool's total supply of BaseToken and FarmingToken

3. Calculate the token amounts if to convert the position's LP tokens to the underlying assets

4. call getMktSellAmount function supplying farm token as an input

5. return the sum of base token from step 3 and step 4

liquidate

Use case

• Once the position is underwater, meaning the debt of the position almost equal to the collateral, the position will be eligible for liquidation

• LP token will be convert to base token, return the debt to a vault contract and remaining back to position owner

Logic

1. Convert the position back to LP tokens

2. Transfer the LP token to configured liquidation strategy contract

3. Return all available BaseToken back to the caller, typically a vault contract

_rewardToBeneficialVault

Use case

• Called from _reinvest function

• use to transfer part of the CAKE reward to the vault that associated with this position

Logic

1. read base token from the vault of interest contract

2. swap reward token to beneficialVaultToken

3. if beneficialvault token not equal to baseToken regardless of a caller balance, can directly transfer to beneficial vault
   1. otherwise, need to keep it as a buybackAmount,

** since beneficial vault is the same as the calling vault, it will think of this reward as a `back` amount to pay debt/ sending back to a position owner

_buyback

Use case

• If the base token of the worker is not the same with the vault token, this will be skipped

Logic

1. Transfer the token to beneficial vault contract

actualBaseTokenBalance

Use case

• Since buybackAmount variable has been created to collect a buyback balance when during the reinvest within the work method, thus the actualBaseTokenBalance exists to differentiate an actual base token balance balance without taking buy back amount into account

Logic

1. Return token amount excluding the amount to buyback

_addShare

Use case

• Internal function to stake all outstanding LP tokens to the given position ID

• Used at the end of when there's an operation to the positions

Logic

1. Get the total amount of LP hold by this contract

2. If there's none, exit

3. deposit all LP token to PancakeSwap's MasterChef contract

4. Calculate the share of this position

5. Update the total share value

_removeShare

Use case

• At the beginning of ever work operation on positions, it will call this function to recalculate everything

• If position to be liquidate, this will be called as well

Logic

1. Calculate the LP balance from the share of the position

2. Withdraw amount of LP from step 1 from PancakeSwap MasterChef contract

3. Subtract the position share from total share of this contract

getPath

Use case

• Check the path that the worker is working on

Logic

1. Return array of address where first element is the base token address and farm token as the second element

getReversedPath

Use case

• Check the path that the worker is working on but in reverse direction

Logic

1. Return array of address where first element is the farm token address and base token as the second element

getRewardPath

Use case

• Check the configured path of reward

Logic

1. Return the reward path vairable

getReinvestPath

Use case

• Internal function to get reinvest path. Return route through WBNB if reinvestPath not set

• Used in _reinvest function where swapping reward token to base token happened

Logic

1. If the configured path has more than one element, return the configured one

2. If the base token is a wrap Native token, return an array of reward as a first element and wNative token as the second element

3. If the base token is an ERC20 token, return an array of reward as a first element and wNative token as the second element, and base token as a last element

setReinvestConfig

Use case

• Config parameters for the reinvest operation

Logic

1. Set state variables according to the function input

setMaxReinvestBountyBps

Use case

• Additional configuration to reinvest scenario

Logic

1. Set the state variable from the function input

2. Basis point can't exceed 3000 (30%)

setStrategyOk

Use case

• Whitelist the contract list of strategies that this worker can call

• This is to prevent malicious strategy contract injection

Logic

1. Loop through all address

2. Set the flag to whitelist/blacklist according to isOk flag

setReinvestorOk

Use case

• Whitelist the list of reinvest address allowed to do reinvest operation

• This is to prevent malicious reinvestor that can manipulate the price of underlying LP pair then liquidate

Logic

1. Loop through all address

2. Set the flag to whitelist/blacklist according to isOk flag

setRewardPath

Use case

• Set path for converting CAKE token to base token

Logic

1. Last element of the array must be the base token

2. Set the state variable from the function input

setCriticalStrategies

Use case

• Set the strategy contract addresses that is a mandatory to operate a worker contract
  • Add base token strategy
    • Open position
    • Reinvest
    • Add collateral
  • Liquidate strategy
    • Close position
    • Liquidate position

Logic

1. Set state variables according to the function input

setTreasuryConfig

Use case

• Set treasury configurations

Logic

1. Set state variables according to the function input

setBeneficialVaultConfig

Use case

• Set beneficial vault related data including beneficialVaultBountyBps, beneficialVaultAddress, and rewardPath

Logic

1. Set state variables according to the function input