Balance Sheet

The BalanceSheet is the global debt registry for Hifi. It tracks the collateral deposits and the debt taken on by all users.

When a user borrow hTokens, a vault is opened for them in the BalanceSheet. All vaults are recorded and managed in this contract.

This is the only upgradeable contract in the Hifi protocol. The most up to date version is the BalanceSheetV2.

Constant Functions

getBondList

function getBondList(
    address account
) external returns (contract IHToken[])

Returns the list of bond markets the given account entered.

It is not an error to provide an invalid address.

Parameters

Name	Type	Description
account	address	The borrower account to make the query against.

getCollateralAmount

function getCollateralAmount(
    address account,
    contract IErc20 collateral
) external returns (uint256 collateralAmount)

Returns the amount of collateral deposited by the given account for the given collateral type.

It is not an error to provide an invalid address.

Parameters

Name	Type	Description
account	address	The borrower account to make the query against.
collateral	contract IErc20	The collateral to make the query against.

getCollateralList

function getCollateralList(
    address account
) external returns (contract IErc20[])

Returns the list of collaterals the given account deposited.

It is not an error to provide an invalid address.

Parameters

Name	Type	Description
account	address	The borrower account to make the query against.

getCurrentAccountLiquidity

function getCurrentAccountLiquidity(
    address account
) external returns (uint256 excessLiquidity, uint256 shortfallLiquidity)

Calculates the current account liquidity.

Parameters

Name	Type	Description
account	address	The account to make the query against.

Return Values

Name	Type	Description
excessLiquidity	uint256	account liquidity in excess of collateral requirements.
shortfallLiquidity	uint256	account shortfall below collateral requirements

getDebtAmount

function getDebtAmount(
    address account,
    contract IHToken bond
) external returns (uint256 debtAmount)

Returns the amount of debt accrued by the given account in the given bond market.

It is not an error to provide an invalid address.

Parameters

Name	Type	Description
account	address	The borrower account to make the query against.
bond	contract IHToken	The bond to make the query against.

getHypotheticalAccountLiquidity

function getHypotheticalAccountLiquidity(
    address account,
    contract IErc20 collateralModify,
    uint256 collateralAmountModify,
    contract IHToken bondModify,
    uint256 debtAmountModify
) external returns (uint256 excessLiquidity, uint256 shortfallLiquidity)

Calculates the account liquidity given a modified collateral, collateral amount, bond and debt amount, using the current prices provided by the oracle.

Works by summing up each collateral amount multiplied by the USD value of each unit and divided by its respective collateral ratio, then dividing the sum by the total amount of debt drawn by the user.

Caveats:

• This function expects that the "collateralList" and the "bondList" are each modified in advance to include the collateral and bond due to be modified.

Parameters

Name	Type	Description
account	address	The account to make the query against.
collateralModify	contract IErc20	The collateral to make the check against.
collateralAmountModify	uint256	The hypothetical normalized amount of collateral.
bondModify	contract IHToken	The bond to make the check against.
debtAmountModify	uint256	The hypothetical amount of debt.

Return Values

Name	Type	Description
excessLiquidity	uint256	hypothetical account liquidity in excess of collateral requirements.
shortfallLiquidity	uint256	hypothetical account shortfall below collateral requirements

getRepayAmount

function getRepayAmount(
    contract IErc20 collateral,
    uint256 seizableCollateralAmount,
    contract IHToken bond
) external returns (uint256 repayAmount)

Calculates the amount of hTokens that should be repaid in order to seize a given amount of collateral. Note that this is for informational purposes only, it doesn't say anything about whether the user can be liquidated.

The formula applied:

$$repayAmount = \frac{seizableCollateralAmount * collateralPrice}{liquidationIncentive * underlyingPrice}$$

Parameters

Name	Type	Description
collateral	contract IErc20	The collateral to make the query against.
seizableCollateralAmount	uint256	The amount of collateral to seize.
bond	contract IHToken	The bond to make the query against.

Return Values

Name	Type	Description
repayAmount	uint256	The amount of hTokens that should be repaid.

getSeizableCollateralAmount

function getSeizableCollateralAmount(
    contract IHToken bond,
    uint256 repayAmount,
    contract IErc20 collateral
) external returns (uint256 seizableCollateralAmount)

Calculates the amount of collateral that can be seized when liquidating a borrow. Note that this is for informational purposes only, it doesn't say anything about whether the user can be liquidated.

The formula applied:

$$seizableCollateralAmount = \frac{repayAmount * liquidationIncentive * underlyingPrice}{collateralPrice}$$

Parameters

Name	Type	Description
bond	contract IHToken	The bond to make the query against.
repayAmount	uint256	The amount of hTokens to repay.
collateral	contract IErc20	The collateral to make the query against.

Return Values

Name	Type	Description
seizableCollateralAmount	uint256	The amount of seizable collateral.

Non-Constant Functions

borrow

function borrow(
    contract IHToken bond,
    uint256 borrowAmount
) external

Increases the debt of the caller and mints new hTokens.

Emits a {Borrow} event.

Requirements:

• The Fintroller must allow this action to be performed.
• The maturity of the bond must be in the future.
• The amount to borrow cannot be zero.
• The new length of the bond list must be below the max bonds limit.
• The new total amount of debt cannot exceed the debt ceiling.
• The caller must not end up having a shortfall of liquidity.

Parameters

Name	Type	Description
bond	contract IHToken	The address of the bond contract.
borrowAmount	uint256	The amount of hTokens to borrow and print into existence.

depositCollateral

function depositCollateral(
    contract IErc20 collateral,
    uint256 depositAmount
) external

Deposits collateral in the caller's account.

Emits a {DepositCollateral} event.

Requirements:

• The Fintroller must allow this action to be performed.
• The amount to deposit cannot be zero.
• The caller must have allowed this contract to spend collateralAmount tokens.
• The new collateral amount cannot exceed the collateral ceiling.

Parameters

Name	Type	Description
collateral	contract IErc20	The address of the collateral contract.
depositAmount	uint256	The amount of collateral to deposit.

liquidateBorrow

function liquidateBorrow(
    address borrower,
    contract IHToken bond,
    uint256 repayAmount,
    contract IErc20 collateral
) external

Repays the debt of the borrower and rewards the caller with a surplus of collateral.

Emits a {LiquidateBorrow} event.

Requirements:

• All from "repayBorrow".
• The caller cannot be the same with the borrower.
• The Fintroller must allow this action to be performed.
• The borrower must have a shortfall of liquidity if the bond didn't mature.
• The amount of seized collateral cannot be more than what the borrower has in the vault.

Parameters

Name	Type	Description
borrower	address	The account to liquidate.
bond	contract IHToken	The address of the bond contract.
repayAmount	uint256	The amount of hTokens to repay.
collateral	contract IErc20	The address of the collateral contract.

repayBorrow

function repayBorrow(
    contract IHToken bond,
    uint256 repayAmount
) external

Erases the borrower's debt and takes the hTokens out of circulation.

Emits a {RepayBorrow} event.

Requirements:

• The amount to repay cannot be zero.
• The Fintroller must allow this action to be performed.
• The caller must have at least repayAmount hTokens.
• The caller must have at least repayAmount debt.

Parameters

Name	Type	Description
bond	contract IHToken	The address of the bond contract.
repayAmount	uint256	The amount of hTokens to repay.

repayBorrowBehalf

function repayBorrowBehalf(
    address borrower,
    contract IHToken bond,
    uint256 repayAmount
) external

Erases the borrower's debt and takes the hTokens out of circulation.

Emits a {RepayBorrow} event.

Requirements:

• Same as the repayBorrow function, but here borrower is the account that must have at least repayAmount hTokens to repay the borrow.

Parameters

Name	Type	Description
borrower	address	The borrower account for which to repay the borrow.
bond	contract IHToken	The address of the bond contract
repayAmount	uint256	The amount of hTokens to repay.

setFintroller

function setFintroller(
    contract IFintroller newFintroller
) external

Updates the Fintroller contract this BalanceSheet is connected to.

Emits a {SetFintroller} event.

Requirements:

• The caller must be the owner.
• The new address cannot be the zero address.

Parameters

Name	Type	Description
newFintroller	contract IFintroller	The new Fintroller contract.

setOracle

function setOracle(
    contract IChainlinkOperator newOracle
) external

Updates the oracle contract.

Emits a {SetOracle} event.

Requirements:

• The caller must be the owner.
• The new address cannot be the zero address.

Parameters

Name	Type	Description
newOracle	contract IChainlinkOperator	The new oracle contract.

withdrawCollateral

function withdrawCollateral(
    contract IErc20 collateral,
    uint256 withdrawAmount
) external

Withdraws a portion or all of the collateral.

Emits a {WithdrawCollateral} event.

Requirements:

• The amount to withdraw cannot be zero.
• There must be enough collateral in the vault.
• The caller's account cannot fall below the collateral ratio.

Parameters

Name	Type	Description
collateral	contract IErc20	The address of the collateral contract.
withdrawAmount	uint256	The amount of collateral to withdraw.

Events

Borrow

event Borrow(
    address account,
    contract IHToken bond,
    uint256 borrowAmount
)

Emitted when a borrow is made.

Parameters

Name	Type	Description
account	address	The address of the borrower.
bond	contract IHToken	The address of the bond contract.
borrowAmount	uint256	The amount of hTokens borrowed.

DepositCollateral

event DepositCollateral(
    address account,
    contract IErc20 collateral,
    uint256 collateralAmount
)

Emitted when collateral is deposited.

Parameters

Name	Type	Description
account	address	The address of the borrower.
collateral	contract IErc20	The related collateral.
collateralAmount	uint256	The amount of deposited collateral.

LiquidateBorrow

event LiquidateBorrow(
    address liquidator,
    address borrower,
    contract IHToken bond,
    uint256 repayAmount,
    contract IErc20 collateral,
    uint256 seizedCollateralAmount
)

Emitted when a borrow is liquidated.

Parameters

Name	Type	Description
liquidator	address	The address of the liquidator.
borrower	address	The address of the borrower.
bond	contract IHToken	The address of the bond contract.
repayAmount	uint256	The amount of repaid funds.
collateral	contract IErc20	The address of the collateral contract.
seizedCollateralAmount	uint256	The amount of seized collateral.

RepayBorrow

event RepayBorrow(
    address payer,
    address borrower,
    contract IHToken bond,
    uint256 repayAmount,
    uint256 newDebtAmount
)

Emitted when a borrow is repaid.

Parameters

Name	Type	Description
payer	address	The address of the payer.
borrower	address	The address of the borrower.
bond	contract IHToken	The address of the bond contract.
repayAmount	uint256	The amount of repaid funds.
newDebtAmount	uint256	The amount of the new debt.

SetFintroller

event SetFintroller(
    address owner,
    address oldFintroller,
    address newFintroller
)

Emitted when a new Fintroller contract is set.

Parameters

Name	Type	Description
owner	address	The address of the owner.
oldFintroller	address	The address of the old Fintroller contract.
newFintroller	address	The address of the new Fintroller contract.

SetOracle

event SetOracle(
    address owner,
    address oldOracle,
    address newOracle
)

Emitted when a new oracle contract is set.

Parameters

Name	Type	Description
owner	address	The address of the owner.
oldOracle	address	The address of the old oracle contract.
newOracle	address	The address of the new oracle contract.

WithdrawCollateral

event WithdrawCollateral(
    address account,
    contract IErc20 collateral,
    uint256 collateralAmount
)

Emitted when collateral is withdrawn.

Parameters

Name	Type	Description
account	address	The address of the borrower.
collateral	contract IErc20	The related collateral.
collateralAmount	uint256	The amount of withdrawn collateral.

Custom Errors

BalanceSheet__BondMatured

error BalanceSheet__BondMatured(contract IHToken bond)

Emitted when the bond matured.

BalanceSheet__BorrowMaxBonds

error BalanceSheet__BorrowMaxBonds(contract IHToken bond, uint256 newBondListLength, uint256 maxBonds)

Emitted when the account exceeds the maximum numbers of bonds permitted.

BalanceSheet__DepositMaxCollaterals

error BalanceSheet__DepositMaxCollaterals(contract IErc20 collateral, uint256 newCollateralListLength, uint256 maxCollaterals)

Emitted when the account exceeds the maximum numbers of collateral permitted.

BalanceSheet__BorrowNotAllowed

error BalanceSheet__BorrowNotAllowed(contract IHToken bond)

Emitted when borrows are not allowed by the Fintroller contract.

BalanceSheet__BorrowZero

error BalanceSheet__BorrowZero()

Emitted when borrowing a zero amount of hTokens.

BalanceSheet__CollateralCeilingOverflow

error BalanceSheet__CollateralCeilingOverflow(uint256 newTotalSupply, uint256 debtCeiling)

Emitted when the new collateral amount exceeds the collateral ceiling.

BalanceSheet__DebtCeilingOverflow

error BalanceSheet__DebtCeilingOverflow(uint256 newCollateralAmount, uint256 debtCeiling)

Emitted when the new total amount of debt exceeds the debt ceiling.

BalanceSheet__DepositCollateralNotAllowed

error BalanceSheet__DepositCollateralNotAllowed(contract IErc20 collateral)

Emitted when collateral deposits are not allowed by the Fintroller contract.

BalanceSheet__DepositCollateralZero

error BalanceSheet__DepositCollateralZero()

Emitted when depositing a zero amount of collateral.

BalanceSheet__FintrollerZeroAddress

error BalanceSheet__FintrollerZeroAddress()

Emitted when setting the Fintroller contract to the zero address.

BalanceSheet__LiquidateBorrowInsufficientCollateral

error BalanceSheet__LiquidateBorrowInsufficientCollateral(address account, uint256 vaultCollateralAmount, uint256 seizableAmount)

Emitted when there is not enough collateral to seize.

BalanceSheet__LiquidateBorrowNotAllowed

error BalanceSheet__LiquidateBorrowNotAllowed(contract IHToken bond)

Emitted when borrow liquidations are not allowed by the Fintroller contract.

BalanceSheet__LiquidateBorrowSelf

error BalanceSheet__LiquidateBorrowSelf(address account)

Emitted when the borrower is liquidating themselves.

BalanceSheet__LiquidityShortfall

error BalanceSheet__LiquidityShortfall(address account, uint256 shortfallLiquidity)

Emitted when there is a liquidity shortfall.

BalanceSheet__NoLiquidityShortfall

error BalanceSheet__NoLiquidityShortfall(address account)

Emitted when there is no liquidity shortfall.

BalanceSheet__OracleZeroAddress

error BalanceSheet__OracleZeroAddress()

Emitted when setting the oracle contract to the zero address.

BalanceSheet__RepayBorrowInsufficientBalance

error BalanceSheet__RepayBorrowInsufficientBalance(contract IHToken bond, uint256 repayAmount, uint256 hTokenBalance)

Emitted when the repayer does not have enough hTokens to repay the debt.

BalanceSheet__RepayBorrowInsufficientDebt

error BalanceSheet__RepayBorrowInsufficientDebt(contract IHToken bond, uint256 repayAmount, uint256 debtAmount)

Emitted when repaying more debt than the borrower owes.

BalanceSheet__RepayBorrowNotAllowed

error BalanceSheet__RepayBorrowNotAllowed(contract IHToken bond)

Emitted when borrow repays are not allowed by the Fintroller contract.

BalanceSheet__RepayBorrowZero

error BalanceSheet__RepayBorrowZero()

Emitted when repaying a borrow with a zero amount of hTokens.

BalanceSheet__WithdrawCollateralUnderflow

error BalanceSheet__WithdrawCollateralUnderflow(address account, uint256 vaultCollateralAmount, uint256 withdrawAmount)

Emitted when withdrawing more collateral than there is in the vault.

BalanceSheet__WithdrawCollateralZero

error BalanceSheet__WithdrawCollateralZero()

Emitted when withdrawing a zero amount of collateral.