Lending Controller Contract

Controlling the Pulse of Maven Finance's Lending

The Lending Controller Contract is a critical piece of the Maven Finance ecosystem.

It lies at the heart of Maven's lending operations, managing the complex dynamics of multiple lending pools and facilitating seamless interaction between borrowers, lenders, and various digital assets.

Within the Maven Finance landscape, the Lending Controller Contract has the essential role of setting parameters for lending, calculating interest rates, and enforcing the lending policies.

Whether you're a lender looking to earn yield on your assets or a borrower seeking liquidity, this contract underpins your experience within Maven's lending framework.

Token Pool Entrypoints

addLiquidity

function addLiquidity(string loanTokenName, nat amount)

Adds liquidity to the provided loan token pool. An equal amount of corresponding mTokens will be minted and sent to users, representing their liquidity provided.

Param Name	Type	Description
loanTokenName	string	Loan token for which liquidity will be added
amount	nat	Total amount of the loan token to be added as liquidity

removeLiquidity

function removeLiquidity(string loanTokenName, nat amount)

Removes liquidity to the provided loan token pool. An equal amount of corresponding mTokens will be burned from users, representing their liquidity removed.

Param Name	Type	Description
loanTokenName	string	Loan token for which liquidity will be added
amount	nat	Total amount of the loan token to be added as liquidity

Vault Entrypoints

closeVault

function closeVault(nat vaultId)

Closes the provided vault.

A vault can only be closed if it has zero outstanding loans. All collateral tokens remaining in the vault will be transferred back to the vault owner.

Can be called only by the vault owner

Param Name	Type	Description
vaultId	nat	The id of the vault to be closed

registerDeposit

function registerDeposit(vaultHandleType vaultHandle, nat amount, string tokenName)

Registers a collateral deposit from a vault

Can be called only by a Vault Contract or by the vault Factory

Param Name	Type	Description
vaultHandle	vaultHandleType: nat vaultId, address vaultOwner	The identifier key of the vault in lending controller consisting of the vault id and vault owner as the key
vaultId	nat	The id of the vault
vaultOwner	address	The address of the vault owner
amount	nat	The total amount that is deposited
tokenName	string	The name of the collateral token deposited

registerWithdrawal

function registerWithdrawal(vaultHandleType vaultHandle, nat amount, string tokenName)

Registers a collateral withdrawal from a vault. Vaults may not withdraw if they are under-collaterized.

Can be called only by a Vault Contract

Param Name	Type	Description
vaultHandle	vaultHandleType: nat vaultId, address vaultOwner	The identifier key of the vault in lending controller consisting of the vault id and vault owner as the key
vaultId	nat	The id of the vault
vaultOwner	address	The address of the vault owner
amount	nat	The total amount that is withdrawn
tokenName	string	The name of the collateral token withdrawn

markForLiquidation

function markForLiquidation(nat vaultId, address vaultOwner)

Marks a vault for liquidation which starts a grace period for the vault owner to deposit additional collateral into the vault to raise its liquidation ratio.

After the grace period, the vault can be liquidated by anyone.

Param Name	Type	Description
vaultId	nat	The id of the vault to be mark for liquidation
vaultOwner	address	The address of the vault owner of the vault to be marked for liquidation

liquidateVault

function liquidateVault(nat vaultId, address vaultOwner, nat amount)

Liquidates a vault based on the total amount of loan tokens sent by the liquidator.

The total amount that can be liquidated from a vault is the maxVaultLiquidationPercent (initially set at 50% and configurable through governance) of its total loan outstanding amount.

Param Name	Type	Description
vaultId	nat	The id of the vault to be liquidated
vaultOwner	address	The address of the vault owner of the vault to be liquidated
amount	nat	The total amount of loan tokens for which the vault will be liquidated by.

borrow

function borrow(nat vaultId, nat quantity)

Borrows tokens from the Lending Controller loan token liquidity pool to the vault owner

Can be called only by a Vault Owner

Param Name	Type	Description
vaultId	nat	The id of the vault
quantity	nat	The total amount of loan tokens to be borrowed

repay

function repay(nat vaultId, nat quantity)

Repays tokens from the vault back to the Lending Controller loan token liquidity pool

Can be called only by a Vault Owner

Param Name	Type	Description
vaultId	nat	The id of the vault
quantity	nat	The total amount of loan tokens to be repaid. If the total amount is greater than the total loan outstanding amount, the excess will be refunded back to the vault owner.

vaultDepositStakedToken

function vaultDepositStakedToken(string tokenName, nat vaultId, nat depositAmount)

Handles the deposit of staked tokens (such as staked MVN) from the vault owner to the vault contract.

Valid staked token contracts have to be registered as a staked collateral token type on the Lending Controller and follow the convention in entrypoint names and types.

Can be called only by a Vault Owner

Param Name	Type	Description
tokenName	string	The name of the collateral token to be deposited
vaultId	nat	The id of the vault
depositAmount	nat	The total amount to be deposited

vaultWithdrawStakedToken

function vaultWithdrawStakedToken(string tokenName, nat vaultId, nat depositAmount)

Handles the withdrawal of staked tokens (such as staked MVN) from the vault contract to the vault owner.

Can be called only by a Vault Owner

Param Name	Type	Description
tokenName	string	The name of the collateral token to be withdrawn
vaultId	nat	The id of the vault
withdrawAmount	nat	The total amount to be withdrawn

Lending Admin Entrypoints

setLoanToken

function setLoanToken(setLoanTokenActionType setLoanTokenAction)

Sets a loan token on the Lending Controller contract

Can be called only by the admin

Param Name	Type	Description
setLoanTokenAction	setLoanTokenActionType: | createLoanTokenActionType createLoanToken | updateLoanTokenActionType updateLoanToken	Specify the action variant to be taken for the loan token: Create or Update
createLoanToken	createLoanTokenActionType: string tokenName, nat tokenDecimals, address oracleAddress, address mTokenAddress, nat reserveRatio, nat optimalUtilisationRate, nat baseInterestRate, nat maxInterestRate, nat interestRateBelowOptimalUtilisation, nat interestRateAboveOptimalUtilisation, nat minRepaymentAmount, tokenType token	Parameters for creating a new loan token
updateLoanToken	updateLoanTokenActionType: string tokenName, address oracleAddress, nat reserveRatio, nat optimalUtilisationRate, nat baseInterestRate, nat maxInterestRate, nat interestRateBelowOptimalUtilisation, nat interestRateAboveOptimalUtilisation, nat minRepaymentAmount, bool isPaused	Parameters for updating an existing loan token
tokenName	string	The reference name of the loan token
tokenDecimals	nat	The number of decimals used by the loan token contract
oracleAddress	address	The oracle address providing data on the price of the loan token
mTokenAddress	address	The mToken contract address corresponding to a 1-to-1 ratio to the amount of loan tokens in the Lending Controller. The mToken contract address may not be changed once set
reserveRatio	nat	Specifies the amount of reserves required (that cannot be loaned out)
optimalUtilisationRatio	nat	Specifies the optimal utilisation ratio with varying interest rates below and above it
baseInterestRate	nat	Specifies the base interest rate used for loans
maxInterestRate	nat	Specifies the maximum interest rate allowed
interestRateBelowOptimalUtilisation	nat	Specifies the interest rate below the optimal utilisation ratio
interestRateAboveOptimalUtilisation	nat	Specifies the interest rate above the optimal utilisation ratio
minRepaymentAmount	nat	Specifies the minimum amount that can be repaid in each call
isPaused	bool	Specifies if the loan token should be paused. If set to True, adding liquidity or borrowing this loan token will be paused. Removing liquidity and repaying loans will still function as normal.
token	tokenType: | unit Mavv | (address tokenContractAddress) Fa12 | (address tokenContractAddress, nat tokenId) MRC-20	The token type of the loan token, corresponding to either Mav, MRC-10 OR MRC-20

setCollateralToken

function setCollateralToken(setCollateralTokenActionType setCollateralTokenAction)

Sets a collateral token on the Lending Controller contract

Can be called only by the admin

Param Name	Type	Description
setCollateralTokenAction	setCollateralTokenActionType: | createCollateralTokenActionType createCollateralToken | updateCollateralTokenActionType updateCollateralToken	Specify the action variant to be taken for the collateral token: Create or Update
createCollateralToken	createCollateralTokenActionType: string tokenName, address tokenContractAddress, nat tokenDecimals, address oracleAddress, bool protected, bool isScaledToken, bool isStakedToken, option(address) stakingContractAddress option(nat) maxDepositAmount tokenType token	Parameters for creating a new collateral token
updateCollateralToken	updateCollateralTokenActionType: string tokenName, address oracleAddress, bool isPaused, option(address) stakingContractAddress, option(nat) maxStakingAmount	Parameters for updating an existing collateral token
tokenName	string	The reference name of the collateral token
tokenContractAddress	address	The contract address of the collateral token
tokenDecimals	nat	The number of decimals used by the collateral token contract
oracleAddress	address	The oracle address providing data on the price of the loan token
protected	bool	Specifies if a collateral token is protected. If set to true, collateral tokens have to be deposited or withdrawn using special entrypoints such as vaultDepositStakedToken and vaultWithdrawStakedToken on the Lending Controller
isScaledToken	bool	Specifies if the collateral token is a scaled token (similar to mToken)
isStakedToken	bool	Specifies if the collateral token is a staked token (similar to staked MVN)
stakingContractAddress	option(address)	An optional contract address to be set only if the collateral token is a staked token
maxDepositAmount	nat	An optional amount to specify the maximum amount of collateral token that can be deposited by all users
isPaused	bool	Specifies
isPaused	bool	Specifies if the collateral token should be paused. If set to True, depositing this collateral tokens into vaults will be paused. Withdraws will still function as normal.
token	tokenType: | unit Mav | (address tokenContractAddress) Fa12 | (address tokenContractAddress, nat tokenId) MRC-20	The token type of the collateral token, corresponding to either Mav, MRC-10 OR MRC-20

registerVaultCreation

function registerVaultCreation(address vaultOwner, nat vaultId, address vaultAddress, string loanTokenName)

Registers the creation of a new Vault Contract from the Vault Factory Contract

Can be called only by the Vault Factory Contract

Param Name	Type	Description
vaultOwner	address	The address of the vault owner
vaultId	nat	The id of the vault
vaultAddress	address	The contract address of the vault contract
loanTokenName	string	The loan token that the vault will be allowed to borrow from

Housekeeping Entrypoints

setAdmin

function setAdmin(address newAdminAddress)

Sets a new admin address for the contract

Can be called only by the admin or the governance contract address

Param Name	Type	Description
newAdminAddress	address	The address of the new admin

setGovernance

function setGovernance(address newGovernanceAddress)

Sets a new governance contract address

Can be called only by the admin or the governance contract address

Param Name	Type	Description
newGovernanceAddress	address	The address of the new governance contract

updateConfig

function updateConfig(nat newConfigValue, lendingControllerConfigActionType lendingControllerConfigAction)

Updates the config variables on the LendingController Contract

Can be called only by the admin (i.e. the governance proxy contract)

Param Name	Type	Description
newConfigValue	nat	The new value of the config parameter
lendingControllerConfigAction	lendingControllerConfigActionType: | unit ConfigCollateralRatio | unit ConfigLiquidationRatio | unit ConfigLiquidationFeePercent | unit ConfigAdminLiquidationFee | unit ConfigMinimumLoanFeePercent | unit ConfigMinLoanFeeTreasuryShare | unit ConfigInterestTreasuryShare	The variant config variable to be updated

setLambda

function setLambda(string lambdaName, bytes func_bytes)

Sets a lambda in the contract with the given bytes and name

Can be called only by the admin (i.e. the governance proxy contract)

Param Name	Type	Description
lambdaName	string	The name of the lambda to be set
func_bytes	bytes	The data of the lambda in Michelson bytes format

BreakGlass Entrypoints

pauseAll

function pauseAll()

Pauses all entrypoints in the contract.

Can be called only by the admin or the governance contract address

unpauseAll

function unpauseAll()

Unpauses all entrypoints in the contract.

Can be called only by the admin or the governance contract address

togglePauseEntrypoint

function togglePauseEntrypoint(lendingControllerTogglePauseEntrypointType targetEntrypoint, unit empty)

Toggles the pausing of a specific entrypoint in the contract

Can be called only by the admin (i.e. the governance proxy contract)

Param Name	Type	Description
targetEntrypoint	lendingControllerTogglePauseEntrypointType: | bool SetLoanToken | bool SetCollateralToken | bool AddLiquidity | bool RemoveLiquidity | bool RegisterVaultCreation | bool CloseVault | bool RegisterDeposit | bool RegisterWithdrawal | bool MarkForLiquidation | bool LiquidateVault | bool Borrow | bool Repay | bool VaultDeposit | bool VaultWithdraw | bool VaultOnLiquidate | bool VaultDepositStakedToken | bool VaultWithdrawStakedToken	The target entrypoint to be paused, and its corresponding pause boolean. If the boolean is set to True, the entrypoint will be paused.
empty	unit	A null param used to prettify interactions with this entrypoint on blockchain explorers such as better-call-dev

View Methods

getAdmin

function getAdmin()

Returns the contract admin

getGovernanceAddress

function getGovernanceAddress()

Returns the contract governance address

getConfig

function getConfig()

Returns the contract configuration parameters

getBreakGlassConfig

function getBreakGlassConfig()

Returns the break glass config parameters (which shows the pause status of entrypoints)

getColTokenRecordByNameOpt

function getColTokenRecordByNameOpt(string tokenName)

Returns the collateral token record by its reference name if it exists, else returns none

getLoanTokenRecordOpt

function getLoanTokenRecordOpt(string tokenName)

Returns the loan token record by its reference name if it exists, else returns none

getOwnedVaultsByUserOpt

function getOwnedVaultsByUserOpt(address userAddress)

Returns a set of vault ids where the given userAddress is the vault owner

getVaultOpt

function getVaultOpt(nat vaultId, address vaultOwnerAddress)

Returns a vault record given its vault id and vault owner address if it exists, else returns none

getLambdaOpt

function getLambdaOpt(string lambdaName)

Returns a lambda in the contract for the given lambda name, else returns none