ExchangeFormulas

Addresses

Chain	Address
Arbitrum Sepolia	0xF8B27E66Ff3A28A14546aF9b123977288A150235
Base Sepolia	0x39024b1e621E3E8be2520199349d9490Da4DB7E4
Base Mainnet	0x42011F7BB1813564Eb025291A53D55d37b13b567

Functions

constructor

constructor(struct StorageInstance app_) public

Dev note

This contract is not designed to be upgradable and is strictly a logic contract. Hance, we are directly initializing the contract from the constructor.

calculatePrice

Apply two kinds of slippage to oracle price:

% penalty in range [0,∞) as amount approaches reserve (where "reserve" is max position increase allowed by risk parameters). Like typical constant-product dex slippage.
% offset in range [0,maxShift] proportional to current / max exposure. Improves price for orders reducing exposure

function calculatePrice(
	ProductId productId,
	bool increasesLongExposure,
	FPUnsigned openInterestLong,
	FPUnsigned openInterestShort,
	FPUnsigned reserveMultiplier,
	FPUnsigned amount
) public view returns (
	FPUnsigned
)

Parameters

Name	Type	Description
`productId`	ProductId	Product for which to compute price
`increasesLongExposure`	bool	True if increasing long or decreasing short.
`openInterestLong`	FPUnsigned	Total size of all this product's longs
`openInterestShort`	FPUnsigned	Total size of all this product's shorts
`reserveMultiplier`	FPUnsigned	Adjust synthetic slippage by scaling "reserve" before computing slippage.
`amount`	FPUnsigned	Size of this order

Return Values

Name	Type	Description
[0]	FPUnsigned	FPUnsigned Oracle price with slippage

checkAllExposure

Reverts if exchange total open interest or any product remaining net exposure has been exceeded.

function checkAllExposure() public view

checkExposure

Revert if additional position would exceed risk params

function checkExposure(
	ProductId productId,
	FPUnsigned newOpenInterest,
	FPUnsigned amount,
	bool isLong
) public view returns (
	FPUnsigned previousRemainingExposure,
	FPUnsigned maxProductExposure
)

Parameters

Name	Type	Description
`productId`	ProductId	Product affected by position increase
`newOpenInterest`	FPUnsigned	Total open interest (long + short) of the vault after position change
`amount`	FPUnsigned	Amount of additional open interest for this product
`isLong`	bool

Return Values

Name	Type	Description
`previousRemainingExposure`	FPUnsigned	Remaining exposure for this product, before increase
`maxProductExposure`	FPUnsigned

getMaxExposure

function getMaxExposure(
	FPUnsigned productWeight,
	FPUnsigned productExposureMultiplier
) public view returns (
	FPUnsigned maxExposure
)

getMaxSafeWithdrawableMargin

Max margin that can be withdrawn from this position without reverting or liquidating

function getMaxSafeWithdrawableMargin(
	FPSigned fundingPayment,
	struct PositionPtr position,
	FPUnsigned maxLeverage,
	FPUnsigned liquidationThreshold
) public view returns (
	int256
)

Dev note

If positive, removing this much liquidity should not

revert due to exposure/OI limits
revert due to out-of-bounds leverage
result in a liquidatable position

Parameters

Name	Type	Description
`fundingPayment`	FPSigned	Funding payment owed by this position
`position`	struct PositionPtr	Position to be withdrawn from
`maxLeverage`	FPUnsigned	Max leverage of this position's product
`liquidationThreshold`	FPUnsigned	Liquidation threshold for this product, e.g. 0.7

Return Values

Name	Type	Description
[0]	int256	int256 Removable margin (+) or required margin add (-)

computeIncrease

function computeIncrease(
	struct IExchangeDomain.IncreaseState x
) public returns (
	struct IExchangeDomain.IncreaseResult
)

aggregatePosition

Compute position values after incrementing

function aggregatePosition(
	FPUnsigned currentPrice,
	struct PositionPtr prevPosition,
	uint256 margin,
	FPUnsigned size,
	FPSigned funding
) public view returns (
	struct IExchangeDomain.IncreasePreview increase
)

Dev note

Linearly combine two positions into one. At any price or time where neither component would have liquidated or hit the max profit, position should have PnL equal to the sum of the two component PnLs

Parameters

Name	Type	Description
`currentPrice`	FPUnsigned	Current oracle price with slippage
`prevPosition`	struct PositionPtr	Position to modify
`margin`	uint256	margin amount of increase being applied
`size`	FPUnsigned	size of increase being applied
`funding`	FPSigned	Current funding value of position's product

computeDecrease

function computeDecrease(
	struct PositionPtr position,
	uint256 margin,
	FPUnsigned size,
	bool store
) external returns (
	struct IExchangeDomain.DecreasePreview decrease
)

canLiquidate

Liquidation information for a position

function canLiquidate(
	struct PositionPtr position,
	FPUnsigned price
) public returns (
	FPSigned pnl,
	FPSigned funding,
	bool isLiquidatable
)

Parameters

Name	Type	Description
`position`	struct PositionPtr	Stored position to evaluate
`price`	FPUnsigned	Current price of position's product

Return Values

Name	Type	Description
`pnl`	FPSigned	PnL of this position, including funding
`funding`	FPSigned	Accrued funding cost (+) or payment (-)
`isLiquidatable`	bool	Whether PnL has reached the liquidation threshold

updateOpenInterest

Parameters to update OpenInterest

function updateOpenInterest(
	ProductId productId,
	FPUnsigned amount,
	bool isLong,
	bool isIncrease,
	bool store
) public

Parameters

Name	Type	Description
`productId`	ProductId	Product of position being modified
`amount`	FPUnsigned	Change in position size
`isLong`	bool	Whether this is a long position
`isIncrease`	bool	Whether the position is being increased or decreased.
`store`	bool	Where OI is being updated or just calculating preview value

increaseProductTotalPosition

function increaseProductTotalPosition(
	ProductId productId,
	bool isLong,
	uint256 margin,
	FPUnsigned size,
	FPSigned funding,
	FPUnsigned price
) public

decreaseProductTotalPosition

Decrease/delete the total position to incorporate a user decrease

function decreaseProductTotalPosition(
	struct PositionPtr userPosition,
	uint256 margin,
	FPUnsigned deltaSize
) external

Parameters

Name	Type	Description
`userPosition`	struct PositionPtr	Position to stop tracking in productTotalLongs/Shorts
`margin`	uint256	Margin by which this position is decreasing
`deltaSize`	FPUnsigned	Size by which this position is decreasing (0 for decreaseMargin)

updateAndGetFundingPayment

Update this position's product's cumulative funding and interest, and then compute the payment owed by the position.

function updateAndGetFundingPayment(
	ProductId productId,
	bool isLong,
	FPUnsigned size,
	FPSigned funding
) public returns (
	FPSigned fundingPayment
)

Dev note

Integrates current funding rate over time between last update and now. See FundingManager.

Parameters

Name	Type	Description
`productId`	ProductId	productId of Position that owes (or is owed) a payment
`isLong`	bool	isLong of Position that owes (or is owed) a payment
`size`	FPUnsigned	size of Position that owes (or is owed) a payment
`funding`	FPSigned	funding of Position that owes (or is owed) a payment

Return Values

Name	Type	Description
`fundingPayment`	FPSigned	Debt owed by this position. Negative values increase position value.

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
) public view returns (
	bool
)

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
[0]	bool	canTakeProfit 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 size,
	FPUnsigned price
) public 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
`size`	FPUnsigned	Size (margin * leverage) of the position
`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 size,
	FPSigned funding,
	FPSigned cumulativeFunding,
	FPUnsigned cumulativeInterest
) public pure returns (
	FPSigned fundingPayment
)

Parameters

Name	Type	Description
`isLong`	bool	Whether this position is long (false=short)
`size`	FPUnsigned	Size (margin * leverage) of the position
`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(
	FPUnsigned size,
	FPUnsigned productFee,
	address user,
	address sender
) public view returns (
	uint256 tradeFee
)

Parameters

Name	Type	Description
`size`	FPUnsigned	Total size of the increase/decrease
`productFee`	FPUnsigned	Product's normal trade fee rate
`user`	address	Owner of the position
`sender`	address	Sender of the transaction

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
) public 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 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
) public 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

canLiquidateBulk

Liquidation information for each position in positionIds

function canLiquidateBulk(
	PositionId[] positionIds
) public returns (
	FPSigned[] pnl,
	FPSigned[] funding,
	bool[] isLiquidatable
)

Parameters

Name	Type	Description
`positionIds`	PositionId[]	Positions to compute liquidation info for

Return Values

Name	Type	Description
`pnl`	FPSigned[]	Position PnL. See `getPositionPnlAndFunding`
`funding`	FPSigned[]	Position funding. See `getPositionPnlAndFunding`
`isLiquidatable`	bool[]	Whether this position is liquidatable

getPositionPnlAndFunding

function getPositionPnlAndFunding(
	ProductId productId,
	bool isLong,
	FPUnsigned size,
	FPUnsigned positionPrice,
	uint256 margin,
	FPSigned funding,
	FPUnsigned price
) public returns (
	FPSigned pnl,
	FPSigned fundingDebt
)

getPositionPnlRate

function getPositionPnlRate(PositionId positionId) public returns (FPSigned pnlRate)

getTotalPnl

function getTotalPnl() external returns (FPSigned totalPnl)

validateOI

function validateOI(uint256 balance) external view

canRemove

function canRemove(PositionId positionId) public returns (bool canRemove_, int256 removeableMargin)