Smart Contract v2 Endpoints
External and View functions of the current Cairo 1 contract
External functions available in the current deployed version.
Types we use:
OptionType - 0 for call option, 1 for put option
Fixed - float type provided by Cubit library. For example 1.2 ETH is represented as 1.2 * 2^64 (2^64 is the precision of the float), similarly strike price 1500 is represented as 1500 * 2^64. This will be no longer be used for external functions since 1.0.0 version
OptionSide - 0 for long, 1 for short
Int - represents "small" number, for example unix timestamp
Option - struct - Option { option_side: OptionSide, maturity: Int, strike_price: Fixed, quote_token_address: Address, base_token_address: Address, option_type: OptionType, }
Pool - struct - Pool { quote_token_address: Address, base_token_address: Address, option_type: OptionType, }
OptionWithPremia - struct - OptionWithPremia { option: Option, premia: Fixed, }
OptionWithUsersPosition - struct - OptionWithUsersPosition { option: Option, position_size: Fixed, value_of_position: Fixed, }
PoolInfo - struct - PoolInfo { pool: Pool, lptoken_address: Address, staked_capital: u256, unlocked_capital: u256, value_of_pool_position: Fixed, }
UserPoolInfo - struct - UserPoolInfo { value_of_user_stake: u256, size_of_users_tokens: u256, pool_info: PoolInfo, }
AMM smart contract
In the codebase it is split into multiple modules.
External
trade_open
option_type : OptionType
strike_price : Fixed
maturity : Int
option_side : OptionSide
option_size : Fixed - for example 1.2 * 2^64 to represent size of 1.2
quote_token_address: Address - for example USDC in case of ETH/USDC
base_token_address: Address - for example ETH in case of ETH/USDC
limit_total_premia: Fixed - max acceptable total premia(with fees) in case of Long trade, min in case of Short
tx_deadline: Int - Maximum acceptable time for the transaction to pass
Return -> (premia : Fixed)
Opens a new position in option defined by the input parameters. Updates internal parameters. Option has to be listed, otherwise the invoke fails. Returns value of premia in corresponding pool's currency before adjustment for option size and fees. Fails if there is not enough liquidity in given pool.
trade_close
option_type : OptionType
strike_price : Fixed
maturity : Int
option_side : OptionSide
option_size : Fixed - for example 1.2 * 2^64 to represent size of 1.2
quote_token_address: Address - for example USDC in case of ETH/USDC
base_token_address: Address - for example ETH in case of ETH/USDC
tx_deadline: Int - Maximum acceptable time for the transaction to pass
limit_total_premia: Fixed - max acceptable total premia(with fees) in case of Long trade, min in case of Short
Return -> (premia : Fixed)
Closes already existing position in given option defined by the input parameters. Can be used before the option expires (2 hours before expiry or earlier). Otherwise fails.
Last 2 hours before expiry the trading is closed. After the expiry the trade_settle should be called to settle the option.
This might require some capital to be locked by the pool. So it might fail if there is not enough capital in the pool.
trade_settle
option_type : OptionType
strike_price : Fixed
maturity : Int
option_side : OptionSide
option_size : Fixed - for example 1.2 * 2^61 to represent size of 1.2
quote_token_address: Address - for example USDC in case of ETH/USDC
base_token_address: Address - for example ETH in case of ETH/USDC
Return -> (premia : Fixed)
Settles the expired option. To work it needs the "expire_option_token_for_pool" to be called first, by anyone.
For long call the payoff is max(0, expiry price - strike price) * size
For short call the payoff is strike price * size - max(0, expiry price - strike price) * size since the locked capital by the user is equal to strike * option size. In other words the user gets remainder of what was left when the long position was paid off.
For long put the payoff is max(0, strike price - expiry price) * size
For long call the payoff is strike price * option size - max(0, strike price - expiry price) * sizesince the locked capital by the user is equal to strike * option size. In other words the user gets remainder of what was left when the long position was paid off.
add_lptoken
quote_token_address: Address
base_token_address: Address
option_type: OptionType
lptoken_address: Address
pooled_token_addr: Address
volatility_adjustment_speed: Fixed
max_lpool_bal: u256
Used by AMM owner to add pool.
deposit_liquidity
pooled_token_addr: Address - address of underlying token used in the pool (ETH/USDC/wBTC/...), used mainly to validate that there are no mistakes the combination all 3 addresses and the option type
quote_token_address: Address
base_token_address: Address
option_type: OptionType
amount: u256
User (caller) deposits "amount" of "pooled_token_addr" tokens in the liquidity pool. The AMM calculates the value of the pool before deposit in terms of the "pooled_token_addr" and based on this mints corresponding number of lp tokens to the user.
withdraw_liquidity
pooled_token_addr: Address - address of underlying token used in the pool (ETH/USDC/wBTC/...), used mainly to validate that there are no mistakes the combination all 3 addresses and the option type
quote_token_address: Address
base_token_address: Address
option_type: OptionType
lp_token_amount: u256 - how many lp tokens should be burned
Withdraws proportional value from the pool to the user, based on the lp_token_amount. Burns the lp_token_amount.
Fails if there is not enough available capital in the pool. Ie value of the pool corresponding to the lp_token_amount might be bigger than currently available capital. This is caused by the AMM locking in capital to payoff options and the value of the pools is some of available (unlocked) capital and value of options and locked capital.
expire_option_token_for_pool
lptoken_address: Address
option_side: OptionSide
strike_price: Fixed
maturity: Int
Settles pool's position in given option once the option expires. This has to be called before users settle their options.
add_option
option_side: OptionSide
maturity: Int
strike_price: Fixed
quote_token_address: Address
base_token_address: Address
option_type: OptionType
lptoken_address: Address
option_token_address_: Address
initial_volatility: Fixed
Adds new option to the AMM and connects it selected liquidity pool (must be existing).
View
get_unlocked_capital
lptoken_address: Address
Return -> (pool_balance: u256)
Returns available (unused) capital (in terms of pooled token) in given pool identified by the lptoken_address.
is_option_available
lptoken_address: Address
option_side: OptionSide
strike_price: Fixed
maturity: Int
Return -> (option_availability: bool)
Checks if given option is available in the AMM. Returns True or False.
get_value_of_pool_position
lptoken_address: Address
Return -> (res: Fixed)
Returns value of the pool's position. Does not take into account the staked capital, just the option position of the pool and its value. Calculates both for expired and non-expired options.
get_value_of_position
option: Option_
position_size: u128
option_type: OptionType
current_volatility: Fixed
Return -> (position_value: Fixed)
Returns value of given position. Answers "How much would I get if I closed the position". Takes into account both the option premia and the locked capital.
get_underlying_for_lptokens
lptoken_address: Address
lpt_amt: u256
Return -> (underlying_amt: u256)
Computes how much a user would get for given amount of lp tokens in given pool if the user withdrawed capital.
get_current_price
quote_token_address: Address of the quote token in given ticker
base_token_address: Address of the base token in given ticker
Return -> (price: Fixed)
Returns current price for given ticker
get_terminal_price
quote_token_address: Address of the quote token in given ticker
base-token_address: Address of the base token in given ticker
maturity: Int - timestamp of the historical price
Return -> ( price: Fixed)
Returns historical price. Last price before maturity.
get_available_lptoken_addresses
order_i: Int
Return -> (lptoken_address: Address)
For given index (order_i) returns address of lptoken. LPTokens (pools) start from 0 and go to n, once the endpoint returns 0, there is no more pools/lp tokens.
get_lpool_balance
lptoken_address: Address
Return -> (res: u256)
Returns total capital in the pool (locked + available capital). This is not a representation of the value of the pool. Serves for internal accounting purposes.
get_max_lpool_balance
pooled_token_addr: Address
Return -> (max_balance: u256)
Returns maximum pool balance for given token(ETH, USDC, BTC etc.)
get_pool_locked_capital
lptoken_address: Address
Return -> (res: u256)
Returns the sum of the capital that the given pool has locked into options.
get_available_options
lptoken_address: Address
order_i: Int
Return -> ( option: Option_)
For given pool and index it returns option definition. Index (order_i) starts at 0 and continues untill the function returns struct with 0 values, then there are no more options.
get_option_position
lptoken_address: Address
option_side: OptionSide
maturity: Int
strike_price: Fixed
Return -> ( res: Fixed )
Returns the pool's position in given option.
get_lptoken_address_for_given_option
quote_token_address: Address
base_token_address: Address
option_type: OptionType
Return -> ( lptoken_address: Address )
For given option it returns the address of liquidity pool.
get_lptokens_for_underlying
pooled_token_addr: Address
underlying_amt: u256
Return -> ( lpt_amt: u256)
get_pool_definition_from_lptoken_address
lptoken_addres: Address
Return -> ( pool: Pool )
For given lptoken address returns Pool definition.
get_option_volatility
lptoken_address: Address
maturity: Int
strike_price: Fixed
Return -> (pool_volatility: Fixed)
Returns volatility parameter for given pool, maturity and strike.
get_pool_volatility_adjustment_speed
lptoken_adress: Adress
Return -> (res: Fixed)
Returns constant that determines speed at which the volatility for given pool changes.
get_underlying_token_address
lptoken_address: Address
Return -> (underlying_token_address_: Address)
Returns underlying asset address (for example ETH adress for ETH/USDC call pool).
get_option_token_address
lptoken_address: Address
option_side: OptionSide
maturity: Int
strike_price: Fixed
Return -> (option_token_address: Address)
Returns address of given option based on option definition.
get_available_lptoken_addresses_usable_index
starting_index: Int
Return -> (usable_index: Int)
Returns lowest non negative index that is available for storing lptoken addresses. (indexing starts at 0)
get_all_options
lptoken_address: Address
Return -> ( Array<Option_>)
Returns a list of structs (Option structs) of all options for given pool.
get_all_non_expired_options_with_premia
lptoken_address: Address
Return -> ( Array<OptionWithPremia> )
Returns a list of structs (OptionWithPremia structs) of all NON expired options for given pool. Same as get_all_options, but with additional information (premia) and only if non expired.
get_option_with_position_of_user
user_address : Address
Return -> ( Array<OptionWithUsersPosition>)
Returns a list of structs (OptionWithUsersPosition structs) of all options where user has some position (owns some option tokens). OptionWithUsersPosition is equivalent to Option with additional position_size and value_of_position.
get_all_lptoken_addresses
Return -> ( Array<Address> )
Returns a list of all lp token addresses. lp tokens are used as id for pools.
get_user_pool_infos
user: Address
Return -> ( Array<UserPoolInfo> )
Returns a list of user's non zero stakes in pools. List of UserPoolInfo.
get_all_poolinfo
Return -> ( Array<PoolInfo> )
Returns information about all pools.
get_max_option_size_percent_of_voladjspd
Return -> (u128)
Returns maximum option size as percentage of the volatility adjustment speed.
get_total_premia
option: Option_
lptoken_address: Address
position_size: u256
is_closing: Bool
Return -> (total_premia_before_fees: Fixed, total_premia_including_fees: Fixed)
Fetches premia(without actual trade) adjusted for size of the trade, both adjusted for fees and not.
Last updated