Skip to main content

Contract Overview

For understanding the mechanics and the advantatges of the Boosted Liquidity Vaults, please refer to the standard documentation. You can also check the source code, the contract interface, and the stETH implementation on Github.

Before implementing an instance of the SingleSidedLiquidityVault contract, it is key to understand its relevant functions.

Useful Variables and Getters​

Public variable getters are autogenerated by the solidity compiler. Some of the useful getters when implementing or interacting with a contract than inherits SingleSidedLiquidityVault are the ones which refer to reward tokens and user state:

Reward Token State​

InternalRewardToken[] public internalRewardTokens;
ExternalRewardToken[] public externalRewardTokens;

Both arrays store information related to the different reward tokens. To better understand such information, let's check their underlying data structures:

struct InternalRewardToken {
    address token;
    uint256 rewardsPerSecond;
    uint256 lastRewardTime;
    uint256 accumulatedRewardsPerShare;
}

struct ExternalRewardToken {
    address token;
    uint256 accumulatedRewardsPerShare;
}

As it can be deducted by looking at the InternalRewardToken struct, an internal reward token is a token where the vault distributes and handles the accounting of rewards over time.

Instead, for external reward tokens the primary accrual of rewards occurs outside the scope of this contract (it happens in other systems such as Convex or Aura). In this case, the vault is responsible for harvesting the rewards and distributing them proportionally to users.

Reward Token State​

mapping(address user => uint256 pairTokens) public pairTokenDeposits;
mapping(address user => uint256 lpTokens) public lpPositions;
mapping(address user => mapping(address rewardToken => int256 rewards)) public userRewardDebts;
  • pairTokenDeposits tracks the deposited pair tokens by each user.
  • lpPositions tracks the LP tokens received when creating the liquidity positions with the provided pair tokens by each user.
  • userRewardDebts is a nested mapping that tracks the amount of each reward token owed to each user. ``

View Functions​

View functions are already implemented by the SingleSidedLiquidityVault contract. Therefore, these functions will be inherited by the implementation contracts. View functions are those public functions which end-users and the implementation contract can use to check the status of the accured rewards:

/// @param  id_        The position ID of the reward token in the `internalRewardTokens` array
/// @param  user_      The user's address to check rewards for
/// @return rewards    The amount of internal rewards that the user has earned
function internalRewardsForToken(uint256 id_, address user_) public view returns (uint256 rewards);

/// @param  id_        The position ID of the reward token in the `externalRewardTokens` array
/// @param  user_      The user's address to check rewards for
/// @return rewards    The amount of internal rewards that the user has earned
function internalRewardsForToken(uint256 id_, address user_) public view returns (uint256 rewards);

Core Functions​

Core functions are also implemented by the SingleSidedLiquidityVault contract. Therefore, these functions will be inherited by the implementation contracts too. Core functions are those external functions which end-users will use to interact with the vault:

deposit​

Allows users to deposit a certain amount of the pair tokens. Mints the equivalent OHM amount in USD, and creates a liquidity position with both tokens. The vault keeps ownership of the LP tokens and tracks the relative ownership of the depositor.

/// @param    amount_        The amount of desposited pair tokens
/// @param    minLpAmount_   The minimum amount of LP tokens to receive
/// @return   lpAmountOut    The actual amount of received LP tokens
function deposit(
    uint256 amount_,
    uint256 minLpAmount_
) external returns (uint256 lpAmountOut);

If the contract call is successful, the Vault will emit the following event:

Deposit(msg.sender, pairTokenUsed, ohmUsed);

withdraw​

Allows users to receive back the corresponding amount pair tokens based on the current composition of the liquidity pool. The vault removes the given amount of LP tokens, returns any received pair tokens to the user, and burns the received OHM. Users also have the ability to claim the earned rewards by using the boolean claim_.

/// @param  lpAmount_           The amount of LP tokens to withdraw
/// @param  minTokenAmounts_    The minimum amounts of pair tokens and OHM to receive
/// @param  claim_              Whether rewards should be claimed or not
function withdraw(
    uint256 lpAmount_,
    uint256[] calldata minTokenAmounts_,
    bool claim_
) external returns (uint256 pairTokenReceived);

If the contract call is successful, the Vault will emit the following event:

Withdraw(msg.sender, pairTokenReceived, ohmReceived);

claimRewards​

At any given time, users have the ability to claim the rewards they have earned. Both external reward tokens (incentives provided by the partner) and internal rewards tokens (any incentives that Olympus may provide) are claimed when calling this function.

function claimRewards() external;

If the contract call is successful, the Vault will emit the following event twice (one for the internal rewards and one for the external ones):

RewardsClaimed(msg.sender, rewardToken, reward - fee);

Virtual Functions​

Virtual functions are not implemented by the SingleSidedLiquidityVault contract. Instead, those functions must be implemented by the developers which aim to integrate a new SSLV on top of Olympus. These are the virtual functions which must be overrriden by the implementation contract:

  • _valueCollateral: Internal function which calculates the equivalent OHM amount for a given amount of partner tokens. This function will usually use several price feeds to calculate the conversion rate.
/// @param amount_      The amount of partner tokens to calculate the OHM value of
/// @return ohmAmount   The amount of OHM for the given amount of partner tokens
function _valueCollateral(uint256 amount_) internal view virtual returns (uint256 ohmAmount);
  • _getPoolPrice: Internal function which calculates the current price of the liquidity pool and expresses it in OHM/TKN ratio.
/// @return ohmTknRatio  The current price of the liquidity pool in OHM/TKN
function _getPoolPrice() internal view virtual returns (uint256 ohmTknRatio);
  • _getPoolOhmShare: Internal function which calculates the vaults' current share of OHM in the liquidity pool.
/// @return ohmShare   The contract's current share of OHM in the liquidity pool
function _getPoolOhmShare() internal view virtual returns (uint256 ohmShare);
  • _deposit: Internal function which deposits OHM and partner tokens into the liquidity pool. This functions is called by the core function deposit which users use to interact with the vault. This function should also handle deposits into any external staking pools like Aura or Convex.
/// @param ohmAmount_    The amount of OHM to deposit
/// @param pairAmount_   The amount of partner tokens to deposit
/// @param minLpAmount_  The minimum amount of liquidity pool tokens to receive
/// @return lpAmountOut  The amount of liquidity pool tokens received
function _deposit(
    uint256 ohmAmount_,
    uint256 pairAmount_,
    uint256 minLpAmount_
) internal virtual returns (uint256 lpAmountOut);
  • _withdraw: Internal function which withdraws OHM and partner tokens from the liquidity pool. This functions is called by the core function withdraw which users use to interact with the vault. This function should also handle withdrawals from any external staking pools like Aura or Convex.
/// @param lpAmount_         The amount of liquidity pool tokens to withdraw
/// @param minTokenAmounts_  The minimum amounts of OHM and partner tokens to receive
/// @return ohmOut           The amount of OHM received
/// @return tknOut           The amount of partner tokens received
function _withdraw(
    uint256 lpAmount_,
    uint256[] calldata minTokenAmounts_
) internal virtual returns (uint256 ohmOut, uint256 tknOut);
  • _accumulateExternalRewards:Internal function which harvests any external rewards from sources like Aura or Convex.
/// @return rewardsOut  The amounts of each external reward token harvested
function _accumulateExternalRewards() internal virtual returns (uint256[] memory rewardsOut);