OptionRegistry.sol

OptionRegistry

This contract is responsible for handling all functionality pertaining to interaction with the opyn option protocol, storing the information about options series and conducting collateral management logic of partially collateralised vaults. The pool uses partial collateralisation which means that options contracts can be undercollateralised this means much better capital efficiency but also introduces margin risk, this is managed by holding a margin buffer in the LiquidityPool that can be used for managing collateral. For documentation on opyns partial liquidation system see: https://medium.com/opyn/partially-collateralized-options-now-in-defi-b9d223eb3f4d opyn-rysk gamma protocol This contract essentially gets infinite approval rights from the LiquidityPool.

Contract used for conducting options issuance and settlement as well as collateral management

Interacts with the opyn-rysk gamma protocol via OpynInteractions for options activity. Interacts with the liquidity pool for collateral and instructions.

Oracle use

The library does not directly use oracles, the opyn-rysk gamma protocol uses chainlink oracles for options pricing.

Function by Function

issue(Types.OptionSeries memory optionSeries) external onlyLiquidityPool returns address Indirect NonTrustedAccessible

This function creates an oToken series via OpynInteractions and stores the identity of this oToken in the option registry without minting a short position. The strike is passed in as e18 decimals and converted with formatStrikePrice() in order to make it compatible with opyn's e18 decimals. It is stored with opyn's decimals. This function is called via the LiquidityPool only.

open(address _series, uint256 amount, uint256 collateralAmount) external onlyLiquidityPool returns bool, uint256 Indirect NonTrustedAccessible

This function mints a short position for an oToken that has been "issued" by the option registry. If it has not been issued then it will not be minted. This contract will retrieve the seriesInfo from the registry, then will retrieve the opyn-rysk vault id for this series if it exists. If it does not exist then a new vault id will be created. A short is created via OpynInteractions to the options registry which is then transferred to the LiquidityPool. This function is called via the LiquidityPool only.

close(address _series, uint amount) external onlyLiquidityPool returns bool, uint256 Indirect NonTrustedAccessible

This function closes a short position that was "issued" by the option registry and a vault already exists (it does not have to be opened by the option registry, but an option of this series has to have been minted at some point). It closes the oToken via OpynInteractions after transferring the oToken from the liquidity pool to the registry. After the close it will return any redeemed collateral to the liquidity pool. It makes sure the oToken can be closed (i.e. if it hasnt already expired).

redeem(address _series) external returns uint256 Direct NonTrustedAccessible

This function interacts with Gamma protocol to "redeem" any oToken. This means that it burns the oToken and returns the option value to the sender after it has expired.

settle(address _series) external onlyLiquidityPool returns bool, uint256, uint256, uint256

This function settles a vault that the registry owns. It can only occur after expiry. All funds are sent back to the liquidityPool. This function can only be called via the liquidity pool which can only be called by a trusted party.

adjustCollateral(uint256 vaultId) external onlyRole(ADMIN_ROLE)

This function checks the vault health by calling checkVaultHealth. If the vault is undercollateralised then the function calls adjustCollateral in the liquidity pool to request collateral extraction approval, This collateral is then transferred into the OptionRegistry from the LiquidityPool and deposited into the vault via OpynInteractions depositCollat. If the vault is above its upper collateral factor then it is over collateralised so funds are withdrawn from the vault and transferred to the liquidityPool, this is reflected in the liquidityPool again.

adjustCollateralCaller(uint256 vaultId) external onlyRole(ADMIN_ROLE)

This function allows a trusted caller to collateralise a vault if it is undercollateralised using their own funds. This is done in emergency scenarios where the liquidity pool has insufficient funds to cover collateralisation.

wCollatLiquidatedVault(uint256 vaultId) external onlyRole(ADMIN_ROLE)

If a vault gets liquidated all collateral will have been lost. This function exists just in case there is some dust collateral left in a vault after a liquidation occurs. It adjusts the collateralAllocated in the liquidityPool.

registerLiquidatedVault(uint256 vaultId) external onlyRole(ADMIN_ROLE)

This function is used to tell that LiquidityPool that a liquidation of a vault controlled by the optionRegistry has happened. It checks the vaultLiquidationDetails, if there is a liquidation it will reflect this in the liquidityPool via collateralAllocated. It will then clear these liquidation details so that liquidations dont get double counted accidentally.

setLiquidityPool() external onlyOwner

This function sets the liquidity pool that is used for collateral transfer, oToken transfers and liquidity pool accessable functionality.

setHealthThresholds() external onlyOwner

This function sets the upper and lower health factors for partially collateralised put and call vaults. If below the thresholds then the vault will need more collateral, if above you can remove collateral if between then leave the collateral as is.

getCollateral(Types.OptionSeries memory series, uint256 amount) external view returns uint256 View

This functon gets the required collateral for the option series passed in and an amount. It then multiplies this by the upper health factor to get the safe amount of collateral to maintain the margin balance.

getOtoken( address underlying, address strikeAsset, uint256 expiration,bool isPut, uint256 strike, address collateral) external view returns address View

This function returns an oToken from the opyn-rysk gamma otoken factory. If the otoken does not exist then it returns the zero address. The strike is passed in in oToken (e8) decimals.

checkVaultHealth(uint256 vaultId) public view returns (bool isBelowMin, bool isAboveMax, uint256 healthFactor, uint256 upperHealthFactor, uint256 collatRequired, address collatAsset) View

This function checks the margin health of a specific vault and returns whether the vault is under or over collateralised and if so how much it is over/under by. Since all vaults use Opyn's partial collateralisation mechanism it means that they require collateral/margin management. The function starts by retrieving the vault from the opyn controller. Then searching for that series in the registry. Then the required collateral for that vault is retrieved from opyn's margin calculator and the collateral in the vault is retrieved. The health factor is calculated as (collatAmount * MAX_BPS) / marginReq. This health factor is then compared to the desired health factor. If it is above the healthFactor is above upperHealthFactor then the registry tells the caller that the vault is overcollateralised and the amount that should be withdrawn, If the opposite is true then the registry tells the caller that the vault is undercollateralised and the amount that should be deposited to return to the upperHealthFactor.

getSeriesAddress(bytes32 issuanceHash) external view returns (address) View

This function gets a series address that has been issued by the registry using an issuance hash

getSeries(Types.OptionSeries memory _series) external view returns (address) View

This function takes in an address then searches the seriesInfo[] mapping in the contract to retrieve the OptionSeries struct for that series address.

getSeriesInfo(address series) external view returns (Types.OptionSeries memory) View

This function takes in an address then searches the seriesInfo[] mapping in the contract to retrieve the OptionSeries struct for that series address, these will match opyn's records.

getIssuanceHash(Types.OptionSeries memory _series) public pure returns (bytes32) View

This function gets the issuance hash of the input value which should be an OptionSeries struct. This hash is used for series storage.

getIssuanceHash(address underlying, address strikeAsset, address collateral, uint expiration, bool isPut, uint strike) internal pure returns(bytes32) View

This function gets the issuance hash of the input values. This hash is used for series storage

formatStrikePrice(uint256 strikePrice, address collateral) public view returns (uint) View

This function converts an e18 strike price to e8 strike price, making sure to round down to deal with any rounding issue on the gamma protocol side of things.

oTokenFactory

address oTokenFactory

immutable variables ///

gammaController

address gammaController

collateralAsset

address collateralAsset

addressBook

contract AddressBookInterface addressBook

marginPool

address marginPool

seriesInfo

mapping(address => struct Types.OptionSeries) seriesInfo

dynamic variables ///

vaultIds

mapping(address => uint256) vaultIds

seriesAddress

mapping(bytes32 => address) seriesAddress

vaultCount

uint64 vaultCount

liquidityPool

address liquidityPool

governance settable variables ///

callUpperHealthFactor

uint64 callUpperHealthFactor

callLowerHealthFactor

uint64 callLowerHealthFactor

putUpperHealthFactor

uint64 putUpperHealthFactor

putLowerHealthFactor

uint64 putLowerHealthFactor

keeper

mapping(address => bool) keeper

MAX_BPS

uint256 MAX_BPS

constant variables ///

SCALE_FROM

uint256 SCALE_FROM

OPYN_DECIMALS

uint8 OPYN_DECIMALS

OptionTokenCreated

event OptionTokenCreated(address token)

events && errors && modifiers ///

SeriesRedeemed

event SeriesRedeemed(address series, uint256 underlyingAmount, uint256 strikeAmount)

OptionsContractOpened

event OptionsContractOpened(address series, uint256 vaultId, uint256 optionsAmount)

OptionsContractClosed

event OptionsContractClosed(address series, uint256 vaultId, uint256 closedAmount)

OptionsContractSettled

event OptionsContractSettled(address series, uint256 collateralReturned, uint256 collateralLost, uint256 amountLost)

VaultLiquidationRegistered

event VaultLiquidationRegistered(address series, uint256 vaultId, uint256 amountLiquidated, uint256 collateralLiquidated)

NoVault

error NoVault()

NotKeeper

error NotKeeper()

NotExpired

error NotExpired()

HealthyVault

error HealthyVault()

AlreadyExpired

error AlreadyExpired()

NotLiquidityPool

error NotLiquidityPool()

NonExistentSeries

error NonExistentSeries()

InvalidCollateral

error InvalidCollateral()

VaultNotLiquidated

error VaultNotLiquidated()

InsufficientBalance

error InsufficientBalance()

constructor

constructor(address _collateralAsset, address _oTokenFactory, address _gammaController, address _marginPool, address _liquidityPool, address _addressBook, address _authority) public

setLiquidityPool

function setLiquidityPool(address _newLiquidityPool) external

Set the liquidity pool address

Name	Type	Description
_newLiquidityPool	address	set the liquidityPool address

setKeeper

function setKeeper(address _target, bool _auth) external

Set or revoke a keeper

Name	Type	Description
_target	address	address to become a keeper
_auth	bool	accept or revoke

setHealthThresholds

function setHealthThresholds(uint64 _putLower, uint64 _putUpper, uint64 _callLower, uint64 _callUpper) external

Set the health thresholds of the pool

Name	Type	Description
_putLower	uint64	the lower health threshold for puts
_putUpper	uint64	the upper health threshold for puts
_callLower	uint64	the lower health threshold for calls
_callUpper	uint64	the upper health threshold for calls

issue

function issue(struct Types.OptionSeries optionSeries) external returns (address)

Either retrieves the option token if it already exists, or deploy it

Name	Type	Description
optionSeries	struct Types.OptionSeries	the series used for the mint - strike passed in as e18

Name	Type	Description
[0]	address	the address of the option

open

function open(address _series, uint256 amount, uint256 collateralAmount) external returns (bool, uint256)

Open an options contract using collateral from the liquidity pool

only callable by the liquidityPool

Name	Type	Description
_series	address	the address of the option token to be created
amount	uint256	the amount of options to deploy - assume in e18
collateralAmount	uint256	the collateral required for the option - assumes in collateral decimals

Name	Type	Description
[0]	bool	if the transaction succeeded
[1]	uint256	the amount of collateral taken from the liquidityPool

close

function close(address _series, uint256 amount) external returns (bool, uint256)

Close an options contract (oToken) before it has expired

only callable by the liquidityPool

Name	Type	Description
_series	address	the address of the option token to be burnt
amount	uint256	the amount of options to burn - assumes in e18

Name	Type	Description
[0]	bool	if the transaction succeeded
[1]	uint256

settle

function settle(address _series) external returns (bool, uint256, uint256, uint256)

Settle an options vault

callable by the liquidityPool so that local variables can also be updated

Name	Type	Description
_series	address	the address of the option token to be burnt

Name	Type	Description
[0]	bool	if the transaction succeeded
[1]	uint256	the amount of collateral returned from the vault
[2]	uint256	the amount of collateral used to pay ITM options on vault settle
[3]	uint256	number of oTokens that the vault was short

adjustCollateral

function adjustCollateral(uint256 vaultId) external

adjust the collateral held in a specific vault because of health

Name	Type	Description
vaultId	uint256	the id of the vault to check

adjustCollateralCaller

function adjustCollateralCaller(uint256 vaultId) external

adjust the collateral held in a specific vault because of health, using collateral from the caller. Only takes from msg.sender, doesnt give them if vault is above the max.

this is a safety function, if worst comes to worse any caller can collateralise a vault to save it.

Name	Type	Description
vaultId	uint256	the id of the vault to check

wCollatLiquidatedVault

function wCollatLiquidatedVault(uint256 vaultId) external

withdraw collateral from a fully liquidated vault

this is a safety function, if a vault is liquidated.

Name	Type	Description
vaultId	uint256	the id of the vault to check

registerLiquidatedVault

function registerLiquidatedVault(uint256 vaultId) external

register a liquidated vault so the collateral allocated is managed

this is a safety function, if a vault is liquidated to update the collateral assets in the pool

Name	Type	Description
vaultId	uint256	the id of the vault to register liquidation for

redeem

function redeem(address _series) external returns (uint256)

Redeem oTokens for the locked collateral

Name	Type	Description
_series	address	the address of the option token to be burnt and redeemed

Name	Type	Description
[0]	uint256	amount returned

getCollateral

function getCollateral(struct Types.OptionSeries series, uint256 amount) external view returns (uint256)

Send collateral funds for an option to be minted

series.strike should be scaled by 1e8.

Name	Type	Description
series	struct Types.OptionSeries	details of the option series
amount	uint256	amount of options to mint always in e18

Name	Type	Description
[0]	uint256	amount transferred

getOtoken

function getOtoken(address underlying, address strikeAsset, uint256 expiration, bool isPut, uint256 strike, address collateral) external view returns (address)

Retrieves the option token if it exists

Name	Type	Description
underlying	address	is the address of the underlying asset of the option
strikeAsset	address	is the address of the collateral asset of the option
expiration	uint256	is the expiry timestamp of the option
isPut	bool	the type of option
strike	uint256	is the strike price of the option - 1e18 format
collateral	address	is the address of the asset to collateralize the option with

Name	Type	Description
[0]	address	the address of the option

checkVaultHealth

function checkVaultHealth(uint256 vaultId) public view returns (bool isBelowMin, bool isAboveMax, uint256 healthFactor, uint256 upperHealthFactor, uint256 collatRequired, address collatAsset)

check the health of a specific vault to see if it requires collateral

Name	Type	Description
vaultId	uint256	the id of the vault to check

Name	Type	Description
isBelowMin	bool	bool to determine whether the vault needs topping up
isAboveMax	bool	bool to determine whether the vault is too overcollateralised
healthFactor	uint256	the health factor of the vault in MAX_BPS format
upperHealthFactor	uint256	the upper bound of the acceptable health facor range in MAX_BPS format
collatRequired	uint256	the amount of collateral required to return the vault back to normal
collatAsset	address	the address of the collateral asset

getSeriesAddress

function getSeriesAddress(bytes32 issuanceHash) external view returns (address)

non-complex getters ///

getSeries

function getSeries(struct Types.OptionSeries _series) external view returns (address)

getSeriesInfo

function getSeriesInfo(address series) external view returns (struct Types.OptionSeries)

getIssuanceHash

function getIssuanceHash(struct Types.OptionSeries _series) public pure returns (bytes32)

getIssuanceHash

function getIssuanceHash(address underlying, address strikeAsset, address collateral, uint256 expiration, bool isPut, uint256 strike) internal pure returns (bytes32)

Helper function for computing the hash of a given issuance.

formatStrikePrice

function formatStrikePrice(uint256 strikePrice, address collateral) public view returns (uint256)

Converts strike price to 1e8 format and floors least significant digits if needed

Name	Type	Description
strikePrice	uint256	strikePrice in 1e18 format
collateral	address	address of collateral asset

Name	Type	Description
[0]	uint256	if the transaction succeeded

_isLiquidityPool

function _isLiquidityPool() internal view

_isKeeper

function _isKeeper() internal view

keepers, managers or governors can access