# UpdateLeverageLifecycles

_This is an external library for leverage update lifecycles Used by GNSTrading and GNSTradingCallbacks facets_

## requestUpdateLeverage

```solidity
function requestUpdateLeverage(struct IUpdateLeverage.UpdateLeverageInput _input) external
```

_Initiate update leverage order, done in 2 steps because need to cancel if liquidation price reached_

### Parameters

| Name    | Type                                                                                                 | Description                     |
| ------- | ---------------------------------------------------------------------------------------------------- | ------------------------------- |
| \_input | [IUpdateLeverage.UpdateLeverageInput](../../../interfaces/types/iupdateleverage#updateleverageinput) | request decrease leverage input |

## executeUpdateLeverage

```solidity
function executeUpdateLeverage(struct ITradingStorage.PendingOrder _order, struct ITradingCallbacks.AggregatorAnswer _answer) external
```

_Execute update leverage callback_

### Parameters

| Name     | Type                                                                                               | Description                     |
| -------- | -------------------------------------------------------------------------------------------------- | ------------------------------- |
| \_order  | [ITradingStorage.PendingOrder](../../../interfaces/types/itradingstorage#pendingorder)             | pending order struct            |
| \_answer | [ITradingCallbacks.AggregatorAnswer](../../../interfaces/types/itradingcallbacks#aggregatoranswer) | price aggregator request answer |

## \_getMultiCollatDiamond

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

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

## \_getNewCollateralAmount

```solidity
function _getNewCollateralAmount(uint256 _existingCollateralAmount, uint256 _existingLeverage, uint256 _newLeverage) internal pure returns (uint120)
```

_Returns new trade collateral amount based on new leverage (collateral precision)_

### Parameters

| Name                       | Type    | Description                                             |
| -------------------------- | ------- | ------------------------------------------------------- |
| \_existingCollateralAmount | uint256 | existing trade collateral amount (collateral precision) |
| \_existingLeverage         | uint256 | existing trade leverage (1e3)                           |
| \_newLeverage              | uint256 | new trade leverage (1e3)                                |

## \_validateRequest

```solidity
function _validateRequest(struct IUpdateLeverage.UpdateLeverageInput _input) internal view returns (struct ITradingStorage.Trade trade, bool isIncrease, uint256 collateralDelta)
```

_Fetches trade, does validation for update leverage request, and returns useful data_

### Parameters

| Name    | Type                                                                                                 | Description          |
| ------- | ---------------------------------------------------------------------------------------------------- | -------------------- |
| \_input | [IUpdateLeverage.UpdateLeverageInput](../../../interfaces/types/iupdateleverage#updateleverageinput) | request input struct |

## \_initiateRequest

```solidity
function _initiateRequest(struct ITradingStorage.Trade _trade, uint24 _newLeverage, uint256 _collateralDelta) internal returns (struct ITradingStorage.Id orderId)
```

_Stores pending update leverage order and makes price aggregator request_

### Parameters

| Name              | Type                                                                     | Description                                   |
| ----------------- | ------------------------------------------------------------------------ | --------------------------------------------- |
| \_trade           | [ITradingStorage.Trade](../../../interfaces/types/itradingstorage#trade) | trade struct                                  |
| \_newLeverage     | uint24                                                                   | new leverage (1e3)                            |
| \_collateralDelta | uint256                                                                  | trade collateral delta (collateral precision) |

## \_prepareCallbackValues

```solidity
function _prepareCallbackValues(struct ITradingStorage.Trade _existingTrade, struct ITradingStorage.Trade _pendingTrade, bool _isIncrease) internal view returns (struct IUpdateLeverage.UpdateLeverageValues values)
```

_Calculates values for callback_

### Parameters

| Name            | Type                                                                     | Description                                           |
| --------------- | ------------------------------------------------------------------------ | ----------------------------------------------------- |
| \_existingTrade | [ITradingStorage.Trade](../../../interfaces/types/itradingstorage#trade) | existing trade struct                                 |
| \_pendingTrade  | [ITradingStorage.Trade](../../../interfaces/types/itradingstorage#trade) | pending trade struct                                  |
| \_isIncrease    | bool                                                                     | true if increase leverage, false if decrease leverage |

## \_validateCallback

```solidity
function _validateCallback(struct ITradingStorage.Trade _existingTrade, struct IUpdateLeverage.UpdateLeverageValues _values, struct ITradingCallbacks.AggregatorAnswer _answer) internal view returns (enum ITradingCallbacks.CancelReason)
```

_Validates callback, and returns corresponding cancel reason_

### Parameters

| Name            | Type                                                                                                   | Description                  |
| --------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------- |
| \_existingTrade | [ITradingStorage.Trade](../../../interfaces/types/itradingstorage#trade)                               | existing trade struct        |
| \_values        | [IUpdateLeverage.UpdateLeverageValues](../../../interfaces/types/iupdateleverage#updateleveragevalues) | pre-calculated useful values |
| \_answer        | [ITradingCallbacks.AggregatorAnswer](../../../interfaces/types/itradingcallbacks#aggregatoranswer)     | price aggregator answer      |

## \_handleCallback

```solidity
function _handleCallback(struct ITradingStorage.Trade _trade, struct ITradingStorage.Trade _pendingTrade, struct IUpdateLeverage.UpdateLeverageValues _values, enum ITradingCallbacks.CancelReason _cancelReason, bool _isIncrease) internal
```

_Handles trade update, removes gov fee OI, and transfers collateral delta (for both successful and failed requests)_

### Parameters

| Name           | Type                                                                                                   | Description                                           |
| -------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
| \_trade        | [ITradingStorage.Trade](../../../interfaces/types/itradingstorage#trade)                               | trade struct                                          |
| \_pendingTrade | [ITradingStorage.Trade](../../../interfaces/types/itradingstorage#trade)                               | pending trade struct                                  |
| \_values       | [IUpdateLeverage.UpdateLeverageValues](../../../interfaces/types/iupdateleverage#updateleveragevalues) | pre-calculated useful values                          |
| \_cancelReason | enum ITradingCallbacks.CancelReason                                                                    | cancel reason                                         |
| \_isIncrease   | bool                                                                                                   | true if increase leverage, false if decrease leverage |
