# v9.2.1 Update

## Summary

* 50% of the spread and price impact is now charged on trade opening and closing instead of 100% on trade opening
* Existing trades don't pay any spread or impact on close (since they already paid in full on open), and they keep paying 100% spread when partial adding
* Spread and price impact on close use the reverse direction as opening spread (makes price lower for longs and higher for shorts)
* Price impact on close uses the opposite side depth and opposite side price impact OI (= cumulative vol now)
* Price impact OI windows now use new cumulative volume logic (much shorter windows duration possible because more accurate, opening a long / closing a short uses/adds to long windows, opening a short / closing a long uses/adds to short windows, new cumulative factor which will be set to 1 to start with but can be used to adjust weight of price impact OI in price impact formula), we never remove any OI from windows anymore (logic much simpler, no longer need to move trade OI to current window for partials)
* Closing price impact higher for short-term trades (depending on protection factor blocks duration and protection factor multiplier per pair), only when net PnL is positive
* Liquidation price now takes into account the closing spread (not the price impact) for trades opened after v9.2 and uses new logic for the liquidation pnl % threshold (closer pnl % threshold as leverage increases, more aggressive for higher leverages similarly to MMR)
* Existing trades aren't affected by the new liquidation threshold logic, liquidation parameters for trades are stored on opening so they can't change for an open trade even when a group's liquidation parameters are updated, however a trade's liquidation params are refreshed to current value when position size is increased using partials
* New stop loss max distance is `liqPnlThresholdP - 10%` (eg. -70% PnL when trade liq pnl % threshold is -80%)
* Added max slippage on close (market close, partial close, tp/sl) mechanism: by default 1% for all opened trades, can be adjusted after trade is open
* Extracted cancel reason logic for limit/stop/tp/sl/liq callbacks into getters, will be used by EA-lookbacks to check ability to execute at past chain state
* LIQ triggers no longer turned into SL triggers when SL is closer otherwise user could set very low max closing slippage and would never be able to be liquidated if price went past his SL and LIQ price, trigger bots will prioritize SL over LIQ when possible

## Full Changelog

### core/facets/GNSPairsStorage.sol (update)

* Added `initializeGroupLiquidationParams`, `setGroupLiquidationParams`, `getGroupLiquidationParams`, and `getPairLiquidationParams`

### core/facets/GNSPriceAggregator.sol (update)

* `getPrice` now accepts `_tradeId` instead of `_trader`

### core/facets/GNSPriceImpact.sol (update)

* Added `initializePairFactors`, `setProtectionCloseFactors`, `setProtectionCloseFactorBlocks`, `setCumulativeFactors`, `getPairFactors`
* Removed `removePriceImpactOpenInterest`, `getTradeLastWindowOiUsd`, `getTradePriceImpactInfo`
* `addPriceImpactOpenInterest` now accepts `_open` argument
* `getTradePriceImpact` now accepts `_isPnlPositive`, `_open`, `_lastPosIncreaseBlock`, and `_contractsVersion` arguments

### core/facets/GNSTradingCallbacks.sol (update)

* Added `validateTriggerOpenOrderCallback` and `validateTriggerCloseOrderCallback` getters

### core/facets/GNSTradingInteractions.sol (update)

* New `updateMaxClosingSlippageP` function
* `closeTradeMarket` and `decreasePositionSize` now accept `_expectedPrice` argument (used for max slippage check in callbacks)

### core/facets/GNSTradingStorage.sol (update)

* New `updateTradeMaxClosingSlippageP` function
* `updateTradePosition` now accepts `_isPartialIncrease` argument
* Added `getTradeLiquidationParams`, `getTradesLiquidationParams`, `getAllTradesLiquidationParams`, and `getCurrentContractsVersion`

### interfaces/IGeneralErrors.sol (update)

* Added `WrongOrderType()` error

### interfaces/libraries/IPairsStorageUtils.sol (update)

* Added new function definitions
* Added `GroupLiquidationParamsUpdated` event
* Added `MaxLiqSpreadPTooHigh`, `WrongLiqParamsThresholds`, `WrongLiqParamsLeverages`, `StartLiqThresholdTooHigh`, `EndLiqThresholdTooLow`, `StartLeverageTooLow`, `EndLeverageTooHigh`

### interfaces/libraries/IPriceAggregatorUtils.sol (update)

* Adjusted `getPrice` function definition
* Updated `PriceRequested` event: now emits `tradeId` instead of `trader`

### interfaces/libraries/IPriceImpactUtils.sol (update)

* Added new function definitions
* Removed deprecated function definitions
* Adjusted `addPriceImpactOpenInterest` and `getTradePriceImpact` functions definitions
* Added `ProtectionCloseFactorUpdated`, `ProtectionCloseFactorBlocksUpdated`, and `CumulativeFactorUpdated` events
* Removed `isPartial` from `PriceImpactOpenInterestAdded` event
* Removed `PriceImpactOpenInterestRemoved` event

### interfaces/libraries/ITradingCallbacksUtils.sol (update)

* Added `validateTriggerOpenOrderCallback` and `validateTriggerCloseOrderCallback` functions definitions

### interfaces/libraries/ITradingCommonUtils.sol (update)

* Added `TradePriceImpactInput` struct to avoid stack too deep in `getTradeClosingPriceImpact`

### interfaces/libraries/ITradingInteractionsUtils.sol (update)

* Added `updateMaxClosingSlippageP` function definition
* Adjusted `closeTradeMarket` and `decreasePositionSize` functions definitions
* Removed `WrongOrderType()` error

### interfaces/libraries/ITradingStorageUtils.sol (update)

* Added new function definitions
* Adjusted `updateTradePosition` function definition
* `TradeStored` event now also emits the trade liquidation params
* `TradePositionUpdated` now emits `isPartialIncrease`
* New `TradeMaxClosingSlippagePUpdated` event

### interfaces/libraries/IUpdatePositionSizeUtils.sol (update)

* Added `long` and `collateralPriceUsd` properties to `PositionSizeIncreaseExecuted` and `PositionSizeDecreaseExecuted` events

### interfaces/types/IBorrowingFees.sol (update)

* `LiqPriceInput` struct has new `liquidationParams` property

### interfaces/types/IPairsStorage.sol (update)

* Added `groupLiquidationParams` mapping and corresponding `GroupLiquidationParams` struct
* `__gap` length decreased from 41 to 40

### interfaces/types/IPriceImpact.sol (update)

* Added `pairFactors` mapping
* `__gap` length decreased from 46 to 45
* Added `_open` property to `OiWindowUpdate` struct
* New `PairFactors` struct

### interfaces/types/ITradingStorage.sol (update)

* Added `tradeLiquidationParams` mapping
* `__gap` length decreased from 39 to 38
* New `ContractsVersion` enum
* `TradeInfo` struct now has `contractsVersion` and `lastPosIncreaseBlock` properties, and `__placeholder` was reduced from `uint48` to `uint8`

### interfaces/types/IUpdatePositionSize.sol (update)

* Added `expectedPrice` property to `DecreasePositionSizeInput` struct
* Added `priceAfterImpact` property to `DecreasePositionSizeValues` struct

### libraries/ArrayGetters.sol (update)

* Added `getTradesLiquidationParams` and `getAllTradesLiquidationParams` getters

### libraries/BorrowingFeesUtils.sol (update)

* `getTradeLiquidationPrice`: calculate `closingFeesCollateral` using new `TradingCommonUtils.getTotalClosingFeesCollateral` helper, pass input liquidation params, trade contracts version, and pair spread % to `_getTradeLiquidationPrice`
* `_getTradeLiquidationPrice`: new `_liquidationParams`, `_contractsVersion`, and `_pairSpreadP` arguments, `_collateralPrecisionDelta` is now uint256 (saves one var to avoid stack too deep), calculate `liqPnlThresholdP` using new `TradingCommonUtils.getLiqPnlThresholdP` helper, in `collateralLiqNegativePnlInt` calculation divide by `1e10` because of new liq threshold precision, if trade opened after v9.2 make liquidation price distance lower by closing spread (= 1/2 pair spread %, capped at `maxLiqSpreadP`)

### libraries/ConstantsUtils.sol (update)

* Replaced `MAX_SL_P` by `SL_LIQ_BUFFER_P=10%`, renamed `LIQ_THRESHOLD_P` to `LEGACY_LIQ_THRESHOLD_P`, added `MIN_LIQ_THRESHOLD_P=50%`/`MAX_LIQ_SPREAD_P=0.05%`/`DEFAULT_MAX_CLOSING_SLIPPAGE_P=1%`

### libraries/PairsStorageUtils.sol (update)

* New `initializeGroupLiquidationParams` function: initializes group liquidation params for all existing groups
* New `setGroupLiquidationParams` function: used to update a group's liquidation params (only affects trades opened after the change)
* New `getGroupLiquidationParams` and `getPairLiquidationParams` getters

### libraries/PriceAggregatorUtils.sol (update)

* `getPrice`: now accepts `_tradeId` argument instead of `_trader`, passes `trader`/`index`/`orderType` data to `linkRequest`

### libraries/PriceImpactUtils.sol (update)

* `MAX_WINDOWS_DURATION` lowered from 30 days to 10 minutes, `MIN_WINDOWS_DURATION` lowered from 10 minutes to 1 minute
* New `initializePairFactors` function that initializes pairs factors
* New `setProtectionCloseFactors` to set the protection close factors for a set of pairs
* New `setProtectionCloseFactorBlocks` to set the protection close factor duration in blocks for a set of pairs
* New `setCumulativeFactors` to set the cumulative factors for a set of pairs
* `addPriceImpactOpenInterest`: Removed partials logic that moved previous trade OI to current window if not expired, changed logic to decide if adds to long or short part of window (opening a long / closing a short adds to long window, opening a short / closing a long adds to short window), removed `lastWindowOiUsd` update (deprecated)
* Removed `removePriceImpactOpenInterest` and `getTradeLastWindowOiUsd`
* `getTradePriceImpact`: new `_isPnlPositive`/`_open`/`_lastPosIncreaseBlock`/`_contractsVersion` arguments, now loads `pairFactors` for pair, uses opposite side depth when `_open = false`, uses opposite side price impact OI when `_open = false`, passes `_open`, `protectionCloseFactor` (only when `_isPnlPositive` is true, `_open` is false, `protectionCloseFactor` isn't zero, and protection close factor didn't expire, otherwise passes `1e10`), `cumulativeFactor` (when not zero, otherwise passes `1e10`), and `_contractsVersion` to `_getTradePriceImpact`
* Removed `getTradePriceImpactInfo` (deprecated)
* New `getPairFactors` getter
* `_getTradePriceImpact`: new `_open`, `_protectionCloseFactor`, `_cumulativeFactor`, `_contractsVersion` arguments, returns early 0 price impact if trade opened before v9.2 and `_open = false` (no closing price impact for trades opened before v9.2 since they paid it fully on open), multiplies `_startOpenInterestUsd` by `_cumulativeFactor`, multiplies by `_protectionCloseFactor` instead of `1e10` in `priceImpactP` calculation and divides result by 2 if trade opened after v9.2 (charge half price impact if trade opened after v9.2 since they paid half on open already, for trades opened before v9.2 charges full opening price impact), sets `_long` to `!_long` if `_open` is false to invert the price impact direction on close

### libraries/TradingCallbacksUtils.sol (update)

* `closeTradeMarketCallback`: use new `_getTradeInfo` getter, Add `TradingCommonUtils.getTradeClosingPriceImpact` call, added max slippage cancel reason check (uses default max slippage % if `tradeInfo.maxSlippageP` not set), use `priceAfterImpact` (= market price + closing spread and price impact) instead of `_a.price` to calculate `v.profitP`, emit `priceAfterImpact` and `priceImpactP` in event
* `executeTriggerOpenOrderCallback`: moved all cancel reason and spread/price impact logic to `validateTriggerOpenOrderCallback`
* `executeTriggerCloseOrderCallback`: moved all cancel reason and spread/price impact logic to `validateTriggerCloseOrderCallback`, emit `priceImpactP` in `LimitExecuted` event
* `validateTriggerOpenOrderCallback`: new getter that contains the extracted cancel reason logic of `executeTriggerOpenOrderCallback`
* `validateTriggerCloseOrderCallback`: new getter that contains the extracted cancel reason logic of `executeTriggerCloseOrderCallback`, for SLs and TPs (not liquidations) set `v.executionPrice` to `TradingCommonUtils.getTradeClosingPriceImpact` result to take into account closing spread and impact, added max slippage cancel reason check for everything but liquidations (uses default max slippage % if `tradeInfo.maxSlippageP` not set)
* `_openTradePrep`: no logic change, just use new `TradingCommonUtils.getTradeOpeningPriceImpact` helper to calculate opening price impact
* New `_getTradeInfo` getter

### libraries/TradingCommonUtils.sol (update)

* `getMarketExecutionPrice`: new `_open`/`_contractsVersion` arguments, returns early with 0 spread if `_open = false` and `_contractsVersion = before v9.2`, divides spread by 2 if `_contractsVersion >= v9.2`, inverts spread direction when `_open` = false
* `getTradeValuePure`: combined `_borrowingFeeCollateral` and `_closingFeeCollateral` into `_feesCollateral` to avoid stack too deep, added `_liqPnlThresholdP` argument, `collateralLiqThreshold` is now `uint256` and uses `_liqPnlThresholdP` instead of `ConstantsUtils.LIQ_THRESHOLD_P` and is adjusted for `1e10` precision, added `int256` conversion for `collateralLiqThreshold` in return statement
* `getLiqPnlThresholdP`: new pure function that returns the corresponding liquidation PnL threshold percentage to use depending on a trade's liquidation params and leverage; uses new logic (linearly decreasing liq pnl threshold as leverage increases, capped between two values)
* `getTradeLiquidationPrice`: pass the stored trade's liquidation params
* `getTradeValueCollateral`: pass `borrowingFeesCollateral + _closingFeesCollateral` to `getTradeValuePure` instead of passing them separately, and also pass `getTradeLiqPnlThresholdP(_trade)`
* `getTradeOpeningPriceImpact`: New view helper to calculate the price impact % and price after spread + price impact for trade openings / partial adds
* `getTradeClosingPriceImpact`: New view helper that returns the closing price impact %, price after closing spread and impact, and net trade value used to determine whether net pnl is positive or not; returns early 0% price impact for trades opened before v9.2, otherwise calculates net trade value (taking into account pnl, spread, price impact, closing fees, and borrowing fees) without protection factor and compares it to the initial trade collateral to determine the `_isPnlPositive` value passed to `getTradePriceImpact` which determines the final returned `priceImpactP` and `priceAfterImpact` values
* `getTradeLiqPnlThresholdP`: new getter that returns the value of `getLiqPnlThresholdP` by passing the trade's stored liquidation params and its leverage
* `getTotalClosingFeesCollateral`: new getter that returns a trade's closing fee based on its `_collateralIndex`/`_pairIndex`/`_positionSizeCollateral`, used in `BorrowingFeesUtils.getTradeLiquidationPrice`/`TradingCommonUtils.getTradeClosingPriceImpact`/`DecreasePositionSizeUtils.validateRequest`
* Renamed `addOiCollateral` to `updateOi`, now accepts `_open` argument and passes it to `handleTradeBorrowingCallback` and `addPriceImpactOpenInterest`
* Renamed `addTradeOiCollateral` to `updateOiTrade`, now accepts `_open` argument and passes it to `updateOi`
* Removed `removeOiCollateral` and `removeTradeOiCollateral`
* `handleOiDelta` now uses `updateOi`, passes `_open = true` when `_newPositionSizeCollateral > existingPositionSizeCollateral` and `_open = false` when `_newPositionSizeCollateral < existingPositionSizeCollateral`

### libraries/TradingInteractionsUtils.sol (update)

* New `updateMaxClosingSlippageP` function that simply calls `GNSTradingStorage.updateTradeMaxClosingSlippageP`
* `closeTradeMarket`: now accepts `_expectedPrice`, reverts if `_expectedPrice` is 0, sets `pendingOrder.trade.openPrice` to `_expectedPrice`, passes trade id to `getPrice`
* `decreasePositionSize`: now accepts `_expectedPrice`, passes it to `requestDecreasePositionSize`
* `triggerOrder`: no longer turn LIQ orders into SL orders when SL is closer, uses `TradingCommonUtils.getTradeOpeningPriceImpact` to calculate `priceImpactP`
* `_openTrade`: uses `TradingCommonUtils.getTradeOpeningPriceImpact` to calculate `priceImpactP`, passes trade id to `getPrice`
* `_getPriceTriggerOrder`: passes trade id to `getPrice`

### libraries/TradingStorageUtils.sol (update)

* `storeTrade`: Fetches the corresponding pair's liquidation params and stores them into the new `tradeLiquidationParams` mapping, limits the trade SL distance using the new `_limitTradeSlDistance` helper, sets `_tradeInfo.contractsVersion` to the current version using `getCurrentContractsVersion()`, sets `_tradeInfo.lastPosIncreaseBlock` to current block, no longer sets `_tradeInfo.lastOiUpdateTs = 0` because corresponding logic was deprecated, calls `updateOiTrade` with `_open = true` instead of `addTradeOiCollateral`, emits the trade's liquidation params
* New `updateTradeMaxClosingSlippageP` setter
* `updateTradePosition`/`updateOpenOrderDetails`/`updateTradeSl`: limit the trade's SL distance using the new `_limitTradeSlDistance` helper instead of `_limitSlDistance`
* `updateTradePosition`: new `_isPartialIncrease` argument, sets the trade's stored liquidation params to the current pair liquidation params when `_isPartialIncrease = true` and sets `i.lastPosIncreaseBlock` to current block, emits `_isPartialIncrease` in `TradePositionUpdated` event
* `closeTrade`: calls `updateOiTrade` with `_open = false` instead of `removeTradeOiCollateral`
* `getTradeLiquidationParams`: new getter to return the new `tradeLiquidationParams` mapping values
* `getCurrentContractsVersion`: new getter to return the current contracts version (will need to be updated at each significant update)
* `_limitSlDistance`: accepts new `_liqPnlThresholdP` argument, calculates `minSlP` as `_liqPnlThresholdP - ConstantsUtils.SL_LIQ_BUFFER_P`, uses calculated `minSlP` instead of `ConstantsUtils.MAX_SL_P`, adjustments done for `1e10` precision of `minSlP`
* `_limitTradeSlDistance`: new view wrapper accepting `_trade` and `_newSl` arguments; returns a trade's capped SL distance based on its open price, leverage, new stop loss value, whether it's a long or a short, and based on its liquidation pnl % threshold fetched using `TradingCommonUtils.getTradeLiqPnlThresholdP(_trade)`

### libraries/updateLeverage/UpdateLeverageLifecycles.sol (update)

* `_initiateRequest`: small adjustment to avoid stack too deep, now passes trade id to `getPrice`
* `_prepareCallbackValues`: pass stored trade liquidation params in `values.liqPrice` calculation
* `_handleCallback`: pass `_isPartialIncrease = false` to `updateTradePosition`

### libraries/updatePositionSize/DecreasePositionSizeUtils.sol (update)

* `validateRequest`: calculate `closingFeesCollateral` using new `TradingCommonUtils.getTotalClosingFeesCollateral` helper, revert if `input.expectedPrice` is 0
* `prepareCallbackValues`: added `values.priceAfterImpact` calculation using new `TradingCommonUtils.getTradeClosingPriceImpact` helper, `values.existingPnlCollateral` now uses `uint64(values.priceAfterImpact)` instead of `_answer.price`
* `validateCallback`: now accepts `_pendingOrder` (to fetch expected price), added max slippage calculations and corresponding cancel reason check (uses default max slippage % if `tradeInfo.maxSlippageP` not set)
* `updateTradeSuccess`: pass `_isPartialIncrease = false` to `updateTradePosition`

### libraries/updatePositionSize/IncreasePositionSizeUtils.sol (update)

* `prepareCallbackValues`: Uses `TradingCommonUtils.getTradeOpeningPriceImpact` to calculate `values.priceAfterImpact`, passes current pair liquidation params to `getTradeLiquidationPrice` for `values.newLiqPrice` calculation (already checks using new liquidation params since trade liquidation params will be refreshed on success callback)
* `updateTradeSuccess`: pass `_isPartialIncrease = true` to `updateTradePosition`

### libraries/updatePositionSize/UpdatePositionSizeLifecycles.sol (update)

* `requestDecreasePositionSize`: passes `_input.expectedPrice` to `_initiateRequest`
* `_initiateRequest`: passes trade id to `getPrice`
* `executeIncreasePositionSizeMarket`/`executeDecreasePositionSizeMarket`: pass trade long and current collateral/usd price to event
* `executeDecreasePositionSizeMarket`: pass `_order` to `DecreasePositionSizeUtils.validateCallback`