System Architecture
The Lyra AMM operates in the Optimistic Ethereum environment, and is comprised of a number of smart contracts that operate together to match traders with LPs to provide traders with the ability to both buy and sell options to the AMM, as well as providing LPs a delta hedged platform to provide liquidity for both collateral and premiums for the options traded.
The system is comprised of 9 core contracts per market, including a replaceable PoolHedger and a SynthetixAdapter which controls logic for exchanging between quote and base assets.

Libraries

FixedPointMathLib

The FixedPointMathLib library implements ln and exp functions for decimals. It is a slightly modified version of the implementation found here.

BlackScholes

The BlackScholes library implements mathematical functions related to the computation of option prices using the BlackScholes pricing model. It implements both core mathematical functions (sqrt, stdNormal and stdNormalCDF) as well as functions specific to BlackScholes (d1d2, optionPrices, delta, vega). Beyond that, it also implements a standardised Vega (stdVega) function, as described in the whitepaper.

GWAV

The GWAV (Geometric Time-Weighted Average Volatility) library implements logic for recording periodic changes to a value and querying the GWAV for any two timestamps. More information on how the GWAV function computes time weighted geometric values can be found here.

Protocol Contracts

LiquidityPool

Allows users to deposit quote asset (sUSD) to receive a LiquidityTokens - an ERC20 which represents a share of the LP. These funds are used both as collateral/premium for the options in OptionMarket and for hedging risk in PoolHedger.
Liquidity Tokens
For accounting reasons, we use a concept of a "TokenPrice" which is the value of liquidity in relation to the rest of the pool. A Token is a share of the entire pool, as such the price of a "token" is:
tokenPrice = poolValueQuote / tokenTotalSupply
As this definition requires pool value/tokens to exist before any liquidity exists in the pool, we set a base price of a token to be 1 unit of quote asset.

LiquidityToken

When liquidity is added, the amount of liquidity that will be added is stored, along with at what timestamp the liquidity can enter the pool. When processed, after the delay and any circuit breakers that might have fired, we can compute the amount owed the the LPs, and provide them a relative share of the LiquidityTokens.
More info about entry/exit mechanisms can be found here.

OptionMarket

The OptionMarket is a collection of boards, each with a number of strikes, which a user can trade against. Along side this, it also manages LiquidityPool locking and freeing of collateral, adjusting collateral for shorts, adjusting OptionToken positions, board expiry/settlement and short position liquidations.

Boards

Boards are a collection of strikes at a specific expiry. Each strike that is tradable is a combination of a strikePrice and the board expiry. They are created by the owner of the contract. At the time of creation, the baseIV of the board is specified, along with a skew value per strike. These combine to define the volatility value for each option, which is required for the BlackScholes pricing model.
Trading
Traders have both the option to buy a call/put option from the market (a long) or to sell a call/put option to the market (a short). Calls can be collateralised either with quote or base. Each position is represented by a tradable NFT. Traders are able to open multiple different positions on the same strike.
When options are purchased from the market, collateral is locked in the LiquidityPool, and users send the premium to the LiquidityPool. When options are sold to the market, users must lock collateral in the ShortCollateral contract, and they will receive the premium from the LiquidityPool. When an option is closed, these steps are reversed.
When a trader is opening a long, or closing a short; that is considered a buy from the perspective of the user, the contract notes this as isBuy = true. Similarly, when a trader opens a short, or closes a long, isBuy = false.
isBuy denotes which direction the market is moving, and scales the board's iv and the listing's vol in that direction. It also denotes whether a fee is charged on top of the BlackScholes option price, or removed from. i.e. if the market is paying for the option, the fee should be removed from the price; to pay less out to the trader, as LPs are the ones making the market and taking on risk.
Board Expiry
Beyond trading, the OptionMarket is also responsible for the liquidation of assets held for a board, as well as reserving the correct amount of assets required to pay out to all the traders. This means that options are automatically cash settled at expiry. When the expiry time has passed, the spot price of baseAsset is reserved, and funds are reserved appropriately for all listings. As options are cash settled, this involves holding onto the difference of spotPrice and strike for long options; and liquidating and sending a portion of the collateral from options sold to the market.

Liquidations

When users open a short position, they must provide at least minCollateral collateral for the options they have shorted. This minCollateral value changes over time and with spot price movements - and is determined via black scholes using a static IV value (which increases closer to expiry). This means the collateral level needs to be maintained, as if the value ever drops below the minCollateral requirements, the position can be forcibly closed by a liquidator. This will cause the position to be closed at an inflated iv value - and then also a portion of remaining collateral to be taken from the trader.

OptionMarketPricer

A collection of pricing logic for the OptionMarket. Using pricing returned from OptionGreekCache, determines the cost and fee of the options being purchased. This also provides the logic for adjusting the iv/skew values for boards/strikes in the OptionMarket.

OptionGreekCache

A system for caching greeks (optionValue, delta and stdVega) for strikes, and aggregating those values for each board and across the entire market (globalCache).
These greeks need to be updated periodically by keepers, as changes in spot price, time and volatility will cause a change in all of the values.
The OptionGreekCache is also responsible for implementing logic for calculating GWAVs for each baseIv and skew, and uses those values for computing the aggregate greeks.

OptionToken

An ERC721 contract that tokenises user option positions. Each OptionToken NFT represents a position held by a trader, including collateral held for the position. As such, transferring this NFT is either transferring the value of the long option, or transferring both the debt associated with a short and the collateral backing it.

ShortCollateral

The ShortCollateral contract holds collateral from users who are selling (shorting) options to the AMM. At the time of liquidation it will send the portion owed to the LPs to the LiquidityPool, and reserve the remainder for users who opened shorts to reclaim. It also contains the logic for settling options.

ShortPoolHedger

This contract assesses the netDelta position of the LiquidityPool/OptionMarket and hedges the risk by purchasing or shorting the base asset, to try bring the market to a delta neutral hedged position. This ideally leaves the LP exposed only to changes in the asset volatility. However, delta hedging is not an exact science.
PoolHedger.hedgeDelta() is the main public keeper function for this contract. It gets the current global netDelta position from the OptionGreekCache, and either purchases/sells eth, or shorts/reduces an eth short; using the Synthetix suite of contracts.
If the netDelta of the market is positive, it implies that when the price of the asset moves up $1, the value of the options goes up by that amount. So given the netDelta from the perspective of the users is 50; if eth moves $1, the value the LPs would have to pay out is $50 more, on the flip side, the LPs profit a similar amount if the price of the asset goes down $1. As such, to hedge the risk of the price movement (to instead create market purely on the volatility of the asset) - the LPs should purchase 50 eth.
The opposite is true for the cases where the netDelta is negative. The LPs would want to short the asset to not be exposed to price movements.
One caveat with this approach is that the LP is funded by sUSD, so when a call option is purchased from the market, enough collateral must be purchased to cover the options purchased. By doing so, the LPs expose themselves to price movements of the asset. As such, these purchases must be hedged by shorting the asset.
In an example:
  • One 50 delta eth call is purchased
  • 1 eth must be purchased
  • netDelta is 0.5, but the position of the LP is 1 eth, so (0.5 - 1) -> -0.5
  • 0.5 eth must be sold to bring the position to delta neutral
  • Thus the PoolHedger shorts 0.5 eth

SynthetixAdapter

The SynthetixAdapter contract retrieves the current spot price and fee rates for a given currency pair from Synthetix. It also enables swaps for all the contracts that use it through the Synthetix DelegateApprovals contract.