Functions
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 returnAmount)
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
settleBadDebt
function settleBadDebt(
address trader
) external
Settle trader's bad debt
Parameters:
| Name | Type | Description |
|---|
trader | address | The address of trader that will be settled |
getBalance
function getBalance(
address trader
) external returns (int256 balance)
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
) external returns (int256 balance)
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) |
getCollateralTokens
function getCollateralTokens(
address trader
) external returns (address[] collateralTokens)
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 |
getAccountValue
function getAccountValue(
address trader
) external returns (int256 accountValueX10_S)
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) |
getFreeCollateral
function getFreeCollateral(
address trader
) external returns (uint256 freeCollateral)
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 freeCollateralByRatio)
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
getFreeCollateralByToken
function getFreeCollateralByToken(
address trader,
address token
) external returns (uint256 freeCollateral)
Get the free collateral amount of the specified collateral token of specified 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 |
|---|
freeCollateral | uint256 | amount of that token (in the token's native decimals) |
getSettlementTokenValue
function getSettlementTokenValue(
address trader
) external returns (int256 balance)
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) |
getSettlementToken
function getSettlementToken(
) external returns (address settlementToken)
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 |
isLiquidatable
function isLiquidatable(
address trader
) external returns (bool isLiquidatable)
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
) external returns (int256 marginRequirement)
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(
) external returns (uint24 collateralMmRatio)
Get the maintenance margin ratio for collateral liquidation
Return Values:
| Name | Type | Description |
|---|
collateralMmRatio | uint24 | The maintenance margin ratio for collateral liquidation |
getLiquidatableCollateralBySettlement
function getLiquidatableCollateralBySettlement(
address token,
uint256 settlementX10_S
) external 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 |
getRepaidSettlementByCollateral
function getRepaidSettlementByCollateral(
address token,
uint256 collateral
) external 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 |
getMaxRepaidSettlementAndLiquidatableCollateral
function getMaxRepaidSettlementAndLiquidatableCollateral(
address trader,
address token
) external returns (uint256 maxRepaidSettlementX10_S, uint256 maxLiquidatableCollateral)
Get a trader's max repaid settlement & max liquidatable collateral by a given collateral 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
decimals
function decimals(
) external returns (uint8 decimals)
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 debtAmount)
(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 clearingHouseConfig)
Get ClearingHouseConfig contract address
Return Values:
| Name | Type | Description |
|---|
clearingHouseConfig | address | The address of ClearingHouseConfig contract |
getAccountBalance
function getAccountBalance(
) external returns (address accountBalance)
Get AccountBalance contract address
Return Values:
| Name | Type | Description |
|---|
accountBalance | address | The address of AccountBalance contract |
getInsuranceFund
function getInsuranceFund(
) external returns (address insuranceFund)
Get InsuranceFund contract address
Return Values:
| Name | Type | Description |
|---|
insuranceFund | address | The address of InsuranceFund contract |
getExchange
function getExchange(
) external returns (address exchange)
Get Exchange contract address
Return Values:
| Name | Type | Description |
|---|
exchange | address | The address of Exchange contract |
getClearingHouse
function getClearingHouse(
) external returns (address clearingHouse)
Get ClearingHouse contract address
Return Values:
| Name | Type | Description |
|---|
clearingHouse | address | The address of ClearingHouse contract |
getCollateralManager
function getCollateralManager(
) external returns (address clearingHouse)
Get CollateralManager contract address
Return Values:
| Name | Type | Description |
|---|
clearingHouse | address | The address of CollateralManager contract |
getWETH9
function getWETH9(
) external returns (address clearingHouse)
Get WETH9 contract address
Return Values:
| Name | Type | Description |
|---|
clearingHouse | address | The address of WETH9 contract |
Events
Deposited
event Deposited(
address collateralToken,
address trader,
uint256 amount
)
Emitted when trader deposit collateral into vault
Parameters:
| Name | Type | Description |
|---|
collateralToken | address | The address of token deposited |
trader | address | The address of trader |
amount | uint256 | The amount of token deposited |
Withdrawn
event Withdrawn(
address collateralToken,
address trader,
uint256 amount
)
Emitted when trader withdraw collateral from vault
Parameters:
| Name | Type | Description |
|---|
collateralToken | address | The address of token withdrawn |
trader | address | The address of trader |
amount | uint256 | The amount of token withdrawn |
CollateralLiquidated
event CollateralLiquidated(
address trader,
address collateralToken,
address liquidator,
uint256 collateral,
uint256 repaidSettlementWithoutInsuranceFundFeeX10_S,
uint256 insuranceFundFeeX10_S,
uint24 discountRatio
)
Emitted when a trader's collateral is liquidated
Parameters:
| Name | Type | Description |
|---|
trader | address | The address of trader |
collateralToken | address | The address of the token that is liquidated |
liquidator | address | The address of liquidator |
collateral | uint256 | The amount of collateral token liquidated |
repaidSettlementWithoutInsuranceFundFeeX10_S | uint256 | The amount of settlement token repaid |
for trader (in settlement token's decimals)
|insuranceFundFeeX10_S| uint256 | The amount of insurance fund fee paid(in settlement token's decimals)
|discountRatio| uint24 | The discount ratio of liquidation price
TrustedForwarderChanged
event TrustedForwarderChanged(
address trustedForwarder
)
Emitted when trustedForwarder is changed
trustedForwarder is only used for metaTx
Parameters:
| Name | Type | Description |
|---|
trustedForwarder | address | The address of trustedForwarder |
ClearingHouseChanged
event ClearingHouseChanged(
address clearingHouse
)
Emitted when clearingHouse is changed
Parameters:
| Name | Type | Description |
|---|
clearingHouse | address | The address of clearingHouse |
CollateralManagerChanged
event CollateralManagerChanged(
address collateralManager
)
Emitted when collateralManager is changed
Parameters:
| Name | Type | Description |
|---|
collateralManager | address | The address of collateralManager |
WETH9Changed
event WETH9Changed(
address WETH9
)
Emitted when WETH9 is changed
Parameters:
| Name | Type | Description |
|---|
WETH9 | address | The address of WETH9 |
BadDebtSettled
event BadDebtSettled(
address trader,
uint256 amount
)
Emitted when bad debt realized and settled
Parameters:
| Name | Type | Description |
|---|
trader | address | Address of the trader |
amount | uint256 | Absolute amount of bad debt |