Interface

IBattle

IBattleActions

IBattleMintBurn

mint

Mints liquidity for a battle

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

function burn(BattleBurnParams memory BurnParams) external

Params:

Name	Description
BattleBurnParams	Parameters for burning liquidity. See Params

collect

Collects the specified amounts of collateral, Spear, and Shield tokens. Transfers them to the recipient. Only called by the contract Manager.

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.

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

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.

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.

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.

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.

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.

function init(DeploymentParams memory params) external override

Params:

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

IBattleState

positions

Retrieves position info for a given position key

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

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

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

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

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

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

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

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

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

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

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

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

fee

Get the fee ratios used for a battle

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

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

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

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.

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.

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.

function setPermissionless() external

setManager

Sets the manager address

function setManager(address _manager) external

setOracle

Sets the oracle address

function setOracle(address _oracle) external

IArenaCreation

createBattle

Create a new battle

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

Params:

Name	Type	Description
bk	BattleKey	Parameters for creating a new battle. See Params

Returns:

Name	Type	Description
battleAddr	address	The address of the new battle

getBattle

Returns existing battle address from the given BattleKey

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

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

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

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

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

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

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