Functions
receive
function receive(
) external
only used for unwrapping weth in withdrawETH
initialize
function initialize(
) external
setTrustedForwarder
function setTrustedForwarder(
) external
setClearingHouse
function setClearingHouse(
) external
setCollateralManager
function setCollateralManager(
) external
setWETH9
function setWETH9(
) external
deposit
function deposit(
address token,
uint256 amount
) external
Deposit collateral into vault
Parameters:
| Name | Type | Description |
|---|
token | address | The address of the token to deposit |
amount | uint256 | The amount of the token to deposit |
depositFor
function depositFor(
address to,
address token,
uint256 amount
) external
Deposit the collateral token for other account
Parameters:
| Name | Type | Description |
|---|
to | address | The address of the account to deposit to |
token | address | The address of collateral token |
amount | uint256 | The amount of the token to deposit |
depositEther
function depositEther(
) external
Deposit ETH as collateral into vault
depositEtherFor
function depositEtherFor(
address to
) external
Deposit ETH as collateral for specified account
Parameters:
| Name | Type | Description |
|---|
to | address | The address of the account to deposit to |
withdraw
function withdraw(
address token,
uint256 amount
) external
Withdraw collateral from vault
Parameters:
| Name | Type | Description |
|---|
token | address | The address of the token to withdraw |
amount | uint256 | The amount of the token to withdraw |
withdrawEther
function withdrawEther(
uint256 amount
) external
Withdraw ETH from vault
Parameters:
| Name | Type | Description |
|---|
amount | uint256 | The amount of the ETH to withdraw |
withdrawAll
function withdrawAll(
address token
) external returns (uint256 amount)
Withdraw all free collateral from vault
Parameters:
| Name | Type | Description |
|---|
token | address | The address of the token to withdraw |
Return Values:
| Name | Type | Description |
|---|
amount | uint256 | The amount of the token withdrawn |
withdrawAllEther
function withdrawAllEther(
) external returns (uint256 amount)
Withdraw all free collateral of ETH from vault
Return Values:
| Name | Type | Description |
|---|
amount | uint256 | The amount of ETH withdrawn |
liquidateCollateral
function liquidateCollateral(
address trader,
address token,
uint256 amount,
bool isDenominatedInSettlementToken
) external returns (uint256)
Liquidate trader's collateral by given settlement token amount or non settlement token amount
Parameters:
| Name | Type | Description |
|---|
trader | address | The address of trader that will be liquidated |
token | address | The address of non settlement collateral token that the trader will be liquidated |
amount | uint256 | The amount of settlement token that the liquidator will repay for trader or |
the amount of non-settlement collateral token that the liquidator will charge from trader
|isDenominatedInSettlementToken | bool | Whether the amount is denominated in settlement token or not
Return Values:
| Name | Type | Description |
|---|
returnAmount | uint256 | The amount of a non-settlement token (in its native decimals) that is liquidated |
when `isDenominatedInSettlementToken` is true or the amount of settlement token that is repaid
when `isDenominatedInSettlementToken` is false
getSettlementToken
function getSettlementToken(
) external returns (address)
Get the settlement token address
We assume the settlement token should match the denominator of the price oracle.
i.e. if the settlement token is USDC, then the oracle should be priced in USD
Return Values:
| Name | Type | Description |
|---|
settlementToken | address | The address of the settlement token |
decimals
function decimals(
) external returns (uint8)
Get settlement token decimals
cached the settlement token's decimal for gas optimization
Return Values:
| Name | Type | Description |
|---|
decimals | uint8 | The decimals of settlement token |
getTotalDebt
function getTotalDebt(
) external returns (uint256)
(Deprecated) Get the borrowed settlement token amount from insurance fund
Return Values:
| Name | Type | Description |
|---|
debtAmount | uint256 | The debt amount (in settlement token's decimals) |
getClearingHouseConfig
function getClearingHouseConfig(
) external returns (address)
Get ClearingHouseConfig contract address
Return Values:
| Name | Type | Description |
|---|
clearingHouseConfig | address | The address of ClearingHouseConfig contract |
getAccountBalance
function getAccountBalance(
) external returns (address)
Get AccountBalance contract address
Return Values:
| Name | Type | Description |
|---|
accountBalance | address | The address of AccountBalance contract |
getInsuranceFund
function getInsuranceFund(
) external returns (address)
Get InsuranceFund contract address
Return Values:
| Name | Type | Description |
|---|
insuranceFund | address | The address of InsuranceFund contract |
getExchange
function getExchange(
) external returns (address)
Get Exchange contract address
Return Values:
| Name | Type | Description |
|---|
exchange | address | The address of Exchange contract |
getClearingHouse
function getClearingHouse(
) external returns (address)
Get ClearingHouse contract address
Return Values:
| Name | Type | Description |
|---|
clearingHouse | address | The address of ClearingHouse contract |
getCollateralManager
function getCollateralManager(
) external returns (address)
Get CollateralManager contract address
Return Values:
| Name | Type | Description |
|---|
clearingHouse | address | The address of CollateralManager contract |
getWETH9
function getWETH9(
) external returns (address)
Get WETH9 contract address
Return Values:
| Name | Type | Description |
|---|
clearingHouse | address | The address of WETH9 contract |
getFreeCollateral
function getFreeCollateral(
address trader
) external returns (uint256)
Get the free collateral value denominated in the settlement token of the specified trader
Parameters:
| Name | Type | Description |
|---|
trader | address | The address of the trader |
Return Values:
| Name | Type | Description |
|---|
freeCollateral | uint256 | the value (in settlement token's decimals) of free collateral available |
for withdraw or opening new positions or orders)
getFreeCollateralByRatio
function getFreeCollateralByRatio(
address trader,
uint24 ratio
) external returns (int256)
Get the free collateral amount of the specified trader and collateral ratio
There are three configurations for different insolvency risk tolerances:
conservative, moderate &aggressive. We will start with the conservative one
and gradually move to aggressive to increase capital efficiency
Parameters:
| Name | Type | Description |
|---|
trader | address | The address of the trader |
ratio | uint24 | The margin requirement ratio, imRatio or mmRatio |
Return Values:
| Name | Type | Description |
|---|
freeCollateralByRatio | int256 | freeCollateral (in settlement token's decimals), by using the |
input margin requirement ratio; can be negative
getSettlementTokenValue
function getSettlementTokenValue(
address trader
) external returns (int256)
Get the specified trader's settlement value, including pending fee, funding payment,
owed realized PnL and unrealized PnL
Note the difference between settlementTokenBalanceX10_S, getSettlementTokenValue() and getBalance():
They are all settlement token balances but with or without
pending fee, funding payment, owed realized PnL, unrealized PnL, respectively
In practical applications, we use getSettlementTokenValue() to get the trader's debt (if < 0)
Parameters:
| Name | Type | Description |
|---|
trader | address | The address of the trader |
Return Values:
| Name | Type | Description |
|---|
balance | int256 | The balance amount (in settlement token's decimals) |
getAccountValue
function getAccountValue(
address trader
) external returns (int256)
Get account value of the specified trader
Parameters:
| Name | Type | Description |
|---|
trader | address | The address of the trader |
Return Values:
| Name | Type | Description |
|---|
accountValueX10_S | int256 | account value (in settlement token's decimals) |
getCollateralTokens
function getCollateralTokens(
address trader
) external returns (address[])
Get the array of collateral token addresses that a trader has in their account
Parameters:
| Name | Type | Description |
|---|
trader | address | The address of the trader |
Return Values:
| Name | Type | Description |
|---|
collateralTokens | address[] | array of collateral token addresses |
getBalance
function getBalance(
address trader
) public returns (int256)
Get the specified trader's settlement token balance, without pending fee, funding payment
and owed realized PnL
The function is equivalent to getBalanceByToken(trader, settlementToken)
We keep this function solely for backward-compatibility with the older single-collateral system.
In practical applications, the developer might want to use getSettlementTokenValue() instead
because the latter includes pending fee, funding payment etc.
and therefore more accurately reflects a trader's settlement (ex. USDC) balance
Parameters:
| Name | Type | Description |
|---|
trader | address | The address of the trader |
Return Values:
| Name | Type | Description |
|---|
balance | int256 | The balance amount (in settlement token's decimals) |
getBalanceByToken
function getBalanceByToken(
address trader,
address token
) public returns (int256)
Get the balance of Vault of the specified collateral token and trader
Parameters:
| Name | Type | Description |
|---|
trader | address | The address of the trader |
token | address | The address of the collateral token |
Return Values:
| Name | Type | Description |
|---|
balance | int256 | The balance amount (in its native decimals) |
getFreeCollateralByToken
function getFreeCollateralByToken(
address trader,
address token
) public returns (uint256)
Get the free collateral amount of the specified collateral token of specified trader
getFreeCollateralByToken(token) = (getSettlementTokenValue() >= 0)
? min(getFreeCollateral() / indexPrice[token], getBalanceByToken(token))
: 0
if token is settlementToken, then indexPrice[token] = 1
Parameters:
| Name | Type | Description |
|---|
trader | address | The address of the trader |
token | address | The address of the collateral token |
Return Values:
| Name | Type | Description |
|---|
freeCollateral | uint256 | amount of that token (in the token's native decimals) |
isLiquidatable
function isLiquidatable(
address trader
) public returns (bool)
Parameters:
| Name | Type | Description |
|---|
trader | address | The address of the trader |
Return Values:
| Name | Type | Description |
|---|
isLiquidatable | bool | If the trader can be liquidated |
getMarginRequirementForCollateralLiquidation
function getMarginRequirementForCollateralLiquidation(
address trader
) public returns (int256)
get the margin requirement for collateral liquidation of a trader
this value is compared with ClearingHouse.getAccountValue() (int)
Parameters:
| Name | Type | Description |
|---|
trader | address | The address of the trader |
Return Values:
| Name | Type | Description |
|---|
marginRequirement | int256 | margin requirement (in 18 decimals) |
getCollateralMmRatio
function getCollateralMmRatio(
) public returns (uint24)
Get the maintenance margin ratio for collateral liquidation
Return Values:
| Name | Type | Description |
|---|
collateralMmRatio | uint24 | The maintenance margin ratio for collateral liquidation |
getRepaidSettlementByCollateral
function getRepaidSettlementByCollateral(
address token,
uint256 collateral
) public returns (uint256 settlementX10_S)
Get a trader's repaid settlement amount by a given collateral amount
Parameters:
| Name | Type | Description |
|---|
token | address | The address of the token of the trader's collateral |
collateral | uint256 | The amount of collateral token the liquidator wants to get |
Return Values:
| Name | Type | Description |
|---|
settlementX10_S | uint256 | The settlement amount(in settlement token's decimals) the liquidator needs to pay |
getLiquidatableCollateralBySettlement
function getLiquidatableCollateralBySettlement(
address token,
uint256 settlementX10_S
) public returns (uint256 collateral)
Get a trader's liquidatable collateral amount by a given settlement amount
Parameters:
| Name | Type | Description |
|---|
token | address | The address of the token of the trader's collateral |
settlementX10_S | uint256 | The amount of settlement token the liquidator wants to pay |
Return Values:
| Name | Type | Description |
|---|
collateral | uint256 | The collateral amount(in its native decimals) the liquidator can get |
getMaxRepaidSettlementAndLiquidatableCollateral
function getMaxRepaidSettlementAndLiquidatableCollateral(
address trader,
address token
) public returns (uint256 maxRepaidSettlementX10_S, uint256 maxLiquidatableCollateral)
Get a trader's max repaid settlement & max liquidatable collateral by a given collateral token
formula:
maxRepaidSettlement = maxLiquidatableCollateral (indexTwap (1 - discountRatio))
maxLiquidatableCollateral =
min(maxRepaidSettlement / (indexTwap * (1 - discountRatio)), getBalanceByToken(trader, token))
Parameters:
| Name | Type | Description |
|---|
trader | address | The address of the trader |
token | address | The address of the token of the trader's collateral |
Return Values:
| Name | Type | Description |
|---|
maxRepaidSettlementX10_S | uint256 | The maximum settlement amount(in settlement token's decimals) |
the liquidator needs to pay to liquidate a trader's collateral token
|maxLiquidatableCollateral | uint256 | The maximum liquidatable collateral amount
(in the collateral token's native decimals) of a trader
settleBadDebt
function settleBadDebt(
address trader
) public
Settle trader's bad debt
will only settle the bad debt when trader didn't have position and non-settlement collateral
Parameters:
| Name | Type | Description |
|---|
trader | address | The address of trader that will be settled |