TradingCommonUtils

External library for helper functions commonly used in many places

getPnlPercent

function getPnlPercent(uint64 _openPrice, uint64 _currentPrice, bool _long, uint24 _leverage) public pure returns (int256 p)

Returns the current percent profit of a trade (1e10 precision)

Parameters

Name	Type	Description
_openPrice	uint64	trade open price (1e10 precision)
_currentPrice	uint64	trade current price (1e10 precision)
_long	bool	true for long, false for short
_leverage	uint24	trade leverage (1e3 precision)

getPositionSizeCollateral

function getPositionSizeCollateral(uint120 _collateralAmount, uint24 _leverage) public pure returns (uint256)

Returns position size of trade in collateral tokens (avoids overflow from uint120 collateralAmount)

Parameters

Name	Type	Description
_collateralAmount	uint120	collateral of trade
_leverage	uint24	leverage of trade (1e3)

getMarketExecutionPrice

function getMarketExecutionPrice(uint256 _price, uint256 _spreadP, bool _long, bool _open, enum ITradingStorage.ContractsVersion _contractsVersion) public pure returns (uint256)

Calculates market execution price for a trade (1e10 precision)

Parameters

Name	Type	Description
_price	uint256	price of the asset (1e10)
_spreadP	uint256	spread percentage (1e10)
_long	bool	true if long, false if short
_open	bool
_contractsVersion	enum ITradingStorage.ContractsVersion

convertCollateralToUsd

function convertCollateralToUsd(uint256 _collateralAmount, uint128 _collateralPrecisionDelta, uint256 _collateralPriceUsd) public pure returns (uint256)

Converts collateral value to USD (1e18 precision)

Parameters

Name	Type	Description
_collateralAmount	uint256	amount of collateral (collateral precision)
_collateralPrecisionDelta	uint128	precision delta of collateral (10^18/10^decimals)
_collateralPriceUsd	uint256	price of collateral in USD (1e8)

convertCollateralToGns

function convertCollateralToGns(uint256 _collateralAmount, uint128 _collateralPrecisionDelta, uint256 _gnsPriceCollateral) internal pure returns (uint256)

Converts collateral value to GNS (1e18 precision)

Parameters

Name	Type	Description
_collateralAmount	uint256	amount of collateral (collateral precision)
_collateralPrecisionDelta	uint128	precision delta of collateral (10^18/10^decimals)
_gnsPriceCollateral	uint256	price of GNS in collateral (1e10)

getTradeValuePure

function getTradeValuePure(uint256 _collateral, int256 _percentProfit, uint256 _feesCollateral, uint128 _collateralPrecisionDelta) public pure returns (uint256)

Calculates trade value (useful when closing a trade) Important: does not calculate if trade can be liquidated or not, has to be done by calling function

Parameters

Name	Type	Description
_collateral	uint256	amount of collateral (collateral precision)
_percentProfit	int256	profit percentage (1e10)
_feesCollateral	uint256	borrowing fee + closing fee in collateral tokens (collateral precision)
_collateralPrecisionDelta	uint128	precision delta of collateral (10^18/10^decimals)

getLiqPnlThresholdP

function getLiqPnlThresholdP(struct IPairsStorage.GroupLiquidationParams _params, uint256 _leverage) public pure returns (uint256)

Pure function that returns the liquidation pnl % threshold for a trade (1e10)

Parameters

Name	Type	Description
_params	IPairsStorage.GroupLiquidationParams	trade liquidation params
_leverage	uint256	trade leverage (1e3 precision)

getMinPositionSizeCollateral

function getMinPositionSizeCollateral(uint8 _collateralIndex, uint256 _pairIndex) public view returns (uint256)

Returns minimum position size in collateral tokens for a pair (collateral precision)

Parameters

Name	Type	Description
_collateralIndex	uint8	collateral index
_pairIndex	uint256	pair index

getPositionSizeCollateralBasis

function getPositionSizeCollateralBasis(uint8 _collateralIndex, uint256 _pairIndex, uint256 _positionSizeCollateral) public view returns (uint256)

Returns position size to use when charging fees

Parameters

Name	Type	Description
_collateralIndex	uint8	collateral index
_pairIndex	uint256	pair index
_positionSizeCollateral	uint256	trade position size in collateral tokens (collateral precision)

isWithinExposureLimits

function isWithinExposureLimits(uint8 _collateralIndex, uint16 _pairIndex, bool _long, uint256 _positionSizeCollateralDelta) external view returns (bool)

Checks if total position size is not higher than maximum allowed open interest for a pair

Parameters

Name	Type	Description
_collateralIndex	uint8	index of collateral
_pairIndex	uint16	index of pair
_long	bool	true if long, false if short
_positionSizeCollateralDelta	uint256	position size delta in collateral tokens (collateral precision)

getTradeBorrowingFeeCollateral

function getTradeBorrowingFeeCollateral(struct ITradingStorage.Trade _trade) public view returns (uint256)

Convenient wrapper to return trade borrowing fee in collateral tokens (collateral precision)

Parameters

Name	Type	Description
_trade	ITradingStorage.Trade	trade input

getTradeLiquidationPrice

function getTradeLiquidationPrice(struct ITradingStorage.Trade _trade, bool _useBorrowingFees) public view returns (uint256)

Convenient wrapper to return trade liquidation price (1e10)

Parameters

Name	Type	Description
_trade	ITradingStorage.Trade	trade input
_useBorrowingFees	bool

getTradeValueCollateral

function getTradeValueCollateral(struct ITradingStorage.Trade _trade, int256 _percentProfit, uint256 _closingFeesCollateral, uint128 _collateralPrecisionDelta) public view returns (uint256 valueCollateral, uint256 borrowingFeesCollateral)

Returns trade value and borrowing fee in collateral tokens

Parameters

Name	Type	Description
_trade	ITradingStorage.Trade	trade data
_percentProfit	int256	profit percentage (1e10)
_closingFeesCollateral	uint256	closing fees in collateral tokens (collateral precision)
_collateralPrecisionDelta	uint128	precision delta of collateral (10^18/10^decimals)

getTradeOpeningPriceImpact

function getTradeOpeningPriceImpact(struct ITradingCommonUtils.TradePriceImpactInput _input, enum ITradingStorage.ContractsVersion _contractsVersion) external view returns (uint256 priceImpactP, uint256 priceAfterImpact)

Returns price impact % (1e10), price after spread and impact (1e10)

Parameters

Name	Type	Description
_input	ITradingCommonUtils.TradePriceImpactInput	input data
_contractsVersion	enum ITradingStorage.ContractsVersion	contracts version

getTradeClosingPriceImpact

function getTradeClosingPriceImpact(struct ITradingCommonUtils.TradePriceImpactInput _input) external view returns (uint256 priceImpactP, uint256 priceAfterImpact, uint256 tradeValueCollateralNoFactor)

Returns price impact % (1e10), price after spread and impact (1e10), and trade value used to know if pnl is positive (collateral precision)

Parameters

Name	Type	Description
_input	ITradingCommonUtils.TradePriceImpactInput	input data

getTradeLiqPnlThresholdP

function getTradeLiqPnlThresholdP(struct ITradingStorage.Trade _trade) public view returns (uint256)

Returns a trade's liquidation threshold % (1e10)

Parameters

Name	Type	Description
_trade	ITradingStorage.Trade	trade struct

getTotalTradeFeesCollateral

function getTotalTradeFeesCollateral(uint8 _collateralIndex, address _trader, uint16 _pairIndex, uint256 _positionSizeCollateral) public view returns (uint256)

Returns all fees for a trade in collateral tokens

Parameters

Name	Type	Description
_collateralIndex	uint8	collateral index
_trader	address	address of trader
_pairIndex	uint16	index of pair
_positionSizeCollateral	uint256	position size in collateral tokens (collateral precision)

getTradeFeesCollateral

function getTradeFeesCollateral(uint8 _collateralIndex, address _trader, uint16 _pairIndex, uint256 _collateralAmount, uint256 _positionSizeCollateral, enum ITradingStorage.PendingOrderType _orderType) public view returns (struct IPairsStorage.TradeFees tradeFees)

Returns all fees for a trade in collateral tokens

Parameters

Name	Type	Description
_collateralIndex	uint8	collateral index
_trader	address	address of trader
_pairIndex	uint16	index of pair
_collateralAmount	uint256	trade collateral amount (collateral precision)
_positionSizeCollateral	uint256	trade position size in collateral tokens (collateral precision)
_orderType	enum ITradingStorage.PendingOrderType	corresponding order type

getMinGovFeeCollateral

function getMinGovFeeCollateral(uint8 _collateralIndex, address _trader, uint16 _pairIndex) public view returns (uint256)

revertIfTradeHasPendingMarketOrder

function revertIfTradeHasPendingMarketOrder(address _user, uint32 _index) public view

Reverts if user initiated any kind of pending market order on his trade

Parameters

Name	Type	Description
_user	address	trade user
_index	uint32	trade index

getGToken

function getGToken(uint8 _collateralIndex) public view returns (contract IGToken)

Returns gToken contract for a collateral index

Parameters

Name	Type	Description
_collateralIndex	uint8	collateral index

transferCollateralFrom

function transferCollateralFrom(uint8 _collateralIndex, address _from, uint256 _amountCollateral) public

Transfers collateral from trader

Parameters

Name	Type	Description
_collateralIndex	uint8	index of the collateral
_from	address	sending address
_amountCollateral	uint256	amount of collateral to receive (collateral precision)

transferCollateralTo

function transferCollateralTo(uint8 _collateralIndex, address _to, uint256 _amountCollateral) internal

Transfers collateral to trader

Parameters

Name	Type	Description
_collateralIndex	uint8	index of the collateral
_to	address	receiving address
_amountCollateral	uint256	amount of collateral to transfer (collateral precision)

transferGnsTo

function transferGnsTo(address _to, uint256 _amountGns) internal

Transfers GNS to address

Parameters

Name	Type	Description
_to	address	receiving address
_amountGns	uint256	amount of GNS to transfer (1e18)

transferGnsFrom

function transferGnsFrom(address _from, uint256 _amountGns) internal

Transfers GNS from address

Parameters

Name	Type	Description
_from	address	sending address
_amountGns	uint256	amount of GNS to receive (1e18)

sendCollateralToVault

function sendCollateralToVault(uint8 _collateralIndex, uint256 _amountCollateral, address _trader) public

Sends collateral to gToken vault for negative pnl

Parameters

Name	Type	Description
_collateralIndex	uint8	collateral index
_amountCollateral	uint256	amount of collateral to send to vault (collateral precision)
_trader	address	trader address

handleTradePnl

function handleTradePnl(struct ITradingStorage.Trade _trade, int256 _collateralSentToTrader, int256 _availableCollateralInDiamond, uint256 _borrowingFeeCollateral) external returns (uint256 traderDebt)

Handles pnl transfers when (fully or partially) closing a trade

Parameters

Name	Type	Description
_trade	ITradingStorage.Trade	trade struct
_collateralSentToTrader	int256	total amount to send to trader (collateral precision)
_availableCollateralInDiamond	int256	part of _collateralSentToTrader available in diamond balance (collateral precision)
_borrowingFeeCollateral	uint256

updateFeeTierPoints

function updateFeeTierPoints(uint8 _collateralIndex, address _trader, uint256 _pairIndex, uint256 _positionSizeCollateral) public

Updates a trader's fee tiers points based on his trade size

Parameters

Name	Type	Description
_collateralIndex	uint8	collateral index
_trader	address	address of trader
_pairIndex	uint256	index of pair
_positionSizeCollateral	uint256	position size in collateral tokens (collateral precision)

distributeVaultFeeCollateral

function distributeVaultFeeCollateral(uint8 _collateralIndex, address _trader, uint256 _valueCollateral) public

Distributes fee to gToken vault

Parameters

Name	Type	Description
_collateralIndex	uint8	index of collateral
_trader	address	address of trader
_valueCollateral	uint256	fee in collateral tokens (collateral precision)

distributeExactGovFeeCollateral

function distributeExactGovFeeCollateral(uint8 _collateralIndex, address _trader, uint256 _govFeeCollateral) public

Distributes gov fees exact amount

Parameters

Name	Type	Description
_collateralIndex	uint8	index of collateral
_trader	address	address of trader
_govFeeCollateral	uint256	position size in collateral tokens (collateral precision)

distributeGnsOtcFeeCollateral

function distributeGnsOtcFeeCollateral(uint8 _collateralIndex, address _trader, uint256 _amountCollateral) public

Increases OTC balance to be distributed once OTC is executed

Parameters

Name	Type	Description
_collateralIndex	uint8	collateral index
_trader	address	trader address
_amountCollateral	uint256	amount of collateral tokens to distribute (collateral precision)

distributeTriggerFeeGns

function distributeTriggerFeeGns(address _trader, uint8 _collateralIndex, uint256 _triggerFeeCollateral, uint256 _gnsPriceCollateral, uint128 _collateralPrecisionDelta) public

Distributes trigger fee in GNS tokens

Parameters

Name	Type	Description
_trader	address	address of trader
_collateralIndex	uint8	index of collateral
_triggerFeeCollateral	uint256	trigger fee in collateral tokens (collateral precision)
_gnsPriceCollateral	uint256	gns/collateral price (1e10 precision)
_collateralPrecisionDelta	uint128	collateral precision delta (10^18/10^decimals)

processFees

function processFees(struct ITradingStorage.Trade _trade, uint256 _positionSizeCollateral, enum ITradingStorage.PendingOrderType _orderType) external returns (uint256)

Distributes opening fees for trade and returns the trade fees charged in collateral tokens

Parameters

Name	Type	Description
_trade	ITradingStorage.Trade	trade struct
_positionSizeCollateral	uint256	position size in collateral tokens (collateral precision)
_orderType	enum ITradingStorage.PendingOrderType	trade order type

distributeReferralFeeCollateral

function distributeReferralFeeCollateral(uint8 _collateralIndex, address _trader, uint256 _positionSizeCollateral, uint256 _referralFeeCollateral, uint256 _gnsPriceCollateral) public

Distributes referral rewards and returns the amount charged in collateral tokens

Parameters

Name	Type	Description
_collateralIndex	uint8	collateral index
_trader	address	address of trader
_positionSizeCollateral	uint256	position size in collateral tokens (collateral precision)
_referralFeeCollateral	uint256	referral fee in collateral tokens (collateral precision)
_gnsPriceCollateral	uint256	gns/collateral price (1e10 precision)

updateOi

function updateOi(struct ITradingStorage.Trade _trade, uint256 _positionSizeCollateral, bool _open, bool _isPnlPositive) public

_Update protocol open interest (any amount) CAREFUL: this will reset the trade's borrowing fees to 0 when open = true

Parameters

Name	Type	Description
_trade	ITradingStorage.Trade	trade struct
_positionSizeCollateral	uint256	position size in collateral tokens (collateral precision)
_open	bool	whether it corresponds to a trade opening or closing
_isPnlPositive	bool	whether it corresponds to a positive pnl trade (only relevant when _open = false)

updateOiTrade

function updateOiTrade(struct ITradingStorage.Trade _trade, bool _open, bool _isPnlPositive) external

_Update protocol open interest (trade position size) CAREFUL: this will reset the trade's borrowing fees to 0 when open = true

Parameters

Name	Type	Description
_trade	ITradingStorage.Trade	trade struct
_open	bool	whether it corresponds to a trade opening or closing
_isPnlPositive	bool	whether it corresponds to a positive pnl trade (only relevant when _open = false)

handleOiDelta

function handleOiDelta(struct ITradingStorage.Trade _trade, uint256 _newPositionSizeCollateral, bool _isPnlPositive) external

Handles OI delta for an existing trade (for trade updates)

Parameters

Name	Type	Description
_trade	ITradingStorage.Trade	trade struct
_newPositionSizeCollateral	uint256	new position size in collateral tokens (collateral precision)
_isPnlPositive	bool	whether it corresponds to a positive pnl trade (only relevant when closing)

_getMultiCollatDiamond

function _getMultiCollatDiamond() internal view returns (contract IGNSMultiCollatDiamond)

Returns current address as multi-collateral diamond interface to call other facets functions.