IDomFiPerp

IDomFiPerp

Addresses

Chain	Address

Functions

previewIncrease

Preview results of an increase

function previewIncrease(
    address user,
    PositionLabel positionLabel,
    bytes32 productId,
    uint256 margin,
    bool isLong,
    FPUnsigned leverage
) external returns (
    struct IDomFiPerp.IncreasePreview increasePreview
)

Dev note

May revert if the increase would revert.

Parameters

Name	Type	Description
user	address	Owner of the position
positionLabel	PositionLabel	User-defined label of the position
productId	bytes32	Product for this position. Required for new positions; ignored ONLY if modifying an existing position.
margin	uint256	Collateral added to the position by the increase
isLong	bool	Whether position is long. Required for new positions; ignored ONLY if modifying an existing position.
leverage	FPUnsigned	Leverage at which margin will be added to the position

Return Values

Name	Type	Description
increasePreview	struct IDomFiPerp.IncreasePreview	Computed IncreasePreview for the position

previewDecrease

Preview results of a decrease

function previewDecrease(
    PositionId positionId,
    uint256 decreaseMargin
) external returns (
    struct IDomFiPerp.DecreasePreview decreasePreview
)

Parameters

Name	Type	Description
positionId	PositionId	Global ID of position to be decreased. Must exist.
decreaseMargin	uint256	Margin amount to decrease by. May be greater than position margin

Return Values

Name	Type	Description
decreasePreview	struct IDomFiPerp.DecreasePreview	Computed DecreasePreview for the position

increasePosition

Increase (or create) a position.

function increasePosition(
    address user,
    PositionLabel positionLabel,
    bytes32 productId,
    uint256 margin,
    bool isLong,
    FPUnsigned leverage
) external

Parameters

Name	Type	Description
user	address	Owner of the position. msg.sender must be user or their manager.
positionLabel	PositionLabel	User-defined ID of position to increase or create. See getPositionId().
productId	bytes32	Product of this position. Ignored in favor of stored value if position already exists.
margin	uint256	Margin to increase this position by.
isLong	bool	Direction of this position. Ignored in favor of stored value if position already exists.
leverage	FPUnsigned	Leverage of this increase's margin. After increase, resulting position must have valid leverage.

removeMargin

Remove margin from a position (increasing leverage). Caller must be the position's owner or their manager.

function removeMargin(PositionId positionId, uint256 marginToRemove, address recipient) external

Dev note

Reverts if

• resulting position is liquidatable
• resulting position has leverage<1 or leverage>product.maxLeverage
• resulting position has margin < minMargin
• removeMargin > position.margin

Parameters

Name	Type	Description
positionId	PositionId	Position to remove margin from
marginToRemove	uint256	Collateral to remove from margin
recipient	address	Send removed collateral to this address

canRemove

Whether a position can have margin withdrawn without liquidation or overleverage, and if so how much. See removeMargin().

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

Parameters

Name	Type	Description
positionId	PositionId	Global ID of Position to check

Return Values

Name	Type	Description
canRemove_	bool	Whether it has margin available to withdraw
removeableMargin	int256	Available removal. Negative if !canRemove_

decreasePositions

Decrease (or close) multiple positions simultaneously. Fails unless all succeed.

function decreasePositions(struct IDomFiPerp.DecreasePositionParams[] params) external

Parameters

Name	Type	Description
params	struct IDomFiPerp.DecreasePositionParams[]	List of decreases. See DecreasePositionParams

decreasePositionWithId

Decrease (or close) a position, and claim proportional share of position margin + PnL. Unlike removing margin, leverage remains the same.

function decreasePositionWithId(PositionId positionId, uint256 margin, address recipient) external

Dev note

If margin >= position.margin, close position.

Parameters

Name	Type	Description
positionId	PositionId	Target position. msg.sender must be its owner or their manager.
margin	uint256	Margin units to decrease
recipient	address	Where to send reclaimed share of position value + PnL

getProduct

Get product details. See Product.

function getProduct(bytes32 productId) external view returns (struct IDomFiPerp.Product product)

Parameters

Name	Type	Description
productId	bytes32	ID of this product

Return Values

Name	Type	Description
product	struct IDomFiPerp.Product	Saved parameters for this product

getPosition

Get details of a position. See Position.

function getPosition(PositionId globalPositionId) external view returns (struct IDomFiPerp.Position position)

Parameters

Name	Type	Description
globalPositionId	PositionId	Global position ID

Return Values

Name	Type	Description
position	struct IDomFiPerp.Position	Saved position

getPosition

Get details of a user position. See Position.

function getPosition(
    address account,
    PositionLabel positionLabel
) external view returns (
    struct IDomFiPerp.Position position
)

Parameters

Name	Type	Description
account	address	Owner of the position
positionLabel	PositionLabel	User-defined label for this position

Return Values

Name	Type	Description
position	struct IDomFiPerp.Position	Saved position

getPositionId

Compute the global position ID of a user's position

function getPositionId(
    address account,
    PositionLabel positionLabel
) external view returns (
    PositionId positionId
)

Parameters

Name	Type	Description
account	address	owner of this position
positionLabel	PositionLabel	User-defined label for this position

Return Values

Name	Type	Description
positionId	PositionId	Globally unique position ID

getMaxExposure

Get max exposure for a product: the highest permitted value of |long open interest - short open interest|

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

Parameters

Name	Type	Description
productWeight	FPUnsigned	product.weight; determines vault balance allocated to this product
productExposureMultiplier	FPUnsigned	multiple of product's vault share allowed for exposure

Return Values

Name	Type	Description
maxExposure	FPUnsigned	permitted max exposure

isManagerFor

Whether manager is a registered manager approved by account .

function isManagerFor(address manager, address account) external returns (bool isManager)

Parameters

Name	Type	Description
manager	address	Possible manager (for instance, an OrderBook)
account	address	User that may have approved manager

Return Values

Name	Type	Description
isManager	bool	Whether manager is a registered manager approved by account .

validateOI

Revert if balance times utilizationMultiplier is less than OI

function validateOI(uint256 balance) external view

Dev note

Triggers after each transfer of DOMD

Parameters

Name	Type	Description
balance	uint256	Balance of DomFiVault

asset

Collateral token of this perp, e.g. USDC or wETH

function asset() external view returns (contract IERC20)

Return Values

Name	Type	Description
[0]	contract IERC20	assetToken Address of token

getPositionPnlAndFunding

Get the Pnl of a position, including funding

function getPositionPnlAndFunding(
    bytes32 productId,
    bool isLong,
    FPUnsigned leverage,
    FPUnsigned positionPrice,
    uint256 margin,
    FPSigned funding,
    FPUnsigned price
) external returns (
    FPSigned pnl,
    FPSigned fundingDebt
)

Parameters

Name	Type	Description
productId	bytes32	productId of position to evaluate
isLong	bool	isLong of position to evaluate
leverage	FPUnsigned	leverage of position to evaluate
positionPrice	FPUnsigned	price of position to evaluate
margin	uint256	margin of position to evaluate
funding	FPSigned	funding of position to evaluate
price	FPUnsigned	Current price of the position's product

Return Values

Name	Type	Description
pnl	FPSigned	Increase in position value since creation, minus funding
fundingDebt	FPSigned	Accrued funding (and interest) which was subtracted from this position's PnL. A positive value reduces position value.

getPositionPnlRate

Compute the current PnL rate (PnL / margin) of a position at the most recent price.

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

Parameters

Name	Type	Description
positionId	PositionId	Globally-unique ID of the position in question

Return Values

Name	Type	Description
pnlRate	FPSigned	PnL rate of this position. 100% = 1.0

totalOpenInterest

total size (margin * leverage) of all outstanding positions in token wei

function totalOpenInterest() external view returns (FPUnsigned)

fundingManager

function fundingManager() external view returns (contract IFundingManager)

getTotalPnl

Compute total trader PnL across all positions, ignoring maxPositionProfit

function getTotalPnl() external returns (FPSigned)

Dev note

Used for withdraw delays. Computed with composite positions.

Return Values

Name	Type	Description
[0]	FPSigned	totalPnl Sum of all position PnLs if there was no maxPositionProfit

updatePrice

Emit a PriceUpdate event for easy off-chain data access

function updatePrice(bytes32 productId, FPUnsigned value, uint64 timestamp, address oracle) external

Dev note

This allows order bots to get price events without tracking oracle changes.

Parameters

Name	Type	Description
productId	bytes32	ID of product with price update
value	FPUnsigned	New price
timestamp	uint64	Timestamp at which price was generated
oracle	address	Source of price update

Events

ProductAdded

event ProductAdded(bytes32 productId, struct IDomFiPerp.Product product)

ProductUpdated

event ProductUpdated(bytes32 productId, struct IDomFiPerp.Product product)

OwnerUpdated

event OwnerUpdated(address newOwner)

GuardianUpdated

event GuardianUpdated(address newGuardian)

GovUpdated

event GovUpdated(address newGov)

IncreasePosition

An event emitted when a position is increased in size.

event IncreasePosition(
    PositionId positionId,
    address user,
    bytes32 productId,
    uint256 fee,
    FPUnsigned executionPrice,
    struct IDomFiPerp.Position position
)

Parameters

Name	Type	Description
positionId	PositionId	The position ID.
user	address	The position's owner.
productId	bytes32	The position's product ID.
fee	uint256	The fee incurred to increase the position.
executionPrice	FPUnsigned	The price used, after slippage
position	struct IDomFiPerp.Position	The position after the increase size.

DecreasePosition

An event emitted when a position is decreased in size.

event DecreasePosition(
    PositionId positionId,
    address user,
    bytes32 productId,
    bool didClose,
    bool didLiquidate,
    uint256 fee,
    int256 netPnl,
    FPUnsigned exitPrice,
    struct IDomFiPerp.Position position
)

Parameters

Name	Type	Description
positionId	PositionId	The position ID.
user	address	The position's owner.
productId	bytes32	The position's product ID.
didClose	bool	true if the position was full closed.
didLiquidate	bool	true if the position was liquidated.
fee	uint256	The fee incurred to decrease the position.
netPnl	int256	The net PnL of the position.
exitPrice	FPUnsigned	The exit price of the partial or full position decrease.
position	struct IDomFiPerp.Position	The position after the partial decrease. In the case of a full decrease, the position will have the last margin amount for the sake of easily identifying the position size before it was fully closed.

RemoveMargin

An event emitted when a position's margin is removed to increase leverage.

event RemoveMargin(
    PositionId positionId,
    address user,
    uint256 oldMargin,
    FPUnsigned oldLeverage,
    struct IDomFiPerp.Position position
)

Parameters

Name	Type	Description
positionId	PositionId	The position ID.
user	address	The position's owner.
oldMargin	uint256	The previous margin amount.
oldLeverage	FPUnsigned	The previous position leverage.
position	struct IDomFiPerp.Position	The position after margin removed.

PositionLiquidated

An event emitted when a position is liquidated.

event PositionLiquidated(
    PositionId positionId,
    address liquidator,
    uint256 liquidatorReward,
    uint256 remainingReward,
    struct IDomFiPerp.Position position
)

Parameters

Name	Type	Description
positionId	PositionId	The position ID.
liquidator	address	The address of the liquidator.
liquidatorReward	uint256	The reward given to the liquidator denominated in the position's collateral token.
remainingReward	uint256	The remaining reward from the liquidated position denominated in the position's collateral token.
position	struct IDomFiPerp.Position	The position before liquidation.

Types

Position

Fields

Name	Type	Description
owner	address
productId	bytes32
margin	uint256	collateral provided for this position
leverage	FPUnsigned
price	FPUnsigned	price when position was increased. weighted average by size
funding	FPSigned	funding + interest when position was last increased
positionLabel	PositionLabel
timestamp	uint64	last position increase
isLong	bool

struct Position {
  address owner;
  bytes32 productId;
  uint256 margin;
  FPUnsigned leverage;
  FPUnsigned price;
  FPSigned funding;
  PositionLabel positionLabel;
  uint64 timestamp;
  bool isLong;
}

ProductParams

Parameters to create a new Product. Does not include OI state variables.

struct ProductParams {
  bytes32 productId;
  FPUnsigned maxLeverage;
  FPUnsigned fee;
  bool isActive;
  FPUnsigned minPriceChange;
  FPUnsigned weight;
  FPUnsigned reserveMultiplier;
  FPUnsigned exposureMultiplier;
  FPUnsigned liquidationThreshold;
  FPUnsigned liquidationBounty;
  FPUnsigned fundingExponent;
}

Product

A product against which positions can be opened, e.g. Bitcoin dominance

Fields

Name	Type	Description
productId	bytes32	Globally unique productID, e.g. formatBytes32String("BTCDOM")
maxLeverage	FPUnsigned	Max leverage for positions on this product, e.g. 3x
fee	FPUnsigned	Fraction of (margin*leverage) taken as a fee for position size changes, e.g. 0.0001
isActive	bool	Whether positions can be opened and increased on this product
openInterestLong	FPUnsigned	Sum of (margin*leverage) for all open longs
openInterestShort	FPUnsigned	Sum of (margin*leverage) for all open shorts
minPriceChange	FPUnsigned	Min oracle increase % for trader to close with profit before minProfitTime
weight	FPUnsigned	Weight with which to allocate global max exposure between products
reserveMultiplier	FPUnsigned	Virtual reserve used to calculate slippage. See DomFiPerp.calculatePrice()
exposureMultiplier	FPUnsigned	Product exposure is limited to exposureMultiplier * its share of global max exposure
liquidationThreshold	FPUnsigned	Liquidate positions if losses exceed liquidationThreshold * margin
liquidationBounty	FPUnsigned	Reward liquidations with liquidationBounty * remaining margin
fundingExponent	FPUnsigned	An exponential scaling factor for funding rate

struct Product {
  bytes32 productId;
  FPUnsigned maxLeverage;
  FPUnsigned fee;
  bool isActive;
  FPUnsigned openInterestLong;
  FPUnsigned openInterestShort;
  FPUnsigned minPriceChange;
  FPUnsigned weight;
  FPUnsigned reserveMultiplier;
  FPUnsigned exposureMultiplier;
  FPUnsigned liquidationThreshold;
  FPUnsigned liquidationBounty;
  FPUnsigned fundingExponent;
}

IncreasePositionParams

Parameters for a request to increase (or create) a position

Fields

Name	Type	Description
user	address	Owner of the position. msg.sender must be user or their manager
positionLabel	PositionLabel	user-defined ID of position to increase or create. See getPositionId()
productId	bytes32	product of this position
margin	uint256	margin to increase this position by
isLong	bool	direction of this position
leverage	FPUnsigned	leverage of this increase's margin. After increase, resulting position must have valid leverage.

struct IncreasePositionParams {
  address user;
  PositionLabel positionLabel;
  bytes32 productId;
  uint256 margin;
  bool isLong;
  FPUnsigned leverage;
}

DecreasePositionParams

Parameters for a request to decrease (or close) a position

Fields

Name	Type	Description
user	address	Owner of this position. msg.sender must be user or their manager
positionLabel	PositionLabel	user-defined ID of position to decrease/close. See getPositionId()
margin	uint256	amount of margin to decrease. Leverage remains the same
recipient	address	Where to send margin and any accompanying PnL

struct DecreasePositionParams {
  address user;
  PositionLabel positionLabel;
  uint256 margin;
  address recipient;
}

IncreasePreview

Preview result of an increasePosition call

Fields

Name	Type	Description
funding	FPSigned	Funding of new position (weighted mean) @custom:executionPrice Slippage-adjusted price at which the increase would execute
price	FPUnsigned	Total price of new position (weighted harmonic mean)
executionPrice	FPUnsigned
leverage	FPUnsigned	Leverage of new position (total size / total margin)
margin	uint256	Margin of new position (prev + increase)

struct IncreasePreview {
  FPSigned funding;
  FPUnsigned price;
  FPUnsigned executionPrice;
  FPUnsigned leverage;
  uint256 margin;
}

DecreasePreview

Preview result of a decreasePosition call

Fields

Name	Type	Description
price	FPUnsigned	execution price of this decrease
totalFee	uint256	trade fee paid by this decrease
margin	uint256	actual decrease in margin
netPnl	int256	PnL realized by this decrease, minus fees
isFullClose	bool	Whether this decrease completely closed the position
isLiquidatable	bool	Whether the position was liquidatable

struct DecreasePreview {
  FPUnsigned price;
  uint256 totalFee;
  uint256 margin;
  int256 netPnl;
  bool isFullClose;
  bool isLiquidatable;
}

PositionId

bytes32 globally-unique ID of a position. See getPositionId.

PositionLabel

bytes16 arbitrary user label for a position.