Double Rewards: A Developer's Guide

MasterChef v1 ⟶ MasterChef v2

MasterChef v1 (MCV1) is the only contract that has minting rights to $SUSHI, as the admin keys were burned. Hence, MasterChef v2 (MCV2) acts as an intermediary contract between the rewarder contracts and MCV1. Projects seeking to implement double rewards will need to implement a unique rewarder contract that is called by MCV2 on contract interactions. The specific utility of the rewarder contract is that it allows a partner project to add rewards for a specific pool by adding a contract that MCV2 calls whenever the user deposits, withdraws, or harvests SLP tokens (13:20: Keno describes the onSushiRewards; 13:59: Keno describes Harvest and pendingSushi). With our Rewarder interface, it is entirely your choice on how to implement a contract that gives out double incentives. This guide is intended to help partner projects understand MCV2, and facilitate the whitelisting process for their rewarder contracts. As you may have already noticed, this guide also parenthetically references Keno’s video demo of MCV2, available here. You can also find a time stamped reference guide for the video here.

Dependent or Independent

There are two types of rewarder contracts projects can use to incentivize their own liquidity on MasterChef: dependent (simple) and independent (complex). Sample implementations can be found here (SimpleRewarder) and here (ComplexRewarder). Although they share a common interface (14:35: Keno describes onSushiRewards, pendingTokens, and the interface), these different implementations have their own unique benefits and drawbacks.

Dependent (Simple)

In a dependent implementation of the rewarder contract, the additional rewards a project can offer are dependent on the amount of $SUSHI that is allocated to their pool (15:20: Keno describes the example simple contract). This means that projects using dependent rewarder contracts must have an allocation of $SUSHI given, or else their additional liquidity mining rewards will invariably be 0. That said, the dependent implementation of the rewarder contract is much simpler, less time consuming to develop, and cheaper for the end user. So, the dependent rewarder contract may be ideal for projects that know in advance they will be receiving an allocation of $SUSHI incentives. Dependent rewarder contracts are specified by setting a rewardMultiplier (15:51 Keno describes the rewardMultiplier). The rewardMultiplier is equal to the amount the partner project would like their rewardToken to be dispersed relative to the $SUSHI rewards in their pool. In the simplest case, this multiplier would be 1, which would entail 1:1 $SUSHI:rewardToken rewards. The rewardToken balance is dispersed in addition to the $SUSHI already being given out. Therefore, in a dependent implementation of a rewarder contract, the project in question simply needs to keep an artificial balance of the rewardToken in MCV2, that is calculated and dispersed to the user through the rewarder interface.

Independent (Complex)

An independent implementation of the rewarder contract is more customizable, but it is more difficult and more expensive for the end user, because it attaches more storage slots. The idea behind the independent rewarder contract is that it allows projects to distribute rewards at a rate that is determined by an independent variable (time-based logic or block-based logic), and the number of SLP tokens the user has (17:42: Keno describes the types of logic available for complex rewarders). The developer can use any baseline to calculate the reward multiplier independent of their $SUSHI allocation. Projects using the independent rewarder can add rewards to a SushiSwap pool without having any allocation of $SUSHI at all. The following values are passed through the rewarder contract to determine the calculations for the user’s rewards: the pool ID, the user’s address, the recipient’s address, the pending $SUSHI amount, and the new amount of LP tokens the user has after the event in question. In the example complex rewarder given in the first paragraph, a hybrid model is used to key into some of the storage advantages of MCV2, which allows for onSushiRewards to track any changes and harvest at the same time, which lowers the overhead accounting costs to a degree (18:36: Keno describes the hybrid model used).

Getting Your Contract Whitelisted

After the status of the allocations for a project has been confirmed by the SushiSwap team, you can get started. If you need the pool id on MasterChefV2, we can provide you with it in advance.

Dependent/Simple Rewarder

  1. Select the reward token multiplier indicating how many tokens are given out per sushi token earned, the reward token and MasterChefV2.

  2. Edit the Name to reflect your project e.g. SampleProjectRewarder.

  3. Deploy the rewarder and provide the SushiSwap team with the Rewarder address

  4. Fund the Rewarder by sending the tokens selected in step 1 to the contract.

Independent/Complex Rewarder

  1. Select tokens distributed per block, the reward token and MasterChefV2.

  2. Edit the Name to reflect your project e.g. SampleProjectRewarder.

  3. Deploy the ComplexRewarder and provide the SushiSwap team with the Rewarder address.

  4. Fund the Rewarder by sending the tokens selected in step 1 to the contract.