> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gains.trade/llms.txt
> Use this file to discover all available pages before exploring further.

# TradingCommonUtils

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

## getPnlPercent

```solidity theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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#groupliquidationparams) | trade liquidation params       |
| \_leverage | uint256                                                                                                                                | trade leverage (1e3 precision) |

## getMinPositionSizeCollateral

```solidity theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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#trade) | trade input |

## getTradeLiquidationPrice

```solidity theme={null}
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#trade) | trade input |
| \_useBorrowingFees | bool                                                                                                     |             |

## getTradeValueCollateral

```solidity theme={null}
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#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 theme={null}
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#tradepriceimpactinput) | input data        |
| \_contractsVersion | enum ITradingStorage.ContractsVersion                                                                                                                | contracts version |

## getTradeClosingPriceImpact

```solidity theme={null}
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#tradepriceimpactinput) | input data  |

## getTradeLiqPnlThresholdP

```solidity theme={null}
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#trade) | trade struct |

## getTotalTradeFeesCollateral

```solidity theme={null}
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 theme={null}
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 theme={null}
function getMinGovFeeCollateral(uint8 _collateralIndex, address _trader, uint16 _pairIndex) public view returns (uint256)
```

## revertIfTradeHasPendingMarketOrder

```solidity theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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#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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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#trade) | trade struct                                              |
| \_positionSizeCollateral | uint256                                                                                                  | position size in collateral tokens (collateral precision) |
| \_orderType              | enum ITradingStorage.PendingOrderType                                                                    | trade order type                                          |

## distributeReferralFeeCollateral

```solidity theme={null}
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 theme={null}
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#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 theme={null}
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#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 theme={null}
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#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 theme={null}
function _getMultiCollatDiamond() internal view returns (contract IGNSMultiCollatDiamond)
```

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