Reward Debt

Reward debt is a ledger entry within a liquidity mining or staking smart contract that represents the cumulative rewards a user has earned but not yet claimed, effectively functioning as an IOU from the protocol to the liquidity provider. It is a core component of the MasterChef-style contract architecture, popularized by decentralized exchanges like PancakeSwap and SushiSwap. The system calculates rewards based on a user's proportional share of the total staked assets, and reward debt ensures that this accrued value is preserved even if other users deposit or withdraw, preventing reward miscalculations and exploitation.

The mechanism works by updating a global accTokenPerShare variable that accumulates rewards per staked token over time. When a user deposits liquidity provider (LP) tokens, their rewardDebt is set to (user.amount * accTokenPerShare) / precision. When they later claim rewards or withdraw, the contract calculates their pending rewards as (user.amount * accTokenPerShare) / precision - user.rewardDebt, pays out that amount, and then resets their rewardDebt to the new calculated value. This ensures users are only paid for rewards accrued during the period their tokens were staked.

A critical implication of reward debt is that it creates a claim-before-action requirement. If a user adds more LP tokens to their stake (deposit), their existing rewardDebt is updated, which will claim any pending rewards automatically. Conversely, withdrawing tokens (withdraw) also triggers a claim. Failing to understand this can lead to confusion, as users might see a "pending rewards" balance disappear after a deposit—this is not a loss, but an automatic collection. The rewardDebt system elegantly prevents reward dilution and sandwich attacks by fixing a user's share at the moment of each transaction.

In practice, developers and analysts monitor reward debt to audit reward distribution and ensure contract integrity. A user's rewardDebt will always be less than or equal to the theoretical maximum based on accTokenPerShare, with the difference representing the claimable amount. This model is foundational for yield farming and has been adapted for staking derivatives and veTokenomics. Understanding reward debt is essential for building or interacting with any protocol that distributes tokens proportionally to staked capital over time.

Reward debt is an internal ledger entry in a staking or liquidity pool smart contract that represents the total amount of rewards a user has already been accounted for based on their share of the pool. When a user deposits assets (e.g., LP tokens), the contract calculates their initial reward debt as (user shares * pool.accRewardPerShare). This value is not a penalty but a baseline used to compute future payouts. When the user later claims or harvests rewards, the contract calculates the difference between the current accumulated rewards for their share and this stored debt, paying out only the delta.

The mechanism ensures proportional and fair distribution as the pool's total rewards grow. Each time rewards are distributed to the pool (e.g., from a rewarder contract or protocol emissions), the accRewardPerShare variable increases. A user's claimable reward at any moment is determined by the formula: (userShares * currentAccRewardPerShare) - userRewardDebt. This design is gas-efficient, as it avoids the need to update every user's balance on each reward distribution event, instead updating a single global accumulator and performing the subtraction only upon user interaction.

A key behavioral insight is that reward debt increases when you stake more. If a user adds to their position, their new reward debt is recalculated based on the updated, higher accRewardPerShare, effectively resetting their claimable rewards for the new deposit to zero from that point forward. This prevents users from receiving retroactive rewards for deposits made after the rewards were accrued. Conversely, when rewards are claimed, the user's reward debt is set to userShares * accRewardPerShare, moving the baseline forward and zeroing out their current claimable balance.

This system is foundational in major DeFi protocols like SushiSwap's MasterChef and its numerous forks. Understanding reward debt is crucial for developers building on these patterns and for users to interpret their pending rewards correctly on interfaces. It explains why pending rewards might appear to reset or change unexpectedly after a deposit or withdrawal, as these actions trigger a recalculation of the debt baseline against the latest global accumulator.

The following pseudocode outlines a simplified staking pool contract. It tracks two key global state variables: accRewardPerShare, which accumulates rewards per staked token, and totalStaked. For each user, it stores their amount of staked tokens and their rewardDebt. The rewardDebt is calculated as user.amount * accRewardPerShare and represents the portion of the accumulated rewards already accounted for the user. When a user deposits or withdraws, their pending rewards are settled by comparing the new accRewardPerShare to the value locked in their rewardDebt.

The deposit function illustrates the core flow. First, it calls an internal _updatePool function to mint new rewards and increase accRewardPerShare. Then, it calculates any pendingReward for the user by taking the difference between their current share of the pool (user.amount * accRewardPerShare) and their stored rewardDebt. This pending amount is sent to the user. Finally, the user's staked amount is increased, and their rewardDebt is recalculated and updated to reflect their new position under the latest accRewardPerShare.

The withdraw function follows an identical accounting pattern but decreases the user's staked amount. Crucially, the _updatePool and pending reward settlement must occur before the user's stake amount changes. This ensures the reward calculation is based on their contribution up to that exact moment. The rewardDebt acts as a cursor or checkpoint, allowing the contract to efficiently calculate what a user is owed between interactions without iterating over all historical transactions.

Reward debt is a cumulative accounting variable used in Automated Market Maker (AMM) liquidity pools, such as those on PancakeSwap, to track a liquidity provider's (LP) share of accrued but unclaimed rewards. When a user deposits liquidity, the contract records their rewardDebt as their staked share multiplied by the pool's current accRewardPerShare. To claim rewards, the contract calculates the difference between the new accRewardPerShare multiplied by the user's share and their stored rewardDebt. This system ensures rewards are distributed proportionally to the amount and duration of a user's stake, preventing front-running and ensuring fairness.

The mechanism operates on a first-in, first-out (FIFO) principle for reward accrual. The key formula is: pendingRewards = (user.amount * pool.accRewardPerShare) - user.rewardDebt. When rewards are deposited into the pool (e.g., CAKE tokens into a syrup pool), the accRewardPerShare increases globally. A user's rewardDebt acts as a personal ledger entry, marking the point up to which they have already been accounted for. Any new rewards accumulate in the delta between this personal marker and the updated global state. This design is gas-efficient, as it only performs calculations when users interact with the contract via deposits, withdrawals, or claims.

Understanding reward debt is essential for LPs to avoid common pitfalls. For example, if you deposit into a pool with a high accRewardPerShare, your initial rewardDebt will be correspondingly high, meaning you must wait for the global accumulator to increase further before you generate claimable rewards. Conversely, an early depositor benefits from a low starting debt. Crucially, withdrawing liquidity forfeits any unclaimed rewards represented by the pending calculation. This system directly interacts with related concepts like vesting schedules and multi-reward farms, where separate debt variables may track different token emissions.