Comptroller
Comptroller
The Comptroller is designed to provide checks for all minting, redeeming, transferring, borrowing, lending, repaying, liquidating, and seizing done by the vToken contract. Each pool has one Comptroller checking these interactions across markets. When a user interacts with a given market by one of these main actions, a call is made to a corresponding hook in the associated Comptroller, which either allows or reverts the transaction. These hooks also update supply and borrow rewards as they are called. The comptroller holds the logic for assessing liquidity snapshots of an account via the collateral factor and liquidation threshold. This check determines the collateral needed for a borrow, as well as how much of a borrow may be liquidated. A user may borrow a portion of their collateral with the maximum amount determined by the markets collateral factor. However, if their borrowed amount exceeds an amount calculated using the market’s corresponding liquidation threshold, the borrow is eligible for liquidation.
The Comptroller also includes two functions liquidateAccount() and healAccount(), which are meant to handle accounts that do not exceed the minLiquidatableCollateral for the Comptroller:
healAccount(): This function is called to seize all of a given user’s collateral, requiring themsg.senderrepay a certain percentage of the debt calculated bycollateral/(borrows*liquidationIncentive). The function can only be called if the calculated percentage does not exceed 100%, because otherwise nobadDebtwould be created andliquidateAccount()should be used instead. The difference in the actual amount of debt and debt paid off is recorded asbadDebtfor each market, which can then be auctioned off for the risk reserves of the associated pool.liquidateAccount(): This function can only be called if the collateral seized will cover all borrows of an account, as well as the liquidation incentive. Otherwise, the pool will incur bad debt, in which case the functionhealAccount()should be used instead. This function skips the logic verifying that the repay amount does not exceed the close factor.
Solidity API
enterMarkets
Add assets to be included in account liquidity calculation; enabling them to be used as collateral
Parameters
vTokens
address[]
The list of addresses of the vToken markets to be enabled
Return Values
[0]
uint256[]
errors An array of NO_ERROR for compatibility with Venus core tooling
📅 Events
MarketEntered is emitted for each market on success
⛔️ Access Requirements
Not restricted
❌ Errors
ActionPaused error is thrown if entering any of the markets is paused
MarketNotListed error is thrown if any of the markets is not listed
updateDelegate
Grants or revokes the borrowing delegate rights to / from an account If allowed, the delegate will be able to borrow funds on behalf of the sender Upon a delegated borrow, the delegate will receive the funds, and the borrower will see the debt on their account
Parameters
delegate
address
The address to update the rights for
allowBorrows
bool
Whether to grant (true) or revoke (false) the rights
📅 Events
DelegateUpdated emits on success
⛔️ Access Requirements
Not restricted
❌ Errors
ZeroAddressNotAllowed is thrown when delegate address is zero
exitMarket
Removes asset from sender's account liquidity calculation; disabling them as collateral
Parameters
vTokenAddress
address
The address of the asset to be removed
Return Values
[0]
uint256
error Always NO_ERROR for compatibility with Venus core tooling
📅 Events
MarketExited is emitted on success
⛔️ Access Requirements
Not restricted
❌ Errors
ActionPaused error is thrown if exiting the market is paused
NonzeroBorrowBalance error is thrown if the user has an outstanding borrow in this market
MarketNotListed error is thrown when the market is not listed
InsufficientLiquidity error is thrown if exiting the market would lead to user's insolvency
SnapshotError is thrown if some vToken fails to return the account's supply and borrows
PriceError is thrown if the oracle returns an incorrect price for some asset
preMintHook
Checks if the account should be allowed to mint tokens in the given market
Parameters
vToken
address
The market to verify the mint against
minter
address
The account which would get the minted tokens
mintAmount
uint256
The amount of underlying being supplied to the market in exchange for tokens
⛔️ Access Requirements
Not restricted
❌ Errors
ActionPaused error is thrown if supplying to this market is paused
MarketNotListed error is thrown when the market is not listed
SupplyCapExceeded error is thrown if the total supply exceeds the cap after minting
mintVerify
Validates mint, accrues interest and updates score in prime. Reverts on rejection. May emit logs.
Parameters
vToken
address
Asset being minted
minter
address
The address minting the tokens
actualMintAmount
uint256
The amount of the underlying asset being minted
mintTokens
uint256
The number of tokens being minted
preRedeemHook
Checks if the account should be allowed to redeem tokens in the given market
Parameters
vToken
address
The market to verify the redeem against
redeemer
address
The account which would redeem the tokens
redeemTokens
uint256
The number of vTokens to exchange for the underlying asset in the market
⛔️ Access Requirements
Not restricted
❌ Errors
ActionPaused error is thrown if withdrawals are paused in this market
MarketNotListed error is thrown when the market is not listed
InsufficientLiquidity error is thrown if the withdrawal would lead to user's insolvency
SnapshotError is thrown if some vToken fails to return the account's supply and borrows
PriceError is thrown if the oracle returns an incorrect price for some asset
redeemVerify
Validates redeem, accrues interest and updates score in prime. Reverts on rejection. May emit logs.
Parameters
vToken
address
Asset being redeemed
redeemer
address
The address redeeming the tokens
redeemAmount
uint256
The amount of the underlying asset being redeemed
redeemTokens
uint256
The number of tokens being redeemed
repayBorrowVerify
Validates repayBorrow, accrues interest and updates score in prime. Reverts on rejection. May emit logs.
Parameters
vToken
address
Asset being repaid
payer
address
The address repaying the borrow
borrower
address
The address of the borrower
actualRepayAmount
uint256
The amount of underlying being repaid
borrowerIndex
uint256
liquidateBorrowVerify
Validates liquidateBorrow, accrues interest and updates score in prime. Reverts on rejection. May emit logs.
Parameters
vTokenBorrowed
address
Asset which was borrowed by the borrower
vTokenCollateral
address
Asset which was used as collateral and will be seized
liquidator
address
The address repaying the borrow and seizing the collateral
borrower
address
The address of the borrower
actualRepayAmount
uint256
The amount of underlying being repaid
seizeTokens
uint256
The amount of collateral token that will be seized
seizeVerify
Validates seize, accrues interest and updates score in prime. Reverts on rejection. May emit logs.
Parameters
vTokenCollateral
address
Asset which was used as collateral and will be seized
vTokenBorrowed
address
Asset which was borrowed by the borrower
liquidator
address
The address repaying the borrow and seizing the collateral
borrower
address
The address of the borrower
seizeTokens
uint256
The number of collateral tokens to seize
transferVerify
Validates transfer, accrues interest and updates score in prime. Reverts on rejection. May emit logs.
Parameters
vToken
address
Asset being transferred
src
address
The account which sources the tokens
dst
address
The account which receives the tokens
transferTokens
uint256
The number of vTokens to transfer
preBorrowHook
disable-eslint
borrowVerify
Validates borrow, accrues interest and updates score in prime. Reverts on rejection. May emit logs.
Parameters
vToken
address
Asset whose underlying is being borrowed
borrower
address
The address borrowing the underlying
borrowAmount
uint256
The amount of the underlying asset requested to borrow
preRepayHook
Checks if the account should be allowed to repay a borrow in the given market
Parameters
vToken
address
The market to verify the repay against
borrower
address
The account which would borrowed the asset
⛔️ Access Requirements
Not restricted
❌ Errors
ActionPaused error is thrown if repayments are paused in this market
MarketNotListed error is thrown when the market is not listed
preLiquidateHook
Checks if the liquidation should be allowed to occur
Parameters
vTokenBorrowed
address
Asset which was borrowed by the borrower
vTokenCollateral
address
Asset which was used as collateral and will be seized
borrower
address
The address of the borrower
repayAmount
uint256
The amount of underlying being repaid
skipLiquidityCheck
bool
Allows the borrow to be liquidated regardless of the account liquidity
❌ Errors
ActionPaused error is thrown if liquidations are paused in this market
MarketNotListed error is thrown if either collateral or borrowed token is not listed
TooMuchRepay error is thrown if the liquidator is trying to repay more than allowed by close factor
MinimalCollateralViolated is thrown if the users' total collateral is lower than the threshold for non-batch liquidations
InsufficientShortfall is thrown when trying to liquidate a healthy account
SnapshotError is thrown if some vToken fails to return the account's supply and borrows
PriceError is thrown if the oracle returns an incorrect price for some asset
preSeizeHook
Checks if the seizing of assets should be allowed to occur
Parameters
vTokenCollateral
address
Asset which was used as collateral and will be seized
seizerContract
address
Contract that tries to seize the asset (either borrowed vToken or Comptroller)
liquidator
address
The address repaying the borrow and seizing the collateral
borrower
address
The address of the borrower
⛔️ Access Requirements
Not restricted
❌ Errors
ActionPaused error is thrown if seizing this type of collateral is paused
MarketNotListed error is thrown if either collateral or borrowed token is not listed
ComptrollerMismatch error is when seizer contract or seized asset belong to different pools
preTransferHook
Checks if the account should be allowed to transfer tokens in the given market
Parameters
vToken
address
The market to verify the transfer against
src
address
The account which sources the tokens
dst
address
The account which receives the tokens
transferTokens
uint256
The number of vTokens to transfer
⛔️ Access Requirements
Not restricted
❌ Errors
ActionPaused error is thrown if withdrawals are paused in this market
MarketNotListed error is thrown when the market is not listed
InsufficientLiquidity error is thrown if the withdrawal would lead to user's insolvency
SnapshotError is thrown if some vToken fails to return the account's supply and borrows
PriceError is thrown if the oracle returns an incorrect price for some asset
healAccount
Seizes all the remaining collateral, makes msg.sender repay the existing borrows, and treats the rest of the debt as bad debt (for each market). The sender has to repay a certain percentage of the debt, computed as collateral / (borrows * liquidationIncentive).
Parameters
user
address
account to heal
⛔️ Access Requirements
Not restricted
❌ Errors
CollateralExceedsThreshold error is thrown when the collateral is too big for healing
SnapshotError is thrown if some vToken fails to return the account's supply and borrows
PriceError is thrown if the oracle returns an incorrect price for some asset
liquidateAccount
Liquidates all borrows of the borrower. Callable only if the collateral is less than a predefined threshold, and the account collateral can be seized to cover all borrows. If the collateral is higher than the threshold, use regular liquidations. If the collateral is below the threshold, and the account is insolvent, use healAccount.
Parameters
borrower
address
the borrower address
orders
struct ComptrollerStorage.LiquidationOrder[]
an array of liquidation orders
⛔️ Access Requirements
Not restricted
❌ Errors
CollateralExceedsThreshold error is thrown when the collateral is too big for a batch liquidation
InsufficientCollateral error is thrown when there is not enough collateral to cover the debt
SnapshotError is thrown if some vToken fails to return the account's supply and borrows
PriceError is thrown if the oracle returns an incorrect price for some asset
setCloseFactor
Sets the closeFactor to use when liquidating borrows
Parameters
newCloseFactorMantissa
uint256
New close factor, scaled by 1e18
📅 Events
Emits NewCloseFactor on success
⛔️ Access Requirements
Controlled by AccessControlManager
setCollateralFactor
Sets the collateralFactor for a market
Parameters
vToken
contract VToken
The market to set the factor on
newCollateralFactorMantissa
uint256
The new collateral factor, scaled by 1e18
newLiquidationThresholdMantissa
uint256
The new liquidation threshold, scaled by 1e18
📅 Events
Emits NewCollateralFactor when collateral factor is updated
and NewLiquidationThreshold when liquidation threshold is updated
⛔️ Access Requirements
Controlled by AccessControlManager
❌ Errors
MarketNotListed error is thrown when the market is not listed
InvalidCollateralFactor error is thrown when collateral factor is too high
InvalidLiquidationThreshold error is thrown when liquidation threshold is lower than collateral factor
PriceError is thrown when the oracle returns an invalid price for the asset
setLiquidationIncentive
Sets liquidationIncentive
Parameters
newLiquidationIncentiveMantissa
uint256
New liquidationIncentive scaled by 1e18
📅 Events
Emits NewLiquidationIncentive on success
⛔️ Access Requirements
Controlled by AccessControlManager
supportMarket
Add the market to the markets mapping and set it as listed
Parameters
vToken
contract VToken
The address of the market (token) to list
⛔️ Access Requirements
Only PoolRegistry
❌ Errors
MarketAlreadyListed is thrown if the market is already listed in this pool
setMarketBorrowCaps
Set the given borrow caps for the given vToken markets. Borrowing that brings total borrows to or above borrow cap will revert.
Parameters
vTokens
contract VToken[]
The addresses of the markets (tokens) to change the borrow caps for
newBorrowCaps
uint256[]
The new borrow cap values in underlying to be set. A value of type(uint256).max corresponds to unlimited borrowing.
⛔️ Access Requirements
Controlled by AccessControlManager
setMarketSupplyCaps
Set the given supply caps for the given vToken markets. Supply that brings total Supply to or above supply cap will revert.
Parameters
vTokens
contract VToken[]
The addresses of the markets (tokens) to change the supply caps for
newSupplyCaps
uint256[]
The new supply cap values in underlying to be set. A value of type(uint256).max corresponds to unlimited supply.
⛔️ Access Requirements
Controlled by AccessControlManager
setActionsPaused
Pause/unpause specified actions
Parameters
marketsList
contract VToken[]
Markets to pause/unpause the actions on
actionsList
enum ComptrollerStorage.Action[]
List of action ids to pause/unpause
paused
bool
The new paused state (true=paused, false=unpaused)
⛔️ Access Requirements
Controlled by AccessControlManager
setMinLiquidatableCollateral
Set the given collateral threshold for non-batch liquidations. Regular liquidations will fail if the collateral amount is less than this threshold. Liquidators should use batch operations like liquidateAccount or healAccount.
Parameters
newMinLiquidatableCollateral
uint256
The new min liquidatable collateral (in USD).
⛔️ Access Requirements
Controlled by AccessControlManager
addRewardsDistributor
Add a new RewardsDistributor and initialize it with all markets. We can add several RewardsDistributor contracts with the same rewardToken, and there could be overlaping among them considering the last reward block
Parameters
_rewardsDistributor
contract RewardsDistributor
Address of the RewardDistributor contract to add
📅 Events
Emits NewRewardsDistributor with distributor address
⛔️ Access Requirements
Only Governance
setPriceOracle
Sets a new price oracle for the Comptroller
Parameters
newOracle
contract ResilientOracleInterface
Address of the new price oracle to set
📅 Events
Emits NewPriceOracle on success
❌ Errors
ZeroAddressNotAllowed is thrown when the new oracle address is zero
setMaxLoopsLimit
Set the for loop iteration limit to avoid DOS
Parameters
limit
uint256
Limit for the max loops can execute at a time
setPrimeToken
Sets the prime token contract for the comptroller
Parameters
_prime
contract IPrime
Address of the Prime contract
setForcedLiquidation
Enables forced liquidations for a market. If forced liquidation is enabled, borrows in the market may be liquidated regardless of the account liquidity
Parameters
vTokenBorrowed
address
Borrowed vToken
enable
bool
Whether to enable forced liquidations
getAccountLiquidity
Determine the current account liquidity with respect to liquidation threshold requirements
Parameters
account
address
The account get liquidity for
Return Values
error
uint256
Always NO_ERROR for compatibility with Venus core tooling
liquidity
uint256
Account liquidity in excess of liquidation threshold requirements,
shortfall
uint256
Account shortfall below liquidation threshold requirements
getBorrowingPower
Determine the current account liquidity with respect to collateral requirements
Parameters
account
address
The account get liquidity for
Return Values
error
uint256
Always NO_ERROR for compatibility with Venus core tooling
liquidity
uint256
Account liquidity in excess of collateral requirements,
shortfall
uint256
Account shortfall below collateral requirements
getHypotheticalAccountLiquidity
Determine what the account liquidity would be if the given amounts were redeemed/borrowed
Parameters
account
address
The account to determine liquidity for
vTokenModify
address
The market to hypothetically redeem/borrow in
redeemTokens
uint256
The number of tokens to hypothetically redeem
borrowAmount
uint256
The amount of underlying to hypothetically borrow
Return Values
error
uint256
Always NO_ERROR for compatibility with Venus core tooling
liquidity
uint256
Hypothetical account liquidity in excess of collateral requirements,
shortfall
uint256
Hypothetical account shortfall below collateral requirements
getAllMarkets
Return all of the markets
Return Values
[0]
contract VToken[]
markets The list of market addresses
isMarketListed
Check if a market is marked as listed (active)
Parameters
vToken
contract VToken
vToken Address for the market to check
Return Values
[0]
bool
listed True if listed otherwise false
getAssetsIn
Returns the assets an account has entered
Parameters
account
address
The address of the account to pull assets for
Return Values
[0]
contract VToken[]
A list with the assets the account has entered
checkMembership
Returns whether the given account is entered in a given market
Parameters
account
address
The address of the account to check
vToken
contract VToken
The vToken to check
Return Values
[0]
bool
True if the account is in the market specified, otherwise false.
liquidateCalculateSeizeTokens
Calculate number of tokens of collateral asset to seize given an underlying amount
Parameters
vTokenBorrowed
address
The address of the borrowed vToken
vTokenCollateral
address
The address of the collateral vToken
actualRepayAmount
uint256
The amount of vTokenBorrowed underlying to convert into vTokenCollateral tokens
Return Values
error
uint256
Always NO_ERROR for compatibility with Venus core tooling
tokensToSeize
uint256
Number of vTokenCollateral tokens to be seized in a liquidation
❌ Errors
PriceError if the oracle returns an invalid price
getRewardsByMarket
Returns reward speed given a vToken
Parameters
vToken
address
The vToken to get the reward speeds for
Return Values
rewardSpeeds
struct ComptrollerStorage.RewardSpeeds[]
Array of total supply and borrow speeds and reward token for all reward distributors
getRewardDistributors
Return all reward distributors for this pool
Return Values
[0]
contract RewardsDistributor[]
Array of RewardDistributor addresses
isComptroller
A marker method that returns true for a valid Comptroller contract
Return Values
[0]
bool
Always true
updatePrices
Update the prices of all the tokens associated with the provided account
Parameters
account
address
Address of the account to get associated tokens with
actionPaused
Checks if a certain action is paused on a market
Parameters
market
address
vToken address
action
enum ComptrollerStorage.Action
Action to check
Return Values
[0]
bool
paused True if the action is paused otherwise false
Last updated