Battle

Each options pool is contained in a Battle contract. Battle contracts provide core functionalities including minting and burning liquidity, trading options tokens, settling and exercising options, and

init

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

function init(DeploymentParams memory params) external override

Params:

Name	Description
DeploymentParams	The parameters for deploying a pool. See Params

_updatePosition

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

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

Params:

Name	Description
UpdatePositionParams	Parameters for updating the position. See Params

Returns:

Name	Description
PositionInfo	The info struct of the given position. See Types

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.

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

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

Params:

Name	Description
ModifyPositionParams	Parameters for modifying the position. See Params

Returns:

Name	Description
PositionInfo	The info struct of the given position. See Types

mint

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

function mint(BattleMintParams memory params) external override lock onlyManager

Params:

Name	Description
BattleMintParams	Parameters for minting a liquidity NFT. See Params

Returns:

Name	Description
PositionInfo	The info struct of the given position. See Types
seed	uint256

burn

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

function burn(BattleBurnParams memory params) external override lock onlyManager

Params:

Name	Description
BattleBurnParams	Parameters for burning a liquidity NFT. See Params

collect

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

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.

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

Params:

Name	Description
BattleTradeParams	Parameters for executing a trade. See Params

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.

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.

function exercise() external override lock

withdrawObligation

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

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.

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

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

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

battleKey

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

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

startAndEndTS

Returns the start and expiry timestamps of the battle

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

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

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

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.

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.