> ## 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.

# UpdateLeverageLifecycles

*This is an external library for leverage update lifecycles Used by GNSTrading and GNSTradingCallbacks facets*

## requestUpdateLeverage

```solidity theme={null}
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](/developer/technical-reference/contracts/interfaces/types/iupdateleverage#updateleverageinput) | request decrease leverage input |

## executeUpdateLeverage

```solidity theme={null}
function executeUpdateLeverage(struct ITradingStorage.PendingOrder _order, struct ITradingCallbacks.AggregatorAnswer _answer) external
```

*Execute update leverage callback*

### Parameters

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

## \_getMultiCollatDiamond

```solidity theme={null}
function _getMultiCollatDiamond() internal view returns (contract IGNSMultiCollatDiamond)
```

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

## \_getNewCollateralAmount

```solidity theme={null}
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 theme={null}
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](/developer/technical-reference/contracts/interfaces/types/iupdateleverage#updateleverageinput) | request input struct |

## \_initiateRequest

```solidity theme={null}
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](/developer/technical-reference/contracts/interfaces/types/itradingstorage#trade) | trade struct                                  |
| \_newLeverage     | uint24                                                                                                   | new leverage (1e3)                            |
| \_collateralDelta | uint256                                                                                                  | trade collateral delta (collateral precision) |

## \_prepareCallbackValues

```solidity theme={null}
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](/developer/technical-reference/contracts/interfaces/types/itradingstorage#trade) | existing trade struct                                 |
| \_pendingTrade  | [ITradingStorage.Trade](/developer/technical-reference/contracts/interfaces/types/itradingstorage#trade) | pending trade struct                                  |
| \_isIncrease    | bool                                                                                                     | true if increase leverage, false if decrease leverage |

## \_validateCallback

```solidity theme={null}
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](/developer/technical-reference/contracts/interfaces/types/itradingstorage#trade)                               | existing trade struct        |
| \_values        | [IUpdateLeverage.UpdateLeverageValues](/developer/technical-reference/contracts/interfaces/types/iupdateleverage#updateleveragevalues) | pre-calculated useful values |
| \_answer        | [ITradingCallbacks.AggregatorAnswer](/developer/technical-reference/contracts/interfaces/types/itradingcallbacks#aggregatoranswer)     | price aggregator answer      |

## \_handleCallback

```solidity theme={null}
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](/developer/technical-reference/contracts/interfaces/types/itradingstorage#trade)                               | trade struct                                          |
| \_pendingTrade | [ITradingStorage.Trade](/developer/technical-reference/contracts/interfaces/types/itradingstorage#trade)                               | pending trade struct                                  |
| \_values       | [IUpdateLeverage.UpdateLeverageValues](/developer/technical-reference/contracts/interfaces/types/iupdateleverage#updateleveragevalues) | pre-calculated useful values                          |
| \_cancelReason | enum ITradingCallbacks.CancelReason                                                                                                    | cancel reason                                         |
| \_isIncrease   | bool                                                                                                                                   | true if increase leverage, false if decrease leverage |