Skip to content

improve readme formatting and content #582

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.

Sign up for GitHub

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

Open
wants to merge 1 commit into
base: develop
Choose a base branch
from
Open

improve readme formatting and content #582

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
230 changes: 118 additions & 112 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,199 +1,205 @@
[![GitHub Actions](https://github.com/VenusProtocol/venus-protocol/actions/workflows/cd.yml/badge.svg)](https://github.com/VenusProtocol/venus-protocol/actions/workflows/cd.yml) [![GitHub Actions](https://github.com/VenusProtocol/venus-protocol/actions/workflows/ci.yml/badge.svg)](https://github.com/VenusProtocol/venus-protocol/actions/workflows/ci.yml)

# Venus Protocol

The Venus Protocol is a BNB Chain collection of smart contracts for supplying or borrowing assets. Through the vToken contracts, accounts on the blockchain _supply_ capital (BNB or BEP-20 tokens) to receive vTokens or _borrow_ assets from the protocol (holding other assets as collateral). The protocol will also enable the minting of VAI, which is the first synthetic stablecoin on Venus that aims to be pegged to 1 USD. VAI is minted by the same collateral that is supplied to the protocol. The Venus vToken contracts track these balances and algorithmically set interest rates for borrowers and suppliers.
[![GitHub Actions](https://github.com/VenusProtocol/venus-protocol/actions/workflows/cd.yml/badge.svg)](https://github.com/VenusProtocol/venus-protocol/actions/workflows/cd.yml)
[![GitHub Actions](https://github.com/VenusProtocol/venus-protocol/actions/workflows/ci.yml/badge.svg)](https://github.com/VenusProtocol/venus-protocol/actions/workflows/ci.yml)

Before getting started with this repo, please read:
The Venus Protocol is a collection of smart contracts on BNB Chain for supplying or borrowing assets. Through VToken contracts, blockchain accounts can *supply* capital (BNB or BEP-20 tokens) to receive vTokens or *borrow* assets from the protocol using other assets as collateral. The protocol also enables the minting of VAI, the first synthetic stablecoin on Venus, which aims to maintain a 1 USD peg. VAI is minted using the same collateral supplied to the protocol. Venus vToken contracts track balances and algorithmically determine interest rates for borrowers and suppliers.

- [Venus Whitepaper](https://github.com/VenusProtocol/venus-protocol/tree/main/docs/VenusWhitepaper.pdf)
📖 Before using this repo, check out the [Venus Whitepaper](./docs/VenusWhitepaper.pdf)
🤝 Want to contribute? See our [Contributing Guidelines](./docs/CONTRIBUTING.md)
🔄 Core Pool code is in this repo; for [Isolated Pools](https://github.com/VenusProtocol/isolated-pools), see their separate repository.

Interested in contributing? Please checkout our [contributing guidelines](./docs/CONTRIBUTING.md)
---

[Isolated pool](https://github.com/VenusProtocol/isolated-pools) is the updated version of the Venus protocol. The Venus "Core Pool" uses the codebase in this repository. On the other hand, Isolated pools use the codebase in the [isolated-pools](https://github.com/VenusProtocol/isolated-pools) repository.
## 📑 Table of Contents

# Contracts
- [Contracts](#contracts)
- [Documentation](#documentation)
- [Installation](#installation)
- [Testing](#testing)
- [Code Coverage](#code-coverage)
- [Deployment](#deployment)
- [Linting](#linting)
- [Hardhat Commands](#hardhat-commands)
- [Discussion](#discussion)

We detail a few of the core contracts in the Venus protocol.
---

<dl>
<dt>VToken, VBep20 and VBNB</dt>
<dd>The Venus vTokens, which are self-contained borrowing and lending contracts. VToken contains the core logic and VBep20, VBUSD, and VBNB add public interfaces for BEP-20 tokens and bnb, respectively. Each VToken is assigned an interest rate and risk model (see InterestRateModel and Comptroller sections), and allows accounts to *mint* (supply capital), *redeem* (withdraw capital), *borrow* and *repay a borrow*. Each VToken is an BEP-20 compliant token where balances represent ownership of the market.</dd>
</dl>
## 📦 Contracts

<dl>
<dt>Diamond Comptroller</dt>
<dd>The risk model contract, which validates permissible user actions and disallows actions if they do not fit certain risk parameters. For instance, the Comptroller enforces that each borrowing user must maintain a sufficient collateral balance across all vTokens. The Comptroller is implemented as a Diamond proxy with several facets (MarketFacet, PolicyFacet, RewardFacet, SetterFacet) corresponding to the particular parts of the Comptroller functionality.</dd>
</dl>
<dt><strong>VToken, VBep20, and VBNB</strong></dt>
<dd>Self-contained lending and borrowing contracts. VToken has the core logic, while VBep20 and VBNB provide interfaces for BEP-20 tokens and BNB. VTokens allow mint, redeem, borrow, and repay functions and act as BEP-20 tokens representing market ownership.</dd>

<dl>
<dt>XVS</dt>
<dd>The Venus Governance Token (XVS). Holders of this token have the ability to govern the protocol via the governor contract.</dd>
</dl>
<dt><strong>Diamond Comptroller</strong></dt>
<dd>Manages protocol risk and permissions via facets like MarketFacet, PolicyFacet, RewardFacet, and SetterFacet. Ensures collateral safety for users borrowing across vTokens.</dd>

<dl>
<dt>Governor Bravo</dt>
<dt><strong>XVS</strong></dt>
<dd>The governance token for the Venus Protocol.</dd>

<dt><strong>Governor Bravo</strong></dt>
<dd>The administrator of the Venus Timelock contracts. Holders of XVS token who have locked their tokens in XVSVault may create and vote on proposals which will be queued into the Venus Timelock and then have effects on other Venus contracts.</dd>
</dl>

<dl>
<dt>InterestRateModel, JumpRateModel, WhitepaperInterestRateModel</dt>
<dt><strong>InterestRateModel Variants</strong></dt>
<dd>Contracts which define interest rate models. These models algorithmically determine interest rates based on the current utilization of a given market (that is, how much of the supplied assets are liquid versus borrowed).</dd>
</dl>

<dl>
<dt>Careful Math</dt>
<dd>Library for safe math operations.</dd>
</dl>

<dl>
<dt>ErrorReporter</dt>
<dd>Library for tracking error codes and failure conditions.</dd>
<dt><strong>CarefulMath, ErrorReporter, Exponential</strong></dt>
<dd>Helper libraries for safe math, error tracking, and fixed-point arithmetic.</dd>
</dl>

<dl>
<dt>Exponential</dt>
<dd>Library for handling fixed-point decimal numbers.</dd>
</dl>
---

### Documentation
## 📚 Documentation

- Public documentation site: https://docs.venus.io, including autogenerated documentation, guides, addresses of the deployment contracts and more content.
- Documentation autogenerated using [solidity-docgen](https://github.com/OpenZeppelin/solidity-docgen).
- To generate the documentation from the natspec comments embedded in the contracts, use `yarn docgen`
- Public docs: [https://docs.venus.io](https://docs.venus.io)
- Generated via [solidity-docgen](https://github.com/OpenZeppelin/solidity-docgen)
- Generate locally:
```bash
yarn docgen
```

## Installation
---

To run venus, pull the repository from GitHub and install its dependencies. You will need [yarn](https://yarnpkg.com/lang/en/docs/install/) or [npm](https://docs.npmjs.com/cli/install) installed.
## ⚙️ Installation

git clone https://github.com/VenusProtocol/venus-protocol
cd venus-protocol
yarn install --lock-file # or `npm install`
Requires [Yarn](https://yarnpkg.com) or [npm](https://www.npmjs.com/):

## Testing
```bash
git clone https://github.com/VenusProtocol/venus-protocol
cd venus-protocol
yarn install --lock-file # or npm install
```

Contract tests are defined under the [tests directory](https://github.com/VenusProtocol/venus-protocol/tree/main/tests). To run the tests run:
---

```
## 🧪 Testing

yarn test
Run tests:

```bash
yarn test
```

- To run fork tests set the`FORKED_NETWORK` var in the `.env` file. An env variable with the name `ARCHIVE_NODE_<FORKED_NETWORK>` is also required.
To test with a forked network, set the `FORKED_NETWORK` and `ARCHIVE_NODE_<FORKED_NETWORK>` environment variables in your `.env` file.

## Code Coverage
---

To run code coverage, run:

```
## ✅ Code Coverage

```bash
npx hardhat coverage

```

## Deployment
---

```
## 🚀 Deployment

```bash
npx hardhat deploy

```

- This command will execute all the deployment scripts in `./deploy` directory - It will skip only deployment scripts which implement a `skip` condition - Here is example of a skip condition: - Skipping deployment script on `bsctestnet` network `func.skip = async (hre: HardhatRuntimeEnvironment) => hre.network.name !== "bsctestnet";`
- The default network will be `hardhat`
- Deployment to another network: - Make sure the desired network is configured in `hardhat.config.ts` - Add `MNEMONIC` variable in `.env` file - Execute deploy command by adding `--network <network_name>` in the deploy command above - E.g. `npx hardhat deploy --network bsctestnet`
- Execution of single or custom set of scripts is possible, if:
- In the deployment scripts you have added `tags` for example: - `func.tags = ["MockTokens"];`
- Once this is done, adding `--tags "<tag_name>,<tag_name>..."` to the deployment command will execute only the scripts containing the tags.

### Dry Run / Forked Deployments
- Deploys all scripts from `./deploy`, skipping those with a `skip` condition.
- Default network is `hardhat`. For others:
1. Configure in `hardhat.config.ts`
2. Add `MNEMONIC` to `.env`
3. Run:
```bash
npx hardhat deploy --network <network_name>
```

To simulate what contracts would be deployed on a given network the deployment scripts support running on a forked network. To run the deployment scripts on a forked network the `HARDHAT_FORK_NETWORK` env variable needs to be set.
### ➕ Tags and Partial Deployments

For example
To run only specific scripts with tags:

```bash
HARDHAT_FORK_NETWORK=ethereum npx hardhat deploy
```ts
func.tags = ["MockTokens"];
```

### Deployed Contracts

Contract addresses deployed before `hardhat-deploy` was adopted are available in the `networking` directory in JSON files by network name.

Contract addresses and abis deployed with hardhat deploy are exported in the `deployments` directory. To create a summary export of all contracts deployed to a network run.
Then:

```
$ yarn hardhat --network <network-name> --export ./deployments/<network-name>.json
```bash
npx hardhat deploy --tags "MockTokens"
```

### Source Code Verification
### 🧪 Dry Run / Forked Deployment

In order to verify the source code of already deployed contracts, run:
`npx hardhat etherscan-verify --network <network_name>`
Example:

Make sure you have added `ETHERSCAN_API_KEY` in `.env` file.
```bash
HARDHAT_FORK_NETWORK=ethereum npx hardhat deploy
```

## Linting
### 📍 Deployed Contracts

To lint the code, run:
- Pre–Hardhat Deploy addresses: `networking/`
- Current deployments: `deployments/`
- Export all deployed contracts for a network:

```bash
yarn hardhat --network <network-name> --export ./deployments/<network-name>.json
```

yarn lint
### ✅ Source Code Verification

```bash
npx hardhat etherscan-verify --network <network_name>
```

To format the code, run:
Requires `ETHERSCAN_API_KEY` in `.env`.

```
---

yarn prettier
## 🧹 Linting

```bash
yarn lint
yarn prettier
```

## Hardhat Commands
---

```
## 🛠 Hardhat Commands

```bash
npx hardhat accounts

npx hardhat compile

npx hardhat clean

npx hardhat test

npx hardhat node

npx hardhat help

REPORT_GAS=true npx hardhat test

npx hardhat coverage

TS_NODE_FILES=true npx ts-node scripts/deploy.ts
```

npx eslint '\*_/_.{js,ts}'

npx eslint '\*_/_.{js,ts}' --fix
### ESLint & Prettier

npx prettier '\*_/_.{json,sol,md}' --check
```bash
npx eslint '**/*.{js,ts}' # lint
npx eslint '**/*.{js,ts}' --fix # auto-fix
npx prettier '**/*.{json,sol,md}' --check
npx prettier '**/*.{json,sol,md}' --write
```

npx prettier '\*_/_.{json,sol,md}' --write
### Solidity Linting

npx solhint 'contracts/\*_/_.sol'
```bash
npx solhint 'contracts/**/*.sol'
npx solhint 'contracts/**/*.sol' --fix
```

npx solhint 'contracts/\*_/_.sol' --fix
### Example Deploy Script

```bash
MNEMONIC="<>" BSC_API_KEY="<>" npx hardhat run ./script/hardhat/deploy.ts --network testnet

```

## Discussion
---

## 💬 Discussion

For any concerns with the protocol, open an issue or visit us on [Telegram](https://t.me/venusprotocol) to discuss.
- For help or feedback, open an issue or join us on [Telegram](https://t.me/venusprotocol).
- For security concerns, please message admins directly in our Telegram chat.

For security concerns, please contact the administrators of our telegram chat.
---

© Copyright 2023, Venus Protocol
© 2023 Venus Protocol