Skip to content

Commit

Permalink
docs: update README, docs and diagrams (#329)
Browse files Browse the repository at this point in the history
  • Loading branch information
@antoncoding
antoncoding authored Nov 24, 2023
1 parent d0abcd7 commit 6be3532
Show file tree
Hide file tree
Showing 23 changed files with 221 additions and 188 deletions.
57 changes: 9 additions & 48 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,84 +2,45 @@

[![foundry-rs - foundry](https://img.shields.io/static/v1?label=foundry-rs&message=foundry&color=blue&logo=github)](https://github.com/foundry-rs/foundry "Go to GitHub repo")
[![CI](https://github.com/lyra-finance/v2-core/actions/workflows/ci.yml/badge.svg)](https://github.com/lyra-finance/v2-core/actions/workflows/ci.yml)
[![Slither Analysis](https://github.com/lyra-finance/v2-core/actions/workflows/slither.yml/badge.svg)](https://github.com/lyra-finance/v2-core/actions/workflows/slither.yml)
[![codecov](https://codecov.io/gh/lyra-finance/v2-core/branch/master/graph/badge.svg?token=43B951MYIN)](https://codecov.io/gh/lyra-finance/v2-core)

<div align="center">
<p align='center'>
<br>
<br>
<img src='./docs/imgs/overall/logo.png' alt='lyra' width="300" />
<h5 align="center"> Cool slogan goes here </h6>
<h5 align="center"> The framework to trade all derivatives </h6>
</p>
</div>


## Installation and Build
## Build

```shell
git submodule update --init --recursive
forge build
```

## Running different tests
## Tests

Only running unit tests

```shell
forge test --match-contract="UNIT_" -vvv
```

Running integration tests

```shell
forge test --match-contract="INTEGRATION_" -vvv
```

Run coverage and generate html report:

```shell
# Generate lcov.info
forge coverage --report lcov

# Create a html report
brew install lcov
genhtml lcov.info -out coverage/ --rc lcov_branch_coverage=1 --keep-going --include "src/"
forge test
```
Go to [test](./test/) folder for more details on how to run different tests.

## Documentation

Go to [docs](./docs) to understand the high level of the design, transaction flow and how different **Lyra v2 components** works together.
Go to [docs](./docs) to understand the high-level design, transaction flow, and how different **Lyra V2 components** work together.

## Static Analysis - Slither
## Static Analysis - [Slither](https://github.com/crytic/slither)

### Installation

```shell
pip3 install slither-analyzer
pip3 install solc-select
solc-select install 0.8.18
solc-select use 0.8.18
```

### Run analysis
Please go to the link above for detail to install. To run the analysis:

```shell
slither src
```

#### Triage issues

Make sure to triage all findings introduced by new PR. They should be appended to `slither.db.json` after the following:

```shell
slither src --triage-mode
```

## Deployment

Got to [scripts](./scripts) to understand how to deploy **Lyra v2** to different networks.

## Gas Metrics

See docs in [test/integration-tests/metrics](./test/integration-tests/metrics/) for more detail.
Got to [scripts](./scripts) to understand how to deploy **Lyra v2** to different networks.
43 changes: 22 additions & 21 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,46 +1,47 @@
# Contract Overview

As DeFi continues to evolve, the industry has expanded well beyond basic token swapping. It now includes a range of advanced financial applications such as lending, perpetual contracts (perps), and options. However, each protocol's distinct contract architecture and accounting system make it increasingly challenging to integrate them all effectively.

Lyra V2 core is a framework designed to handle various derivatives in an clean way. It currently supports instruments like spot trading, perps, and options, with the capability to include more in the future. To make this possible, we've completely revamped the underlying 'account' layer. Additionally, we've defined a new validation process, making it flexible enough to accommodate a wide range of trading scenarios.

## Agenda

* [Base Layer Overview](#the-base-layer)
* [SubAccounts](#subaccounts)
* [Managers](#managers)
* [Assets](#assets)
* [Shared Risk and Hooks](#shared-risk)
* [What is Lyra V2](#lyra-v2)
* [AMMs](#amms)
* Future AMM
* VGVV
* [Lyra V2](#lyra-v2)

## The Base layer

There are three big parts that compose of the **base layer**: `Account`, `Managers` and `Assets`.
There are three big parts that compose of the **base layer**: `SubAccount`, `Managers` and `Assets`.

![base-layer](./imgs/overall/base-layer-basic.png)

### SubAccounts

`SubAccounts` is a fully permission-less contract that allows anyone to create an account entity (represent as ERC721), which stores a list of `{asset, subId, balance}` for a user. Each `asset` can have multiple `subIds` that represent asset sub categories (e.g. asset->option, subId->Jan 1st, $1000 Strike, ETH Call).
`SubAccounts` is a fully permission-less contract data storage contract. It allows anyone to create an account entity (represent as ERC721), and stores a list of `{asset, subId, balance}` for an user. Each `asset` can have multiple `subIds` that represent asset sub categories (e.g. asset: option, subId: "Jan 1st, $1000 Strike, ETH Call").

The primary goal of `SubAccounts` is to give different **Managers** and **Assets** the flexibility to create unique validation rules for various account actions.

The two main missions of `SubAccounts` are:

* validate if `msg.sender` is authorized to change (increase or decrease) one account's balance.
* inform all relevant parties about the trade. This includes:
* manager hook: invoke the **manager** to validate the final state of the account
* asset hook: invoke the **asset** to validate the transfer and determine the ending balance.
* **manager hook**: invoke the **manager** to validate the final state of the account
* **asset hook**: invoke the **asset** to validate the transfer and determine the ending balance.

Additionally, balances of assets can be either positive or negative. For example: if Alice wants to long 1 call and Bob wants to short 1 call, they no longer need to "deposit and create an option token in another contract". An approved party just submits a transfer and changes each account's balance from [0, 0] to [1, -1].

P.S. Go to [SubAccounts](./accounts) for some more detailed documentation about the approval system and the hooks.
P.S. Go to [SubAccounts](./subaccounts.md) for some more detailed documentation about the approval system and the hooks.

### Managers

A manager should be used to govern a set of accounts, and has certain privileges. The 3 main jobs of a manager are:

* **Account state validation**: After a transaction is executed on an account, the manager will take a look at the final state of an account and decide if this account is valid. For example, a transaction that leaves an account holding only -1000 USDC should be denied. But if the account has another 10 ETH in it, it's probably okay.
* **Debt Management**: It is also the manager's obligation to determine "dangerous accounts" that might leave the system in debt and take care of liquidations. In the current design, all managers are sharing the same `DutchAuction` module for liquidation. The auction contract can start an auction if an account's net maintenance margin is below 0, and allow bidders to buy the portfolio.
* **Debt Management**: It is also the manager's obligation to determine "dangerous accounts" that might leave the system in debt and take care of liquidations. In the current design, all managers are sharing the same `DutchAuction` module for liquidation. The auction contract can start an auction if an account's net maintenance margin is below 0, and allow bidders to buy the portfolio through a dutch auction.

* **Settlement**: If an account has assets with expiry, the manager should also handle the settlement after expiry. For example, if an account long 1 2000-ETH-CALL-DEC01-2022 and it expired in the money, the manager has the right to increase the account's usdc balance, and burn the option balance at expiry.

Expand All @@ -64,9 +65,9 @@ For more detailed explanation about each asset, please go to [Assets](./assets.m

The asset has the privileges to update its own "asset balance" of any account. This is to support actions such as (a) deposits and withdrawals of underlying tokens (b) interest accrual.

![adjustment-flow](./imgs/overall/adjustment-flow.png)
### Small Summary

We can see from the diagram that `Assets` and `Managers` can both access the account directly with `assetAdjustment` and `managerAdjustment`. Every other external party (including orderbook) will need to get approvals from the account owner to act on their behalf.
We can see from the diagram above that `Assets` and `Managers` can both access the account directly with `assetAdjustment` and `managerAdjustment`. Every other external party (including orderbook) will need to get approvals from the account owner to act on their behalf. And all external calls (invoked with `submitTransfers`) can only update the balances symmetrically. Meaning that if any subAccount's AssetA balance is increased by 1, there must be another subaccount that its balance is decreased by 1.

### Shared Risk

Expand All @@ -77,23 +78,23 @@ Managers and assets each have privileges that, if used maliciously, could affect

This means that a set of connected managers and assets will form a "trusted group" inside which everyone shares the same solvency risks; If any of the contract is compromised or hacked, the whole "ecosystem" goes insolvent together. As a result, a manager should revert all transfers that adds a "unknown asset" into an account; and an asset should revert all transfers from or to a account controlled by "unknown manager".

![account-permission](./imgs/overall/trusted-group.png)

#### Hooks

To check these requirements, whenever a trade happens, `SubAccounts` passes the transfer information to the **Asset** contract through the **asset hook** to make sure the final balance of an account is valid and the account is controlled by a good manager, and at the end of all **transfers**, it triggers the **manager hook** to let the manager determine the final state of an account.
To check these requirements, whenever a trade happens, `SubAccounts` passes the transfer information to the **Asset** contract through the **asset hook** to make sure the final balance of an account is valid and the account is controlled by a good manager, and at the end of all **transfers**, it triggers the **manager hooks** to let the manager determine the final state of all involved accounts.

![account-permission](./imgs/overall/hooks.png)

It's worth mentioning that because the **account contract** is totally permission-less, anyone can spin up their own "ecosystem" with risk totally separated from other ecosystems.

![account-permission](./imgs/overall/account-permissions.png)
It's worth mentioning that because the **account contract** is totally permission-less, anyone can spin up their own "ecosystem" with risk totally separated from other ecosystems.

## Lyra V2

The ultimate goal of Lyra v2 is to build a permission-less margin system for both traders and AMMs, with a modular framework for upgrading existing contracts and supplementing the Lyra ecosystem with new features. At the base layer, this will be composed of 2 manager and 3 assets at the launch of V2. You can find the more detailed documentation about each modules from the links below:
The goal of Lyra v2-core contracts is to build a margin layer that supports all derivatives, with a modular framework for upgrading existing contracts and supplementing the Lyra ecosystem with new features. At the base layer, this will be composed of 2 manager and 4 assets at the launch of V2. You can find the more detailed documentation about each modules from the links below:

* [Assets](assets.md) Overview
* (Manager) [SRM: Standard Risk Manager](./managers/SRM.md)
* (Manager) [PMRM: Portfolio Margining Risk Manager](./managers/PMRM.md)
* (Asset) [Cash Asset](./)
* (Asset) [Option Asset](./)
* (Asset) [Perp Asset](./)
* (Asset) [BaseAsset Asset](./)

![scope](./imgs/overall/v2-scope.png)
![scope](./imgs/overall/v2.png)
51 changes: 0 additions & 51 deletions docs/accounts.md
View file

This file was deleted.

Loading

0 comments on commit 6be3532

Please sign in to comment.