@donaswap/masterchef-v3

MasterChefV3 API

PoolInfo

struct PoolInfo {
  uint256 allocPoint;
  IDonaswapV3Pool v3Pool;
  address token0;
  address token1;
  uint24 fee;
  uint256 totalLiquidity;
  uint256 totalBoostLiquidity;
}

UserPositionInfo

struct UserPositionInfo {
  uint128 liquidity;
  uint128 boostLiquidity;
  int24 tickLower;
  int24 tickUpper;
  uint256 rewardGrowthInside;
  uint256 reward;
  address user;
  uint256 pid;
  uint256 boostMultiplier;
}

poolLength

uint256 poolLength

poolInfo

mapping(uint256 => PoolInfo) poolInfo

Info of each MCV3 pool.

userPositionInfos

mapping(uint256 => UserPositionInfo) userPositionInfos

userPositionInfos[tokenId] => UserPositionInfo

TokenId is unique, and we can query the pid by tokenId.

v3PoolPid

mapping(address => mapping(address => mapping(uint24 => uint256))) v3PoolPid

v3PoolPid[token0][token1][fee] => pid

v3PoolAddressPid

mapping(address => uint256) v3PoolAddressPid

v3PoolAddressPid[v3PoolAddress] => pid

CAKE

IERC20 CAKE

Address of CAKE contract.

WETH

address WETH

Address of WETH contract.

receiver

address receiver

Address of Receiver contract.

nonfungiblePositionManager

INonfungiblePositionManager nonfungiblePositionManager

LMPoolDeployer

ILMPoolDeployer LMPoolDeployer

Address of liquidity mining pool deployer contract.

FARM_BOOSTER

IFarmBooster FARM_BOOSTER

Address of farm booster contract.

emergency

bool emergency

Only use for emergency situations.

totalAllocPoint

uint256 totalAllocPoint

Total allocation points. Must be the sum of all pools' allocation points.

latestPeriodNumber

uint256 latestPeriodNumber

latestPeriodStartTime

uint256 latestPeriodStartTime

latestPeriodEndTime

uint256 latestPeriodEndTime

latestPeriodCakePerSecond

uint256 latestPeriodCakePerSecond

operatorAddress

address operatorAddress

Address of the operator.

PERIOD_DURATION

uint256 PERIOD_DURATION

Default period duration.

MAX_DURATION

uint256 MAX_DURATION

MIN_DURATION

uint256 MIN_DURATION

PRECISION

uint256 PRECISION

BOOST_PRECISION

uint256 BOOST_PRECISION

Basic boost factor, none boosted user's boost factor

MAX_BOOST_PRECISION

uint256 MAX_BOOST_PRECISION

Hard limit for maxmium boost factor, it must greater than BOOST_PRECISION

Q128

uint256 Q128

MAX_U256

uint256 MAX_U256

cakeAmountBelongToMC

uint256 cakeAmountBelongToMC

Record the cake amount belong to

constructor

constructor(IERC20 _CAKE, INonfungiblePositionManager _nonfungiblePositionManager, address _WETH) public

Parameters

Name	Type	Description
_CAKE	IERC20	The CAKE token contract address.
_nonfungiblePositionManager	INonfungiblePositionManager	the NFT position manager contract address.
_WETH	address

getLatestPeriodInfoByPid

function getLatestPeriodInfoByPid(uint256 _pid) public view returns (uint256 cakePerSecond, uint256 endTime)

Returns the cake per second , period end time.

Parameters

Name	Type	Description
_pid	uint256	The pool pid.

Return Values

Name	Type	Description
cakePerSecond	uint256	Cake reward per second.
endTime	uint256	Period end time.

getLatestPeriodInfo

function getLatestPeriodInfo(address _v3Pool) public view returns (uint256 cakePerSecond, uint256 endTime)

Returns the cake per second , period end time. This is for liquidity mining pool.

Parameters

Name	Type	Description
_v3Pool	address	Address of the V3 pool.

Return Values

Name	Type	Description
cakePerSecond	uint256	Cake reward per second.
endTime	uint256	Period end time.

pendingCake

function pendingCake(uint256 _tokenId) external view returns (uint256 reward)

View function for checking pending CAKE rewards.

The pending cake amount is based on the last state in LMPool. The actual amount will happen whenever liquidity changes or harvest.

Parameters

Name	Type	Description
_tokenId	uint256	Token Id of NFT.

Return Values

Name	Type	Description
reward	uint256	Pending reward.

setEmergency

function setEmergency(bool _emergency) external

For emergency use only.

setReceiver

function setReceiver(address _receiver) external

setLMPoolDeployer

function setLMPoolDeployer(ILMPoolDeployer _LMPoolDeployer) external

add

function add(uint256 _allocPoint, IDonaswapV3Pool _v3Pool, bool _withUpdate) external

Add a new pool. Can only be called by the owner. One v3 pool can only create one pool.

Parameters

Name	Type	Description
_allocPoint	uint256	Number of allocation points for the new pool.
_v3Pool	IDonaswapV3Pool	Address of the V3 pool.
_withUpdate	bool	Whether call "massUpdatePools" operation.

set

function set(uint256 _pid, uint256 _allocPoint, bool _withUpdate) external

Update the given pool's CAKE allocation point. Can only be called by the owner.

Parameters

Name	Type	Description
_pid	uint256	The id of the pool. See poolInfo.
_allocPoint	uint256	New number of allocation points for the pool.
_withUpdate	bool	Whether call "massUpdatePools" operation.

onERC721Received

function onERC721Received(address, address _from, uint256 _tokenId, bytes) external returns (bytes4)

Upon receiving a ERC721

harvest

function harvest(uint256 _tokenId, address _to) external returns (uint256 reward)

harvest cake from pool.

Parameters

Name	Type	Description
_tokenId	uint256	Token Id of NFT.
_to	address	Address to.

Return Values

Name	Type	Description
reward	uint256	Cake reward.

withdraw

function withdraw(uint256 _tokenId, address _to) external returns (uint256 reward)

Withdraw LP tokens from pool.

Parameters

Name	Type	Description
_tokenId	uint256	Token Id of NFT to deposit.
_to	address	Address to which NFT token to withdraw.

Return Values

Name	Type	Description
reward	uint256	Cake reward.

updateLiquidity

function updateLiquidity(uint256 _tokenId) external

Update liquidity for the NFT position.

Parameters

Name	Type	Description
_tokenId	uint256	Token Id of NFT to update.

updateBoostMultiplier

function updateBoostMultiplier(uint256 _tokenId, uint256 _newMultiplier) external

Update farm boost multiplier for the NFT position.

Parameters

Name	Type	Description
_tokenId	uint256	Token Id of NFT to update.
_newMultiplier	uint256	New boost multiplier.

IncreaseLiquidityParams

struct IncreaseLiquidityParams {
  uint256 tokenId;
  uint256 amount0Desired;
  uint256 amount1Desired;
  uint256 amount0Min;
  uint256 amount1Min;
  uint256 deadline;
}

increaseLiquidity

function increaseLiquidity(struct IncreaseLiquidityParams params) external payable returns (uint128 liquidity, uint256 amount0, uint256 amount1)

Increases the amount of liquidity in a position, with tokens paid by the msg.sender

Parameters

Name	Type	Description
params	struct IncreaseLiquidityParams	tokenId The ID of the token for which liquidity is being increased, amount0Desired The desired amount of token0 to be spent, amount1Desired The desired amount of token1 to be spent, amount0Min The minimum amount of token0 to spend, which serves as a slippage check, amount1Min The minimum amount of token1 to spend, which serves as a slippage check, deadline The time by which the transaction must be included to effect the change

Return Values

Name	Type	Description
liquidity	uint128	The new liquidity amount as a result of the increase
amount0	uint256	The amount of token0 to acheive resulting liquidity
amount1	uint256	The amount of token1 to acheive resulting liquidity

DecreaseLiquidityParams

struct DecreaseLiquidityParams {
  uint256 tokenId;
  uint128 liquidity;
  uint256 amount0Min;
  uint256 amount1Min;
  uint256 deadline;
}

decreaseLiquidity

function decreaseLiquidity(struct DecreaseLiquidityParams params) external returns (uint256 amount0, uint256 amount1)

Decreases the amount of liquidity in a position and accounts it to the position

Parameters

Name	Type	Description
params	struct DecreaseLiquidityParams	tokenId The ID of the token for which liquidity is being decreased, amount The amount by which liquidity will be decreased, amount0Min The minimum amount of token0 that should be accounted for the burned liquidity, amount1Min The minimum amount of token1 that should be accounted for the burned liquidity, deadline The time by which the transaction must be included to effect the change

Return Values

Name	Type	Description
amount0	uint256	The amount of token0 accounted to the position's tokens owed
amount1	uint256	The amount of token1 accounted to the position's tokens owed

CollectParams

struct CollectParams {
  uint256 tokenId;
  address recipient;
  uint128 amount0Max;
  uint128 amount1Max;
}

collect

function collect(struct CollectParams params) external returns (uint256 amount0, uint256 amount1)

Collects up to a maximum amount of fees owed to a specific position to the recipient

Warning!!! Please make sure to use multicall to call unwrapWETH9 or sweepToken when set recipient address(0), or you will lose your funds. amount0Max The maximum amount of token0 to collect, amount1Max The maximum amount of token1 to collect

Parameters

Name	Type	Description
params	struct CollectParams	tokenId The ID of the NFT for which tokens are being collected, recipient The account that should receive the tokens,

Return Values

Name	Type	Description
amount0	uint256	The amount of fees collected in token0
amount1	uint256	The amount of fees collected in token1

collectTo

function collectTo(struct CollectParams params, address to) external returns (uint256 amount0, uint256 amount1)

Collects up to a maximum amount of fees owed to a specific position to the recipient, then refund.

Parameters

Name	Type	Description
params	struct CollectParams	CollectParams.
to	address	Refund recipient.

Return Values

Name	Type	Description
amount0	uint256	The amount of fees collected in token0
amount1	uint256	The amount of fees collected in token1

unwrapWETH9

function unwrapWETH9(uint256 amountMinimum, address recipient) external

Unwraps the contract's WETH9 balance and sends it to recipient as ETH.

The amountMinimum parameter prevents malicious contracts from stealing WETH9 from users.

Parameters

Name	Type	Description
amountMinimum	uint256	The minimum amount of WETH9 to unwrap
recipient	address	The address receiving ETH

sweepToken

function sweepToken(address token, uint256 amountMinimum, address recipient) external

Transfers the full amount of a token held by this contract to recipient

The amountMinimum parameter prevents malicious contracts from stealing the token from users

Parameters

Name	Type	Description
token	address	The contract address of the token which will be transferred to recipient
amountMinimum	uint256	The minimum amount of token required for a transfer
recipient	address	The destination address of the token

burn

function burn(uint256 _tokenId) external

Burns a token ID, which deletes it from the NFT contract. The token must have 0 liquidity and all tokens must be collected first.

Parameters

Name	Type	Description
_tokenId	uint256	The ID of the token that is being burned

upkeep

function upkeep(uint256 _amount, uint256 _duration, bool _withUpdate) external

Upkeep period.

Parameters

Name	Type	Description
_amount	uint256	The amount of cake injected.
_duration	uint256	The period duration.
_withUpdate	bool	Whether call "massUpdatePools" operation.

updatePools

function updatePools(uint256[] pids) external

Update cake reward for the liquidity mining pool.

Avoid too many pools, and a single transaction cannot be fully executed for all pools.

setOperator

function setOperator(address _operatorAddress) external

Set operator address.

Callable by owner

Parameters

Name	Type	Description
_operatorAddress	address	New operator address.

setPeriodDuration

function setPeriodDuration(uint256 _periodDuration) external

Set period duration.

Callable by owner

Parameters

Name	Type	Description
_periodDuration	uint256	New period duration.

updateFarmBoostContract

function updateFarmBoostContract(address _newFarmBoostContract) external

Update farm boost contract address.

Parameters

Name	Type	Description
_newFarmBoostContract	address	The new farm booster address.

ZeroAddress

error ZeroAddress()

NotOwnerOrOperator

error NotOwnerOrOperator()

NoBalance

error NoBalance()

NotDonaswapNFT

error NotDonaswapNFT()

InvalidNFT

error InvalidNFT()

NotOwner

error NotOwner()

NoLiquidity

error NoLiquidity()

InvalidPeriodDuration

error InvalidPeriodDuration()

NoLMPool

error NoLMPool()

InvalidPid

error InvalidPid()

DuplicatedPool

error DuplicatedPool(uint256 pid)

NotEmpty

error NotEmpty()

WrongReceiver

error WrongReceiver()

InconsistentAmount

error InconsistentAmount()

InsufficientAmount

error InsufficientAmount()

Init

event Init()

AddPool

event AddPool(uint256 pid, uint256 allocPoint, IDonaswapV3Pool v3Pool, ILMPool lmPool)

SetPool

event SetPool(uint256 pid, uint256 allocPoint)

Deposit

event Deposit(address from, uint256 pid, uint256 tokenId, uint256 liquidity, int24 tickLower, int24 tickUpper)

Withdraw

event Withdraw(address from, address to, uint256 pid, uint256 tokenId)

UpdateLiquidity

event UpdateLiquidity(address from, uint256 pid, uint256 tokenId, int128 liquidity, int24 tickLower, int24 tickUpper)

NewOperatorAddress

event NewOperatorAddress(address operator)

NewLMPoolDeployerAddress

event NewLMPoolDeployerAddress(address deployer)

NewReceiver

event NewReceiver(address receiver)

NewPeriodDuration

event NewPeriodDuration(uint256 periodDuration)

Harvest

event Harvest(address sender, address to, uint256 pid, uint256 tokenId, uint256 reward)

NewUpkeepPeriod

event NewUpkeepPeriod(uint256 periodNumber, uint256 startTime, uint256 endTime, uint256 cakePerSecond, uint256 cakeAmount)

UpdateUpkeepPeriod

event UpdateUpkeepPeriod(uint256 periodNumber, uint256 oldEndTime, uint256 newEndTime, uint256 remainingCake)

UpdateFarmBoostContract

event UpdateFarmBoostContract(address farmBoostContract)

SetEmergency

event SetEmergency(bool emergency)