Search
K

LiquidityPool.sol

General Overview

The Liquidity Pool holds most core functionality for the Rysk Dynamic Hedging Vault, it is responsible for managing all funds. It uses several libraries and contracts which have been explained in other docs.
Throughout the contract there are conversions between decimals, there are three decimals to be aware of e6 (USDC decimals) or collateral decimals, e8 otoken decimals and e18 share value, eth, and options calculation decimals. Where each decimal type is used is commented in each function.

Oracle use

The contract uses Chainlink Price feed oracles. The contract also makes use of the Portfolio values feed request response oracle and may in the future make use of a volatility feed oracle. These are documented in the oracle documentation.

Descriptions

Most variables and functions if not mentioned here can be fully explained by their natspec in the contracts so have been left out

hedgingReactors

This variable is an array that stores hedging reactor addresses. Each hedging reactor can be referenced by its index in rebalancePortfolioDelta or each hedging reactor is referenced by iterating over the array, for example in completeWithdraw() or getPortfolioDelta(). When a hedging reactor is added it is added to the last place of the array, when removed the array should be shifted so as not to leave any array elements as zero addresses.

pauses

There is pause and unpause functionality which pauses all state changing functionality. There is also pause and unpause trading which pauses any options buying or selling activity from the pool. This pause functionality can be executed by Guardians or above.

optionParams

This is a struct that contains variables that pertain to the min and max call strike which are the minimum and maximum strikes that can be written for calls by the pool and the min and max put strikes. The min and max expiry are also stored which are the minimum and maximum length options that the pool can write. These variables can be updated by management or above and helps with managing pool exposure depending on the market outlook.

max price and time deviation thresholds

These values are used to set the time and price thresholds for when an oracle update becomes stale. For example, if an oracle update was done at 600 and the threshold is 10 if the time is now 611 the oracle update is stale and the pool will not do anything until the oracle is updated again. This is to deal with the value of the pool changing due to price and time movement and thus the liability value and delta value being off.

handler

These are contracts that have the authority to issue, write, and buyback options from the liquidityPool. They must be authorised. This architecture allows for multiple handlers and upgradeability on the handlers.

Mutual fund system (deposit(), redeem(), initiateWithdraw(), completeWithdraw(), pauseTradingAndRequest(), executeEpochCalculations())

An explainer of the mutual fund system or how deposits/withdraws/redeems/pauseTradingAndRequest and executeEpochCalculation work can be seen here: Deposit and Withdraw Mechanism

rebalancePortfolioDelta()

This function uses hedging reactors to hedge off a specified delta. The manager (or above) will specify the delta to hedge and the index of the reactor in the hedgingReactors array. The hedging reactor can be anything that implements the IHedgingReactor interface, it is used for accessing alternate derivatives that can be used for delta hedging. Currently only spot and perps are implemented but any derivative or asset can be implemented in the future.

adjustCollateral()

This function is used by the option registry to update the collateralAllocated in the LiquidityPool when funds are moved around. If the option registry is moving funds back into the LiquidityPool then it will decrease collateralAllocated. If the option registry is moving funds from the LiquidityPool then it will get a safe approval and will increase the collateralAllocated. Collateral allocated should never drop below negative because the balance of option registry should not go up beyond what it is allocated (because it generates no profits from providing collateral)(it can only go down, say if an option gets exercised).

settleVault()

This function is used to settle a vault and move collateral between the registry and the vault when an option expires.

getPortfolioDelta()

This function is used to get the portfolio delta. This first retrieves the delta from the portfolio value feed oracle (making sure it isnt stale), it then gets the delta from all hedging reactors finally it gets the ephemeralDelta that has been recorded between a request and response.

Normal Distribution approximation library

Reference for implementation:

Black scholes library

Reference for implementation:
Contract used as the Dynamic Hedging Vault for storing funds, issuing shares and processing options transactions
Interacts with the OptionRegistry for options behaviour, Interacts with hedging reactors for alternative derivatives Interacts with Handlers for periphary user options interactions. Interacts with Chainlink price feeds throughout. Interacts with Volatility Feed via getImpliedVolatility(), interacts with a chainlink PortfolioValues external adaptor oracle via PortfolioValuesFeed.
immutable variables ///

protocol

contract Protocol protocol

strikeAsset

address strikeAsset

underlyingAsset

address underlyingAsset

collateralAsset

address collateralAsset

collateralAllocated

uint256 collateralAllocated
dynamic variables ///

ephemeralLiabilities

int256 ephemeralLiabilities

ephemeralDelta

int256 ephemeralDelta

depositEpoch

uint256 depositEpoch

withdrawalEpoch

uint256 withdrawalEpoch

depositEpochPricePerShare

mapping(uint256 => uint256) depositEpochPricePerShare

withdrawalEpochPricePerShare

mapping(uint256 => uint256) withdrawalEpochPricePerShare

depositReceipts

mapping(address => struct IAccounting.DepositReceipt) depositReceipts

withdrawalReceipts

mapping(address => struct IAccounting.WithdrawalReceipt) withdrawalReceipts

pendingDeposits

uint256 pendingDeposits

pendingWithdrawals

uint256 pendingWithdrawals

partitionedFunds

uint256 partitionedFunds

bufferPercentage

uint256 bufferPercentage
governance settable variables ///

hedgingReactors

address[] hedgingReactors

collateralCap

uint256 collateralCap

maxDiscount

uint256 maxDiscount

bidAskIVSpread

uint256 bidAskIVSpread

optionParams

struct Types.OptionParams optionParams

riskFreeRate

uint256 riskFreeRate

handler

mapping(address => bool) handler

isTradingPaused

bool isTradingPaused

maxTimeDeviationThreshold

uint256 maxTimeDeviationThreshold

maxPriceDeviationThreshold

uint256 maxPriceDeviationThreshold

belowThresholdGradient

uint256 belowThresholdGradient

aboveThresholdGradient

uint256 aboveThresholdGradient

aboveThresholdYIntercept

uint256 aboveThresholdYIntercept

utilizationFunctionThreshold

uint256 utilizationFunctionThreshold

keeper

mapping(address => bool) keeper

MAX_BPS

uint256 MAX_BPS
constant variables ///

DepositEpochExecuted

event DepositEpochExecuted(uint256 epoch)
structs && events ///

WithdrawalEpochExecuted

event WithdrawalEpochExecuted(uint256 epoch)

Withdraw

event Withdraw(address recipient, uint256 amount, uint256 shares)

Deposit

event Deposit(address recipient, uint256 amount, uint256 epoch)

Redeem

event Redeem(address recipient, uint256 amount, uint256 epoch)

InitiateWithdraw

event InitiateWithdraw(address recipient, uint256 amount, uint256 epoch)

WriteOption

event WriteOption(address series, uint256 amount, uint256 premium, uint256 escrow, address buyer)

SettleVault

event SettleVault(address series, uint256 collateralReturned, uint256 collateralLost, address closer)

BuybackOption

event BuybackOption(address series, uint256 amount, uint256 premium, uint256 escrowReturned, address seller)

constructor

constructor(address _protocol, address _strikeAsset, address _underlyingAsset, address _collateralAsset, uint256 rfr, string name, string symbol, struct Types.OptionParams _optionParams, address _authority) public

pause

function pause() external
setters ///

pauseUnpauseTrading

function pauseUnpauseTrading(bool _pause) external

unpause

function unpause() external

setHedgingReactorAddress

function setHedgingReactorAddress(address _reactorAddress) external
set a new hedging reactor
only governance can call this function
Name
Type
Description
_reactorAddress
address
append a new hedging reactor

removeHedgingReactorAddress

function removeHedgingReactorAddress(uint256 _index, bool _override) external
remove a new hedging reactor by index
only governance can call this function
Name
Type
Description
_index
uint256
remove a hedging reactor
_override
bool
whether to override whether the reactor is wound down (THE REACTOR SHOULD BE WOUND DOWN SEPERATELY)

setNewOptionParams

function setNewOptionParams(uint128 _newMinCallStrike, uint128 _newMaxCallStrike, uint128 _newMinPutStrike, uint128 _newMaxPutStrike, uint128 _newMinExpiry, uint128 _newMaxExpiry) external
update all optionParam variables for max and min strikes and max and min expiries for options that the DHV can issue
only management or above can call this function

setBidAskSpread

function setBidAskSpread(uint256 _bidAskSpread) external
set the bid ask spread used to price option buying
only management or above can call this function
Name
Type
Description
_bidAskSpread
uint256
the bid ask spread to update to

setMaxDiscount

function setMaxDiscount(uint256 _maxDiscount) external
set the maximum percentage discount for an option
only management or above can call this function
Name
Type
Description
_maxDiscount
uint256
of the option as a percentage in 1e18 format. ie: 1*e18 == 1%

setCollateralCap

function setCollateralCap(uint256 _collateralCap) external
set the maximum collateral amount allowed in the pool
only governance can call this function
Name
Type
Description
_collateralCap
uint256
of the collateral held

setBufferPercentage

function setBufferPercentage(uint256 _bufferPercentage) external
update the liquidity pool buffer limit
only governance can call this function
Name
Type
Description
_bufferPercentage
uint256
the minimum balance the liquidity pool must have as a percentage of collateral allocated to options. (for 20% enter 2000)

setRiskFreeRate

function setRiskFreeRate(uint256 _riskFreeRate) external
update the liquidity pool risk free rate
Name
Type
Description
_riskFreeRate
uint256
the risk free rate of the market

setMaxTimeDeviationThreshold

function setMaxTimeDeviationThreshold(uint256 _maxTimeDeviationThreshold) external
update the max oracle time deviation threshold

setMaxPriceDeviationThreshold

function setMaxPriceDeviationThreshold(uint256 _maxPriceDeviationThreshold) external
update the max oracle price deviation threshold

changeHandler

function changeHandler(address _handler, bool auth) external
change the status of a handler

setKeeper

function setKeeper(address _keeper, bool _auth) external
change the status of a keeper

setUtilizationSkewParams

function setUtilizationSkewParams(uint256 _belowThresholdGradient, uint256 _aboveThresholdGradient, uint256 _utilizationFunctionThreshold) external
@notice sets the parameters for the function that determines the utilization price factor The function is made up of two parts, both linear. The line to the left of the utilisation threshold has a low gradient while the gradient to the right of the threshold is much steeper. The aim of this function is to make options much more expensive near full utilization while not having much effect at low utilizations. @param _belowThresholdGradient the gradient of the function where utiization is below function threshold. e18 @param _aboveThresholdGradient the gradient of the line above the utilization threshold. e18 @param _utilizationFunctionThreshold the percentage utilization above which the function moves from its shallow line to its steep line

rebalancePortfolioDelta

function rebalancePortfolioDelta(int256 delta, uint256 reactorIndex) external
function for hedging portfolio delta through external means
Name
Type
Description
delta
int256
the current portfolio delta
reactorIndex
uint256
the index of the reactor in the hedgingReactors array to use

adjustCollateral

function adjustCollateral(uint256 lpCollateralDifference, bool addToLpBalance) external
adjust the collateral held in a specific vault because of health
called by the option registry only
Name
Type
Description
lpCollateralDifference
uint256
amount of collateral taken from or given to the liquidity pool in collateral decimals
addToLpBalance
bool
true if collateral is returned to liquidity pool, false if collateral is withdrawn from liquidity pool

settleVault

function settleVault(address seriesAddress) external returns (uint256)
closes an oToken vault, returning collateral (minus ITM option expiry value) back to the pool
Name
Type
Description
seriesAddress
address
the address of the oToken vault to close
Name
Type
Description
[0]
uint256
collatReturned the amount of collateral returned to the liquidity pool, assumes in collateral decimals

handlerIssue

function handlerIssue(struct Types.OptionSeries optionSeries) external returns (address)
issue an option
only callable by a handler contract
Name
Type
Description
optionSeries
struct Types.OptionSeries
the series detail of the option - strike decimals in e18

handlerWriteOption

function handlerWriteOption(struct Types.OptionSeries optionSeries, address seriesAddress, uint256 amount, contract IOptionRegistry optionRegistry, uint256 premium, int256 delta, address recipient) external returns (uint256)
write an option that already exists
only callable by a handler contract
Name
Type
Description
optionSeries
struct Types.OptionSeries
the series detail of the option - strike decimals in e8
seriesAddress
address
the series address of the oToken
amount
uint256
the number of options to write - in e18
optionRegistry
contract IOptionRegistry
the registry used for options writing
premium
uint256
the premium of the option - in collateral decimals
delta
int256
the delta of the option - in e18
recipient
address
the receiver of the option

handlerIssueAndWriteOption

function handlerIssueAndWriteOption(struct Types.OptionSeries optionSeries, uint256 amount, uint256 premium, int256 delta, address recipient) external returns (uint256, address)
write an option that doesnt exist
only callable by a handler contract
Name
Type
Description
optionSeries
struct Types.OptionSeries
the series detail of the option - strike decimals in e18
amount
uint256
the number of options to write - in e18
premium
uint256
the premium of the option - in collateral decimals
delta
int256
the delta of the option - in e18
recipient
address
the receiver of the option

handlerBuybackOption

function handlerBuybackOption(struct Types.OptionSeries optionSeries, uint256 amount, contract IOptionRegistry optionRegistry, address seriesAddress, uint256 premium, int256 delta, address seller) external returns (uint256)
buy back an option that already exists
only callable by a handler contract
Name
Type
Description
optionSeries
struct Types.OptionSeries
the series detail of the option - strike decimals in e8
amount
uint256
the number of options to buyback - in e18
optionRegistry
contract IOptionRegistry
the registry used for options writing
seriesAddress
address
the series address of the oToken
premium
uint256
the premium of the option - in collateral decimals
delta
int256
the delta of the option - in e18
seller
address
the receiver of the option

resetEphemeralValues

function resetEphemeralValues() external
reset the temporary portfolio and delta values that have been changed since the last oracle update
only callable by the portfolio values feed oracle contract

pauseTradingAndRequest

function pauseTradingAndRequest() external returns (bytes32)
reset the temporary portfolio and delta values that have been changed since the last oracle update
this function must be called in order to execute an epoch calculation

executeEpochCalculation

function executeEpochCalculation() external
execute the epoch and set all the price per shares
this function must be called in order to execute an epoch calculation and batch a mutual fund epoch

deposit

function deposit(uint256 _amount) external returns (bool)
function for adding liquidity to the options liquidity pool
entry point to provide liquidity to dynamic hedging vault
Name
Type
Description
_amount
uint256
amount of the strike asset to deposit
Name
Type
Description
[0]
bool
success

redeem

function redeem(uint256 _shares) external returns (uint256)
function for allowing a user to redeem their shares from a previous epoch
Name
Type
Description
_shares
uint256
the number of shares to redeem
Name
Type
Description
[0]
uint256
the number of shares actually returned

initiateWithdraw

function initiateWithdraw(uint256 _shares) external
function for initiating a withdraw request from the pool
entry point to remove liquidity to dynamic hedging vault
Name
Type
Description
_shares
uint256
amount of shares to return

completeWithdraw

function completeWithdraw(uint256 _shares) external returns (uint256)
function for completing the withdraw from a pool
entry point to remove liquidity to dynamic hedging vault
Name
Type
Description
_shares
uint256
amount of shares to return

_getNormalizedBalance

function _getNormalizedBalance(address asset) internal view returns (uint256 normalizedBalance)
Returning balance in 1e18 format
Name
Type
Description
asset
address
address of the asset to get balance and normalize
Name
Type
Description
normalizedBalance
uint256
balance in 1e18 format

getBalance

function getBalance(address asset) public view returns (uint256)
Returning balance in 1e6 format
Name
Type
Description
asset
address
address of the asset to get balance
Name
Type
Description
[0]
uint256
balance of the address accounting for partitionedFunds

getExternalDelta

function getExternalDelta() public view returns (int256 externalDelta)
get the delta of the hedging reactors
Name
Type
Description
externalDelta
int256
hedging reactor delta in e18 format

getPortfolioDelta

function getPortfolioDelta() public view returns (int256)
get the delta of the portfolio
Name
Type
Description
[0]
int256
portfolio delta

quotePriceWithUtilizationGreeks

function quotePriceWithUtilizationGreeks(struct Types.OptionSeries optionSeries, uint256 amount, bool toBuy) external view returns (uint256 quote, int256 delta)
get the quote price and delta for a given option
Name
Type
Description
optionSeries
struct Types.OptionSeries
option type to quote - strike assumed in e18
amount
uint256
the number of options to mint - assumed in e18
toBuy
bool
whether the protocol is buying the option
Name
Type
Description
quote
uint256
the price of the options - returns in e18
delta
int256
the delta of the options - returns in e18

addUtilizationPremium

function addUtilizationPremium(struct Types.UtilizationState quoteState, struct Types.OptionSeries optionSeries, uint256 amount, bool toBuy) internal view
applies a utilization premium when the protocol is selling options. Stores the utilization price in quoteState.utilizationPrice for use in quotePriceWithUtilizationGreeks
Name
Type
Description
quoteState
struct Types.UtilizationState
the struct created in quoteStateWithUtilizationGreeks to store memory variables
optionSeries
struct Types.OptionSeries
the option type for which we are quoting a price
amount