# IPriceImpactUtils

*Interface for GNSPriceImpact facet (inherits types and also contains functions, events, and custom errors)*

## initializePriceImpact

```solidity
function initializePriceImpact(uint48 _windowsDuration, uint48 _windowsCount) external
```

*Initializes price impact facet*

### Parameters

| Name              | Type   | Description                |
| ----------------- | ------ | -------------------------- |
| \_windowsDuration | uint48 | windows duration (seconds) |
| \_windowsCount    | uint48 | windows count              |

## initializeNegPnlCumulVolMultiplier

```solidity
function initializeNegPnlCumulVolMultiplier(uint40 _negPnlCumulVolMultiplier) external
```

*Initializes negative pnl cumulative volume multiplier*

### Parameters

| Name                       | Type   | Description      |
| -------------------------- | ------ | ---------------- |
| \_negPnlCumulVolMultiplier | uint40 | new value (1e10) |

## initializePairFactors

```solidity
function initializePairFactors(uint16[] _pairIndices, uint40[] _protectionCloseFactors, uint32[] _protectionCloseFactorBlocks, uint40[] _cumulativeFactors) external
```

*Initializes pair factors*

### Parameters

| Name                          | Type      | Description                     |
| ----------------------------- | --------- | ------------------------------- |
| \_pairIndices                 | uint16\[] | pair indices to initialize      |
| \_protectionCloseFactors      | uint40\[] | protection close factors (1e10) |
| \_protectionCloseFactorBlocks | uint32\[] | protection close factor blocks  |
| \_cumulativeFactors           | uint40\[] | cumulative factors (1e10)       |

## setPriceImpactWindowsCount

```solidity
function setPriceImpactWindowsCount(uint48 _newWindowsCount) external
```

*Updates price impact windows count*

### Parameters

| Name              | Type   | Description       |
| ----------------- | ------ | ----------------- |
| \_newWindowsCount | uint48 | new windows count |

## setPriceImpactWindowsDuration

```solidity
function setPriceImpactWindowsDuration(uint48 _newWindowsDuration) external
```

*Updates price impact windows duration*

### Parameters

| Name                 | Type   | Description                    |
| -------------------- | ------ | ------------------------------ |
| \_newWindowsDuration | uint48 | new windows duration (seconds) |

## setNegPnlCumulVolMultiplier

```solidity
function setNegPnlCumulVolMultiplier(uint40 _negPnlCumulVolMultiplier) external
```

*Updates negative pnl cumulative volume multiplier*

### Parameters

| Name                       | Type   | Description      |
| -------------------------- | ------ | ---------------- |
| \_negPnlCumulVolMultiplier | uint40 | new value (1e10) |

## setProtectionCloseFactorWhitelist

```solidity
function setProtectionCloseFactorWhitelist(address[] _traders, bool[] _whitelisted) external
```

*Whitelists/unwhitelists traders from protection close factor*

### Parameters

| Name          | Type       | Description       |
| ------------- | ---------- | ----------------- |
| \_traders     | address\[] | traders addresses |
| \_whitelisted | bool\[]    | values            |

## setPairDepths

```solidity
function setPairDepths(uint256[] _indices, uint128[] _depthsAboveUsd, uint128[] _depthsBelowUsd) external
```

*Updates pairs 1% depths above and below*

### Parameters

| Name             | Type       | Description                   |
| ---------------- | ---------- | ----------------------------- |
| \_indices        | uint256\[] | indices of pairs              |
| \_depthsAboveUsd | uint128\[] | depths above the price in USD |
| \_depthsBelowUsd | uint128\[] | depths below the price in USD |

## setProtectionCloseFactors

```solidity
function setProtectionCloseFactors(uint16[] _pairIndices, uint40[] _protectionCloseFactors) external
```

*Sets protection close factors for pairs*

### Parameters

| Name                     | Type      | Description                         |
| ------------------------ | --------- | ----------------------------------- |
| \_pairIndices            | uint16\[] | pair indices to update              |
| \_protectionCloseFactors | uint40\[] | new protection close factors (1e10) |

## setProtectionCloseFactorBlocks

```solidity
function setProtectionCloseFactorBlocks(uint16[] _pairIndices, uint32[] _protectionCloseFactorBlocks) external
```

*Sets protection close factor blocks duration for pairs*

### Parameters

| Name                          | Type      | Description                        |
| ----------------------------- | --------- | ---------------------------------- |
| \_pairIndices                 | uint16\[] | pair indices to update             |
| \_protectionCloseFactorBlocks | uint32\[] | new protection close factor blocks |

## setCumulativeFactors

```solidity
function setCumulativeFactors(uint16[] _pairIndices, uint40[] _cumulativeFactors) external
```

*Sets cumulative factors for pairs*

### Parameters

| Name                | Type      | Description                   |
| ------------------- | --------- | ----------------------------- |
| \_pairIndices       | uint16\[] | pair indices to update        |
| \_cumulativeFactors | uint40\[] | new cumulative factors (1e10) |

## setExemptOnOpen

```solidity
function setExemptOnOpen(uint16[] _pairIndices, bool[] _exemptOnOpen) external
```

*Sets whether pairs are exempt from price impact on open*

### Parameters

| Name           | Type      | Description            |
| -------------- | --------- | ---------------------- |
| \_pairIndices  | uint16\[] | pair indices to update |
| \_exemptOnOpen | bool\[]   | new values             |

## setExemptAfterProtectionCloseFactor

```solidity
function setExemptAfterProtectionCloseFactor(uint16[] _pairIndices, bool[] _exemptAfterProtectionCloseFactor) external
```

*Sets whether pairs are exempt from price impact on close once protection close factor has expired*

### Parameters

| Name                               | Type      | Description            |
| ---------------------------------- | --------- | ---------------------- |
| \_pairIndices                      | uint16\[] | pair indices to update |
| \_exemptAfterProtectionCloseFactor | bool\[]   | new values             |

## addPriceImpactOpenInterest

```solidity
function addPriceImpactOpenInterest(address _trader, uint32 _index, uint256 _oiDeltaCollateral, bool _open, bool _isPnlPositive) external
```

*Adds open interest to current window*

### Parameters

| Name                | Type    | Description                                                                        |
| ------------------- | ------- | ---------------------------------------------------------------------------------- |
| \_trader            | address | trader address                                                                     |
| \_index             | uint32  | trade index                                                                        |
| \_oiDeltaCollateral | uint256 | open interest to add (collateral precision)                                        |
| \_open              | bool    | whether it corresponds to opening or closing a trade                               |
| \_isPnlPositive     | bool    | whether it corresponds to a positive pnl trade (only relevant when \_open = false) |

## getPriceImpactOi

```solidity
function getPriceImpactOi(uint256 _pairIndex, bool _long) external view returns (uint256 activeOi)
```

*Returns active open interest used in price impact calculation for a pair and side (long/short)*

### Parameters

| Name        | Type    | Description                    |
| ----------- | ------- | ------------------------------ |
| \_pairIndex | uint256 | index of pair                  |
| \_long      | bool    | true for long, false for short |

## getTradePriceImpact

```solidity
function getTradePriceImpact(address _trader, uint256 _marketPrice, uint256 _pairIndex, bool _long, uint256 _tradeOpenInterestUsd, bool _isPnlPositive, bool _open, uint256 _lastPosIncreaseBlock, enum ITradingStorage.ContractsVersion _contractsVersion) external view returns (uint256 priceImpactP, uint256 priceAfterImpact)
```

*Returns price impact % (1e10 precision) and price after impact (1e10 precision) for a trade*

### Parameters

| Name                   | Type                                  | Description                                                                           |
| ---------------------- | ------------------------------------- | ------------------------------------------------------------------------------------- |
| \_trader               | address                               | trader address (to check if whitelisted from protection close factor)                 |
| \_marketPrice          | uint256                               | market price (1e10 precision)                                                         |
| \_pairIndex            | uint256                               | index of pair                                                                         |
| \_long                 | bool                                  | true for long, false for short                                                        |
| \_tradeOpenInterestUsd | uint256                               | open interest of trade in USD (1e18 precision)                                        |
| \_isPnlPositive        | bool                                  | true if positive pnl, false if negative pnl (only relevant when \_open = false)       |
| \_open                 | bool                                  | true on open, false on close                                                          |
| \_lastPosIncreaseBlock | uint256                               | block when trade position size was last increased (only relevant when \_open = false) |
| \_contractsVersion     | enum ITradingStorage.ContractsVersion | trade contracts version                                                               |

## getPairDepth

```solidity
function getPairDepth(uint256 _pairIndex) external view returns (struct IPriceImpact.PairDepth)
```

*Returns a pair's depths above and below the price*

### Parameters

| Name        | Type    | Description   |
| ----------- | ------- | ------------- |
| \_pairIndex | uint256 | index of pair |

## getOiWindowsSettings

```solidity
function getOiWindowsSettings() external view returns (struct IPriceImpact.OiWindowsSettings)
```

*Returns current price impact windows settings*

## getOiWindow

```solidity
function getOiWindow(uint48 _windowsDuration, uint256 _pairIndex, uint256 _windowId) external view returns (struct IPriceImpact.PairOi)
```

*Returns OI window details (long/short OI)*

### Parameters

| Name              | Type    | Description                |
| ----------------- | ------- | -------------------------- |
| \_windowsDuration | uint48  | windows duration (seconds) |
| \_pairIndex       | uint256 | index of pair              |
| \_windowId        | uint256 | id of window               |

## getOiWindows

```solidity
function getOiWindows(uint48 _windowsDuration, uint256 _pairIndex, uint256[] _windowIds) external view returns (struct IPriceImpact.PairOi[])
```

*Returns multiple OI windows details (long/short OI)*

### Parameters

| Name              | Type       | Description                |
| ----------------- | ---------- | -------------------------- |
| \_windowsDuration | uint48     | windows duration (seconds) |
| \_pairIndex       | uint256    | index of pair              |
| \_windowIds       | uint256\[] | ids of windows             |

## getPairDepths

```solidity
function getPairDepths(uint256[] _indices) external view returns (struct IPriceImpact.PairDepth[])
```

*Returns depths above and below the price for multiple pairs*

### Parameters

| Name      | Type       | Description      |
| --------- | ---------- | ---------------- |
| \_indices | uint256\[] | indices of pairs |

## getPairFactors

```solidity
function getPairFactors(uint256[] _indices) external view returns (struct IPriceImpact.PairFactors[])
```

*Returns factors for a set of pairs (1e10)*

### Parameters

| Name      | Type       | Description      |
| --------- | ---------- | ---------------- |
| \_indices | uint256\[] | indices of pairs |

## getNegPnlCumulVolMultiplier

```solidity
function getNegPnlCumulVolMultiplier() external view returns (uint48)
```

*Returns negative pnl cumulative volume multiplier*

## getProtectionCloseFactorWhitelist

```solidity
function getProtectionCloseFactorWhitelist(address _trader) external view returns (bool)
```

*Returns whether a trader is whitelisted from protection close factor*

## OiWindowsSettingsInitialized

```solidity
event OiWindowsSettingsInitialized(uint48 windowsDuration, uint48 windowsCount)
```

*Triggered when OiWindowsSettings is initialized (once)*

### Parameters

| Name            | Type   | Description                       |
| --------------- | ------ | --------------------------------- |
| windowsDuration | uint48 | duration of each window (seconds) |
| windowsCount    | uint48 | number of windows                 |

## PriceImpactWindowsCountUpdated

```solidity
event PriceImpactWindowsCountUpdated(uint48 windowsCount)
```

*Triggered when OiWindowsSettings.windowsCount is updated*

### Parameters

| Name         | Type   | Description           |
| ------------ | ------ | --------------------- |
| windowsCount | uint48 | new number of windows |

## PriceImpactWindowsDurationUpdated

```solidity
event PriceImpactWindowsDurationUpdated(uint48 windowsDuration)
```

*Triggered when OiWindowsSettings.windowsDuration is updated*

### Parameters

| Name            | Type   | Description                           |
| --------------- | ------ | ------------------------------------- |
| windowsDuration | uint48 | new duration of each window (seconds) |

## NegPnlCumulVolMultiplierUpdated

```solidity
event NegPnlCumulVolMultiplierUpdated(uint40 negPnlCumulVolMultiplier)
```

*Triggered when negPnlCumulVolMultiplier is updated*

### Parameters

| Name                     | Type   | Description      |
| ------------------------ | ------ | ---------------- |
| negPnlCumulVolMultiplier | uint40 | new value (1e10) |

## ProtectionCloseFactorWhitelistUpdated

```solidity
event ProtectionCloseFactorWhitelistUpdated(address trader, bool whitelisted)
```

*Triggered when a trader is whitelisted/unwhitelisted from protection close factor*

### Parameters

| Name        | Type    | Description                                 |
| ----------- | ------- | ------------------------------------------- |
| trader      | address | trader address                              |
| whitelisted | bool    | true if whitelisted, false if unwhitelisted |

## ProtectionCloseFactorUpdated

```solidity
event ProtectionCloseFactorUpdated(uint256 pairIndex, uint40 protectionCloseFactor)
```

*Triggered when a pair's protection close factor is updated*

### Parameters

| Name                  | Type    | Description                        |
| --------------------- | ------- | ---------------------------------- |
| pairIndex             | uint256 | index of the pair                  |
| protectionCloseFactor | uint40  | new protection close factor (1e10) |

## ProtectionCloseFactorBlocksUpdated

```solidity
event ProtectionCloseFactorBlocksUpdated(uint256 pairIndex, uint32 protectionCloseFactorBlocks)
```

*Triggered when a pair's protection close factor duration is updated*

### Parameters

| Name                        | Type    | Description                        |
| --------------------------- | ------- | ---------------------------------- |
| pairIndex                   | uint256 | index of the pair                  |
| protectionCloseFactorBlocks | uint32  | new protection close factor blocks |

## CumulativeFactorUpdated

```solidity
event CumulativeFactorUpdated(uint256 pairIndex, uint40 cumulativeFactor)
```

*Triggered when a pair's cumulative factor is updated*

### Parameters

| Name             | Type    | Description                  |
| ---------------- | ------- | ---------------------------- |
| pairIndex        | uint256 | index of the pair            |
| cumulativeFactor | uint40  | new cumulative factor (1e10) |

## ExemptOnOpenUpdated

```solidity
event ExemptOnOpenUpdated(uint256 pairIndex, bool exemptOnOpen)
```

*Triggered when a pair's exemptOnOpen value is updated*

### Parameters

| Name         | Type    | Description                                        |
| ------------ | ------- | -------------------------------------------------- |
| pairIndex    | uint256 | index of the pair                                  |
| exemptOnOpen | bool    | whether the pair is exempt of price impact on open |

## ExemptAfterProtectionCloseFactorUpdated

```solidity
event ExemptAfterProtectionCloseFactorUpdated(uint256 pairIndex, bool exemptAfterProtectionCloseFactor)
```

*Triggered when a pair's exemptAfterProtectionCloseFactor value is updated*

### Parameters

| Name                             | Type    | Description                                                                                  |
| -------------------------------- | ------- | -------------------------------------------------------------------------------------------- |
| pairIndex                        | uint256 | index of the pair                                                                            |
| exemptAfterProtectionCloseFactor | bool    | whether the pair is exempt of price impact on close once protection close factor has expired |

## PriceImpactOpenInterestAdded

```solidity
event PriceImpactOpenInterestAdded(struct IPriceImpact.OiWindowUpdate oiWindowUpdate)
```

*Triggered when OI is added to a window.*

### Parameters

| Name           | Type                               | Description                                                           |
| -------------- | ---------------------------------- | --------------------------------------------------------------------- |
| oiWindowUpdate | struct IPriceImpact.OiWindowUpdate | OI window update details (windowsDuration, pairIndex, windowId, etc.) |

## PriceImpactOiTransferredPairs

```solidity
event PriceImpactOiTransferredPairs(uint256 pairsCount, uint256 prevCurrentWindowId, uint256 prevEarliestWindowId, uint256 newCurrentWindowId)
```

*Triggered when multiple pairs' OI are transferred to a new window (when updating windows duration).*

### Parameters

| Name                 | Type    | Description                                                           |
| -------------------- | ------- | --------------------------------------------------------------------- |
| pairsCount           | uint256 | number of pairs                                                       |
| prevCurrentWindowId  | uint256 | previous current window ID corresponding to previous window duration  |
| prevEarliestWindowId | uint256 | previous earliest window ID corresponding to previous window duration |
| newCurrentWindowId   | uint256 | new current window ID corresponding to new window duration            |

## PriceImpactOiTransferredPair

```solidity
event PriceImpactOiTransferredPair(uint256 pairIndex, struct IPriceImpact.PairOi totalPairOi)
```

*Triggered when a pair's OI is transferred to a new window.*

### Parameters

| Name        | Type                       | Description                                          |
| ----------- | -------------------------- | ---------------------------------------------------- |
| pairIndex   | uint256                    | index of the pair                                    |
| totalPairOi | struct IPriceImpact.PairOi | total USD long/short OI of the pair (1e18 precision) |

## OnePercentDepthUpdated

```solidity
event OnePercentDepthUpdated(uint256 pairIndex, uint128 valueAboveUsd, uint128 valueBelowUsd)
```

*Triggered when a pair's depth is updated.*

### Parameters

| Name          | Type    | Description                   |
| ------------- | ------- | ----------------------------- |
| pairIndex     | uint256 | index of the pair             |
| valueAboveUsd | uint128 | new USD depth above the price |
| valueBelowUsd | uint128 | new USD depth below the price |

## WrongWindowsDuration

```solidity
error WrongWindowsDuration()
```

## WrongWindowsCount

```solidity
error WrongWindowsCount()
```


---

# 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/interfaces/libraries/ipriceimpactutils.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.