Comment on page

VToken

VToken
Each asset that is supported by a pool is integrated through an instance of the VToken contract. As outlined in the protocol overview, each isolated pool creates its own vToken corresponding to an asset. Within a given pool, each included vToken is referred to as a market of the pool. The main actions a user regularly interacts with in a market are:
mint/redeem of vTokens;
transfer of vTokens;
borrow/repay a loan on an underlying asset;
liquidate a borrow or liquidate/heal an account.
A user supplies the underlying asset to a pool by minting vTokens, where the corresponding vToken amount is determined by the exchangeRate. The exchangeRate will change over time, dependent on a number of factors, some of which accrue interest. Additionally, once users have minted vToken in a pool, they can borrow any asset in the isolated pool by using their vToken as collateral. In order to borrow an asset or use a vToken as collateral, the user must be entered into each corresponding market (else, the vToken will not be considered collateral for a borrow). Note that a user may borrow up to a portion of their collateral determined by the market’s collateral factor. However, if their borrowed amount exceeds an amount calculated using the market’s corresponding liquidation threshold, the borrow is eligible for liquidation. When a user repays a borrow, they must also pay off interest accrued on the borrow.
The Venus protocol includes unique mechanisms for healing an account and liquidating an account. These actions are performed in the Comptroller and consider all borrows and collateral for which a given account is entered within a market. These functions may only be called on an account with a total collateral amount that is no larger than a universal minLiquidatableCollateral value, which is used for all markets within a Comptroller. Both functions settle all of an account’s borrows, but healAccount() may add badDebt to a vToken. For more detail, see the description of healAccount() and liquidateAccount() in the Comptroller summary section below.
Solidity API
initialize
Construct a new money market
function initialize(address underlying_, contract ComptrollerInterface comptroller_, contract InterestRateModel interestRateModel_, uint256 initialExchangeRateMantissa_, string name_, string symbol_, uint8 decimals_, address admin_, address accessControlManager_, struct VTokenInterface.RiskManagementInit riskManagement, uint256 reserveFactorMantissa_) external
Parameters
Name
Type
Description
underlying_
address
The address of the underlying asset
comptroller_
contract ComptrollerInterface
The address of the Comptroller
interestRateModel_
contract InterestRateModel
The address of the interest rate model
initialExchangeRateMantissa_
uint256
The initial exchange rate, scaled by 1e18
name_
string
ERC-20 name of this token
symbol_
string
ERC-20 symbol of this token
decimals_
uint8
ERC-20 decimal precision of this token
admin_
address
Address of the administrator of this token
accessControlManager_
address
AccessControlManager contract address
riskManagement
struct VTokenInterface.RiskManagementInit
Addresses of risk & income related contracts
reserveFactorMantissa_
uint256
Percentage of borrow interest that goes to reserves (from 0 to 1e18)
❌ Errors
ZeroAddressNotAllowed is thrown when admin address is zero
ZeroAddressNotAllowed is thrown when shortfall contract address is zero
ZeroAddressNotAllowed is thrown when protocol share reserve address is zero
transfer
Transfer amount tokens from msg.sender to dst
function transfer(address dst, uint256 amount) external returns (bool)
Parameters
Name
Type
Description
dst
address
The address of the destination account
amount
uint256
The number of tokens to transfer
Return Values
Name
Type
Description
[0]
bool
success True if the transfer succeeded, reverts otherwise
📅 Events
Emits Transfer event on success
⛔️ Access Requirements
Not restricted
❌ Errors
TransferNotAllowed is thrown if trying to transfer to self
transferFrom
Transfer amount tokens from src to dst
function transferFrom(address src, address dst, uint256 amount) external returns (bool)
Parameters
Name
Type
Description
src
address
The address of the source account
dst
address
The address of the destination account
amount
uint256
The number of tokens to transfer
Return Values
Name
Type
Description
[0]
bool
success True if the transfer succeeded, reverts otherwise
📅 Events
Emits Transfer event on success
⛔️ Access Requirements
Not restricted
❌ Errors
TransferNotAllowed is thrown if trying to transfer to self
approve
Approve spender to transfer up to amount from src
function approve(address spender, uint256 amount) external returns (bool)
Parameters
Name
Type
Description
spender
address
The address of the account which may transfer tokens
amount
uint256
The number of tokens that are approved (uint256.max means infinite)
Return Values
Name
Type
Description
[0]
bool
success Whether or not the approval succeeded
📅 Events
Emits Approval event
⛔️ Access Requirements
Not restricted
❌ Errors
ZeroAddressNotAllowed is thrown when spender address is zero
increaseAllowance
Increase approval for spender
function increaseAllowance(address spender, uint256 addedValue) external returns (bool)
Parameters
Name
Type
Description
spender
address
The address of the account which may transfer tokens
addedValue
uint256
The number of additional tokens spender can transfer
Return Values
Name
Type
Description
[0]
bool
success Whether or not the approval succeeded
📅 Events
Emits Approval event
⛔️ Access Requirements
Not restricted
❌ Errors
ZeroAddressNotAllowed is thrown when spender address is zero
decreaseAllowance
Decreases approval for spender
function decreaseAllowance(address spender, uint256 subtractedValue) external returns (bool)
Parameters
Name
Type
Description
spender
address
The address of the account which may transfer tokens
subtractedValue
uint256
The number of tokens to remove from total approval
Return Values
Name
Type
Description
[0]
bool
success Whether or not the approval succeeded
📅 Events
Emits Approval event
⛔️ Access Requirements
Not restricted
❌ Errors
ZeroAddressNotAllowed is thrown when spender address is zero
balanceOfUnderlying
Get the underlying balance of the owner
function balanceOfUnderlying(address owner) external returns (uint256)
Parameters
Name
Type
Description
owner
address
The address of the account to query
Return Values
Name
Type
Description
[0]
uint256
amount The amount of underlying owned by owner
totalBorrowsCurrent
Returns the current total borrows plus accrued interest
function totalBorrowsCurrent() external returns (uint256)
Return Values
Name
Type
Description
[0]
uint256
totalBorrows The total borrows with interest
borrowBalanceCurrent
Accrue interest to updated borrowIndex and then calculate account's borrow balance using the updated borrowIndex
function borrowBalanceCurrent(address account) external returns (uint256)
Parameters
Name
Type
Description
account
address
The address whose balance should be calculated after updating borrowIndex
Return Values
Name
Type
Description
[0]
uint256
borrowBalance The calculated balance
mint
Sender supplies assets into the market and receives vTokens in exchange
function mint(uint256 mintAmount) external returns (uint256)
Parameters
Name
Type
Description
mintAmount
uint256
The amount of the underlying asset to supply
Return Values
Name
Type
Description
[0]
uint256
error Always NO_ERROR for compatibility with Venus core tooling
📅 Events
Emits Mint and Transfer events; may emit AccrueInterest
⛔️ Access Requirements
Not restricted
mintBehalf
Sender calls on-behalf of minter. minter supplies assets into the market and receives vTokens in exchange
function mintBehalf(address minter, uint256 mintAmount) external returns (uint256)
Parameters
Name
Type
Description
minter
address
User whom the supply will be attributed to
mintAmount
uint256
The amount of the underlying asset to supply
Return Values
Name
Type
Description
[0]
uint256
error Always NO_ERROR for compatibility with Venus core tooling
📅 Events
Emits Mint and Transfer events; may emit AccrueInterest
⛔️ Access Requirements
Not restricted
❌ Errors
ZeroAddressNotAllowed is thrown when minter address is zero
redeem
Sender redeems vTokens in exchange for the underlying asset
function redeem(uint256 redeemTokens) external returns (uint256)
Parameters
Name
Type
Description
redeemTokens
uint256
The number of vTokens to redeem into underlying
Return Values
Name
Type
Description
[0]
uint256
error Always NO_ERROR for compatibility with Venus core tooling
📅 Events
Emits Redeem and Transfer events; may emit AccrueInterest
⛔️ Access Requirements
Not restricted
❌ Errors
RedeemTransferOutNotPossible is thrown when the protocol has insufficient cash
redeemUnderlying
Sender redeems vTokens in exchange for a specified amount of underlying asset
function redeemUnderlying(uint256 redeemAmount) external returns (uint256)
Parameters
Name
Type
Description
redeemAmount
uint256
The amount of underlying to receive from redeeming vTokens
Return Values
Name
Type
Description
[0]
uint256
error Always NO_ERROR for compatibility with Venus core tooling
borrow
Sender borrows assets from the protocol to their own address
function borrow(uint256 borrowAmount) external returns (uint256)
Parameters
Name
Type
Description
borrowAmount
uint256
The amount of the underlying asset to borrow
Return Values
Name
Type
Description
[0]
uint256
error Always NO_ERROR for compatibility with Venus core tooling
📅 Events
Emits Borrow event; may emit AccrueInterest
⛔️ Access Requirements
Not restricted
❌ Errors
BorrowCashNotAvailable is thrown when the protocol has insufficient cash
repayBorrow
Sender repays their own borrow
function repayBorrow(uint256 repayAmount) external returns (uint256)
Parameters
Name
Type
Description
repayAmount
uint256
The amount to repay, or type(uint256).max for the full outstanding amount
Return Values
Name
Type
Description
[0]
uint256
error Always NO_ERROR for compatibility with Venus core tooling
📅 Events
Emits RepayBorrow event; may emit AccrueInterest
⛔️ Access Requirements
Not restricted
repayBorrowBehalf
Sender repays a borrow belonging to borrower
function repayBorrowBehalf(address borrower, uint256 repayAmount) external returns (uint256)
Parameters
Name
Type
Description
borrower
address
the account with the debt being payed off
repayAmount
uint256
The amount to repay, or type(uint256).max for the full outstanding amount
Return Values
Name
Type
Description
[0]
uint256
error Always NO_ERROR for compatibility with Venus core tooling
📅 Events
Emits RepayBorrow event; may emit AccrueInterest
⛔️ Access Requirements
Not restricted
liquidateBorrow
The sender liquidates the borrowers collateral. The collateral seized is transferred to the liquidator.
function liquidateBorrow(address borrower, uint256 repayAmount, contract VTokenInterface vTokenCollateral) external returns (uint256)
Parameters
Name
Type
Description
borrower
address
The borrower of this vToken to be liquidated
repayAmount
uint256
The amount of the underlying borrowed asset to repay
vTokenCollateral
contract VTokenInterface
The market in which to seize collateral from the borrower
Return Values
Name
Type
Description
[0]
uint256
error Always NO_ERROR for compatibility with Venus core tooling
📅 Events
Emits LiquidateBorrow event; may emit AccrueInterest
⛔️ Access Requirements
Not restricted
❌ Errors
LiquidateAccrueCollateralInterestFailed is thrown when it is not possible to accrue interest on the collateral vToken
LiquidateCollateralFreshnessCheck is thrown when interest has not been accrued on the collateral vToken
LiquidateLiquidatorIsBorrower is thrown when trying to liquidate self
LiquidateCloseAmountIsZero is thrown when repayment amount is zero
LiquidateCloseAmountIsUintMax is thrown when repayment amount is UINT_MAX
setProtocolSeizeShare
sets protocol share accumulated from liquidations
function setProtocolSeizeShare(uint256 newProtocolSeizeShareMantissa_) external
Parameters
Name
Type
Description
newProtocolSeizeShareMantissa_
uint256
new protocol share mantissa
📅 Events
Emits NewProtocolSeizeShare event on success
⛔️ Access Requirements
Controlled by AccessControlManager
❌ Errors
Unauthorized error is thrown when the call is not authorized by AccessControlManager
ProtocolSeizeShareTooBig is thrown when the new seize share is too high
setReserveFactor
accrues interest and sets a new reserve factor for the protocol using _setReserveFactorFresh
function setReserveFactor(uint256 newReserveFactorMantissa) external
Parameters
Name
Type
Description
newReserveFactorMantissa
uint256
New reserve factor (from 0 to 1e18)
📅 Events
Emits NewReserveFactor event; may emit AccrueInterest
⛔️ Access Requirements
Controlled by AccessControlManager
❌ Errors
Unauthorized error is thrown when the call is not authorized by AccessControlManager
SetReserveFactorBoundsCheck is thrown when the new reserve factor is too high
reduceReserves
Accrues interest and reduces reserves by transferring to the protocol reserve contract
function reduceReserves(uint256 reduceAmount) external
Parameters
Name
Type
Description
reduceAmount
uint256
Amount of reduction to reserves
📅 Events
Emits ReservesReduced event; may emit AccrueInterest
⛔️ Access Requirements
Not restricted
❌ Errors
ReduceReservesCashNotAvailable is thrown when the vToken does not have sufficient cash
ReduceReservesCashValidation is thrown when trying to withdraw more cash than the reserves have
addReserves
The sender adds to reserves.
function addReserves(uint256 addAmount) external
Parameters
Name
Type
Description
addAmount
uint256
The amount of underlying token to add as reserves
📅 Events
Emits ReservesAdded event; may emit AccrueInterest
⛔️ Access Requirements
Not restricted
setInterestRateModel
accrues interest and updates the interest rate model using _setInterestRateModelFresh
function setInterestRateModel(contract InterestRateModel newInterestRateModel) external
Parameters
Name
Type
Description
newInterestRateModel
contract InterestRateModel
the new interest rate model to use
📅 Events
Emits NewMarketInterestRateModel event; may emit AccrueInterest
⛔️ Access Requirements
Controlled by AccessControlManager
❌ Errors
Unauthorized error is thrown when the call is not authorized by AccessControlManager
healBorrow
Repays a certain amount of debt, treats the rest of the borrow as bad debt, essentially "forgiving" the borrower. Healing is a situation that should rarely happen. However, some pools may list risky assets or be configured improperly – we want to still handle such cases gracefully. We assume that Comptroller does the seizing, so this function is only available to Comptroller.
function healBorrow(address payer, address borrower, uint256 repayAmount) external
Parameters
Name
Type
Description
payer
address
account who repays the debt
borrower
address
account to heal
repayAmount
uint256
amount to repay
📅 Events
Emits RepayBorrow, BadDebtIncreased events; may emit AccrueInterest
⛔️ Access Requirements
Only Comptroller
❌ Errors
HealBorrowUnauthorized is thrown when the request does not come from Comptroller
forceLiquidateBorrow
The extended version of liquidations, callable only by Comptroller. May skip the close factor check. The collateral seized is transferred to the liquidator.
function forceLiquidateBorrow(address liquidator, address borrower, uint256 repayAmount, contract VTokenInterface vTokenCollateral, bool skipLiquidityCheck) external
Parameters
Name
Type
Description
liquidator
address
The address repaying the borrow and seizing collateral
borrower
address
The borrower of this vToken to be liquidated

Name	Type	Description
underlying_	address	The address of the underlying asset
comptroller_	contract ComptrollerInterface	The address of the Comptroller
interestRateModel_	contract InterestRateModel	The address of the interest rate model
initialExchangeRateMantissa_	uint256	The initial exchange rate, scaled by 1e18
name_	string	ERC-20 name of this token
symbol_	string	ERC-20 symbol of this token
decimals_	uint8	ERC-20 decimal precision of this token
admin_	address	Address of the administrator of this token
accessControlManager_	address	AccessControlManager contract address
riskManagement	struct VTokenInterface.RiskManagementInit	Addresses of risk & income related contracts
reserveFactorMantissa_	uint256	Percentage of borrow interest that goes to reserves (from 0 to 1e18)

Name	Type	Description
dst	address	The address of the destination account
amount	uint256	The number of tokens to transfer

Name	Type	Description
src	address	The address of the source account
dst	address	The address of the destination account
amount	uint256	The number of tokens to transfer

Name	Type	Description
spender	address	The address of the account which may transfer tokens
amount	uint256	The number of tokens that are approved (uint256.max means infinite)

Name	Type	Description
minter	address	User whom the supply will be attributed to
mintAmount	uint256	The amount of the underlying asset to supply

Name	Type	Description
borrower	address	the account with the debt being payed off
repayAmount	uint256	The amount to repay, or type(uint256).max for the full outstanding amount

Name	Type	Description
borrower	address	The borrower of this vToken to be liquidated
repayAmount	uint256	The amount of the underlying borrowed asset to repay
vTokenCollateral	contract VTokenInterface	The market in which to seize collateral from the borrower

Name	Type	Description
payer	address	account who repays the debt
borrower	address	account to heal
repayAmount	uint256	amount to repay

Name	Type	Description
liquidator	address	The address repaying the borrow and seizing collateral
borrower	address	The borrower of this vToken to be liquidated