# TradingCommonUtils

*External library for helper functions commonly used in many places*

## getPnlPercent

```solidity
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

```solidity
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

```solidity
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

```solidity
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

```solidity
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

```solidity
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

```solidity
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](/developer/technical-reference/contracts/interfaces/types/ipairsstorage.md#groupliquidationparams) | trade liquidation params       |
| \_leverage | uint256                                                                                                                                   | trade leverage (1e3 precision) |

## getMinPositionSizeCollateral

```solidity
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

```solidity
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

```solidity
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

```solidity
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](/developer/technical-reference/contracts/interfaces/types/itradingstorage.md#trade) | trade input |

## getTradeLiquidationPrice

```solidity
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](/developer/technical-reference/contracts/interfaces/types/itradingstorage.md#trade) | trade input |
| \_useBorrowingFees | bool                                                                                                        |             |

## getTradeValueCollateral

```solidity
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](/developer/technical-reference/contracts/interfaces/types/itradingstorage.md#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

```solidity
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](/developer/technical-reference/contracts/interfaces/libraries/itradingcommonutils.md#tradepriceimpactinput) | input data        |
| \_contractsVersion | enum ITradingStorage.ContractsVersion                                                                                                                   | contracts version |

## getTradeClosingPriceImpact

```solidity
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](/developer/technical-reference/contracts/interfaces/libraries/itradingcommonutils.md#tradepriceimpactinput) | input data  |

## getTradeLiqPnlThresholdP

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

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

### Parameters

| Name    | Type                                                                                                        | Description  |
| ------- | ----------------------------------------------------------------------------------------------------------- | ------------ |
| \_trade | [ITradingStorage.Trade](/developer/technical-reference/contracts/interfaces/types/itradingstorage.md#trade) | trade struct |

## getTotalTradeFeesCollateral

```solidity
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

```solidity
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

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

## revertIfTradeHasPendingMarketOrder

```solidity
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

```solidity
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

```solidity
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

```solidity
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

```solidity
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

```solidity
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

```solidity
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

```solidity
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](/developer/technical-reference/contracts/interfaces/types/itradingstorage.md#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

```solidity
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

```solidity
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

```solidity
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

```solidity
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

```solidity
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

```solidity
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](/developer/technical-reference/contracts/interfaces/types/itradingstorage.md#trade) | trade struct                                              |
| \_positionSizeCollateral | uint256                                                                                                     | position size in collateral tokens (collateral precision) |
| \_orderType              | enum ITradingStorage.PendingOrderType                                                                       | trade order type                                          |

## distributeReferralFeeCollateral

```solidity
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

```solidity
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](/developer/technical-reference/contracts/interfaces/types/itradingstorage.md#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

```solidity
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](/developer/technical-reference/contracts/interfaces/types/itradingstorage.md#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

```solidity
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](/developer/technical-reference/contracts/interfaces/types/itradingstorage.md#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

```solidity
function _getMultiCollatDiamond() internal view returns (contract IGNSMultiCollatDiamond)
```

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gains.trade/developer/technical-reference/contracts/libraries/tradingcommonutils.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.