ClearingHouse

Entry point for users to vault and perpetual markets

Methods

DEFAULT_ADMIN_ROLE

function DEFAULT_ADMIN_ROLE() external view returns (bytes32)

Returns

EMERGENCY_ADMIN

function EMERGENCY_ADMIN() external view returns (bytes32)

Returns

GOVERNANCE

function GOVERNANCE() external view returns (bytes32)

Returns

addStakingContract

function addStakingContract(contract IStakingContract staking) external nonpayable

Add a staking contract

Staking contract is not implemented yet

Parameters

allowListPerpetual

function allowListPerpetual(contract IPerpetual perp) external nonpayable

Add one perpetual market to the list of markets

Parameters

canSeizeCollateral

function canSeizeCollateral(address liquidatee) external view returns (bool)

Parameters

Returns

changePosition

function changePosition(uint256 idx, uint256 amount, uint256 minAmount, enum LibPerpetual.Side direction) external nonpayable

Open or increase or reduce a position, either LONG or SHORT

No number for the leverage is given but the amount in the vault must be bigger than minMarginAtCreation

Parameters

closePositionWithdrawCollateral

function closePositionWithdrawCollateral(uint256 idx, uint256 proposedAmount, uint256 minAmount, contract IERC20Metadata token) external nonpayable

Single close position function, groups closing position and withdrawing collateralImportant: proposedAmount must be large enough to close the entire position else the function call will fail

Parameters

decreaseAllowance

function decreaseAllowance(address receiver, uint256 subtractedAmount, contract IERC20Metadata token) external nonpayable

Decrease withdrawal approval for a receiving address on the vault

Parameters

delistPerpetual

function delistPerpetual(contract IPerpetual perp) external nonpayable

Remove on perpetual market of the list of markets

Parameters

deposit

function deposit(uint256 amount, contract IERC20Metadata token) external nonpayable

Deposit tokens into the vault

Parameters

depositFor

function depositFor(address user, uint256 amount, contract IERC20Metadata token) external nonpayable

Deposit tokens into the vault on behalf of another user

Parameters

extendPositionWithCollateral

function extendPositionWithCollateral(uint256 idx, address user, uint256 collateralAmount, contract IERC20Metadata token, uint256 positionAmount, enum LibPerpetual.Side direction, uint256 minAmount) external nonpayable

Single open position function, groups depositing collateral and extending position

Parameters

getDebtAcrossMarkets

function getDebtAcrossMarkets(address account) external view returns (int256 userDebt)

Get user debt across all perpetual markets

Parameters

Returns

getFreeCollateralByRatio

function getFreeCollateralByRatio(address account, int256 ratio) external view returns (int256 freeCollateral)

Get free collateral of a user given a chosen margin ratio

Parameters

Returns

getNumMarkets

function getNumMarkets() external view returns (uint256)

Return the number of active markets

Returns

getPnLAcrossMarkets

function getPnLAcrossMarkets(address account) external view returns (int256 unrealizedPositionPnl)

Get user profit/loss across all perpetual markets

Parameters

Returns

getRoleAdmin

function getRoleAdmin(bytes32 role) external view returns (bytes32)

Returns the admin role that controls role. See {grantRole} and {revokeRole}. To change a role's admin, use {_setRoleAdmin}.

Parameters

Returns

getTotalMarginRequirement

function getTotalMarginRequirement(address account, int256 ratio) external view returns (int256 requiredMargin)

Get the margin required to serve user debt at a chosen margin ratio

Parameters

Returns

grantRole

function grantRole(bytes32 role, address account) external nonpayable

Grants role to account. If account had not been already granted role, emits a {RoleGranted} event. Requirements: - the caller must have role's admin role. May emit a {RoleGranted} event.

Parameters

hasRole

function hasRole(bytes32 role, address account) external view returns (bool)

Returns true if account has been granted role.

Parameters

Returns

id

function id(uint256) external view returns (uint256)

Allowlisted Perpetual indices

Parameters

Returns

increaseAllowance

function increaseAllowance(address receiver, uint256 addedAmount, contract IERC20Metadata token) external nonpayable

Increase withdrawal approval for a receiving address on the vault

Parameters

insurance

function insurance() external view returns (contract IInsurance)

Insurance contract

Returns

insuranceRatio

function insuranceRatio() external view returns (uint256)

Insurance ratio

Once the insurance reserve exceed this ratio of the tvl, governance can withdraw exceeding insurance fee

Returns

isEmergencyAdmin

function isEmergencyAdmin(address account) external view returns (bool)

Parameters

Returns

isGovernor

function isGovernor(address account) external view returns (bool)

Parameters

Returns

liquidateLp

function liquidateLp(uint256 idx, address liquidatee, uint256[2] minVTokenAmounts, uint256 proposedAmount, uint256 minAmount) external nonpayable

Submit the address of a LP whose position is worth liquidating for a reward

Parameters

liquidateTrader

function liquidateTrader(uint256 idx, address liquidatee, uint256 proposedAmount, uint256 minAmount) external nonpayable

Submit the address of an Trader whose position is worth liquidating for a reward

Parameters

liquidationDiscount

function liquidationDiscount() external view returns (uint256)

Discount on the collateral price for the liquidator

Returns

liquidationReward

function liquidationReward() external view returns (uint256)

liquidation reward paid to liquidators

Paid on dollar value of an trader position. important: liquidationReward < minMargin or liquidations will result in protocol losses

Returns

liquidationRewardInsuranceShare

function liquidationRewardInsuranceShare() external view returns (uint256)

Portion of the liquidation reward that the insurance gets

Returns

marketIds

function marketIds() external view returns (uint256)

Number of Allowlisted Perpetuals

Returns

minMargin

function minMargin() external view returns (int256)

minimum maintenance margin

Returns

minMarginAtCreation

function minMarginAtCreation() external view returns (int256)

minimum margin when opening a position

Returns

minPositiveOpenNotional

function minPositiveOpenNotional() external view returns (uint256)

minimum positive open notional when opening a position

Returns

nonUACollSeizureDiscount

function nonUACollSeizureDiscount() external view returns (uint256)

Discount ratio to be applied on non-UA collaterals before seizing said collaterals for some UA

Must be lower than liquidationDiscount to ensure liquidations don't generate bad debt

Returns

openReversePosition

function openReversePosition(uint256 idx, uint256 closeProposedAmount, uint256 closeMinAmount, uint256 openProposedAmount, uint256 openMinAmount, enum LibPerpetual.Side direction) external nonpayable

Open a position in the opposite direction of the currently opened positionFor example, a trader with a LONG position can switch to a SHORT position with just one call to this function

Parameters

pause

function pause() external nonpayable

Pause the contract

Can only be called by Emergency Admin

paused

function paused() external view returns (bool)

Returns true if the contract is paused, and false otherwise.

Returns

perpetuals

function perpetuals(uint256) external view returns (contract IPerpetual)

Allowlisted Perpetual contracts

Parameters

Returns

provideLiquidity

function provideLiquidity(uint256 idx, uint256[2] amounts, uint256 minLpAmount) external nonpayable

Provide liquidity to the pool, without depositing new capital in the vault

Parameters

removeLiquidity

function removeLiquidity(uint256 idx, uint256 liquidityAmountToRemove, uint256[2] minVTokenAmounts, uint256 proposedAmount, uint256 minAmount) external nonpayable

Remove liquidity from the pool and account profit/loss in UA

Parameters

renounceRole

function renounceRole(bytes32 role, address account) external nonpayable

Revokes role from the calling account. Roles are often managed via {grantRole} and {revokeRole}: this function's purpose is to provide a mechanism for accounts to lose their privileges if they are compromised (such as when a trusted device is misplaced). If the calling account had been revoked role, emits a {RoleRevoked} event. Requirements: - the caller must be account. May emit a {RoleRevoked} event.

Parameters

revokeRole

function revokeRole(bytes32 role, address account) external nonpayable

Revokes role from account. If account had been granted role, emits a {RoleRevoked} event. Requirements: - the caller must have role's admin role. May emit a {RoleRevoked} event.

Parameters

seizeCollateral

function seizeCollateral(address liquidatee) external nonpayable

Buy the non-UA collaterals of a user at a discounted UA price to settle the debt of said user

Parameters

setParameters

function setParameters(IClearingHouse.ClearingHouseParams params) external nonpayable

Parameters

settleDust

function settleDust(uint256 idx, uint256 proposedAmount, uint256 minAmount, enum LibPerpetual.Side direction) external nonpayable

Sell dust of a given market

Can only be called by Emergency Admin

Parameters

stakingContract

function stakingContract() external view returns (contract IStakingContract)

Staking contract

Returns

supportsInterface

function supportsInterface(bytes4 interfaceId) external view returns (bool)

See {IERC165-supportsInterface}.

Parameters

Returns

uaDebtSeizureThreshold

function uaDebtSeizureThreshold() external view returns (int256)

UA debt amount at which non-UA collaterals can be seized to pay back UA debts

Returns

unpause

function unpause() external nonpayable

Unpause the contract

Can only be called by Emergency Admin

updateGlobalState

function updateGlobalState() external nonpayable

vault

function vault() external view returns (contract IVault)

Vault contract

Returns

withdraw

function withdraw(uint256 amount, contract IERC20Metadata token) external nonpayable

Withdraw tokens from the vault

Parameters

withdrawAll

function withdrawAll(contract IERC20Metadata token) external nonpayable

Withdraw all tokens from the vault

Should only be called by the trader

Parameters

withdrawFrom

function withdrawFrom(address user, uint256 amount, contract IERC20Metadata token) external nonpayable

Withdraw tokens from the vault on behalf of a user

Parameters

Events

ChangePosition

event ChangePosition(uint256 indexed idx, address indexed user, enum LibPerpetual.Side direction, int256 addedOpenNotional, int256 addedPositionSize, int256 profit, int256 tradingFeesPayed, int256 insuranceFeesPayed, bool isPositionIncreased, bool isPositionClosed)

Emitted when a position is opened/extended

Parameters

ClearingHouseParametersChanged

event ClearingHouseParametersChanged(int256 newMinMargin, int256 newMinMarginAtCreation, uint256 newMinPositiveOpenNotional, uint256 newLiquidationReward, uint256 newInsuranceRatio, uint256 newLiquidationRewardInsuranceShare, uint256 newLiquidationDiscount, uint256 nonUACollSeizureDiscount, int256 uaDebtSeizureThreshold)

Emitted when parameters are changed

Parameters

DustSold

event DustSold(uint256 indexed idx, int256 profit, int256 tradingFeesPayed)

Emitted when dust is sold by governance

Parameters

LiquidationCall

event LiquidationCall(uint256 indexed idx, address indexed liquidatee, address indexed liquidator, uint256 notional, int256 profit, int256 tradingFeesPayed, bool isTrader)

Emitted when an user position is liquidated

Parameters

LiquidityProvided

event LiquidityProvided(uint256 indexed idx, address indexed liquidityProvider, uint256 quoteAmount, uint256 baseAmount, int256 tradingFeesEarned)

Emitted when (additional) liquidity is provided

Parameters

LiquidityRemoved

event LiquidityRemoved(uint256 indexed idx, address indexed liquidityProvider, uint256 reductionRatio, int256 profit, int256 tradingFeesPayed, bool isPositionClosed)

Emitted when liquidity is removed

Parameters

MarketAdded

event MarketAdded(contract IPerpetual indexed perpetual, uint256 listedIdx, uint256 numPerpetuals)

Emitted when new perpetual market is added

Parameters

MarketRemoved

event MarketRemoved(contract IPerpetual indexed perpetual, uint256 delistedIdx, uint256 numPerpetuals)

Emitted when perpetual market is removed

Parameters

Paused

event Paused(address account)

Parameters

RoleAdminChanged

event RoleAdminChanged(bytes32 indexed role, bytes32 indexed previousAdminRole, bytes32 indexed newAdminRole)

Parameters

RoleGranted

event RoleGranted(bytes32 indexed role, address indexed account, address indexed sender)

Parameters

RoleRevoked

event RoleRevoked(bytes32 indexed role, address indexed account, address indexed sender)

Parameters

SeizeCollateral

event SeizeCollateral(address indexed liquidatee, address indexed liquidator)

Emitted when an user non-UA collaterals are seized

Parameters

StakingContractChanged

event StakingContractChanged(contract IStakingContract newStakingContract)

Parameters

Unpaused

event Unpaused(address account)

Parameters

Errors

ClearingHouse_AmountProvidedTooLarge

error ClearingHouse_AmountProvidedTooLarge()

Emitted when a user attempts to provide liquidity with amount larger than his free collateral or collateral balance

ClearingHouse_ChangePositionZeroAmount

error ClearingHouse_ChangePositionZeroAmount()

Emitted when a user attempts to change his position with no amount

ClearingHouse_ClosePositionStillOpen

error ClearingHouse_ClosePositionStillOpen()

Emitted when the position is not reduced entirely using closePositionWithdrawCollateral

ClearingHouse_DepositForZeroAddress

error ClearingHouse_DepositForZeroAddress()

Emitted when attempting to deposit to the zero address

ClearingHouse_ExcessiveLiquidationDiscount

error ClearingHouse_ExcessiveLiquidationDiscount()

Emitted when the liquidationDiscount is too high

ClearingHouse_ExcessiveLiquidationRewardInsuranceShare

error ClearingHouse_ExcessiveLiquidationRewardInsuranceShare()

Emitted when the proposed share of the liquidation reward for the insurance is too high

ClearingHouse_ExcessivePositiveOpenNotional

error ClearingHouse_ExcessivePositiveOpenNotional()

Emitted when the proposed minimum open notional is too high

ClearingHouse_ExtendPositionInsufficientMargin

error ClearingHouse_ExtendPositionInsufficientMargin()

Emitted when there is not enough margin to extend to the proposed position amount

ClearingHouse_ExtendPositionZeroAmount

error ClearingHouse_ExtendPositionZeroAmount()

Emitted when a user attempts to extend their position with amount equal to 0

ClearingHouse_InsufficientDiffBtwLiquidationDiscountAndNonUACollSeizureDiscount

error ClearingHouse_InsufficientDiffBtwLiquidationDiscountAndNonUACollSeizureDiscount()

Emitted when the difference between liquidationDiscount and nonUACollSeizureDiscount isn't large enough

ClearingHouse_InsufficientUaDebtSeizureThreshold

error ClearingHouse_InsufficientUaDebtSeizureThreshold()

Emitted when the proposed UA debt limit is lower than the minimum acceptable value

ClearingHouse_InvalidInsuranceRatio

error ClearingHouse_InvalidInsuranceRatio()

Emitted when the proposed insurance ratio is too low or too high

ClearingHouse_InvalidLiquidationReward

error ClearingHouse_InvalidLiquidationReward()

Emitted when the proposed liquidation reward is too low or too high

ClearingHouse_InvalidMinMargin

error ClearingHouse_InvalidMinMargin()

Emitted when the proposed minMargin is too low or too high

ClearingHouse_InvalidMinMarginAtCreation

error ClearingHouse_InvalidMinMarginAtCreation()

Emitted when the proposed minMarginAtCreation is too low or too high

ClearingHouse_LiquidateInsufficientProposedAmount

error ClearingHouse_LiquidateInsufficientProposedAmount()

Emitted when the attempted liquidation does not close the full position

ClearingHouse_LiquidateInvalidPosition

error ClearingHouse_LiquidateInvalidPosition()

Emitted when the liquidatee does not have an open position

ClearingHouse_LiquidateValidMargin

error ClearingHouse_LiquidateValidMargin()

Emitted when the margin of the liquidatee's position is still valid

ClearingHouse_LiquidationDebtSizeZero

error ClearingHouse_LiquidationDebtSizeZero()

Emitted when a collateral liquidation for a user with no UA debt is tried

ClearingHouse_MarketDoesNotExist

error ClearingHouse_MarketDoesNotExist()

Emitted when attempting to remove a perpetual market which does not exist

ClearingHouse_NegativeDustProceeds

error ClearingHouse_NegativeDustProceeds()

Emitted when governance tries to sell dust with a negative balance

ClearingHouse_PerpetualMarketAlreadyAssigned

error ClearingHouse_PerpetualMarketAlreadyAssigned()

Emitted when passing the address of a perpetual market which has already been added

ClearingHouse_ProvideLiquidityZeroAmount

error ClearingHouse_ProvideLiquidityZeroAmount()

Emitted when a user attempts to provide liquidity with amount equal to 0

ClearingHouse_ReducePositionZeroAmount

error ClearingHouse_ReducePositionZeroAmount()

Emitted when a user attempts to reduce their position with amount equal to 0

ClearingHouse_RemoveLiquidityInsufficientFunds

error ClearingHouse_RemoveLiquidityInsufficientFunds()

Emitted when a user attempts to withdraw more liquidity than they have

ClearingHouse_SufficientUserCollateral

error ClearingHouse_SufficientUserCollateral()

Emitted when a liquidator tries seizing collateral of user with sufficient collaterals level

ClearingHouse_UnderOpenNotionalAmountRequired

error ClearingHouse_UnderOpenNotionalAmountRequired()

Emitted when a user tries to open a position with an incorrect open notional amount

ClearingHouse_WithdrawInsufficientMargin

error ClearingHouse_WithdrawInsufficientMargin()

Emitted when there is not enough margin to withdraw the requested amount

ClearingHouse_ZeroAddress

error ClearingHouse_ZeroAddress()

Emitted when the zero address is provided

PRBMathSD59x18__AbsInputTooSmall

error PRBMathSD59x18__AbsInputTooSmall()

Emitted when the input is MIN_SD59x18.

PRBMathSD59x18__MulInputTooSmall

error PRBMathSD59x18__MulInputTooSmall()

Emitted when one of the inputs is MIN_SD59x18.

PRBMathSD59x18__MulOverflow

error PRBMathSD59x18__MulOverflow(uint256 rAbs)

Emitted when the intermediary absolute result overflows SD59x18.

Parameters

PRBMath__MulDivFixedPointOverflow

error PRBMath__MulDivFixedPointOverflow(uint256 prod1)

Emitted when the result overflows uint256.

Parameters

Last updated