# 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](/developer/technical-reference/contracts/interfaces/types/iupdateleverage.md#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](/developer/technical-reference/contracts/interfaces/types/itradingstorage.md#pendingorder)             | pending order struct            |
| \_answer | [ITradingCallbacks.AggregatorAnswer](/developer/technical-reference/contracts/interfaces/types/itradingcallbacks.md#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](/developer/technical-reference/contracts/interfaces/types/iupdateleverage.md#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](/developer/technical-reference/contracts/interfaces/types/itradingstorage.md#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](/developer/technical-reference/contracts/interfaces/types/itradingstorage.md#trade) | existing trade struct                                 |
| \_pendingTrade  | [ITradingStorage.Trade](/developer/technical-reference/contracts/interfaces/types/itradingstorage.md#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](/developer/technical-reference/contracts/interfaces/types/itradingstorage.md#trade)                               | existing trade struct        |
| \_values        | [IUpdateLeverage.UpdateLeverageValues](/developer/technical-reference/contracts/interfaces/types/iupdateleverage.md#updateleveragevalues) | pre-calculated useful values |
| \_answer        | [ITradingCallbacks.AggregatorAnswer](/developer/technical-reference/contracts/interfaces/types/itradingcallbacks.md#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](/developer/technical-reference/contracts/interfaces/types/itradingstorage.md#trade)                               | trade struct                                          |
| \_pendingTrade | [ITradingStorage.Trade](/developer/technical-reference/contracts/interfaces/types/itradingstorage.md#trade)                               | pending trade struct                                  |
| \_values       | [IUpdateLeverage.UpdateLeverageValues](/developer/technical-reference/contracts/interfaces/types/iupdateleverage.md#updateleveragevalues) | pre-calculated useful values                          |
| \_cancelReason | enum ITradingCallbacks.CancelReason                                                                                                       | cancel reason                                         |
| \_isIncrease   | bool                                                                                                                                      | true if increase leverage, false if decrease leverage |


---

# 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/libraries/updateleverage/updateleveragelifecycles.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.