# 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). | --- # 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.divergence-protocol.com/technical-reference/core/battle.md?ask= ``` 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.