# Battle

## init

Inits state variable in storage. It is called only once for a battle.

```javascript
function init(DeploymentParams memory params) external override
```

**Params:**

| **Name**         | **Description**                                                                                                                          |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| DeploymentParams | The parameters for deploying a pool. See [Params](https://docs.divergence-protocol.com/technical-reference/core/params#DeploymentParams) |

## \_updatePosition

Updates a position and flips its upper tick and/or lower tick from initialized to uninitialized, or vice versa.

```javascript
function _updatePosition(UpdatePositionParams memory params) internal returns (PositionInfo storage position)
```

**Params:**

| **Name**             | **Description**                                                                                                                               |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| UpdatePositionParams | Parameters for updating the position. See [Params](https://docs.divergence-protocol.com/technical-reference/core/params#UpdatePositionParams) |

**Returns:**

| **Name**     | **Description**                                                                                                                       |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| PositionInfo | The info struct of the given position. See [Types](https://docs.divergence-protocol.com/technical-reference/core/types/#PositionInfo) |

### checkTicks

Checks whether the given lower tick and upper tick are within the minimum and maximum tick bounds. Also checks whether the lower tick is less than the upper tick.

```javascript
function checkTicks(int24 tickLower, int24 tickUpper) private pure
```

**Params:**

| **Name**  | **Type** | **Description**                         |
| --------- | -------- | --------------------------------------- |
| tickLower | int24    | The lower tick boundary of the position |
| tickUpper | int24    | The upper tick boundary of the position |

## \_modifyPosition

Helper for computing liquidity delta amounts to the curve when liquidity for a position is modified

```javascript
function _modifyPosition(ModifyPositionParams memory params) internal returns (PositionInfo storage position)
```

**Params:**

| **Name**             | **Description**                                                                                                                                |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| ModifyPositionParams | Parameters for modifying the position. See [Params](https://docs.divergence-protocol.com/technical-reference/core/params#ModifyPositionParams) |

**Returns:**

| **Name**     | **Description**                                                                                                                       |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| PositionInfo | The info struct of the given position. See [Types](https://docs.divergence-protocol.com/technical-reference/core/types/#PositionInfo) |

## mint

Create a liquidity NFT for the given parameters. Only called by the non-fungible position Manager.

```javascript
function mint(BattleMintParams memory params) external override lock onlyManager
```

**Params:**

| **Name**         | **Description**                                                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| BattleMintParams | Parameters for minting a liquidity NFT. See [Params](https://docs.divergence-protocol.com/technical-reference/core/params#BattleMintParams) |

**Returns:**

| **Name**     | **Description**                                                                                                                       |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| PositionInfo | The info struct of the given position. See [Types](https://docs.divergence-protocol.com/technical-reference/core/types/#PositionInfo) |
| seed         | uint256                                                                                                                               |

## burn

Burns a liquidity NFT according to the given parameters. Only called by the non-fungible position manager.

```javascript
function burn(BattleBurnParams memory params) external override lock onlyManager
```

**Params:**

| **Name**         | **Description**                                                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| BattleBurnParams | Parameters for burning a liquidity NFT. See [Params](https://docs.divergence-protocol.com/technical-reference/core/params#BattleBurnParams) |

## collect

Collects the specified amounts of collateral, Spear, and Shield tokens. Transfers them to the recipient. Only called by the non-fungible position manager.

```javascript
function collect(address recipient, uint256 cAmount, uint256 spAmount, uint256 shAmount) external override onlyManager
```

**Params:**

| **Name**  | **Type** | **Description**                              |
| --------- | -------- | -------------------------------------------- |
| recipient | address  | Address of the recipient                     |
| cAmount   | uint256  | Amount of collateral tokens to transfer      |
| spAmount  | uint256  | Amount of Spear tokens to mint and transfer  |
| shAmount  | uint256  | Amount of Shield tokens to mint and transfer |

## trade

Executes a trade by swapping collateral to either Spear or Shield tokens. When the price direction is up (down), an amount of Shield (Spear) token output is sent to the buyer.

```javascript
function trade(BattleTradeParams memory params) external returns (uint256 cAmount, uint256 sAmount, uint256 fAmount)
```

**Params:**

| **Name**          | **Description**                                                                                                                        |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| BattleTradeParams | Parameters for executing a trade. See [Params](https://docs.divergence-protocol.com/technical-reference/core/params#BattleTradeParams) |

**Returns:**

| **Name** | **Type** | **Description**                                                     |
| -------- | -------- | ------------------------------------------------------------------- |
| cAmount  | uint256  | Amount of collateral token input spent to be spent for the trade    |
| sAmount  | uint256  | Amount of Spear or Shield token output to be received for the trade |
| fAmount  | uint256  | Amount of fee in collateral token to be spent for the trade         |

## settle

Settles options of a pool after their expiry. It updates the battle outcome based on the underlying price retrieved from an external oracle.

```javascript
function settle() external override
```

## exercise

This function allows a participant to exercise their winning long Spear or long Shield position. Each winning Spear or Shield pays 1 collateral. This payoff is claimed after paying an `exerciseFeeAmount`. eg. Alice bought 100 spear. The battle outcome turns out to be `spear_win`. By calling this function, she claims 100 collateral tokens less `exerciseFeeAmount`.

```javascript
function exercise() external override lock
```

## withdrawObligation

Enables the liquidity provider to withdraw the collateral amount reserved for settlement. Only called by the Manager.

```javascript
function withdrawObligation(address recipient, uint256 amount) external override onlyManager lock
```

**Params:**

| **Name**  | **Type** | **Description**                                      |
| --------- | -------- | ---------------------------------------------------- |
| recipient | address  | The liquidity provider address to receive collateral |
| amount    | uint256  | The amount of collateral to be received              |

## collectProtocolFee

Collect the protocol fee accrued to the pool. Can only be called by the owner.

```javascript
function collectProtocolFee(address recipient) external override lock
```

## collateralBalance

This is a private view function that returns the current balance of collateral tokens held by the contract

```javascript
function collateralBalance() private view returns (uint256) 
```

**Returns:**

| **Type** | **Description**                      |
| -------- | ------------------------------------ |
| uint256  | Current balance of collateral tokens |

## positions

Retrieves information about a specific position based on its position key

```javascript
function positions(bytes32 positionKeyB32) external view override returns (PositionInfo memory info)
```

**Params:**

| **Name**       | **Type** | **Description** |
| -------------- | -------- | --------------- |
| positionKeyB32 | bytes32  | Position key    |

**Returns:**

| **Name**     | **Description**                                                                                                                       |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| PositionInfo | The info struct of the given position. See [Types](https://docs.divergence-protocol.com/technical-reference/core/types/#PositionInfo) |

## battleKey

Returns the battle key, which contains information about the battle configuration.

```javascript
function battleKey() external view override returns (BattleKey memory)
```

**Returns:**

| **Name**  | **Description**                                                                                                                                                                                                                 |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| BattleKey | The key containing parameters for a battle, such as the collateral token, underlying asset, expiration timestamp, and strike value. See [Types](https://docs.divergence-protocol.com/technical-reference/core/types/#BattleKey) |

## startAndEndTS

Returns the start and expiry timestamps of the battle

```javascript
function startAndEndTS() external view override returns (uint256, uint256)
```

**Returns:**

| **Type** | **Description**                |
| -------- | ------------------------------ |
| uint256  | Start timestamp of the battle  |
| uint256  | Expiry timestamp of the battle |

## spearBalanceOf

Returns the amount of Spear tokens held by an account

```javascript
function spearBalanceOf(address account) external view override returns (uint256 amount)
```

**Returns:**

| **Name** | **Type** | **Description**                            |
| -------- | -------- | ------------------------------------------ |
| amount   | uint256  | Amount of Spear tokens held by the account |

## shieldBalanceOf

Returns the amount of shield tokens held by an account

```javascript
function shieldBalanceOf(address account) external view override returns (uint256 amount)
```

**Returns:**

| **Name** | **Type** | **Description**                             |
| -------- | -------- | ------------------------------------------- |
| amount   | uint256  | Amount of shield tokens held by the account |

## spearAndShield

This function returns the addresses of the Spear and Shield tokens

```javascript
function spearAndShield() external view override returns (address, address)
```

**Returns:**

| **Name** | **Type** | **Description**             |
| -------- | -------- | --------------------------- |
| spear    | address  | Address of the Spear token  |
| shield   | address  | Address of the Shield token |

## getInsideLast

This function returns the growth variables for the specified tick range.

```javascript
function getInsideLast(int24 tickLower, int24 tickUpper) external view override returns (GrowthX128 memory)
```

**Params:**

| **Name**  | **Type** | **Description**                      |
| --------- | -------- | ------------------------------------ |
| tickLower | int24    | The lower tick boundary of the range |
| tickUpper | int24    | The upper tick boundary of the range |

**Returns:**

| **Name**   | **Description**                                                                                                                    |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| GrowthX128 | Growth variables for the tick range. See [Types](https://docs.divergence-protocol.com/technical-reference/core/types/#GrowthX128). |