⭐Vault

The Perp v3 vault is a collection of contracts responsible for holding and managing all user collateral (maker, taker).

Vault

Deposit and withdraw.

/// @notice `amountXCD` uses collateral token decimals (6 decimals for USDT)
function deposit(
    address trader, 
    uint256 amountXCD
)

function withdraw(
    uint256 amountXCD
)

Add / remove margin. Get marketId from Metadata.

/// @inheritdoc IVault
/// @notice `amountXCD` uses collateral token decimals (6 decimals for USDT)
function transferFundToMargin(
    uint256 marketId, 
    uint256 amountXCD
)

function transferMarginToFund(
    uint256 marketId, 
    uint256 amountXCD
)

Read PnL, margin and other account data. Get marketId from Metadata.

/// @notice Read pending (unrealized) PnL for a given market.
function getUnsettledPnl(
    uint256 marketId, 
    address trader
)
returns (
    int256 unsettledPnl
)

/// @notice Read `fund`; the user's free (usable) collateral balance.
function getFund(
    address trader
)
returns (
    uint256 fund
)

/// @notice Read position margin exclusive of pending fees, unsettledPnLetc.
function getSettledMargin(
    uint256 marketId, 
    address trader
)
returns (
    int256 marginWithoutPending
)

/// @notice Read total position margin
/// @dev margin = settledMargin + unsettledPnl
function getMargin(
    uint256 marketId,
    address trader
)
returns (
    int256 margin
)

/// @notice Read position free margin (removable margin)
/// @dev free margin = max(margin state + pending margin + settleable unsettled pnl, 0)
function getFreeMargin(
    uint256 marketId,
    address trader
)
returns (
    uint256 freeMargin
)

/// @notice Read position size
function getPositionSize(
    uint256 marketId,
    address trader
)
returns (
    int256 positionSize
)

/// @notice Read position open notional (position value in settlement token at time of position entry.
function getOpenNotional(
    uint256 marketId,
    address trader
)
returns (
    int256 openNotional
)

/// @notice Read position pending margin; margin after current unsettled PnL, borrowing fees, funding fees are settled.
function getPendingMargin(
    uint256 marketId, 
    address trader
)
returns (
    int256 pendingMargin
)

IMarginProfile

/// @notice Margin requirement types
enum MarginRequirementType {
    INITIAL,
    MAINTENANCE
}

/// @notice margin ratio = account value / open notional
function getMarginRatio(
    uint256 marketId, 
    address trader, 
    uint256 price
)
returns (
    int256 marginRatio
)

/// @notice free collateral (for withdrawal) = min(free margin, account value) - initial margin requirement
/// @notice See free collateral for trades below
function getFreeCollateral(
    uint256 marketId, 
    address trader, 
    uint256 price
)
returns (
    uint256 freeCollateral
)

/// @notice free collateral (for trades) = min(margin, account value) - initial or maintenance margin requirement
/// INITIAL is for increasing position, MAINTENANCE is for reducing position
function getFreeCollateralForTrade(
    uint256 marketId,
    address trader,
    uint256 price, // User supplied price (recommend using latest Pyth price)
    MarginRequirementType marginRequirementType
)
returns (
    int256 freeCollateralForTrade
);

/// @notice margin requirement = open notional * required margin ratio (initial or maintenance)
function getMarginRequirement(
    uint256 marketId,
    address trader,
    MarginRequirementType marginRequirementType
) external view returns (uint256);

/// @notice unrealized pnl = position value + open notional
function getUnrealizedPnl(uint256 marketId, address trader, uint256 price) external view returns (int256);

/// @notice account value = margin (note it should include unsettled pnl and borrowing fee) + unrealized pnl
function getAccountValue(uint256 marketId, address trader, uint256 price) external view returns (int256);

/// @notice the margin trader can use for trading. when positive, it's always greater than or equal to "free margin"
function getMargin(uint256 marketId, address trader) external view returns (int256);

/// @notice the margin trader can access in any cases. it may be less than margin when pnl pool doesn't has enough
/// liquidity for unsettled profit
function getFreeMargin(uint256 marketId, address trader) external view returns (uint256);

function getOpenNotional(uint256 marketId, address trader) external view returns (int256);

function getPositionSize(uint256 marketId, address trader) external view returns (int256);