Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add additional documentation #4

Merged
merged 4 commits into from
Sep 8, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 2 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,6 @@
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI Status](../../actions/workflows/test.yaml/badge.svg)](../../actions)

This template repo is a quick and easy way to get started with a new Solidity project. It comes with a number of features that are useful for developing and deploying smart contracts. Such as:

- Pre-commit hooks for formatting, auto generated documentation, and more
- Various libraries with useful contracts (OpenZeppelin, Solady) and libraries (Deployment log generation, storage checks, deployer templates)

#### Table of Contents

- [Setup](#setup)
Expand Down Expand Up @@ -39,8 +34,8 @@ forge script script/Deploy.s.sol --broadcast --rpc-url <rpc_url> --verify

## Docs

The documentation and architecture diagrams for the contracts within this repo can be found [here](docs/).
Detailed documentation generated from the NatSpec documentation of the contracts can be found [here](docs/autogen/src/src/).
The documentation and architecture diagrams for the contracts within this repo can be found [here](docs/README.md).
Detailed documentation generated from the NatSpec documentation of the contracts can be found [here](docs/autogen/src/SUMMARY.md).
When exploring the contracts within this repository, it is recommended to start with the interfaces first and then move on to the implementation as outlined [here](CONTRIBUTING.md#natspec--comments)

## Contributing
Expand Down
69 changes: 69 additions & 0 deletions asset/architecture.drawio
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
<mxfile host="65bd71144e" scale="1" border="5">
<diagram id="TrCcAzhzWdwAyr-SGnU9" name="Page-1">
<mxGraphModel dx="400" dy="947" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" background="#ffffff" math="0" shadow="0">
<root>
<mxCell id="0"/>
<mxCell id="1" parent="0"/>
<mxCell id="2" value="Pocket&lt;br&gt;(Base)" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
<mxGeometry x="160" y="480" width="120" height="60" as="geometry"/>
</mxCell>
<mxCell id="12" style="edgeStyle=none;html=1;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" parent="1" source="3" target="7" edge="1">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="14" style="edgeStyle=none;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" parent="1" source="3" target="8" edge="1">
<mxGeometry relative="1" as="geometry">
<Array as="points">
<mxPoint x="380" y="440"/>
<mxPoint x="540" y="440"/>
</Array>
</mxGeometry>
</mxCell>
<mxCell id="15" style="edgeStyle=none;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" parent="1" source="3" target="2" edge="1">
<mxGeometry relative="1" as="geometry">
<Array as="points">
<mxPoint x="380" y="440"/>
<mxPoint x="220" y="440"/>
</Array>
</mxGeometry>
</mxCell>
<mxCell id="3" value="Vault&lt;br&gt;(ETH)" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
<mxGeometry x="320" y="340" width="120" height="60" as="geometry"/>
</mxCell>
<mxCell id="4" value="Vault&lt;br&gt;(USDC)" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
<mxGeometry x="120" y="340" width="120" height="60" as="geometry"/>
</mxCell>
<mxCell id="5" value="Vault&lt;br&gt;(...)" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
<mxGeometry x="520" y="340" width="120" height="60" as="geometry"/>
</mxCell>
<mxCell id="9" style="edgeStyle=none;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" parent="1" source="6" target="3" edge="1">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="10" style="edgeStyle=none;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" parent="1" source="6" target="5" edge="1">
<mxGeometry relative="1" as="geometry">
<Array as="points">
<mxPoint x="380" y="300"/>
<mxPoint x="580" y="300"/>
</Array>
</mxGeometry>
</mxCell>
<mxCell id="11" style="edgeStyle=none;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" parent="1" source="6" target="4" edge="1">
<mxGeometry relative="1" as="geometry">
<Array as="points">
<mxPoint x="380" y="300"/>
<mxPoint x="180" y="300"/>
</Array>
</mxGeometry>
</mxCell>
<mxCell id="6" value="TCAP" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
<mxGeometry x="320" y="200" width="120" height="60" as="geometry"/>
</mxCell>
<mxCell id="7" value="Pocket&lt;br&gt;(Aave)" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
<mxGeometry x="320" y="480" width="120" height="60" as="geometry"/>
</mxCell>
<mxCell id="8" value="Pocket&lt;br&gt;(...)" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
<mxGeometry x="480" y="480" width="120" height="60" as="geometry"/>
</mxCell>
</root>
</mxGraphModel>
</diagram>
</mxfile>
Binary file added asset/architecture.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
14 changes: 14 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,17 @@
# Documentation

The auto-generated documentation from the natspec comments in the contracts can be found [here](./autogen/src/SUMMARY.md).

---

The TCAP token is an overcollateralized ERC20 token that aims to be pegged to the market cap of the crypto market. Users can mint TCAP by depositing ERC20 tokens into vaults as collateral. When collateral is deposited into a vault, the user can pick a "pocket" to deposit the collateral into.

![Architecture](../asset/architecture.png)

A pocket manages user assets and isolates them from other deposits. A base pocket simply stores the collateral and does not allow for any lending for example. The Aave pocket is a more complex pocket that lends the deposited collateral on Aave allowing user's capital to be used more efficiently. This mechanism allows a user to chose what level of additional risk they want to take on, as well as isolate their collateral from other deposits.

## Liquidations

Should a user's health factor drop below the liquidation threshold the user's collateral can be liquidated. Liquidators can buy TCAP tokens on the open market and call the liquidate function. The liquidation process burns the TCAP tokens and sends the underlying collateral (liquidation reward) back to the liquidator. By default only a portion of a user's position can be liquidated which pushes the user's health factor back above the liquidation threshold.

The liquidation mechanism is based on the V1 version of the TCAP token. The calculation of the liquidation reward and derivation of the formula can be found [here](https://medium.com/@voithjm1/tokenomics-of-tcap-ce9da45e1be9). A minimum and maximum health factor is enforced after the liquidation. The minimum health factor is enforced after the liquidation to ensure that the user should not be able to be liquidated again immediately after a liquidation. The maximum health factor is enforced to ensure the user does not suffer from a larger than necessary liquidation reward, as the more TCAP tokens are liquidated by the liquidator, the more profitable the liquidation becomes and the more of the underlying collateral the user loses. In cases where the user cannot be liquidated in a way that keeps their health factor between the minimum and maximum health factor, the entire position can be liquidated to mitigate the risk of bad debt.
9 changes: 2 additions & 7 deletions docs/autogen/src/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,6 @@
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI Status](../../actions/workflows/test.yaml/badge.svg)](../../actions)

This template repo is a quick and easy way to get started with a new Solidity project. It comes with a number of features that are useful for developing and deploying smart contracts. Such as:

- Pre-commit hooks for formatting, auto generated documentation, and more
- Various libraries with useful contracts (OpenZeppelin, Solady) and libraries (Deployment log generation, storage checks, deployer templates)

#### Table of Contents

- [Setup](#setup)
Expand Down Expand Up @@ -39,8 +34,8 @@ forge script script/Deploy.s.sol --broadcast --rpc-url <rpc_url> --verify

## Docs

The documentation and architecture diagrams for the contracts within this repo can be found [here](docs/).
Detailed documentation generated from the NatSpec documentation of the contracts can be found [here](docs/autogen/src/src/).
The documentation and architecture diagrams for the contracts within this repo can be found [here](docs/README.md).
Detailed documentation generated from the NatSpec documentation of the contracts can be found [here](docs/autogen/src/SUMMARY.md).
When exploring the contracts within this repository, it is recommended to start with the interfaces first and then move on to the implementation as outlined [here](CONTRIBUTING.md#natspec--comments)

## Contributing
Expand Down
4 changes: 2 additions & 2 deletions docs/autogen/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
# src
- [❱ interface](src/interface/README.md)
- [❱ pockets](src/interface/pockets/README.md)
- [IAAVEv3Pocket](src/interface/pockets/IAAVEv3Pocket.sol/interface.IAAVEv3Pocket.md)
- [IAaveV3Pocket](src/interface/pockets/IAaveV3Pocket.sol/interface.IAaveV3Pocket.md)
- [IPocket](src/interface/pockets/IPocket.sol/interface.IPocket.md)
- [IMulticall](src/interface/IMulticall.sol/interface.IMulticall.md)
- [IOracle](src/interface/IOracle.sol/interface.IOracle.md)
Expand All @@ -20,7 +20,7 @@
- [BaseOracleUSD](src/oracle/BaseOracleUSD.sol/abstract.BaseOracleUSD.md)
- [TCAPTargetOracle](src/oracle/TCAPTargetOracle.sol/contract.TCAPTargetOracle.md)
- [❱ pockets](src/pockets/README.md)
- [AAVEv3Pocket](src/pockets/AAVEv3Pocket.sol/contract.AAVEv3Pocket.md)
- [AaveV3Pocket](src/pockets/AaveV3Pocket.sol/contract.AaveV3Pocket.md)
- [BasePocket](src/pockets/BasePocket.sol/contract.BasePocket.md)
- [TCAPV2](src/TCAPV2.sol/contract.TCAPV2.md)
- [Vault](src/Vault.sol/contract.Vault.md)
2 changes: 1 addition & 1 deletion docs/autogen/src/src/TCAPV2.sol/contract.TCAPV2.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# TCAPV2
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/adb271543417436c1309ef4ed99a33410b5ee7ce/src/TCAPV2.sol)
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/6bc13f590e0d259edfc7844b2201ce75ef760a67/src/TCAPV2.sol)

**Inherits:**
[ITCAPV2](/src/interface/ITCAPV2.sol/interface.ITCAPV2.md), ERC20, AccessControl
Expand Down
2 changes: 1 addition & 1 deletion docs/autogen/src/src/Vault.sol/contract.Vault.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Vault
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/adb271543417436c1309ef4ed99a33410b5ee7ce/src/Vault.sol)
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/6bc13f590e0d259edfc7844b2201ce75ef760a67/src/Vault.sol)

**Inherits:**
[IVault](/src/interface/IVault.sol/interface.IVault.md), AccessControl, [Multicall](/src/lib/Multicall.sol/abstract.Multicall.md)
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# IMulticall
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/adb271543417436c1309ef4ed99a33410b5ee7ce/src/interface/IMulticall.sol)
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/6bc13f590e0d259edfc7844b2201ce75ef760a67/src/interface/IMulticall.sol)

Enables calling multiple methods in a single call to the contract

Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# IOracle
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/adb271543417436c1309ef4ed99a33410b5ee7ce/src/interface/IOracle.sol)
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/6bc13f590e0d259edfc7844b2201ce75ef760a67/src/interface/IOracle.sol)

Interface that needs to be implemented by all oracles

Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# ITCAPV2
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/adb271543417436c1309ef4ed99a33410b5ee7ce/src/interface/ITCAPV2.sol)
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/6bc13f590e0d259edfc7844b2201ce75ef760a67/src/interface/ITCAPV2.sol)

**Inherits:**
IERC20, IAccessControl, [IVersioned](/src/interface/IVersioned.sol/interface.IVersioned.md)
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# IVault
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/adb271543417436c1309ef4ed99a33410b5ee7ce/src/interface/IVault.sol)
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/6bc13f590e0d259edfc7844b2201ce75ef760a67/src/interface/IVault.sol)

**Inherits:**
IAccessControl, [IMulticall](/src/interface/IMulticall.sol/interface.IMulticall.md), [IVersioned](/src/interface/IVersioned.sol/interface.IVersioned.md)
Expand Down Expand Up @@ -231,6 +231,8 @@ Liquidates a user's loan

*Throws if the loan is not healthy*

*after the liquidation the health factor must be between the minimum and maximum bounds of the liquidation params*


```solidity
function liquidate(address user, uint96 pocketId, uint256 burnAmount) external returns (uint256 liquidationReward);
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# IVersioned
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/adb271543417436c1309ef4ed99a33410b5ee7ce/src/interface/IVersioned.sol)
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/6bc13f590e0d259edfc7844b2201ce75ef760a67/src/interface/IVersioned.sol)


## Functions
Expand Down

This file was deleted.

Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# IAaveV3Pocket
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/6bc13f590e0d259edfc7844b2201ce75ef760a67/src/interface/pockets/IAaveV3Pocket.sol)

**Inherits:**
[IPocket](/src/interface/pockets/IPocket.sol/interface.IPocket.md)

Interface for pockets depositing underlying tokens into Aave v3


## Functions
### POOL


```solidity
function POOL() external view returns (IPool pool);
```
**Returns**

|Name|Type|Description|
|----|----|-----------|
|`pool`|`IPool`|Aave v3 Pool|


Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# IPocket
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/adb271543417436c1309ef4ed99a33410b5ee7ce/src/interface/pockets/IPocket.sol)
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/6bc13f590e0d259edfc7844b2201ce75ef760a67/src/interface/pockets/IPocket.sol)

**Inherits:**
[IVersioned](/src/interface/IVersioned.sol/interface.IVersioned.md)
Expand Down Expand Up @@ -91,7 +91,7 @@ function UNDERLYING_TOKEN() external view returns (IERC20);

### OVERLYING_TOKEN

*the overlying token can be an AAVE aToken (e.g., aWETH), it can also be equal to the underlying token*
*the overlying token can be an Aave aToken (e.g., aWETH), it can also be equal to the underlying token*


```solidity
Expand Down
2 changes: 1 addition & 1 deletion docs/autogen/src/src/interface/pockets/README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@


# Contents
- [IAAVEv3Pocket](IAAVEv3Pocket.sol/interface.IAAVEv3Pocket.md)
- [IAaveV3Pocket](IAaveV3Pocket.sol/interface.IAaveV3Pocket.md)
- [IPocket](IPocket.sol/interface.IPocket.md)
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Constants
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/adb271543417436c1309ef4ed99a33410b5ee7ce/src/lib/Constants.sol)
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/6bc13f590e0d259edfc7844b2201ce75ef760a67/src/lib/Constants.sol)


## State Variables
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# FeeCalculatorLib
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/adb271543417436c1309ef4ed99a33410b5ee7ce/src/lib/FeeCalculatorLib.sol)
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/6bc13f590e0d259edfc7844b2201ce75ef760a67/src/lib/FeeCalculatorLib.sol)


## Functions
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# LiquidationLib
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/adb271543417436c1309ef4ed99a33410b5ee7ce/src/lib/LiquidationLib.sol)
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/6bc13f590e0d259edfc7844b2201ce75ef760a67/src/lib/LiquidationLib.sol)


## Functions
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Multicall
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/adb271543417436c1309ef4ed99a33410b5ee7ce/src/lib/Multicall.sol)
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/6bc13f590e0d259edfc7844b2201ce75ef760a67/src/lib/Multicall.sol)

**Inherits:**
[IMulticall](/src/interface/IMulticall.sol/interface.IMulticall.md)
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# AggregatedChainlinkOracle
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/adb271543417436c1309ef4ed99a33410b5ee7ce/src/oracle/AggregatedChainlinkOracle.sol)
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/6bc13f590e0d259edfc7844b2201ce75ef760a67/src/oracle/AggregatedChainlinkOracle.sol)

**Inherits:**
[BaseOracleUSD](/src/oracle/BaseOracleUSD.sol/abstract.BaseOracleUSD.md)
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# BaseOracleUSD
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/adb271543417436c1309ef4ed99a33410b5ee7ce/src/oracle/BaseOracleUSD.sol)
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/6bc13f590e0d259edfc7844b2201ce75ef760a67/src/oracle/BaseOracleUSD.sol)

**Inherits:**
[IOracle](/src/interface/IOracle.sol/interface.IOracle.md)
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# TCAPTargetOracle
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/adb271543417436c1309ef4ed99a33410b5ee7ce/src/oracle/TCAPTargetOracle.sol)
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/6bc13f590e0d259edfc7844b2201ce75ef760a67/src/oracle/TCAPTargetOracle.sol)

**Inherits:**
[AggregatedChainlinkOracle](/src/oracle/AggregatedChainlinkOracle.sol/contract.AggregatedChainlinkOracle.md)
Expand Down
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# AAVEv3Pocket
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/adb271543417436c1309ef4ed99a33410b5ee7ce/src/pockets/AAVEv3Pocket.sol)
# AaveV3Pocket
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/6bc13f590e0d259edfc7844b2201ce75ef760a67/src/pockets/AaveV3Pocket.sol)

**Inherits:**
[BasePocket](/src/pockets/BasePocket.sol/contract.BasePocket.md), [IAAVEv3Pocket](/src/interface/pockets/IAAVEv3Pocket.sol/interface.IAAVEv3Pocket.md)
[BasePocket](/src/pockets/BasePocket.sol/contract.BasePocket.md), [IAaveV3Pocket](/src/interface/pockets/IAaveV3Pocket.sol/interface.IAaveV3Pocket.md)

The AAVE v3 Pocket deposits funds into AAVE v3 to earn interest
The Aave v3 Pocket deposits funds into Aave v3 to earn interest


## State Variables
Expand All @@ -25,7 +25,7 @@ constructor(address vault_, address underlyingToken_, address overlyingToken_, a

### _onDeposit

*deposits underlying token into AAVE v3, aTokens are deposited into this pocket*
*deposits underlying token into Aave v3, aTokens are deposited into this pocket*


```solidity
Expand All @@ -34,7 +34,7 @@ function _onDeposit(uint256 amountUnderlying) internal override returns (uint256

### _onWithdraw

*redeems aTokens with AAVE v3, underlying token is returned to user*
*redeems aTokens with Aave v3, underlying token is returned to user*


```solidity
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# BasePocket
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/adb271543417436c1309ef4ed99a33410b5ee7ce/src/pockets/BasePocket.sol)
[Git Source](https://github.com/cryptexfinance/tcapv2.0/blob/6bc13f590e0d259edfc7844b2201ce75ef760a67/src/pockets/BasePocket.sol)

**Inherits:**
[IPocket](/src/interface/pockets/IPocket.sol/interface.IPocket.md), Initializable
Expand Down
Loading
Loading