Skip to main content

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

NameTypeDescription
accountaddressThe 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

NameTypeDescription
accountaddressThe borrower account to make the query against.
collateralcontract IErc20The 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

NameTypeDescription
accountaddressThe borrower account to make the query against.

getCurrentAccountLiquidity

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

Calculates the current account liquidity.

Parameters

NameTypeDescription
accountaddressThe account to make the query against.

Return Values

NameTypeDescription
excessLiquidityuint256account liquidity in excess of collateral requirements.
shortfallLiquidityuint256account 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

NameTypeDescription
accountaddressThe borrower account to make the query against.
bondcontract IHTokenThe 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

NameTypeDescription
accountaddressThe account to make the query against.
collateralModifycontract IErc20The collateral to make the check against.
collateralAmountModifyuint256The hypothetical normalized amount of collateral.
bondModifycontract IHTokenThe bond to make the check against.
debtAmountModifyuint256The hypothetical amount of debt.

Return Values

NameTypeDescription
excessLiquidityuint256hypothetical account liquidity in excess of collateral requirements.
shortfallLiquidityuint256hypothetical 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=seizableCollateralAmountโˆ—collateralPriceliquidationIncentiveโˆ—underlyingPricerepayAmount = \frac{seizableCollateralAmount * collateralPrice}{liquidationIncentive * underlyingPrice}

Parameters

NameTypeDescription
collateralcontract IErc20The collateral to make the query against.
seizableCollateralAmountuint256The amount of collateral to seize.
bondcontract IHTokenThe bond to make the query against.

Return Values

NameTypeDescription
repayAmountuint256The 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=repayAmountโˆ—liquidationIncentiveโˆ—underlyingPricecollateralPriceseizableCollateralAmount = \frac{repayAmount * liquidationIncentive * underlyingPrice}{collateralPrice}

Parameters

NameTypeDescription
bondcontract IHTokenThe bond to make the query against.
repayAmountuint256The amount of hTokens to repay.
collateralcontract IErc20The collateral to make the query against.

Return Values

NameTypeDescription
seizableCollateralAmountuint256The 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

NameTypeDescription
bondcontract IHTokenThe address of the bond contract.
borrowAmountuint256The 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

NameTypeDescription
collateralcontract IErc20The address of the collateral contract.
depositAmountuint256The 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

NameTypeDescription
borroweraddressThe account to liquidate.
bondcontract IHTokenThe address of the bond contract.
repayAmountuint256The amount of hTokens to repay.
collateralcontract IErc20The 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

NameTypeDescription
bondcontract IHTokenThe address of the bond contract.
repayAmountuint256The 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

NameTypeDescription
borroweraddressThe borrower account for which to repay the borrow.
bondcontract IHTokenThe address of the bond contract
repayAmountuint256The 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

NameTypeDescription
newFintrollercontract IFintrollerThe 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

NameTypeDescription
newOraclecontract IChainlinkOperatorThe 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

NameTypeDescription
collateralcontract IErc20The address of the collateral contract.
withdrawAmountuint256The amount of collateral to withdraw.

Events

Borrow

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

Emitted when a borrow is made.

Parameters

NameTypeDescription
accountaddressThe address of the borrower.
bondcontract IHTokenThe address of the bond contract.
borrowAmountuint256The amount of hTokens borrowed.

DepositCollateral

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

Emitted when collateral is deposited.

Parameters

NameTypeDescription
accountaddressThe address of the borrower.
collateralcontract IErc20The related collateral.
collateralAmountuint256The 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

NameTypeDescription
liquidatoraddressThe address of the liquidator.
borroweraddressThe address of the borrower.
bondcontract IHTokenThe address of the bond contract.
repayAmountuint256The amount of repaid funds.
collateralcontract IErc20The address of the collateral contract.
seizedCollateralAmountuint256The 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

NameTypeDescription
payeraddressThe address of the payer.
borroweraddressThe address of the borrower.
bondcontract IHTokenThe address of the bond contract.
repayAmountuint256The amount of repaid funds.
newDebtAmountuint256The amount of the new debt.

SetFintroller

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

Emitted when a new Fintroller contract is set.

Parameters

NameTypeDescription
owneraddressThe address of the owner.
oldFintrolleraddressThe address of the old Fintroller contract.
newFintrolleraddressThe address of the new Fintroller contract.

SetOracle

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

Emitted when a new oracle contract is set.

Parameters

NameTypeDescription
owneraddressThe address of the owner.
oldOracleaddressThe address of the old oracle contract.
newOracleaddressThe address of the new oracle contract.

WithdrawCollateral

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

Emitted when collateral is withdrawn.

Parameters

NameTypeDescription
accountaddressThe address of the borrower.
collateralcontract IErc20The related collateral.
collateralAmountuint256The 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__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.