Lenses
Those contracts expose an interface to query on-chain data related to the Morpho Protocols, its markets, and its users.
Be careful, currently there are 2 Lens that were deployed and are not strictly the same. Some differences are mentioned below.
One to query morpho-aave's related data & a different one to query morpho-compound's related data.
Compound requires supply & borrow indexes of each market to be manually updated. This implies that taking into account accrued interests since each last market's index update requires additional gas for each market and cannot be done in a view. Morpho-Compound simulates this update (with exact precision) and thus sometimes requires a list of markets to be passed as an argument (of which to virtually update supply & borrow indexes; the more you provide, the higher the gas cost of calling such a function).
Providing an empty array or an array with unknown addresses (such as
address(0)
) will not compute any virtual index update.The unit used for Compound is a WAD which is equal to 1e18 giving 18 decimals precision.
For Aave, the unit used is a RAY which is equal to 1e27 giving 27 decimals precision.
Querying supply/borrow rates on Morpho is straightforward. Though, one must understand that a Morpho user can be either on the underlying pool or matched peer-to-peer.
Hence, users benefit from a custom rate, depending on the proportion of their liquidity matched peer-to-peer. Their rate is thus located somewhere between the underlying pool's rate and Morpho's peer-to-peer rate.
Remark that the worst-case scenario for the user is when all its liquidity is on the pool, at the pool rate. Conversely, the best-case scenario is when the user's liquidity is fully matched peer-to-peer, at Morpho's peer-to-peer rate.
On Morpho-Compound, rates are given per block (as on Compound), meaning that computing a yearly rate should be done using the following formulas:
Concerning the rates:
As in Compound and Aave, rates are compounded, what is relevant to display on any front-end is the APY with the following formula:
Keep in mind the different units for both: WAD for Compound, RAY for Aave.
However, the frequency of compounding rates is not fixed. Thus, the most precise way to compare protocols between them is to focus on the APR:
The value of
nbBlocksPerYear
is yet to be chosen by the developer, though assuming 5 blocks/minute is a minimum blockchain velocity, nbBlocksPerYear
should at least be 2,600,000
.Comparing Morpho-Compound's rates per block to Compound's rates per block is much easier, as they are both expressed in the same unit. For example:
lens.getAverageSupplyRatePerBlock(cDai) > cDai.supplyRatePerBlock()
reflects that a supplier on Morpho is on average benefitting from a better yield through Morpho-Compound than on Compound.Comparing Morpho-AaveV2's APR to AaveV2's APR is much easier, as they are both expressed in the same unit. For example:
lens.getAverageSupplyRatePerYear(aDai) > pool.getReserveData(dai).currentLiquidityRate
reflects that a supplier on Morpho-AaveV2 is on average benefitting from a better yield through Morpho than on Aave V2.Computes and returns the current supply rate per block (in WAD) experienced by Morpho-Compound users on average in a given market.
On Morpho-AaveV2: getAverageSupplyRatePerYear()
Computes and returns the current supply APR (in WAD) experienced by Morpho-aave users on average in a given market.
This function is recommended for data platforms and strategists, as it reflects the real rate you can expect to have on Morpho as a supplier.
The keyword
average
is used because each Morpho supplier benefits from a custom supply rate, depending on the proportion of their liquidity matched peer-to-peer; thus higher than the underlying protocol's pool supply rate but may be lower than Morpho's peer-to-peer supply rate. Note again that, in the worst case, a user experiences the pool supply rate.function getAverageSupplyRatePerBlock(
address _poolTokenAddress
)
view
returns (
uint256 avgSupplyRatePerBlock,
uint256 p2pSupplyAmount,
uint256 poolSupplyAmount
)
Input parameter | Input type | Description |
---|---|---|
_poolTokenAddress | address | The address of the underlying protocol's pool token of which to query the average supply rate. |
Return value | Return type | Description |
---|---|---|
avgSupplyRatePerBlock | uint256 | The supply rate per block experienced on average on the given market (in WAD). |
p2pSupplyAmount | uint256 | The total amount of underlying ERC20 tokens supplied through Morpho matched peer-to-peer on the given market. |
poolSupplyAmount | uint256 | The total amount of underlying ERC20 tokens supplied through Morpho on the pool. |
On Morpho-AaveV2: getAverageBorrowRatePerYear()
Computes and returns the current borrow rate per block (in WAD) experienced on average on a given market.
This function is recommended for data platforms and strategists, as it reflects the real rate you can expect to have on Morpho as a borrower.
The keyword
average
is used because a Morpho Borrower benefits from a custom supply rate, depending on the proportion of their liquidity matched peer-to-peer; thus lower than the underlying protocol's pool borrow rate but may be higher than Morpho's peer-to-peer borrow rate.function getAverageBorrowRatePerBlock(
address _poolTokenAddress
)
view
returns (
uint256 avgBorrowRatePerBlock,
uint256 p2pBorrowAmount,
uint256 poolBorrowAmount
)
Input parameter | Input type | Description |
---|---|---|
_poolTokenAddress | address | The address of the underlying protocol's pool token of which to query the average borrow rate. |
Return value | Return type | Description |
---|---|---|
avgBorrowRatePerBlock | uint256 | The borrowing rate per block experienced on average on the given market (in WAD). |
p2pBorrowAmount | uint256 | The total amount of underlying ERC20 tokens borrowed through Morpho and matched peer-to-peer on the given market. |
poolBorrowAmount | uint256 | The total amount of underlying ERC20 tokens borrowed through Morpho from the underlying pool. |
On Morpho-AaveV2: getNextUserSupplyRatePerYear()
Computes and returns the minimum supply rate per block (in WAD) a supplier could experience on a given market if they were to supply a given amount. This function simulates parts of Morpho's matching engine, matching the supplier with the first borrower waiting to be matched through Morpho and/or with a borrow delta, if there is one. Note that if a supplier is not matched instantly, he can be matched later - eg. when new borrowers come in - and will thus experience a higher rate.
The simulated supply rate is a lower bound, meaning that if the user was to supply the given amount on the given market, they would at worst benefit from the returned supply rate but may also benefit from a higher supply rate if they are matched with more than the first borrower; or if they are automatically matched with a borrower later.
function getNextUserSupplyRatePerBlock(
address _poolTokenAddress,
address _user,
uint256 _amount
)
view
returns (
uint256 nextSupplyRatePerBlock,
uint256 balanceOnPool,
uint256 balanceInP2P,
uint256 totalBalance
)
On Morpho-AaveV2, the peer-to-peer-related data is always returned first:
function getNextUserSupplyRatePerYear(
address _poolTokenAddress,
address _user,
uint256 _amount
)
view
returns (
uint256 nextSupplyRatePerYear,
uint256 balanceInP2P,
uint256 balanceOnPool,
uint256 totalBalance
)
Input parameter | Input type | Description |
---|---|---|
_poolTokenAddress | address | The address of the underlying protocol's pool token to hypothetically supply to. |
_user | address | The address of the hypothetical supplier. |
_amount | uint256 | The amount of underlying ERC20 tokens to hypothetically supply. |
Return value | Return type | Description |
---|---|---|
nextSupplyRatePerBlock | uint256 | The hypothetical supply rate per block experienced by the user on the given market (in WAD). |
balanceOnPool | uint256 | The hypothetical total amount of underlying ERC20 tokens supplied through Morpho on the underlying pool after the simulation. |
balanceInP2P | uint256 | The hypothetical total amount of underlying ERC20 tokens supplied through Morpho and matched peer-to-peer after the simulation. |
totalBalance | uint256 | Equals balanceOnPool + balanceInP2P , only used for gas savings. |
On Morpho-AaveV2: getNextUserBorrowRatePerYear()
Computes and returns the maximum borrow rate per block (in WAD) a borrower could experience on a given market if they were to borrow a given amount. This function simulates parts of Morpho's matching engine, matching the borrower with the first supplier waiting to be matched through Morpho and/or with a supply delta (if there is one).
The simulated borrow rate is an upper bound, meaning that if the user was to borrow the given amount on the given market, they would at worst benefit from the returned borrow rate but may also benefit from a lower borrow rate if they are matched with more than the first supplier; or if they are automatically matched with a supplier later.
function getNextUserBorrowRatePerBlock(
address _poolTokenAddress,
address _user,
uint256 _amount
)
view
returns (
uint256 nextBorrowRatePerBlock,solidity
uint256 balanceOnPool,
uint256 balanceInP2P,
uint256 totalBalance
)
On Morpho-AaveV2, the peer-to-peer-related data is always returned first:
function getNextUserBorrowRatePerYear(
address _poolTokenAddress,
address _user,
uint256 _amount
)
view
returns (
uint256 nextBorrowRatePerYear,
uint256 balanceInP2P,
uint256 balanceOnPool,
uint256 totalBalance
)
Input parameter | Input type | Description |
---|---|---|
_poolTokenAddress | address | The address of the underlying protocol's pool token to hypothetically borrow from. |
_user | address | The address of the hypothetical borrower. |
_amount | uint256 | The amount of underlying ERC20 tokens to hypothetically borrow. |
Return value | Return type | Description |
---|---|---|
nextBorrowRatePerBlock | uint256 | The hypothetical borrow rate per block experienced by the user on the given market (in WAD). |
balanceOnPool | uint256 | The hypothetical total amount of underlying ERC20 tokens borrowed through Morpho from the underlying pool after the simulation. |
balanceInP2P | uint256 | The hypothetical total amount of underlying ERC20 tokens borrowed through Morpho and matched peer-to-peer after the simulation. |
totalBalance | uint256 | Equals balanceOnPool + balanceInP2P , only used for gas savings. |
On Morpho-AaveV2: getCurrentUserSupplyRatePerYear()
Computes and returns the current supply rate experienced by a user on a given market on Morpho.
function getCurrentUserSupplyRatePerBlock(
address _poolTokenAddress,
address _user
)
view
returns (
uint256 supplyRatePerBlock
)
Input parameter | Input type | Description |
---|---|---|
_poolTokenAddress | address | The address of the underlying protocol's pool token of which to get the experienced supply rate. |
_user | address | The address of the user to query the supply rate for. |
Return value | Return type | Description |
---|---|---|
supplyRatePerBlock | uint256 | The experienced supply rate per block of the given user on the given market (in wad). |
On Morpho-AaveV2: getCurrentUserBorrowRatePerYear()
Computes and returns the current borrow rate experienced by a user on a given market on Morpho.
function getCurrentUserBorrowRatePerBlock(
address _poolTokenAddress,solidity
address _user
)
view
returns (
uint256 borrowRatePerBlock
)
Input parameter | Input type | Description |
---|---|---|
_poolTokenAddress | address | The address of the underlying protocol's pool token of which to get the experienced borrow rate. |
_user | address | The address of the user to query the supply rate for. |
Return value | Return type | Description |
---|---|---|
borrowRatePerBlock | uint256 | The experienced borrow rate per block of the given user on the given market (in wad). |
On Morpho-AaveV2: getRatesPerYear()
Computes and returns supply and borrowing rates from the underlying protocol's pool and peer-to-peer rates of a given market.
This should only be used for advanced usage. Please refer to getAverageSupplyRatePerBlock() and getAverageBorrowRatePerBlock() for more straight-forward market rates.
function getRatesPerBlock(
address _poolTokenAddress
)
view
returns (
uint256 p2pSupplyRate,
uint256 p2pBorrowRate,
uint256 poolSupplyRate,
uint256 poolBorrowRate
)
Input parameter | Input type | Description |
---|---|---|
_poolTokenAddress | address | The address of the underlying protocol's pool token of which to get rates. |
Return value | Return type | Description |
---|---|---|
p2pSupplyRate | uint256 | The peer-to-peer supply rate per block of the given market (in WAD). |
p2pBorrowRate | uint256 | The peer-to-peer borrow rate per block of the given market (in WAD). |
poolSupplyRate | uint256 | The underlying pool's supply rate per block of the given market (in WAD). |
poolBorrowRate | uint256 | The underlying pool's borrow rate per block of the given market (in WAD). |
Returns whether a given underlying protocol's pool token corresponds to a created market on Morpho.
function isMarketCreated(
address _poolTokenAddress
)
view
returns (bool)
Input parameter | Input type | Description |
---|---|---|
_poolTokenAddress | address | The address of the underlying protocol's pool token. |
Return value | Return type | Description |
---|---|---|
isMarketCreated | bool | Whether the given pool token corresponds to a market created on Morpho. |
Returns whether a given underlying protocol's pool token corresponds to a created, not fully paused market on Morpho.
function isMarketCreatedAndNotPaused(
address _poolTokenAddress
)
view
returns (bool)
Input parameter | Input type | Description |
---|---|---|
_poolTokenAddress | address | The address of the underlying protocol's pool token. |
Return value | Return type | Description |
---|---|---|
isMarketCreated | bool | Whether the given pool token corresponds to a market created and not entirely paused on Morpho. |
Returns whether a given underlying protocol's pool token corresponds to a created and unpaused market on Morpho.
function isMarketCreatedAndNotPausedNorPartiallyPaused(
address _poolTokenAddress
)
view
returns (bool)
Input parameter | Input type | Description |
---|---|---|
_poolTokenAddress | address | The address of the underlying protocol's pool token. |
Return value | Return type | Description |
---|---|---|
isMarketCreated | bool | Whether the given pool token corresponds to a market created and unpaused on Morpho. |
Returns the list of pool token addresses corresponding to created markets on Morpho.
function getAllMarkets()
view
returns (address[] memory marketsCreated)
Return value | Return type | Description |
---|---|---|
marketsCreated | address[] | The list of pool token addresses corresponding to created markets on Morpho. |
Returns main market data related to the state of a given market.
function getMainMarketData(
address _poolTokenAddress
)
view
returns (
uint256 avgSupplyRatePerBlock,
uint256 avgBorrowRatePerBlock,
uint256 p2pSupplyAmount,
uint256 p2pBorrowAmount,
uint256 poolSupplyAmount,
uint256 poolBorrowAmount
)
Input parameter | Input type | Description |
---|---|---|
_poolTokenAddress | address | The address of the underlying protocol's pool token. |
Return value | Return type | Description |
---|---|---|
avgSupplyRatePerBlock | uint256 | The supply rate per block experienced on average on the given market (in WAD). |
avgBorrowRatePerBlock | uint256 | The borrow rate per block experienced on average on the given market (in WAD). |
p2pSupplyAmount | uint256 | The total amount of underlying ERC20 tokens supplied through Morpho and matched peer-to-peer, on the given market. |
p2pBorrowAmount | uint256 | The total amount of underlying ERC20 tokens borrowed through Morpho and matched peer-to-peer, on the given market. |
poolSupplyAmount | uint256 | The total amount of underlying ERC20 tokens supplied through Morpho on the underlying pool. |
poolBorrowAmount | uint256 | The total amount of underlying ERC20 tokens borrowed through Morpho from the underlying pool. |
Returns advanced market data related to the state of a given market.
function getAdvancedMarketData(
address _poolTokenAddress
)
view
returns (
uint256 p2pSupplyIndex,
uint256 p2pBorrowIndex,
uint256 poolSupplyIndex,
uint256 poolBorrowIndex,
uint32 lastUpdateBlockNumber,
uint256 p2pSupplyDelta,
uint256 p2pBorrowDelta
)
On Morpho-AaveV2,
lastUpdateBlockNumber
is replaced with lastUpdateTimestamp
.Input parameter | Input type | Description |
---|---|---|
_poolTokenAddress | address | The address of the underlying protocol's pool token. |
Return value | Return type | Description |
---|---|---|
p2pSupplyIndex | uint256 | The peer-to-peer supply index used to track supply interests accrued on the given market. |
p2pBorrowIndex | uint256 | The peer-to-peer supply index used to track borrow interests accrued on the given market. |
poolSupplyIndex | uint256 | The underlying protocol's pool supply index (e.g. on Compound: cToken's exchange rate). |
poolBorrowIndex | uint256 | The underlying protocol's pool borrow index. |
lastUpdateBlockNumber | uint32 | The block number of the last time indexes were last updated on Morpho.
On Morpho-AaveV2, this is replaced with lastUpdateTimestamp : the block.timestamp of the last indexes update. |
p2pSupplyDelta | uint256 | The total amount of underlying ERC20 tokens supplied through Morpho, stored as matched peer-to-peer but supplied on the underlying pool (cf. Delta mechanism for further details). |
p2pBorrowDelta | uint256 | The total amount of underlying ERC20 tokens borrow through Morpho, stored as matched peer-to-peer but borrowed from the underlying pool (cf. Delta mechanism for further details). |
Returns advanced market data related to the state of a given market.
function getMarketConfiguration(
address _poolTokenAddress
)
view
returns (
address underlying,
bool isCreated,
bool p2pDisabled,
bool isPaused,
bool isPartiallyPaused,
uint16 reserveFactor,
uint16 p2pIndexCursor,
uint256 collateralFactor
)
On Morpho-AaveV2,
collateralFactor
is not returned. You can instead query loanToValue
and liquidationThreshold
from Aave V2 with pool.getConfiguration
.Input parameter | Input type | Description |
---|---|---|
_poolTokenAddress | address | The address of the underlying protocol's pool token. |
Return value | Return type | Description |
---|---|---|
underlying | address | The address of the underlying ERC20 token of the given market. |
isCreated | bool | Whether the market is created on Morpho. |
p2pDisabled | bool | Whether the market has peer-to-peer matches disabled (in case accruing rewards from the underlying protocol's pool is more profitable). |
isPaused | bool | Whether the market is fully paused (no interaction allowed) on Morpho. |
isPartiallyPaused | bool | Whether the market is partially paused (only repay and withdraw are allowed) on Morpho. |
reserveFactor | uint16 | The percentage of interests accrued taken out to Morpho's reserve (in bps). |
p2pIndexCursor | uint16 | The peer-to-peer central rate's position between the underlying pool's supply rate and its borrow rate (in bps, 0% = supply rate, 100% = borrow rate). |
collateralFactor | uint256 | The collateral factor used on the given market (same as the underlying protocol's pool). |
Computes and returns the sum of all the underlying ERC20 supplied through Morpho, matched peer-to-peer and supplied to the underlying protocol's pool.
function getTotalMarketSupply(
address _poolTokenAddress
)
view
returns (
uint256 p2pSupplyAmount,
uint256 poolSupplyAmount,
uint256 supplyDeltaAmount
)
Input parameter | Input type | Description |
---|---|---|
_poolTokenAddress | address | The address of the underlying protocol's pool token. |
Return value | Return type | Description |
---|---|---|
p2pSupplyAmount | uint256 | The amount of underlying ERC20 tokens supplied through Morpho and matched peer-to-peer. |
poolSupplyAmount | uint256 | The amount of underlying ERC20 tokens supplied through Morpho to the underlying pool. |
Computes and returns the sum of all the underlying ERC20 borrowed through Morpho, matched peer-to-peer and borrowed from the underlying protocol's pool.
function getTotalMarketBorrow(
address _poolTokenAddress
)
view
returns (
uint256 p2pBorrowAmount,
uint256 poolBorrowAmount,
uint256 borrowDeltaAmount
)
Input parameter | Input type | Description |
---|---|---|
_poolTokenAddress | address | The address of the underlying protocol's pool token. |
Return value | Return type | Description |
---|---|---|
p2pBorrowAmount | uint256 | The amount of underlying ERC20 tokens borrowed through Morpho and matched peer-to-peer. |
poolBorrowAmount | uint256 | The amount of underlying ERC20 tokens borrowed through Morpho from the underlying pool. |
Returns the list of Morpho's pause flags on a given market, indicating whether supplies, borrows, repays, withdrawals, collateral liquidations, debt liquidations are paused on this market or not as well as whether the market is deprecated (a deprecated market allows liquidations as soon as a user borrows from it).
function getMarketPauseStatus(
address _poolToken
)
view
returns (
bool isSupplyPaused,
bool isBorrowPaused,
bool isWithdrawPaused,
bool isRepayPaused,
bool isLiquidateCollateralPaused,
bool isLiquidateBorrowPaused,
bool isDeprecated
)
Input parameter | Input type | Description |
---|---|---|
_poolToken | address | The address of the underlying protocol's pool token. |
Return value | Return type | Description |
---|---|---|
isSupplyPaused | bool | Whether the given market has paused supplies. |
isBorrowPaused | bool | Whether the given market has paused borrows. |
isWithdrawPaused | bool | Whether the given market has paused withdrawals. |
isRepayPaused | bool | Whether the given market has paused repays. |
isLiquidateCollateralPaused | bool | Whether the given market has paused collateral liquidations. |
isLiquidateBorrowPaused | bool | Whether the given market has paused debt liquidations. |
isDeprecated | bool | Whether the given market is deprecated. |
Returns the list of markets a given user is currently supplying to or borrowing from.
function getEnteredMarkets(
address _user
)
view
returns (
address[] memory enteredMarkets
)
Input parameter | Input type | Description |
---|---|---|
_user | address | The address of the user of whom to query entered markets. |
Return value | Return type | Description |
---|---|---|
enteredMarkets | address[] | The list of markets the given user is currently supplying to or borrowing from. |
considering
function getUserMaxCapacitiesForAsset(
address _user,
address _poolTokenAddress
)
view
returns (
uint256 withdrawable,
uint256 borrowable
)
Input parameter | Input type | Description |
---|---|---|
_user | address | The address of the user of whom to query max capacities. |
_poolTokenAddress | address | The address of the underlying protocol's pool token of which to query the given user's max capacities. |
Return value | Return type | Description |
---|---|---|
withdrawable | uint256 | The maximum amount of underlying ERC20 tokens the user can withdraw, without getting liquidated. |