GitHubDiscordX/Twitter

DistributionV5

Introduction

The DistributionV5 contract is the core logic and coordination layer of the protocol on Ethereum. It is responsible for managing all aspects of user staking, calculating reward entitlements, handling multipliers, enforcing locking logic, and coordinating cross-chain reward delivery via LayerZero.

Key Responsibilities

  1. User staking and tracking:

    • Allows users to deposit stETH into the protocol’s staking system.

    • Supports custom staking options like specifying a claimLockEnd_ (lock duration) and setting a referrer address to benefit from referral multipliers.

    • Keeps detailed records of each user’s stake, including lock periods, multipliers.

  2. Reward distribution logic:

    • Computes user reward entitlements based on their stake amount, stake duration, pool configuration, referral status, and global reward emission rates.

    • Allocates rewards across multiple reward pools (“buckets”), such as Capital, Builder, Compute, Code, and Protection — each with independent reward supply and logic.

    • Ensures fair, non-overlapping distribution across these groups.

  3. Power factor and referral system:

    • Integrates a lock-based power factor system, rewarding users who lock their claim for longer periods.

    • Implements a referral tier system, where both the referrer and referred user can receive enhanced yield.

    • Dynamically recalculates multipliers on every stake update, using precise mathematical formulas defined in external libraries (e.g., LinearDistributionIntervalDecrease, ReferrerLib).

  4. Cross-chain reward dispatch:

    • After reward calculation, it communicates with the L1Sender contract to send reward payloads to Arbitrum (L2).

    • Uses LayerZero to send encoded reward data to the L2MessageReceiver, where actual MOR tokens are minted and delivered to users.

  5. Data and State Management:

    • Maintains granular, bucket-specific data about user stakes, referral structures, and global reward metrics.

    • Optimizes gas costs and ensures integrity by storing only the necessary state variables and leveraging internal libraries for math and reward logic.

Storage

isNotUpgradeable

Returns true if the contract no longer supports upgrades to a new version.

bool public isNotUpgradeable;

depositToken

The stETH token address, see the LIDO doc.

address public depositToken;

l1Sender

The L1Sender contract address.

address public l1Sender;

pools

Contain information about MOR reward pools for buckets. pools[<poolId>].

Pool[] public pools;
 
struct Pool {
  uint128 payoutStart;
  uint128 decreaseInterval;
  uint128 withdrawLockPeriod;
  uint128 claimLockPeriod;
  uint128 withdrawLockPeriodAfterStake;
  uint256 initialReward;
  uint256 rewardDecrease;
  uint256 minimalStake;
  bool isPublic;
}
Name
Description

payoutStart

The unix epoch timestamp in seconds when the pool starts to pay out rewards.

decreaseInterval

The interval in seconds between reward decreases.

withdrawLockPeriod

The period in seconds when the user can't withdraw his stake.

claimLockPeriod

The period in seconds when the user can't claim his rewards after the payoutStart

withdrawLockPeriodAfterStake

The period in seconds when the user can't withdraw his stake after staking.

initialReward

The initial MOR reward for the bucket.

rewardDecrease

The MOR reward decrease per decreaseInterval.

minimalStake

The minimal stake amount

isPublic

true - for Capital bucket, false for others.

poolsData

Contain additional internal information about MOR reward pools for buckets. poolsData[<poolId>].

mapping(uint256 => PoolData) public poolsData;

struct PoolData {
  uint128 lastUpdate;
  uint256 rate;
  uint256 totalVirtualDeposited;
}
Name
Description

lastUpdate

The unix epoch timestamp when the rate was updated.

rate

The current pool coefficient, used to calculate awards.

totalVirtualDeposited

The total amount of stETH deposited in the pool with multiplier.

usersData

Stores all staking-related data for users. usersData[<stakerAddress>][<poolId>].

mapping(address => mapping(uint256 => UserData)) public usersData;

struct UserData {
  uint128 lastStake;
  uint256 deposited;
  uint256 rate;
  uint256 pendingRewards;
  uint128 claimLockStart;
  uint128 claimLockEnd;
  uint256 virtualDeposited;
  uint128 lastClaim;
  address referrer;
}
Name
Description

lastStake

The unix epoch timestamp when the user stake was last.

deposited

The amount of staked stETH.

rate

The last user reward rate, used to calculate awards.

pendingRewards

The last saved MOR rewards for the user. This value is updated when stake, withdraw or claim from the user account occurs. It is not the final award.

claimLockStart

MOR rewards lock period starts at this timestamp.

claimLockEnd

MOR rewards lock period end at this timestamp.

virtualDeposited

The amount of staked stETH, with multipliers.

lastClaim

The last claim timestamp.

referrer

The referrer address.

totalDepositedInPublicPools

Tracks the total amount of stETH deposited in the public pools (specifically the capital bucket).

poolsLimits

Defines pool-specific limits and parameters. poolsLimits[<poolId>] - limits for the capital bucket.

mapping(uint256 => PoolLimits) public poolsLimits;

struct PoolLimits {
  uint128 claimLockPeriodAfterStake;
  uint128 claimLockPeriodAfterClaim;
}
Name
Description

claimLockPeriodAfterStake

The period in seconds when the staker can't claim tokens after staking.

claimLockPeriodAfterClaim

The period in seconds when the user can't claim tokens after claiming

referrerTiers

Stores referral reward tiers per pool. referrerTiers[<poolId>][<tierIndex>].

mapping(uint256 => ReferrerTier[]) public referrerTiers;

struct ReferrerTier {
  uint256 amount;
  uint256 multiplier;
}
Name
Description

amount

The minimal token amount for the tier

multiplier

The multiplier for the tier, where 1% = 0.01 * 1025.

referrersData

Tracks referral activity per user and pool. referrersData[<stakerAddress>][<poolId>].

mapping(address => mapping(uint256 => ReferrerData)) public referrersData;

struct ReferrerData {
  uint256 amountStaked;
  uint256 virtualAmountStaked;
  uint256 rate;
  uint256 pendingRewards;
  uint128 lastClaim;
}
Name
Description

amountStaked

The amount of referred stETH.

virtualAmountStaked

The amount of referred stETH, with multipliers.

rate

The last referrer reward rate, used to calculate awards.

pendingRewards

The last saved MOR rewards for the referrer. It is not the final award.

lastClaim

The last claim timestamp.

Write functions for stakers

stake

The stake function allows users to deposit stETH into the protocol from the Ethereum network, then the staker will get a share of the rewards. 

stake(
  uint256 poolId_,
  uint256 amount_, 
  uint128 claimLockEnd_, 
  address referrer_
) external;
Name
Description

poolId_

The reward pool ID.

amount_

The stETH amount to stake, where 1 stETH = 1018.

claimLockEnd_

The unix epoch timestamp in seconds. Use the default zero value.

referrer_

The referrer address. Use the default zero address.

withdraw

The withdraw function allows users to retrieve their staked stETH after a withdraw lock period.

function withdraw(
  uint256 poolId_, 
  uint256 amount_
) external;
Name
Description

poolId_

The reward pool ID.

amount_

The stETH amount to withdraw, where 1 stETH = 1018.

claim

The claim function enables stakers to receive the MOR tokens they’ve accrued.

function claim(
  uint256 poolId_, 
  address receiver_
) external payable;
Name
Description

poolId_

The reward pool ID.

receiver_

The address who will receive MOR on L2.

lockClaim

The function to lock rewards and receive claim lock multiplier (power factor). Used when a user has an active stake and wants to receive a multiplier without triggering a new staking transaction.

function lockClaim(
  uint256 poolId_,
  uint128 claimLockEnd_
) external poolExists(poolId_);
Name
Description

poolId_

The reward pool ID.

claimLockEnd_

The unix epoch timestamp in seconds.

claimReferrerTier

The function enables referrer to receive the MOR tokens they’ve accrued.

function claimReferrerTier(
  uint256 poolId_, 
  address receiver_
) external payable poolExists(poolId_);
Name
Description

poolId_

The reward pool ID.

receiver_

The address who will receive MOR on L2.

Write functions for contract owner

Distribution_init

Initializes the contract. This is a one-time setup function, used during deployment via proxies.

function DistributionV5_init(
  address depositToken_,
  address l1Sender_,
  Pool[] calldata poolsInfo_
) external initializer;
Name
Description

depositToken_

The stETH token address.

l1Sender_

The L1Sender contract address.

poolsInfo_

The rewards pools info (buckets reward info).

createPool

The function to create a new reward pool for the bucket.

function createPool(Pool calldata pool_) public onlyOwner;
Name
Description

pool_

The rewards pool info (bucket reward info).

editPool

The function to edit an existed reward pool for the bucket.

function editPool(
  uint256 poolId_,
  Pool calldata pool_
) external onlyOwner poolExists(poolId_);
Name
Description

pool_

The rewards pool info (bucket reward info).

poolId_

The reward pool ID.

editPoolLimits

The function to edit the reward pool limits.

function editPoolLimits(
  uint256 poolId_,
  PoolLimits calldata poolLimits_
) external onlyOwner poolExists(poolId_);
Name
Description

poolId_

The reward pool ID.

poolLimits_

The pool's limit data.

manageUsersInPrivatePool

The function to manage users and their rate in the private pool (not capital bucket). This function specifically controls the user shares in the other buckets.

function manageUsersInPrivatePool(
  uint256 poolId_,
  address[] calldata users_,
  uint256[] calldata amounts_,
  uint128[] calldata claimLockEnds_,
  address[] calldata referrers_
) external onlyOwner poolExists(poolId_);
Name
Description

poolId_

The reward pool ID.

users_

The users addresses.

amounts_

The virtual staked amount vlaues for users_

claimLockEnds_

The claim lock end values for users_.

referrers_

The referrer values for users_

editReferrerTiers

The function to setup tiers for the refferal system.

function editReferrerTiers(
  uint256 poolId_,
  ReferrerTier[] calldata referrerTiers_
) external onlyOwner poolExists(poolId_)
Name
Description

poolId_

The reward pool ID.

referrerTiers_

The referrer tiers structs.

bridgeOverplus

The function transfers the stETH yield from L1 to L2. Returns the unique identifier for the trabsfer operation from the Arbitrum Bridge.

function bridgeOverplus(
  uint256 gasLimit_,
  uint256 maxFeePerGas_,
  uint256 maxSubmissionCost_
) external payable onlyOwner returns (bytes memory);
Name
Description

gasLimit_

The gas limit for the Arbitrum Bridge.

maxFeePerGas_

The max fee per gas for the Arbitrum Bridge.

maxSubmissionCost_

The max submission cost.

removeUpgradeability

The function to remove the possibility to upgrade the smart contract.

function removeUpgradeability() external onlyOwner;

Read functions

getPeriodReward

The function to calculate the bucket rewards for the specified period. Returns the reward amount, where 1 MOR = 1018.

function getPeriodReward(
  uint256 poolId_,
  uint128 startTime_,
  uint128 endTime_
) external view returns (uint256);
Name
Description

poolId_

The reward pool ID.

startTime_

The unix timestamp. Start calculate rewards from this timestamp.

endTime_

The unix timestamp. End calculate rewards to this timestamp.

getCurrentUserReward

This function calculates the total claimable MOR token rewards for a given staker within a specific bucket, based on their current stake and multipliers. Where 1 MOR = 1018.

function getCurrentUserReward(
  uint256 poolId_, 
  address user_
) external view returns (uint256);
Name
Description

poolId_

The reward pool ID.

user_

The staker address.

getCurrentReferrerReward

This function calculates the total claimable MOR token rewards for a given referrer within a specific bucket, based on referrals and tier multipliers. Where 1 MOR = 1018.

function getCurrentReferrerReward(
  uint256 poolId_, 
  address user_
) public view returns (uint256)
Name
Description

poolId_

The reward pool ID.

user_

The staker address.

getClaimLockPeriodMultiplier

The function to calculate the power factor for the specified period. Returns the multiplier, where x1 = 1025.

function getClaimLockPeriodMultiplier(
  uint256 poolId_,
  uint128 claimLockStart_,
  uint128 claimLockEnd_
) public view returns (uint256)
Name
Description

poolId_

The reward pool ID.

claimLockStart_

The unix timestamp. Start calculate the power factor from this timestamp.

claimLockEnd_

The unix timestamp. End calculate the power factor to this timestamp.

getCurrentUserMultiplier

The function to calculate the power factor and referrer multiplier for the specified staker. Returns the multiplier, where x1 = 1025.

function getCurrentUserMultiplier(
  uint256 poolId_, 
  address user_
) public view returns (uint256)
Name
Description

poolId_

The reward pool ID.

user_

The staker address.

getReferrerMultiplier

The function to calculate the tier multiplier for the specified referrer. Returns the multiplier, where x1 = 1025.

function getReferrerMultiplier(
  uint256 poolId_,
  address referrer_
) public view returns (uint256)
Name
Description

poolId_

The reward pool ID.

referrer_

The referrer address.

overplus

The function to calculate the current protocol yield, the difference between staked stETH and current contract balance.

function overplus() external view returns (uint256);

Last updated

Was this helpful?