Carmine Options AMM
Search
⌃K
Comment on page

Smart Contract v1 Endpoints

External and View functions of the contract
External functions available in the current deployed version. Next major version (from 1.0.0) will keep the functions but will replace types of input variables.
Types we use:
  • OptionType - 0 for call option, 1 for put option
  • Math64x61_ - float type... for example 1.2 ETH is represented as 1.2 * 2^61 (2^61 is the precision of the float), similarly strike price 1500 is represented as 1500 * 2^61. 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: Math64x61_, 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: Math64x61_, }
  • OptionWithUsersPosition - struct - OptionWithUsersPosition { option: Option, position_size: Math64x61_, value_of_position: Math64x61_, }
  • PoolInfo - struct - PoolInfo { pool: Pool, lptoken_address: Address, staked_capital: Math64x61_, unlocked_capital: Math64x61_, value_of_pool_position: Math64x61_, }
  • UserPoolInfo - struct - UserPoolInfo { value_of_user_stake: Uint256, pool_info: PoolInfo, }

AMM smart contract

In the codebase it is split into multiple modules.

External

trade_open

  • option_type : OptionType
  • strike_price : Math64x61_
  • maturity : Int
  • option_side : OptionSide
  • option_size : Math64x61_ - 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
  • limit_total_premia: Math64x61 - 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 : Math64x61_)
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. Fails if there is not enough liquidity in given pool.

trade_close

  • option_type : OptionType
  • strike_price : Math64x61_
  • maturity : Int
  • option_side : OptionSide
  • option_size : Math64x61_ - 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
  • tx_deadline: Int - Maximum acceptable time for the transaction to pass
  • limit_total_premia: Math64x61 - max acceptable total premia(with fees) in case of Long trade, min in case of Short
  • Return -> (premia : Math64x61_)
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 : Math64x61_
  • maturity : Int
  • option_side : OptionSide
  • option_size : Math64x61_ - 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 : Math64x61_)
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: Math64x61_
  • max_lpool_bal: Uint256
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: Uint256
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: Uint256 - 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: Math64x61_
  • 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: Math64x61_
  • quote_token_address: Address
  • base_token_address: Address
  • option_type: OptionType
  • lptoken_address: Address
  • option_token_address_: Address
  • initial_volatility: Math64x61_,
Adds new option to the AMM and connects it selected liquidity pool (must be existing).

​

View

get_pool_available_balance

  • lptoken_address: Address
  • Return -> (pool_balance: Math64x61_)
Returns available (unused) capital in given pool identified by the lptoken_address.

is_option_available

  • lptoken_address: Address
  • option_side: OptionSide
  • strike_price: Math64x61_
  • maturity: Int
  • Return -> (option_availability: felt)
Checks if given option is available in the AMM. Returns True (1) or False (0).

get_value_of_pool_position

  • lptoken_address: Address
  • Return -> (res: Math64x61_)
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.

get_value_of_position

  • option: Option
  • position_size: Math64x61_
  • option_type: OptionType
  • current_volatility: Math64x61_
​
  • Return -> (position_value: felt)
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: Uint256
  • Return -> (underlying_amt: Uint256)
Computes how much a user would get for given amount of lp tokens in given pool if the user withdrawed capital.

empiric_median_price

  • key: felt - key used by empiric oracle as id for an asset
  • Return -> (price: Math64x61_)
Just gets and returns the empiric's median price

get_terminal_price

  • key: felt - key used by empiric oracle as id for an asset
  • maturity: Int - timestamp of the historical price
  • Return -> ( price: Math64x61_ )
Returns historical Empiric's 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: Math64x61_)\
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: Uint256)
Returns maximum pool balance for given token(ETH, USDC, BC etc.)

get_pool_locked_capital

  • lptoken_address: Address
  • Return -> (res: Math64x61_)
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_pools_option_position

  • lptoken_address: Address
  • option_side: OptionSide
  • maturity: Int
  • strike_price: Math64x61_
  • Return -> ( res: Math64x61_ )
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: Uint256
  • Return -> ( lpt_amt: Uint256)

get_pool_definition_from_lptoken_address

  • lptoken_addres: Address
  • Return -> ( pool: Pool )
For given lptoken address returns Pool definition.

get_option_type

  • lptoken_address: Address
  • Return -> (option_type: OptionType)
Returns option type (put/call) of given liqudity pool.

get_pool_volatility

  • lptoken_address: Address
  • maturity: Int
  • Return -> (pool_volatility: Math64x61_)
Returns volatility parameter for given pool and maturity.

get_pool_volatility_separate

  • lptoken_address: Address
  • maturity: Int
  • strike_price: Math64x61_
  • Return -> (pool_volatility: Math64x61_)
Returns volatility parameter for given pool, maturity and strike.

get_pool_volatility_auto

  • lptoken_address: Address
  • maturity: Int
  • strike_price: Math64x61_
  • Return -> (pool_volatility: Math64x61_)
Returns volatility parameter for given pool, maturity and strike, but accounts for the possibility that volatility is not distinguished between strikes.

get_pool_volatility_adjustment_speed

  • lptoken_adress: Adress
  • Return -> (res: Math64x61_)
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_unlocked_capital

  • lptoken_address: Address
  • Return -> (unlocked_capital: Math64x61_)
Returns how much available capital (no used/locked) in the given pool.

get_option_token_address

  • lptoken_address: Address
  • option_side: OptionSide
  • maturity: Int
  • strike_price: Math64x61_
  • Return -> (option_token_address: Address)
Returns address of given option based on option definition.

get_available_options_usable_index

  • lptoken_address: Address
  • starting_index: Int
  • Return -> (usable_index: Int)
Returns lowest non negative index that is available in the given pool. If the given pool has or had listed n options, it returns n (indexing starts at 0).

get_available_lptoken_addresses_usable_index

  • starting_index: Int
  • Return -> (usable_index: Int)
Same as get_available_options_usable_index just used for pools in the AMM.

get_all_options

  • lptoken_address: Address
  • Return -> ( array_len : felt, array : felt* )
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_len : felt, array : felt* )
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_len : felt, array : felt*, )
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_len : felt, 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 -> ( user_pool_infos_len: felt, user_pool_infos: UserPoolInfo* )
Returns a list of user's non zero stakes in pools. List of UserPoolInfo.

get_user_pool_infos

  • user_pool_infos_len: felt
  • user_pool_infos: UserPoolInfo*
Retruns pool information for the given user.

get_all_poolinfo

  • Return -> ( pool_info_len: felt, pool_info: PoolInfo* )
Returns information about all pools.

get_option_info_from_addresses

  • lptoken_address: Address
  • option_token_address: Address
  • Return -> (option: Option)
Returns information about given option.

get_max_option_size_percent_of_voladjspd

  • Return -> (max_opt_size_as_perc_of_vol_adjspd: Int)
Returns maximum option size as percentage of the volatility adjustment speed.

get_total_premia

  • option: Option
  • lptoken_address: Address
  • position_size: Uint256
  • is_closing: Bool
  • Return -> (total_premia_before_fees: Math64x61_, total_premia_including_fees: Math64x61_)
Fetches premia(without actual trade) adjusted for size of the trade, both adjusted for fees and not.
​
​
​
Tech docs - Previous
Smart Contract Architecture
Next - Tech docs
Smart Contract v2 Endpoints
Last modified 19d ago