IDomFiPerp
Addresses
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
)
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
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
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
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)
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
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.