MinterAmm
is an Automated Market Maker or "AMM" designed specifically for trading options for ERC20
tokens. It exposes functions for buying and selling bToken
as well as selling wToken
[^1]. Each MinterAmm
trades one of the two types of option Series: Puts or Calls. All option premiums will be in units of the AMM's collateral token, which for a Call AMM will be equal to the underlying token (e.g. a WBTC Call AMM's collateral token is WBTC), and for a Put AMM be equal to USDC (e.g. a WBTC Put AMM's collateral token is USDC). It uses the collateral token added by liquidity providers to mint bTokens
and wTokens
, keeping the wTokens
for itself and selling the bTokens
to traders. The AMM exposes functions for providing and withdrawing liquidity in the AMM pool. It is often useful to know the total value of all the option tokens and collateral token that comprise a pool, and there is a function for that as well.MinterAmm
, the quoted premium includes consists of the component from the onchain Black-Scholes approximation formula, as well as a price impact component. It is not possible to guarantee an exact option token price, because the price depends on the reserves of bToken
and wToken
held by the AMM, and those reserves might change if another transaction which affects the reserve amounts gets mined before the original trader's transaction gets mined. This is also true for when an LP withdraws their liquidity from the AMM and sets sellTokens = true
, which will sell the wTokens
owed to trader back to AMM in return for collateral token. This is why all of these functions take some slippage function argument, either collateralMinimum
when selling option tokens, or collateralMaximum
when buying option tokens.bTokens
, buying 'bTokens', and selling wTokens
.bTokenBuy
, bTokenSell
, or wTokenSell
unexpected behavior can occur. So to preclude this from happening we gate these function calls with the minTradeSize
modifierupdateImplementation
and transferOwnership
exist so that the owners can update the contracts in the event of a critical vulnerability that puts user's funds at risk.ERC20
token whose price determines the (glossary.md#moneyness) of the Series this AMM trades. For example, both WBTC Call option series and WBTC Put option series share WBTC as their underlying token, because the price of WBTC determines whether the Series is in or out of the money. If this AMM trades Calls then this will be the same token as the collateralToken.ERC20
token used to denominate the strike price
of the Series this AMM trades. This will almost always be USDC, but in the future could be different when SIREN denominates prices in something other than USDC. If this AMM trades Puts then this will be the same token as the collateralToken​ERC20
token this AMM uses for collateral. This is the token used to denominate all option prices (a.k.a. premiums) in the MinterAmm
, as well as the liquidity provided by LPs​SeriesController
associated with this MinterAmm
. The MinterAmm
uses the SeriesController
to interact with the Series it trades.ERC1155Controller
associated with this MinterAmm
. The MinterAmm
uses the ERC1155Controller
to interact with the the option tokens of the Series it trades.MinterAmm
takes when it executes a trade.0.4
, multiplied by the square root of the number of seconds in a year (i.e. implied_volatility * 0.4 * Math.sqrt(365 * 24 * 60 * 60)
)includeUnclaimed
exists only as a way to save on gas when calculating total pool value on chain; if the caller knows all option tokens have been claimed (which will be true if claimAllExpiredTokens
has just been called), it can pass false
for includeUnclaimed
and skip calculating their value.includeUnclaimed
true
if the value of expired of unclaimed wToken
should be included in the total pool calculation, and false
if it should not be includedseriesId
bToken
and wToken
available to the AMM for the given seriesId
. The AMM uses these balances as inputs into its bonding curve equation to compute the premiums for buying and selling option tokens.bToken
and wToken
held by the AMM, but additionally those option tokens that could be minted using the AMM's collateral token. The amounts returned will likely be slightly less than the full bToken
and wToken
amounts owned by the AMM, because the amounts returned must satisfy the ratio of the wToken
and bToken
prices computed by the onchain Black-Scholes approximation formula. See the documentation section on [protocol math](TODO point to this) for the motivation behind calculating virtual reserve balances in this manner.seriesId
bTokenVirtualBalance
bToken
available on the AMMwTokenVirtualBalance
wToken
available on the AMMseriesId
denominated in the priceToken. The returned values always use 8
decimal places. For example, if the Series' underlying == WBTC and price == USDC, then this function will return 4500000000000
($45_000 in human readable units).seriesId
bToken
as a percentage of collateral locked by 1 option token, multiplied by a scaling factor of 1e18
. For instance, if the price of 1 bToken
is 0.1 * 1e18
, and the bToken
's Series has a strike price of $35,000, then the price of 1 bToken
in units of USDC is $3,500.0.5 * 1e18
and be thought treated logically as simply 0.5
.calcPrice
uses a Black-Scholes approximation formula for pricing bTokens
. See the section [protocol math](TODO link to this) for more details on the approximation formula.wToken
is always 1e18 - price_of_btoken
, so in the above scenario, the price of the wToken
would be $35,000 - $3,500 = $31,500.strike
currentPrice
bTokenAmount
of bTokens
on the given seriesId
in units of collateral token. The premium has two components: the price returned by the Black-Scholes approximation formula, and the added cost of price impact.seriesId
bTokenAmount
bToken
the caller wants to receive in return for paying the premiumbTokenAmount
of bTokens
on the given seriesId
in units of collateral token. The premium has two components: the price returned by the Black-Scholes approximation formula, and the price impact.seriesId
bTokenAmount
bToken
the caller wants to sell to the AMMwTokenAmount
of wTokens
on the given seriesId
in units of collateral token. The premium has two components: the price returned by the Black-Scholes approximation formula, and the price impact.seriesId
wTokenAmount
wToken
the caller wants to sell to the AMMbTokens
and wTokens
held by the AMM. This function is useful for offchain clients to calculate the total collateral token available to the AMM. The offchain clients can use this to calculate the collateral owed to LPs when The LPs withdraw their LP Token​bTokens
and wTokens
held by the AMM on the LP's behalf. This function is useful for offchain clients to calculate value of the option tokens owed to the holder of lpTokenAmount
of LP Token.lpTokenAmount
is equal to 10% of the total supply of LP Token, then the return value of MinterAmm.getOptionTokensSaleValue
will be equal to the premiums for selling 10% of the bTokens
and wTokens
held by the AMM. See MinterAmm.bTokenGetCollateralOut
and MinterAmm.wTokenGetCollateralOut
for how to calculate the premiums when selling bTokens
and wTokens
.lpTokenAmount
lpTokenMinimum
argument to specify the minimum acceptable amount of LP Token the caller will receive, and any lower than this will cause the function call to revert.lpTokenMinimum
collateraAmount
of collateral tokenlpTokenAmount
of their LP Token and in exchange receives their pro-rata share of the AMM's tokens. For example, if lpTokenAmount
is equal to 10% of the total supply of LP Tokens, then the caller will receive 10% of the AMM's collateral token as well as 10% of each of the option tokens the AMM holds. If sellTokens
is set to true
, then the caller will receive only collateral token, because all of LP's option tokens will be sold to the AMM in exchange for collateral token. However, because of price impact the value of the collateral token the LP receives may be less than 10% of the AMM's total value.collateralMinimum
argument to specify the minimum acceptable amount of collateral token the caller will receive, and any lower than this will cause the function call to revert.lpTokenAmount
sellTokens
true
if the caller wishes to sell their option tokens to the AMM and only receive collateral token, and false
if they wish to receive less collateral token but receive their pro-rata share of the AMM's option tokens which they can sell at a later timecollateralMinimum
MinterAmm.claimExpiredTokens
​bTokens
and wTokens
held by the AMM. If the Series is out of the money then all bTokens
will be worthless, and the wTokens
will be claimed for the collateral value locked when minting them. If the Series is in the money then both the bTokens
and wTokens
will have some non-zero value.seriesId
bTokenAmount
of bToken
from the AMM, but will revert if the premium calculated by the AMM exceeds collateralMaximum
. The return value is the premium (in units of collateral token) the caller pays. Prior to calling this function, the caller must approve the AMM for the collateralMaximum
amount. See MinterAmm.bTokenGetCollateralIn
for how the AMM calculates the premium.seriesId
bTokenAmount
bToken
the caller wishes to purchasecollateralMaximum
bToken
. The actual premium can exceed this value due to slippage​bTokenAmount
of bToken
to the AMM, but will revert if the premium calculated by the AMM goes below collateralMinimum
. The return value is the premium (in units of collateral token) the caller receives. Prior to calling this function, the caller must approve the AMM for the bTokenAmount
. See MinterAmm.bTokenGetCollateralOut
for how the AMM calculates the premium.seriesId
bTokenAmount
bToken
the caller wishes to purchasecollateralMinimum
bToken
, The actual premium can go below this value due to slippage​wTokenAmount
of wToken
to the AMM, but will revert if the premium calculated by the AMM goes below collateralMinimum
. The return value is the premium (in units of collateral token) the caller receives. Prior to calling this function, the caller must approve the AMM for the wTokenAmount
. See MinterAmm.wTokenGetCollateralOut
for how the AMM calculates the premium.seriesId
wTokenAmount
wToken
the caller wishes to purchasecollateralMinimum
wToken
, The actual premium can go below this value due to slippage​MinterAmm.calcPrice
for how it is used._volatilityFactor
0.4 * implied_vol * sqrt(num_seconds_in_year)
MinterAmm
's logic contract. The SIREN protocol's contracts use the EIP-1822 standard for implementing upgradeable contracts. This allows us to update vulnerable contracts and keep users' option tokens safe. When the SIREN protocol has reached a certain level of stability, we can remove these safety guards and ensure no one on the Siren team can swap out the smart contract functionality._newImplementation
MinterAmm
's function implementationsnewOwner
address. See the onlyOwner
modifier for the permissions granted to the protocol admin.newOwner
wToken
because of a technical blocker in the SIREN protocol's Black-Scholes approximation algorithm. The algorithm over-prices bToken
's and underprices wToken
's, and so if the AMM were to sell wToken
's then through arbitrage the AMM would quickly be drained of all wToken
's. For that reason, we cannot add functionality for selling wToken
's to the AMM