A Technical Overview of Lyra V2

The Lyra V2 protocol is the culmination of 12 months of rigorous research and development. In this blog post, we deep dive into the key features of the protocol’s design, including its modular architecture, subaccount and asset management innovations, permissionless onchain risk checks and liquidations, and strategic trade-offs that contribute to its journey toward complete decentralization.

Modularity

Lyra V1 pioneered the options AMM space, but its major limitation has been its monolithic design. Developers’ ability to add new features was hamstrung, since any change would require major refactoring to the core smart contracts and subsequent audits. In order to introduce the features traders needed, we had to change rethink our design principles.

Enter Lyra V2. The new protocol employs a modular framework that prioritizes flexibility, adaptability and performance. This modular approach allows for fast, cheap upgrades that enable developers to add new features on top of the protocol to meet the rapidly evolving crypto market dynamics.

There are three main components to the protocol:

• Subaccounts: a trading account, represented as an NFT, that hold assets and defines margin rules for those assets,
• Assets: the instruments and collateral that can be traded,
• Managers: a manager defines the margining rules for a subaccount and its assets.

Subaccounts

The fundamental unit of the protocol is a subaccount. Subaccounts are a new standard for grouping assets and encoding rules surrounding interactions between subaccounts. Each subaccount is an ERC-721 NFT that owns a collection of Assets that are managed by a subaccount Manager. Note that this means that a single account can hold multiple subaccounts.

These rules are controlled through the use of newly introduced hooks; external function calls to relevant contracts that occur during and after any transfer. There are two such hooks: the manager hooks and asset hooks. The former ensures the final state of the subaccount is valid (i.e. the transfer does not make the subaccount liquidatable) whereas the latter determines the final balance of the relevant assets (such as by applying interest).

Assets

Assets define the rules of what balances represent, and how these balances change when users interact. Assets can be collateral (e.g. USDC, ETH) or instruments (e.g. a perpetual or option). Each asset has access to a uint96 subId which can be used to encode any information. In essence, each asset is an ERC1155 with a more limited id space (uint96 instead of uint256), and supports both positive and negative balances (int256 instead of uint256). Each asset can then constrain the id space and possible final balance that can be held. Assets can be categorized as:

• A traditional ERC721 (subId can be anything, balance can only be 1 or 0)
• A traditional ERC20 (subId must be 0, balance can only be positive)
• A borrowable ERC20 (subId must be 0, balance can be both positive or negative)
• An instrument, such as a perpetual or option, stored in state (subId can be anything, balance can be both positive or negative)

Managers

Managers are contracts which govern the rules of interaction between different subaccounts. These managers are responsible for:

• Risk management: Managers mandate the margin requirement for all supported subaccounts. For example, in the standard margin manager, perpetuals and short options require margin, while USDC and credit balances of the base asset(s) provide collateral. Managers maintain the solvency of the system by preventing users from opening dangerously leveraged positions.
• Liquidations: Users who fall beneath their margin requirements will be subject to liquidation, removing risk from the system and further decreasing the likelihood of insolvencies.
• Settlement: Managers are responsible for settling all trades conducted by their supported subaccounts. For example, the managers are responsible for settling all options at expiration.

As market conditions evolve, new managers can rapidly be deployed to facilitate any assets or purposes.

V2.0

The first version of the protocol supports four asset types:

• CashAsset: A designated quote asset (such as USDC) that acts as the primary method of collateralizing a subaccount. Users can have either credit or debit balances of this asset, and so an inbuilt lending market is obtained for free.
• WrappedERC20Asset: As the name suggests, these are simply the wrapped underlying assets. These will be primarily used to hedge and collateralize subaccounts. Users can also borrow against these assets.
• OptionAsset: European call or put options that settle to a TWAP of the index price.
• PerpAsset: Perpetual futures.

And two risk managers:

• Portfolio Margin Risk Manager (PMRM): The PMRM uses portfolio margin to compute a user’s margin requirement. The manager evaluates the entire portfolio holistically under a variety of spot and volatility shocks and sets the margin to be the worst possible loss. This manager is intended for use by market makers and sophisticated takers that want to manage complex portfolios and minimize their margin requirements.
• Standard Margin Risk Manager (SMRM): The SMRM, by contrast, evaluates the margin of each position in isolation, with offsetting logic for spreads for improved capital efficiency. A special feature of this manager is that it allows for multi-asset collateral - traders will be able to use various base assets to collateralize their perpetuals and options. For instance, a user will be able to collateralize a short BTC perpetual with ETH. This manager is intended for use by retail traders managing less complex portfolios that want access to features like capital efficient spreads and multi-asset collateral.

A key feature to stress about these managers is that all risk checks will be performed trustlessly and transparently on chain. This means that traders can rest assured that a malicious actor cannot trigger an unjustified liquidation of their subaccount.

Decentralization

While decentralization is a core principle of V2, certain trade-offs were made to ensure the final product is efficient and safe. We can summarize these as follows:

• Parameters: At launch, all parameters will be controlled within immutable ranges by token holders; specifically, parameters will be governed by the short term executor - see this LEAP for more detail. This means that parameter updates (including adding new markets) will take up to a week to implement, meaning traders always have a week to consider important parameter changes that could impact their portfolios. Notably, immutable parameter ranges set at contract deployment time substantially limit the risk of a governance attack.
• Verified Integrations: Portfolio margin computations for opening and closing trades are gas intensive, requiring a search for the max loss scenario from 27 vol and spot shock scenarios, all onchain. Verified integrations are contracts approved by governance that can perform this search offchain and then post the required margin with the transaction, during which one onchain risk check is performed to ensure portfolio solvency instead of the regular 27. This is crucial for, say, an orderbook model, where market makers using portfolio margin accounts are the counterparty in almost every trade. This requires more developer effort from the verified integrator to ensure offchain risk checks are reliable, but substantially reduces gas cost and preserves self-custody by guaranteeing a subaccount cannot be liquidated unjustly.
• Oracles: At launch, all relevant data needed to compute a user’s margin (spot + forward + perpetual prices, implied volatility, etc) is obtained as a feed from the firm Block Scholes. Further efforts will be needed to decentralize the data being used in the protocol.

Learn More

Lyra V2's protocol is the foundation for a fair, efficient and decentralized settlement layer for crypto derivatives trading.

• If you want a deeper dive into the protocol’s design, read our whitepaper.
• If you’re interested in building an integration for Lyra V2, join our Discord and reach out the core team.
• If you want an opportunity to test out V2, join the waitlist.

The storm provides ⚡ ⛈️ 🌪️