PerpLib

PerpLib

Library for core Domination Finance perpetual exchange logic

Computes PnL, funding payments, withdraw delays, etc. Mostly used by DomFiPerp and OrderBookV2.

Addresses

Chain	Address

Functions

_canTakeProfit

Return whether a position is allowed to take profit: if either

• the price has changed by more than minPriceChange
• minProfitTime has elapsed

function _canTakeProfit(
    bool isLong,
    uint256 positionTimestamp,
    FPUnsigned positionPrice,
    FPUnsigned oraclePrice,
    FPUnsigned minPriceChange,
    uint256 minProfitTime
) internal view returns (
    bool canTakeProfit
)

Parameters

Name	Type	Description
isLong	bool	Whether this is a long position
positionTimestamp	uint256	Time position was last increased
positionPrice	FPUnsigned	Composite price when position was increase/updated
oraclePrice	FPUnsigned	Current oracle price
minPriceChange	FPUnsigned	Minimum price change to take profit. This should be larger than the minimum oracle price change
minProfitTime	uint256	Time to wait for minPriceChange before realizing profit anyway.

Return Values

Name	Type	Description
canTakeProfit	bool	If a position is allowed to take profit.

_getPnl

Compute the PnL of a position, in collateral units, based on price action.

function _getPnl(
    bool isLong,
    FPUnsigned positionPrice,
    FPUnsigned positionLeverage,
    uint256 margin,
    FPUnsigned price
) internal pure returns (
    FPSigned pnl
)

Parameters

Name	Type	Description
isLong	bool	If this is a long position (false=short)
positionPrice	FPUnsigned	Composite price when position was increase/updated
positionLeverage	FPUnsigned	Leverage of the position, used to compute size
margin	uint256	Margin of the position, used to compute size
price	FPUnsigned	Current price of the position, including any modifications

Return Values

Name	Type	Description
pnl	FPSigned	Profit (positive) or loss (negative) attributable to position

_getFundingPayment

Compute the funding payment owed by a position

function _getFundingPayment(
    bool isLong,
    FPUnsigned positionLeverage,
    uint256 margin,
    FPSigned funding,
    FPSigned cumulativeFunding,
    FPUnsigned cumulativeInterest
) internal pure returns (
    FPSigned fundingPayment
)

Parameters

Name	Type	Description
isLong	bool	Whether this position is long (false=short)
positionLeverage	FPUnsigned	Leverage of the position, used to compute size
margin	uint256	Margin of the position, used to compute size
funding	FPSigned	Composite cumulative funding+interest when the position was created/updated
cumulativeFunding	FPSigned	Current cumulative funding for the position's product.
cumulativeInterest	FPUnsigned	Current cumulative base interest rate for the position's product

Return Values

Name	Type	Description
fundingPayment	FPSigned	Funding payment owed by the position. Negative values increase the value of the position.

_getTradeFee

Compute the trade fee incurred by changing a position's size

function _getTradeFee(
    uint256 margin,
    FPUnsigned leverage,
    FPUnsigned productFee,
    address user,
    address sender,
    contract IFeeCalculator feeCalculator
) internal view returns (
    uint256 tradeFee
)

Parameters

Name	Type	Description
margin	uint256	Margin of the increase/decrease
leverage	FPUnsigned	Leverage at which the increase/decrease was applied
productFee	FPUnsigned	Product's normal trade fee rate
user	address	Owner of the position
sender	address	Sender of the transaction
feeCalculator	contract IFeeCalculator	FeeCalculator instance to apply user/sender discount

Return Values

Name	Type	Description
tradeFee	uint256	Collateral owed by user

_getUtilizationRatio

Compute utilization ratio of the vault, and whether instant redemptions should be allowed.

function _getUtilizationRatio(
    FPUnsigned totalOpenInterest,
    uint256 balance,
    FPSigned totalPnl,
    uint256 pendingWithdraw,
    FPUnsigned healthyUtilizationRatio
) internal pure returns (
    bool instantRedeemAvailable,
    FPSigned utilizationRatio
)

Dev note

Utilization ratio: $\frac{totalOpenInterest}{balance - pendingWithdraw - totalPnl}$. If the denominator, effective balance, is zero, return utilizationRatio=0 and allow instant redemptions only if there is no open interest.

Parameters

Name	Type	Description
totalOpenInterest	FPUnsigned	Sum of sizes (margin * leverage) of all open positions
balance	uint256	Collateral balance of the vault (deposits - trader PnL)
totalPnl	FPSigned	Outstanding total PnL of all positions
pendingWithdraw	uint256	Estimated collateral value of all pending withdraw requests
healthyUtilizationRatio	FPUnsigned	The maximum utilization ratio before instant withdrawals are forbidden

Return Values

Name	Type	Description
instantRedeemAvailable	bool	$utilizationRatio \leq healthyUtilizationRatio$
utilizationRatio	FPSigned	$\frac{totalOpenInterest}{balance - pendingWithdraw - totalPnl}$

_getWithdrawDuration

Compute the duration of a withdraw request

function _getWithdrawDuration(
    FPSigned utilizationRatio,
    FPUnsigned requestedShareFraction,
    FPUnsigned healthyUtilizationRatio,
    uint256 maxWithdrawDuration,
    uint256 durationPerUtilizationRatio
) internal pure returns (
    uint64 withdrawDuration
)

Parameters

Name	Type	Description
utilizationRatio	FPSigned	utilization ratio (given by _getUtilizationRatio)
requestedShareFraction	FPUnsigned	Fraction of the vault shares requested. $[0,1]$
healthyUtilizationRatio	FPUnsigned	Utilization ratio below which withdraws should be immediate
maxWithdrawDuration	uint256	Maximum permitted withdraw request duration
durationPerUtilizationRatio	uint256	See DomFiVault.setTotalDurationPerUtilizationRatio

Return Values

Name	Type	Description
withdrawDuration	uint64	Length of a withdraw request