# Interface

## IBattle

### IBattleActions

#### IBattleMintBurn

#### mint

Mints liquidity for a battle

```javascript
function mint(BattleMintParams memory mp) external returns (uint256 seed)
```

**Params:**

| **Name** | **Type**         | **Description**                  |
| -------- | ---------------- | -------------------------------- |
| mp       | BattleMintParams | Parameters for minting liquidity |

**Returns:**

| **Name** | **Type** | **Description**                                                                               |
| -------- | -------- | --------------------------------------------------------------------------------------------- |
| seed     | uint256  | The token amount provided for the position, of the collateral, Spear or Shield liquidity type |

#### burn

Removes liquidity from a battle

```javascript
function burn(BattleBurnParams memory BurnParams) external
```

**Params:**

| **Name**         | **Description**                                                                                                                       |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| BattleBurnParams | Parameters for burning liquidity. 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 contract Manager.

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

**Params:**

| **Name**  | **Description**                                      |
| --------- | ---------------------------------------------------- |
| recipient | The address who will receive collateral/spear/shield |
| cAmount   | The amount of collateral to be transferred           |
| spAmount  | The amount of Spear tokens to be transferred         |
| shAmount  | The amount of Shield tokens to be transferred        |

#### IBattleTrade

#### 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 tp) external returns (uint256 cAmount, uint256 sAmount, uint256 fAmount)
```

**Params:**

| **Name** | **Type**          | **Description**                                                                                                                        |
| -------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| tp       | 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         |

#### IBattleBase

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

#### exercise

This function allows a participant to exercise their winning long Spear or long Shield position, and claim the collateral payoff. For each winning Spear or Shield, 1 collateral can be claimed. eg. Alice bought 100 spear. The battle outcome turns out to be `spear_win`. she can claim 100 collateral tokens by call this function.

```javascript
function exercise() external
```

#### withdrawObligation

Returns the amount of unused collateral to the liquidity provider after settlement. For options that expire out-of-money, the amount of collateral obligation reserved prior to settlement becomes claimable. Only called by the Manager.

```javascript
function withdrawObligation(address recipient, uint256 amount) external;
```

**Params:**

| **Name**  | **Type** | **Description**                           |
| --------- | -------- | ----------------------------------------- |
| recipient | address  | Address which will receive the collateral |
| amount    | uint256  | The amount of collateral to be withdrawn  |

#### collectProtocolFee

This function allows the accumulated protocol fee to be collected. Can only be called by the owner.

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

**Params:**

| **Name**  | **Type** | **Description**            |
| --------- | -------- | -------------------------- |
| recipient | address  | The address receiving fees |

### IBattleInit

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

### IBattleState

#### positions

Retrieves position info for a given position key

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

**Params:**

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

**Returns:**

| **Name** | **Type**     | **Description**                |
| -------- | ------------ | ------------------------------ |
| info     | PositionInfo | Information about the position |

#### battleOutcome

Gets the result of the battle

```javascript
function battleOutcome() external view returns (Outcome)
```

**Returns:**

| **Name** | **Type** | **Description**           |
| -------- | -------- | ------------------------- |
| result   | Outcome  | The outcome of the battle |

#### battleKey

Returns the BattleKey that uniquely identifies a battle

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

**Returns:**

| **Name** | **Type**  | **Description** |
| -------- | --------- | --------------- |
| key      | BattleKey | The battle key  |

#### manager

Returns the address for the manager of the pool

```javascript
function manager()  external  view  returns  (address)
```

**Returns:**

| **Name** | **Type** | **Description**                    |
| -------- | -------- | ---------------------------------- |
| manager  | address  | Address of the manager of the pool |

#### slot0

Returns data stored in the baseInfo struct

```javascript
function slot0() external view returns (uint160 sqrtPriceX96, int24 tick, bool unlocked)
```

**Returns:**

| **Name**     | **Type** | **Description**                           |
| ------------ | -------- | ----------------------------------------- |
| sqrtPriceX96 | uint160  | The current sqrtPrice of the pool         |
| tick         | int24    | The current tick of the battle            |
| unlocked     | bool     | Flag indicating if the battle is unlocked |

#### spearAndShield

Returns the addresses of the Spear and Shield tokens

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

**Returns:**

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

#### startAndEndTS

Get the start and end timestamps of the battle

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

**Returns:**

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

#### spearBalanceOf

Get the balance of Spear tokens for an account

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

**Params:**

| **Name** | **Type** | **Description**        |
| -------- | -------- | ---------------------- |
| account  | address  | Address of the account |

**Returns:**

| **Name** | **Type** | **Description**             |
| -------- | -------- | --------------------------- |
| amount   | uint256  | The balance of Spear tokens |

#### shieldBalanceOf

Get the balance of Shield tokens for an account

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

**Params:**

| **Name** | **Type** | **Description**        |
| -------- | -------- | ---------------------- |
| account  | address  | Address of the account |

**Returns:**

| **Name** | **Type** | **Description**              |
| -------- | -------- | ---------------------------- |
| amount   | uint256  | The balance of Shield tokens |

#### spear

Get the address of the Spear token

```javascript
function spear() external view returns (address)
```

**Returns:**

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

#### shield

Get the address of the Shield token

```javascript
function shield() external view returns (address)
```

**Returns:**

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

#### getInsideLast

Get the growth rate inside a tick range

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

**Params:**

| **Name**  | **Type** | **Description**         |
| --------- | -------- | ----------------------- |
| tickLower | int24    | Lower tick of the range |
| tickUpper | int24    | Upper tick 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) |

#### fee

Get the fee ratios used for a battle

```javascript
function fee() external view returns (uint256, uint256, uint256)
```

**Returns:**

| **Type** | **Description**                                          |
| -------- | -------------------------------------------------------- |
| uint256  | The fee ratio taken on every trade                       |
| uint256  | The portion of transaction fee that goes to the protocol |
| uint256  | The exercise fee paid by those who call exercise()       |

## Callback

### IMintCallback

#### mintCallback

Sets the amount owed to the pool for the minted liquidity

```javascript
function mintCallback(uint256 amountOwed,  bytes  calldata data)  external
```

**Params:**

| **Name**   | **Type** | **Description**                                      |
| ---------- | -------- | ---------------------------------------------------- |
| amountOwed | uint256  | The amount owed to the pool for the minted liquidity |
| data       | bytes    | Any additional data passed through by the caller     |

### ITradeCallback

#### tradeCallback

Call back function after trading

```javascript
function tradeCallback(uint256 cAmount, uint256 sAmount, bytes calldata data) external;
```

**Params:**

| **Name** | **Type**    | **Description**                                  |
| -------- | ----------- | ------------------------------------------------ |
| cAmount  | TradeAction | The amount of collateral                         |
| sAmount  | TradeAction | The amount of Spear or Shield tokens             |
| data     | bytes       | Any additional data passed through by the caller |

## IArena

### IArenaAdmin

#### setFeeForUnderlying

Sets the fee parameters for an underlying asset

```javascript
function setFeeForUnderlying(string calldata underlying, Fee calldata newFee) external;
```

**Params:**

| **Name**   | **Type** | **Description**                      |
| ---------- | -------- | ------------------------------------ |
| underlying | string   | The name of the underlying asset     |
| newFee     | Fee      | The new fee for the underlying asset |

#### setCollateralWhitelist

Sets the whitelist status for a collateral token. Can only be set by the owner. This function will no longer be in use when the permissionless mode is enabled.

```javascript
function setCollateralWhitelist(address collateral, bool isSupported) external
```

**Params:**

| **Name**    | **Type** | **Description**                              |
| ----------- | -------- | -------------------------------------------- |
| collateral  | address  | The address of the collateral token          |
| isSupported | bool     | The whitelist status of the collateral token |

#### setUnderlyingWhitelist

Sets the whitelist status and fee for an underlying asset.

```javascript
function setUnderlyingWhitelist(string memory underlying, bool isSupported, Fee calldata fee) external
```

**Params:**

| **Name**    | **Type** | **Description**                              |
| ----------- | -------- | -------------------------------------------- |
| underlying  | string   | The symbol or name of the underlying asset   |
| isSupported | bool     | The whitelist status of the underlying asset |
| fee         | Fee      | The fee structure for the underlying asset   |

#### setPermissionless

Toggles the permissionless mode of the contract. Permissionless mode is disabled initially, when the contracts begin in production. Only whitelisted collateral tokens can be used in battles. Once the permissionless mode is enabled, battles can be created with any ERC-20 token without the need for a whitelist.

```javascript
function setPermissionless() external
```

#### setManager

Sets the manager address

```javascript
function setManager(address _manager) external
```

#### setOracle

Sets the oracle address

```javascript
function setOracle(address _oracle) external
```

### IArenaCreation

#### createBattle

Create a new battle

```javascript
function createBattle(BattleKey memory bk) external returns (address battleAddr);
```

**Params:**

| **Name** | **Type**  | **Description**                                                                                                                             |
| -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| bk       | BattleKey | Parameters for creating a new battle. See [Params](https://docs.divergence-protocol.com/technical-reference/core/params#createbattleparams) |

**Returns:**

| **Name**   | **Type** | **Description**               |
| ---------- | -------- | ----------------------------- |
| battleAddr | address  | The address of the new battle |

#### getBattle

Returns existing battle address from the given BattleKey

```javascript
function getBattle(BattleKey memory battleKey) external view returns (address battleAddr);
```

**Params:**

| **Name**  | **Type** | **Description**                                   |
| --------- | -------- | ------------------------------------------------- |
| battleKey | bytes32  | The battle Key containing a pool's specifications |

**Returns:**

| **Name**   | **Type** | **Description**                                               |
| ---------- | -------- | ------------------------------------------------------------- |
| battleAddr | address  | The address of the existing battle or address(0) if not found |

### IArenaState

#### getAllBattles

Get information for all battles

```javascript
function getAllBattles() external view returns (BattleInfo[] memory);
```

**Returns:**

| **Name**   | **Type** | **Description**                                                                                                                                                                          |
| ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| BattleInfo | memory   | Information about all battles, each including the battle address, battle key, sqrtPrice, start and expiry timestamps, spear and shield token addresses and balances, and battle outcome. |

### IOracle

Collects and updates underlying asset prices used for settling options. It retrieves asset prices and supplies them to all contracts that use them.

#### updatePriceByExternal

Gets and computes price from external oracles

```javascript
function getPriceByExternal(address cOracleAddr, uint256 ts) external view returns (uint256 price_, uint256 actualTs)
```

**Params:**

| **Name**    | **Type** | **Description**                                 |
| ----------- | -------- | ----------------------------------------------- |
| cOracleAddr | address  | The contract address for a chainlink price feed |
| ts          | uint256  | Timestamp for the asset price                   |

**Returns:**

| **Name** | **Type** | **Description**                                           |
| -------- | -------- | --------------------------------------------------------- |
| price    | uint256  | The retrieved price                                       |
| actualTs | uint256  | The timestamp at which the price is updated by the oracle |

#### getCOracle

Returns the address of the chainlink oracle for an underlying

```javascript
function getCOracle(string memory symbol) external view returns (address)
```

**Params:**

| **Name** | **Type** | **Description**                                          |
| -------- | -------- | -------------------------------------------------------- |
| symbol   | string   | The symbol of the asset for which the price is being set |

**Returns:**

| **Type** | **Description**                                 |
| -------- | ----------------------------------------------- |
| address  | The contract address for a chainlink price feed |

### IOwner

#### owner

Fetches the address of the contract owner

```javascript
function owner() external view returns (address);
```

**Returns:**

| **Type** | **Description**                   |
| -------- | --------------------------------- |
| address  | The address of the contract owner |

### ISToken

Mints or burns Spear or Shield tokens

#### mint

Mints an amount of tokens to a specific account

```javascript
function mint(address account, uint256 amount) external;
```

**Params:**

| **Name** | **Type** | **Description**                                            |
| -------- | -------- | ---------------------------------------------------------- |
| account  | address  | The address to which spear or shield tokens will be minted |
| amount   | uint256  | The amount of spear or shield tokens to mint               |

#### burn

Burns an amount of tokens from a specific account

```javascript
function burn(address account, uint256 amount) external;
```

**Params:**

| **Name** | **Type** | **Description**                                              |
| -------- | -------- | ------------------------------------------------------------ |
| account  | address  | The address from which spear or shield tokens will be burned |
| amount   | uint256  | The amount of spear or shield tokens to burn                 |