SeriesController
implements all of the logic involving the lifecycle of option tokens. It uses the ISeriesController.Series
struct to represent all option series.SeriesController.mintOptions
can be used to mint onchain Call and Put options. The call to SeriesController.mintOptions
locks X
amount of collateral token to a Series and in return mints X
bToken
and X
wToken
to the caller. This bToken
can then be sold at its premium to those wishing to purchase ERC20
options, and if after expiry the Series is in the money then the bToken
can be redeemed for a portion of the Series'
locked collateral. The wToken
can be kept until the Series expires at which point the remaining locked collateral can be claimed. The SeriesController
exposes functions for redeeming the bToken
(SeriesController.exerciseOption
) and wToken
(SeriesController.claimCollateral
).X
bToken
+ X
wToken
is worth X
collateral token [^1], there is a function SeriesController.closePosition
which acts like the inverse of SeriesController.mintOptions
; X
bToken
+ X
wToken
can be burned in return for the X
collateral token locked in the Series.updateImplementation
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.SeriesController.createSeries
. Each Series uses a monotonically incrementing uint64
as an index into the array of Series. To read the fields of any single Series struct, use the series
function.SeriesController
's ERC1155Controller
. This is the contract that implements all of the ERC1155
token functions.8
, which is the number of leading 0's in all of the oracle price values used by the SeriesController
. More specifically, all of the current market prices returned by SeriesController.getSettlementPrice
and SeriesController.getCurrentPrice
use 8
leading decimals. For example, if the current price of WBTC
[TODO glossary] is $34,000, then the value returned by SeriesController.getCurrentPrice
for a WBTC
Call Series would be 34_000 * 1e8
.block.timestamp
. If block.timestamp
is before the Series' expiration date, then it is in the state OPEN
, otherwise it is in the state EXPIRED
. Only certain functions can be executed when the state is OPEN
, and some only when the state is EXPIRED
.seriesId
seriesId
bToken
, claiming `wToken, or closing a position.amount
basisPoints
_bTokenAmount
of this Series's bToken
, as well as the exercise fee, both in units of collateral token. See the documentation section on [protocol math](TODO point to this) for how the exercise payout is calculated.SeriesController.exerciseOption](#exerciseOption) so you can see what the payout will be prior to exercising the
bToken`._seriesId
_bTokenAmount
buyerShare
feeAmount
_wTokenAmount
of this Series's wToken
, as well as the exercise fee, both in units of collateral token. See the documentation section on [protocol math](TODO point to this) for how the claim payout is calculated._seriesId
_wTokenAmount
writerShare
feeAmount
bToken
holder's option is ITM, and for Puts this is the price below which the bToken
holder's option is ITM. The strike price always has 8 decimals. For example, a strikePrice
of 3400000000000
indicates the price is $34,000._seriesId
OPEN
state and can mint options and close positions, but cannot redeem option tokens. At and after this date the Series is in the EXPIRED
state and can redeem option tokens, but can no longer mint or close out positions._seriesId
ERC20
token whose price determines the (glossary.md#moneyness) of the Series. 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 is a Call Series then this will be the same token as the collateralToken._seriesId
ERC20
token used to denominate the strike price. This will almost always be USDC, but in the future could be different if we want to denominate prices in something other than USDC. If this a Put Series then this will be the same token as the collateralToken​_seriesId
ERC20
token used to underwrite this Series'
option positions. This token will be used to denominate all option prices in the MinterAmm
​_seriesId
ERC1155
token index of the wToken
for this Series. This index can then be used on the ERC1155Controller
to query for wToken
balances._seriesId
_seriesId
ERC1155
token index of the bToken
for this Series. This index can then be used on the ERC1155Controller
to query for bToken
balances._seriesId
_seriesId
SeriesController.mintOptions
and decreases with every call to SeriesController.exerciseOption
, SeriesController.claimCollateral
, and SeriesController.closePosition
. This function is also useful for calculating part of the TVL (Total Value Locked) in the protocol._seriesId
_optionTokenAmount
of option tokens. For Call options this is simply equal to _optionTokenAmount
; 1 bToken
or 1 wToken
are backed by 1 collateral token. However, for Puts it's slightly more complicated. Because a Put option gives the bToken
holder the right to sell the underlying token at the strike price, 1 bToken
or 1 wToken
must be backed by 1 * strike_price * decimals_coefficient
amount of collateral token. The decimals_coefficient
is term which divides out the price token and underlying token decimals, leaving only the correct decimals of the collateral token remaining._seriesId
_optionTokenAmount
wToken
or bToken
0
if it has not been set yet. A Series' settlement price is set by an offchain bot as soon as that Series expires. The settlement price will have 8 decimals, and use the same units as the priceToken. For example, if the settlement price of a certain Series is $34,000, then settlement_price = 34_000 * 1e8
.0
if the current block timestamp is prior to the Series expiration date. It's also possible the settlement date will be equal to 0
for a small amount of time (1-15 minutes) after the expiration date. This is because the EVM does not provide any functionality for automatically calling contract functions on a predefined schedule (such as cron), and so an offchain process must send a transaction calling PriceOracle.setSettlementPrice
and set the current underlying token's price manually. The EVM gives no guarantees on when a transaction will be included in the blockchain, so the protocol cannot guarantee the settlement price will be set exactly at the Series' expiration date._seriesId
isSet
settlementPrice
WBTC
[TODO glossary] was $34,000, then the value returned by SeriesController.getCurrentPrice
for a WBTC
Series would be 34_000 * 1e8
. This price is fetched via the PriceOracle
, which in turn fetches it from an onchain oracle.underlyingToken
ERC20
tokenpriceToken
ERC20
tokenonlyOwner
modifier so it can only be called by the protocol admins.ERC20
token the Series will be for (i.e. the token whose price movements will determine the long and short payouts). The priceToken will be the token used to denominate the price in (e.g. for a WBTC option denominated in USDC, the underlying token will be WBTC and the price token will be USDC, but for a WBTC option denominated in ETH, the underlying token will be WBTC and the price token will be ETH). The collateralToken determines the ERC20
token used to underwrite the covered options. For Put options the collateralToken
must be equal to the priceToken
, and for Call options the collateralToken
must be equal to the underlyingToken
._tokens
underlyingToken
, priceToken
, and collateralToken
for these Series_expirationDates
_restrictedMinters
MinterAmm
addresses which will be the only AMM's permitted to mint option tokens for these Series_optionTokenAmount
amount of a given Series's wTokens
and bTokens
by locking collateral in that Series. The option tokens are transferred to the caller. One of the fundamental formulas for the SIREN protocol is:X collateralToken ==> X wToken and X bToken
X
amount of collateral token a minter locks in the protocol, the minter receives X
amount of wToken
and X
amount of bToken
.SeriesController.getCollateralPerOptionToken
for more details on computing the exact amount of collateral needed to mint a given amount of option tokens.seriesId
_optionTokenAmount
wTokens
or bTokens
to mint_bTokenAmount
amount of bToken
and transfers the bToken
's payout to the caller. The SIREN protocol are cash-settled, so the payout for bTokens
is calculated as some fraction of the collateral token locked in the Series. The payout of the bToken
depends on the Series' strike price and the price of the underlying token. For Puts, the payout increases as the underlying token's price decreases and for Calls the payout increases as the underlying tokne's price increases. See the section [Protocol Math](TODO link) for the details on how the protocol calculates bToken
payout.seriesId
_bTokenAmount
bTokens
to exercise_revertOtm
true
if you want this function call to revert if the Series is OTM, false
if you want it to continue executing even if it's OTM. Passing true
will save gas but will require the calling context to handle the error (possibly resulting in the entire transaction reverting). Passing false
will use more gas, but will effectively be a no-op and preclude the calling context from worrying about their transaction reverting_wTokenAmount
amount of wToken
and transfers the wToken
's payout to the caller. The SIREN protocol are cash-settled, so the payout for wTokens
is calculated as some fraction of the collateral token locked in the Series. The payout of the wToken
depends on the Series' strike price and the price of the underlying token. For Puts, the payout decreases as the underlying token's price decreases and for Calls the payout decreases as the underlying token's price increases. See the section [Protocol Math](TODO link) for the details on how the protocol calculates wToken
payout.seriesId
_wTokenAmount
_optionTokenAmount
amount of wToken
and bToken
, then transfers the equivalent amount of collateral token to the caller. For Calls the amount of collateral token received will be equal to _optionTokenAmount
, and for Puts the amount of collateral token received will be equal to _optionTokenAmount * strikePrice
(see the getCollateralPerOptionToken function for more details on this calculations).closePosition
but you still want your collateral, you can call exerciseOption and claimCollateral to convert your bToken
and wToken
to collateral token.seriesId
_optionTokenAmount
SeriesController
'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 LP's liquidity and the collateral locked in Series 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
SeriesController
's function implementations_newAdmin
address. See the onlyOwner
modifier for the permissions granted to the protocol admin._newAdmin